@drakon-systems/multi-clawd 1.7.1 → 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**
@@ -182,6 +312,21 @@ restart, and finishes with a doctor health check.
 > plugin*, which is a confusing way to be told nothing is wrong. `multi-clawd
 > version` shows both halves, and since v1.6.0 says plainly whether the pair
 > is a problem.
+>
+> ### ⚠️ `openclaw plugins update --all` cannot move this plugin
+>
+> It will tell you the plugin is up to date when it is not. We install with
+> `--pin` (OpenClaw's own security audit raises a HIGH finding for unpinned
+> install specs, so pinning is the right side of that trade), and OpenClaw
+> resolves registry metadata *for the pinned spec* — comparing 1.6.0 against
+> 1.6.0 and returning "up to date" while a newer version sits on npm. The
+> honest "pinned to X; registry default resolves to Y" message exists in
+> OpenClaw but is built inside its `--dry-run` branch, so a real update run
+> never prints it.
+>
+> **Use `multi-clawd update`.** Since v1.7.2 `doctor` also checks the registry
+> itself (cached, and silent when offline), so a lagging plugin is reported
+> rather than left to a command that reassures you wrongly.
 
 Prefer the raw form?
 
@@ -219,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.1/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.
 
@@ -295,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):**
@@ -405,11 +549,25 @@ How it decides, per launch (all data from each account's live
 | Account state | Effect |
 |---|---|
 | `rejected` + reset in the future | skipped until `resetsAt` passes |
+| `rejected` with no reset, on a named window | skipped for an hour, then re-probed (v1.7.2) |
+| `rejected` on the `unknown` window | still used — that is where a single-model limit lands, and it must not strand the account |
 | any window utilization ≥ threshold | skipped (nearly maxed — the point of the pool) |
-| `allowed_warning` alone | still used — weekly windows warn early; only the utilization number rotates |
+| `allowed_warning` with a number below threshold | still used — trust the number |
+| `allowed_warning` and **no** number, on a short window | skipped (v1.7.2) — see below |
+| `allowed_warning` and no number, on the weekly window | still used — weekly warns from ~30% and would flap |
 | no data / stale data | used — never rotate on missing evidence |
 | whole pool exhausted | home account anyway → real limit error → your chain drops provider |
 
+**Why the short-window rule exists (v1.7.2).** The threshold rule needs a
+utilization number, and Anthropic does not send one for the 5-hour session
+window — across every observation we hold from two accounts it arrives as a
+bare status plus a reset time, while the weekly windows carry percentages. A
+rule that waits for a number therefore could never pre-empt the session
+limit: the pool would take the hit and rotate afterwards. So on hour-scoped
+windows the warning counts on its own. It stays narrow deliberately — a
+reported number always wins over the status, and a warning from a window that
+has since reset is void, exactly like a stale percentage.
+
 Notes:
 
 - Rotation happens at limit boundaries only. A mid-conversation handover
@@ -504,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

@@ -3,6 +3,17 @@ const DEFAULT_UTILIZATION_THRESHOLD = 0.85;
 const DEFAULT_STALE_AFTER_MS = 6 * 60 * 60 * 1000;
 export const MODEL_REJECTED_TTL_MS = 60 * 60 * 1000;
 const MODEL_WINDOW_PREFIX = "model:";
+const SHORT_WINDOW_PATTERN = /(^|_)hours?(_|$)/;
+export function isShortWindow(window) {
+    return SHORT_WINDOW_PATTERN.test(window);
+}
+const PERIOD_WINDOW_PATTERN = /(^|_)(minutes?|hours?|days?|weeks?|months?)(_|$)/;
+export function isPeriodWindow(window) {
+    return PERIOD_WINDOW_PATTERN.test(window);
+}
+export function isWarningStatus(status) {
+    return /warning/i.test(status);
+}
 export const MAX_RESET_HORIZON_MS = 8 * 24 * 60 * 60 * 1000;
 export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
@@ -51,13 +62,20 @@ 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,
                 reason: `${window} rejected until ${new Date(resetMs).toISOString()}`,
             };
         }
+        if (w.status === "rejected" && resetMs === undefined && isPeriodWindow(window)) {
+            return {
+                verdict: "exhausted",
+                resumeAt: w.seenAt + MODEL_REJECTED_TTL_MS,
+                reason: `${window} rejected ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; TTL block)`,
+            };
+        }
         if (worst.verdict === "ok" &&
             typeof w.utilization === "number" &&
             w.utilization >= threshold &&
@@ -67,6 +85,16 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
                 reason: `${window} utilization ${w.utilization} >= ${threshold}`,
             };
         }
+        if (worst.verdict === "ok" &&
+            typeof w.utilization !== "number" &&
+            isShortWindow(window) &&
+            isWarningStatus(w.status) &&
+            (resetBearing || resetMs === undefined)) {
+            worst = {
+                verdict: "near_limit",
+                reason: `${window} reported ${w.status} with no utilization — short window, treated as near-limit`,
+            };
+        }
     }
     if (worst.verdict === "ok" && !hasLiveEvidence)
         return { verdict: "no_data" };

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/dist/index.js

@@ -471,7 +471,7 @@ function writeStickyEntry(file, entry, logger) {
         logger.warn(`[multi-clawd] sticky state write failed: ${String(err)}`);
     }
 }
-function registerPoolBackend(api, pool, accounts, registeredIds, execMode) {
+export function registerPoolBackend(api, pool, accounts, registeredIds, execMode) {
     const logger = api.logger;
     if (!pool)
         return;

package/dist/update-core.js

@@ -57,6 +57,25 @@ export function formatCliSkew(opts) {
                 `the plugin serving your turns is behind. Fix: multi-clawd update`);
     }
 }
+export const REGISTRY_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
+export function registryCacheIsFresh(checkedAt, nowMs, ttlMs = REGISTRY_CHECK_TTL_MS) {
+    if (typeof checkedAt !== "number")
+        return false;
+    return checkedAt <= nowMs && nowMs - checkedAt < ttlMs;
+}
+export function formatRegistryLag(opts) {
+    if (!opts.installed || !opts.latest)
+        return undefined;
+    if (compareVersions(opts.installed, opts.latest) >= 0) {
+        return { level: "ok", text: `plugin v${opts.installed} is the latest published version` };
+    }
+    return {
+        level: "warn",
+        text: `plugin v${opts.installed} — npm publishes v${opts.latest}. The install is pinned, so ` +
+            `\`openclaw plugins update --all\` reports it up to date and will not move it. ` +
+            `Fix: multi-clawd update`,
+    };
+}
 export function formatUpdateBanner(opts) {
     const action = decideUpdateAction(opts);
     switch (action) {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.7.1",
+  "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.1",
-  "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;