@tpsdev-ai/flair 0.44.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";
@@ -2318,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
@@ -9451,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 */ }
@@ -9480,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) {
@@ -9690,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
@@ -9908,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.
@@ -9972,7 +10001,6 @@ program
             else
                 console.log(line);
         }
-        await refreshWiredClients();
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -9999,7 +10027,6 @@ program
                 console.error(line);
             }
         }
-        await refreshWiredClients();
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -12130,7 +12157,7 @@ program
                         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 cache, missing global install, or network")}`);
+                        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)")}`);
                     }

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/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.44.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",