@tpsdev-ai/flair 0.25.0 → 0.25.2

package/README.md

@@ -134,6 +134,15 @@ flair memory search "native addon loading in sandboxed runtimes"
 # → [0.67] Harper v5 sandbox blocks node:module but process.dlopen works
 ```
 
+### Trust-Graded Recall
+Recall can carry an opt-in **trust-evidence block** per result — provenance (verified vs claimed author), usage signal, freshness/validity, supersession — so an agent weighs *what to trust*, not just *what matched*. On top of it:
+
+- **Confidence bands** (`matchQuality`): each result is labeled `strong` / `moderate` / `breadcrumb` from its absolute similarity — a weak-but-relevant hit is taken for what it is, not mistaken for a confident one.
+- **First-class abstention** (`abstain`): when nothing clears a confidence floor, recall returns an honest "no memory covers this" verdict instead of the N weakest matches.
+- **Citation-on-write** (`usedMemoryIds`) + **`record_usage`**: report which memories actually grounded an answer — a deduped, principal-bound usage signal (honest evidence, never retrieval-popularity) that strengthens future recall.
+
+Opt-in and additive (`includeTrust` / `abstain` on the recall path) — off by default, byte-identical when unused. Reachable today via the authenticated HTTP API and the native `/mcp` tools; first-class exposure in the `flair` CLI, `@tpsdev-ai/flair-client`, and the `flair-mcp` bridge is a follow-up. Full arc in the [CHANGELOG](CHANGELOG.md) (flair#744).
+
 ### Tiered Durability
 Not all memories are equal:
 
@@ -340,7 +349,7 @@ Add to your `CLAUDE.md`:
 
     At the start of every session, run mcp__flair__bootstrap before responding.
 
-Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The MCP server exposes `memory_store`, `memory_search`, `memory_get`, `memory_delete`, `bootstrap`, `soul_set`, `soul_get`.
+Your agent's memory **follows it across CLIs** — same Flair instance, same agent identity, switch from Claude Code to Gemini CLI to Codex CLI without losing state. The `flair-mcp` server — the bridge these CLIs connect to — exposes `memory_store`, `memory_search`, `memory_update`, `memory_get`, `memory_delete`, `relationship_store`, `bootstrap`, `soul_set`, `soul_get`, `flair_workspace_set`, and `flair_orgevent`. (Flair's in-Harper native `/mcp` surface is a separate, still-experimental tool set with `attention` + `record_usage` — see Trust-Graded Recall above.)
 
 For per-CLI config snippets (Gemini CLI's `~/.gemini/settings.json`, Codex CLI's `~/.codex/config.toml`, etc.), see **[docs/mcp-clients.md](docs/mcp-clients.md)**. For a deeper Claude Code walk-through with `CLAUDE.md` patterns, see [docs/claude-code.md](docs/claude-code.md).
 
@@ -353,7 +362,7 @@ Use Flair as the memory backend for n8n's AI Agent. Same memories readable from
 @tpsdev-ai/n8n-nodes-flair
 ```
 
-Two nodes ship: **Flair Chat Memory** (Memory port, conversation buffer) and **Flair Search** (Tool port, semantic search + get-by-subject). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
+Three nodes ship: **Flair Chat Memory** (Memory port, conversation buffer), **Flair Search** (Tool port, semantic search + get-by-subject), and **Flair Write** (Tool port, store memories). Setup walkthrough, subject/sessionId patterns, and security guidance in **[docs/n8n.md](docs/n8n.md)**.
 
 ### JavaScript / TypeScript (Client Library)
 
@@ -541,13 +550,13 @@ Flair is in active development and daily use. We dogfood it — the agents that
 - ✅ Web admin UI (principals, connectors, IdPs, instance config)
 - ✅ Federation (hub-and-spoke sync with signed requests and pairing tokens)
 - ✅ OpenClaw memory plugin
-- ✅ MCP server for Claude Code / Cursor / Windsurf
+- ✅ MCP server for Claude Code / Cursor / Codex / Gemini CLI
 - ✅ Lightweight client library (`@tpsdev-ai/flair-client`)
 - ✅ Portable agent identity (export/import between instances)
 - ✅ `flair --version`, `flair upgrade`
+- ✅ First-run soul wizard (interactive personality setup)
 
 **What's next:**
-- [ ] First-run soul wizard (interactive personality setup)
 - [ ] Git-backed memory sync
 - [ ] Encryption at rest (opt-in AES-256-GCM per memory)
 - [ ] Harper Fabric deployment (managed multi-office)

package/dist/cli.js

@@ -12,8 +12,8 @@ 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 { checkVersion, formatVersionNudge, primeVersionCheckCache, FLAIR_PKG_NAME } from "./version-check.js";
+import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache } 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";
@@ -1641,6 +1641,23 @@ export function decideAfterVerify(result, previousVersion) {
     if (result.ok)
         return { kind: "ok" };
     const reason = result.error ?? "post-restart verification failed";
+    // A HEALTHY instance whose ONLY failure was that the verifier couldn't
+    // authenticate (401/403) is demonstrably UP: the public /Health answered
+    // 2xx AND the server responded to the authenticated probe — it rejected our
+    // credentials, it did not fail to respond. A version we couldn't READ is not
+    // grounds to roll back a RUNNING instance. Rolling back here is destructive
+    // AND self-defeating — the rollback's own re-verify hits the identical
+    // missing-credential wall, producing the false "ROLLBACK ALSO FAILED / state
+    // UNKNOWN" for an instance that was healthy the whole time. (The real
+    // incident: /HealthDetail became a verified-read in flair#747, so a machine
+    // with no admin-pass/agent key authenticates fine against the pre-upgrade
+    // version but not post-restart — the pre-flight credential check can't
+    // anticipate a version that changes /HealthDetail's auth requirement.)
+    // Report it as up-but-unverified and NEVER roll back. This supersedes
+    // flair#741 fix #3's "prefer the known-good version" default, which the
+    // incident proved wrong for a healthy instance.
+    if (isCredentialOnlyFailure(result))
+        return { kind: "healthy-unverified", reason };
     if (!previousVersion)
         return { kind: "cannot-rollback", reason };
     return { kind: "rollback", reason, toVersion: previousVersion };
@@ -8036,6 +8053,12 @@ program
                 continue;
             const data = await res.json();
             const latest = data.version ?? "unknown";
+            if (name === FLAIR_PKG_NAME && latest !== "unknown") {
+                try {
+                    primeVersionCheckCache(latest);
+                }
+                catch { /* best-effort */ }
+            }
             const installed = probe();
             let status;
             if (installed === null) {
@@ -8352,18 +8375,22 @@ program
         console.log(`✅ verified: healthy, authenticated${verify.version ? `, running ${verify.version}` : ""}`);
         return;
     }
-    console.error(`❌ post-restart verification failed: ${verdict.reason}`);
-    if (isCredentialOnlyFailure(verify)) {
-        // flair#741 fix #3: a responding server that rejects the verifier's
-        // credentials proves the instance is UP — it is not evidence the
-        // upgrade itself broke anything. Say so explicitly instead of leaving
-        // the reader to infer it from the raw error text. Rollback still
-        // proceeds below (a credential check that worked pre-upgrade — see
-        // the pre-flight above — and stopped working mid-run is an edge case
-        // ambiguous enough that "prefer the known-good version" is still the
-        // safer default), but the reason for it is now honest.
-        console.error("   The instance is up and responded — the verifier could not authenticate. This is not a sign the upgrade broke anything.");
+    // flair#741 follow-through: a healthy instance the verifier just couldn't
+    // authenticate against. The upgrade SUCCEEDED — the new version's server is
+    // up (public /Health passed); we simply couldn't read its version over the
+    // authenticated /HealthDetail. Report the caveat and STOP — never roll back
+    // a running instance over a credentials gap. (decideAfterVerify only
+    // returns this for isCredentialOnlyFailure(verify), so the old
+    // "print an honest note but roll back anyway" branch that used to sit below
+    // is gone — that credentials case can no longer reach the rollback path.)
+    if (verdict.kind === "healthy-unverified") {
+        console.log(`✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
+        console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
+        console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
+        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");
@@ -8701,6 +8728,15 @@ async function startFlairProcess(port) {
 async function restartFlair(port) {
     await stopFlairProcess(port);
     await startFlairProcess(port);
+    // Bust the version-handshake cache so the next preAction nudge re-fetches
+    // the LIVE version instead of the pre-restart cached one (the false
+    // "server is running <old>" users hit for up to 60s post-upgrade+restart).
+    // Same (rootPath, serverUrl) key the preAction hook computes (~line 2189)
+    // — must match exactly, or this busts the wrong cache file.
+    try {
+        invalidateHandshakeCache(process.env.ROOTPATH ?? defaultDataDir(), `http://127.0.0.1:${port}`);
+    }
+    catch { /* best-effort — never fail a restart over cache cleanup */ }
 }
 program
     .command("restart")

package/dist/version-check.js

@@ -116,6 +116,19 @@ export async function checkVersion(installed, injected = {}) {
     }
     return { installed, latest: null, source: "unavailable" };
 }
+/**
+ * Primes the version-check cache with an already-known `latest` — e.g. right
+ * after `flair upgrade` fetches the true latest fresh via its own direct
+ * registry call, so the NEXT `checkVersion` (from `flair status`/`doctor`)
+ * reflects it immediately instead of serving a stale cached value for up to
+ * `DEFAULT_TTL_MS`. Reuses `writeCacheFile`, which is already best-effort/
+ * never-throws — a failed cache write must never surface as a command error.
+ */
+export function primeVersionCheckCache(latest, injected = {}) {
+    const cachePath = injected.cachePath ?? DEFAULT_CACHE_PATH;
+    const now = injected.now ?? (() => Date.now());
+    writeCacheFile(cachePath, { latest, checkedAt: now() });
+}
 const NO_GAP = { severity: "none", majorBehind: false, releasesBehind: 0 };
 /**
  * Classify how far `installed` is behind `latest` using major.minor.patch

package/dist/version-handshake.js

@@ -14,7 +14,7 @@
  * ROOTPATH, or a --target-switched remote), and a mismatch cached for one
  * must never bleed into a nudge about a different one.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
@@ -110,6 +110,25 @@ export async function checkServerHandshake(cliVersion, rootPath, serverUrl, inje
     }
     return { cliVersion, runningVersion: null, mismatch: false, source: "unavailable" };
 }
+/**
+ * Deletes the cached running-version entry for a given (rootPath, serverUrl)
+ * pair — e.g. after `flair restart`/`flair upgrade` bounces the server, so
+ * the NEXT `checkServerHandshake` call re-fetches the live version instead
+ * of returning the pre-restart one for up to `DEFAULT_HANDSHAKE_TTL_MS`.
+ * Best-effort, like the rest of this module: a failed cache delete (missing
+ * file, permissions, read-only $HOME) must never surface as an error.
+ */
+export function invalidateHandshakeCache(rootPath, serverUrl, injected = {}) {
+    const cacheDir = injected.cacheDir ?? DEFAULT_HANDSHAKE_CACHE_DIR;
+    try {
+        const path = cacheFilePath(cacheDir, rootPath, serverUrl);
+        if (existsSync(path))
+            rmSync(path);
+    }
+    catch {
+        // Best-effort — a failed cache delete must never surface as an error.
+    }
+}
 /**
  * The one-line stderr nudge, or null when there's nothing worth printing
  * (no mismatch, or nothing to compare against). Exact wording per the spec:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "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",