@drakon-systems/multi-clawd 1.9.8 → 2.0.0

package/dist/shim.js

@@ -5,7 +5,7 @@ import { classifyStateReadFailure, clearCredentialFailure, clearModelRejection,
 import { rewriteModelArg } from "./degrade.js";
 import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
 import { canonicalModelId } from "./models.js";
-import { buildRetryEnv, chooseRetryAccount, parseRetryRoster, retryArming, RETRY_ROSTER_ENV, } from "./retry-plan.js";
+import { buildRetryEnv, chooseLaunchableRetryAccount, materializeRetryAccount, parseRetryRoster, retryArming, RETRY_ROSTER_ENV, } from "./retry-plan.js";
 import { effectiveConfigDir, handoverForLaunch, handoverSnapshotTo, parseSessionDirs, SESSION_DIRS_ENV, snapshotResumeTranscript, } from "./session-handover.js";
 function resolveClaudeCommand() {
     const override = process.env.MULTI_CLAWD_CLAUDE_BIN;
@@ -95,6 +95,7 @@ if (modelOverride) {
         process.stderr.write(`[multi-clawd shim] ${note}\n`);
 }
 const retryRoster = parseRetryRoster(process.env[RETRY_ROSTER_ENV]);
+delete process.env[RETRY_ROSTER_ENV];
 const resumeSnapshot = retryRoster.length > 0 && parseSessionDirs(process.env[SESSION_DIRS_ENV]).length > 0
     ? snapshotResumeTranscript(childArgs, process.env)
     : undefined;
@@ -233,11 +234,13 @@ function attemptRetry() {
     if (!retryArmed || retryUsed)
         return false;
     const model = effectiveModelId();
-    const target = chooseRetryAccount({
+    const target = chooseLaunchableRetryAccount({
         roster: retryRoster,
         readState: readSiblingState,
         modelId: model,
         nowMs: Date.now(),
+        materialize: (account) => materializeRetryAccount(account, (path) => readFileSync(path, "utf8")),
+        onSkip: (id, reason) => process.stderr.write(`[multi-clawd shim] not retrying onto ${id}: its declared credential did not resolve (${reason})\n`),
     });
     if (!target) {
         process.stderr.write(`[multi-clawd shim] model limit on ${accountId} with no healthy sibling to retry onto — ` +

package/dist/usage-poll.js

@@ -0,0 +1,372 @@
+import { classifyAccountHealth } from "./health.js";
+import { mergeHealthStates } from "./shim-core.js";
+export const USAGE_ENDPOINT = "https://api.anthropic.com/api/oauth/usage";
+export const USAGE_WINDOW_PREFIX = "usage:";
+export const DEFAULT_USAGE_POLL_INTERVAL_MS = 2 * 60 * 1000;
+export const MIN_USAGE_POLL_INTERVAL_MS = 60 * 1000;
+export const MAX_USAGE_POLL_INTERVAL_MS = 30 * 60 * 1000;
+export const DEFAULT_USAGE_WARN_THRESHOLD = 0.95;
+export const USAGE_FETCH_TIMEOUT_MS = 15_000;
+export function effectiveUsagePollInterval(cfg) {
+    const requested = cfg?.intervalMs ?? DEFAULT_USAGE_POLL_INTERVAL_MS;
+    if (!Number.isFinite(requested))
+        return DEFAULT_USAGE_POLL_INTERVAL_MS;
+    return Math.min(MAX_USAGE_POLL_INTERVAL_MS, Math.max(MIN_USAGE_POLL_INTERVAL_MS, requested));
+}
+export function effectiveUsageWarnThreshold(cfg) {
+    const t = cfg?.warnThreshold;
+    return typeof t === "number" && t > 0 && t <= 1 ? t : DEFAULT_USAGE_WARN_THRESHOLD;
+}
+function parseResetsAt(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : undefined;
+}
+function parsePercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return undefined;
+    return value / 100;
+}
+const WINDOW_KEY_RE = /^(five_hour|seven_day(_[a-z0-9_]+)?)$/;
+export function parseUsageResponse(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const b = body;
+    const windows = {};
+    for (const [key, value] of Object.entries(b)) {
+        if (!WINDOW_KEY_RE.test(key))
+            continue;
+        if (typeof value !== "object" || value === null)
+            continue;
+        const w = value;
+        const utilization = parsePercent(w.utilization);
+        if (utilization === undefined)
+            continue;
+        windows[key] = { utilization, resetsAt: parseResetsAt(w.resets_at) };
+    }
+    const scoped = [];
+    if (Array.isArray(b.limits)) {
+        for (const entry of b.limits) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const e = entry;
+            const scope = e.scope;
+            const model = scope?.model;
+            const label = model?.display_name;
+            const utilization = parsePercent(e.percent);
+            if (typeof label !== "string" || !label.trim() || utilization === undefined)
+                continue;
+            scoped.push({ label: label.trim(), utilization, resetsAt: parseResetsAt(e.resets_at) });
+        }
+    }
+    if (Object.keys(windows).length === 0)
+        return undefined;
+    return { windows, scoped };
+}
+export const ACCOUNT_USAGE_WINDOWS = ["five_hour", "seven_day"];
+export function usageHealthWindows(snapshot, nowMs) {
+    const out = {};
+    for (const [key, w] of Object.entries(snapshot.windows)) {
+        if (!ACCOUNT_USAGE_WINDOWS.includes(key))
+            continue;
+        out[`${USAGE_WINDOW_PREFIX}${key}`] = {
+            status: w.utilization >= 1 ? "rejected" : "allowed",
+            utilization: w.utilization,
+            resetsAt: w.resetsAt,
+            seenAt: nowMs,
+        };
+    }
+    return out;
+}
+export function readOAuthAccessToken(raw, nowMs) {
+    if (raw === undefined)
+        return { skip: "no .credentials.json (not signed in, or credentials held elsewhere)" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { skip: ".credentials.json is not valid JSON" };
+    }
+    const oauth = parsed?.claudeAiOauth;
+    if (typeof oauth !== "object" || oauth === null)
+        return { skip: ".credentials.json has no OAuth session" };
+    const o = oauth;
+    if (typeof o.accessToken !== "string" || o.accessToken.trim() === "") {
+        return { skip: ".credentials.json has no access token" };
+    }
+    if (typeof o.expiresAt === "number" && o.expiresAt <= nowMs) {
+        return { skip: "access token expired — the next CLI launch refreshes it" };
+    }
+    return { token: o.accessToken };
+}
+export async function fetchUsage(token, fetchImpl, timeoutMs = USAGE_FETCH_TIMEOUT_MS) {
+    const controller = typeof AbortController === "function" ? new AbortController() : undefined;
+    const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+    try {
+        const res = await fetchImpl(USAGE_ENDPOINT, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "anthropic-beta": "oauth-2025-04-20",
+                accept: "application/json",
+            },
+            signal: controller?.signal,
+        });
+        if (res.status === 401 || res.status === 403) {
+            return { ok: false, kind: "auth", reason: `usage endpoint refused the login (HTTP ${res.status})` };
+        }
+        if (res.status === 429)
+            return { ok: false, kind: "throttled", reason: "usage endpoint rate-limited the poll" };
+        if (res.status < 200 || res.status >= 300) {
+            return { ok: false, kind: "transient", reason: `usage endpoint returned HTTP ${res.status}` };
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            return { ok: false, kind: "parse", reason: "usage endpoint returned a non-JSON body" };
+        }
+        const snapshot = parseUsageResponse(body);
+        if (!snapshot)
+            return { ok: false, kind: "parse", reason: "usage endpoint body had no readable window" };
+        return { ok: true, snapshot };
+    }
+    catch (err) {
+        const name = err instanceof Error ? err.name : typeof err;
+        return { ok: false, kind: "transient", reason: `usage request failed (${name})` };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export function usageWindowLabel(window) {
+    const bare = window.startsWith(USAGE_WINDOW_PREFIX) ? window.slice(USAGE_WINDOW_PREFIX.length) : window;
+    if (bare === "five_hour")
+        return "5-hour";
+    if (bare === "seven_day")
+        return "weekly";
+    if (bare.startsWith("seven_day_"))
+        return `weekly ${bare.slice("seven_day_".length).replace(/_/g, " ")}`;
+    return bare;
+}
+function relative(resetsAt, nowMs) {
+    if (resetsAt === undefined)
+        return "";
+    const mins = Math.max(0, Math.round((resetsAt * 1000 - nowMs) / 60000));
+    if (mins < 90)
+        return ` (resets in ~${mins}m)`;
+    const hours = Math.round(mins / 60);
+    if (hours < 36)
+        return ` (resets in ~${hours}h)`;
+    return ` (resets in ~${Math.round(hours / 24)}d)`;
+}
+export function usageAlertPrefix(poolId) {
+    return `usage:${poolId}:`;
+}
+export function usagePoolAlertKey(poolId) {
+    return `usage-pool:${poolId}`;
+}
+export function decideUsageAlerts(params) {
+    const { poolId, accounts, warnThreshold, nowMs } = params;
+    const raise = [];
+    const keep = new Set();
+    const prefix = usageAlertPrefix(poolId);
+    const answered = accounts.filter((a) => a.snapshot !== undefined);
+    const hot = new Set();
+    let soonestReset;
+    for (const account of answered) {
+        const snapshot = account.snapshot;
+        const others = accounts.filter((a) => a.id !== account.id);
+        const sibling = others.find((a) => a.verdict === "ok" || a.verdict === "no_data" || a.verdict === undefined);
+        for (const [window, w] of Object.entries(snapshot.windows)) {
+            if (w.utilization < warnThreshold)
+                continue;
+            if (ACCOUNT_USAGE_WINDOWS.includes(window)) {
+                hot.add(account.id);
+                if (w.resetsAt !== undefined && (soonestReset === undefined || w.resetsAt < soonestReset)) {
+                    soonestReset = w.resetsAt;
+                }
+            }
+            const key = `${prefix}${account.id}:${window}`;
+            keep.add(key);
+            const pct = Math.round(w.utilization * 100);
+            const where = !ACCOUNT_USAGE_WINDOWS.includes(window)
+                ? w.utilization >= 1
+                    ? "that model is refused on this account until reset"
+                    : "that model will be refused on this account at 100%"
+                : w.utilization >= 1
+                    ? "this account is exhausted on that window"
+                    : others.length === 0
+                        ? "no sibling account to hand over to"
+                        : sibling
+                            ? `new launches route to ${sibling.id}`
+                            : "no healthy sibling to hand over to";
+            raise.push({
+                key,
+                severity: "error",
+                text: `pool ${poolId}: account "${account.id}" ${usageWindowLabel(window)} usage at ${pct}%${relative(w.resetsAt, nowMs)} — ${where}`,
+            });
+        }
+        for (const limit of snapshot.scoped) {
+            if (limit.utilization < warnThreshold)
+                continue;
+            const key = `${prefix}${account.id}:model:${limit.label.toLowerCase().replace(/\s+/g, "-")}`;
+            keep.add(key);
+            const pct = Math.round(limit.utilization * 100);
+            raise.push({
+                key,
+                severity: "error",
+                text: `pool ${poolId}: account "${account.id}" ${limit.label} model limit at ${pct}%${relative(limit.resetsAt, nowMs)} — ${limit.utilization >= 1 ? "that model is refused on this account until reset" : "that model will be refused on this account at 100%"}`,
+            });
+        }
+    }
+    if (accounts.length > 0 && hot.size === accounts.length) {
+        const key = usagePoolAlertKey(poolId);
+        keep.add(key);
+        const pct = Math.round(warnThreshold * 100);
+        raise.push({
+            key,
+            severity: "error",
+            text: `pool ${poolId}: EVERY account is above ${pct}% on at least one usage window — ` +
+                `at 100% turns degrade down the ladder or fall through to the next provider` +
+                `${soonestReset !== undefined ? `; soonest reset${relative(soonestReset, nowMs)}` : ""}`,
+        });
+    }
+    return { raise, keep };
+}
+export function createUsagePollController(params) {
+    const { poolId, members, healthOptions, warnThreshold, io } = params;
+    const now = io.now ?? (() => Date.now());
+    const lastProblem = new Map();
+    const lastVerdict = new Map();
+    const noteProblem = (id, problem) => {
+        const previous = lastProblem.get(id);
+        if (problem === previous)
+            return;
+        if (problem)
+            io.logger.warn(`[multi-clawd] usage poll: account "${id}" — ${problem}`);
+        else if (previous)
+            io.logger.info(`[multi-clawd] usage poll: account "${id}" — reading usage again`);
+        if (problem)
+            lastProblem.set(id, problem);
+        else
+            lastProblem.delete(id);
+    };
+    async function tick() {
+        const at = now();
+        const reports = [];
+        for (const member of members) {
+            let raw;
+            try {
+                raw = io.readFile(member.credentialsFile);
+            }
+            catch (err) {
+                raw = undefined;
+                noteProblem(member.id, `credentials unreadable (${err instanceof Error ? err.name : String(err)})`);
+                reports.push({ id: member.id, skipped: "credentials unreadable", verdict: verdictFor(member.id) });
+                continue;
+            }
+            const token = readOAuthAccessToken(raw, at);
+            if ("skip" in token) {
+                noteProblem(member.id, token.skip);
+                reports.push({ id: member.id, skipped: token.skip, verdict: verdictFor(member.id) });
+                continue;
+            }
+            const result = await fetchUsage(token.token, io.fetchImpl);
+            if (!result.ok) {
+                noteProblem(member.id, result.reason);
+                reports.push({ id: member.id, failure: { kind: result.kind, reason: result.reason }, verdict: verdictFor(member.id) });
+                continue;
+            }
+            const live = {
+                accountId: member.id,
+                updatedAt: at,
+                windows: usageHealthWindows(result.snapshot, at),
+            };
+            try {
+                io.writeUsage(member.id, live);
+            }
+            catch (err) {
+                io.logger.warn(`[multi-clawd] usage poll: usage write failed for "${member.id}": ${String(err)}`);
+            }
+            let disk;
+            try {
+                disk = io.readHealth(member.id) ?? { accountId: member.id, windows: {} };
+            }
+            catch (err) {
+                noteProblem(member.id, `health file unreadable (${err instanceof Error ? err.message : String(err)})`);
+                reports.push({ id: member.id, snapshot: result.snapshot, skipped: "health file unreadable", verdict: "no_data" });
+                continue;
+            }
+            noteProblem(member.id, undefined);
+            const merged = mergeHealthStates(disk, live, at);
+            const verdict = classifyAccountHealth(merged, healthOptions, at).verdict;
+            const previous = lastVerdict.get(member.id);
+            if (previous !== undefined && previous !== verdict) {
+                io.logger.info(`[multi-clawd] usage poll: account "${member.id}" ${previous} → ${verdict} (${describeSnapshot(result.snapshot)})`);
+            }
+            else if (previous === undefined) {
+                io.logger.info(`[multi-clawd] usage poll: account "${member.id}" ${describeSnapshot(result.snapshot)} → ${verdict}`);
+            }
+            lastVerdict.set(member.id, verdict);
+            reports.push({ id: member.id, snapshot: result.snapshot, verdict });
+        }
+        const known = reports.filter((r) => r.snapshot !== undefined && r.skipped === undefined);
+        const unknown = reports.filter((r) => !known.includes(r));
+        const decision = decideUsageAlerts({
+            poolId,
+            accounts: reports.map((r) => ({ id: r.id, snapshot: known.includes(r) ? r.snapshot : undefined, verdict: r.verdict })),
+            warnThreshold,
+            nowMs: at,
+        });
+        for (const r of unknown) {
+            for (const key of io.alertKeysWithPrefix(`${usageAlertPrefix(poolId)}${r.id}:`))
+                decision.keep.add(key);
+        }
+        if (unknown.length > 0) {
+            for (const key of io.alertKeysWithPrefix(usagePoolAlertKey(poolId)))
+                decision.keep.add(key);
+        }
+        const raised = [];
+        for (const alert of decision.raise) {
+            io.raiseAlert(alert);
+            raised.push(alert.key);
+        }
+        const cleared = [];
+        const family = [...io.alertKeysWithPrefix(usageAlertPrefix(poolId)), ...io.alertKeysWithPrefix(usagePoolAlertKey(poolId))];
+        for (const key of family) {
+            if (decision.keep.has(key))
+                continue;
+            io.clearAlert(key);
+            cleared.push(key);
+        }
+        return { at, accounts: reports, raised, cleared };
+    }
+    const lastReadProblem = new Map();
+    function verdictFor(id) {
+        let state;
+        try {
+            state = io.readHealth(id);
+        }
+        catch (err) {
+            const problem = `health file unreadable (${err instanceof Error ? err.message : String(err)})`;
+            if (lastReadProblem.get(id) !== problem) {
+                io.logger.warn(`[multi-clawd] usage poll: account "${id}" — ${problem}`);
+                lastReadProblem.set(id, problem);
+            }
+            return "no_data";
+        }
+        lastReadProblem.delete(id);
+        return classifyAccountHealth(state, healthOptions, now()).verdict;
+    }
+    return { tick };
+}
+export function describeSnapshot(snapshot) {
+    const parts = Object.entries(snapshot.windows).map(([k, w]) => `${usageWindowLabel(k)} ${Math.round(w.utilization * 100)}%`);
+    for (const s of snapshot.scoped)
+        parts.push(`${s.label} ${Math.round(s.utilization * 100)}%`);
+    return parts.join(" · ");
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.9.8",
+  "version": "2.0.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",
@@ -59,6 +59,25 @@
             "type": "number",
             "description": "After rotating away from home, stay on the rotated-to account at least this long before returning home (anti-flap hysteresis; health always overrides). Default 600000 (10min)."
           },
+          "usagePoll": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Live usage polling (v1.10): read each pooled account's current usage from the provider on a timer (the same figures the Claude CLI's /usage shows) and fold them into the pool's health state, so near-limit rotation fires on the 5-hour window with a real percentage behind it and a window at 100% is exhausted before a turn is refused. Raises an operator alert (via the heartbeat) when any window passes warnThreshold. Read-only on credentials: uses the login the CLI already holds, never refreshes or copies it. Applies to native and configDir accounts; token-based accounts keep stream telemetry only.",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "Default true. Set false to turn polling off entirely."
+              },
+              "intervalMs": {
+                "type": "number",
+                "description": "Poll interval. Default 120000 (2min); minimum 60000."
+              },
+              "warnThreshold": {
+                "type": "number",
+                "description": "Raise an operator alert when any usage window reaches this fraction. Default 0.95."
+              }
+            }
+          },
           "degrade": {
             "type": "object",
             "additionalProperties": false,

package/package.json

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

@@ -39,6 +39,7 @@ ${BOLD}🦞 multi-clawd${RESET} — multi-account Claude failover for OpenClaw
   ${BOLD}explain${RESET}   your setup in plain English — accounts, pool, fallback chain
   ${BOLD}chain${RESET}     audit your model routing — what actually serves each turn
   ${BOLD}direct${RESET}    the direct anthropic/* route — status, or \`direct sync\` to store profiles
+  ${BOLD}usage${RESET}     live usage per account from the provider — what is left, and what the pool will do
   ${BOLD}update${RESET}    update the plugin to the latest version
   ${BOLD}doctor${RESET}    health check (add --probe for a live turn)
   ${BOLD}hermes${RESET}    sync or diagnose Hermes Agent's Anthropic credential pool
@@ -711,6 +712,115 @@ async function explain() {
   console.log(`\n${DIM}(health checks: multi-clawd doctor · change things: multi-clawd setup)${RESET}`);
 }
 
+/**
+ * `usage` — ask the provider for each account's live usage (the figures the
+ * Claude CLI's own /usage shows), print them next to the pool's verdict, and
+ * say which account the next pooled launch would run on. Read-only: uses the
+ * login the CLI already holds and never refreshes or copies it. `--json` for
+ * machines.
+ */
+async function usageCommand(args) {
+  const { readFileSync: rf } = await import("node:fs");
+  const { homedir } = await import("node:os");
+  let up, health, shim, env;
+  try {
+    up = await import(resolve(__dirname, "..", "dist", "usage-poll.js"));
+    health = await import(resolve(__dirname, "..", "dist", "health.js"));
+    shim = await import(resolve(__dirname, "..", "dist", "shim-core.js"));
+    env = await import(resolve(__dirname, "..", "dist", "account-env.js"));
+  } catch (err) {
+    console.error(distFailure("usage", "usage-poll.js", err));
+    process.exit(1);
+  }
+  const config = readOpenclawConfigSync();
+  if (!config) {
+    console.error("usage: could not read ~/.openclaw/openclaw.json");
+    process.exit(1);
+  }
+  const pc = config?.plugins?.entries?.["multi-clawd"]?.config ?? {};
+  const accounts = Array.isArray(pc.accounts) ? pc.accounts : [];
+  const pool = pc.pool ? { ...pc.pool, id: pc.pool.id?.trim() || "clawd", accounts: pc.pool.accounts ?? [] } : undefined;
+  const healthOptions = {
+    utilizationThreshold: pool?.utilizationThreshold,
+    staleAfterMs: pool?.staleAfterMs,
+    rotateOnOverage: pool?.rotateOnOverage,
+  };
+  const warnThreshold = up.effectiveUsageWarnThreshold(pool?.usagePoll);
+  const rotateAt = pool?.utilizationThreshold ?? 0.85;
+  const stateDir = join(homedir(), ".openclaw", "state", "multi-clawd");
+  const now = Date.now();
+  const rows = [];
+  for (const a of accounts) {
+    const row = { id: a.id, label: a.label };
+    if (a.oauthTokenFile || a.oauthTokenRef) {
+      row.skipped = "setup-token login — not polled: the usage endpoint needs the user:profile scope, setup-tokens carry only user:inference (stream telemetry only)";
+    } else if (!a.native && !a.configDir) {
+      row.skipped = "no login dir";
+    } else {
+      let raw;
+      try {
+        raw = rf(join(env.accountConfigDir(a), ".credentials.json"), "utf8");
+      } catch {
+        raw = undefined;
+      }
+      const token = up.readOAuthAccessToken(raw, now);
+      if ("skip" in token) row.skipped = token.skip;
+      else {
+        const r = await up.fetchUsage(token.token, (url, init) => fetch(url, init));
+        if (r.ok) row.snapshot = r.snapshot;
+        else row.failure = r.reason;
+      }
+    }
+    let state;
+    try {
+      state = shim.parseStoredState(rf(join(stateDir, `${a.id}.json`), "utf8"));
+    } catch {
+      /* no telemetry yet */
+    }
+    const h = health.classifyAccountHealth(state, healthOptions, now);
+    row.verdict = h.verdict;
+    row.reason = h.reason;
+    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);
+  }
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ at: new Date(now).toISOString(), rotateAt, warnThreshold, pool: pool?.id, nextLaunch: next, accounts: rows }, null, 2));
+    return;
+  }
+  const pct = (u) => `${Math.round(u * 100)}%`;
+  const until = (resetsAt) => {
+    if (resetsAt === undefined) return "";
+    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`);
+  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)}`);
+      }
+      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)}`);
+      }
+    } else if (r.failure) {
+      console.log(`     ⚠️  ${r.failure}`);
+    } else {
+      console.log(`     ${DIM}not polled: ${r.skipped}${RESET}`);
+    }
+    console.log("");
+  }
+  if (pool) {
+    console.log(next ? `  next pooled launch (${pool.id}/…) runs on ${BOLD}${next}${RESET}` : `  ${BOLD}every pooled account is exhausted${RESET} — turns degrade or fall through the chain`);
+  }
+  console.log(`\n${DIM}(the gateway polls this every ${Math.round(up.effectiveUsagePollInterval(pool?.usagePoll) / 1000)}s and alerts via the heartbeat; see "Live usage" in the README)${RESET}`);
+}
+
 /**
  * `login <account>` — launch the RIGHT Claude login flow for a configured
  * account: correct config-dir environment, dir created if missing, verified
@@ -831,6 +941,9 @@ switch (cmd) {
   case "direct":
     await direct(rest);
     break;
+  case "usage":
+    await usageCommand(rest);
+    break;
   case "doctor":
     runSibling("doctor.mjs", rest);
     break;