@tpsdev-ai/flair 0.44.8 → 0.44.10

package/dist/cli.js

@@ -19,11 +19,11 @@ import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache }
 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, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
+import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, wireAntigravity, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
+import { flairCliVersion, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning, FLAIR_MCP_PACKAGE } 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, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, detectWiredFlairMcp, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
@@ -2394,14 +2394,58 @@ export function upgradeStatusSuffix(name, status) {
     if (status === "current")
         return " (current)";
     if (status === "missing") {
-        return name === "@tpsdev-ai/flair-mcp"
+        return name === FLAIR_MCP_PACKAGE
             ? " (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)";
+    // 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).
+    if (status === "outdated" && name === FLAIR_MCP_PACKAGE) {
+        return " (npx-wired — run: flair doctor --fix to re-pin)";
+    }
     return "";
 }
+/**
+ * Resolve the `flair upgrade` finding for flair-mcp from its ACTUAL wiring,
+ * not a global-install probe (flair#1208).
+ *
+ * flair-mcp is zero-install via npx (#1168): a correctly-wired machine never
+ * installs it globally, so the global bin/lib probe returning null is the
+ * NORMAL state, not "missing". Its real installed version is the pin its wiring
+ * carries (a client MCP config's args, refreshed by `flair doctor --fix`).
+ *
+ * Resolution order:
+ *   1. Legacy global install — the bin/lib probe found a version. Honor it.
+ *   2. Not wired anywhere — genuinely missing; the remedy (upgradeStatusSuffix)
+ *      is `flair doctor --fix`, never `npm install -g`.
+ *   3. Wired with a concrete pin — that pin IS the installed version
+ *      (current when it equals latest, else outdated → re-pin via doctor).
+ *   4. Wired but unpinned (a bare npx spec / the SessionStart hook) — `npx -y`
+ *      re-resolves latest every session, so the effective version IS latest →
+ *      current.
+ */
+export function resolveFlairMcpFinding(globalProbe, latest, wiring) {
+    // 1. Legacy global install.
+    if (globalProbe !== null) {
+        return { installed: globalProbe, status: globalProbe === latest ? "current" : "outdated" };
+    }
+    // 2. Not wired anywhere.
+    if (!wiring.wired) {
+        return { installed: null, status: "missing" };
+    }
+    // 3. Wired with a pin.
+    if (wiring.pinnedVersion) {
+        return {
+            installed: wiring.pinnedVersion,
+            status: wiring.pinnedVersion === latest ? "current" : "outdated",
+        };
+    }
+    // 4. Wired but unpinned — npx resolves latest on every session.
+    return { installed: latest, status: "current" };
+}
 /**
  * Pure flag resolution for `flair upgrade`'s restart/verify defaults
  * (flair#635 decision: restart is now the default; `--no-restart` opts
@@ -2714,7 +2758,7 @@ program
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
     .option("--skip-soul", "Skip interactive personality setup")
-    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, all, or none")
+    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, antigravity, all, or none")
     .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
     .option("--skip-smoke", "Skip the MCP smoke test")
     .option("--skip-claude-md", "Skip appending the Flair bootstrap line to CLAUDE.md (claude-code only)")
@@ -2933,9 +2977,9 @@ program
     const noMcp = opts.mcp === false;
     const selectedClients = [];
     if (clientOpt && clientOpt !== "all" && clientOpt !== "none" && !noMcp) {
-        const valid = ["claude-code", "codex", "gemini", "cursor"];
+        const valid = ["claude-code", "codex", "gemini", "cursor", "antigravity"];
         if (!valid.includes(clientOpt)) {
-            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, all, none`);
+            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, antigravity, all, none`);
             process.exit(1);
         }
         selectedClients.push(clientOpt);
@@ -3536,6 +3580,9 @@ program
                         case "cursor":
                             result = wireCursor({ ...mcpEnv, FLAIR_CLIENT: "cursor" });
                             break;
+                        case "antigravity":
+                            result = wireAntigravity({ ...mcpEnv, FLAIR_CLIENT: "antigravity" });
+                            break;
                         default: result = { ok: false, message: `Unknown client: ${clientId}` };
                     }
                     wiringResults.push({ client: clientId, message: result.message, wired: result.ok });
@@ -7408,6 +7455,133 @@ export function decideCandidateAction(candidate, action) {
     }
     return { ok: true };
 }
+// ─── ADK tag-lineage on promote (#1205 slice 1205a — Sherlock security req) ───
+// ADK session records are written by adk-flair (memory_service.py) under a
+// SHARED-namespace agentId, with per-user separation carried ENTIRELY by a
+// compound scope tag `adk:<app>:<user>`. That tag is the access-control
+// boundary. A candidate distilled from those records therefore MUST carry the
+// scope tag when promoted, or the promoted claim lands in the shared agentId
+// memory retrievable by every other user of the app — a cross-user leak.
+//
+// `rem promote` historically hard-coded `["nightly-rem-promoted", from:<id>]`
+// and DROPPED the source tag. We now propagate the source scope tag for
+// ADK-sourced candidates, and FAIL CLOSED (refuse) when a candidate is
+// ADK-sourced but its scope tag can't be uniquely+completely determined.
+//
+// SCOPING (deliberate, per spec): fail-closed applies ONLY to ADK-sourced
+// candidates. Non-ADK candidates carry no `adk:` tag and promote byte-for-byte
+// as before — a transient/deleted source on a non-ADK candidate must NOT block
+// its promotion.
+//
+// SEAM (foundation only; the distillation engine is slice #1205b): ADK-sourcing
+// is detected here by re-reading the candidate's source memories and inspecting
+// their tags. That leaves ONE residual fail-open: an ADK-sourced candidate all
+// of whose source memories are unreadable (deleted/transient) yields no `adk:`
+// evidence and is treated as non-ADK. Closing that corner without regressing
+// non-ADK promotion requires the ENGINE to stamp the authoritative scope tag
+// onto the MemoryCandidate row at distillation time (it distills per single
+// scope:tagged tag, so it knows it authoritatively). `derivePromotedTags` is
+// written so that override can be threaded in later without touching callers.
+export const ADK_SCOPE_TAG_PREFIX = "adk:";
+/**
+ * Decide the tag set for a promoted Memory given the candidate id and the
+ * result of fetching each of its source memories. Pure — no I/O; the action
+ * callback does the fetching and threads the results here so this is unit-
+ * testable and the fail-closed logic is exercised directly.
+ *
+ * `stampedScopeTag` (#1205b-1 — the engine slice the #1205a SEAM note below
+ * anticipated): the authoritative scope:"tagged" tag the distillation engine
+ * stamped onto the MemoryCandidate row (resources/MemoryReflect.ts →
+ * buildStagedCandidateRow). When present it is AUTHORITATIVE and short-circuits
+ * the source re-read entirely — the engine distilled under exactly this one
+ * tag, so it knows the per-user scope tag independent of whether the source
+ * memories are still readable. This closes the residual fail-open the SEAM
+ * note describes: a candidate all of whose sources are unreadable yields no
+ * `adk:` evidence and would otherwise be mis-classified NON-ADK and promoted
+ * tagless into the shared agentId namespace (a cross-user leak). Threading it
+ * in as an optional trailing arg keeps every pre-#1205b caller (and every
+ * candidate that never carried a stamp) on the unchanged source-re-read path.
+ *
+ * With NO stamp (undefined/empty) the source-re-read classification runs
+ * exactly as in #1205a:
+ *  - No `adk:` scope tag across readable sources → NON-ADK candidate; return
+ *    the provenance tags only (unchanged behavior).
+ *  - Exactly one `adk:` scope tag AND every source readable → ADK-sourced;
+ *    return [scopeTag, ...provenance].
+ *  - `adk:` evidence present but the scope tag is ambiguous (>1 distinct tag)
+ *    OR incomplete (some source unreadable) → REFUSE (fail-closed): a
+ *    tagless/mis-tagged claim in a shared ADK namespace is a cross-user leak,
+ *    not a benign miss.
+ */
+export function derivePromotedTags(candidateId, sources, stampedScopeTag) {
+    const provenance = ["nightly-rem-promoted", `from:${candidateId}`];
+    // #1205b-1: a stamped scope tag is AUTHORITATIVE — consume it directly, never
+    // re-read sources. This is the seam closure: correctness no longer depends on
+    // source readability. `adkSourced` (which gates the Soul-promotion refusal in
+    // the promote action) tracks whether the stamped tag is an ADK scope tag.
+    if (typeof stampedScopeTag === "string" && stampedScopeTag.length > 0) {
+        return {
+            ok: true,
+            tags: [stampedScopeTag, ...provenance],
+            adkSourced: stampedScopeTag.startsWith(ADK_SCOPE_TAG_PREFIX),
+        };
+    }
+    const adkTags = new Set();
+    let anySourceUnreadable = false;
+    for (const s of sources) {
+        if (!s.ok) {
+            anySourceUnreadable = true;
+            continue;
+        }
+        for (const t of s.tags) {
+            if (typeof t === "string" && t.startsWith(ADK_SCOPE_TAG_PREFIX))
+                adkTags.add(t);
+        }
+    }
+    // No positive ADK evidence → non-ADK. An unreadable source with zero ADK
+    // evidence does NOT fail closed here (that would regress non-ADK promotion);
+    // see the SEAM note above.
+    if (adkTags.size === 0) {
+        return { ok: true, tags: provenance, adkSourced: false };
+    }
+    if (adkTags.size > 1) {
+        return {
+            ok: false,
+            reason: `ADK-sourced candidate spans multiple scope tags (${[...adkTags].sort().join(", ")}); refusing to promote — a merged cross-user claim would leak across users`,
+        };
+    }
+    if (anySourceUnreadable) {
+        return {
+            ok: false,
+            reason: `ADK-sourced candidate has unreadable source memories; the per-user scope tag cannot be confirmed — refusing to promote (fail-closed)`,
+        };
+    }
+    const scopeTag = [...adkTags][0];
+    return { ok: true, tags: [scopeTag, ...provenance], adkSourced: true };
+}
+// ─── Machine reviewer namespace (#1205 slice 1205a — Sherlock security req 4) ─
+// A promotion records a reviewerId that feeds audit/attribution
+// (schemas/memory.graphql:209). An automated (machine-driven) promotion path
+// must record a reviewerId that can NEVER be mistaken for a human/agent
+// reviewer, so attribution isn't laundered. Reserve the `machine:` namespace
+// for that, and forbid the human `--reviewer` path from claiming it.
+export const MACHINE_REVIEWER_PREFIX = "machine:";
+/** Canonical machine reviewerId for the ADK auto-promote consumer (#1205b). */
+export const MACHINE_REVIEWER_ADK_AUTO_PROMOTE = "machine:adk-auto-promote";
+/** True iff `id` is in the reserved machine-reviewer namespace — i.e. it
+ *  denotes an automated path, not a human or agent reviewer. */
+export function isMachineReviewerId(id) {
+    return typeof id === "string" && id.startsWith(MACHINE_REVIEWER_PREFIX);
+}
+/** The human `flair rem promote` path must not record a reviewerId in the
+ *  reserved machine namespace — that would launder automated attribution onto
+ *  a human-operated promotion. Returns an error string, or null if allowed. */
+export function validateHumanReviewerId(reviewerId) {
+    if (isMachineReviewerId(reviewerId)) {
+        return `--reviewer '${reviewerId}' uses the reserved '${MACHINE_REVIEWER_PREFIX}' namespace (reserved for automated promotion); use a human/agent reviewer id`;
+    }
+    return null;
+}
 // ─── flair rem promote ───────────────────────────────────────────────────────
 // Slice 2 of FLAIR-NIGHTLY-REM (ops-2qq). Promote a candidate to either Soul
 // or persistent Memory. Both --rationale and --to are required (spec § 5: no
@@ -7435,6 +7609,13 @@ rem
         process.exit(1);
     }
     const reviewerId = opts.reviewer || process.env.FLAIR_AGENT_ID || "admin";
+    // The human promote path must not record a reserved machine reviewerId
+    // (Sherlock #4): that would launder automated attribution.
+    const reviewerErr = validateHumanReviewerId(reviewerId);
+    if (reviewerErr) {
+        console.error(`Error: ${reviewerErr}`);
+        process.exit(1);
+    }
     try {
         // Fetch the candidate
         const candidate = await api("GET", `/MemoryCandidate/${encodeURIComponent(candidateId)}`);
@@ -7445,6 +7626,51 @@ rem
             console.error(`Error: candidate ${candidateId} ${msg}`);
             process.exit(1);
         }
+        // ADK tag-lineage: derive the promoted-claim tag set.
+        //
+        // #1205b-1: if the engine stamped an authoritative `scopeTag` on the
+        // candidate (scope:"tagged" distillation), consume it DIRECTLY and skip
+        // the source re-read — correctness no longer depends on the source
+        // memories still being readable (the #1205a seam closure). We only fall
+        // back to re-reading sources when there is NO stamp (a pre-#1205b
+        // candidate, or a non-tagged distillation).
+        const stampedScopeTag = typeof candidate.scopeTag === "string" && candidate.scopeTag.length > 0 ? candidate.scopeTag : undefined;
+        const sourceFetches = [];
+        if (!stampedScopeTag) {
+            // No authoritative stamp — re-read sources to classify. Fail-closed for
+            // ADK-sourced candidates whose per-user scope tag can't be confirmed;
+            // unchanged for non-ADK candidates. See derivePromotedTags for rules.
+            const sourceIds = Array.isArray(candidate.sourceMemoryIds) ? candidate.sourceMemoryIds : [];
+            for (const sid of sourceIds) {
+                try {
+                    const mem = await api("GET", `/Memory/${encodeURIComponent(String(sid))}`);
+                    if (mem && !mem.error) {
+                        sourceFetches.push({ ok: true, tags: Array.isArray(mem.tags) ? mem.tags : [] });
+                    }
+                    else {
+                        sourceFetches.push({ ok: false });
+                    }
+                }
+                catch {
+                    sourceFetches.push({ ok: false });
+                }
+            }
+        }
+        const tagDecision = derivePromotedTags(candidateId, sourceFetches, stampedScopeTag);
+        if (!tagDecision.ok) {
+            console.error(`Error: candidate ${candidateId} — ${tagDecision.reason}`);
+            process.exit(1);
+        }
+        // Soul entries are agentId-scoped and cannot carry a per-user scope tag,
+        // so an ADK-sourced candidate promoted to Soul is a cross-user leak by
+        // construction — fail closed. (Server-side trust-tier enforcement that
+        // hard-locks the target is the engine slice #1205b; this is the CLI-side
+        // foundation.)
+        if (opts.to === "soul" && tagDecision.adkSourced) {
+            console.error(`Error: candidate ${candidateId} is ADK-sourced (scope tag ${tagDecision.tags[0]}); Soul is agentId-scoped and cannot carry a per-user scope tag — refusing to promote to Soul (would leak across users). Promote ADK-sourced candidates to memory.`);
+            process.exit(1);
+        }
+        const promotedTags = tagDecision.tags;
         const decidedAt = new Date().toISOString();
         // Write the resulting Soul or Memory entry
         if (opts.to === "memory") {
@@ -7454,7 +7680,7 @@ rem
                 agentId: candidate.agentId,
                 content: candidate.claim,
                 durability: "persistent",
-                tags: ["nightly-rem-promoted", `from:${candidateId}`],
+                tags: promotedTags,
                 derivedFrom: candidate.sourceMemoryIds ?? [],
                 promotionStatus: "approved",
                 promotedAt: decidedAt,
@@ -9517,18 +9743,30 @@ program
                 }
                 catch { /* best-effort */ }
             }
-            const installed = probe();
+            const globalProbe = probe();
+            let installed;
             let status;
-            if (installed === null) {
-                // openclaw-plugin packages are optional — if openclaw isn't
-                // installed, don't surface a misleading "install with npm" advice.
-                status = kind === "openclaw-plugin" ? "optional" : "missing";
-            }
-            else if (installed === latest) {
-                status = "current";
+            if (name === FLAIR_MCP_PACKAGE) {
+                // flair-mcp is zero-install via npx (#1168) — a null global probe is
+                // the NORMAL state, not "missing". Resolve it from its actual wiring
+                // (the pin in a client MCP config / the SessionStart hook) so the
+                // listing is truthful and the remedy actually works (flair#1208).
+                const home = process.env.HOME ?? homedir();
+                ({ installed, status } = resolveFlairMcpFinding(globalProbe, latest, detectWiredFlairMcp(home)));
             }
             else {
-                status = "outdated";
+                installed = globalProbe;
+                if (installed === null) {
+                    // openclaw-plugin packages are optional — if openclaw isn't
+                    // installed, don't surface a misleading "install with npm" advice.
+                    status = kind === "openclaw-plugin" ? "optional" : "missing";
+                }
+                else if (installed === latest) {
+                    status = "current";
+                }
+                else {
+                    status = "outdated";
+                }
             }
             findings.push({ name, installed, latest, status, kind });
             // Suppress the line for openclaw plugins that are optional-because-
@@ -9553,12 +9791,19 @@ program
     console.log("\nScope: npm-global packages (flair, flair-mcp) + openclaw plugins. Other integrations (pi-flair, langgraph-flair, n8n-nodes-flair, hermes-flair) upgrade in their own ecosystems (pi / pip / n8n).");
     const outdated = findings.filter((f) => f.status === "outdated");
     const missing = findings.filter((f) => f.status === "missing");
+    // flair-mcp is refreshed by re-pinning its wiring (`flair doctor --fix` /
+    // the post-upgrade pin refresh below), NEVER `npm install -g` — a global
+    // bin does nothing for an `npx -y -p @tpsdev-ai/flair-mcp` invocation
+    // (#1168/#1208). So a stale-pinned flair-mcp drives a remedy line, not the
+    // npm-install + restart transaction. It is kept out of npmUpgrades here and
+    // surfaced separately below.
+    const flairMcpOutdated = outdated.find((f) => f.name === FLAIR_MCP_PACKAGE) ?? null;
     // openclaw plugins upgrade through `openclaw plugins install`, not `npm
     // install -g` (npm-installed wouldn't connect to OpenClaw's gateway slot).
     // Split outdated into npm-upgradeable vs openclaw-plugin so we can use
     // the right command for each.
     const npmUpgrades = outdated
-        .filter((f) => f.kind !== "openclaw-plugin")
+        .filter((f) => f.kind !== "openclaw-plugin" && f.name !== FLAIR_MCP_PACKAGE)
         .map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
     const openclawUpgrades = outdated
         .filter((f) => f.kind === "openclaw-plugin")
@@ -9568,15 +9813,26 @@ program
         console.log("\n✅ Everything is up to date.");
         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.`);
-        if (npmMissing.length > 0) {
-            console.log(`   Install missing: npm install -g ${npmMissing.map((f) => f.name).join(" ")}`);
+    // 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.
+    if (totalUpgrades === 0) {
+        if (missing.length > 0) {
+            const npmMissing = missing.filter((f) => f.name !== FLAIR_MCP_PACKAGE);
+            const mcpMissing = missing.some((f) => f.name === FLAIR_MCP_PACKAGE);
+            console.log(`\n❔ ${missing.length} package${missing.length > 1 ? "s" : ""} not detected — all detected packages are up to date.`);
+            if (npmMissing.length > 0) {
+                console.log(`   Install missing: npm install -g ${npmMissing.map((f) => f.name).join(" ")}`);
+            }
+            if (mcpMissing) {
+                console.log(`   flair-mcp is zero-install via npx — run: flair doctor --fix to wire the hook`);
+            }
         }
-        if (mcpMissing.length > 0) {
-            console.log(`   flair-mcp is zero-install via npx — run: flair doctor --fix to re-wire the hook`);
+        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`);
         }
         return;
     }
@@ -12154,7 +12410,8 @@ program
                                 const wireResult = client.id === "claude-code" ? wireClaudeCode(wireEnv) :
                                     client.id === "codex" ? wireCodex(wireEnv) :
                                         client.id === "gemini" ? wireGemini(wireEnv) :
-                                            wireCursor(wireEnv);
+                                            client.id === "antigravity" ? wireAntigravity(wireEnv) :
+                                                wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
                                 if (wireResult.ok)
                                     fixed++;
@@ -12680,7 +12937,14 @@ program
 // a real user query, so a high score means "recall is functioning", not
 // "recall is optimal". Its job is to catch recall CRATERING (embeddings
 // down, index busted) — the score collapsing toward 0 is the signal, not
-// fine-grained precision grading. Requires an actual agent identity to
+// fine-grained precision grading. NOTE (#1216): this cue-from-the-memory
+// design is self-polluting as a recall-QUALITY metric — relevance is
+// query/corpus overlap by construction, so near-duplicate density reads as a
+// recall collapse (flair#967 / #857 / #996). It is deliberately NOT the
+// recall-quality number; that authority is the deterministic, fixed-label,
+// CI-gated eval at test/bench/recall-eval (recall@k / nDCG@10 / MRR). This
+// probe stays scoped to live-health cratering only. Requires an actual
+// agent identity to
 // query AS (semantic search is agent-scoped) — no identity, fewer than the
 // sample-size memories to sample, or a search error all degrade to `null` +
 // a `gaps` entry, same graceful-degradation contract as every metric here —

package/dist/doctor-client.js

@@ -22,7 +22,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { clientConfigPath } from "./install/clients.js";
+import { ALL_CLIENTS, clientConfigPath } from "./install/clients.js";
+import { FLAIR_MCP_PACKAGE } from "./lib/mcp-spec.js";
 // The exact substring `flair init` writes into CLAUDE.md (src/cli.ts, the
 // `init` action) and that the doctor check + fix both key off of.
 export const CLAUDE_MD_BOOTSTRAP_MARKER = "mcp__flair__bootstrap";
@@ -365,6 +366,59 @@ export function checkSessionStartHook(homeDir) {
         return { present: false, path };
     }
 }
+// ── flair-mcp presence by WIRING, not global install (flair#1208) ───────────
+//
+// flair-mcp is zero-install via npx by design (#1168): a correctly-wired
+// machine invokes it as `npx -y -p @tpsdev-ai/flair-mcp` and NEVER installs it
+// globally, so `flair upgrade`'s global bin/lib probe finds nothing and
+// mis-reports it "not detected." Its real "installed version" is the pin its
+// wiring carries — the mcpServerSpec() written into a client's MCP config
+// (pinned since #1135). Detect it there instead.
+/**
+ * Extract a pinned `@tpsdev-ai/flair-mcp` version from any wiring string — a
+ * client MCP `args` array, a Codex TOML args line, or a SessionStart hook
+ * command. Returns the version when the spec is written
+ * `@tpsdev-ai/flair-mcp@<ver>`; null for a bare/unpinned spec.
+ *
+ * The SessionStart hook is deliberately unpinned (`npx -y -p
+ * @tpsdev-ai/flair-mcp`, buildSessionStartHookCommand above), so a hook
+ * establishes that flair-mcp is wired but never carries a version — the pin
+ * comes from the client MCP config.
+ */
+export function extractFlairMcpPin(text) {
+    if (typeof text !== "string")
+        return null;
+    // `@tpsdev-ai/flair-mcp@<version>`; the version token runs until the first
+    // character that can't appear in a spec embedded in JSON args / TOML.
+    const m = text.match(/@tpsdev-ai\/flair-mcp@([0-9A-Za-z][^\s"'\],]*)/);
+    return m ? m[1] : null;
+}
+export function detectWiredFlairMcp(homeDir) {
+    let wired = false;
+    let pinnedVersion = null;
+    // The package name only ever appears in a Flair MCP wiring block, so its
+    // presence in a config's text is a reliable "flair-mcp is wired here" signal.
+    const note = (text) => {
+        if (!text || !text.includes(FLAIR_MCP_PACKAGE))
+            return;
+        wired = true;
+        if (!pinnedVersion) {
+            const pin = extractFlairMcpPin(text);
+            if (pin)
+                pinnedVersion = pin;
+        }
+    };
+    // 1. The SessionStart hook (claude-code). Establishes wiring; unpinned by design.
+    const hook = checkSessionStartHook(homeDir);
+    if (hook.present && isFlairHookCommand(hook.command ?? ""))
+        note(hook.command);
+    // 2. Every known client's MCP config — a wired flair block carries the spec.
+    for (const client of ALL_CLIENTS) {
+        const configPath = withHome(homeDir, () => clientConfigPath(client.id));
+        note(readTextFile(configPath));
+    }
+    return { wired, pinnedVersion };
+}
 /**
  * Merge-safe insert of a Flair SessionStart hook group into
  * ~/.claude/settings.json — creates the file/array if absent, preserves any

package/dist/install/clients.js

@@ -204,9 +204,16 @@ function replaceCodexFlairBlock(raw, env) {
  * Creates the file (and parent dir) if absent; preserves existing servers and
  * any other top-level keys. Returns ok:true only when the file was written.
  */
-function wireJsonMcp(configPath, label, env) {
+function wireJsonMcp(configPath, label, env, 
+// The parenthetical appended to a successful wire/refresh message. Defaults to
+// the confident "restart <label> to pick it up". A client whose end-to-end
+// pickup Flair has NOT verified (Antigravity — flair#1209) passes an honest
+// note instead, so the message claims only what it did (wrote the config), not
+// that the client will read it.
+pickupNote) {
     const home = resolveHome();
     const display = configPath.startsWith(home) ? "~" + configPath.slice(home.length) : configPath;
+    const note = pickupNote ?? `restart ${label} to pick it up`;
     try {
         let config = {};
         if (existsSync(configPath)) {
@@ -229,7 +236,7 @@ function wireJsonMcp(configPath, label, env) {
         mkdirSync(dirname(configPath), { recursive: true });
         writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
         const action = urlAgentMatch ? "refreshed pin in" : "wired";
-        return { ok: true, message: `${label}: ${action} ${display} (restart ${label} to pick it up)` };
+        return { ok: true, message: `${label}: ${action} ${display} (${note})` };
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -256,6 +263,23 @@ function geminiConfigPath() {
 function codexConfigPath() {
     return join(resolveHome(), ".codex", "config.toml");
 }
+/**
+ * Antigravity CLI (`agy`) + Antigravity 2.0 IDE + SDK: they share ONE central
+ * MCP config at ~/.gemini/config/mcp_config.json on every OS (flair#1209).
+ *
+ * This is a SIBLING of, and distinct from, Gemini CLI's ~/.gemini/settings.json
+ * (geminiConfigPath above) — both tools live under ~/.gemini but read different
+ * files, so wiring one never touches the other. Same standard `mcpServers`
+ * stdio schema (command/args/env) the JSON clients above use.
+ *
+ * Path per Antigravity's own docs (antigravity.google/docs/mcp) and a Google
+ * Developer Advocate write-up (atamel.dev "Where does Antigravity look for MCP
+ * Servers?"). NOTE: the end-to-end wiring has NOT been verified against a real
+ * `agy` install — see the PR body.
+ */
+function antigravityConfigPath() {
+    return join(resolveHome(), ".gemini", "config", "mcp_config.json");
+}
 /**
  * Single dispatcher for "where does this client's MCP config live" — used by
  * `flair doctor`'s client-integration checks (flair#588) to read the config
@@ -272,6 +296,8 @@ export function clientConfigPath(id) {
             return geminiConfigPath();
         case "cursor":
             return cursorConfigPath();
+        case "antigravity":
+            return antigravityConfigPath();
     }
 }
 // ---- Internal wiring functions --------------------------------------------------
@@ -330,6 +356,18 @@ function _wireGemini(env) {
 function _wireCursor(env) {
     return wireJsonMcp(cursorConfigPath(), "Cursor", env);
 }
+// Antigravity uses the same standard JSON `mcpServers` stdio schema as Gemini/
+// Cursor (command/args/env), so wireJsonMcp merges into it byte-identically —
+// only the config PATH differs (flair#1209).
+//
+// The success message deliberately does NOT claim "restart Antigravity to pick
+// it up": Flair writes the config to the documented path, but has not verified
+// end-to-end that a live `agy` reads it. So the message claims only the write,
+// and asks the user to confirm pickup (flair#1209 review — honesty on an
+// unverified integration).
+function _wireAntigravity(env) {
+    return wireJsonMcp(antigravityConfigPath(), "Antigravity", env, "wiring unverified against a real agy — restart Antigravity and confirm the flair tools appear");
+}
 // ---- Exported detection & wiring array ------------------------------------------
 export const ALL_CLIENTS = [
     {
@@ -356,6 +394,13 @@ export const ALL_CLIENTS = [
         bin: "cursor",
         wire: _wireCursor,
     },
+    {
+        id: "antigravity",
+        label: "Antigravity",
+        // Google's Antigravity CLI — the executable is `agy` (flair#1209).
+        bin: "agy",
+        wire: _wireAntigravity,
+    },
 ];
 /**
  * The summary `flair init` prints LAST.
@@ -432,3 +477,6 @@ export function wireGemini(env) {
 export function wireCursor(env) {
     return _wireCursor(env);
 }
+export function wireAntigravity(env) {
+    return _wireAntigravity(env);
+}