@tpsdev-ai/flair 0.28.0 → 0.30.0

package/dist/src/rem/scheduler.js

@@ -0,0 +1,449 @@
+/**
+ * REM nightly scheduler — platform-native scheduler install/uninstall.
+ *
+ * Per FLAIR-NIGHTLY-REM § 3 (`flair rem nightly enable|disable`). Renders
+ * launchd plist (macOS) or systemd timer+service (Linux) from templates,
+ * deploys a shim script to `~/.flair/bin/flair-rem-nightly`, and loads the
+ * job into the user-session scheduler.
+ *
+ * Templates use `{{KEY}}` placeholders — single-pass substitution. The full
+ * placeholder set is enumerated in `interface SchedulerSubstitutions` so
+ * adding a new key requires touching both this module and the template.
+ *
+ * No daemon code lives here — the scheduler invokes the shim, the shim
+ * invokes `flair rem nightly run-once`, the runner module does the work.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, rmSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+export const SHIM_PATH_DEFAULT = resolve(homedir(), ".flair", "bin", "flair-rem-nightly");
+export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist");
+export const SYSTEMD_USER_DIR = resolve(homedir(), ".config", "systemd", "user");
+export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.timer");
+export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.service");
+function detectPlatform(override) {
+    if (override)
+        return override;
+    const p = platform();
+    if (p === "darwin")
+        return "darwin";
+    if (p === "linux")
+        return "linux";
+    throw new Error(`unsupported platform for REM nightly scheduler: ${p} (only darwin and linux)`);
+}
+function defaultTemplateRoot() {
+    // Templates live alongside dist/ in the published package and alongside
+    // src/rem/ in the source tree. Walk up from this file until we find
+    // a directory containing templates/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "templates"),
+        resolve(here, "..", "..", "..", "templates"),
+        resolve(here, "..", "templates"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    throw new Error(`unable to locate templates directory (looked in: ${candidates.join(", ")})`);
+}
+export function renderTemplate(text, subs) {
+    return text.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
+        const value = subs[key];
+        if (value === undefined)
+            throw new Error(`unknown template placeholder: ${key}`);
+        return String(value);
+    });
+}
+export function readTemplate(rootDir, relativePath) {
+    const full = resolve(rootDir, relativePath);
+    if (!existsSync(full)) {
+        throw new Error(`template not found: ${full}`);
+    }
+    return readFileSync(full, "utf-8");
+}
+/**
+ * Validates the hour:minute schedule. Throws on invalid input rather than
+ * silently coercing — surface bad input at the install boundary.
+ */
+function validateSchedule(hour, minute) {
+    if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+        throw new Error(`hour must be an integer 0-23, got ${hour}`);
+    }
+    if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+        throw new Error(`minute must be an integer 0-59, got ${minute}`);
+    }
+}
+function buildSubstitutions(opts, shimPath, flairBin) {
+    validateSchedule(opts.hour, opts.minute);
+    if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
+        throw new Error(`invalid agent id: ${opts.agentId}`);
+    }
+    return {
+        FLAIR_BIN: flairBin,
+        SHIM_PATH: shimPath,
+        HOME: homedir(),
+        AGENT_ID: opts.agentId,
+        FLAIR_URL: opts.flairUrl,
+        HOUR: String(opts.hour),
+        HOUR_PAD: String(opts.hour).padStart(2, "0"),
+        MINUTE: String(opts.minute),
+        MINUTE_PAD: String(opts.minute).padStart(2, "0"),
+    };
+}
+function writeFileWithDir(path, contents, mode = 0o600) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, contents, { mode });
+}
+// 30s ceiling on launchctl/systemctl invocations so a hung service manager
+// can't block the CLI indefinitely. Sherlock #415 follow-up.
+const SPAWN_TIMEOUT_MS = 30_000;
+// Status-check spawns (launchctl print / systemctl is-active) return
+// near-instantly when the service manager is reachable, and fail fast (no
+// hang) when it isn't (e.g. "Failed to connect to bus"). A short ceiling
+// keeps `flair rem nightly status` and the Health endpoint responsive even
+// when the query is inconclusive.
+const STATUS_CHECK_TIMEOUT_MS = 5_000;
+function spawnReport(cmd, timeoutMs = SPAWN_TIMEOUT_MS) {
+    const r = spawnSync(cmd[0], cmd.slice(1), {
+        encoding: "buffer",
+        timeout: timeoutMs,
+    });
+    return {
+        code: r.status,
+        stdout: r.stdout?.toString("utf-8") ?? "",
+        stderr: r.stderr?.toString("utf-8") ?? "",
+    };
+}
+/**
+ * Command to genuinely query the platform scheduler's active/loaded state
+ * for a given install (as opposed to the shape of `loadCommand`, which
+ * *installs* it). Shared by the sync and async active-state checks below so
+ * the two can't drift.
+ */
+function activeCheckCommand(plat) {
+    if (plat === "darwin") {
+        return ["launchctl", "print", `gui/${process.getuid?.() ?? ""}/dev.flair.rem.nightly`];
+    }
+    return ["systemctl", "--user", "is-active", "flair-rem-nightly.timer"];
+}
+/**
+ * Interprets the result of `activeCheckCommand()`. Shared by the sync
+ * (CLI) and async (server) callers.
+ *
+ * - true  — the service manager confirms the job is loaded/active.
+ * - false — confirmed NOT active. This includes the "no session bus" case
+ *   (flair#850): when `systemctl --user` can't reach a bus, it fails
+ *   before printing a status word ("Failed to connect to bus: No medium
+ *   found") — but nothing CAN be running without a bus, so `false` is the
+ *   honest answer, not "unknown".
+ * - null  — genuinely inconclusive (the command itself couldn't run at
+ *   all — e.g. the binary is missing — with no output to interpret).
+ */
+export function interpretActiveResult(plat, code, stdout, stderr) {
+    const noOutput = !stdout.trim() && !stderr.trim();
+    if (plat === "darwin") {
+        if (code === 0)
+            return true;
+        if (code === null && noOutput)
+            return null; // spawn itself failed — inconclusive
+        return false; // launchctl ran and reported not-loaded
+    }
+    const out = stdout.trim();
+    if (out === "active" || out === "activating")
+        return true;
+    if (out === "inactive" || out === "failed" || out === "unknown")
+        return false;
+    if (code === null && noOutput)
+        return null; // spawn itself failed — inconclusive
+    return false; // covers the no-bus case: empty stdout, nonzero/failed exit
+}
+/**
+ * Synchronous active-state check for CLI use (`flair rem nightly status`).
+ * Blocking is fine here — this is a one-shot process and the caller wants
+ * the answer before printing anything.
+ */
+function queryActiveState(plat) {
+    const [cmd, ...args] = activeCheckCommand(plat);
+    const r = spawnReport([cmd, ...args], STATUS_CHECK_TIMEOUT_MS);
+    return interpretActiveResult(plat, r.code, r.stdout, r.stderr);
+}
+/**
+ * Async, non-blocking equivalent for server contexts (the Health endpoint)
+ * where a synchronous subprocess would stall the request-handling thread.
+ * Same semantics as `queryActiveState()`.
+ */
+export async function queryActiveStateAsync(plat, timeoutMs = STATUS_CHECK_TIMEOUT_MS) {
+    const [cmd, ...args] = activeCheckCommand(plat);
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        let child;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise(result);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child?.kill("SIGKILL");
+            }
+            catch { /* best-effort */ }
+            finish(null);
+        }, timeoutMs);
+        try {
+            child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (d) => { stdout += d.toString("utf-8"); });
+        child.stderr?.on("data", (d) => { stderr += d.toString("utf-8"); });
+        child.on("error", () => finish(null));
+        child.on("close", (code) => finish(interpretActiveResult(plat, code, stdout, stderr)));
+    });
+}
+/**
+ * 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.
+ */
+export function describeLoadFailure(plat, loadResult) {
+    const stderr = loadResult.stderr || "";
+    if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        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 `flair rem nightly enable`.");
+    }
+    return null;
+}
+/**
+ * Formats the `flair rem nightly enable` report from an `EnableResult`.
+ * Pulled out of the CLI action so the success-vs-failure decision (flair#850:
+ * do not print a success headline before activation is known to have
+ * succeeded) is unit-testable without spawning a real launchctl/systemctl or
+ * parsing CLI argv.
+ *
+ * `r.loadResult` is only set when the load command actually ran (the CLI
+ * never sets `skipLoad`). A missing `loadResult` (test-only path) is treated
+ * as success — matches the CLI's real-world behavior, which always runs the
+ * load command and therefore always gets a `loadResult`.
+ */
+export function formatEnableReport(r, input) {
+    const { hour, minute, agentId, flairUrl } = input;
+    const scheduleTime = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+    const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
+    if (activationFailed) {
+        const lr = r.loadResult;
+        const lines = [
+            `⚠️  REM nightly scheduler files written but NOT activated (${r.platform})`,
+            `   Schedule:    ${scheduleTime} local time — NOT scheduled (see below)`,
+            `   Scheduler:   ${r.schedulerPath}`,
+            `   Shim:        ${r.shimPath}`,
+            `   Agent:       ${agentId}`,
+            `   Flair URL:   ${flairUrl}`,
+            `   Activation:  ${r.loadCommand.join(" ")} → code ${lr.code}`,
+        ];
+        if (lr.stderr)
+            lines.push(`     stderr: ${lr.stderr.trim()}`);
+        const remedy = describeLoadFailure(r.platform, lr);
+        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`);
+        return { lines, ok: false };
+    }
+    const lines = [
+        `✅ REM nightly scheduler enabled (${r.platform})`,
+        `   Schedule:    ${scheduleTime} local time`,
+        `   Scheduler:   ${r.schedulerPath}`,
+        `   Shim:        ${r.shimPath}`,
+        `   Agent:       ${agentId}`,
+        `   Flair URL:   ${flairUrl}`,
+    ];
+    if (r.loadResult) {
+        lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+    }
+    lines.push("");
+    lines.push(`Tip: run \`flair rem nightly run-once --dry-run\` to verify the cycle works`);
+    lines.push(`     before the first scheduled fire. Disable with \`flair rem nightly disable\`.`);
+    return { lines, ok: true };
+}
+/**
+ * Formats the `flair rem nightly status` report from a `SchedulerStatus`.
+ * Extracted for the same testability reason as `formatEnableReport()`
+ * (flair#850): status must report genuine active state, not file presence.
+ */
+export function formatStatusReport(s) {
+    const activeTxt = s.active === true ? "yes" : s.active === false ? "no" : "unknown";
+    const lines = [
+        `REM nightly scheduler (${s.platform}):`,
+        `  Active:      ${activeTxt}`,
+        `  Installed:   ${s.installed ? "yes" : "no"}`,
+        `  Scheduler:   ${s.schedulerPath}`,
+        `  Shim:        ${s.shimPath}${s.shimExists ? "" : " (missing)"}`,
+    ];
+    if (!s.installed) {
+        lines.push("");
+        lines.push(`Enable with: flair rem nightly enable --agent <id> [--at HH:MM]`);
+    }
+    else if (s.active === false) {
+        lines.push("");
+        lines.push(`Files are written but nothing is scheduled — the job is not loaded/active.`);
+        lines.push(`Re-run: flair rem nightly enable --agent <id> [--at HH:MM]`);
+    }
+    // Status is informational — it does not itself signal process failure,
+    // consistent with the pre-existing "not installed" case never exiting
+    // nonzero. `ok` here only reflects whether the headline claims success.
+    return { lines, ok: s.active !== false };
+}
+/**
+ * Installs the platform-native scheduler entry and the shim script.
+ *
+ * macOS: writes ~/Library/LaunchAgents/dev.flair.rem.nightly.plist + bootstraps it via launchctl.
+ * Linux: writes ~/.config/systemd/user/flair-rem-nightly.{timer,service} + enables the timer.
+ *
+ * In both cases, also deploys ~/.flair/bin/flair-rem-nightly as the shim
+ * the scheduler invokes.
+ */
+export function enableScheduler(opts) {
+    const plat = detectPlatform(opts.platformOverride);
+    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+    const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
+    const subs = buildSubstitutions(opts, shimPath, flairBin);
+    // 1. Deploy the shim (always — both platforms invoke it).
+    const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-rem-nightly.sh.tmpl"), subs);
+    writeFileWithDir(shimPath, shimContents, 0o700);
+    chmodSync(shimPath, 0o700);
+    // 2. Write the scheduler entry.
+    if (plat === "darwin") {
+        const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        const plistContents = renderTemplate(readTemplate(templateRoot, "launchd/dev.flair.rem.nightly.plist.tmpl"), subs);
+        writeFileWithDir(plistPath, plistContents, 0o600);
+        const loadCommand = ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? ""}`, plistPath];
+        let loadResult;
+        if (!opts.skipLoad) {
+            // Bootout first in case a prior install left the job loaded.
+            spawnReport(["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath]);
+            loadResult = spawnReport(loadCommand);
+        }
+        return { platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult };
+    }
+    // Linux: systemd user units.
+    const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+    const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+    const serviceContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.service.tmpl"), subs);
+    const timerContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.timer.tmpl"), subs);
+    writeFileWithDir(servicePath, serviceContents, 0o600);
+    writeFileWithDir(timerPath, timerContents, 0o600);
+    const loadCommand = ["systemctl", "--user", "enable", "--now", "flair-rem-nightly.timer"];
+    let loadResult;
+    if (!opts.skipLoad) {
+        spawnReport(["systemctl", "--user", "daemon-reload"]);
+        loadResult = spawnReport(loadCommand);
+    }
+    return { platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult };
+}
+/**
+ * Removes the scheduler entry. Audit log + snapshots are preserved.
+ */
+export function disableScheduler(opts = {}) {
+    const plat = detectPlatform(opts.platformOverride);
+    const removed = [];
+    if (plat === "darwin") {
+        const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        const unloadCommand = ["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath];
+        let unloadResult;
+        if (existsSync(plistPath)) {
+            if (!opts.skipUnload) {
+                unloadResult = spawnReport(unloadCommand);
+            }
+            rmSync(plistPath, { force: true });
+            removed.push(plistPath);
+        }
+        if (opts.removeShim) {
+            const shim = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+            if (existsSync(shim)) {
+                rmSync(shim, { force: true });
+                removed.push(shim);
+            }
+        }
+        return { platform: plat, removed, unloadCommand, unloadResult };
+    }
+    const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+    const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+    const unloadCommand = ["systemctl", "--user", "disable", "--now", "flair-rem-nightly.timer"];
+    let unloadResult;
+    if (existsSync(timerPath) || existsSync(servicePath)) {
+        if (!opts.skipUnload) {
+            unloadResult = spawnReport(unloadCommand);
+            spawnReport(["systemctl", "--user", "daemon-reload"]);
+        }
+        if (existsSync(timerPath)) {
+            rmSync(timerPath, { force: true });
+            removed.push(timerPath);
+        }
+        if (existsSync(servicePath)) {
+            rmSync(servicePath, { force: true });
+            removed.push(servicePath);
+        }
+    }
+    if (opts.removeShim) {
+        const shim = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+        if (existsSync(shim)) {
+            rmSync(shim, { force: true });
+            removed.push(shim);
+        }
+    }
+    return { platform: plat, removed, unloadCommand, unloadResult };
+}
+/**
+ * Reports whether the scheduler is installed AND whether it is genuinely
+ * active. File presence alone proves the templates were written — it does
+ * NOT prove `launchctl`/`systemctl` successfully loaded the job (flair#850).
+ */
+export function schedulerStatus(opts = {}) {
+    const plat = detectPlatform(opts.platformOverride);
+    const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+    let schedulerPath;
+    let installed;
+    if (plat === "darwin") {
+        schedulerPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        installed = existsSync(schedulerPath);
+    }
+    else {
+        schedulerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+        const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+        installed = existsSync(schedulerPath) && existsSync(servicePath);
+    }
+    let active;
+    if (!installed) {
+        active = false; // nothing written — definitely nothing active
+    }
+    else if (opts.skipActiveCheck) {
+        active = null; // caller opted out — unknown, not a claim either way
+    }
+    else {
+        active = queryActiveState(plat);
+    }
+    return {
+        platform: plat,
+        installed,
+        active,
+        schedulerPath,
+        shimPath,
+        shimExists: existsSync(shimPath),
+    };
+}

package/docs/assets/flair-cross-orchestrator.cast

@@ -3,7 +3,7 @@
 [0.001, "o", "  Flair  \u00b7  same identity, every orchestrator\r\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n"]
 [1.3, "o", "$ # One agent identity. One memory store. Three orchestrators.\r\n"]
 [1.2, "o", "$ flair init --client all --agent flint\r\n"]
-[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude/mcp.json)\r\n"]
+[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude.json)\r\n"]
 [0.18, "o", "  \u001b[32m\u2713\u001b[0m Codex CLI     wired (~/.codex/config.toml)\r\n"]
 [0.18, "o", "  \u001b[32m\u2713\u001b[0m Gemini CLI    wired (~/.gemini/settings.json)\r\n\r\n"]
 [1.0, "o", "  Each MCP client now connects to:  http://127.0.0.1:9926\r\n"]

package/docs/bridges.md

@@ -101,7 +101,7 @@ A few things worth knowing:
 - **`--agent` is required** unless your descriptor maps an `agentId` column. If you forget, `flair bridge import` errors with a one-line operator-pointer hint plus a structured `BridgeRuntimeError` JSON on stderr.
 - **`--dry-run` is your friend.** Validates the descriptor, parses every record, applies the mapping, but skips the PUT. Use it to confirm the count and check a few records before committing.
 - **Output is throttled** to one progress line every 2 seconds (or every 25 records, whichever comes first), so big imports don't flood your terminal.
-- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [§10 of the spec](../specs/FLAIR-BRIDGES.md#-10-error-format)). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
+- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [Error format](#error-format) below). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
 
 ## Shape A — Declarative YAML
 
@@ -286,6 +286,6 @@ If you want an agent to write a bridge for you, here's the one-shot prompt:
 
 That's the bar. If an agent can't ship a working bridge from this doc plus the scaffold, the doc is the bug.
 
-## Full spec
+## Authority
 
-The authoritative contract is in [`specs/FLAIR-BRIDGES.md`](../specs/FLAIR-BRIDGES.md). This doc is the user-facing view; the spec covers edge cases, future extensions, and design rationale.
+This document is the authoritative contract for the bridge plugin system: the record schema, both plugin shapes, discovery, distribution, trust, round-trip testing, and the error format are all specified above. There is no separate design spec — the original planning document was retired once the system shipped, and its design-rationale and milestone-scoping sections are preserved in git history rather than maintained here.

package/docs/deployment.md

@@ -179,6 +179,7 @@ Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.fl
 | `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth; rotate via the Harper ops API, not by changing this env var. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
 | `FLAIR_KEY_PASSPHRASE` | Passphrase used to derive the AES-256-GCM key that wraps federation private-key seeds at rest. Auto-generated to `~/.flair/keys/.passphrase` if unset. | Set explicitly for production federation deployments so the passphrase isn't auto-generated and lost on disk wipe. |
 | `HTTP_PORT` | Override the Harper HTTP port. Useful for sandboxes; production deployments should configure the port in `config.yaml` instead. | Rare. |
+| `FLAIR_OPS_BIND` | Bind address for the Harper **ops API**. Resolution order: `flair init --ops-bind` > this variable > the `opsBind` key `flair init` persists in `~/.flair/config.yaml` > `127.0.0.1`. Every Flair-managed Harper start re-asserts the resolved value, so the persisted key is what makes a choice survive `flair restart` / `flair upgrade`. | Only for deployments that genuinely need remote ops admin (multi-host / Fabric) — set it to `0.0.0.0`, or record it once with `flair init --ops-bind 0.0.0.0`. Single-host installs want the loopback default. |
 
 ---
 

package/docs/mcp-clients.md

@@ -38,9 +38,11 @@ Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP ser
 
 Pick whichever you use. The MCP server is the same package; only the config syntax differs.
 
+> **Pin the version.** The snippets below use the bare package name for readability. `flair init` wires clients to a **pinned** spec (`@tpsdev-ai/flair-mcp@<version>`) on purpose: an unpinned reference re-resolves to whatever is currently published on every agent session, so any future publish reaches your machine silently. If you wire by hand, append the version you intend to run — `@tpsdev-ai/flair-mcp@0.28.0` — and bump it deliberately. `flair init` is the easier path and does this for you.
+
 ### Claude Code
 
-The canonical approach is the `claude mcp add` CLI (writes to `~/.claude/mcp.json`):
+The canonical approach is the `claude mcp add` CLI (writes to `~/.claude.json`):
 
 ```bash
 claude mcp add flair --scope user \

package/docs/n8n.md

@@ -93,7 +93,7 @@ If any of those don't hold, use Flair's CLI / SDK clients (which support per-age
 
 ## Get By Tag — coming soon
 
-The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter (tracked in the [n8n-node spec](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) §6). Workaround for now: use Semantic Search and let the model filter results by tags in the response.
+The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter. Workaround for now: use Semantic Search and let the model filter results by tags in the response.
 
 ## Worked examples
 
@@ -117,6 +117,5 @@ Same Flair instance, same memories, different surfaces.
 
 ## See also
 
-- [Spec — `@tpsdev-ai/n8n-nodes-flair`](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) — implementation plan, design decisions, anti-patterns
 - [Bridges](./bridges.md) — how Flair memories flow between hosts and instances
 - [Federation](./federation.md) — hub-and-spoke replication

package/docs/notes/rem-ux.md

@@ -1,6 +1,6 @@
 # REM UX — trigger model, attach semantics, review loop
 
-> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. Parent spec: `specs/FLAIR-NIGHTLY-REM.md`; slice spec: `specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md`.
+> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. See [`docs/rem.md`](../rem.md) for the REM configuration and command reference.
 
 ## Triggers — three, nothing implicit
 

package/docs/rem.md

@@ -2,6 +2,8 @@
 
 REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is ever auto-promoted. `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
 
+> **⚠️ Prerequisite: a configured generative backend.** All REM commands (`rapid`, `nightly`, `candidates`, `promote`, `reject`) require Harper's `models.generate()` to be wired — without it, REM calls fail with `Reflection error: No generative backend configured`. Set up a backend first (see [Configuration](#configuration) below) before running any REM command. The fastest path is Ollama with a non-thinking model, which needs zero credentials and keeps all traffic local.
+
 ## Configuration
 
 Distillation runs **server-side**, via Harper's model-access API (`models.generate()`). Flair ships zero provider code — which backend answers a REM call is entirely a Harper `models:` configuration decision.

package/docs/supply-chain-policy.md

@@ -19,13 +19,13 @@ We don't pull in any newly-published dep version for **at least 7 days** after i
 
 #### 1a. Keep-current allow-list
 
-Some deps are tightly coupled to Flair's runtime correctness — Harper bug fixes and security patches land in `@harperfast/harper`, embedding-pipeline fixes land in `harper-fabric-embeddings`. We accept the bake-time risk and pull these eagerly. Current allow-list:
+Some deps are tightly coupled to Flair's runtime correctness — Harper bug fixes and security patches land in `harper`, embedding-pipeline fixes land in `harper-fabric-embeddings`. We accept the bake-time risk and pull these eagerly. Current allow-list:
 
 | Package | Why kept current |
 |---------|------------------|
-| `@harperfast/harper` | Foundational. Vector-index and HNSW correctness fixes land here; we want them ASAP. High-volume upstream, fast detection if compromised. |
+| `harper` | Foundational. Vector-index and HNSW correctness fixes land here; we want them ASAP. High-volume upstream, fast detection if compromised. **Bare name, not `@harperfast/harper`** — the two are permanent lockstep publishes of the same source, and depending on the scoped one made every install materialise both copies (~213 MB), because `@harperfast/oauth` peers on the bare name and npm cannot dedupe across two names. Aligned in flair#870. |
 | `harper-fabric-embeddings` | Embedding model loader. Coupled to Harper version. Same trust-and-volume reasoning. |
-| `@harperfast/oauth` | Same high-trust `@harperfast/*` owner as `@harperfast/harper`. Used ONLY by the **default-OFF** native-MCP OAuth surface (`FLAIR_MCP_OAUTH`), which dynamically imports it only when the flag is on — it is **not loaded in the shipped default build**, so bake-time exposure is zero until an operator explicitly opts in. Pinned to the exact version whose `withMCPAuth` API the surface was built against; the API surface (not a floating range) is what we depend on. |
+| `@harperfast/oauth` | Same high-trust upstream owner as `harper`. Used ONLY by the **default-OFF** native-MCP OAuth surface (`FLAIR_MCP_OAUTH`), which dynamically imports it only when the flag is on — it is **not loaded in the shipped default build**, so bake-time exposure is zero until an operator explicitly opts in. Pinned to the exact version whose `withMCPAuth` API the surface was built against; the API surface (not a floating range) is what we depend on. |
 
 Adding to this list is a deliberate decision. The bar:
 - The upstream is well-known and high-volume (gets eyeballs fast).
@@ -75,7 +75,7 @@ Only Nathan publishes to npm (per the existing MFA boundary). Flint preps the re
 
 ### `.github/renovate.json` — deliberate, cooldown-gated update proposals
 
-Renovate opens PRs to propose dependency updates so we don't drift behind upstream indefinitely — but on our terms, not the registry's. It is configured to never auto-merge (`automerge: false`), to pin (`rangeStrategy: "pin"`, consistent with §2), and to respect the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS` in `check-dep-ages.mjs`) so it only proposes versions that have already cleared the detection window. Non-major updates are grouped; majors land as isolated PRs. The keep-current allow-list (`@harperfast/harper`, `harper-fabric-embeddings`, `@harperfast/oauth`) mirrors the script's `DEFAULT_KEEP_CURRENT` — keep the two in lockstep when either changes. Vulnerability alerts bypass the cooldown. Every Renovate PR still runs the full CI suite (including the bake-time and workspace-deps gates) and is K&S-reviewed before merge.
+Renovate opens PRs to propose dependency updates so we don't drift behind upstream indefinitely — but on our terms, not the registry's. It is configured to never auto-merge (`automerge: false`), to pin (`rangeStrategy: "pin"`, consistent with §2), and to respect the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS` in `check-dep-ages.mjs`) so it only proposes versions that have already cleared the detection window. Non-major updates are grouped; majors land as isolated PRs. The keep-current allow-list (`harper`, `harper-fabric-embeddings`, `@harperfast/oauth`) mirrors the script's `DEFAULT_KEEP_CURRENT` — keep the two in lockstep when either changes. Vulnerability alerts bypass the cooldown. Every Renovate PR still runs the full CI suite (including the bake-time and workspace-deps gates) and is K&S-reviewed before merge.
 
 ### `scripts/check-workspace-deps.mjs` (already shipped, PR #368)
 

package/docs/upgrade.md

@@ -177,7 +177,7 @@ FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
 (or `--fabric-password-file <path>` instead of the `FABRIC_PASSWORD` env var — reads the
 password from a file, chmod 600). This resolves the target version (latest published
 `@tpsdev-ai/flair`, or pin one with `--version`), stages a clean deployable with the
-required `@harperfast/harper` version pin applied (`--harper-version` to override),
+required `harper` version pin applied (`--harper-version` to override),
 confirms the staged Harper build before deploying, then reuses `flair deploy` to push it
 and verifies the result. `--check` shows the version diff and plan without deploying
 anything; `--yes` skips the confirmation prompt for scripted use.
@@ -223,7 +223,7 @@ Exit codes:
 *Flair's own* federation peer table, not Harper Fabric's own cluster-replication
 nodes. Harper's `cluster_status` operation (the one that would answer "what nodes are
 in this cluster and are they in sync") is harper-pro-only and unavailable in the OSS
-`@harperfast/harper` build this CLI ships — there is no way for this CLI to enumerate
+`harper` build this CLI ships — there is no way for this CLI to enumerate
 Fabric's own replication topology, on the origin or anywhere else. A Fabric replica
 that was never separately paired as a Flair federation peer (`flair federation pair`)
 is invisible to this sweep: `0 peers known` means "0 peers on file," never "0 peers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.28.0",
+  "version": "0.30.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",
@@ -56,15 +56,15 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.1.22",
     "@harperfast/oauth": "2.4.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
+    "harper": "5.1.22",
     "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
-    "js-yaml": "4.1.1",
+    "js-yaml": "4.3.0",
     "node-llama-cpp": "3.18.1",
-    "tar": "7.5.13",
+    "tar": "7.5.20",
     "tweetnacl": "1.0.3"
   },
   "optionalDependencies": {