@drakon-systems/multi-clawd 2.5.0 → 2.6.0

package/README.md

@@ -31,6 +31,7 @@ multi-clawd setup     # guided wizard: accounts, isolated second login, pool, wa
 multi-clawd login claw2   # launch the right Claude sign-in for an account (or re-auth it)
 multi-clawd explain   # your whole setup in plain English — accounts, chain, live health
 multi-clawd explain --history --since 7d   # per-account launches, retries, rotations
+multi-clawd explain --json   # live health plus a rough weekly pace estimate, machine-readable
 multi-clawd account disable claw2 --dry-run  # preview benching an account
 multi-clawd chain     # audit your model routing — what actually serves each turn
 multi-clawd direct    # the direct anthropic/* route: status, or `direct sync` (v1.9, optional)
@@ -415,7 +416,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.6.0/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 +634,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 +695,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

@@ -30,6 +30,49 @@ export function renderUsageLine(usage, nowMs) {
     })
         .join(" · ");
 }
+const WEEK_MS = 7 * 86_400_000;
+const MIN_PACE_ELAPSED_MS = WEEK_MS / 10;
+const PACE_RESET_SLACK_MS = 3_600_000;
+export function computeWeeklyPace(usage, nowMs) {
+    const u = ["usage:seven_day", "seven_day"]
+        .map((w) => usage?.find((x) => x.window === w))
+        .find((x) => x !== undefined);
+    if (!u || u.resetsAt === undefined)
+        return undefined;
+    if (!Number.isFinite(u.utilization) || u.utilization < 0 || u.utilization > 1)
+        return undefined;
+    if (!Number.isFinite(u.resetsAt) || !Number.isFinite(nowMs))
+        return undefined;
+    const remaining = u.resetsAt - nowMs;
+    if (remaining <= 0 || remaining > WEEK_MS + PACE_RESET_SLACK_MS)
+        return undefined;
+    const elapsed = Math.max(0, WEEK_MS - remaining);
+    if (elapsed < MIN_PACE_ELAPSED_MS)
+        return undefined;
+    const expectedPct = elapsed / WEEK_MS;
+    const projectedExhaustionAt = u.utilization >= 1
+        ? nowMs
+        : u.utilization > 0 ? nowMs + ((1 - u.utilization) * elapsed) / u.utilization : undefined;
+    return {
+        window: u.window,
+        expectedPct,
+        aheadOfPace: u.utilization - expectedPct,
+        projectedExhaustionAt,
+        willLastToReset: projectedExhaustionAt === undefined || projectedExhaustionAt >= u.resetsAt,
+        resetsAt: u.resetsAt,
+        estimate: true,
+    };
+}
+export function renderPaceLine(pace, nowMs) {
+    if (!pace)
+        return undefined;
+    const pts = Math.round(pace.aheadOfPace * 100);
+    const where = pts === 0 ? "on pace" : pts > 0 ? `${pts} points ahead of pace` : `${-pts} points behind pace`;
+    const verdict = pace.willLastToReset
+        ? "should last to the reset"
+        : `could run out in ${relativeUntil(pace.projectedExhaustionAt ?? nowMs, nowMs)}, before the reset in ${relativeUntil(pace.resetsAt, nowMs)}`;
+    return `weekly pace (rough estimate): ~${Math.round(pace.expectedPct * 100)}% of the week gone, ${where}; ${verdict}`;
+}
 export function describeAccount(acc) {
     if (acc.native) {
         return "the machine's main `claude` login (default config dir; OS keychain on macOS)";
@@ -145,6 +188,9 @@ export function renderExplanation(model) {
             const word = VERDICT_WORDS[h.verdict] ?? h.verdict;
             lines.push(`  ${h.id}: ${model.accounts.find((a) => a.id === h.id)?.disabled ? "disabled by operator" : word}${h.detail ? ` — ${h.detail}` : ""}`);
             lines.push(`      usage: ${h.usage?.length ? renderUsageLine(h.usage, nowMs) : "no live telemetry"}`);
+            const paceLine = renderPaceLine(computeWeeklyPace(h.usage, nowMs), nowMs);
+            if (paceLine)
+                lines.push(`      ${paceLine}`);
         }
         if (model.pool) {
             const strategy = poolStrategy(model.pool.strategy);
@@ -155,6 +201,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 +214,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 +250,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.6.0",
   "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.6.0",
   "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

@@ -50,6 +50,27 @@ Run via npx (${DIM}npx ${PKG} <command>${RESET}) or install globally
 `);
 }
 
+// Per-command usage, printed for `<command> --help` / `-h` before anything is
+// dispatched, so asking for help never reads config, runs checks, or starts the
+// setup wizard. `hermes` is absent on purpose: it handles its own help.
+const COMMAND_HELP = {
+  setup: "multi-clawd setup [--dry-run]\n\n  Guided setup wizard (accounts, pool, watchdog).\n  --dry-run   preview the changes without writing anything",
+  login: "multi-clawd login [<id>]\n\n  Log a configured account in (or re-auth it). Without <id>, lists the\n  configured accounts to choose from.",
+  account: "multi-clawd account <enable|disable> <id> [--dry-run]\n\n  Disable or enable a pool account.\n  --dry-run   preview the change without writing it",
+  explain: "multi-clawd explain [--json | --history [--since 7d|24h]]\n\n  Your setup in plain English: accounts, pool, fallback chain.\n  --json      machine-readable output\n  --history   recent pool events; --since limits the window",
+  chain: "multi-clawd chain [--raw]\n\n  Audit your model routing: what actually serves each turn.\n  --raw       include raw routing detail",
+  direct: "multi-clawd direct [status | sync [--dry-run] [--yes] [--resync]]\n\n  The direct anthropic/* route. Default is status.\n  sync        store profiles for the direct route\n  --dry-run   preview without writing\n  --yes       skip the confirmation prompt\n  --resync    refresh profiles that are already stored",
+  usage: "multi-clawd usage [--json]\n\n  Live usage per account from the provider: what is left, and what the\n  pool will do.\n  --json      machine-readable output",
+  update: "multi-clawd update\n\n  Update the plugin to the latest version.",
+  doctor: "multi-clawd doctor [--probe] [--probe-pool] [--verbose] [--raw]\n\n  Health check.\n  --probe       run a live turn per account plus the pool\n  --probe-pool  with --probe: probe the pool ref only (one turn)\n  --verbose     show more detail\n  --raw         show raw output",
+  version: "multi-clawd version\n\n  Show CLI and installed plugin versions.",
+};
+
+if (Object.hasOwn(COMMAND_HELP, cmd) && rest.some((a) => a === "--help" || a === "-h")) {
+  console.log(`\n${COMMAND_HELP[cmd]}\n`);
+  process.exit(0);
+}
+
 const { resolveInstallDir } = await import(join(__dirname, "_shared.mjs"));
 
 function installedVersion(installPath) {
@@ -677,11 +698,12 @@ async function healWatchdogUnit() {
 /** `explain` — gather config + live health, render the plain-English view. */
 async function explain(args = []) {
   let historySince;
-  if (args.length) {
+  const asJson = args.length === 1 && args[0] === "--json";
+  if (args.length && !asJson) {
     const allowed = args[0] === "--history" && (args.length === 1 ||
       (args.length === 3 && args[1] === "--since"));
     if (!allowed) {
-      console.error("explain: usage: multi-clawd explain [--history [--since 7d|24h]]");
+      console.error("explain: usage: multi-clawd explain [--json | --history [--since 7d|24h]]");
       process.exitCode = 1;
       return;
     }
@@ -749,7 +771,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;
@@ -774,6 +797,14 @@ async function explain(args = []) {
       /* no journal yet: every account counts as never served */
     }
   }
+  if (asJson) {
+    // #94: machine-readable health with the display-only weekly pace estimate.
+    console.log(JSON.stringify({
+      at: new Date(now).toISOString(),
+      accounts: healthRows.map((r) => ({ ...r, weeklyPace: ec.computeWeeklyPace(r.usage, now) ?? null })),
+    }, null, 2));
+    return;
+  }
   // v1.9: the direct anthropic/* route, when any account opted in.
   let direct;
   const dctx = await loadDirect(config);
@@ -864,13 +895,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"