@tpsdev-ai/flair 0.28.0 → 0.30.0

package/dist/cli.js

@@ -261,6 +261,40 @@ function readPortFromConfig() {
     catch { /* ignore */ }
     return null;
 }
+/**
+ * Read the persisted ops-API bind host from ~/.flair/config.yaml (flair#863).
+ * Line-anchored so it can't be satisfied by some other key that merely ends
+ * in `opsBind`, and quote-tolerant because a hand-edited config may quote it.
+ *
+ * `path` is injected the same way launchdPlistPath's `launchAgentsDir` is —
+ * so tests exercise the real parse against a temp file instead of the
+ * developer's own ~/.flair.
+ */
+function readOpsBindFromConfig(path = configPath()) {
+    try {
+        if (existsSync(path)) {
+            const yaml = readFileSync(path, "utf-8");
+            const m = yaml.match(/^\s*opsBind:\s*["']?([^"'\s#]+)["']?/m);
+            if (m && m[1])
+                return m[1];
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
+/** Read the persisted ops-API port from ~/.flair/config.yaml (flair#863). */
+function readOpsPortFromConfig(path = configPath()) {
+    try {
+        if (existsSync(path)) {
+            const yaml = readFileSync(path, "utf-8");
+            const m = yaml.match(/^\s*opsPort:\s*(\d+)/m);
+            if (m)
+                return Number(m[1]);
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
 // Unified port resolution: --port flag > FLAIR_URL env > config file > default
 // Every command that talks to Harper MUST use these helpers.
 function resolveHttpPort(opts) {
@@ -320,29 +354,60 @@ function resolveOpsPort(opts) {
     // Default: httpPort - 1
     return resolveHttpPort(opts) - 1;
 }
-// Ops API bind-host resolution (flair#670): --ops-bind flag > FLAIR_OPS_BIND
-// env > loopback default. This is the escape hatch — deployments that
-// genuinely need remote ops access (multi-host / Fabric) pass an explicit
-// wider address (e.g. `--ops-bind 0.0.0.0`) to opt back in; everything else
-// gets the loopback-only single-host default. FLAIR_OPS_BIND (not just the
-// flag) matters for `flair start`'s non-launchd fallback spawn, which has no
-// --ops-bind flag of its own — see the comment at its OPERATIONSAPI_NETWORK_PORT
-// assignment for why it re-resolves this on every start instead of trusting
-// the persisted config alone.
-function resolveOpsBindHost(opts) {
-    if (opts.opsBind !== undefined && opts.opsBind !== null && String(opts.opsBind).trim() !== "") {
-        return String(opts.opsBind).trim();
-    }
-    const envBind = process.env.FLAIR_OPS_BIND;
+// Ops API bind-host resolution (flair#670, #863): --ops-bind flag >
+// FLAIR_OPS_BIND env > persisted `opsBind` in ~/.flair/config.yaml > loopback
+// default. This is the escape hatch — deployments that genuinely need remote
+// ops access (multi-host / Fabric) pass an explicit wider address (e.g.
+// `--ops-bind 0.0.0.0`) to opt back in; everything else gets the loopback-only
+// single-host default.
+//
+// The config-file rung (flair#863) is what makes `--ops-bind` durable. Every
+// Harper spawn re-asserts the bind (see opsNetworkPortValue's doc comment for
+// why it MUST), and those spawns happen in `flair start` / `flair restart` /
+// `flair upgrade`, none of which take an `--ops-bind` flag. Without a
+// flair-owned persisted value, a one-off `flair init --ops-bind 0.0.0.0` would
+// be silently reverted to the loopback default by the very next restart — the
+// widening case would be as broken as the narrowing one. Mirrors
+// resolveOpsPort's config rung.
+export function resolveOpsBindHostFrom(flag, envBind, configuredBind) {
+    if (flag !== undefined && flag !== null && String(flag).trim() !== "")
+        return String(flag).trim();
     if (envBind && envBind.trim() !== "")
         return envBind.trim();
+    if (configuredBind && configuredBind.trim() !== "")
+        return configuredBind.trim();
     return DEFAULT_OPS_BIND_HOST;
 }
+function resolveOpsBindHost(opts) {
+    return resolveOpsBindHostFrom(opts.opsBind, process.env.FLAIR_OPS_BIND, readOpsBindFromConfig());
+}
+/**
+ * The one place that renders Harper's `operationsApi.network.port` value
+ * (flair#863). Used by both the HARPER_SET_CONFIG block
+ * (buildOperationsApiConfig) and every `OPERATIONSAPI_NETWORK_PORT` env var
+ * flair sets, so the two can never disagree about whether the bind host is
+ * present.
+ *
+ * Why every spawn has to carry the host-qualified form, not a bare number:
+ * Harper's HARPER_SET_CONFIG handling (harper
+ * config/harperConfigEnvVars.ts) records, for each key it force-sets, the
+ * value that key had BEFORE the force — `state.originalValues` in
+ * `<rootPath>/backup/.harper-config-state.json` — and on the next boot where
+ * HARPER_SET_CONFIG is absent, `cleanupRemovedEnvVar` RESTORES those
+ * originals into harper-config.yaml. So a bare `OPERATIONSAPI_NETWORK_PORT`
+ * anywhere in flair's spawn chain doesn't just lose on that boot: it is
+ * latched as the "original" and silently re-widens the bind to all interfaces
+ * on the first later boot that omits HARPER_SET_CONFIG. That is exactly what
+ * `flair restart` / `flair upgrade` do on the non-launchd path.
+ */
+export function opsNetworkPortValue(opsBindHost, opsPort) {
+    return `${opsBindHost}:${opsPort}`;
+}
 /**
  * Build the `operationsApi` block for Harper's HARPER_SET_CONFIG (flair#670).
  *
  * `network.port` uses Harper's "host:port" string form — Harper's server
- * bootstrap (@harperfast/harper dist/server/threads/threadServer.js,
+ * bootstrap (harper dist/server/threads/threadServer.js,
  * listenOnPorts/listenOnPortsBun) splits a config port value on its last
  * `:` into an explicit bind host + port when present, and falls back to
  * binding all interfaces (0.0.0.0 / ::) when given a bare number. A colon-free
@@ -350,15 +415,48 @@ function resolveOpsBindHost(opts) {
  * it with a host is the only config-level way to narrow the bind.
  *
  * `domainSocket` lives under `network` per Harper's own config schema
- * (@harperfast/harper/config-root.schema.json → properties.operationsApi
+ * (harper/config-root.schema.json → properties.operationsApi
  * .properties.network.properties.domainSocket, and
  * dist/validation/configValidator.js's `operationsApi.network.domainSocket`
  * Joi path) — nested here, not as a sibling of `network`.
  */
 export function buildOperationsApiConfig(opsPort, opsSocket, opsBindHost) {
     return {
-        network: { port: `${opsBindHost}:${opsPort}`, cors: true, domainSocket: opsSocket },
+        network: { port: opsNetworkPortValue(opsBindHost, opsPort), cors: true, domainSocket: opsSocket },
+    };
+}
+/**
+ * Build the flair-owned environment overrides for a DIRECT (non-launchd)
+ * Harper spawn (flair#863) — shared by `flair start`'s fallback path and
+ * startFlairProcess() (which backs `flair restart` and `flair upgrade`).
+ * Callers spread this over `process.env`.
+ *
+ * These two sites used to build the env inline and had drifted: `start` set a
+ * host-qualified OPERATIONSAPI_NETWORK_PORT, `startFlairProcess` set none at
+ * all. Neither path sets HARPER_SET_CONFIG, and Harper restores the
+ * pre-SET_CONFIG original for every key SET_CONFIG had forced whenever that
+ * variable is absent — so the site that omitted the var silently re-widened
+ * the ops API to all interfaces on every restart/upgrade, and persisted it.
+ * One builder means the next spawn site cannot reintroduce that gap.
+ *
+ * Deliberately omits HDB_ADMIN_PASSWORD when no password is in hand: an empty
+ * string would strip Harper's auth on an existing install.
+ */
+export function buildDirectSpawnEnv(opts) {
+    const env = {
+        ROOTPATH: opts.dataDir,
+        // The embedding backend self-registers in-process at boot
+        // (resources/embeddings-boot.ts); this only tells it where the model lives.
+        FLAIR_MODELS_DIR: opts.modelsDir,
+        DEFAULTS_MODE: "dev",
+        HDB_ADMIN_USERNAME: opts.adminUser,
+        HTTP_PORT: String(opts.httpPort),
+        OPERATIONSAPI_NETWORK_PORT: opsNetworkPortValue(opts.opsBindHost, opts.opsPort),
+        LOCAL_STUDIO: "false",
     };
+    if (opts.adminPass)
+        env.HDB_ADMIN_PASSWORD = opts.adminPass;
+    return env;
 }
 /**
  * Decide whether a persisted `operationsApi.network.port` value (read back
@@ -384,6 +482,33 @@ export function detectOpsApiAllInterfacesBind(portValue) {
     }
     return { allInterfaces: true, boundHost: null };
 }
+/**
+ * Decide the source `flair init` should use for the admin password when no
+ * explicit `--admin-pass` / `--admin-pass-file` / env var was given
+ * (flair#827).
+ *
+ * Before this existed, init ALWAYS generated a fresh random password and
+ * overwrote `~/.flair/admin-pass` on every run — including a re-run against
+ * an install that was already bootstrapped and working (e.g. following
+ * `flair doctor`'s ops-bind finding, whose only prescribed remedy is
+ * re-running `flair init`). Harper's `HDB_ADMIN_PASSWORD` env var only seeds
+ * a brand-new install's user record — it does NOT rotate an existing user's
+ * stored password hash on every boot. So overwriting the file desynced it
+ * from what Harper actually had persisted, and the very next ops-API call in
+ * that SAME init run (seeding the agent) failed with a 401 "Login failed",
+ * breaking working auth on an install that had nothing wrong with its
+ * credentials.
+ *
+ * An admin-pass file that already exists on disk IS the working install's
+ * password — `flair init` is the only thing that ever writes it — so reuse
+ * it instead of generating a new one. That makes re-init idempotent: safe to
+ * run again at any time without risking the instance's auth. Deliberately
+ * rotating the admin password is a separate operation, not a `flair init`
+ * side effect.
+ */
+export function resolveInitAdminPasswordSource(adminPassFileExists) {
+    return adminPassFileExists ? "reuse-existing" : "generate-new";
+}
 // ─── Ops-socket permission posture (flair#763) ─────────────────────────────────
 //
 // The ops API domain socket (dataDir/operations-server) is protected by a
@@ -666,10 +791,26 @@ function resolveOpsUrlFromTarget(targetUrl) {
     }
     return url.toString().replace(/\/$/, "");
 }
-function writeConfig(port) {
-    const p = configPath();
-    mkdirSync(join(homedir(), ".flair"), { recursive: true });
-    writeFileSync(p, `# Flair configuration\nport: ${port}\n`);
+/**
+ * Persist the instance coordinates other commands need to find and re-assert
+ * this install (flair#863).
+ *
+ * This rewrites the file wholesale, so `opsPort`/`opsBind` default to whatever
+ * is already persisted rather than being dropped — otherwise an unrelated
+ * caller (e.g. `flair doctor --fix` correcting a drifted HTTP port) would
+ * silently erase the operator's `--ops-bind` choice and the next restart would
+ * revert the bind.
+ */
+function writeConfig(port, opsPort, opsBind, path = configPath()) {
+    const resolvedOpsPort = opsPort ?? readOpsPortFromConfig(path);
+    const resolvedOpsBind = opsBind ?? readOpsBindFromConfig(path);
+    mkdirSync(dirname(path), { recursive: true });
+    let body = `# Flair configuration\nport: ${port}\n`;
+    if (resolvedOpsPort !== null && resolvedOpsPort !== undefined)
+        body += `opsPort: ${resolvedOpsPort}\n`;
+    if (resolvedOpsBind)
+        body += `opsBind: ${resolvedOpsBind}\n`;
+    writeFileSync(path, body);
 }
 function privKeyPath(agentId, keysDir) {
     return join(keysDir, `${agentId}.key`);
@@ -682,11 +823,25 @@ function flairPackageDir() {
     return join(import.meta.dirname ?? __dirname, "..");
 }
 function harperBin() {
-    // Resolve relative to this file's location (dist/cli.js → ../node_modules/...)
-    const candidates = [
-        join(import.meta.dirname ?? __dirname, "..", "node_modules", "@harperfast", "harper", "dist", "bin", "harper.js"),
-        join(process.cwd(), "node_modules", "@harperfast", "harper", "dist", "bin", "harper.js"),
+    // Resolve relative to this file's location (dist/cli.js → ../node_modules/...).
+    //
+    // flair#870: flair depends on the BARE `harper` package name. The scoped
+    // `@harperfast/harper` segments are kept as a fallback so an in-place upgrade
+    // over a pre-#870 install (whose node_modules still holds the scoped copy,
+    // and whose Harper is the one currently serving the data dir) keeps booting
+    // until the next clean install. Bare name is tried first so a tree that has
+    // BOTH resolves to the one flair actually declares.
+    const roots = [
+        join(import.meta.dirname ?? __dirname, ".."),
+        process.cwd(),
     ];
+    const pkgSegments = [["harper"], ["@harperfast", "harper"]];
+    const candidates = [];
+    for (const root of roots) {
+        for (const segs of pkgSegments) {
+            candidates.push(join(root, "node_modules", ...segs, "dist", "bin", "harper.js"));
+        }
+    }
     for (const c of candidates)
         if (existsSync(c))
             return c;
@@ -1846,6 +2001,39 @@ const __pkgVersion = (() => {
         return "unknown";
     }
 })();
+/**
+ * The `@tpsdev-ai/flair-mcp` spec written into a client's MCP config.
+ *
+ * PINNED, deliberately. A bare `npx -y @tpsdev-ai/flair-mcp` re-resolves to
+ * whatever is currently published on EVERY agent session — so a single bad
+ * publish (stolen credentials, a malicious commit that clears review, or a
+ * compromised dependency of the MCP package) reaches every wired user
+ * silently, with no lockfile and no review step in the path. The postmark-mcp
+ * incident was exactly this shape: a legitimate publish by the legitimate
+ * owner, propagating for 16 days before anyone noticed. Worse, a yank does
+ * not help — unpinned clients keep resolving latest.
+ *
+ * Our publish side is already hardened (OIDC staged publish, human 2FA at the
+ * release gate), but that defends against credential theft, not against a bad
+ * version being published legitimately. The consumer side is where that gap
+ * closes, and pinning is what closes it: a wired client keeps running the
+ * exact version that was current when it was wired, and moving forward
+ * becomes a deliberate act.
+ *
+ * flair and flair-mcp ship in version lockstep from this monorepo, so the
+ * running CLI's own version is the correct pin. `flair init` re-run rewires
+ * to the then-current version; see the upgrade-rewire follow-up issue for
+ * making `flair upgrade` do the same.
+ *
+ * Falls back to the unpinned spec only when the version can't be read, which
+ * is the same condition under which `--version` reports "unknown" — a broken
+ * install, where a working MCP wiring matters more than a precise pin.
+ */
+export function mcpServerSpec(version = __pkgVersion) {
+    return version && version !== "unknown"
+        ? `@tpsdev-ai/flair-mcp@${version}`
+        : "@tpsdev-ai/flair-mcp";
+}
 const program = new Command();
 program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── CLI↔server version handshake (flair#695 §B) ────────────────────────────
@@ -2117,9 +2305,10 @@ program
         selectedClients.push(clientOpt);
     }
     // Admin password: determine from opts, env, or generate
-    // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
+    // Priority: 1) --admin-pass-file, 2) env vars, 3) reuse existing file, 4) generate new
     let adminPass;
     let passwordSource = "generated";
+    let reusedExistingAdminPass = false;
     // Warn if --admin-pass is passed inline (not from env)
     if (shouldShowInlineSecretWarning(opts.adminPass, false, new Set(["--admin-pass"]), "--admin-pass")) {
         console.error("warning: --admin-pass passed inline. Consider --admin-pass-file <path> or FLAIR_ADMIN_PASS env " +
@@ -2151,34 +2340,65 @@ program
         passwordSource = "env"; // Treat same as env for display purposes
     }
     else {
-        // Generate new password and write to file atomically
-        adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
-        passwordSource = "generated";
-        // Atomic write: create temp file in same dir, then rename
         const flairDir = join(homedir(), ".flair");
-        mkdirSync(flairDir, { recursive: true });
         const adminPassPath = join(flairDir, "admin-pass");
-        const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
-        const finalTempPath = join(tempPath, "admin-pass");
-        try {
-            writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
-            renameSync(finalTempPath, adminPassPath);
-            rmSync(tempPath, { recursive: true, force: true });
+        passwordSource = "generated";
+        if (resolveInitAdminPasswordSource(existsSync(adminPassPath)) === "reuse-existing") {
+            // flair#827: an admin-pass file already on disk means a PRIOR `flair
+            // init` already bootstrapped Harper's admin user with this password.
+            // HDB_ADMIN_PASSWORD only seeds a brand-new install — Harper does
+            // NOT rotate an existing user's stored password hash from env on
+            // every boot. Generating and overwriting the file here would desync
+            // it from what Harper actually has persisted, breaking ops-API auth
+            // (401 "Login failed") on THIS SAME init run (the agent-seeding call
+            // below) without fixing whatever the re-run was meant to fix — e.g.
+            // `flair doctor`'s ops-bind finding, whose only prescribed remedy is
+            // re-running `flair init`. Re-init must be idempotent here: reuse
+            // the existing password so it's always safe to re-run against a
+            // working install. Rotating the admin password on purpose is a
+            // separate, deliberate operation (see the ops runbook), not a side
+            // effect of re-init.
+            try {
+                adminPass = readAdminPassFileSecure(adminPassPath);
+            }
+            catch (err) {
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
+            }
+            reusedExistingAdminPass = true;
         }
-        catch (err) {
-            // Clean up temp dir on failure
+        else {
+            // Generate new password and write to file atomically
+            adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
+            // Atomic write: create temp file in same dir, then rename
+            mkdirSync(flairDir, { recursive: true });
+            const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
+            const finalTempPath = join(tempPath, "admin-pass");
             try {
+                writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
+                renameSync(finalTempPath, adminPassPath);
                 rmSync(tempPath, { recursive: true, force: true });
             }
-            catch { }
-            throw err;
+            catch (err) {
+                // Clean up temp dir on failure
+                try {
+                    rmSync(tempPath, { recursive: true, force: true });
+                }
+                catch { }
+                throw err;
+            }
         }
     }
     const adminUser = DEFAULT_ADMIN_USER;
-    // If we generated the password, report where it was saved
+    // If we generated (or reused) the password, report where it lives
     if (passwordSource === "generated") {
         const adminPassPath = join(homedir(), ".flair", "admin-pass");
-        console.log(`Admin password saved to: ${adminPassPath}`);
+        if (reusedExistingAdminPass) {
+            console.log(`Reusing existing admin password from: ${adminPassPath} (flair#827: re-init never rotates it — see the ops runbook to change it deliberately)`);
+        }
+        else {
+            console.log(`Admin password saved to: ${adminPassPath}`);
+        }
     }
     // Check Node.js version
     const major = parseInt(process.version.slice(1), 10);
@@ -2210,8 +2430,13 @@ program
         catch { /* not running */ }
         if (!alreadyRunning) {
             const bin = harperBin();
-            if (!bin)
-                throw new Error("@harperfast/harper not found in node_modules.\nRun: npm install @harperfast/harper");
+            if (!bin) {
+                throw new Error("Harper CLI not found: no dist/bin/harper.js under node_modules/harper " +
+                    "(or the legacy node_modules/@harperfast/harper) next to this flair " +
+                    `install or in ${process.cwd()}.\n` +
+                    "Flair ships Harper as a dependency, so this normally means a partial " +
+                    "or interrupted install.\nFix: reinstall flair — npm install -g @tpsdev-ai/flair");
+            }
             mkdirSync(dataDir, { recursive: true });
             // Detect whether Harper has already been installed in this data dir.
             // harper-config.yaml is created during install — its presence means
@@ -2246,7 +2471,12 @@ program
                 THREADS_COUNT: "1",
                 NODE_HOSTNAME: "localhost",
                 HTTP_PORT: String(httpPort),
-                OPERATIONSAPI_NETWORK_PORT: String(opsPort),
+                // flair#863: host-qualified, NOT a bare port. A bare value here is
+                // what Harper latches as `originalValues["operationsApi.network.port"]`
+                // when HARPER_SET_CONFIG force-sets the same key — and restores on the
+                // first later boot without HARPER_SET_CONFIG, re-widening the bind to
+                // all interfaces. See opsNetworkPortValue's doc comment.
+                OPERATIONSAPI_NETWORK_PORT: opsNetworkPortValue(opsBindHost, opsPort),
                 LOCAL_STUDIO: "false",
             };
             // models (flair#504 Phase 1): the embedding backend registers itself
@@ -2386,7 +2616,7 @@ program
     <key>THREADS_COUNT</key><string>1</string>
     <key>NODE_HOSTNAME</key><string>localhost</string>
     <key>HTTP_PORT</key><string>${httpPort}</string>
-    <key>OPERATIONSAPI_NETWORK_PORT</key><string>${opsPort}</string>
+    <key>OPERATIONSAPI_NETWORK_PORT</key><string>${escapeXml(opsNetworkPortValue(opsBindHost, opsPort))}</string>
     <key>LOCAL_STUDIO</key><string>false</string>
   </dict>
   <key>RunAtLoad</key><true/>
@@ -2400,8 +2630,15 @@ program
             }
         }
     }
-    // Persist port to config so other commands can find this instance
-    writeConfig(httpPort);
+    // Persist the instance coordinates so other commands can find AND
+    // re-assert this instance. flair#863: `opsBind` in particular has to be
+    // persisted here, not just handed to this run's spawn — `flair start` /
+    // `flair restart` / `flair upgrade` re-assert the bind on every spawn and
+    // have no `--ops-bind` flag of their own, so this is the only thing that
+    // survives an `--ops-bind` choice past the next restart. It also runs on
+    // the already-running path (where init skips the spawn entirely), which is
+    // what makes doctor's `flair init && flair restart` remedy actually apply.
+    writeConfig(httpPort, opsPort, opsBindHost);
     if (agentId) {
         // Generate or reuse keypair
         mkdirSync(keysDir, { recursive: true });
@@ -2515,7 +2752,8 @@ program
         }
         // ── MCP client wiring ────────────────────────────────────────────────
         // The full one-command front door: detect installed MCP clients and wire
-        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp` server. Claude
+        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp@<version>` server
+        // (pinned — see mcpServerSpec()). Claude
         // Code is auto-wired into ~/.claude.json (the only client the CLI can
         // safely modify); other clients get copy-paste snippets. `--no-mcp`
         // skips wiring entirely; `--client <name>` targets one client; the
@@ -2551,7 +2789,7 @@ program
                     const flairMcpConfig = {
                         type: "stdio",
                         command: "npx",
-                        args: ["-y", "@tpsdev-ai/flair-mcp"],
+                        args: ["-y", mcpServerSpec()],
                         // flair#718 authorship-provenance: each client's wired env block
                         // gets its OWN FLAIR_CLIENT label (never the shared mcpEnv
                         // object directly — that would stamp the same label into every
@@ -2640,7 +2878,9 @@ program
         if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
             console.log("\n   Smoke-testing MCP server...");
             try {
-                const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
+                // Same spec that gets WIRED above — the smoke test must exercise the
+                // exact version the user will run, not whatever npm resolves latest to.
+                const mcpProc = spawn("npx", ["-y", mcpServerSpec()], {
                     env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
                     stdio: ["pipe", "pipe", "pipe"],
                 });
@@ -5863,8 +6103,7 @@ export function describeReflectError(message) {
     return { kind: "other", text: message };
 }
 // ─── flair rem rapid ──────────────────────────────────────────────────────────
-// Executes by default (specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3C,
-// issue #707): distills server-side via /ReflectMemories execute:true and
+// Executes by default (§3C, issue #707): distills server-side via /ReflectMemories execute:true and
 // stages MemoryCandidate rows, printing a staged-candidate summary. --prompt-only
 // preserves the pre-#710 handoff behavior byte-for-byte, for the bring-your-
 // own-model workflow.
@@ -6329,27 +6568,17 @@ remNightly
     const minute = parseInt(match[2], 10);
     const port = readPortFromConfig() ?? DEFAULT_PORT;
     const flairUrl = opts.flairUrl || process.env.FLAIR_URL || `http://127.0.0.1:${port}`;
-    const { enableScheduler } = await import("./rem/scheduler.js");
+    const { enableScheduler, formatEnableReport } = await import("./rem/scheduler.js");
     try {
         const r = enableScheduler({ agentId, flairUrl, hour, minute });
-        console.log(`✅ REM nightly scheduler enabled (${r.platform})`);
-        console.log(`   Schedule:    ${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")} local time`);
-        console.log(`   Scheduler:   ${r.schedulerPath}`);
-        console.log(`   Shim:        ${r.shimPath}`);
-        console.log(`   Agent:       ${agentId}`);
-        console.log(`   Flair URL:   ${flairUrl}`);
-        if (r.loadResult) {
-            if (r.loadResult.code === 0) {
-                console.log(`   Load:        ${r.loadCommand.join(" ")} → ok`);
-            }
-            else {
-                console.log(`   Load:        ${r.loadCommand.join(" ")} → code ${r.loadResult.code}`);
-                if (r.loadResult.stderr)
-                    console.log(`     stderr: ${r.loadResult.stderr.trim()}`);
-            }
-        }
-        console.log(`\nTip: run \`flair rem nightly run-once --dry-run\` to verify the cycle works`);
-        console.log(`     before the first scheduled fire. Disable with \`flair rem nightly disable\`.`);
+        // formatEnableReport() owns the success-vs-failure decision (flair#850:
+        // do not print a success headline before activation is known to have
+        // succeeded) — see src/rem/scheduler.ts for the unit-tested logic.
+        const { lines, ok } = formatEnableReport(r, { hour, minute, agentId, flairUrl });
+        for (const line of lines)
+            console.log(line);
+        if (!ok)
+            process.exit(1);
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -6387,18 +6616,14 @@ remNightly
 });
 remNightly
     .command("status")
-    .description("Show whether the nightly scheduler is installed")
+    .description("Show whether the nightly scheduler is installed and genuinely active")
     .action(async () => {
-    const { schedulerStatus } = await import("./rem/scheduler.js");
+    const { schedulerStatus, formatStatusReport } = await import("./rem/scheduler.js");
     try {
         const s = schedulerStatus();
-        console.log(`REM nightly scheduler (${s.platform}):`);
-        console.log(`  Installed:   ${s.installed ? "yes" : "no"}`);
-        console.log(`  Scheduler:   ${s.schedulerPath}`);
-        console.log(`  Shim:        ${s.shimPath}${s.shimExists ? "" : " (missing)"}`);
-        if (!s.installed) {
-            console.log(`\nEnable with: flair rem nightly enable --agent <id> [--at HH:MM]`);
-        }
+        const { lines } = formatStatusReport(s);
+        for (const line of lines)
+            console.log(line);
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -7556,7 +7781,7 @@ export function resolveFabricCredentials(opts) {
 // Mirrors `flair deploy`'s credential handling (FABRIC_USER/FABRIC_PASSWORD env
 // fallbacks, password-via-flag warning, --fabric-password-file — see
 // resolveFabricCredentials above) and NEVER prints credentials. The
-// version-resolution + @harperfast/harper pin + reuse of deploy() lives in
+// version-resolution + harper pin + reuse of deploy() lives in
 // src/fabric-upgrade.ts; this wrapper only does CLI plumbing + the confirm.
 async function runFabricUpgrade(opts) {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -7664,7 +7889,7 @@ async function runFabricUpgrade(opts) {
 // before the package swap, with a keep-last-3 retention policy.
 //
 // Native-backup alternative considered and rejected: Harper ships a
-// `get_backup` operation (@harperfast/harper's dataLayer/getBackup.ts,
+// `get_backup` operation (harper's dataLayer/getBackup.ts,
 // wired in server/serverHelpers/serverUtilities.ts, documented in
 // components/mcp/tools/schemas/operationDescriptions.ts) that streams a
 // live backup over the running HTTP operations API. It's available in this
@@ -8010,13 +8235,13 @@ program
     // ── Fabric upgrade (--target) ────────────────────────────────────────────
     // When --target is passed, upgrade the Flair component DEPLOYED to that
     // Harper Fabric URL instead of the local npm install. Reuses `flair deploy`
-    // under the hood with the @harperfast/harper pin baked in (flair#513).
+    // under the hood with the harper pin baked in (flair#513).
     .option("--target <url>", "Upgrade the Flair deployed to this Fabric URL (not the local install)")
     .option("--fabric-user <user>", "Fabric admin username — for --target (env: FABRIC_USER preferred; inline leaks to shell history)")
     .option("--fabric-password <pass>", "Fabric admin password — for --target (prefer FABRIC_PASSWORD env or --fabric-password-file; inline leaks to shell history)")
     .option("--fabric-password-file <path>", "Read the Fabric admin password from a file (chmod 600) — for --target")
     .option("--version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
-    .option("--harper-version <semver>", "Pin @harperfast/harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
+    .option("--harper-version <semver>", "Pin harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
     .option("--project <name>", "Fabric component name for --target", "flair")
     .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
     .option("--yes", "Skip the confirmation prompt for --target")
@@ -8574,34 +8799,23 @@ program
         process.exit(1);
     }
     const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
-    const opsPort = resolveOpsPort(opts);
-    // flair#670: this fallback path (no launchd plist) sets no HARPER_SET_CONFIG,
-    // so OPERATIONSAPI_NETWORK_PORT applies unfiltered on top of whatever init
-    // persisted to harper-config.yaml. A bare port number here would silently
-    // strip a loopback (or escape-hatch) bind host back to all-interfaces on
-    // every plain `flair start`. Re-resolving the same host:port form init uses
-    // keeps this re-assertion consistent instead of regressing it — the
-    // escape hatch on this path is FLAIR_OPS_BIND (no --ops-bind flag on `start`).
-    const opsBindHost = resolveOpsBindHost({});
-    const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
+    // flair#670/#863: this fallback path (no launchd plist) sets no
+    // HARPER_SET_CONFIG, so the ops bind has to be re-asserted explicitly on
+    // every spawn — see buildDirectSpawnEnv. The escape hatch on this path is
+    // FLAIR_OPS_BIND or the `opsBind` that `flair init --ops-bind` persisted to
+    // ~/.flair/config.yaml; there is no --ops-bind flag on `start`.
     const env = {
         ...process.env,
-        ROOTPATH: dataDir,
-        // See the matching comment at the install-time spawn site above.
-        FLAIR_MODELS_DIR: modelsDir,
-        DEFAULTS_MODE: "dev",
-        HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
-        HTTP_PORT: String(port),
-        OPERATIONSAPI_NETWORK_PORT: `${opsBindHost}:${opsPort}`,
-        LOCAL_STUDIO: "false",
+        ...buildDirectSpawnEnv({
+            dataDir,
+            modelsDir: process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models"),
+            httpPort: port,
+            opsPort: resolveOpsPort(opts),
+            opsBindHost: resolveOpsBindHost({}),
+            adminUser: DEFAULT_ADMIN_USER,
+            adminPass,
+        }),
     };
-    // Only set HDB_ADMIN_PASSWORD if we have a real value — empty string
-    // would strip Harper's auth on an existing install
-    if (adminPass) {
-        env.HDB_ADMIN_PASSWORD = adminPass;
-    }
-    // models (flair#504 Phase 1): no env var needed — resources/embeddings-boot.ts
-    // self-registers the backend in-process on every boot (flair#694).
     const proc = spawn(process.execPath, [bin, "run", "."], {
         cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
     });
@@ -8726,22 +8940,29 @@ async function startFlairProcess(port) {
     // to the initial Harper spawn) followed by `flair restart` would silently
     // drop admin credentials — any subsequent auth'd call returns 401.
     const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
-    const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
+    // flair#863: the same env `flair start` builds, from the same builder — this
+    // path sets no HARPER_SET_CONFIG, and Harper RESTORES the pre-SET_CONFIG
+    // original for every key SET_CONFIG had forced whenever that variable is
+    // absent (cleanupRemovedEnvVar; see opsNetworkPortValue). This site used to
+    // set no OPERATIONSAPI_NETWORK_PORT at all, so every `flair restart` /
+    // `flair upgrade` on the non-launchd path silently reverted
+    // `operationsApi.network.port` to a bare number in harper-config.yaml and
+    // re-bound the ops API to all interfaces — permanently, since the reverted
+    // value is what the next boot reads. It also made doctor's
+    // `flair init && flair restart` remedy a no-op: the restart undid whatever
+    // init had just written.
     const env = {
         ...process.env,
-        ROOTPATH: dataDir,
-        // See the matching comment at the install-time spawn site above.
-        FLAIR_MODELS_DIR: modelsDir,
-        DEFAULTS_MODE: "dev",
-        HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
-        HTTP_PORT: String(port),
-        LOCAL_STUDIO: "false",
+        ...buildDirectSpawnEnv({
+            dataDir,
+            modelsDir: process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models"),
+            httpPort: port,
+            opsPort: resolveOpsPort({ port }),
+            opsBindHost: resolveOpsBindHost({}),
+            adminUser: DEFAULT_ADMIN_USER,
+            adminPass,
+        }),
     };
-    if (adminPass) {
-        env.HDB_ADMIN_PASSWORD = adminPass;
-    }
-    // models (flair#504 Phase 1): no env var needed — resources/embeddings-boot.ts
-    // self-registers the backend in-process on every boot (flair#694).
     const proc = spawn(process.execPath, [bin, "run", "."], {
         cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
     });
@@ -8958,7 +9179,7 @@ program
         // through the HNSW cosine index, which throws "Cosine distance comparison
         // requires an array" against rows whose stored embedding shape is
         // incompatible with the running Harper version (e.g. data written under
-        // @harperfast/harper@5.0.1 read under 5.0.9). The ops API bypasses the
+        // harper@5.0.1 read under 5.0.9). The ops API bypasses the
         // vector index — exactly what we need when the goal is to replace every
         // embedding with a freshly-computed one. Without this path, `flair
         // reembed` could not recover from the very condition it exists to fix.
@@ -9393,7 +9614,7 @@ Exit codes:
 
 "peer" here means a Flair federation peer (GET /FederationPeers on the
 origin) — NOT Harper's own cluster-replication nodes, which the OSS
-@harperfast/harper build this CLI ships does not expose (cluster_status is
+harper build this CLI ships does not expose (cluster_status is
 a harper-pro-only operation). A Fabric replica that was never
 federation-paired (\`flair federation pair\`) is invisible to this sweep —
 see src/fleet-verify.ts's file header for the full caveat.`)
@@ -9707,7 +9928,13 @@ program
     // 3b. Ops API bind (flair#670) — report-only finding, never auto-fixed.
     // Rebinding the ops API requires a Harper restart to take effect, so
     // `doctor --fix` deliberately does not touch it here; the fix is
-    // `flair init` (re-run) or a manual harper-config.yaml edit + restart.
+    // `flair init` (re-run, then `flair restart` to apply it) or a manual
+    // harper-config.yaml edit + restart. flair#827: re-running `flair init`
+    // used to regenerate ~/.flair/admin-pass unconditionally, desyncing it
+    // from Harper's already-persisted credential and breaking admin auth on
+    // the very re-run this remedy prescribed — resolveInitAdminPasswordSource
+    // (see its doc comment) now reuses the existing password instead, so this
+    // remedy is safe to follow on a working install.
     try {
         const harperConfigPath = join(defaultDataDir(), "harper-config.yaml");
         if (existsSync(harperConfigPath)) {
@@ -9716,7 +9943,7 @@ program
             const bind = detectOpsApiAllInterfacesBind(opsPortValue);
             if (bind.allInterfaces) {
                 console.log(`  ${render.icons.error} Ops API bound to ${render.wrap(render.c.bold, "all interfaces")} (${render.wrap(render.c.dim, String(opsPortValue))})`);
-                console.log(`     ${render.wrap(render.c.dim, "Single-host installs don't need this reachable off-box. Fix:")} flair init ${render.wrap(render.c.dim, "(rebinds to loopback + domain socket on next start; pass --ops-bind for deliberate remote admin)")}`);
+                console.log(`     ${render.wrap(render.c.dim, "Single-host installs don't need this reachable off-box. Fix:")} flair init && flair restart ${render.wrap(render.c.dim, "(rebinds to loopback + domain socket; re-init reuses your existing admin password, so this is safe on a running install — pass --ops-bind for deliberate remote admin)")}`);
                 issues++;
             }
         }
@@ -12082,7 +12309,7 @@ soul.command("list")
 // Slice 1: discovery + scaffold. Slice 2: YAML runtime + `import` for Shape A
 // + agentic-stack reference adapter as a built-in.
 // `test` and `export` are still stubbed; Shape B (npm code plugins) too.
-// See specs/FLAIR-BRIDGES.md.
+// See docs/bridges.md.
 const bridge = program.command("bridge").description("Manage memory bridges (import/export between Flair and foreign systems)");
 bridge
     .command("list")
@@ -13762,6 +13989,6 @@ if (import.meta.main) {
     await runCli();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
+export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
 // launchd label (flair#693)
 LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };