@tpsdev-ai/flair 0.49.0 → 0.50.0

package/dist/rem/scheduler.js

@@ -19,7 +19,7 @@ import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, resolveFlairBin, formatFlairBinWarning, verifyFirstRun, probeUserLingerEnabled, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 // Re-exported so this module's public surface is unchanged by the extraction
 // into src/lib/scheduler-platform.ts (a second scheduler — `flair federation
 // sync enable` — needs the identical launchctl/systemctl interpretation, and
@@ -180,8 +180,8 @@ export async function queryActiveStateAsync(plat, timeoutMs = STATUS_CHECK_TIMEO
  * known pattern — the caller already prints the raw stderr, so the operator
  * still has something to go on.
  */
-export function describeLoadFailure(plat, loadResult) {
-    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable");
+export function describeLoadFailure(plat, loadResult, session) {
+    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable", session);
 }
 /**
  * Formats the `flair rem nightly enable` report from an `EnableResult`.
@@ -199,6 +199,15 @@ export function describeLoadFailure(plat, loadResult) {
  * happen once. A missing `loadResult`/`firstRun` (test-only skipLoad shape)
  * therefore withholds the headline too, instead of being treated as success.
  */
+function appendFlairBinWarning(lines, r) {
+    if (r.flairBinCanonical !== false || !r.flairBin)
+        return;
+    const warning = formatFlairBinWarning(r.flairBin, r.flairBinPublic ?? null, "flair rem nightly enable");
+    if (warning.length === 0)
+        return;
+    lines.push("");
+    lines.push(...warning);
+}
 export function formatEnableReport(r, input) {
     const { hour, minute, agentId, flairUrl } = input;
     const scheduleTime = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
@@ -216,11 +225,15 @@ export function formatEnableReport(r, input) {
         ];
         if (lr.stderr)
             lines.push(`     stderr: ${lr.stderr.trim()}`);
-        const remedy = describeLoadFailure(r.platform, lr);
+        const lingerEnabled = input.lingerEnabled !== undefined
+            ? input.lingerEnabled
+            : (r.platform === "linux" ? (input.probeLinger ?? probeUserLingerEnabled)() : undefined);
+        const remedy = describeLoadFailure(r.platform, lr, { lingerEnabled, env: input.env });
         lines.push("");
         lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
         lines.push("");
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair rem nightly status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     if (!r.firstRunVerified) {
@@ -272,6 +285,7 @@ export function formatEnableReport(r, input) {
         }
         lines.push("");
         lines.push(`   Check anytime with: flair rem nightly status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     const lines = [
@@ -288,6 +302,7 @@ export function formatEnableReport(r, input) {
     lines.push(`   First run:   completed through the service manager, exit 0`);
     lines.push("");
     lines.push(`Disable with \`flair rem nightly disable\`.`);
+    appendFlairBinWarning(lines, r);
     return { lines, ok: true };
 }
 /**
@@ -329,7 +344,8 @@ export function formatStatusReport(s) {
  */
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
-    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const resolvedFlair = resolveFlairBin(opts.flairBin);
+    const flairBin = resolvedFlair.path;
     const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
@@ -383,6 +399,7 @@ export function enableScheduler(opts) {
         return {
             platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult,
             firstRunVerified: firstRun?.verified === true, firstRun,
+            flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
         };
     }
     // Linux: systemd user units.
@@ -408,6 +425,7 @@ export function enableScheduler(opts) {
     return {
         platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult,
         firstRunVerified: firstRun?.verified === true, firstRun,
+        flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
     };
 }
 /**

package/dist/resources/MemoryBootstrap.js

@@ -502,16 +502,18 @@ export class BootstrapMemories extends Resource {
                     skillAssignments.push(record);
                     continue;
                 }
-                // flair#1182 — the raw soul container (key→value), independent of the
-                // token-budgeted/priority-truncated `sections.soul` lines built below.
-                soulMap[record.key] = record.value;
                 const line = `**${record.key}:** ${record.value}`;
                 const tokens = estimateTokens(line);
                 const priority = SOUL_KEY_PRIORITY[record.key] ?? 50;
-                soulEntries.push({ key: record.key, line, tokens, priority });
+                soulEntries.push({ key: record.key, value: record.value, line, tokens, priority });
             }
             // Sort by priority (lower = more important)
             soulEntries.sort((a, b) => a.priority - b.priority);
+            // flair#1371 — the structured `soul` map follows the admission decision.
+            // Filling it during the scan (flair#1182) shipped every key even when
+            // this loop dropped the entry, so sections.soul / soulTokens / the
+            // context pointer described N while `soul` delivered N+1 (delivered
+            // but not counted or charged — the #1206 mirror).
             for (const entry of soulEntries) {
                 if (soulTokens + entry.tokens > soulMaxTokens) {
                     // Skip large entries that exceed budget — truncate or skip
@@ -522,6 +524,7 @@ export class BootstrapMemories extends Resource {
                     if (maxChars > 100) {
                         const truncated = `**${entry.key}:** ${entry.line.slice(entry.key.length + 6, entry.key.length + 6 + maxChars)}…(truncated)`;
                         sections.soul.push(truncated);
+                        soulMap[entry.key] = entry.value;
                         const cost = estimateTokens(truncated);
                         soulTokens += cost;
                         tokenBudget -= cost; // #1199 — soul draws from the shared budget
@@ -529,6 +532,7 @@ export class BootstrapMemories extends Resource {
                     continue;
                 }
                 sections.soul.push(entry.line);
+                soulMap[entry.key] = entry.value;
                 soulTokens += entry.tokens;
                 tokenBudget -= entry.tokens; // #1199 — soul draws from the shared budget
             }

package/dist/resources/health.js

@@ -1,4 +1,4 @@
-import { Resource, databases } from "harper";
+import { Resource, databases, server, logger } from "harper";
 import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, dirname } from "node:path";
@@ -8,6 +8,9 @@ import { resolveBuildInfo } from "./build-info.js";
 import { getMigrationStatusSnapshot } from "./migrations/status.js";
 import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
+import { hybridEnabled } from "./bm25.js";
+import { bm25IndexEnabled, bm25IndexStatus } from "./bm25-index-service.js";
+import { buildPublicHealthBody, resolveSearchReadiness } from "./search-readiness.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -52,7 +55,7 @@ function resolveVersion() {
     return process.env.npm_package_version ?? "dev";
 }
 /**
- * Health endpoint — truly public, returns only { ok: true }.
+ * Health endpoint — truly public. Identity-free; no auth, no role check.
  *
  * `allowRead() { return true }` opens Harper's role gate for anonymous GETs,
  * which is what makes /Health work for callers outside `authorizeLocal`'s
@@ -66,8 +69,15 @@ function resolveVersion() {
  *
  * Same pattern as `FederationPair.allowCreate(){ return true }` (PR #299):
  * declare the Resource anonymously-accessible at the Harper layer; let the
- * handler itself enforce whatever it needs (in this case, nothing — /Health
- * is intentionally and always public).
+ * handler itself enforce whatever it needs.
+ *
+ * flair#1326: `ok: true` used to mean only "this resource answered." That
+ * is a green light that lies when search routes are not mounted yet, or
+ * when the hybrid BM25 index is still cold (first search after restart
+ * scans the corpus; the lag grows with store size). `searchReady` is
+ * always present. When search cannot be served at all, this endpoint
+ * returns HTTP 503 and `ok: false`. When the process is live but recall
+ * is still cold, it stays 200 and names the lag on `searchReadyReason`.
  *
  * Rich stats (memory counts, agent names, etc.) are behind /HealthDetail
  * which requires authentication. This prevents information leakage on
@@ -96,13 +106,39 @@ export class Health extends Resource {
         // a 40-hex sha when the build ran in a git work tree, an honest null
         // otherwise (tarball builds) — never omitted, never fabricated (Sherlock).
         const build = resolveBuildInfo();
-        return {
-            ok: true,
+        const readiness = currentSearchReadiness();
+        const body = buildPublicHealthBody(readiness, {
             version: build?.version ?? resolveVersion(),
             buildCommit: build?.commit ?? null,
-        };
+        });
+        if (readiness.status !== 200) {
+            return new Response(JSON.stringify(body), {
+                status: readiness.status,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        return body;
     }
 }
+/** Same sources /Health and /HealthDetail consult so they cannot disagree. */
+let _warnedMissingRegistry = false;
+function currentSearchReadiness() {
+    // Shipped Harper launch: this Resource is already registered, so
+    // server.resources is populated. The null skip is a stated fail-open
+    // (Sherlock on #1406) for the injectable/test path — not an accident.
+    const resources = server.resources ?? null;
+    if (!resources && !_warnedMissingRegistry) {
+        _warnedMissingRegistry = true;
+        logger.warn?.("Health: server.resources is absent — skipping the search-route mount check (table-only fail-open). Shipped Harper launch always exposes the registry.");
+    }
+    return resolveSearchReadiness({
+        resources,
+        memoryTable: db.flair?.Memory,
+        bm25: bm25IndexStatus(),
+        hybridEnabled: hybridEnabled(),
+        bm25IndexEnabled: bm25IndexEnabled(),
+    });
+}
 /**
  * Authenticated health detail — returns memory/agent/soul stats + process info.
  * Requires Ed25519 agent auth or admin basic auth.
@@ -127,6 +163,15 @@ export class HealthDetail extends Resource {
         const stats = { ok: true };
         const nowMs = Date.now();
         const warnings = [];
+        // flair#1326: same search-ready signal as public /Health. HealthDetail
+        // stays HTTP 200 (it is a stats dump, not a traffic gate); the field
+        // and a warning name the lag so `flair status` / operators can see it.
+        const readiness = currentSearchReadiness();
+        stats.searchReady = readiness.searchReady;
+        if (readiness.searchReadyReason) {
+            stats.searchReadyReason = readiness.searchReadyReason;
+            warnings.push({ level: "warn", message: readiness.searchReadyReason });
+        }
         const ctx = this.getContext?.();
         // #614 fix: resolve identity via the shared three-way verdict
         // (internal/agent/anonymous — agent-auth.ts) instead of reading

package/dist/resources/mcp-tools.js

@@ -811,6 +811,7 @@ export const TOOLS = {
                     { count: "memoriesIncluded", containers: ["memories", "predicted"] }, // #1199
                     { count: "teammateFindingsIncluded", containers: ["teammateFindings"] }, // #1199
                     { count: "sections.events", containers: ["events"] }, // #1206
+                    { count: "sections.soul", containers: ["soul"] }, // #1371
                 ],
                 // present + typed even when empty — never a bare {} / missing key (#1182).
                 selfDescribingEmpty: [

package/dist/resources/search-readiness.js

@@ -0,0 +1,100 @@
+/**
+ * search-readiness.ts — the honest /Health search-ready signal (flair#1326).
+ *
+ * Harper's process can answer /health (and Flair's /Health resource can
+ * answer {ok:true}) while search is still unusable:
+ *
+ *   1. Boot window — jsResources register incrementally. /Health can be up
+ *      while /Memory and /SemanticSearch still 404 from Harper's catch-all
+ *      (documented in packages/adk-flair-js/test/helpers/boot-harper.mjs).
+ *   2. Cold BM25 index — hybrid retrieval's persistent index is lazy-built
+ *      on the first search, not at component start (bm25-index-service.ts).
+ *      That first-query corpus scan grows with store size. /Health answering
+ *      is not "recall is warm."
+ *
+ * This module is Harper-free so the decision is unit-testable against the
+ * shipped function. Callers inject the registry / table / index status they
+ * already have.
+ *
+ * Two layers, on purpose:
+ *   - Routes/table not mounted → not healthy (ok:false, HTTP 503). A
+ *     traffic-gating probe that only looks at status must not get a green
+ *     light for a node whose search routes are not serving.
+ *   - Routes up but index still cold → process is live (ok:true, HTTP 200)
+ *     and searchReady:false names the lag. We do NOT 503 on a cold index:
+ *     the index builds on the first search, and a health check must not
+ *     trigger that scan (bm25-index-service.ts: "Eager building would add a
+ *     full corpus scan to every boot including … health checks"). 503-until-
+ *     warm would deadlock — health waits for the index, the index waits for
+ *     a search that never comes.
+ */
+function routeMounted(resources, name) {
+    const entry = resources.get?.(name) ?? resources.getMatch?.(name);
+    return Boolean(entry?.Resource);
+}
+/**
+ * Decide whether search is actually usable, and whether /Health should claim
+ * the process is healthy.
+ *
+ * `resources` is optional. Stated fail-open (Sherlock on #1406): when the
+ * registry is missing we skip the route-mount check rather than 503 forever.
+ * A table handle can exist while `/Memory` and `/SemanticSearch` still 404,
+ * so this is weaker than the primary defense. In the shipped launch path
+ * `/Health` is served by this Resource after Harper has registered us, so
+ * `server.resources` is populated; the skip is the injectable/test path
+ * (and a theoretical export without a registry). Health.ts logs once if
+ * the live call site actually takes it.
+ */
+export function resolveSearchReadiness(opts) {
+    if (opts.resources) {
+        const memoryMounted = routeMounted(opts.resources, "Memory");
+        const searchMounted = routeMounted(opts.resources, "SemanticSearch");
+        if (!memoryMounted || !searchMounted) {
+            const missing = [
+                !memoryMounted ? "Memory" : null,
+                !searchMounted ? "SemanticSearch" : null,
+            ].filter(Boolean).join(", ");
+            return notServing(`search routes not mounted (${missing})`);
+        }
+    }
+    if (!opts.memoryTable || typeof opts.memoryTable.search !== "function") {
+        return notServing("memory table not queryable");
+    }
+    // Hybrid + the persistent index are default-on. A cold or in-flight BM25
+    // index means the first search will pay a full corpus scan — the #1326
+    // lag. Name it; do not fail liveness.
+    //
+    // `disabled` (feed/build failure) and `FLAIR_BM25_INDEX=false` both fall
+    // back to the per-query scan. The kill switch never calls ensureReady, so
+    // status stays `empty` for the life of the process — that is serving, not
+    // cold. Treating it as lag would make searchReady false forever and refuse
+    // a node that is already answering recall.
+    const indexInPath = opts.hybridEnabled !== false && opts.bm25IndexEnabled !== false;
+    if (indexInPath && opts.bm25) {
+        if (opts.bm25.state === "building") {
+            return namesLag("bm25 index building — first search is still scanning the corpus");
+        }
+        if (opts.bm25.state === "empty") {
+            return namesLag("bm25 index not built (cold boot; first search scans the corpus)");
+        }
+    }
+    return { searchReady: true, ok: true, status: 200 };
+}
+function notServing(searchReadyReason) {
+    return { searchReady: false, ok: false, status: 503, searchReadyReason };
+}
+function namesLag(searchReadyReason) {
+    return { searchReady: false, ok: true, status: 200, searchReadyReason };
+}
+/** Public /Health JSON body. `searchReady` is always present (never omitted). */
+export function buildPublicHealthBody(readiness, identity) {
+    const body = {
+        ok: readiness.ok,
+        version: identity.version,
+        buildCommit: identity.buildCommit,
+        searchReady: readiness.searchReady,
+    };
+    if (readiness.searchReadyReason)
+        body.searchReadyReason = readiness.searchReadyReason;
+    return body;
+}

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

@@ -60,6 +60,7 @@ import { compositeScore } from "./scoring.js";
 import { buildBM25, fuseRrfNormalized, SEM_LIMIT } from "./bm25.js";
 import { isAllowedBm25Candidate } from "./bm25-filter.js";
 import { indexedBm25Ids } from "./bm25-index-service.js";
+import { byRecencyThenId } from "./sort-comparators.js";
 // Convert HNSW cosine distance (1 - similarity) to similarity score.
 function distanceToSimilarity(distance) {
     return 1 - distance;
@@ -484,7 +485,14 @@ export async function retrieveCandidates(params) {
     // 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);
+    //
+    // Ties at this sort are cross-leg RRF identities (flair#1412): no
+    // within-leg tie-break can prevent `1/(k+3)+1/(k+5) === 1/(k+5)+1/(k+3)`.
+    // Break them by createdAt DESC (null → oldest, never NaN) then id ASC.
+    // Determinism is the id ASC total order. createdAt is best-effort recency
+    // within an exact `_rank` tie — federated writer clocks can skew, and
+    // that cannot reintroduce nondeterminism (see byRecencyThenId).
+    filteredResults.sort((a, b) => (b._rank - a._rank) || byRecencyThenId(a, b));
     for (const r of filteredResults)
         delete r._rank;
     return filteredResults;

package/dist/resources/sort-comparators.js

@@ -0,0 +1,45 @@
+/**
+ * Deterministic sort comparators (flair#1412).
+ *
+ * Retrieval and selection sorts used to key on one number (score, rank,
+ * priority) and then inherit `Array.prototype.sort`'s input order on ties.
+ * That input order is Harper scan order, which is free to change across
+ * restarts. The family below makes the tie-break the default thing to
+ * reach for: each helper has its own primary key, and they share the
+ * `compareKey` tail — not one comparator forced onto every site.
+ *
+ * Do not collapse this into a single `byScoreThenId`. cosine.ts keys on
+ * corpus `.index`; MemoryBootstrap (flair#1409, not this PR) keys on the
+ * soul `key`. The shared part is the tail.
+ *
+ * Locale-independent: `compareKey` is code-unit / numeric `<`/`>`, never
+ * `localeCompare`. ISO-8601 UTC strings compare chronologically that way.
+ */
+/** Total-order tail. Works for ids, corpus indexes, soul keys. */
+export function compareKey(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Score / rank descending, then `id` ascending. */
+export function byNumberDescThenId(getNumber) {
+    return (a, b) => (getNumber(b) - getNumber(a)) || compareKey(a.id, b.id);
+}
+/**
+ * `createdAt` DESC (null → oldest, never NaN) then `id` ASC.
+ *
+ * Determinism comes from `id` ASC — ids are unique, so this is a total
+ * order no matter what `createdAt` does. Do not date-arithmetic a
+ * possibly-null field: `new Date(null).getTime()` is 0, but subtracting
+ * NaN (unparseable / missing-after-coercion) is undefined behaviour for
+ * `Array.prototype.sort`. Empty-string fallback keeps the comparison in
+ * string space; an empty value is less than any ISO-8601 UTC timestamp,
+ * so it sorts last under DESC.
+ *
+ * Clock-skew caveat: `createdAt` is writer-stamped. Across federated
+ * writers this is best-effort recency within an exact `_rank` tie, not a
+ * correctness claim. Skew can misorder rows the ranker already called
+ * equivalent; it cannot reintroduce nondeterminism, because `id` ASC
+ * still resolves every remaining tie.
+ */
+export function byRecencyThenId(a, b) {
+    return compareKey(b.createdAt ?? "", a.createdAt ?? "") || compareKey(a.id, b.id);
+}

package/dist/src/lib/scheduler-platform.js

@@ -20,9 +20,9 @@
  * in `verifyFirstRun()`: success may not be claimed until the thing the
  * operator asked for has been observed to happen once.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { resolve, dirname, isAbsolute } from "node:path";
-import { platform } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, realpathSync } from "node:fs";
+import { resolve, dirname, isAbsolute, basename } from "node:path";
+import { platform, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 /**
  * 30s ceiling on launchctl/systemctl invocations so a hung service manager
@@ -90,20 +90,71 @@ export function interpretActiveResult(plat, code, stdout, stderr) {
         return null; // spawn itself failed — inconclusive
     return false; // covers the no-bus case: empty stdout, nonzero/failed exit
 }
+/** True when this session already has the env `systemctl --user` needs. */
+export function sessionHasUserBusEnv(env = process.env) {
+    return Boolean(env.XDG_RUNTIME_DIR?.trim() && env.DBUS_SESSION_BUS_ADDRESS?.trim());
+}
+/**
+ * Reads whether lingering is already enabled for the current user.
+ * `loginctl show-user … Linger=yes` is the official answer; the stamp file
+ * `loginctl enable-linger` creates is the fallback when loginctl is missing
+ * or inconclusive. A failed probe is `null`, never linger-off — inventing
+ * linger-off would repeat the linger remedy after it already ran (#1107).
+ */
+export function probeUserLingerEnabled(opts = {}) {
+    const run = opts.run ?? spawnReport;
+    const lingerStampExists = opts.lingerStampExists ?? ((u) => existsSync(`/var/lib/systemd/linger/${u}`));
+    let user = "";
+    try {
+        user = userInfo().username;
+    }
+    catch {
+        user = process.env.USER || process.env.LOGNAME || "";
+    }
+    if (!user)
+        return null;
+    const r = run(["loginctl", "show-user", user, "--property=Linger"], STATUS_CHECK_TIMEOUT_MS);
+    const m = /^Linger=(yes|no)\s*$/m.exec(r.stdout ?? "");
+    if (m)
+        return m[1] === "yes";
+    if (lingerStampExists(user))
+        return true;
+    return null;
+}
 /**
- * Human remedy text for a failed scheduler-load attempt (flair#850). Covers
- * the one root cause traced so far: a missing systemd user session bus,
- * which blocks `systemctl --user` entirely in ssh-without-lingering,
- * container, and CI contexts. Returns null when the failure doesn't match a
- * known pattern — the caller already prints the raw stderr, so the operator
- * still has something to go on.
+ * Human remedy text for a failed scheduler-load attempt (flair#850, #1107).
+ * Covers the traced "no systemd user session bus" failure, which blocks
+ * `systemctl --user` entirely in ssh-without-lingering, container, and CI
+ * contexts. Two cases that used to share one remedy:
+ *   (a) lingering genuinely off — print `loginctl enable-linger`
+ *   (b) linger already on, this session has no user-bus env — print the
+ *       `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` export lines
+ * Repeating (a) after the operator has applied it is the #1107 lie.
+ * Returns null when the failure doesn't match a known pattern — the caller
+ * already prints the raw stderr, so the operator still has something to go on.
  *
  * `enableCommand` is the caller's own enable invocation, named in the remedy
  * so the operator is told to re-run the command they actually ran.
  */
-export function describeLoadFailure(plat, loadResult, enableCommand) {
+export function describeLoadFailure(plat, loadResult, enableCommand, session) {
     const stderr = loadResult.stderr || "";
     if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        if (session?.lingerEnabled === true) {
+            const env = session.env ?? process.env;
+            if (!sessionHasUserBusEnv(env)) {
+                return ("No systemd user session bus is available in this session. Lingering is already enabled — " +
+                    "do not re-run `loginctl enable-linger`. The remaining gap is this session's user-bus environment. " +
+                    "Export:\n" +
+                    "     export XDG_RUNTIME_DIR=/run/user/$(id -u)\n" +
+                    "     export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus\n" +
+                    `   then re-run \`${enableCommand}\`.`);
+            }
+            return ("No systemd user session bus is available in this session. Lingering is already enabled and " +
+                "this session already has XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS — " +
+                "do not re-run `loginctl enable-linger` or re-export those variables. " +
+                "Check that `$XDG_RUNTIME_DIR/bus` exists (the systemd --user instance may not be running), " +
+                `then re-run \`${enableCommand}\`.`);
+        }
         return ("No systemd user session bus is available in this session (common over ssh without lingering, " +
             "in containers, or under CI). Fix: enable lingering for this user — `loginctl enable-linger <user>` " +
             `— then re-run \`${enableCommand}\`.`);
@@ -172,6 +223,77 @@ export function resolveNodeBin(explicit) {
         "enable time — refusing to install a shim that would resolve `node` from the service manager's PATH " +
         "at run time. Install node (or put it on PATH for this shell) and re-run enable.");
 }
+/**
+ * Resolves the path enable will bake as FLAIR_BIN, and whether that path is
+ * the stable public `flair` entry (flair#1279).
+ *
+ * Resolution order:
+ *   1. `explicit` — caller/test override. Relatives are resolved against cwd.
+ *   2. `hooks.argv1` / `process.argv[1]` — whatever launched enable.
+ *   3. The public `flair` on PATH, only when (1) and (2) are empty.
+ * Nothing absolute resolvable ⇒ throw. A bare `"flair"` is not an exec
+ * target under #1231's `exec <node> <script>` form (`node flair` looks in
+ * cwd, not PATH).
+ */
+export function resolveFlairBin(explicit, hooks) {
+    const publicBin = hooks && "publicBin" in hooks ? (hooks.publicBin ?? null) : lookupPublicFlairBin();
+    const captured = explicit ?? hooks?.argv1 ?? process.argv[1];
+    let path;
+    if (typeof captured === "string" && captured.length > 0) {
+        path = isAbsolute(captured) ? captured : resolve(captured);
+    }
+    else if (publicBin) {
+        path = publicBin;
+    }
+    else {
+        throw new Error("unable to resolve an absolute path to the flair CLI (process.argv[1] was empty and `command -v flair` " +
+            "found nothing). The scheduler shim bakes this path in at enable time — refusing to install a shim " +
+            "whose exec target is unknown. Re-run enable via the `flair` command.");
+    }
+    return { path, publicBin, canonical: isCanonicalFlairBin(path, publicBin) };
+}
+/** True when `baked` is the public `flair` entry, not a working-tree capture. */
+export function isCanonicalFlairBin(baked, publicBin) {
+    if (basename(baked) === "flair")
+        return true;
+    if (publicBin && pathsReferToSameFile(baked, publicBin))
+        return true;
+    return false;
+}
+/**
+ * The enable-report lines for a non-canonical FLAIR_BIN. Empty when the
+ * baked path is the public entry — callers should not print a warning then.
+ */
+export function formatFlairBinWarning(baked, publicBin, enableCommand) {
+    if (isCanonicalFlairBin(baked, publicBin))
+        return [];
+    const lines = [
+        `⚠️  FLAIR_BIN is ${baked} — that is the process that ran enable, not a stable public entry.`,
+        `   A later blue/green directory swap, or deleting this working tree, will strand the scheduler unit.`,
+    ];
+    if (publicBin) {
+        lines.push(`   Public \`flair\` on PATH: ${publicBin}. Re-run \`${enableCommand}\` as the \`flair\` command to bake that path instead.`);
+    }
+    else {
+        lines.push(`   No \`flair\` on PATH. Re-run \`${enableCommand}\` via the installed \`flair\` command (or a stable symlink) so the baked path survives a tree swap.`);
+    }
+    return lines;
+}
+function lookupPublicFlairBin() {
+    const r = spawnReport(["/bin/sh", "-c", "command -v flair"], STATUS_CHECK_TIMEOUT_MS);
+    const found = r.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (r.code === 0 && found && isAbsolute(found) && existsSync(found))
+        return found;
+    return null;
+}
+function pathsReferToSameFile(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
 // ─── first-run verification (flair#1231) ────────────────────────────────────
 // A load/bootstrap command exiting 0 proves the service manager accepted the
 // job — not that the job can run. The only vantage that exercises the real