@drakon-systems/multi-clawd 2.5.0 → 2.5.1

package/README.md

@@ -415,7 +415,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/v2.5.0/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.5.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.
 
@@ -633,7 +633,14 @@ a gateway reload. A turn already admitted or running continues on its selected
 account; the command does not interrupt it.
 
 `pool.strategy` defaults to `"ordered"`, which retains the configured account
-order. Set it to `"reset-aware"` to use healthy weekly quota before its
+order. In every strategy, when no `ok` or `no_data` account is left but some
+are near their limit, the launch goes to the near-limit account with the most
+headroom: the lowest fresh utilization, taking the newer of the stream and
+usage-poll records for each window. Equal figures keep pool order, an account
+with a figure outranks one without, and two without keep pool order.
+Exhausted and credential-failed accounts are never chosen. `explain` says
+"all near limit, picked X at N%" and the direct Anthropic route orders its
+near-limit profiles the same way. Set it to `"reset-aware"` to use healthy weekly quota before its
 `seven_day` window resets: among `ok` accounts with live seven-day reset data,
 the soonest reset wins. Accounts without that data follow in pool order;
 near-limit or exhausted accounts never outrank a healthy one. Equal reset
@@ -687,6 +694,7 @@ How it decides, per launch (all data from each account's live
 | `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 |
+| every usable account near its limit | the near-limit account with the most headroom (lowest fresh utilization) serves; equal figures and accounts without a number keep pool order |
 | whole pool exhausted | home account anyway → real limit error → your chain drops provider |
 
 **Why the short-window rule exists (v1.7.2).** (v1.10's live usage poll now

package/dist/direct-report.js

@@ -27,11 +27,13 @@ export async function gatherDirectStatus(params) {
         : undefined;
     const verdicts = members.map((m) => {
         const state = params.readHealth(m.accountId);
+        const health = classifyAccountHealth(state, params.healthOptions, params.nowMs);
         return {
             accountId: m.accountId,
             profileId: m.profileId,
             disabled: m.disabled,
-            verdict: classifyAccountHealth(state, params.healthOptions, params.nowMs).verdict,
+            verdict: health.verdict,
+            utilization: health.utilization,
             sevenDayResetsAt: params.strategy === "reset-aware"
                 ? sevenDayReset(state, params.healthOptions, params.nowMs)
                 : undefined,

package/dist/direct-route.js

@@ -1,4 +1,5 @@
 import { isSecretRefShape } from "./token-resolution.js";
+import { headroomBefore } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
 import { spreadBefore } from "./spread.js";
 export const DIRECT_PROVIDER = "anthropic";
@@ -135,7 +136,7 @@ export function planDirectOrder(params) {
     if (members.length === 0)
         throw new Error("pool.accounts[].disabled: every direct member is disabled");
     const decision = decideStickySelection({
-        verdicts: members.map((m) => ({ id: m.accountId, verdict: m.verdict, sevenDayResetsAt: m.sevenDayResetsAt, servedInWindow: m.servedInWindow, lastServedAt: m.lastServedAt })),
+        verdicts: members.map((m) => ({ id: m.accountId, verdict: m.verdict, sevenDayResetsAt: m.sevenDayResetsAt, utilization: m.utilization, servedInWindow: m.servedInWindow, lastServedAt: m.lastServedAt })),
         sticky: params.sticky,
         nowMs: params.nowMs,
         minDwellMs: params.minDwellMs,
@@ -151,6 +152,9 @@ export function planDirectOrder(params) {
             : 0) ||
         (params.strategy === "spread" && VERDICT_RANK[a.m.verdict] === 0
             ? (spreadBefore(a.m, b.m) ? -1 : spreadBefore(b.m, a.m) ? 1 : 0)
+            : 0) ||
+        (a.m.verdict === "near_limit" && b.m.verdict === "near_limit"
+            ? (headroomBefore(a.m, b.m) ? -1 : headroomBefore(b.m, a.m) ? 1 : 0)
             : 0) || a.index - b.index)
         .map(({ m }) => m.profileId);
     const managed = new Set(params.members.map((m) => m.profileId));

package/dist/direct-sync.js

@@ -253,11 +253,13 @@ export function createDirectOrderController(deps) {
                     : undefined;
                 const verdicts = deps.members.map((m) => {
                     const state = deps.readHealth(m.accountId);
+                    const health = classifyAccountHealth(state, deps.healthOptions, nowMs);
                     return {
                         accountId: m.accountId,
                         profileId: m.profileId,
                         disabled: m.disabled,
-                        verdict: classifyAccountHealth(state, deps.healthOptions, nowMs).verdict,
+                        verdict: health.verdict,
+                        utilization: health.utilization,
                         sevenDayResetsAt: deps.strategy === "reset-aware"
                             ? sevenDayReset(state, deps.healthOptions, nowMs)
                             : undefined,

package/dist/explain-core.js

@@ -155,6 +155,7 @@ export function renderExplanation(model) {
                 return {
                     id,
                     verdict: h?.verdict ?? "no_data",
+                    utilization: h?.utilization,
                     sevenDayResetsAt: (h?.usage?.find((u) => u.window === "usage:seven_day" && u.resetsAt !== undefined && u.resetsAt > nowMs)
                         ?? h?.usage?.find((u) => u.window === "seven_day" && u.resetsAt !== undefined && u.resetsAt > nowMs))?.resetsAt,
                 };
@@ -167,8 +168,10 @@ export function renderExplanation(model) {
                 let reason;
                 if (preferred && decision.account !== preferred)
                     reason = "sticky dwell keeps this usable account";
+                else if (picked?.verdict === "near_limit")
+                    reason = describeNearLimitPick(verdicts, picked);
                 else if (strategy === "ordered")
-                    reason = picked?.verdict === "near_limit" ? "first near-limit member in pool order" : "first healthy member in pool order";
+                    reason = "first healthy member in pool order";
                 else if (strategy === "spread")
                     reason = picked && (picked.verdict === "ok" || picked.verdict === "no_data") ? describeSpreadPick(picked, windowMs) : "no healthy member; using the existing fallback";
                 else if (picked?.verdict === "ok" && picked.sevenDayResetsAt !== undefined)
@@ -201,6 +204,21 @@ export function renderExplanation(model) {
     }
     return lines.join("\n");
 }
+export function describeNearLimitPick(verdicts, picked) {
+    const nearLimit = verdicts.filter((v) => v.verdict === "near_limit");
+    const scope = nearLimit.length === verdicts.length ? "all near limit" : "no healthy member, the rest near limit";
+    const others = nearLimit.filter((v) => v.id !== picked.id);
+    if (picked.utilization === undefined) {
+        return `${scope}, picked ${picked.id} (no utilization number; pool order)`;
+    }
+    const pct = `${Math.round(picked.utilization * 100)}%`;
+    if (others.length === 0)
+        return `${scope}, picked ${picked.id} at ${pct}`;
+    const shown = others
+        .map((v) => `${v.id} ${v.utilization === undefined ? "no number" : `${Math.round(v.utilization * 100)}%`}`)
+        .join(", ");
+    return `${scope}, picked ${picked.id} at ${pct} — most headroom (${shown})`;
+}
 export function renderDirectSection(direct, nowMs) {
     const lines = [];
     lines.push("DIRECT ROUTE  anthropic/*  (gateway → Anthropic API with each account's setup-token)");

package/dist/health.js

@@ -20,6 +20,9 @@ export function isPeriodWindow(window) {
 export function isOverageWindow(window) {
     return /overage/i.test(window);
 }
+export function logicalWindowKey(window) {
+    return window.startsWith("usage:") ? window.slice("usage:".length) : window;
+}
 export function isLongQuotaWindow(window) {
     return /(^|_)(days?|weeks?|months?)(_|$)/.test(window) && !isOverageWindow(window);
 }
@@ -90,6 +93,7 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     let hasLiveEvidence = false;
     let overageUtilization;
     let quotaUtilization;
+    const freshestByWindow = new Map();
     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;
@@ -176,6 +180,14 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
         if (!isOverageWindow(window) && typeof w.utilization === "number") {
             quotaUtilization = Math.max(quotaUtilization ?? 0, w.utilization);
         }
+        if (typeof w.utilization === "number" &&
+            (resetBearing || resetMs === undefined) &&
+            (!isOverageWindow(window) || options.rotateOnOverage)) {
+            const logical = logicalWindowKey(window);
+            const seen = freshestByWindow.get(logical);
+            if (!seen || w.seenAt > seen.seenAt)
+                freshestByWindow.set(logical, { utilization: w.utilization, seenAt: w.seenAt });
+        }
         if (worst.verdict === "ok" &&
             typeof w.utilization !== "number" &&
             isShortWindow(window) &&
@@ -189,6 +201,12 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     }
     if (worst.verdict === "ok" && !hasLiveEvidence)
         return { verdict: "no_data" };
+    let utilization;
+    for (const { utilization: u } of freshestByWindow.values()) {
+        utilization = utilization === undefined ? u : Math.max(utilization, u);
+    }
+    if (utilization !== undefined)
+        worst = { ...worst, utilization };
     if (worst.verdict === "ok" && overageUtilization !== undefined) {
         const pct = (n) => `${Math.round(n * 100)}%`;
         worst = {
@@ -258,7 +276,24 @@ export function choosePoolAccount(pool, strategy = "ordered") {
     const usable = pool.find((a) => a.verdict === "ok" || a.verdict === "no_data");
     if (usable)
         return usable.id;
-    return pool.find((a) => a.verdict === "near_limit")?.id;
+    return nearLimitWithMostHeadroom(pool)?.id;
+}
+export function headroomBefore(a, b) {
+    if (a.utilization === undefined)
+        return false;
+    if (b.utilization === undefined)
+        return true;
+    return a.utilization < b.utilization;
+}
+export function nearLimitWithMostHeadroom(pool) {
+    let best;
+    for (const member of pool) {
+        if (member.verdict !== "near_limit")
+            continue;
+        if (!best || headroomBefore(member, best))
+            best = member;
+    }
+    return best;
 }
 export function allCredentialFailed(pool) {
     return pool.length > 0 && pool.every((a) => a.verdict === "credential_failed");

package/dist/index.js

@@ -850,6 +850,7 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             id: v.id,
             verdict: v.health.verdict,
             observedAt: v.health.observedAt,
+            utilization: v.health.utilization,
             sevenDayResetsAt: strategy === "reset-aware"
                 ? sevenDayReset(states.find((s) => s.id === v.id)?.state, options, now)
                 : undefined,

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "2.5.0",
+  "version": "2.5.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

@@ -749,7 +749,8 @@ async function explain(args = []) {
       weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
       staleAfterMs: pool?.staleAfterMs,
     }, now);
-    return { id: a.id, verdict: h.verdict, detail, usage };
+    // #93: the headroom figure the pool ranks near-limit members by.
+    return { id: a.id, verdict: h.verdict, detail, usage, utilization: h.utilization };
   });
   let stickyAccount;
   let stickyEntry;
@@ -864,13 +865,14 @@ async function usageCommand(args) {
     const h = health.classifyAccountHealth(state, healthOptions, now);
     row.verdict = h.verdict;
     row.reason = h.reason;
+    if (h.utilization !== undefined) row.utilization = h.utilization;
     if (pool?.strategy === "reset-aware") resetById.set(a.id, health.sevenDayReset(state, healthOptions, now));
     rows.push(row);
   }
   let next;
   if (pool) {
     const verdicts = pool.accounts.filter((id) => !accounts.find((a) => a.id === id)?.disabled).map((id) => ({ id, verdict: rows.find((r) => r.id === id)?.verdict ?? "no_data",
-      sevenDayResetsAt: resetById.get(id) }));
+      utilization: rows.find((r) => r.id === id)?.utilization, sevenDayResetsAt: resetById.get(id) }));
     if (pool.strategy === "reset-aware" || pool.strategy === "spread") {
       const stickySelection = await import(resolve(__dirname, "..", "dist", "sticky.js"));
       let sticky;

package/scripts/doctor.mjs

@@ -635,7 +635,8 @@ else {
     };
     const rawVerdicts = members.map((id) => {
       const state = readJson(join(STATE_DIR, `${id}.json`));
-      return { id, verdict: classifyAccountHealth(state, healthOptions, now).verdict,
+      const health = classifyAccountHealth(state, healthOptions, now);
+      return { id, verdict: health.verdict, utilization: health.utilization,
         sevenDayResetsAt: pool.strategy === "reset-aware" ? sevenDayReset(state, healthOptions, now) : undefined };
     });
     const verdicts = pool.strategy === "spread"