@drakon-systems/multi-clawd 2.2.0 → 2.3.0

package/README.md

@@ -386,7 +386,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.2.0/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.3.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.
 
@@ -553,7 +553,8 @@ error.
   ],
   "pool": {
     "id": "clawd",
-    "accounts": ["claw1", "claw2"],   // preference order; first = home
+    "accounts": ["claw1", "claw2"],   // preference order; first = home for ordered strategy
+    "strategy": "ordered",            // optional: "reset-aware" drains healthy weekly quota that resets soonest
     "utilizationThreshold": 0.85,     // default hand-over; minute/hour and overage windows use this
     "weeklyUtilizationThreshold": 0.97, // optional: day/week/month quota windows at 97%
     "minDwellMs": 600000,             // v0.3: anti-flap dwell before returning home
@@ -577,6 +578,15 @@ error.
 } }
 ```
 
+`pool.strategy` defaults to `"ordered"`, which retains the configured account
+order. 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
+times keep pool order. The existing `minDwellMs` delay still holds an account
+that remains usable. Both CLI launches and the direct Anthropic route use the
+same preference. Other values are rejected by the plugin config schema.
+
 How it decides, per launch (all data from each account's live
 `rate_limit_event` stream, captured by the shim):
 

package/dist/direct-report.js

@@ -1,4 +1,4 @@
-import { classifyAccountHealth } from "./health.js";
+import { classifyAccountHealth, sevenDayReset } from "./health.js";
 import { DIRECT_PROVIDER, collectDirectMembers, } from "./direct-route.js";
 import { parseUnusableProfiles, planAgentOrder, readDirectRouteSnapshot, safeCliError, } from "./direct-sync.js";
 export function describeDirectSource(member) {
@@ -19,11 +19,17 @@ export async function gatherDirectStatus(params) {
     if (members.length === 0 && problems.length === 0)
         return undefined;
     const errors = [];
-    const verdicts = members.map((m) => ({
-        accountId: m.accountId,
-        profileId: m.profileId,
-        verdict: classifyAccountHealth(params.readHealth(m.accountId), params.healthOptions, params.nowMs).verdict,
-    }));
+    const verdicts = members.map((m) => {
+        const state = params.readHealth(m.accountId);
+        return {
+            accountId: m.accountId,
+            profileId: m.profileId,
+            verdict: classifyAccountHealth(state, params.healthOptions, params.nowMs).verdict,
+            sevenDayResetsAt: params.strategy === "reset-aware"
+                ? sevenDayReset(state, params.healthOptions, params.nowMs)
+                : undefined,
+        };
+    });
     const read = members.length > 0 ? await readDirectRouteSnapshot(params.runner, params.agentId) : {};
     if ("error" in read && read.error)
         errors.push(read.error);
@@ -46,6 +52,7 @@ export async function gatherDirectStatus(params) {
             sticky: params.sticky,
             nowMs: params.nowMs,
             minDwellMs: params.minDwellMs,
+            strategy: params.strategy,
         }).order;
     }
     const byProfile = new Map(unusable.map((u) => [u.profileId, u]));

package/dist/direct-route.js

@@ -132,16 +132,20 @@ export function planDirectOrder(params) {
     if (members.length === 0)
         return undefined;
     const decision = decideStickySelection({
-        verdicts: members.map((m) => ({ id: m.accountId, verdict: m.verdict })),
+        verdicts: members.map((m) => ({ id: m.accountId, verdict: m.verdict, sevenDayResetsAt: m.sevenDayResetsAt })),
         sticky: params.sticky,
         nowMs: params.nowMs,
         minDwellMs: params.minDwellMs,
+        strategy: params.strategy,
     });
     const first = members.find((m) => m.accountId === decision.account) ?? members[0];
     const rest = members
         .filter((m) => m !== first)
         .map((m, index) => ({ m, index }))
-        .sort((a, b) => VERDICT_RANK[a.m.verdict] - VERDICT_RANK[b.m.verdict] || a.index - b.index)
+        .sort((a, b) => VERDICT_RANK[a.m.verdict] - VERDICT_RANK[b.m.verdict] ||
+        (params.strategy === "reset-aware" && a.m.verdict === "ok"
+            ? (a.m.sevenDayResetsAt ?? Infinity) - (b.m.sevenDayResetsAt ?? Infinity)
+            : 0) || a.index - b.index)
         .map(({ m }) => m.profileId);
     const managed = new Set(members.map((m) => m.profileId));
     const unmanaged = (params.currentOrder ?? []).filter((id, i, all) => typeof id === "string" && !managed.has(id) && all.indexOf(id) === i);

package/dist/direct-sync.js

@@ -1,4 +1,4 @@
-import { classifyAccountHealth } from "./health.js";
+import { classifyAccountHealth, sevenDayReset } from "./health.js";
 import { DIRECT_PROVIDER, planDirectOrder } from "./direct-route.js";
 import { parseClaudeSetupToken } from "./hermes-core.js";
 export function safeCliError(result) {
@@ -224,6 +224,7 @@ export function planAgentOrder(params) {
         sticky: params.sticky,
         nowMs: params.nowMs,
         minDwellMs: params.minDwellMs,
+        strategy: params.strategy,
     });
     if (!plan)
         return { missing };
@@ -244,13 +245,19 @@ export function createDirectOrderController(deps) {
                 return { managedOrder: [], agents: [] };
             running = true;
             try {
-                const verdicts = deps.members.map((m) => ({
-                    accountId: m.accountId,
-                    profileId: m.profileId,
-                    verdict: classifyAccountHealth(deps.readHealth(m.accountId), deps.healthOptions, nowMs).verdict,
-                }));
+                const verdicts = deps.members.map((m) => {
+                    const state = deps.readHealth(m.accountId);
+                    return {
+                        accountId: m.accountId,
+                        profileId: m.profileId,
+                        verdict: classifyAccountHealth(state, deps.healthOptions, nowMs).verdict,
+                        sevenDayResetsAt: deps.strategy === "reset-aware"
+                            ? sevenDayReset(state, deps.healthOptions, nowMs)
+                            : undefined,
+                    };
+                });
                 const sticky = deps.readSticky();
-                const managed = planDirectOrder({ members: verdicts, sticky, nowMs, minDwellMs: deps.minDwellMs });
+                const managed = planDirectOrder({ members: verdicts, sticky, nowMs, minDwellMs: deps.minDwellMs, strategy: deps.strategy });
                 if (!managed)
                     return { managedOrder: [], agents: [] };
                 if (JSON.stringify(managed.sticky) !== JSON.stringify(sticky))
@@ -285,6 +292,7 @@ export function createDirectOrderController(deps) {
                             sticky,
                             nowMs,
                             minDwellMs: deps.minDwellMs,
+                            strategy: deps.strategy,
                         });
                         for (const id of plan.missing) {
                             const k = `${agentId}:${id}`;

package/dist/explain-core.js

@@ -1,4 +1,5 @@
-import { DEFAULT_UTILIZATION_THRESHOLD } from "./health.js";
+import { DEFAULT_UTILIZATION_THRESHOLD, choosePoolAccount, poolStrategy } from "./health.js";
+import { decideStickySelection } from "./sticky.js";
 const WINDOW_LABELS = {
     five_hour: "5-hour",
     seven_day: "weekly",
@@ -88,9 +89,15 @@ export function renderExplanation(model) {
         const generalThreshold = model.pool.utilizationThreshold ?? DEFAULT_UTILIZATION_THRESHOLD;
         const weeklyThreshold = model.pool.weeklyUtilizationThreshold ?? generalThreshold;
         lines.push(`POOL  ${model.pool.id}  (${model.pool.accounts.join(" → ")})`);
-        lines.push(`  Every Claude launch runs on the first account below its threshold;`);
-        lines.push(`  the home account reclaims work`);
-        lines.push(`  automatically once its window resets.`);
+        lines.push(`  Strategy: ${poolStrategy(model.pool.strategy)}.`);
+        if (poolStrategy(model.pool.strategy) === "reset-aware") {
+            lines.push("  Healthy accounts with a live seven-day reset are preferred by soonest reset.");
+        }
+        else {
+            lines.push("  Every Claude launch runs on the first account below its threshold;");
+            lines.push("  the home account reclaims work");
+            lines.push("  automatically once its window resets.");
+        }
         lines.push(`  Thresholds: general ${Math.round(generalThreshold * 100)}%, weekly ${Math.round(weeklyThreshold * 100)}%${model.pool.weeklyUtilizationThreshold === undefined ? " (follows general)" : ""}.`);
         lines.push(`  The weekly threshold applies to day/week/month quota windows; overage uses the general threshold.`);
         const ladder = model.pool.degrade?.ladder ?? [];
@@ -130,8 +137,42 @@ export function renderExplanation(model) {
             lines.push(`      usage: ${h.usage?.length ? renderUsageLine(h.usage, nowMs) : "no live telemetry"}`);
         }
         if (model.pool) {
+            const strategy = poolStrategy(model.pool.strategy);
+            const verdicts = model.pool.accounts.map((id) => {
+                const h = model.health.find((row) => row.id === id);
+                return {
+                    id,
+                    verdict: h?.verdict ?? "no_data",
+                    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,
+                };
+            });
+            if (verdicts.length) {
+                const preferred = choosePoolAccount(verdicts, strategy);
+                const decision = decideStickySelection({ verdicts, sticky: model.stickyEntry, nowMs, minDwellMs: model.pool.minDwellMs, strategy });
+                const picked = verdicts.find((v) => v.id === decision.account);
+                let reason;
+                if (preferred && decision.account !== preferred)
+                    reason = "sticky dwell keeps this usable account";
+                else if (strategy === "ordered")
+                    reason = picked?.verdict === "near_limit" ? "first near-limit member in pool order" : "first healthy member in pool order";
+                else if (picked?.verdict === "ok" && picked.sevenDayResetsAt !== undefined)
+                    reason = `seven-day window resets soonest (in ${relativeUntil(picked.sevenDayResetsAt, nowMs)})`;
+                else if (picked?.verdict === "ok")
+                    reason = "first healthy member without live seven-day reset data";
+                else if (picked?.verdict === "no_data")
+                    reason = "first member without live health data";
+                else
+                    reason = "no healthy member; using the existing fallback";
+                lines.push(`  strategy: ${strategy} — picked ${decision.account}: ${reason}`);
+            }
+            else {
+                lines.push(`  strategy: ${strategy}`);
+            }
             lines.push(model.stickyAccount
-                ? `  pool is rotated onto ${model.stickyAccount} (returns home when the home window resets)`
+                ? strategy === "reset-aware"
+                    ? `  pool is on ${model.stickyAccount} (dwell applies while it remains usable)`
+                    : `  pool is rotated onto ${model.stickyAccount} (returns home when the home window resets)`
                 : `  pool is on its home account (no rotation active)`);
         }
     }

package/dist/health.js

@@ -222,7 +222,27 @@ export function summarizeWindowUsage(state, options, nowMs) {
     }
     return usage.sort((a, b) => (b.resetsAt ?? 0) - (a.resetsAt ?? 0));
 }
-export function choosePoolAccount(pool) {
+export function poolStrategy(value) {
+    return value === "reset-aware" ? "reset-aware" : "ordered";
+}
+export function sevenDayReset(state, options, nowMs) {
+    const usage = summarizeWindowUsage(state, options, nowMs);
+    return (usage.find((w) => w.window === "usage:seven_day" && w.resetsAt !== undefined)
+        ?? usage.find((w) => w.window === "seven_day" && w.resetsAt !== undefined))?.resetsAt;
+}
+export function choosePoolAccount(pool, strategy = "ordered") {
+    if (strategy === "reset-aware") {
+        let best;
+        for (const member of pool) {
+            if (member.verdict !== "ok")
+                continue;
+            if (!best || (member.sevenDayResetsAt !== undefined &&
+                (best.sevenDayResetsAt === undefined || member.sevenDayResetsAt < best.sevenDayResetsAt)))
+                best = member;
+        }
+        if (best?.sevenDayResetsAt !== undefined)
+            return best.id;
+    }
     const usable = pool.find((a) => a.verdict === "ok" || a.verdict === "no_data");
     if (usable)
         return usable.id;
@@ -252,6 +272,6 @@ export function fallbackPoolAccount(pool, nowMs) {
         return retest.id;
     return (pool.find((a) => a.verdict !== "credential_failed") ?? pool[0]).id;
 }
-export function pickPoolAccountForLaunch(pool, nowMs) {
-    return choosePoolAccount(pool) ?? fallbackPoolAccount(pool, nowMs);
+export function pickPoolAccountForLaunch(pool, nowMs, strategy = "ordered") {
+    return choosePoolAccount(pool, strategy) ?? fallbackPoolAccount(pool, nowMs);
 }

package/dist/index.js

@@ -7,7 +7,7 @@ import { MODEL_ALIASES, buildCatalogEntries, canonicalModelId, isModernClaudeMod
 import { decideDegradation, matchesPin } from "./degrade.js";
 import { resolveExecMode, permissionModeArgs } from "./exec-policy.js";
 import { resolveBaseModelIds } from "./catalog-source.js";
-import { allCredentialFailed, classifyAccountHealth, credentialFailureFor, lastAuthSuccessAt, overdueProbeAccount, } from "./health.js";
+import { allCredentialFailed, classifyAccountHealth, credentialFailureFor, lastAuthSuccessAt, overdueProbeAccount, sevenDayReset, } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
 import { mergeHealthStates, parseStoredState, recordCredentialFailure, } from "./shim-core.js";
 import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js";
@@ -843,12 +843,16 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             id: v.id,
             verdict: v.health.verdict,
             observedAt: v.health.observedAt,
+            sevenDayResetsAt: pool.strategy === "reset-aware"
+                ? sevenDayReset(states.find((s) => s.id === v.id)?.state, options, now)
+                : undefined,
         }));
         const decision = decideStickySelection({
             verdicts: poolVerdicts,
             sticky: previousSticky,
             nowMs: now,
             minDwellMs,
+            strategy: pool.strategy,
         });
         const chosen = members.find((a) => a.id === decision.account) ?? members[0];
         const previousAccount = previousSticky?.account ?? members[0].id;
@@ -1051,6 +1055,7 @@ export function startDirectOrderSync(params) {
         intervalMs,
         healthOptions,
         minDwellMs: params.pool?.minDwellMs,
+        strategy: params.pool?.strategy,
         command: params.directRoute?.openclawCommand,
     });
     if (directController?.signature === signature && directTimer) {
@@ -1065,6 +1070,7 @@ export function startDirectOrderSync(params) {
         readHealth: (id) => readHealthState(id),
         healthOptions,
         minDwellMs: params.pool?.minDwellMs,
+        strategy: params.pool?.strategy,
         configOrder: params.configOrder,
         readSticky: () => readStickyEntry(stickyFile),
         writeSticky: (entry) => writeStickyEntry(stickyFile, entry, logger),

package/dist/sticky.js

@@ -4,9 +4,19 @@ export function decideStickySelection(params) {
     const { verdicts, sticky, nowMs } = params;
     const minDwellMs = params.minDwellMs ?? DEFAULT_MIN_DWELL_MS;
     const home = verdicts[0];
-    const healthChoice = choosePoolAccount(verdicts);
+    const healthChoice = choosePoolAccount(verdicts, params.strategy);
     if (!healthChoice)
         return { account: fallbackPoolAccount(verdicts, nowMs) };
+    if (params.strategy === "reset-aware") {
+        const current = sticky && verdicts.find((v) => v.id === sticky.account);
+        const stillUsable = current?.verdict === "ok" || current?.verdict === "no_data";
+        if (sticky && stillUsable && nowMs - sticky.since < minDwellMs) {
+            return { account: sticky.account, sticky };
+        }
+        if (sticky?.account === healthChoice)
+            return { account: healthChoice, sticky };
+        return { account: healthChoice, sticky: { account: healthChoice, since: nowMs } };
+    }
     const stickyVerdict = sticky
         ? verdicts.find((v) => v.id === sticky.account)?.verdict
         : undefined;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.2.0",
+  "version": "2.3.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",
@@ -41,7 +41,12 @@
             "items": {
               "type": "string"
             },
-            "description": "Account ids (from accounts[]) in preference order; the first is the home account and reclaims the pool when its usage window resets."
+            "description": "Account ids (from accounts[]) in preference order; the first is the home account in the default ordered strategy."
+          },
+          "strategy": {
+            "type": "string",
+            "enum": ["ordered", "reset-aware"],
+            "description": "Healthy account selection: ordered (default) keeps pool order; reset-aware prefers the healthy account whose live seven-day quota window resets soonest."
           },
           "utilizationThreshold": {
             "type": "number",

package/package.json

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

@@ -215,6 +215,7 @@ async function loadDirect(config) {
       configOrder,
       sticky,
       minDwellMs: pool?.minDwellMs,
+      strategy: pool?.strategy,
       nowMs: Date.now(),
       ...opts,
     });
@@ -692,9 +693,11 @@ async function explain() {
     return { id: a.id, verdict: h.verdict, detail, usage };
   });
   let stickyAccount;
+  let stickyEntry;
   if (pool) {
     try {
       const sticky = JSON.parse(rf(join(stateDir, `pool-${pool.id}.sticky.json`), "utf8"));
+      stickyEntry = sticky;
       if (sticky?.account && sticky.account !== pool.accounts[0]) stickyAccount = sticky.account;
     } catch {
       /* no sticky state */
@@ -710,7 +713,7 @@ async function explain() {
   }
   console.log(`\n${BOLD}🦞 multi-clawd — your setup, in plain English${RESET}\n`);
   console.log(
-    ec.renderExplanation({ accounts, pool, chain, health: healthRows, stickyAccount, nowMs: now, direct }),
+    ec.renderExplanation({ accounts, pool, chain, health: healthRows, stickyAccount, stickyEntry, nowMs: now, direct }),
   );
   console.log(`\n${DIM}(health checks: multi-clawd doctor · change things: multi-clawd setup)${RESET}`);
 }
@@ -755,6 +758,7 @@ async function usageCommand(args) {
   const stateDir = join(homedir(), ".openclaw", "state", "multi-clawd");
   const now = Date.now();
   const rows = [];
+  const resetById = new Map();
   for (const a of accounts) {
     const row = { id: a.id, label: a.label };
     if (a.oauthTokenFile || a.oauthTokenRef) {
@@ -785,12 +789,21 @@ async function usageCommand(args) {
     const h = health.classifyAccountHealth(state, healthOptions, now);
     row.verdict = h.verdict;
     row.reason = h.reason;
+    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.map((id) => ({ id, verdict: rows.find((r) => r.id === id)?.verdict ?? "no_data" }));
-    next = health.choosePoolAccount(verdicts);
+    const verdicts = pool.accounts.map((id) => ({ id, verdict: rows.find((r) => r.id === id)?.verdict ?? "no_data",
+      sevenDayResetsAt: resetById.get(id) }));
+    if (pool.strategy === "reset-aware") {
+      const stickySelection = await import(resolve(__dirname, "..", "dist", "sticky.js"));
+      let sticky;
+      try { sticky = JSON.parse(rf(join(stateDir, `pool-${pool.id}.sticky.json`), "utf8")); } catch { /* none */ }
+      next = stickySelection.decideStickySelection({ verdicts, sticky, nowMs: now, minDwellMs: pool.minDwellMs, strategy: pool.strategy }).account;
+    } else {
+      next = health.choosePoolAccount(verdicts);
+    }
   }
   if (args.includes("--json")) {
     console.log(JSON.stringify({ at: new Date(now).toISOString(), rotateAt, warnThreshold, pool: pool?.id, nextLaunch: next, accounts: rows }, null, 2));

package/scripts/doctor.mjs

@@ -294,12 +294,13 @@ const { createSystemCredentialIo, findCredentialCopies, describeSplitStore } = a
   ["createSystemCredentialIo", "findCredentialCopies", "describeSplitStore"],
   "cli",
 );
-const { summarizeWindowUsage, classifyAccountHealth, overdueProbeAccount, lastAuthSuccessAt } =
+const { summarizeWindowUsage, classifyAccountHealth, overdueProbeAccount, lastAuthSuccessAt, sevenDayReset } =
   await importDist("health.js", [
     "summarizeWindowUsage",
     "classifyAccountHealth",
     "overdueProbeAccount",
     "lastAuthSuccessAt",
+    "sevenDayReset",
   ]);
 const { DEFAULT_UTILIZATION_THRESHOLD } = await import(join(REPO_DIR, "dist", "health.js"));
 // "cli", like the chain audits: resolving WHICH login backs an account is
@@ -536,16 +537,17 @@ else {
       weeklyUtilizationThreshold: pool.weeklyUtilizationThreshold,
       rotateOnOverage: pool.rotateOnOverage,
     };
-    const verdicts = members.map((id) => ({
-      id,
-      verdict: classifyAccountHealth(readJson(join(STATE_DIR, `${id}.json`)), healthOptions, now)
-        .verdict,
-    }));
+    const verdicts = members.map((id) => {
+      const state = readJson(join(STATE_DIR, `${id}.json`));
+      return { id, verdict: classifyAccountHealth(state, healthOptions, now).verdict,
+        sevenDayResetsAt: pool.strategy === "reset-aware" ? sevenDayReset(state, healthOptions, now) : undefined };
+    });
     const decision = decideStickySelection({
       verdicts,
       sticky,
       nowMs: now,
       minDwellMs: pool.minDwellMs,
+      strategy: pool.strategy,
     });
     const identity = identities.find((i) => i.accountId === decision.account);
     const who =
@@ -888,6 +890,7 @@ if (accounts.some((a) => a && a.direct !== undefined && a.direct !== false)) {
         configOrder: Array.isArray(config?.auth?.order?.anthropic) ? config.auth.order.anthropic : undefined,
         sticky: readJson(join(STATE_DIR, "direct-order.sticky.json")),
         minDwellMs: pool?.minDwellMs,
+        strategy: pool?.strategy,
         nowMs: Date.now(),
       });
       if (!status) continue;