@drakon-systems/multi-clawd 2.1.2 → 2.2.0

package/README.md

@@ -284,16 +284,15 @@ claude-cli/claude-fable-5        # main login
 
 ## Platform support
 
-multi-clawd is pure Node (no native modules, no shell-outs) and mirrors the
-bundled `claude-cli` backend 1:1 — it runs anywhere OpenClaw's normal Claude
-Code backend runs.
+multi-clawd uses Node without native modules. External commands are run with
+argument arrays, never through a shell string. Launch mode varies by platform.
 
 | Platform | Status |
 |---|---|
 | Linux | ✅ Verified in production (x64 and arm64) |
-| macOS | ✅ Supported — no platform-specific code paths |
+| macOS | ✅ Supported — reads Claude logins from the Keychain through the `security` CLI and schedules the optional watchdog with a launchd plist in `~/Library/LaunchAgents/` |
 | Windows (WSL2) | ✅ Supported — OpenClaw's recommended gateway runtime on Windows; follow the Linux instructions inside WSL |
-| Windows (native) | ⚠️ Expected to work (the gateway spawns `claude` for this plugin exactly as it does for the bundled backend), not yet verified by us — reports welcome |
+| Windows (native) | ⚠️ Not yet verified by us — verified launch is not implemented on Windows; it falls back to the legacy node + shim launch, so the v2.1.0 verified-launch fix for OpenClaw 2026.10.2 setup authority ("Ask OpenClaw") does not apply there. Reports welcome. |
 
 ## Install
 
@@ -375,6 +374,8 @@ cd multi-clawd && npm install && npm run build
 openclaw plugins install "$(pwd)"
 ```
 
+npm 10 and 11 both work here because the lockfile is committed.
+
 ```powershell
 # Windows (native, PowerShell)
 git clone https://github.com/Drakon-Systems-Ltd/multi-clawd.git
@@ -385,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.2/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.
 
@@ -553,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
@@ -629,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
@@ -745,9 +748,10 @@ What to know:
 
 - **Why a native or config-dir login needs its own token.** That login is a
   rotating one-time OAuth grant, and a copy of it breaks on the next refresh.
-  multi-clawd never reads Claude's own credential files. Run `claude
-  setup-token` signed in as that account and store the token. `setup` walks
-  you through it.
+  multi-clawd never copies that login into a direct profile. (The usage poll
+  and login checks do read Claude's credential files, but never copy or
+  rewrite them.) Run `claude setup-token` signed in as that account and store
+  the token. `setup` walks you through it.
 - **Already stored a profile yourself?** Adopt it with
   `"direct": { "profileId": "anthropic:<id>" }`. It gets ordered, never
   rewritten.
@@ -828,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
@@ -849,11 +865,11 @@ callsite (the ones static scanners flag) and why each exists.
 
 | Surface | What multi-clawd does |
 |---|---|
-| Network | **Zero egress of its own.** The only network activity is npm/registry traffic during `install`/`update`, and the Claude Code subprocesses talking to Anthropic exactly as the bundled backend does. No telemetry, no analytics, no vendor endpoints. |
-| Credentials | Reads each account's setup-token at launch (file, or a secret-manager reference resolved by your gateway) and passes it **only** via the child process env. Never written elsewhere, never logged, never printed — log redaction is covered by dedicated tests. |
-| Files read | `~/.openclaw/openclaw.json` (config), account config dirs you declare (e.g. `~/.claw2`), token files you declare. |
-| Files written | `~/.openclaw/state/multi-clawd/<account>.json` (local usage-health telemetry, stays on the box), config backups the wizard takes before merging, and — only if you accept the wizard's watchdog step — one systemd user unit / launchd plist pointing at the installed watchdog script. |
-| Processes | Spawns the `claude` CLI per turn (same as the bundled backend). The optional watchdog may restart the OpenClaw gateway when the eviction signature appears — that's its entire job, documented below. |
+| Network | The gateway plugin polls `https://api.anthropic.com/api/oauth/usage` for eligible pooled accounts on an interval (default 120000 ms / 2 minutes); `pool.usagePoll.enabled: false` disables that poll. `multi-clawd usage` requests the same endpoint on demand. `doctor` runs `npm view` when its registry cache is stale; install and update commands contact the package registry. Claude Code subprocesses make their own provider requests. No plugin telemetry or analytics endpoint. |
+| Credentials | Reads declared setup-token files or gateway-resolved `oauthTokenRef` values for Claude child launches; reads each eligible account's `.credentials.json` access token for the usage poll; reads Claude login credentials from files or the macOS Keychain via the `security` CLI for login checks and runtime auth; reads account identity for file-backed logins from `.claude.json` (`~/.claude.json` for a native login, or the account config dir). Setup tokens are passed to Claude through the child environment. |
+| Files read | `~/.openclaw/openclaw.json`, declared account config dirs and token files, Claude `.credentials.json` and `.claude.json` files as described above, and local state files. |
+| Files written | Under `~/.openclaw/state/multi-clawd/` by default: `<id>.json`, `<id>.usage.json`, `pool-<id>.sticky.json`, `direct-order.sticky.json`, `known-models.json`, `alerts-spool.jsonl`, `watchdog.json`, `registry-check.json`, `auth-profiles-<agent>.json`, `runtime/<hash>/` (copied runtime files), and `watchdog-launcher.mjs`. The watchdog state file can be redirected with `MULTI_CLAWD_WATCHDOG_STATE`. Setup writes `~/.openclaw/openclaw.json` and a dated backup. On session handover, transcript `.jsonl` files are copied between account config dirs. The optional watchdog installs `~/.config/systemd/user/multi-clawd-eviction-watchdog.service` and `.timer` on Linux, or `~/Library/LaunchAgents/com.multi-clawd.eviction-watchdog.plist` on macOS; the unit points at the state-dir launcher. |
+| Processes | Launches Claude Code and the node + shim transport; CLI, setup and doctor run npm, OpenClaw, Claude and OS scheduler commands; the optional watchdog checks OpenClaw logs and may restart the gateway; Hermes integration runs its Python bridge. See [SECURITY.md](SECURITY.md) for the process-call table. |
 | Consent | The wizard asks before every write, merges non-destructively, and never overwrites an existing account entry. `--dry-run` previews everything. |
 
 Housekeeping:

package/SECURITY.md

@@ -15,9 +15,9 @@ credit you (unless you'd rather we didn't), and note it in the CHANGELOG.
 
 ## How credentials are handled
 
-- **Tokens are never logged and never appear in a command line.** They are
-  passed to the Claude CLI child process through its environment only, so they
-  cannot leak into a process list, a shell history, or a log file.
+- **Tokens are never logged and never appear in a command line.** Claude CLI
+  child launches receive setup tokens through their environment; direct-route
+  OpenClaw commands receive them on stdin.
 - **Secret references are preferred over token files.** `oauthTokenRef` uses
   the same `{source, provider, id}` shape as the rest of `openclaw.json` and
   resolves through the gateway's own configured secret providers (1Password,
@@ -34,8 +34,9 @@ credit you (unless you'd rather we didn't), and note it in the CHANGELOG.
   environment variables covering authentication, runtime, and telemetry are
   cleared before each launch, so one account's credential cannot bleed into
   another account's session.
-- **State files are written `0600`,** atomically (temp file + rename), and
-  contain rate-limit telemetry only — never credentials.
+- **Per-account health and usage files are written `0600`,** using temporary
+  files and rename, and contain rate-limit data rather than credentials. Other
+  state files include model, alert, registry and watchdog data.
 
 ## Permissions
 
@@ -48,20 +49,25 @@ nothing and Claude keeps its default prompt-honouring behaviour.
 ## Why static scanners flag this package
 
 Automated scans flag multi-clawd for `dangerous_exec`. That is expected and
-correct: starting Claude Code processes *is* the product. Every such callsite
-is listed here so you can check them yourself.
+correct: starting Claude Code processes *is* the product. Every source file
+that calls a child-process API is listed here so you can check it yourself.
 
 | Location | What it runs | Why |
 | --- | --- | --- |
-| `dist/shim.js` | the `claude` binary | The core function: launches Claude Code for the selected account. Argv is built from a fixed base list plus your configured model; no shell. |
-| `dist/watchdog-schedule.js` | `node <bundled script>` | Runs the eviction watchdog on a timer. Path is the package's own script. |
-| `scripts/cli.mjs` | `node <bundled script>` | The CLI dispatching to its own subcommands. |
-| `scripts/setup.mjs` | `launchctl` / `systemctl` | Loads the watchdog timer during setup on macOS/Linux. |
-| `dist/openclaw-runner.js` | the `openclaw` CLI (or `directRoute.openclawCommand`) | Direct route only (v1.9, accounts with `direct`): reads and writes the `anthropic` auth profiles and order through OpenClaw's own subcommands (`models auth list`/`order get`/`order set`/`paste-token`, `secrets apply`, `models status`). A setup-token only ever travels on the child's stdin. Never spawned without `direct` configured. |
-
-None of these pass a string to a shell — they are direct process spawns with
-argument arrays, so there is no quoting or injection surface. Paths are
-package-internal or derived from your home directory, never from remote input.
+| `dist/shim.js` | selected `claude` executable | Launches Claude Code for the selected account and, when an in-turn retry is armed, relaunches it for a sibling account. |
+| `dist/shim-transport.js` | `node <shim>` | Runs the shim for an execute-transport turn. |
+| `dist/credential-store.js` | `security find-generic-password` / `security dump-keychain` | Reads a macOS Keychain login or inventories Keychain item attributes for credential checks. |
+| `dist/watchdog-schedule.js` | generated `watchdog-launcher.mjs` runs `node <bundled eviction-watchdog.mjs>` | Renders the state-dir launcher that a systemd user timer or launchd agent runs. The launcher resolves the current install before spawning its bundled watchdog script. |
+| `dist/openclaw-runner.js` | the `openclaw` CLI (or `directRoute.openclawCommand`) | Direct route only: reads and writes the `anthropic` auth profiles and order through OpenClaw subcommands. A setup token travels on the child's stdin. |
+| `scripts/cli.mjs` | `npm view` / `npm i -g`, `openclaw --version`, `openclaw` plugin install and gateway restart, `claude` login/status commands, `launchctl` / `systemctl`, and `node <bundled script>` | Checks and updates the CLI/plugin, handles account login, dispatches subcommands and repairs watchdog scheduling. |
+| `scripts/setup.mjs` | `claude --version`, `launchctl` / `systemctl` | Checks the Claude CLI and loads or repairs optional watchdog scheduling. |
+| `scripts/doctor.mjs` | `npm view`, `claude --version`, `openclaw models auth list` / `openclaw agent`, `launchctl` / `systemctl` | Checks registry version when its cache is stale, inspects auth and watchdog status, and optionally probes accounts. |
+| `scripts/eviction-watchdog.mjs` | `openclaw logs --plain` / `openclaw gateway restart` | Detects the eviction signature and restarts the gateway when the watchdog's conditions are met. |
+| `scripts/hermes.mjs` | Python interpreter with `-c` / bundled bridge | Checks Python availability and runs the Hermes bridge. |
+
+None of these pass a command string to a shell: child-process calls use an
+executable and argument array. The launcher generated by `watchdog-schedule`
+uses the same form.
 
 ## Things you should decide for yourself
 

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.2",
+  "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.2",
+  "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",
@@ -61,7 +61,7 @@
     "setup": "node scripts/setup.mjs",
     "sync-manifest": "node -e \"const fs=require('fs');const m=JSON.parse(fs.readFileSync('openclaw.plugin.json','utf8'));m.version=process.env.npm_package_version||JSON.parse(fs.readFileSync('package.json','utf8')).version;fs.writeFileSync('openclaw.plugin.json',JSON.stringify(m,null,2)+'\\n')\"",
     "sync-readme-tag": "node scripts/sync-readme-tag.mjs",
-    "version": "npm run sync-manifest && npm run sync-readme-tag && git add openclaw.plugin.json README.md"
+    "version": "npm run sync-manifest && npm run sync-readme-tag && git add openclaw.plugin.json README.md package-lock.json"
   },
   "peerDependencies": {
     "openclaw": ">=2026.8.1"

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,
         },