@tpsdev-ai/flair 0.30.0 → 0.31.0

package/dist/resources/embeddings-boot.js

@@ -98,19 +98,17 @@ const MODEL_NAME = "nomic-embed-text";
  * table for the exact contract this PR bumps to).
  *
  * "mean" is nomic-embed-text-v1.5's actual pooling type — NOT assumed from
- * the model's reputation, directly confirmed against the shipped GGUF:
- * `node_modules/.bin/node-llama-cpp inspect gguf
- * ~/.flair/data/models/nomic-embed-text-v1.5.Q4_K_M.gguf` reports
- * `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
+ * the model's reputation, directly confirmed against the shipped GGUF by
+ * reading its metadata: `"nomic-bert": { pooling_type: 1 }`, and llama.cpp's
  * `enum llama_pooling_type` maps 1 -> `LLAMA_POOLING_TYPE_MEAN` (0 = none,
- * 1 = mean, 2 = cls, 3 = last, 4 = rank). nomic-embed-text is a
- * NomicBertModel architecture, not Qwen3 (last-token) — flair registers no
- * Qwen3-class embedding model today (the Qwen3-Reranker-0.6B in
- * resources/rerank-provider.ts is a SEPARATE code path that calls
- * node-llama-cpp directly for generative yes/no scoring, never goes through
- * HFE's register()/init(), and has no embedding-pooling context at all — see
- * that file's header). If a Qwen3-class (last-token-pooling) embedding model
- * is ever registered here, it must declare `pooling: "last"`, not "mean".
+ * 1 = mean, 2 = cls, 3 = last, 4 = rank). (That reading was originally taken
+ * with `node-llama-cpp inspect gguf`, which flair no longer depends on —
+ * flair#893. Any GGUF inspector reports the same metadata field; install the
+ * CLI ad hoc if the check needs repeating.) nomic-embed-text is a
+ * NomicBertModel architecture, not Qwen3 (last-token), and flair registers no
+ * Qwen3-class embedding model today. If a Qwen3-class (last-token-pooling)
+ * embedding model is ever registered here, it must declare `pooling: "last"`,
+ * not "mean".
  *
  * Applies to the bench-only `modelPath` override too (`benchModelPathOverride()`
  * below): `FLAIR_RECALL_HARNESS_MODEL_PATH` lets an operator point this

package/dist/resources/embeddings-provider.js

@@ -152,7 +152,7 @@ const EMBEDDING_PREFIXES_ENABLED = true; // Phase 2 prefix flip ON — re-baseli
  * embedding call, so this lets it override the ONE thing that matters
  * (whether `models.embed` receives `inputType`, and whether `getModelId()`
  * stamps the suffix) via the env var it already forwards to `startHarper()`
- * (the same mechanism `FLAIR_HYBRID_RETRIEVAL`/`FLAIR_RERANK_ENABLED` use).
+ * (the same mechanism `FLAIR_HYBRID_RETRIEVAL` uses).
  *
  * Bidirectional, not two separate force-on/force-off hatches: THE GATE has
  * flipped direction once already (off→on, this PR) and may again in the
@@ -236,12 +236,15 @@ async function getModelsApi() {
 /**
  * Resolve the directory the embeddings model lives in / downloads into.
  *
- * 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
+ * Implementation lives in `resources/models-dir.ts` (extracted in flair#815)
+ * so any model consumer can share the exact same resolution without importing
+ * this module — several unit-isolated tests `mock.module()` this file
+ * wholesale, and an incomplete stub then breaks every file that imports it.
+ * See models-dir.ts's header for why that hazard makes the tiny standalone
+ * module worth keeping even now that embeddings are its only consumer.
+ * 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 { resolveModelsDir } from "./models-dir.js";

package/dist/resources/health.js

@@ -3,9 +3,9 @@ import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getRerankStatus } from "./rerank-provider.js";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
 import { getMigrationStatusSnapshot } from "./migrations/status.js";
+import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
 const db = databases;
 const redactHome = (p) => {
@@ -560,12 +560,21 @@ export class HealthDetail extends Resource {
         // "pre-flight integrity check in progress" state the K&S verdict calls
         // for; a halted migration surfaces here (with `reason`) AND as a
         // warning below so it's visible without a separate lookup.
+        //
+        // flair#812: the dataDir is resolved by the shared, READ-ONLY resolver
+        // (resources/migrations/data-dir.ts) rather than the old
+        // `HDB_ROOT ?? homedir()/.flair/data` expression duplicated here — that
+        // env var is never set by anything, so the left branch was dead and the
+        // path silently disagreed with wherever the boot cycle actually wrote.
+        // `lastCycleError` is surfaced so `flair doctor` can name WHY a cycle
+        // didn't run, not merely that it didn't.
         try {
-            const migrationsDataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const migrationsDataDir = resolveMigrationDataDirForRead();
             const snapshot = getMigrationStatusSnapshot(migrationsDataDir);
             stats.migrations = {
                 cyclePhase: snapshot.cyclePhase,
                 lastCycleAt: snapshot.lastCycleAt ?? null,
+                lastCycleError: snapshot.lastCycleError ?? null,
                 migrations: snapshot.migrations,
             };
             for (const m of snapshot.migrations) {
@@ -573,13 +582,25 @@ export class HealthDetail extends Resource {
                     warnings.push({ level: "warn", message: `migration '${m.id}' ${m.state}${m.reason ? `: ${m.reason}` : ""} — see \`flair doctor\`` });
                 }
             }
+            // The boot trigger sets `scheduled` synchronously at module load, so
+            // `idle` here means resources/migration-boot.js never loaded — the
+            // instance is running a build whose migration trigger is absent or
+            // failed to import, and NO migration will ever run on it.
+            if (snapshot.cyclePhase === "idle" && snapshot.migrations.length > 0) {
+                warnings.push({
+                    level: "warn",
+                    message: "migration boot cycle never fired on this instance (cyclePhase=idle) — no migration will run until this is resolved; see `flair doctor`",
+                });
+            }
         }
         catch {
             stats.migrations = null;
         }
         // ── Disk ──
+        // flair#812: same shared read-only resolution as the migrations section
+        // above, so `disk.dataDir` names the directory migrations actually use.
         try {
-            const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const dataDir = resolveMigrationDataDirForRead();
             const snapshotDir = join(homedir(), ".flair", "snapshots");
             const dirSize = async (root, maxDepth = 6) => {
                 if (!(await exists(root)))
@@ -658,22 +679,6 @@ export class HealthDetail extends Resource {
         catch {
             stats.bridges = null;
         }
-        // ── Reranker ──
-        // Cross-encoder rerank stage. Reports flag/model/mode + live counters so we
-        // can see if it's silently degrading (fallbackCount climbing) in prod.
-        try {
-            const rr = getRerankStatus();
-            stats.rerank = rr;
-            if (rr.enabled && rr.state === "failed") {
-                warnings.push({ level: "warn", message: `reranker enabled but unavailable: ${rr.error ?? "init failed"} — recall falling back to vector order` });
-            }
-            if (rr.enabled && rr.rerankCount > 0 && rr.fallbackCount > rr.rerankCount) {
-                warnings.push({ level: "warn", message: `reranker falling back more than reranking (${rr.fallbackCount} fallbacks / ${rr.rerankCount} reranks) — check latency budget / topN` });
-            }
-        }
-        catch {
-            stats.rerank = null;
-        }
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──

package/dist/resources/in-process.js

@@ -0,0 +1,225 @@
+/**
+ * ─── The in-process call seam (one incantation, one place) ───────────────────
+ *
+ * How code running INSIDE the Harper process invokes a flair resource AS a
+ * specific agent — flair's own native MCP handler (resources/mcp-tools.ts), and
+ * any co-located application component that loads flair as a sub-component and
+ * calls it directly instead of over HTTP.
+ *
+ * Three things an in-process caller has to get right, none of which is visible
+ * from a resource's own source and none of which used to fail in a way that
+ * points at the cause:
+ *
+ * 1. **Identity.** Every flair resource resolves its caller through
+ *    resources/agent-auth.ts's `resolveAgentAuth()`, whose FIRST hop is the
+ *    `tpsAgent` annotation the HTTP auth middleware stamps on a verified
+ *    request. There is no HTTP request in-process, so the caller supplies that
+ *    annotation itself — {@link agentContext}.
+ *
+ * 2. **Not accidentally becoming an administrator.** A context with no usable
+ *    agent id resolves to flair's trusted `internal` verdict, which is
+ *    UNFILTERED. See the safety-design block below: this module's API shape is
+ *    built around making that unreachable by accident.
+ *
+ * 3. **Collection binding.** A resource's `post()` — the create path — only
+ *    works on a resource instance Harper has marked as a COLLECTION. That mark
+ *    is a PRIVATE field (`#isCollection`) set inside Harper's own
+ *    `getResource()`; the public `isCollection` is a GETTER WITH NO SETTER on
+ *    `Resource.prototype`. So the obvious `new Cls(undefined, ctx)` +
+ *    `h.isCollection = true` does not "not work" quietly — under ESM (always
+ *    strict mode) the assignment throws
+ *    `TypeError: Cannot set property isCollection ... which has only a getter`,
+ *    and dropping the assignment instead yields
+ *    `405 The <X> does not have a post method implemented` from Harper's base
+ *    `Resource.post()`. {@link collectionResource} is the one supported way in:
+ *    hand `getResource()` an `{ isCollection: true }` option and let Harper set
+ *    its own private field.
+ *
+ * flair itself got (3) wrong in four MCP tool paths before this module existed —
+ * the same mistake a consumer reading only the resource classes would make.
+ *
+ * ─── SAFETY DESIGN: the dangerous thing has to look dangerous ────────────────
+ *
+ * MEASURED, against the real resolver:
+ *
+ *   resolveAgentAuth({ request: { tpsAgent: undefined } })  ->  { kind: "internal" }
+ *   resolveAgentAuth({ request: { tpsAgent: ""        } })  ->  { kind: "internal" }
+ *   allowAdmin({ request: { tpsAgent: undefined } })        ->  true
+ *
+ * `resolveAgentAuth` tests `tpsAgent` for TRUTHINESS, so a missing or empty id
+ * is indistinguishable from "no identity was supplied at all" — and that is the
+ * trusted verdict. The consequence is that the most ordinary application bug
+ * there is — `agentContext(session.agentId)` where the field is undefined, a
+ * typo'd property, a lookup that found nothing — would not fail closed. It
+ * would silently grant unfiltered cross-agent reads and writes, and pass the
+ * admin-only gate on admin-only resources. No error, no 403, no log line.
+ *
+ * That is the same defect class as a check that cannot fail: **the failure mode
+ * of "I forgot the id" must never be "you are now an administrator."** So:
+ *
+ *   - {@link agentContext} THROWS on a missing, empty or blank id. It is always
+ *     a programming error, and an exception is the only outcome that cannot be
+ *     mistaken for success.
+ *   - {@link agentContext} takes NO options. It is structurally incapable of
+ *     producing an admin context, so spreading a caller-influenced object into
+ *     its arguments cannot escalate.
+ *   - Admin is a SEPARATE, NAMED export ({@link adminContext}), and so is the
+ *     unfiltered maintenance verdict ({@link internalContext}). Both are
+ *     greppable: `git grep -n "adminContext\|internalContext"` enumerates every
+ *     privileged call site in a codebase.
+ *   - {@link collectionResource} REQUIRES a context and throws without one, so
+ *     the privileged path can never be reached by leaving an argument off. The
+ *     dangerous path is now the LONGEST path, not the shortest.
+ *
+ * These guards are runtime, not types, on purpose: an embedding application may
+ * be plain JavaScript, where a `string` parameter annotation buys exactly
+ * nothing. test/integration/in-process-agents.test.ts pins both the guards and
+ * the hazard they exist for, against a real Harper.
+ *
+ * ── Deliberately dependency-free ─────────────────────────────────────────────
+ * No `import { databases } from "harper"` (see resources/memory-visibility.ts
+ * for why that import is load-bearing to avoid): these helpers are pure shape,
+ * and an embedding app may want them before any table is resolved.
+ */
+/**
+ * Thrown when an in-process call is built in a way that would have silently
+ * escalated. Its own type so a caller can distinguish "I wired this wrong" from
+ * a resource's business-logic refusal (which arrives as a `Response`, not a
+ * throw).
+ */
+export class InProcessContextError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InProcessContextError";
+    }
+}
+/** Reject anything that would resolve to the trusted `internal` verdict, or to a nonsense id. */
+function requireAgentId(agentId, fnName) {
+    if (typeof agentId !== "string" || agentId.trim() === "") {
+        const got = agentId === undefined ? "undefined"
+            : agentId === null ? "null"
+                : typeof agentId !== "string" ? `a ${typeof agentId}`
+                    : agentId === "" ? "an empty string"
+                        : "a blank string";
+        throw new InProcessContextError(`${fnName}() requires a non-empty agent id, but received ${got}. ` +
+            "This is refused rather than defaulted because flair resolves a missing or empty " +
+            "tpsAgent to its trusted `internal` verdict, which reads and writes UNFILTERED across " +
+            "every agent and passes the admin-only gate — so returning a context here would have " +
+            "turned a missing id into silent administrator access. Resolve the agent id from your " +
+            "own server-side state before calling, and never from request data.");
+    }
+    return agentId;
+}
+/**
+ * The resource context that makes an in-process call act as ONE SPECIFIC agent.
+ * This is the call an application makes; the other two constructors below are
+ * privileged and deliberately harder to type.
+ *
+ * **`agentId` is asserted, not proven.** flair reads it and acts as that agent:
+ * no signature, no lookup against the `Agent` table, no registration
+ * requirement. That is right for a caller already inside the trust boundary —
+ * it could write the raw table anyway — and it is exactly why the id must come
+ * from YOUR OWN server-side state (the session you authenticated, the job
+ * record you dequeued) and **never from request data**. An agent id that
+ * reaches here from a body field, a query param, or a header you did not verify
+ * yourself is privilege escalation with no error and no trace.
+ *
+ * Throws {@link InProcessContextError} on a missing, empty or blank id — see the
+ * safety-design block at the top of this file for why that is not merely
+ * defensive.
+ *
+ * Takes no options, and in particular no way to ask for admin: use
+ * {@link adminContext} for that, so the escalation is a word you had to type.
+ *
+ * ```ts
+ * const Memory = server.resources.get("Memory").Resource;
+ * const h = await collectionResource(Memory, agentContext("planner"));
+ * const { id } = await h.post({ agentId: "planner", content: "…" });
+ * ```
+ */
+export function agentContext(agentId) {
+    return {
+        request: {
+            tpsAgent: requireAgentId(agentId, "agentContext"),
+            tpsAgentIsAdmin: false,
+        },
+    };
+}
+/**
+ * Like {@link agentContext}, but with flair-admin authority: unfiltered
+ * cross-agent reads, and writes attributed to agents other than this one.
+ *
+ * Asserted, never checked — nothing validates that the named agent is actually
+ * an admin principal. **Treat a call to this exactly as you would a root
+ * shell:** provisioning and maintenance only, never a request handler's
+ * default, and never with an id or a flag derived from anything a caller
+ * supplied.
+ *
+ * It is a separate export rather than an option so that (a) no options object
+ * spread into {@link agentContext} can escalate, and (b) every privileged call
+ * site in a codebase is findable by name.
+ *
+ * Throws {@link InProcessContextError} on a missing, empty or blank id.
+ */
+export function adminContext(agentId) {
+    return {
+        request: {
+            tpsAgent: requireAgentId(agentId, "adminContext"),
+            tpsAgentIsAdmin: true,
+        },
+    };
+}
+/**
+ * The TRUSTED, UNATTRIBUTED, UNFILTERED context — flair's `internal` verdict.
+ * Reads see every agent's private records; writes are owned by nobody.
+ *
+ * This exists for work that is genuinely infrastructure rather than an agent's:
+ * provisioning a principal, a migration, a maintenance sweep. It is the same
+ * verdict a context-less call used to fall into by accident; naming it means an
+ * application can no longer reach it by forgetting an argument, and means
+ * `git grep internalContext` enumerates every place flair or an embedder took
+ * that authority deliberately.
+ *
+ * There is no id to validate: the verdict comes precisely from the ABSENCE of
+ * an identity annotation, so the returned object carries none. The marker field
+ * is inert — it documents intent at a debugger breakpoint and is read by
+ * nothing.
+ *
+ * ```ts
+ * // Registering a principal — infrastructure, not an agent's own write.
+ * const h = await collectionResource(Agent, internalContext());
+ * await h.post({ id, name: id, publicKey });
+ * ```
+ */
+export function internalContext() {
+    return { request: {}, __flairInternal: true };
+}
+/**
+ * A resource instance bound to `context` and marked as a COLLECTION, so its
+ * `post()` (the create path) works — see this module's header for why that mark
+ * cannot be applied from outside Harper.
+ *
+ * `context` is REQUIRED. Passing nothing used to yield the unfiltered
+ * `internal` verdict, which made the privileged path the shortest one to type;
+ * it now throws. Pass {@link agentContext} for an agent's own work,
+ * {@link adminContext} or {@link internalContext} when the authority is
+ * genuinely intended.
+ *
+ * Reads do not need this — `Cls.get(id, context)` and `Cls.search(query,
+ * context)` (Harper's static resource methods) already thread the context and
+ * start their own transaction.
+ */
+export async function collectionResource(Cls, context) {
+    if (context == null || typeof context !== "object") {
+        throw new InProcessContextError("collectionResource() requires an explicit context, but received " +
+            (context === undefined ? "undefined" : context === null ? "null" : `a ${typeof context}`) +
+            ". Omitting it would resolve to flair's trusted `internal` verdict — unfiltered reads and " +
+            "unattributed writes across every agent — so the privileged path is never the one you get " +
+            "by leaving an argument off. Pass agentContext(id) to act as an agent, or internalContext() " +
+            "if this really is infrastructure work.");
+    }
+    // `{}` is a sufficient RequestTarget here: getResource() reads only `.id` off
+    // it (undefined ⇒ Harper mints the primary key), and takes the collection
+    // mark from the options argument.
+    return (await Cls.getResource({}, context, { isCollection: true }));
+}

package/dist/resources/mcp-tools.js

@@ -36,6 +36,7 @@
  * slice.
  */
 import { resolveVersion } from "./version.js";
+import { agentContext, adminContext, collectionResource } from "./in-process.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -78,16 +79,22 @@ export function __setHandlers(overrides) {
  * agent, never anonymous, never a header re-verify.
  */
 function delegationContext(agent) {
-    return {
-        request: {
-            tpsAgent: agent.agentId,
-            tpsAgentIsAdmin: agent.isAdmin,
-            headers: {
-                get: (k) => (k.toLowerCase() === "x-tps-agent" ? agent.agentId : undefined),
-            },
-        },
-        user: undefined,
+    // Shape single-sourced from resources/in-process.ts — the same context an
+    // embedding Harper app builds to act as one of its agents — plus the
+    // `x-tps-agent` header shim the delegated handlers' own header-reading paths
+    // expect.
+    //
+    // The admin branch is spelled out rather than passed as a flag: adminContext()
+    // is the greppable name for "this call carries flair-admin authority". Both
+    // constructors THROW on an empty agent id, which is the outcome we want here —
+    // a token that resolved to no principal must fail the tool call, never fall
+    // through to flair's unfiltered `internal` verdict.
+    const ctx = agent.isAdmin ? adminContext(agent.agentId) : agentContext(agent.agentId);
+    ctx.request.headers = {
+        get: (k) => (k.toLowerCase() === "x-tps-agent" ? agent.agentId : undefined),
     };
+    ctx.user = undefined;
+    return ctx;
 }
 /**
  * Unwrap a handler return value into a plain object/string for the MCP result.
@@ -128,8 +135,7 @@ async function memorySearch(agent, args) {
 }
 async function memoryStore(agent, args) {
     const Cls = await handler("Memory");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // agentId is the RESOLVED agent — Memory.post also re-checks ownership via
     // resolveAgentAuth, so a mismatched body agentId would 403 anyway; we set it
     // to the verified id so the write is correctly owned.
@@ -204,8 +210,10 @@ async function memoryUpdate(agent, args) {
         // version's provenance records which client authored this update.
         if (agent.clientId)
             record.claimedClient = agent.clientId;
-        h.isCollection = true;
-        return unwrap(await h.post(record));
+        // A create needs a COLLECTION-bound instance (see resources/in-process.ts);
+        // `h` above is the by-id handle the get()/put() branches use.
+        const coll = await collectionResource(Cls, delegationContext(agent));
+        return unwrap(await coll.post(record));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
@@ -281,8 +289,7 @@ async function soulGet(agent, args) {
 }
 async function workspaceSet(agent, args) {
     const Cls = await handler("WorkspaceState");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // No agentId in the body — WorkspaceState.post attributes the record to the
     // authenticated identity (from the context), never the body. Same no-forge
     // contract as the flair-mcp stdio tool.
@@ -304,8 +311,7 @@ async function workspaceSet(agent, args) {
 }
 async function orgEvent(agent, args) {
     const Cls = await handler("OrgEvent");
-    const h = new Cls(undefined, delegationContext(agent));
-    h.isCollection = true;
+    const h = await collectionResource(Cls, delegationContext(agent));
     // No authorId in the body — OrgEvent.post attributes to the authenticated
     // identity, never the body (no forging as another agent).
     const body = { kind: args?.kind, summary: args?.summary };

package/dist/resources/migration-boot.js

@@ -25,20 +25,43 @@
  * `runMigrationCycle` itself never throws (see runner.ts's module doc) —
  * the `.catch()` below is pure defense-in-depth so a bug there can never
  * take down the process either.
+ *
+ * ─── flair#812: this path must never fail silently ────────────────────────
+ * `runMigrationCycle` REPORTS why a cycle didn't run (`{ ran: false, reason
+ * }`) — it does not log it, because it is a library. This file, the only
+ * caller, previously DISCARDED that value, which is what turned a
+ * recoverable environment problem into an invisible one: on a provisioned
+ * install where `~/.flair/data` isn't creatable, the runner's very first
+ * step (`acquireMigrationLock` → `mkdirSync`) threw `EACCES`, the runner
+ * caught it and returned `reason: "lock error: ..."`, and nothing anywhere
+ * said a word. `.migrations/state.json` was never written, no
+ * `[flair-migrations]` marker ever appeared, and EVERY migration — shipped
+ * and future — was skipped on that instance forever.
+ *
+ * So: the data dir is now resolved to a candidate PROVEN writable before
+ * the cycle is handed one (resources/migrations/data-dir.ts), and every
+ * non-benign outcome — an unresolvable data dir, tables that never became
+ * ready, a runner-reported failure, an unexpected throw — is BOTH logged
+ * with a `[flair-migrations]` marker AND recorded as a `failed` progress
+ * entry per registered migration. That progress entry is what makes the
+ * condition visible where an operator will actually meet it:
+ * `/HealthDetail` (with a warning), `flair doctor`'s Migrations section
+ * (counted as an issue) and `flair quality`'s `instance.migrationsClean`.
+ *
+ * The one deliberately-quiet outcome is `single-flight` — another thread or
+ * process holds the lock and is running the cycle. That is the guard doing
+ * its job, not a failure, and Harper boots N worker threads that each load
+ * this module; logging it would emit N-1 scary lines on every healthy boot.
  */
 import { databases } from "harper";
-import { homedir } from "node:os";
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildRegistry } from "./migrations/registry.js";
 import { runMigrationCycle } from "./migrations/runner.js";
-import { seedIdleProgress } from "./migrations/progress.js";
+import { markIdleMigrationsFailed, seedIdleProgress, setCyclePhase } from "./migrations/progress.js";
+import { describeUnresolvableDataDir, resolveWritableMigrationDataDir, } from "./migrations/data-dir.js";
 import { getMode } from "./embeddings-provider.js";
-/** Same dataDir resolution as resources/health.ts's disk section. */
-export function resolveMigrationDataDir() {
-    return process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
-}
 /** Same "resolve the running package's own version" idiom as resources/health.ts. */
 export function resolveRunningVersion() {
     try {
@@ -103,6 +126,26 @@ async function waitForEmbeddingsSettled(maxWaitMs = 8_500, intervalMs = 150) {
         await new Promise((r) => setTimeout(r, intervalMs));
     }
 }
+/**
+ * Records a boot-path failure everywhere an operator might look: the
+ * process log (with the `[flair-migrations]` marker the runbook greps for),
+ * the cycle status (`lastCycleError`, surfaced by `/HealthDetail` and named
+ * by `flair doctor`), and a `failed` entry for each migration that never
+ * started — because a boot path that cannot run is not a per-migration
+ * problem, it is an instance-wide one, and `flair doctor` / `flair quality`
+ * read per-migration state.
+ *
+ * `failed` (not `halted`) is deliberate for these: nothing was attempted
+ * against the corpus, so there is no halted work to resume. And the marking
+ * deliberately touches only migrations still `idle` — see
+ * `markIdleMigrationsFailed` for why overwriting a terminal state would be
+ * a downgrade rather than extra information.
+ */
+function reportBootFailure(registry, reason) {
+    console.error(`[flair-migrations] ${reason}`);
+    setCyclePhase("done", reason);
+    markIdleMigrationsFailed(registry.list().map((m) => m.id), reason);
+}
 let scheduled = false;
 export function scheduleMigrationBoot() {
     if (scheduled)
@@ -110,30 +153,57 @@ export function scheduleMigrationBoot() {
     scheduled = true;
     const registry = buildRegistry();
     seedIdleProgress(registry.list().map((m) => m.id));
+    // Proof-of-life, set SYNCHRONOUSLY at module load: from here on,
+    // `cyclePhase === "idle"` means this module never loaded at all — the
+    // one hypothesis flair#812 could not otherwise rule out from the outside.
+    setCyclePhase("scheduled");
     setImmediate(() => {
         void (async () => {
             const ready = await waitForTablesReady();
             if (!ready) {
-                console.error("[flair-migrations] Memory/Relationship tables never became ready — skipping this boot's migration cycle (will retry next boot)");
+                reportBootFailure(registry, "Memory/Relationship tables never became ready within 30s — this boot's migration cycle was skipped (it retries on the next restart)");
                 return;
             }
             await waitForEmbeddingsSettled();
+            // Resolve a data dir PROVEN writable before handing one to the runner
+            // — the runner's first act is to take a file lock there, and a
+            // failure at that point is reported back rather than thrown, which is
+            // precisely how flair#812 stayed invisible. See data-dir.ts.
+            const resolved = resolveWritableMigrationDataDir();
+            if (!resolved.dataDir) {
+                reportBootFailure(registry, describeUnresolvableDataDir(resolved.tried));
+                return;
+            }
             try {
-                await runMigrationCycle({
+                const result = await runMigrationCycle({
                     registry,
                     getTable,
-                    dataDir: resolveMigrationDataDir(),
+                    dataDir: resolved.dataDir,
                     runningVersion: resolveRunningVersion(),
                 });
+                // `nothing pending` is the healthy no-op; `single-flight` is the
+                // lock guard working as designed on a multi-threaded boot. Anything
+                // else is a cycle that WANTED to run and couldn't, and must be loud.
+                if (!result.ran && result.reason && !isBenignSkip(result.reason)) {
+                    reportBootFailure(registry, `migration cycle did not run: ${result.reason}`);
+                }
             }
             catch (err) {
                 // Defense-in-depth only — runMigrationCycle is documented to never
                 // throw. A boot-path exception must never surface here regardless.
-                console.error(`[flair-migrations] unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
+                reportBootFailure(registry, `unexpected error from runMigrationCycle: ${err?.message ?? String(err)}`);
             }
         })();
     });
 }
+/**
+ * The two `{ ran: false }` reasons that are NOT failures: nothing was
+ * pending, or another holder is already running the cycle. Matched on the
+ * prefixes runner.ts constructs (`"nothing pending"`, `"single-flight: …"`).
+ */
+export function isBenignSkip(reason) {
+    return reason === "nothing pending" || reason.startsWith("single-flight:");
+}
 // Test-only reset so a unit/integration test can re-trigger scheduling
 // within the same process (never used in production — a real process only
 // ever boots once).