@drakon-systems/multi-clawd 1.7.4 → 1.8.1

package/README.md

@@ -364,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.4/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.8.1/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.
 

package/dist/alerts.js

@@ -13,6 +13,9 @@ export function addAlert(state, alert, nowMs) {
 export function clearAlert(state, key) {
     return { alerts: state.alerts.filter((a) => a.key !== key) };
 }
+export function alertKeysWithPrefix(state, prefix) {
+    return state.alerts.filter((a) => a.key.startsWith(prefix)).map((a) => a.key);
+}
 function isLive(alert, nowMs) {
     const ttl = alert.ttlMs ?? DEFAULT_TTL_MS[alert.severity];
     return nowMs - alert.at <= ttl;

package/dist/credential-state.js

@@ -0,0 +1,30 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseStoredState, mergeHealthStates, clearCredentialFailure, } from "./shim-core.js";
+export function healthStateFile(accountId) {
+    return join(homedir(), ".openclaw", "state", "multi-clawd", `${accountId}.json`);
+}
+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;
+    }
+}

package/dist/health.js

@@ -16,10 +16,24 @@ const PERIOD_WINDOW_PATTERN = /(^|_)(minutes?|hours?|days?|weeks?|months?)(_|$)/
 export function isPeriodWindow(window) {
     return PERIOD_WINDOW_PATTERN.test(window);
 }
+export function isOverageWindow(window) {
+    return /overage/i.test(window);
+}
 export function isWarningStatus(status) {
     return /warning/i.test(status);
 }
 export const MAX_RESET_HORIZON_MS = 8 * 24 * 60 * 60 * 1000;
+export const PERIOD_RESET_LESS_BLOCK_MS = 6 * 60 * 60 * 1000;
+export function resetLessBlockMs(window) {
+    return isShortWindow(window) ? MODEL_REJECTED_TTL_MS : PERIOD_RESET_LESS_BLOCK_MS;
+}
+function windowAppliesToModel(w, requestedWindowKey) {
+    if (w.model === undefined)
+        return true;
+    if (requestedWindowKey === undefined)
+        return false;
+    return modelWindowKey(w.model) === requestedWindowKey;
+}
 export function credentialFailureFor(state, nowMs) {
     const credential = state?.credential;
     if (!credential || credential.status !== "failed")
@@ -43,6 +57,8 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     const requestedWindowKey = requestedModel !== undefined ? modelWindowKey(requestedModel) : undefined;
     let worst = { verdict: "ok" };
     let hasLiveEvidence = false;
+    let overageUtilization;
+    let quotaUtilization;
     for (const [window, w] of Object.entries(state.windows)) {
         const resetMs = typeof w.resetsAt === "number" ? w.resetsAt * 1000 : undefined;
         const resetBearing = resetMs !== undefined && resetMs > nowMs;
@@ -78,13 +94,17 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
                 reason: `${requestedModel} limit hit ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; TTL block)`,
             };
         }
-        const fresh = resetBearing || nowMs - w.seenAt <= staleAfterMs;
+        const ownBlockMs = w.status === "rejected" && resetMs === undefined && isPeriodWindow(window)
+            ? resetLessBlockMs(window)
+            : 0;
+        const fresh = resetBearing || nowMs - w.seenAt <= Math.max(staleAfterMs, ownBlockMs);
         if (!fresh)
             continue;
         hasLiveEvidence = true;
         if (w.status === "rejected" &&
             resetBearing &&
             isPeriodWindow(window) &&
+            windowAppliesToModel(w, requestedWindowKey) &&
             rejectionStillAssertable(w.seenAt, nowMs)) {
             return {
                 verdict: "exhausted",
@@ -92,21 +112,32 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
                 reason: `${window} rejected until ${new Date(resetMs).toISOString()}`,
             };
         }
-        if (w.status === "rejected" && resetMs === undefined && isPeriodWindow(window)) {
+        if (w.status === "rejected" &&
+            resetMs === undefined &&
+            isPeriodWindow(window) &&
+            windowAppliesToModel(w, requestedWindowKey) &&
+            nowMs - w.seenAt <= resetLessBlockMs(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)`,
+                resumeAt: w.seenAt + resetLessBlockMs(window),
+                reason: `${window} rejected ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; ${Math.round(resetLessBlockMs(window) / 3600000)}h block)`,
             };
         }
-        if (worst.verdict === "ok" &&
-            typeof w.utilization === "number" &&
+        if (typeof w.utilization === "number" &&
             w.utilization >= threshold &&
             (resetBearing || resetMs === undefined)) {
-            worst = {
-                verdict: "near_limit",
-                reason: `${window} utilization ${w.utilization} >= ${threshold}`,
-            };
+            if (isOverageWindow(window) && !options.rotateOnOverage) {
+                overageUtilization = Math.max(overageUtilization ?? 0, w.utilization);
+            }
+            else if (worst.verdict === "ok") {
+                worst = {
+                    verdict: "near_limit",
+                    reason: `${window} utilization ${w.utilization} >= ${threshold}`,
+                };
+            }
+        }
+        if (!isOverageWindow(window) && typeof w.utilization === "number") {
+            quotaUtilization = Math.max(quotaUtilization ?? 0, w.utilization);
         }
         if (worst.verdict === "ok" &&
             typeof w.utilization !== "number" &&
@@ -121,6 +152,16 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     }
     if (worst.verdict === "ok" && !hasLiveEvidence)
         return { verdict: "no_data" };
+    if (worst.verdict === "ok" && overageUtilization !== undefined) {
+        const pct = (n) => `${Math.round(n * 100)}%`;
+        worst = {
+            ...worst,
+            overageAdvisory: `paid overage is ${pct(overageUtilization)} spent while real quota is at ` +
+                `${quotaUtilization !== undefined ? pct(quotaUtilization) : "an unreported level"} — ` +
+                `not rotating on spill-over alone. Set pool.rotateOnOverage: true to rotate on it, ` +
+                `or leave it to keep using the overage you have paid for.`,
+        };
+    }
     return worst;
 }
 export function summarizeWindowUsage(state, options, nowMs) {

package/dist/index.js

@@ -11,10 +11,12 @@ import { resolveExecMode, permissionModeArgs } from "./exec-policy.js";
 import { resolveBaseModelIds } from "./catalog-source.js";
 import { allCredentialFailed, classifyAccountHealth } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
-import { clearCredentialFailure, mergeHealthStates, parseStoredState, recordCredentialFailure, } from "./shim-core.js";
+import { 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";
+import { addAlert, alertKeysWithPrefix, clearAlert, pendingAlertText, } from "./alerts.js";
+import { healthStateFile, clearAccountCredentialFailure } from "./credential-state.js";
+export { healthStateFile, clearAccountCredentialFailure };
 import { buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
 import { diffCatalogModels, formatNewModelNotice, } from "./model-currency.js";
 import { checkAccountCredential, createRefProbeTracker, } from "./login-health.js";
@@ -69,6 +71,10 @@ let loginProbeTimer;
 function raiseAlert(alert) {
     alertState = addAlert(alertState, alert, Date.now());
 }
+export function pendingOperatorAlerts(nowMs) {
+    ingestAlertSpool();
+    return pendingAlertText(alertState, nowMs);
+}
 function ingestAlertSpool() {
     const spool = join(homedir(), ".openclaw", "state", "multi-clawd", "alerts-spool.jsonl");
     let raw;
@@ -281,9 +287,6 @@ function buildRuntimeModel(account, modelId) {
     };
 }
 const SHIM_PATH = fileURLToPath(new URL("./shim.js", import.meta.url));
-export function healthStateFile(accountId) {
-    return join(homedir(), ".openclaw", "state", "multi-clawd", `${accountId}.json`);
-}
 function knownModelsFile() {
     return join(homedir(), ".openclaw", "state", "multi-clawd", "known-models.json");
 }
@@ -476,8 +479,7 @@ export default definePluginEntry({
             const logger = api.logger;
             try {
                 api.on("heartbeat_prompt_contribution", () => {
-                    ingestAlertSpool();
-                    const text = pendingAlertText(alertState, Date.now());
+                    const text = pendingOperatorAlerts(Date.now());
                     return text ? { appendContext: text } : undefined;
                 });
             }
@@ -497,32 +499,6 @@ 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"));
@@ -576,6 +552,7 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     const options = {
         utilizationThreshold: pool.utilizationThreshold,
         staleAfterMs: pool.staleAfterMs,
+        rotateOnOverage: pool.rotateOnOverage,
     };
     const poolAccount = {
         id: poolId,
@@ -589,9 +566,10 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     backend.prepareExecution = async (ctx) => {
         const now = Date.now();
         const requestedModel = canonicalModelId(ctx.modelId) ?? ctx.modelId;
-        const verdicts = members.map((a) => ({
-            id: a.id,
-            health: classifyAccountHealth(readHealthState(a.id), options, now, requestedModel),
+        const states = members.map((a) => ({ id: a.id, state: readHealthState(a.id) }));
+        const verdicts = states.map(({ id, state }) => ({
+            id,
+            health: classifyAccountHealth(state, options, now, requestedModel),
         }));
         if (allCredentialFailed(verdicts.map((v) => ({ id: v.id, verdict: v.health.verdict })))) {
             const detail = verdicts
@@ -621,13 +599,33 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             logger.info(`[multi-clawd] ${line}`);
             raiseAlert({ key: `rotation:${poolId}`, severity: "info", text: line });
         }
+        const exhaustionPrefix = `pool-exhausted:${poolId}:`;
+        for (const key of alertKeysWithPrefix(alertState, exhaustionPrefix)) {
+            const alertedModel = key.slice(exhaustionPrefix.length);
+            const stillExhausted = states.every(({ state }) => classifyAccountHealth(state, options, now, alertedModel).verdict === "exhausted");
+            if (!stillExhausted)
+                alertState = clearAlert(alertState, key);
+        }
         if (verdicts.every((v) => v.health.verdict === "exhausted")) {
             raiseAlert({
-                key: `pool-exhausted:${poolId}:${requestedModel}`,
+                key: `${exhaustionPrefix}${requestedModel}`,
                 severity: "error",
                 text: `pool ${poolId}: every account is exhausted for ${requestedModel} — turns are degrading or falling through the chain`,
             });
         }
+        for (const v of verdicts) {
+            const key = `overage:${poolId}:${v.id}`;
+            if (v.health.overageAdvisory) {
+                raiseAlert({
+                    key,
+                    severity: "info",
+                    text: `pool ${poolId}: account "${v.id}" — ${v.health.overageAdvisory}`,
+                });
+            }
+            else {
+                alertState = clearAlert(alertState, key);
+            }
+        }
         for (const v of verdicts) {
             const key = `credential:${poolId}:${v.id}`;
             if (v.health.verdict === "credential_failed") {

package/dist/shim-core.js

@@ -89,6 +89,7 @@ export function parseStoredState(raw) {
             isUsingOverage: typeof w.isUsingOverage === "boolean" ? w.isUsingOverage : undefined,
             seenAt: w.seenAt,
             rawInfo: typeof w.rawInfo === "string" ? w.rawInfo : undefined,
+            model: typeof w.model === "string" ? w.model : undefined,
         };
     }
     let credential;
@@ -291,7 +292,7 @@ export function clearCredentialFailure(state, now) {
         credential: { status: "ok", seenAt: now },
     };
 }
-export function updateHealthState(state, event, now) {
+export function updateHealthState(state, event, now, model) {
     const key = event.rateLimitType ?? "unknown";
     return {
         ...state,
@@ -305,6 +306,7 @@ export function updateHealthState(state, event, now) {
                 isUsingOverage: event.isUsingOverage,
                 seenAt: now,
                 rawInfo: event.rawInfo,
+                model: model === undefined ? undefined : canonicalizeModelIdForWindow(model),
             },
         },
     };

package/dist/shim.js

@@ -113,7 +113,7 @@ const scanner = createLineScanner((line) => {
     try {
         const event = parseRateLimitEvent(line);
         if (event) {
-            state = updateHealthState(state, event, Date.now());
+            state = updateHealthState(state, event, Date.now(), effectiveModelId());
             persistState();
         }
         const limitHit = parseModelLimitError(line);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.7.4",
+  "version": "1.8.1",
   "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",
@@ -51,6 +51,10 @@
             "type": "number",
             "description": "Ignore health data older than this. Default 21600000 (6h)."
           },
+          "rotateOnOverage": {
+            "type": "boolean",
+            "description": "Rotate when the seven_day_overage_included window (quota PLUS purchased spill-over) crosses utilizationThreshold. Default false: high utilization there means little paid overage left, not little quota left, so the pool keeps using the overage you have paid for and raises an operator alert instead of deciding for you."
+          },
           "minDwellMs": {
             "type": "number",
             "description": "After rotating away from home, stay on the rotated-to account at least this long before returning home (anti-flap hysteresis; health always overrides). Default 600000 (10min)."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.7.4",
+  "version": "1.8.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. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",

package/scripts/cli.mjs

@@ -16,7 +16,7 @@
  * has to remember `--pin --force`.
  */
 import { execFileSync, spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync as existsSyncEarly } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import readline from "node:readline/promises";
@@ -92,6 +92,34 @@ async function askYes(question, dflt = true) {
 }
 
 /** This package's own version (the CLI half). */
+/**
+ * Why a `dist/` import failed, in the user's terms.
+ *
+ * The bare "reinstall the package" message was wrong in the one case that
+ * actually happens: this CLI installs globally, `openclaw` is a peerDependency,
+ * and on a box where the peer is not resolvable from this directory a perfectly
+ * complete build still throws ERR_MODULE_NOT_FOUND. Reinstalling cannot fix
+ * that, so "reinstall the package" sends people in circles — it did, on a Mac,
+ * 18 Aug 2026. Check the file exists first, then report the real cause.
+ */
+function distFailure(cmd, mod, err) {
+  const path = resolve(__dirname, "..", "dist", mod);
+  if (!existsSyncEarly(path)) {
+    return `${cmd}: built dist/${mod} is missing — reinstall the package.`;
+  }
+  const missingPeer = /Cannot find package '([^']+)'/.exec(String(err?.message ?? ""));
+  if (missingPeer) {
+    const peer = missingPeer[1];
+    return [
+      `${cmd}: dist/${mod} is present but cannot load — the "${peer}" package is not`,
+      `resolvable from this install (${resolve(__dirname, "..")}).`,
+      `Install "${peer}" globally alongside this CLI, or run the CLI with npx from a`,
+      `directory where "${peer}" resolves.`,
+    ].join("\n  ");
+  }
+  return `${cmd}: dist/${mod} failed to load — ${err?.message ?? err}`;
+}
+
 function cliVersion() {
   return JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf8")).version;
 }
@@ -134,8 +162,8 @@ async function chain(args = []) {
   let ca;
   try {
     ca = await import(resolve(__dirname, "..", "dist", "chain-audit.js"));
-  } catch {
-    console.error("chain: built dist/ is missing — reinstall the package.");
+  } catch (err) {
+    console.error(distFailure("chain", "chain-audit.js", err));
     process.exit(1);
   }
 
@@ -227,8 +255,8 @@ async function update() {
   let uc;
   try {
     uc = await import(resolve(__dirname, "..", "dist", "update-core.js"));
-  } catch {
-    console.error("update: built dist/ is missing — reinstall the package.");
+  } catch (err) {
+    console.error(distFailure("update", "update-core.js", err));
     process.exit(1);
   }
   console.log(`\n${BOLD}🦞 multi-clawd update${RESET}\n`);
@@ -391,8 +419,8 @@ async function explain() {
     ec = await import(resolve(__dirname, "..", "dist", "explain-core.js"));
     health = await import(resolve(__dirname, "..", "dist", "health.js"));
     shim = await import(resolve(__dirname, "..", "dist", "shim-core.js"));
-  } catch {
-    console.error("explain: built dist/ is missing — reinstall the package.");
+  } catch (err) {
+    console.error(distFailure("explain", "explain-core.js", err));
     process.exit(1);
   }
   let config = {};
@@ -465,9 +493,12 @@ async function login() {
   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.");
+    // credential-state.js, NOT index.js: this is the one call login needs from
+    // the plugin side, and index.js drags in the `openclaw` peer, which is not
+    // resolvable from a global CLI install on every machine.
+    idx = await import(resolve(__dirname, "..", "dist", "credential-state.js"));
+  } catch (err) {
+    console.error(distFailure("login", "login-plan.js", err));
     process.exit(1);
   }
   let config = {};