@tpsdev-ai/flair 0.44.7 → 0.44.9

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 });
@@ -9517,18 +9564,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 +9612,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 +9634,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 +12231,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++;
@@ -14328,7 +14406,13 @@ program
             console.error(`${render.icons.error} No context available.`);
             process.exit(1);
         }
-        const tokensUsed = result.tokenEstimate ?? 0;
+        // flair#1199 — the budget footer reflects the PROSE the human injects
+        // (stdout = result.context), not the full serialized payload. tokenEstimate
+        // now measures the whole response (structured containers + prose), which
+        // the CLI's structured fields the human doesn't read would inflate.
+        const tokensUsed = typeof result.context === "string" && result.context.length > 0
+            ? Math.ceil(result.context.length / 4)
+            : (result.tokenEstimate ?? 0);
         const maxTokens = parseInt(opts.maxTokens, 10);
         const included = result.memoriesIncluded ?? 0;
         const truncated = result.memoriesTruncated ?? 0;

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);
+}

package/dist/resources/MemoryBootstrap.js

@@ -59,7 +59,11 @@ import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
  *
  * Request:
  *   { agentId, currentTask?, maxTokens?, includeSoul?, since?,
- *     channel?, surface?, subjects?, entities? }
+ *     channel?, surface?, subjects?, entities?, includeContext? }
+ *   `includeContext` (flair#1199): whether to assemble the prose `context`
+ *   mirror. Default true here (the resource/REST/CLI path); the /mcp bootstrap
+ *   wrapper passes false so a token-budgeted connector — which reads the
+ *   structured containers — never receives the same bodies twice.
  *   `entities` (flair#681): the caller's own declared attention-plane
  *   vocabulary strings (see resources/entity-vocab.ts) for collision
  *   surfacing's entity-overlap join. Invalid entries are silently dropped
@@ -69,12 +73,37 @@ import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
  *
  * Response:
  *   { context, sections, tokenEstimate, memoriesIncluded, memoriesAvailable,
- *     agentId, scope, soul, memories, predicted[, currentTaskHint] }
+ *     teammateFindingsIncluded, teammateFindingsTruncated, agentId, scope, soul,
+ *     memories, predicted, teammateFindings, events[, currentTaskHint][, predictedHint] }
  *   The self-describing keys (flair#1182 part 1) — `agentId` (resolved caller),
  *   `scope` (read model applied to the caller), `soul`/`memories`/`predicted`
  *   (the caller's OWN records as structured containers), and `currentTaskHint`
  *   (present only when currentTask is absent/blank) — are ALWAYS emitted so a
  *   client can tell an empty instance from one that doesn't support them.
+ *   flair#1199 — the structured containers are CANONICAL; `context` is a prose
+ *   mirror (opt-in via includeContext). Cross-agent teammate findings ship in
+ *   the `teammateFindings` container (own memories in `memories`), counted by
+ *   `teammateFindingsIncluded` (a separate denominator from `memoriesIncluded`,
+ *   which is own-scoped so it never exceeds `memoriesAvailable`). flair#1206 —
+ *   org events ship in their OWN structured `events` container (ALWAYS present,
+ *   `[]` when none), so a connector reading the structured payload gets them even
+ *   when the prose `context` is off (the /mcp default); before #1206 they lived
+ *   ONLY in the prose string and were orphaned at includeContext=false.
+ *
+ *   flair#1199 CAP CONTRACT (corrected): `maxTokens` is the HARD cap on CONTENT
+ *   SELECTION — the shared `tokenBudget` starts at `maxTokens` and every admitted
+ *   soul/memory/finding line is gated against the remaining budget, so the sum of
+ *   selected CONTENT never exceeds `maxTokens`. `tokenEstimate` HONESTLY reports
+ *   the real serialized payload (`JSON.stringify(responseBody)`), which includes
+ *   the structured-container JSON scaffolding and so MAY exceed `maxTokens` by
+ *   that overhead — measurement (honest reporting) is deliberately decoupled from
+ *   budgeting (what to select). This is the flair#1207 fix: #1199 had folded a
+ *   per-item structured overhead + a scaffolding reserve INTO the selection
+ *   budget, which silently shrank recall below 0.44.6 for the same `maxTokens`;
+ *   the overhead is a reporting concern (already captured by `tokenEstimate`),
+ *   never a selection constraint, so it no longer shrinks the content budget.
+ *   `predictedHint` is present only when subjects were provided but `predicted`
+ *   came back empty.
  */
 // Collision surfacing (flair#681) tunables.
 const COLLISION_WINDOW_DAYS = 7;
@@ -110,6 +139,19 @@ const MAX_CANDIDATE_POOL = 100;
 // `minScore` request param) — preserved verbatim from the original raw
 // JS dot-product scan's `.filter((s) => s.score > 0.3)`.
 const TASK_RELEVANCE_FLOOR = 0.3;
+// flair#1207 — the per-item structured-payload overhead that #1199 charged
+// against the content-selection budget (a `+ STRUCT_ITEM_OVERHEAD_TOKENS = 70`
+// added to every item's cost, PLUS a `structOverheadReserve` pre-deducted from
+// the starting budget) has been REMOVED. It conflated measurement with
+// budgeting: `tokenEstimate` already measures the real serialized payload
+// (JSON.stringify(responseBody)) — the structured JSON scaffolding overhead is
+// captured there, honestly. Folding it into the SELECTION budget too
+// double-penalized and silently shrank recall below 0.44.6 for the same
+// `maxTokens` (6 findings → 3). The content budget is now `maxTokens` again
+// (0.44.6 selection capacity), and each item's cost is just the rendered prose
+// line — while `tokenEstimate` keeps reporting the true serialized size, which
+// may exceed `maxTokens` by the scaffolding overhead. See the module-doc CAP
+// CONTRACT above.
 // Rough token estimate: ~4 chars per token for English text
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
@@ -151,7 +193,16 @@ export class BootstrapMemories extends Resource {
         subjects, // e.g., ["flair", "auth"] — entities to preload context for
         includeTrust = false, // flair#744 slice 1 — opt-in per-memory trust block
         abstain = false, // flair#744 slice 2 — opt-in task-relevance abstention
-         } = data || {};
+        // flair#1199 — whether to assemble the prose `context` string. The
+        // structured containers (soul/memories/predicted/teammateFindings) are the
+        // CANONICAL payload; `context` is a human/agent-readable MIRROR of the same
+        // bytes. Default TRUE here (the resource/REST/CLI path has always emitted
+        // prose, and every direct caller reads it) — but the /mcp bootstrap wrapper
+        // (resources/mcp-tools.ts) passes `false` by default, so a token-budgeted
+        // connector, which consumes the structured fields, never receives the same
+        // bodies twice. When false, `context` is a compact structural pointer (no
+        // bodies), so nothing crosses the wire twice on that path.
+        includeContext = true, } = data || {};
         // Authenticated identity lives on getContext().request — `this.request` is
         // NOT populated on Harper v5 Resources. Reading it returned undefined and
         // the scope check was silently bypassed, letting a non-admin agent read
@@ -189,27 +240,80 @@ export class BootstrapMemories extends Resource {
             collision: [],
             events: [],
         };
-        let tokenBudget = maxTokens;
+        // flair#1207 — the content-SELECTION budget is `maxTokens`, matching 0.44.6
+        // capacity. #1199 pre-deducted a `structOverheadReserve` (min(600, 15% of
+        // maxTokens)) here to "reserve headroom" for the structured-container JSON
+        // scaffolding, on the theory that `maxTokens` should bound the serialized
+        // payload. That silently shrank the content budget and, combined with the
+        // per-item overhead (also removed), cut recall below 0.44.6 for the same
+        // `maxTokens` (#1207). The reserve is gone: `maxTokens` is the HARD cap on
+        // CONTENT SELECTION only. `tokenEstimate` (below) still reports the real
+        // serialized size honestly — which may exceed `maxTokens` by the scaffolding
+        // overhead, exactly as 0.44.6's payload did (0.44.6 just under-measured it).
+        // Single shared budget across soul + every memory section (soul used to be
+        // budgeted SEPARATELY and added ON TOP, so context alone could reach
+        // 1.4×maxTokens; #1199 folded soul into this shared budget — that part
+        // stays). Every admitted line is gated against the remaining budget, so the
+        // sum of selected CONTENT never exceeds `maxTokens`.
+        let tokenBudget = Math.max(0, maxTokens);
+        // Own memories included in the payload (permanent + recent + predicted +
+        // own task-relevant). Denominator is `memoriesAvailable` (own-scoped), so
+        // memoriesIncluded ≤ memoriesAvailable always holds (#1199 coherent
+        // counters). Cross-agent teammate findings are counted separately below.
         let memoriesIncluded = 0;
         let memoriesAvailable = 0;
         let memoriesTruncated = 0;
+        // flair#1199 — cross-agent teammate findings included (a DIFFERENT
+        // denominator than own memories): counting these into `memoriesIncluded`
+        // is what let one client see included(9) > available(3).
+        let teammateFindingsIncluded = 0;
+        // flair#1207 — teammate findings SKIPPED for size in the task-relevant
+        // packing loop. That loop `continue`s past an over-budget record silently;
+        // without a counter, a client can't tell "no relevant teammate finding" from
+        // "a relevant one existed but didn't fit the budget" (Sherlock's #1207
+        // self-describing-size-skip note; own-memory size-skips already increment
+        // `memoriesTruncated`, but that loop never did — now both do).
+        let teammateFindingsTruncated = 0;
         // flair#1182 (part 1) — self-describing bootstrap. These structured
         // container keys are ALWAYS emitted on the response (empty `{}`/`[]` when
         // the caller has nothing), so a client can tell an *empty* instance from
         // one that doesn't support these keys at all — and can read the caller's
         // own soul/memories as structured data instead of parsing the `context`
-        // markdown string. Scoped to the CALLER'S OWN records only
-        // (permanent/recent/relevant/predicted are all agentId==self reads);
-        // teammate findings stay in `context`/`sections.teammate` and are never
-        // duplicated here, so these containers carry no other agent's data.
+        // markdown string. `soul`/`memories`/`predicted` are scoped to the CALLER'S
+        // OWN records only (permanent/recent/relevant/predicted are all agentId==self
+        // reads). flair#1199 — cross-agent teammate findings now have their OWN
+        // structured container (`teammateFindings`, below), attributed via `source`,
+        // rather than living only in the prose `context` (which is opt-in as of
+        // #1199); the own-only containers still carry no other agent's data.
         const soulMap = {};
         const includedOwnMemories = [];
         const includedPredicted = [];
+        // flair#1199 — teammate (cross-agent) findings get their OWN structured
+        // container. Before #1199 they lived ONLY in the prose `context`; now that
+        // `context` is an opt-in mirror (default off on the /mcp path), they need a
+        // structured home so a connector that consumes the containers still sees
+        // them. Kept SEPARATE from `memories`/`predicted` (which stay own-only per
+        // the #1182 boundary) and clearly attributed via `source`.
+        const includedTeammateFindings = [];
+        // flair#1206 — org events get their OWN structured container. Before #1206
+        // they lived ONLY in the prose `context` string ("## Recent Org Events"),
+        // so at includeContext=false (the /mcp default) they were counted in
+        // `sections.events` and measured into `tokenEstimate` (when prose was on) but
+        // NEVER delivered in any field a connector could read — orphaned. Populated
+        // from the SAME deduped+sliced set the prose lines are (so count, charge and
+        // delivery all key off one thing), ALWAYS emitted (`[]` when none), and the
+        // targetIds relevance filter is already applied upstream (see the OrgEvent
+        // read below). Declared out here so it is in scope for the response body even
+        // if the events read (in a try/catch) yields nothing.
+        const includedEvents = [];
         const leanMemory = (m, section) => ({
             id: m.id,
             content: m.content,
             durability: m.durability ?? null,
             createdAt: m.createdAt ?? null,
+            // #1201 — the record's own last-write time, so a structured consumer can
+            // compute freshness off the same anchor the trust block's ageDays uses.
+            updatedAt: m.updatedAt ?? null,
             agentId: m.agentId ?? agentId,
             subject: m.subject ?? null,
             section,
@@ -257,12 +361,15 @@ export class BootstrapMemories extends Resource {
                     if (maxChars > 100) {
                         const truncated = `**${entry.key}:** ${entry.line.slice(entry.key.length + 6, entry.key.length + 6 + maxChars)}…(truncated)`;
                         sections.soul.push(truncated);
-                        soulTokens += estimateTokens(truncated);
+                        const cost = estimateTokens(truncated);
+                        soulTokens += cost;
+                        tokenBudget -= cost; // #1199 — soul draws from the shared budget
                     }
                     continue;
                 }
                 sections.soul.push(entry.line);
                 soulTokens += entry.tokens;
+                tokenBudget -= entry.tokens; // #1199 — soul draws from the shared budget
             }
         }
         // --- 1b. Skill assignments (ordered by priority, conflict detection) ---
@@ -388,14 +495,23 @@ export class BootstrapMemories extends Resource {
         // requested, so a non-trust bootstrap fetches (and returns) exactly what it
         // did before. These records are never returned raw when the block is off,
         // so widening the select cannot change the off-path response bytes.
+        // #1201 — `updatedAt` is projected on BOTH paths (not just the trust path):
+        // the structured `memories`/`predicted` containers carry it so a consumer
+        // can compute freshness, and the trust block's ageDays keys off it.
         const OWN_SELECT = includeTrust
-            ? ["id", "agentId", "content", "durability", "createdAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags", "provenance", "usageCount", "validFrom"]
-            : ["id", "agentId", "content", "durability", "createdAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags"];
+            ? ["id", "agentId", "content", "durability", "createdAt", "updatedAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags", "provenance", "usageCount", "validFrom"]
+            : ["id", "agentId", "content", "durability", "createdAt", "updatedAt", "supersedes", "subject", "validTo", "expiresAt", "_safetyFlags"];
         // flair#744 slice 1 — the Memory records that became visible lines in the
         // memory-bearing sections (permanent/recent/predicted/relevant/teammate),
         // collected as they're added so the opt-in `trust` array below can carry a
         // self-contained block per included memory. Stays empty (and unused) when
-        // includeTrust is off.
+        // includeTrust is off. flair#1201 — each entry carries the SECTION it landed
+        // in, so a trust entry's `matchQuality` is legible: null on a lifecycle
+        // section (permanent/recent/predicted — not a retrieval surface) reads as
+        // "not scored", not as a scoring failure, and a band on a retrieval section
+        // (relevant/teammate) is applied by the SAME rule to own and teammate
+        // records. Fixes the "own recent → null while teammate → strong looks like
+        // my own records scored worse" misread.
         const includedTrustMemories = [];
         // flair#744 slice 2 — the best absolute semantic similarity seen while
         // scoring the task-relevant candidate pool (section 4). Drives the opt-in
@@ -451,12 +567,12 @@ export class BootstrapMemories extends Resource {
         const permanent = permanentRows.filter((m) => !permanentSupersededIds.has(m.id));
         for (const m of permanent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line);
+            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
             if (cost <= tokenBudget) {
                 sections.permanent.push(line);
                 includedOwnMemories.push(leanMemory(m, "permanent"));
                 if (includeTrust)
-                    includedTrustMemories.push(m);
+                    includedTrustMemories.push({ m, section: "permanent" });
                 tokenBudget -= cost;
                 memoriesIncluded++;
             }
@@ -523,7 +639,7 @@ export class BootstrapMemories extends Resource {
         let recentSpent = 0;
         for (const m of recent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line);
+            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
             if (recentSpent + cost > recentBudget) {
                 memoriesTruncated++;
                 continue;
@@ -531,7 +647,7 @@ export class BootstrapMemories extends Resource {
             sections.recent.push(line);
             includedOwnMemories.push(leanMemory(m, "recent"));
             if (includeTrust)
-                includedTrustMemories.push(m);
+                includedTrustMemories.push({ m, section: "recent" });
             recentSpent += cost;
             tokenBudget -= cost;
             memoriesIncluded++;
@@ -566,7 +682,7 @@ export class BootstrapMemories extends Resource {
             let predictedSpent = 0;
             for (const m of subjectMemories) {
                 const line = formatMemory(m, agentId);
-                const cost = estimateTokens(line);
+                const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
                 if (predictedSpent + cost > predictedBudget) {
                     memoriesTruncated++;
                     continue;
@@ -574,7 +690,7 @@ export class BootstrapMemories extends Resource {
                 sections.predicted.push(line);
                 includedPredicted.push(leanMemory(m, "predicted"));
                 if (includeTrust)
-                    includedTrustMemories.push(m);
+                    includedTrustMemories.push({ m, section: "predicted" });
                 predictedSpent += cost;
                 tokenBudget -= cost;
                 memoriesIncluded++;
@@ -741,22 +857,52 @@ export class BootstrapMemories extends Resource {
                 // section double-spends.
                 for (const { memory: m } of scored) {
                     const line = formatMemory(m, agentId);
-                    const cost = estimateTokens(line);
-                    if (cost > tokenBudget)
+                    const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
+                    if (cost > tokenBudget) {
+                        // flair#1207 — a size-skip in the score-ordered task-relevant loop
+                        // is no longer silent: record it on the counter matching the record's
+                        // denominator (own → memoriesTruncated, teammate → the separate
+                        // teammateFindingsTruncated), so a client can distinguish "no relevant
+                        // finding" from "a relevant finding didn't fit the budget".
+                        if (m._source)
+                            teammateFindingsTruncated++;
+                        else
+                            memoriesTruncated++;
                         continue;
+                    }
                     if (m._source) {
                         sections.teammate.push(line);
+                        // flair#1199 — cross-agent teammate findings join their OWN
+                        // structured container (attributed via `source`), so a connector
+                        // consuming the containers still sees them when prose `context` is
+                        // off. Counted separately (teammateFindingsIncluded), NOT into
+                        // memoriesIncluded — that different-denominator mix is what let
+                        // included exceed available.
+                        includedTeammateFindings.push({
+                            id: m.id,
+                            content: m.content,
+                            durability: m.durability ?? null,
+                            createdAt: m.createdAt ?? null,
+                            updatedAt: m.updatedAt ?? null,
+                            subject: m.subject ?? null,
+                            source: m._source,
+                            section: "teammate",
+                        });
+                        if (includeTrust)
+                            includedTrustMemories.push({ m, section: "teammate" });
+                        tokenBudget -= cost;
+                        teammateFindingsIncluded++;
                     }
                     else {
                         sections.relevant.push(line);
                         // flair#1182 — own task-relevant records join the `memories`
-                        // container; teammate (`_source`) records stay in `context` only.
+                        // container.
                         includedOwnMemories.push(leanMemory(m, "relevant"));
+                        if (includeTrust)
+                            includedTrustMemories.push({ m, section: "relevant" });
+                        tokenBudget -= cost;
+                        memoriesIncluded++;
                     }
-                    if (includeTrust)
-                        includedTrustMemories.push(m);
-                    tokenBudget -= cost;
-                    memoriesIncluded++;
                 }
             }
         }
@@ -905,12 +1051,52 @@ export class BootstrapMemories extends Resource {
                     continue;
                 eventResults.push(event);
             }
-            eventResults.sort((a, b) => (a.createdAt || "").localeCompare(b.createdAt || ""));
-            for (const evt of eventResults.slice(0, 10)) {
+            // flair#1200 — collapse byte-identical duplicate events before rendering.
+            // The same logical event can land in the table more than once (a producer
+            // that double-fires, or the same broadcast emitted from two paths); each
+            // physical row has a distinct id/createdAt (OrgEvent.post keys the id off
+            // a millisecond timestamp), so they aren't caught by primary-key upsert
+            // and render as exact dupes. Org-event slots are scarce (10), so dedup
+            // BEFORE the slice — otherwise ~half the slots are wasted on duplicates.
+            // Keyed on the CONTENT (kind + summary + detail + targets), keeping the
+            // most-recent occurrence per signature.
+            const eventBySignature = new Map();
+            for (const evt of eventResults) {
+                const sig = JSON.stringify([
+                    evt.kind ?? "",
+                    evt.summary ?? "",
+                    evt.detail ?? "",
+                    Array.isArray(evt.targetIds) ? [...evt.targetIds].sort() : (evt.targetIds ?? null),
+                ]);
+                const prev = eventBySignature.get(sig);
+                if (!prev || (evt.createdAt || "") > (prev.createdAt || ""))
+                    eventBySignature.set(sig, evt);
+            }
+            const dedupedEvents = [...eventBySignature.values()]
+                .sort((a, b) => (a.createdAt || "").localeCompare(b.createdAt || ""));
+            for (const evt of dedupedEvents.slice(0, 10)) {
                 const elapsed = Date.now() - new Date(evt.createdAt).getTime();
                 const mins = Math.floor(elapsed / 60_000);
                 const relTime = mins < 60 ? `${mins}min ago` : `${Math.floor(mins / 60)}h ago`;
                 sections.events.push(`- ${evt.kind}: ${evt.summary} (${relTime})`);
+                // flair#1206 — the SAME deduped+sliced event, structured, so a connector
+                // reading the containers gets it when prose `context` is off (the /mcp
+                // default). Same set as the prose line ⇒ `sections.events` (the count),
+                // the `tokenEstimate` charge (this array is always in the body), and the
+                // delivery all key off one thing. Optional fields (detail/targetIds/scope)
+                // are omitted when absent so the object stays lean. The targetIds
+                // relevance filter and #1200 content-signature dedup were already applied
+                // upstream (eventResults → eventBySignature), so this is a pure move from
+                // prose to structured — no scope widening, no re-introduced duplicates.
+                includedEvents.push({
+                    id: evt.id,
+                    kind: evt.kind,
+                    summary: evt.summary,
+                    ...(evt.detail != null ? { detail: evt.detail } : {}),
+                    ...(Array.isArray(evt.targetIds) && evt.targetIds.length > 0 ? { targetIds: evt.targetIds } : {}),
+                    createdAt: evt.createdAt ?? null,
+                    ...(evt.scope != null ? { scope: evt.scope } : {}),
+                });
             }
         }
         catch {
@@ -959,9 +1145,27 @@ export class BootstrapMemories extends Resource {
         if (sections.events.length > 0) {
             parts.push("## Recent Org Events\n" + sections.events.join("\n"));
         }
-        const context = parts.join("\n\n");
+        const fullContext = parts.join("\n\n");
+        // flair#1199 — the structured containers are canonical; `context` is a prose
+        // MIRROR of the same bytes. When includeContext is off (the /mcp default),
+        // ship a compact structural pointer instead of re-embedding every body — so
+        // no field's bytes cross the wire twice. Always a string, so a client can
+        // still tell an empty instance from an unsupported one. When on, the prose
+        // is the full assembled context (the resource/REST/CLI behaviour, unchanged).
+        const context = includeContext
+            ? fullContext
+            : (fullContext.length === 0
+                ? ""
+                : `Structured payload in soul/memories/predicted/teammateFindings `
+                    + `(${memoriesIncluded} own + ${teammateFindingsIncluded} teammate memories, `
+                    + `${sections.soul.length} soul entries). Pass includeContext:true for the assembled prose context.`);
         const soulTokens = sections.soul.reduce((sum, line) => sum + estimateTokens(line), 0);
-        const memoryTokens = maxTokens - tokenBudget;
+        // #1199 — memory-line token spend (informational breakdown), independent of
+        // the reserve/soul now sharing the budget. Sum of the rendered memory lines.
+        const memoryTokens = [
+            ...sections.permanent, ...sections.recent, ...sections.predicted,
+            ...sections.relevant, ...sections.teammate,
+        ].reduce((sum, line) => sum + estimateTokens(line), 0);
         // flair#744 slice 1 — opt-in per-memory trust block. Bootstrap renders
         // memories as text lines rather than result objects, so the block is
         // surfaced as a `trust` array of self-contained entries (each carries its
@@ -969,9 +1173,12 @@ export class BootstrapMemories extends Resource {
         // HERE, in the response tail, strictly after all read-scope resolution and
         // purely for the response — never consulted for any authority decision
         // (#735-spirit zero-authority invariant). Default OFF ⇒ the `trust` key is
-        // absent ⇒ the response is byte-identical to pre-slice-1.
+        // absent ⇒ the response is byte-identical to pre-slice-1. flair#1201 — each
+        // entry carries its `section` so `matchQuality: null` on a lifecycle section
+        // reads as "not a retrieval surface", not as a scoring failure on the
+        // caller's own records.
         const trust = includeTrust
-            ? includedTrustMemories.map((m) => ({ id: m.id, ...buildTrustBlock(m) }))
+            ? includedTrustMemories.map(({ m, section }) => ({ id: m.id, section, ...buildTrustBlock(m) }))
             : undefined;
         // flair#744 slice 2 — opt-in abstention verdict for the task-relevance
         // surface. Present ONLY when `abstain` is requested (byte-identical to
@@ -1000,7 +1207,17 @@ export class BootstrapMemories extends Resource {
         const currentTaskHint = taskProvided
             ? undefined
             : "No currentTask was provided. Pass currentTask (a short description of what you're working on) to enable task-relevant memory retrieval, teammate findings, and collision surfacing.";
-        return {
+        // flair#1199 — when `subjects` were provided but nothing surfaced in
+        // `predicted`, say WHY (like currentTaskHint), so an empty `predicted: []`
+        // next to a non-empty `subjects` doesn't read as broken. Predicted fills
+        // from your OWN non-permanent memories whose `subject` matches one of the
+        // provided subjects; it stays empty until you've tagged memories that way.
+        const predictedHint = (predictedSubjects.length > 0 && includedPredicted.length === 0)
+            ? `No memories tagged with the requested subjects (${predictedSubjects.join(", ")}) were found. `
+                + `predicted surfaces your own non-permanent memories whose subject matches one of the provided `
+                + `subjects — it fills as you store memories tagged with these subjects.`
+            : undefined;
+        const responseBody = {
             context,
             // flair#1182 (part 1) — always-present self-describing keys: who the
             // server resolved the caller as, the read model applied, and the caller's
@@ -1011,7 +1228,19 @@ export class BootstrapMemories extends Resource {
             soul: soulMap,
             memories: includedOwnMemories,
             predicted: includedPredicted,
+            // flair#1199 — cross-agent teammate findings as a structured container
+            // (always present, `[]` when none), so a connector that consumes the
+            // containers still gets them when prose `context` is off.
+            teammateFindings: includedTeammateFindings,
+            // flair#1206 — org events as a structured container (always present, `[]`
+            // when none, same self-describing-empty-state pattern as the containers
+            // above). Before #1206 events lived ONLY in the prose `context`, so at the
+            // /mcp default (includeContext=false) they were counted+measured but never
+            // delivered. Deduped (#1200) and targetIds-scoped (same set as the prose
+            // "## Recent Org Events" lines), so count/charge/delivery all agree.
+            events: includedEvents,
             ...(currentTaskHint ? { currentTaskHint } : {}),
+            ...(predictedHint ? { predictedHint } : {}),
             ...(trust ? { trust } : {}),
             ...(abstention ? { abstention } : {}),
             sections: {
@@ -1027,12 +1256,36 @@ export class BootstrapMemories extends Resource {
                 collision: sections.collision.length,
                 events: sections.events.length,
             },
-            tokenEstimate: soulTokens + memoryTokens,
             soulTokens,
             memoryTokens,
+            // flair#1199 — own memories included (denominator: memoriesAvailable, also
+            // own-scoped), so memoriesIncluded ≤ memoriesAvailable always holds.
             memoriesIncluded,
             memoriesAvailable,
+            // Cross-agent teammate findings included — a SEPARATE denominator, labelled
+            // so it's never confused with the own-memory counters.
+            teammateFindingsIncluded,
             memoriesTruncated,
+            // flair#1207 — teammate findings skipped for size in the task-relevant loop
+            // (own size-skips there increment memoriesTruncated). Surfacing this makes
+            // a size-skip self-describing: "a relevant teammate finding didn't fit"
+            // is now distinguishable from "no relevant teammate finding".
+            teammateFindingsTruncated,
         };
+        // flair#1199 — tokenEstimate must reflect the ACTUAL serialized payload the
+        // caller receives (the structured containers included), not just the prose
+        // `context`. The old `soulTokens + memoryTokens` counted only the context
+        // string, so it under-reported by ~2× once the structured fields shipped
+        // alongside. Measured over the assembled body (the ~1-line tokenEstimate
+        // field it omits is negligible). flair#1207 CAP CONTRACT: this is an HONEST
+        // report of the real serialized size, NOT a value bounded by `maxTokens`.
+        // `maxTokens` is the hard cap on CONTENT SELECTION (the shared tokenBudget);
+        // the structured-container JSON scaffolding is genuine payload the caller
+        // pays for, so tokenEstimate MAY exceed `maxTokens` by that overhead. Do not
+        // "fix" an over-maxTokens tokenEstimate by shrinking selection — that is the
+        // exact #1199→#1207 regression (it dropped relevant findings). If the real
+        // payload consistently overruns for a use case, raise `maxTokens`.
+        const tokenEstimate = estimateTokens(JSON.stringify(responseBody));
+        return { ...responseBody, tokenEstimate };
     }
 }

package/dist/resources/mcp-tools.js

@@ -364,6 +364,13 @@ async function bootstrap(agent, args) {
         surface: args?.surface,
         subjects: args?.subjects,
         entities: args?.entities,
+        // flair#1199 — a /mcp connector consumes the STRUCTURED containers
+        // (soul/memories/predicted/teammateFindings), so the prose `context` mirror
+        // is OFF by default here: shipping both doubled the payload past maxTokens
+        // (the reported ~2× overrun). The resource itself defaults includeContext
+        // true (the REST/CLI prose path); this wrapper flips it for the connector,
+        // and forwards an explicit true when a caller wants the prose anyway.
+        includeContext: args?.includeContext === true,
     };
     // flair#744 slice 1 — opt-in per-memory trust block array. Forwarded ONLY
     // when requested so a plain bootstrap delegates a byte-identical body.
@@ -624,7 +631,7 @@ export const TOOLS = {
             inputSchema: {
                 type: "object",
                 properties: {
-                    maxTokens: { type: "number", description: "Max tokens in output (default 4000)" },
+                    maxTokens: { type: "number", description: "Content-selection budget in tokens (default 4000): the hard cap on how much soul/memory/finding CONTENT is selected. The actual serialized response (reported by tokenEstimate) may exceed this by the structured-container JSON scaffolding — maxTokens bounds what is selected, not the raw output size. Raise it to include more content." },
                     currentTask: { type: "string", description: "Current task — enables semantic search for relevant memories" },
                     channel: { type: "string", description: "Channel name (discord, tps-mail, claude-code)" },
                     surface: { type: "string", description: "Surface name (tps-build, tps-review, cli-session)" },
@@ -636,6 +643,7 @@ export const TOOLS = {
                     },
                     includeTrust: { type: "boolean", description: "Also return a `trust` array with a per-included-memory trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
                     abstain: { type: "boolean", description: "Opt into a task-relevance abstention verdict: also return an `abstention` object ({ abstained, bestScore, threshold }) reporting whether any memory covered `currentTask` above a global confidence threshold. Default false." },
+                    includeContext: { type: "boolean", description: "Also return the prose `context` string — a human-readable mirror of the structured soul/memories/predicted/teammateFindings containers (which are the canonical payload). Default false here: the structured fields already carry everything, so shipping the prose too would double the payload." },
                 },
             },
         },

package/dist/resources/trust-block.js

@@ -141,6 +141,7 @@ export function buildTrustBlock(record, now = Date.now()) {
     const validFrom = typeof record.validFrom === "string" ? record.validFrom : null;
     const validTo = typeof record.validTo === "string" ? record.validTo : null;
     const createdAt = typeof record.createdAt === "string" ? record.createdAt : null;
+    const updatedAt = typeof record.updatedAt === "string" ? record.updatedAt : null;
     const validToMs = parseTime(validTo);
     const validFromMs = parseTime(validFrom);
     let validityStatus = "valid";
@@ -150,10 +151,22 @@ export function buildTrustBlock(record, now = Date.now()) {
     else if (Number.isFinite(validFromMs) && validFromMs > now) {
         validityStatus = "future";
     }
-    const createdMs = parseTime(createdAt);
+    // flair#1201 (refined) — carry BOTH temporal signals rather than collapsing
+    // to one. `ageDays` is TRUE AGE (days since `createdAt`, fallback updatedAt);
+    // `staleDays` is FRESHNESS (days since `updatedAt`, fallback createdAt). The
+    // first #1201 pass keyed ageDays off updatedAt only, which overcorrected — a
+    // record created weeks ago but edited today then read as "0 days old", losing
+    // its true age. Both are the record's OWN fields (never a superseded
+    // predecessor's — #1189), so neither reintroduces lineage-inheritance. For a
+    // never-updated record updatedAt == createdAt, so ageDays == staleDays.
+    const createdMs = parseTime(createdAt ?? updatedAt);
     const ageDays = Number.isFinite(createdMs)
         ? Math.max(0, Math.floor((now - createdMs) / MS_PER_DAY))
         : null;
+    const updatedMs = parseTime(updatedAt ?? createdAt);
+    const staleDays = Number.isFinite(updatedMs)
+        ? Math.max(0, Math.floor((now - updatedMs) / MS_PER_DAY))
+        : null;
     return {
         author: typeof record.agentId === "string" ? record.agentId : null,
         provenanceStatus: verifiedAuthor ? "verified" : "unattributed",
@@ -165,7 +178,9 @@ export function buildTrustBlock(record, now = Date.now()) {
         validFrom,
         validTo,
         createdAt,
+        updatedAt,
         ageDays,
+        staleDays,
         supersedes: typeof record.supersedes === "string" ? record.supersedes : null,
         // flair#744 refinement — confidence band from the result's absolute
         // similarity (null when there is no signal to judge). Pure, global,

package/docs/integrations.md

@@ -15,6 +15,7 @@ Where Flair already runs. Each integration shown here is a working surface — t
 | **Continue.dev** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
 | **OpenAI Codex CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
 | **Gemini CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
+| **Antigravity CLI** (`agy`) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | `~/.gemini/config/mcp_config.json`; pickup by a live `agy` pending verification |
 | **Goose** (block/goose) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Goose ships native MCP support |
 | **LangGraph (TS)** | [`langgraph-flair`](#langgraph-typescript) | FlairClient | Drop-in `BaseStore` |
 | **OpenClaw** | [`openclaw-flair`](#openclaw) | Ed25519 | Native plugin + context engine |
@@ -69,6 +70,8 @@ FLAIR_AGENT_ID = "codex"
 
 **Gemini CLI** (`~/.gemini/settings.json`): same shape as Cursor.
 
+**Antigravity CLI** (`agy`) (`~/.gemini/config/mcp_config.json` — Antigravity's own MCP config, separate from Gemini CLI's `settings.json`): same shape as Cursor. Newly added; the config path follows Antigravity's documentation, but Flair has not yet verified end-to-end pickup by a live `agy` — after wiring, restart Antigravity and confirm the flair tools appear.
+
 **Continue.dev** (`~/.continue/config.json`):
 ```json
 {

package/package.json

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