@tpsdev-ai/flair 0.44.13 → 0.45.0

package/dist/cli.js

@@ -3743,6 +3743,7 @@ agent
     .option("--name <name>", "Display name (defaults to id)")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password for registration")
+    .option("--admin-pass-file <path>", "Read the admin password from a file (chmod 600 enforced). Preferred over inline --admin-pass — keeps the secret out of ps and shell history; works for remote targets too (an explicit flag is operator intent).")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair REST URL; derives the ops API URL (port-1) to seed the Agent there (env: FLAIR_TARGET)")
@@ -3759,6 +3760,22 @@ agent
     // `flair import`: explicit --ops-target > derive from --target > localhost.
     const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.target, opsTarget: opts.opsTarget }) ?? opsPort;
     const isRemoteTarget = typeof seedOpsTarget === "string";
+    // flair#1259 — --admin-pass-file resolves into the same explicit slot the
+    // inline flag uses (same shape as `flair federation sync`), read in-process
+    // via readAdminPassFileSecure so the secret never appears in ps or shell
+    // history. This does NOT weaken the #1085 remote guard below: an explicit
+    // flag naming a file IS operator intent toward this target, exactly like an
+    // explicit inline --admin-pass — what the guard blocks is the AMBIENT
+    // env/local-file fallbacks silently traveling to a third-party host.
+    if (!opts.adminPass && opts.adminPassFile) {
+        try {
+            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
+        }
+        catch (err) {
+            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
+            process.exit(1);
+        }
+    }
     // #590 — local convenience fallback: FLAIR_ADMIN_PASS env, then the secure
     // ~/.flair/admin-pass file `flair init` already writes (mode 0600). Never
     // applied for a remote target — see resolveLocalAdminPass.
@@ -3772,12 +3789,13 @@ agent
     }
     if (!adminPass) {
         if (isRemoteTarget) {
-            console.error("Error: --admin-pass is required for agent add when targeting a remote instance " +
-                "(--target/--ops-target) — the local ~/.flair/admin-pass fallback is not used for remote targets.");
+            console.error("Error: --admin-pass <pass> or --admin-pass-file <path> is required for agent add when targeting " +
+                "a remote instance (--target/--ops-target) — the local ~/.flair/admin-pass and FLAIR_ADMIN_PASS " +
+                "fallbacks are never used for remote targets. Prefer --admin-pass-file: it keeps the secret out of ps.");
         }
         else {
-            console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table). " +
-                "Set FLAIR_ADMIN_PASS, or make sure ~/.flair/admin-pass exists (created by `flair init`).");
+            console.error("Error: --admin-pass <pass> or --admin-pass-file <path> is required for agent add (needed to insert " +
+                "into Agent table). Set FLAIR_ADMIN_PASS, or make sure ~/.flair/admin-pass exists (created by `flair init`).");
         }
         process.exit(1);
     }
@@ -13891,18 +13909,26 @@ sessionSnapshot
         console.error(`  Pass --target <new-path> or remove the existing dir.`);
         process.exit(1);
     }
+    // flair#903 — fail CLOSED on a tampered archive. node-tar's defaults below
+    // do contain malicious entries (leading "/" stripped, ".." entries
+    // dropped, no writing through a symlink — verified on the pinned tar
+    // against all four vectors), but they discard those entries SILENTLY: the
+    // restore printed the target dir as a plain success minus the parts it
+    // never mentioned. Validation runs BEFORE the target directory is even
+    // created — a tampered snapshot aborts the whole restore, names the
+    // offending entry, and writes nothing (same posture as the data-dir
+    // restore's extractSnapshotSafely). The default extract flags stay as
+    // containment defense-in-depth — deliberately NOT preservePaths; if that
+    // flag is ever added here, this call MUST move to extractSnapshotSafely.
+    // See src/lib/safe-snapshot-extract.ts.
+    try {
+        await validateSnapshotArchive({ file: snapshotPath, targetDir });
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     mkdirSync(targetDir, { recursive: true, mode: 0o700 });
-    // Deliberately NOT preservePaths, and deliberately NOT routed through
-    // extractSnapshotSafely. --snapshot is an operator-supplied path, so
-    // provenance here is no more controlled than the data-dir restore's — the
-    // difference is the flag, not the trust. node-tar's defaults keep their
-    // own containment: leading "/" stripped from entry paths, ".." entries
-    // dropped, and no writing through a symlink (including one created
-    // earlier in the same archive). Verified against the pinned tar (7.5.20)
-    // on all four cases, each contained, with a benign control entry landing
-    // to prove the archives parsed. Add `preservePaths` here and that
-    // containment disappears — this call would then need extractSnapshotSafely,
-    // exactly as the data-dir restore does. See src/lib/safe-snapshot-extract.ts.
     await tarExtract({ file: snapshotPath, cwd: targetDir });
     console.log(targetDir);
     console.error(`  extracted to: ${targetDir}`);

package/dist/lib/safe-snapshot-extract.js

@@ -68,6 +68,18 @@ function hasDotDotSegment(p) {
  * `linkpath` is the entry's link target, when it has one.
  */
 export function checkSnapshotEntry(entryPath, type, linkpath, resolvedTargetDir) {
+    // flair#901 fail-closed shape checks: an entry this check cannot READ is an
+    // entry it must not PASS. An empty path used to resolve to the target dir
+    // itself (inside, so ok), and a link entry with no linkpath skipped the
+    // link branches entirely — both silently approved exactly when the input
+    // was least trustworthy (tampered archive, or an upstream property rename
+    // surviving to runtime).
+    if (!entryPath) {
+        return { ok: false, reason: "entry has an empty or unreadable path — refusing an entry this check cannot classify" };
+    }
+    if ((type === "Link" || type === "SymbolicLink") && !linkpath) {
+        return { ok: false, reason: `${type === "Link" ? "hard link" : "symlink"} "${entryPath}" has no readable link target — refusing an entry this check cannot classify` };
+    }
     if (looksAbsolute(entryPath)) {
         return { ok: false, reason: `entry has an absolute path ("${entryPath}"), which would write outside the target directory` };
     }
@@ -154,14 +166,20 @@ export async function validateSnapshotArchive(opts) {
     const violations = [];
     await tarList({
         file: opts.file,
+        // Typed against tar's ReadEntry (flair#901) — a property rename upstream
+        // now fails compilation instead of coercing to ""/undefined at runtime.
+        // The coercions below remain as the runtime belt, and they no longer
+        // default to safe: checkSnapshotEntry refuses an empty path and a
+        // link-typed entry with no link target.
         onReadEntry: (entry) => {
-            const verdict = checkSnapshotEntry(String(entry.path ?? ""), entry.type, entry.linkpath ? String(entry.linkpath) : undefined, resolvedTargetDir);
+            const entryPath = typeof entry.path === "string" ? entry.path : "";
+            const verdict = checkSnapshotEntry(entryPath, entry.type, typeof entry.linkpath === "string" && entry.linkpath !== "" ? entry.linkpath : undefined, resolvedTargetDir);
             // `verdict.ok === false` rather than `!verdict.ok`: an explicit
             // comparison against the literal discriminant is what narrows the union
             // to its failure member, so `reason` is known to exist here. The union
             // is deliberately shaped so a caller cannot read a reason off a success.
             if (verdict.ok === false) {
-                violations.push({ entryPath: String(entry.path ?? ""), reason: verdict.reason });
+                violations.push({ entryPath, reason: verdict.reason });
             }
         },
     });

package/dist/rem/snapshot.js

@@ -20,6 +20,7 @@ import { mkdirSync, writeFileSync, statSync, chmodSync, rmSync, existsSync, read
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
+import { validateSnapshotArchive } from "../lib/safe-snapshot-extract.js";
 export const SNAPSHOT_ROOT = resolve(homedir(), ".flair", "snapshots");
 /** Validates the agent id and returns its snapshot directory. */
 export function remSnapshotDir(agent) {
@@ -133,20 +134,20 @@ export async function extractSnapshot(opts) {
     if (existsSync(targetDir)) {
         throw new Error(`target directory already exists: ${targetDir}`);
     }
+    // flair#903 — fail CLOSED on a tampered archive. node-tar's defaults below
+    // do contain malicious entries (leading "/" stripped, ".." entries dropped,
+    // no writing through symlinks — verified on the pinned tar against all four
+    // vectors), but they discard those entries SILENTLY: the restore reported
+    // success minus the parts it never mentioned, and the operator held a
+    // partial restore they believed was complete. Validation runs BEFORE the
+    // target directory is even created: a tampered snapshot aborts the whole
+    // restore, names the offending entry, and writes nothing (same posture as
+    // the data-dir restore's extractSnapshotSafely). The default extract flags
+    // are kept as containment defense-in-depth — deliberately NOT
+    // preservePaths; if that flag is ever added here, this call MUST move to
+    // extractSnapshotSafely (see src/lib/safe-snapshot-extract.ts).
+    await validateSnapshotArchive({ file: opts.snapshotPath, targetDir });
     mkdirSync(targetDir, { recursive: true, mode: 0o700 });
-    // Deliberately NOT preservePaths, and deliberately NOT routed through
-    // src/lib/safe-snapshot-extract.ts. The snapshot path comes from the
-    // operator, so provenance here is no more controlled than the data-dir
-    // restore's — the difference is the flag, not the trust. With node-tar's
-    // defaults its own containment applies: it strips a leading "/" from entry
-    // paths, drops ".." entries, and refuses to write through a symlink,
-    // including one created earlier in the same archive. Verified against the
-    // pinned tar (7.5.20) on all four cases — absolute path, ".." traversal,
-    // in-archive symlink, pre-existing symlink in the target — each contained,
-    // with a benign control entry landing to prove the archives were valid.
-    // If `preservePaths` is ever added here, that containment is gone and this
-    // call MUST move to extractSnapshotSafely, which is why the data-dir
-    // restore needs the wrapper and this does not.
     await tarExtract({ file: opts.snapshotPath, cwd: targetDir });
     return { targetDir, entries };
 }

package/dist/resources/Memory.js

@@ -6,7 +6,7 @@ import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
-import { assertValidVisibility } from "./memory-visibility.js";
+import { assertValidVisibility, assertVisibilityAllowedForDurability } from "./memory-visibility.js";
 import { assertValidDurability } from "./memory-durability.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeScopedSearch, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
@@ -641,6 +641,20 @@ export class Memory extends databases.flair.Memory {
                 return new Response(JSON.stringify({ error: "invalid_visibility", message: visibilityError }), { status: 400, headers: { "content-type": "application/json" } });
             }
         }
+        // ── flair#1257: ephemeral memories are private-only (hard precondition) ──
+        // The durability-keyed default below sends ephemeral to "private", but a
+        // default is not a constraint — an explicit visibility:"shared" here would
+        // make continuity-journal entries org-readable AND federation-pushed.
+        // Refused at the server so the boundary holds for every caller, not just
+        // the hooks that promise to send "private". content.durability is already
+        // defaulted ("standard" when absent) and enum-validated above, so this
+        // sees the row's effective durability.
+        {
+            const tierError = assertVisibilityAllowedForDurability(content.durability, content.visibility);
+            if (tierError) {
+                return new Response(JSON.stringify({ error: "invalid_visibility_for_durability", message: tierError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         if (content.visibility === undefined || content.visibility === null) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }
@@ -853,6 +867,23 @@ export class Memory extends databases.flair.Memory {
                 return new Response(JSON.stringify({ error: "invalid_visibility", message: visibilityError }), { status: 400, headers: { "content-type": "application/json" } });
             }
         }
+        // ── flair#1257: ephemeral memories are private-only (hard precondition) ──
+        // Same rule as post(), with one PUT-specific wrinkle: an update payload
+        // may omit durability entirely (put() stamps no durability default), so
+        // `PUT /Memory/<id> {"visibility":"shared"}` against a stored ephemeral
+        // row names no durability of its own — the EFFECTIVE durability is the
+        // pre-existing row's, and the flip must refuse just like a fresh
+        // ephemeral+shared create. An explicit durability on the write wins: a
+        // write that promotes the row OUT of ephemeral (e.g. distillation lifting
+        // it to persistent, #1205) while sharing it is a legitimate promotion,
+        // not an ephemeral share. preExisting was fetched above.
+        {
+            const effectiveDurability = content.durability ?? preExisting?.durability;
+            const tierError = assertVisibilityAllowedForDurability(effectiveDurability, content.visibility);
+            if (tierError) {
+                return new Response(JSON.stringify({ error: "invalid_visibility_for_durability", message: tierError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         if (!preExisting && (content.visibility === undefined || content.visibility === null)) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }

package/dist/resources/MemoryBootstrap.js

@@ -15,6 +15,7 @@ import { buildCollisionEntries, buildEntityMatchCondition, freshPresenceByAgent,
 // retrievalCount hit-tracking side effects (see resources/
 // semantic-retrieval-core.ts's module doc for the full boundary).
 import { retrieveCandidates, DEFAULT_SELECT } from "./semantic-retrieval-core.js";
+import { hybridEnabled } from "./bm25.js";
 import { buildTrustBlock } from "./trust-block.js";
 import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
 import { estimateTokens } from "./token-estimate.js";
@@ -51,8 +52,9 @@ import { estimateTokens } from "./token-estimate.js";
  *      (no new embedding code — Memory is the semantic surface, WorkspaceState/
  *      OrgEvent are the entity surface, per the K&S verdict). Gated on
  *      freshness (Presence, via the SAME internal roster path, never the raw
- *      table) and #550's existing relevance floor. See resources/
- *      collision-lib.ts for the pure join/rank/format logic.
+ *      table); drawn from #550's fused-rank scored pool (flair#1246 — no
+ *      relevance floor). See resources/collision-lib.ts for the pure
+ *      join/rank/format logic.
  *
  * Prediction: when context signals (channel, surface, subjects) are provided,
  * the bootstrap loads more aggressively — Flair is fast enough that the
@@ -128,9 +130,12 @@ import { estimateTokens } from "./token-estimate.js";
  *   memoriesAvailable` — included and truncated are disjoint sets of UNIQUE own
  *   memories (a memory budget-skipped in one section but admitted in another counts
  *   as included, never both). `teammateFindingsMatched` is the teammate match pool
- *   that cleared the relevance floor; `teammateFindingsIncluded +
- *   teammateFindingsTruncated == teammateFindingsMatched`, so "truncated" means
- *   "relevant but no budget," not "every candidate not selected."
+ *   that entered the scored candidate set — since flair#1246 that is the
+ *   K-bounded fused-rank retrieval pool (no relevance floor; the historical
+ *   `_score > 0.3` gate was measured inert and removed); `teammateFindingsIncluded
+ *   + teammateFindingsTruncated == teammateFindingsMatched` (the #1199 contract,
+ *   unchanged), so "truncated" means "retrieved but no budget," not "every
+ *   candidate not selected."
  *   `predictedHint` is present only when subjects were provided but `predicted`
  *   came back empty.
  */
@@ -204,10 +209,18 @@ const OWN_NONPERMANENT_FETCH_LIMIT = 500;
 const AVG_LINE_TOKEN_ESTIMATE = 60;
 const MIN_CANDIDATE_POOL = 50;
 const MAX_CANDIDATE_POOL = 100;
-// Bootstrap's own historical relevance floor (distinct from SemanticSearch's
-// `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#1246 — the historical TASK_RELEVANCE_FLOOR (`_score > 0.3`, carried
+// verbatim from the original raw JS dot-product scan) is REMOVED, not
+// recalibrated: a 6-variant measurement on the shipped embedding model proved
+// it inert (126 records across field-analog/nonce/contamination/control/
+// max-dilution/scattered-senses shapes — nothing scored under ~0.44, so the
+// floor cut zero records and never delivered "show nothing when nothing's
+// relevant" either; fully-unrelated bland noise sits 0.44–0.63). Selection on
+// the task-relevant surface is fused retrieval rank + the token budget. Do
+// not reintroduce a constant floor — an absolute bar tight enough to exclude
+// bland noise (max-dilution noise cosine 0.6086) also excludes the
+// pathological on-task case (0.5656); a real relevance gate would need a
+// corpus-relative instrument, which is a new feature, not a constant.
 // 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
@@ -364,9 +377,10 @@ export class BootstrapMemories extends Resource {
         // 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 (cleared the relevance floor but didn't fit the BUDGET).
-        // Reported ALONGSIDE `teammateFindingsMatched` (the whole floor-clearing pool
-        // considered), so "truncated" unambiguously means "relevant-but-no-budget",
+        // packing loop (entered the scored retrieval pool but didn't fit the
+        // BUDGET; flair#1246 — the pool is the K-bounded fused-rank candidate
+        // set, no relevance floor). Reported ALONGSIDE `teammateFindingsMatched`
+        // (the whole scored pool considered), so "truncated" unambiguously means "relevant-but-no-budget",
         // NOT "every candidate not selected" — 0.44.9's `truncated:89` beside
         // `included:4` read as "89 relevant findings cut" with no pool to anchor it
         // (heskew's #1207 nit). Both are disjoint-and-exhaustive over the matched
@@ -876,12 +890,13 @@ export class BootstrapMemories extends Resource {
             }
         }
         // Collision surfacing's semantic-match candidates (flair#681) — the
-        // BEST (highest-scoring) cross-agent memory per teammate from #550's
+        // BEST (top fused-rank) cross-agent memory per teammate from #550's
         // `scored` list below, captured here (before that list's tokens get
         // spent on the relevant/teammate sections) so the collision block can
-        // reuse the IDENTICAL scored+floor-gated set without recomputing or
-        // re-embedding anything. Stays empty when there's no currentTask (no
-        // `scored` list is ever built) or no cross-agent hits.
+        // reuse the IDENTICAL scored set (flair#1246 — fused retrieval rank, no
+        // floor gate) without recomputing or re-embedding anything. Stays empty
+        // when there's no currentTask (no `scored` list is ever built) or no
+        // cross-agent hits.
         const semanticTeammateMatches = [];
         // --- 4. Task-relevant memories (semantic search) ---
         if (currentTask && tokenBudget > 200) {
@@ -915,12 +930,27 @@ export class BootstrapMemories extends Resource {
                     queryEmbedding,
                     conditions: [scope.condition],
                     limit: candidatePoolK,
-                    // HNSW-leg pushdown ONLY (K&S verdict): no BM25 fusion for
-                    // bootstrap — a different cost profile, since BM25 over the org
-                    // corpus for a one-shot session-load could be MORE expensive than
-                    // HNSW-only unless cached across sessions. Turning it on is an
-                    // explicit opt-in follow-on, gated on its own harness run.
-                    hybrid: false,
+                    // flair#1246 — ONE RANKER, ONE SCALE: this pass now invokes the
+                    // core in the SAME mode memory_search does (hybrid + q via the
+                    // shared hybridEnabled() selector, so the FLAIR_HYBRID_RETRIEVAL
+                    // kill-switch moves BOTH surfaces together — a split mode IS the
+                    // #1246 bug). HNSW-only here was an accident of early code, and it
+                    // made bootstrap's teammate picks diverge from search on the same
+                    // store+query: a record whose task-relevance is LEXICAL (exact task
+                    // terms in semantically-atypical prose) ranks BELOW bland-generic
+                    // noise on pure cosine (measured at N=21: on-task 0.5656 vs noise
+                    // 0.6086 — HNSW rank 6 while search fused it to rank 1), and at
+                    // field scale (corpus >> candidatePoolK) that inversion becomes
+                    // exclusion from the K-bounded pool entirely. The BM25 leg is the
+                    // rescue: it admits the record at lexical rank 1 and union-RRF
+                    // fusion carries it to the top, same as search. Perf (Kern-ratified
+                    // trade): the BM25 corpus scan this adds to the bootstrap path is
+                    // the same per-call scan every memory_search request already runs.
+                    hybrid: hybridEnabled(),
+                    // The lexical leg — same query text the embedding was computed
+                    // from, so both legs rank the same question (parity with search,
+                    // where `q` drives BM25 and the keyword bump).
+                    q: currentTask,
                     // Per-set (this K-bounded pool only, never cross-applied to the
                     // permanent/recent/predicted sets above) — see this function's
                     // supersededIds docs above and resources/
@@ -960,30 +990,32 @@ export class BootstrapMemories extends Resource {
                 });
                 // flair#744 slice 2: the best-match confidence for the abstention
                 // decision — the max absolute cosine across the retrieved pool, read
-                // ONLY from `_semSimilarity` (never any principal/authority field). Note
-                // this floor (ABSTENTION_THRESHOLD ≈ 0.15) sits BELOW bootstrap's own
-                // long-standing TASK_RELEVANCE_FLOOR (0.3) that gates `scored` below, so
-                // an abstaining task (bestSim < 0.15) already has no candidate passing
-                // the floor — abstention only ADDS an explicit "nothing covered this"
-                // signal, it never removes a memory the reader would otherwise have seen.
+                // ONLY from `_semSimilarity` (never any principal/authority field).
+                // Abstention is unaffected by #1246's floor removal: it only ADDS an
+                // explicit "nothing covered this" signal against its own GLOBAL
+                // threshold (resources/abstention.ts), it never removes a memory the
+                // reader would otherwise have seen.
                 if (abstain)
                     taskBestSimilarity = bestSemanticSimilarity(candidates);
-                // Preserve the ORIGINAL score > 0.3 floor exactly (bootstrap's own
-                // historical relevance floor — distinct from SemanticSearch's
-                // `minScore` request param — strict inequality, applied client-side;
-                // `candidates` are already `_score`-sorted best-first, so filtering
-                // preserves that order). `retrieveCandidates()`'s cosine similarity
-                // replaces the raw JS dot product as the ranking signal (HNSW-only,
-                // no BM25) — the K&S-ratified, closest-to-a-wash choice; the
-                // recall harness gates any regression from this ranking-signal
-                // change (magnitude-sensitive dot product → normalized cosine).
+                // flair#1246 — selection is FUSED RETRIEVAL RANK + the token budget
+                // in the packing loop below; there is NO score floor (see the
+                // TASK_RELEVANCE_FLOOR removal note by the pool constants above —
+                // measured inert on the shipped embedding model). `candidates` arrive
+                // best-first on the same ranking memory_search uses (fused RRF order
+                // under hybrid; see retrieveCandidates), so this filter+map preserves
+                // that order. `score` carries `_score` — the honest absolute cosine
+                // (+ legacy keyword bump) per #985/#1267 — for display/reporting;
+                // ORDER and score can legitimately disagree (a BM25 rank-1 rescue
+                // outranks higher-cosine bland hits, which is the recall win).
                 const scored = candidates
-                    .filter((m) => !includedIds.has(m.id) && m._score > TASK_RELEVANCE_FLOOR)
+                    .filter((m) => !includedIds.has(m.id))
                     .map((m) => ({ memory: m, score: m._score }));
                 // flair#681: the collision block's semantic surface — one candidate
-                // per teammate (the highest-scoring hit; `scored` is already sorted
-                // desc, so the first occurrence of a given `_source` IS the best
-                // one). `m._source` is only ever set for a cross-agent record (see
+                // per teammate (`scored` is sorted best-first by the fused retrieval
+                // rank, so the first occurrence of a given `_source` IS that
+                // teammate's best-ranked hit; its `score` field reports the honest
+                // absolute cosine, which per #985/#1267 can disagree with rank).
+                // `m._source` is only ever set for a cross-agent record (see
                 // retrieveCandidates()'s `_source` tagging) — an own memory never
                 // contributes here.
                 const seenCollisionAgents = new Set();
@@ -1077,7 +1109,8 @@ export class BootstrapMemories extends Resource {
         //   - Entity overlap (WorkspaceState + OrgEvent): exact vocabulary-string
         //     match, high-precision, no separate relevance score needed.
         //   - Semantic match (Memory, via #550/4 above): `semanticTeammateMatches`,
-        //     already floor-gated (score > 0.3) — reused as-is, no new scoring.
+        //     each teammate's best-ranked hit from the fused retrieval pool
+        //     (flair#1246 — no score floor) — reused as-is, no new scoring.
         // Gated on freshness (Presence, via the internal roster path) — a
         // teammate absent from the roster, or whose presenceStatus is "offline",
         // never surfaces regardless of how strong the entity/semantic match is.
@@ -1311,9 +1344,10 @@ export class BootstrapMemories extends Resource {
             if (!includedOwnIds.has(id))
                 memoriesTruncatedUnique++;
         memoriesTruncated = memoriesTruncatedUnique;
-        // flair#1207 — the teammate MATCH POOL considered (cleared the relevance
-        // floor, drawn from the bounded candidate pool): every matched teammate
-        // finding is EITHER included OR budget-truncated, so this equals their sum.
+        // flair#1207 — the teammate MATCH POOL considered (flair#1246: the
+        // cross-agent records that entered the scored set — drawn from the
+        // K-bounded fused-rank candidate pool, no relevance floor): every matched
+        // teammate finding is EITHER included OR budget-truncated, so this equals their sum.
         // Reporting it anchors `teammateFindingsTruncated` as "relevant-but-no-budget"
         // rather than an unexplained large number beside a small `included`.
         const teammateFindingsMatched = teammateFindingsIncluded + teammateFindingsTruncated;
@@ -1455,16 +1489,18 @@ export class BootstrapMemories extends Resource {
                 + "after zero-row no-op auto-heal filtering. This container is present-but-empty by design, not dropped."
             : undefined;
         // teammateFindings: [] — name WHICH legitimate empty this is (no task → no
-        // retrieval; matched-but-budget-truncated; or nothing cleared the relevance
-        // floor), so it never reads as a silent drop.
+        // retrieval; matched-but-budget-truncated; or no cross-agent record entered
+        // the task-relevant retrieval pool at all — flair#1246: there is no
+        // relevance floor, so "empty" means empty retrieval, never a score cut),
+        // so it never reads as a silent drop.
         const teammateFindingsHint = includedTeammateFindings.length === 0
             ? (!taskProvided
                 ? "No teammateFindings: cross-agent findings are retrieved against your currentTask, and none was provided. "
                     + "Pass currentTask to populate this."
                 : teammateFindingsTruncated > 0
                     ? `No teammateFindings fit the token budget: ${teammateFindingsTruncated} relevant cross-agent finding(s) `
-                        + "cleared the relevance floor but were budget-truncated. Raise maxTokens to include them."
-                    : "No cross-agent (teammate) memory cleared the task-relevance floor for this currentTask. "
+                        + "were retrieved but budget-truncated. Raise maxTokens to include them."
+                    : "No cross-agent (teammate) memory entered the task-relevant retrieval pool for this currentTask. "
                         + "This container is present-but-empty by design, not dropped.")
             : undefined;
         const responseBody = {
@@ -1532,8 +1568,9 @@ export class BootstrapMemories extends Resource {
             // size-skip self-describing: "a relevant teammate finding didn't fit" is
             // now distinguishable from "no relevant teammate finding".
             teammateFindingsTruncated,
-            // flair#1207 — the teammate match POOL considered (cleared the relevance
-            // floor). teammateFindingsIncluded + teammateFindingsTruncated ==
+            // flair#1207 — the teammate match POOL considered (flair#1246: entered
+            // the scored fused-rank retrieval set; no relevance floor).
+            // teammateFindingsIncluded + teammateFindingsTruncated ==
             // teammateFindingsMatched, so "truncated" reads as "relevant-but-no-budget"
             // against a stated pool, not an unanchored large number.
             teammateFindingsMatched,

package/dist/resources/MemoryFeed.js

@@ -2,6 +2,8 @@ import { Resource, databases } from "harper";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 import { computeContentHash, findExistingMemoryByContentHash } from "./memory-feed-lib.js";
 import { FORBIDDEN, UNAUTH, stampAttribution } from "./record-type-kit.js";
+import { assertValidVisibility, assertVisibilityAllowedForDurability, PRIVATE_VISIBILITY } from "./memory-visibility.js";
+import { assertValidDurability } from "./memory-durability.js";
 export class FeedMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (the auth reshape removes the
     // gate's admin elevation).
@@ -53,6 +55,46 @@ export class FeedMemories extends Resource {
                 headers: { "Content-Type": "application/json" },
             });
         }
+        // ── Write-side durability/visibility validation (#1009/#1238/#1257) ─────
+        // This endpoint writes via the RAW table object below — NOT the exported
+        // Memory resource — so it inherits NONE of Memory.post()/put()'s write
+        // guards (Sherlock's #1261 review: ephemeral+shared, and any invalid
+        // visibility or durability, landed through POST /FeedMemories untouched).
+        // The three guards are applied here in the same order as Memory.post().
+        //
+        // Placed BEFORE the content-hash dedup early-return, deliberately: a
+        // refused combination must refuse deterministically, not return 200 with
+        // the existing record whenever a duplicate happens to exist.
+        //
+        // The effective durability for the tier rule is the one the record below
+        // actually stamps — `content.durability ?? "standard"`. A raw table put
+        // REPLACES the row, so even an update-in-place that omits durability
+        // produces a "standard" row regardless of what it replaces; the stored
+        // row's tier is decided entirely by this payload.
+        const durability = content.durability ?? "standard";
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), {
+                    status: 400,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+            const visibilityError = assertValidVisibility(content.visibility);
+            if (visibilityError) {
+                return new Response(JSON.stringify({ error: "invalid_visibility", message: visibilityError }), {
+                    status: 400,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+            const tierError = assertVisibilityAllowedForDurability(durability, content.visibility);
+            if (tierError) {
+                return new Response(JSON.stringify({ error: "invalid_visibility_for_durability", message: tierError }), {
+                    status: 400,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+        }
         const now = new Date().toISOString();
         const contentHash = computeContentHash(agentId, body);
         const existing = await findExistingMemoryByContentHash(databases.flair.Memory.search(), agentId, contentHash);
@@ -64,11 +106,24 @@ export class FeedMemories extends Resource {
             agentId,
             content: body,
             contentHash,
-            durability: content.durability ?? "standard",
+            durability,
             createdAt: content.createdAt ?? now,
             updatedAt: content.updatedAt ?? now,
             archived: content.archived ?? false,
         };
+        // flair#1257, omission leak: this endpoint stamps NO durability-keyed
+        // visibility default (unlike Memory.post/put — Layer 1), so an ephemeral
+        // feed write with visibility omitted would land with no visibility field
+        // at all, which the read side resolves to NON-private (the migration
+        // invariant). The refusal guard above cannot see an omission, so the
+        // private-only tier invariant is closed here by stamping "private" on
+        // exactly the ephemeral case. Deliberately NOT the general durability-
+        // keyed default: stamping it for standard/persistent/permanent would flip
+        // the visibility of every existing feed caller's writes — a behavioural
+        // change this fix must not smuggle in.
+        if (record.durability === "ephemeral" && (record.visibility === undefined || record.visibility === null)) {
+            record.visibility = PRIVATE_VISIBILITY;
+        }
         await databases.flair.Memory.put(record);
         return record;
     }

package/dist/resources/abstention.js

@@ -46,11 +46,13 @@
  * GLOBAL / data-driven, NEVER per-principal (Sherlock binding condition 2).
  *
  * CONSERVATIVE hand-set value (0.15): well below the strong-match band real
- * embeddings produce for genuinely relevant memories, and below bootstrap's
- * own long-standing task-relevance floor (0.3, resources/MemoryBootstrap.ts's
- * TASK_RELEVANCE_FLOOR) — so abstention fires only when there is essentially
- * nothing semantically near the query, erring toward returning results rather
- * than over-abstaining. Promoting abstention to the DEFAULT recall mode, and
+ * embeddings produce for genuinely relevant memories (and below anything the
+ * flair#1246 measurement observed on the shipped model — 126 records across 6
+ * synthetic variants all scored ≥ ~0.44) — so abstention fires only when
+ * there is essentially nothing semantically near the query, erring toward
+ * returning results rather than over-abstaining. (Bootstrap's own
+ * TASK_RELEVANCE_FLOOR, which this comment once referenced, was removed by
+ * flair#1246 — that same measurement proved it inert.) Promoting abstention to the DEFAULT recall mode, and
  * tuning this value on the recall-bench corpus, is a SEPARATE follow-up (see
  * flair#744) — this slice ships the response shape at a safe opt-in floor, not
  * the calibrated default.
@@ -100,10 +102,11 @@ export const STRONG_BAND = 0.55;
  * Reads ONLY the `_semSimilarity` number the retrieval core
  * (resources/semantic-retrieval-core.ts) attaches to each semantic-leg result
  * WHEN abstention is requested — an absolute cosine similarity in [0,1],
- * independent of the RRF normalization that makes the ranking `_score`
- * a *relative* signal (the top RRF-fused result is normalized to 1.0 regardless
- * of how weak the actual match is, so `_score` is unusable as a confidence
- * floor — this is why abstention reads the absolute similarity instead).
+ * independent of the RRF fusion that orders hybrid results. (Historically the
+ * hybrid `_score` was itself RRF rank-normalized — top result pinned at 1.0
+ * however weak the match — which is why this reads the dedicated absolute
+ * field; since flair#985 the raw `_score` is absolute too, and
+ * `_semSimilarity` stays the explicit opt-in confidence channel.)
  *
  * Returns null when NO candidate carries a `_semSimilarity` (no embedding-based
  * match at all — e.g. a keyword-only degraded search, or an empty pool). Per

package/dist/resources/auth-middleware.js

@@ -4,6 +4,7 @@ import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, isPrincipalDeactivated, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
+import { NOT_FOUND } from "./record-type-kit.js";
 import { isForbiddenOwnerMutation, resolveGuardedRecord } from "./record-owner-guard.js";
 import { checkHttpRateLimit } from "./rate-limit.js";
 // --- Admin credentials ---
@@ -638,11 +639,18 @@ server.http(async (request, nextLayer) => {
                         // used to be a `visibility === "office"` bypass (any authenticated
                         // agent, no grant needed) — that's gone; the private-exclusion is
                         // now enforced the same way every other read path enforces it.
+                        //
+                        // Denial is the SAME 404 the resource layer returns (flair#1264):
+                        // Memory.get() deliberately answers NOT_FOUND for a cross-agent
+                        // private id so a denied caller can't distinguish "doesn't exist"
+                        // from "exists but not yours" — a 403 here, worse yet one naming
+                        // the owning agent, confirmed the id exists AND disclosed its
+                        // owner, defeating that anti-enumeration contract one layer up.
+                        // Reuses record-type-kit's NOT_FOUND so the two layers cannot
+                        // drift apart in shape.
                         const scope = await resolveReadScope(agentId);
                         if (!scope.isAllowed(record)) {
-                            return new Response(JSON.stringify({
-                                error: `forbidden: cannot read memory owned by ${record.agentId}`,
-                            }), { status: 403, headers: { "Content-Type": "application/json" } });
+                            return NOT_FOUND();
                         }
                     }
                 }

package/dist/resources/bm25.js

@@ -107,9 +107,13 @@ export function rrfScores(rankings, universe) {
     return score;
 }
 // Fuse semantic + BM25 candidate id-lists via candidate-union RRF and return a
-// per-id score normalized to [0,1] (rrf / max_rrf_in_union). This normalized
-// value is the rawScore fed to compositeScore so durability/recency/rBoost and
-// the RBOOST_RELEVANCE_FLOOR / minScore thresholds still apply unchanged.
+// per-id score normalized to [0,1] (rrf / max_rrf_in_union). The top-ranked id
+// is pinned at exactly 1.0 BY CONSTRUCTION — this is a RANKING value, not a
+// similarity, and must never be reported as one (flair#985: reporting it as
+// `_score` made every stale flair-client dedup gate see a ≥0.95 "similarity"
+// on EVERY store and silently drop the write). semantic-retrieval-core.ts uses
+// it to ORDER hybrid results (and as compositeScore's ranking input); the
+// reported raw `_score` is the absolute cosine, computed separately.
 //
 //   semIds  — semantic candidate ids, best-first (from the HNSW pass).
 //   bm25Ids — BM25 candidate ids, best-first, already sliced to SEM_LIMIT and

package/dist/resources/memory-visibility.js

@@ -79,3 +79,51 @@ export function assertValidVisibility(visibility) {
         `(got: ${JSON.stringify(visibility)}). Omit it to use the durability-keyed default: ` +
         `permanent/persistent -> shared, standard/ephemeral -> private.`);
 }
+/** Deliberately a LOCAL literal, not an import from memory-durability.ts: this
+ *  module's zero-imports property is load-bearing (see the header — src/cli.ts
+ *  must be able to import it with no transitive baggage), and the tripwire
+ *  tests in test/unit/visibility-write-validation.test.ts pin the value to the
+ *  durability enum so the two cannot drift apart silently. */
+export const EPHEMERAL_DURABILITY = "ephemeral";
+/**
+ * ─── flair#1257 hard precondition: ephemeral memories are private-only ───────
+ *
+ * `ephemeral` is the continuity-journal tier: auto-captured working state,
+ * self-pruning, never meant to leave its owner. `defaultVisibilityForDurability`
+ * keys it to `private`, but a DEFAULT is not a CONSTRAINT — before this guard,
+ * an explicit `visibility:"shared"` on an ephemeral write was accepted, which
+ * would have made journal entries org-readable AND federation-pushed. Kern's
+ * #1257 ruling requires the server to REFUSE the combination so the boundary
+ * holds for every caller (REST, in-process, any adapter), not just the hooks
+ * that promise to send `private` explicitly.
+ *
+ * The rule is deliberately "ephemeral may only carry `private` or nothing",
+ * NOT "refuse ephemeral+shared": on the read side any value other than the
+ * literal "private" resolves to non-private (the migration invariant above),
+ * so an unknown value on an ephemeral row would leak exactly like "shared".
+ * assertValidVisibility refuses unknowns first at both call sites, but this
+ * guard must stay fail-closed on its own — unknown means refused, not allowed.
+ *
+ * Absent (`undefined`/`null`) is accepted: it resolves through the
+ * durability-keyed default, which for ephemeral is `private` — the documented,
+ * intentional path (and the one the continuity hooks use, belt-and-suspenders
+ * with an explicit `private`).
+ *
+ * Returns an error message, or null when the combination is acceptable.
+ * `durability` is the EFFECTIVE durability of the row being written — for
+ * Memory.put() updates, where the payload may omit durability, the caller
+ * passes the pre-existing row's durability as the fallback so a PUT that flips
+ * a stored ephemeral row to shared refuses too.
+ */
+export function assertVisibilityAllowedForDurability(durability, visibility) {
+    if (durability !== EPHEMERAL_DURABILITY)
+        return null;
+    if (visibility === undefined || visibility === null || visibility === PRIVATE_VISIBILITY) {
+        return null;
+    }
+    return (`ephemeral memories are private-only (continuity journal tier, flair#1257): ` +
+        `durability "${EPHEMERAL_DURABILITY}" cannot be written with visibility ${JSON.stringify(visibility)}. ` +
+        `Omit visibility (the durability-keyed default is "${PRIVATE_VISIBILITY}") or set it to ` +
+        `"${PRIVATE_VISIBILITY}"; for a memory other agents should read, use durability ` +
+        `"standard", "persistent", or "permanent".`);
+}

package/dist/resources/semantic-retrieval-core.js

@@ -29,14 +29,29 @@
 // withDetachedTxn's transaction-chain workaround — both SemanticSearch and
 // MemoryBootstrap are Harper Resources with their own `ctx`).
 //
-// Returns results AFTER all filters, sorted best-first by `_score` — bounded
-// ONLY by the `limit` the caller chose to push down (the core never
+// Returns results AFTER all filters, sorted best-first by RETRIEVAL RANK —
+// bounded ONLY by the `limit` the caller chose to push down (the core never
 // multiplies `limit` internally; any overfetch policy — SemanticSearch's
 // CANDIDATE_MULTIPLIER, MemoryBootstrap's K formula — is the CALLER's
 // decision, made
 // before calling in). Never exposes which internal leg (BM25+RRF hybrid vs.
 // legacy HNSW-only vs. keyword-only fallback) produced a given result — the
 // output shape is identical regardless of `hybrid`.
+//
+// ── SCORE CONTRACT (flair#985) ───────────────────────────────────────────────
+// `_score` under `scoring:"raw"` is ALWAYS an ABSOLUTE similarity (cosine of
+// the query and the record's stored embedding, plus the legacy +0.05 substring
+// keyword bump) — on every path, hybrid included. It is NEVER a
+// rank-normalized value. Ordering and score are deliberately decoupled on the
+// hybrid path: results are ORDERED by the fused RRF rank (that ordering is the
+// hybrid recall win), but each result's `_score` reports its true evidence, so
+// order and `_score` can disagree. The pre-#985 hybrid path reported the
+// normalized RRF value AS `_score`, which pinned the top result of ANY query
+// at 1.0 — and every consumer thresholding `_score` as a similarity (the
+// pre-0.18 flair-client dedup gate at 0.95, `minScore`, `flair doctor`'s
+// embed-verify probe) failed open at maximal confidence. For the dedup gate
+// that meant EVERY memory_store from a stale client silently dropped its
+// content into the arbitrary top-1 match — the #985 data-loss report.
 import { databases } from "harper";
 import { withDetachedTxn } from "./table-helpers.js";
 import { wrapUntrusted } from "./content-safety.js";
@@ -85,10 +100,12 @@ export async function retrieveCandidates(params) {
         // ── (a) Semantic candidate records (best-first) ──────────────────────
         const semRecords = [];
         const semIds = [];
-        // flair#744 slice 2: absolute cosine similarity per semantic candidate
-        // (from the HNSW `$distance`), captured HERE before `$distance` is stripped
-        // downstream — the confidence signal the abstention decision reads (only
-        // when `withSemSimilarity`; empty/unused otherwise).
+        // Absolute cosine similarity per semantic candidate (from the HNSW
+        // `$distance`), captured HERE before `$distance` is stripped downstream.
+        // Captured UNCONDITIONALLY (flair#985): this is the value `_score` reports
+        // under `scoring:"raw"` — see the fused loop below — and, when
+        // `withSemSimilarity` (flair#744 slice 2), also the confidence signal the
+        // abstention decision reads via the opt-in `_semSimilarity` field.
         const semSimById = new Map();
         if (qEmb) {
             const semQuery = {
@@ -119,9 +136,20 @@ export async function retrieveCandidates(params) {
                     continue;
                 if (!passesAllowed(record))
                     continue;
-                if (withSemSimilarity && record.$distance !== undefined) {
+                if (record.$distance !== undefined) {
                     semSimById.set(record.id, distanceToSimilarity(record.$distance));
                 }
+                else {
+                    // Harper's cosine-sort query omits `$distance` for a SINGLETON
+                    // post-filter result set (see the legacy path below and
+                    // resources/SemanticSearch.ts's original writeup). Point-lookup the
+                    // record and compute cosine ourselves from its real stored
+                    // embedding — a missing/empty stored embedding yields 0 (safe "no
+                    // semantic evidence"), never a false-high score.
+                    const full = await withDetachedTxn(ctx, () => databases.flair.Memory.get(record.id));
+                    const storedEmbedding = Array.isArray(full?.embedding) ? full.embedding : [];
+                    semSimById.set(record.id, cosineSimilarity(qEmb, storedEmbedding));
+                }
                 semRecords.push(record);
                 semIds.push(record.id);
             }
@@ -175,40 +203,78 @@ export async function retrieveCandidates(params) {
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                     _source: source,
+                    _rank: finalScore,
                 });
             }
         }
         else {
-            // ── Candidate-union RRF → normalized [0,1] rawScore ────────────────
+            // ── Candidate-union RRF → normalized [0,1] RANKING value ────────────
+            // flair#985: the fused RRF value ORDERS results but is never REPORTED
+            // as a score. RRF normalization pins the top candidate at exactly 1.0
+            // regardless of how weak the real match is — reporting it as `_score`
+            // (the pre-#985 behavior) silently changed the meaning of `_score` from
+            // "absolute similarity, 0.95 ≈ near-duplicate" to "relative rank". Every
+            // consumer that thresholds `_score` as a similarity then fails OPEN at
+            // maximal confidence: the pre-0.18 flair-client dedup gate (`score >=
+            // 0.95` → suppress the write) suppressed EVERY memory_store into the
+            // arbitrary top-1 — however unrelated — which is the #985 field report
+            // (4/5 writes silently lost cross-topic). `minScore`, `flair doctor`'s
+            // embed-verify probe, and compositeScore's relevance floors all carry
+            // the same absolute-scale expectation. So: rank by fusion (`_rank`,
+            // internal, stripped before return — the hybrid recall win lives in the
+            // fused ORDER), report absolute evidence (`_score` = true cosine + the
+            // legacy keyword bump, same scale as the legacy HNSW-only path below).
             const fused = fuseRrfNormalized(semIds, bm25Ids);
             for (const [id, rrfRaw] of fused) {
                 const record = allowedById.get(id);
                 if (!record)
                     continue; // should not happen — union ⊆ allowed
-                const rawScore = rrfRaw; // already normalized to [0,1]
-                let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+                // Absolute semantic similarity for this candidate. Sem-leg candidates
+                // already carry it (captured above, incl. the singleton-`$distance`
+                // fallback). A BM25-only candidate never went through the HNSW leg —
+                // point-lookup its stored embedding and compute the true cosine, so a
+                // genuinely-relevant lexical rescue reports its real similarity
+                // instead of a fabricated one (missing/legacy embedding ⇒ 0, safe).
+                let semSim = semSimById.get(id);
+                if (semSim === undefined && qEmb) {
+                    const full = await withDetachedTxn(ctx, () => databases.flair.Memory.get(id));
+                    const storedEmbedding = Array.isArray(full?.embedding) ? full.embedding : [];
+                    semSim = cosineSimilarity(qEmb, storedEmbedding);
+                    semSimById.set(id, semSim);
+                }
+                let keywordHit = false;
+                if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
+                    keywordHit = true;
+                }
+                const rawScore = (semSim ?? 0) + (keywordHit ? 0.05 : 0);
+                let finalScore = scoring === "raw" ? rawScore : compositeScore(rrfRaw, record);
                 if (temporalBoost > 1.0)
                     finalScore *= temporalBoost;
                 const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
                 const source = record.agentId !== agentId ? record.agentId : undefined;
-                // flair#744 slice 2: absolute cosine confidence for the abstention
-                // decision — only for records that had a semantic (HNSW) candidate; a
-                // BM25-lexical-only match carries no cosine and contributes none.
-                const semSim = withSemSimilarity ? semSimById.get(id) : undefined;
                 results.push({
                     ...record,
                     content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                     _source: source,
-                    ...(semSim !== undefined ? { _semSimilarity: semSim } : {}),
+                    // Ordering key: fused rank for raw mode; composite value for
+                    // composite mode (composite ordering is unchanged by #985 — its
+                    // rrfRaw input and result order are exactly the pre-#985 behavior).
+                    _rank: scoring === "raw" ? rrfRaw : finalScore,
+                    // flair#744 slice 2: the opt-in absolute-confidence field for the
+                    // abstention decision. Attach remains OPT-IN so non-abstain
+                    // responses stay byte-identical (the capture above is now
+                    // unconditional, but the response field is not).
+                    ...(withSemSimilarity && semSim !== undefined ? { _semSimilarity: semSim } : {}),
                 });
             }
         }
     }
     else if (qEmb) {
-        // ─── HNSW vector search path (legacy, hybrid flag OFF — or a caller
-        // like MemoryBootstrap forcing HNSW-leg-only regardless of the flag) ────
+        // ─── HNSW vector search path (legacy, hybrid flag OFF — the
+        // FLAIR_HYBRID_RETRIEVAL kill-switch path for BOTH production callers
+        // since flair#1246) ─────────────────────────────────────────────────────
         const query = {
             sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
             select: hnswSelect,
@@ -269,6 +335,7 @@ export async function retrieveCandidates(params) {
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
+                _rank: finalScore,
                 ...(withSemSimilarity ? { _semSimilarity: semanticScore } : {}),
             });
         }
@@ -314,6 +381,7 @@ export async function retrieveCandidates(params) {
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
+                _rank: finalScore,
             });
         }
     }
@@ -331,10 +399,22 @@ export async function retrieveCandidates(params) {
         }
         filteredResults = results.filter((r) => !supersededIds.has(r.id));
     }
-    // Apply minimum score filter
+    // Apply minimum score filter — against `_score`, which is ALWAYS on the
+    // absolute-similarity scale after flair#985 (the hybrid path used to report
+    // the rank-normalized RRF value here, so `minScore: 0.95` matched the
+    // always-1.0 top-1 of ANY query instead of meaning "similarity ≥ 0.95").
     if (minScore > 0) {
         filteredResults = filteredResults.filter((r) => r._score >= minScore);
     }
-    filteredResults.sort((a, b) => b._score - a._score);
+    // Order by the internal ranking key (fused RRF rank on the hybrid raw path;
+    // identical to `_score` everywhere else), then strip it — `_rank` is an
+    // ordering key, never part of the response shape. Note the hybrid raw
+    // ordering is deliberately NOT by `_score`: the recall win of hybrid
+    // retrieval lives in the fused ORDER (a BM25 rank-1 rescue outranks weak
+    // semantic hits), while `_score` carries the honest absolute evidence for
+    // each result — the two can disagree, and that is correct.
+    filteredResults.sort((a, b) => b._rank - a._rank);
+    for (const r of filteredResults)
+        delete r._rank;
     return filteredResults;
 }

package/docs/quickstart-fabric.md

@@ -50,7 +50,7 @@ The target defaults to `https://<cluster>.<org>.harperfabric.com`. Override with
 
 A fleet-verify table follows. That HTTPS origin is your `FLAIR_URL`.
 
-Then set an admin password in Fabric Studio (Cluster Settings → Admin). `flair agent add` against a remote instance requires `--admin-pass` — it will not reuse `~/.flair/admin-pass` or `FLAIR_ADMIN_PASS` from your laptop.
+Then set an admin password in Fabric Studio (Cluster Settings → Admin). `flair agent add` against a remote instance requires an explicit `--admin-pass-file` or `--admin-pass` — it will not reuse `~/.flair/admin-pass` or `FLAIR_ADMIN_PASS` from your laptop.
 
 ## 3. Register an agent against the remote instance
 
@@ -61,10 +61,15 @@ On Fabric, ops lives on the **same hostname at port 9925**, not the CLI's defaul
 ```bash
 export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
 
+# Keep the Fabric admin password in an owner-only file; the CLI reads it in-process.
+printf '%s\n' '<fabric-admin-password>' > ~/.flair/fabric-admin-pass && chmod 600 ~/.flair/fabric-admin-pass
+
 # Fabric ops is :9925 on the same host, not derived :442. docs-freshness-allow: Fabric ops API
-flair agent add mybot --target "$FLAIR_URL" --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass <fabric-admin-password>
+flair agent add mybot --target "$FLAIR_URL" --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass-file ~/.flair/fabric-admin-pass
 ```
 
+`--admin-pass-file` reads the file inside the CLI process (mode `0600` enforced), so the password never appears in shell history **or** `ps`. Inline `--admin-pass <pass>` still works but lands in both; the older `--admin-pass "$(cat <path>)"` workaround stays out of history but is still visible to local `ps` while the command runs. Remote `agent add` honors **only** an explicit flag by design — `FLAIR_ADMIN_PASS` and `~/.flair/admin-pass` are this machine's *local* credentials and are never reused against a remote target.
+
 ```
 Keypair written: ~/.flair/keys/mybot.key
 ✅ Agent 'mybot' (mybot) registered (ops: https://<cluster>.<org>.harperfabric.com:9925) <!-- docs-freshness-allow: Fabric ops API -->
@@ -86,7 +91,41 @@ In Cursor: **Plugins → Configure**
 
 Those are the two plugin schema fields. Local Cursor's `npx` can use the key from step 3 at `~/.flair/keys/mybot.key`. A cloud agent's `npx` runs on a different machine — that VM needs the key (or host-env admin credentials). See [`packages/cursor-flair/README.md`](../packages/cursor-flair/README.md).
 
-## 5. Verify
+## 5. Wire a Grok Bot agent
+
+Same connector, different panel. This is the field-verified sequence — including the two places it fails first.
+
+**One identity per agent.** Short lowercase ids (`grok-cos` for a Chief-of-Staff agent). Never share an id across agents, and never leave admin credentials as an agent's standing auth — the admin password is for registration, once.
+
+1. In the Grok Bot agent's **Tools & MCPs** panel, add the Flair connector (the same `flair-mcp` stdio server the Cursor plugin runs):
+
+   | Variable | Value |
+   |---|---|
+   | `FLAIR_URL` | `https://<cluster>.<org>.harperfabric.com` |
+   | `FLAIR_AGENT_ID` | `grok-cos` (this agent's own id) |
+
+2. Ask for a bootstrap. **The first one returns 401.** That is fail-closed working as designed: the id is not registered yet and the machine has no key. Do not "fix" it by pasting admin credentials into the agent's environment.
+
+3. Provide the Fabric admin password through the platform's secret mechanism — Grok Bot's secure secret card — never pasted in chat. It is needed once, for registration only.
+
+4. On the machine that runs the MCP process (for Grok Bot, that is the agent VM): Node.js **22 or newer** — the field machine had 20 and had to upgrade before anything else worked. Then:
+
+   ```bash
+   npm i -g @tpsdev-ai/flair
+
+   # Fabric ops is :9925 on the same host, as in step 3. docs-freshness-allow: Fabric ops API
+   flair agent add grok-cos --target https://<cluster>.<org>.harperfabric.com --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass "$(cat <pass-file>)"
+   ```
+
+   Keep the pass file mode `0600`. Newer releases add `--admin-pass-file <path>`, which reads the file in-process (invisible to `ps`) — check `flair agent add --help` and prefer it when present.
+
+5. **Restart the MCP process** if it started before the key existed — it does not pick the key up mid-session. Still 401 with the key on disk? Set the key path explicitly in the agent's MCP env: `FLAIR_KEY_PATH=~/.flair/keys/grok-cos.key`. Known papercut, tracked in [flair#1271](https://github.com/tpsdev-ai/flair/issues/1271).
+
+6. Verify: ask the agent to "load my Flair bootstrap". You should get soul + memories **including shared org context** — findings written by teammate agents. A shared-visibility write from this agent is now readable by every org agent.
+
+**Account-wide connectors are shared.** A connector added at the Grok Bot account level is one identity used by every agent on that account. For per-agent identity, give each agent its own MCP entry with its own `FLAIR_AGENT_ID` — and register each id (steps 2–5).
+
+## 6. Verify
 
 ```bash
 flair status --target "$FLAIR_URL"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.13",
+  "version": "0.45.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",