@tpsdev-ai/flair 0.27.1 → 0.29.0

package/README.md

@@ -67,7 +67,7 @@ If you need any of those specifically, use them. If you need crypto-pinned ident
 
 Anthropic shipped [Claude Dreams](https://platform.claude.com/docs/en/managed-agents/dreams) (research preview, April 2026) — async pipeline that reads a memory store + session transcripts and produces a curated output store: duplicates merged, stale entries replaced, insights surfaced. Validates the category: agent memory accumulates drift and needs cleanup.
 
-Flair ships both the on-demand curation surface (`flair rem rapid`) AND the scheduled nightly cycle, per the [FLAIR-NIGHTLY-REM spec](specs/FLAIR-NIGHTLY-REM.md) and its [in-process distillation slice](specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md). Config recipe (Ollama zero-key default, hosted-provider egress warning, clustered-deploy rules): [`docs/rem.md`](docs/rem.md).
+Flair ships both the on-demand curation surface (`flair rem rapid`) AND the scheduled nightly cycle, per [`docs/rem.md`](docs/rem.md) and its [distillation UX design note](docs/notes/rem-ux.md). **REM requires a configured generative backend** (Ollama, OpenAI, Anthropic, etc.) — without one, `flair rem rapid` fails with `Reflection error: No generative backend configured`. Config recipe (Ollama zero-key default, hosted-provider egress warning, clustered-deploy rules): [`docs/rem.md`](docs/rem.md).
 
 - **`flair rem rapid`** — reflects and distills server-side by default, staging candidates in one bounded call. `--focus {lessons_learned, patterns, decisions, errors}` mirrors Dreams' `instructions` parameter. `--prompt-only` falls back to the bring-your-own-model handoff. Outputs *candidates*, not a wholesale store swap.
 - **`flair rem candidates` / `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id>`** — review and promote distilled candidates with required rationale.

package/dist/bridges/builtins/index.js

@@ -10,7 +10,7 @@
  * To add a new built-in:
  *   - YAML: write `src/bridges/builtins/<name>.ts` exporting a `YamlBridgeDescriptor`
  *   - Code plugin: write `src/bridges/builtins/<name>.ts` exporting a `MemoryBridge`
- *   Then register it here. See specs/FLAIR-BRIDGES.md §2 for shapes A/B.
+ *   Then register it here. See docs/bridges.md § Two shapes for shapes A/B.
  */
 import { agenticStackDescriptor } from "./agentic-stack.js";
 import { claudeProjectMemoryBridge } from "./claude-project.js";

package/dist/bridges/discover.js

@@ -1,6 +1,6 @@
 /**
  * Bridge discovery — scans the four conventional sources defined in
- * FLAIR-BRIDGES.md §7:
+ * docs/bridges.md § Discovery:
  *
  *   1. Project YAML:   <cwd>/.flair-bridge/*.yaml
  *   2. User YAML:      ~/.flair/bridges/*.yaml

package/dist/bridges/runtime/load-plugin.js

@@ -53,7 +53,7 @@ export async function loadCodePlugin(discovered, opts = {}) {
             field: "exports",
             expected: "named `bridge` export or default export implementing MemoryBridge",
             got: typeof mod === "object" && mod !== null ? `exports=${Object.keys(mod).join(",") || "(empty)"}` : typeof mod,
-            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See specs/FLAIR-BRIDGES.md §6`,
+            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See docs/bridges.md § Shape B`,
         });
     }
     // Validate the shape. Keep this minimal — we trust the plugin author

package/dist/bridges/scaffold.js

@@ -1,7 +1,7 @@
 /**
  * Bridge scaffolding — emits a working starter for a new bridge.
  *
- * From FLAIR-BRIDGES.md §2: "Scaffold & test in-tree. `flair bridge
+ * From docs/bridges.md § Two shapes: "Scaffold & test in-tree. `flair bridge
  * scaffold <name>` emits a working starter; `flair bridge test <name>`
  * runs a round-trip diff." This file handles the `scaffold` half.
  *
@@ -34,7 +34,7 @@ function fileDescriptorTemplate(name) {
 # Generated by \`flair bridge scaffold ${name} --file\`.
 # Edit to match your foreign system, then run \`flair bridge test ${name}\`.
 #
-# Spec: see FLAIR-BRIDGES.md §4 (memory schema) and §5 (YAML shape).
+# Spec: see docs/bridges.md § The memory record and § Shape A.
 name: ${name}
 version: 1
 kind: file
@@ -90,7 +90,7 @@ function apiIndexTemplate(name) {
  * flair-bridge-${name}
  *
  * Generated by \`flair bridge scaffold ${name} --api\`.
- * Spec: see FLAIR-BRIDGES.md §4 (memory schema) and §6 (code plugin shape).
+ * Spec: see docs/bridges.md § The memory record and § Shape B.
  *
  * After editing, run:
  *   flair bridge test ${name}

package/dist/bridges/types.js

@@ -1,7 +1,7 @@
 /**
  * Types for the Flair memory bridge plugin system.
  *
- * Mirrors the contract in specs/FLAIR-BRIDGES.md. These types are the
+ * Mirrors the contract in docs/bridges.md. These types are the
  * public surface a bridge author (human or agent) targets.
  *
  * IMPORTANT: the YAML bridge format (shape A) also conforms to these types

package/dist/cli.js

@@ -384,6 +384,33 @@ export function detectOpsApiAllInterfacesBind(portValue) {
     }
     return { allInterfaces: true, boundHost: null };
 }
+/**
+ * Decide the source `flair init` should use for the admin password when no
+ * explicit `--admin-pass` / `--admin-pass-file` / env var was given
+ * (flair#827).
+ *
+ * Before this existed, init ALWAYS generated a fresh random password and
+ * overwrote `~/.flair/admin-pass` on every run — including a re-run against
+ * an install that was already bootstrapped and working (e.g. following
+ * `flair doctor`'s ops-bind finding, whose only prescribed remedy is
+ * re-running `flair init`). Harper's `HDB_ADMIN_PASSWORD` env var only seeds
+ * a brand-new install's user record — it does NOT rotate an existing user's
+ * stored password hash on every boot. So overwriting the file desynced it
+ * from what Harper actually had persisted, and the very next ops-API call in
+ * that SAME init run (seeding the agent) failed with a 401 "Login failed",
+ * breaking working auth on an install that had nothing wrong with its
+ * credentials.
+ *
+ * An admin-pass file that already exists on disk IS the working install's
+ * password — `flair init` is the only thing that ever writes it — so reuse
+ * it instead of generating a new one. That makes re-init idempotent: safe to
+ * run again at any time without risking the instance's auth. Deliberately
+ * rotating the admin password is a separate operation, not a `flair init`
+ * side effect.
+ */
+export function resolveInitAdminPasswordSource(adminPassFileExists) {
+    return adminPassFileExists ? "reuse-existing" : "generate-new";
+}
 // ─── Ops-socket permission posture (flair#763) ─────────────────────────────────
 //
 // The ops API domain socket (dataDir/operations-server) is protected by a
@@ -1846,6 +1873,39 @@ const __pkgVersion = (() => {
         return "unknown";
     }
 })();
+/**
+ * The `@tpsdev-ai/flair-mcp` spec written into a client's MCP config.
+ *
+ * PINNED, deliberately. A bare `npx -y @tpsdev-ai/flair-mcp` re-resolves to
+ * whatever is currently published on EVERY agent session — so a single bad
+ * publish (stolen credentials, a malicious commit that clears review, or a
+ * compromised dependency of the MCP package) reaches every wired user
+ * silently, with no lockfile and no review step in the path. The postmark-mcp
+ * incident was exactly this shape: a legitimate publish by the legitimate
+ * owner, propagating for 16 days before anyone noticed. Worse, a yank does
+ * not help — unpinned clients keep resolving latest.
+ *
+ * Our publish side is already hardened (OIDC staged publish, human 2FA at the
+ * release gate), but that defends against credential theft, not against a bad
+ * version being published legitimately. The consumer side is where that gap
+ * closes, and pinning is what closes it: a wired client keeps running the
+ * exact version that was current when it was wired, and moving forward
+ * becomes a deliberate act.
+ *
+ * flair and flair-mcp ship in version lockstep from this monorepo, so the
+ * running CLI's own version is the correct pin. `flair init` re-run rewires
+ * to the then-current version; see the upgrade-rewire follow-up issue for
+ * making `flair upgrade` do the same.
+ *
+ * Falls back to the unpinned spec only when the version can't be read, which
+ * is the same condition under which `--version` reports "unknown" — a broken
+ * install, where a working MCP wiring matters more than a precise pin.
+ */
+export function mcpServerSpec(version = __pkgVersion) {
+    return version && version !== "unknown"
+        ? `@tpsdev-ai/flair-mcp@${version}`
+        : "@tpsdev-ai/flair-mcp";
+}
 const program = new Command();
 program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── CLI↔server version handshake (flair#695 §B) ────────────────────────────
@@ -2117,9 +2177,10 @@ program
         selectedClients.push(clientOpt);
     }
     // Admin password: determine from opts, env, or generate
-    // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
+    // Priority: 1) --admin-pass-file, 2) env vars, 3) reuse existing file, 4) generate new
     let adminPass;
     let passwordSource = "generated";
+    let reusedExistingAdminPass = false;
     // Warn if --admin-pass is passed inline (not from env)
     if (shouldShowInlineSecretWarning(opts.adminPass, false, new Set(["--admin-pass"]), "--admin-pass")) {
         console.error("warning: --admin-pass passed inline. Consider --admin-pass-file <path> or FLAIR_ADMIN_PASS env " +
@@ -2151,34 +2212,65 @@ program
         passwordSource = "env"; // Treat same as env for display purposes
     }
     else {
-        // Generate new password and write to file atomically
-        adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
-        passwordSource = "generated";
-        // Atomic write: create temp file in same dir, then rename
         const flairDir = join(homedir(), ".flair");
-        mkdirSync(flairDir, { recursive: true });
         const adminPassPath = join(flairDir, "admin-pass");
-        const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
-        const finalTempPath = join(tempPath, "admin-pass");
-        try {
-            writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
-            renameSync(finalTempPath, adminPassPath);
-            rmSync(tempPath, { recursive: true, force: true });
+        passwordSource = "generated";
+        if (resolveInitAdminPasswordSource(existsSync(adminPassPath)) === "reuse-existing") {
+            // flair#827: an admin-pass file already on disk means a PRIOR `flair
+            // init` already bootstrapped Harper's admin user with this password.
+            // HDB_ADMIN_PASSWORD only seeds a brand-new install — Harper does
+            // NOT rotate an existing user's stored password hash from env on
+            // every boot. Generating and overwriting the file here would desync
+            // it from what Harper actually has persisted, breaking ops-API auth
+            // (401 "Login failed") on THIS SAME init run (the agent-seeding call
+            // below) without fixing whatever the re-run was meant to fix — e.g.
+            // `flair doctor`'s ops-bind finding, whose only prescribed remedy is
+            // re-running `flair init`. Re-init must be idempotent here: reuse
+            // the existing password so it's always safe to re-run against a
+            // working install. Rotating the admin password on purpose is a
+            // separate, deliberate operation (see the ops runbook), not a side
+            // effect of re-init.
+            try {
+                adminPass = readAdminPassFileSecure(adminPassPath);
+            }
+            catch (err) {
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
+            }
+            reusedExistingAdminPass = true;
         }
-        catch (err) {
-            // Clean up temp dir on failure
+        else {
+            // Generate new password and write to file atomically
+            adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
+            // Atomic write: create temp file in same dir, then rename
+            mkdirSync(flairDir, { recursive: true });
+            const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
+            const finalTempPath = join(tempPath, "admin-pass");
             try {
+                writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
+                renameSync(finalTempPath, adminPassPath);
                 rmSync(tempPath, { recursive: true, force: true });
             }
-            catch { }
-            throw err;
+            catch (err) {
+                // Clean up temp dir on failure
+                try {
+                    rmSync(tempPath, { recursive: true, force: true });
+                }
+                catch { }
+                throw err;
+            }
         }
     }
     const adminUser = DEFAULT_ADMIN_USER;
-    // If we generated the password, report where it was saved
+    // If we generated (or reused) the password, report where it lives
     if (passwordSource === "generated") {
         const adminPassPath = join(homedir(), ".flair", "admin-pass");
-        console.log(`Admin password saved to: ${adminPassPath}`);
+        if (reusedExistingAdminPass) {
+            console.log(`Reusing existing admin password from: ${adminPassPath} (flair#827: re-init never rotates it — see the ops runbook to change it deliberately)`);
+        }
+        else {
+            console.log(`Admin password saved to: ${adminPassPath}`);
+        }
     }
     // Check Node.js version
     const major = parseInt(process.version.slice(1), 10);
@@ -2515,7 +2607,8 @@ program
         }
         // ── MCP client wiring ────────────────────────────────────────────────
         // The full one-command front door: detect installed MCP clients and wire
-        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp` server. Claude
+        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp@<version>` server
+        // (pinned — see mcpServerSpec()). Claude
         // Code is auto-wired into ~/.claude.json (the only client the CLI can
         // safely modify); other clients get copy-paste snippets. `--no-mcp`
         // skips wiring entirely; `--client <name>` targets one client; the
@@ -2551,7 +2644,7 @@ program
                     const flairMcpConfig = {
                         type: "stdio",
                         command: "npx",
-                        args: ["-y", "@tpsdev-ai/flair-mcp"],
+                        args: ["-y", mcpServerSpec()],
                         // flair#718 authorship-provenance: each client's wired env block
                         // gets its OWN FLAIR_CLIENT label (never the shared mcpEnv
                         // object directly — that would stamp the same label into every
@@ -2640,7 +2733,9 @@ program
         if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
             console.log("\n   Smoke-testing MCP server...");
             try {
-                const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
+                // Same spec that gets WIRED above — the smoke test must exercise the
+                // exact version the user will run, not whatever npm resolves latest to.
+                const mcpProc = spawn("npx", ["-y", mcpServerSpec()], {
                     env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
                     stdio: ["pipe", "pipe", "pipe"],
                 });
@@ -5863,8 +5958,7 @@ export function describeReflectError(message) {
     return { kind: "other", text: message };
 }
 // ─── flair rem rapid ──────────────────────────────────────────────────────────
-// Executes by default (specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3C,
-// issue #707): distills server-side via /ReflectMemories execute:true and
+// Executes by default (§3C, issue #707): distills server-side via /ReflectMemories execute:true and
 // stages MemoryCandidate rows, printing a staged-candidate summary. --prompt-only
 // preserves the pre-#710 handoff behavior byte-for-byte, for the bring-your-
 // own-model workflow.
@@ -8873,6 +8967,28 @@ program
     }
 });
 // ─── flair reembed ────────────────────────────────────────────────────────────
+//
+// ROOT-CAUSE GUARD — recall graph correctness (recall-hnsw-graph-heal).
+// `flair reembed` replaces the stored embedding of many rows IN PLACE (it
+// clears embedding/embeddingModel, then re-PUTs through Memory.put()'s regen
+// branch — the same bulk in-place re-embed path resources/migrations/
+// embedding-stamp.ts uses). Historically, an OLDER (pre-fix) Harper's
+// INCREMENTAL HNSW update left stale/asymmetric reverse edges under bulk
+// re-embed, which collapsed prod recall in July. That engine bug is FIXED in
+// the Harper this ships against (5.1.22) — its update path reconstructs the
+// prior vector and does the reverse-edge cleanup the old build skipped — so a
+// bulk re-embed no longer corrupts the graph. DEFENSE-IN-DEPTH RULE (a
+// prudent, version-independent default, not a workaround for a live bug): pair
+// any BULK re-embed with a structural graph REBUILD trigger rather than relying
+// on incremental HNSW updates to converge (today: the
+// `@indexed(type:"HNSW", M:16)` descriptor bump in schemas/memory.graphql,
+// which makes Harper clear + rebuild the graph cleanly from the stored vectors
+// on the next boot — see resources/migrations/graph-heal.ts). Do NOT use
+// resources/MemoryReindex.ts's `_reindex` for graph correctness (it re-PUTs the
+// same vector through the incremental path and rebuilds nothing). If a `flair
+// reembed` run ever materially changes the vector space (e.g. a model swap),
+// follow it with a deploy that trips the structural reindex (bump the HNSW
+// descriptor / restart after a schema change).
 program
     .command("reembed")
     .description("Re-generate embeddings for memories with stale or missing model tags")
@@ -9685,7 +9801,13 @@ program
     // 3b. Ops API bind (flair#670) — report-only finding, never auto-fixed.
     // Rebinding the ops API requires a Harper restart to take effect, so
     // `doctor --fix` deliberately does not touch it here; the fix is
-    // `flair init` (re-run) or a manual harper-config.yaml edit + restart.
+    // `flair init` (re-run, then `flair restart` to apply it) or a manual
+    // harper-config.yaml edit + restart. flair#827: re-running `flair init`
+    // used to regenerate ~/.flair/admin-pass unconditionally, desyncing it
+    // from Harper's already-persisted credential and breaking admin auth on
+    // the very re-run this remedy prescribed — resolveInitAdminPasswordSource
+    // (see its doc comment) now reuses the existing password instead, so this
+    // remedy is safe to follow on a working install.
     try {
         const harperConfigPath = join(defaultDataDir(), "harper-config.yaml");
         if (existsSync(harperConfigPath)) {
@@ -9694,7 +9816,7 @@ program
             const bind = detectOpsApiAllInterfacesBind(opsPortValue);
             if (bind.allInterfaces) {
                 console.log(`  ${render.icons.error} Ops API bound to ${render.wrap(render.c.bold, "all interfaces")} (${render.wrap(render.c.dim, String(opsPortValue))})`);
-                console.log(`     ${render.wrap(render.c.dim, "Single-host installs don't need this reachable off-box. Fix:")} flair init ${render.wrap(render.c.dim, "(rebinds to loopback + domain socket on next start; pass --ops-bind for deliberate remote admin)")}`);
+                console.log(`     ${render.wrap(render.c.dim, "Single-host installs don't need this reachable off-box. Fix:")} flair init && flair restart ${render.wrap(render.c.dim, "(rebinds to loopback + domain socket; re-init reuses your existing admin password, so this is safe on a running install — pass --ops-bind for deliberate remote admin)")}`);
                 issues++;
             }
         }
@@ -12060,7 +12182,7 @@ soul.command("list")
 // Slice 1: discovery + scaffold. Slice 2: YAML runtime + `import` for Shape A
 // + agentic-stack reference adapter as a built-in.
 // `test` and `export` are still stubbed; Shape B (npm code plugins) too.
-// See specs/FLAIR-BRIDGES.md.
+// See docs/bridges.md.
 const bridge = program.command("bridge").description("Manage memory bridges (import/export between Flair and foreign systems)");
 bridge
     .command("list")

package/dist/rem/runner.js

@@ -20,8 +20,8 @@
  *   - Steps 1, 2 shipped in slice-1 PR-1 (#414).
  *   - Step 3 (maintenance) shipped in a prior slice-2 PR — fills
  *     `archived`/`expired` in the audit row.
- *   - Step 4: per specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3B,
- *     "Deferred from parent § 4 step 4" — trust tiers aren't derivable yet
+ *   - Step 4: per §3B (issue #707), "Deferred from parent § 4 step 4" —
+ *     trust tiers aren't derivable yet
  *     (that's the emergent-trust arc). The input filter stays as today (own
  *     agent, non-archived, non-permanent, scope window); the safety net for
  *     un-tiered input is structural — candidates are staged, never

package/dist/resources/MemoryReflect.js

@@ -5,7 +5,7 @@
  * reflection prompt for a human/agent to run through their own LLM, or (b)
  * with execute:true, runs the distillation server-side via Harper's models
  * facade and stages the results as MemoryCandidate rows for review. See
- * specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md §3A (issue #707).
+ * issue #707 (§3A).
  *
  * Request:
  *   agentId      string   — which agent to reflect on

package/dist/resources/RecordUsage.js

@@ -34,6 +34,17 @@
  * (and its ownership gate) — its own auth model is verified-agent +
  * within-org + explicitly NO ownership requirement.
  *
+ * NO READ-SCOPE GATE — INTENTIONAL ASYMMETRY with citation-on-write
+ * (flair#775): this endpoint deliberately does NOT validate reported ids
+ * against the caller's read scope. Usage feedback is the cross-agent
+ * contract described above (agent B reports using agent A's memory
+ * regardless of A's visibility setting), and the no-enumeration response
+ * below already denies existence probing on this surface. Citation-on-write
+ * (./usage-recording.ts's recordCitations()) DOES scope-gate each cited id —
+ * it is a separate write surface with a narrower threat model; see that
+ * module's doc. Do not "unify" the two: the difference is a K&S binding
+ * condition on the flair#775 locked design, not drift.
+ *
  * WHY THIS ISN'T A @table-BACKED RESOURCE: the actual dedup ledger (one row
  * per (agentId, memoryId) contribution) lives in the `MemoryUsage` table
  * (schemas/memory.graphql), guarded by resources/MemoryUsage.ts. But this
@@ -164,7 +175,10 @@ export class RecordUsage extends Resource {
                 // ./usage-recording.ts's recordUsageContribution() — a shared,
                 // single-implementation extraction (also used by citation-on-write,
                 // resources/Memory.ts's post()/put()). Byte-identical behavior to
-                // the former private _recordOne() this replaced.
+                // the former private _recordOne() this replaced. Deliberately NO
+                // read-scope check on memoryId here (flair#775 asymmetry — see the
+                // module doc's NO READ-SCOPE GATE paragraph; citation-on-write's
+                // recordCitations() is the surface that scope-gates).
                 await recordUsageContribution(ctx, agentId, memoryId, attribution, now);
             }
             catch (err) {

package/dist/resources/embeddings-provider.js

@@ -107,9 +107,6 @@
  * still a separate, deliberate step from shipping this code — see the PR
  * description for that distinction.
  */
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 const VALID_INPUT_TYPES = new Set(["document", "query"]);
 /**
  * THE GATE (flair#504 Phase 2 — flipped ON). A module-level constant, not an
@@ -239,42 +236,15 @@ async function getModelsApi() {
 /**
  * Resolve the directory the embeddings model lives in / downloads into.
  *
- * Resolution order (everything writable, never the read-only package dir):
- *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
- *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
- *                                ~/.flair/data when it spawns Harper). User-
- *                                owned and writable even on sudo-global installs.
- *   3. <cwd>/models            — ONLY if a model already lives there. Backward
- *                                compat for existing writable installs that
- *                                downloaded into the package dir before this fix;
- *                                never used as a download target on fresh installs.
- *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
- *
- * The chosen dir is always writable, so the embeddings engine can download the
- * model on first use without hitting EACCES on a root-owned package dir.
- *
- * Called by `resources/embeddings-boot.ts` (flair#694) to build the
- * `modelsDir` it passes to harper-fabric-embeddings' `register()` — both run
- * in the SAME process now (unlike the retired src/cli.ts-side computation,
- * which duplicated this exact default because it ran in a separate process
- * that set the resulting value via an env var). Still exported and tested
- * independently (test/unit/embeddings-models-dir.test.ts) as the single
- * documented source of truth for this default.
+ * Implementation moved to `resources/models-dir.ts` (flair#815) so the
+ * reranker can share the exact same resolution without importing this module
+ * (several unit-isolated tests `mock.module()` this file wholesale — see
+ * models-dir.ts's header). Re-exported here so existing consumers keep their
+ * import site: `resources/embeddings-boot.ts` (flair#694), which builds the
+ * `modelsDir` it passes to harper-fabric-embeddings' `register()`, and
+ * test/unit/embeddings-models-dir.test.ts, which pins the resolution order.
  */
-export function resolveModelsDir() {
-    const override = process.env.FLAIR_MODELS_DIR;
-    if (override)
-        return override;
-    const rootPath = process.env.ROOTPATH;
-    if (rootPath)
-        return join(rootPath, "models");
-    // Backward compat: a prior (writable) install may have the model cached in
-    // the package dir. Reuse it rather than re-downloading — but only if present.
-    const cwdModels = join(process.cwd(), "models");
-    if (existsSync(cwdModels))
-        return cwdModels;
-    return join(homedir(), ".flair", "data", "models");
-}
+export { resolveModelsDir } from "./models-dir.js";
 // Kern: "Boot probe MUST have a 5-10s timeout ... on timeout set mode='none'
 // + log a warning. A hung probe ... must never block Harper boot."
 const PROBE_TIMEOUT_MS = 8_000;

package/dist/resources/mcp-tools.js

@@ -35,6 +35,7 @@
  * version bump + a new FlairClient method, out of scope for this query-only
  * slice.
  */
+import { resolveVersion } from "./version.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -248,7 +249,14 @@ async function bootstrap(agent, args) {
     // ONLY when requested so a plain bootstrap delegates a byte-identical body.
     if (args?.abstain === true)
         body.abstain = true;
-    return unwrap(await h.post(body));
+    // flair#831 — attach the running Flair version to the RESPONSE (not the
+    // delegated request body) so the calling agent learns the server version
+    // on its very first call.
+    const result = unwrap(await h.post(body));
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ...result, flairVersion: resolveVersion() };
+    }
+    return result;
 }
 async function soulSet(agent, args) {
     const Cls = await handler("Soul");

package/dist/resources/memory-reflect-lib.js

@@ -1,6 +1,6 @@
 // ─── Memory Reflection — pure logic for /ReflectMemories ────────────────────
 // Pure helpers backing resources/MemoryReflect.ts (FLAIR-NIGHTLY-REM slice 2,
-// §3A — see specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md, issue #707).
+// §3A — see issue #707).
 //
 // Same split as resources/memory-consolidate-lib.ts: importing MemoryReflect.ts
 // pulls in the Harper runtime (`databases`/`Resource`/`models`, storage init),

package/dist/resources/migrations/embedding-stamp.js

@@ -101,6 +101,29 @@
  * OTHER, not-yet-understood counting artifact; this lets the runner PROVE
  * (via `.get()`, a primary-key lookup — always live, never index-assisted)
  * that a nonzero countPending() result is real before halting on it.
+ *
+ * ROOT-CAUSE GUARD — recall graph correctness (recall-hnsw-graph-heal).
+ * This migration RE-EMBEDS rows in BULK via `PUT /Memory/:id` — it replaces
+ * the stored vector of many rows in place. Historically, an OLDER (pre-fix)
+ * Harper's INCREMENTAL HNSW update left stale/asymmetric reverse edges under
+ * exactly this kind of bulk re-embed (order-dependent), which collapsed prod
+ * recall (p@3 0.25) in July. That engine bug is FIXED in the Harper this ships
+ * against (5.1.22): its index() reconstructs the prior vector from the stored
+ * node and carries the node's real connections into the reverse-edge cleanup
+ * the old build skipped, so a bulk re-embed no longer corrupts the graph.
+ * DEFENSE-IN-DEPTH RULE (a prudent, version-independent default — not a
+ * workaround for a live bug): pair any BULK re-embed with a structural graph
+ * REBUILD trigger rather than relying on incremental HNSW updates to converge
+ * — it keeps recall correct regardless of engine version, closes the rare
+ * decode-failure edge case, and heals a graph already corrupted on disk by an
+ * older engine. Do NOT reach for resources/MemoryReindex.ts's `_reindex` for
+ * graph correctness (it re-PUTs the same vector through the incremental path
+ * and rebuilds nothing). The lever flair uses is a structural schema-descriptor
+ * change: the `@indexed(type:"HNSW", M:16)` bump in schemas/memory.graphql
+ * ships alongside this migration precisely so a graph corrupted under an older
+ * engine is rebuilt on the upgrade boot (observed/ledgered by
+ * resources/migrations/graph-heal.ts). Before enabling any FUTURE bulk
+ * re-embed, ship a structural reindex trigger with it.
  */
 import { databases } from "@harperfast/harper";
 import { getModelId } from "../embeddings-provider.js";