@tpsdev-ai/flair 0.47.0 → 0.48.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.47.0",
-  "commit": "8e83a73aac3803eceb942532fe565340c9ad52e8",
-  "builtAt": "2026-08-21T17:53:45.214Z",
+  "version": "0.48.0",
+  "commit": "a6cc5ad0f58d9b2549ffd6214028120955c87349",
+  "builtAt": "2026-08-22T19:11:54.849Z",
   "builder": "tsc"
 }

package/dist/cli.js

@@ -2561,11 +2561,13 @@ export function upgradeStatusSuffix(name, status) {
     }
     if (status === "optional")
         return " (install via: openclaw plugins install @tpsdev-ai/openclaw-flair)";
-    // flair-mcp is refreshed by re-pinning its wiring (`flair doctor --fix` /
-    // the post-upgrade pin refresh), never `npm install -g` — a global bin does
-    // nothing for an `npx -y -p @tpsdev-ai/flair-mcp` invocation (flair#1208).
+    // flair-mcp is refreshed by re-pinning its wiring, never `npm install -g` —
+    // a global bin does nothing for an `npx -y -p @tpsdev-ai/flair-mcp`
+    // invocation (flair#1208). The re-pin is `flair upgrade`'s own job (the
+    // #1135/#1167 pin refresh) — never advise `doctor --fix` for it
+    // (flair#1324).
     if (status === "outdated" && name === FLAIR_MCP_PACKAGE) {
-        return " (npx-wired — run: flair doctor --fix to re-pin)";
+        return " (npx-wired — flair upgrade refreshes the pin)";
     }
     return "";
 }
@@ -10220,11 +10222,69 @@ program
         console.log("\n✅ Everything is up to date.");
         return;
     }
-    // Nothing to install via npm/openclaw. What is left is advisory: packages
-    // not detected (missing) and/or a flair-mcp whose wired pin is behind latest
-    // — both fixed by re-wiring (`flair doctor --fix`), never by the
-    // npm-install + restart transaction below (#1168/#1208). Print the remedies
-    // and stop.
+    // ONE pin-refresh implementation, two callers (flair#1324): the post-
+    // install refresh below (#1135/#1167), and the stale-pin-only path — when
+    // flair-mcp's wired pin is behind latest but no package needs installing,
+    // `flair upgrade` refreshes the pin itself instead of advising a
+    // `doctor --fix` round-trip. Only refreshes clients that are ALREADY
+    // wired — never wires new ones. Best-effort: failures warn but never fail
+    // the upgrade.
+    async function refreshWiredMcpClientPins(targetPort) {
+        const agentId = resolveAgentIdOrEnv({}) ?? (() => {
+            try {
+                const kd = defaultKeysDir();
+                const keyFiles = readdirSync(kd).filter((f) => f.endsWith(".key"));
+                // Node-scoped federation keys aren't agents (flair#1193) — never
+                // pin-refresh a connector as one.
+                const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), kd));
+                return agentKeyFile ? agentKeyFile.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:${targetPort}`;
+        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}`);
+        }
+    }
+    // Nothing to install via npm/openclaw. What is left is advisory (packages
+    // not detected) and/or a flair-mcp whose wired pin is behind latest. The
+    // stale pin is `flair upgrade`'s OWN job (flair#1324): refresh it right
+    // here rather than bouncing the user to `flair doctor --fix` — advice
+    // that was both roundabout and, until #1324, routed every upgrading user
+    // through doctor's consent hazard. Under --check, only say what a real
+    // run will do. `npm install -g` remains wrong for flair-mcp either way
+    // (#1168/#1208).
     if (totalUpgrades === 0) {
         if (missing.length > 0) {
             const npmMissing = missing.filter((f) => f.name !== FLAIR_MCP_PACKAGE);
@@ -10239,7 +10299,12 @@ program
         }
         if (flairMcpOutdated) {
             console.log(`\n⬆️  flair-mcp is wired via npx (pinned ${flairMcpOutdated.installed} → latest ${flairMcpOutdated.latest}).`);
-            console.log(`   Re-pin it: flair doctor --fix`);
+            if (checkOnly) {
+                console.log("   Run: flair upgrade (refreshes the pin)");
+            }
+            else {
+                await refreshWiredMcpClientPins(resolveHttpPort({}));
+            }
         }
         return;
     }
@@ -10460,54 +10525,7 @@ program
     // 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 kd = defaultKeysDir();
-                const keyFiles = readdirSync(kd).filter((f) => f.endsWith(".key"));
-                // Node-scoped federation keys aren't agents (flair#1193) — never
-                // pin-refresh a connector as one.
-                const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), kd));
-                return agentKeyFile ? agentKeyFile.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}`);
-        }
-    })();
+    await refreshWiredMcpClientPins(upgradePort);
     // ── 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
@@ -13094,35 +13112,20 @@ program
             // the SessionStart check above: installed / absent / stale-form).
             // Continuity is OPT-IN — installing the PostToolUse+Stop pair IS the
             // opt-in — so "absent" renders as informational "not enabled": NEVER
-            // a pass (an unrun check must not look green) and never counted as an
-            // issue. A partial/stale install IS an issue and is --fix-able;
-            // --fix also offers first-time enablement (the y/N prompt is the
-            // consent; non-TTY --fix is itself the consent signal, matching every
-            // other doctor fix).
+            // a pass (an unrun check must not look green), never counted as an
+            // issue, and NEVER wired by --fix (flair#1324: doctor's fixable set
+            // is broken state; initiating an opt-in the user hasn't made is not a
+            // fix — a y/N prompt auto-answers yes in every non-TTY run, so it was
+            // no consent gate at all; enablement is `flair hook install
+            // --continuity` only). A partial or stale pair IS evidence of a prior
+            // opt-in, so repairing it to the complete current form remains a
+            // legitimate --fix.
             const continuity = checkContinuityCaptureHooks(homedir());
             if (continuity.state === "installed") {
                 console.log(`  ${render.icons.ok} Continuity capture hooks: PostToolUse + Stop wired in ${render.wrap(render.c.dim, continuity.path)}`);
             }
             else if (continuity.state === "absent") {
                 console.log(`  ${render.icons.info} Continuity capture hooks: not enabled ${render.wrap(render.c.dim, "(opt-in — auto-journal working state into the ephemeral memory tier; enable: flair hook install --continuity)")}`);
-                if (autoFix) {
-                    if (dryRun) {
-                        console.log(`     ${render.wrap(render.c.dim, "Would wire the continuity capture hooks (PostToolUse + Stop) in")} ${continuity.path}`);
-                    }
-                    else {
-                        const proceed = await confirmFix(`  Enable continuity capture (PostToolUse + Stop hooks in ${continuity.path})? [y/N] `);
-                        if (!proceed) {
-                            console.log(`     Skipped.`);
-                        }
-                        else {
-                            const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
-                            const fixRes = fixContinuityCaptureHooks(homedir(), fixAgentId);
-                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok && fixRes.changed)
-                                fixed++;
-                        }
-                    }
-                }
             }
             else {
                 const continuityDetail = continuity.state === "partial"

package/dist/resources/Memory.js

@@ -614,8 +614,22 @@ export class Memory extends databases.flair.Memory {
             }
         }
         content.durability ||= "standard";
-        content.createdAt = new Date().toISOString();
-        content.updatedAt = content.createdAt;
+        // ── flair#1336: honor a caller-supplied createdAt (parity with put()) ──
+        // put() — the other HTTP-reachable create path — has always preserved the
+        // caller's createdAt (`content.createdAt ?? now`), and adk-flair's
+        // add_memory forwards MemoryEntry.timestamp through it for historical
+        // imports. When #1336 moved client creates onto POST, this line's
+        // unconditional re-stamp silently discarded those timestamps (caught by
+        // the #1334 list-pagination live test: rows written with backdated
+        // timestamps came back stamped "now"). Honoring the caller grants no new
+        // capability — PUT already accepted arbitrary createdAt from the same
+        // principals. validFrom below keys off createdAt and follows it, exactly
+        // as on the put() path; updatedAt stays the true write moment; the
+        // ephemeral expiresAt stamp keys off Date.now(), so a backdated create
+        // cannot stretch the #1257 exposure window.
+        const nowIso = new Date().toISOString();
+        content.createdAt = content.createdAt ?? nowIso;
+        content.updatedAt = nowIso;
         content.archived = content.archived ?? false;
         // ─── Default visibility (durability-keyed) — Layer 1, part A ────────────
         // post() only ever creates a NEW record — patchRecord/supersede-close/
@@ -658,9 +672,13 @@ export class Memory extends databases.flair.Memory {
         if (content.visibility === undefined || content.visibility === null) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }
-        // Validate derivedFrom source IDs exist (best-effort, non-blocking)
+        // Validate derivedFrom source IDs exist (best-effort, non-blocking).
+        // lastReflected keys off updatedAt (the write moment), NOT createdAt —
+        // since #1336 a create may carry a backdated caller createdAt, and the
+        // reflection bookkeeping must record when the derivation actually ran.
+        // (Pre-#1336 the two were always identical here.)
         if (Array.isArray(content.derivedFrom) && content.derivedFrom.length > 0) {
-            const now = content.createdAt;
+            const now = content.updatedAt;
             for (const sourceId of content.derivedFrom) {
                 try {
                     const src = await databases.flair.Memory.get(sourceId);

package/dist/resources/SemanticSearch.js

@@ -61,7 +61,7 @@ export class SemanticSearch extends Resource {
         // recall-harness (test/bench/recall-harness/run.ts) and `recall-eval.mjs`
         // before reconsidering this default if the compositeScore formula or
         // corpus changes.
-        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, abstain = false, explain = false } = data || {};
+        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, includeMetadata = false, abstain = false, explain = false } = data || {};
         // Authenticated identity lives on the Harper Resource context (getContext().request).
         // `this.request` is NOT populated on Harper v5 Resources — prior reads here
         // silently returned undefined and the defense-in-depth scope check below
@@ -234,7 +234,20 @@ export class SemanticSearch extends Resource {
             // default projection omits. Widen the select ONLY when the caller opts
             // in — passing undefined otherwise keeps the default (no `provenance`)
             // so a non-trust recall response stays byte-identical.
-            select: includeTrust ? [...DEFAULT_SELECT, "provenance"] : undefined,
+            //
+            // flair#1332: same idiom for the client-writable `metadata` JSON blob
+            // (ADK custom_metadata store-and-return). DEFAULT_SELECT deliberately
+            // does NOT grow it (K&S projection ruling — the shared retrieval core
+            // serves every consumer, and none of the others should pay result-size
+            // for an opaque blob they never read); adk-flair opts in per-request
+            // with `includeMetadata: true`. `subject` needs no widening — it is
+            // already in DEFAULT_SELECT. Neither flag ⇒ select stays undefined ⇒
+            // response bytes unchanged.
+            select: (includeTrust || includeMetadata)
+                ? [...DEFAULT_SELECT,
+                    ...(includeTrust ? ["provenance"] : []),
+                    ...(includeMetadata ? ["metadata"] : [])]
+                : undefined,
             // flair#744 slice 2 + confidence-band refinement: attach the absolute
             // per-result cosine confidence when the caller opts into abstention OR
             // the trust block — abstention reads the best of it for its verdict, and

package/package.json

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

package/schemas/memory.graphql

@@ -85,6 +85,19 @@ type Memory @table(database: "flair") {
                                # stamped by the ORIGINATING instance itself and preserved (never re-stamped) as the record flows through
                                # sync merges. @indexed for the later sync push-query filter (per-record signature verification and the
                                # classifier org-gate are separate, later slices — not built here).
+  metadata: String             # JSON blob (flair#1332/#1202): ADK custom_metadata, store-and-return. CLIENT-WRITABLE
+                               # (unlike provenance above, which is server-stamped) and OPAQUE TO THE SERVER by
+                               # contract: stored verbatim, returned verbatim, never parsed server-side, never
+                               # queryable (Harper cannot query into a JSON blob), and NO key inside this blob
+                               # ever influences any server decision — visibility, read-scope, durability,
+                               # expiry, federation, ranking, nothing. A blob carrying {"visibility":"shared"}
+                               # leaves the record's ACTUAL visibility at its default (contract-tested in
+                               # packages/adk-flair/tests/test_metadata_and_list.py). If a specific key ever
+                               # needs to be filterable, promote THAT key to its own @indexed scalar column
+                               # (the #1202-documented add-on pattern; `subject` below is the first example) —
+                               # never parse this blob. Size/shape caps are enforced at the writing client
+                               # (adk-flair: 64KB serialized, depth ≤ 16, ≤ 512 keys). Nullable/additive —
+                               # existing rows read null, unchanged behavior (clean-upgrade-path gate).
   entities: [String] @indexed  # attention-plane vocabulary strings (flair#675). Added in v1 (not v2) per K&S
                                # verdict on FLAIR-ATTENTION-PLANE.md — gives the future attention query
                                # uniform index pushdown across Memory/WorkspaceState/OrgEvent instead of a