@tpsdev-ai/flair 0.21.0 → 0.22.0

package/dist/cli.js

@@ -3,17 +3,22 @@ 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 { 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
@@ -121,39 +126,50 @@ 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
@@ -373,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")}`;
@@ -418,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,
@@ -434,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);
@@ -742,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"
@@ -802,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}/`
@@ -1091,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'
@@ -1119,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),
@@ -1320,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
@@ -1501,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")
@@ -1794,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 {
@@ -1816,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,
@@ -1837,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");
@@ -1901,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">
@@ -1925,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>
@@ -2675,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.
@@ -3389,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
@@ -4061,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.
@@ -4171,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")
@@ -4405,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) {
@@ -4420,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);
     }
 });
@@ -4942,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:`);
@@ -6029,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,
@@ -6092,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}`));
@@ -6102,32 +6531,378 @@ async function runFabricUpgrade(opts) {
         process.exit(1);
     }
 }
+// ─── 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})`);
+            }
+        }
+    }
+    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", "Restart Flair after upgrade")
+    .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 (env: FABRIC_USER) — for --target")
-    .option("--fabric-password <pass>", "Fabric admin password (env: FABRIC_PASSWORD) — for --target")
+    .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 { execSync, execFileSync } = await import("node:child_process");
+    const { execFileSync } = await import("node:child_process");
     const checkOnly = opts.check ?? false;
     const showAll = opts.all ?? false;
     console.log("Checking for updates...\n");
@@ -6236,22 +7011,121 @@ program
         }
         return;
     }
-    // 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`);
-    for (const { pkg, latest } of npmUpgrades) {
+    // 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 {
-            console.log(`  Installing ${pkg}@${latest}...`);
-            execFileSync("npm", ["install", "-g", `${pkg}@${latest}`], { stdio: "pipe" });
-            console.log(`  ✅ ${pkg}@${latest} installed`);
+            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(`  ❌ ${pkg} upgrade failed: ${err.message}`);
-        }
-    }
-    for (const { pkg, latest } of openclawUpgrades) {
+            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}...`);
+            execFileSync("npm", ["install", "-g", `${pkg}@${latest}`], { stdio: "pipe" });
+            console.log(`  ✅ ${pkg}@${latest} installed`);
+        }
+        catch (err) {
+            console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
+            if (pkg === "@tpsdev-ai/flair")
+                flairInstallFailed = true;
+        }
+    }
+    for (const { pkg, latest } of openclawUpgrades) {
         // OpenClaw plugins upgrade via `openclaw plugins install --force --pin`.
         // Requires openclaw on PATH; if not, surface the manual recipe instead
         // of a confusing failure.
@@ -6271,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
@@ -6390,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),
@@ -6404,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",
     });
@@ -6418,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)) {
@@ -6436,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" });
@@ -6446,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
@@ -6603,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}`);
     }
@@ -6896,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")
@@ -6913,16 +7950,27 @@ program
     .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,
@@ -6947,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)
@@ -6971,6 +8018,35 @@ program
         }
         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:`));
@@ -6994,6 +8070,67 @@ program
         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")
@@ -7153,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)) {
@@ -7402,6 +8586,146 @@ program
             }
         }
     }
+    // 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) {
@@ -7567,7 +8891,9 @@ 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)")
@@ -7676,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")
@@ -7702,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)")
@@ -7983,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)")
@@ -8009,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;
@@ -8210,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>")
@@ -8243,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) => {
@@ -8274,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) => {
@@ -9620,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
@@ -9687,15 +11082,26 @@ presence
 // ─── flair workspace ─────────────────────────────────────────────────────────
 //
 // Coordination write surface (Kris #510). `workspace set` writes the
-// agent's OWN WorkspaceState via a signed POST /WorkspaceState. Identity comes
-// from the Ed25519 signature — the body carries NO agentId, so an agent can only
-// write as itself (the WorkspaceState.post() handler overwrites agentId from the
-// signature regardless of body content). Mirrors `presence set`'s signed-POST shape.
+// 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")
@@ -9724,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;
@@ -9742,14 +11156,14 @@ 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}` : ""}`);
@@ -9757,15 +11171,28 @@ workspace
 // ─── flair orgevent ──────────────────────────────────────────────────────────
 //
 // Coordination write surface (Kris #510). `orgevent` publishes an
-// OrgEvent ATTRIBUTED to the authenticated agent via a signed POST /OrgEvent.
-// The event's authorId comes from the Ed25519 signature — the body carries NO
-// authorId, so an agent CANNOT forge another agent's events (the OrgEvent.post()
-// handler overwrites authorId from the signature). Mirrors `presence set`'s shape.
+// 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")
@@ -9796,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;
@@ -9809,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