@tpsdev-ai/flair 0.42.0 → 0.44.1

package/dist/cli.js

@@ -20,7 +20,7 @@ import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
 import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
-import { flairCliVersion, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
+import { flairCliVersion, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
 import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
@@ -136,6 +136,7 @@ function shouldShowInlineSecretWarning(optValue, fromEnv, secretFlagNames, flagN
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
+const FABRIC_OPS_PORT = 9925;
 const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
@@ -1076,10 +1077,15 @@ function resolveOpsTarget(opts) {
     return opts.opsTarget || process.env.FLAIR_OPS_TARGET || undefined;
 }
 /** Derive the ops API URL from a Flair base URL.
- *  Convention: ops port = HTTP port - 1.
- *  If target has an explicit port, use port-1 (validated: must be 1-65535).
- *  If no explicit port: https → 442 (443-1), http → 19925 (19926-1), bare host → https://<host>:19925.
- *  Throws on unparseable URLs.
+ *  https with effective port 443 (no explicit port, or explicit :443): returns
+ *    <host>:9925 (FABRIC_OPS_PORT) — the Fabric managed case where port-1/:442
+ *    is a dead-end.
+ *  All other cases unchanged:
+ *    https with non-443 explicit port → port-1 (self-hosted TLS: 19926→19925, 8443→8442)
+ *    http with explicit port → port-1 (19926→19925)
+ *    http with no port → DEFAULT_OPS_PORT (19925)
+ *  Bare hosts are normalised to https:// (effective-443 → Fabric path).
+ *  Throws on unparseable URLs or out-of-range ports.
  */
 /** Compute the effective ops API URL for remote commands.
  *  - If --ops-target is set, use it directly (no derivation).
@@ -1099,6 +1105,17 @@ function resolveOpsUrlFromTarget(targetUrl) {
     // Normalise bare hosts: add https:// prefix so URL parser can handle them.
     const normalised = targetUrl.includes("://") ? targetUrl : `https://${targetUrl}`;
     const url = new URL(normalised);
+    // https target with effective port 443 (no explicit port, or explicit :443):
+    // this is the Fabric managed case — the ops API is on the well-known Fabric
+    // ops port, never REST-adjacent. The port-1 / :442 logic is a dead-end here.
+    if (url.protocol === "https:" && (url.port === "" || url.port === "443")) {
+        url.port = String(FABRIC_OPS_PORT);
+        return url.toString().replace(/\/$/, "");
+    }
+    // All other cases: unchanged port-1 convention.
+    //   https with non-443 explicit port → port-1 (self-hosted TLS: 19926→19925, 8443→8442)
+    //   http with explicit port → port-1 (19926→19925)
+    //   http with no port → DEFAULT_OPS_PORT (19925)
     const port = parseInt(url.port, 10);
     if (!isNaN(port) && port > 0 && port <= 65535) {
         const opsPort = port - 1;
@@ -1111,13 +1128,8 @@ function resolveOpsUrlFromTarget(targetUrl) {
     if (url.port !== "" && url.port !== undefined) {
         throw new Error(`Invalid target port: ${url.port} (must be 1-65535)`);
     }
-    // No explicit port — infer from scheme
-    if (url.protocol === "https:") {
-        url.port = "442";
-    }
-    else {
-        url.port = String(DEFAULT_OPS_PORT);
-    }
+    // No explicit port on http — use the default ops port.
+    url.port = String(DEFAULT_OPS_PORT);
     return url.toString().replace(/\/$/, "");
 }
 /**
@@ -1782,12 +1794,21 @@ export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId,
 export async function callOpsApi(opsUrl, body, user, pass) {
     const url = `${opsUrl.replace(/\/$/, "")}/`;
     const auth = Buffer.from(`${user}:${pass}`).toString("base64");
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(30_000),
-    });
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`ops API unreachable at ${opsUrl} (derived from --target). ` +
+            `Set --ops-target or FLAIR_OPS_TARGET to override. ` +
+            `(${message})`);
+    }
     if (!res.ok) {
         const text = await res.text().catch(() => "");
         throw new Error(`Ops API call failed (${res.status}): ${text}`);
@@ -2297,6 +2318,25 @@ export function shouldPrintUpgradeLine(status, showAll) {
         return false;
     return true;
 }
+/**
+ * Returns the human-readable suffix for a package status line in
+ * `flair upgrade` / `flair upgrade --check` output.
+ *
+ * flair-mcp is zero-install via npx — its suffix must never suggest a
+ * global install (flair#1168).
+ */
+export function upgradeStatusSuffix(name, status) {
+    if (status === "current")
+        return " (current)";
+    if (status === "missing") {
+        return name === "@tpsdev-ai/flair-mcp"
+            ? " (zero-install via npx — run: flair doctor --fix)"
+            : " (run: npm install -g)";
+    }
+    if (status === "optional")
+        return " (install via: openclaw plugins install @tpsdev-ai/openclaw-flair)";
+    return "";
+}
 /**
  * Pure flag resolution for `flair upgrade`'s restart/verify defaults
  * (flair#635 decision: restart is now the default; `--no-restart` opts
@@ -9430,10 +9470,7 @@ program
                     : status === "optional" ? "○"
                         : "❔";
             const installedLabel = installed ?? (status === "optional" ? "not installed (openclaw not detected)" : "not detected");
-            const suffix = status === "current" ? " (current)"
-                : status === "missing" ? " (run: npm install -g)"
-                    : status === "optional" ? " (install via: openclaw plugins install @tpsdev-ai/openclaw-flair)"
-                        : "";
+            const suffix = upgradeStatusSuffix(name, status);
             console.log(`  ${icon} ${name}: ${installedLabel} → ${latest}${suffix}`);
         }
         catch { /* skip unavailable packages */ }
@@ -9459,8 +9496,15 @@ program
         return;
     }
     if (missing.length > 0 && outdated.length === 0) {
+        const npmMissing = missing.filter((f) => f.name !== "@tpsdev-ai/flair-mcp");
+        const mcpMissing = missing.filter((f) => f.name === "@tpsdev-ai/flair-mcp");
         console.log(`\n❔ ${missing.length} package${missing.length > 1 ? "s" : ""} not detected — all detected packages are up to date.`);
-        console.log(`   Install missing: npm install -g ${missing.map((f) => f.name).join(" ")}`);
+        if (npmMissing.length > 0) {
+            console.log(`   Install missing: npm install -g ${npmMissing.map((f) => f.name).join(" ")}`);
+        }
+        if (mcpMissing.length > 0) {
+            console.log(`   flair-mcp is zero-install via npx — run: flair doctor --fix to re-wire the hook`);
+        }
         return;
     }
     if (checkOnly) {
@@ -9669,6 +9713,61 @@ program
             console.error(`  ❌ ${pkg} upgrade failed: ${err.message}`);
         }
     }
+    // flair#1167: `npm install -g` replaced package.json in-place, so the
+    // module-load-cached CLI version is stale. Clear it so mcpServerSpec()
+    // resolves the NEW version for the pin refresh below.
+    clearFlairCliVersionCache();
+    // ── Refresh wired MCP client configs (flair#1135, flair#1167) ──────────
+    // After a successful package install, the flair-mcp package on disk is
+    // newer than the pinned version in wired client configs. Re-run wiring for
+    // already-wired clients so the pin stays in lockstep with the installed
+    // version. Runs BEFORE the restart so --no-restart and --no-verify paths
+    // also get the refresh (flair#1167). Best-effort: failures warn but never
+    // fail the upgrade.
+    await (async () => {
+        const agentId = resolveAgentIdOrEnv({}) ?? (() => {
+            try {
+                const keyFiles = readdirSync(defaultKeysDir()).filter((f) => f.endsWith(".key"));
+                return keyFiles.length > 0 ? keyFiles[0].replace(/\.key$/, "") : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!agentId) {
+            console.log("\n   (no agent id known — skip MCP client pin refresh; run `flair init` to refresh manually)");
+            return;
+        }
+        const httpUrl = `http://127.0.0.1:${upgradePort}`;
+        const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
+        const detected = detectClients().filter(c => c.detected);
+        if (detected.length === 0)
+            return;
+        console.log("\n   Refreshing MCP client pins...");
+        for (const client of detected) {
+            const configPath = clientConfigPath(client.id);
+            if (!existsSync(configPath))
+                continue;
+            // Only refresh clients that are already wired — don't wire new ones.
+            let hasFlair = false;
+            try {
+                const raw = readFileSync(configPath, "utf-8");
+                if (client.id === "codex") {
+                    hasFlair = codexConfigHasFlairSection(raw);
+                }
+                else {
+                    const cfg = JSON.parse(raw);
+                    hasFlair = !!cfg.mcpServers?.flair;
+                }
+            }
+            catch { /* unreadable/malformed — skip */ }
+            if (!hasFlair)
+                continue;
+            const env = { ...mcpEnv, FLAIR_CLIENT: client.id };
+            const result = client.wire(env);
+            console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
+        }
+    })();
     // ── 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
@@ -9887,55 +9986,6 @@ program
         authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
-    // ── Refresh wired MCP client configs (flair#1135) ──────────────────────
-    // After a successful upgrade, the flair-mcp package on disk is newer than
-    // the pinned version in wired client configs. Re-run wiring for
-    // already-wired clients so the pin stays in lockstep with the installed
-    // version. Best-effort: failures warn but never fail the upgrade.
-    const refreshWiredClients = async () => {
-        const agentId = resolveAgentIdOrEnv({}) ?? (() => {
-            try {
-                const keyFiles = readdirSync(defaultKeysDir()).filter((f) => f.endsWith(".key"));
-                return keyFiles.length > 0 ? keyFiles[0].replace(/\.key$/, "") : null;
-            }
-            catch {
-                return null;
-            }
-        })();
-        if (!agentId) {
-            console.log("\n   (no agent id known — skip MCP client pin refresh; run `flair init` to refresh manually)");
-            return;
-        }
-        const httpUrl = `http://127.0.0.1:${upgradePort}`;
-        const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
-        const detected = detectClients().filter(c => c.detected);
-        if (detected.length === 0)
-            return;
-        console.log("\n   Refreshing MCP client pins...");
-        for (const client of detected) {
-            const configPath = clientConfigPath(client.id);
-            if (!existsSync(configPath))
-                continue;
-            // Only refresh clients that are already wired — don't wire new ones.
-            let hasFlair = false;
-            try {
-                const raw = readFileSync(configPath, "utf-8");
-                if (client.id === "codex") {
-                    hasFlair = codexConfigHasFlairSection(raw);
-                }
-                else {
-                    const cfg = JSON.parse(raw);
-                    hasFlair = !!cfg.mcpServers?.flair;
-                }
-            }
-            catch { /* unreadable/malformed — skip */ }
-            if (!hasFlair)
-                continue;
-            const env = { ...mcpEnv, FLAIR_CLIENT: client.id };
-            const result = client.wire(env);
-            console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
-        }
-    };
     if (verdict.kind === "ok") {
         // flair#1022: the verified facts are unchanged and still stated — the
         // upgrade did land. What changes is the MARKER and the claim around it.
@@ -9951,7 +10001,6 @@ program
             else
                 console.log(line);
         }
-        await refreshWiredClients();
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -9978,7 +10027,6 @@ program
                 console.error(line);
             }
         }
-        await refreshWiredClients();
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -12085,22 +12133,34 @@ program
             const hook = inspectSessionStartHook(homedir());
             if (hook.present) {
                 if (hook.execution === "broken") {
-                    // Reported in full, with the remedy — but NOT counted as an issue,
-                    // so it never flips doctor's exit code on its own. This is a
-                    // verification of the environment at the moment doctor runs (a
-                    // cold `npx` cache, an offline machine, a slow registry), exactly
-                    // like the FLAIR_URL reachability and agent-registration
-                    // verifications above, which are warnings for the same reason. A
-                    // fresh, correct install on a machine that simply has not fetched
-                    // the adapter yet must not be told it is broken in the exit code.
-                    // The unsilenced finding below IS counted: that one is a fact
-                    // about the file, true regardless of the environment.
-                    console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
-                    console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "If this persists, the Node runtime probably changed and the globally")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "installed @tpsdev-ai/flair-mcp no longer resolves for it.")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} npm install -g @tpsdev-ai/flair-mcp ${render.wrap(render.c.dim, "(reinstall for the runtime you use now)")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Or, if you no longer want ambient memory:")} flair hook uninstall`);
+                    // Two very different states that share one probe outcome:
+                    //
+                    // 1. Silenced (current) command that didn't run — the npx cache
+                    //    is cold, the machine is offline, or the adapter hasn't been
+                    //    fetched yet.  On a fresh install this is NORMAL: the hook is
+                    //    wired but no Claude Code session has exercised it yet.
+                    //    Report as informational, not a warning, and never suggest
+                    //    reinstall — the setup is correct, the environment just
+                    //    hasn't warmed yet.
+                    //
+                    // 2. Unsilenced (legacy) command that didn't run — the hook has
+                    //    been in place long enough that a cold cache is not the
+                    //    explanation.  This IS a genuine failure: warn and name the
+                    //    actual state with a fitting remedy.
+                    if (hook.silenced) {
+                        console.log(`  ${render.icons.ok} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)} — not yet exercised`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "The hook is correctly wired but the adapter has not been fetched yet.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "This is normal on a fresh install — the first Claude Code session will warm the npx cache.")}`);
+                    }
+                    else {
+                        console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "The hook command could not be executed. Check that npx can resolve")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "@tpsdev-ai/flair-mcp — a cold npx cache or network issue")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "issue can prevent the adapter from running on its first invocation.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(rewrites the hook to the current silent-failure form)")}`);
+                    }
                 }
                 else if (hook.execution === "unknown") {
                     console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but could not be verified ${render.wrap(render.c.dim, `(${hook.detail ?? "no detail"})`)}`);
@@ -16058,7 +16118,7 @@ if (import.meta.main) {
 // ─── Exported for testing ─────────────────────────────────────────────────────
 export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, 
 // Harper's own config — the per-instance port record (flair#914)
-harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
+harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, FABRIC_OPS_PORT, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
 // launchd label (flair#693)
 LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, 
 // launchd management observation (flair#1022)

package/dist/doctor-client.js

@@ -41,7 +41,7 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 //
 // WHY THE INVOCATION IS WRAPPED
 // -----------------------------
-// The hook runs `npx -y @tpsdev-ai/flair-mcp flair-session-start`: it resolves
+// The hook runs `npx -y -p @tpsdev-ai/flair-mcp flair-session-start`: it resolves
 // a package binary through whatever Node runtime the user's shell happens to
 // expose. Under a Node version manager, globally installed packages are
 // per-runtime-version, so a routine and entirely unrelated runtime upgrade
@@ -117,7 +117,7 @@ export function buildSessionStartHookCommand(agentId, flairUrl) {
         throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
     }
     const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
-    const invocation = `${env} npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
     return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
 }
 /**
@@ -525,6 +525,18 @@ export function inspectSessionStartHook(homeDir, opts = {}) {
     const verdict = classifyHookProbe(outcome);
     return { path: found.path, present: true, command, ours, silenced, upgradable, execution: verdict.execution, detail: verdict.detail };
 }
+export function classifyHookReadiness(report) {
+    if (!report.present)
+        return "absent";
+    if (!report.ours)
+        return "custom";
+    if (report.execution === "runs")
+        return "runs";
+    if (report.execution === "broken") {
+        return report.silenced ? "not-yet-exercised" : "genuinely-broken";
+    }
+    return "unverified";
+}
 /**
  * Rewrite an existing Flair-authored hook command to the current canonical
  * form, in place, preserving the agent id and URL the entry already carries —

package/dist/hook-install.js

@@ -344,7 +344,7 @@ export function hookStatus(homeDir, harness) {
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
-    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
+    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
     const env = parseHookCommandEnv(command);
     return {
         harness, path, wired: true, correctShape,

package/dist/lib/mcp-enable.js

@@ -286,10 +286,12 @@ export function readSigningKeyFile(path) {
 /**
  * The `@harperfast/oauth` config block, matching the installed 2.2.0
  * package's field names (node_modules/@harperfast/oauth/dist/types.d.ts).
- * Secrets are `${ENV_VAR}` placeholders — never literal values — so this
- * block is safe to write to harperdb-config.yaml via `set_configuration`
- * (the config file itself carries no secret material; see the
- * secrets-provisioning step for how the referenced env vars land).
+ * Secrets are `${ENV_VAR}` placeholders — never literal values.
+ *
+ * flair#1136: set_configuration delivery was removed. Fabric regenerates
+ * the root harperdb-config.yaml; the component's own config.yaml is the
+ * source of truth for the oauth block. This function builds the block that
+ * ships in config.yaml — it is never written to harperdb-config.yaml.
  *
  * flair#756: `dynamicClientRegistration: { enabled: false }` is written
  * EXPLICITLY — never omitted. See the module header's "Leaving
@@ -634,32 +636,7 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
     }
     return { principalCreated, credentialId, credentialReused: Boolean(existing) };
 }
-/** `set_configuration` (writes harperdb-config.yaml) then `restart`
- *  (whole-process restart) — the genuine Harper Operations API operations
- *  this module's header documents. Throws on either non-2xx response. */
-export async function applyRemoteConfigAndRestart(params, deps = {}) {
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const opsUrl = opsBaseUrl(params.opsPortOrUrl);
-    const authHeader = basicAuthHeader(params.adminUser, params.adminPass);
-    const setRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({ operation: "set_configuration", ...params.configBlock }),
-    });
-    if (!setRes.ok) {
-        const text = await setRes.text().catch(() => "");
-        throw new Error(`set_configuration failed (HTTP ${setRes.status}): ${text}`);
-    }
-    const restartRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({ operation: "restart" }),
-    });
-    if (!restartRes.ok) {
-        const text = await restartRes.text().catch(() => "");
-        throw new Error(`restart failed (HTTP ${restartRes.status}): ${text}`);
-    }
-}
+// ─── Restart only ────────────────────────────────────────────────────────────
 /** `restart` only — used by `disableMcp` (flag off + restart, no config
  *  rewrite: the `@harperfast/oauth` config block is left in place; it is
  *  inert whenever `FLAIR_MCP_OAUTH` is unset, per the byte-identical-boot

package/dist/lib/mcp-spec.js

@@ -55,8 +55,14 @@ export function resolveFlairCliVersion(startDir) {
 let cachedVersion;
 /**
  * This CLI's own version — the single source for `--version`, the CLI↔server
- * handshake, `upgrade --check`, and the MCP pin. Cached: the answer cannot
- * change within a process, and several commands ask repeatedly.
+ * handshake, `upgrade --check`, and the MCP pin. Cached: the answer normally
+ * cannot change within a process, and several commands ask repeatedly.
+ *
+ * The one exception is `flair upgrade`: `npm install -g` replaces package.json
+ * in-place while the process is still running, so the cached version becomes
+ * stale. Callers that run after an in-process upgrade must call
+ * {@link clearFlairCliVersionCache} first so the next read resolves the new
+ * version from disk (flair#1167).
  */
 export function flairCliVersion() {
     if (cachedVersion === undefined) {
@@ -64,6 +70,14 @@ export function flairCliVersion() {
     }
     return cachedVersion;
 }
+/**
+ * Clear the cached CLI version so the next call to {@link flairCliVersion}
+ * re-resolves from the package.json on disk. Needed after an in-process
+ * `npm install -g` replaces the package (flair#1167).
+ */
+export function clearFlairCliVersionCache() {
+    cachedVersion = undefined;
+}
 /** True when `version` is usable as a pin. */
 export function isResolvedVersion(version) {
     return !!version && version !== UNKNOWN_VERSION;

package/docs/deploying-on-fabric.md

@@ -129,14 +129,17 @@ where nothing answers:
 # --target https://<fabric-node>:19926/<instance>     → ops derived as :19925 ✓
 ```
 
+**Fabric's ops API runs on the same hostname at port 9925** <!-- docs-freshness-allow: Fabric ops API port, not legacy data port --> (the deploy/upgrade path already targets this port). For a managed `*.harperfabric.com` instance:
+
+```bash
+# Same hostname, port 9925 — not port 442 <!-- docs-freshness-allow: Fabric ops API -->
+flair init --target https://<cluster>.<org>.harperfabric.com \
+    --ops-target https://<cluster>.<org>.harperfabric.com:9925 <!-- docs-freshness-allow: Fabric ops API -->
+```
+
 **Pass `--ops-target <url>` explicitly** (or set `FLAIR_OPS_TARGET`) on any command that
 touches the ops API: `init --target`, `agent add --target`, `federation token --target`.
 
-> **Gap — needs a Fabric account to verify.** This guide does not state the correct
-> ops-API URL for a managed `*.harperfabric.com` instance, or whether the ops API is
-> reachable remotely there at all. The derivation above is certain (read from source);
-> the right value to pass is not.
-
 Precedence: `--target` > `--url` > `FLAIR_TARGET` > `FLAIR_URL` > localhost. For ops:
 `--ops-target` > `FLAIR_OPS_TARGET` > derived > localhost.
 
@@ -250,8 +253,9 @@ and shells out to `lsof`. The command you'd reach for when something breaks is u
 here. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
 
 **Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation
-peer table, not Harper's cluster nodes — `cluster_status` is harper-pro-only and absent
-from the OSS `harper` build. **`0 peers known` means "0 on file", never "0 exist."**
+peer table, not Harper's cluster nodes. **`cluster_status` works on Fabric** — Fabric
+always runs harper-pro (not the OSS harper build), so cluster_status is available over
+the ops API. `0 peers known` means "0 on file", never "0 exist."
 
 **There is no disk or quota telemetry.** `flair status` reports usage for two directories:
 no free space, no total, no quota, no warning threshold, walk capped at six levels, no
@@ -263,6 +267,35 @@ with nothing saying so. The one indirect signal is a migration halting for space
 > wouldn't matter: Flair calls it only as a post-failure convergence oracle and discards
 > the `size` field. Component disk usage is invisible structurally.
 
+### The `mcp.enabled` operator step
+
+MCP is **off by default**. The shipped component `config.yaml` contains
+`@harperfast/oauth` → `mcp` → `enabled: false`. Until [flair#1152](https://github.com/tpsdev-ai/flair/issues/1152)
+lands (interpolate from env — *ON HOLD*), you must flip this manually:
+
+1. In your deployed component's `config.yaml`, change:
+    ```yaml
+    '@harperfast/oauth':
+     mcp:
+       enabled: true      # was: false
+    ```
+2. Re-deploy the component so Harper picks up the new value.
+3. **Verify the `/mcp` surface is actually serving** (the flag alone does not
+   guarantee it — a secret that is stored but never decrypted fails at self-verify):
+    ```bash
+    # Check /mcp is reachable and returning MCP protocol (not a loopback proxy or 404)
+    curl -sf https://\<cluster\>.\<org\>.harperfabric.com/mcp
+    # Should return MCP JSON-RPC content; if you get HTML redirect or 404 the flag
+    # is not effective
+    ```
+
+**⚠ SECURITY CAVEAT — the upgrade-reverts trap.** Any package update or fleet component
+update re-ships the literal `enabled: false` and silently darkens a live `/mcp` surface.
+You must **re-flip to `true` after every upgrade** and re-deploy. An updated component
+without this re-flip will appear healthy (`/Health` green) while its MCP tools are
+dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
+runbook.
+
 ### Known hazard: unbounded npm cache
 
 **Open — [flair#886](https://github.com/tpsdev-ai/flair/issues/886).** Every deploy runs a

package/docs/hosted-on-fabric.md

@@ -79,6 +79,35 @@ The staging file is written in every case, so a fallback never strands you mid-r
 
 `--secrets-mechanism <fabric-env-secrets|env-file>` remains an explicit override and skips the probe entirely.
 
+### The `mcp.enabled` operator step (Fabric)
+
+MCP is **off by default**. The shipped component `config.yaml` contains
+`@harperfast/oauth` → `mcp` → `enabled: false`. Until [flair#1152](https://github.com/tpsdev-ai/flair/issues/1152)
+lands (interpolate from env — *ON HOLD*), you must flip this manually:
+
+1. In your deployed component's `config.yaml`, change:
+   ```yaml
+   '@harperfast/oauth':
+     mcp:
+       enabled: true     # was: false
+   ```
+2. Re-deploy the component so Harper picks up the new value.
+3. **Verify the `/mcp` surface is actually serving** (the flag alone does not
+   guarantee it — a secret that is stored but never decrypted fails at self-verify):
+   ```bash
+   # Check /mcp is reachable and returning MCP protocol (not a loopback proxy or 404)
+   curl -sf https://<cluster>.<org>.harperfabric.com/mcp
+   # Should return MCP JSON-RPC content; if you get HTML redirect or 404 the flag
+   # is not effective
+   ```
+
+**⚠ SECURITY CAVEAT — the upgrade-reverts trap.** Any package update or fleet component
+update re-ships the literal `enabled: false` and silently darkens a live `/mcp` surface.
+You must **re-flip to `true` after every upgrade** and re-deploy. An updated component
+without this re-flip will appear healthy (`/Health` green) while its MCP tools are
+dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
+runbook.
+
 ---
 
 ## Agent authentication
@@ -140,7 +169,7 @@ flair fleet verify --target https://<cluster>.<org>.harperfabric.com
 
 **`flair doctor`** takes no `--target` — it hardcodes localhost, reads a local PID file, and shells out to `lsof`. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
 
-**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. `cluster_status` is harper-pro-only. `0 peers known` means "0 on file", never "0 exist."
+**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. **`cluster_status` works on Fabric** — Fabric always runs harper-pro (not the OSS harper build), so cluster_status is available over the ops API. `0 peers known` means "0 on file", never "0 exist."
 
 ---
 

package/docs/mcp-clients.md

@@ -109,7 +109,7 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
+            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
           }
         ]
       }

package/docs/quickstart.md

@@ -154,6 +154,8 @@ flair search --agent local "native addon loading in sandboxed runtimes"
 
 You searched for a concept, not the keywords. The line under each hit is its creation date, durability tier, and rank score.
 
+> **When stdout is not a terminal** — piped to another command, captured in a script, or run in CI — the same `flair search` command emits a JSON array instead of the formatted prose above. Each hit is an object with `id`, `text`, `createdAt`, `durability`, and `_score` fields. Add `--explain` to include an `_explain` ranking breakdown on each hit. Use `flair search --json` to force JSON output even in a terminal, or `flair memory search` for the raw JSON form in all contexts.
+
 > The percentage is a **rank-fusion score, not a similarity**. It is normalized so the top result is always near 100%. Read it as ordering within these results, never as confidence that the match is good.
 
 Add `--explain` to see the ranking inputs per hit — the raw score, the composite score under `--scoring composite`, and the record's durability, age and usage count. When output is JSON (`--json`, or any time stdout is not a terminal) the same breakdown arrives as an `_explain` object on each hit, so scripts get it too. Use `--limit`, `--tag`, `--since 7d` to narrow the search. `flair memory search` runs the same query but always prints raw JSON — use it when piping to a script.

package/docs/troubleshooting.md

@@ -23,7 +23,8 @@ If it fails to start:
 lsof -i :19926
 
 # Check logs (macOS)
-cat ~/.flair/data/log/hdb.log | tail -50
+cat ~/.flair/data/log/hdb.log | tail -50     # Harper ≤ 5.1 only (see below)
+cat ~/.flair/data/log/system.log | tail -50   # Harper 5.2+ (live log)
 
 # Check logs (Linux)
 journalctl --user -u flair --since "10 minutes ago"
@@ -242,6 +243,14 @@ flair --help          # all commands
 flair <command> -h    # command-specific help
 ```
 
-Logs: `~/.flair/data/log/hdb.log`
+**Log paths depend on Harper version:**
+
+- **Harper ≤ 5.1:** `~/.flair/data/log/hdb.log`
+- **Harper 5.2+:** `~/.flair/data/log/system.log`
+
+> ⚠ **On Harper 5.2+, `hdb.log` freezes at the upgrade boundary.** The live log is
+> `system.log`. The Harper ops `read_log` endpoint keeps serving the frozen `hdb.log`,
+> so remote diagnosis reads days-stale entries that look current. Always check
+> `system.log` after upgrading to 5.2+.
 
 File issues: [github.com/tpsdev-ai/flair/issues](https://github.com/tpsdev-ai/flair/issues)

package/docs/upgrade.md

@@ -177,7 +177,8 @@ If you'd rather upgrade by hand instead of `flair upgrade`:
 
 ```bash
 npm install -g @tpsdev-ai/flair@latest
-npm install -g @tpsdev-ai/flair-mcp@latest   # if installed
+# flair-mcp is zero-install via npx — no global install needed.
+# flair doctor --fix rewires the hook to the current npx form.
 flair restart
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.42.0",
+  "version": "0.44.1",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",