@tpsdev-ai/flair 0.23.0 → 0.24.0

package/dist/cli.js

@@ -3,11 +3,11 @@ import { Command } from "commander";
 import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
 import * as render from "./render.js";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, unlinkSync, chownSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
-import { spawn } from "node:child_process";
-import { createHash, createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } from "node:crypto";
+import { spawn, execFileSync } from "node:child_process";
+import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
 import { keystore } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
@@ -18,8 +18,11 @@ import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
 import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
-import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
+import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
+import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
 import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, describeAgentGateFinding, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
+import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
+import { readSecretFileSecure, readAdminPassFileSecure, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -125,82 +128,117 @@ const DEFAULT_OPS_PORT = 19925;
 const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
+// flair#670 — single-host default for the Harper ops API bind address.
+// Loopback-only (+ the domain socket, always provisioned) shrinks the
+// network-exposure surface: single-host installs don't need :9925 reachable
+// from any interface but the box itself, so an accidentally-exposed port
+// (misconfigured firewall/container networking) can't be reached remotely.
+const DEFAULT_OPS_BIND_HOST = "127.0.0.1";
+// readSecretFileSecure / readAdminPassFileSecure / defaultAdminPassPath /
+// resolveLocalAdminPass / defaultKeysDir now live in src/lib/auth-resolve.ts
+// (flair#747) — imported above, re-exported at the bottom of this file so
+// the public CLI module surface is unchanged.
+function defaultDataDir() {
+    return join(homedir(), ".flair", "data");
+}
+// ─── launchd label (flair#693) ─────────────────────────────────────────────
+// A bare "ai.tpsdev.flair" label is global to the current macOS user's
+// launchd session. A second Flair instance on one host (dev + prod, a
+// second user, the Harper-app embedded-component shape) used to collide on
+// that SAME label — `flair start`/`stop`/`restart` from either instance
+// could silently unload/replace the OTHER instance's daemon (see
+// test/unit/upgrade-data-snapshot.test.ts's header for the exact hazard
+// this caused, pre-fix).
+//
+// The label now incorporates instance identity: a short deterministic hash
+// of the RESOLVED data dir. Same data dir -> same label every run
+// (idempotent init/start/stop); different data dirs -> different labels,
+// so two instances can never collide. Every code path that touches the
+// label goes through the helpers below — no scattered label string
+// literals — and resolveLaunchdLabel()/migrateLegacyLaunchdLabel() handle
+// finding + cleanly migrating a pre-flair#693 install off the bare legacy
+// label so it is never orphaned.
+const LEGACY_LAUNCHD_LABEL = "ai.tpsdev.flair";
+function defaultLaunchAgentsDir() {
+    return join(homedir(), "Library", "LaunchAgents");
+}
+/** Instance-scoped launchd label for `dataDir`: ai.tpsdev.flair.<8-hex-char sha256 of the resolved data dir>. */
+function launchdLabel(dataDir) {
+    const hash = createHash("sha256").update(resolve(dataDir), "utf8").digest("hex").slice(0, 8);
+    return `${LEGACY_LAUNCHD_LABEL}.${hash}`;
+}
+function launchdPlistPath(label, launchAgentsDir = defaultLaunchAgentsDir()) {
+    return join(launchAgentsDir, `${label}.plist`);
+}
 /**
- * Read a secret (admin password, Fabric password, ...) from a file, refusing
- * if the file is world/group readable.
- *
- * Secret files (default ~/.flair/admin-pass; also used for --fabric-password-file)
- * are short-lived values generated by `openssl rand` — mode 0600 keeps them
- * out of reach of other local users + most backup tooling. A 0644 file
- * silently leaks the secret to anyone with read access to the user's home
- * (multi-user hosts, NFS, time-machine snapshots, etc.).
- *
- * Throws with an actionable error if the file isn't owner-only, otherwise
- * returns the trimmed file content (values generated by `openssl rand
- * -base64` conventionally end in a newline). `flagName` is only used to
- * personalize the error text (e.g. "--admin-pass-file" vs
- * "--fabric-password-file") — the check itself is identical either way.
+ * Which launchd label an existing installation for `dataDir` is actually
+ * registered under right now. Prefers the new instance-scoped label if its
+ * plist is present; falls back to the pre-flair#693 bare
+ * LEGACY_LAUNCHD_LABEL if only THAT plist is present (so start/stop/
+ * uninstall against an old install still find and manage it instead of
+ * silently no-op'ing and orphaning it); otherwise returns the new label
+ * with nothing registered yet (e.g. before the first `init`).
+ * `launchAgentsDir` is injectable so tests can point this at a temp dir
+ * instead of the real ~/Library/LaunchAgents.
+ */
+function resolveLaunchdLabel(dataDir, launchAgentsDir = defaultLaunchAgentsDir()) {
+    const newLabel = launchdLabel(dataDir);
+    const newPlistPath = launchdPlistPath(newLabel, launchAgentsDir);
+    if (existsSync(newPlistPath))
+        return { label: newLabel, plistPath: newPlistPath, isLegacy: false };
+    const legacyPlistPath = launchdPlistPath(LEGACY_LAUNCHD_LABEL, launchAgentsDir);
+    if (existsSync(legacyPlistPath))
+        return { label: LEGACY_LAUNCHD_LABEL, plistPath: legacyPlistPath, isLegacy: true };
+    return { label: newLabel, plistPath: newPlistPath, isLegacy: false };
+}
+/**
+ * Migrate a pre-flair#693 legacy-labeled launchd service to the new
+ * instance-scoped label for `dataDir`: unload the legacy service FIRST,
+ * then rewrite its plist content under the new label/path (same content,
+ * only the <Label> value and filename change) and remove the legacy plist
+ * file. There is never a moment where both the legacy and new labels are
+ * registered for the same data dir. No-op (migrated: false) if there's
+ * nothing legacy to migrate, or the new label is already registered.
  */
-function readSecretFileSecure(path, flagName) {
-    if (!existsSync(path)) {
-        throw new Error(`${flagName} path does not exist: ${path}`);
+function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defaultLaunchAgentsDir()) {
+    const resolved = resolveLaunchdLabel(dataDir, launchAgentsDir);
+    if (!resolved.isLegacy) {
+        return { migrated: false, label: resolved.label, plistPath: resolved.plistPath };
     }
-    const st = statSync(path);
-    if (st.mode & 0o077) {
-        const modeOctal = (st.mode & 0o777).toString(8).padStart(3, "0");
-        throw new Error(`Refusing to read ${flagName} at ${path}: permissions ${modeOctal} are too open. ` +
-            `Run \`chmod 600 ${path}\` to restrict to owner-only.`);
+    const newLabel = launchdLabel(dataDir);
+    const newPlistPath = launchdPlistPath(newLabel, launchAgentsDir);
+    try {
+        runLaunchctl(`launchctl unload "${resolved.plistPath}"`);
     }
-    const content = readFileSync(path, "utf-8").replace(/\s+$/, "");
-    if (!content) {
-        throw new Error(`${flagName}: file is empty or contains only whitespace: ${path}`);
+    catch { /* best effort */ }
+    const legacyContent = readFileSync(resolved.plistPath, "utf-8");
+    const newContent = legacyContent.replace(`<key>Label</key><string>${LEGACY_LAUNCHD_LABEL}</string>`, `<key>Label</key><string>${newLabel}</string>`);
+    writeFileSync(newPlistPath, newContent);
+    try {
+        unlinkSync(resolved.plistPath);
     }
-    return content;
-}
-/** `readSecretFileSecure` specialized for --admin-pass-file (see that function for the shared check). */
-export function readAdminPassFileSecure(path) {
-    return readSecretFileSecure(path, "--admin-pass-file");
-}
-function defaultAdminPassPath() {
-    return join(homedir(), ".flair", "admin-pass");
+    catch { /* best effort */ }
+    return { migrated: true, label: newLabel, plistPath: newPlistPath };
 }
 /**
- * Resolve an admin password for LOCAL-only CLI convenience (`agent add`,
- * `principal add`) without requiring `--admin-pass` on every call (#590).
- * Also reused by `api()`'s local-target auth fallback (flair#634) — called
- * there as `resolveLocalAdminPass(undefined, !isLocal)`, so only its file leg
- * ever fires (the env leg is already handled by `api()` itself first).
- *
- * Resolution order: explicit value (the `--admin-pass` flag) → `FLAIR_ADMIN_PASS`
- * env → the secure `~/.flair/admin-pass` file `flair init` already writes with
- * mode 0600 (read via `readAdminPassFileSecure`, which enforces that mode).
- *
- * When `isRemoteTarget` is true, ONLY the explicit value is honored — the env
- * and file legs are skipped entirely. This is the security-critical guard: a
- * `--target`/`--ops-target` deploy must never silently reuse THIS machine's
- * local admin secret against someone else's Harper instance. Remote callers
- * keep requiring an explicit `--admin-pass`.
- *
- * Throws (via readAdminPassFileSecure) if the file exists but has unsafe
- * permissions, so a misconfigured file surfaces as an actionable chmod error
- * instead of a generic "admin pass required" message.
+ * Load + start `dataDir`'s launchd service, migrating off a pre-flair#693
+ * legacy registration FIRST if one is found (migrateLegacyLaunchdLabel
+ * above). Call order is load-bearing — unload legacy -> load new -> start
+ * new, never a window with both registered — and pinned by
+ * test/unit/launchd-label.test.ts. `load` failure is tolerated (e.g.
+ * "already loaded" is a common, harmless nonzero exit); `start` failure
+ * propagates so callers can fall back to a direct (non-launchd) start.
+ * Shared by the `start` command and startFlairProcess() (used by restart/
+ * upgrade/snapshot) so this sequence is expressed in exactly one place.
  */
-function resolveLocalAdminPass(explicit, isRemoteTarget = false, adminPassPath = defaultAdminPassPath()) {
-    if (explicit)
-        return explicit;
-    if (isRemoteTarget)
-        return undefined;
-    if (process.env.FLAIR_ADMIN_PASS)
-        return process.env.FLAIR_ADMIN_PASS;
-    if (!existsSync(adminPassPath))
-        return undefined;
-    return readAdminPassFileSecure(adminPassPath);
-}
-function defaultKeysDir() {
-    return join(homedir(), ".flair", "keys");
-}
-function defaultDataDir() {
-    return join(homedir(), ".flair", "data");
+function ensureLaunchdServiceLoaded(dataDir, runLaunchctl, launchAgentsDir = defaultLaunchAgentsDir()) {
+    const migration = migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir);
+    try {
+        runLaunchctl(`launchctl load "${migration.plistPath}"`);
+    }
+    catch { /* already loaded, etc. — best effort */ }
+    runLaunchctl(`launchctl start ${migration.label}`);
+    return migration;
 }
 function configPath() {
     // Check both .yaml and .yml extensions
@@ -282,6 +320,294 @@ 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;
+    if (envBind && envBind.trim() !== "")
+        return envBind.trim();
+    return DEFAULT_OPS_BIND_HOST;
+}
+/**
+ * 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,
+ * 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
+ * numeric port is exactly the pre-#670 behavior (all-interfaces); prefixing
+ * 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
+ * .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 },
+    };
+}
+/**
+ * Decide whether a persisted `operationsApi.network.port` value (read back
+ * from harper-config.yaml) indicates an all-interfaces ops-API bind
+ * (flair#670 doctor finding — report-only, no --fix: rebinding a live
+ * production instance is a restart-worthy change, not something `doctor`
+ * should do silently on an unrelated command).
+ *
+ * A bare port number/numeric string is Harper's all-interfaces default (the
+ * pre-#670 behavior, or an install that predates it and hasn't been
+ * re-`init`ed). A "host:port" string means something upstream — a `flair
+ * init` since #670, or manual config — already narrowed the bind.
+ */
+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 lastColon = str.lastIndexOf(":");
+    if (lastColon > 0) {
+        return { allInterfaces: false, boundHost: str.slice(0, lastColon).replace(/[[\]]/g, "") };
+    }
+    return { allInterfaces: true, boundHost: null };
+}
+// ─── Ops-socket permission posture (flair#763) ─────────────────────────────────
+//
+// The ops API domain socket (dataDir/operations-server) is protected by a
+// two-layer posture, with the socket's IMMEDIATE PARENT DIRECTORY as the
+// primary, load-bearing gate (resolved from the socket path — never a
+// hardcoded ~/.flair, so custom --data-dir installs get the same gate):
+//
+//   FLAIR_SOCKET_GROUP unset → parent dir 0700, socket 0600 (owner-only).
+//   FLAIR_SOCKET_GROUP set    → parent dir 0750 (owner+group traverse — else
+//                               the group grant is unreachable behind the dir
+//                               gate), socket 0660 + chgrp to that group.
+//
+// The two layers move in lockstep BOTH directions: a later UNSET returns the
+// dir to 0700 and the socket to 0600. The directory gate is race-free
+// (checked on every connect(2) traversal), umask-independent (explicit
+// chmod), and cross-platform (VFS-level, unlike socket-file permission
+// enforcement on connect(2) which varies across BSD lineage); the socket-file
+// mode is defense-in-depth within it. Split from #670 (network bind shipped
+// in #762); same local-admin-surface axis as #654 (authorizeLocal off).
+/** Group names allowed for FLAIR_SOCKET_GROUP — validated BEFORE existence
+ *  resolution (Sherlock #763): rejects path-traversal / whitespace / any
+ *  weird-but-"valid" name before it reaches getgrnam/chgrp. */
+export const SOCKET_GROUP_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9._-]*$/;
+export function isValidSocketGroupName(name) {
+    return SOCKET_GROUP_NAME_RE.test(name);
+}
+/** System groups broad enough that opting the ops socket into them silently
+ *  grants access to a wide set of accounts (macOS `staff` = every human user
+ *  on the box). Not a gate — a warning (Sherlock #763). */
+const BROAD_SYSTEM_GROUPS = new Set(["staff", "wheel", "users", "admin", "everyone", "adm"]);
+/** The posture (parent-dir + socket file modes) for a given FLAIR_SOCKET_GROUP
+ *  value. Pure — the single source of truth for the two lockstep states. */
+export function resolveSocketPosture(group) {
+    const g = (group ?? "").trim();
+    if (g.length > 0)
+        return { dirMode: 0o750, socketMode: 0o660, group: g };
+    return { dirMode: 0o700, socketMode: 0o600, group: null };
+}
+const NODE_SOCKET_FS = {
+    chmodSync,
+    statSync: (p) => {
+        const s = statSync(p);
+        return { mode: s.mode, uid: s.uid, gid: s.gid };
+    },
+    existsSync,
+    chownSync,
+};
+/** Resolve a group NAME to its numeric gid, cross-platform, or null if the
+ *  group does not exist. Uses execFileSync (arg vector — no shell) and the
+ *  name is regex-validated by the caller before it gets here. */
+function resolveGroupGid(name) {
+    try {
+        if (process.platform === "darwin") {
+            // dscl reads Directory Services (macOS groups don't live in /etc/group).
+            const out = execFileSync("dscl", [".", "-read", `/Groups/${name}`, "PrimaryGroupID"], {
+                encoding: "utf-8",
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            const m = out.match(/PrimaryGroupID:\s*(\d+)/);
+            return m ? Number(m[1]) : null;
+        }
+        // Linux / other POSIX: getent resolves NSS (files, LDAP, …).
+        const out = execFileSync("getent", ["group", name], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const parts = out.trim().split(":");
+        return parts.length >= 3 && parts[2] !== "" ? Number(parts[2]) : null;
+    }
+    catch {
+        return null; // command failed / group not found → treated as missing
+    }
+}
+/**
+ * Apply the ops-socket permission posture (flair#763). Idempotent: safe to
+ * call before Harper spawns (dir gate only — socket not present yet) and again
+ * after the socket appears (socket mode + optional chgrp). fs and resolveGid
+ * are injectable for unit tests (temp dirs / mocked group resolution).
+ *
+ * Fail-closed: an invalid OR missing FLAIR_SOCKET_GROUP is a hard error — NEVER
+ * a silent fallback to 0600. The group name is regex-validated BEFORE
+ * existence resolution.
+ */
+export function applyOpsSocketPosture(opts) {
+    const fs = opts.fs ?? NODE_SOCKET_FS;
+    const resolveGid = opts.resolveGid ?? resolveGroupGid;
+    const posture = resolveSocketPosture(opts.group);
+    let gid = null;
+    let broadGroup = false;
+    if (posture.group !== null) {
+        if (!isValidSocketGroupName(posture.group)) {
+            throw new Error(`Invalid FLAIR_SOCKET_GROUP '${posture.group}': group names must match ${SOCKET_GROUP_NAME_RE.source}.`);
+        }
+        gid = resolveGid(posture.group);
+        if (gid === null) {
+            throw new Error(`FLAIR_SOCKET_GROUP '${posture.group}' does not exist on this system. ` +
+                `Create the group first, or unset FLAIR_SOCKET_GROUP to use the owner-only default (dir 0700 / socket 0600).`);
+        }
+        broadGroup = BROAD_SYSTEM_GROUPS.has(posture.group);
+    }
+    const parentDir = dirname(opts.socketPath);
+    // Directory gate — the race-free primary control. Applied whether or not the
+    // socket exists yet, so it is in place BEFORE Harper creates the socket.
+    fs.chmodSync(parentDir, posture.dirMode);
+    // Socket file: defense-in-depth mode + optional chgrp — only once it exists.
+    let socketApplied = false;
+    if (fs.existsSync(opts.socketPath)) {
+        fs.chmodSync(opts.socketPath, posture.socketMode);
+        if (gid !== null) {
+            const st = fs.statSync(opts.socketPath);
+            try {
+                // uid unchanged (we own it); only the group moves.
+                fs.chownSync(opts.socketPath, st.uid, gid);
+            }
+            catch (err) {
+                throw new Error(`Failed to chgrp the ops socket to group '${posture.group}' (gid ${gid}): ${err?.code ?? err?.message ?? err}. ` +
+                    `chgrp requires membership in the target group — join '${posture.group}' or pick a different FLAIR_SOCKET_GROUP.`);
+            }
+        }
+        socketApplied = true;
+    }
+    return {
+        dirMode: posture.dirMode,
+        socketMode: posture.socketMode,
+        group: posture.group,
+        gid,
+        dirApplied: true,
+        socketApplied,
+        broadGroup,
+    };
+}
+/**
+ * Resolve + apply the ops-socket posture for a data dir, with the right
+ * fatal-vs-warn handling. A broken FLAIR_SOCKET_GROUP opt-in is a hard error
+ * (fail closed, no silent fallback); a failure of the owner-only default is
+ * non-fatal defense-in-depth (warn — the dir gate remains the load-bearing
+ * control). Returns the applied posture, or null on a non-fatal default-path
+ * failure. The socket path is derived from dataDir so a --data-dir install is
+ * gated at its own root, never a hardcoded ~/.flair.
+ */
+function readyOpsSocketPosture(dataDir) {
+    const socketPath = join(dataDir, "operations-server");
+    const group = process.env.FLAIR_SOCKET_GROUP;
+    const optedIn = !!(group && group.trim().length > 0);
+    try {
+        const res = applyOpsSocketPosture({ socketPath, group });
+        if (res.broadGroup) {
+            console.error(`warning: FLAIR_SOCKET_GROUP='${res.group}' is a broad system group — every member gets ops-socket access. Prefer a dedicated group.`);
+        }
+        return res;
+    }
+    catch (err) {
+        if (optedIn)
+            throw err; // opt-in misconfiguration — fail closed
+        console.error(`warning: could not tighten ops-socket permissions (${err?.message ?? err}); ` +
+            `the ${dataDir} directory gate remains the primary control.`);
+        return null;
+    }
+}
+/**
+ * The `flair doctor` detection matrix for the ops-socket posture (flair#763,
+ * Sherlock's exact six rows). Report-only — never auto-remediated (changing a
+ * live socket's mode needs a restart). Pure: takes the parent-dir mode, the
+ * socket mode, and whether FLAIR_SOCKET_GROUP is set (the opt-in signal).
+ */
+export function classifyOpsSocketPosture(dirMode, socketMode, groupOptIn) {
+    const dm = dirMode & 0o777;
+    const sm = socketMode & 0o777;
+    const dirWorld = (dm & 0o007) !== 0;
+    const sockWorld = (sm & 0o007) !== 0;
+    const dirGroup = (dm & 0o070) !== 0;
+    const sockGroup = (sm & 0o070) !== 0;
+    if (groupOptIn) {
+        // Deliberate multi-user posture (dir 0750 / socket 0660). Clean as long as
+        // no WORLD access leaked onto either — a world bit means a regressed mode.
+        if (!dirWorld && !sockWorld) {
+            return {
+                flagged: false,
+                row: "deliberate-group-clean",
+                reason: "deliberate FLAIR_SOCKET_GROUP posture (dir 0750 / socket 0660) — no world access",
+            };
+        }
+        return {
+            flagged: true,
+            row: "group-opt-in-world-open",
+            reason: "FLAIR_SOCKET_GROUP is set but the parent directory or socket is world-accessible",
+        };
+    }
+    // No opt-in. World access is the worst and takes precedence.
+    if (dirWorld && sockWorld) {
+        return {
+            flagged: true,
+            row: "both-open",
+            reason: "both the socket's parent directory and the socket itself are group/world-accessible",
+        };
+    }
+    if (dirWorld) {
+        return {
+            flagged: true,
+            row: "root-open",
+            reason: "the socket's parent directory is group/world-traversable — the primary access gate is breached",
+        };
+    }
+    if (sockWorld) {
+        return {
+            flagged: true,
+            row: "socket-open",
+            reason: "the ops socket is group/world-accessible",
+        };
+    }
+    // No world bits, but group bits present without the opt-in.
+    if (dirGroup || sockGroup) {
+        return {
+            flagged: true,
+            row: "group-mode-without-opt-in",
+            reason: "the socket carries group permissions but FLAIR_SOCKET_GROUP is not set (unintended group access)",
+        };
+    }
+    return {
+        flagged: false,
+        row: "default-clean",
+        reason: "owner-only posture (dir 0700 / socket 0600)",
+    };
+}
 // ─── Target resolution (remote Flair instance) ─────────────────────────────────
 // --target <url> (or FLAIR_TARGET env) points all CLI operations at a remote
 // Flair instance instead of localhost. This enables bootstrapping and
@@ -373,225 +699,51 @@ function b64(bytes) {
 function b64url(bytes) {
     return Buffer.from(bytes).toString("base64url");
 }
-function isLocalBase(base) {
-    try {
-        const url = new URL(base);
-        return url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1";
-    }
-    catch {
-        return !base;
-    }
-}
+// isLocalBase / ApiHttpError / resolveKeyPath / buildEd25519Auth / authFetch
+// now live in src/lib/auth-resolve.ts (flair#747) — imported above.
 /**
- * Thrown by api() for an HTTP-level failure (as opposed to a network error,
- * which fetch() itself throws before api() ever sees a status code).
- * Data-carrying, not just a message string, so callers downstream can make
- * decisions without re-parsing text (flair#741):
- *   - `status`: the HTTP status code, so probeInstance (src/probe.ts) can
- *     classify ProbeResult.authFailureKind (401/403 = credential failure,
- *     duck-typed off this property — see probe.ts's authedGet doc).
- *   - `noCredentials`: true only for the specific bare-403-no-auth-header
- *     case (api()'s own hint-carrying branch below) — distinguishes "we had
- *     nothing to send" from "we sent something and it was rejected" so
- *     verifyAuthedGet (below) knows exactly when its agent-key fallback
- *     applies (fix #2) versus when a real credential was tried and failed
- *     (where guessing at other keys would be misleading, not helpful).
+ * api() resolves the request's Harper HTTP/REST auth via the shared
+ * `authedRequest` (src/lib/auth-resolve.ts — see that module's header for
+ * the full 5-tier resolution order, including tier 5, the Ed25519 agent-key
+ * FLOOR this used to lack entirely). The only thing api() itself still owns
+ * is Harper-CLI-convention agentId extraction (FLAIR_AGENT_ID env, or an
+ * agentId embedded in the request body/query string) — request-shape
+ * knowledge that belongs here, not in the generic resolver.
+ *
+ * NOTE: this function is for the Harper HTTP/REST API only. The Harper
+ * operations API (used by seedAgentViaOpsApi / seedFederationInstanceViaOpsApi)
+ * ALSO honors authorizeLocal: a header-less loopback request to the ops port
+ * is auto-authorized as super_user (verified by live probe — flair#610). Those
+ * helpers nonetheless send Basic admin auth UNCONDITIONALLY, so they never
+ * depend on that ambient elevation and behave identically against a remote or
+ * hardened instance. Hardening the ops-API loopback posture itself (bind scope
+ * / disabling authorizeLocal there) is tracked separately in flair#654 and is
+ * out of scope for this HTTP/REST auth path.
  */
-class ApiHttpError extends Error {
-    status;
-    noCredentials;
-    constructor(status, message, noCredentials = false) {
-        super(message);
-        this.name = "ApiHttpError";
-        this.status = status;
-        this.noCredentials = noCredentials;
-    }
-}
 async function api(method, path, body, options) {
     // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
     // When baseUrl is provided (--target), use it directly.
     const savedPort = readPortFromConfig();
     const defaultUrl = savedPort ? `http://127.0.0.1:${savedPort}` : `http://127.0.0.1:${DEFAULT_PORT}`;
     const base = options?.baseUrl ?? (process.env.FLAIR_URL || defaultUrl);
-    const isLocal = isLocalBase(base);
-    // Auth resolution order (flair#634 — local targets used to send NO auth at
-    // all here and ride Harper's authorizeLocal forged super_user; #632 gated
-    // FederationInstance/FederationPeers behind allowAdmin, so credential-less
-    // local calls to those now 403 instead of silently passing):
-    // 1. FLAIR_TOKEN env → Bearer token (backward compat)
-    // 2. FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD env → Basic admin auth. Applies to
-    //    BOTH local and remote targets — an explicit env var always wins, local
-    //    included, so a caller that sets it never depends on authorizeLocal.
-    // 3. FLAIR_AGENT_ID env + key file → Ed25519 signature (standard)
-    // 4. LOCAL TARGETS ONLY: the secure ~/.flair/admin-pass file `flair init`
-    //    writes (#593) → Basic admin auth, via the same resolveLocalAdminPass
-    //    convenience `agent add`/`principal add` already use (#590). Guarded to
-    //    isLocal so a --target/FLAIR_URL request aimed elsewhere never rides
-    //    this machine's local admin secret.
-    // 5. No auth (remote will 401/403; local now also gets a real 403 from
-    //    #632-gated resources instead of the old forged-admin passthrough)
-    //
-    // NOTE: this function is for the Harper HTTP/REST API only. The Harper
-    // operations API (used by seedAgentViaOpsApi / seedFederationInstanceViaOpsApi)
-    // ALSO honors authorizeLocal: a header-less loopback request to the ops port
-    // is auto-authorized as super_user (verified by live probe — flair#610). Those
-    // helpers nonetheless send Basic admin auth UNCONDITIONALLY, so they never
-    // depend on that ambient elevation and behave identically against a remote or
-    // hardened instance. Hardening the ops-API loopback posture itself (bind scope
-    // / disabling authorizeLocal there) is tracked separately in flair#654 and is
-    // out of scope for this HTTP/REST auth path.
-    let authHeader;
-    const token = process.env.FLAIR_TOKEN;
-    if (token) {
-        authHeader = `Bearer ${token}`;
-    }
-    else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
-        // Admin Basic auth — used by federation, backup, and other admin CLI commands
-        const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
-        authHeader = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
-    }
-    else {
-        // Extract agentId from body (POST/PUT) or URL query params (GET)
-        let agentId = process.env.FLAIR_AGENT_ID || (body && typeof body === "object" ? body.agentId : undefined);
-        if (!agentId && path.includes("agentId=")) {
-            const match = path.match(/agentId=([^&]+)/);
-            if (match)
-                agentId = decodeURIComponent(match[1]);
-        }
-        if (agentId) {
-            const keyPath = resolveKeyPath(agentId);
-            if (keyPath) {
-                try {
-                    // Sign the path without query params — auth middleware verifies the clean path
-                    // Auth middleware verifies the full request path including query params
-                    authHeader = buildEd25519Auth(agentId, method, path, keyPath);
-                }
-                catch (err) {
-                    // Key exists but auth build failed — warn and continue without auth
-                    const message = err instanceof Error ? err.message : String(err);
-                    console.error(`Warning: Ed25519 auth failed for agent '${agentId}': ${message}`);
-                }
-            }
-        }
-        // Local-only fallback (flair#634): no explicit env, no usable agent key.
-        // FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD are already ruled out by this point
-        // (handled above), so resolveLocalAdminPass's env leg is a no-op here and
-        // this only ever resolves the ~/.flair/admin-pass file — isRemoteTarget
-        // is `!isLocal` so it's skipped entirely for --target/FLAIR_URL requests.
-        if (!authHeader) {
-            try {
-                const filePass = resolveLocalAdminPass(undefined, !isLocal);
-                if (filePass) {
-                    authHeader = `Basic ${Buffer.from(`admin:${filePass}`).toString("base64")}`;
-                }
-            }
-            catch (err) {
-                // File exists but has unsafe permissions — warn (never the secret
-                // itself) and fall through to no-auth.
-                const message = err instanceof Error ? err.message : String(err);
-                console.error(`Warning: ~/.flair/admin-pass unusable: ${message}`);
-            }
-        }
-    }
-    const res = await fetch(`${base}${path}`, {
-        method,
-        headers: {
-            "content-type": "application/json",
-            ...(authHeader ? { authorization: authHeader } : {}),
-        },
-        body: body ? JSON.stringify(body) : undefined,
-    });
-    // Handle 204 No Content (e.g., PUT upsert returns empty body)
-    if (res.status === 204 || res.headers.get("content-length") === "0") {
-        if (!res.ok)
-            throw new ApiHttpError(res.status, `HTTP ${res.status}`);
-        return { ok: true };
-    }
-    const text = await res.text();
-    if (!res.ok) {
-        // 403 with no credentials sent at all is the flair#634 case: a gated
-        // resource (e.g. #632's FederationInstance/FederationPeers) rejected a
-        // credential-less call. Name the fix instead of surfacing the raw
-        // "forbidden" body — never a stack trace.
-        if (res.status === 403 && !authHeader) {
-            const hint = isLocal
-                ? "Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass."
-                : "Set FLAIR_ADMIN_PASS (remote targets have no local admin-pass fallback).";
-            throw new ApiHttpError(403, `HTTP 403: no credentials sent. ${hint}`, /* noCredentials */ true);
-        }
-        throw new ApiHttpError(res.status, text || `HTTP ${res.status}`);
-    }
-    if (!text)
-        return { ok: true };
-    return JSON.parse(text);
-}
-/** Find the agent's private key file from standard locations. */
-function resolveKeyPath(agentId) {
-    const candidates = [
-        process.env.FLAIR_KEY_DIR ? join(process.env.FLAIR_KEY_DIR, `${agentId}.key`) : null,
-        join(homedir(), ".flair", "keys", `${agentId}.key`),
-        join(homedir(), ".tps", "secrets", "flair", `${agentId}-priv.key`),
-    ].filter(Boolean);
-    return candidates.find((p) => existsSync(p)) ?? null;
-}
-/** Build a TPS-Ed25519 auth header from a raw 32-byte seed on disk. */
-function buildEd25519Auth(agentId, method, path, keyPath) {
-    const raw = readFileSync(keyPath);
-    const pkcs8Header = Buffer.from("302e020100300506032b657004220420", "hex");
-    let privKey;
-    if (raw.length === 32) {
-        // Raw 32-byte seed
-        privKey = createPrivateKey({ key: Buffer.concat([pkcs8Header, raw]), format: "der", type: "pkcs8" });
-    }
-    else {
-        // Try as base64-encoded PKCS8 DER (standard Flair key format)
-        const decoded = Buffer.from(raw.toString("utf-8").trim(), "base64");
-        if (decoded.length === 32) {
-            // Base64-encoded raw seed
-            privKey = createPrivateKey({ key: Buffer.concat([pkcs8Header, decoded]), format: "der", type: "pkcs8" });
-        }
-        else {
-            // Full PKCS8 DER or PEM
-            try {
-                privKey = createPrivateKey({ key: decoded, format: "der", type: "pkcs8" });
-            }
-            catch {
-                privKey = createPrivateKey(raw);
-            }
-        }
-    }
-    const ts = Date.now().toString();
-    const nonce = randomUUID();
-    const payload = `${agentId}:${ts}:${nonce}:${method}:${path}`;
-    const sig = nodeCryptoSign(null, Buffer.from(payload), privKey).toString("base64");
-    return `TPS-Ed25519 ${agentId}:${ts}:${nonce}:${sig}`;
-}
-/** Authenticated fetch against Flair using Ed25519. */
-async function authFetch(baseUrl, agentId, keyPath, method, path, body) {
-    const auth = buildEd25519Auth(agentId, method, path, keyPath);
-    const headers = { Authorization: auth };
-    if (body !== undefined)
-        headers["Content-Type"] = "application/json";
-    return fetch(`${baseUrl}${path}`, {
-        method,
-        headers,
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
+    // Extract agentId from FLAIR_AGENT_ID env, or the body (POST/PUT) / URL
+    // query params (GET) — Harper-CLI-request-shape knowledge, not a generic
+    // auth concern, so it stays here rather than in authedRequest.
+    let agentId = process.env.FLAIR_AGENT_ID || (body && typeof body === "object" ? body.agentId : undefined);
+    if (!agentId && path.includes("agentId=")) {
+        const match = path.match(/agentId=([^&]+)/);
+        if (match)
+            agentId = decodeURIComponent(match[1]);
+    }
+    return authedRequest(method, path, body, { baseUrl: base, agentId, keysDir: options?.keysDir });
 }
 /**
  * The authedGet `flair upgrade` verification (flair#635/#741) hands to
- * probeInstance(): api()'s existing local-credential chain (FLAIR_TOKEN >
- * FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD > FLAIR_AGENT_ID+key > ~/.flair/admin-
- * pass file), with an Ed25519 agent-key fallback layered on top (flair#741
- * fix #2).
- *
- * The gap this closes: api()'s agent-key leg only fires when an agentId is
- * ALREADY known (FLAIR_AGENT_ID env, or an agentId in the request body/query
- * string) — none of which a bare `flair upgrade` ever sets. So on a machine
- * with an agent key under ~/.flair/keys but no admin password anywhere,
- * api() falls straight through to its no-credentials 403, even though
- * `flair doctor`'s verified-read gate would happily use that same key. This
- * wrapper is what actually reuses that path for verification.
+ * probeInstance() — now a one-line delegation to api(), since api() itself
+ * carries the tier-5 agent-key floor this wrapper used to implement
+ * standalone (flair#747 generalized flair#742's fix from "upgrade
+ * verification only" into api()'s own resolution chain, so every api()
+ * caller gets it, not just this one).
  *
  * Auth requirement of the verification target itself: /HealthDetail
  * (probeInstance's default versionPath) is NOT admin-gated — its
@@ -599,52 +751,9 @@ async function authFetch(baseUrl, agentId, keyPath, method, path, body) {
  * auth.ts), which permits ANY registered agent, not just admins. So a
  * signed request from any registered agent's key is sufficient; there's no
  * need to special-case a different, more-public endpoint.
- *
- * Only engages the fallback when api() reports NOTHING was available to
- * send (`ApiHttpError.noCredentials`) — a wrong/rejected credential (bad
- * admin-pass, unregistered FLAIR_AGENT_ID) is a different, more specific
- * problem than "nothing to try"; guessing at unrelated keys on disk in that
- * case would obscure the real error instead of explaining it.
- *
- * Selection rule when multiple keys exist in `keysDir` (mirrors doctor's
- * planAgentIterations sort — doctor-client.ts): try them in sorted
- * (deterministic) filename order, first one that authenticates wins. A
- * liveness/verified-read check only needs ONE working identity, unlike
- * doctor's per-agent registration report which needs to enumerate all of
- * them.
  */
 export async function verifyAuthedGet(baseUrl, path, keysDir) {
-    try {
-        return await api("GET", path, undefined, { baseUrl });
-    }
-    catch (err) {
-        if (!(err instanceof ApiHttpError) || !err.noCredentials)
-            throw err;
-        let keyFiles = [];
-        try {
-            keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key")).sort();
-        }
-        catch {
-            // No keys dir at all — nothing to fall back to.
-        }
-        for (const kf of keyFiles) {
-            const agentId = kf.replace(/\.key$/, "");
-            const keyPath = join(keysDir, kf);
-            try {
-                const res = await authFetch(baseUrl, agentId, keyPath, "GET", path);
-                if (res.ok)
-                    return await res.json();
-            }
-            catch {
-                // This key didn't work (unregistered, bad signature, network blip
-                // on this one attempt) — try the next one.
-            }
-        }
-        // No local key authenticated either — surface api()'s original,
-        // actionable "no credentials sent" hint rather than a fallback-specific
-        // message; it already names both remedies (FLAIR_ADMIN_PASS / `flair init`).
-        throw err;
-    }
+    return api("GET", path, undefined, { baseUrl, keysDir });
 }
 /**
  * flair#741 fix #3: does this ProbeResult's failure mean "the server
@@ -1772,6 +1881,7 @@ program
     .option("--agent <id>", "Alias for --agent-id")
     .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
     .option("--ops-port <port>", "Harper operations API port")
+    .option("--ops-bind <addr>", "Harper ops API bind address (env: FLAIR_OPS_BIND; default: 127.0.0.1 loopback-only for single-host — pass e.g. 0.0.0.0 for multi-host/Fabric remote admin)")
     .option("--admin-pass <pass>", "Admin password (generated if omitted)")
     .option("--admin-pass-file <path>", "Read admin password from file (chmod 600 recommended)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
@@ -1971,6 +2081,7 @@ program
     // ── Local init (full one-command setup) ──
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
+    const opsBindHost = resolveOpsBindHost(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     const dataDir = opts.dataDir ?? defaultDataDir();
     // Resolve MCP client selection (union of init's auto-wire + the multi-client
@@ -2063,6 +2174,13 @@ program
     // the fresh-start path) since the launchd plist step needs it too, even
     // when Harper was already running and the fresh-spawn branch was skipped.
     const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
+    // flair#763: put the ops-socket directory gate in place BEFORE Harper
+    // spawns, so the socket is never reachable during the create→chmod window
+    // (the dir gate is the race-free primary control). This also validates
+    // FLAIR_SOCKET_GROUP early — a bad group fails fast, before a full boot.
+    // The socket doesn't exist yet, so only the parent-dir mode is applied here.
+    mkdirSync(dataDir, { recursive: true });
+    readyOpsSocketPosture(dataDir);
     if (!opts.skipStart) {
         // Check if already running
         try {
@@ -2089,10 +2207,13 @@ program
             // request is no longer auto-authorized as super_user. Every ops-API
             // seed call below (seedAgentViaOpsApi et al.) already passes a real
             // adminPass via Basic auth, so this does not change local-init behavior.
+            // operationsApi (flair#670): loopback-only by default (buildOperationsApiConfig
+            // — see its doc comment for the "host:port" bind mechanism and the
+            // domainSocket schema path), escape hatch via --ops-bind/FLAIR_OPS_BIND.
             const harperSetConfig = JSON.stringify({
                 rootPath: dataDir,
                 http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
-                operationsApi: { network: { port: opsPort, cors: true }, domainSocket: opsSocket },
+                operationsApi: buildOperationsApiConfig(opsPort, opsSocket, opsBindHost),
                 mqtt: { network: { port: null }, webSocket: false },
                 localStudio: { enabled: false },
                 authentication: { authorizeLocal: false, enableSessions: true },
@@ -2173,22 +2294,46 @@ program
         console.log("Waiting for Harper health check...");
         await waitForHealth(httpPort, adminUser, adminPass, STARTUP_TIMEOUT_MS);
         console.log("Harper is healthy ✓");
+        // flair#763: the socket now exists — apply its file mode (+ chgrp for the
+        // FLAIR_SOCKET_GROUP opt-in). The dir gate above is re-asserted idempotently.
+        readyOpsSocketPosture(dataDir);
         // Register launchd service on macOS so Harper survives reboots
         // and `flair restart` / `flair stop` work via launchctl.
         if (process.platform === "darwin") {
             const harperBinPath = harperBin();
             if (harperBinPath) {
-                const label = "ai.tpsdev.flair";
-                const plistDir = join(homedir(), "Library", "LaunchAgents");
+                const label = launchdLabel(dataDir);
+                const plistDir = defaultLaunchAgentsDir();
                 mkdirSync(plistDir, { recursive: true });
-                const plistPath = join(plistDir, `${label}.plist`);
+                const plistPath = launchdPlistPath(label, plistDir);
+                // flair#693 migration: a pre-flair#693 install registered under
+                // the bare LEGACY_LAUNCHD_LABEL. init always writes fresh plist
+                // content below (it has the current ports/creds in hand), so
+                // migration here is just "clean up the old registration" —
+                // unload + remove it BEFORE writing the new one, so re-running
+                // init never leaves two services behind for this data dir.
+                const legacyPlistPath = launchdPlistPath(LEGACY_LAUNCHD_LABEL, plistDir);
+                if (existsSync(legacyPlistPath)) {
+                    try {
+                        const { execSync } = await import("node:child_process");
+                        execSync(`launchctl unload "${legacyPlistPath}"`, { stdio: "pipe" });
+                    }
+                    catch { /* best effort */ }
+                    try {
+                        unlinkSync(legacyPlistPath);
+                    }
+                    catch { /* best effort */ }
+                    console.log(`Migrated off legacy launchd label (${LEGACY_LAUNCHD_LABEL}) ✓`);
+                }
                 const opsSocket = join(dataDir, "operations-server");
                 // authorizeLocal: false (flair#654) — same posture as the initial spawn
                 // above; the launchd-managed process must not diverge from it.
+                // operationsApi (flair#670): same buildOperationsApiConfig posture as the
+                // initial spawn above — the launchd-managed process must not diverge.
                 const setConfig = JSON.stringify({
                     rootPath: dataDir,
                     http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
-                    operationsApi: { network: { port: opsPort, cors: true }, domainSocket: opsSocket },
+                    operationsApi: buildOperationsApiConfig(opsPort, opsSocket, opsBindHost),
                     mqtt: { network: { port: null }, webSocket: false },
                     localStudio: { enabled: false },
                     authentication: { authorizeLocal: false, enableSessions: true },
@@ -3133,6 +3278,121 @@ keys
     }
     console.log(`\n  ${render.wrap(render.c.bold, String(moved.length))} moved, ${kept.length} kept, ${ignored.length} ignored\n`);
 });
+// ─── flair hook ──────────────────────────────────────────────────────────────
+// Ambient memory via harness SessionStart hooks (flair#745, design record
+// #719 — the "Paved-paths" round). `flair doctor --fix`/`flair init` already
+// wire the same SessionStart hook as a side effect of a bigger flow; this is
+// the standalone, symmetric command family (install/uninstall/status) an
+// operator or a headless/scheduled setup script can run on its own. All the
+// mutation logic (fail-closed on malformed settings.json, idempotent merge,
+// dry-run delta, symmetric removal) lives in src/hook-install.ts — this
+// section is pure CLI plumbing: option parsing, default resolution, and
+// rendering the pure functions' results.
+function resolveHookAgentId(opts, homeDir) {
+    return (opts.agent ||
+        opts.agentId ||
+        process.env.FLAIR_AGENT_ID ||
+        readClientMcpBlock("claude-code", homeDir).agentId ||
+        undefined);
+}
+function resolveHookFlairUrl(opts, homeDir) {
+    return (opts.url ||
+        process.env.FLAIR_TARGET ||
+        process.env.FLAIR_URL ||
+        readClientMcpBlock("claude-code", homeDir).flairUrl ||
+        resolveBaseUrl({}));
+}
+function requireSupportedHarness(raw) {
+    const name = raw || "claude-code";
+    if (!isSupportedHarness(name)) {
+        console.error(`Unknown harness '${name}'. Supported: ${SUPPORTED_HARNESSES.join(", ")}`);
+        process.exit(1);
+    }
+    return name;
+}
+const hook = program.command("hook").description("Manage ambient-memory harness SessionStart hooks (flair#745)");
+hook
+    .command("install")
+    .description("Wire the Flair SessionStart hook into the harness config so memory loads automatically at session start")
+    .option("--harness <name>", `Target harness (${SUPPORTED_HARNESSES.join(", ")})`, "claude-code")
+    .option("--dry-run", "Print the exact JSON delta without writing")
+    .option("--agent <id>", "Agent ID to wire (else FLAIR_AGENT_ID, else the agent already wired for the claude-code MCP client)")
+    .option("--agent-id <id>", "Alias for --agent")
+    .option("--url <url>", "Flair URL to wire (else FLAIR_TARGET/FLAIR_URL, else the existing claude-code MCP wiring, else the local default)")
+    .action((opts) => {
+    const harness = requireSupportedHarness(opts.harness);
+    const home = homedir();
+    const agentId = resolveHookAgentId(opts, home);
+    if (!agentId) {
+        console.error("No agent id known — pass --agent <id>, set FLAIR_AGENT_ID, or run `flair init` / `flair agent add` first.");
+        process.exit(1);
+    }
+    const flairUrl = resolveHookFlairUrl(opts, home);
+    const dryRun = !!opts.dryRun;
+    const result = installHook({ homeDir: home, harness, agentId, flairUrl, dryRun });
+    console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook install")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
+    console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
+    if (result.backupPath) {
+        console.log(`     ${render.wrap(render.c.dim, `backup: ${result.backupPath}`)}`);
+    }
+    if (result.delta) {
+        console.log(`\n  ${render.wrap(render.c.dim, `${dryRun ? "would apply" : "applied"} (${result.delta.action}):`)}`);
+        console.log(render.asJSON(result.delta));
+    }
+    console.log("");
+    if (!result.ok)
+        process.exit(1);
+});
+hook
+    .command("uninstall")
+    .description("Remove the Flair SessionStart hook entry — only ours, everything else in the file is left untouched")
+    .option("--harness <name>", `Target harness (${SUPPORTED_HARNESSES.join(", ")})`, "claude-code")
+    .option("--dry-run", "Print the exact JSON delta without writing")
+    .action((opts) => {
+    const harness = requireSupportedHarness(opts.harness);
+    const home = homedir();
+    const dryRun = !!opts.dryRun;
+    const result = uninstallHook({ homeDir: home, harness, dryRun });
+    console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook uninstall")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
+    console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
+    if (result.backupPath) {
+        console.log(`     ${render.wrap(render.c.dim, `backup: ${result.backupPath}`)}`);
+    }
+    if (result.delta) {
+        console.log(`\n  ${render.wrap(render.c.dim, `${dryRun ? "would apply" : "applied"} (${result.delta.action}):`)}`);
+        console.log(render.asJSON(result.delta));
+    }
+    console.log("");
+    if (!result.ok)
+        process.exit(1);
+});
+hook
+    .command("status")
+    .description("Show whether the SessionStart hook is wired, its shape, and which Flair instance it targets")
+    .option("--harness <name>", `Target harness (${SUPPORTED_HARNESSES.join(", ")})`, "claude-code")
+    .action((opts) => {
+    const harness = requireSupportedHarness(opts.harness);
+    const home = homedir();
+    const status = hookStatus(home, harness);
+    console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook status")}\n`);
+    console.log(`  ${render.wrap(render.c.dim, "Harness:")} ${status.harness}`);
+    console.log(`  ${render.wrap(render.c.dim, "Config:")}  ${status.path}`);
+    if (status.parseError) {
+        console.log(`  ${render.icons.error} ${status.parseError}`);
+        console.log("");
+        process.exit(1);
+    }
+    if (!status.wired) {
+        console.log(`  ${render.icons.error} not wired`);
+        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install`);
+        console.log("");
+        process.exit(1);
+    }
+    console.log(`  ${status.correctShape ? render.icons.ok : render.icons.warn} wired${status.correctShape ? "" : " (unexpected shape — was it hand-edited?)"}`);
+    console.log(`     ${render.wrap(render.c.dim, "Agent:")}     ${status.agentId ?? render.wrap(render.c.dim, "(unknown — could not parse command)")}`);
+    console.log(`     ${render.wrap(render.c.dim, "Flair URL:")} ${status.flairUrl ?? render.wrap(render.c.dim, "(unknown — could not parse command)")}`);
+    console.log("");
+});
 // ─── flair mcp ───────────────────────────────────────────────────────────────
 // Headless agent-auth to a Harper MCP `/mcp` endpoint: RFC 7523
 // client_credentials + private_key_jwt, using the agent's EXISTING Ed25519
@@ -3235,6 +3495,574 @@ mcp
         process.exit(1);
     }
 });
+/** Default manifest path: `~/.flair/mcp-clients.json`, sibling to
+ *  admin-pass/config.yaml — independent of --keys-dir (a custom keys dir
+ *  doesn't imply a custom manifest location, and vice versa). */
+export function defaultMcpClientManifestPath() {
+    return join(homedir(), ".flair", "mcp-clients.json");
+}
+/** Read the manifest; a missing file is "no clients granted yet", not an
+ *  error. Malformed JSON is also treated as empty (defensive — a corrupt
+ *  manifest must never crash `list`), never partially parsed. */
+export function readMcpClientManifest(manifestPath) {
+    if (!existsSync(manifestPath))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Write the manifest, 0600 — it names every granted machine client's
+ *  key-file path, which is operationally sensitive even though it carries
+ *  no key material itself. */
+function writeMcpClientManifest(manifestPath, entries) {
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, JSON.stringify(entries, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(manifestPath, 0o600);
+}
+/** Machine-readable "ready-to-paste" MCP config block for `grant`'s output.
+ *  Pure — no I/O — so it's independently unit-testable. Mirrors the
+ *  `mcpServers` top-level key src/install/clients.ts's jsonSnippet already
+ *  established as this codebase's paste-target convention, pointed at the
+ *  Model-2 OAuth `/mcp` HTTP surface (not that stdio-bridge path).
+ *
+ *  The Authorization header CANNOT be a static, working value: a
+ *  client_credentials access token is short-lived (default 300s TTL,
+ *  server-side — see token.js's DEFAULT_CLIENT_CREDENTIALS_TTL) and this
+ *  grant issues no refresh token by design. Printing a real-looking-but-
+ *  dead token would be actively misleading, so the placeholder says exactly
+ *  what to run instead — never a fabricated "it just works" static header.
+ */
+export function buildMcpGrantConfig(params) {
+    return {
+        mcpServers: {
+            [params.name]: {
+                type: "http",
+                url: params.resource,
+                headers: {
+                    Authorization: `Bearer <mint before each session: ` +
+                        `flair mcp token --agent-id ${params.name} --json — copy .access_token here; ` +
+                        `expires in minutes, not a long-lived credential>`,
+                },
+            },
+        },
+        note: `Key material lives at ${params.keyFile} (0600, never printed). ` +
+            `The Bearer token above is a placeholder — mint a fresh one with ` +
+            `\`flair mcp token --agent-id ${params.name}\` at connection time.`,
+    };
+}
+export class McpClientNameExistsError extends Error {
+    constructor(name) {
+        super(`Machine client '${name}' already exists — use \`flair mcp revoke ${name}\` first or pick a different name.`);
+        this.name = "McpClientNameExistsError";
+    }
+}
+export class McpClientAgentIdCollisionError extends Error {
+    constructor(name) {
+        super(`An agent named '${name}' already exists in Flair but is not an mcp-granted machine client ` +
+            `— pick a different name (or \`flair agent remove ${name}\` first if that's intentional).`);
+        this.name = "McpClientAgentIdCollisionError";
+    }
+}
+export class McpClientNotFoundError extends Error {
+    constructor(name) {
+        super(`No granted machine client named '${name}' (see \`flair mcp list\`).`);
+        this.name = "McpClientNotFoundError";
+    }
+}
+const MCP_CLIENT_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+/**
+ * Core, testable `flair mcp grant` orchestration — no process.exit, no
+ * console output, so it's directly unit-testable with a mocked fetch and a
+ * temp dir (same split as classifyKeysDir/applyKeyPrune above). Throws
+ * typed errors; the CLI action below catches and formats them.
+ */
+export async function grantMcpClient(params, deps = {}) {
+    const { name, keysDir, manifestPath, issuer, opsPortOrUrl, adminUser, adminPass } = params;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const now = deps.now ?? (() => new Date().toISOString());
+    const generateKeyPair = deps.generateKeyPair ?? (() => nacl.sign.keyPair());
+    if (!MCP_CLIENT_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid machine client name '${name}' — must be 1-64 chars, start alphanumeric, ` +
+            `and contain only letters, digits, '_', '-' (it becomes an Agent id, a key filename, and a URL path segment).`);
+    }
+    const manifest = readMcpClientManifest(manifestPath);
+    if (manifest.some((e) => e.name === name)) {
+        throw new McpClientNameExistsError(name);
+    }
+    // Defense-in-depth: refuse to silently reuse/clobber an unrelated
+    // pre-existing Agent id (e.g. a human-run principal sharing this name).
+    const opsUrl = typeof opsPortOrUrl === "number" ? `http://127.0.0.1:${opsPortOrUrl}/` : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    const authHeader = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
+    const existingRes = await fetchImpl(opsUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: authHeader },
+        body: JSON.stringify({
+            operation: "search_by_value",
+            database: "flair",
+            table: "Agent",
+            search_attribute: "id",
+            search_value: name,
+            get_attributes: ["id"],
+        }),
+    });
+    if (existingRes.ok) {
+        const existing = await existingRes.json().catch(() => []);
+        if (Array.isArray(existing) && existing.length > 0) {
+            throw new McpClientAgentIdCollisionError(name);
+        }
+    }
+    mkdirSync(keysDir, { recursive: true });
+    const privPath = privKeyPath(name, keysDir);
+    const pubPath = pubKeyPath(name, keysDir);
+    const kp = generateKeyPair();
+    const seed = kp.secretKey.slice(0, 32);
+    const pubKeyB64url = b64url(kp.publicKey);
+    writeFileSync(privPath, Buffer.from(seed), { mode: 0o600 });
+    chmodSync(privPath, 0o600);
+    writeFileSync(pubPath, Buffer.from(kp.publicKey));
+    const nowIso = now();
+    const insertRes = await fetchImpl(opsUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: authHeader },
+        body: JSON.stringify({
+            operation: "insert",
+            database: "flair",
+            table: "Agent",
+            records: [{
+                    id: name,
+                    name,
+                    type: "agent",
+                    kind: "agent",
+                    status: "active",
+                    displayName: name,
+                    admin: false,
+                    defaultTrustTier: "unverified",
+                    runtime: "headless",
+                    publicKey: pubKeyB64url,
+                    createdAt: nowIso,
+                    updatedAt: nowIso,
+                }],
+        }),
+    });
+    if (!insertRes.ok) {
+        // Roll back the key files we just wrote — nothing left behind locally
+        // on a failed grant.
+        for (const p of [privPath, pubPath]) {
+            try {
+                const { unlinkSync } = await import("node:fs");
+                unlinkSync(p);
+            }
+            catch { /* best effort */ }
+        }
+        const text = await insertRes.text().catch(() => "");
+        throw new Error(`Failed to create Agent '${name}' via operations API (${insertRes.status}): ${text}`);
+    }
+    const clientId = `${issuer.replace(/\/+$/, "")}/MCPClientMetadata/${name}`;
+    const entry = {
+        name,
+        agentId: name,
+        clientId,
+        keyFile: privPath,
+        pubKeyFile: pubPath,
+        issuer,
+        createdAt: nowIso,
+        status: "active",
+    };
+    writeMcpClientManifest(manifestPath, [...manifest, entry]);
+    const resource = `${issuer.replace(/\/+$/, "")}/mcp`;
+    const config = buildMcpGrantConfig({ name, resource, keyFile: privPath });
+    return { entry, config };
+}
+/**
+ * Core, testable `flair mcp revoke` orchestration. SERVER-SIDE ack is
+ * mandatory before any local mutation: the Agent record backing this
+ * client's CIMD identity is DELETEd via the admin-authenticated ops API
+ * first; only a 2xx response ("ack") triggers local key-file deletion and
+ * manifest cleanup. A network error or non-2xx leaves everything local
+ * untouched and throws — the caller (CLI action) reports a clear failure
+ * and exits non-zero. This mirrors `agent remove`'s existing
+ * delete-then-cleanup ordering.
+ */
+export async function revokeMcpClient(params, deps = {}) {
+    const { name, manifestPath, opsPortOrUrl, adminUser, adminPass, keepKeys } = params;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const manifest = readMcpClientManifest(manifestPath);
+    const entry = manifest.find((e) => e.name === name);
+    if (!entry) {
+        throw new McpClientNotFoundError(name);
+    }
+    const opsUrl = typeof opsPortOrUrl === "number" ? `http://127.0.0.1:${opsPortOrUrl}/` : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    const authHeader = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
+    let delRes;
+    try {
+        delRes = await fetchImpl(opsUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: authHeader },
+            body: JSON.stringify({ operation: "delete", database: "flair", table: "Agent", ids: [entry.agentId] }),
+        });
+    }
+    catch (err) {
+        throw new Error(`Server-side revoke failed: could not reach the operations API to delete Agent '${entry.agentId}' ` +
+            `(${err?.message ?? err}). Nothing was deleted locally — retry once the instance is reachable.`);
+    }
+    if (!delRes.ok) {
+        const text = await delRes.text().catch(() => "");
+        throw new Error(`Server-side revoke failed (HTTP ${delRes.status}) deleting Agent '${entry.agentId}': ${text}. ` +
+            `Nothing was deleted locally.`);
+    }
+    // Server ack received — now safe to clean up locally.
+    if (!keepKeys) {
+        const { unlinkSync } = await import("node:fs");
+        for (const p of [entry.keyFile, entry.pubKeyFile]) {
+            if (p && existsSync(p)) {
+                try {
+                    unlinkSync(p);
+                }
+                catch { /* best effort */ }
+            }
+        }
+    }
+    writeMcpClientManifest(manifestPath, manifest.filter((e) => e.name !== name));
+    return entry;
+}
+mcp
+    .command("grant <name>")
+    .description("Provision a named, individually-revocable machine client for the /mcp OAuth surface " +
+    "(flair Agent + Ed25519 keypair; the existing CIMD path — see `flair mcp token` — makes it usable).")
+    .option("--issuer <url>", "Public origin for the CIMD client_id (defaults to FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL)")
+    .option("--keys-dir <dir>", "Directory to write the new key pair into (else FLAIR_KEY_DIR, ~/.flair/keys)")
+    .option("--manifest <path>", "Path to the local machine-client manifest (else ~/.flair/mcp-clients.json)")
+    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--json", "Print machine-readable JSON instead of a human summary")
+    .action(async (name, opts) => {
+    const issuer = opts.issuer ?? defaultMcpIssuer();
+    if (!issuer) {
+        console.error("Error: --issuer is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL) — the CIMD client_id " +
+            "must be a stable, publicly-resolvable URL.");
+        process.exit(1);
+    }
+    // Workflow gate: proof `flair mcp enable` has actually run against this
+    // instance — a live probe of the OAuth metadata endpoint (flair#756;
+    // replaces the old DCR-gate-token presence check, which a CIMD-only
+    // instance legitimately can't satisfy).
+    const gate = await selfVerifyMcpMetadata(issuer);
+    if (!gate.ok) {
+        console.error(`Error: the /mcp OAuth surface isn't answering at ${issuer} (${gate.detail}). Run \`flair mcp enable\` first.`);
+        process.exit(1);
+    }
+    const adminPass = resolveLocalAdminPass(opts.adminPass);
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for `flair mcp grant` (needed to insert into the Agent table). " +
+            "Set FLAIR_ADMIN_PASS, or make sure ~/.flair/admin-pass exists (created by `flair init`).");
+        process.exit(1);
+    }
+    const keysDir = opts.keysDir ?? defaultKeysDir();
+    const manifestPath = opts.manifest ?? defaultMcpClientManifestPath();
+    const opsPort = resolveOpsPort(opts);
+    try {
+        const { entry, config } = await grantMcpClient({
+            name,
+            keysDir,
+            manifestPath,
+            issuer,
+            opsPortOrUrl: opsPort,
+            adminUser: DEFAULT_ADMIN_USER,
+            adminPass,
+        });
+        if (opts.json) {
+            console.log(render.asJSON({ entry, config }));
+            return;
+        }
+        console.log(`\n${render.wrap(render.c.bold, `✅ Machine client '${name}' granted`)}\n`);
+        console.log(render.kv("client_id", entry.clientId));
+        console.log(render.kv("key file", render.wrap(render.c.dim, entry.keyFile)));
+        console.log(render.kv("issuer", entry.issuer));
+        console.log(`\n${render.wrap(render.c.dim, "Ready-to-paste MCP config (references the key file, never inline key material):")}\n`);
+        console.log(render.asJSON(config));
+        console.log("");
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+mcp
+    .command("revoke <name>")
+    .description("Server-side revoke a granted machine client (deletes its backing Agent record), then clean up locally.")
+    .option("--manifest <path>", "Path to the local machine-client manifest (else ~/.flair/mcp-clients.json)")
+    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
+    .option("--issuer <url>", "Public origin of the /mcp OAuth surface — used only for the enable-gate probe (defaults to FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL)")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--keep-keys", "Do not delete local key files after a successful server-side revoke")
+    .action(async (name, opts) => {
+    const issuer = opts.issuer ?? defaultMcpIssuer();
+    if (!issuer) {
+        console.error("Error: --issuer is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL) to verify the /mcp OAuth surface before revoking.");
+        process.exit(1);
+    }
+    // Workflow gate — see the matching comment on `grant` above.
+    const gate = await selfVerifyMcpMetadata(issuer);
+    if (!gate.ok) {
+        console.error(`Error: the /mcp OAuth surface isn't answering at ${issuer} (${gate.detail}). Run \`flair mcp enable\` first.`);
+        process.exit(1);
+    }
+    const adminPass = resolveLocalAdminPass(opts.adminPass);
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for `flair mcp revoke`.");
+        process.exit(1);
+    }
+    const manifestPath = opts.manifest ?? defaultMcpClientManifestPath();
+    const opsPort = resolveOpsPort(opts);
+    try {
+        await revokeMcpClient({
+            name,
+            manifestPath,
+            opsPortOrUrl: opsPort,
+            adminUser: DEFAULT_ADMIN_USER,
+            adminPass,
+            keepKeys: !!opts.keepKeys,
+        });
+        console.log(`${render.icons.ok} Machine client '${name}' revoked (server-side Agent record deleted${opts.keepKeys ? "; local keys kept" : " and local keys removed"}).`);
+    }
+    catch (err) {
+        console.error(`${render.icons.error} ${err.message}`);
+        process.exit(1);
+    }
+});
+mcp
+    .command("list")
+    .description("List granted machine clients (name, client_id, status, created).")
+    .option("--manifest <path>", "Path to the local machine-client manifest (else ~/.flair/mcp-clients.json)")
+    .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
+    .action((opts) => {
+    const manifestPath = opts.manifest ?? defaultMcpClientManifestPath();
+    const entries = readMcpClientManifest(manifestPath);
+    const mode = render.resolveOutputMode(opts);
+    if (mode === "json") {
+        console.log(render.asJSON(entries));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "no machine clients granted (see `flair mcp grant <name>`)")}`);
+        return;
+    }
+    console.log(`${render.wrap(render.c.bold, String(entries.length))} machine client(s)\n`);
+    const cols = [
+        { label: "name", key: "name", format: (v) => render.wrap(render.c.bold, String(v ?? "—")) },
+        { label: "client_id", key: "clientId", format: (v) => render.wrap(render.c.dim, String(v ?? "—")) },
+        { label: "status", key: "status", format: (v) => (v === "active" ? render.wrap(render.c.green, String(v)) : String(v ?? "—")) },
+        { label: "created", key: "createdAt", format: (v) => render.relativeTime(v) },
+    ];
+    console.log(render.table(cols, entries));
+});
+// ─── flair mcp enable / disable / status ────────────────────────────────────
+// flair#719 — the last piece of the paved-paths command family. Automates
+// docs/notes/mcp-oauth-model2.md's 8-step operator checklist into one
+// command, per the design record + K&S verdicts on #719's thread (see
+// src/lib/mcp-enable.ts's module header for the full binding design record,
+// including the scenario addendum: `enable` targets the HOSTED shape only —
+// it runs on the OPERATOR's machine, against a REMOTE instance, and refuses
+// honestly against a local-origin instance rather than walking eight steps
+// toward a connector that can never connect).
+/** Simple y/N confirmation over readline — TTY-only, mirrors the existing
+ *  restore-confirmation pattern (`flair snapshot restore`) above. */
+async function confirmYesNo(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => rl.question(`${question} [y/N] `, (a) => { rl.close(); res(a); }));
+    return /^y(es)?$/i.test(answer.trim());
+}
+/** Plain-text readline prompt (tests never exercise this — CLI-only). Used
+ *  for --idp-client-id/--idp-client-secret/--idp-subject when a flag is
+ *  omitted and stdin is a TTY. */
+async function promptText(question) {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => rl.question(question, (a) => { rl.close(); res(a); }));
+    return answer.trim();
+}
+function printEnableSteps(result) {
+    console.log(`\n${render.wrap(render.c.bold, "flair mcp enable")}${result.dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
+    for (const s of result.steps) {
+        console.log(`  ${s.ok ? render.icons.ok : render.icons.error} ${render.wrap(render.c.dim, s.step)}`);
+        console.log(`     ${s.detail}`);
+    }
+    console.log("");
+}
+mcp
+    .command("enable")
+    .description("One-command hosted-shape enablement of the OAuth /mcp surface for claude.ai — automates the " +
+    "docs/notes/mcp-oauth-model2.md checklist. Targets a REMOTE instance with a public HTTPS origin; " +
+    "refuses honestly against a local-origin instance.")
+    .option("--instance <url>", "Remote flair instance to enable against (else FLAIR_URL)")
+    .option("--issuer <url>", "Public origin claude.ai will use (else --instance)")
+    .option("--idp-provider <name>", "Upstream IdP provider", "github")
+    .option("--idp-client-id <id>", "IdP OAuth app client id (else prompted interactively)")
+    .option("--idp-client-secret <secret>", "IdP OAuth app client secret (else prompted interactively — prefer the prompt; an inline flag leaks to shell history)")
+    .option("--idp-subject <value>", "Your expected `sub`/login at the IdP (GitHub: your username; else prompted interactively)")
+    .option("--principal <id>", "Principal (Agent) to map your IdP identity to — personal-shape default", "self")
+    .option("--principal-kind <human|agent>", "Kind for a newly-created principal", "human")
+    .option("--secrets-mechanism <fabric-env-secrets|env-file>", "Override the shape-aware secrets mechanism (else auto-detected from --instance)")
+    .option("--secrets-path <path>", "Override the secrets staging file path")
+    .option("--cimd-allowed-hosts <hosts>", "Comma-separated clientIdMetadataDocuments.allowedHosts override (else claude.ai,claude.com)")
+    .option("--signing-key-file <path>", "RS256 signing key PEM file (else ~/.flair/mcp-signing-key.pem)")
+    .option("--admin-pass <pass>", "Admin password for the target instance (or FLAIR_ADMIN_PASS)")
+    .option("--confirm-secrets-applied", "Confirm the staged secrets are already live on the target instance's environment (skips the interactive confirm)")
+    .option("--dry-run", "Generate keys/tokens/config and validate inputs; skip every remote call")
+    .option("--json", "Print machine-readable JSON instead of a human summary")
+    .action(async (opts) => {
+    const instance = opts.instance ?? process.env.FLAIR_URL;
+    if (!instance) {
+        console.error("Error: --instance is required (or set FLAIR_URL) — `flair mcp enable` targets a specific remote instance.");
+        process.exit(1);
+    }
+    // Local-origin refusal short-circuits before we ask for anything else —
+    // never walk the operator through IdP app creation for a connector that
+    // can never connect.
+    const localCheck = checkLocalOriginRefusal(instance);
+    if (localCheck.refused) {
+        console.error(`${render.icons.error} ${localCheck.message}`);
+        process.exit(1);
+    }
+    const dryRun = Boolean(opts.dryRun);
+    // --instance is ALWAYS remote for this command (local is refused above)
+    // — isRemoteTarget=true so a missing --admin-pass/FLAIR_ADMIN_PASS never
+    // silently falls back to THIS machine's local ~/.flair/admin-pass file
+    // against someone else's instance (see resolveLocalAdminPass's doc comment).
+    const adminPass = dryRun ? (opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "") : resolveLocalAdminPass(opts.adminPass, /* isRemoteTarget */ true);
+    if (!dryRun && !adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required (the operations API on the target instance needs it " +
+            "for identity mapping + set_configuration + restart).");
+        process.exit(1);
+    }
+    let idpClientId = opts.idpClientId;
+    let idpClientSecret = opts.idpClientSecret;
+    let idpSubject = opts.idpSubject;
+    if (!dryRun && process.stdin.isTTY) {
+        if (!idpClientId)
+            idpClientId = await promptText(`${opts.idpProvider} OAuth app client id: `);
+        if (!idpClientSecret)
+            idpClientSecret = await promptText(`${opts.idpProvider} OAuth app client secret: `);
+        if (!idpSubject)
+            idpSubject = await promptText(`Your expected ${opts.idpProvider} login/sub: `);
+    }
+    const secretsMechanism = opts.secretsMechanism;
+    if (secretsMechanism && secretsMechanism !== "fabric-env-secrets" && secretsMechanism !== "env-file") {
+        console.error(`Error: --secrets-mechanism must be "fabric-env-secrets" or "env-file", got "${secretsMechanism}"`);
+        process.exit(1);
+    }
+    const cimdAllowedHosts = opts.cimdAllowedHosts
+        ? String(opts.cimdAllowedHosts).split(",").map((h) => h.trim()).filter(Boolean)
+        : undefined;
+    const result = await enableMcp({
+        instance,
+        issuer: opts.issuer,
+        idpProvider: opts.idpProvider,
+        idpClientId,
+        idpClientSecret,
+        idpSubject,
+        principal: opts.principal,
+        principalKind: opts.principalKind,
+        adminUser: DEFAULT_ADMIN_USER,
+        adminPass,
+        signingKeyFilePath: opts.signingKeyFile,
+        secretsMechanism,
+        secretsStagingPath: opts.secretsPath,
+        cimdAllowedHosts,
+        dryRun,
+        confirmSecretsApplied: Boolean(opts.confirmSecretsApplied),
+    }, { confirmPrompt: dryRun ? undefined : confirmYesNo });
+    if (opts.json) {
+        console.log(render.asJSON(result));
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
+    printEnableSteps(result);
+    if (result.refused) {
+        process.exit(1);
+    }
+    if (!result.ok) {
+        console.error(`${render.icons.error} enable failed at step "${result.failedStep}" — see detail above for the exact fix, then re-run \`flair mcp enable\` (earlier steps are idempotent and will be reused).`);
+        process.exit(1);
+    }
+    if (result.dryRun) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "dry-run: no remote calls were made.")}`);
+        return;
+    }
+    console.log(`${render.icons.ok} ${render.wrap(render.c.bold, "claude.ai can now connect.")}\n`);
+    console.log(result.pasteBlock ?? "");
+    console.log("");
+});
+mcp
+    .command("disable")
+    .description("Flag off + restart = byte-identical boot (Model-2 contract) — removes the /mcp OAuth surface.")
+    .option("--instance <url>", "Remote flair instance to disable against (else FLAIR_URL)")
+    .option("--admin-pass <pass>", "Admin password for the target instance (or FLAIR_ADMIN_PASS)")
+    .option("--confirm-flag-off", "Confirm FLAIR_MCP_OAUTH is already unset on the target instance's environment (skips the interactive confirm)")
+    .option("--json", "Print machine-readable JSON instead of a human summary")
+    .action(async (opts) => {
+    const instance = opts.instance ?? process.env.FLAIR_URL;
+    if (!instance) {
+        console.error("Error: --instance is required (or set FLAIR_URL).");
+        process.exit(1);
+    }
+    // --instance is always remote for this command — see the matching
+    // comment in `mcp enable` above.
+    const adminPass = resolveLocalAdminPass(opts.adminPass, /* isRemoteTarget */ true);
+    if (!adminPass) {
+        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required.");
+        process.exit(1);
+    }
+    const result = await disableMcp({ instance, adminUser: DEFAULT_ADMIN_USER, adminPass, confirmFlagOff: Boolean(opts.confirmFlagOff) }, { confirmPrompt: confirmYesNo });
+    if (opts.json) {
+        console.log(render.asJSON(result));
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
+    console.log(`${result.ok ? render.icons.ok : render.icons.error} ${result.detail}`);
+    if (!result.ok)
+        process.exit(1);
+});
+mcp
+    .command("status")
+    .description("Surface the /mcp OAuth surface's live state: enabled? CIMD advertised? granted machine-client count.")
+    .option("--instance <url>", "Remote flair instance to check (else FLAIR_URL)")
+    .option("--manifest <path>", "Path to the local machine-client manifest (else ~/.flair/mcp-clients.json)")
+    .option("--json", "Print machine-readable JSON instead of a human summary")
+    .action(async (opts) => {
+    const instance = opts.instance ?? process.env.FLAIR_URL;
+    if (!instance) {
+        console.error("Error: --instance is required (or set FLAIR_URL).");
+        process.exit(1);
+    }
+    const manifestPath = opts.manifest ?? defaultMcpClientManifestPath();
+    const result = await mcpStatus({ instance }, { countMachineClients: () => readMcpClientManifest(manifestPath).length });
+    if (opts.json) {
+        console.log(render.asJSON(result));
+        return;
+    }
+    console.log(`\n${render.wrap(render.c.bold, "flair mcp status")}\n`);
+    console.log(render.kv("instance", result.instance));
+    console.log(render.kv("enabled", result.enabled ? render.wrap(render.c.green, "yes") : render.wrap(render.c.yellow, "no")));
+    console.log(render.kv("metadata", result.detail));
+    // flair#756: CIMD is the only supported client-registration path — this
+    // reflects clientIdMetadataDocuments config presence on the target
+    // instance, the only signal `status` can see without admin credentials.
+    console.log(render.kv("CIMD", result.cimdSupported ? render.wrap(render.c.green, "advertised") : render.wrap(render.c.yellow, "not advertised")));
+    console.log(render.kv("machine clients", String(result.machineClientCount ?? 0)));
+    console.log("");
+});
 // ─── flair principal ─────────────────────────────────────────────────────────
 // 1.0 identity management. The Principal model extends Agent — this is the
 // preferred CLI surface for managing identities going forward.
@@ -5924,36 +6752,24 @@ async function fetchHealthDetail(opts) {
     }
     catch { /* unreachable */ }
     if (healthy) {
-        const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
-        if (agentId) {
-            const keyPath = resolveKeyPath(agentId);
-            if (keyPath) {
-                try {
-                    const authHeader = buildEd25519Auth(agentId, "GET", "/HealthDetail", keyPath);
-                    const res = await fetch(`${baseUrl}/HealthDetail`, {
-                        headers: { Authorization: authHeader },
-                        signal: AbortSignal.timeout(5000),
-                    });
-                    if (res.ok)
-                        healthData = await res.json().catch(() => null);
-                }
-                catch { /* fall through */ }
-            }
+        // flair#747: /HealthDetail is a verified-read (any registered agent, not
+        // just admins — see verifyAuthedGet's doc). Previously this tried the
+        // --agent/FLAIR_AGENT_ID key FIRST and admin-pass env only as a manual
+        // second attempt, with no admin-pass-FILE leg and no floor at all when
+        // no --agent was given — exactly the flair#741 gap, on the `status`
+        // command family specifically. Now routed through the shared resolver:
+        // env admin-pass > pinned agent key (if --agent/FLAIR_AGENT_ID given) >
+        // ~/.flair/admin-pass file > the Ed25519 floor (any registered key) when
+        // nothing else resolved.
+        try {
+            healthData = await authedRequest("GET", "/HealthDetail", undefined, {
+                baseUrl,
+                agentId: opts.agent || process.env.FLAIR_AGENT_ID,
+            });
         }
-        if (!healthData) {
-            const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS;
-            if (adminPass) {
-                try {
-                    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
-                    const res = await fetch(`${baseUrl}/HealthDetail`, {
-                        headers: { Authorization: auth },
-                        signal: AbortSignal.timeout(5000),
-                    });
-                    if (res.ok)
-                        healthData = await res.json().catch(() => null);
-                }
-                catch { /* fall through */ }
-            }
+        catch {
+            // No credential tier resolved a verified read — healthData stays
+            // null; callers already render an "unauthenticated" / limited view.
         }
     }
     return { healthy, baseUrl, healthData };
@@ -7620,9 +8436,10 @@ program
     const port = resolveHttpPort(opts);
     const platform = process.platform;
     if (platform === "darwin") {
-        // macOS: try launchd first
-        const label = "ai.tpsdev.flair";
-        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        // macOS: try launchd first. resolveLaunchdLabel (flair#693) finds
+        // whichever label this data dir is actually registered under —
+        // the new instance-scoped one, or a pre-flair#693 legacy install.
+        const { plistPath } = resolveLaunchdLabel(defaultDataDir());
         if (existsSync(plistPath)) {
             try {
                 const { execSync } = await import("node:child_process");
@@ -7677,17 +8494,19 @@ program
     }
     const platform = process.platform;
     if (platform === "darwin") {
-        const label = "ai.tpsdev.flair";
-        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        // resolveLaunchdLabel (flair#693) finds whichever label this data
+        // dir is currently registered under (new instance-scoped, or a
+        // pre-flair#693 legacy install) so the existsSync gate below is
+        // accurate before we attempt anything.
+        const { plistPath } = resolveLaunchdLabel(dataDir);
         if (existsSync(plistPath)) {
             try {
                 const { execSync } = await import("node:child_process");
-                try {
-                    execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
-                }
-                catch { }
-                execSync(`launchctl start ${label}`, { stdio: "pipe" });
+                const { label, migrated } = ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
+                if (migrated)
+                    console.log(`Migrated launchd service off the legacy label (${LEGACY_LAUNCHD_LABEL}) → ${label} ✓`);
                 await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
+                readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
                 console.log("✅ Flair started (launchd)");
                 return;
             }
@@ -7704,6 +8523,14 @@ program
     }
     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");
     const env = {
         ...process.env,
@@ -7713,7 +8540,7 @@ program
         DEFAULTS_MODE: "dev",
         HDB_ADMIN_USERNAME: DEFAULT_ADMIN_USER,
         HTTP_PORT: String(port),
-        OPERATIONSAPI_NETWORK_PORT: String(opsPort),
+        OPERATIONSAPI_NETWORK_PORT: `${opsBindHost}:${opsPort}`,
         LOCAL_STUDIO: "false",
     };
     // Only set HDB_ADMIN_PASSWORD if we have a real value — empty string
@@ -7729,6 +8556,7 @@ program
     proc.unref();
     try {
         await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
+        readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
         console.log(`✅ Flair started on port ${port}`);
     }
     catch {
@@ -7751,8 +8579,12 @@ program
  */
 async function stopFlairProcess(port) {
     if (process.platform === "darwin") {
-        const label = "ai.tpsdev.flair";
-        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        const dataDir = defaultDataDir();
+        // resolveLaunchdLabel (flair#693) finds whichever label this data dir
+        // is currently registered under (new instance-scoped, or a
+        // pre-flair#693 legacy install) — stop only needs to operate on
+        // whichever exists, no migration.
+        const { label, plistPath } = resolveLaunchdLabel(dataDir);
         if (existsSync(plistPath)) {
             try {
                 const { execSync } = await import("node:child_process");
@@ -7765,7 +8597,7 @@ async function stopFlairProcess(port) {
                 // immediately restart can verify exit. Without this, waitForHealth
                 // can race against the still-shutting-down old process and return
                 // success before KeepAlive brings the new one up.
-                const oldPid = readHarperPid(defaultDataDir());
+                const oldPid = readHarperPid(dataDir);
                 try {
                     execSync(`launchctl stop ${label}`, { stdio: "pipe" });
                 }
@@ -7803,21 +8635,17 @@ async function stopFlairProcess(port) {
  * Counterpart to `stopFlairProcess`; see that function's doc comment.
  */
 async function startFlairProcess(port) {
+    const dataDir = defaultDataDir();
     if (process.platform === "darwin") {
-        const label = "ai.tpsdev.flair";
-        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+        // resolveLaunchdLabel (flair#693) finds whichever label this data dir
+        // is currently registered under before we attempt anything.
+        const { plistPath } = resolveLaunchdLabel(dataDir);
         if (existsSync(plistPath)) {
             try {
                 const { execSync } = await import("node:child_process");
-                try {
-                    execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
-                }
-                catch { }
-                try {
-                    execSync(`launchctl start ${label}`, { stdio: "pipe" });
-                }
-                catch { }
+                ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
                 await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
+                readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture across restart/upgrade
                 return;
             }
             catch (err) {
@@ -7830,7 +8658,6 @@ async function startFlairProcess(port) {
     if (!bin) {
         throw new Error("Harper binary not found. Run 'flair init' first.");
     }
-    const dataDir = defaultDataDir();
     // Match `flair start`: accept either HDB_ADMIN_PASSWORD or FLAIR_ADMIN_PASS.
     // Without this, `flair init --admin-pass X` (which only exports HDB_*
     // to the initial Harper spawn) followed by `flair restart` would silently
@@ -7857,6 +8684,7 @@ async function startFlairProcess(port) {
     });
     proc.unref();
     await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
+    readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture across restart/upgrade
 }
 /**
  * The ONE restart mechanism for a local Flair install. Shared by `flair
@@ -7897,20 +8725,28 @@ program
     .action(async (opts) => {
     const platform = process.platform;
     const port = readPortFromConfig() ?? DEFAULT_PORT;
-    // Stop first: remove launchd service on macOS, then kill by port on all platforms
+    // Stop first: remove launchd service(s) on macOS, then kill by port on
+    // all platforms. Removes BOTH the new instance-scoped plist and a
+    // pre-flair#693 legacy plist if present — uninstall's job is to purge
+    // everything for this data dir, so it doesn't rely on resolveLaunchdLabel's
+    // "prefer new" pick alone (which would skip a stray legacy leftover).
     if (platform === "darwin") {
-        const label = "ai.tpsdev.flair";
-        const plistPath = join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
-        if (existsSync(plistPath)) {
-            try {
-                const { execSync } = await import("node:child_process");
-                execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
+        const dataDir = defaultDataDir();
+        const candidatePlists = [launchdPlistPath(launchdLabel(dataDir)), launchdPlistPath(LEGACY_LAUNCHD_LABEL)];
+        let removedAny = false;
+        for (const plistPath of candidatePlists) {
+            if (existsSync(plistPath)) {
+                try {
+                    const { execSync } = await import("node:child_process");
+                    execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
+                }
+                catch { /* best effort */ }
+                unlinkSync(plistPath);
+                removedAny = true;
             }
-            catch { /* best effort */ }
-            const { unlinkSync } = await import("node:fs");
-            unlinkSync(plistPath);
-            console.log("✅ Launchd service removed");
         }
+        if (removedAny)
+            console.log("✅ Launchd service removed");
     }
     // Kill any process still on the port (covers direct-start, no-service, or failed unload)
     try {
@@ -8774,6 +9610,43 @@ program
     else {
         console.log(`  ${render.icons.warn} No config file at ${render.wrap(render.c.dim, cfgPath)} — using defaults`);
     }
+    // 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.
+    try {
+        const harperConfigPath = join(defaultDataDir(), "harper-config.yaml");
+        if (existsSync(harperConfigPath)) {
+            const harperConfig = parseYaml(readFileSync(harperConfigPath, "utf-8")) || {};
+            const opsPortValue = harperConfig?.operationsApi?.network?.port;
+            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)")}`);
+                issues++;
+            }
+        }
+    }
+    catch { /* best-effort — don't fail doctor over a malformed harper-config.yaml */ }
+    // 3c. Ops-socket permission posture (flair#763) — report-only, never
+    // auto-fixed. Re-tightening a live socket needs a restart, so the remedy is
+    // `flair init`/restart (which re-applies the posture), not a `doctor --fix`.
+    // Only assessed when the socket exists (Harper has booted at least once).
+    try {
+        const socketPath = join(defaultDataDir(), "operations-server");
+        if (existsSync(socketPath)) {
+            const dirMode = statSync(dirname(socketPath)).mode;
+            const socketMode = statSync(socketPath).mode;
+            const groupOptIn = !!(process.env.FLAIR_SOCKET_GROUP && process.env.FLAIR_SOCKET_GROUP.trim().length > 0);
+            const verdict = classifyOpsSocketPosture(dirMode, socketMode, groupOptIn);
+            if (verdict.flagged) {
+                console.log(`  ${render.icons.error} Ops socket permissions: ${verdict.reason}`);
+                console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair init ${render.wrap(render.c.dim, "(re-applies the 0700 dir / 0600 socket posture on next start; set FLAIR_SOCKET_GROUP for deliberate multi-user access)")}`);
+                issues++;
+            }
+        }
+    }
+    catch { /* best-effort — a stat failure shouldn't fail doctor */ }
     // 4. Embeddings check — REAL semantic round-trip (only if Harper is responding).
     //
     // The dead-simple `{ q: "test" }` probe used to pass even when embeddings were
@@ -9988,21 +10861,14 @@ program
     const baseUrl = resolveBaseUrl(opts);
     const mode = render.resolveOutputMode(opts);
     try {
-        const headers = { "content-type": "application/json" };
-        const keyPath = opts.key || resolveKeyPath(agentId);
-        if (keyPath) {
-            headers["authorization"] = buildEd25519Auth(agentId, "POST", "/BootstrapMemories", keyPath);
-        }
-        const res = await fetch(`${baseUrl}/BootstrapMemories`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ agentId, maxTokens: parseInt(opts.maxTokens, 10) }),
-        });
-        if (!res.ok) {
-            const body = await res.text();
-            throw new Error(`${res.status}: ${body}`);
-        }
-        const result = (await res.json());
+        // flair#747: routed through the shared resolver — --key is an
+        // explicit tier-1 override (as before), now additionally backstopped
+        // by env admin-pass / ~/.flair/admin-pass / the Ed25519 floor if
+        // neither --key nor the agent's own resolveKeyPath(agentId) lookup
+        // finds a usable key. Previously this only ever tried Ed25519 (no
+        // admin fallback at all) and sent NO Authorization header when no key
+        // was found, relying on Harper's local passthrough.
+        const result = (await authedRequest("POST", "/BootstrapMemories", { agentId, maxTokens: parseInt(opts.maxTokens, 10) }, { baseUrl, agentId, explicitKeyPath: opts.key }));
         if (mode === "json") {
             // Agent-first: emit the full server response, augmented with the cap
             // that was requested. Includes context, sections, tokenEstimate, etc.
@@ -11874,4 +12740,6 @@ if (import.meta.main) {
     await runCli();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, 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, };
+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, 
+// launchd label (flair#693)
+LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };