@tpsdev-ai/flair 0.22.1 → 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 { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, } from "./doctor-client.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,185 +699,77 @@ 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.
+/**
+ * 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.
+ */
 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 Error(`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 Error(`HTTP 403: no credentials sent. ${hint}`);
-        }
-        throw new Error(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() — 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
+ * `allowRead()` is `allowVerified()` (resources/health.ts, resources/agent-
+ * 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.
+ */
+export async function verifyAuthedGet(baseUrl, path, keysDir) {
+    return api("GET", path, undefined, { baseUrl, keysDir });
+}
+/**
+ * flair#741 fix #3: does this ProbeResult's failure mean "the server
+ * responded but rejected the verifier's credentials" — proof of liveness,
+ * NOT a data-integrity risk — as opposed to a genuine down/unreachable/5xx
+ * failure where the instance's real state can't be determined? Pure.
+ *
+ * This is the single predicate behind three call sites in the `upgrade`
+ * command: whether the pre-upgrade credential pre-flight aborts (fix #1),
+ * and whether the post-restart / post-rollback verification failure
+ * messages claim "instance state UNKNOWN — do not assume data integrity"
+ * (they must NOT, for this case — that's the flair#741 incident itself) or
+ * explain the real, much less scary situation instead.
+ */
+export function isCredentialOnlyFailure(result) {
+    return result.healthy === true && result.authFailureKind === "credentials";
 }
 async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
     const url = `http://127.0.0.1:${httpPort}/Health`;
@@ -1663,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")
@@ -1862,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
@@ -1954,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 {
@@ -1980,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 },
@@ -2064,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 },
@@ -2281,7 +2535,12 @@ program
                         type: "stdio",
                         command: "npx",
                         args: ["-y", "@tpsdev-ai/flair-mcp"],
-                        env: mcpEnv,
+                        // flair#718 authorship-provenance: each client's wired env block
+                        // gets its OWN FLAIR_CLIENT label (never the shared mcpEnv
+                        // object directly — that would stamp the same label into every
+                        // client's config) so writes from THIS client's proxy stamp
+                        // provenance.claimed.client = "claude-code".
+                        env: { ...mcpEnv, FLAIR_CLIENT: "claude-code" },
                     };
                     try {
                         if (existsSync(claudeJsonPath)) {
@@ -2337,15 +2596,18 @@ program
                 }
                 else {
                     let result;
+                    // flair#718 authorship-provenance — see the claude-code branch's
+                    // identical comment above: FLAIR_CLIENT is per-client, so it's
+                    // added at each call site rather than baked into the shared mcpEnv.
                     switch (clientId) {
                         case "codex":
-                            result = wireCodex(mcpEnv);
+                            result = wireCodex({ ...mcpEnv, FLAIR_CLIENT: "codex" });
                             break;
                         case "gemini":
-                            result = wireGemini(mcpEnv);
+                            result = wireGemini({ ...mcpEnv, FLAIR_CLIENT: "gemini" });
                             break;
                         case "cursor":
-                            result = wireCursor(mcpEnv);
+                            result = wireCursor({ ...mcpEnv, FLAIR_CLIENT: "cursor" });
                             break;
                         default: result = { ok: false, message: `Unknown client: ${clientId}` };
                     }
@@ -2858,107 +3120,948 @@ agent
     }
     console.log(`\n✅ Agent '${id}' removed successfully`);
 });
-// ─── flair mcp ───────────────────────────────────────────────────────────────
-// Headless agent-auth to a Harper MCP `/mcp` endpoint: RFC 7523
-// client_credentials + private_key_jwt, using the agent's EXISTING Ed25519
-// identity key (no new key material, no browser, no human). The plugin side
-// (HarperFast/oauth, parent issue #159) shipped the full chain in the
-// published 2.2.0 release: assertion verification (#160/PR #165), CIMD-first
-// client resolution (#161/#167), and the client_credentials token-endpoint
-// grant + issuance rate limiting (#170/#171, closing #162/#163). `flair mcp
-// token` signs the assertion and, by default, requests a real access token
-// against the token endpoint; see src/mcp-client-assertion.ts.
-const mcp = program.command("mcp").description("MCP client-credentials agent-auth (RFC 7523 private_key_jwt)");
+/** Best-effort seed-validity check for a `.key` file: does it parse via any
+ *  of the formats loadEd25519PrivateKeyFromFile (src/mcp-client-assertion.ts
+ *  — the same loader `flair mcp token` uses) accepts? Never throws — used
+ *  only to decide "invalid" vs. "worth a registration check", not to
+ *  actually sign anything. */
+function isValidPrivateKeySeedFile(keyPath) {
+    try {
+        loadEd25519PrivateKeyFromFile(keyPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify every entry in `keysDir` for `flair keys prune`. Pure READ —
+ * never writes or moves anything; see applyKeyPrune below for the actual
+ * move. Directories (including keysDir's own `.pruned` archive, PRUNED_DIR_NAME)
+ * and files not ending in `.key` are "ignored" without any network call.
+ * `.key` files with an unparseable seed are "invalid" without a network call
+ * either — only a `.key` file that DOES parse triggers a signed
+ * `GET /Agent/:id` against `baseUrl` (checkAgentRegistered above, the exact
+ * same check doctor's registration gate uses).
+ *
+ * If that check EVER reports "unreachable" — the instance couldn't be
+ * confirmed up for that key — the WHOLE run aborts immediately
+ * (`aborted: true`, `entries: []`, short-circuiting the loop): never
+ * classify anything, prunable or not, while registration state can't be
+ * verified. A missing keysDir is treated as "nothing to classify" (fresh
+ * install), not an error — matches `flair doctor`'s own "Keys directory
+ * missing" being a separate, non-fatal finding.
+ */
+export async function classifyKeysDir(keysDir, baseUrl) {
+    if (!existsSync(keysDir))
+        return { aborted: false, entries: [] };
+    const dirents = readdirSync(keysDir, { withFileTypes: true });
+    const entries = [];
+    const candidates = [];
+    for (const d of dirents) {
+        if (d.isDirectory()) {
+            entries.push({
+                name: d.name,
+                class: "ignored",
+                reason: d.name === PRUNED_DIR_NAME ? "prune archive directory" : "directory (not a key file)",
+            });
+            continue;
+        }
+        if (!d.name.endsWith(".key")) {
+            entries.push({ name: d.name, class: "ignored", reason: "not a .key file" });
+            continue;
+        }
+        candidates.push({ name: d.name, agentId: d.name.slice(0, -".key".length) });
+    }
+    for (const c of candidates) {
+        const keyPath = join(keysDir, c.name);
+        if (!isValidPrivateKeySeedFile(keyPath)) {
+            const decision = classifyKeyFile(c.agentId, false, null, baseUrl);
+            entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
+            continue;
+        }
+        const reg = await checkAgentRegistered(baseUrl, c.agentId, keysDir);
+        if (reg.state === "unreachable") {
+            return {
+                aborted: true,
+                abortReason: `could not reach ${baseUrl} to verify agent '${c.agentId}' is registered` +
+                    `${reg.detail ? ` (${reg.detail})` : ""} — aborting; nothing was classified or moved. ` +
+                    `Pass --instance <url> to target a different instance.`,
+                entries: [],
+            };
+        }
+        const decision = classifyKeyFile(c.agentId, true, { state: reg.state, detail: reg.detail }, baseUrl);
+        entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
+    }
+    return { aborted: false, entries };
+}
+/**
+ * Move every "stale" or "invalid" entry from `keysDir` into
+ * `<keysDir>/.pruned/<dateStamp>/`, creating the archive dir as needed —
+ * MOVE, never delete, so a bad classification is always recoverable. Only
+ * ever called with entries classifyKeysDir already decided are prunable; a
+ * "keep" or "ignored" entry passed in here is simply skipped (defense in
+ * depth — a registered agent's key must never move, even if a caller bug
+ * fed it in). Collisions (same filename already archived from an earlier
+ * prune run today) get a numeric suffix (resolveCollisionSafeName) rather
+ * than silently overwriting the earlier archive.
+ */
+export function applyKeyPrune(keysDir, entries, dateStamp) {
+    const prunable = entries.filter((e) => e.class === "stale" || e.class === "invalid");
+    if (prunable.length === 0)
+        return [];
+    const destDir = join(keysDir, PRUNED_DIR_NAME, dateStamp);
+    mkdirSync(destDir, { recursive: true });
+    const existing = new Set(readdirSync(destDir));
+    const moved = [];
+    for (const e of prunable) {
+        const destName = resolveCollisionSafeName(existing, e.name);
+        existing.add(destName);
+        const from = join(keysDir, e.name);
+        const to = join(destDir, destName);
+        renameSync(from, to);
+        moved.push({ name: e.name, movedTo: to });
+    }
+    return moved;
+}
+const keys = program.command("keys").description("Manage Ed25519 key files in the key directory");
+keys
+    .command("prune")
+    .description("Move stale/unregistered/invalid keys to <keysDir>/.pruned/<date>/ — dry-run by default")
+    .option("--apply", "Actually move prunable keys (default: dry-run, prints what would move and why)")
+    .option("--keys-dir <dir>", "Directory to scan for key files (else FLAIR_KEY_DIR, ~/.flair/keys)")
+    .option("--instance <url>", "Flair instance to check registration against (else FLAIR_TARGET/FLAIR_URL/config)")
+    .option("--port <port>", "Harper HTTP port (used when --instance/FLAIR_URL/FLAIR_TARGET are not set)")
+    .action(async (opts) => {
+    const keysDir = opts.keysDir ?? process.env.FLAIR_KEY_DIR ?? defaultKeysDir();
+    const baseUrl = resolveBaseUrl({ target: opts.instance, port: opts.port });
+    const apply = !!opts.apply;
+    console.log(`\n${render.wrap(render.c.bold, "🔑 Flair Keys Prune")}${apply ? "" : render.wrap(render.c.dim, " (dry run)")}\n`);
+    console.log(`  Keys directory: ${render.wrap(render.c.dim, keysDir)}`);
+    console.log(`  Instance:       ${render.wrap(render.c.dim, baseUrl)}\n`);
+    const result = await classifyKeysDir(keysDir, baseUrl);
+    if (result.aborted) {
+        console.error(`  ${render.icons.error} ${result.abortReason}`);
+        console.log("");
+        process.exit(1);
+    }
+    const stale = result.entries.filter((e) => e.class === "stale");
+    const invalid = result.entries.filter((e) => e.class === "invalid");
+    const kept = result.entries.filter((e) => e.class === "keep");
+    const ignored = result.entries.filter((e) => e.class === "ignored");
+    const prunable = [...stale, ...invalid];
+    if (stale.length + invalid.length + kept.length === 0) {
+        console.log(`  ${render.icons.ok} No key files found in ${render.wrap(render.c.dim, keysDir)} — nothing to prune.`);
+        console.log("");
+        return;
+    }
+    for (const e of prunable) {
+        const icon = e.class === "invalid" ? render.icons.error : render.icons.warn;
+        console.log(`  ${icon} ${render.wrap(render.c.bold, e.name)} — ${e.class}: ${e.reason}`);
+    }
+    for (const e of kept) {
+        console.log(`  ${render.icons.ok} ${e.name} — registered, keeping`);
+    }
+    if (!apply) {
+        console.log("");
+        console.log(`  ${render.wrap(render.c.dim, `${prunable.length} prunable (${stale.length} stale, ${invalid.length} invalid), ${kept.length} kept, ${ignored.length} ignored`)}`);
+        if (prunable.length > 0) {
+            console.log(`  ${render.wrap(render.c.dim, "Run with --apply to move prunable keys to")} ${join(keysDir, PRUNED_DIR_NAME, pruneDateStamp())}`);
+        }
+        console.log("");
+        return;
+    }
+    const moved = applyKeyPrune(keysDir, result.entries, pruneDateStamp());
+    console.log("");
+    for (const m of moved) {
+        console.log(`  ${render.icons.ok} moved ${m.name} -> ${m.movedTo}`);
+    }
+    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
+// identity key (no new key material, no browser, no human). The plugin side
+// (HarperFast/oauth, parent issue #159) shipped the full chain in the
+// published 2.2.0 release: assertion verification (#160/PR #165), CIMD-first
+// client resolution (#161/#167), and the client_credentials token-endpoint
+// grant + issuance rate limiting (#170/#171, closing #162/#163). `flair mcp
+// token` signs the assertion and, by default, requests a real access token
+// against the token endpoint; see src/mcp-client-assertion.ts.
+const mcp = program.command("mcp").description("MCP client-credentials agent-auth (RFC 7523 private_key_jwt)");
+mcp
+    .command("token")
+    .description("Build + sign an RFC 7523 client_assertion and request an MCP client_credentials " +
+    "access token. Caches the minted token (in-process) and reuses it until " +
+    "near-expiry — use --force-refresh to mint unconditionally.")
+    .requiredOption("--agent-id <id>", "Agent id — becomes the client_id (iss/sub claims)")
+    .option("--client-id <url>", "Client ID Metadata Document URL for this agent (defaults to this instance's " +
+    "MCPClientMetadata URL, derived from FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL)")
+    .option("--token-endpoint <url>", "Token-endpoint URL — becomes the `aud` claim (defaults to this instance's " +
+    "own oauth token endpoint, same env vars)")
+    .option("--resource <url>", "RFC 8707 resource indicator for the token request (defaults to this instance's canonical /mcp URI)")
+    .option("--keys-dir <dir>", "Directory to look for <agentId>.key (else FLAIR_KEY_DIR, ~/.flair/keys, ~/.tps/secrets/flair)")
+    .option("--expires-in <seconds>", `Assertion exp - iat window, seconds (default + hard cap: ${MAX_ASSERTION_LIFETIME_SECONDS})`)
+    .option("--dry-run", "Sign the assertion and print what would be sent, but do not call the token endpoint")
+    .option("--force-refresh", "Mint a fresh token even if a cached, not-near-expiry one exists")
+    .option("--json", "Print machine-readable JSON instead of a human summary")
+    .action(async (opts) => {
+    const agentId = opts.agentId;
+    const keyPath = resolveAgentKeyPath(agentId, opts.keysDir);
+    if (!keyPath) {
+        console.error(`Error: no private key found for agent '${agentId}'. Checked --keys-dir, FLAIR_KEY_DIR, ` +
+            `~/.flair/keys, and ~/.tps/secrets/flair.`);
+        process.exit(1);
+    }
+    const clientId = opts.clientId ?? defaultMcpClientId(agentId);
+    if (!clientId) {
+        console.error("Error: --client-id is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL to derive it from " +
+            "this instance's MCPClientMetadata URL).");
+        process.exit(1);
+    }
+    const tokenEndpoint = opts.tokenEndpoint ?? defaultMcpTokenEndpoint();
+    if (!tokenEndpoint) {
+        console.error("Error: --token-endpoint is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL to derive " +
+            "this instance's own oauth token endpoint).");
+        process.exit(1);
+    }
+    const resource = opts.resource ?? defaultMcpResource();
+    const expiresIn = opts.expiresIn ? Number(opts.expiresIn) : undefined;
+    let privateKey;
+    try {
+        privateKey = loadEd25519PrivateKeyFromFile(keyPath);
+    }
+    catch (err) {
+        console.error(`Error: failed to load private key at ${keyPath}: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+    if (opts.dryRun) {
+        const { assertion, claims } = signClientAssertion({
+            clientId,
+            tokenEndpoint,
+            privateKey,
+            expiresInSeconds: expiresIn,
+        });
+        const form = buildTokenRequestForm({ clientId, assertion, resource });
+        if (opts.json) {
+            console.log(JSON.stringify({ assertion, claims, wouldSendForm: form, tokenEndpoint }, null, 2));
+            return;
+        }
+        console.log(`client_assertion (RFC 7523, EdDSA):\n\n${assertion}\n`);
+        console.log(`claims: iss=sub=${claims.iss}  aud=${claims.aud}  exp-iat=${claims.exp - claims.iat}s  jti=${claims.jti}`);
+        console.log(`\n--dry-run: NOT sent. This assertion is the client_assertion value for:\n` +
+            `  POST ${tokenEndpoint}\n  ${JSON.stringify(form, null, 2).split("\n").join("\n  ")}`);
+        return;
+    }
+    try {
+        const token = await getMcpAccessToken({
+            clientId,
+            tokenEndpoint,
+            privateKey,
+            resource,
+            expiresInSeconds: expiresIn,
+            forceRefresh: Boolean(opts.forceRefresh),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(token, null, 2));
+            return;
+        }
+        console.log(`access_token minted (${token.tokenType}, expires_in=${token.expiresIn}s):\n\n${token.accessToken}`);
+        if (token.scope)
+            console.log(`\nscope: ${token.scope}`);
+    }
+    catch (err) {
+        if (err instanceof McpTokenRequestError) {
+            console.error(`Error: token request failed (HTTP ${err.status}${err.error ? ` ${err.error}` : ""}): ${err.message}`);
+        }
+        else {
+            console.error(`Error: token request failed: ${err?.message ?? err}`);
+        }
+        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("token")
-    .description("Build + sign an RFC 7523 client_assertion and request an MCP client_credentials " +
-    "access token. Caches the minted token (in-process) and reuses it until " +
-    "near-expiry — use --force-refresh to mint unconditionally.")
-    .requiredOption("--agent-id <id>", "Agent id — becomes the client_id (iss/sub claims)")
-    .option("--client-id <url>", "Client ID Metadata Document URL for this agent (defaults to this instance's " +
-    "MCPClientMetadata URL, derived from FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL)")
-    .option("--token-endpoint <url>", "Token-endpoint URL — becomes the `aud` claim (defaults to this instance's " +
-    "own oauth token endpoint, same env vars)")
-    .option("--resource <url>", "RFC 8707 resource indicator for the token request (defaults to this instance's canonical /mcp URI)")
-    .option("--keys-dir <dir>", "Directory to look for <agentId>.key (else FLAIR_KEY_DIR, ~/.flair/keys, ~/.tps/secrets/flair)")
-    .option("--expires-in <seconds>", `Assertion exp - iat window, seconds (default + hard cap: ${MAX_ASSERTION_LIFETIME_SECONDS})`)
-    .option("--dry-run", "Sign the assertion and print what would be sent, but do not call the token endpoint")
-    .option("--force-refresh", "Mint a fresh token even if a cached, not-near-expiry one exists")
+    .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 agentId = opts.agentId;
-    const keyPath = resolveAgentKeyPath(agentId, opts.keysDir);
-    if (!keyPath) {
-        console.error(`Error: no private key found for agent '${agentId}'. Checked --keys-dir, FLAIR_KEY_DIR, ` +
-            `~/.flair/keys, and ~/.tps/secrets/flair.`);
+    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);
     }
-    const clientId = opts.clientId ?? defaultMcpClientId(agentId);
-    if (!clientId) {
-        console.error("Error: --client-id is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL to derive it from " +
-            "this instance's MCPClientMetadata URL).");
+    // 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 tokenEndpoint = opts.tokenEndpoint ?? defaultMcpTokenEndpoint();
-    if (!tokenEndpoint) {
-        console.error("Error: --token-endpoint is required (or set FLAIR_MCP_ISSUER/FLAIR_PUBLIC_URL to derive " +
-            "this instance's own oauth token endpoint).");
-        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;
     }
-    const resource = opts.resource ?? defaultMcpResource();
-    const expiresIn = opts.expiresIn ? Number(opts.expiresIn) : undefined;
-    let privateKey;
-    try {
-        privateKey = loadEd25519PrivateKeyFromFile(keyPath);
+    printEnableSteps(result);
+    if (result.refused) {
+        process.exit(1);
     }
-    catch (err) {
-        console.error(`Error: failed to load private key at ${keyPath}: ${err?.message ?? err}`);
+    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 (opts.dryRun) {
-        const { assertion, claims } = signClientAssertion({
-            clientId,
-            tokenEndpoint,
-            privateKey,
-            expiresInSeconds: expiresIn,
-        });
-        const form = buildTokenRequestForm({ clientId, assertion, resource });
-        if (opts.json) {
-            console.log(JSON.stringify({ assertion, claims, wouldSendForm: form, tokenEndpoint }, null, 2));
-            return;
-        }
-        console.log(`client_assertion (RFC 7523, EdDSA):\n\n${assertion}\n`);
-        console.log(`claims: iss=sub=${claims.iss}  aud=${claims.aud}  exp-iat=${claims.exp - claims.iat}s  jti=${claims.jti}`);
-        console.log(`\n--dry-run: NOT sent. This assertion is the client_assertion value for:\n` +
-            `  POST ${tokenEndpoint}\n  ${JSON.stringify(form, null, 2).split("\n").join("\n  ")}`);
+    if (result.dryRun) {
+        console.log(`${render.icons.info} ${render.wrap(render.c.dim, "dry-run: no remote calls were made.")}`);
         return;
     }
-    try {
-        const token = await getMcpAccessToken({
-            clientId,
-            tokenEndpoint,
-            privateKey,
-            resource,
-            expiresInSeconds: expiresIn,
-            forceRefresh: Boolean(opts.forceRefresh),
-        });
-        if (opts.json) {
-            console.log(JSON.stringify(token, null, 2));
-            return;
-        }
-        console.log(`access_token minted (${token.tokenType}, expires_in=${token.expiresIn}s):\n\n${token.accessToken}`);
-        if (token.scope)
-            console.log(`\nscope: ${token.scope}`);
+    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);
     }
-    catch (err) {
-        if (err instanceof McpTokenRequestError) {
-            console.error(`Error: token request failed (HTTP ${err.status}${err.error ? ` ${err.error}` : ""}): ${err.message}`);
-        }
-        else {
-            console.error(`Error: token request failed: ${err?.message ?? err}`);
-        }
+    // --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
@@ -5649,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 };
@@ -7017,6 +8108,66 @@ program
     // `opts` — safe to call this early.
     const { restart: shouldRestart, verify: shouldVerify, deprecatedRestartFlagUsed } = resolveUpgradeRestartVerify(opts);
     const upgradePort = resolveHttpPort({});
+    // Hoisted so the pre-flight check (below) and the post-restart/rollback
+    // verification steps (further down) all target the same URL — upgrade
+    // never restarts Flair onto a different port.
+    const baseUrl = `http://127.0.0.1:${upgradePort}`;
+    // ── Credential pre-flight (flair#741 fix #1) ────────────────────────────
+    // Post-restart verification (below) needs to authenticate against the
+    // running instance. If it can't do that RIGHT NOW, against the CURRENT,
+    // pre-upgrade instance, every upgrade on this machine is structurally
+    // doomed before a single package is touched: post-restart verify fails
+    // for the exact same credential reason, the rollback fires, and the
+    // rollback's own re-verify fails identically — producing "ROLLBACK ALSO
+    // FAILED VERIFICATION / state UNKNOWN" for an instance that was healthy
+    // the entire time. That is exactly the flair#741 incident report (a
+    // real 0.22.0→0.22.1 upgrade, healthy Flair, no ~/.flair/admin-pass, no
+    // FLAIR_ADMIN_PASS). Catch it here, before any mutation, with a message
+    // that says plainly: nothing was touched.
+    //
+    // Runs the SAME verification call (probeInstance + the agent-key-aware
+    // verifyAuthedGet, fix #2) that post-restart verification uses below —
+    // just against the pre-upgrade instance, with no expectVersion (there's
+    // no target version to compare against yet; the question here is purely
+    // "does an authenticated read work at all").
+    //
+    // Gated on --verify (shouldVerify): this check exists ONLY to keep
+    // post-restart verification honest. A user who already opted out of
+    // that verification with --no-verify has no use for a pre-flight that
+    // protects it, and blocking their upgrade on a check they didn't ask
+    // for would be a new, surprising failure mode of its own.
+    //
+    // Deliberately does NOT abort when the pre-flight instance is merely
+    // UNREACHABLE (down/timeout) rather than reachable-but-unauthenticated.
+    // `flair upgrade` may be the user's way of FIXING a down instance (bad
+    // code on disk that a newer version resolves) — today's behavior
+    // (pre-flair#741, no pre-flight at all) already lets that proceed, and
+    // a new hard block here would take away a legitimate recovery path for
+    // a failure mode this issue was never about. Only the specific
+    // "server responded, credentials didn't work" case is structurally
+    // doomed in a way a fresh install/restart can't fix on its own — so
+    // only that case aborts. (If a down instance turns out to ALSO lack
+    // credentials, that surfaces the normal way: post-restart verification
+    // fails and rolls back, same as any other post-restart failure.)
+    if (shouldVerify) {
+        const preflight = await probeInstance(baseUrl, {
+            // A short, bounded budget — this instance is presumed already
+            // running (upgrade's normal case); doctor's probePort convention
+            // (probeFlairReachable's doc comment) uses the same ~3s ballpark
+            // for "is anything there at all" checks.
+            timeoutMs: 3000,
+            pollIntervalMs: 300,
+            authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
+        });
+        if (isCredentialOnlyFailure(preflight)) {
+            console.error(`❌ pre-flight check failed: ${preflight.error}`);
+            console.error("   Nothing has been touched — no packages were installed, no restart happened.");
+            console.error("   The current instance is up and responded; the verifier just has no way to authenticate against it.");
+            console.error("   Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key — then re-run flair upgrade.");
+            console.error("   (--no-verify skips this check too, but post-restart verification would then fail the exact same way.)");
+            process.exit(1);
+        }
+    }
     // ── Pre-upgrade data snapshot (flair#637, opt-in as of the 2026-07-08 rewire) ──
     // Only an @tpsdev-ai/flair package swap touches the code that reads/
     // writes ~/.flair/data — an flair-mcp-only or openclaw-plugin-only
@@ -7170,7 +8321,7 @@ program
     }
     console.log("\nRestarting Flair...");
     const port = upgradePort;
-    const baseUrl = `http://127.0.0.1:${port}`;
+    // baseUrl was hoisted above (pre-flight, fix #1) — same URL, no redeclaration.
     try {
         await restartFlair(port);
     }
@@ -7185,13 +8336,16 @@ program
         return;
     }
     console.log("\nVerifying...");
-    // The authenticated leg dogfoods api()'s local-credential resolution
-    // (flair#640: env > agent key > ~/.flair/admin-pass file) — probeInstance
-    // itself never resolves credentials, it just calls whatever's handed to it.
+    // The authenticated leg reuses verifyAuthedGet (flair#741 fix #2): api()'s
+    // local-credential resolution (flair#640: env > agent key when an agentId
+    // is already known > ~/.flair/admin-pass file), PLUS an Ed25519 agent-key
+    // fallback when none of that resolves anything — see verifyAuthedGet's
+    // doc comment. probeInstance itself never resolves credentials, it just
+    // calls whatever's handed to it.
     const verify = await probeInstance(baseUrl, {
         expectVersion: expectedFlairVersion ?? undefined,
         timeoutMs: STARTUP_TIMEOUT_MS,
-        authedGet: (path) => api("GET", path, undefined, { baseUrl }),
+        authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
     if (verdict.kind === "ok") {
@@ -7199,6 +8353,17 @@ program
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
+    if (isCredentialOnlyFailure(verify)) {
+        // flair#741 fix #3: a responding server that rejects the verifier's
+        // credentials proves the instance is UP — it is not evidence the
+        // upgrade itself broke anything. Say so explicitly instead of leaving
+        // the reader to infer it from the raw error text. Rollback still
+        // proceeds below (a credential check that worked pre-upgrade — see
+        // the pre-flight above — and stopped working mid-run is an edge case
+        // ambiguous enough that "prefer the known-good version" is still the
+        // safer default), but the reason for it is now honest.
+        console.error("   The instance is up and responded — the verifier could not authenticate. This is not a sign the upgrade broke anything.");
+    }
     if (verdict.kind === "cannot-rollback") {
         console.error("   Cannot roll back automatically: the previously-installed @tpsdev-ai/flair version is unknown.");
         console.error("   Check the instance now: flair doctor");
@@ -7224,7 +8389,7 @@ program
     const rollbackVerify = await probeInstance(baseUrl, {
         expectVersion: verdict.toVersion,
         timeoutMs: STARTUP_TIMEOUT_MS,
-        authedGet: (path) => api("GET", path, undefined, { baseUrl }),
+        authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
     });
     const rollbackVerdict = decideAfterRollbackVerify(rollbackVerify);
     if (rollbackVerdict.kind === "rolled-back") {
@@ -7233,7 +8398,22 @@ program
         process.exit(1);
     }
     console.error(`❌❌ ROLLBACK ALSO FAILED VERIFICATION: ${rollbackVerdict.reason}`);
-    console.error("   Instance state is UNKNOWN — do not assume data integrity.");
+    // flair#741 fix #3: this is the exact incident report — a 403 from a
+    // responding, healthy server (credentials-only failure) was printed as
+    // "state UNKNOWN — do not assume data integrity" for BOTH the upgrade
+    // verify AND the rollback re-verify, because the same missing-auth-
+    // material condition rejects both. Reserve the UNKNOWN/do-not-assume
+    // text for failures where the instance's real state genuinely can't be
+    // determined (connection refused, timeout, 5xx) — a credential-only
+    // failure here means the rollback likely landed fine and the checker
+    // simply can't prove it.
+    if (isCredentialOnlyFailure(rollbackVerify)) {
+        console.error("   The instance is up and responding — the verifier could not authenticate (credentials, not the rollback, are the problem).");
+        console.error("   Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key, then check: flair doctor");
+    }
+    else {
+        console.error("   Instance state is UNKNOWN — do not assume data integrity.");
+    }
     // This double-failure isn't auto-recoverable yet (flair#637) — but if a
     // pre-upgrade snapshot landed, point at the CONCRETE path instead of
     // just the issue number, so recovery doesn't start with a GitHub search.
@@ -7256,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");
@@ -7313,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;
             }
@@ -7340,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,
@@ -7349,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
@@ -7365,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 {
@@ -7387,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");
@@ -7401,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" });
                 }
@@ -7439,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) {
@@ -7466,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
@@ -7493,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
@@ -7533,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 {
@@ -8191,6 +9391,7 @@ program
     let issues = 0;
     let fixed = 0; // issues that --fix successfully resolved during this run (flair#721)
     let harperResponding = false;
+    let keyAgentIds = []; // populated by step 2 (Keys directory) below; feeds the flair#722 per-agent iteration
     console.log(`\n${render.wrap(render.c.bold, "🩺 Flair Doctor")}\n`);
     // 0. Version check (flair#587) — offline-tolerant + cached, independent
     // of Harper being up. A gap of ≥2 minor versions (or any major) is
@@ -8386,6 +9587,7 @@ program
     if (existsSync(keysDir)) {
         const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
         if (keyFiles.length > 0) {
+            keyAgentIds = keyFiles.map((f) => f.replace(/\.key$/, ""));
             console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(keyFiles.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
         }
         else {
@@ -8408,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
@@ -8537,7 +9776,7 @@ program
                                 console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent id known — pass --agent <id>`);
                             }
                             else {
-                                const wireEnv = { FLAIR_AGENT_ID: fixAgentId, FLAIR_URL: block.flairUrl || baseUrl };
+                                const wireEnv = { FLAIR_AGENT_ID: fixAgentId, FLAIR_URL: resolveWireFlairUrl(block.flairUrl, baseUrl) };
                                 const wireResult = client.id === "claude-code" ? wireClaudeCode(wireEnv) :
                                     client.id === "codex" ? wireCodex(wireEnv) :
                                         client.id === "gemini" ? wireGemini(wireEnv) :
@@ -8637,6 +9876,54 @@ program
             }
         }
     }
+    // 7a. Resolve which agent identities the two verified-read sections below
+    // (Fleet presence, Migrations) iterate (flair#722). Previously both
+    // sections required --agent explicitly; doctor already enumerates every
+    // key in ~/.flair/keys (step 2 above), so by default it now runs the
+    // signed read AS EACH of those agents instead of hiding behind a flag —
+    // a real dogfood run found the #720 halted-migration warning visible via
+    // `flair status --agent local` but invisible in the default `doctor` run
+    // the same user ran minutes later. --agent <id> narrows this to exactly
+    // that one identity (planAgentIterations — same pre-#722 semantics: a
+    // single signed identity, just no longer widened to "every key").
+    //
+    // The registration gate (checkAgentRegistered — same signed GET
+    // /Agent/:id used by the Client integration section above) is resolved
+    // ONCE here per agent and shared by both sections, so a bad/unregistered
+    // key doesn't cost two network round-trips, and its "found" count isn't
+    // double-counted by each section re-discovering the same finding
+    // (flair#721 found/fixed/remaining summary — these are found-only, no
+    // --fix action exists for a bad local key). A gate failure for one agent
+    // never aborts the others — that's the failure isolation flair#722 asks
+    // for; describeAgentGateFinding (src/doctor-client.ts) is pure decision
+    // logic so it's unit-tested without a real Harper.
+    const verifiedReadAgentIds = harperResponding
+        ? planAgentIterations(keyAgentIds, opts.agent || process.env.FLAIR_AGENT_ID)
+        : [];
+    const agentGates = [];
+    for (const id of verifiedReadAgentIds) {
+        const reg = await checkAgentRegistered(baseUrl, id, defaultKeysDir());
+        agentGates.push({ id, state: reg.state, detail: reg.detail });
+        const finding = describeAgentGateFinding(id, reg.state, reg.detail);
+        if (finding?.isIssue)
+            issues++;
+    }
+    // Shared renderer for one agent's registration-gate outcome — prints the
+    // "Agent: <id>" subsection header, and if the gate isn't clean, the
+    // finding (never re-counted here; already counted once above) and
+    // returns false so the caller skips its own verified fetch for this
+    // agent and moves on to the next (failure isolation).
+    function renderAgentGateHeader(gate) {
+        console.log(`    ${render.wrap(render.c.dim, `Agent: ${gate.id}`)}`);
+        const finding = describeAgentGateFinding(gate.id, gate.state, gate.detail);
+        if (!finding)
+            return true;
+        const icon = finding.icon === "error" ? render.icons.error : render.icons.warn;
+        console.log(`      ${icon} ${finding.message}`);
+        if (finding.fixHint)
+            console.log(`         ${render.wrap(render.c.dim, "Fix:")} ${finding.fixHint}`);
+        return false;
+    }
     // 8. Fleet presence (flair#639) — known instances via /Presence heartbeats.
     //
     // "Instance" here means each AGENT's heartbeat row — Presence is keyed by
@@ -8657,69 +9944,82 @@ program
     // `doctor` unless those agents also heartbeat straight to the hub. Not
     // fixed here — flair#639's fix list is version-stamping + a doctor
     // listing, not widening federation sync scope.
-    if (harperResponding) {
-        console.log(`\n  ${render.wrap(render.c.bold, "Fleet presence")}`);
+    //
+    // flair#722: iterated per agent (agentGates above) instead of a single
+    // --agent-gated read. flairVersion/harperVersion are gated to verified
+    // readers on the server (resources/Presence.ts, same boundary as
+    // currentTask), so each agent subsection signs its own GET — a working
+    // key reveals versions for that subsection; roster IDENTITY is public
+    // either way. Zero local keys (and no --agent) falls back to exactly the
+    // pre-#722 single unauthenticated read (hidden versions, "Pass --agent"
+    // hint) — there's no agent to sign as, but remote agents may still have
+    // heartbeated onto this instance and identities are worth showing.
+    async function fetchAndRenderFleetPresence(headers, canSign, indent) {
         try {
-            // flairVersion/harperVersion are gated to verified readers on the
-            // server (resources/Presence.ts, same boundary as currentTask) — sign
-            // the GET when we have an agent + key so the fields aren't silently
-            // nulled out from under us.
-            const fleetAgentId = opts.agent || process.env.FLAIR_AGENT_ID;
-            const fleetKeyPath = fleetAgentId ? join(defaultKeysDir(), `${fleetAgentId}.key`) : undefined;
-            const canSign = !!(fleetAgentId && fleetKeyPath && existsSync(fleetKeyPath));
-            const headers = canSign
-                ? { Authorization: buildEd25519Auth(fleetAgentId, "GET", "/Presence", fleetKeyPath) }
-                : {};
             const presRes = await fetch(`${baseUrl}/Presence`, { headers, signal: AbortSignal.timeout(5000) });
             if (!presRes.ok) {
-                console.log(`  ${render.icons.warn} Could not fetch presence roster (HTTP ${presRes.status})`);
+                console.log(`${indent}${render.icons.warn} Could not fetch presence roster (HTTP ${presRes.status})`);
+                return;
             }
-            else {
-                const roster = (await presRes.json());
-                if (!Array.isArray(roster) || roster.length === 0) {
-                    console.log(`  ${render.icons.info} No known instances yet — no /Presence heartbeats recorded on this instance`);
-                }
-                else {
-                    const rows = sortOldestVersionFirst(markStale(roster));
-                    for (const row of rows) {
-                        const lastSeen = typeof row.lastHeartbeatAt === "number"
-                            ? render.relativeTime(new Date(row.lastHeartbeatAt).toISOString())
-                            : "—";
-                        const versionLabel = !canSign
-                            ? render.wrap(render.c.dim, "hidden")
-                            : row.flairVersion
-                                ? `v${row.flairVersion}`
-                                : render.wrap(render.c.dim, "no version reported");
-                        const staleNote = row.stale && row.newestVersion
-                            ? " " + render.wrap(render.c.yellow, `(stale — fleet newest is v${row.newestVersion})`)
-                            : "";
-                        const icon = row.stale ? render.icons.warn : render.icons.ok;
-                        const statusSuffix = row.presenceStatus ? ` (${row.presenceStatus})` : "";
-                        // Natural-presence: same staleness principle as the version
-                        // column — a live activity is shown as current, a decayed one as
-                        // "last-known". `activityFresh === false` (server verdict) plus a
-                        // known lastActivity → "(was: X)"; a fresh, non-idle activity →
-                        // "(X)". Skip entirely when there's nothing informative to say
-                        // (no signal, or idle) so the line stays quiet for the common case.
-                        const lastActivity = row.lastActivity ?? row.activity;
-                        const activityNote = row.activityFresh === false
-                            ? (lastActivity && lastActivity !== "idle"
-                                ? " " + render.wrap(render.c.dim, `(was: ${lastActivity})`)
-                                : "")
-                            : (row.activity && row.activity !== "idle"
-                                ? " " + render.wrap(render.c.dim, `(${row.activity})`)
-                                : "");
-                        console.log(`  ${icon} ${row.id} — ${versionLabel} — last seen ${lastSeen}${statusSuffix}${activityNote}${staleNote}`);
-                    }
-                    if (!canSign) {
-                        console.log(`     ${render.wrap(render.c.dim, "Pass --agent <id> (with a matching key in ~/.flair/keys) to reveal versions — flairVersion/harperVersion require a verified signature, same as currentTask.")}`);
-                    }
-                    console.log(`     ${render.wrap(render.c.dim, "Staleness above is fleet-relative (newest version seen among these instances) — comparing against the latest PUBLISHED flair is the version check at the top of this report, not this section.")}`);
-                }
+            const roster = (await presRes.json());
+            if (!Array.isArray(roster) || roster.length === 0) {
+                console.log(`${indent}${render.icons.info} No known instances yet — no /Presence heartbeats recorded on this instance`);
+                return;
             }
+            const rows = sortOldestVersionFirst(markStale(roster));
+            for (const row of rows) {
+                const lastSeen = typeof row.lastHeartbeatAt === "number"
+                    ? render.relativeTime(new Date(row.lastHeartbeatAt).toISOString())
+                    : "—";
+                const versionLabel = !canSign
+                    ? render.wrap(render.c.dim, "hidden")
+                    : row.flairVersion
+                        ? `v${row.flairVersion}`
+                        : render.wrap(render.c.dim, "no version reported");
+                const staleNote = row.stale && row.newestVersion
+                    ? " " + render.wrap(render.c.yellow, `(stale — fleet newest is v${row.newestVersion})`)
+                    : "";
+                const icon = row.stale ? render.icons.warn : render.icons.ok;
+                const statusSuffix = row.presenceStatus ? ` (${row.presenceStatus})` : "";
+                // Natural-presence: same staleness principle as the version
+                // column — a live activity is shown as current, a decayed one as
+                // "last-known". `activityFresh === false` (server verdict) plus a
+                // known lastActivity → "(was: X)"; a fresh, non-idle activity →
+                // "(X)". Skip entirely when there's nothing informative to say
+                // (no signal, or idle) so the line stays quiet for the common case.
+                const lastActivity = row.lastActivity ?? row.activity;
+                const activityNote = row.activityFresh === false
+                    ? (lastActivity && lastActivity !== "idle"
+                        ? " " + render.wrap(render.c.dim, `(was: ${lastActivity})`)
+                        : "")
+                    : (row.activity && row.activity !== "idle"
+                        ? " " + render.wrap(render.c.dim, `(${row.activity})`)
+                        : "");
+                console.log(`${indent}${icon} ${row.id} — ${versionLabel} — last seen ${lastSeen}${statusSuffix}${activityNote}${staleNote}`);
+            }
+            if (!canSign) {
+                console.log(`${indent}   ${render.wrap(render.c.dim, "Pass --agent <id> (with a matching key in ~/.flair/keys) to reveal versions — flairVersion/harperVersion require a verified signature, same as currentTask.")}`);
+            }
+            console.log(`${indent}   ${render.wrap(render.c.dim, "Staleness above is fleet-relative (newest version seen among these instances) — comparing against the latest PUBLISHED flair is the version check at the top of this report, not this section.")}`);
         }
         catch (err) {
-            console.log(`  ${render.icons.warn} Fleet presence check failed: ${err?.message ?? err}`);
+            console.log(`${indent}${render.icons.warn} Fleet presence check failed: ${err?.message ?? err}`);
+        }
+    }
+    if (harperResponding) {
+        console.log(`\n  ${render.wrap(render.c.bold, "Fleet presence")}`);
+        if (agentGates.length === 0) {
+            await fetchAndRenderFleetPresence({}, false, "  ");
+        }
+        else {
+            for (const gate of agentGates) {
+                const registered = renderAgentGateHeader(gate);
+                if (!registered)
+                    continue;
+                const keyPath = resolveKeyPath(gate.id) ?? join(defaultKeysDir(), `${gate.id}.key`);
+                const headers = { Authorization: buildEd25519Auth(gate.id, "GET", "/Presence", keyPath) };
+                await fetchAndRenderFleetPresence(headers, true, "      ");
+            }
         }
     }
     // 9. Migration state (flair#695) — pending/in-progress/blocked + last
@@ -8729,52 +10029,70 @@ program
     // 1a above (a halted migration retries automatically on the next boot —
     // there's no separate "run the migration now" fix; the fix for
     // "blocked" is whatever the halt reason names, e.g. freeing disk).
-    if (harperResponding) {
-        console.log(`\n  ${render.wrap(render.c.bold, "Migrations")}`);
+    //
+    // flair#722: iterated per agent (agentGates above), same as Fleet
+    // presence — each subsection's finding is found-only (no per-agent
+    // --fix here beyond the existing restart-on-halt story). Gate FINDINGS
+    // are rendered in full under Fleet presence only (the first
+    // verified-read section); re-printing the identical per-agent finding
+    // here doubled the noise on real multi-key machines (a 27-key dogfood
+    // box printed 15 not-registered findings twice each), so this section
+    // iterates only the gate-passed agents and rolls the rest into one
+    // aggregate skip line. The issue COUNT is unaffected either way — gate
+    // findings are counted exactly once, at gate-resolution time (step 7a).
+    async function fetchAndRenderMigrations(headers, indent) {
         try {
-            const migAgentId = opts.agent || process.env.FLAIR_AGENT_ID;
-            const migKeyPath = migAgentId ? join(defaultKeysDir(), `${migAgentId}.key`) : undefined;
-            const migCanSign = !!(migAgentId && migKeyPath && existsSync(migKeyPath));
-            if (!migCanSign) {
-                console.log(`  ${render.icons.info} Pass --agent <id> (with a matching key in ~/.flair/keys) to see migration state — requires a verified read, same as Fleet presence above.`);
+            const migRes = await fetch(`${baseUrl}/HealthDetail`, { headers, signal: AbortSignal.timeout(5000) });
+            if (!migRes.ok) {
+                console.log(`${indent}${render.icons.warn} Could not fetch migration state (HTTP ${migRes.status})`);
+                return;
             }
-            else {
-                const migHeaders = { Authorization: buildEd25519Auth(migAgentId, "GET", "/HealthDetail", migKeyPath) };
-                const migRes = await fetch(`${baseUrl}/HealthDetail`, { headers: migHeaders, signal: AbortSignal.timeout(5000) });
-                if (!migRes.ok) {
-                    console.log(`  ${render.icons.warn} Could not fetch migration state (HTTP ${migRes.status})`);
+            const detail = (await migRes.json());
+            const migBlock = detail?.migrations;
+            if (!migBlock || !Array.isArray(migBlock.migrations) || migBlock.migrations.length === 0) {
+                console.log(`${indent}${render.icons.info} No migrations registered on this instance`);
+                return;
+            }
+            if (migBlock.cyclePhase === "pre-hash") {
+                console.log(`${indent}${render.icons.info} Pre-flight integrity check in progress — migrations deferred until it completes`);
+            }
+            for (const m of migBlock.migrations) {
+                if (m.state === "completed") {
+                    console.log(`${indent}${render.icons.ok} ${m.id}: completed`);
+                }
+                else if (m.state === "halted" || m.state === "failed") {
+                    console.log(`${indent}${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
+                    issues++;
+                }
+                else if (m.state === "running") {
+                    console.log(`${indent}${render.icons.info} ${m.id}: in progress (${m.rowsDone} done, ${m.rowsRemaining} remaining)`);
                 }
                 else {
-                    const detail = (await migRes.json());
-                    const migBlock = detail?.migrations;
-                    if (!migBlock || !Array.isArray(migBlock.migrations) || migBlock.migrations.length === 0) {
-                        console.log(`  ${render.icons.info} No migrations registered on this instance`);
-                    }
-                    else {
-                        if (migBlock.cyclePhase === "pre-hash") {
-                            console.log(`  ${render.icons.info} Pre-flight integrity check in progress — migrations deferred until it completes`);
-                        }
-                        for (const m of migBlock.migrations) {
-                            if (m.state === "completed") {
-                                console.log(`  ${render.icons.ok} ${m.id}: completed`);
-                            }
-                            else if (m.state === "halted" || m.state === "failed") {
-                                console.log(`  ${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
-                                issues++;
-                            }
-                            else if (m.state === "running") {
-                                console.log(`  ${render.icons.info} ${m.id}: in progress (${m.rowsDone} done, ${m.rowsRemaining} remaining)`);
-                            }
-                            else {
-                                console.log(`  ${render.icons.info} ${m.id}: ${m.state}`);
-                            }
-                        }
-                    }
+                    console.log(`${indent}${render.icons.info} ${m.id}: ${m.state}`);
                 }
             }
         }
         catch (err) {
-            console.log(`  ${render.icons.warn} Migration state check failed: ${err?.message ?? err}`);
+            console.log(`${indent}${render.icons.warn} Migration state check failed: ${err?.message ?? err}`);
+        }
+    }
+    if (harperResponding) {
+        console.log(`\n  ${render.wrap(render.c.bold, "Migrations")}`);
+        if (agentGates.length === 0) {
+            console.log(`  ${render.icons.info} Pass --agent <id> (with a matching key in ~/.flair/keys) to see migration state — requires a verified read, same as Fleet presence above.`);
+        }
+        else {
+            const passedGates = agentGates.filter((g) => describeAgentGateFinding(g.id, g.state, g.detail) === null);
+            for (const gate of passedGates) {
+                renderAgentGateHeader(gate);
+                const keyPath = resolveKeyPath(gate.id) ?? join(defaultKeysDir(), `${gate.id}.key`);
+                const headers = { Authorization: buildEd25519Auth(gate.id, "GET", "/HealthDetail", keyPath) };
+                await fetchAndRenderMigrations(headers, "      ");
+            }
+            const skipped = agentGates.length - passedGates.length;
+            if (skipped > 0) {
+                console.log(`  ${render.icons.info} ${skipped} agent(s) skipped — registration-gate findings reported under Fleet presence above`);
+            }
         }
     }
     // Summary — see summarizeDoctorRun above (flair#721): distinguishes
@@ -9543,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.
@@ -11429,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, };