@tpsdev-ai/flair 0.29.0 → 0.30.0

package/dist/cli-shim.cjs

@@ -9,7 +9,7 @@
  *   The real CLI (dist/cli.js) is an ES module. In ESM, every top-level
  *   `import` is HOISTED and the whole module graph is LINKED + EVALUATED before
  *   the first statement in the file body runs. Flair's deps (harper-fabric-
- *   embeddings requires Node >=22, @harperfast/harper / commander require >=20)
+ *   embeddings requires Node >=22, harper / commander require >=20)
  *   fail to load on an older engine — so a Node-version check placed even at the
  *   very top of cli.ts never executes: the import graph crashes first. That is
  *   exactly the silent-onboarding-failure bug (a Harper dev got zero output and

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
@@ -693,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`);
@@ -709,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;
@@ -2302,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
@@ -2338,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
@@ -2478,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/>
@@ -2492,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 });
@@ -6423,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}`);
@@ -6481,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}`);
@@ -7650,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`;
@@ -7758,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
@@ -8104,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")
@@ -8668,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",
     });
@@ -8820,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",
     });
@@ -9052,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.
@@ -9487,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.`)
@@ -13862,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, };

package/dist/deploy.js

@@ -156,28 +156,38 @@ export function deriveVerifyResources(packageRoot) {
     names.sort();
     return names.length ? names : [FALLBACK_VERIFY_RESOURCE];
 }
+// flair#870: flair declares the BARE `harper` package name, so that is probed
+// first. `@harperfast/harper` is a permanent lockstep publish of the same
+// source under the legacy scoped name; it stays in the probe list because
+// `packageRoot` can be a staged install of an OLDER published flair (see
+// src/fabric-upgrade.ts) that declared the scoped name.
+const HARPER_PKG_NAMES = ["harper", "@harperfast/harper"];
 function resolveHarperBin(packageRoot) {
-    const local = join(packageRoot, "node_modules/@harperfast/harper/dist/bin/harper.js");
-    if (existsSync(local))
-        return local;
-    try {
-        const req = createRequire(join(packageRoot, "package.json"));
-        const mainPath = req.resolve("@harperfast/harper");
-        let dir = dirname(mainPath);
-        for (let i = 0; i < 6; i++) {
-            const candidate = join(dir, "dist/bin/harper.js");
-            if (existsSync(candidate))
-                return candidate;
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
+    for (const pkg of HARPER_PKG_NAMES) {
+        const local = join(packageRoot, "node_modules", pkg, "dist/bin/harper.js");
+        if (existsSync(local))
+            return local;
     }
-    catch {
-        /* fall through */
+    for (const pkg of HARPER_PKG_NAMES) {
+        try {
+            const req = createRequire(join(packageRoot, "package.json"));
+            const mainPath = req.resolve(pkg);
+            let dir = dirname(mainPath);
+            for (let i = 0; i < 6; i++) {
+                const candidate = join(dir, "dist/bin/harper.js");
+                if (existsSync(candidate))
+                    return candidate;
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        catch {
+            /* try the next package name */
+        }
     }
-    throw new Error("Could not locate Harper CLI binary (@harperfast/harper). " +
+    throw new Error(`Could not locate Harper CLI binary (tried ${HARPER_PKG_NAMES.join(", ")}). ` +
         "Flair deploy requires Harper to be installed alongside Flair.");
 }
 // Pure arg-array builder — separated from spawnHarper so the timeout