@tpsdev-ai/flair 0.48.0 → 0.50.0

package/dist/cli.js

@@ -20,14 +20,14 @@ import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache }
 import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
-import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, wireAntigravity, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
+import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, wireAntigravity, wirePi, piFlairSpec, PI_FLAIR_PACKAGE, PI_FLAIR_DEFAULT_URL, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
 import { flairCliVersion, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning, FLAIR_MCP_PACKAGE } from "./lib/mcp-spec.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, effectiveFlairUrl, checkClaudeMdBootstrap, detectWiredFlairMcp, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, checkContinuityCaptureHooks, fixContinuityCaptureHooks, } from "./doctor-client.js";
+import { readClientMcpBlock, effectiveFlairUrl, checkPiFlairWiring, checkClaudeMdBootstrap, detectWiredFlairMcp, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, checkContinuityCaptureHooks, fixContinuityCaptureHooks, } from "./doctor-client.js";
 import { checkGlobalBinOnPath, cliBootPathWarning, resolveNpmGlobalPrefix, } from "./install/global-bin-path.js";
-import { installHook, uninstallHook, hookStatus, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
-import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
+import { installHook, uninstallHook, hookStatus, hookStatusIdentityLines, HOOK_STATUS_UNPARSED, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, hookSettingsPath, hookInstallHint, harnessSupportsContinuity, resolveHookAgentId, } from "./hook-install.js";
+import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, DEFAULT_ADMIN_USER, resolveAdminUser, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
 import { entityFormatHint, parseEntitiesCsv } from "./lib/entity-vocab-cli.js";
@@ -141,7 +141,8 @@ function shouldShowInlineSecretWarning(optValue, fromEnv, secretFlagNames, flagN
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
 const FABRIC_OPS_PORT = 9925;
-const DEFAULT_ADMIN_USER = "admin";
+// DEFAULT_ADMIN_USER + resolveAdminUser (flag > FLAIR_ADMIN_USER env > "admin")
+// live in src/lib/auth-resolve.ts — imported above (flair#1345).
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
 // flair#670 — single-host default for the Harper ops API bind address.
@@ -684,6 +685,48 @@ function resolveSigningIdentityFor(opts, command) {
 function resolveSigningAgentId(opts, command) {
     return resolveSigningIdentityFor(opts, command).agentId;
 }
+// ── Shared credential/identity flag surface (flair#1106) ─────────────────────
+// Sibling commands (memory add, backup, federation sync) used to drift on
+// the same concepts: `--admin-pass-file` existed on backup/sync but was an
+// unknown option on `memory add`, and `memory add --agent` was a commander
+// requiredOption so FLAIR_AGENT_ID could never satisfy it. One helper owns
+// the credential flag names/shapes; identity (`--agent`) stays optional so
+// the env fallback can actually apply. This does not invent a new auth
+// model — it only declares the flags authedRequest already resolves.
+/** Flag strings the sibling commands must share (name + argument shape). */
+export const SHARED_CREDENTIAL_FLAGS = {
+    adminPass: "--admin-pass <pass>",
+    adminPassFile: "--admin-pass-file <path>",
+    adminUser: "--admin-user <name>",
+};
+export const SHARED_IDENTITY_FLAGS = {
+    agent: "--agent <id>",
+};
+function addSharedCredentialOptions(cmd) {
+    return cmd
+        .option(SHARED_CREDENTIAL_FLAGS.adminPass, "Admin password (or set FLAIR_ADMIN_PASS env, or use --admin-pass-file)")
+        .option(SHARED_CREDENTIAL_FLAGS.adminPassFile, "Read admin password from a file (e.g., ~/.flair/admin-pass). Preferred over --admin-pass for launchd/cron — keeps the secret out of ps and shell history.")
+        .option(SHARED_CREDENTIAL_FLAGS.adminUser, "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)");
+}
+function addSharedIdentityOption(cmd) {
+    return cmd.option(SHARED_IDENTITY_FLAGS.agent, "Agent ID (or set FLAIR_AGENT_ID env)");
+}
+/**
+ * Resolve `--admin-pass-file` into the same `adminPass` slot the inline flag
+ * uses. Shared so sibling commands cannot drift on how the file is read
+ * (mode 0600 via readAdminPassFileSecure).
+ */
+function applyAdminPassFile(opts) {
+    if (!opts.adminPass && opts.adminPassFile) {
+        try {
+            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
+        }
+        catch (err) {
+            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
+            process.exit(1);
+        }
+    }
+}
 // Ops port resolution: --ops-port flag > FLAIR_OPS_PORT env > config opsPort > httpPort - 1
 //
 // Deliberately NOT routed through Harper's per-instance config the way
@@ -1428,7 +1471,13 @@ async function api(method, path, body, options) {
                 agentId = decodeURIComponent(match[1]);
         }
     }
-    return authedRequest(method, path, body, { baseUrl: base, agentId, keysDir: options?.keysDir });
+    return authedRequest(method, path, body, {
+        baseUrl: base,
+        agentId,
+        keysDir: options?.keysDir,
+        explicitAdminPass: options?.explicitAdminPass,
+        adminUser: options?.adminUser,
+    });
 }
 /**
  * The authedGet `flair upgrade` verification (flair#635/#741) hands to
@@ -1905,6 +1954,27 @@ function readHarperPid(dataDir) {
         return null;
     }
 }
+/**
+ * flair#1345 — Harper returns the SAME 401 `{"error":"Login failed"}` for a
+ * wrong password and for a nonexistent username, and the CLI's errors used
+ * to hint only at the password. On an instance whose superuser is not named
+ * `admin` (now reachable in practice: the #604/#610 `authorizeLocal: false`
+ * hardening removed the credential-less loopback path, so these calls MUST
+ * send real Basic auth) that sent operators down the wrong trail entirely.
+ * Name both causes, each with the knob that fixes it.
+ */
+function opsAuth401Hint(adminUser) {
+    if (adminUser === undefined) {
+        // No credentials were sent at all (local caller riding authorizeLocal) —
+        // "wrong password or username" would be asserting a cause that isn't
+        // established. The remedy is to send credentials.
+        return ("\n  No admin credentials were sent and the instance rejected the request." +
+            "\n  Pass --admin-pass <pass> or --admin-pass-file <path> (and --admin-user <name> if the superuser is not 'admin').");
+    }
+    return (`\n  The operations API rejected the admin credentials (tried username '${adminUser}'). Two possible causes:` +
+        "\n  - wrong password — check --admin-pass / --admin-pass-file / FLAIR_ADMIN_PASS" +
+        `\n  - wrong username — this instance's superuser may not be '${adminUser}'; pass --admin-user <name> or set FLAIR_ADMIN_USER`);
+}
 /**
  * Seed an agent record via the Harper operations API.
  * Accepts either a port number (localhost) or a full URL string (--target).
@@ -1958,6 +2028,9 @@ export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, ad
         const text = await res.text().catch(() => "");
         if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
             return;
+        if (res.status === 401) {
+            throw new Error(`Operations API insert failed (401): ${text}${opsAuth401Hint(auth === undefined ? undefined : adminUser)}`);
+        }
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
@@ -2009,6 +2082,9 @@ export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId,
         const text = await res.text().catch(() => "");
         if (res.status === 409 || text.includes("duplicate") || text.includes("already exists"))
             return;
+        if (res.status === 401) {
+            throw new Error(`Federation Instance insert via ops API failed (401): ${text}${opsAuth401Hint(auth === undefined ? undefined : adminUser)}`);
+        }
         throw new Error(`Federation Instance insert via ops API failed (${res.status}): ${text}`);
     }
 }
@@ -2586,9 +2662,9 @@ export function upgradeStatusSuffix(name, status) {
  *      is `flair doctor --fix`, never `npm install -g`.
  *   3. Wired with a concrete pin — that pin IS the installed version
  *      (current when it equals latest, else outdated → re-pin via doctor).
- *   4. Wired but unpinned (a bare npx spec / the SessionStart hook) — `npx -y`
- *      re-resolves latest every session, so the effective version IS latest →
- *      current.
+ *   4. Wired but unpinned (a bare npx spec / a pre-#1143 SessionStart hook) —
+ *      `npx -y` re-resolves latest every session, so the effective version IS
+ *      latest → current.
  */
 export function resolveFlairMcpFinding(globalProbe, latest, wiring) {
     // 1. Legacy global install.
@@ -2917,11 +2993,12 @@ program
     .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("--admin-user <name>", "Admin username when authenticating to an already-running instance via --target/--ops-target (env: FLAIR_ADMIN_USER; default: admin — local bootstrap and Fabric provisioning always create 'admin')")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--data-dir <dir>", "Harper data directory")
     .option("--skip-start", "Skip Harper startup (assume already running)")
     .option("--skip-soul", "Skip interactive personality setup")
-    .option("--client <client>", "MCP client(s) to wire: claude-code, codex, gemini, cursor, antigravity, all, or none")
+    .option("--client <client>", "Client(s) to wire: claude-code, codex, gemini, cursor, antigravity, pi (native extension), all, or none")
     .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
     .option("--skip-smoke", "Skip the MCP smoke test")
     .option("--skip-claude-md", "Skip appending the Flair bootstrap line to CLAUDE.md (claude-code only)")
@@ -3005,7 +3082,10 @@ program
             }
             flairAdminPass = opts.adminPass;
         }
-        const adminUser = DEFAULT_ADMIN_USER;
+        // flair#1345: only the already-running-instance leg honors --admin-user /
+        // FLAIR_ADMIN_USER — the provisioning leg just CREATED the superuser as
+        // DEFAULT_ADMIN_USER via provisionFabric, so that name is ground truth.
+        const adminUser = didProvision ? DEFAULT_ADMIN_USER : resolveAdminUser(opts.adminUser);
         const auth = `Basic ${Buffer.from(`${adminUser}:${flairAdminPass}`).toString("base64")}`;
         const role = opts.remote ? "hub" : undefined;
         // Generate or reuse keypair (only if --agent-id provided, or --remote needs
@@ -3140,9 +3220,9 @@ program
     const noMcp = opts.mcp === false;
     const selectedClients = [];
     if (clientOpt && clientOpt !== "all" && clientOpt !== "none" && !noMcp) {
-        const valid = ["claude-code", "codex", "gemini", "cursor", "antigravity"];
+        const valid = ["claude-code", "codex", "gemini", "cursor", "antigravity", "pi"];
         if (!valid.includes(clientOpt)) {
-            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, antigravity, all, none`);
+            console.error(`Unknown client: ${clientOpt}. Valid: claude-code, codex, gemini, cursor, antigravity, pi, all, none`);
             process.exit(1);
         }
         selectedClients.push(clientOpt);
@@ -3773,6 +3853,13 @@ program
                         case "antigravity":
                             result = wireAntigravity({ ...mcpEnv, FLAIR_CLIENT: "antigravity" });
                             break;
+                        // pi is a NATIVE EXTENSION, not an MCP client (flair#1342):
+                        // wirePi edits ~/.pi/agent/settings.json `packages`, and pi
+                        // settings carry no env block — no FLAIR_CLIENT to stamp; the
+                        // wire message tells the user what to export at pi launch.
+                        case "pi":
+                            result = wirePi(mcpEnv);
+                            break;
                         default: result = { ok: false, message: `Unknown client: ${clientId}` };
                     }
                     wiringResults.push({ client: clientId, message: result.message, wired: result.ok });
@@ -3784,7 +3871,12 @@ program
         // Launch flair-mcp and confirm it answers a JSON-RPC initialize over
         // stdio. Best-effort: failures warn but never fail the command. Skipped
         // with --skip-smoke, --no-mcp, --client none, or when nothing was wired.
-        if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
+        // pi doesn't run flair-mcp (native extension, flair#1342), so a pi-only
+        // wiring has nothing this smoke test exercises — spawning it anyway
+        // would render a green "MCP server responded" for a setup that never
+        // starts an MCP server.
+        const wiredAnyMcpClient = wiringResults.some((r) => r.client !== "pi");
+        if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0 && wiredAnyMcpClient) {
             console.log("\n   Smoke-testing MCP server...");
             try {
                 // Same spec that gets WIRED above — the smoke test must exercise the
@@ -3934,6 +4026,7 @@ agent
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password for registration")
     .option("--admin-pass-file <path>", "Read the admin password from a file (chmod 600 enforced). Preferred over inline --admin-pass — keeps the secret out of ps and shell history; works for remote targets too (an explicit flag is operator intent).")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair REST URL; derives the ops API URL (port-1) to seed the Agent there (env: FLAIR_TARGET)")
@@ -3942,7 +4035,7 @@ agent
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     const name = opts.name ?? id;
     // Where to seed the Agent record. Default is localhost (opsPort). When
     // --ops-target or --target is given, seed on the remote instead of localhost
@@ -4026,6 +4119,7 @@ agent
     .command("list")
     .description("List all agents")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--agent <id>", "Agent ID to authenticate as via Ed25519 (or FLAIR_AGENT_ID env) when no admin pass")
     .option("--keys-dir <dir>", "Directory holding the agent's Ed25519 key")
     .option("--port <port>", "Harper HTTP port")
@@ -4043,7 +4137,7 @@ agent
     let agents;
     if (adminPass) {
         const opsPort = resolveOpsPort(opts);
-        const auth = Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64");
+        const auth = Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64");
         // List every Agent without null-scanning the primary key. A
         // `starts_with ""` on `id` makes Harper search the index for nulls, which
         // the bundled Harper (5.0.21) rejects with "id is not indexed for nulls".
@@ -4163,6 +4257,7 @@ agent
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .action(async (id, opts) => {
     const httpPort = resolveHttpPort(opts);
@@ -4174,7 +4269,7 @@ agent
             "to keep secrets out of shell history.");
     }
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     if (!adminPass) {
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for key rotation");
@@ -4247,12 +4342,13 @@ agent
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--force", "Skip interactive confirmation (required when stdin is not a TTY)")
     .action(async (id, opts) => {
     const opsPort = resolveOpsPort(opts);
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     if (!adminPass) {
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for agent remove");
@@ -4525,18 +4621,12 @@ keys
 // 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) {
+function resolveHookFlairUrl(opts, homeDir, harness) {
     return (opts.url ||
         process.env.FLAIR_TARGET ||
         process.env.FLAIR_URL ||
-        readClientMcpBlock("claude-code", homeDir).flairUrl ||
+        readClientMcpBlock(harness, homeDir).flairUrl ||
+        (harness !== "claude-code" ? readClientMcpBlock("claude-code", homeDir).flairUrl : undefined) ||
         resolveBaseUrl({}));
 }
 function requireSupportedHarness(raw) {
@@ -4553,19 +4643,19 @@ hook
     .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>", "Agent ID to wire (else FLAIR_AGENT_ID, else the agent already wired for this harness's 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)")
+    .option("--url <url>", "Flair URL to wire (else FLAIR_TARGET/FLAIR_URL, else this harness's MCP wiring, else the local default)")
     .option("--continuity", "Wire the continuity capture hooks instead (PostToolUse + Stop — flair#1257; installing them IS the opt-in)")
     .action((opts) => {
     const harness = requireSupportedHarness(opts.harness);
     const home = homedir();
-    const agentId = resolveHookAgentId(opts, home);
+    const agentId = resolveHookAgentId(opts, home, harness);
     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 flairUrl = resolveHookFlairUrl(opts, home, harness);
     const dryRun = !!opts.dryRun;
     if (opts.continuity) {
         const result = installContinuityHooks({ homeDir: home, harness, agentId, flairUrl, dryRun });
@@ -4582,6 +4672,11 @@ hook
     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}`);
+    const pinWarning = unpinnedSpecWarning();
+    if (pinWarning && result.ok) {
+        for (const line of pinWarning.split("\n"))
+            console.error(`   ⚠ ${line}`);
+    }
     if (result.backupPath) {
         console.log(`     ${render.wrap(render.c.dim, `backup: ${result.backupPath}`)}`);
     }
@@ -4641,16 +4736,20 @@ hook
     // status in every branch below. "absent" is NOT a failure: installing the
     // pair is the opt-in, so absence renders as "not enabled".
     const renderContinuity = () => {
+        // Continuity is Claude Code only. Do not tip `--continuity --harness
+        // <other>` — that writes Claude tool matchers into the wrong file.
+        if (!harnessSupportsContinuity(harness))
+            return;
         const cont = continuityHookStatus(home, harness);
         if (cont.state === "installed") {
             console.log(`  ${render.icons.ok} continuity capture: PostToolUse + Stop wired`);
         }
         else if (cont.state === "absent") {
-            console.log(`  ${render.icons.info} continuity capture: not enabled ${render.wrap(render.c.dim, "(opt-in: flair hook install --continuity)")}`);
+            console.log(`  ${render.icons.info} continuity capture: not enabled ${render.wrap(render.c.dim, `(opt-in: ${hookInstallHint(harness, "--continuity")})`)}`);
         }
         else {
             const missing = !cont.postToolUse.present ? "PostToolUse missing" : !cont.stop.present ? "Stop missing" : "stale form";
-            console.log(`  ${render.icons.warn} continuity capture: ${cont.state} (${missing}) ${render.wrap(render.c.dim, "— re-run: flair hook install --continuity")}`);
+            console.log(`  ${render.icons.warn} continuity capture: ${cont.state} (${missing}) ${render.wrap(render.c.dim, `— re-run: ${hookInstallHint(harness, "--continuity")}`)}`);
         }
     };
     console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook status")}\n`);
@@ -4663,21 +4762,28 @@ hook
     }
     if (!status.wired) {
         console.log(`  ${render.icons.error} not wired`);
-        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install`);
+        console.log(`     ${render.wrap(render.c.dim, "Fix:")} ${hookInstallHint(status.harness)}`);
         renderContinuity();
         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)")}`);
+    // flair#1325 — skip the URL line only when agentId was recovered
+    // (the installer form that omits FLAIR_URL). A wired correct-shape
+    // command with no env assignments still prints unknown, not a
+    // silent all-clear.
+    for (const line of hookStatusIdentityLines(status)) {
+        const label = line.label === "Agent" ? "Agent:    " : "Flair URL:";
+        const value = line.value === HOOK_STATUS_UNPARSED ? render.wrap(render.c.dim, line.value) : line.value;
+        console.log(`     ${render.wrap(render.c.dim, label)} ${value}`);
+    }
     // flair#1007 — whether a command that stopped resolving would fail quietly
     // or print an error on every session start.
     if (status.silenced) {
         console.log(`     ${render.wrap(render.c.dim, "On failure:")} silent (exit 0, no output)`);
     }
     else {
-        console.log(`     ${render.icons.warn} ${render.wrap(render.c.dim, "On failure:")} prints an error on every session — run \`flair hook install\` to adopt the silent form`);
+        console.log(`     ${render.icons.warn} ${render.wrap(render.c.dim, "On failure:")} prints an error on every session — run \`${hookInstallHint(status.harness)}\` to adopt the silent form`);
     }
     renderContinuity();
     console.log("");
@@ -5026,6 +5132,7 @@ mcp
     .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("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .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")
@@ -5061,7 +5168,7 @@ mcp
             manifestPath,
             issuer,
             opsPortOrUrl: opsPort,
-            adminUser: DEFAULT_ADMIN_USER,
+            adminUser: resolveAdminUser(opts.adminUser),
             adminPass,
         });
         if (opts.json) {
@@ -5086,6 +5193,7 @@ mcp
     .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("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .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")
@@ -5114,7 +5222,7 @@ mcp
             name,
             manifestPath,
             opsPortOrUrl: opsPort,
-            adminUser: DEFAULT_ADMIN_USER,
+            adminUser: resolveAdminUser(opts.adminUser),
             adminPass,
             keepKeys: !!opts.keepKeys,
         });
@@ -5205,6 +5313,7 @@ mcp
     .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. Required explicitly for a remote target — FLAIR_ADMIN_PASS and ~/.flair/admin-pass are this machine's local credentials and are never sent to a remote instance")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .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")
@@ -5264,7 +5373,7 @@ mcp
         idpSubject,
         principal: opts.principal,
         principalKind: opts.principalKind,
-        adminUser: DEFAULT_ADMIN_USER,
+        adminUser: resolveAdminUser(opts.adminUser),
         adminPass,
         signingKeyFilePath: opts.signingKeyFile,
         secretsMechanism,
@@ -5313,6 +5422,7 @@ mcp
     .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("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .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) => {
@@ -5328,7 +5438,7 @@ mcp
         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 });
+    const result = await disableMcp({ instance, adminUser: resolveAdminUser(opts.adminUser), adminPass, confirmFlagOff: Boolean(opts.confirmFlagOff) }, { confirmPrompt: confirmYesNo });
     if (opts.json) {
         console.log(render.asJSON(result));
         if (!result.ok)
@@ -5399,12 +5509,13 @@ principal
     .option("--runtime <runtime>", "Runtime: openclaw, claude-code, headless, external")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password for registration")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
     .action(async (id, opts) => {
     const opsPort = resolveOpsPort(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     const kind = opts.kind ?? "agent";
     const name = opts.name ?? id;
     const isAdmin = opts.admin ?? false;
@@ -5491,6 +5602,7 @@ principal
     .description("List all principals")
     .option("--kind <kind>", "Filter by kind: human or agent")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
@@ -5501,7 +5613,7 @@ principal
         console.error(`${render.icons.error} --admin-pass or FLAIR_ADMIN_PASS required`);
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const conditions = opts.kind
         ? [{ search_attribute: "kind", search_type: "equals", search_value: opts.kind }]
         : [{ search_attribute: "id", search_type: "starts_with", search_value: "" }];
@@ -5623,6 +5735,7 @@ principal
     .command("disable <id>")
     .description("Deactivate a principal (revokes access, preserves data)")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .action(async (id, opts) => {
     const opsPort = resolveOpsPort(opts);
@@ -5631,7 +5744,7 @@ principal
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -5653,6 +5766,7 @@ principal
     .command("promote <id> <tier>")
     .description("Change a principal's trust tier (endorsed, corroborated, unverified)")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .action(async (id, tier, opts) => {
     const validTiers = ["endorsed", "corroborated", "unverified"];
@@ -5666,7 +5780,7 @@ principal
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -5698,6 +5812,7 @@ idp
     .option("--no-jit-provision", "Disable auto-creation of principals for new IdP users")
     .option("--default-trust <tier>", "Trust tier for JIT principals", "unverified")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .action(async (opts) => {
     const opsPort = resolveOpsPort(opts);
@@ -5707,7 +5822,7 @@ idp
         process.exit(1);
     }
     const id = `idp_${randomUUID().slice(0, 8)}`;
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const now = new Date().toISOString();
     const record = {
         id,
@@ -5744,6 +5859,7 @@ idp
     .command("list")
     .description("List configured IdPs")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
@@ -5753,7 +5869,7 @@ idp
         console.error(`${render.icons.error} --admin-pass or FLAIR_ADMIN_PASS required`);
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -5798,6 +5914,7 @@ idp
     .command("remove <id>")
     .description("Remove an IdP configuration")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .action(async (id, opts) => {
     const opsPort = resolveOpsPort(opts);
@@ -5806,7 +5923,7 @@ idp
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -5865,12 +5982,13 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys (for from-agent Ed25519 auth)")
     .action(async (fromAgent, toAgent, opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     const scope = opts.scope ?? "read";
     if (!adminPass) {
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for grant");
@@ -5914,11 +6032,12 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .action(async (fromAgent, toAgent, opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     if (!adminPass) {
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required for revoke");
         process.exit(1);
@@ -5962,7 +6081,7 @@ async function loadInstanceSecretKey(instanceId, opts) {
     // Fallback: check DB for legacy _keySeed
     const opsPort = resolveOpsPort(opts);
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -6048,6 +6167,95 @@ function driverCheckAppliesTo(opts) {
     const target = resolveTarget(opts);
     return !target || isLocalBase(target.replace(/\/$/, ""));
 }
+/**
+ * flair#1108: a bare undici/Node "fetch failed" names neither the URL
+ * that was probed nor the knob that would change it. These helpers are
+ * the operator-facing sentence and the setting that produced (or would
+ * change) that URL. Pure so the contract can be unit-tested without
+ * driving process.exit.
+ */
+export function federationStatusUrlSetting(opts) {
+    if (opts.target)
+        return "--target";
+    if (process.env.FLAIR_TARGET)
+        return "FLAIR_TARGET";
+    if (process.env.FLAIR_URL)
+        return "FLAIR_URL";
+    if (opts.port !== undefined && opts.port !== null && String(opts.port) !== "")
+        return "--port";
+    return "FLAIR_URL or --port";
+}
+export function describeFederationStatusFetchFailed(url, setting) {
+    return `fetch failed against ${url} (set ${setting})`;
+}
+/** True for a connect-level failure (no HTTP status): Node's undici
+ *  `TypeError: fetch failed`, Bun's `Unable to connect…`, or a cause
+ *  carrying a connect/DNS errno. Auth and HTTP errors stay out. */
+export function isFederationStatusConnectFailure(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/\bfetch failed\b/i.test(msg))
+        return true;
+    if (/unable to connect/i.test(msg))
+        return true;
+    const cause = err instanceof Error ? err.cause : undefined;
+    const code = cause && typeof cause === "object" && cause && "code" in cause
+        ? String(cause.code)
+        : "";
+    return /^(ECONNREFUSED|ENOTFOUND|ECONNRESET|ETIMEDOUT|EAI_AGAIN|EHOSTUNREACH)$/.test(code);
+}
+export function rewriteFederationStatusFetchFailed(err, url, setting) {
+    if (!isFederationStatusConnectFailure(err))
+        return err;
+    const next = new Error(describeFederationStatusFetchFailed(url, setting));
+    if (err && typeof err === "object" && "status" in err) {
+        next.status = err.status;
+    }
+    return next;
+}
+/**
+ * Auth-shaped vs connect-level for `federation status`. A rewritten
+ * fetch-failed sentence embeds the probed URL; that URL can contain a
+ * whole-token `401` (e.g. `--port 401`). The old `message.includes("401")`
+ * check then printed the credential remedy and hid the URL+setting this
+ * change exists to surface (Bugbot on flair#1108).
+ */
+export function isFederationStatusAuthFailure(err) {
+    if (!err)
+        return false;
+    if (isFederationStatusConnectFailure(err))
+        return false;
+    if (typeof err === "object" && "status" in err) {
+        const status = err.status;
+        if (status === 401 || status === 403)
+            return true;
+    }
+    const m = err instanceof Error
+        ? err.message
+        : String(typeof err === "object" && err && "message" in err
+            ? err.message ?? err
+            : err);
+    return m.includes("missing_or_invalid_authorization") || /(?:^|\D)401(?:\D|$)/.test(m);
+}
+/**
+ * Whether to print the "set one of: FLAIR_AGENT_ID / FLAIR_ADMIN_PASS /
+ * FLAIR_TOKEN" block. Narrower than `isFederationStatusAuthFailure`: a
+ * 403 with credentials already sent (wrong password) is fatal, but the
+ * server's own body is the honest message — the credential-list remedy
+ * is for missing/invalid auth (401), not a rejected password (flair#634).
+ */
+export function isFederationStatusAuthRemedy(err) {
+    if (!err || isFederationStatusConnectFailure(err))
+        return false;
+    if (typeof err === "object" && "status" in err && err.status === 401) {
+        return true;
+    }
+    const m = err instanceof Error
+        ? err.message
+        : String(typeof err === "object" && err && "message" in err
+            ? err.message ?? err
+            : err);
+    return m.includes("missing_or_invalid_authorization") || /(?:^|\D)401(?:\D|$)/.test(m);
+}
 federation
     .command("status")
     .description("Show federation status and peer connections")
@@ -6056,8 +6264,11 @@ federation
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .option("--json", "Emit JSON {instance, peers, driver} (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const target = resolveTarget(opts);
-    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    // Same URL api() would have derived, including --port (the command
+    // advertised --port but previously dropped it on the floor). Naming
+    // that URL on fetch failure is only honest if it is the URL we probe.
+    const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+    const urlSetting = federationStatusUrlSetting(opts);
     const mode = render.resolveOutputMode(opts);
     // flair#1233: fetch instance and peers INDEPENDENTLY. One read failing
     // must never take down the whole render — the principle latestPeerContact
@@ -6067,41 +6278,33 @@ federation
     let instance = null;
     let instanceErr = null;
     try {
-        instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
+        instance = await api("GET", "/FederationInstance", undefined, { baseUrl });
     }
     catch (err) {
-        instanceErr = err;
+        instanceErr = rewriteFederationStatusFetchFailed(err, baseUrl, urlSetting);
     }
     // peers: null = unverifiable (the read failed), [] = verified empty.
     let peers = null;
     let peersErr = null;
     try {
-        const r = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        const r = await api("GET", "/FederationPeers", undefined, { baseUrl });
         peers = r.peers ?? [];
     }
     catch (err) {
-        peersErr = err;
+        peersErr = rewriteFederationStatusFetchFailed(err, baseUrl, urlSetting);
     }
     // Auth-shaped failures stay FATAL even when the other read succeeded:
     // both endpoints sit behind the same allowAdmin gate, so a 401/403 is a
     // property of the session's credentials, not of one endpoint — and
     // degrading it to "unverifiable" would swallow the actionable remedy
     // (flair#634's UX, kept). Only non-auth failures degrade independently.
-    const authShaped = (err) => {
-        if (!err)
-            return false;
-        if (err.status === 401 || err.status === 403)
-            return true;
-        const m = String(err.message ?? err);
-        return m.includes("missing_or_invalid_authorization") || m.includes("401");
-    };
     // Both reads failed → nothing to render at all. Either way keep the
     // classic failure UX (auth remedy when it's an auth problem), exit
     // non-zero.
-    if ((instanceErr && peersErr) || authShaped(instanceErr) || authShaped(peersErr)) {
+    if ((instanceErr && peersErr) || isFederationStatusAuthFailure(instanceErr) || isFederationStatusAuthFailure(peersErr)) {
         const primaryErr = instanceErr ?? peersErr;
         const msg = String(primaryErr.message ?? primaryErr);
-        if (msg.includes("missing_or_invalid_authorization") || msg.includes("401")) {
+        if (isFederationStatusAuthRemedy(primaryErr)) {
             console.error(`${render.icons.error} federation status requires auth.`);
             console.error(`  ${render.wrap(render.c.dim, "Set one of:")}`);
             console.error(`    ${render.wrap(render.c.cyan, "FLAIR_AGENT_ID=<your-agent-id>")}     ${render.wrap(render.c.dim, "(Ed25519 — uses ~/.flair/keys/<id>.key)")}`);
@@ -6459,6 +6662,7 @@ federation
     .description("Pair this spoke with a hub instance")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--token <token>", "One-time pairing token from hub admin (env: FLAIR_PAIRING_TOKEN) [deprecated: use --token-from]")
     .option("--token-from <file>", "Read bootstrap triple from JSON file (use '-' for stdin)")
@@ -6536,7 +6740,7 @@ federation
                 "Without it, 'flair federation sync' will report 'No hub peer configured'.");
             process.exit(1);
         }
-        const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
         const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
         const peerRes = await fetch(`${opsEndpoint}/`, {
             method: "POST",
@@ -6573,6 +6777,7 @@ federation
     .description("Generate a one-time pairing token (run on the hub)")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--ttl <minutes>", "Token TTL in minutes (default: 60)", "60")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
@@ -6587,7 +6792,7 @@ federation
         const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000).toISOString();
         const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-        const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
         // 1. Persist the PairingToken record
         const opsRes = await fetch(`${opsEndpoint}/`, {
             method: "POST",
@@ -6692,7 +6897,7 @@ export async function runFederationSyncOnce(opts) {
         const syncStartedAt = new Date().toISOString();
         const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
         const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-        const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
         const tables = ["Memory", "Soul", "Agent", "Relationship"];
         const instance = await api("GET", "/FederationInstance", undefined, apiOpts);
         const hubUrl = hub.endpoint ?? hub.id;
@@ -6934,28 +7139,16 @@ export async function runFederationSyncOnce(opts) {
         return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
     }
 }
-const federationSync = federation
+const federationSync = addSharedCredentialOptions(federation
     .command("sync")
     .description("Push local changes to the hub (one-shot). Subcommands manage the scheduled driver.")
     .option("--port <port>", "Harper HTTP port")
-    .option("--admin-pass <pass>", "Admin password")
-    .option("--admin-pass-file <path>", "Read the admin password from a file (e.g. ~/.flair/admin-pass). Preferred for launchd/cron — keeps the secret out of ps and shell history.")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
-    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
-    .action(async (opts) => {
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")).action(async (opts) => {
     // --admin-pass-file resolves into the same `adminPass` slot the inline
     // flag uses, so the scheduler never has to embed a secret in a unit file.
-    // readAdminPassFileSecure() refuses a file that is not owner-only.
-    if (!opts.adminPass && opts.adminPassFile) {
-        try {
-            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
-        }
-        catch (err) {
-            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
-            process.exit(1);
-        }
-    }
+    applyAdminPassFile(opts);
     const r = await runFederationSyncOnce(opts);
     if (r.error) {
         console.error(`Error: ${r.error.message}`);
@@ -7140,6 +7333,7 @@ federation
     .option("--interval <seconds>", "Seconds between syncs", "30")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair URL")
     .option("--ops-target <url>", "Explicit ops API URL")
@@ -8666,7 +8860,7 @@ async function fetchHealthDetail(opts, signingAgentIdOverride) {
             const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
             if (adminPass) {
                 res = await fetch(`${baseUrl}/Health`, {
-                    headers: { Authorization: `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}` },
+                    headers: { Authorization: `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPass}`).toString("base64")}` },
                     signal: AbortSignal.timeout(5000),
                 });
             }
@@ -8718,8 +8912,10 @@ const statusCmd = program
         discoveredPort = await discoverLocalFlairPort(baseUrl);
     }
     // Version-behind check (flair#587) — offline-tolerant + cached, so this
-    // never adds meaningful latency or fails `status` when the registry is
-    // unreachable. Independent of Harper health; runs either way.
+    // never fails `status` when the registry is unreachable, and costs no
+    // network round trip on the common up-to-date path. When a cached answer
+    // would print a nudge it spends one short-timeout refetch so the printed
+    // fact is current (flair#1341). Independent of Harper health; runs either way.
     const versionCheckResult = await checkVersion(__pkgVersion);
     const versionNudge = formatVersionNudge(versionCheckResult);
     if (opts.json) {
@@ -9211,7 +9407,7 @@ statusCmd
             }
         }
         else {
-            const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+            const auth = `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPass}`).toString("base64")}`;
             const maxTokens = Number.parseInt(String(opts.maxTokens ?? "4000"), 10);
             for (const agentId of agentList) {
                 try {
@@ -11754,7 +11950,7 @@ program
         // embedding with a freshly-computed one. Without this path, `flair
         // reembed` could not recover from the very condition it exists to fix.
         const opsPort = resolveOpsPort(opts);
-        const opsAuth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+        const opsAuth = `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPass}`).toString("base64")}`;
         // Harper rejects empty-value conditions ("not indexed for nulls"). Use
         // `createdAt > 1970-01-01` as the "select all" pattern: every Memory row
         // has a createdAt, the index is built, and the comparison is total.
@@ -11852,7 +12048,7 @@ program
     let allMemories = [];
     if (adminPassSingle) {
         const opsPort = resolveOpsPort(opts);
-        const opsAuth = `Basic ${Buffer.from(`admin:${adminPassSingle}`).toString("base64")}`;
+        const opsAuth = `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPassSingle}`).toString("base64")}`;
         const searchRes = await fetch(`http://127.0.0.1:${opsPort}/`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: opsAuth },
@@ -11940,7 +12136,10 @@ program
         console.error(`${render.icons.error} ${render.wrap(render.c.red, "set --agent / FLAIR_AGENT_ID or FLAIR_ADMIN_PASS")}`);
         process.exit(1);
     }
-    const baseUrl = `http://127.0.0.1:${resolveHttpPort(opts)}`;
+    // Single source of truth (flair#1351): banner prints the URL the test's
+    // own client uses. resolveBaseUrl is the existing CLI resolver; pass the
+    // same value through to api() so the two cannot diverge.
+    const baseUrl = resolveBaseUrl(opts);
     console.log(`\n${render.wrap(render.c.bold, "Flair test")} ${render.wrap(render.c.dim, `(url: ${baseUrl})`)}\n`);
     let passed = 0;
     let failed = 0;
@@ -11975,7 +12174,7 @@ program
         };
         if (agentId)
             body.agentId = agentId;
-        await api("PUT", `/Memory/${id}`, body);
+        await api("PUT", `/Memory/${id}`, body, { baseUrl });
         memoryId = id;
         return true;
     });
@@ -11985,7 +12184,7 @@ program
         const body = { q: "flair test", limit: 5 };
         if (agentId)
             body.agentId = agentId;
-        const result = await api("POST", "/SemanticSearch", body);
+        const result = await api("POST", "/SemanticSearch", body, { baseUrl });
         return (result?.results?.length ?? 0) > 0;
     });
     // 3. Delete the test memory via DELETE /Memory/<id>
@@ -11995,7 +12194,7 @@ program
             console.log(`       (skipped — no id returned from write step)`);
             return true;
         }
-        await api("DELETE", `/Memory/${memoryId}`, agentId ? { agentId } : undefined);
+        await api("DELETE", `/Memory/${memoryId}`, agentId ? { agentId } : undefined, { baseUrl });
         return true;
     });
     const passColor = passed > 0 ? render.c.green : render.c.dim;
@@ -12666,6 +12865,9 @@ program
         catch { /* unreachable/unparseable → null → the finding is skipped, not passed */ }
         // The component directory for a local install is the flair package itself:
         // `flair start` spawns `harper run .` with cwd = flairPackageDir().
+        // That path is often inside node_modules on an npm install-g; doctor still
+        // READs it for drift detection, but describePublicUrlFinding never names
+        // it as the fix (flair#1313 — wiped on every upgrade).
         const componentEnvPath = join(flairPackageDir(), COMPONENT_ENV_FILENAME);
         let componentEnvValue = null;
         try {
@@ -12755,7 +12957,7 @@ program
         }
         const auditStatus = auditCredIssue
             ? { state: "skipped", reason: "no-admin-credentials", detail: auditCredIssue }
-            : await verifyAuditLog(baseUrl, opts.agent, defaultKeysDir(), `http://127.0.0.1:${resolveOpsPort(opts)}`, DEFAULT_ADMIN_USER, auditAdminPass);
+            : await verifyAuditLog(baseUrl, opts.agent, defaultKeysDir(), `http://127.0.0.1:${resolveOpsPort(opts)}`, resolveAdminUser(undefined), auditAdminPass);
         switch (auditStatus.state) {
             case "ok":
                 // Present-tense claim ONLY (see AuditVerifyResult): the probe
@@ -12834,11 +13036,13 @@ program
     }
     // 7. Client integration (flair#588) — the first 6 checks diagnose the
     // SERVER side. This diagnoses whether Flair is actually wired to a real
-    // MCP client (Claude Code, Codex, Gemini, Cursor): the MCP block present
-    // + reachable + the configured agent genuinely registered (every detected
-    // client), plus CLAUDE.md + the SessionStart hook (Claude Code only,
-    // since only Claude Code has those mechanisms). Reuses detectClients()
-    // rather than reimplementing client detection.
+    // client: for MCP clients (Claude Code, Codex, Gemini, Cursor,
+    // Antigravity) the MCP block present + reachable + the configured agent
+    // genuinely registered; for pi (a NATIVE EXTENSION host — flair#1342) the
+    // pi-flair reference in pi's own settings, including the flair#1346
+    // npm:-under-"extensions" trap; plus CLAUDE.md (Claude Code) and the
+    // SessionStart hook (Claude Code + Codex — flair#1148). Reuses
+    // detectClients() rather than reimplementing client detection.
     console.log(`\n  ${render.wrap(render.c.bold, "Client integration")}`);
     // Prompt y/N before a content-editing fix, but only when interactive —
     // in a non-TTY context (CI, scripts) --fix itself is the consent signal,
@@ -12858,6 +13062,7 @@ program
     }
     else {
         let claudeCodeAgentId;
+        let codexAgentId;
         let anyKnownAgentId;
         // `doctor --fix` writes client configs through the same wire functions
         // init does, so it owes the user the same warning when the spec it would
@@ -12870,9 +13075,175 @@ program
             }
         }
         for (const client of detectedClients) {
+            // ── pi (flair#1342): NATIVE EXTENSION, not an MCP client ───────────
+            // There is no mcpServers block to read — pi loads @tpsdev-ai/pi-flair
+            // through its own settings.json (`packages`). Every check below is a
+            // filesystem fact except agent registration, which is only checkable
+            // when this shell exposes the env pi would launch with — and the
+            // output says which of the two it verified.
+            if (client.kind === "native-extension") {
+                let pi = checkPiFlairWiring(homedir(), process.cwd());
+                // --fix for pi needs no agent id (pi settings carry no env block);
+                // a resolvable id only improves the export hint in the message.
+                const wirePiFix = async (prompt) => {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would update")} ${pi.settingsPath}`);
+                        return;
+                    }
+                    const proceed = await confirmFix(prompt);
+                    if (!proceed) {
+                        console.log(`     Skipped.`);
+                        return;
+                    }
+                    const hintAgentId = resolveFixAgentId({
+                        optsAgent: opts.agent,
+                        envAgentId: process.env.FLAIR_AGENT_ID,
+                        anyKnownAgentId,
+                        keyAgentIds,
+                        keysDir: defaultKeysDir(),
+                    }) ?? "<your-agent-id>";
+                    const wireResult = wirePi({ FLAIR_AGENT_ID: hintAgentId, FLAIR_URL: baseUrl });
+                    console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
+                    if (wireResult.ok)
+                        fixed++;
+                };
+                // (a) The flair#1346 trap FIRST, and by NAME: an npm: spec under
+                // "extensions" is silently ignored by pi — the user believes they
+                // are wired while pi registers zero tools. This is the documented
+                // field failure mode and must never fold into a generic "not
+                // wired": the fix is a MOVE to "packages", not an add.
+                const userTraps = pi.misconfigured.filter((m) => m.path === pi.settingsPath);
+                const projectTraps = pi.misconfigured.filter((m) => m.path !== pi.settingsPath);
+                for (const bad of pi.misconfigured) {
+                    console.log(`  ${render.icons.error} pi: ${PI_FLAIR_PACKAGE} is listed under "extensions" as an npm: spec (${bad.entry}) in ${render.wrap(render.c.dim, bad.path)}`);
+                    console.log(`     pi silently ignores npm: specs under "extensions", so the Flair tools never register (flair#1346). Package sources belong under "packages".`);
+                    issues++;
+                }
+                if (userTraps.length > 0) {
+                    if (autoFix) {
+                        await wirePiFix(`  Move the npm: spec to "packages" in ${pi.settingsPath} now? [y/N] `);
+                        // Re-derive the wiring from disk so the sections below reason
+                        // about the POST-fix state — otherwise a move that just
+                        // succeeded would still read as "not wired" and prompt again.
+                        pi = checkPiFlairWiring(homedir(), process.cwd());
+                    }
+                    else {
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(moves it to "packages")`)}`);
+                    }
+                }
+                if (projectTraps.length > 0) {
+                    // wirePi edits the USER-scope settings only — a project-scope
+                    // trap gets the exact manual fix, never a --fix that claims a
+                    // file it does not touch.
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} move the entry from "extensions" to "packages" in ${projectTraps[0].path}`);
+                }
+                if (!pi.wired) {
+                    console.log(`  ${render.icons.error} pi: ${PI_FLAIR_PACKAGE} not wired in ${render.wrap(render.c.dim, pi.settingsPath)}`);
+                    if (autoFix) {
+                        await wirePiFix(`  Wire pi now (adds ${piFlairSpec()} to "packages" in ${pi.settingsPath})? [y/N] `);
+                    }
+                    else {
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(adds ${piFlairSpec()} to "packages")`)} — or: pi install npm:${PI_FLAIR_PACKAGE}`);
+                    }
+                    issues++;
+                    continue;
+                }
+                if (pi.wiredVia === "packages") {
+                    console.log(`  ${render.icons.ok} pi: ${PI_FLAIR_PACKAGE} wired via "packages" (${pi.spec}) in ${render.wrap(render.c.dim, pi.wiredIn)}`);
+                    if (!pi.pinnedVersion) {
+                        console.log(`     ${render.icons.info} unpinned — pi re-resolves latest on (re)install; pin with ${piFlairSpec()}`);
+                    }
+                }
+                else {
+                    // extension-path: the documented pre-0.49 workaround (a local
+                    // path to the installed dist/index.js). Works, but the canonical
+                    // form is a "packages" entry — and a DANGLING path is a broken
+                    // wiring pi skips silently, so check the one thing checkable.
+                    if (pi.extensionPathExists) {
+                        console.log(`  ${render.icons.ok} pi: ${PI_FLAIR_PACKAGE} wired via a file-path "extensions" entry (${pi.spec}) in ${render.wrap(render.c.dim, pi.wiredIn)}`);
+                        console.log(`     ${render.wrap(render.c.dim, `pre-0.49 workaround — the canonical form is a "packages" entry: ${piFlairSpec()}`)}`);
+                    }
+                    else {
+                        console.log(`  ${render.icons.error} pi: the "extensions" entry ${pi.spec} in ${render.wrap(render.c.dim, pi.wiredIn)} points at a file that does not exist — pi silently skips missing extension paths`);
+                        if (autoFix) {
+                            await wirePiFix(`  Wire pi via "packages" instead (adds ${piFlairSpec()})? [y/N] `);
+                        }
+                        else {
+                            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(adds ${piFlairSpec()} to "packages"; remove the dangling entry yourself)`)}`);
+                        }
+                        issues++;
+                        continue;
+                    }
+                }
+                // Env sanity (flair#1342 scope 3). pi settings carry no env block:
+                // pi-flair reads FLAIR_* from the environment of whatever shell/IDE
+                // launches pi. Doctor can only see ITS OWN environment — these
+                // lines verify this shell, and say so, rather than pretending to
+                // verify every pi launch. None of them counts as an issue: a clean
+                // pi launched elsewhere can be fine while this shell is bare, and
+                // vice versa.
+                console.log(`     ${render.wrap(render.c.dim, "pi-flair reads FLAIR_AGENT_ID / FLAIR_URL / FLAIR_KEY_PATH from the shell that launches pi — doctor sees only its own environment (this shell):")}`);
+                const piEnvAgent = process.env.FLAIR_AGENT_ID;
+                const piEnvUrl = process.env.FLAIR_URL;
+                const piEnvKey = process.env.FLAIR_KEY_PATH;
+                if (piEnvAgent) {
+                    console.log(`     ${render.icons.ok} FLAIR_AGENT_ID set ('${piEnvAgent}')`);
+                }
+                else {
+                    console.log(`     ${render.icons.warn} FLAIR_AGENT_ID not set in this shell — pi-flair falls back to the cwd directory name as its agent id (identity varies by project); export FLAIR_AGENT_ID=<id> where pi is launched`);
+                }
+                if (piEnvUrl) {
+                    console.log(`     ${render.icons.ok} FLAIR_URL set (${piEnvUrl})`);
+                }
+                else {
+                    console.log(`     ${render.icons.info} FLAIR_URL not set — pi-flair defaults to ${render.wrap(render.c.dim, PI_FLAIR_DEFAULT_URL)}`);
+                }
+                if (piEnvKey) {
+                    if (existsSync(piEnvKey)) {
+                        console.log(`     ${render.icons.ok} FLAIR_KEY_PATH set (${piEnvKey})`);
+                    }
+                    else {
+                        console.log(`     ${render.icons.warn} FLAIR_KEY_PATH points at a missing file (${piEnvKey})`);
+                    }
+                }
+                else {
+                    console.log(`     ${render.icons.info} FLAIR_KEY_PATH not set — auto-resolved from ~/.flair/keys`);
+                }
+                // Agent registration — checkable only when this shell exposes an
+                // agent id at all; otherwise say what was NOT verified instead of
+                // skipping silently.
+                if (piEnvAgent) {
+                    const piUrl = piEnvUrl || PI_FLAIR_DEFAULT_URL;
+                    const piReachable = await probeFlairReachable(piUrl);
+                    if (!piReachable) {
+                        console.log(`     ${render.icons.warn} FLAIR_URL ${render.wrap(render.c.dim, piUrl)} not reachable — cannot verify agent registration`);
+                    }
+                    else {
+                        const piReg = await checkAgentRegistered(piUrl, piEnvAgent, defaultKeysDir());
+                        if (piReg.state === "registered") {
+                            console.log(`     ${render.icons.ok} agent '${piEnvAgent}' registered`);
+                        }
+                        else if (piReg.state === "not-registered") {
+                            console.log(`     ${render.icons.error} agent '${piEnvAgent}' is NOT registered on this Flair instance`);
+                            console.log(`        ${render.wrap(render.c.dim, "Fix:")} flair agent add ${piEnvAgent}`);
+                            issues++;
+                        }
+                        else {
+                            const piFinding = describeAgentGateFinding(piEnvAgent, piReg.state, piReg.detail, { instanceReachable: piReachable });
+                            console.log(`     ${render.icons.warn} ${piFinding?.message ?? `could not verify agent registration (${piReg.detail})`}`);
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "agent registration not verified — no FLAIR_AGENT_ID visible to doctor")}`);
+                }
+                continue;
+            }
             const block = readClientMcpBlock(client.id, homedir());
             if (client.id === "claude-code" && block.agentId)
                 claudeCodeAgentId = block.agentId;
+            if (client.id === "codex" && block.agentId)
+                codexAgentId = block.agentId;
             if (block.agentId)
                 anyKnownAgentId = anyKnownAgentId ?? block.agentId;
             if (!block.present) {
@@ -12919,8 +13290,14 @@ program
                                             client.id === "antigravity" ? wireAntigravity(wireEnv) :
                                                 wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
-                                if (wireResult.ok)
+                                if (wireResult.ok) {
                                     fixed++;
+                                    if (client.id === "claude-code")
+                                        claudeCodeAgentId = fixAgentId;
+                                    if (client.id === "codex")
+                                        codexAgentId = fixAgentId;
+                                    anyKnownAgentId = anyKnownAgentId ?? fixAgentId;
+                                }
                             }
                         }
                     }
@@ -12970,8 +13347,9 @@ program
                 console.log(`     ${render.icons.warn} ${finding?.message ?? `could not verify agent registration (${reg.detail})`}`);
             }
         }
-        // Claude-Code-specific: CLAUDE.md + SessionStart hook. Only Claude Code
-        // has these mechanisms, so only run them when claude-code was detected.
+        // Claude-Code-specific: CLAUDE.md + SessionStart hook + continuity.
+        // Codex has a SessionStart hook too (checked below); CLAUDE.md and
+        // continuity stay Claude Code only.
         if (detectedClients.some((c) => c.id === "claude-code")) {
             const claudeMd = checkClaudeMdBootstrap(process.cwd(), homedir());
             if (claudeMd.present) {
@@ -13161,6 +13539,92 @@ program
                 issues++;
             }
         }
+        // Codex SessionStart hook (flair#1148) — same flair-session-start
+        // command Claude Code uses, written to ~/.codex/hooks.json. Continuity
+        // and CLAUDE.md stay Claude-Code-only; Codex's session-start mechanism
+        // is the hook file.
+        if (detectedClients.some((c) => c.id === "codex")) {
+            const hook = inspectSessionStartHook(homedir(), { settingsPath: hookSettingsPath(homedir(), "codex") });
+            if (hook.present) {
+                if (hook.execution === "broken") {
+                    if (hook.silenced) {
+                        console.log(`  ${render.icons.ok} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)} — not yet exercised`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "The hook is correctly wired but the adapter has not been fetched yet.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "This is normal on a fresh install — the first Codex session will warm the npx cache.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Codex requires /hooks to trust a newly written command before it runs.")}`);
+                    }
+                    else {
+                        console.log(`  ${render.icons.warn} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex ${render.wrap(render.c.dim, "(rewrites the hook to the current silent-failure form)")}`);
+                    }
+                }
+                else if (hook.execution === "unknown") {
+                    console.log(`  ${render.icons.warn} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)}, but could not be verified ${render.wrap(render.c.dim, `(${hook.detail ?? "no detail"})`)}`);
+                }
+                else if (!hook.ours) {
+                    console.log(`  ${render.icons.ok} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "(custom command — not verified, not modified)")}`);
+                }
+                else {
+                    console.log(`  ${render.icons.ok} SessionStart hook (codex): flair-session-start wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "and still runs")}`);
+                }
+                if (!hook.silenced && hook.ours) {
+                    console.log(`  ${render.icons.warn} SessionStart hook (codex): a failure would print an error on every session (this command predates the silent-failure fix)`);
+                    if (hook.upgradable) {
+                        if (autoFix) {
+                            if (dryRun) {
+                                console.log(`     ${render.wrap(render.c.dim, "Would rewrite the hook command in")} ${hook.path}`);
+                            }
+                            else {
+                                const proceed = await confirmFix(`  Rewrite the Flair SessionStart hook in ${hook.path} so failures stay silent? [y/N] `);
+                                if (!proceed) {
+                                    console.log(`     Skipped.`);
+                                }
+                                else {
+                                    const upgrade = upgradeSessionStartHookCommand(homedir(), hook.path);
+                                    console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
+                                    if (upgrade.ok && upgrade.changed)
+                                        fixed++;
+                                }
+                            }
+                        }
+                        else {
+                            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex ${render.wrap(render.c.dim, "(rewrites the hook command in place — same agent, same instance)")}`);
+                        }
+                    }
+                    else {
+                        console.log(`     ${render.wrap(render.c.dim, "This hook was hand-edited, so Flair will not rewrite it. To adopt the current form:")} flair hook install --harness codex`);
+                    }
+                    issues++;
+                }
+            }
+            else {
+                console.log(`  ${render.icons.error} SessionStart hook (codex): not found in ${render.wrap(render.c.dim, hook.path)}`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would add SessionStart hook to")} ${hook.path}`);
+                    }
+                    else {
+                        const proceed = await confirmFix(`  Add the flair-session-start SessionStart hook to ${hook.path}? [y/N] `);
+                        if (!proceed) {
+                            console.log(`     Skipped.`);
+                        }
+                        else {
+                            const fixAgentId = resolveHookAgentId({ agent: opts.agent }, homedir(), "codex");
+                            const fixRes = fixSessionStartHook(homedir(), fixAgentId, hook.path);
+                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                            if (fixRes.ok)
+                                fixed++;
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex`);
+                }
+                issues++;
+            }
+        }
     }
     // 7a. Resolve which agent identities the two verified-read sections below
     // (Fleet presence, Migrations) iterate (flair#722). Previously both
@@ -13560,7 +14024,8 @@ program
 // from /HealthDetail at all — it's the one metric in this file that requires
 // live QUERIES, because it's checking whether querying itself still works.
 // For a sample of the querying agent's OWN memories (fetchRecallSpotCheckData
-// below, GET /Memory?agentId=<self>), a CUE is derived from each memory
+// below, a projected+bounded GET /Memory — flair#1360: never the unfiltered
+// collection with embeddings inline), a CUE is derived from each memory
 // (deriveRecallCue — its `subject` if present, else the leading ~8 words /
 // first sentence of `content`; a PARTIAL cue, never the full content) and
 // searched for through the EXACT SAME authenticated read path `flair memory
@@ -13573,23 +14038,42 @@ program
 // own id appears in its search's top-k; MRR = mean reciprocal rank (0 if
 // not found within k).
 //
-// Framing — this is a HEALTH SPOT-CHECK, not a benchmark and not a trust
-// judgment. Querying by a cue derived FROM the target memory is easier than
-// a real user query, so a high score means "recall is functioning", not
-// "recall is optimal". Its job is to catch recall CRATERING (embeddings
-// down, index busted) — the score collapsing toward 0 is the signal, not
-// fine-grained precision grading. NOTE (#1216): this cue-from-the-memory
-// design is self-polluting as a recall-QUALITY metric — relevance is
-// query/corpus overlap by construction, so near-duplicate density reads as a
-// recall collapse (flair#967 / #857 / #996). It is deliberately NOT the
-// recall-quality number; that authority is the deterministic, fixed-label,
-// CI-gated eval at test/bench/recall-eval (recall@k / nDCG@10 / MRR). This
-// probe stays scoped to live-health cratering only. Requires an actual
-// agent identity to
-// query AS (semantic search is agent-scoped) — no identity, fewer than the
-// sample-size memories to sample, or a search error all degrade to `null` +
-// a `gaps` entry, same graceful-degradation contract as every metric here —
-// NEVER a false 0.0 masquerading as a real (broken) score.
+// Framing — this is a REPORT-ONLY HEALTH SPOT-CHECK, not a benchmark, not a
+// trust judgment, and (since flair#967) not an alerting signal either.
+// Querying by a cue derived FROM the target memory is easier than a real
+// user query, so a high score means "recall is functioning", not "recall is
+// optimal". NOTE (#1216): this cue-from-the-memory design is self-polluting
+// as a recall-QUALITY metric — relevance is query/corpus overlap by
+// construction, so near-duplicate density reads as a recall collapse
+// (flair#967 / #857 / #996). It is deliberately NOT the recall-quality
+// number; that authority is the deterministic, fixed-label, CI-gated eval at
+// test/bench/recall-eval, wired as a gate in
+// test/integration-heavy/recall-eval-gate.test.ts.
+//
+// flair#967 — WHY THIS METRIC NO LONGER EMITS AN EVENT. Measured on rockit
+// production over 32 nightly runs: population σ = 0.291, mean absolute
+// run-to-run delta = 0.223, against a QUALITY_EVENT_RECALL_DROP_THRESHOLD of
+// 0.2. The alarm sat at 0.69σ — BELOW the metric's own noise floor, so the
+// median night-to-night wobble already exceeded the delta that declared a
+// regression. Replaying diffQualitySnapshots over the stored snapshot series
+// predicts the sweep's 6 findings-mails in 34 runs exactly, 6 for 6, and all
+// six were oscillation: lifetime precision 0. So the emission is gone. The
+// score is still computed, still printed, still snapshotted (history and the
+// cratering signal are both preserved) — it just no longer has the authority
+// to page anyone, because it never once earned it. That authority stays with
+// the deterministic CI gate above, which is fixed-label, hermetic and
+// actually detects ranking regressions. Re-arming this probe is a data
+// question, not a taste question: it needs a measured precision on the FIXED
+// cue derivation first, and a threshold DERIVED from that run-to-run variance
+// (≥2σ on the sample design), not another literal.
+//
+// Requires an actual agent identity to query AS (semantic search is
+// agent-scoped) — no identity, fewer than the sample-size memories to sample,
+// an UNHEALTHY sample (planRecallSpotCheck below: duplicate or empty cues, so
+// the window cannot be scored fairly) or a search error all degrade to `null`
+// + a `gaps` entry, same graceful-degradation contract as every metric here —
+// NEVER a false 0.0 masquerading as a real (broken) score, and never a number
+// quietly computed over a window that could not produce one.
 /** First-pass default, same "documented heuristic, not derived from data we
  *  don't have" spirit as health.ts's own 10%-hash-fallback threshold below.
  *  Tunable later if a real fleet shows this is too loud/quiet. */
@@ -13604,17 +14088,108 @@ export const QUALITY_HASH_FALLBACK_DEGRADED_PCT = 10;
  *  "first-pass default, tunable later" spirit as the thresholds above. */
 export const QUALITY_RECALL_SAMPLE_SIZE = 10;
 export const QUALITY_RECALL_K = 5;
+/**
+ * Fields the recall spot-check and the quality-snapshot lookup actually
+ * read. Harper REST `select(...)` (same syntax adk-flair-js's listMemories
+ * already uses) projects these server-side so the nightly sweep never
+ * pulls embedding vectors inline — the defect in flair#1360 was an
+ * unfiltered `GET /Memory?agentId=…` that returned every row's 768-d
+ * vector (~66 MB × 2 per `--emit` run on a 3k-row store) just to sample
+ * 10 memories. `type` is intentionally omitted: it is not a declared
+ * Memory column (see schemas/memory.graphql); snapshot exclusion keys
+ * off `subject` (`quality-snapshot/…`).
+ */
+export const QUALITY_MEMORY_LIST_SELECT = ["id", "subject", "content", "createdAt"];
+/**
+ * Extra most-recent rows fetched beyond `sampleSize` so
+ * `planRecallSpotCheck` can drop the sweep's own quality-snapshot
+ * bookkeeping and still fill a 10-row window — without scanning the
+ * table. Nightly `--emit` writes one snapshot per run; 16 is a buffer
+ * for a few extra `--emit`s in the same recency window, not a second
+ * full-table read.
+ */
+export const QUALITY_RECALL_SNAPSHOT_OVERFETCH = 16;
+/**
+ * Harper REST collection path for the recall spot-check's sample fetch:
+ * agent-scoped, projected (never `embedding`), recency-sorted, bounded.
+ * `limit(start,end)` is Harper's offset window — same as
+ * packages/adk-flair-js/src/memory_service.ts.
+ */
+export function qualityRecallSamplePath(agentId, sampleSize = QUALITY_RECALL_SAMPLE_SIZE) {
+    const select = QUALITY_MEMORY_LIST_SELECT.join(",");
+    const end = sampleSize + QUALITY_RECALL_SNAPSHOT_OVERFETCH;
+    return `/Memory?agentId=${encodeURIComponent(agentId)}&select(${select})&sort(-createdAt)&limit(0,${end})`;
+}
+/**
+ * Harper REST collection path for the previous quality-snapshot lookup:
+ * same projection as the sample fetch (never `embedding`). Subject is
+ * passed as a query equals (indexed) plus a client-side re-filter —
+ * Memory.search() historically did not turn bare query params into
+ * conditions beyond the signed agent scope, so the client-side filter
+ * in fetchPreviousQualitySnapshot stays as defense in depth. No `limit`:
+ * a bounded window could miss yesterday's snapshot after a busy day of
+ * writes, and without a reliable server-side subject pushdown that
+ * would silently look like a first run.
+ */
+export function qualitySnapshotLookupPath(agentId, subject) {
+    const select = QUALITY_MEMORY_LIST_SELECT.join(",");
+    return `/Memory?agentId=${encodeURIComponent(agentId)}&subject=${encodeURIComponent(subject)}&select(${select})&sort(-createdAt)`;
+}
+/** Leading-word cap on the content-derived cue. 25, matching the arm of the
+ *  flair#967 A/B that was actually measured (same 10 memories, same instance,
+ *  same minute: subject cue → recall@5 0.60 / MRR 0.16; first-25-words-of-
+ *  content cue → 1.00 / 0.78). Still a PARTIAL cue by construction — capped,
+ *  never the whole memory for anything longer than the cap. */
+const RECALL_CUE_CONTENT_WORD_LIMIT = 25;
+/**
+ * Is `subject` DISCRIMINATIVE enough to be handed to semantic search as a
+ * query in its own right? (flair#967.)
+ *
+ * The old bar was `length >= 3`, which is a check on whether the subject
+ * EXISTS, not on whether it is a query. Measured consequence: slug-shaped
+ * subjects — `pr-1359`, `kern-2026-08-23`, the spot-check's own
+ * `quality-snapshot/127.0.0.1:9926` — carry almost no semantic signal, so
+ * searching one is a query for nothing in particular (searching `pr-1359` on
+ * rockit production returned, as top-1, a review note about PR #1275 from five
+ * days earlier). Worse, every memory sharing such a subject issues the
+ * IDENTICAL query and gets the IDENTICAL result list, so siblings must
+ * mutually displace each other and all but one are scored as misses no matter
+ * how healthy retrieval is.
+ *
+ * The rule, stated plainly — a subject is used as the cue only when it is:
+ *   1. at least 3 characters (the original bar, kept), AND
+ *   2. NOT opaque-identifier-shaped: an unspaced token carrying a digit or an
+ *      identifier separator (`/ : _ . # @ \`) is a slug, not a phrase.
+ *      Whitespace is the primary discriminator — `Harper 5.2 upgrade` is
+ *      prose and stays a cue; `kern-2026-08-23` is not. A bare hyphen does
+ *      NOT make a slug, so ordinary compounds (`two-gate`) survive, AND
+ *   3. carrying at least one alphabetic run of 3+ characters — a subject with
+ *      no word in it (`---`, `42`) is not a query either.
+ *
+ * Fails CLOSED: anything that isn't clearly a phrase falls back to content,
+ * which the A/B measured as the strictly better cue. Pure — no I/O.
+ */
+export function isDiscriminativeSubject(subject) {
+    const s = (subject ?? "").trim();
+    if (s.length < 3)
+        return false;
+    if (!/\s/.test(s) && /[0-9/:_.#@\\]/.test(s))
+        return false;
+    if (!/[A-Za-z]{3}/.test(s))
+        return false;
+    return true;
+}
 /**
  * Derive a PARTIAL search cue from a memory — used by the recall spot-check
  * (Slice 1d) to query for a memory without handing back its full content.
- * Prefers `subject` when present and non-trivial (a real word or phrase, not
- * empty/whitespace-only padding); otherwise falls back to the first sentence
- * of `content`, capped to the leading ~8 words so the cue stays a genuine
+ * Prefers `subject` ONLY when it is discriminative (isDiscriminativeSubject
+ * above — flair#967); otherwise falls back to the first sentence of
+ * `content`, capped to the leading ~25 words so the cue stays a genuine
  * partial cue rather than the whole memory. Pure — no I/O.
  */
 export function deriveRecallCue(memory) {
     const subject = (memory.subject ?? "").trim();
-    if (subject.length >= 3)
+    if (isDiscriminativeSubject(subject))
         return subject;
     const content = (memory.content ?? "").trim();
     if (!content)
@@ -13622,7 +14197,7 @@ export function deriveRecallCue(memory) {
     const sentenceMatch = content.match(/^[^.!?\n]+[.!?]?/);
     const firstSentence = (sentenceMatch ? sentenceMatch[0] : content).trim();
     const words = firstSentence.split(/\s+/).filter(Boolean);
-    const cueWordLimit = 8;
+    const cueWordLimit = RECALL_CUE_CONTENT_WORD_LIMIT;
     return words.length <= cueWordLimit ? firstSentence : words.slice(0, cueWordLimit).join(" ");
 }
 /**
@@ -13659,6 +14234,71 @@ export function computeRecallSpotCheck(sampledIds, perQueryResultIds, k) {
         k,
     };
 }
+/** Rows the spot-check writes itself, and therefore must never grade itself
+ *  on — see RecallSpotCheckPlan['excludedSnapshotRows']. */
+function isQualitySnapshotRow(m) {
+    return m?.type === "quality-snapshot" || (m?.subject ?? "").startsWith("quality-snapshot/");
+}
+/**
+ * Pure planner for the recall spot-check: raw memory rows → the window to
+ * query (id + cue) plus that window's health. Extracted from
+ * fetchRecallSpotCheckData so the sampling, cue-derivation and
+ * fail-closed health rules are testable without any I/O (flair#967).
+ *
+ * Order of operations, and why:
+ *  1. drop the tool's own quality-snapshot rows (never grade your own
+ *     bookkeeping);
+ *  2. take the `sampleSize` most-recently-written remaining rows (unchanged —
+ *     recency is still the sampling frame; see the issue's direction 3 for the
+ *     stratified-sampling follow-up this deliberately does NOT take on);
+ *  3. derive each cue via deriveRecallCue;
+ *  4. judge the window: any duplicate cue, or any empty cue, makes it
+ *     UNSCORABLE — reported as unhealthy, never silently scored.
+ */
+export function planRecallSpotCheck(memories, opts = {}) {
+    const sampleSize = opts.sampleSize ?? QUALITY_RECALL_SAMPLE_SIZE;
+    const rows = Array.isArray(memories) ? memories : [];
+    const scorable = rows.filter((m) => !isQualitySnapshotRow(m ?? {}));
+    const excludedSnapshotRows = rows.length - scorable.length;
+    const sorted = scorable.slice().sort((a, b) => {
+        const ta = a?.createdAt ? new Date(a.createdAt).getTime() : 0;
+        const tb = b?.createdAt ? new Date(b.createdAt).getTime() : 0;
+        return tb - ta;
+    });
+    const sampled = sorted.slice(0, sampleSize).map((m) => ({ id: String(m?.id), cue: deriveRecallCue(m ?? {}) }));
+    const counts = new Map();
+    let emptyCueCount = 0;
+    for (const s of sampled) {
+        if (!s.cue) {
+            emptyCueCount += 1;
+            continue;
+        }
+        counts.set(s.cue, (counts.get(s.cue) ?? 0) + 1);
+    }
+    const duplicateCues = [...counts.entries()].filter(([, n]) => n > 1).map(([cue]) => cue);
+    if (duplicateCues.length === 0 && emptyCueCount === 0) {
+        return { sampled, health: { healthy: true }, excludedSnapshotRows };
+    }
+    const parts = [];
+    if (duplicateCues.length > 0) {
+        const shown = duplicateCues.slice(0, 3).map((c) => `"${c.length > 60 ? `${c.slice(0, 57)}...` : c}"`).join(", ");
+        const dupMemberCount = duplicateCues.reduce((n, c) => n + (counts.get(c) ?? 0), 0);
+        parts.push(`${dupMemberCount} of the ${sampled.length} sampled memories derive the same cue as another (${shown}${duplicateCues.length > 3 ? `, +${duplicateCues.length - 3} more` : ""}) — identical cues are one query with one result list, so those memories must displace each other and cannot all be found`);
+    }
+    if (emptyCueCount > 0) {
+        parts.push(`${emptyCueCount} of the ${sampled.length} sampled memories have no derivable cue (no subject and no content)`);
+    }
+    return {
+        sampled,
+        health: {
+            healthy: false,
+            reason: `sample unhealthy — ${parts.join("; ")}. No score recorded for this run (flair#967: fail closed rather than publish an unscorable number).`,
+            duplicateCues,
+            emptyCueCount,
+        },
+        excludedSnapshotRows,
+    };
+}
 /**
  * Pure computation: /HealthDetail response (+ reachability) → quality report.
  * Never throws — every missing data source degrades to a null section + a
@@ -13856,50 +14496,55 @@ export function computeQualityReport(healthy, healthData, opts = {}) {
  * `agentId`'s own memories and, for each, search for a cue derived from it.
  * Reuses the EXACT read path `flair memory search` / `flair memory list`
  * use — `api()` (→ authedRequest's 5-tier resolver) for both the
- * `GET /Memory?agentId=...` sample fetch and the `POST /SemanticSearch`
- * queries — so this has zero new endpoint and zero new auth mechanism; it
- * is scoped to `agentId`'s own memories exactly as those commands already
- * are. Never throws: every failure mode (no agentId, fewer than
- * `sampleSize` memories, a fetch/search error) returns `{ ok: false,
- * skipReason }` for computeQualityReport to turn into a `gaps` entry.
+ * projected, bounded `GET /Memory?…&select(…)&limit(…)` sample fetch
+ * (flair#1360 — never the unfiltered collection with embeddings inline)
+ * and the `POST /SemanticSearch` queries — so this has zero new endpoint
+ * and zero new auth mechanism; it is scoped to `agentId`'s own memories
+ * exactly as those commands already are. Never throws: every failure mode
+ * (no agentId, fewer than `sampleSize` memories, a fetch/search error)
+ * returns `{ ok: false, skipReason }` for computeQualityReport to turn
+ * into a `gaps` entry.
  */
-async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
+export async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
     const sampleSize = opts.sampleSize ?? QUALITY_RECALL_SAMPLE_SIZE;
     const k = opts.k ?? QUALITY_RECALL_K;
+    const request = opts.request ?? api;
     if (!agentId) {
         return { ok: false, skipReason: "no agent identity to query as — pass --agent or set FLAIR_AGENT_ID" };
     }
     let all;
     try {
-        const q = new URLSearchParams({ agentId }).toString();
-        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl, agentId });
+        const raw = await request("GET", qualityRecallSamplePath(agentId, sampleSize), undefined, { baseUrl, agentId });
         all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
     }
     catch (err) {
         return { ok: false, agentId, skipReason: `could not fetch memories to sample: ${err?.message ?? String(err)}` };
     }
-    if (all.length < sampleSize) {
+    // Deterministic sample + cue derivation + fail-closed health judgment, all
+    // pure (planRecallSpotCheck above). Snapshot rows are excluded there, so the
+    // "enough memories" check has to run on the PLANNED window, not on the raw
+    // row count — an instance whose recent writes are mostly the sweep's own
+    // bookkeeping should skip with a reason, not score a short window.
+    const plan = planRecallSpotCheck(all, { sampleSize });
+    if (plan.sampled.length < sampleSize) {
+        const excluded = plan.excludedSnapshotRows > 0 ? ` (${plan.excludedSnapshotRows} quality-snapshot row(s) excluded — the spot-check never grades its own bookkeeping)` : "";
         return {
             ok: false,
             agentId,
-            skipReason: `agent '${agentId}' has ${all.length} memories, fewer than the ${sampleSize} needed to sample`,
+            skipReason: `agent '${agentId}' has ${plan.sampled.length} scorable memories, fewer than the ${sampleSize} needed to sample${excluded}`,
         };
     }
-    // Deterministic sample: the sampleSize most-recently-written memories.
-    const sorted = all.slice().sort((a, b) => {
-        const ta = a.createdAt ? new Date(a.createdAt).getTime() : 0;
-        const tb = b.createdAt ? new Date(b.createdAt).getTime() : 0;
-        return tb - ta;
-    });
-    const sampled = sorted.slice(0, sampleSize);
+    // flair#967: a window whose cues collide cannot be scored fairly — report
+    // that fact instead of a number, and don't spend the searches either.
+    if (!plan.health.healthy) {
+        return { ok: false, agentId, skipReason: plan.health.reason, sampleHealth: plan.health };
+    }
     const sampledIds = [];
     const perQueryResultIds = [];
     try {
-        for (const m of sampled) {
-            const id = String(m.id);
-            const cue = deriveRecallCue(m);
+        for (const { id, cue } of plan.sampled) {
             const body = { agentId, q: cue, limit: k };
-            const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId });
+            const res = await request("POST", "/SemanticSearch", body, { baseUrl, agentId });
             const results = Array.isArray(res) ? res : (res?.results ?? []);
             sampledIds.push(id);
             perQueryResultIds.push(results.map((r) => String(r.id)));
@@ -13908,7 +14553,7 @@ async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
     catch (err) {
         return { ok: false, agentId, skipReason: `recall spot-check search failed: ${err?.message ?? String(err)}` };
     }
-    return { ok: true, agentId, sampledIds, perQueryResultIds, k };
+    return { ok: true, agentId, sampledIds, perQueryResultIds, k, sampleHealth: plan.health };
 }
 // ─── flair quality --emit (Slice 2 of the memory-quality-observability arc:
 // quality OrgEvents) ─────────────────────────────────────────────────────────
@@ -13958,6 +14603,22 @@ async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
 export const QUALITY_EVENT_COVERAGE_ABS_THRESHOLD_PCT = 90;
 export const QUALITY_EVENT_COVERAGE_DROP_THRESHOLD_PCT = 5;
 export const QUALITY_EVENT_STALENESS_ABS_THRESHOLD_PCT = 10;
+/**
+ * RETAINED AT ITS ORIGINAL VALUE AND DELIBERATELY UNWIRED (flair#967).
+ *
+ * Nothing in diffQualitySnapshots reads this any more — the recall spot-check
+ * is report-only and emits no event at any delta (see the Slice 1d framing in
+ * the module doc for the 32-run σ = 0.291 / precision-0 measurement behind
+ * that). The constant stays, unchanged at 0.2, as the standing evidence that
+ * the fix was "remove alerting authority from a metric that never earned it",
+ * NOT "widen the gate until it stops talking" — a silenced check and a
+ * de-authorised one look identical in a changelog and are opposites in
+ * practice, and 0.2 sitting here at 0.69σ is the arithmetic that makes the
+ * difference legible. If this probe is ever re-armed, the replacement
+ * threshold must be DERIVED from the measured run-to-run variance of the
+ * FIXED cue derivation, not typed in — do not just re-reference this literal.
+ * Asserted unchanged by test/unit/quality-recall-spotcheck-967.test.ts.
+ */
 export const QUALITY_EVENT_RECALL_DROP_THRESHOLD = 0.2;
 export const QUALITY_EVENT_DEDUP_GROWTH_PCT_THRESHOLD = 0.5; // >50%
 export const QUALITY_EVENT_DEDUP_GROWTH_ABS_THRESHOLD = 5; // AND by >= 5 clusters
@@ -14024,29 +14685,30 @@ export function diffQualitySnapshots(current, previous) {
             });
         }
     }
-    // ── recall spot-check: recall@k and MRR, same delta-drop threshold ──
-    if (current.recallSpotCheck && previous.recallSpotCheck) {
-        const beforeR = previous.recallSpotCheck.recallAtK;
-        const afterR = current.recallSpotCheck.recallAtK;
-        if (beforeR - afterR > QUALITY_EVENT_RECALL_DROP_THRESHOLD) {
-            findings.push({
-                kind: "quality.regression",
-                scope: "quality",
-                summary: `recall spot-check recall@k dropped from ${beforeR} to ${afterR} since last snapshot`,
-                detail: { metric: "recallSpotCheck.recallAtK", before: beforeR, after: afterR, threshold: QUALITY_EVENT_RECALL_DROP_THRESHOLD },
-            });
-        }
-        const beforeM = previous.recallSpotCheck.mrr;
-        const afterM = current.recallSpotCheck.mrr;
-        if (beforeM - afterM > QUALITY_EVENT_RECALL_DROP_THRESHOLD) {
-            findings.push({
-                kind: "quality.regression",
-                scope: "quality",
-                summary: `recall spot-check MRR dropped from ${beforeM} to ${afterM} since last snapshot`,
-                detail: { metric: "recallSpotCheck.mrr", before: beforeM, after: afterM, threshold: QUALITY_EVENT_RECALL_DROP_THRESHOLD },
-            });
-        }
-    }
+    // ── recall spot-check: REPORT-ONLY, no branch here on purpose (flair#967) ──
+    //
+    // This metric used to emit two quality.regression events (recall@k and MRR,
+    // both at QUALITY_EVENT_RECALL_DROP_THRESHOLD). It no longer emits anything,
+    // at any delta. Measured, on rockit production:
+    //
+    //   32 nightly runs · population σ 0.291 · mean |run-to-run delta| 0.223
+    //   threshold 0.2  →  0.69σ, i.e. BELOW the metric's own noise floor
+    //   6 findings-mails in 34 runs, replay-predicted 6/6 from these branches,
+    //   all 6 oscillation  →  lifetime precision 0
+    //
+    // Removing an emission is not the same move as raising a threshold, and the
+    // distinction is the whole point: raising 0.2 would leave a check that still
+    // claims to detect recall regressions while detecting none, whereas this
+    // hands that job to the instrument that can actually do it — the
+    // deterministic, fixed-label, CI-gated eval in
+    // test/integration-heavy/recall-eval-gate.test.ts (test/bench/recall-eval),
+    // whose floors sit ≥2 whole queries below the measured value against a
+    // 0.000 noise band. QUALITY_EVENT_RECALL_DROP_THRESHOLD is left at 0.2,
+    // unwired, so that stays checkable rather than asserted.
+    //
+    // current.recallSpotCheck / previous.recallSpotCheck are still SNAPSHOTTED
+    // (buildQualitySnapshot above) — the history that made this diagnosis
+    // possible keeps accumulating, and `flair quality` still prints the number.
     // ── quiet agents: per-agent, NEWLY quiet only (was false last snapshot,
     // true now) — never re-fires for an agent that was already quiet last
     // snapshot, and never fires for an agent absent from the previous snapshot
@@ -14100,21 +14762,23 @@ export function qualitySnapshotSubject(baseUrl) {
     return `quality-snapshot/${host}`;
 }
 /** Fetch the most recent prior quality snapshot for `agentId` at `baseUrl`,
- *  via the exact same read path fetchRecallSpotCheckData uses (`api("GET",
- *  "/Memory?agentId=...")`, self-scoped by the signed request's own agent
- *  identity — no new endpoint). Filters client-side by subject (the server's
- *  `GET /Memory?...` doesn't translate query params into search conditions
- *  beyond the signed agentId scope — see resources/Memory.ts's search()),
- *  same client-side-filter pattern `memory list --hash-fallback` already
- *  uses. Returns null on: no prior snapshot, a fetch error, or a snapshot row
- *  whose content isn't parseable/versioned JSON (never throws — a corrupt or
- *  foreign row degrades to "no snapshot", same as a genuine first run, rather
- *  than crashing `--emit`). */
-async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject) {
+ *  via the same signed `GET /Memory` read path fetchRecallSpotCheckData
+ *  uses (self-scoped by the signed request's own agent identity — no new
+ *  endpoint). Projects the same fields (never embeddings — flair#1360) and
+ *  asks for `subject` as a query equals; still filters client-side by
+ *  subject because Memory.search() historically did not turn bare query
+ *  params into search conditions beyond the signed agentId scope (see
+ *  resources/Memory.ts's search()), same client-side-filter pattern
+ *  `memory list --hash-fallback` already uses. Returns null on: no prior
+ *  snapshot, a fetch error, or a snapshot row whose content isn't
+ *  parseable/versioned JSON (never throws — a corrupt or foreign row
+ *  degrades to "no snapshot", same as a genuine first run, rather than
+ *  crashing `--emit`). */
+export async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject, opts = {}) {
+    const request = opts.request ?? api;
     let all;
     try {
-        const q = new URLSearchParams({ agentId }).toString();
-        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl, agentId });
+        const raw = await request("GET", qualitySnapshotLookupPath(agentId, subject), undefined, { baseUrl, agentId });
         all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
     }
     catch {
@@ -14226,6 +14890,12 @@ program
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         const out = { healthy, url: baseUrl, flairVersion: __pkgVersion, ...report };
+        // flair#967: when a window was assembled, say whether it was scorable —
+        // structurally, not only as prose inside a `gaps` reason. An unhealthy
+        // sample is a FACT ABOUT THE RUN that a consumer must be able to read
+        // without string-matching.
+        if (recallSpotCheckData.sampleHealth)
+            out.recallSampleHealth = recallSpotCheckData.sampleHealth;
         if (emitResult) {
             out.emit = { firstRun: emitResult.firstRun, snapshotId: emitResult.snapshotId, errors: emitResult.errors };
             out.emittedEvents = emitResult.emittedEvents.map((e) => ({
@@ -14339,15 +15009,15 @@ program
         console.log(render.kv("Clusters", `${render.wrap(render.c.bold, String(dc.clusterCount))} ${render.wrap(render.c.dim, `(${dc.totalMemoriesInClusters} memories, largest cluster ${dc.largestClusterSize})`)}`));
         console.log(`  ${render.wrap(render.c.dim, "an ops signal — near-duplicate memories piling up, not a trust judgment")}`);
     }
-    // Recall spot-check (flair-quality Slice 1d) — a health SPOT-CHECK, not
-    // a benchmark or trust judgment: catches recall cratering (embeddings/
-    // index down), not a quality grade. See QualityReport['recallSpotCheck']
-    // doc for the full framing.
+    // Recall spot-check (flair-quality Slice 1d) — a REPORT-ONLY health
+    // spot-check: not a benchmark, not a trust judgment, and since flair#967
+    // not an alerting signal either. See QualityReport['recallSpotCheck'] doc
+    // and the Slice 1d module doc for the full framing.
     if (report.recallSpotCheck) {
         const rc = report.recallSpotCheck;
-        console.log(`\n${render.wrap(render.c.bold, "Recall spot-check")} ${render.wrap(render.c.dim, `(agent ${rc.agentId ?? "—"}, health signal — not a benchmark)`)}`);
+        console.log(`\n${render.wrap(render.c.bold, "Recall spot-check")} ${render.wrap(render.c.dim, `(agent ${rc.agentId ?? "—"}, report-only — not a benchmark, not an alert)`)}`);
         console.log(render.kv(`recall@${rc.k}`, `${render.wrap(render.c.bold, rc.recallAtK.toFixed(2))} ${render.wrap(render.c.dim, `(MRR ${rc.mrr.toFixed(2)}, ${rc.sampleSize} sampled)`)}`));
-        console.log(`  ${render.wrap(render.c.dim, "catches recall cratering (embeddings/index down) — a high score means recall is functioning, not that it's optimal")}`);
+        console.log(`  ${render.wrap(render.c.dim, "observability only — recall REGRESSIONS are detected by the deterministic CI gate (test/bench/recall-eval), not by this number")}`);
     }
     // Gaps
     if (report.gaps.length > 0) {
@@ -14576,9 +15246,8 @@ function parseEntitiesOptionOrExit(csv) {
 }
 const ENTITIES_OPTION_DESCRIPTION = "Comma-separated entity vocabulary strings this record touches (type:value from the closed type set, e.g. repo:tpsdev-ai/flair — see docs/entity-vocabulary.md; feeds `flair attention`)";
 const memory = program.command("memory").description("Manage agent memories");
-memory.command("add [content]")
-    .description("Write a new memory row for an agent (content via positional arg or --content)")
-    .requiredOption("--agent <id>")
+addSharedCredentialOptions(addSharedIdentityOption(memory.command("add [content]")
+    .description("Write a new memory row for an agent (content via positional arg or --content)")))
     .option("--content <text>", "memory content (alias for positional arg)")
     .option("--durability <d>", "permanent|persistent|standard|ephemeral (default standard). Also decides the default visibility when --visibility is omitted: permanent/persistent -> shared, standard/ephemeral -> private").option("--tags <csv>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content)")
@@ -14592,10 +15261,15 @@ memory.command("add [content]")
         console.error("error: content required (positional arg or --content)");
         process.exit(1);
     }
-    const agentId = resolveSigningAgentId(opts, "memory add") ?? opts.agent;
-    const memId = `${opts.agent}-${Date.now()}`;
+    applyAdminPassFile(opts);
+    const agentId = resolveSigningAgentId(opts, "memory add");
+    if (!agentId) {
+        console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+        process.exit(2);
+    }
+    const memId = `${agentId}-${Date.now()}`;
     const body = {
-        id: memId, agentId: opts.agent, content, durability: opts.durability || "standard",
+        id: memId, agentId, content, durability: opts.durability || "standard",
         tags: opts.tags ? String(opts.tags).split(",").map((x) => x.trim()).filter(Boolean) : undefined,
         type: "memory", createdAt: new Date().toISOString(),
     };
@@ -14628,7 +15302,11 @@ memory.command("add [content]")
         if (entities.length > 0)
             body.entities = entities;
     }
-    const out = await api("PUT", `/Memory/${memId}`, body, { agentId });
+    const out = await api("PUT", `/Memory/${memId}`, body, {
+        agentId,
+        explicitAdminPass: opts.adminPass,
+        adminUser: opts.adminUser,
+    });
     console.log(JSON.stringify(out, null, 2));
 });
 // ─── flair memory write-task-summary ────────────────────────────────────────
@@ -14906,7 +15584,7 @@ memory.command("hygiene")
     const enabled = new Set((opts.pattern ?? "compact-id,test-content,tiny").split(",").map((s) => s.trim()).filter(Boolean));
     const tinyThreshold = Math.max(0, Number(opts.tinyThreshold) || 25);
     const apply = !!opts.apply;
-    const opsAuth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+    const opsAuth = `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPass}`).toString("base64")}`;
     async function ops(body) {
         const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
             method: "POST",
@@ -15874,7 +16552,14 @@ bridge
         process.exit(2);
     }
     try {
-        const result = await runRoundTrip({ descriptor: loaded.descriptor, cwd, fixturePath: opts.fixture });
+        const result = await runRoundTrip({
+            descriptor: loaded.descriptor,
+            cwd,
+            fixturePath: opts.fixture,
+            // Keep the intermediate export so a failure can print a live path.
+            // The next harness start sweeps leftovers older than a minute (flair#1032).
+            retainTmpDir: true,
+        });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
             process.exit(result.passed ? 0 : 1);
@@ -16081,31 +16766,20 @@ function printTrustError(detail) {
     }
 }
 // ─── flair backup ────────────────────────────────────────────────────────────
-program
+addSharedCredentialOptions(program
     .command("backup")
     .description("Export agents, memories, and souls to a JSON archive")
     .option("--output <path>", "Output file path (default: ~/.flair/backups/flair-backup-<timestamp>.json)")
     .option("--agents <ids>", "Comma-separated agent IDs to include (default: all)")
     .option("--port <port>", "Harper HTTP port")
-    .option("--url <url>", "Flair base URL (overrides --port)")
-    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env, or use --admin-pass-file)")
-    .option("--admin-pass-file <path>", "Read admin password from a file (e.g., ~/.flair/admin-pass). Preferred over --admin-pass for launchd/cron — keeps the secret out of ps and shell history.")
-    .action(async (opts) => {
+    .option("--url <url>", "Flair base URL (overrides --port)")).action(async (opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
-    let adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    if (!adminPass && opts.adminPassFile) {
-        // readAdminPassFileSecure refuses world/group readable files (mode 0600
-        // recommended). Common gotcha: files generated via
-        // `openssl rand -base64 24 > admin-pass` end in a newline; helper trims it.
-        try {
-            adminPass = readAdminPassFileSecure(opts.adminPassFile);
-        }
-        catch (err) {
-            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
-            process.exit(1);
-        }
-    }
-    const adminUser = DEFAULT_ADMIN_USER;
+    applyAdminPassFile(opts);
+    // Env is a second-class fallback after the explicit flags (same order
+    // backup used before the shared helper). FLAIR_ADMIN_PASS is still
+    // accepted so existing scripts keep working.
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    const adminUser = resolveAdminUser(opts.adminUser);
     if (!adminPass) {
         console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for backup");
         process.exit(1);
@@ -16194,11 +16868,12 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--dry-run", "Show what would be imported without making changes")
     .action(async (backupPath, opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    const adminUser = DEFAULT_ADMIN_USER;
+    const adminUser = resolveAdminUser(opts.adminUser);
     const dryRun = Boolean(opts.dryRun);
     const mode = opts.replace ? "replace" : "merge";
     if (!adminPass) {
@@ -16311,6 +16986,7 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Keys directory", defaultKeysDir())
     .action(async (agentId, opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
@@ -16319,7 +16995,7 @@ program
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
         process.exit(1);
     }
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     async function adminGet(path) {
         const res = await fetch(`${baseUrl}${path}`, { headers: { Authorization: auth }, signal: AbortSignal.timeout(10_000) });
         if (!res.ok)
@@ -16402,6 +17078,7 @@ program
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--ops-target <url>", "Explicit ops API URL for the Agent seed (env: FLAIR_OPS_TARGET; bypasses port derivation). Use when --url is remote and the ops port isn't HTTP-1.")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--keys-dir <dir>", "Keys directory", defaultKeysDir())
     .action(async (importPath, opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
@@ -16462,12 +17139,12 @@ program
         : nacl.sign.keyPair.fromSeed(new Uint8Array(decodedSeed.subarray(0, 32))).publicKey;
     const pubKeyB64url = b64url(pubKey);
     // Register agent via ops API (remote when --url/--ops-target points off-box)
-    await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, DEFAULT_ADMIN_USER, adminPass);
+    await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, resolveAdminUser(opts.adminUser), adminPass);
     console.log(typeof seedOpsTarget === "string"
         ? `  Agent registered (ops: ${seedOpsTarget})`
         : `  Agent registered`);
     // Restore memories
-    const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     let memCount = 0;
     for (const mem of data.memories ?? []) {
         try {
@@ -16748,7 +17425,7 @@ program
                             createdAt: new Date().toISOString(),
                         };
                         const memoryPath = `/Memory/${memoryId}`;
-                        const auth = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+                        const auth = `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPass}`).toString("base64")}`;
                         const res = await fetch(`${httpUrl}${memoryPath}`, {
                             method: "PUT",
                             headers: {
@@ -17222,7 +17899,7 @@ if (import.meta.main) {
 // ─── Exported for testing ─────────────────────────────────────────────────────
 export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, 
 // Harper's own config — the per-instance port record (flair#914)
-harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, FABRIC_OPS_PORT, 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, 
+harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, FABRIC_OPS_PORT, 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, DEFAULT_ADMIN_USER, resolveAdminUser, 
 // launchd label (flair#693)
 LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, 
 // launchd management observation (flair#1022)