@drakon-systems/multi-clawd 1.7.2 → 1.7.3

package/README.md

@@ -54,6 +54,136 @@ install anything? Every command also runs as
 
 Then `multi-clawd explain` shows you exactly what you built.
 
+## Hermes Agent integration
+
+multi-clawd can also import the configured Claude subscriptions into Hermes
+Agent's native Anthropic credential pool. Install and set up
+[Hermes Agent](https://hermes-agent.nousresearch.com/docs/) first, keep
+`hermes` on `PATH`, then preview and apply the import:
+
+```bash
+multi-clawd hermes sync --dry-run
+multi-clawd hermes sync --strategy round_robin
+multi-clawd hermes doctor
+
+# An existing Hermes profile (create it first: hermes profile create work):
+multi-clawd hermes sync --profile work --strategy least_used
+
+# Read a non-default OpenClaw configuration:
+multi-clawd hermes doctor --config ~/configs/openclaw.json
+```
+
+Validated against Hermes Agent **0.19.1**.
+
+### Only stable setup tokens are imported
+
+The one credential this adapter will copy is an account's `oauthTokenFile` — a
+plain `claude setup-token` value, the same string multi-clawd already passes to
+Claude Code as `CLAUDE_CODE_OAUTH_TOKEN`. It carries no refresh token and
+nothing rotates it, so a second copy in Hermes stays valid.
+
+Everything else is refused, on purpose:
+
+- **`native` logins are not importable, but need nothing imported.** A native
+  login is a `.credentials.json` file holding a *rotating* OAuth grant whose
+  refresh token is single-use, so copying it into Hermes and the next refresh —
+  by Claude Code, or by Hermes itself — would invalidate the other copy, which
+  Hermes then marks dead and drops from rotation. It doesn't need copying
+  anyway: Hermes' own `claude_code` credential source already reads that exact
+  same native `~/.claude/.credentials.json` directly, so leave a native account
+  on that source instead of duplicating the grant.
+- **`configDir` logins are not importable, and Hermes cannot be pointed at
+  them either.** The same single-use-refresh-token problem applies, and unlike
+  a native login there is no Hermes-side fallback: as of Hermes Agent 0.19.1,
+  its `claude_code` credential source reads only the native path above, never
+  an arbitrary `configDir`. A `configDir` account can only reach Hermes' pool
+  by getting its own `oauthTokenFile` (a `claude setup-token`, same as above),
+  or it stays OpenClaw-only.
+- **`oauthTokenRef` is never resolved.** Reading a gateway secret reference
+  here would turn a reference into a copied plaintext secret in a second store;
+  the adapter fails closed and says so. An account may carry a `configDir`
+  alongside its `oauthTokenFile` — it is simply ignored for Hermes.
+
+`doctor` names every account it cannot import and why; `sync` refuses to write
+anything until they are fixed or removed. **Re-run `sync` whenever a
+setup-token file changes** — nothing propagates a new token automatically.
+
+### What sync does
+
+Accounts are read from `plugins.entries["multi-clawd"].config.accounts` in
+`~/.openclaw/openclaw.json` by default. Every account is validated and every
+token file read and parsed before Hermes is asked to write anything.
+
+- Only deterministic rows labelled `multi-clawd:<account-id>` are added or
+  updated, and only those rows are sent to Hermes — it merges them into the
+  pool under its own lock, so unrelated credentials are never read, copied, or
+  rewritten. The operation is idempotent.
+- Row priority follows your `pool.accounts` preference order (home account
+  first), which is the order Hermes' `fill_first` drains in. Accounts absent
+  from `pool.accounts` follow in `accounts[]` order.
+- `--strategy` sets Hermes' Anthropic pool strategy to one of `fill_first`,
+  `round_robin`, `random`, `least_used`. **Omit it and your configured strategy
+  is left alone** (`fill_first` only when nothing is set at all).
+- `--dry-run` runs the same validation and planning and writes nothing.
+- Planning always reads the target home's *own* pool. A Hermes profile with no
+  Anthropic rows yet falls back to reading the global pool — `doctor` labels
+  that as an effective-only view, and sync never copies those rows into the
+  profile.
+- Named profiles must already exist; the adapter never creates one, so a
+  deleted profile is not resurrected as an empty skeleton. Run
+  `hermes profile create <name>` first. The target home is whatever Hermes
+  itself reports as its root (via its own `hermes_constants` module) — never
+  reimplemented here — which is `~/.hermes` on POSIX, `%LOCALAPPDATA%\hermes`
+  on native Windows, or a Docker/custom `HERMES_HOME` root; a named profile is
+  `<root>/profiles/<name>`. `--profile default` always targets that root, even
+  when the active `HERMES_HOME` currently points at another profile.
+- Only multi-clawd's own broken state (duplicate or malformed managed rows)
+  blocks a sync. Several `claude_code` rows, or another tool's malformed row,
+  are reported as warnings — they are legitimate states and not this plugin's
+  to fix.
+
+The pool and the config are two separate Hermes files. Each write is atomic on
+its own and both are verified by re-reading afterwards; the pair is not atomic,
+so the pool is written first and both are idempotent — an interruption between
+them leaves a state that re-running `sync` repairs, rather than one needing a
+rollback.
+
+### What this integration is (and is not)
+
+Hermes talks to the **native Anthropic Messages API** with Hermes' own tool
+system. It does not run the OpenClaw plugin backend or the Claude Code harness,
+so OpenClaw skills/MCP wiring and Claude Code's built-in harness are not copied
+across. multi-clawd supplies the account credentials and the configured Hermes
+pool distribution only. Hermes then provides native reactive failover and the
+selected distribution strategy. Proactive near-limit telemetry/rotation from
+multi-clawd's OpenClaw pool is **not implemented for Hermes yet**.
+
+### Security model
+
+Tokens are read from real files with strict size limits, parsed locally, and
+sent to the bundled Python bridge only as one JSON document on **stdin**. They
+are never placed in argv, exported as environment variables, or printed to
+stdout/stderr — no token, no prefix, no fingerprint — and command errors use
+fixed safe messages. On POSIX, a token source file must be private —
+group/other-readable or -writable (any `chmod` bits beyond `600`) is refused
+outright, not just warned about, checked via `fstat` on the already-open file
+descriptor so there is no gap between the check and the read (Windows has no
+equivalent bit layout, so the check is a no-op there; the config JSON is read
+through the same code path but never needs to be private). The bridge uses
+Hermes' installed Python APIs directly (no shell-string execution), writes
+only inside the selected `HERMES_HOME`, and never echoes identifiers or other
+fields belonging to a row it doesn't manage — an unrelated row is reported by
+position only, even when its own source/label/status fields are stuffed with
+a token-like string. Paths reject NUL bytes, expand only a leading `~/`, and
+profile names cannot contain traversal or separators.
+
+`doctor` validates files, account configuration, and the shape of Hermes' pool
+and config on disk — it makes **no live request to Anthropic** and cannot
+prove a setup token is still accepted. A token can pass every doctor check and
+still be expired or revoked; that is discovered at runtime, where Hermes' own
+native 401/429 handling takes over exactly as it does for any other credential
+in its pool.
+
 ## Why
 
 OpenClaw's bundled `claude-cli` backend runs Claude Code on a **single**
@@ -234,7 +364,7 @@ openclaw plugins install (Get-Location).Path
 **Or let your agent install it.** Running an OpenClaw assistant or Claude
 Code on the target machine already? Paste it this and go make coffee:
 
-> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.7.2/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.7.3/SETUP-AGENT.md
 > and follow it to set up multi-clawd on this machine. I own a second
 > Claude account — ask me when you need me to log in.
 
@@ -310,9 +440,8 @@ dir* — a separate Claude "app" — so the logins can never clobber each other.
 
    ```bash
    mkdir -p ~/.claw2 && chmod 700 ~/.claw2
-   CLAUDE_CONFIG_DIR=~/.claw2 claude setup-token   # log in as the 2nd account
-   # store the token where the plugin can read it (0600):
-   #   ~/.claw2/oauth-token
+   CLAUDE_CONFIG_DIR=~/.claw2 claude setup-token > ~/.claw2/oauth-token   # log in as the 2nd account
+   chmod 600 ~/.claw2/oauth-token
    ```
 
    **Windows (native, PowerShell):**
@@ -533,6 +662,14 @@ Housekeeping:
 - Prefer a secret reference (`oauthTokenRef`, v0.3) over a plaintext
   file; when a file is used, keep it `0600` (POSIX) or locked to your user
   with `icacls` (Windows).
+- **Credential resolution fails closed (v1.7.3).** An account that declares
+  `oauthTokenRef` or `oauthTokenFile` is authenticated by that token. If it
+  resolves to nothing — provider briefly unavailable, empty secret, truncated
+  file — and the account has no `configDir` to fall back on, the launch is
+  refused with `declares a token source but none resolved` rather than
+  allowed to proceed on the machine's default login and spend a different
+  account's quota under this account's name. Native accounts are exempt: the
+  default login *is* their credential.
 - Migrating a token file into a vault? `op read` (and most secret CLIs)
   append a trailing newline on output — resolution trims the resolved
   value (guaranteed in `token-resolution.ts`), so a file-vs-vault diff

package/dist/account-env.js

@@ -12,11 +12,17 @@ export function buildAccountChildEnv(account, token, stateFile) {
         MULTI_CLAWD_ACCOUNT_ID: account.id,
         MULTI_CLAWD_STATE_FILE: stateFile,
     };
-    if (token)
-        env.CLAUDE_CODE_OAUTH_TOKEN = token;
+    const usableToken = token?.trim() ? token : undefined;
+    if (usableToken)
+        env.CLAUDE_CODE_OAUTH_TOKEN = usableToken;
     if (!account.native && account.configDir) {
         env.CLAUDE_CONFIG_DIR = expandHomePath(account.configDir);
     }
+    const declaresToken = Boolean(account.oauthTokenFile) || Boolean(account.oauthTokenRef);
+    if (!account.native && declaresToken && !usableToken && !account.configDir) {
+        throw new Error(`[multi-clawd] account "${account.id}" declares a token source but none resolved — ` +
+            `refusing to launch on the default login`);
+    }
     return env;
 }
 export function tokenFileModeWarning(path, mode) {

package/dist/chain-audit.js

@@ -25,7 +25,7 @@ function parseRef(ref) {
     const idx = ref.indexOf("/");
     if (idx < 0)
         return { modelId: ref };
-    return { provider: ref.slice(0, idx), modelId: ref.slice(idx + 1) };
+    return { provider: ref.slice(0, idx).trim().toLowerCase(), modelId: ref.slice(idx + 1) };
 }
 export function offPoolClaudeRef(ref, poolId) {
     if (typeof ref !== "string" || ref.length === 0)
@@ -35,7 +35,7 @@ export function offPoolClaudeRef(ref, poolId) {
         return null;
     if (provider === undefined)
         return null;
-    if (provider === poolId)
+    if (provider === poolId.trim().toLowerCase())
         return null;
     if (provider === "anthropic" || provider === "claude-cli")
         return "strong";

package/dist/health.js

@@ -62,7 +62,7 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
         if (!fresh)
             continue;
         hasLiveEvidence = true;
-        if (w.status === "rejected" && resetBearing) {
+        if (w.status === "rejected" && resetBearing && isPeriodWindow(window)) {
             return {
                 verdict: "exhausted",
                 resumeAt: resetMs,

package/dist/hermes-core.js

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+export const HERMES_MANAGED_ID_PREFIX = "multi-clawd-";
+export const HERMES_MANAGED_SOURCE = "manual:multi-clawd";
+export const HERMES_SUPPORTED_STRATEGIES = [
+    "fill_first",
+    "round_robin",
+    "random",
+    "least_used",
+];
+export const HERMES_DEFAULT_STRATEGY = "fill_first";
+export const HERMES_MAX_SETUP_TOKEN_BYTES = 8 * 1024;
+export class HermesAdapterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HermesAdapterError";
+    }
+}
+const PROFILE_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const ACCOUNT_RE = PROFILE_RE;
+const RESERVED_PROFILES = new Set(["hermes", "test", "tmp", "root", "sudo"]);
+const SETUP_TOKEN_RE = /^sk-ant-oat\d{2,}-[!-~]+$/;
+const API_KEY_PREFIX = "sk-ant-api";
+const NATIVE_SETUP_TOKEN_GUIDANCE = "add an oauthTokenFile holding a `claude setup-token` value, or let Hermes read the native " +
+    "login itself — its own claude_code credential source reads ~/.claude/.credentials.json directly";
+const CONFIGDIR_SETUP_TOKEN_GUIDANCE = "Hermes' claude_code credential source only reads the native ~/.claude/.credentials.json, never " +
+    "an arbitrary configDir, so this account cannot be pointed at Hermes directly — add its own " +
+    "oauthTokenFile holding a `claude setup-token` value, or leave it OpenClaw-only";
+function fail(code, message) {
+    throw new HermesAdapterError(code, message);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function optionalNonEmptyString(value, code) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || !value.trim())
+        fail(code, "account configuration is malformed");
+    return value.trim();
+}
+export function validateHermesStrategy(value) {
+    if (typeof value !== "string") {
+        fail("invalid_strategy", `strategy must be one of: ${HERMES_SUPPORTED_STRATEGIES.join(", ")}`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!HERMES_SUPPORTED_STRATEGIES.includes(normalized)) {
+        fail("invalid_strategy", `strategy must be one of: ${HERMES_SUPPORTED_STRATEGIES.join(", ")}`);
+    }
+    return normalized;
+}
+export function validateHermesProfileName(value) {
+    if (typeof value !== "string")
+        fail("invalid_profile", "profile name is invalid");
+    const normalized = value.trim().toLowerCase();
+    if (!PROFILE_RE.test(normalized) || (normalized !== "default" && RESERVED_PROFILES.has(normalized))) {
+        fail("invalid_profile", "profile name must be a safe Hermes profile identifier");
+    }
+    return normalized;
+}
+export function validateHermesAccount(value) {
+    const row = asRecord(value);
+    if (!row || typeof row.id !== "string" || !row.id.trim()) {
+        fail("malformed_account", "account configuration is malformed");
+    }
+    const oauthTokenRef = asRecord(row.oauthTokenRef);
+    if (row.oauthTokenRef !== undefined && !oauthTokenRef) {
+        fail("malformed_account", "account configuration is malformed");
+    }
+    return {
+        id: row.id.trim().toLowerCase(),
+        label: optionalNonEmptyString(row.label, "malformed_account"),
+        native: row.native === true || undefined,
+        configDir: optionalNonEmptyString(row.configDir, "malformed_account"),
+        oauthTokenFile: optionalNonEmptyString(row.oauthTokenFile, "malformed_account"),
+        oauthTokenRef,
+    };
+}
+export function describeHermesAccountSupport(account) {
+    if (!ACCOUNT_RE.test(account.id)) {
+        return {
+            supported: false,
+            code: "unsupported_account_id",
+            reason: "account id must be lowercase letters, digits, '_' or '-' (max 64 chars) to become a Hermes credential id",
+        };
+    }
+    if (account.oauthTokenFile)
+        return { supported: true };
+    if (account.native) {
+        return {
+            supported: false,
+            code: "native_not_supported",
+            reason: "a native Claude login is a rotating single-use grant, unsafe to duplicate — " +
+                NATIVE_SETUP_TOKEN_GUIDANCE,
+        };
+    }
+    if (account.oauthTokenRef) {
+        return {
+            supported: false,
+            code: "secret_ref_not_supported",
+            reason: "oauthTokenRef is never resolved here — a secret reference must not be turned into a " +
+                `copied plaintext secret; ${NATIVE_SETUP_TOKEN_GUIDANCE}`,
+        };
+    }
+    if (account.configDir) {
+        return {
+            supported: false,
+            code: "setup_token_file_required",
+            reason: "a configDir login is a rotating single-use grant, unsafe to duplicate, and " +
+                CONFIGDIR_SETUP_TOKEN_GUIDANCE,
+        };
+    }
+    return {
+        supported: false,
+        code: "setup_token_file_required",
+        reason: `no importable Hermes credential source — ${NATIVE_SETUP_TOKEN_GUIDANCE}`,
+    };
+}
+export function collectHermesAccounts(values) {
+    if (!Array.isArray(values) || values.length === 0) {
+        fail("no_accounts", "no multi-clawd accounts are configured");
+    }
+    const accounts = [];
+    const unsupported = [];
+    const seen = new Set();
+    for (const value of values) {
+        const account = validateHermesAccount(value);
+        if (seen.has(account.id)) {
+            unsupported.push({
+                id: account.id,
+                code: "duplicate_account",
+                reason: "duplicate account id — remove the repeated entry from the OpenClaw config",
+            });
+            continue;
+        }
+        seen.add(account.id);
+        const support = describeHermesAccountSupport(account);
+        if (support.supported)
+            accounts.push(account);
+        else
+            unsupported.push({ id: account.id, code: support.code, reason: support.reason });
+    }
+    return { accounts, unsupported };
+}
+export function hermesAccountPriorities(pluginConfig, accounts) {
+    const known = new Set(accounts.map((account) => account.id));
+    const ordered = [];
+    const push = (raw) => {
+        if (typeof raw !== "string")
+            return;
+        const id = raw.trim().toLowerCase();
+        if (!known.has(id) || ordered.includes(id))
+            return;
+        ordered.push(id);
+    };
+    const config = asRecord(pluginConfig);
+    const pools = Array.isArray(config?.pool) ? config.pool : [config?.pool];
+    for (const entry of pools) {
+        const preference = asRecord(entry)?.accounts;
+        if (Array.isArray(preference))
+            for (const id of preference)
+                push(id);
+    }
+    for (const account of accounts)
+        push(account.id);
+    return new Map(ordered.map((id, index) => [id, index]));
+}
+export function chooseHermesCredentialSource(accountValue, candidates) {
+    const account = validateHermesAccount(accountValue);
+    const support = describeHermesAccountSupport(account);
+    if (!support.supported)
+        fail(support.code, support.reason);
+    if (!candidates.oauthTokenFilePath) {
+        fail("setup_token_file_required", `no importable Hermes credential source — ${NATIVE_SETUP_TOKEN_GUIDANCE}`);
+    }
+    if (!candidates.existingPaths.includes(candidates.oauthTokenFilePath)) {
+        fail("setup_token_file_missing", "the configured oauthTokenFile does not exist");
+    }
+    return { kind: "oauthTokenFile", path: candidates.oauthTokenFilePath };
+}
+export function parseClaudeSetupToken(text) {
+    if (typeof text !== "string" || Buffer.byteLength(text, "utf8") > HERMES_MAX_SETUP_TOKEN_BYTES) {
+        fail("malformed_setup_token", "the setup-token file is unreadable or too large");
+    }
+    const lines = text.split("\n");
+    if (lines.length > 1 && lines[lines.length - 1] === "")
+        lines.pop();
+    if (lines.length !== 1) {
+        fail("malformed_setup_token", "the setup-token file must hold exactly one line");
+    }
+    let token = lines[0];
+    if (token.endsWith("\r"))
+        token = token.slice(0, -1);
+    if (!token)
+        fail("malformed_setup_token", "the setup-token file is empty");
+    if (token.startsWith("{") || token.startsWith("[")) {
+        fail("rotating_grant_not_supported", "that file holds a JSON Claude credentials grant, not a setup token — rotating grants are " +
+            "single-use and unsafe to duplicate. If this is your native ~/.claude login, it needs no " +
+            "copy at all — Hermes' own claude_code credential source already reads that file directly. " +
+            "A configDir login has no such fallback (claude_code cannot be pointed at a configDir) and " +
+            "needs its own oauthTokenFile setup token instead");
+    }
+    if (token.startsWith(API_KEY_PREFIX)) {
+        fail("malformed_setup_token", "that looks like a Claude API key, not a setup token — setup tokens start with sk-ant-oat");
+    }
+    if (!SETUP_TOKEN_RE.test(token)) {
+        fail("malformed_setup_token", "the setup token does not match the expected sk-ant-oat… shape");
+    }
+    return token;
+}
+export function stableHermesCredentialId(accountId) {
+    const account = validateHermesAccount({ id: accountId });
+    if (!ACCOUNT_RE.test(account.id)) {
+        fail("unsupported_account_id", "account id cannot be turned into a Hermes credential id");
+    }
+    const digest = createHash("sha256").update(`multi-clawd/hermes/${account.id}`, "utf8").digest("hex");
+    return `${HERMES_MANAGED_ID_PREFIX}${digest.slice(0, 16)}`;
+}
+export function buildHermesManagedCredential(accountValue, setupToken, priority) {
+    const account = validateHermesAccount(accountValue);
+    if (typeof setupToken !== "string" || !setupToken) {
+        fail("malformed_setup_token", "the setup token is missing");
+    }
+    if (!Number.isSafeInteger(priority) || priority < 0) {
+        fail("invalid_priority", "credential priority must be a non-negative integer");
+    }
+    return {
+        accountId: account.id,
+        id: stableHermesCredentialId(account.id),
+        label: `multi-clawd:${account.id}`,
+        source: HERMES_MANAGED_SOURCE,
+        authType: "oauth",
+        accessToken: setupToken,
+        priority,
+    };
+}
+export function buildHermesBridgeRequest(input) {
+    if (!["probe", "doctor", "apply"].includes(input.operation)) {
+        fail("unsupported_operation", "operation must be probe, doctor, or apply");
+    }
+    if (typeof input.targetHome !== "string" || !input.targetHome) {
+        fail("invalid_target_home", "the target Hermes home is invalid");
+    }
+    const request = {
+        operation: input.operation,
+        targetHome: input.targetHome,
+    };
+    if (input.operation !== "apply")
+        return request;
+    request.dryRun = input.dryRun === true;
+    request.credentials = (input.credentials ?? []).map((credential) => ({ ...credential }));
+    if (input.strategy !== undefined)
+        request.strategy = validateHermesStrategy(input.strategy);
+    return request;
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "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.3",
+  "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
@@ -554,6 +556,9 @@ switch (cmd) {
   case "doctor":
     runSibling("doctor.mjs", rest);
     break;
+  case "hermes":
+    runSibling("hermes.mjs", rest);
+    break;
   case "update":
     await update();
     break;