@drakon-systems/multi-clawd 1.7.2 → 1.7.4

package/dist/index.js

@@ -9,8 +9,9 @@ import { MODEL_ALIASES, buildCatalogEntries, canonicalModelId, isModernClaudeMod
 import { decideDegradation, matchesPin } from "./degrade.js";
 import { resolveExecMode, permissionModeArgs } from "./exec-policy.js";
 import { resolveBaseModelIds } from "./catalog-source.js";
-import { classifyAccountHealth } from "./health.js";
+import { allCredentialFailed, classifyAccountHealth } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
+import { clearCredentialFailure, mergeHealthStates, parseStoredState, recordCredentialFailure, } from "./shim-core.js";
 import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js";
 import { resolveSecretRefValues } from "openclaw/plugin-sdk/secret-ref-runtime";
 import { addAlert, clearAlert, pendingAlertText } from "./alerts.js";
@@ -116,53 +117,104 @@ const realCredentialIo = {
     },
     platform: process.platform,
 };
-function startLoginHealthProbe(accounts, logger) {
-    if (loginProbeTimer)
-        clearInterval(loginProbeTimer);
-    const lastStatus = new Map();
-    const refTrackers = new Map();
-    const probe = async () => {
-        const now = Date.now();
-        for (const account of accounts) {
-            let status;
-            let reason;
-            if (isSecretRefShape(account.oauthTokenRef) && !account.oauthTokenFile && !account.native) {
-                let tracker = refTrackers.get(account.id);
-                if (!tracker) {
-                    tracker = createRefProbeTracker();
-                    refTrackers.set(account.id, tracker);
-                }
-                const result = (await activeTokenResolver?.resolveDetailed(account.oauthTokenRef)) ?? {
-                    failure: "provider_error",
-                };
-                const outcome = tracker.observe(result, now);
-                status = outcome.status;
-                reason = outcome.reason;
-            }
-            else {
-                const check = checkAccountCredential(account, realCredentialIo);
-                status = check.status;
-                reason = check.reason;
+const refProbeTrackers = new Map();
+const lastProbeStatus = new Map();
+function recordAccountCredentialFailure(accountId, reason, nowMs) {
+    const file = healthStateFile(accountId);
+    let state;
+    try {
+        state = parseStoredState(readFileSync(file, "utf8")) ?? { accountId, windows: {} };
+    }
+    catch {
+        state = { accountId, windows: {} };
+    }
+    const next = mergeHealthStates(state, recordCredentialFailure(state, reason, nowMs), nowMs);
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch {
+    }
+}
+export async function runLoginHealthProbe(accounts, logger, deps = {}) {
+    const now = deps.nowMs ?? Date.now();
+    const resolver = deps.resolver ?? activeTokenResolver;
+    const io = deps.io ?? realCredentialIo;
+    for (const account of accounts) {
+        let status;
+        let reason;
+        let cause;
+        if (isSecretRefShape(account.oauthTokenRef) && !account.oauthTokenFile && !account.native) {
+            let tracker = refProbeTrackers.get(account.id);
+            if (!tracker) {
+                tracker = createRefProbeTracker();
+                refProbeTrackers.set(account.id, tracker);
             }
-            const previous = lastStatus.get(account.id);
-            lastStatus.set(account.id, status);
-            if (status === "broken" && previous !== "broken") {
-                const text = `account "${account.id}" login looks dead (${reason ?? "unknown"}) — turns on it will fail until fixed`;
+            const result = (await resolver?.resolveDetailed(account.oauthTokenRef)) ?? {
+                failure: "provider_error",
+            };
+            const outcome = tracker.observe(result, now);
+            status = outcome.status;
+            reason = outcome.reason;
+            cause = outcome.cause;
+        }
+        else {
+            const check = checkAccountCredential(account, io);
+            status = check.status;
+            reason = check.reason;
+        }
+        const previous = lastProbeStatus.get(account.id);
+        lastProbeStatus.set(account.id, status);
+        if (status === "broken" && cause === "credential") {
+            recordAccountCredentialFailure(account.id, reason ?? "login probe found no credential", now);
+            if (previous !== "broken") {
+                const text = `account "${account.id}" login looks dead (${reason ?? "unknown"}) — excluded from pool selection until it is fixed`;
                 logger.error(`[multi-clawd] ${text}`);
                 raiseAlert({ key: `login:${account.id}`, severity: "error", text });
             }
-            else if (status === "degraded" && previous !== "degraded") {
-                logger.info(`[multi-clawd] account "${account.id}" login degraded: ${reason ?? "resolver error"}`);
-            }
-            else if (status === "ok" && (previous === "broken" || previous === "degraded")) {
-                logger.info(`[multi-clawd] account "${account.id}" login recovered`);
-                alertState = clearAlert(alertState, `login:${account.id}`);
+        }
+        else if (status === "broken" && cause === "provider") {
+            if (previous !== "broken") {
+                const text = `account "${account.id}" credential resolver is unreachable (${reason ?? "unknown"}) — ` +
+                    `this looks like a host or network problem rather than a broken login, so account ` +
+                    `selection is unchanged. Check connectivity to the secret provider.`;
+                logger.error(`[multi-clawd] ${text}`);
+                raiseAlert({ key: `login-resolver:${account.id}`, severity: "error", text });
             }
         }
-    };
-    const initial = setTimeout(() => void probe().catch(() => { }), LOGIN_PROBE_INITIAL_DELAY_MS);
+        else if (status === "broken" && previous !== "broken") {
+            const text = `account "${account.id}" login looks dead (${reason ?? "unknown"}) — turns on it will fail until fixed`;
+            logger.error(`[multi-clawd] ${text}`);
+            raiseAlert({ key: `login:${account.id}`, severity: "error", text });
+        }
+        else if (status === "degraded" && previous !== "degraded") {
+            logger.info(`[multi-clawd] account "${account.id}" login degraded: ${reason ?? "resolver error"}`);
+        }
+        else if (status === "ok" && (previous === "broken" || previous === "degraded")) {
+            logger.info(`[multi-clawd] account "${account.id}" login recovered`);
+            alertState = clearAlert(alertState, `login:${account.id}`);
+            alertState = clearAlert(alertState, `login-resolver:${account.id}`);
+        }
+    }
+}
+export function startLoginHealthProbe(accounts, logger) {
+    if (loginProbeTimer)
+        clearInterval(loginProbeTimer);
+    const live = new Set(accounts.map((a) => a.id));
+    for (const id of [...refProbeTrackers.keys()]) {
+        if (!live.has(id))
+            refProbeTrackers.delete(id);
+    }
+    for (const id of [...lastProbeStatus.keys()]) {
+        if (!live.has(id))
+            lastProbeStatus.delete(id);
+    }
+    const probe = () => void runLoginHealthProbe(accounts, logger).catch(() => { });
+    const initial = setTimeout(probe, LOGIN_PROBE_INITIAL_DELAY_MS);
     initial.unref?.();
-    loginProbeTimer = setInterval(() => void probe().catch(() => { }), LOGIN_PROBE_INTERVAL_MS);
+    loginProbeTimer = setInterval(probe, LOGIN_PROBE_INTERVAL_MS);
     loginProbeTimer.unref?.();
 }
 const warnedTokenFileModes = new Set();
@@ -193,9 +245,9 @@ function peekToken(account) {
         return undefined;
     throw new Error(`[multi-clawd] account "${account.id}" needs oauthTokenFile, oauthTokenRef, or configDir`);
 }
-async function resolveTokenAsync(account) {
+async function resolveTokenAsync(account, resolver) {
     if (isSecretRefShape(account.oauthTokenRef) && !account.native && !account.oauthTokenFile) {
-        return activeTokenResolver?.resolve(account.oauthTokenRef);
+        return (resolver ?? activeTokenResolver)?.resolve(account.oauthTokenRef);
     }
     return peekToken(account);
 }
@@ -330,8 +382,8 @@ export function buildBackend(account, execMode) {
         },
     };
 }
-async function buildAccountEnv(account) {
-    const token = await resolveTokenAsync(account);
+async function buildAccountEnv(account, resolver) {
+    const token = await resolveTokenAsync(account, resolver);
     return buildAccountChildEnv(account, token, healthStateFile(account.id));
 }
 function buildCatalogProvider(account) {
@@ -445,6 +497,32 @@ function readHealthState(accountId) {
         return undefined;
     }
 }
+export function clearAccountCredentialFailure(accountId) {
+    const file = healthStateFile(accountId);
+    let state;
+    try {
+        state = parseStoredState(readFileSync(file, "utf8")) ?? {
+            accountId,
+            windows: {},
+        };
+    }
+    catch {
+        return false;
+    }
+    if (state.credential?.status !== "failed")
+        return false;
+    const cleared = mergeHealthStates(state, clearCredentialFailure(state, Date.now()), Date.now());
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(cleared, null, 2), { mode: 0o600 });
+        renameSync(tmp, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function readStickyEntry(file) {
     try {
         const parsed = JSON.parse(readFileSync(file, "utf8"));
@@ -471,7 +549,7 @@ function writeStickyEntry(file, entry, logger) {
         logger.warn(`[multi-clawd] sticky state write failed: ${String(err)}`);
     }
 }
-export function registerPoolBackend(api, pool, accounts, registeredIds, execMode) {
+export function registerPoolBackend(api, pool, accounts, registeredIds, execMode, deps) {
     const logger = api.logger;
     if (!pool)
         return;
@@ -515,6 +593,17 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             id: a.id,
             health: classifyAccountHealth(readHealthState(a.id), options, now, requestedModel),
         }));
+        if (allCredentialFailed(verdicts.map((v) => ({ id: v.id, verdict: v.health.verdict })))) {
+            const detail = verdicts
+                .map((v) => `${v.id} (${v.health.reason ?? "credential rejected"})`)
+                .join("; ");
+            const text = `pool ${poolId}: every account's login is rejected by the Claude CLI — ` +
+                `re-authenticate with \`multi-clawd login <account>\`. ${detail}`;
+            logger.error(`[multi-clawd] ${text}`);
+            raiseAlert({ key: `pool-credentials:${poolId}`, severity: "error", text });
+            writeStickyEntry(stickyFile, undefined, logger);
+            throw new Error(`[multi-clawd] ${text}`);
+        }
         const previousSticky = readStickyEntry(stickyFile);
         const decision = decideStickySelection({
             verdicts: verdicts.map((v) => ({ id: v.id, verdict: v.health.verdict })),
@@ -539,8 +628,45 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
                 text: `pool ${poolId}: every account is exhausted for ${requestedModel} — turns are degrading or falling through the chain`,
             });
         }
+        for (const v of verdicts) {
+            const key = `credential:${poolId}:${v.id}`;
+            if (v.health.verdict === "credential_failed") {
+                raiseAlert({
+                    key,
+                    severity: "error",
+                    text: `pool ${poolId}: account "${v.id}" is excluded — ${v.health.reason ?? "its login was rejected by the Claude CLI"}. Fix with \`multi-clawd login ${v.id}\`.`,
+                });
+            }
+            else {
+                alertState = clearAlert(alertState, key);
+            }
+        }
+        alertState = clearAlert(alertState, `pool-credentials:${poolId}`);
         writeStickyEntry(stickyFile, decision.sticky, logger);
-        const env = await buildAccountEnv(chosen);
+        const order = [chosen, ...members.filter((m) => m.id !== chosen.id)];
+        let env;
+        const unresolved = [];
+        for (const candidate of order) {
+            try {
+                env = await buildAccountEnv(candidate, deps?.resolver);
+                if (candidate.id !== chosen.id) {
+                    logger.warn(`[multi-clawd] pool ${poolId}: ${chosen.id}'s credential did not resolve — ` +
+                        `launching on ${candidate.id} instead (account not benched; secret provider may be down)`);
+                }
+                break;
+            }
+            catch (err) {
+                unresolved.push(`${candidate.id} (${err.message})`);
+            }
+        }
+        if (!env) {
+            const text = `pool ${poolId}: no account's credential could be resolved — ` +
+                `the secret provider is unreachable or every reference is empty. ${unresolved.join("; ")}`;
+            logger.error(`[multi-clawd] ${text}`);
+            raiseAlert({ key: `pool-unresolvable:${poolId}`, severity: "error", text });
+            throw new Error(`[multi-clawd] ${text}`);
+        }
+        alertState = clearAlert(alertState, `pool-unresolvable:${poolId}`);
         if (ladder.length > 0) {
             const pinned = matchesPin(pins, {
                 agentDir: ctx.agentDir ?? "",

package/dist/login-health.js

@@ -15,6 +15,7 @@ export function createRefProbeTracker(options = {}) {
                 firstFailureAt = undefined;
                 return {
                     status: "broken",
+                    cause: "credential",
                     reason: "oauthTokenRef resolved to nothing (credential problem)",
                 };
             }
@@ -25,6 +26,7 @@ export function createRefProbeTracker(options = {}) {
             if (consecutive >= deadAfterConsecutive && elapsed >= deadAfterMs) {
                 return {
                     status: "broken",
+                    cause: "provider",
                     reason: `resolver failing ${deadAfterConsecutive}+ consecutive probes over ${Math.round(deadAfterMs / 60000)}m`,
                 };
             }

package/dist/shim-core.js

@@ -91,10 +91,22 @@ export function parseStoredState(raw) {
             rawInfo: typeof w.rawInfo === "string" ? w.rawInfo : undefined,
         };
     }
+    let credential;
+    if (typeof p.credential === "object" && p.credential !== null) {
+        const c = p.credential;
+        if ((c.status === "failed" || c.status === "ok") && typeof c.seenAt === "number") {
+            credential = {
+                status: c.status,
+                reason: typeof c.reason === "string" ? c.reason : undefined,
+                seenAt: c.seenAt,
+            };
+        }
+    }
     return {
         accountId: typeof p.accountId === "string" ? p.accountId : "unknown",
         updatedAt: typeof p.updatedAt === "number" ? p.updatedAt : undefined,
         windows,
+        credential,
     };
 }
 export function mergeHealthStates(disk, live, now, pruneAfterMs = PRUNE_AFTER_MS) {
@@ -119,11 +131,19 @@ export function mergeHealthStates(disk, live, now, pruneAfterMs = PRUNE_AFTER_MS
             }
         }
     }
+    let credential = disk.credential;
+    if (live.credential && (!credential || live.credential.seenAt >= credential.seenAt)) {
+        credential = live.credential;
+    }
+    if (now !== undefined && credential && now - credential.seenAt > pruneAfterMs) {
+        credential = undefined;
+    }
     const updatedAt = Math.max(disk.updatedAt ?? 0, live.updatedAt ?? 0);
     return {
         accountId: live.accountId,
         updatedAt: updatedAt > 0 ? updatedAt : undefined,
         windows,
+        credential,
     };
 }
 const MODEL_ID_PROVIDER_PREFIXES = [
@@ -207,6 +227,70 @@ export function recordModelLimit(state, modelId, now, resetsAt) {
         },
     };
 }
+const AUTH_FAILURE_PATTERNS = [
+    /oauth (session|token) (has )?(expired|been revoked)/i,
+    /failed to authenticate/i,
+    /invalid (api key|bearer token|access token)/i,
+    /authentication[_ ]?error/i,
+    /please run \/login/i,
+    /not logged in/i,
+    /unauthori[sz]ed/i,
+];
+const AUTH_REASON_MAX_CHARS = 200;
+export function parseAuthFailure(line) {
+    if (!/(authenticat|oauth|logged in|\/login|unauthori|api key|access token|bearer token)/i.test(line)) {
+        return undefined;
+    }
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof record !== "object" || record === null)
+        return undefined;
+    const r = record;
+    const isErrorRecord = r.type === "error" ||
+        r.is_error === true ||
+        (typeof r.subtype === "string" && r.subtype.startsWith("error"));
+    if (!isErrorRecord)
+        return undefined;
+    const texts = [];
+    if (typeof r.result === "string")
+        texts.push(r.result);
+    if (typeof r.error === "string")
+        texts.push(r.error);
+    if (typeof r.error === "object" && r.error !== null) {
+        const msg = r.error.message;
+        if (typeof msg === "string")
+            texts.push(msg);
+    }
+    for (const text of texts) {
+        if (AUTH_FAILURE_PATTERNS.some((p) => p.test(text))) {
+            return { reason: text.trim().slice(0, AUTH_REASON_MAX_CHARS) };
+        }
+    }
+    return undefined;
+}
+export function recordCredentialFailure(state, reason, now) {
+    return {
+        ...state,
+        updatedAt: now,
+        credential: {
+            status: "failed",
+            reason: reason.slice(0, AUTH_REASON_MAX_CHARS),
+            seenAt: now,
+        },
+    };
+}
+export function clearCredentialFailure(state, now) {
+    return {
+        ...state,
+        updatedAt: now,
+        credential: { status: "ok", seenAt: now },
+    };
+}
 export function updateHealthState(state, event, now) {
     const key = event.rateLimitType ?? "unknown";
     return {

package/dist/shim.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { classifyStateReadFailure, createLineScanner, mergeHealthStates, parseRateLimitEvent, parseStoredState, updateHealthState, } from "./shim-core.js";
+import { classifyStateReadFailure, clearCredentialFailure, createLineScanner, mergeHealthStates, parseAuthFailure, parseRateLimitEvent, parseStoredState, recordCredentialFailure, updateHealthState, } from "./shim-core.js";
 import { rewriteModelArg } from "./degrade.js";
 import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
 import { canonicalModelId } from "./models.js";
@@ -108,6 +108,7 @@ function guessLimitResetsAt() {
     }
     return undefined;
 }
+let sawAuthFailure = false;
 const scanner = createLineScanner((line) => {
     try {
         const event = parseRateLimitEvent(line);
@@ -124,6 +125,13 @@ const scanner = createLineScanner((line) => {
                 process.stderr.write(`[multi-clawd shim] model limit hit recorded: ${model} (reported as "${limitHit.displayName}")\n`);
             }
         }
+        const authFailure = parseAuthFailure(line);
+        if (authFailure && !sawAuthFailure) {
+            sawAuthFailure = true;
+            state = recordCredentialFailure(state, authFailure.reason, Date.now());
+            persistState();
+            process.stderr.write(`[multi-clawd shim] auth failure recorded for ${accountId}: ${authFailure.reason}\n`);
+        }
     }
     catch {
     }
@@ -138,11 +146,26 @@ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
         child.kill(signal);
     });
 }
+function clearRecordedAuthFailureOnSuccess() {
+    if (!stateFile || sawAuthFailure)
+        return;
+    try {
+        if (readPersistedState()?.credential?.status !== "failed")
+            return;
+        state = clearCredentialFailure(state, Date.now());
+        persistState();
+        process.stderr.write(`[multi-clawd shim] auth recovered for ${accountId} — credential exclusion cleared\n`);
+    }
+    catch {
+    }
+}
 child.on("close", (code, signal) => {
     if (signal) {
         process.kill(process.pid, signal);
         return;
     }
+    if ((code ?? 0) === 0)
+        clearRecordedAuthFailureOnSuccess();
     process.exit(code ?? 0);
 });
 child.on("error", (err) => {

package/dist/sticky.js

@@ -1,4 +1,4 @@
-import { choosePoolAccount } from "./health.js";
+import { choosePoolAccount, fallbackPoolAccount } from "./health.js";
 export const DEFAULT_MIN_DWELL_MS = 10 * 60 * 1000;
 export function decideStickySelection(params) {
     const { verdicts, sticky, nowMs } = params;
@@ -6,7 +6,7 @@ export function decideStickySelection(params) {
     const home = verdicts[0];
     const healthChoice = choosePoolAccount(verdicts);
     if (!healthChoice)
-        return { account: home.id };
+        return { account: fallbackPoolAccount(verdicts) };
     const stickyVerdict = sticky
         ? verdicts.find((v) => v.id === sticky.account)?.verdict
         : undefined;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "description": "Register additional Claude Code logins (Max/Pro accounts) as first-class OpenClaw CLI backends for cross-account failover, keeping the full skills/MCP harness on every account.",
   "cliBackends": [
     "claw1",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.7.2",
-  "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account.",
+  "version": "1.7.4",
+  "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",
   "author": "Drakon Systems Ltd",
@@ -44,6 +44,8 @@
   "files": [
     "dist",
     "scripts",
+    "!scripts/__pycache__",
+    "!**/*.py[cod]",
     "openclaw.plugin.json",
     "README.md",
     "SECURITY.md",

package/scripts/cli.mjs

@@ -5,6 +5,7 @@
  *   npx @drakon-systems/multi-clawd setup     guided setup wizard
  *   npx @drakon-systems/multi-clawd update    update to the latest version
  *   npx @drakon-systems/multi-clawd doctor    health check
+ *   npx @drakon-systems/multi-clawd hermes    sync/diagnose Hermes credentials
  *   npx @drakon-systems/multi-clawd version   versions (CLI + installed plugin)
  *
  * (Installed globally via `npm i -g @drakon-systems/multi-clawd`, the same
@@ -38,6 +39,7 @@ ${BOLD}🦞 multi-clawd${RESET} — multi-account Claude failover for OpenClaw
   ${BOLD}chain${RESET}     audit your model routing — what actually serves each turn
   ${BOLD}update${RESET}    update the plugin to the latest version
   ${BOLD}doctor${RESET}    health check (add --probe for a live turn)
+  ${BOLD}hermes${RESET}    sync or diagnose Hermes Agent's Anthropic credential pool
   ${BOLD}version${RESET}   show CLI + installed plugin versions
 
 Run via npx (${DIM}npx ${PKG} <command>${RESET}) or install globally
@@ -459,10 +461,11 @@ async function login() {
   const { readFileSync: rf, existsSync, mkdirSync, chmodSync, statSync, mkdtempSync, rmSync } =
     await import("node:fs");
   const { homedir, tmpdir } = await import("node:os");
-  let lp, ec;
+  let lp, ec, idx;
   try {
     lp = await import(resolve(__dirname, "..", "dist", "login-plan.js"));
     ec = await import(resolve(__dirname, "..", "dist", "explain-core.js"));
+    idx = await import(resolve(__dirname, "..", "dist", "index.js"));
   } catch {
     console.error("login: built dist/ is missing — reinstall the package.");
     process.exit(1);
@@ -511,6 +514,17 @@ async function login() {
     console.error(`\n  ❌ ${plan.command.join(" ")} exited with ${r.status ?? "an error"}.`);
     process.exit(1);
   }
+  // Explicit re-authentication ends any recorded runtime credential failure
+  // immediately (#8) — without this the freshly re-authed account stays
+  // benched until the 15-minute TTL expires, which reads to the operator as
+  // "logging back in did nothing".
+  try {
+    if (idx.clearAccountCredentialFailure?.(acc.id)) {
+      console.log(`\n  ↻ cleared ${acc.id}'s recorded login failure — the pool can use it again.`);
+    }
+  } catch {
+    /* clearing is a courtesy; never fail a login over it */
+  }
   if (plan.verify === "auth-status") {
     try {
       const out = spawnSync("claude", ["auth", "status"], { encoding: "utf8", env }).stdout ?? "";
@@ -554,6 +568,9 @@ switch (cmd) {
   case "doctor":
     runSibling("doctor.mjs", rest);
     break;
+  case "hermes":
+    runSibling("hermes.mjs", rest);
+    break;
   case "update":
     await update();
     break;

package/scripts/doctor.mjs

@@ -263,6 +263,20 @@ const io = {
 const accounts = pluginConfig.accounts ?? [];
 if (accounts.length === 0) warn("no accounts configured");
 for (const account of accounts) {
+  // RUNTIME credential health first: the source check below only proves a
+  // credential EXISTS, and #8 is exactly the case where a present credential
+  // is a session the Claude CLI has already rejected. A recorded runtime
+  // failure is the stronger evidence, so it is reported as such.
+  const recorded = readJson(join(STATE_DIR, `${account.id}.json`))?.credential;
+  if (recorded?.status === "failed") {
+    const ageMin = Math.round((Date.now() - recorded.seenAt) / 60000);
+    bad(
+      `${account.id}: the Claude CLI rejected this login ${ageMin}m ago${
+        recorded.reason ? ` (${recorded.reason})` : ""
+      } — excluded from the pool; fix with \`multi-clawd login ${account.id}\``,
+    );
+    continue;
+  }
   if (account.oauthTokenRef) {
     warn(`${account.id}: oauthTokenRef — validated by the gateway's async probe, not doctor`);
     continue;