@tpsdev-ai/flair 0.22.1 → 0.23.0

package/dist/cli.js

@@ -19,7 +19,7 @@ import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verif
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
 import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
-import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, } from "./doctor-client.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, describeAgentGateFinding, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -382,6 +382,31 @@ function isLocalBase(base) {
         return !base;
     }
 }
+/**
+ * Thrown by api() for an HTTP-level failure (as opposed to a network error,
+ * which fetch() itself throws before api() ever sees a status code).
+ * Data-carrying, not just a message string, so callers downstream can make
+ * decisions without re-parsing text (flair#741):
+ *   - `status`: the HTTP status code, so probeInstance (src/probe.ts) can
+ *     classify ProbeResult.authFailureKind (401/403 = credential failure,
+ *     duck-typed off this property — see probe.ts's authedGet doc).
+ *   - `noCredentials`: true only for the specific bare-403-no-auth-header
+ *     case (api()'s own hint-carrying branch below) — distinguishes "we had
+ *     nothing to send" from "we sent something and it was rejected" so
+ *     verifyAuthedGet (below) knows exactly when its agent-key fallback
+ *     applies (fix #2) versus when a real credential was tried and failed
+ *     (where guessing at other keys would be misleading, not helpful).
+ */
+class ApiHttpError extends Error {
+    status;
+    noCredentials;
+    constructor(status, message, noCredentials = false) {
+        super(message);
+        this.name = "ApiHttpError";
+        this.status = status;
+        this.noCredentials = noCredentials;
+    }
+}
 async function api(method, path, body, options) {
     // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
     // When baseUrl is provided (--target), use it directly.
@@ -479,7 +504,7 @@ async function api(method, path, body, options) {
     // Handle 204 No Content (e.g., PUT upsert returns empty body)
     if (res.status === 204 || res.headers.get("content-length") === "0") {
         if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
+            throw new ApiHttpError(res.status, `HTTP ${res.status}`);
         return { ok: true };
     }
     const text = await res.text();
@@ -492,9 +517,9 @@ async function api(method, path, body, options) {
             const hint = isLocal
                 ? "Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass."
                 : "Set FLAIR_ADMIN_PASS (remote targets have no local admin-pass fallback).";
-            throw new Error(`HTTP 403: no credentials sent. ${hint}`);
+            throw new ApiHttpError(403, `HTTP 403: no credentials sent. ${hint}`, /* noCredentials */ true);
         }
-        throw new Error(text || `HTTP ${res.status}`);
+        throw new ApiHttpError(res.status, text || `HTTP ${res.status}`);
     }
     if (!text)
         return { ok: true };
@@ -553,6 +578,90 @@ async function authFetch(baseUrl, agentId, keyPath, method, path, body) {
         body: body !== undefined ? JSON.stringify(body) : undefined,
     });
 }
+/**
+ * The authedGet `flair upgrade` verification (flair#635/#741) hands to
+ * probeInstance(): api()'s existing local-credential chain (FLAIR_TOKEN >
+ * FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD > FLAIR_AGENT_ID+key > ~/.flair/admin-
+ * pass file), with an Ed25519 agent-key fallback layered on top (flair#741
+ * fix #2).
+ *
+ * The gap this closes: api()'s agent-key leg only fires when an agentId is
+ * ALREADY known (FLAIR_AGENT_ID env, or an agentId in the request body/query
+ * string) — none of which a bare `flair upgrade` ever sets. So on a machine
+ * with an agent key under ~/.flair/keys but no admin password anywhere,
+ * api() falls straight through to its no-credentials 403, even though
+ * `flair doctor`'s verified-read gate would happily use that same key. This
+ * wrapper is what actually reuses that path for verification.
+ *
+ * Auth requirement of the verification target itself: /HealthDetail
+ * (probeInstance's default versionPath) is NOT admin-gated — its
+ * `allowRead()` is `allowVerified()` (resources/health.ts, resources/agent-
+ * auth.ts), which permits ANY registered agent, not just admins. So a
+ * signed request from any registered agent's key is sufficient; there's no
+ * need to special-case a different, more-public endpoint.
+ *
+ * Only engages the fallback when api() reports NOTHING was available to
+ * send (`ApiHttpError.noCredentials`) — a wrong/rejected credential (bad
+ * admin-pass, unregistered FLAIR_AGENT_ID) is a different, more specific
+ * problem than "nothing to try"; guessing at unrelated keys on disk in that
+ * case would obscure the real error instead of explaining it.
+ *
+ * Selection rule when multiple keys exist in `keysDir` (mirrors doctor's
+ * planAgentIterations sort — doctor-client.ts): try them in sorted
+ * (deterministic) filename order, first one that authenticates wins. A
+ * liveness/verified-read check only needs ONE working identity, unlike
+ * doctor's per-agent registration report which needs to enumerate all of
+ * them.
+ */
+export async function verifyAuthedGet(baseUrl, path, keysDir) {
+    try {
+        return await api("GET", path, undefined, { baseUrl });
+    }
+    catch (err) {
+        if (!(err instanceof ApiHttpError) || !err.noCredentials)
+            throw err;
+        let keyFiles = [];
+        try {
+            keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key")).sort();
+        }
+        catch {
+            // No keys dir at all — nothing to fall back to.
+        }
+        for (const kf of keyFiles) {
+            const agentId = kf.replace(/\.key$/, "");
+            const keyPath = join(keysDir, kf);
+            try {
+                const res = await authFetch(baseUrl, agentId, keyPath, "GET", path);
+                if (res.ok)
+                    return await res.json();
+            }
+            catch {
+                // This key didn't work (unregistered, bad signature, network blip
+                // on this one attempt) — try the next one.
+            }
+        }
+        // No local key authenticated either — surface api()'s original,
+        // actionable "no credentials sent" hint rather than a fallback-specific
+        // message; it already names both remedies (FLAIR_ADMIN_PASS / `flair init`).
+        throw err;
+    }
+}
+/**
+ * flair#741 fix #3: does this ProbeResult's failure mean "the server
+ * responded but rejected the verifier's credentials" — proof of liveness,
+ * NOT a data-integrity risk — as opposed to a genuine down/unreachable/5xx
+ * failure where the instance's real state can't be determined? Pure.
+ *
+ * This is the single predicate behind three call sites in the `upgrade`
+ * command: whether the pre-upgrade credential pre-flight aborts (fix #1),
+ * and whether the post-restart / post-rollback verification failure
+ * messages claim "instance state UNKNOWN — do not assume data integrity"
+ * (they must NOT, for this case — that's the flair#741 incident itself) or
+ * explain the real, much less scary situation instead.
+ */
+export function isCredentialOnlyFailure(result) {
+    return result.healthy === true && result.authFailureKind === "credentials";
+}
 async function waitForHealth(httpPort, adminUser, adminPass, timeoutMs) {
     const url = `http://127.0.0.1:${httpPort}/Health`;
     const deadline = Date.now() + timeoutMs;
@@ -2281,7 +2390,12 @@ program
                         type: "stdio",
                         command: "npx",
                         args: ["-y", "@tpsdev-ai/flair-mcp"],
-                        env: mcpEnv,
+                        // flair#718 authorship-provenance: each client's wired env block
+                        // gets its OWN FLAIR_CLIENT label (never the shared mcpEnv
+                        // object directly — that would stamp the same label into every
+                        // client's config) so writes from THIS client's proxy stamp
+                        // provenance.claimed.client = "claude-code".
+                        env: { ...mcpEnv, FLAIR_CLIENT: "claude-code" },
                     };
                     try {
                         if (existsSync(claudeJsonPath)) {
@@ -2337,15 +2451,18 @@ program
                 }
                 else {
                     let result;
+                    // flair#718 authorship-provenance — see the claude-code branch's
+                    // identical comment above: FLAIR_CLIENT is per-client, so it's
+                    // added at each call site rather than baked into the shared mcpEnv.
                     switch (clientId) {
                         case "codex":
-                            result = wireCodex(mcpEnv);
+                            result = wireCodex({ ...mcpEnv, FLAIR_CLIENT: "codex" });
                             break;
                         case "gemini":
-                            result = wireGemini(mcpEnv);
+                            result = wireGemini({ ...mcpEnv, FLAIR_CLIENT: "gemini" });
                             break;
                         case "cursor":
-                            result = wireCursor(mcpEnv);
+                            result = wireCursor({ ...mcpEnv, FLAIR_CLIENT: "cursor" });
                             break;
                         default: result = { ok: false, message: `Unknown client: ${clientId}` };
                     }
@@ -2858,6 +2975,164 @@ agent
     }
     console.log(`\n✅ Agent '${id}' removed successfully`);
 });
+/** Best-effort seed-validity check for a `.key` file: does it parse via any
+ *  of the formats loadEd25519PrivateKeyFromFile (src/mcp-client-assertion.ts
+ *  — the same loader `flair mcp token` uses) accepts? Never throws — used
+ *  only to decide "invalid" vs. "worth a registration check", not to
+ *  actually sign anything. */
+function isValidPrivateKeySeedFile(keyPath) {
+    try {
+        loadEd25519PrivateKeyFromFile(keyPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify every entry in `keysDir` for `flair keys prune`. Pure READ —
+ * never writes or moves anything; see applyKeyPrune below for the actual
+ * move. Directories (including keysDir's own `.pruned` archive, PRUNED_DIR_NAME)
+ * and files not ending in `.key` are "ignored" without any network call.
+ * `.key` files with an unparseable seed are "invalid" without a network call
+ * either — only a `.key` file that DOES parse triggers a signed
+ * `GET /Agent/:id` against `baseUrl` (checkAgentRegistered above, the exact
+ * same check doctor's registration gate uses).
+ *
+ * If that check EVER reports "unreachable" — the instance couldn't be
+ * confirmed up for that key — the WHOLE run aborts immediately
+ * (`aborted: true`, `entries: []`, short-circuiting the loop): never
+ * classify anything, prunable or not, while registration state can't be
+ * verified. A missing keysDir is treated as "nothing to classify" (fresh
+ * install), not an error — matches `flair doctor`'s own "Keys directory
+ * missing" being a separate, non-fatal finding.
+ */
+export async function classifyKeysDir(keysDir, baseUrl) {
+    if (!existsSync(keysDir))
+        return { aborted: false, entries: [] };
+    const dirents = readdirSync(keysDir, { withFileTypes: true });
+    const entries = [];
+    const candidates = [];
+    for (const d of dirents) {
+        if (d.isDirectory()) {
+            entries.push({
+                name: d.name,
+                class: "ignored",
+                reason: d.name === PRUNED_DIR_NAME ? "prune archive directory" : "directory (not a key file)",
+            });
+            continue;
+        }
+        if (!d.name.endsWith(".key")) {
+            entries.push({ name: d.name, class: "ignored", reason: "not a .key file" });
+            continue;
+        }
+        candidates.push({ name: d.name, agentId: d.name.slice(0, -".key".length) });
+    }
+    for (const c of candidates) {
+        const keyPath = join(keysDir, c.name);
+        if (!isValidPrivateKeySeedFile(keyPath)) {
+            const decision = classifyKeyFile(c.agentId, false, null, baseUrl);
+            entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
+            continue;
+        }
+        const reg = await checkAgentRegistered(baseUrl, c.agentId, keysDir);
+        if (reg.state === "unreachable") {
+            return {
+                aborted: true,
+                abortReason: `could not reach ${baseUrl} to verify agent '${c.agentId}' is registered` +
+                    `${reg.detail ? ` (${reg.detail})` : ""} — aborting; nothing was classified or moved. ` +
+                    `Pass --instance <url> to target a different instance.`,
+                entries: [],
+            };
+        }
+        const decision = classifyKeyFile(c.agentId, true, { state: reg.state, detail: reg.detail }, baseUrl);
+        entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
+    }
+    return { aborted: false, entries };
+}
+/**
+ * Move every "stale" or "invalid" entry from `keysDir` into
+ * `<keysDir>/.pruned/<dateStamp>/`, creating the archive dir as needed —
+ * MOVE, never delete, so a bad classification is always recoverable. Only
+ * ever called with entries classifyKeysDir already decided are prunable; a
+ * "keep" or "ignored" entry passed in here is simply skipped (defense in
+ * depth — a registered agent's key must never move, even if a caller bug
+ * fed it in). Collisions (same filename already archived from an earlier
+ * prune run today) get a numeric suffix (resolveCollisionSafeName) rather
+ * than silently overwriting the earlier archive.
+ */
+export function applyKeyPrune(keysDir, entries, dateStamp) {
+    const prunable = entries.filter((e) => e.class === "stale" || e.class === "invalid");
+    if (prunable.length === 0)
+        return [];
+    const destDir = join(keysDir, PRUNED_DIR_NAME, dateStamp);
+    mkdirSync(destDir, { recursive: true });
+    const existing = new Set(readdirSync(destDir));
+    const moved = [];
+    for (const e of prunable) {
+        const destName = resolveCollisionSafeName(existing, e.name);
+        existing.add(destName);
+        const from = join(keysDir, e.name);
+        const to = join(destDir, destName);
+        renameSync(from, to);
+        moved.push({ name: e.name, movedTo: to });
+    }
+    return moved;
+}
+const keys = program.command("keys").description("Manage Ed25519 key files in the key directory");
+keys
+    .command("prune")
+    .description("Move stale/unregistered/invalid keys to <keysDir>/.pruned/<date>/ — dry-run by default")
+    .option("--apply", "Actually move prunable keys (default: dry-run, prints what would move and why)")
+    .option("--keys-dir <dir>", "Directory to scan for key files (else FLAIR_KEY_DIR, ~/.flair/keys)")
+    .option("--instance <url>", "Flair instance to check registration against (else FLAIR_TARGET/FLAIR_URL/config)")
+    .option("--port <port>", "Harper HTTP port (used when --instance/FLAIR_URL/FLAIR_TARGET are not set)")
+    .action(async (opts) => {
+    const keysDir = opts.keysDir ?? process.env.FLAIR_KEY_DIR ?? defaultKeysDir();
+    const baseUrl = resolveBaseUrl({ target: opts.instance, port: opts.port });
+    const apply = !!opts.apply;
+    console.log(`\n${render.wrap(render.c.bold, "🔑 Flair Keys Prune")}${apply ? "" : render.wrap(render.c.dim, " (dry run)")}\n`);
+    console.log(`  Keys directory: ${render.wrap(render.c.dim, keysDir)}`);
+    console.log(`  Instance:       ${render.wrap(render.c.dim, baseUrl)}\n`);
+    const result = await classifyKeysDir(keysDir, baseUrl);
+    if (result.aborted) {
+        console.error(`  ${render.icons.error} ${result.abortReason}`);
+        console.log("");
+        process.exit(1);
+    }
+    const stale = result.entries.filter((e) => e.class === "stale");
+    const invalid = result.entries.filter((e) => e.class === "invalid");
+    const kept = result.entries.filter((e) => e.class === "keep");
+    const ignored = result.entries.filter((e) => e.class === "ignored");
+    const prunable = [...stale, ...invalid];
+    if (stale.length + invalid.length + kept.length === 0) {
+        console.log(`  ${render.icons.ok} No key files found in ${render.wrap(render.c.dim, keysDir)} — nothing to prune.`);
+        console.log("");
+        return;
+    }
+    for (const e of prunable) {
+        const icon = e.class === "invalid" ? render.icons.error : render.icons.warn;
+        console.log(`  ${icon} ${render.wrap(render.c.bold, e.name)} — ${e.class}: ${e.reason}`);
+    }
+    for (const e of kept) {
+        console.log(`  ${render.icons.ok} ${e.name} — registered, keeping`);
+    }
+    if (!apply) {
+        console.log("");
+        console.log(`  ${render.wrap(render.c.dim, `${prunable.length} prunable (${stale.length} stale, ${invalid.length} invalid), ${kept.length} kept, ${ignored.length} ignored`)}`);
+        if (prunable.length > 0) {
+            console.log(`  ${render.wrap(render.c.dim, "Run with --apply to move prunable keys to")} ${join(keysDir, PRUNED_DIR_NAME, pruneDateStamp())}`);
+        }
+        console.log("");
+        return;
+    }
+    const moved = applyKeyPrune(keysDir, result.entries, pruneDateStamp());
+    console.log("");
+    for (const m of moved) {
+        console.log(`  ${render.icons.ok} moved ${m.name} -> ${m.movedTo}`);
+    }
+    console.log(`\n  ${render.wrap(render.c.bold, String(moved.length))} moved, ${kept.length} kept, ${ignored.length} ignored\n`);
+});
 // ─── flair mcp ───────────────────────────────────────────────────────────────
 // Headless agent-auth to a Harper MCP `/mcp` endpoint: RFC 7523
 // client_credentials + private_key_jwt, using the agent's EXISTING Ed25519
@@ -7017,6 +7292,66 @@ program
     // `opts` — safe to call this early.
     const { restart: shouldRestart, verify: shouldVerify, deprecatedRestartFlagUsed } = resolveUpgradeRestartVerify(opts);
     const upgradePort = resolveHttpPort({});
+    // Hoisted so the pre-flight check (below) and the post-restart/rollback
+    // verification steps (further down) all target the same URL — upgrade
+    // never restarts Flair onto a different port.
+    const baseUrl = `http://127.0.0.1:${upgradePort}`;
+    // ── Credential pre-flight (flair#741 fix #1) ────────────────────────────
+    // Post-restart verification (below) needs to authenticate against the
+    // running instance. If it can't do that RIGHT NOW, against the CURRENT,
+    // pre-upgrade instance, every upgrade on this machine is structurally
+    // doomed before a single package is touched: post-restart verify fails
+    // for the exact same credential reason, the rollback fires, and the
+    // rollback's own re-verify fails identically — producing "ROLLBACK ALSO
+    // FAILED VERIFICATION / state UNKNOWN" for an instance that was healthy
+    // the entire time. That is exactly the flair#741 incident report (a
+    // real 0.22.0→0.22.1 upgrade, healthy Flair, no ~/.flair/admin-pass, no
+    // FLAIR_ADMIN_PASS). Catch it here, before any mutation, with a message
+    // that says plainly: nothing was touched.
+    //
+    // Runs the SAME verification call (probeInstance + the agent-key-aware
+    // verifyAuthedGet, fix #2) that post-restart verification uses below —
+    // just against the pre-upgrade instance, with no expectVersion (there's
+    // no target version to compare against yet; the question here is purely
+    // "does an authenticated read work at all").
+    //
+    // Gated on --verify (shouldVerify): this check exists ONLY to keep
+    // post-restart verification honest. A user who already opted out of
+    // that verification with --no-verify has no use for a pre-flight that
+    // protects it, and blocking their upgrade on a check they didn't ask
+    // for would be a new, surprising failure mode of its own.
+    //
+    // Deliberately does NOT abort when the pre-flight instance is merely
+    // UNREACHABLE (down/timeout) rather than reachable-but-unauthenticated.
+    // `flair upgrade` may be the user's way of FIXING a down instance (bad
+    // code on disk that a newer version resolves) — today's behavior
+    // (pre-flair#741, no pre-flight at all) already lets that proceed, and
+    // a new hard block here would take away a legitimate recovery path for
+    // a failure mode this issue was never about. Only the specific
+    // "server responded, credentials didn't work" case is structurally
+    // doomed in a way a fresh install/restart can't fix on its own — so
+    // only that case aborts. (If a down instance turns out to ALSO lack
+    // credentials, that surfaces the normal way: post-restart verification
+    // fails and rolls back, same as any other post-restart failure.)
+    if (shouldVerify) {
+        const preflight = await probeInstance(baseUrl, {
+            // A short, bounded budget — this instance is presumed already
+            // running (upgrade's normal case); doctor's probePort convention
+            // (probeFlairReachable's doc comment) uses the same ~3s ballpark
+            // for "is anything there at all" checks.
+            timeoutMs: 3000,
+            pollIntervalMs: 300,
+            authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
+        });
+        if (isCredentialOnlyFailure(preflight)) {
+            console.error(`❌ pre-flight check failed: ${preflight.error}`);
+            console.error("   Nothing has been touched — no packages were installed, no restart happened.");
+            console.error("   The current instance is up and responded; the verifier just has no way to authenticate against it.");
+            console.error("   Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key — then re-run flair upgrade.");
+            console.error("   (--no-verify skips this check too, but post-restart verification would then fail the exact same way.)");
+            process.exit(1);
+        }
+    }
     // ── Pre-upgrade data snapshot (flair#637, opt-in as of the 2026-07-08 rewire) ──
     // Only an @tpsdev-ai/flair package swap touches the code that reads/
     // writes ~/.flair/data — an flair-mcp-only or openclaw-plugin-only
@@ -7170,7 +7505,7 @@ program
     }
     console.log("\nRestarting Flair...");
     const port = upgradePort;
-    const baseUrl = `http://127.0.0.1:${port}`;
+    // baseUrl was hoisted above (pre-flight, fix #1) — same URL, no redeclaration.
     try {
         await restartFlair(port);
     }
@@ -7185,13 +7520,16 @@ program
         return;
     }
     console.log("\nVerifying...");
-    // The authenticated leg dogfoods api()'s local-credential resolution
-    // (flair#640: env > agent key > ~/.flair/admin-pass file) — probeInstance
-    // itself never resolves credentials, it just calls whatever's handed to it.
+    // The authenticated leg reuses verifyAuthedGet (flair#741 fix #2): api()'s
+    // local-credential resolution (flair#640: env > agent key when an agentId
+    // is already known > ~/.flair/admin-pass file), PLUS an Ed25519 agent-key
+    // fallback when none of that resolves anything — see verifyAuthedGet's
+    // doc comment. probeInstance itself never resolves credentials, it just
+    // calls whatever's handed to it.
     const verify = await probeInstance(baseUrl, {
         expectVersion: expectedFlairVersion ?? undefined,
         timeoutMs: STARTUP_TIMEOUT_MS,
-        authedGet: (path) => api("GET", path, undefined, { baseUrl }),
+        authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
     if (verdict.kind === "ok") {
@@ -7199,6 +7537,17 @@ program
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
+    if (isCredentialOnlyFailure(verify)) {
+        // flair#741 fix #3: a responding server that rejects the verifier's
+        // credentials proves the instance is UP — it is not evidence the
+        // upgrade itself broke anything. Say so explicitly instead of leaving
+        // the reader to infer it from the raw error text. Rollback still
+        // proceeds below (a credential check that worked pre-upgrade — see
+        // the pre-flight above — and stopped working mid-run is an edge case
+        // ambiguous enough that "prefer the known-good version" is still the
+        // safer default), but the reason for it is now honest.
+        console.error("   The instance is up and responded — the verifier could not authenticate. This is not a sign the upgrade broke anything.");
+    }
     if (verdict.kind === "cannot-rollback") {
         console.error("   Cannot roll back automatically: the previously-installed @tpsdev-ai/flair version is unknown.");
         console.error("   Check the instance now: flair doctor");
@@ -7224,7 +7573,7 @@ program
     const rollbackVerify = await probeInstance(baseUrl, {
         expectVersion: verdict.toVersion,
         timeoutMs: STARTUP_TIMEOUT_MS,
-        authedGet: (path) => api("GET", path, undefined, { baseUrl }),
+        authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
     });
     const rollbackVerdict = decideAfterRollbackVerify(rollbackVerify);
     if (rollbackVerdict.kind === "rolled-back") {
@@ -7233,7 +7582,22 @@ program
         process.exit(1);
     }
     console.error(`❌❌ ROLLBACK ALSO FAILED VERIFICATION: ${rollbackVerdict.reason}`);
-    console.error("   Instance state is UNKNOWN — do not assume data integrity.");
+    // flair#741 fix #3: this is the exact incident report — a 403 from a
+    // responding, healthy server (credentials-only failure) was printed as
+    // "state UNKNOWN — do not assume data integrity" for BOTH the upgrade
+    // verify AND the rollback re-verify, because the same missing-auth-
+    // material condition rejects both. Reserve the UNKNOWN/do-not-assume
+    // text for failures where the instance's real state genuinely can't be
+    // determined (connection refused, timeout, 5xx) — a credential-only
+    // failure here means the rollback likely landed fine and the checker
+    // simply can't prove it.
+    if (isCredentialOnlyFailure(rollbackVerify)) {
+        console.error("   The instance is up and responding — the verifier could not authenticate (credentials, not the rollback, are the problem).");
+        console.error("   Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key, then check: flair doctor");
+    }
+    else {
+        console.error("   Instance state is UNKNOWN — do not assume data integrity.");
+    }
     // This double-failure isn't auto-recoverable yet (flair#637) — but if a
     // pre-upgrade snapshot landed, point at the CONCRETE path instead of
     // just the issue number, so recovery doesn't start with a GitHub search.
@@ -8191,6 +8555,7 @@ program
     let issues = 0;
     let fixed = 0; // issues that --fix successfully resolved during this run (flair#721)
     let harperResponding = false;
+    let keyAgentIds = []; // populated by step 2 (Keys directory) below; feeds the flair#722 per-agent iteration
     console.log(`\n${render.wrap(render.c.bold, "🩺 Flair Doctor")}\n`);
     // 0. Version check (flair#587) — offline-tolerant + cached, independent
     // of Harper being up. A gap of ≥2 minor versions (or any major) is
@@ -8386,6 +8751,7 @@ program
     if (existsSync(keysDir)) {
         const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
         if (keyFiles.length > 0) {
+            keyAgentIds = keyFiles.map((f) => f.replace(/\.key$/, ""));
             console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(keyFiles.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
         }
         else {
@@ -8537,7 +8903,7 @@ program
                                 console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent id known — pass --agent <id>`);
                             }
                             else {
-                                const wireEnv = { FLAIR_AGENT_ID: fixAgentId, FLAIR_URL: block.flairUrl || baseUrl };
+                                const wireEnv = { FLAIR_AGENT_ID: fixAgentId, FLAIR_URL: resolveWireFlairUrl(block.flairUrl, baseUrl) };
                                 const wireResult = client.id === "claude-code" ? wireClaudeCode(wireEnv) :
                                     client.id === "codex" ? wireCodex(wireEnv) :
                                         client.id === "gemini" ? wireGemini(wireEnv) :
@@ -8637,6 +9003,54 @@ program
             }
         }
     }
+    // 7a. Resolve which agent identities the two verified-read sections below
+    // (Fleet presence, Migrations) iterate (flair#722). Previously both
+    // sections required --agent explicitly; doctor already enumerates every
+    // key in ~/.flair/keys (step 2 above), so by default it now runs the
+    // signed read AS EACH of those agents instead of hiding behind a flag —
+    // a real dogfood run found the #720 halted-migration warning visible via
+    // `flair status --agent local` but invisible in the default `doctor` run
+    // the same user ran minutes later. --agent <id> narrows this to exactly
+    // that one identity (planAgentIterations — same pre-#722 semantics: a
+    // single signed identity, just no longer widened to "every key").
+    //
+    // The registration gate (checkAgentRegistered — same signed GET
+    // /Agent/:id used by the Client integration section above) is resolved
+    // ONCE here per agent and shared by both sections, so a bad/unregistered
+    // key doesn't cost two network round-trips, and its "found" count isn't
+    // double-counted by each section re-discovering the same finding
+    // (flair#721 found/fixed/remaining summary — these are found-only, no
+    // --fix action exists for a bad local key). A gate failure for one agent
+    // never aborts the others — that's the failure isolation flair#722 asks
+    // for; describeAgentGateFinding (src/doctor-client.ts) is pure decision
+    // logic so it's unit-tested without a real Harper.
+    const verifiedReadAgentIds = harperResponding
+        ? planAgentIterations(keyAgentIds, opts.agent || process.env.FLAIR_AGENT_ID)
+        : [];
+    const agentGates = [];
+    for (const id of verifiedReadAgentIds) {
+        const reg = await checkAgentRegistered(baseUrl, id, defaultKeysDir());
+        agentGates.push({ id, state: reg.state, detail: reg.detail });
+        const finding = describeAgentGateFinding(id, reg.state, reg.detail);
+        if (finding?.isIssue)
+            issues++;
+    }
+    // Shared renderer for one agent's registration-gate outcome — prints the
+    // "Agent: <id>" subsection header, and if the gate isn't clean, the
+    // finding (never re-counted here; already counted once above) and
+    // returns false so the caller skips its own verified fetch for this
+    // agent and moves on to the next (failure isolation).
+    function renderAgentGateHeader(gate) {
+        console.log(`    ${render.wrap(render.c.dim, `Agent: ${gate.id}`)}`);
+        const finding = describeAgentGateFinding(gate.id, gate.state, gate.detail);
+        if (!finding)
+            return true;
+        const icon = finding.icon === "error" ? render.icons.error : render.icons.warn;
+        console.log(`      ${icon} ${finding.message}`);
+        if (finding.fixHint)
+            console.log(`         ${render.wrap(render.c.dim, "Fix:")} ${finding.fixHint}`);
+        return false;
+    }
     // 8. Fleet presence (flair#639) — known instances via /Presence heartbeats.
     //
     // "Instance" here means each AGENT's heartbeat row — Presence is keyed by
@@ -8657,69 +9071,82 @@ program
     // `doctor` unless those agents also heartbeat straight to the hub. Not
     // fixed here — flair#639's fix list is version-stamping + a doctor
     // listing, not widening federation sync scope.
-    if (harperResponding) {
-        console.log(`\n  ${render.wrap(render.c.bold, "Fleet presence")}`);
+    //
+    // flair#722: iterated per agent (agentGates above) instead of a single
+    // --agent-gated read. flairVersion/harperVersion are gated to verified
+    // readers on the server (resources/Presence.ts, same boundary as
+    // currentTask), so each agent subsection signs its own GET — a working
+    // key reveals versions for that subsection; roster IDENTITY is public
+    // either way. Zero local keys (and no --agent) falls back to exactly the
+    // pre-#722 single unauthenticated read (hidden versions, "Pass --agent"
+    // hint) — there's no agent to sign as, but remote agents may still have
+    // heartbeated onto this instance and identities are worth showing.
+    async function fetchAndRenderFleetPresence(headers, canSign, indent) {
         try {
-            // flairVersion/harperVersion are gated to verified readers on the
-            // server (resources/Presence.ts, same boundary as currentTask) — sign
-            // the GET when we have an agent + key so the fields aren't silently
-            // nulled out from under us.
-            const fleetAgentId = opts.agent || process.env.FLAIR_AGENT_ID;
-            const fleetKeyPath = fleetAgentId ? join(defaultKeysDir(), `${fleetAgentId}.key`) : undefined;
-            const canSign = !!(fleetAgentId && fleetKeyPath && existsSync(fleetKeyPath));
-            const headers = canSign
-                ? { Authorization: buildEd25519Auth(fleetAgentId, "GET", "/Presence", fleetKeyPath) }
-                : {};
             const presRes = await fetch(`${baseUrl}/Presence`, { headers, signal: AbortSignal.timeout(5000) });
             if (!presRes.ok) {
-                console.log(`  ${render.icons.warn} Could not fetch presence roster (HTTP ${presRes.status})`);
+                console.log(`${indent}${render.icons.warn} Could not fetch presence roster (HTTP ${presRes.status})`);
+                return;
             }
-            else {
-                const roster = (await presRes.json());
-                if (!Array.isArray(roster) || roster.length === 0) {
-                    console.log(`  ${render.icons.info} No known instances yet — no /Presence heartbeats recorded on this instance`);
-                }
-                else {
-                    const rows = sortOldestVersionFirst(markStale(roster));
-                    for (const row of rows) {
-                        const lastSeen = typeof row.lastHeartbeatAt === "number"
-                            ? render.relativeTime(new Date(row.lastHeartbeatAt).toISOString())
-                            : "—";
-                        const versionLabel = !canSign
-                            ? render.wrap(render.c.dim, "hidden")
-                            : row.flairVersion
-                                ? `v${row.flairVersion}`
-                                : render.wrap(render.c.dim, "no version reported");
-                        const staleNote = row.stale && row.newestVersion
-                            ? " " + render.wrap(render.c.yellow, `(stale — fleet newest is v${row.newestVersion})`)
-                            : "";
-                        const icon = row.stale ? render.icons.warn : render.icons.ok;
-                        const statusSuffix = row.presenceStatus ? ` (${row.presenceStatus})` : "";
-                        // Natural-presence: same staleness principle as the version
-                        // column — a live activity is shown as current, a decayed one as
-                        // "last-known". `activityFresh === false` (server verdict) plus a
-                        // known lastActivity → "(was: X)"; a fresh, non-idle activity →
-                        // "(X)". Skip entirely when there's nothing informative to say
-                        // (no signal, or idle) so the line stays quiet for the common case.
-                        const lastActivity = row.lastActivity ?? row.activity;
-                        const activityNote = row.activityFresh === false
-                            ? (lastActivity && lastActivity !== "idle"
-                                ? " " + render.wrap(render.c.dim, `(was: ${lastActivity})`)
-                                : "")
-                            : (row.activity && row.activity !== "idle"
-                                ? " " + render.wrap(render.c.dim, `(${row.activity})`)
-                                : "");
-                        console.log(`  ${icon} ${row.id} — ${versionLabel} — last seen ${lastSeen}${statusSuffix}${activityNote}${staleNote}`);
-                    }
-                    if (!canSign) {
-                        console.log(`     ${render.wrap(render.c.dim, "Pass --agent <id> (with a matching key in ~/.flair/keys) to reveal versions — flairVersion/harperVersion require a verified signature, same as currentTask.")}`);
-                    }
-                    console.log(`     ${render.wrap(render.c.dim, "Staleness above is fleet-relative (newest version seen among these instances) — comparing against the latest PUBLISHED flair is the version check at the top of this report, not this section.")}`);
-                }
+            const roster = (await presRes.json());
+            if (!Array.isArray(roster) || roster.length === 0) {
+                console.log(`${indent}${render.icons.info} No known instances yet — no /Presence heartbeats recorded on this instance`);
+                return;
             }
+            const rows = sortOldestVersionFirst(markStale(roster));
+            for (const row of rows) {
+                const lastSeen = typeof row.lastHeartbeatAt === "number"
+                    ? render.relativeTime(new Date(row.lastHeartbeatAt).toISOString())
+                    : "—";
+                const versionLabel = !canSign
+                    ? render.wrap(render.c.dim, "hidden")
+                    : row.flairVersion
+                        ? `v${row.flairVersion}`
+                        : render.wrap(render.c.dim, "no version reported");
+                const staleNote = row.stale && row.newestVersion
+                    ? " " + render.wrap(render.c.yellow, `(stale — fleet newest is v${row.newestVersion})`)
+                    : "";
+                const icon = row.stale ? render.icons.warn : render.icons.ok;
+                const statusSuffix = row.presenceStatus ? ` (${row.presenceStatus})` : "";
+                // Natural-presence: same staleness principle as the version
+                // column — a live activity is shown as current, a decayed one as
+                // "last-known". `activityFresh === false` (server verdict) plus a
+                // known lastActivity → "(was: X)"; a fresh, non-idle activity →
+                // "(X)". Skip entirely when there's nothing informative to say
+                // (no signal, or idle) so the line stays quiet for the common case.
+                const lastActivity = row.lastActivity ?? row.activity;
+                const activityNote = row.activityFresh === false
+                    ? (lastActivity && lastActivity !== "idle"
+                        ? " " + render.wrap(render.c.dim, `(was: ${lastActivity})`)
+                        : "")
+                    : (row.activity && row.activity !== "idle"
+                        ? " " + render.wrap(render.c.dim, `(${row.activity})`)
+                        : "");
+                console.log(`${indent}${icon} ${row.id} — ${versionLabel} — last seen ${lastSeen}${statusSuffix}${activityNote}${staleNote}`);
+            }
+            if (!canSign) {
+                console.log(`${indent}   ${render.wrap(render.c.dim, "Pass --agent <id> (with a matching key in ~/.flair/keys) to reveal versions — flairVersion/harperVersion require a verified signature, same as currentTask.")}`);
+            }
+            console.log(`${indent}   ${render.wrap(render.c.dim, "Staleness above is fleet-relative (newest version seen among these instances) — comparing against the latest PUBLISHED flair is the version check at the top of this report, not this section.")}`);
         }
         catch (err) {
-            console.log(`  ${render.icons.warn} Fleet presence check failed: ${err?.message ?? err}`);
+            console.log(`${indent}${render.icons.warn} Fleet presence check failed: ${err?.message ?? err}`);
+        }
+    }
+    if (harperResponding) {
+        console.log(`\n  ${render.wrap(render.c.bold, "Fleet presence")}`);
+        if (agentGates.length === 0) {
+            await fetchAndRenderFleetPresence({}, false, "  ");
+        }
+        else {
+            for (const gate of agentGates) {
+                const registered = renderAgentGateHeader(gate);
+                if (!registered)
+                    continue;
+                const keyPath = resolveKeyPath(gate.id) ?? join(defaultKeysDir(), `${gate.id}.key`);
+                const headers = { Authorization: buildEd25519Auth(gate.id, "GET", "/Presence", keyPath) };
+                await fetchAndRenderFleetPresence(headers, true, "      ");
+            }
         }
     }
     // 9. Migration state (flair#695) — pending/in-progress/blocked + last
@@ -8729,52 +9156,70 @@ program
     // 1a above (a halted migration retries automatically on the next boot —
     // there's no separate "run the migration now" fix; the fix for
     // "blocked" is whatever the halt reason names, e.g. freeing disk).
-    if (harperResponding) {
-        console.log(`\n  ${render.wrap(render.c.bold, "Migrations")}`);
+    //
+    // flair#722: iterated per agent (agentGates above), same as Fleet
+    // presence — each subsection's finding is found-only (no per-agent
+    // --fix here beyond the existing restart-on-halt story). Gate FINDINGS
+    // are rendered in full under Fleet presence only (the first
+    // verified-read section); re-printing the identical per-agent finding
+    // here doubled the noise on real multi-key machines (a 27-key dogfood
+    // box printed 15 not-registered findings twice each), so this section
+    // iterates only the gate-passed agents and rolls the rest into one
+    // aggregate skip line. The issue COUNT is unaffected either way — gate
+    // findings are counted exactly once, at gate-resolution time (step 7a).
+    async function fetchAndRenderMigrations(headers, indent) {
         try {
-            const migAgentId = opts.agent || process.env.FLAIR_AGENT_ID;
-            const migKeyPath = migAgentId ? join(defaultKeysDir(), `${migAgentId}.key`) : undefined;
-            const migCanSign = !!(migAgentId && migKeyPath && existsSync(migKeyPath));
-            if (!migCanSign) {
-                console.log(`  ${render.icons.info} Pass --agent <id> (with a matching key in ~/.flair/keys) to see migration state — requires a verified read, same as Fleet presence above.`);
+            const migRes = await fetch(`${baseUrl}/HealthDetail`, { headers, signal: AbortSignal.timeout(5000) });
+            if (!migRes.ok) {
+                console.log(`${indent}${render.icons.warn} Could not fetch migration state (HTTP ${migRes.status})`);
+                return;
             }
-            else {
-                const migHeaders = { Authorization: buildEd25519Auth(migAgentId, "GET", "/HealthDetail", migKeyPath) };
-                const migRes = await fetch(`${baseUrl}/HealthDetail`, { headers: migHeaders, signal: AbortSignal.timeout(5000) });
-                if (!migRes.ok) {
-                    console.log(`  ${render.icons.warn} Could not fetch migration state (HTTP ${migRes.status})`);
+            const detail = (await migRes.json());
+            const migBlock = detail?.migrations;
+            if (!migBlock || !Array.isArray(migBlock.migrations) || migBlock.migrations.length === 0) {
+                console.log(`${indent}${render.icons.info} No migrations registered on this instance`);
+                return;
+            }
+            if (migBlock.cyclePhase === "pre-hash") {
+                console.log(`${indent}${render.icons.info} Pre-flight integrity check in progress — migrations deferred until it completes`);
+            }
+            for (const m of migBlock.migrations) {
+                if (m.state === "completed") {
+                    console.log(`${indent}${render.icons.ok} ${m.id}: completed`);
+                }
+                else if (m.state === "halted" || m.state === "failed") {
+                    console.log(`${indent}${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
+                    issues++;
+                }
+                else if (m.state === "running") {
+                    console.log(`${indent}${render.icons.info} ${m.id}: in progress (${m.rowsDone} done, ${m.rowsRemaining} remaining)`);
                 }
                 else {
-                    const detail = (await migRes.json());
-                    const migBlock = detail?.migrations;
-                    if (!migBlock || !Array.isArray(migBlock.migrations) || migBlock.migrations.length === 0) {
-                        console.log(`  ${render.icons.info} No migrations registered on this instance`);
-                    }
-                    else {
-                        if (migBlock.cyclePhase === "pre-hash") {
-                            console.log(`  ${render.icons.info} Pre-flight integrity check in progress — migrations deferred until it completes`);
-                        }
-                        for (const m of migBlock.migrations) {
-                            if (m.state === "completed") {
-                                console.log(`  ${render.icons.ok} ${m.id}: completed`);
-                            }
-                            else if (m.state === "halted" || m.state === "failed") {
-                                console.log(`  ${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
-                                issues++;
-                            }
-                            else if (m.state === "running") {
-                                console.log(`  ${render.icons.info} ${m.id}: in progress (${m.rowsDone} done, ${m.rowsRemaining} remaining)`);
-                            }
-                            else {
-                                console.log(`  ${render.icons.info} ${m.id}: ${m.state}`);
-                            }
-                        }
-                    }
+                    console.log(`${indent}${render.icons.info} ${m.id}: ${m.state}`);
                 }
             }
         }
         catch (err) {
-            console.log(`  ${render.icons.warn} Migration state check failed: ${err?.message ?? err}`);
+            console.log(`${indent}${render.icons.warn} Migration state check failed: ${err?.message ?? err}`);
+        }
+    }
+    if (harperResponding) {
+        console.log(`\n  ${render.wrap(render.c.bold, "Migrations")}`);
+        if (agentGates.length === 0) {
+            console.log(`  ${render.icons.info} Pass --agent <id> (with a matching key in ~/.flair/keys) to see migration state — requires a verified read, same as Fleet presence above.`);
+        }
+        else {
+            const passedGates = agentGates.filter((g) => describeAgentGateFinding(g.id, g.state, g.detail) === null);
+            for (const gate of passedGates) {
+                renderAgentGateHeader(gate);
+                const keyPath = resolveKeyPath(gate.id) ?? join(defaultKeysDir(), `${gate.id}.key`);
+                const headers = { Authorization: buildEd25519Auth(gate.id, "GET", "/HealthDetail", keyPath) };
+                await fetchAndRenderMigrations(headers, "      ");
+            }
+            const skipped = agentGates.length - passedGates.length;
+            if (skipped > 0) {
+                console.log(`  ${render.icons.info} ${skipped} agent(s) skipped — registration-gate findings reported under Fleet presence above`);
+            }
         }
     }
     // Summary — see summarizeDoctorRun above (flair#721): distinguishes