@drakon-systems/multi-clawd 2.1.3 → 2.2.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.2.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.
 
@@ -554,7 +554,8 @@ error.
   "pool": {
     "id": "clawd",
     "accounts": ["claw1", "claw2"],   // preference order; first = home
-    "utilizationThreshold": 0.85,     // hand over at 85% of any window
+    "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
@@ -630,6 +631,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 +832,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/explain-core.js

@@ -1,3 +1,4 @@
+import { DEFAULT_UTILIZATION_THRESHOLD } from "./health.js";
 const WINDOW_LABELS = {
     five_hour: "5-hour",
     seven_day: "weekly",
@@ -84,11 +85,14 @@ 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(`  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.`);

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)) {

package/dist/index.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,
     };
@@ -1040,6 +1041,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,
     };
@@ -1137,6 +1139,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 +1208,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/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.1.3",
+  "version": "2.2.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",
@@ -47,6 +47,12 @@
             "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.2.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,
   };
@@ -676,6 +677,7 @@ async function explain() {
     }
     const h = health.classifyAccountHealth(state, {
       utilizationThreshold: pool?.utilizationThreshold,
+      weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
       staleAfterMs: pool?.staleAfterMs,
     }, now);
     let detail = h.reason;
@@ -684,6 +686,7 @@ 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 };
@@ -742,11 +745,13 @@ 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 = [];
@@ -797,13 +802,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

@@ -301,6 +301,7 @@ const { summarizeWindowUsage, classifyAccountHealth, overdueProbeAccount, lastAu
     "overdueProbeAccount",
     "lastAuthSuccessAt",
   ]);
+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 +496,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,6 +533,7 @@ else {
     const healthOptions = {
       staleAfterMs: pool.staleAfterMs,
       utilizationThreshold: pool.utilizationThreshold,
+      weeklyUtilizationThreshold: pool.weeklyUtilizationThreshold,
       rotateOnOverage: pool.rotateOnOverage,
     };
     const verdicts = members.map((id) => ({
@@ -876,6 +881,7 @@ 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,
         },