@tpsdev-ai/flair 0.53.0 → 0.54.1

package/dist/lib/owned-pins.js

@@ -0,0 +1,219 @@
+/**
+ * owned-pins.ts — flair#1485
+ *
+ * The single catalogue of files `flair init` / `flair hook install` write a
+ * pinned `@tpsdev-ai/flair-mcp@<version>` into. `flair upgrade` refreshes
+ * every entry that is already wired; `flair doctor` reads the same list to
+ * decide whether a pin is current.
+ *
+ * Two kinds:
+ *   mcp-client         — ALL_CLIENTS kind:"mcp" config paths
+ *   session-start-hook — SUPPORTED_HARNESSES hook settings paths
+ *
+ * Adding a client to ALL_CLIENTS or a harness to SUPPORTED_HARNESSES adds
+ * it here automatically — no second list to forget on the next upgrade.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { ALL_CLIENTS, clientConfigPath, } from "../install/clients.js";
+import { checkSessionStartHook, extractFlairMcpPin, isFlairHookCommand, readClientMcpBlock, } from "../doctor-client.js";
+import { hookInstallHint, hookSettingsPath, repinSessionStartHook, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { flairCliVersion, isResolvedVersion } from "./mcp-spec.js";
+function withHome(homeDir, fn) {
+    const prev = process.env.HOME;
+    process.env.HOME = homeDir;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prev;
+    }
+}
+function displayHomePath(homeDir, path) {
+    if (path.startsWith(homeDir))
+        return "~" + path.slice(homeDir.length);
+    return path;
+}
+/**
+ * Every file Flair pins. Order: MCP clients (registry order), then hooks
+ * (harness registry order). Upgrade and doctor both iterate this.
+ */
+export function listOwnedPinTargets(homeDir) {
+    return withHome(homeDir, () => {
+        const targets = [];
+        for (const client of ALL_CLIENTS) {
+            if (client.kind !== "mcp")
+                continue;
+            const path = clientConfigPath(client.id);
+            targets.push({
+                kind: "mcp-client",
+                id: client.id,
+                path,
+                displayPath: displayHomePath(homeDir, path),
+            });
+        }
+        for (const harness of SUPPORTED_HARNESSES) {
+            const path = hookSettingsPath(homeDir, harness);
+            targets.push({
+                kind: "session-start-hook",
+                id: harness,
+                path,
+                displayPath: displayHomePath(homeDir, path),
+            });
+        }
+        return targets;
+    });
+}
+function readFileText(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readOwnedPin(target, homeDir) {
+    if (target.kind === "session-start-hook") {
+        const hook = checkSessionStartHook(homeDir, target.path);
+        const present = !!(hook.present && hook.command && isFlairHookCommand(hook.command));
+        return {
+            target,
+            present,
+            pin: present ? extractFlairMcpPin(hook.command ?? "") : null,
+        };
+    }
+    const block = readClientMcpBlock(target.id, homeDir);
+    const text = readFileText(target.path) ?? "";
+    return {
+        target,
+        present: block.present,
+        pin: block.present ? extractFlairMcpPin(text) : null,
+    };
+}
+export function readOwnedPins(homeDir) {
+    return listOwnedPinTargets(homeDir).map((t) => readOwnedPin(t, homeDir));
+}
+/**
+ * Wired pins whose concrete version is not the installed CLI version.
+ * Unpinned / absent entries are not stale — they are a different check.
+ */
+export function staleOwnedPins(homeDir, expectedVersion = flairCliVersion()) {
+    if (!isResolvedVersion(expectedVersion))
+        return [];
+    return readOwnedPins(homeDir).filter((r) => r.present && r.pin !== null && r.pin !== expectedVersion);
+}
+export function staleSessionStartHookPins(homeDir, expectedVersion = flairCliVersion()) {
+    return staleOwnedPins(homeDir, expectedVersion).filter((r) => r.target.kind === "session-start-hook");
+}
+export function staleMcpClientPins(homeDir, expectedVersion = flairCliVersion()) {
+    return staleOwnedPins(homeDir, expectedVersion).filter((r) => r.target.kind === "mcp-client");
+}
+/**
+ * What `flair upgrade` prints from a refresh result.
+ *
+ * A failed `client.wire` is `action: "skip"` + `ok: false` (same shape as a
+ * fail-closed hook re-pin). Filtering on `action !== "skip"` alone dropped
+ * that failure, left the pin stale, and printed nothing (Bugbot on #1485).
+ * Failures always surface. MCP no-ops/updates still print; hook no-ops stay quiet.
+ */
+export function ownedPinRefreshShouldReport(r) {
+    if (!r.ok)
+        return true;
+    if (r.target.kind === "mcp-client")
+        return r.action !== "skip";
+    return r.action === "update";
+}
+export function staleHookRemedy(readings) {
+    const harnesses = readings
+        .filter((r) => r.target.kind === "session-start-hook")
+        .map((r) => r.target.id);
+    if (harnesses.length === 0)
+        return "flair hook install";
+    return [...new Set(harnesses)].map((h) => hookInstallHint(h)).join(" ; ");
+}
+/**
+ * Refresh every already-wired owned pin to the running CLI's spec.
+ *
+ * MCP client pins need `agentId` (the wire functions rewrite the env block).
+ * SessionStart hooks do not — `repinSessionStartHook` reads the agent from
+ * the existing command. A missing agentId therefore skips MCP only; it must
+ * not skip hooks (that was the early-return hole in the inline upgrade path).
+ *
+ * NEVER adds a hook or wires a new client.
+ */
+export function refreshOwnedPins(opts) {
+    const { homeDir } = opts;
+    const flairUrl = opts.flairUrl ?? "http://127.0.0.1:9926";
+    const agentId = opts.agentId ?? null;
+    const targets = listOwnedPinTargets(homeDir);
+    const results = [];
+    return withHome(homeDir, () => {
+        for (const target of targets) {
+            if (target.kind === "session-start-hook") {
+                const harness = target.id;
+                const repin = repinSessionStartHook(homeDir, harness);
+                results.push({
+                    target,
+                    action: repin.action,
+                    ok: repin.ok,
+                    message: repin.message,
+                });
+                continue;
+            }
+            const block = readClientMcpBlock(target.id, homeDir);
+            if (!block.present) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: not wired — skip`,
+                });
+                continue;
+            }
+            if (!agentId) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: no agent id — skip MCP pin refresh`,
+                });
+                continue;
+            }
+            const client = ALL_CLIENTS.find((c) => c.id === target.id);
+            if (!client) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: not in client registry — skip`,
+                });
+                continue;
+            }
+            const env = {
+                FLAIR_AGENT_ID: agentId,
+                FLAIR_URL: flairUrl,
+                FLAIR_CLIENT: target.id,
+            };
+            const before = extractFlairMcpPin(readFileText(target.path) ?? "");
+            const wired = client.wire(env);
+            const after = extractFlairMcpPin(readFileText(target.path) ?? "");
+            // Failed write stays skip+ok:false (fail-closed, like hook re-pin).
+            // ownedPinRefreshShouldReport treats !ok as printable — do not recode
+            // this as a quiet skip.
+            const action = !wired.ok ? "skip"
+                : before !== after ? "update"
+                    : "noop";
+            results.push({
+                target,
+                action,
+                ok: wired.ok,
+                message: wired.message,
+            });
+        }
+        return results;
+    });
+}

package/dist/lib/uninstall-purge.js

@@ -0,0 +1,218 @@
+/**
+ * uninstall-purge.ts — flair#853
+ *
+ * `flair uninstall --purge` used to delete only `~/.flair/data` and
+ * `~/.flair/keys`, then print "Flair fully purged". That left the admin
+ * password, backups/logs/upgrade-snapshots, the REM nightly shim, client
+ * MCP/hook wiring, and the systemd/launchd scheduler units — a secret and
+ * a job that can resurrect on reinstall.
+ *
+ * This module is the purge body. The CLI stops the Harper service, then
+ * calls `purgeFlairInstall`. Docs say purge removes everything including
+ * data and keys; this does that, plus secrets, schedulers, and client
+ * wiring. The npm package is an intentional leftover: this CLI cannot
+ * uninstall itself. The report always names leftovers instead of claiming
+ * "fully purged" when anything remains.
+ */
+import { existsSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ALL_CLIENTS } from "../install/clients.js";
+import { uninstallContinuityHooks, uninstallHook, harnessSupportsContinuity, hookBackupPath, hookSettingsPath, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { disableScheduler as disableRemScheduler, LAUNCHD_LABEL as REM_LAUNCHD_LABEL, SYSTEMD_SERVICE_UNIT as REM_SYSTEMD_SERVICE, SYSTEMD_TIMER_UNIT as REM_SYSTEMD_TIMER, } from "../rem/scheduler.js";
+import { disableScheduler as disableFederationScheduler, LAUNCHD_LABEL as FED_LAUNCHD_LABEL, SYSTEMD_SERVICE_UNIT as FED_SYSTEMD_SERVICE, SYSTEMD_TIMER_UNIT as FED_SYSTEMD_TIMER, } from "../federation/scheduler.js";
+/** The published CLI package. Named here so the leftover line cannot drift
+ *  from the remedy command. */
+export const FLAIR_NPM_PACKAGE = "@tpsdev-ai/flair";
+function resolveHome(homeDir) {
+    return homeDir ?? process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+function withHome(homeDir, fn) {
+    const prev = process.env.HOME;
+    process.env.HOME = homeDir;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prev;
+    }
+}
+function displayUnderHome(homeDir, absPath) {
+    if (absPath.startsWith(homeDir))
+        return "~" + absPath.slice(homeDir.length);
+    return absPath;
+}
+function rmPath(absPath, removed, leftovers, display) {
+    if (!existsSync(absPath))
+        return;
+    try {
+        rmSync(absPath, { recursive: true, force: true });
+        removed.push(display);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        leftovers.push({
+            path: display,
+            kind: "failed",
+            reason: `could not remove: ${reason}`,
+        });
+    }
+}
+function schedulerPaths(homeDir, spec) {
+    return [
+        join(homeDir, ".flair", "bin", spec.shimName),
+        join(homeDir, "Library", "LaunchAgents", `${spec.launchdLabel}.plist`),
+        join(homeDir, ".config", "systemd", "user", spec.systemdTimer),
+        join(homeDir, ".config", "systemd", "user", spec.systemdService),
+    ];
+}
+function disableAndSweepScheduler(homeDir, skipUnload, kind, removed, leftovers) {
+    const spec = kind === "rem"
+        ? {
+            shimName: "flair-rem-nightly",
+            launchdLabel: REM_LAUNCHD_LABEL,
+            systemdTimer: REM_SYSTEMD_TIMER,
+            systemdService: REM_SYSTEMD_SERVICE,
+            disable: disableRemScheduler,
+        }
+        : {
+            shimName: "flair-federation-sync",
+            launchdLabel: FED_LAUNCHD_LABEL,
+            systemdTimer: FED_SYSTEMD_TIMER,
+            systemdService: FED_SYSTEMD_SERVICE,
+            disable: disableFederationScheduler,
+        };
+    const paths = schedulerPaths(homeDir, spec);
+    try {
+        spec.disable({
+            skipUnload,
+            removeShim: true,
+            shimPathOverride: paths[0],
+            launchdPlistOverride: paths[1],
+            systemdTimerOverride: paths[2],
+            systemdServiceOverride: paths[3],
+        });
+    }
+    catch {
+        // File sweep below still runs — unload failure must not keep units on disk.
+    }
+    for (const abs of paths) {
+        rmPath(abs, removed, leftovers, displayUnderHome(homeDir, abs));
+    }
+}
+/**
+ * `uninstallHook` / `uninstallContinuityHooks` copy the settings file to a
+ * sibling `.bak` whenever it exists — including on a no-op. Purge must not
+ * leave that copy (or a pre-existing `.bak` it just overwrote). flair#853
+ * Bugbot: only deleting the bak after an actual remove left
+ * `~/.claude/settings.json.bak` / `~/.codex/hooks.json.bak` behind.
+ */
+function sweepHookBackup(settingsPath, reportedBackup, homeDir, removed, leftovers) {
+    const candidates = new Set();
+    if (reportedBackup)
+        candidates.add(reportedBackup);
+    candidates.add(hookBackupPath(settingsPath));
+    for (const bak of candidates) {
+        rmPath(bak, removed, leftovers, displayUnderHome(homeDir, bak));
+    }
+}
+/**
+ * Remove Flair-owned state under `homeDir`: the `~/.flair` tree (data, keys,
+ * admin-pass, backups, logs, snapshots, shims), REM + federation scheduler
+ * units on both platforms, SessionStart/continuity hooks, and MCP/native
+ * client wiring. The npm package is listed as an intentional leftover
+ * unless `omitNpmLeftover` is set.
+ */
+export function purgeFlairInstall(opts = {}) {
+    const homeDir = resolveHome(opts.homeDir);
+    const skipUnload = !!opts.skipSchedulerUnload;
+    const removed = [];
+    const leftovers = [];
+    disableAndSweepScheduler(homeDir, skipUnload, "rem", removed, leftovers);
+    disableAndSweepScheduler(homeDir, skipUnload, "federation", removed, leftovers);
+    for (const harness of SUPPORTED_HARNESSES) {
+        const hook = uninstallHook({ homeDir, harness });
+        if (!hook.ok) {
+            leftovers.push({ path: hook.path, kind: "failed", reason: hook.message });
+        }
+        else if (hook.delta && hook.delta.action !== "noop") {
+            removed.push(displayUnderHome(homeDir, hook.path) + " (SessionStart hook)");
+        }
+        sweepHookBackup(hook.path, hook.backupPath, homeDir, removed, leftovers);
+        if (!harnessSupportsContinuity(harness))
+            continue;
+        const continuity = uninstallContinuityHooks({ homeDir, harness });
+        if (!continuity.ok) {
+            leftovers.push({ path: continuity.path, kind: "failed", reason: continuity.message });
+        }
+        else if (continuity.actions && (continuity.actions.PostToolUse === "remove" || continuity.actions.Stop === "remove")) {
+            removed.push(displayUnderHome(homeDir, continuity.path) + " (continuity hooks)");
+        }
+        sweepHookBackup(continuity.path, continuity.backupPath, homeDir, removed, leftovers);
+    }
+    // Pre-existing sibling backups (or a harness we skipped) must not survive.
+    for (const harness of SUPPORTED_HARNESSES) {
+        sweepHookBackup(hookSettingsPath(homeDir, harness), null, homeDir, removed, leftovers);
+    }
+    const unwireResults = withHome(homeDir, () => ALL_CLIENTS.map((c) => c.unwire()));
+    for (const u of unwireResults) {
+        if (!u.ok) {
+            leftovers.push({ path: u.message, kind: "failed", reason: u.message });
+        }
+        else if (u.removed) {
+            removed.push(u.message);
+        }
+    }
+    const flairDir = join(homeDir, ".flair");
+    rmPath(flairDir, removed, leftovers, "~/.flair");
+    if (existsSync(flairDir)) {
+        leftovers.push({
+            path: "~/.flair",
+            kind: "failed",
+            reason: "directory still present after purge",
+        });
+    }
+    if (!opts.omitNpmLeftover) {
+        leftovers.push({
+            path: FLAIR_NPM_PACKAGE,
+            kind: "intentional",
+            reason: "this CLI cannot uninstall itself",
+            remedy: `npm uninstall -g ${FLAIR_NPM_PACKAGE}`,
+        });
+    }
+    return { removed, leftovers };
+}
+export function formatPurgeReport(result) {
+    const lines = [];
+    for (const item of result.removed) {
+        lines.push(`✅ Removed: ${item}`);
+    }
+    const failed = result.leftovers.filter((l) => l.kind === "failed");
+    const intentional = result.leftovers.filter((l) => l.kind === "intentional");
+    for (const item of failed) {
+        lines.push(`⚠️  Left (failed): ${item.path} — ${item.reason}`);
+    }
+    if (failed.length === 0 && intentional.length === 0) {
+        lines.push("");
+        lines.push("🗑️  Flair fully purged");
+        return { lines, claimedFullyPurged: true };
+    }
+    lines.push("");
+    lines.push("🗑️  Flair purged (data, keys, secrets, schedulers, and client wiring)");
+    if (intentional.length > 0) {
+        lines.push("");
+        lines.push("Intentionally left:");
+        for (const item of intentional) {
+            lines.push(`  • ${item.path} — ${item.reason}`);
+            if (item.remedy)
+                lines.push(`    Remove with: ${item.remedy}`);
+        }
+    }
+    return { lines, claimedFullyPurged: false };
+}
+export function purgeHadFailures(result) {
+    return result.leftovers.some((l) => l.kind === "failed");
+}

package/dist/rem/restore.js

@@ -41,14 +41,12 @@ function asArray(raw) {
 function soulWrite(opts) {
     return opts.soulApiCall ?? opts.apiCall;
 }
-async function listAgentCandidates(apiCall, agentId) {
-    return asArray(await apiCall("POST", "/MemoryCandidate/search_by_conditions", {
-        operator: "and",
-        conditions: [
-            { search_attribute: "agentId", search_type: "equals", search_value: agentId },
-        ],
-        get_attributes: ["id", "claim"],
-    }));
+async function listAgentCandidates(opsSearch, agentId) {
+    if (!opsSearch)
+        return [];
+    return asArray(await opsSearch("MemoryCandidate", [
+        { search_attribute: "agentId", search_type: "equals", search_value: agentId },
+    ], ["id", "claim"]));
 }
 function parseJsonlSafe(text) {
     if (!text.trim())
@@ -142,7 +140,7 @@ export async function applySnapshot(opts) {
         try {
             const currentMem = asArray(await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`));
             const currentSouls = asArray(await opts.apiCall("GET", `/Soul?agentId=${encodeURIComponent(opts.agentId)}`));
-            const currentCandidates = await listAgentCandidates(opts.apiCall, opts.agentId);
+            const currentCandidates = await listAgentCandidates(opts.opsSearch, opts.agentId);
             result.deleted.memories = currentMem.length;
             result.deleted.souls = currentSouls.length;
             result.deleted.candidates = currentCandidates.length;
@@ -186,7 +184,7 @@ export async function applySnapshot(opts) {
     // so a leftover row 403s Soul PUT after operator auth succeeds.
     let currentCandidates = [];
     try {
-        currentCandidates = await listAgentCandidates(opts.apiCall, opts.agentId);
+        currentCandidates = await listAgentCandidates(opts.opsSearch, opts.agentId);
     }
     catch (err) {
         errors.push(`fetch-candidates: ${err?.message ?? String(err)}`);

package/dist/resources/AgentReadPosition.js

@@ -0,0 +1,74 @@
+/**
+ * AgentReadPosition.ts — HTTP surface for the per-agent read-position primitive.
+ *
+ * GET  /AgentReadPosition/{agentId}?stream=org-event
+ * POST /AgentReadPosition/{agentId}  { stream, position }
+ *
+ * Owner-scoped: an agent reads/advances only its own watermark. Admins and
+ * internal calls may act on any agent. The table itself is not @export.
+ */
+import { Resource } from "harper";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
+import { ORG_EVENT_STREAM } from "./agent-read-position-lib.js";
+import { advanceReadPosition, defaultReadPositionTable, getReadPosition, } from "./agent-read-position.js";
+function pathAgentId(pathInfo, resource) {
+    return ((typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : null) ??
+        (typeof pathInfo === "string" ? pathInfo : null) ??
+        resource?.getId?.() ??
+        null);
+}
+function queryValue(pathInfo, name) {
+    if (typeof pathInfo !== "object" || pathInfo === null)
+        return null;
+    return pathInfo.conditions?.find((c) => c.attribute === name)?.value ?? null;
+}
+function denyOwner() {
+    return new Response(JSON.stringify({ error: "forbidden: can only read or advance your own watermark" }), { status: 403, headers: { "Content-Type": "application/json" } });
+}
+function ownerDenied(auth, agentId) {
+    if (auth.kind === "anonymous")
+        return true;
+    if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== agentId)
+        return true;
+    return false;
+}
+export class AgentReadPosition extends Resource {
+    async allowRead() {
+        return allowVerified(this.getContext?.());
+    }
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async get(pathInfo) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        const agentId = pathAgentId(pathInfo, this);
+        if (!agentId) {
+            return new Response(JSON.stringify({ error: "agentId required in path: GET /AgentReadPosition/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        if (ownerDenied(auth, agentId))
+            return denyOwner();
+        const stream = queryValue(pathInfo, "stream") || ORG_EVENT_STREAM;
+        const ctx = this.getContext?.();
+        const position = await getReadPosition(defaultReadPositionTable(), agentId, stream, ctx);
+        return { agentId, stream, position };
+    }
+    async post(content, pathInfo) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        const agentId = pathAgentId(pathInfo, this) ??
+            (content && typeof content === "object" ? content.agentId : null) ??
+            null;
+        if (!agentId) {
+            return new Response(JSON.stringify({ error: "agentId required in path: POST /AgentReadPosition/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        if (ownerDenied(auth, agentId))
+            return denyOwner();
+        const stream = (content && typeof content === "object" && content.stream) || ORG_EVENT_STREAM;
+        const position = content && typeof content === "object" ? String(content.position ?? "") : "";
+        if (!position) {
+            return new Response(JSON.stringify({ error: "position required to advance watermark" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const ctx = this.getContext?.();
+        const result = await advanceReadPosition(defaultReadPositionTable(), agentId, stream, position, ctx);
+        return { agentId, stream, ...result };
+    }
+}

package/dist/resources/Federation.js

@@ -109,7 +109,9 @@ export function noteFederationMergedMemory(recordTable, mergedData) {
  * AdminInstance.ts/AdminDashboard.ts: this is an admin-view endpoint (peers
  * never call it during pairing — FederationPair.post() reads the Instance
  * table directly server-side to hand a peer our identity; this HTTP GET is
- * CLI tooling only).
+ * CLI tooling only). The spoke pair CLI must not GET this path to fill a
+ * missing pair publicKey (flair#822): allowRead is allowAdmin, and get()
+ * find-or-creates an Instance (that would invent a hub row; #839).
  */
 export class FederationInstance extends Resource {
     async allowRead() {
@@ -325,7 +327,11 @@ export class FederationPair extends Resource {
                 console.warn(`[federation] drop_user failed: ${err?.message} — cleanup sweep will retry`);
             }
         }
-        // Return our own identity for the peer to record
+        // Return our own identity for the peer to record. Already
+        // `{ id, publicKey, role }` when an Instance row exists (flair#213).
+        // `instance: null` means the hub has no FederationInstance — that is
+        // #839, not a pair-response-shape bug. The spoke must ERROR, never
+        // store publicKey:"" (flair#822).
         let ourInstance = null;
         try {
             for await (const i of databases.flair.Instance.search()) {

package/dist/resources/Memory.js

@@ -269,9 +269,10 @@ async function runDedupGate(ctx, content) {
     // miss a near-duplicate during that window. Bounded (the re-embed pass is
     // batched and finishes in minutes), self-healing once the pass completes,
     // and a missed dedup is a duplicate row, not data loss — quality, not
-    // correctness. Stage 1 (this PR) doesn't trigger this at all: no re-embed
-    // runs, so there's no mixed-space window until stage 2's separate,
-    // deliberate ops step.
+    // correctness. flair#1073: if that window lasts days (boot cycle marked
+    // embedding-stamp complete without converging), /HealthDetail names the
+    // outstanding migration and that duplicate detection is inactive — do
+    // not treat a long-lived split as this documented transient.
     let embedding = Array.isArray(content.embedding) ? content.embedding : null;
     if (!embedding) {
         try {