@drakon-systems/multi-clawd 2.1.3 → 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.1.3/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,8 +553,10 @@ error.
   ],
   "pool": {
     "id": "clawd",
-    "accounts": ["claw1", "claw2"],   // preference order; first = home
-    "utilizationThreshold": 0.85,     // hand over at 85% of any window
+    "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
     "degrade": {                      // v0.3.5: last step before provider drop
       "ladder": ["claude-opus-4-8"],  // whole pool exhausted → same account, lower tier
@@ -576,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):
 
@@ -630,6 +641,7 @@ from the provider** on a timer — the same figures the Claude CLI's own
   "id": "clawd",
   "accounts": ["claw1", "claw2"],
   "utilizationThreshold": 0.85,     // hand over here (unchanged)
+  "weeklyUtilizationThreshold": 0.97, // optional: day/week/month quota windows at 97%; overage stays at 85%
   "usagePoll": {                    // v1.10 — on by default
     "intervalMs": 120000,           // every 2 min (minimum 60000)
     "warnThreshold": 0.95           // operator alert from here
@@ -830,6 +842,18 @@ event, and no plugin API can force a rebuild. See `DESIGN.md`.
   a usable login now reports as available, a dead one still reports
   "missing-auth", and the direct API transport keeps refusing CLI-login
   accounts as before. Update with `multi-clawd update`.
+  If an account's stored login is deleted or becomes unreadable, the account
+  can stay available until the 30-second cache window that began at its last
+  assessment ends; the window runs from that assessment, not from the loss.
+  The first availability check after the window ends starts a background
+  re-check, and the account stays available only while that re-check is
+  pending; once it finishes it marks the account unavailable. Even if the
+  re-check stalls, a login backed by a valid access token is refused at its
+  access-token expiry minus 60 seconds, including at that exact moment and
+  even inside the first window. A login proven only by a recent successful
+  turn (its stored token can already be expired) is refused at two windows
+  after the assessment or 24 hours after that turn, whichever comes first. A
+  CLI login failure recorded on a real turn removes it at once.
 
 - **Shim window persistence is sequential-safe, not concurrent-writer-safe.**
   `persistState()` in `src/shim.ts` does a read-merge-write on every save so a

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,3 +1,5 @@
+import { DEFAULT_UTILIZATION_THRESHOLD, choosePoolAccount, poolStrategy } from "./health.js";
+import { decideStickySelection } from "./sticky.js";
 const WINDOW_LABELS = {
     five_hour: "5-hour",
     seven_day: "weekly",
@@ -84,11 +86,20 @@ export function renderExplanation(model) {
     }
     lines.push("");
     if (model.pool) {
-        const pct = Math.round((model.pool.utilizationThreshold ?? 0.85) * 100);
+        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 that is NOT nearly maxed`);
-        lines.push(`  out — hand-over at ${pct}% of any rate window, home account reclaims`);
-        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 ?? [];
         if (ladder.length > 0) {
             lines.push(`  If the WHOLE pool is exhausted: step down to ${ladder.join(" → ")} first.`);
@@ -126,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

@@ -1,5 +1,5 @@
 import { modelWindowApplies, modelWindowKey } from "./shim-core.js";
-const DEFAULT_UTILIZATION_THRESHOLD = 0.85;
+export const DEFAULT_UTILIZATION_THRESHOLD = 0.85;
 const DEFAULT_STALE_AFTER_MS = 6 * 60 * 60 * 1000;
 export const MODEL_REJECTED_TTL_MS = 60 * 60 * 1000;
 export const CREDENTIAL_FAILED_TTL_MS = 15 * 60 * 1000;
@@ -19,6 +19,9 @@ export function isPeriodWindow(window) {
 export function isOverageWindow(window) {
     return /overage/i.test(window);
 }
+export function isLongQuotaWindow(window) {
+    return /(^|_)(days?|weeks?|months?)(_|$)/.test(window) && !isOverageWindow(window);
+}
 export function isWarningStatus(status) {
     return /warning/i.test(status);
 }
@@ -75,7 +78,7 @@ export function lastAuthSuccessAt(state) {
 }
 export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
-    const threshold = options.utilizationThreshold ?? DEFAULT_UTILIZATION_THRESHOLD;
+    const generalThreshold = options.utilizationThreshold ?? DEFAULT_UTILIZATION_THRESHOLD;
     if (!state)
         return { verdict: "no_data" };
     const credentialFailure = credentialFailureFor(state, nowMs);
@@ -153,6 +156,9 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
                 reason: `${window} rejected ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; ${Math.round(resetLessBlockMs(window) / 3600000)}h block)`,
             };
         }
+        const threshold = isLongQuotaWindow(window)
+            ? options.weeklyUtilizationThreshold ?? generalThreshold
+            : generalThreshold;
         if (typeof w.utilization === "number" &&
             w.utilization >= threshold &&
             (resetBearing || resetMs === undefined)) {
@@ -216,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;
@@ -246,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";
@@ -805,6 +805,7 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     }
     const options = {
         utilizationThreshold: pool.utilizationThreshold,
+        weeklyUtilizationThreshold: pool.weeklyUtilizationThreshold,
         staleAfterMs: pool.staleAfterMs,
         rotateOnOverage: pool.rotateOnOverage,
     };
@@ -842,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;
@@ -1040,6 +1045,7 @@ export function startDirectOrderSync(params) {
     const intervalMs = Math.max(15_000, params.directRoute?.intervalMs ?? 60_000);
     const healthOptions = {
         utilizationThreshold: params.pool?.utilizationThreshold,
+        weeklyUtilizationThreshold: params.pool?.weeklyUtilizationThreshold,
         staleAfterMs: params.pool?.staleAfterMs,
         rotateOnOverage: params.pool?.rotateOnOverage,
     };
@@ -1049,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) {
@@ -1063,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),
@@ -1137,6 +1145,7 @@ export function startUsagePoll(params) {
     const warnThreshold = effectiveUsageWarnThreshold(pool.usagePoll);
     const healthOptions = {
         utilizationThreshold: pool.utilizationThreshold,
+        weeklyUtilizationThreshold: pool.weeklyUtilizationThreshold,
         staleAfterMs: pool.staleAfterMs,
         rotateOnOverage: pool.rotateOnOverage,
     };
@@ -1205,7 +1214,7 @@ export function startUsagePoll(params) {
     usageInitial.unref?.();
     usageTimer = setInterval(tick, intervalMs);
     usageTimer.unref?.();
-    logger.info(`[multi-clawd] usage poll: reading live usage for ${members.map((m) => m.id).join(", ")} every ${Math.round(intervalMs / 1000)}s — rotate at ${Math.round((pool.utilizationThreshold ?? 0.85) * 100)}%, warn at ${Math.round(warnThreshold * 100)}%${skipped.length > 0 ? `; not polled: ${skipped.join("; ")}` : ""}`);
+    logger.info(`[multi-clawd] usage poll: reading live usage for ${members.map((m) => m.id).join(", ")} every ${Math.round(intervalMs / 1000)}s — rotate at ${Math.round((pool.utilizationThreshold ?? 0.85) * 100)}%${pool.weeklyUtilizationThreshold !== undefined ? ` (weekly ${Math.round(pool.weeklyUtilizationThreshold * 100)}%)` : ""}, warn at ${Math.round(warnThreshold * 100)}%${skipped.length > 0 ? `; not polled: ${skipped.join("; ")}` : ""}`);
     return { active: true, members: members.map((m) => m.id) };
 }
 export async function runUsagePollTickNow() {

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.1.3",
+  "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,12 +41,23 @@
             "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",
             "description": "Hand over when any rate-limit window's utilization reaches this fraction. Default 0.85."
           },
+          "weeklyUtilizationThreshold": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Hand over when a day/week/month-scale quota window (such as seven_day) reaches this fraction. Defaults to utilizationThreshold. Minute/hour and overage windows keep using utilizationThreshold; overage rotation still requires rotateOnOverage."
+          },
           "staleAfterMs": {
             "type": "number",
             "description": "Ignore health data older than this. Default 21600000 (6h)."

package/package.json

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

@@ -200,6 +200,7 @@ async function loadDirect(config) {
   const runner = run.createOpenclawRunner(directRoute.openclawCommand ?? "openclaw");
   const healthOptions = {
     utilizationThreshold: pool?.utilizationThreshold,
+    weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
     staleAfterMs: pool?.staleAfterMs,
     rotateOnOverage: pool?.rotateOnOverage,
   };
@@ -214,6 +215,7 @@ async function loadDirect(config) {
       configOrder,
       sticky,
       minDwellMs: pool?.minDwellMs,
+      strategy: pool?.strategy,
       nowMs: Date.now(),
       ...opts,
     });
@@ -676,6 +678,7 @@ async function explain() {
     }
     const h = health.classifyAccountHealth(state, {
       utilizationThreshold: pool?.utilizationThreshold,
+      weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
       staleAfterMs: pool?.staleAfterMs,
     }, now);
     let detail = h.reason;
@@ -684,14 +687,17 @@ async function explain() {
     }
     const usage = health.summarizeWindowUsage(state, {
       utilizationThreshold: pool?.utilizationThreshold,
+      weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
       staleAfterMs: pool?.staleAfterMs,
     }, now);
     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 */
@@ -707,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}`);
 }
@@ -742,14 +748,17 @@ async function usageCommand(args) {
   const pool = pc.pool ? { ...pc.pool, id: pc.pool.id?.trim() || "clawd", accounts: pc.pool.accounts ?? [] } : undefined;
   const healthOptions = {
     utilizationThreshold: pool?.utilizationThreshold,
+    weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
     staleAfterMs: pool?.staleAfterMs,
     rotateOnOverage: pool?.rotateOnOverage,
   };
   const warnThreshold = up.effectiveUsageWarnThreshold(pool?.usagePoll);
   const rotateAt = pool?.utilizationThreshold ?? 0.85;
+  const weeklyRotateAt = pool?.weeklyUtilizationThreshold;
   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) {
@@ -780,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));
@@ -797,13 +815,17 @@ async function usageCommand(args) {
     const mins = Math.max(0, Math.round((resetsAt * 1000 - now) / 60000));
     return mins < 90 ? ` (resets in ~${mins}m)` : mins < 36 * 60 ? ` (resets in ~${Math.round(mins / 60)}h)` : ` (resets in ~${Math.round(mins / 1440)}d)`;
   };
-  const mark = (u) => (u >= 1 ? "⛔" : u >= warnThreshold ? "🔴" : u >= rotateAt ? "🟠" : "🟢");
-  console.log(`\n${BOLD}🦞 multi-clawd — live usage${RESET}  ${DIM}(rotate at ${pct(rotateAt)}, warn at ${pct(warnThreshold)})${RESET}\n`);
+  const mark = (u, window) => {
+    const weekly = window && health.isLongQuotaWindow(window);
+    const threshold = weekly ? weeklyRotateAt ?? rotateAt : rotateAt;
+    return u >= 1 ? "⛔" : u >= warnThreshold ? "🔴" : u >= threshold ? "🟠" : "🟢";
+  };
+  console.log(`\n${BOLD}🦞 multi-clawd — live usage${RESET}  ${DIM}(rotate at ${pct(rotateAt)}${weeklyRotateAt !== undefined ? `, weekly ${pct(weeklyRotateAt)}` : ""}, warn at ${pct(warnThreshold)})${RESET}\n`);
   for (const r of rows) {
     console.log(`  ${BOLD}${r.id}${RESET}${r.label ? ` ${DIM}— ${r.label}${RESET}` : ""}   pool verdict: ${r.verdict}${r.reason ? ` ${DIM}(${r.reason})${RESET}` : ""}`);
     if (r.snapshot) {
       for (const [w, u] of Object.entries(r.snapshot.windows)) {
-        console.log(`     ${mark(u.utilization)} ${up.usageWindowLabel(w).padEnd(12)} ${pct(u.utilization).padStart(4)}${until(u.resetsAt)}`);
+        console.log(`     ${mark(u.utilization, w)} ${up.usageWindowLabel(w).padEnd(12)} ${pct(u.utilization).padStart(4)}${until(u.resetsAt)}`);
       }
       for (const s of r.snapshot.scoped) {
         console.log(`     ${mark(s.utilization)} ${`${s.label} model`.padEnd(12)} ${pct(s.utilization).padStart(4)}${until(s.resetsAt)}`);

package/scripts/doctor.mjs

@@ -294,13 +294,15 @@ 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
 // doctor's own diagnostic, not a description of the running plugin's
 // behaviour. Asking the installed copy meant a fix to the resolver could not
@@ -495,6 +497,9 @@ else {
   const members = (pool.accounts ?? []).filter((id) => accounts.some((a) => a.id === id));
   if (members.length < 2) bad(`pool "${pool.id ?? "clawd"}" has ${members.length} valid member(s); needs ≥ 2`);
   else ok(`pool "${pool.id ?? "clawd"}": ${members.join(" → ")}`);
+  const generalThreshold = pool.utilizationThreshold ?? DEFAULT_UTILIZATION_THRESHOLD;
+  const weeklyThreshold = pool.weeklyUtilizationThreshold ?? generalThreshold;
+  note(`thresholds: general ${Math.round(generalThreshold * 100)}%, weekly ${Math.round(weeklyThreshold * 100)}%${pool.weeklyUtilizationThreshold === undefined ? " (follows general)" : ""}`);
   // Setup-token members: what they do and do not get, said once, plainly.
   const tokenMembers = members
     .map((id) => accounts.find((a) => a.id === id))
@@ -529,18 +534,20 @@ else {
     const healthOptions = {
       staleAfterMs: pool.staleAfterMs,
       utilizationThreshold: pool.utilizationThreshold,
+      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 =
@@ -876,12 +883,14 @@ if (accounts.some((a) => a && a.direct !== undefined && a.direct !== false)) {
         readHealth,
         healthOptions: {
           utilizationThreshold: pool?.utilizationThreshold,
+          weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
           staleAfterMs: pool?.staleAfterMs,
           rotateOnOverage: pool?.rotateOnOverage,
         },
         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;