@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/cli.js

@@ -3,16 +3,23 @@ import { Command } from "commander";
 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 { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, } from "node:fs";
 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";
+import { createHash, createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
 import { keystore } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
 import { fabricUpgrade } from "./fabric-upgrade.js";
-import { detectClients, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { checkVersion, formatVersionNudge } from "./version-check.js";
+import { checkServerHandshake, formatHandshakeNudge } from "./version-handshake.js";
+import { probeInstance } from "./probe.js";
+import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
+import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
+import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.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 +42,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.
@@ -86,33 +126,76 @@ const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
 /**
- * Read an admin password from a file, refusing if the file is world/group readable.
+ * Read a secret (admin password, Fabric password, ...) from a file, refusing
+ * if the file is world/group readable.
  *
- * Admin pass files (default ~/.flair/admin-pass) are short-lived secrets generated
- * by `openssl rand` — mode 0600 keeps them out of reach of other local users + most
- * backup tooling. A 0644 file silently leaks the secret to anyone with read access
- * to the user's home (multi-user hosts, NFS, time-machine snapshots, etc.).
+ * Secret files (default ~/.flair/admin-pass; also used for --fabric-password-file)
+ * are short-lived values generated by `openssl rand` — mode 0600 keeps them
+ * out of reach of other local users + most backup tooling. A 0644 file
+ * silently leaks the secret to anyone with read access to the user's home
+ * (multi-user hosts, NFS, time-machine snapshots, etc.).
  *
- * Throws with an actionable error if the file isn't owner-only, otherwise returns
- * the trimmed file content (admin-pass files generated by `openssl rand -base64`
- * conventionally end in a newline).
+ * Throws with an actionable error if the file isn't owner-only, otherwise
+ * returns the trimmed file content (values generated by `openssl rand
+ * -base64` conventionally end in a newline). `flagName` is only used to
+ * personalize the error text (e.g. "--admin-pass-file" vs
+ * "--fabric-password-file") — the check itself is identical either way.
  */
-export function readAdminPassFileSecure(path) {
+function readSecretFileSecure(path, flagName) {
     if (!existsSync(path)) {
-        throw new Error(`--admin-pass-file path does not exist: ${path}`);
+        throw new Error(`${flagName} path does not exist: ${path}`);
     }
     const st = statSync(path);
     if (st.mode & 0o077) {
         const modeOctal = (st.mode & 0o777).toString(8).padStart(3, "0");
-        throw new Error(`Refusing to read --admin-pass-file at ${path}: permissions ${modeOctal} are too open. ` +
+        throw new Error(`Refusing to read ${flagName} at ${path}: permissions ${modeOctal} are too open. ` +
             `Run \`chmod 600 ${path}\` to restrict to owner-only.`);
     }
     const content = readFileSync(path, "utf-8").replace(/\s+$/, "");
     if (!content) {
-        throw new Error(`admin password file is empty or contains only whitespace: ${path}`);
+        throw new Error(`${flagName}: file is empty or contains only whitespace: ${path}`);
     }
     return content;
 }
+/** `readSecretFileSecure` specialized for --admin-pass-file (see that function for the shared check). */
+export function readAdminPassFileSecure(path) {
+    return readSecretFileSecure(path, "--admin-pass-file");
+}
+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).
+ * Also reused by `api()`'s local-target auth fallback (flair#634) — called
+ * there as `resolveLocalAdminPass(undefined, !isLocal)`, so only its file leg
+ * ever fires (the env leg is already handled by `api()` itself first).
+ *
+ * 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");
 }
@@ -306,24 +389,38 @@ async function api(method, path, body, options) {
     const defaultUrl = savedPort ? `http://127.0.0.1:${savedPort}` : `http://127.0.0.1:${DEFAULT_PORT}`;
     const base = options?.baseUrl ?? (process.env.FLAIR_URL || defaultUrl);
     const isLocal = isLocalBase(base);
-    // Auth resolution order:
+    // Auth resolution order (flair#634 — local targets used to send NO auth at
+    // all here and ride Harper's authorizeLocal forged super_user; #632 gated
+    // FederationInstance/FederationPeers behind allowAdmin, so credential-less
+    // local calls to those now 403 instead of silently passing):
     // 1. FLAIR_TOKEN env → Bearer token (backward compat)
-    // 2. FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD env → Basic admin auth (remote targets only).
-    //    For local targets with authorizeLocal=true, skip Basic auth and let Harper handle it.
+    // 2. FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD env → Basic admin auth. Applies to
+    //    BOTH local and remote targets — an explicit env var always wins, local
+    //    included, so a caller that sets it never depends on authorizeLocal.
     // 3. FLAIR_AGENT_ID env + key file → Ed25519 signature (standard)
-    // 4. No auth (Harper authorizeLocal handles local; remote will 401)
+    // 4. LOCAL TARGETS ONLY: the secure ~/.flair/admin-pass file `flair init`
+    //    writes (#593) → Basic admin auth, via the same resolveLocalAdminPass
+    //    convenience `agent add`/`principal add` already use (#590). Guarded to
+    //    isLocal so a --target/FLAIR_URL request aimed elsewhere never rides
+    //    this machine's local admin secret.
+    // 5. No auth (remote will 401/403; local now also gets a real 403 from
+    //    #632-gated resources instead of the old forged-admin passthrough)
     //
     // NOTE: this function is for the Harper HTTP/REST API only. The Harper
     // operations API (used by seedAgentViaOpsApi / seedFederationInstanceViaOpsApi)
-    // does NOT honor authorizeLocal — it always requires Basic admin auth, and
-    // those helpers send it unconditionally. authorizeLocal=true affects this
-    // path; it does not affect ops-API calls.
+    // ALSO honors authorizeLocal: a header-less loopback request to the ops port
+    // is auto-authorized as super_user (verified by live probe — flair#610). Those
+    // helpers nonetheless send Basic admin auth UNCONDITIONALLY, so they never
+    // depend on that ambient elevation and behave identically against a remote or
+    // hardened instance. Hardening the ops-API loopback posture itself (bind scope
+    // / disabling authorizeLocal there) is tracked separately in flair#654 and is
+    // out of scope for this HTTP/REST auth path.
     let authHeader;
     const token = process.env.FLAIR_TOKEN;
     if (token) {
         authHeader = `Bearer ${token}`;
     }
-    else if (!isLocal && (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD)) {
+    else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
         // Admin Basic auth — used by federation, backup, and other admin CLI commands
         const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
         authHeader = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
@@ -351,6 +448,25 @@ async function api(method, path, body, options) {
                 }
             }
         }
+        // Local-only fallback (flair#634): no explicit env, no usable agent key.
+        // FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD are already ruled out by this point
+        // (handled above), so resolveLocalAdminPass's env leg is a no-op here and
+        // this only ever resolves the ~/.flair/admin-pass file — isRemoteTarget
+        // is `!isLocal` so it's skipped entirely for --target/FLAIR_URL requests.
+        if (!authHeader) {
+            try {
+                const filePass = resolveLocalAdminPass(undefined, !isLocal);
+                if (filePass) {
+                    authHeader = `Basic ${Buffer.from(`admin:${filePass}`).toString("base64")}`;
+                }
+            }
+            catch (err) {
+                // File exists but has unsafe permissions — warn (never the secret
+                // itself) and fall through to no-auth.
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`Warning: ~/.flair/admin-pass unusable: ${message}`);
+            }
+        }
     }
     const res = await fetch(`${base}${path}`, {
         method,
@@ -367,8 +483,19 @@ async function api(method, path, body, options) {
         return { ok: true };
     }
     const text = await res.text();
-    if (!res.ok)
+    if (!res.ok) {
+        // 403 with no credentials sent at all is the flair#634 case: a gated
+        // resource (e.g. #632's FederationInstance/FederationPeers) rejected a
+        // credential-less call. Name the fix instead of surfacing the raw
+        // "forbidden" body — never a stack trace.
+        if (res.status === 403 && !authHeader) {
+            const hint = isLocal
+                ? "Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass."
+                : "Set FLAIR_ADMIN_PASS (remote targets have no local admin-pass fallback).";
+            throw new Error(`HTTP 403: no credentials sent. ${hint}`);
+        }
         throw new Error(text || `HTTP ${res.status}`);
+    }
     if (!text)
         return { ok: true };
     return JSON.parse(text);
@@ -558,6 +685,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
@@ -591,10 +802,13 @@ function readHarperPid(dataDir) {
  * Seed an agent record via the Harper operations API.
  * Accepts either a port number (localhost) or a full URL string (--target).
  *
- * `adminPass` is typed as optional but in practice the Harper operations API
- * always requires Basic admin auth — every existing call site passes one.
- * The optional signature leaves headroom for a future Harper that honors
- * `authorizeLocal` on its ops endpoint; until then, callers must pass it.
+ * `adminPass` is optional: a local caller may omit it and ride Harper's
+ * `authorizeLocal`, which auto-authorizes a header-less loopback request to
+ * the ops port as super_user (current behavior, verified by live probe —
+ * flair#610). When passed, the helper sends Basic admin auth so it never
+ * depends on that ambient elevation and behaves identically against a remote
+ * or hardened instance. Hardening the ops-API loopback posture is tracked in
+ * flair#654.
  */
 export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, adminUser, adminPass) {
     const url = typeof opsPortOrUrl === "number"
@@ -651,10 +865,12 @@ export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, ad
 // admin:admin-pass), not the REST API (which needs server-side HDB_ADMIN_PASSWORD
 // — unavailable on Fabric).  Same pattern as seedAgentViaOpsApi above.
 //
-// `adminPass` is optional in the signature for symmetry with seedAgentViaOpsApi
-// and to keep the door open for a future Harper that honors authorizeLocal on
-// its ops endpoint. Today the Harper operations API always requires Basic admin
-// auth; every current caller passes it.
+// `adminPass` is optional (symmetry with seedAgentViaOpsApi): a local caller may
+// omit it and ride authorizeLocal, which the Harper ops API honors today — a
+// header-less loopback request is auto-authorized as super_user (flair#610).
+// When passed, the helper sends Basic admin auth so it never depends on that
+// ambient elevation and behaves identically against a remote or hardened
+// instance. Hardening that posture is tracked in flair#654.
 export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId, publicKey, role, adminUser, adminPass) {
     const url = typeof opsPortOrUrl === "number"
         ? `http://127.0.0.1:${opsPortOrUrl}/`
@@ -689,7 +905,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 +998,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;
@@ -940,9 +1156,6 @@ export async function ensureFlairPairInitiatorRole(opsUrl, adminUser, adminPass)
 //      WorkspaceState, OAuthClient — NOT the logical Memory/Event/Workspace/OAuth
 //      shorthand the flair_pair_initiator spec used, which was harmless only
 //      because every grant there is false).
-//   3. Obs* writes: if the presence-emitter writes ObsAgentSnapshot AS the agent
-//      it needs insert/update — currently read-only here; confirm the writer's
-//      identity (system vs agent) and widen only if it's the agent.
 // Harper 5.0.21 add_role requires an `attribute_permissions` array on EVERY table
 // grant (empty = no attribute-level restriction, so the table-level CRUD applies);
 // omitting it makes add_role reject the whole spec ("Missing 'attribute_permissions'
@@ -968,14 +1181,20 @@ const FLAIR_AGENT_PERMISSION = {
             Integration: grant(true, true, true, true),
             Credential: grant(true, true, true, true),
             Presence: grant(true, true, true, false),
+            // MemoryUsage (flair#683): the usage-feedback dedup ledger. Read (own
+            // contributions, scoped in resources/MemoryUsage.ts) + insert (a fresh
+            // contribution row) only — NO update/delete. This is load-bearing, not
+            // just least-privilege tidiness: the dedup rule ("(agent, memory)
+            // contributes ≤ 1") is enforced by requiring a NEW ledger row before
+            // any usageCount bump; if an agent could delete its own row, it could
+            // re-trigger the /RecordUsage endpoint for the same memory indefinitely
+            // (create → count → delete → count again → repeat), defeating the cap
+            // entirely. See resources/MemoryUsage.ts's module doc.
+            MemoryUsage: grant(true, true, false, false),
             // Agent: read for discovery, update own card; creation/removal is admin.
             Agent: grant(true, false, true, false),
             // Read-only reference data.
             Instance: grant(true, false, false, false),
-            // Observatory read-models — public reads; writes are system-driven (gate 3).
-            ObsOffice: grant(true, false, false, false),
-            ObsAgentSnapshot: grant(true, false, false, false),
-            ObsEventFeed: grant(true, false, false, false),
             // Federation / OAuth / IdP / internal — system + admin only; agents get none.
             Peer: grant(false, false, false, false),
             PairingToken: grant(false, false, false, false),
@@ -1161,7 +1380,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) {
@@ -1169,6 +1388,50 @@ export function shouldPrintUpgradeLine(status, showAll) {
         return false;
     return true;
 }
+/**
+ * Pure flag resolution for `flair upgrade`'s restart/verify defaults
+ * (flair#635 decision: restart is now the default; `--no-restart` opts
+ * out). `--restart` is a deprecated no-op accepted for backward compat —
+ * `deprecatedRestartFlagUsed` tells the caller to print a one-time notice
+ * without re-deriving the raw Commander value itself.
+ *
+ * Commander quirk this relies on: registering both `--restart` (plain
+ * boolean) and `--no-restart` (negatable) on the same command means
+ * `opts.restart` is `undefined` when neither flag is passed, `true` when
+ * `--restart` is passed, and `false` when `--no-restart` is passed — so
+ * `!== false` is the correct "should restart" default-true test, and
+ * `=== true` isolates "the user explicitly typed the deprecated flag".
+ */
+export function resolveUpgradeRestartVerify(opts) {
+    return {
+        restart: opts.restart !== false,
+        verify: opts.verify !== false,
+        deprecatedRestartFlagUsed: opts.restart === true,
+    };
+}
+/**
+ * Whether `flair deploy` / `flair upgrade --target` should run the
+ * post-deploy fleet convergence sweep (flair#636). Registering
+ * `--no-fleet-verify` via commander leaves `opts.fleetVerify` undefined when
+ * unset, `false` when the flag is passed — mirrors resolveUpgradeRestartVerify's
+ * `!== false` default-true idiom above.
+ */
+export function shouldRunFleetVerify(opts) {
+    return opts.fleetVerify !== false;
+}
+export function decideAfterVerify(result, previousVersion) {
+    if (result.ok)
+        return { kind: "ok" };
+    const reason = result.error ?? "post-restart verification failed";
+    if (!previousVersion)
+        return { kind: "cannot-rollback", reason };
+    return { kind: "rollback", reason, toVersion: previousVersion };
+}
+export function decideAfterRollbackVerify(result) {
+    if (result.ok)
+        return { kind: "rolled-back" };
+    return { kind: "rollback-failed", reason: result.error ?? "rollback verification failed" };
+}
 /**
  * Order a soul key→count map for display: highest count first, ties broken
  * alphabetically for stable output. Soul entries are keyed identity facts
@@ -1350,6 +1613,48 @@ const __pkgVersion = (() => {
 })();
 const program = new Command();
 program.name("flair").version(__pkgVersion, "-v, --version");
+// ─── CLI↔server version handshake (flair#695 §B) ────────────────────────────
+// Every command invocation gets a cheap, cached (~60s), short-timeout check
+// of the running server's version against this CLI's own — catches the
+// bare-npm-upgrade trap where `npm i -g @tpsdev-ai/flair@latest` swaps the
+// CLI binary but the already-running Harper daemon keeps serving the OLD
+// code until `flair restart`. `doctor` is excluded here — it already prints
+// a richer version triple (CLI/installed, running, latest-published) plus
+// migration state, so a global hook nudge on top of that would be
+// redundant noise on the one command whose whole job is this exact report.
+program.hook("preAction", async (_thisCommand, actionCommand) => {
+    if (actionCommand.name() === "doctor")
+        return;
+    // Interactive-only: this is a pure stderr UX nudge for a human at a
+    // terminal ("bare-npm users must not get stuck"), not a machine-consumed
+    // signal — it never changes exit codes or stdout. Gating on TTY means a
+    // piped/scripted/CI invocation (and every existing test that spawns the
+    // CLI against a mock server) never pays the extra network round trip,
+    // which matters beyond latency: several unit tests spawn this CLI against
+    // a single-shot mock HTTP server asserting on exactly one received
+    // request (e.g. test/unit/presence-set.test.ts) — an unconditional extra
+    // GET /Health here would silently consume that slot and break them.
+    if (!process.stdout.isTTY)
+        return;
+    try {
+        const opts = (actionCommand.opts?.() ?? {});
+        const serverUrl = `http://127.0.0.1:${resolveHttpPort(opts)}`;
+        // Cache key component: prefer the server's own ROOTPATH if this shell
+        // happens to have it set (operating a non-default Harper instance
+        // root), else fall back to Flair's own resolved data directory — same
+        // "which local install is this" identity every other doctor/status
+        // check already keys off, so a stale cache from a since-reinstalled
+        // instance sharing the same port never bleeds into a fresh one.
+        const rootPath = process.env.ROOTPATH ?? defaultDataDir();
+        const result = await checkServerHandshake(__pkgVersion, rootPath, serverUrl);
+        const nudge = formatHandshakeNudge(result);
+        if (nudge)
+            console.error(`⚠️  ${nudge}`);
+    }
+    catch {
+        // NEVER block or fail the underlying command over this check.
+    }
+});
 // ─── flair init ──────────────────────────────────────────────────────────────
 program
     .command("init")
@@ -1367,6 +1672,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)")
@@ -1641,6 +1948,12 @@ program
     if (major < 18)
         throw new Error(`Node.js >= 18 required (found ${process.version})`);
     let alreadyRunning = false;
+    // <ROOTPATH>/models — resources/embeddings-provider.ts's resolveModelsDir()
+    // tier 2 default; an operator override already in the environment wins
+    // (tier 1). Scoped above the alreadyRunning branch below (not just inside
+    // the fresh-start path) since the launchd plist step needs it too, even
+    // when Harper was already running and the fresh-spawn branch was skipped.
+    const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
     if (!opts.skipStart) {
         // Check if already running
         try {
@@ -1663,17 +1976,22 @@ program
             // database before the env is initialized).
             const alreadyInstalled = existsSync(join(dataDir, "harper-config.yaml"));
             const opsSocket = join(dataDir, "operations-server");
+            // authorizeLocal: false (flair#654) — a credential-less loopback ops-API
+            // request is no longer auto-authorized as super_user. Every ops-API
+            // seed call below (seedAgentViaOpsApi et al.) already passes a real
+            // adminPass via Basic auth, so this does not change local-init behavior.
             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: opsSocket },
                 mqtt: { network: { port: null }, webSocket: false },
                 localStudio: { enabled: false },
-                authentication: { authorizeLocal: true, enableSessions: true },
+                authentication: { authorizeLocal: false, enableSessions: true },
             });
             const env = {
                 ...process.env,
                 ROOTPATH: dataDir,
+                FLAIR_MODELS_DIR: modelsDir,
                 HARPER_SET_CONFIG: harperSetConfig,
                 DEFAULTS_MODE: "dev",
                 HDB_ADMIN_USERNAME: adminUser,
@@ -1684,6 +2002,14 @@ program
                 OPERATIONSAPI_NETWORK_PORT: String(opsPort),
                 LOCAL_STUDIO: "false",
             };
+            // models (flair#504 Phase 1): the embedding backend registers itself
+            // in-process at boot (resources/embeddings-boot.ts, loaded by
+            // config.yaml's `jsResource` glob) — NOT via a config env var. See
+            // that file's header for why (flair#694: HARPER_CONFIG persisted a
+            // `models.embedding.default` block into harper-config.yaml that an
+            // older/downgraded build's boot would tear down to an invalid empty
+            // shell). FLAIR_MODELS_DIR above is still the channel that tells the
+            // registration where to find/download the model.
             if (alreadyInstalled) {
                 console.log("Existing Harper installation found — skipping install.");
                 console.log("If something is wrong, run: flair doctor");
@@ -1748,14 +2074,23 @@ program
                 mkdirSync(plistDir, { recursive: true });
                 const plistPath = join(plistDir, `${label}.plist`);
                 const opsSocket = join(dataDir, "operations-server");
+                // authorizeLocal: false (flair#654) — same posture as the initial spawn
+                // above; the launchd-managed process must not diverge from it.
                 const setConfig = 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: opsSocket },
                     mqtt: { network: { port: null }, webSocket: false },
                     localStudio: { enabled: false },
-                    authentication: { authorizeLocal: true, enableSessions: true },
+                    authentication: { authorizeLocal: false, enableSessions: true },
                 });
+                // models (flair#504 Phase 1): no env var needed here — the
+                // launchd-managed process loads the SAME dist/resources/*.js as any
+                // other spawn, so resources/embeddings-boot.ts self-registers the
+                // backend on every KeepAlive restart in-process. See that file's
+                // header (flair#694) for why this replaced the old HARPER_CONFIG
+                // plist line.
+                const escapeXml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
                 const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -1772,7 +2107,8 @@ program
   <key>EnvironmentVariables</key>
   <dict>
     <key>ROOTPATH</key><string>${dataDir}</string>
-    <key>HARPER_SET_CONFIG</key><string>${setConfig.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;")}</string>
+    <key>FLAIR_MODELS_DIR</key><string>${modelsDir}</string>
+    <key>HARPER_SET_CONFIG</key><string>${escapeXml(setConfig)}</string>
     <key>DEFAULTS_MODE</key><string>dev</string>
     <key>HDB_ADMIN_USERNAME</key><string>${adminUser}</string>
     <key>HDB_ADMIN_PASSWORD</key><string>${adminPass}</string>
@@ -1906,8 +2242,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 +2310,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 +2474,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 +2481,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 });
@@ -2482,6 +2858,108 @@ agent
     }
     console.log(`\n✅ Agent '${id}' removed successfully`);
 });
+// ─── flair mcp ───────────────────────────────────────────────────────────────
+// Headless agent-auth to a Harper MCP `/mcp` endpoint: RFC 7523
+// client_credentials + private_key_jwt, using the agent's EXISTING Ed25519
+// identity key (no new key material, no browser, no human). The plugin side
+// (HarperFast/oauth, parent issue #159) shipped the full chain in the
+// published 2.2.0 release: assertion verification (#160/PR #165), CIMD-first
+// client resolution (#161/#167), and the client_credentials token-endpoint
+// grant + issuance rate limiting (#170/#171, closing #162/#163). `flair mcp
+// token` signs the assertion and, by default, requests a real access token
+// against the token endpoint; see src/mcp-client-assertion.ts.
+const mcp = program.command("mcp").description("MCP client-credentials agent-auth (RFC 7523 private_key_jwt)");
+mcp
+    .command("token")
+    .description("Build + sign an RFC 7523 client_assertion and request an MCP client_credentials " +
+    "access token. Caches the minted token (in-process) and reuses it until " +
+    "near-expiry — use --force-refresh to mint unconditionally.")
+    .requiredOption("--agent-id <id>", "Agent id — becomes the client_id (iss/sub claims)")
+    .option("--client-id <url>", "Client ID Metadata Document URL for this agent (defaults to this instance's " +
+    "MCPClientMetadata URL, derived from FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL)")
+    .option("--token-endpoint <url>", "Token-endpoint URL — becomes the `aud` claim (defaults to this instance's " +
+    "own oauth token endpoint, same env vars)")
+    .option("--resource <url>", "RFC 8707 resource indicator for the token request (defaults to this instance's canonical /mcp URI)")
+    .option("--keys-dir <dir>", "Directory to look for <agentId>.key (else FLAIR_KEY_DIR, ~/.flair/keys, ~/.tps/secrets/flair)")
+    .option("--expires-in <seconds>", `Assertion exp - iat window, seconds (default + hard cap: ${MAX_ASSERTION_LIFETIME_SECONDS})`)
+    .option("--dry-run", "Sign the assertion and print what would be sent, but do not call the token endpoint")
+    .option("--force-refresh", "Mint a fresh token even if a cached, not-near-expiry one exists")
+    .option("--json", "Print machine-readable JSON instead of a human summary")
+    .action(async (opts) => {
+    const agentId = opts.agentId;
+    const keyPath = resolveAgentKeyPath(agentId, opts.keysDir);
+    if (!keyPath) {
+        console.error(`Error: no private key found for agent '${agentId}'. Checked --keys-dir, FLAIR_KEY_DIR, ` +
+            `~/.flair/keys, and ~/.tps/secrets/flair.`);
+        process.exit(1);
+    }
+    const clientId = opts.clientId ?? defaultMcpClientId(agentId);
+    if (!clientId) {
+        console.error("Error: --client-id is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL to derive it from " +
+            "this instance's MCPClientMetadata URL).");
+        process.exit(1);
+    }
+    const tokenEndpoint = opts.tokenEndpoint ?? defaultMcpTokenEndpoint();
+    if (!tokenEndpoint) {
+        console.error("Error: --token-endpoint is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL to derive " +
+            "this instance's own oauth token endpoint).");
+        process.exit(1);
+    }
+    const resource = opts.resource ?? defaultMcpResource();
+    const expiresIn = opts.expiresIn ? Number(opts.expiresIn) : undefined;
+    let privateKey;
+    try {
+        privateKey = loadEd25519PrivateKeyFromFile(keyPath);
+    }
+    catch (err) {
+        console.error(`Error: failed to load private key at ${keyPath}: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+    if (opts.dryRun) {
+        const { assertion, claims } = signClientAssertion({
+            clientId,
+            tokenEndpoint,
+            privateKey,
+            expiresInSeconds: expiresIn,
+        });
+        const form = buildTokenRequestForm({ clientId, assertion, resource });
+        if (opts.json) {
+            console.log(JSON.stringify({ assertion, claims, wouldSendForm: form, tokenEndpoint }, null, 2));
+            return;
+        }
+        console.log(`client_assertion (RFC 7523, EdDSA):\n\n${assertion}\n`);
+        console.log(`claims: iss=sub=${claims.iss}  aud=${claims.aud}  exp-iat=${claims.exp - claims.iat}s  jti=${claims.jti}`);
+        console.log(`\n--dry-run: NOT sent. This assertion is the client_assertion value for:\n` +
+            `  POST ${tokenEndpoint}\n  ${JSON.stringify(form, null, 2).split("\n").join("\n  ")}`);
+        return;
+    }
+    try {
+        const token = await getMcpAccessToken({
+            clientId,
+            tokenEndpoint,
+            privateKey,
+            resource,
+            expiresInSeconds: expiresIn,
+            forceRefresh: Boolean(opts.forceRefresh),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(token, null, 2));
+            return;
+        }
+        console.log(`access_token minted (${token.tokenType}, expires_in=${token.expiresIn}s):\n\n${token.accessToken}`);
+        if (token.scope)
+            console.log(`\nscope: ${token.scope}`);
+    }
+    catch (err) {
+        if (err instanceof McpTokenRequestError) {
+            console.error(`Error: token request failed (HTTP ${err.status}${err.error ? ` ${err.error}` : ""}): ${err.message}`);
+        }
+        else {
+            console.error(`Error: token request failed: ${err?.message ?? err}`);
+        }
+        process.exit(1);
+    }
+});
 // ─── flair principal ─────────────────────────────────────────────────────────
 // 1.0 identity management. The Principal model extends Agent — this is the
 // preferred CLI surface for managing identities going forward.
@@ -2501,15 +2979,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)
@@ -3185,7 +3674,7 @@ federation
     }
 });
 // `flair federation reachability` — probe local instance + all paired peers.
-// Productizes ~/ops/scripts/flair-boot-probe.sh: a single command that tells
+// Productizes flair#695: a single command that tells
 // you whether memories CAN flow across the federation right now. Read-only;
 // no mutations, no side effects beyond a single tagged status read per peer.
 federation
@@ -3662,15 +4151,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 +4249,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 {
@@ -3818,7 +4346,7 @@ federation
     await runFederationWatch(opts);
 });
 // `flair federation prune` — remove stale spoke peers (never the hub).
-// Productizes ~/ops/scripts/cleanup-stale-fed-peers.sh into a real CLI
+// Productizes flair#695 into a real CLI
 // subcommand with safety: dry-run is the default, --apply required to delete.
 function parseDuration(spec) {
     // Accept forms like "30d", "12h", "90m". Returns milliseconds.
@@ -3928,7 +4456,7 @@ federation
 });
 // `flair federation verify` — end-to-end roundtrip: write a tagged memory
 // locally, wait for federation push, probe peers for the tag. Productizes
-// ~/ops/scripts/verify-fed-sync.sh. Cleans up the test memory at the end.
+// flair#695 Cleans up the test memory at the end.
 federation
     .command("verify")
     .description("End-to-end check: write a tagged memory locally and verify it shows up on each peer")
@@ -4162,13 +4690,61 @@ rem
         process.exit(1);
     }
 });
+// ─── flair rem rapid — pure helpers ──────────────────────────────────────────
+// Extracted for testability, same pattern as validatePromoteOpts /
+// decideCandidateAction above: the action callback below spawns api() +
+// process.exit, which makes it high-effort/low-value to drive directly;
+// these two functions are the actual decision logic.
+/** One staged-candidate summary line: `[id] claim, truncated to ~80 chars`. */
+export function formatCandidateLine(candidate, maxClaimLen = 80) {
+    const claim = candidate.claim ?? "";
+    const truncated = claim.length > maxClaimLen ? `${claim.slice(0, maxClaimLen)}…` : claim;
+    return `  [${candidate.id ?? "?"}] ${truncated}`;
+}
+/**
+ * Classifies a thrown /ReflectMemories execute-mode error for CLI display.
+ * `api()` throws `Error(responseBodyText)` for non-2xx responses (see api()
+ * above) — the two execute-mode failure bodies are:
+ *   503 no-backend:        { error: "No generative backend configured..." }
+ *   502 distillation_failed: { error: "distillation_failed", detail: "..." }
+ * Any other shape (network errors, the 400/403 actor-resolution errors
+ * prompt mode shares) falls back to "other" — printed as a plain message,
+ * no docs pointer or retry hint attached since neither applies.
+ */
+export function describeReflectError(message) {
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed && typeof parsed === "object") {
+            if (parsed.error === "distillation_failed") {
+                return { kind: "distillation-failed", text: String(parsed.detail ?? parsed.error) };
+            }
+            if (typeof parsed.error === "string" && parsed.error.startsWith("No generative backend configured")) {
+                return { kind: "no-backend", text: parsed.error };
+            }
+            if (typeof parsed.error === "string") {
+                return { kind: "other", text: parsed.error };
+            }
+        }
+    }
+    catch {
+        // Not a JSON error body — network error, etc. Pass the raw message through.
+    }
+    return { kind: "other", text: message };
+}
+// ─── flair rem rapid ──────────────────────────────────────────────────────────
+// Executes by default (specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3C,
+// issue #707): distills server-side via /ReflectMemories execute:true and
+// stages MemoryCandidate rows, printing a staged-candidate summary. --prompt-only
+// preserves the pre-#710 handoff behavior byte-for-byte, for the bring-your-
+// own-model workflow.
 rem
     .command("rapid")
-    .description("REM — reflection/learning: generate a structured LLM reflection prompt")
+    .description("REM — reflection/learning: distill recent memories into staged candidates")
     .option("--port <port>", "Harper HTTP port")
     .option("--agent <id>", "Agent ID (or FLAIR_AGENT_ID env)")
     .option("--focus <type>", "lessons_learned | patterns | decisions | errors", "lessons_learned")
     .option("--since <date>", "ISO timestamp lower bound (default: 24h ago)")
+    .option("--prompt-only", "Return the reflection prompt instead of executing (pre-#710 handoff behavior)")
     .action(async (opts) => {
     const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
     if (!agentId) {
@@ -4177,30 +4753,62 @@ rem
     }
     console.log(`\n-- rem rapid --`);
     console.log(`Agent: ${agentId}  Focus: ${opts.focus}`);
-    try {
-        const body = {
-            agentId,
-            focus: opts.focus,
-        };
-        if (opts.since)
-            body.since = opts.since;
-        const result = await api("POST", "/ReflectMemories", body);
-        if (result.error) {
-            console.error(`Reflection error: ${result.error}`);
+    const body = {
+        agentId,
+        focus: opts.focus,
+    };
+    if (opts.since)
+        body.since = opts.since;
+    if (opts.promptOnly) {
+        // --prompt-only: EXACT pre-#710 behavior — prompt-return mode, unchanged.
+        try {
+            const result = await api("POST", "/ReflectMemories", body);
+            if (result.error) {
+                console.error(`Reflection error: ${result.error}`);
+                process.exit(1);
+            }
+            console.log(`\nSource memories: ${result.count ?? 0}`);
+            if (result.suggestedTags?.length) {
+                console.log(`Tags: ${result.suggestedTags.join(", ")}`);
+            }
+            console.log("\n--- Reflection Prompt ---");
+            console.log(result.prompt ?? "(no prompt returned)");
+            console.log("--- End Prompt ---\n");
+            console.log("Feed the prompt above to your LLM, then write insights back with:");
+            console.log("  flair memory add --agent <id> --content <insight> --durability persistent --derived-from <source-ids>");
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
             process.exit(1);
         }
-        console.log(`\nSource memories: ${result.count ?? 0}`);
-        if (result.suggestedTags?.length) {
-            console.log(`Tags: ${result.suggestedTags.join(", ")}`);
+        return;
+    }
+    // Default: execute mode — distill server-side, stage candidates.
+    try {
+        const result = await api("POST", "/ReflectMemories", { ...body, execute: true });
+        const candidates = Array.isArray(result.candidates) ? result.candidates : [];
+        console.log(`\nModel:      ${result.model ?? "?"}`);
+        console.log(`Candidates: ${result.count ?? candidates.length}`);
+        if (candidates.length > 0) {
+            console.log();
+            for (const c of candidates)
+                console.log(formatCandidateLine(c));
         }
-        console.log("\n--- Reflection Prompt ---");
-        console.log(result.prompt ?? "(no prompt returned)");
-        console.log("--- End Prompt ---\n");
-        console.log("Feed the prompt above to your LLM, then write insights back with:");
-        console.log("  flair memory add --agent <id> --content <insight> --durability persistent --derived-from <source-ids>");
+        console.log(`\nreview: flair rem candidates / flair rem promote <id>`);
     }
     catch (err) {
-        console.error(`Error: ${err.message}`);
+        const desc = describeReflectError(err.message ?? String(err));
+        if (desc.kind === "no-backend") {
+            console.error(`Reflection error: ${desc.text}`);
+            console.error(`See docs/rem.md#configuration for how to point Flair at a models: backend.`);
+        }
+        else if (desc.kind === "distillation-failed") {
+            console.error(`Reflection error: distillation failed — ${desc.text}`);
+            console.error(`Retry, or run with --prompt-only for the manual handoff.`);
+        }
+        else {
+            console.error(`Error: ${desc.text}`);
+        }
         process.exit(1);
     }
 });
@@ -4699,6 +5307,11 @@ remNightly
             console.log(`Archived:   ${row.archived ?? "—"}`);
             console.log(`Expired:    ${row.expired ?? "—"}`);
         }
+        // row.candidates populates when step 5 (distillation) was attempted
+        // this cycle — see src/rem/runner.ts. Absent when dry-run skipped it.
+        if (row.candidates) {
+            console.log(`Staged:     ${row.candidates.length} candidate${row.candidates.length === 1 ? "" : "s"}`);
+        }
         console.log(`Duration:   ${row.durationMs}ms`);
         if (row.errors.length > 0) {
             console.log(`Errors:`);
@@ -4964,7 +5577,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 +5694,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 +5730,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 +5786,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) {
@@ -5771,32 +6399,68 @@ statusCmd
         console.log("\n✅ no warnings");
     }
 });
+export function resolveFabricCredentials(opts) {
+    const warnings = [];
+    if (opts.fabricUser && !process.env.FABRIC_USER) {
+        warnings.push("warning: --fabric-user passed inline. Consider FABRIC_USER env — " +
+            "a login name in shell history/ps is recon.");
+    }
+    const fabricUser = opts.fabricUser ?? process.env.FABRIC_USER;
+    let fabricPassword;
+    if (opts.fabricPassword) {
+        if (opts.fabricPasswordFile) {
+            warnings.push("warning: --fabric-password (inline) takes precedence over --fabric-password-file " +
+                "when both are given. Pass --fabric-password-file alone to keep the secret out of shell history.");
+        }
+        if (!process.env.FABRIC_PASSWORD) {
+            warnings.push("warning: --fabric-password leaks to shell history. Prefer FABRIC_PASSWORD env or --fabric-password-file.");
+        }
+        fabricPassword = opts.fabricPassword;
+    }
+    else if (opts.fabricPasswordFile) {
+        fabricPassword = readSecretFileSecure(opts.fabricPasswordFile, "--fabric-password-file");
+    }
+    else {
+        fabricPassword = process.env.FABRIC_PASSWORD;
+    }
+    return { fabricUser, fabricPassword, warnings };
+}
 // ─── flair upgrade --target <fabric> ────────────────────────────────────────
 //
 // One-command upgrade of a Flair instance DEPLOYED to a Harper Fabric cluster.
 // Mirrors `flair deploy`'s credential handling (FABRIC_USER/FABRIC_PASSWORD env
-// fallbacks, password-via-flag warning) and NEVER prints credentials. The
+// fallbacks, password-via-flag warning, --fabric-password-file — see
+// resolveFabricCredentials above) and NEVER prints credentials. The
 // version-resolution + @harperfast/harper pin + reuse of deploy() lives in
 // src/fabric-upgrade.ts; this wrapper only does CLI plumbing + the confirm.
 async function runFabricUpgrade(opts) {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
     const red = (s) => `\x1b[31m${s}\x1b[0m`;
     const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-    const fabricUser = opts.fabricUser ?? process.env.FABRIC_USER;
-    const fabricPassword = opts.fabricPassword ?? process.env.FABRIC_PASSWORD;
+    let fabricUser;
+    let fabricPassword;
+    let credWarnings = [];
+    try {
+        ({ fabricUser, fabricPassword, warnings: credWarnings } = resolveFabricCredentials(opts));
+    }
+    catch (err) {
+        console.error(red(`Error: ${err.message}`));
+        process.exit(1);
+    }
     const check = opts.check ?? false;
     // Creds are not required for --check (read-only registry + best-effort GET),
     // but ARE required to actually deploy.
     if (!check && !(fabricUser && fabricPassword)) {
         console.error(red("flair upgrade --target: credentials required to deploy"));
-        console.error("  pass --fabric-user + --fabric-password (or FABRIC_USER / FABRIC_PASSWORD env)");
+        console.error("  set FABRIC_USER + FABRIC_PASSWORD env (safest), or pass --fabric-user + --fabric-password-file <path>");
+        console.error("  inline --fabric-user/--fabric-password also work but leak to shell history — avoid on shared/multi-user hosts");
         console.error("  or use --check to preview the plan without credentials");
         process.exit(1);
     }
-    // Warn on password-via-flag (leaks to shell history). Env is preferred.
-    if (opts.fabricPassword && !process.env.FABRIC_PASSWORD) {
-        console.error(dim("warning: --fabric-password leaks to shell history. Prefer FABRIC_PASSWORD env."));
-    }
+    // Never log the credential VALUES — only the flag names, via the
+    // resolver's own warning strings.
+    for (const w of credWarnings)
+        console.error(dim(w));
     const upgradeOpts = {
         target: opts.target,
         project: opts.project,
@@ -5834,6 +6498,29 @@ async function runFabricUpgrade(opts) {
             return;
         }
         console.log(`\n${green("✓")} Fabric upgrade complete.`);
+        // ── Post-upgrade fleet sweep (flair#636) ────────────────────────────────
+        // "deploy complete" from harper's own CLI means "origin took it" — this
+        // confirms every known federation peer actually converged on the version
+        // we just deployed, instead of trusting a single boolean. Skippable with
+        // --no-fleet-verify. fabricUser/fabricPassword are guaranteed set here —
+        // the !check branch above already required both.
+        if (!shouldRunFleetVerify(opts)) {
+            console.log(dim("(--no-fleet-verify: skipping post-upgrade fleet sweep)"));
+        }
+        else {
+            console.log(`\n${green("→")} Fleet verify`);
+            const sweep = await sweepFleet({
+                target: upgradeOpts.target,
+                fabricUser: fabricUser,
+                fabricPassword: fabricPassword,
+                expectVersion: result.plan.targetVersion,
+            });
+            console.log(renderFleetSweepTable(sweep));
+            if (sweep.exitCode !== FLEET_EXIT_OK) {
+                console.error(red(`\n✗ fleet verify failed (exit ${sweep.exitCode}) — upgrade is NOT fully converged.`));
+                process.exit(sweep.exitCode);
+            }
+        }
     }
     catch (err) {
         console.error(red(`\n✗ fabric upgrade failed: ${err.message}`));
@@ -5844,39 +6531,385 @@ async function runFabricUpgrade(opts) {
         process.exit(1);
     }
 }
-// ─── flair upgrade ────────────────────────────────────────────────────────────
-program
-    .command("upgrade")
-    .description("Upgrade Flair — local packages by default, or a deployed Fabric with --target")
-    .option("--check", "Only check for updates / show the plan, don't install or deploy")
-    .option("--restart", "Restart Flair after upgrade")
-    .option("--all", "Show transitive packages (e.g. flair-client) in the listing — verbose mode for debugging dep versions")
-    // ── Fabric upgrade (--target) ────────────────────────────────────────────
-    // When --target is passed, upgrade the Flair component DEPLOYED to that
-    // Harper Fabric URL instead of the local npm install. Reuses `flair deploy`
-    // under the hood with the @harperfast/harper pin baked in (flair#513).
-    .option("--target <url>", "Upgrade the Flair deployed to this Fabric URL (not the local install)")
-    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER) — for --target")
-    .option("--fabric-password <pass>", "Fabric admin password (env: FABRIC_PASSWORD) — for --target")
-    .option("--version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
-    .option("--harper-version <semver>", "Pin @harperfast/harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
-    .option("--project <name>", "Fabric component name for --target", "flair")
-    .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
-    .option("--yes", "Skip the confirmation prompt for --target")
-    .action(async (opts) => {
-    // ── Fabric-upgrade branch ───────────────────────────────────────────────
-    if (opts.target) {
-        await runFabricUpgrade(opts);
-        return;
+// ─── Pre-upgrade data snapshot (flair#637) ─────────────────────────────────
+// `flair upgrade` used to swap @tpsdev-ai/flair's own package with no backup
+// of ~/.flair/data — if an upgrade broke something past the package level
+// (schema/data, not just code), there was no tested way back. This is cheap
+// insurance: a timestamped tar.gz of the whole data directory taken right
+// before the package swap, with a keep-last-3 retention policy.
+//
+// Native-backup alternative considered and rejected: Harper ships a
+// `get_backup` operation (@harperfast/harper's dataLayer/getBackup.ts,
+// wired in server/serverHelpers/serverUtilities.ts, documented in
+// components/mcp/tools/schemas/operationDescriptions.ts) that streams a
+// live backup over the running HTTP operations API. It's available in this
+// OSS tier (no license/tier gate found in operation_authorization.ts — just
+// `requires_su`), but it backs up ONE database/table at a time
+// (GetBackupObject requires `schema`/`table`, or defaults to a single "data"
+// database) — not the whole `~/.flair/data` tree: no config, no
+// users/roles, no keys, no other schemas. Using it here would mean
+// enumerating every schema/table and making N authenticated HTTP calls
+// against a server this same command is about to take down — for a LESS
+// complete result than a plain recursive file copy, and one that can't run
+// at all once the server is stopped (it's an operations-API call, not a
+// standalone filesystem utility). Rejected in favor of the file-level
+// snapshot below. See docs/upgrade.md for the restore procedure this
+// produces.
+const UPGRADE_SNAPSHOT_ROOT = resolve(homedir(), ".flair", "upgrade-snapshots");
+const UPGRADE_SNAPSHOT_RETAIN = 3;
+function upgradeSnapshotFileName() {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return `flair-data-${ts}.tar.gz`;
+}
+/**
+ * Snapshot `dataDir` (normally ~/.flair/data) into a timestamped tar.gz
+ * under ~/.flair/upgrade-snapshots/.
+ *
+ * Consistency: the caller is expected to have stopped Flair first (a
+ * running Harper's data dir can be mid-write, and a plain file copy of a
+ * live database directory isn't guaranteed point-in-time consistent —
+ * Harper 5.x's engine is RocksDB, verified from the .sst/WAL/MANIFEST
+ * layout under database/*, and a torn WAL/SST set won't open) — this
+ * function itself doesn't stop anything, it just archives whatever is on
+ * disk right now.
+ *
+ * Preserves file modes exactly — deliberately NOT using tar's `portable`
+ * option (used elsewhere in this file for the deploy tarball and session
+ * snapshots), which flattens every entry's mode to a umask-based "reasonable
+ * default" and would turn 0600 key/admin-pass files into whatever that
+ * default is. Never follows symlinks out of `dataDir`: node-tar already
+ * archives symlinks as symlinks by default (no `follow` option set here),
+ * and the filter below additionally skips any symlink whose resolved target
+ * falls outside `dataDir`, plus any non-regular file (sockets, FIFOs, device
+ * nodes — e.g. a stale `operations-server` domain socket left behind by a
+ * prior run) that tar can't meaningfully archive anyway.
+ *
+ * Throws on any failure — `flair upgrade` treats a snapshot failure as
+ * abort-the-upgrade by default (safe default; --no-snapshot is the opt-out
+ * for hosts that can't spare the time/disk).
+ *
+ * `snapshotRoot` defaults to UPGRADE_SNAPSHOT_ROOT (~/.flair/upgrade-snapshots)
+ * but is an explicit parameter — not read from homedir() internally — so
+ * unit tests can point it at a throwaway temp dir instead of this machine's
+ * real ~/.flair (test/unit/upgrade-data-snapshot.test.ts).
+ */
+export async function createDataSnapshot(dataDir, snapshotRoot = UPGRADE_SNAPSHOT_ROOT) {
+    mkdirSync(snapshotRoot, { recursive: true, mode: 0o700 });
+    const snapshotPath = join(snapshotRoot, upgradeSnapshotFileName());
+    // realpath, not just resolve() — on macOS (and some Linux distros) the
+    // system temp dir itself sits behind a symlink (/tmp -> /private/tmp), so
+    // a plain lexical resolve() of `dataDir` would never equal the realpath()
+    // of a symlink target genuinely INSIDE it, misclassifying every in-bounds
+    // symlink as an escape.
+    const resolvedDataDir = realpathSync(resolve(dataDir));
+    const filter = (entryPath) => {
+        // entryPath is relative to `cwd` (dataDir) per tar's create() contract.
+        const abs = resolve(resolvedDataDir, entryPath);
+        let st;
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            return false; // vanished between readdir and stat — skip, don't crash the snapshot
+        }
+        if (st.isSocket() || st.isFIFO() || st.isCharacterDevice() || st.isBlockDevice()) {
+            console.error(`  (skipping non-regular file in snapshot: ${entryPath})`);
+            return false;
+        }
+        if (st.isSymbolicLink()) {
+            let real;
+            try {
+                real = realpathSync(abs);
+            }
+            catch {
+                console.error(`  (skipping broken symlink in snapshot: ${entryPath})`);
+                return false;
+            }
+            const withinDataDir = real === resolvedDataDir || real.startsWith(resolvedDataDir + sep);
+            if (!withinDataDir) {
+                console.error(`  (skipping symlink pointing outside the data dir: ${entryPath})`);
+                return false;
+            }
+        }
+        return true;
+    };
+    // preservePaths: true — WITHOUT it, node-tar strips the leading `/` off
+    // any absolute symlink target it archives (found the hard way: an
+    // in-bounds symlink pointing at an absolute path under `dataDir` came
+    // back on extraction as a nonsense RELATIVE path, silently broken). Every
+    // entry path here is already relative (fileList is `["."]`, cwd is
+    // `dataDir`) — this only affects symlink target text, restoring it
+    // verbatim, which is exactly what a same-host restore into the original
+    // ~/.flair/data path needs.
+    await tarCreate({ gzip: true, cwd: resolvedDataDir, file: snapshotPath, filter, preservePaths: true }, ["."]);
+    // Owner-only — the archive can contain 0600 key/admin-pass material.
+    chmodSync(snapshotPath, 0o600);
+    return { path: snapshotPath, bytes: statSync(snapshotPath).size };
+}
+/**
+ * Keep only the newest `retain` upgrade snapshots, deleting older ones.
+ * Best-effort: a pruning failure is logged, not thrown — it must never
+ * un-succeed an upgrade whose snapshot already landed safely on disk.
+ * Returns the paths removed.
+ *
+ * `snapshotRoot` is explicit for the same testability reason as
+ * `createDataSnapshot` above.
+ */
+export function pruneOldSnapshots(retain = UPGRADE_SNAPSHOT_RETAIN, snapshotRoot = UPGRADE_SNAPSHOT_ROOT) {
+    if (!existsSync(snapshotRoot))
+        return [];
+    const removed = [];
+    try {
+        const files = readdirSync(snapshotRoot)
+            .filter((f) => f.startsWith("flair-data-") && f.endsWith(".tar.gz"))
+            .map((f) => join(snapshotRoot, f))
+            .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+        for (const stale of files.slice(retain)) {
+            try {
+                rmSync(stale, { force: true });
+                removed.push(stale);
+            }
+            catch (err) {
+                console.error(`  (could not prune old snapshot ${stale}: ${err.message})`);
+            }
+        }
     }
-    const { execSync, execFileSync } = await import("node:child_process");
-    const checkOnly = opts.check ?? false;
-    const showAll = opts.all ?? false;
-    console.log("Checking for updates...\n");
-    const packages = [
-        {
-            name: "@tpsdev-ai/flair",
-            kind: "bin",
+    catch (err) {
+        console.error(`  (snapshot retention check failed: ${err.message})`);
+    }
+    return removed;
+}
+export function decideUpgradeSnapshotAction(flairIsUpgrading, snapshotRequested, hasDataDir) {
+    if (!flairIsUpgrading)
+        return "not-upgrading";
+    if (!snapshotRequested)
+        return hasDataDir ? "nudge" : "not-upgrading";
+    return hasDataDir ? "snapshot" : "no-data";
+}
+/**
+ * The exact non-blocking recommendation nudge printed when `flair upgrade`
+ * runs without --snapshot (the default) and a data dir exists to snapshot.
+ * Exported as a constant — not inlined in two places — so the CLI output and
+ * its unit test assertion can't drift apart. Modeled on Harper's own
+ * upgrade prompt ("if you have not created a backup of your data, we
+ * recommend you cancel and back up before proceeding") but informational,
+ * never blocking: this must stay safe for non-interactive/scripted upgrades.
+ */
+export const UPGRADE_SNAPSHOT_NUDGE_LINES = [
+    "No pre-upgrade snapshot will be taken.",
+    "To capture one first: `flair snapshot create` (physical) or `flair backup` (logical export), or re-run with --snapshot.",
+];
+// ─── flair snapshot ─────────────────────────────────────────────────────────
+// Explicit, first-class surface for the physical data-dir snapshot mechanism
+// above (createDataSnapshot / pruneOldSnapshots / UPGRADE_SNAPSHOT_ROOT).
+// Added alongside the opt-in rewrite of `flair upgrade`'s snapshot trigger
+// (2026-07-08) so taking one is a real command, not just a side effect of
+// upgrading with --snapshot.
+//
+// Deliberately NOT named/shaped like `flair backup` / `flair restore`
+// (further below) — those are a LOGICAL export/import of Agent/Memory/Soul
+// records as JSON over the HTTP API, portable across hosts and versions.
+// `flair snapshot` is a PHYSICAL, byte-exact tar.gz of the whole
+// ~/.flair/data directory (RocksDB files, keys, config, admin-pass — every
+// byte, same host, same version) taken with Flair stopped for consistency.
+// Different mechanism, different restore procedure, different failure
+// modes — hence its own namespace (`snapshot create|list|restore`) instead
+// of overloading the JSON one. Mirrors the `rem snapshot` / `session
+// snapshot` subcommand idiom used elsewhere in this file.
+const snapshotCmd = program
+    .command("snapshot")
+    .description("Physical ~/.flair/data snapshots (byte-exact tar.gz, local-only — see `flair backup`/`flair restore` for the logical JSON export/import)");
+snapshotCmd
+    .command("create")
+    .description("Take a physical snapshot of the Flair data directory now (briefly stops Flair for a consistent copy — use `flair backup` for a no-downtime logical export)")
+    .option("--data-dir <path>", "Data directory to snapshot (default: ~/.flair/data)")
+    .option("--port <port>", "Harper HTTP port (used to quiesce Flair around the snapshot)")
+    .action(async (opts) => {
+    const dataDir = opts.dataDir ? resolve(opts.dataDir) : defaultDataDir();
+    const port = resolveHttpPort(opts);
+    if (!existsSync(dataDir)) {
+        console.error(`Error: data directory does not exist: ${dataDir}`);
+        process.exit(1);
+    }
+    console.log(`Snapshotting ${dataDir}...`);
+    console.log("(Flair will be briefly stopped for a point-in-time-consistent copy, then restarted.)");
+    // Same consistency requirement as the upgrade path's snapshot step: a
+    // live RocksDB directory (WAL/MANIFEST/SST) isn't safe to copy while
+    // Flair is running, so this stops Flair, snapshots, and restarts it —
+    // same stop/start helpers `flair upgrade`'s snapshot step uses, so a
+    // standalone `flair snapshot create` gives the exact same
+    // point-in-time-consistent guarantee, not a weaker one.
+    let stoppedForSnapshot = false;
+    try {
+        await stopFlairProcess(port);
+        stoppedForSnapshot = true;
+        const snapshot = await createDataSnapshot(dataDir);
+        const removed = pruneOldSnapshots();
+        console.log(`✅ Snapshot: ${snapshot.path} (${humanBytes(snapshot.bytes)})`);
+        if (removed.length > 0) {
+            console.log(`   Pruned ${removed.length} older snapshot${removed.length > 1 ? "s" : ""} (keeping last ${UPGRADE_SNAPSHOT_RETAIN})`);
+        }
+    }
+    catch (err) {
+        console.error(`❌ snapshot failed: ${err.message}`);
+        if (stoppedForSnapshot) {
+            try {
+                await startFlairProcess(port);
+            }
+            catch { /* best effort — surface the original snapshot error, not this */ }
+        }
+        process.exit(1);
+    }
+    try {
+        await startFlairProcess(port);
+    }
+    catch (err) {
+        console.error(`❌ the snapshot succeeded but Flair failed to restart: ${err.message}`);
+        console.error("   Check: flair doctor");
+        process.exit(1);
+    }
+});
+snapshotCmd
+    .command("list")
+    .description("List physical data snapshots under ~/.flair/upgrade-snapshots/")
+    .option("--json", "Output as JSON")
+    .action((opts) => {
+    if (!existsSync(UPGRADE_SNAPSHOT_ROOT)) {
+        if (opts.json) {
+            console.log("[]");
+            return;
+        }
+        console.log(`(no snapshots — ${UPGRADE_SNAPSHOT_ROOT} does not exist yet)`);
+        console.log("Run `flair snapshot create` to make one, or `flair upgrade --snapshot` to take one automatically before an upgrade.");
+        return;
+    }
+    const rows = readdirSync(UPGRADE_SNAPSHOT_ROOT)
+        .filter((f) => f.startsWith("flair-data-") && f.endsWith(".tar.gz"))
+        .map((f) => {
+        const p = join(UPGRADE_SNAPSHOT_ROOT, f);
+        const s = statSync(p);
+        return { file: f, path: p, size: s.size, mtime: s.mtime.toISOString() };
+    })
+        .sort((a, b) => b.mtime.localeCompare(a.mtime));
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("(no snapshots)");
+        return;
+    }
+    const fileW = Math.max(20, ...rows.map((r) => r.file.length));
+    console.log(`  ${"file".padEnd(fileW)}  size      age`);
+    for (const r of rows) {
+        console.log(`  ${r.file.padEnd(fileW)}  ${humanBytes(r.size).padEnd(8)}  ${relativeTime(r.mtime)}`);
+    }
+    console.log(`\n${rows.length} snapshot${rows.length > 1 ? "s" : ""}.`);
+});
+snapshotCmd
+    .command("restore <path>")
+    .description("Restore a physical snapshot: stops Flair, replaces the data directory, restarts")
+    .option("--data-dir <path>", "Data directory to replace (default: ~/.flair/data)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--yes", "Skip the confirmation prompt (this destroys the current data directory)")
+    .action(async (snapshotArg, opts) => {
+    const snapshotPath = resolve(snapshotArg);
+    if (!existsSync(snapshotPath)) {
+        console.error(`Error: snapshot does not exist: ${snapshotPath}`);
+        process.exit(1);
+    }
+    const dataDir = opts.dataDir ? resolve(opts.dataDir) : defaultDataDir();
+    const port = resolveHttpPort(opts);
+    console.log("This will STOP Flair, DELETE the current data directory, and replace it with:");
+    console.log(`  snapshot: ${snapshotPath}`);
+    console.log(`  target:   ${dataDir}`);
+    if (!opts.yes) {
+        if (!process.stdin.isTTY) {
+            console.error("\nError: refusing to destroy the data directory in a non-interactive shell without --yes.");
+            process.exit(1);
+        }
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((res) => rl.question(`\nDestroy ${dataDir} and restore from this snapshot? [y/N] `, (a) => { rl.close(); res(a); }));
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            console.log("Aborted.");
+            return;
+        }
+    }
+    try {
+        await stopFlairProcess(port);
+    }
+    catch (err) {
+        console.error(`❌ failed to stop Flair: ${err.message}`);
+        process.exit(1);
+    }
+    try {
+        rmSync(dataDir, { recursive: true, force: true });
+        mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+        // preservePaths mirrors createDataSnapshot's own preservePaths: true —
+        // restores absolute symlink targets verbatim instead of node-tar's
+        // default of stripping the leading "/" on extraction. No `follow`
+        // option, so symlinks extract as symlinks (never their targets'
+        // contents), and file modes extract exactly as stored — the archive
+        // itself already only contains what createDataSnapshot's filter chose
+        // to include (in-bounds symlinks, regular files/dirs only), so restore
+        // needs no re-filtering of its own.
+        await tarExtract({ file: snapshotPath, cwd: dataDir, preservePaths: true });
+    }
+    catch (err) {
+        console.error(`❌ restore failed: ${err.message}`);
+        console.error(`   ${dataDir} may be partially restored or empty — do not start Flair until this is resolved.`);
+        process.exit(1);
+    }
+    try {
+        await startFlairProcess(port);
+    }
+    catch (err) {
+        console.error(`❌ restore succeeded but Flair failed to restart: ${err.message}`);
+        console.error("   Check: flair doctor");
+        process.exit(1);
+    }
+    console.log(`✅ Restored ${dataDir} from ${snapshotPath}`);
+    console.log("   Flair restarted. Verify: flair status && flair doctor");
+});
+// ─── flair upgrade ────────────────────────────────────────────────────────────
+program
+    .command("upgrade")
+    .description("Upgrade Flair — local packages by default, or a deployed Fabric with --target")
+    .option("--check", "Only check for updates / show the plan, don't install or deploy")
+    .option("--restart", "[deprecated] no-op — restart now happens automatically after upgrade; use --no-restart to opt out")
+    .option("--no-restart", "Skip the restart after upgrade (stage new packages now, restart later)")
+    .option("--no-verify", "Skip post-restart health/version/auth verification (default: verify — so a broken upgrade can't report success; see flair#635)")
+    .option("--snapshot", "Take a pre-upgrade ~/.flair/data snapshot before the package swap, keep-last-3 retention (default: off — see `flair snapshot create` to take one by hand, or `flair backup` for a logical export; flair#637)")
+    .option("--all", "Show transitive packages (e.g. flair-client) in the listing — verbose mode for debugging dep versions")
+    // ── Fabric upgrade (--target) ────────────────────────────────────────────
+    // When --target is passed, upgrade the Flair component DEPLOYED to that
+    // Harper Fabric URL instead of the local npm install. Reuses `flair deploy`
+    // under the hood with the @harperfast/harper pin baked in (flair#513).
+    .option("--target <url>", "Upgrade the Flair deployed to this Fabric URL (not the local install)")
+    .option("--fabric-user <user>", "Fabric admin username — for --target (env: FABRIC_USER preferred; inline leaks to shell history)")
+    .option("--fabric-password <pass>", "Fabric admin password — for --target (prefer FABRIC_PASSWORD env or --fabric-password-file; inline leaks to shell history)")
+    .option("--fabric-password-file <path>", "Read the Fabric admin password from a file (chmod 600) — for --target")
+    .option("--version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
+    .option("--harper-version <semver>", "Pin @harperfast/harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
+    .option("--project <name>", "Fabric component name for --target", "flair")
+    .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
+    .option("--yes", "Skip the confirmation prompt for --target")
+    .option("--no-fleet-verify", "Skip the automatic post-upgrade fleet convergence sweep for --target (default: sweep runs — see flair#636)")
+    .action(async (opts) => {
+    // ── Fabric-upgrade branch ───────────────────────────────────────────────
+    if (opts.target) {
+        await runFabricUpgrade(opts);
+        return;
+    }
+    const { execFileSync } = await import("node:child_process");
+    const checkOnly = opts.check ?? false;
+    const showAll = opts.all ?? false;
+    console.log("Checking for updates...\n");
+    const packages = [
+        {
+            name: "@tpsdev-ai/flair",
+            kind: "bin",
             probe: () => probeBinVersion(execFileSync, "flair"),
         },
         {
@@ -5884,7 +6917,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 +6960,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 +6979,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");
@@ -5978,11 +7011,108 @@ program
         }
         return;
     }
+    // Hoisted here (was previously computed after install/restart) — the
+    // pre-upgrade snapshot below needs to know the target port AND whether a
+    // restart is coming, before any package is touched. Pure function of
+    // `opts` — safe to call this early.
+    const { restart: shouldRestart, verify: shouldVerify, deprecatedRestartFlagUsed } = resolveUpgradeRestartVerify(opts);
+    const upgradePort = resolveHttpPort({});
+    // ── Pre-upgrade data snapshot (flair#637, opt-in as of the 2026-07-08 rewire) ──
+    // Only an @tpsdev-ai/flair package swap touches the code that reads/
+    // writes ~/.flair/data — an flair-mcp-only or openclaw-plugin-only
+    // upgrade never runs different Harper/Flair code against the data, so
+    // there's nothing at risk and nothing to snapshot.
+    //
+    // Decision (Nathan, 2026-07-08): the physical snapshot used to run
+    // automatically on every local upgrade (opt-out via --no-snapshot). That
+    // defaulted every upgrade into tarring the entire data dir (can be
+    // 800MB+, keep-last-3 retention ~2.5GB) for a failure mode the
+    // tested-downgrade guarantee (docs/upgrade.md, test/compat/downgrade-
+    // boot.test.ts) already covers — and it diverged from Harper's own
+    // upgrade CLI, which recommends a backup before proceeding but never
+    // auto-tars the data directory itself. `--snapshot` is now opt-in, off
+    // by default; opting out gets a non-blocking recommendation nudge
+    // instead of a silent skip. The underlying mechanism (createDataSnapshot
+    // / pruneOldSnapshots, the stop-snapshot-restart quiesce dance, and
+    // abort-the-upgrade-on-snapshot-failure) is unchanged — only the trigger
+    // moved from opt-out to opt-in. `flair snapshot create` (below) exposes
+    // the exact same mechanism as a standalone command for anyone who wants
+    // one without wrapping it around an upgrade.
+    const flairIsUpgrading = npmUpgrades.some((u) => u.pkg === "@tpsdev-ai/flair");
+    const snapshotDataDir = defaultDataDir();
+    const snapshotDecision = decideUpgradeSnapshotAction(flairIsUpgrading, !!opts.snapshot, existsSync(snapshotDataDir));
+    let snapshotPath = null;
+    if (snapshotDecision === "nudge") {
+        // Non-blocking nudge only — never prompt/block here, this must stay
+        // safe for non-interactive/scripted upgrades. Modeled on Harper's own
+        // upgrade prompt ("if you have not created a backup ... we recommend
+        // you cancel and back up before proceeding") but informational, not a
+        // gate.
+        console.log("");
+        for (const line of UPGRADE_SNAPSHOT_NUDGE_LINES)
+            console.log(render.wrap(render.c.dim, line));
+    }
+    else if (snapshotDecision === "no-data") {
+        console.log(`\n(no data directory at ${snapshotDataDir} yet — nothing to snapshot)`);
+    }
+    else if (snapshotDecision === "snapshot") {
+        console.log("\nSnapshotting data before upgrade...");
+        // Consistency: a running Harper's data dir can be mid-write, and a
+        // plain file copy of a live database directory isn't guaranteed
+        // point-in-time consistent (Harper 5.x = RocksDB: WAL/SST/MANIFEST
+        // can tear under a live copy). Stopping first — then immediately
+        // restarting the OLD version, before any package changes — gives a
+        // quiesced, safe-to-copy directory with only a brief blip, even for
+        // --no-restart (the snapshot's correctness doesn't depend on
+        // whether the caller wants a restart AFTER the upgrade — those are
+        // orthogonal). See docs/upgrade.md for the native-backup alternative
+        // considered and rejected (Harper's `get_backup` op backs up one
+        // table/schema at a time over the running HTTP API — not the whole
+        // data dir — and rejecting it here means this path never depends on
+        // the server being up).
+        let stoppedForSnapshot = false;
+        try {
+            await stopFlairProcess(upgradePort);
+            stoppedForSnapshot = true;
+            const snapshot = await createDataSnapshot(snapshotDataDir);
+            snapshotPath = snapshot.path;
+            const removed = pruneOldSnapshots();
+            console.log(`✅ Snapshot: ${snapshotPath} (${humanBytes(snapshot.bytes)})`);
+            console.log(`   Restore: flair snapshot restore "${snapshotPath}"`);
+            if (removed.length > 0) {
+                console.log(`   Pruned ${removed.length} older snapshot${removed.length > 1 ? "s" : ""} (keeping last ${UPGRADE_SNAPSHOT_RETAIN})`);
+            }
+        }
+        catch (err) {
+            console.error(`❌ snapshot failed: ${err.message}`);
+            console.error("   Aborting upgrade — no packages were changed. Omit --snapshot to proceed without one (not recommended).");
+            if (stoppedForSnapshot) {
+                try {
+                    await startFlairProcess(upgradePort);
+                }
+                catch { /* best effort — surface the original snapshot error, not this */ }
+            }
+            process.exit(1);
+        }
+        try {
+            await startFlairProcess(upgradePort);
+        }
+        catch (err) {
+            console.error(`❌ failed to restart Flair after the pre-upgrade snapshot: ${err.message}`);
+            console.error(`   The snapshot itself succeeded (${snapshotPath}) — no packages were changed. Check: flair doctor`);
+            process.exit(1);
+        }
+    }
     // Perform upgrade. `latest` comes from the npm registry's HTTP
     // response, so CodeQL (correctly) treats it as untrusted input.
     // Use execFileSync with argv — the spec `<name>@<version>` becomes a
     // single argument to the upgrade command, no shell to inject into.
     console.log(`\nUpgrading ${totalUpgrades} package${totalUpgrades > 1 ? "s" : ""}...\n`);
+    // Tracked separately (rather than inferred from findings alone) because the
+    // post-restart verify/rollback step below needs to know whether @tpsdev-ai/flair's
+    // OWN install actually succeeded — if it failed, the running version is still the
+    // OLD one and verification should expect that, not the target we failed to reach.
+    let flairInstallFailed = false;
     for (const { pkg, latest } of npmUpgrades) {
         try {
             console.log(`  Installing ${pkg}@${latest}...`);
@@ -5991,6 +7121,8 @@ program
         }
         catch (err) {
             console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
+            if (pkg === "@tpsdev-ai/flair")
+                flairInstallFailed = true;
         }
     }
     for (const { pkg, latest } of openclawUpgrades) {
@@ -6013,31 +7145,107 @@ program
             console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
         }
     }
-    if (opts.restart) {
-        console.log("\nRestarting Flair...");
-        try {
-            const port = resolveHttpPort({});
-            const label = "ai.tpsdev.flair";
-            const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
-            if (process.platform === "darwin" && existsSync(plistPath)) {
-                try {
-                    execSync(`launchctl stop ${label}`, { stdio: "pipe" });
-                }
-                catch { }
-                await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
-                console.log("✅ Flair restarted with new version");
-            }
-            else {
-                console.log("Run: flair restart");
-            }
-        }
-        catch {
-            console.log("Run: flair restart");
-        }
+    // ── Restart + verify + rollback (flair#635) ─────────────────────────────
+    // Decision (2026-07-08): restart is now the default post-upgrade step —
+    // installing new code without restarting leaves the OLD process serving
+    // while the version on disk lies about what's actually running.
+    // --no-restart opts back out for the "stage now, bounce later" case.
+    // --restart is kept as a deprecated no-op for old muscle memory.
+    // Upgrade = install → restart → verify → (rollback on failure), one
+    // transaction — never report success on a broken restart.
+    const flairFinding = findings.find((f) => f.name === "@tpsdev-ai/flair");
+    const previousFlairVersion = flairFinding?.installed ?? null;
+    const expectedFlairVersion = flairFinding?.status === "outdated" && !flairInstallFailed
+        ? flairFinding.latest
+        : flairFinding?.installed ?? null;
+    // shouldRestart/shouldVerify/deprecatedRestartFlagUsed were hoisted above
+    // the pre-upgrade snapshot block — it needs to know these before any
+    // package is touched.
+    if (deprecatedRestartFlagUsed) {
+        console.error("warning: --restart is deprecated and is now a no-op — flair upgrade restarts by default. Use --no-restart to skip it.");
+    }
+    if (!shouldRestart) {
+        console.log("\nRun: flair restart to use the new version");
+        return;
+    }
+    console.log("\nRestarting Flair...");
+    const port = upgradePort;
+    const baseUrl = `http://127.0.0.1:${port}`;
+    try {
+        await restartFlair(port);
+    }
+    catch (err) {
+        console.error(`❌ restart failed: ${err.message}`);
+        console.error("   Flair may be partially down. Check: flair doctor");
+        process.exit(1);
+    }
+    console.log("✅ Flair restarted");
+    if (!shouldVerify) {
+        console.log("  (--no-verify: skipping post-restart verification)");
+        return;
+    }
+    console.log("\nVerifying...");
+    // The authenticated leg dogfoods api()'s local-credential resolution
+    // (flair#640: env > agent key > ~/.flair/admin-pass file) — probeInstance
+    // itself never resolves credentials, it just calls whatever's handed to it.
+    const verify = await probeInstance(baseUrl, {
+        expectVersion: expectedFlairVersion ?? undefined,
+        timeoutMs: STARTUP_TIMEOUT_MS,
+        authedGet: (path) => api("GET", path, undefined, { baseUrl }),
+    });
+    const verdict = decideAfterVerify(verify, previousFlairVersion);
+    if (verdict.kind === "ok") {
+        console.log(`✅ verified: healthy, authenticated${verify.version ? `, running ${verify.version}` : ""}`);
+        return;
+    }
+    console.error(`❌ post-restart verification failed: ${verdict.reason}`);
+    if (verdict.kind === "cannot-rollback") {
+        console.error("   Cannot roll back automatically: the previously-installed @tpsdev-ai/flair version is unknown.");
+        console.error("   Check the instance now: flair doctor");
+        process.exit(1);
+    }
+    console.log(`\nRolling back @tpsdev-ai/flair to ${verdict.toVersion}...`);
+    try {
+        execFileSync("npm", ["install", "-g", `@tpsdev-ai/flair@${verdict.toVersion}`], { stdio: "pipe" });
+    }
+    catch (err) {
+        console.error(`❌ rollback install failed: ${err.message}`);
+        console.error(`   Flair is currently running the FAILED version (${expectedFlairVersion ?? "unknown"}). Manual intervention required.`);
+        process.exit(1);
+    }
+    try {
+        await restartFlair(port);
+    }
+    catch (err) {
+        console.error(`❌ rollback restart failed: ${err.message}`);
+        console.error("   Instance state is UNKNOWN — it may be down entirely. Check: flair doctor");
+        process.exit(1);
+    }
+    const rollbackVerify = await probeInstance(baseUrl, {
+        expectVersion: verdict.toVersion,
+        timeoutMs: STARTUP_TIMEOUT_MS,
+        authedGet: (path) => api("GET", path, undefined, { baseUrl }),
+    });
+    const rollbackVerdict = decideAfterRollbackVerify(rollbackVerify);
+    if (rollbackVerdict.kind === "rolled-back") {
+        console.error(`❌ upgrade failed verification and was rolled back to @tpsdev-ai/flair@${verdict.toVersion}.`);
+        console.error(`   Original failure: ${verdict.reason}`);
+        process.exit(1);
+    }
+    console.error(`❌❌ ROLLBACK ALSO FAILED VERIFICATION: ${rollbackVerdict.reason}`);
+    console.error("   Instance state is UNKNOWN — do not assume data integrity.");
+    // This double-failure isn't auto-recoverable yet (flair#637) — but if a
+    // pre-upgrade snapshot landed, point at the CONCRETE path instead of
+    // just the issue number, so recovery doesn't start with a GitHub search.
+    if (snapshotPath) {
+        console.error(`   A pre-upgrade snapshot is available: ${snapshotPath}`);
+        console.error(`   Restore: flair snapshot restore "${snapshotPath}" (or see docs/upgrade.md#downgrade).`);
     }
     else {
-        console.log("\nRun: flair restart to use the new version");
+        console.error("   No pre-upgrade snapshot was taken for this run (snapshot is opt-in — pass --snapshot next time, or ~/.flair/data didn't exist yet).");
+        console.error("   Check `flair snapshot list` for a manual one, or restore from a `flair backup` JSON export. See docs/upgrade.md#downgrade.");
     }
+    process.exit(1);
 });
 // ─── flair stop ───────────────────────────────────────────────────────────────
 program
@@ -6132,9 +7340,12 @@ program
     }
     const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
     const opsPort = resolveOpsPort(opts);
+    const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
     const env = {
         ...process.env,
         ROOTPATH: dataDir,
+        // See the matching comment at the install-time spawn site above.
+        FLAIR_MODELS_DIR: modelsDir,
         DEFAULTS_MODE: "dev",
         HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
         HTTP_PORT: String(port),
@@ -6146,6 +7357,8 @@ program
     if (adminPass) {
         env.HDB_ADMIN_PASSWORD = adminPass;
     }
+    // models (flair#504 Phase 1): no env var needed — resources/embeddings-boot.ts
+    // self-registers the backend in-process on every boot (flair#694).
     const proc = spawn(process.execPath, [bin, "run", "."], {
         cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
     });
@@ -6160,14 +7373,20 @@ program
     }
 });
 // ─── flair restart ────────────────────────────────────────────────────────────
-program
-    .command("restart")
-    .description("Restart the Flair (Harper) instance")
-    .option("--port <port>", "Harper HTTP port")
-    .action(async (opts) => {
-    const port = resolveHttpPort(opts);
-    const platform = process.platform;
-    if (platform === "darwin") {
+/**
+ * Stop the local Flair (Harper) process — launchd `stop` on darwin when a
+ * plist is present (falling back on failure), otherwise a manual SIGTERM by
+ * port. Split out of the old monolithic `restartFlair` (flair#637) so the
+ * pre-upgrade snapshot can quiesce the data directory between a stop and a
+ * start without duplicating this logic — `restartFlair` is now just
+ * `stopFlairProcess` followed by `startFlairProcess`.
+ *
+ * Idempotent-ish: stopping an already-stopped instance is a harmless no-op
+ * on both paths (launchctl stop on an unloaded/idle service, or an empty
+ * `lsof` match).
+ */
+async function stopFlairProcess(port) {
+    if (process.platform === "darwin") {
         const label = "ai.tpsdev.flair";
         const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
         if (existsSync(plistPath)) {
@@ -6178,9 +7397,10 @@ program
                     execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
                 }
                 catch { }
-                // Capture the current PID *before* stopping so we can verify exit. Without
-                // this, waitForHealth can race against the still-shutting-down old process
-                // and return success before KeepAlive brings the new one up.
+                // Capture the current PID *before* stopping so callers that
+                // immediately restart can verify exit. Without this, waitForHealth
+                // can race against the still-shutting-down old process and return
+                // success before KeepAlive brings the new one up.
                 const oldPid = readHarperPid(defaultDataDir());
                 try {
                     execSync(`launchctl stop ${label}`, { stdio: "pipe" });
@@ -6188,69 +7408,122 @@ program
                 catch { }
                 if (oldPid)
                     await waitForProcessExit(oldPid, STARTUP_TIMEOUT_MS);
-                await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
-                console.log("✅ Flair restarted");
                 return;
             }
             catch (err) {
-                console.error(`launchd restart failed, falling back to port restart: ${err.message}`);
+                console.error(`launchd stop failed, falling back to port-based stop: ${err.message}`);
             }
         }
     }
-    {
-        // Port-based restart (Linux, or macOS fallback)
-        console.log("Stopping...");
-        try {
-            const { execSync } = await import("node:child_process");
-            const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
-            if (lsof) {
-                for (const pid of lsof.split("\n")) {
-                    try {
-                        process.kill(Number(pid.trim()), "SIGTERM");
-                    }
-                    catch { }
+    // Port-based stop (Linux, or macOS fallback when no launchd plist)
+    console.log("Stopping...");
+    try {
+        const { execSync } = await import("node:child_process");
+        const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+        if (lsof) {
+            for (const pid of lsof.split("\n")) {
+                try {
+                    process.kill(Number(pid.trim()), "SIGTERM");
                 }
-                // Wait briefly for shutdown
-                await new Promise(r => setTimeout(r, 2000));
+                catch { }
             }
+            // Wait briefly for shutdown
+            await new Promise(r => setTimeout(r, 2000));
         }
-        catch { /* not running */ }
-        console.log("Starting...");
-        const bin = harperBin();
-        if (!bin) {
-            console.error("❌ Harper binary not found. Run 'flair init' first.");
-            process.exit(1);
-        }
-        const dataDir = defaultDataDir();
-        // Match `flair start`: accept either HDB_ADMIN_PASSWORD or FLAIR_ADMIN_PASS.
-        // Without this, `flair init --admin-pass X` (which only exports HDB_*
-        // to the initial Harper spawn) followed by `flair restart` would silently
-        // drop admin credentials — any subsequent auth'd call returns 401.
-        const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
-        const env = {
-            ...process.env,
-            ROOTPATH: dataDir,
-            DEFAULTS_MODE: "dev",
-            HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
-            HTTP_PORT: String(port),
-            LOCAL_STUDIO: "false",
-        };
-        if (adminPass) {
-            env.HDB_ADMIN_PASSWORD = adminPass;
-        }
-        const proc = spawn(process.execPath, [bin, "run", "."], {
-            cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
-        });
-        proc.unref();
-        try {
-            await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
-            console.log("✅ Flair restarted");
-        }
-        catch {
-            console.error("❌ Flair failed to restart within timeout");
-            process.exit(1);
+    }
+    catch { /* not running */ }
+}
+/**
+ * Start the local Flair (Harper) process — launchd `start` on darwin when a
+ * plist is present (falling back on failure), otherwise a direct spawn.
+ * Counterpart to `stopFlairProcess`; see that function's doc comment.
+ */
+async function startFlairProcess(port) {
+    if (process.platform === "darwin") {
+        const label = "ai.tpsdev.flair";
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        if (existsSync(plistPath)) {
+            try {
+                const { execSync } = await import("node:child_process");
+                try {
+                    execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
+                }
+                catch { }
+                try {
+                    execSync(`launchctl start ${label}`, { stdio: "pipe" });
+                }
+                catch { }
+                await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
+                return;
+            }
+            catch (err) {
+                console.error(`launchd start failed, falling back to direct start: ${err.message}`);
+            }
         }
     }
+    console.log("Starting...");
+    const bin = harperBin();
+    if (!bin) {
+        throw new Error("Harper binary not found. Run 'flair init' first.");
+    }
+    const dataDir = defaultDataDir();
+    // Match `flair start`: accept either HDB_ADMIN_PASSWORD or FLAIR_ADMIN_PASS.
+    // Without this, `flair init --admin-pass X` (which only exports HDB_*
+    // to the initial Harper spawn) followed by `flair restart` would silently
+    // drop admin credentials — any subsequent auth'd call returns 401.
+    const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
+    const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
+    const env = {
+        ...process.env,
+        ROOTPATH: dataDir,
+        // See the matching comment at the install-time spawn site above.
+        FLAIR_MODELS_DIR: modelsDir,
+        DEFAULTS_MODE: "dev",
+        HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
+        HTTP_PORT: String(port),
+        LOCAL_STUDIO: "false",
+    };
+    if (adminPass) {
+        env.HDB_ADMIN_PASSWORD = adminPass;
+    }
+    // models (flair#504 Phase 1): no env var needed — resources/embeddings-boot.ts
+    // self-registers the backend in-process on every boot (flair#694).
+    const proc = spawn(process.execPath, [bin, "run", "."], {
+        cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
+    });
+    proc.unref();
+    await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
+}
+/**
+ * The ONE restart mechanism for a local Flair install. Shared by `flair
+ * restart` and `flair upgrade`'s post-install restart step (flair#635) so
+ * the two never drift into two different ways to bounce the same process.
+ * Composed of `stopFlairProcess` + `startFlairProcess` (flair#637) — the
+ * pre-upgrade snapshot step calls those two directly with a snapshot taken
+ * in between, instead of going through this wrapper.
+ *
+ * Throws on failure instead of calling process.exit — callers decide how to
+ * react (`flair restart` exits 1; `flair upgrade` treats a failed restart as
+ * an upgrade failure and may attempt a rollback).
+ */
+async function restartFlair(port) {
+    await stopFlairProcess(port);
+    await startFlairProcess(port);
+}
+program
+    .command("restart")
+    .description("Restart the Flair (Harper) instance")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (opts) => {
+    const port = resolveHttpPort(opts);
+    try {
+        await restartFlair(port);
+        console.log("✅ Flair restarted");
+    }
+    catch (err) {
+        console.error(`❌ Flair failed to restart: ${err?.message ?? err}`);
+        process.exit(1);
+    }
 });
 // ─── flair uninstall ──────────────────────────────────────────────────────────
 program
@@ -6345,7 +7618,28 @@ program
     const dryRun = opts.dryRun ?? false;
     const batchSize = Number(opts.batchSize);
     const delayMs = Number(opts.delayMs);
-    const currentModel = process.env.FLAIR_EMBEDDING_MODEL ?? "nomic-embed-text-v1.5-Q4_K_M";
+    // flair#504 Phase 2: MUST match resources/embeddings-provider.ts's
+    // getModelId() — including THE GATE (EMBEDDING_PREFIXES_ENABLED), not
+    // just the suffix. Duplicated as literals, not imported, because
+    // src/cli.ts and resources/**.ts are separate build targets —
+    // tsconfig.cli.json's rootDir is "src" and only includes src/cli.ts +
+    // src/cli-shim.cts, and the published CLI package ships only dist/ built
+    // from that config (package.json's "files"), so resources/ isn't
+    // reachable from (or bundled into) the CLI binary. THE GATE is now ON
+    // (flipped, re-baselined through the ratchet gate — see
+    // embeddings-provider.ts's file header and PR #689 for the park history
+    // this flip revisits), so `currentModel` here is `<base>+searchprefix` —
+    // matching getModelId()'s gate-on return exactly. If
+    // EMBEDDING_PREFIXES_ENABLED or EMBEDDING_VARIANT ever changes in
+    // embeddings-provider.ts, update this block too — a drift here silently
+    // breaks `--stale-only`: it would compare every row's embeddingModel
+    // against the WRONG current-model string, so rows would read as already
+    // "current" (or as needing re-embed) out of sync with what getModelId()
+    // is actually stamping new writes with.
+    const EMBEDDING_PREFIXES_ENABLED = true; // MUST mirror resources/embeddings-provider.ts's gate
+    const EMBEDDING_VARIANT = "searchprefix";
+    const baseModel = process.env.FLAIR_EMBEDDING_MODEL ?? "nomic-embed-text-v1.5-Q4_K_M";
+    const currentModel = EMBEDDING_PREFIXES_ENABLED ? `${baseModel}+${EMBEDDING_VARIANT}` : baseModel;
     if (agentId) {
         console.log(`Re-embedding memories for agent: ${agentId}`);
     }
@@ -6638,8 +7932,9 @@ program
     .description("Deploy Flair as a component to a remote Harper Fabric cluster")
     .option("--fabric-org <org>", "Fabric org (env: FABRIC_ORG)")
     .option("--fabric-cluster <cluster>", "Fabric cluster within the org (env: FABRIC_CLUSTER)")
-    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER)")
-    .option("--fabric-password <pass>", "Fabric admin password (env: FABRIC_PASSWORD)")
+    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER preferred; inline leaks to shell history)")
+    .option("--fabric-password <pass>", "Fabric admin password (prefer FABRIC_PASSWORD env or --fabric-password-file; inline leaks to shell history)")
+    .option("--fabric-password-file <path>", "Read the Fabric admin password from a file (chmod 600)")
     .option("--fabric-token <token>", "OAuth bearer token (env: FABRIC_TOKEN) — reserved for future Fabric bearer support")
     .option("--target <url>", "Override the Fabric URL template (https://<cluster>.<org>.harperfabric.com)")
     .option("--project <name>", "Component name in Fabric", "flair")
@@ -6653,15 +7948,29 @@ program
     .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)")
+    .option("--no-fleet-verify", "Skip the automatic post-deploy fleet convergence sweep (default: sweep runs — see flair#636)")
     .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`;
+    let fabricUser;
+    let fabricPassword;
+    let credWarnings = [];
+    try {
+        ({ fabricUser, fabricPassword, warnings: credWarnings } = resolveFabricCredentials(opts));
+    }
+    catch (err) {
+        console.error(red(`Error: ${err.message}`));
+        process.exit(1);
+    }
     const deployOpts = {
         fabricOrg: opts.fabricOrg ?? process.env.FABRIC_ORG,
         fabricCluster: opts.fabricCluster ?? process.env.FABRIC_CLUSTER,
-        fabricUser: opts.fabricUser ?? process.env.FABRIC_USER,
-        fabricPassword: opts.fabricPassword ?? process.env.FABRIC_PASSWORD,
+        fabricUser,
+        fabricPassword,
         fabricToken: opts.fabricToken ?? process.env.FABRIC_TOKEN,
         target: opts.target,
         project: opts.project,
@@ -6675,6 +7984,8 @@ program
         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);
@@ -6684,11 +7995,10 @@ program
             console.error(`  - ${e}`);
         process.exit(1);
     }
-    // Warn on password-via-flag (leaks to shell history). Env is preferred.
-    if (opts.fabricPassword && !process.env.FABRIC_PASSWORD) {
-        console.error(dim("warning: --fabric-password leaks to shell history. " +
-            "Prefer FABRIC_PASSWORD env."));
-    }
+    // Never log the credential VALUES — only the flag names, via the
+    // resolver's own warning strings (see resolveFabricCredentials above).
+    for (const w of credWarnings)
+        console.error(dim(w));
     const url = buildDeployUrl(deployOpts);
     console.log(`${green("→")} Deploying ${deployOpts.project} to ${url}`);
     if (deployOpts.dryRun)
@@ -6700,9 +8010,43 @@ program
             console.log(dim(`  package root: ${result.packageRoot}`));
             return;
         }
-        console.log(`\n${green("✓")} Flair ${result.version} deployed${deployOpts.verify ? " and verified serving" : ""}`);
+        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}`);
+        // ── Post-deploy fleet sweep (flair#636) ─────────────────────────────
+        // Harper's own "Successfully deployed" (and the served-API verify
+        // above) only confirm the ORIGIN. This sweeps the origin + every known
+        // federation peer for actual version/health convergence — the gap that
+        // let the 0.21.0 deploy report success while a peer was still throwing
+        // 1006s. Skippable with --no-fleet-verify. Needs Basic-auth creds
+        // (fabricUser+fabricPassword) — a --fabric-token-only deploy has no way
+        // to authenticate the sweep, so it's skipped with a note instead of a
+        // silent no-op.
+        if (!shouldRunFleetVerify(opts)) {
+            console.log(dim("\n(--no-fleet-verify: skipping post-deploy fleet sweep)"));
+        }
+        else if (!deployOpts.fabricUser || !deployOpts.fabricPassword) {
+            console.log(dim("\n(skipping fleet verify — no --fabric-user/--fabric-password to authenticate the sweep; only --fabric-token was provided)"));
+        }
+        else {
+            console.log(`\n${green("→")} Fleet verify`);
+            const sweep = await sweepFleet({
+                target: result.url,
+                fabricUser: deployOpts.fabricUser,
+                fabricPassword: deployOpts.fabricPassword,
+                expectVersion: result.version,
+            });
+            console.log(renderFleetSweepTable(sweep));
+            if (sweep.exitCode !== FLEET_EXIT_OK) {
+                console.error(red(`\n✗ fleet verify failed (exit ${sweep.exitCode}) — deploy is NOT fully converged.`));
+                process.exit(sweep.exitCode);
+            }
+        }
         console.log(`\nNext steps:`);
         console.log(dim(`  1. Set an admin password in Fabric Studio (Cluster Settings → Admin)`));
         console.log(dim(`  2. Seed your first agent:`));
@@ -6720,9 +8064,73 @@ program
         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);
     }
 });
+// ─── flair fleet ──────────────────────────────────────────────────────────────
+//
+// Fabric fleet operations (flair#636). `flair deploy` / `flair upgrade
+// --target` already run this sweep automatically post-deploy (skippable
+// with --no-fleet-verify) — this is the standalone entry point for running
+// it independently, e.g. as a periodic health check or before a rolling
+// restart step (see the flair#636 decision comment: this sweep is the gate
+// between peers during a rolling restart, not the restart mechanism itself).
+const fleet = program.command("fleet").description("Fabric fleet operations (post-deploy convergence verification)");
+fleet
+    .command("verify")
+    .description("Sweep a Fabric origin + its known federation peers for version/health convergence")
+    .requiredOption("--target <url>", "Fabric URL to verify (the origin node)")
+    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER — preferred; inline leaks to ps/shell history)")
+    .option("--fabric-password <pass>", "Fabric admin password (prefer FABRIC_PASSWORD env or --fabric-password-file; inline leaks to shell history)")
+    .option("--fabric-password-file <path>", "Read the Fabric admin password from a mode-0600 file (keeps it out of argv and env)")
+    .option("--expect-version <semver>", "Version every node must report (default: the origin's own reported version — a self-consistency check)")
+    .option("--timeout <ms>", "Per-node /Health poll timeout in ms", "60000")
+    .option("--json", "Emit JSON (also: pipe + FLAIR_OUTPUT=json)")
+    .addHelpText("after", `
+Exit codes:
+  0  all nodes verified: healthy, authenticated, and version-matched
+  1  origin failed (unreachable, unauthenticated, or wrong version)
+  2  origin OK, but a reachable peer is running a DIFFERENT version (skew)
+  3  origin OK, no skew among reachable peers, but a peer could not be
+     verified at all (unreachable, auth rejected, or no endpoint on file)
+
+"peer" here means a Flair federation peer (GET /FederationPeers on the
+origin) — NOT Harper's own cluster-replication nodes, which the OSS
+@harperfast/harper build this CLI ships does not expose (cluster_status is
+a harper-pro-only operation). A Fabric replica that was never
+federation-paired (\`flair federation pair\`) is invisible to this sweep —
+see src/fleet-verify.ts's file header for the full caveat.`)
+    .action(async (opts) => {
+    // Single source of truth for cred resolution + shell-history warnings,
+    // shared with `flair upgrade --target` and `flair deploy`.
+    const { fabricUser, fabricPassword, warnings } = resolveFabricCredentials(opts);
+    for (const w of warnings)
+        console.error(render.wrap(render.c.dim, w));
+    if (!fabricUser || !fabricPassword) {
+        console.error(render.wrap(render.c.red, "flair fleet verify: credentials required"));
+        console.error("  set FABRIC_USER + FABRIC_PASSWORD env, or --fabric-password-file, or (discouraged) --fabric-user/--fabric-password inline");
+        process.exit(1);
+    }
+    const result = await sweepFleet({
+        target: opts.target,
+        fabricUser,
+        fabricPassword,
+        expectVersion: opts.expectVersion,
+        timeoutMs: Number(opts.timeout ?? 60_000),
+    });
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(result));
+    }
+    else {
+        console.log(render.wrap(render.c.bold, `Fleet verify — ${result.target}`));
+        console.log(renderFleetSweepTable(result));
+    }
+    process.exit(result.exitCode);
+});
 // ─── flair doctor ─────────────────────────────────────────────────────────────
 program
     .command("doctor")
@@ -6743,6 +8151,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 {
@@ -6864,6 +8290,53 @@ program
             issues++;
         }
     }
+    // 1a. CLI ↔ running-server version handshake (flair#695 §B) — the
+    // version TRIPLE: this CLI's own version (__pkgVersion, checked against
+    // npm-latest in step 0 above), and the RUNNING server's reported
+    // version (GET /Health — public, no auth needed). A mismatch means the
+    // installed package was upgraded but the daemon hasn't restarted onto
+    // it yet — exactly the bare-npm trap the global preAction hook (above,
+    // every other command) nudges about on stderr; doctor prints the full
+    // picture here instead of a one-liner and `--fix` offers the restart.
+    let runningVersion = null;
+    if (harperResponding) {
+        try {
+            const healthRes = await fetch(`${baseUrl}/Health`, { signal: AbortSignal.timeout(3000) });
+            if (healthRes.ok) {
+                const body = (await healthRes.json());
+                runningVersion = typeof body?.version === "string" ? body.version : null;
+            }
+        }
+        catch { /* leave runningVersion null — reported below as "unknown" */ }
+        if (runningVersion && runningVersion !== __pkgVersion) {
+            console.log(`  ${render.icons.error} Version mismatch: CLI/installed ${render.wrap(render.c.bold, __pkgVersion)} but server is running ${render.wrap(render.c.bold, runningVersion)}`);
+            if (autoFix) {
+                if (dryRun) {
+                    console.log(`     ${render.wrap(render.c.dim, "Would run:")} flair restart`);
+                }
+                else {
+                    try {
+                        const { execSync } = await import("node:child_process");
+                        execSync(`${process.argv[0]} ${process.argv[1]} restart --port ${effectivePort}`, { stdio: "inherit" });
+                        console.log(`     ${render.icons.ok} Restarted onto ${__pkgVersion}`);
+                    }
+                    catch {
+                        console.log(`     ${render.icons.error} Restart failed — try: flair restart`);
+                    }
+                }
+            }
+            else {
+                console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair restart`);
+            }
+            issues++;
+        }
+        else if (runningVersion) {
+            console.log(`  ${render.icons.ok} Server running version matches CLI (${runningVersion})`);
+        }
+        else {
+            console.log(`  ${render.icons.warn} Could not determine the running server's version`);
+        }
+    }
     // 2. Keys directory
     const keysDir = defaultKeysDir();
     if (existsSync(keysDir)) {
@@ -6969,6 +8442,290 @@ 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++;
+            }
+        }
+    }
+    // 8. Fleet presence (flair#639) — known instances via /Presence heartbeats.
+    //
+    // "Instance" here means each AGENT's heartbeat row — Presence is keyed by
+    // agentId (schemas/schema.graphql), not by Flair server — so several rows
+    // can (and typically will) share one flairVersion/harperVersion whenever
+    // several agents heartbeat through the same Flair. That's still the
+    // useful fleet signal: an outlier version on one row means THAT agent's
+    // serving instance is behind the rest.
+    //
+    // SCOPE, verified against runFederationSyncOnce's own table list a few
+    // hundred lines up (`const tables = ["Memory", "Soul", "Agent",
+    // "Relationship"]`): Presence is NOT one of the tables federation sync
+    // replicates. So this section reports only what THIS instance's own
+    // Presence table has recorded — every agent whose FLAIR_URL points
+    // directly at the Flair `doctor` is talking to. On a hub+spokes
+    // deployment where each spoke runs its own separate Flair database, a
+    // spoke's locally-recorded heartbeats are invisible from the hub's
+    // `doctor` unless those agents also heartbeat straight to the hub. Not
+    // fixed here — flair#639's fix list is version-stamping + a doctor
+    // listing, not widening federation sync scope.
+    if (harperResponding) {
+        console.log(`\n  ${render.wrap(render.c.bold, "Fleet presence")}`);
+        try {
+            // flairVersion/harperVersion are gated to verified readers on the
+            // server (resources/Presence.ts, same boundary as currentTask) — sign
+            // the GET when we have an agent + key so the fields aren't silently
+            // nulled out from under us.
+            const fleetAgentId = opts.agent || process.env.FLAIR_AGENT_ID;
+            const fleetKeyPath = fleetAgentId ? join(defaultKeysDir(), `${fleetAgentId}.key`) : undefined;
+            const canSign = !!(fleetAgentId && fleetKeyPath && existsSync(fleetKeyPath));
+            const headers = canSign
+                ? { Authorization: buildEd25519Auth(fleetAgentId, "GET", "/Presence", fleetKeyPath) }
+                : {};
+            const presRes = await fetch(`${baseUrl}/Presence`, { headers, signal: AbortSignal.timeout(5000) });
+            if (!presRes.ok) {
+                console.log(`  ${render.icons.warn} Could not fetch presence roster (HTTP ${presRes.status})`);
+            }
+            else {
+                const roster = (await presRes.json());
+                if (!Array.isArray(roster) || roster.length === 0) {
+                    console.log(`  ${render.icons.info} No known instances yet — no /Presence heartbeats recorded on this instance`);
+                }
+                else {
+                    const rows = sortOldestVersionFirst(markStale(roster));
+                    for (const row of rows) {
+                        const lastSeen = typeof row.lastHeartbeatAt === "number"
+                            ? render.relativeTime(new Date(row.lastHeartbeatAt).toISOString())
+                            : "—";
+                        const versionLabel = !canSign
+                            ? render.wrap(render.c.dim, "hidden")
+                            : row.flairVersion
+                                ? `v${row.flairVersion}`
+                                : render.wrap(render.c.dim, "no version reported");
+                        const staleNote = row.stale && row.newestVersion
+                            ? " " + render.wrap(render.c.yellow, `(stale — fleet newest is v${row.newestVersion})`)
+                            : "";
+                        const icon = row.stale ? render.icons.warn : render.icons.ok;
+                        const statusSuffix = row.presenceStatus ? ` (${row.presenceStatus})` : "";
+                        // Natural-presence: same staleness principle as the version
+                        // column — a live activity is shown as current, a decayed one as
+                        // "last-known". `activityFresh === false` (server verdict) plus a
+                        // known lastActivity → "(was: X)"; a fresh, non-idle activity →
+                        // "(X)". Skip entirely when there's nothing informative to say
+                        // (no signal, or idle) so the line stays quiet for the common case.
+                        const lastActivity = row.lastActivity ?? row.activity;
+                        const activityNote = row.activityFresh === false
+                            ? (lastActivity && lastActivity !== "idle"
+                                ? " " + render.wrap(render.c.dim, `(was: ${lastActivity})`)
+                                : "")
+                            : (row.activity && row.activity !== "idle"
+                                ? " " + render.wrap(render.c.dim, `(${row.activity})`)
+                                : "");
+                        console.log(`  ${icon} ${row.id} — ${versionLabel} — last seen ${lastSeen}${statusSuffix}${activityNote}${staleNote}`);
+                    }
+                    if (!canSign) {
+                        console.log(`     ${render.wrap(render.c.dim, "Pass --agent <id> (with a matching key in ~/.flair/keys) to reveal versions — flairVersion/harperVersion require a verified signature, same as currentTask.")}`);
+                    }
+                    console.log(`     ${render.wrap(render.c.dim, "Staleness above is fleet-relative (newest version seen among these instances) — comparing against the latest PUBLISHED flair is the version check at the top of this report, not this section.")}`);
+                }
+            }
+        }
+        catch (err) {
+            console.log(`  ${render.icons.warn} Fleet presence check failed: ${err?.message ?? err}`);
+        }
+    }
+    // 9. Migration state (flair#695) — pending/in-progress/blocked + last
+    // ledger-derived outcome per registered migration, read off the same
+    // authenticated /HealthDetail the "Fleet presence" section above
+    // already fetches. `--fix` here means the SAME restart offered in step
+    // 1a above (a halted migration retries automatically on the next boot —
+    // there's no separate "run the migration now" fix; the fix for
+    // "blocked" is whatever the halt reason names, e.g. freeing disk).
+    if (harperResponding) {
+        console.log(`\n  ${render.wrap(render.c.bold, "Migrations")}`);
+        try {
+            const migAgentId = opts.agent || process.env.FLAIR_AGENT_ID;
+            const migKeyPath = migAgentId ? join(defaultKeysDir(), `${migAgentId}.key`) : undefined;
+            const migCanSign = !!(migAgentId && migKeyPath && existsSync(migKeyPath));
+            if (!migCanSign) {
+                console.log(`  ${render.icons.info} Pass --agent <id> (with a matching key in ~/.flair/keys) to see migration state — requires a verified read, same as Fleet presence above.`);
+            }
+            else {
+                const migHeaders = { Authorization: buildEd25519Auth(migAgentId, "GET", "/HealthDetail", migKeyPath) };
+                const migRes = await fetch(`${baseUrl}/HealthDetail`, { headers: migHeaders, signal: AbortSignal.timeout(5000) });
+                if (!migRes.ok) {
+                    console.log(`  ${render.icons.warn} Could not fetch migration state (HTTP ${migRes.status})`);
+                }
+                else {
+                    const detail = (await migRes.json());
+                    const migBlock = detail?.migrations;
+                    if (!migBlock || !Array.isArray(migBlock.migrations) || migBlock.migrations.length === 0) {
+                        console.log(`  ${render.icons.info} No migrations registered on this instance`);
+                    }
+                    else {
+                        if (migBlock.cyclePhase === "pre-hash") {
+                            console.log(`  ${render.icons.info} Pre-flight integrity check in progress — migrations deferred until it completes`);
+                        }
+                        for (const m of migBlock.migrations) {
+                            if (m.state === "completed") {
+                                console.log(`  ${render.icons.ok} ${m.id}: completed`);
+                            }
+                            else if (m.state === "halted" || m.state === "failed") {
+                                console.log(`  ${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
+                                issues++;
+                            }
+                            else if (m.state === "running") {
+                                console.log(`  ${render.icons.info} ${m.id}: in progress (${m.rowsDone} done, ${m.rowsRemaining} remaining)`);
+                            }
+                            else {
+                                console.log(`  ${render.icons.info} ${m.id}: ${m.state}`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.log(`  ${render.icons.warn} Migration state check failed: ${err?.message ?? err}`);
+        }
+    }
     // Summary
     console.log("");
     if (issues === 0) {
@@ -6982,7 +8739,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
@@ -7134,13 +8891,15 @@ sessionSnapshot
 });
 // ─── Memory and Soul commands ────────────────────────────────────────────────
 const memory = program.command("memory").description("Manage agent memories");
-memory.command("add [content]").requiredOption("--agent <id>")
+memory.command("add [content]")
+    .description("Write a new memory row for an agent (content via positional arg or --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) {
@@ -7166,7 +8925,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.
@@ -7183,7 +8942,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)")
@@ -7243,6 +9002,7 @@ memory.command("write-task-summary")
     console.log(memId);
 });
 memory.command("search [query]")
+    .description("Semantic search over an agent's memories (query via positional arg or --q)")
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--q <query>", "search query (alias for positional arg)")
     .option("--limit <n>", "Max results", "5")
@@ -7269,6 +9029,7 @@ memory.command("search [query]")
     console.log(JSON.stringify(res, null, 2));
 });
 memory.command("list")
+    .description("List an agent's memories (optionally filtered by --tag or embedding-backfill triage)")
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--tag <tag>")
     .option("--hash-fallback", "Only memories with missing or hash-fallback embeddings (for backfill triage)")
@@ -7379,7 +9140,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;
@@ -7394,8 +9155,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.
@@ -7515,7 +9276,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) ───────────────────────────────────────
@@ -7550,7 +9311,7 @@ program
     .option("--since <iso-or-relative>", "Only memories created after this point (ISO 8601 or '7d'/'24h'/'30m')")
     .option("--as-of <iso>", "Temporal validity: only memories valid at this point (ISO 8601)")
     .option("--include-superseded", "Include memories that have been superseded")
-    .option("--scoring <mode>", "Scoring mode: composite (default) re-ranks by durability/recency/retrieval; raw uses cosine similarity only", "composite")
+    .option("--scoring <mode>", "Scoring mode: raw (default) uses cosine similarity/BM25 only; composite re-ranks by durability/recency/retrieval (measurably hurts precision as of flair#623 — opt-in only)", "raw")
     .option("--min-score <n>", "Drop results below this score (0..1)", "0")
     // Client-side filters (applied after server response)
     .option("--durability <level>", "Filter to permanent|persistent|standard|ephemeral (client-side)")
@@ -7576,7 +9337,7 @@ program
             agentId,
             q: query,
             limit: Number.parseInt(opts.limit, 10) || 5,
-            scoring: opts.scoring === "raw" ? "raw" : "composite",
+            scoring: opts.scoring === "composite" ? "composite" : "raw",
         };
         if (opts.tag)
             payload.tag = opts.tag;
@@ -7777,8 +9538,73 @@ program
         process.exit(1);
     }
 });
+// ─── flair relationship add ──────────────────────────────────────────────────
+//
+// Ergonomic agent-directed write surface for the Relationship graph
+// (relationship-write-path spec): an explicit subject/predicate/object triple
+// ("record that <subject> <predicate> <object>"), distinct from a free-text
+// Memory. Mirrors `flair memory add`'s shape (--agent required, signed via
+// the shared `api()` helper — see api()'s doc above for the Ed25519
+// resolution order) rather than hand-rolling a signer, per this repo's
+// existing convention (flair orgevent does hand-roll one because OrgEvent.put()
+// self-verifies authorId against the signature; Relationship doesn't need that
+// — the server stamps agentId from the verdict regardless of what's sent).
+//
+// PUTs to the CANONICAL id (see canonicalRelationshipId below), not a random
+// one — re-running this command with the SAME subject/predicate/object
+// UPSERTS the existing row (confidence/validTo/source refresh) instead of
+// creating a duplicate. This mirrors flair-client's RelationshipApi.write()
+// (packages/flair-client/src/client.ts) BYTE FOR BYTE — the CLI can't import
+// that workspace package into the published @tpsdev-ai/flair bundle (same
+// reasoning as the existing Memory-id-generation mirroring a few thousand
+// lines up), so the algorithm is duplicated here rather than shared. A
+// cross-check test (test/unit/cli-relationship-add.test.ts) pins the two
+// implementations to identical output so they can't silently drift apart —
+// a drift here would mean the CLI and the MCP tool/RelationshipApi land the
+// SAME triple at TWO different ids, defeating the whole dedup guarantee.
+function canonicalRelationshipId(agentId, subject, predicate, object) {
+    const material = [agentId, subject, predicate, object].join("\u0000").toLowerCase();
+    return createHash("sha256").update(material, "utf8").digest().subarray(0, 16).toString("base64url");
+}
+const relationship = program.command("relationship").description("Manage agent relationship triples (knowledge graph)");
+relationship.command("add")
+    .description("Record that <subject> <predicate> <object> — an explicit entity-to-entity relationship triple. " +
+    "Re-asserting the SAME triple (same subject/predicate/object) UPSERTS the existing row rather than " +
+    "duplicating it. Predicate is free text; recommended vocabulary: manages, works_on, reviews, depends_on, " +
+    "replaces, owns, reports_to, advises. To CONTRADICT a prior relationship: changing the predicate creates " +
+    "a SEPARATE row and does NOT auto-close the old one — re-assert the OLD triple with --valid-to set to now " +
+    "(or delete it) before/after writing the new one.")
+    .requiredOption("--agent <id>")
+    .requiredOption("--subject <text>", "Source entity (e.g. 'nathan')")
+    .requiredOption("--predicate <text>", "Relationship type, free text (e.g. 'manages')")
+    .requiredOption("--object <text>", "Target entity (e.g. 'flair')")
+    .option("--confidence <n>", "0.0-1.0, how certain (default 1.0 = explicitly stated)")
+    .option("--valid-from <iso>", "ISO timestamp this relationship became true (default: now)")
+    .option("--valid-to <iso>", "ISO timestamp this relationship ended (leave unset for an active relationship)")
+    .option("--source <text>", "Where this was learned from (a memory ID, conversation, etc.)")
+    .action(async (opts) => {
+    const id = canonicalRelationshipId(opts.agent, opts.subject, opts.predicate, opts.object);
+    const body = {
+        id,
+        agentId: opts.agent,
+        subject: opts.subject,
+        predicate: opts.predicate,
+        object: opts.object,
+    };
+    if (opts.confidence !== undefined)
+        body.confidence = Number(opts.confidence);
+    if (opts.validFrom)
+        body.validFrom = opts.validFrom;
+    if (opts.validTo)
+        body.validTo = opts.validTo;
+    if (opts.source)
+        body.source = opts.source;
+    const out = await api("PUT", `/Relationship/${id}`, body);
+    console.log(JSON.stringify(out, null, 2));
+});
 const soul = program.command("soul").description("Manage agent soul entries");
 soul.command("set")
+    .description("Set (upsert) a soul entry for an agent by key")
     .requiredOption("--agent <id>")
     .requiredOption("--key <key>")
     .requiredOption("--value <value>")
@@ -7810,6 +9636,7 @@ soul.command("set")
         console.log(render.kv("durability", render.wrap(render.c.magenta, opts.durability)));
 });
 soul.command("get")
+    .description("Fetch a single soul entry by id (agent:key)")
     .argument("<id>")
     .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (id, opts) => {
@@ -7841,6 +9668,7 @@ soul.command("get")
     }
 });
 soul.command("list")
+    .description("List all soul entries for an agent")
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
@@ -9187,7 +11015,7 @@ program
     }
 });
 // ─── flair presence ─────────────────────────────────────────────────────────
-const VALID_PRESENCE_ACTIVITIES = ["coding", "reviewing", "planning", "idle"];
+const VALID_PRESENCE_ACTIVITIES = ["coding", "reviewing", "planning", "debugging", "idle"];
 const MAX_TASK_LENGTH = 120;
 const presence = program.command("presence").description("Manage agent presence (The Office Space)");
 presence
@@ -9253,16 +11081,27 @@ presence
 });
 // ─── flair workspace ─────────────────────────────────────────────────────────
 //
-// Coordination write surface (ops-wmgx / 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
-// signature regardless of body content). Mirrors `presence set`'s signed-POST shape.
+// Coordination write surface (Kris #510). `workspace set` writes the
+// agent's OWN WorkspaceState via a signed PUT /WorkspaceState/{id}. Identity
+// is asserted by including agentId in the body — the server never trusts it
+// blindly, it 403s any mismatch against the Ed25519 signature's agentId
+// (WorkspaceState.put(), resources/WorkspaceState.ts), so this is a
+// self-declaration the server verifies 1:1, not attribution-from-body.
+//
+// (flair#679, measured against a real spawned Harper): table-backed resources
+// only accept writes via PUT /<Table>/<id> — a bare POST /WorkspaceState 405s
+// ("does not have a post method implemented to handle HTTP method POST"),
+// same restriction documented in resources/Memory.ts and already fixed for
+// `soul set` (#498). WorkspaceState.ts DOES define a post() method, but
+// Harper's REST layer never routes a real HTTP POST to it — post() is only
+// reachable via in-process resource instantiation, never the wire. put(),
+// unlike post(), does NOT default createdAt/timestamp/agentId — the CLI
+// supplies them all explicitly below.
 const MAX_WORKSPACE_FIELD_LENGTH = 2000;
 const workspace = program.command("workspace").description("Manage agent workspace state (The Office Space)");
 workspace
     .command("set")
-    .description("Set your agent's current workspace state (POST /WorkspaceState)")
+    .description("Set your agent's current workspace state (PUT /WorkspaceState/{id})")
     .requiredOption("--ref <ref>", "Workspace ref (branch, worktree, or task ref)")
     .option("--label <text>", "Human-readable label for this workspace")
     .option("--provider <name>", "Provider/runtime (e.g. claude-code, openclaw)", "cli")
@@ -9291,15 +11130,23 @@ workspace
         process.exit(1);
     }
     const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
-    const auth = buildEd25519Auth(agentId, "POST", "/WorkspaceState", keyPath);
-    // NOTE: agentId is intentionally NOT included in the body — the handler
-    // attributes the record from the Ed25519 signature (no forging).
+    // Deterministic id (agentId:ref) — re-running `workspace set` for the same
+    // ref overwrites the same record, which is intentional (one row per
+    // agent+ref, not an append log).
+    const id = `${agentId}:${opts.ref}`;
+    const auth = buildEd25519Auth(agentId, "PUT", `/WorkspaceState/${id}`, keyPath);
+    // agentId IS included in the body now — WorkspaceState.put() (unlike
+    // post()) does not auto-attribute from the signature, it 403s any
+    // mismatch. This is a self-declaration the server verifies against the
+    // signature, not a forgeable claim.
     const now = new Date().toISOString();
     const body = {
-        id: `${agentId}:${opts.ref}`,
+        id,
+        agentId,
         ref: opts.ref,
         provider: opts.provider ?? "cli",
         timestamp: now,
+        createdAt: now,
     };
     if (opts.label)
         body.label = opts.label;
@@ -9309,30 +11156,43 @@ workspace
         body.phase = opts.phase;
     if (opts.summary)
         body.summary = opts.summary;
-    const res = await fetch(`${baseUrl}/WorkspaceState`, {
-        method: "POST",
+    const res = await fetch(`${baseUrl}/WorkspaceState/${id}`, {
+        method: "PUT",
         headers: { "Content-Type": "application/json", Authorization: auth },
         body: JSON.stringify(body),
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        console.error(`Error: POST /WorkspaceState failed (${res.status}): ${text}`);
+        console.error(`Error: PUT /WorkspaceState/${id} failed (${res.status}): ${text}`);
         process.exit(1);
     }
     console.log(`✓ Workspace state updated for '${agentId}': ref=${opts.ref}${opts.phase ? `, phase=${opts.phase}` : ""}`);
 });
 // ─── flair orgevent ──────────────────────────────────────────────────────────
 //
-// Coordination write surface (ops-wmgx / 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()
-// handler overwrites authorId from the signature). Mirrors `presence set`'s shape.
+// Coordination write surface (Kris #510). `orgevent` publishes an
+// OrgEvent ATTRIBUTED to the authenticated agent via a signed PUT
+// /OrgEvent/{id}. authorId is asserted in the body but self-verified server
+// side: OrgEvent.put() (resources/OrgEvent.ts) 403s any authorId that doesn't
+// match the Ed25519 signature's agentId, so an agent still cannot forge
+// another agent's events — the difference from post() is that put() checks-
+// and-rejects a mismatch rather than silently overwriting it.
+//
+// (flair#679, measured against a real spawned Harper): table-backed resources
+// only accept writes via PUT /<Table>/<id> — a bare POST /OrgEvent 405s
+// ("does not have a post method implemented to handle HTTP method POST"),
+// same restriction documented in resources/Memory.ts and already fixed for
+// `soul set` (#498). OrgEvent.ts DOES define a post() method that
+// auto-generates id/createdAt, but Harper's REST layer never routes a real
+// HTTP POST to it — post() is only reachable via in-process resource
+// instantiation, never the wire. put() does NOT default id/createdAt, so the
+// CLI generates and supplies them itself (id convention mirrors flair-client's
+// Memory.write(): `${agentId}-${randomUUID()}`).
 const MAX_ORGEVENT_SUMMARY_LENGTH = 500;
 const MAX_ORGEVENT_DETAIL_LENGTH = 8000;
 program
     .command("orgevent")
-    .description("Publish an org-wide coordination event attributed to your agent (POST /OrgEvent)")
+    .description("Publish an org-wide coordination event attributed to your agent (PUT /OrgEvent/{id})")
     .requiredOption("--kind <kind>", "Event kind (e.g. coord.claim, coord.release, status)")
     .requiredOption("--summary <text>", "Short summary of the event")
     .option("--detail <text>", "Longer detail payload")
@@ -9363,12 +11223,22 @@ program
     // orgevent reuses --target for recipients, so the remote-URL override is
     // --target-url here (env FLAIR_TARGET still honored via resolveBaseUrl).
     const baseUrl = resolveBaseUrl({ target: opts.targetUrl, port: opts.port }).replace(/\/$/, "");
-    const auth = buildEd25519Auth(agentId, "POST", "/OrgEvent", keyPath);
-    // NOTE: authorId is intentionally NOT included in the body — the handler
-    // attributes the event from the Ed25519 signature (no forging).
+    // id generation mirrors flair-client's Memory.write() convention
+    // (`${agentId}-${randomUUID()}`) — unique per publish, unlike OrgEvent's
+    // own (HTTP-unreachable) post() default of `${authorId}-${isoTimestamp}`,
+    // which can collide within the same millisecond.
+    const id = `${agentId}-${randomUUID()}`;
+    const auth = buildEd25519Auth(agentId, "PUT", `/OrgEvent/${id}`, keyPath);
+    // authorId IS included in the body now — OrgEvent.put() (unlike post())
+    // does not auto-attribute from the signature, it 403s any mismatch. This
+    // is a self-declaration the server verifies against the signature, not a
+    // forgeable claim.
     const body = {
+        id,
+        authorId: agentId,
         kind: opts.kind,
         summary: opts.summary,
+        createdAt: new Date().toISOString(),
     };
     if (opts.detail)
         body.detail = opts.detail;
@@ -9376,21 +11246,126 @@ program
         body.scope = opts.scope;
     if (Array.isArray(opts.target) && opts.target.length > 0)
         body.targetIds = opts.target;
-    const res = await fetch(`${baseUrl}/OrgEvent`, {
-        method: "POST",
+    const res = await fetch(`${baseUrl}/OrgEvent/${id}`, {
+        method: "PUT",
         headers: { "Content-Type": "application/json", Authorization: auth },
         body: JSON.stringify(body),
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        console.error(`Error: POST /OrgEvent failed (${res.status}): ${text}`);
+        console.error(`Error: PUT /OrgEvent/${id} failed (${res.status}): ${text}`);
         process.exit(1);
     }
     const data = await res.json().catch(() => null);
     const targets = Array.isArray(opts.target) && opts.target.length > 0 ? ` → ${opts.target.join(", ")}` : "";
     console.log(`✓ OrgEvent published as '${agentId}': kind=${opts.kind}${targets}`);
-    if (data?.id)
-        console.log(`  id: ${data.id}`);
+    console.log(`  id: ${data?.id ?? id}`);
+});
+// ─── flair attention ─────────────────────────────────────────────────────────
+//
+// Entity-scoped attention query (flair#677). "What's touching entity E in the
+// last N days?" — a unified, grouped-by-source view across Memory,
+// Relationship, WorkspaceState, Presence, and OrgEvent (POST /AttentionQuery,
+// resources/AttentionQuery.ts). Read-only; signed the same way `flair search`
+// signs POST /SemanticSearch. Entity must be a vocabulary string (exact
+// type:value match — resources/entity-vocab.ts); the server 400s anything
+// malformed.
+/** Render one attention-result row for its source group — human-readable mode only. */
+function describeAttentionRow(source, r) {
+    const dim = (s) => render.wrap(render.c.dim, s);
+    const day = (iso) => (typeof iso === "string" ? iso.slice(0, 10) : "");
+    switch (source) {
+        case "memory":
+            return `${r.content ? String(r.content).replace(/\s+/g, " ").slice(0, 100) : "(no content)"} ${dim(`[${r.agentId} · ${day(r.createdAt)}]`)}`;
+        case "relationship":
+            return `${r.subject} —${r.predicate}→ ${r.object} ${dim(`[${r.agentId} · ${day(r.createdAt)}]`)}`;
+        case "workspaceState":
+            return `${r.summary ?? r.ref} ${dim(`[${r.agentId}${r.phase ? ` · ${r.phase}` : ""} · ${String(r.timestamp ?? "").slice(0, 16).replace("T", " ")}]`)}`;
+        case "presence":
+            return `${r.currentTask} ${dim(`[${r.displayName ?? r.agentId}${r.activity ? ` · ${r.activity}` : ""}]`)}`;
+        case "orgEvent":
+            return `${r.summary} ${dim(`[${r.authorId} · ${r.kind} · ${day(r.createdAt)}]`)}`;
+        default:
+            return JSON.stringify(r);
+    }
+}
+program
+    .command("attention <entity>")
+    .description("What's touching entity E in the last N days? Grouped view across memory/relationship/workspace/presence/orgevent (POST /AttentionQuery)")
+    .option("--days <n>", "Window size in days (default 7)")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+    .option("--key <path>", "Ed25519 private key path")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+    .option("--json", "Output raw JSON")
+    .action(async (entity, opts) => {
+    try {
+        const agentId = resolveAgentIdOrEnv(opts);
+        if (!agentId) {
+            console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+            process.exit(2);
+        }
+        const payload = { entity };
+        if (opts.days !== undefined) {
+            const n = Number.parseInt(opts.days, 10);
+            if (!Number.isFinite(n) || n <= 0) {
+                console.error("error: --days must be a positive integer");
+                process.exit(2);
+            }
+            payload.days = n;
+        }
+        const baseUrl = resolveBaseUrl(opts);
+        const headers = { "content-type": "application/json" };
+        const keyPath = opts.key || resolveKeyPath(agentId);
+        if (keyPath) {
+            headers["authorization"] = buildEd25519Auth(agentId, "POST", "/AttentionQuery", keyPath);
+        }
+        const res = await fetch(`${baseUrl}/AttentionQuery`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(text || `HTTP ${res.status}`);
+        const result = text ? JSON.parse(text) : {};
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON(result));
+            return;
+        }
+        const groups = result.groups ?? {};
+        const counts = result.counts ?? {};
+        console.log(`${render.icons.info} Attention: ${render.wrap(render.c.bold, result.entity ?? entity)} ` +
+            `${render.wrap(render.c.dim, `(last ${result.windowDays ?? payload.days ?? 7}d, since ${result.since ?? "?"})`)}`);
+        console.log(render.wrap(render.c.dim, `total: ${counts.total ?? 0}`));
+        console.log();
+        const sections = [
+            { key: "memory", label: "Memory" },
+            { key: "relationship", label: "Relationship" },
+            { key: "workspaceState", label: "Workspace" },
+            { key: "presence", label: "Presence" },
+            { key: "orgEvent", label: "OrgEvent" },
+        ];
+        for (const { key, label } of sections) {
+            const rows = Array.isArray(groups[key]) ? groups[key] : [];
+            console.log(`${render.wrap(render.c.bold, label)} ${render.wrap(render.c.dim, `(${rows.length})`)}`);
+            if (rows.length === 0) {
+                console.log(`  ${render.wrap(render.c.dim, "—")}`);
+                console.log();
+                continue;
+            }
+            for (const r of rows) {
+                console.log(`  ${describeAttentionRow(key, r)}`);
+            }
+            console.log();
+        }
+    }
+    catch (err) {
+        console.error(`${render.icons.error} Attention query failed: ${err.message}`);
+        process.exit(1);
+    }
 });
 // Parse argv and run the CLI. Exported so the CommonJS preflight shim
 // (cli-shim.cts → dist/cli-shim.cjs, the real bin entry) can invoke it after
@@ -9406,4 +11381,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, };