@tpsdev-ai/flair 0.53.0 → 0.54.1

package/dist/lib/daemon-liveness.js

@@ -11,7 +11,7 @@
  *
  * The fix is a classifier with FIVE states, not a boolean:
  *
- *   RUNNING       identity-verified pid alive  +  health 200
+ *   RUNNING       identity-verified pid alive  +  flair-identified /Health 2xx
  *   NOT_RUNNING   no pidfile, or verified dead  +  port refused
  *   WEDGED        identity-VERIFIED pid alive   +  not serving   -> stop ACTS
  *   DISAGREEMENT  evidence conflicts, identity NOT verified       -> stop REFUSES
@@ -36,6 +36,10 @@
  * reads, `kill(pid, 0)`, the health probe, the start-time readers) live in
  * `src/cli.ts`, so every branch here is unit-testable without a daemon.
  */
+/** Something accepted a TCP connection and spoke HTTP — flair or not. */
+export function healthIndicatesListener(health) {
+    return health.kind === "ok" || health.kind === "foreign";
+}
 /**
  * Classify the gathered evidence into one of the five states.
  *
@@ -53,6 +57,9 @@ export function classifyDaemonState(ev, ctx) {
     const pid = ev.pidfile.kind === "present" ? ev.pidfile.pid : null;
     const liveness = ev.pidLiveness;
     // THE INVARIANT: WEDGED is reachable only through a VERIFIED identity.
+    // RUNNING requires flair-identified /Health — a foreign 200 is not RUNNING
+    // (flair#1478). Verified + alive + foreign lands in WEDGED: our pid is
+    // proven, but it is not serving flair's /Health.
     if (ev.identity.kind === "verified" && liveness?.kind === "alive") {
         if (ev.health.kind === "ok") {
             return { state: "RUNNING", pid: ev.identity.pid };
@@ -64,7 +71,7 @@ export function classifyDaemonState(ev, ctx) {
         if (ev.health.kind === "refused") {
             return { state: "NOT_RUNNING" };
         }
-        if (ev.health.kind === "ok") {
+        if (healthIndicatesListener(ev.health)) {
             return {
                 state: "DISAGREEMENT",
                 detail: pid === null
@@ -205,3 +212,125 @@ export function parseSidecarJson(content) {
         return null;
     return { pid, startTimeMs, port, flairVersion };
 }
+/**
+ * Flair's public `/Health` fingerprint (resources/search-readiness.ts
+ * `buildPublicHealthBody`). `ok: true` alone is not enough — a decoy can
+ * return that. Require the fields that distinguish flair from "an HTTP
+ * server answered": `version`, `searchReady`, and `buildCommit` (always
+ * present, string or null).
+ */
+export function isFlairHealthBody(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return false;
+    const rec = body;
+    if (typeof rec.ok !== "boolean")
+        return false;
+    if (typeof rec.version !== "string" || rec.version.length === 0)
+        return false;
+    if (typeof rec.searchReady !== "boolean")
+        return false;
+    if (!("buildCommit" in rec))
+        return false;
+    if (rec.buildCommit !== null && typeof rec.buildCommit !== "string")
+        return false;
+    return true;
+}
+/**
+ * Classify a finished HTTP probe or a network error. Pure so the adapter
+ * (fetch) stays in cli.ts and every branch is unit-testable.
+ */
+export function classifyHealthProbe(input) {
+    if (input.kind === "network-error") {
+        if (input.code === "ECONNREFUSED" || input.code === "ConnectionRefused") {
+            return { kind: "refused" };
+        }
+        return { kind: "unreachable" };
+    }
+    if (input.status >= 200 && input.status < 300 && isFlairHealthBody(input.body)) {
+        return { kind: "ok" };
+    }
+    return { kind: "foreign" };
+}
+/** Trailing-slash-insensitive lexical compare — no filesystem, no realpath. */
+export function canonicalLexicalPath(p) {
+    if (p === "/" || p === "")
+        return "/";
+    return p.replace(/[/\\]+$/, "");
+}
+/**
+ * Bind the launched pid to the port's listener set. Empty / null is
+ * unavailable (best-effort skip). A populated set that omits `launchedPid`
+ * is a stale/foreign holder — not healed.
+ */
+export function classifyPortOwner(input) {
+    if (input.listenerPids === null || input.listenerPids.length === 0) {
+        return { kind: "unavailable" };
+    }
+    if (input.listenerPids.includes(input.launchedPid)) {
+        return { kind: "match" };
+    }
+    return { kind: "mismatch", listenerPids: input.listenerPids };
+}
+/**
+ * Confirm the listener is the flair instance we launched: worktree (cwd /
+ * cmdline resolves to `@tpsdev-ai/flair`) and dataDir (`ROOTPATH`). Each
+ * check is fail-closed when we could inspect, and skipped when we could not.
+ */
+export function classifyInstanceMatch(input) {
+    if (input.servingFlairPackage === false) {
+        return { kind: "mismatch", reason: "listener is not a flair worktree" };
+    }
+    if (input.environReadable) {
+        if (!input.processRootPath) {
+            return { kind: "mismatch", reason: "listener process has no ROOTPATH" };
+        }
+        if (canonicalLexicalPath(input.processRootPath) !== canonicalLexicalPath(input.expectedDataDir)) {
+            return {
+                kind: "mismatch",
+                reason: `listener ROOTPATH ${input.processRootPath} is not dataDir ${input.expectedDataDir}`,
+            };
+        }
+    }
+    const worktreeKnown = input.servingFlairPackage === true;
+    const dataDirKnown = input.environReadable && input.processRootPath !== null;
+    if (worktreeKnown || dataDirKnown)
+        return { kind: "match" };
+    return { kind: "unavailable" };
+}
+/** `/proc/<pid>/environ` is NUL-separated `KEY=value`. */
+export function parseNullSeparatedEnviron(raw) {
+    const out = {};
+    for (const entry of raw.split("\0")) {
+        if (!entry)
+            continue;
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            continue;
+        out[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return out;
+}
+export function extractRootPath(environ) {
+    const v = environ.ROOTPATH;
+    return typeof v === "string" && v.length > 0 ? v : null;
+}
+/**
+ * The #1454 sidecar self-heal gate (flair#1478). Adopt a reconstructed
+ * sidecar ONLY when /Health is flair-identified AND the port-owning pid
+ * is the launched instance (worktree/dataDir). Port-owner or instance
+ * `unavailable` is a best-effort skip — not a green light and not a
+ * refusal. `mismatch` on either is NOT healed. False-green is worse
+ * than no self-heal.
+ */
+export function shouldAdoptMissingSidecar(input) {
+    if (!input.sidecarAbsent || !input.dataDirSafe || !input.pidfilePresent || !input.pidAlive) {
+        return false;
+    }
+    if (input.health.kind !== "ok")
+        return false;
+    if (input.portOwner.kind === "mismatch")
+        return false;
+    if (input.instanceMatch.kind === "mismatch")
+        return false;
+    return true;
+}

package/dist/lib/doctor-config-path.js

@@ -0,0 +1,61 @@
+/**
+ * doctor-config-path.ts — resolve config.yaml the way the runtime does (flair#1514).
+ *
+ * Harper loads the component's `config.yaml` from the directory it was
+ * started in (`harper run .` → `./config.yaml`). `flair mcp enable` already
+ * walks `./config.yaml` then `~/.flair/config.yaml`. Doctor used to consult
+ * ONLY `~/.flair/config.yaml`, so a wrapper-launched component dir
+ * (`~/agents/flair/config.yaml`) printed "No config file at ~/.flair/config.yaml
+ * — using defaults" while the running instance was on the real file.
+ *
+ * One resolver, used by doctor's config line and by the federation-driver
+ * peer-gate (the gate must see the same file Harper sees, or a peered
+ * install whose peers live only in the component config would be treated
+ * as "no peers" and the driver check would be silenced — the #1514 hazard).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const CONFIG_BASENAMES = ["config.yaml", "config.yml"];
+function configFilesIn(dir) {
+    return CONFIG_BASENAMES.map((name) => join(dir, name));
+}
+/**
+ * Candidate paths in runtime order: cwd, then the component dir (if distinct),
+ * then `~/.flair`. Existence is not checked — callers that want the first
+ * existing file use `resolveFlairConfigYaml`.
+ */
+export function flairConfigYamlCandidates(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const homeDir = opts.homeDir ?? homedir();
+    const out = [...configFilesIn(cwd)];
+    if (opts.componentDir) {
+        const componentDir = resolve(opts.componentDir);
+        if (componentDir !== cwd)
+            out.push(...configFilesIn(componentDir));
+    }
+    out.push(...configFilesIn(join(homeDir, ".flair")));
+    return out;
+}
+/**
+ * First existing config.yaml along the runtime resolution order, or null.
+ */
+export function resolveFlairConfigYaml(opts = {}) {
+    for (const p of flairConfigYamlCandidates(opts)) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** `port:` from a YAML file, same regex `readPortFromConfig` uses on ~/.flair. */
+export function readPortFromYamlFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const m = readFileSync(path, "utf-8").match(/port:\s*(\d+)/);
+        return m ? Number(m[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/doctor-federation-driver.js

@@ -0,0 +1,189 @@
+/**
+ * doctor-federation-driver.ts — gate doctor's federation-driver check (flair#1514).
+ *
+ * `describeScheduledDriverFinding` treats unit-files-on-disk + not-loaded as
+ * ✗ INSTALLED BUT NOT LOADED. On a standalone install that never paired a
+ * hub there is nothing for the driver to run, so that ✗ is a false alarm
+ * (and a red one — operators tightening a fleet read it as broken sync).
+ *
+ * The gate:
+ *   - zero peers configured → N/A / informational, never ✗, never an issue
+ *   - peers ARE configured + driver present → the scheduled-driver verdict
+ *   - peers ARE configured + driver missing/broken → still ✗
+ *
+ * "Peers configured" is an OR of the same places the issue asked us to look:
+ * live /FederationPeers, component config.yaml (resolved from the component
+ * dir — see doctor-config-path.ts), FLAIR_FEDERATION_* hub/peer env (not
+ * the require-* policy flags), and node-scoped federation keys.
+ *
+ * Policy flags (`FLAIR_FEDERATION_REQUIRE_RECORD_*`) do not mean peers exist.
+ * Treating them as configured would re-fail a standalone install that only
+ * set a harden-the-edge default.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { load as parseYaml } from "js-yaml";
+import { describeScheduledDriverFinding, } from "./scheduler-platform.js";
+/** Known policy-only FLAIR_FEDERATION_* keys — not a peer/hub declaration. */
+export const FEDERATION_POLICY_ENV_KEYS = [
+    "FLAIR_FEDERATION_REQUIRE_RECORD_SIGNATURES",
+    "FLAIR_FEDERATION_REQUIRE_RECORD_PRINCIPAL",
+];
+const POLICY_ENV = new Set(FEDERATION_POLICY_ENV_KEYS);
+const ENV_ASSIGNMENT_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * True when any signal says this install has federation peers (or a hub)
+ * to sync with. Any positive signal wins — missing the component-dir
+ * config is how the check would go silent on a real peered install.
+ */
+export function federationPeersConfigured(input) {
+    if (typeof input.livePeerCount === "number" && input.livePeerCount > 0)
+        return true;
+    if (input.nodeKeyIds && input.nodeKeyIds.length > 0)
+        return true;
+    if (envDeclaresFederationPeers(input.env ?? {}))
+        return true;
+    if (configDeclaresFederationPeers(input.configDoc))
+        return true;
+    return false;
+}
+export function envDeclaresFederationPeers(env) {
+    for (const [key, value] of Object.entries(env)) {
+        if (!key.startsWith("FLAIR_FEDERATION_"))
+            continue;
+        if (POLICY_ENV.has(key))
+            continue;
+        if (typeof value === "string" && value.trim().length > 0)
+            return true;
+    }
+    return false;
+}
+function looksLikePeerEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const o = entry;
+    const keys = ["endpoint", "url", "hub", "target", "publicKey", "role", "id"];
+    return keys.some((k) => typeof o[k] === "string" && String(o[k]).trim().length > 0);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function peersArrayDeclares(value) {
+    return Array.isArray(value) && value.length > 0 && value.some(looksLikePeerEntry);
+}
+/**
+ * Conservative read of config.yaml: only explicit federation hub/peer
+ * declarations count. A Harper component config with no `federation`
+ * block (the shipped default) is not configured.
+ */
+export function configDeclaresFederationPeers(doc) {
+    if (!doc || typeof doc !== "object")
+        return false;
+    const root = doc;
+    const fed = root.federation;
+    if (fed && typeof fed === "object") {
+        const f = fed;
+        if (peersArrayDeclares(f.peers))
+            return true;
+        if (nonEmptyString(f.hub) || nonEmptyString(f.endpoint) || nonEmptyString(f.target) || nonEmptyString(f.url)) {
+            return true;
+        }
+    }
+    if (peersArrayDeclares(root.peers))
+        return true;
+    return false;
+}
+/** Load + parse a YAML file; unreadable/unparseable → null (not "no peers"). */
+export function loadYamlDoc(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return parseYaml(readFileSync(path, "utf-8")) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** KEY=value assignments from a .env body. Values are not interpreted beyond trim/quotes. */
+export function parseEnvAssignments(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const m = ENV_ASSIGNMENT_RE.exec(line);
+        if (!m)
+            continue;
+        let v = line.slice(line.indexOf("=") + 1).trim();
+        if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
+            (v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
+            v = v.slice(1, -1);
+        }
+        out[m[1]] = v;
+    }
+    return out;
+}
+/**
+ * Merge process.env FLAIR_FEDERATION_* with assignments from component
+ * `.env` files. Process env wins (same as Harper loadEnv: already-set
+ * names are not overwritten).
+ */
+export function collectFederationEnv(opts) {
+    const out = {};
+    const processEnv = opts.processEnv ?? process.env;
+    for (const [key, value] of Object.entries(processEnv)) {
+        if (key.startsWith("FLAIR_FEDERATION_"))
+            out[key] = value;
+    }
+    for (const p of opts.envFilePaths ?? []) {
+        if (!existsSync(p))
+            continue;
+        let text;
+        try {
+            text = readFileSync(p, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseEnvAssignments(text);
+        for (const [key, value] of Object.entries(parsed)) {
+            if (!key.startsWith("FLAIR_FEDERATION_"))
+                continue;
+            if (out[key] === undefined)
+                out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Doctor verdict for the federation sync driver (flair#1514).
+ *
+ * Not-configured is N/A: informational marker, never the fail marker,
+ * never an issue. Configured + missing/broken still ✗ — the check is
+ * gated, not silenced.
+ */
+export function describeFederationDriverFinding(input) {
+    if (!input.peersConfigured) {
+        const idle = input.driver.installed
+            ? "not configured (driver installed, idle)"
+            : "not configured";
+        return {
+            state: "not-enabled",
+            icon: "info",
+            isIssue: false,
+            message: `Federation: ${idle}`,
+            detail: input.driver.installed
+                ? ["No peers configured — the sync driver has nothing to run. This is the healthy default."]
+                : ["No peers configured. Pair a hub (`flair federation pair`) before enabling the sync driver."],
+        };
+    }
+    if (!input.driver.installed) {
+        return {
+            state: "degraded",
+            icon: "error",
+            isIssue: true,
+            message: `${input.driver.label}: not installed — nothing will run federation sync`,
+            detail: [
+                "Peers are configured, but the sync driver is not installed, so nothing will push to them.",
+                `Fix: ${input.driver.enableCommand}   # then check: ${input.driver.statusCommand}`,
+            ],
+        };
+    }
+    return describeScheduledDriverFinding(input.driver);
+}

package/dist/lib/doctor-run.js

@@ -22,6 +22,8 @@
 import { existsSync, readdirSync } from "node:fs";
 import { checkClaudeMdBootstrap, checkSessionStartHook, effectiveFlairUrl, hookCommandIsSilenced, isFlairHookCommand, partitionKeyIds, planAgentIterations, readClientMcpBlock, } from "../doctor-client.js";
 import { hookInstallHint, hookSettingsPath, installHook, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { staleHookRemedy, staleMcpClientPins, staleSessionStartHookPins } from "./owned-pins.js";
+import { flairCliVersion, isResolvedVersion } from "./mcp-spec.js";
 import { isDetached, renderDetachedWarning, } from "./launchd-management.js";
 /**
  * The catalog. This is the contract upgrade asserts against.
@@ -70,6 +72,24 @@ function runMcpBlock(ctx) {
             detail: `no Flair MCP server wired into any detected client (${mcp.join(", ")}) — wire one with: flair init --client <id>`,
         });
     }
+    // flair#1485 / Bugbot: a failed MCP pin refresh used to print nothing and
+    // leave the old @tpsdev-ai/flair-mcp pin in place. Presence is not
+    // currency — the same catalogue upgrade refreshes must fail here too.
+    const expected = flairCliVersion();
+    if (isResolvedVersion(expected)) {
+        const stale = staleMcpClientPins(ctx.homeDir, expected)
+            .filter((r) => wired.includes(r.target.id));
+        if (stale.length > 0) {
+            const first = stale[0];
+            const detail = stale.length === 1
+                ? `MCP server (${first.target.id}): pinned to flair-mcp@${first.pin} (installed CLI is ${expected})`
+                : `MCP server: stale pins ${stale.map((s) => `${s.target.id}@${s.pin}`).join(", ")} (installed CLI is ${expected})`;
+            return result(id, label, "fail", {
+                detail,
+                remedy: "flair upgrade",
+            });
+        }
+    }
     return result(id, label, "pass", { detail: `configured for ${wired.join(", ")}` });
 }
 function runFlairUrl(ctx) {
@@ -155,6 +175,26 @@ function runSessionStartHook(ctx) {
             remedy: hookInstallHint(harness),
         });
     }
+    // flair#1485: "it runs" is not "it is current". A hook whose pin is not
+    // the installed CLI version still launches the old adapter on every
+    // session. Compare against flairCliVersion() — not the MCP client pin —
+    // so two equally-stale pins cannot hide each other. Same owned-pin
+    // catalogue `flair upgrade` refreshes.
+    const expected = flairCliVersion();
+    if (isResolvedVersion(expected)) {
+        const stale = staleSessionStartHookPins(ctx.homeDir, expected)
+            .filter((r) => harnesses.includes(r.target.id));
+        if (stale.length > 0) {
+            const first = stale[0];
+            const detail = stale.length === 1
+                ? `SessionStart hook (${first.target.id}): pinned to flair-mcp@${first.pin} (installed CLI is ${expected})`
+                : `SessionStart hook: stale pins ${stale.map((s) => `${s.target.id}@${s.pin}`).join(", ")} (installed CLI is ${expected})`;
+            return result(id, label, "fail", {
+                detail,
+                remedy: staleHookRemedy(stale),
+            });
+        }
+    }
     return result(id, label, "pass", {
         detail: `wired for ${harnesses.join(", ")}`,
     });

package/dist/lib/entity-vocab-cli.js

@@ -5,9 +5,9 @@
  * INLINED, not imported: cross-boundary imports from src/ into resources/
  * don't survive npm packaging — tsconfig.cli.json compiles with
  * `rootDir: "src"`, so dist/cli.js has no resources/ module it can resolve
- * at the same relative path. This is the same reason src/cli.ts inlines the
- * federation crypto helpers (see the note beside `sortKeys()` there) and the
- * private-visibility filter. The two files MUST stay in sync:
+ * at the same relative path. This is the same reason src/commands/federation.ts
+ * inlines the federation crypto helpers (see the note beside `sortKeys()` there)
+ * and the private-visibility filter. The two files MUST stay in sync:
  * test/unit/cli-entities-option.test.ts imports BOTH and pins ENTITY_TYPES
  * equality, validator parity across a known-answer table, and the
  * entityFormatHint() string — drift fails CI rather than shipping.

package/dist/lib/federation-pair-identity.js

@@ -0,0 +1,47 @@
+/**
+ * Spoke pair identity (flair#822).
+ *
+ * Pair already returns `instance.{id,publicKey}` when the hub has a
+ * FederationInstance row (flair#213). An empty spoke hub-Peer key means
+ * that row was missing at pair time — a symptom of open #839, not a
+ * pair-response-shape bug. Chip is fail-closed: ERROR, never store
+ * `publicKey: ""`. Do not GET `/FederationInstance` from the spoke —
+ * that path is admin-gated (bootstrap Basic cannot read it) and
+ * find-or-creates a new Instance on a miss, which would invent a hub
+ * row. A spoke Peer write does not provision the missing hub row.
+ */
+function nonEmptyString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function instancePublicKey(value) {
+    const row = value && typeof value === "object" ? value : null;
+    return {
+        id: nonEmptyString(row?.id),
+        publicKey: nonEmptyString(row?.publicKey),
+    };
+}
+/**
+ * Accept a pair JSON body only when `instance.publicKey` is non-empty.
+ * `id` may fall back to `"hub"` if the key is present but the id is not.
+ */
+export function hubPeerFromPairResult(result) {
+    const inst = result && typeof result === "object"
+        ? result.instance
+        : undefined;
+    const { id, publicKey } = instancePublicKey(inst);
+    if (!publicKey)
+        return { ok: false, reason: "missing_public_key" };
+    return { ok: true, peer: { id: id || "hub", publicKey } };
+}
+export const EMPTY_HUB_PEER_KEY_ERROR = "hub pair response omitted instance.publicKey — refusing to store an empty hub Peer key. " +
+    "The hub likely has no FederationInstance row (flair#839); a spoke Peer write does not create one.";
+/**
+ * Fail-closed: pair `instance.publicKey` or ERROR. Never returns an empty key.
+ * Does not fetch `/FederationInstance` (admin-gated + find-or-create).
+ */
+export function resolveHubPeerIdentity(pairResult) {
+    const fromPair = hubPeerFromPairResult(pairResult);
+    if (fromPair.ok)
+        return { ...fromPair, source: "pair" };
+    return { ok: false, error: EMPTY_HUB_PEER_KEY_ERROR };
+}

package/dist/lib/launchd-repair.js

@@ -182,13 +182,14 @@ export function decideAdoptStop(state, postStopHealth) {
                 remedy: ["flair stop", "flair doctor --fix"],
             };
     }
-    // Proceed ONLY when the port is provably free (ECONNREFUSED). "ok" means
-    // something is still serving; "unreachable" means a wedged daemon may still
-    // be BOUND to the port (ignored SIGTERM) — both would EADDRINUSE on load.
+    // Proceed ONLY when the port is provably free (ECONNREFUSED). "ok" or
+    // "foreign" means something is still serving; "unreachable" means a wedged
+    // daemon may still be BOUND to the port (ignored SIGTERM) — both would
+    // EADDRINUSE on load.
     if (postStopHealth.kind !== "refused") {
         return {
             kind: "failed",
-            detail: postStopHealth.kind === "ok"
+            detail: postStopHealth.kind === "ok" || postStopHealth.kind === "foreign"
                 ? "port still occupied after stopping the direct process"
                 : "port not confirmed free after stopping the direct process (a wedged process may still hold it)",
             remedy: ["flair stop", "flair doctor --fix"],

package/dist/lib/ops-api-bind.js

@@ -0,0 +1,115 @@
+/**
+ * ops-api-bind.ts — one decision for "is the Harper ops API bound to all
+ * interfaces?", shared by `flair doctor` and `flair status` (flair#670,
+ * unified in flair#852).
+ *
+ * The Harper ops API used to bind all interfaces unconditionally. `flair init`
+ * now defaults it to loopback + the domain socket, with an escape hatch
+ * (`--ops-bind` / `FLAIR_OPS_BIND`) for deployments that genuinely need remote
+ * ops access (flair#670). That narrowing is only useful if every health surface
+ * agrees on what the running install actually bound, and it is what doctor
+ * reads out of Harper's own config. The predicate is an allow-list: ONLY a
+ * loopback host narrows the bind. A bare numeric port, a wildcard host
+ * (`0.0.0.0:19925`, `[::]:19925`, …), an empty/unspecified host and an
+ * unparseable value are all reported as exposed — a `host:port` string is not
+ * evidence of narrowing unless the host is actually loopback.
+ *
+ * That allow-list is the flair#852 wildcard blind spot. The detector originally
+ * treated ANY `host:port` as narrowed, so `flair init --ops-bind 0.0.0.0`
+ * persisted `0.0.0.0:19925` and both `flair status` and `flair doctor` printed
+ * green while the ops API was reachable off-box.
+ *
+ * flair#852 was the two surfaces disagreeing. `flair doctor` flagged the bare
+ * port while `flair status` printed "✓ all checks passing" — a security-relevant
+ * exposure visible to one command and invisible to the other, so users shipped
+ * with the ops API reachable off-box. The fix is structural: the decision lives
+ * HERE, both commands call it, and status folds the finding into the same
+ * warning verdict that drives its green line.
+ *
+ * Pure: parsing Harper's config is the caller's job (doctor/status both read it
+ * with `readHarperConfig`); this module only decides.
+ */
+/**
+ * Hosts that genuinely narrow the ops-API bind to loopback. This is an
+ * allow-list on purpose: ANYTHING not in it — a wildcard (`0.0.0.0`, `::`,
+ * `[::]`, `0:0:0:0:0:0:0:0`), an explicit routable host, an empty/unspecified
+ * host, or a value we cannot parse — is reported as exposed. The cost of a
+ * missed exposure (a user ships an ops API reachable off-box) is worse than the
+ * cost of warning about a bind we did not recognise.
+ */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+/**
+ * Best-effort host half of a persisted `operationsApi.network.port` value.
+ * Returns null when the value declares no host (a bare port) or the host is
+ * unparseable; the caller reports both as exposed.
+ *
+ * Handles the forms flair and Harper write:
+ *   - `127.0.0.1:19925`  → `127.0.0.1`
+ *   - `[::1]:19925`      → `::1`   (bracketed IPv6, port stripped)
+ *   - `[::]:19925`       → `::`
+ *   - `::1:19925`        → `::1`   (bare IPv6 with a trailing numeric port)
+ *   - `::`               → `::`    (bare wildcard, nothing to strip)
+ *   - `0:0:0:0:0:0:0:0`  → `0:0:0:0:0:0:0` (still not loopback — flagged)
+ *
+ * Splits on the LAST colon so an IPv6 literal keeps its port, matching
+ * `harperPortValue`. A trailing all-digit segment is treated as the port; a
+ * bare IPv6 like `::` has no trailing port, so the whole value is the host.
+ */
+function parseBindHost(str) {
+    if (str.startsWith("[")) {
+        const close = str.indexOf("]");
+        if (close === -1)
+            return null; // malformed bracket form — unparseable
+        return str.slice(1, close);
+    }
+    const lastColon = str.lastIndexOf(":");
+    if (lastColon === -1)
+        return null; // bare port — no host to narrow on
+    const tail = str.slice(lastColon + 1);
+    return /^\d+$/.test(tail) ? str.slice(0, lastColon) : str;
+}
+/**
+ * Decide whether a persisted `operationsApi.network.port` value (read back from
+ * harper-config.yaml) indicates an ops-API bind reachable off-box.
+ *
+ * A bare port number/numeric string is Harper's all-interfaces default (the
+ * pre-flair#670 behavior, or an install that predates the fix and has not been
+ * re-`init`ed). A `host:port` string narrows the bind ONLY when the host is
+ * loopback — a wildcard (`0.0.0.0:19925`, `[::]:19925`, `::19925`) is still
+ * all-interfaces, and is flagged (flair#852). Empty/unspecified and unparseable
+ * values are flagged too.
+ */
+export function detectOpsApiAllInterfacesBind(portValue) {
+    if (portValue === undefined || portValue === null)
+        return { allInterfaces: false, boundHost: null };
+    const str = String(portValue).trim();
+    if (str === "")
+        return { allInterfaces: false, boundHost: null };
+    const host = parseBindHost(str);
+    if (host !== null && LOOPBACK_HOSTS.has(host.toLowerCase())) {
+        return { allInterfaces: false, boundHost: host };
+    }
+    return { allInterfaces: true, boundHost: null };
+}
+const OPS_API_BIND_REMEDY = "Single-host installs don't need this reachable off-box. Fix: flair init && flair restart " +
+    "(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)";
+/**
+ * The ops-API bind finding for a parsed harper-config, or null when the config
+ * declares no ops port (nothing to report). This is the single source of truth
+ * `flair doctor` and `flair status` both call, so they cannot disagree about
+ * the same instance.
+ */
+export function opsApiBindFinding(harperConfig) {
+    const portValue = harperConfig?.operationsApi?.network?.port;
+    if (portValue === undefined || portValue === null || String(portValue).trim() === "")
+        return null;
+    const { allInterfaces, boundHost } = detectOpsApiAllInterfacesBind(portValue);
+    return {
+        allInterfaces,
+        portValue,
+        boundHost,
+        message: `Ops API bound to all interfaces (${String(portValue)})`,
+        remedy: OPS_API_BIND_REMEDY,
+    };
+}