@tpsdev-ai/flair 0.52.0 → 0.54.1

package/dist/fleet-verify.js

@@ -38,40 +38,128 @@
  * authenticated version check, same Fabric admin Basic-auth credentials as
  * the origin — a Fabric cluster shares one admin realm). A peer with no
  * usable endpoint is reported "unverifiable" — never silently dropped, never
- * printed green. See classifyNode()'s "method" field: "direct" (we actually
- * hit it) vs "none" (we could not attempt a check at all, and say why).
+ * printed green, and does not fail the run (flair#988). A reachable peer
+ * verified on the wrong version still fails as diverged. See classifyNode()'s
+ * "method" field: "direct" (we actually hit it) vs "none" (we could not
+ * attempt a check at all, and say why).
  */
 import { probeInstance } from "./probe.js";
 import * as render from "./render.js";
 // ─── Exit codes (documented in `flair fleet verify --help`) ─────────────────
-/** All nodes verified: healthy, authenticated, and version-matched. */
+//
+// Three operator-facing states (flair#988). UNVERIFIABLE (couldn't check)
+// must never share an exit with DIVERGED (probed, verified wrong):
+//
+//   1. All probed nodes OK, none diverged → 0 "converged."
+//      Unverifiable peers are listed + warned; they do NOT fail the run.
+//   2. Any reachable node DIVERGED (wrong version) → non-zero
+//      "NOT converged — <node> diverged."
+//   3. Some peers UNVERIFIABLE, none diverged → 0 + WARNING
+//      (same exit as (1); a distinct warning exit would also be fine as
+//      long as it is not (2)'s code).
+//
+// Exit 3 remains for a reachable peer we *attempted* to probe (unreachable
+// / auth-failed). That is a failed check, not "no endpoint on file."
+/** All probed nodes verified. Unverifiable peers warn but do not fail (flair#988). */
 export const FLEET_EXIT_OK = 0;
 /** Origin failed — unreachable, unauthenticated, or running the wrong version. Worst case: the cluster's entrypoint itself is broken. */
 export const FLEET_EXIT_ORIGIN_FAILED = 1;
-/** Origin is fine, but at least one reachable peer is running a DIFFERENT version — a mixed-version fleet (the #638 scenario). */
+/** Origin is fine, but at least one reachable peer is running a DIFFERENT version — a mixed-version fleet (the #638 scenario). This is DIVERGED. */
 export const FLEET_EXIT_PEER_SKEW = 2;
-/** Origin is fine, no version skew among reachable peers, but at least one peer could not be verified at all (unreachable, auth rejected, or no endpoint on file). */
+/** Origin is fine, no version skew among reachable peers, but a reachable peer we attempted to probe was unreachable or rejected auth. */
 export const FLEET_EXIT_PEER_UNREACHABLE = 3;
 export const FLEET_EXIT_DESCRIPTIONS = {
-    [FLEET_EXIT_OK]: "all nodes verified: healthy, authenticated, version-matched",
+    [FLEET_EXIT_OK]: "all probed nodes verified (unverifiable peers are listed as a warning and do not fail)",
     [FLEET_EXIT_ORIGIN_FAILED]: "origin failed (unreachable, unauthenticated, or wrong version)",
-    [FLEET_EXIT_PEER_SKEW]: "origin OK, but a reachable peer is running a DIFFERENT version (skew)",
-    [FLEET_EXIT_PEER_UNREACHABLE]: "origin OK, no skew among reachable peers, but a peer could not be verified at all (unreachable, auth rejected, or no endpoint on file)",
+    [FLEET_EXIT_PEER_SKEW]: "origin OK, but a reachable peer diverged (wrong version)",
+    [FLEET_EXIT_PEER_UNREACHABLE]: "origin OK, no skew among reachable peers, but a reachable peer was unreachable or rejected auth",
 };
+function isDivergedStatus(status) {
+    return status === "skew";
+}
+function isCheckFailedStatus(status) {
+    return status === "unreachable" || status === "auth-failed";
+}
+function formatUnverifiableWarning(unverifiableCount, verifiableCount) {
+    return (`${unverifiableCount} peer(s) unverifiable — could not check (no endpoint); ` +
+        `converged among the ${verifiableCount} verifiable node(s).`);
+}
+/**
+ * Separate "couldn't check" from "verified wrong" (flair#988).
+ * Single source of truth for exit code + operator sentences. Unverifiable
+ * peers never fail the run; a reachable skew still does.
+ */
+export function describeFleetSweep(origin, peers) {
+    const unverifiable = peers.filter((p) => p.status === "unverifiable");
+    const verifiableOk = [origin, ...peers].filter((p) => p.status === "ok");
+    const divergedNodes = [origin, ...peers].filter((p) => isDivergedStatus(p.status));
+    const warning = unverifiable.length > 0
+        ? formatUnverifiableWarning(unverifiable.length, verifiableOk.length)
+        : null;
+    if (origin.status !== "ok" && !isDivergedStatus(origin.status)) {
+        return {
+            kind: "check-failed",
+            exitCode: FLEET_EXIT_ORIGIN_FAILED,
+            diverged: false,
+            divergedNodeId: null,
+            unverifiableCount: unverifiable.length,
+            verifiableCount: verifiableOk.length,
+            summary: `origin ${origin.status} — could not complete check.`,
+            warning,
+        };
+    }
+    if (divergedNodes.length > 0) {
+        const node = divergedNodes[0];
+        return {
+            kind: "diverged",
+            exitCode: origin.status !== "ok" ? FLEET_EXIT_ORIGIN_FAILED : FLEET_EXIT_PEER_SKEW,
+            diverged: true,
+            divergedNodeId: node.id,
+            unverifiableCount: unverifiable.length,
+            verifiableCount: verifiableOk.length,
+            summary: `NOT converged — ${node.id} diverged.`,
+            warning,
+        };
+    }
+    const checkFailedPeer = peers.find((p) => isCheckFailedStatus(p.status));
+    if (checkFailedPeer) {
+        return {
+            kind: "check-failed",
+            exitCode: FLEET_EXIT_PEER_UNREACHABLE,
+            diverged: false,
+            divergedNodeId: null,
+            unverifiableCount: unverifiable.length,
+            verifiableCount: verifiableOk.length,
+            summary: `peer ${checkFailedPeer.id} ${checkFailedPeer.status} — could not complete check.`,
+            warning,
+        };
+    }
+    return {
+        kind: "converged",
+        exitCode: FLEET_EXIT_OK,
+        diverged: false,
+        divergedNodeId: null,
+        unverifiableCount: unverifiable.length,
+        verifiableCount: verifiableOk.length,
+        summary: "converged.",
+        warning,
+    };
+}
 /**
- * Priority order when multiple problems exist at once: an origin failure
- * always wins (nothing downstream matters if the entrypoint is broken), then
- * skew (a real mixed-version fleet), then unreachable/unverifiable (we
- * genuinely don't know that node's state).
+ * Priority: origin failure, then reachable skew (DIVERGED), then a reachable
+ * peer we attempted and could not complete (unreachable / auth-failed).
+ * Unverifiable peers (no endpoint, never paired) do not fail the run.
  */
 export function decideFleetExitCode(origin, peers) {
-    if (origin.status !== "ok")
-        return FLEET_EXIT_ORIGIN_FAILED;
-    if (peers.some((p) => p.status === "skew"))
-        return FLEET_EXIT_PEER_SKEW;
-    if (peers.some((p) => p.status !== "ok"))
-        return FLEET_EXIT_PEER_UNREACHABLE;
-    return FLEET_EXIT_OK;
+    return describeFleetSweep(origin, peers).exitCode;
+}
+/**
+ * Whether `flair deploy` / `flair upgrade --target` should abort after the
+ * sweep. Unverifiable-only is not a failure — that was the #988 bug: every
+ * non-OK used to print "deploy is NOT fully converged."
+ */
+export function fleetSweepShouldAbort(verdict) {
+    return verdict.exitCode !== FLEET_EXIT_OK;
 }
 // ─── Pure decision logic: ProbeResult → FleetNodeResult ─────────────────────
 /**
@@ -241,8 +329,17 @@ export async function sweepFleet(opts, injected) {
             detail: `GET /FederationPeers on the origin failed: ${peerEnumerationError} — fleet coverage unknown, cannot confirm every peer was even considered`,
         });
     }
-    const exitCode = decideFleetExitCode(origin, peers);
-    return { target: opts.target, expectVersion, expectVersionSource, origin, peers, peerEnumerationError, exitCode };
+    const verdict = describeFleetSweep(origin, peers);
+    return {
+        target: opts.target,
+        expectVersion,
+        expectVersionSource,
+        origin,
+        peers,
+        peerEnumerationError,
+        exitCode: verdict.exitCode,
+        verdict,
+    };
 }
 // ─── Rendering ───────────────────────────────────────────────────────────────
 const STATUS_COLOR = {
@@ -287,5 +384,31 @@ export function renderFleetSweepTable(result) {
             : "no version baseline available (origin unreachable/unauthenticated and no --expect-version given) — skew could not be checked";
     lines.push("");
     lines.push(render.wrap(render.c.dim, expectLine));
+    const verdictLines = renderFleetSweepVerdict(result.verdict);
+    if (verdictLines) {
+        lines.push("");
+        lines.push(verdictLines);
+    }
+    return lines.join("\n");
+}
+/**
+ * Operator-facing verdict after the per-node table (flair#988).
+ * Unverifiable-only → warning, never "NOT converged."
+ * A reachable skew → "NOT converged — <node> diverged."
+ */
+export function renderFleetSweepVerdict(verdict) {
+    const lines = [];
+    if (verdict.warning) {
+        lines.push(`${render.icons.warn} ${render.wrap(render.c.yellow, `WARNING ${verdict.warning}`)}`);
+    }
+    if (verdict.kind === "diverged") {
+        lines.push(`${render.icons.error} ${render.wrap(render.c.red, verdict.summary)}`);
+    }
+    else if (verdict.kind === "check-failed") {
+        lines.push(`${render.icons.error} ${render.wrap(render.c.red, verdict.summary)}`);
+    }
+    else if (!verdict.warning) {
+        lines.push(`${render.icons.ok} ${render.wrap(render.c.green, verdict.summary)}`);
+    }
     return lines.join("\n");
 }

package/dist/install/clients.js

@@ -171,6 +171,26 @@ export function appendCodexFlairBlock(raw, env) {
     const separator = raw.length === 0 ? "" : raw.endsWith("\n\n") ? "" : raw.endsWith("\n") ? "\n" : "\n\n";
     return raw + separator + tomlSnippet(env) + "\n";
 }
+/**
+ * Inverse of appendCodexFlairBlock / replaceCodexFlairBlock: drop the
+ * `[mcp_servers.flair]` table and its `[mcp_servers.flair.*]` subtables,
+ * leaving every other table untouched. Pure — callers write the result.
+ */
+export function removeCodexFlairBlock(raw) {
+    const header = "[mcp_servers.flair]";
+    const idx = raw.indexOf(header);
+    if (idx === -1)
+        return raw;
+    const before = raw.slice(0, idx);
+    const after = raw.slice(idx);
+    const nextHeader = after.slice(header.length).search(/\n\[(?!mcp_servers\.flair\.)/);
+    const rest = nextHeader === -1 ? "" : after.slice(header.length + nextHeader);
+    const restBody = rest.replace(/^\n+/, "");
+    const joined = before.replace(/\s+$/, "") + (restBody ? "\n\n" + restBody : "");
+    if (joined.trim().length === 0)
+        return "";
+    return joined.replace(/^\n+/, "").replace(/\s+$/, "\n");
+}
 /**
  * flair#1135: does the existing `[mcp_servers.flair]` TOML section carry the
  * CURRENT pinned mcpServerSpec()? Pure string scan — no TOML parser needed
@@ -657,6 +677,125 @@ function _wireCursor(env) {
 function _wireAntigravity(env) {
     return wireJsonMcp(antigravityConfigPath(), "Antigravity", env, "wiring unverified against a real agy — restart Antigravity and confirm the flair tools appear");
 }
+function displayUnderHome(configPath) {
+    const home = resolveHome();
+    return configPath.startsWith(home) ? "~" + configPath.slice(home.length) : configPath;
+}
+/**
+ * Remove `mcpServers.flair` from a JSON MCP config. Preserves sibling servers
+ * and every other top-level key. A no-op when the file or the flair entry is
+ * absent. Refuses to write when the file is not a JSON object.
+ */
+function unwireJsonMcp(configPath, label) {
+    const display = displayUnderHome(configPath);
+    if (!existsSync(configPath)) {
+        return { ok: true, removed: false, message: `${label}: no config at ${display}` };
+    }
+    try {
+        const raw = readFileSync(configPath, "utf-8").trim();
+        if (!raw) {
+            return { ok: true, removed: false, message: `${label}: no Flair MCP entry in ${display}` };
+        }
+        const config = JSON.parse(raw);
+        if (!config || typeof config !== "object" || Array.isArray(config)) {
+            return { ok: false, removed: false, message: `${label}: refusing to modify a non-object config at ${display}` };
+        }
+        const servers = config.mcpServers;
+        if (!servers || typeof servers !== "object" || Array.isArray(servers) || !("flair" in servers)) {
+            return { ok: true, removed: false, message: `${label}: no Flair MCP entry in ${display}` };
+        }
+        delete servers.flair;
+        if (Object.keys(servers).length === 0) {
+            delete config.mcpServers;
+        }
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+        return { ok: true, removed: true, message: `${label}: unwired ${display}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, removed: false, message: `${label}: could not unwire ${display}: ${reason}` };
+    }
+}
+function _unwireClaudeCode() {
+    return unwireJsonMcp(join(resolveHome(), ".claude.json"), "Claude Code");
+}
+function _unwireCodex() {
+    const path = codexConfigPath();
+    const display = "~/.codex/config.toml";
+    if (!existsSync(path)) {
+        return { ok: true, removed: false, message: `Codex: no config at ${display}` };
+    }
+    try {
+        const raw = readFileSync(path, "utf-8");
+        if (!codexConfigHasFlairSection(raw)) {
+            return { ok: true, removed: false, message: `Codex: no Flair MCP entry in ${display}` };
+        }
+        writeFileSync(path, removeCodexFlairBlock(raw));
+        return { ok: true, removed: true, message: `Codex: unwired ${display}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, removed: false, message: `Codex: could not unwire ${display}: ${reason}` };
+    }
+}
+function _unwireGemini() {
+    return unwireJsonMcp(geminiConfigPath(), "Gemini");
+}
+function _unwireCursor() {
+    return unwireJsonMcp(cursorConfigPath(), "Cursor");
+}
+function _unwireAntigravity() {
+    return unwireJsonMcp(antigravityConfigPath(), "Antigravity");
+}
+function _unwirePi() {
+    const path = piSettingsPath();
+    const display = displayUnderHome(path);
+    if (!existsSync(path)) {
+        return { ok: true, removed: false, message: `pi: no config at ${display}` };
+    }
+    try {
+        const raw = readFileSync(path, "utf-8").trim();
+        if (!raw) {
+            return { ok: true, removed: false, message: `pi: no Flair extension in ${display}` };
+        }
+        const config = JSON.parse(raw);
+        if (!config || typeof config !== "object" || Array.isArray(config)) {
+            return { ok: false, removed: false, message: `pi: refusing to modify a non-object config at ${display}` };
+        }
+        let changed = false;
+        if (Array.isArray(config.packages)) {
+            const kept = config.packages.filter((entry) => {
+                const source = piPackageEntrySource(entry);
+                return !(source && isPiFlairNpmSource(source));
+            });
+            if (kept.length !== config.packages.length) {
+                config.packages = kept;
+                changed = true;
+            }
+        }
+        if (Array.isArray(config.extensions)) {
+            const kept = config.extensions.filter((entry) => {
+                if (typeof entry === "string" && (isPiFlairNpmSource(entry) || isPiFlairExtensionPath(entry))) {
+                    return false;
+                }
+                return true;
+            });
+            if (kept.length !== config.extensions.length) {
+                config.extensions = kept;
+                changed = true;
+            }
+        }
+        if (!changed) {
+            return { ok: true, removed: false, message: `pi: no Flair extension in ${display}` };
+        }
+        writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+        return { ok: true, removed: true, message: `pi: unwired ${display}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, removed: false, message: `pi: could not unwire ${display}: ${reason}` };
+    }
+}
 // ---- Exported detection & wiring array ------------------------------------------
 export const ALL_CLIENTS = [
     {
@@ -665,6 +804,7 @@ export const ALL_CLIENTS = [
         bin: "claude",
         kind: "mcp",
         wire: _wireClaudeCode,
+        unwire: _unwireClaudeCode,
     },
     {
         id: "codex",
@@ -672,6 +812,7 @@ export const ALL_CLIENTS = [
         bin: "codex",
         kind: "mcp",
         wire: _wireCodex,
+        unwire: _unwireCodex,
     },
     {
         id: "gemini",
@@ -679,6 +820,7 @@ export const ALL_CLIENTS = [
         bin: "gemini",
         kind: "mcp",
         wire: _wireGemini,
+        unwire: _unwireGemini,
     },
     {
         id: "cursor",
@@ -686,6 +828,7 @@ export const ALL_CLIENTS = [
         bin: "cursor",
         kind: "mcp",
         wire: _wireCursor,
+        unwire: _unwireCursor,
     },
     {
         id: "antigravity",
@@ -694,6 +837,7 @@ export const ALL_CLIENTS = [
         bin: "agy",
         kind: "mcp",
         wire: _wireAntigravity,
+        unwire: _unwireAntigravity,
     },
     {
         id: "pi",
@@ -708,6 +852,7 @@ export const ALL_CLIENTS = [
         // a pi whose wiring is worth checking/fixing. Pure fs check, both legs.
         detect: () => detectBin("pi") || existsSync(piSettingsPath()),
         wire: _wirePi,
+        unwire: _unwirePi,
     },
 ];
 /**
@@ -800,3 +945,25 @@ export function wireAntigravity(env) {
 export function wirePi(env) {
     return _wirePi(env);
 }
+export function unwireClaudeCode() {
+    return _unwireClaudeCode();
+}
+export function unwireCodex() {
+    return _unwireCodex();
+}
+export function unwireGemini() {
+    return _unwireGemini();
+}
+export function unwireCursor() {
+    return _unwireCursor();
+}
+export function unwireAntigravity() {
+    return _unwireAntigravity();
+}
+export function unwirePi() {
+    return _unwirePi();
+}
+/** Unwire every registry client. A missing or already-clean config is a no-op. */
+export function unwireAllClients() {
+    return ALL_CLIENTS.map((client) => client.unwire());
+}

package/dist/lib/auth-resolve.js

@@ -21,9 +21,13 @@
  *      resolved `--admin-pass` flag) or `explicitKeyPath` (e.g. `--key`,
  *      paired with `agentId`). Always wins; this is the operator saying
  *      "use exactly this."
+ *   1.5 A FLAG-PINNED agent (flair#1500) — `agentIdSource === "flag"`
+ *      (`--agent X`). Signs as X BEFORE the env tier, and hard-errors if X
+ *      has no key. An explicitly named identity is never quietly replaced.
  *   2. ENV — `FLAIR_TOKEN` (Bearer) or `FLAIR_ADMIN_PASS` / `HDB_ADMIN_
  *      PASSWORD` (Basic admin auth). Ambient but still an explicit
- *      operator/CI choice.
+ *      operator/CI choice. (An ENV-pinned identity — `FLAIR_AGENT_ID` — stays
+ *      BELOW this tier; see the never-silent notice below.)
  *   3. A PINNED agent identity — `agentId` was already known (an --agent
  *      flag, FLAIR_AGENT_ID env, or an id the caller extracted from its own
  *      request body/query string) — signed with THAT agent's key via the
@@ -49,6 +53,14 @@
  * more specific failure; guessing at unrelated keys on disk in that case
  * would obscure the real error instead of explaining it (the flair#741 fix
  * #3 lesson, applied here — see `sendJsonRequest`'s 403 branch).
+ *
+ * ── Named identity vs ambient credential: never a silent substitution ────
+ * Precedence above is deliberately unchanged (flair#1504/#1507), but a caller
+ * that NAMED an identity (`--agent` or `FLAIR_AGENT_ID`) and got a different,
+ * usually more-privileged, credential is always told so on stderr — see
+ * `describeIdentityOverride`/`emitIdentityOverrideNotice` below. A named
+ * identity is never quietly upgraded to admin, and a two-explicit-flags
+ * conflict (`--admin-pass` + `--agent`) is never quiet either.
  */
 import { existsSync, readFileSync, readdirSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
@@ -419,6 +431,44 @@ export async function tryAgentKeyFloor(baseUrl, method, path, body, keysDir) {
     }
     return undefined;
 }
+/**
+ * One actionable line for a named identity that was not the signer, or `null`
+ * when the named identity itself signed (the normal, expected case). Pure and
+ * exported so the matrix is unit-testable without spawning the CLI.
+ */
+export function describeIdentityOverride(input) {
+    const { agentId, namedSource, credentialSource, adminPassEnvVar } = input;
+    const named = namedSource === "flag" ? `--agent '${agentId}'` : `FLAIR_AGENT_ID='${agentId}'`;
+    switch (credentialSource) {
+        case "flag-agent":
+        case "pinned-agent":
+        case "explicit-key":
+            // The named identity signed — nothing was overridden.
+            return null;
+        case "explicit-admin":
+            return `Warning: ${named} names an identity, but --admin-pass was also given; signing as admin. Drop --admin-pass to sign as '${agentId}'.`;
+        case "env-token":
+            return `Warning: ${named} names an identity, but FLAIR_TOKEN is set; signing with that bearer token instead. Unset FLAIR_TOKEN to sign as '${agentId}'.`;
+        case "env-admin":
+            return `Warning: ${named} names an identity, but an ambient admin password (${adminPassEnvVar ?? "FLAIR_ADMIN_PASS"}) is set; signing as admin. Unset it to sign as '${agentId}'.`;
+        case "local-admin-file":
+            return `Warning: ${named} names an identity, but no key was found for it and the local ~/.flair/admin-pass file is present; signing as admin. Add a key for '${agentId}' to sign as it.`;
+    }
+}
+// De-duplicate in one process (a command may issue several requests) so an
+// operator sees the notice once, not once per call. Tests reset it explicitly.
+const emittedIdentityOverrides = new Set();
+/** Write an override notice to stderr once per process. Injectable for tests. */
+export function emitIdentityOverrideNotice(message, write = (s) => { process.stderr.write(s); }) {
+    if (emittedIdentityOverrides.has(message))
+        return;
+    emittedIdentityOverrides.add(message);
+    write(message + "\n");
+}
+/** Test hook: forget notices already emitted in this process. */
+export function resetIdentityOverrideNotices() {
+    emittedIdentityOverrides.clear();
+}
 /**
  * The shared resolver: given a Flair REST call and whatever credential
  * material the caller already knows about, resolve auth across all 5 tiers
@@ -432,13 +482,18 @@ export async function authedRequest(method, path, body, opts) {
     // (flair#1345 — these three sites used to hardcode the literal `admin`).
     const adminUser = resolveAdminUser(opts.adminUser);
     let authHeader;
+    // Which tier supplied authHeader — drives the never-silent override notice
+    // below (see describeIdentityOverride).
+    let credSource;
     // Tier 1: explicit — caller-resolved flag material always wins.
     if (opts.explicitAdminPass) {
         authHeader = `Basic ${Buffer.from(`${adminUser}:${opts.explicitAdminPass}`).toString("base64")}`;
+        credSource = "explicit-admin";
     }
     else if (opts.explicitKeyPath && opts.agentId) {
         try {
             authHeader = buildEd25519Auth(opts.agentId, method, path, opts.explicitKeyPath);
+            credSource = "explicit-key";
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -459,15 +514,18 @@ export async function authedRequest(method, path, body, opts) {
                 `or the local admin-pass file.`);
         }
         authHeader = buildEd25519Auth(opts.agentId, method, path, keyPath);
+        credSource = "flag-agent";
     }
     // Tier 2: env — FLAIR_TOKEN (Bearer), else FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD (Basic).
     if (!authHeader) {
         if (process.env.FLAIR_TOKEN) {
             authHeader = `Bearer ${process.env.FLAIR_TOKEN}`;
+            credSource = "env-token";
         }
         else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
             const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
             authHeader = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
+            credSource = "env-admin";
         }
     }
     // Tier 3: a PINNED agent identity — sign specifically as this agent via
@@ -478,6 +536,7 @@ export async function authedRequest(method, path, body, opts) {
         if (keyPath) {
             try {
                 authHeader = buildEd25519Auth(opts.agentId, method, path, keyPath);
+                credSource = "pinned-agent";
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -491,6 +550,7 @@ export async function authedRequest(method, path, body, opts) {
             const filePass = resolveLocalAdminPass(undefined, !isLocal);
             if (filePass) {
                 authHeader = `Basic ${Buffer.from(`${adminUser}:${filePass}`).toString("base64")}`;
+                credSource = "local-admin-file";
             }
         }
         catch (err) {
@@ -500,6 +560,21 @@ export async function authedRequest(method, path, body, opts) {
             console.error(`Warning: ~/.flair/admin-pass unusable: ${message}`);
         }
     }
+    // Never let a named identity (--agent flag or FLAIR_AGENT_ID env) be
+    // silently outranked by a different credential. Precedence is unchanged
+    // (see the section above describeIdentityOverride); only the silence is.
+    if (opts.agentId && (opts.agentIdSource === "flag" || opts.agentIdSource === "env") && credSource) {
+        const notice = describeIdentityOverride({
+            agentId: opts.agentId,
+            namedSource: opts.agentIdSource,
+            credentialSource: credSource,
+            adminPassEnvVar: process.env.FLAIR_ADMIN_PASS
+                ? "FLAIR_ADMIN_PASS"
+                : process.env.HDB_ADMIN_PASSWORD ? "HDB_ADMIN_PASSWORD" : undefined,
+        });
+        if (notice)
+            emitIdentityOverrideNotice(notice);
+    }
     try {
         return await sendJsonRequest(opts.baseUrl, method, path, body, authHeader, isLocal);
     }