@tpsdev-ai/flair 0.47.1 → 0.49.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, } 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.
@@ -1905,6 +1906,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 +1980,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 +2034,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}`);
     }
 }
@@ -2917,11 +2945,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 +3034,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 +3172,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 +3805,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 +3823,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 +3978,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 +3987,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 +4071,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 +4089,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 +4209,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 +4221,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 +4294,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");
@@ -4669,8 +4717,15 @@ hook
         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) {
@@ -5026,6 +5081,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 +5117,7 @@ mcp
             manifestPath,
             issuer,
             opsPortOrUrl: opsPort,
-            adminUser: DEFAULT_ADMIN_USER,
+            adminUser: resolveAdminUser(opts.adminUser),
             adminPass,
         });
         if (opts.json) {
@@ -5086,6 +5142,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 +5171,7 @@ mcp
             name,
             manifestPath,
             opsPortOrUrl: opsPort,
-            adminUser: DEFAULT_ADMIN_USER,
+            adminUser: resolveAdminUser(opts.adminUser),
             adminPass,
             keepKeys: !!opts.keepKeys,
         });
@@ -5205,6 +5262,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 +5322,7 @@ mcp
         idpSubject,
         principal: opts.principal,
         principalKind: opts.principalKind,
-        adminUser: DEFAULT_ADMIN_USER,
+        adminUser: resolveAdminUser(opts.adminUser),
         adminPass,
         signingKeyFilePath: opts.signingKeyFile,
         secretsMechanism,
@@ -5313,6 +5371,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 +5387,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 +5458,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 +5551,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 +5562,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 +5684,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 +5693,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 +5715,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 +5729,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 +5761,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 +5771,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 +5808,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 +5818,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 +5863,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 +5872,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 +5931,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 +5981,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 +6030,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 },
@@ -6459,6 +6527,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 +6605,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 +6642,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 +6657,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 +6762,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;
@@ -6940,6 +7010,7 @@ const federationSync = federation
     .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("--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 (env: FLAIR_TARGET)")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
@@ -7140,6 +7211,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 +8738,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 +8790,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 +9285,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 +11828,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 +11926,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 +12014,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 +12052,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 +12062,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 +12072,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 +12743,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 +12835,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 +12914,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 + the SessionStart hook
+    // (Claude Code only, since only Claude Code has those mechanisms). 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,
@@ -12870,6 +12952,170 @@ 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;
@@ -13573,23 +13819,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 +13869,61 @@ 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;
+/** 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 +13931,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 +13968,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
@@ -13878,26 +14252,29 @@ async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
     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 results = Array.isArray(res) ? res : (res?.results ?? []);
@@ -13908,7 +14285,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 +14335,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 +14417,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
@@ -14226,6 +14620,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 +14739,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) {
@@ -14906,7 +15306,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",
@@ -16090,6 +16490,7 @@ program
     .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.")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .action(async (opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     let adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
@@ -16105,7 +16506,7 @@ program
             process.exit(1);
         }
     }
-    const adminUser = DEFAULT_ADMIN_USER;
+    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 +16595,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 +16713,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 +16722,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 +16805,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 +16866,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 +17152,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 +17626,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)