@drakon-systems/multi-clawd 2.5.1 → 2.6.1

package/README.md

@@ -31,6 +31,7 @@ multi-clawd setup     # guided wizard: accounts, isolated second login, pool, wa
 multi-clawd login claw2   # launch the right Claude sign-in for an account (or re-auth it)
 multi-clawd explain   # your whole setup in plain English — accounts, chain, live health
 multi-clawd explain --history --since 7d   # per-account launches, retries, rotations
+multi-clawd explain --json   # live health plus a rough weekly pace estimate, machine-readable
 multi-clawd account disable claw2 --dry-run  # preview benching an account
 multi-clawd chain     # audit your model routing — what actually serves each turn
 multi-clawd direct    # the direct anthropic/* route: status, or `direct sync` (v1.9, optional)
@@ -415,7 +416,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.5.1/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.6.1/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.
 

package/dist/explain-core.js

@@ -30,6 +30,49 @@ export function renderUsageLine(usage, nowMs) {
     })
         .join(" · ");
 }
+const WEEK_MS = 7 * 86_400_000;
+const MIN_PACE_ELAPSED_MS = WEEK_MS / 10;
+const PACE_RESET_SLACK_MS = 3_600_000;
+export function computeWeeklyPace(usage, nowMs) {
+    const u = ["usage:seven_day", "seven_day"]
+        .map((w) => usage?.find((x) => x.window === w))
+        .find((x) => x !== undefined);
+    if (!u || u.resetsAt === undefined)
+        return undefined;
+    if (!Number.isFinite(u.utilization) || u.utilization < 0 || u.utilization > 1)
+        return undefined;
+    if (!Number.isFinite(u.resetsAt) || !Number.isFinite(nowMs))
+        return undefined;
+    const remaining = u.resetsAt - nowMs;
+    if (remaining <= 0 || remaining > WEEK_MS + PACE_RESET_SLACK_MS)
+        return undefined;
+    const elapsed = Math.max(0, WEEK_MS - remaining);
+    if (elapsed < MIN_PACE_ELAPSED_MS)
+        return undefined;
+    const expectedPct = elapsed / WEEK_MS;
+    const projectedExhaustionAt = u.utilization >= 1
+        ? nowMs
+        : u.utilization > 0 ? nowMs + ((1 - u.utilization) * elapsed) / u.utilization : undefined;
+    return {
+        window: u.window,
+        expectedPct,
+        aheadOfPace: u.utilization - expectedPct,
+        projectedExhaustionAt,
+        willLastToReset: projectedExhaustionAt === undefined || projectedExhaustionAt >= u.resetsAt,
+        resetsAt: u.resetsAt,
+        estimate: true,
+    };
+}
+export function renderPaceLine(pace, nowMs) {
+    if (!pace)
+        return undefined;
+    const pts = Math.round(pace.aheadOfPace * 100);
+    const where = pts === 0 ? "on pace" : pts > 0 ? `${pts} points ahead of pace` : `${-pts} points behind pace`;
+    const verdict = pace.willLastToReset
+        ? "should last to the reset"
+        : `could run out in ${relativeUntil(pace.projectedExhaustionAt ?? nowMs, nowMs)}, before the reset in ${relativeUntil(pace.resetsAt, nowMs)}`;
+    return `weekly pace (rough estimate): ~${Math.round(pace.expectedPct * 100)}% of the week gone, ${where}; ${verdict}`;
+}
 export function describeAccount(acc) {
     if (acc.native) {
         return "the machine's main `claude` login (default config dir; OS keychain on macOS)";
@@ -145,6 +188,9 @@ export function renderExplanation(model) {
             const word = VERDICT_WORDS[h.verdict] ?? h.verdict;
             lines.push(`  ${h.id}: ${model.accounts.find((a) => a.id === h.id)?.disabled ? "disabled by operator" : word}${h.detail ? ` — ${h.detail}` : ""}`);
             lines.push(`      usage: ${h.usage?.length ? renderUsageLine(h.usage, nowMs) : "no live telemetry"}`);
+            const paceLine = renderPaceLine(computeWeeklyPace(h.usage, nowMs), nowMs);
+            if (paceLine)
+                lines.push(`      ${paceLine}`);
         }
         if (model.pool) {
             const strategy = poolStrategy(model.pool.strategy);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "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",

package/package.json

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

@@ -9,7 +9,7 @@
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 /** Where the plugin is installed: path install wins, else newest npm-project install. */
 export function resolveInstallDir() {
@@ -50,3 +50,57 @@ export const WATCHDOG_LAUNCHER = join(
   "multi-clawd",
   "watchdog-launcher.mjs",
 );
+
+/** The default OpenClaw config path, resolved for display (never a literal `~`). */
+export function openclawConfigPath() {
+  return join(homedir(), ".openclaw", "openclaw.json");
+}
+
+/**
+ * One diagnostic for every command that needs the OpenClaw config (#106).
+ *
+ * `error` is whatever reading or parsing threw. The message names the resolved
+ * path and the next step, and keeps the real causes apart: the file is missing
+ * (and whether OpenClaw itself looks installed), it is unreadable for this
+ * user, it is not a regular file, or it is present but not valid JSON. It never
+ * repeats raw Node error text: an fs message is noise to a first-time user, and
+ * a JSON SyntaxError quotes a slice of the file, which may hold credentials.
+ *
+ * A `configPath` other than the default (hermes `--config`) gets a "check the
+ * path" step instead of `multi-clawd setup`, which only writes the default;
+ * that split applies to the missing and the not-a-regular-file cases alike.
+ */
+export function describeOpenclawConfigError(error, configPath = openclawConfigPath()) {
+  const code = typeof error?.code === "string" ? error.code : undefined;
+  const isDefault = configPath === openclawConfigPath();
+  const at = `OpenClaw config at ${configPath}`;
+  if (code === "ENOENT") {
+    const dir = dirname(configPath);
+    if (isDefault && !existsSync(dir)) {
+      return `OpenClaw config not found at ${configPath} (no ${dir} directory). ` +
+        "Install and start OpenClaw first, then run `multi-clawd setup`.";
+    }
+    return `OpenClaw config not found at ${configPath}. ` + (isDefault
+      ? "Run `multi-clawd setup` to create it."
+      : "Check the --config path, or omit it to use the default location.");
+  }
+  if (code === "EACCES" || code === "EPERM") {
+    return `${at} is not readable: permission denied. Run multi-clawd as the user that ` +
+      "owns the OpenClaw install, or fix the file's ownership and mode; `multi-clawd setup` cannot fix this.";
+  }
+  const notRegular = { EISDIR: "it is a directory", ELOOP: "it is a symbolic-link loop",
+    ENOTDIR: "a parent in the path is not a directory" }[code];
+  if (notRegular) {
+    // `multi-clawd setup` writes only the default path, so for a custom
+    // `--config` the fix is the named path (or the option), never setup.
+    return `${at} is not a regular file (${notRegular}). ` + (isDefault
+      ? "Move whatever is at that path aside, then run `multi-clawd setup` or restore the OpenClaw config file."
+      : "Restore the OpenClaw config file at that path, or correct the --config path (omit it to use the " +
+        "default location); `multi-clawd setup` only writes the default path.");
+  }
+  if (error instanceof SyntaxError) {
+    return `${at} is malformed JSON. Fix the file by hand (a JSON validator helps) and retry; ` +
+      "`multi-clawd setup` does not repair it.";
+  }
+  return `${at} could not be read${code ? ` (${code})` : ""}.`;
+}

package/scripts/cli.mjs

@@ -50,6 +50,27 @@ Run via npx (${DIM}npx ${PKG} <command>${RESET}) or install globally
 `);
 }
 
+// Per-command usage, printed for `<command> --help` / `-h` before anything is
+// dispatched, so asking for help never reads config, runs checks, or starts the
+// setup wizard. `hermes` is absent on purpose: it handles its own help.
+const COMMAND_HELP = {
+  setup: "multi-clawd setup [--dry-run]\n\n  Guided setup wizard (accounts, pool, watchdog).\n  --dry-run   preview the changes without writing anything",
+  login: "multi-clawd login [<id>]\n\n  Log a configured account in (or re-auth it). Without <id>, lists the\n  configured accounts to choose from.",
+  account: "multi-clawd account <enable|disable> <id> [--dry-run]\n\n  Disable or enable a pool account.\n  --dry-run   preview the change without writing it",
+  explain: "multi-clawd explain [--json | --history [--since 7d|24h]]\n\n  Your setup in plain English: accounts, pool, fallback chain.\n  --json      machine-readable output\n  --history   recent pool events; --since limits the window",
+  chain: "multi-clawd chain [--raw]\n\n  Audit your model routing: what actually serves each turn.\n  --raw       include raw routing detail",
+  direct: "multi-clawd direct [status | sync [--dry-run] [--yes] [--resync]]\n\n  The direct anthropic/* route. Default is status.\n  sync        store profiles for the direct route\n  --dry-run   preview without writing\n  --yes       skip the confirmation prompt\n  --resync    refresh profiles that are already stored",
+  usage: "multi-clawd usage [--json]\n\n  Live usage per account from the provider: what is left, and what the\n  pool will do.\n  --json      machine-readable output",
+  update: "multi-clawd update\n\n  Update the plugin to the latest version.",
+  doctor: "multi-clawd doctor [--probe] [--probe-pool] [--verbose] [--raw]\n\n  Health check.\n  --probe       run a live turn per account plus the pool\n  --probe-pool  with --probe: probe the pool ref only (one turn)\n  --verbose     show more detail\n  --raw         show raw output",
+  version: "multi-clawd version\n\n  Show CLI and installed plugin versions.",
+};
+
+if (Object.hasOwn(COMMAND_HELP, cmd) && rest.some((a) => a === "--help" || a === "-h")) {
+  console.log(`\n${COMMAND_HELP[cmd]}\n`);
+  process.exit(0);
+}
+
 const { resolveInstallDir } = await import(join(__dirname, "_shared.mjs"));
 
 function installedVersion(installPath) {
@@ -168,6 +189,23 @@ function readOpenclawConfigSync() {
   }
 }
 
+/**
+ * The OpenClaw config for a command that cannot run without it (#106). On any
+ * read or parse failure, prints the one shared diagnostic — resolved path,
+ * what is wrong, next step — on stderr and exits 1. Read-only: never creates
+ * or repairs the file.
+ */
+async function requireOpenclawConfig(command) {
+  const { describeOpenclawConfigError, openclawConfigPath } = await import(join(__dirname, "_shared.mjs"));
+  const path = openclawConfigPath();
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    console.error(`${command}: ${describeOpenclawConfigError(err, path)}`);
+    process.exit(1);
+  }
+}
+
 /**
  * Everything the direct-route surfaces need, loaded from dist. None of these
  * modules import the `openclaw` peer, so they load from a global install.
@@ -247,11 +285,7 @@ async function loadDirect(config) {
 async function direct(args = []) {
   const { readFileSync: rf, mkdtempSync, writeFileSync, rmSync, statSync } = await import("node:fs");
   const { homedir, tmpdir } = await import("node:os");
-  const config = readOpenclawConfigSync();
-  if (!config) {
-    console.error("direct: could not read your OpenClaw config");
-    process.exit(1);
-  }
+  const config = await requireOpenclawConfig("direct");
   const ctx = await loadDirect(config);
   const sub = args.find((a) => !a.startsWith("--")) ?? "status";
   console.log(`\n${BOLD}🦞 multi-clawd — direct anthropic/* route${RESET}\n`);
@@ -376,13 +410,7 @@ async function chain(args = []) {
     process.exit(1);
   }
 
-  let config;
-  try {
-    config = JSON.parse(rf(join(homedir(), ".openclaw", "openclaw.json"), "utf8"));
-  } catch {
-    console.error("chain: could not read ~/.openclaw/openclaw.json");
-    process.exit(1);
-  }
+  const config = await requireOpenclawConfig("chain");
 
   const pc = config?.plugins?.entries?.["multi-clawd"]?.config ?? {};
   const poolId = pc.pool?.id?.trim() || (pc.pool ? "clawd" : undefined);
@@ -677,11 +705,12 @@ async function healWatchdogUnit() {
 /** `explain` — gather config + live health, render the plain-English view. */
 async function explain(args = []) {
   let historySince;
-  if (args.length) {
+  const asJson = args.length === 1 && args[0] === "--json";
+  if (args.length && !asJson) {
     const allowed = args[0] === "--history" && (args.length === 1 ||
       (args.length === 3 && args[1] === "--since"));
     if (!allowed) {
-      console.error("explain: usage: multi-clawd explain [--history [--since 7d|24h]]");
+      console.error("explain: usage: multi-clawd explain [--json | --history [--since 7d|24h]]");
       process.exitCode = 1;
       return;
     }
@@ -709,13 +738,7 @@ async function explain(args = []) {
     console.error(distFailure("explain", "explain-core.js", err));
     process.exit(1);
   }
-  let config = {};
-  try {
-    config = JSON.parse(rf(join(homedir(), ".openclaw", "openclaw.json"), "utf8"));
-  } catch {
-    console.error("explain: could not read ~/.openclaw/openclaw.json");
-    process.exit(1);
-  }
+  const config = await requireOpenclawConfig("explain");
   const pc = config?.plugins?.entries?.["multi-clawd"]?.config ?? {};
   const accounts = Array.isArray(pc.accounts) ? pc.accounts : [];
   const pool = pc.pool
@@ -775,6 +798,14 @@ async function explain(args = []) {
       /* no journal yet: every account counts as never served */
     }
   }
+  if (asJson) {
+    // #94: machine-readable health with the display-only weekly pace estimate.
+    console.log(JSON.stringify({
+      at: new Date(now).toISOString(),
+      accounts: healthRows.map((r) => ({ ...r, weeklyPace: ec.computeWeeklyPace(r.usage, now) ?? null })),
+    }, null, 2));
+    return;
+  }
   // v1.9: the direct anthropic/* route, when any account opted in.
   let direct;
   const dctx = await loadDirect(config);
@@ -814,11 +845,7 @@ async function usageCommand(args) {
     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 config = await requireOpenclawConfig("usage");
   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;
@@ -954,13 +981,7 @@ async function login() {
     console.error(distFailure("login", "login-plan.js", err));
     process.exit(1);
   }
-  let config = {};
-  try {
-    config = JSON.parse(rf(join(homedir(), ".openclaw", "openclaw.json"), "utf8"));
-  } catch {
-    console.error("login: could not read ~/.openclaw/openclaw.json — run `multi-clawd setup` first.");
-    process.exit(1);
-  }
+  const config = await requireOpenclawConfig("login");
   const accounts = config?.plugins?.entries?.["multi-clawd"]?.config?.accounts ?? [];
   if (accounts.length === 0) {
     console.error("login: no multi-clawd accounts configured — run `multi-clawd setup` first.");
@@ -1050,6 +1071,9 @@ switch (cmd) {
       process.exitCode = 1;
       break;
     }
+    // Same missing/unreadable/malformed diagnostic as every other config
+    // reader (#106), instead of the raw fs error changeAccount would throw.
+    await requireOpenclawConfig("account");
     try {
       const { changeAccount } = await import("./account-config.mjs");
       const result = changeAccount(id, action === "disable", flags.includes("--dry-run"));
@@ -1085,7 +1109,8 @@ switch (cmd) {
     break;
   case "version":
   case "--version":
-  case "-v": {
+  case "-v":
+  case "-V": {
     const cliVersion = JSON.parse(
       readFileSync(resolve(__dirname, "..", "package.json"), "utf8"),
     ).version;
@@ -1098,7 +1123,14 @@ switch (cmd) {
     if (skewNote) console.log(`\n⚠️  ${skewNote}`);
     break;
   }
-  default:
+  default: {
+    const wantsHelp = cmd === undefined || cmd === "help" || cmd === "--help" || cmd === "-h";
+    if (!wantsHelp) {
+      // Say what went wrong on stderr, then show the list and exit non-zero.
+      console.error(`multi-clawd: unknown command '${cmd}'`);
+      console.error("Run 'multi-clawd --help' for the list of commands.");
+    }
     usage();
-    process.exit(cmd === undefined || cmd === "help" || cmd === "--help" ? 0 : 1);
+    process.exit(wantsHelp ? 0 : 1);
+  }
 }

package/scripts/hermes.mjs

@@ -15,6 +15,7 @@ import {
 import { homedir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { describeOpenclawConfigError } from "./_shared.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const BRIDGE = join(HERE, "hermes_bridge.py");
@@ -56,6 +57,17 @@ function safePath(raw, label) {
 
 class ReadLimitedError extends Error {}
 
+/**
+ * A directory at the path. Carries EISDIR, the code `readFileSync` raises for
+ * it, so a caller's `describe` (the shared #106 diagnostic) names the cause
+ * and the next step instead of the generic size-cap line; without `describe`
+ * it still fails closed with that line. Other non-regular files keep the
+ * generic guard: nothing is read from them either way.
+ */
+class NotRegularFileError extends ReadLimitedError {
+  code = "EISDIR";
+}
+
 /**
  * `requirePrivate` rejects a POSIX file readable or writable by group/other
  * (mode & 0o077 != 0) — checked via fstat on the already-open fd, so nothing
@@ -63,11 +75,12 @@ class ReadLimitedError extends Error {}
  * bit layout, so the check is skipped there; the config JSON is read through
  * here too but never with this flag, since it holds no secret.
  */
-function readLimited(path, limit, label, { requirePrivate = false } = {}) {
+function readLimited(path, limit, label, { requirePrivate = false, describe } = {}) {
   let fd;
   try {
     fd = openSync(path, "r");
     const stat = fstatSync(fd);
+    if (stat.isDirectory()) throw new NotRegularFileError(`${label} is unavailable or too large`);
     if (!stat.isFile() || stat.size > limit) throw new ReadLimitedError(`${label} is unavailable or too large`);
     if (requirePrivate && process.platform !== "win32" && (stat.mode & 0o077) !== 0) {
       throw new ReadLimitedError(
@@ -78,7 +91,9 @@ function readLimited(path, limit, label, { requirePrivate = false } = {}) {
     if (data.byteLength > limit) throw new ReadLimitedError(`${label} is unavailable or too large`);
     return data.toString("utf8");
   } catch (error) {
+    if (error instanceof NotRegularFileError && describe) fail(describe(error));
     if (error instanceof ReadLimitedError) fail(error.message);
+    if (describe) fail(describe(error));
     fail(`${label} could not be read`);
   } finally {
     if (fd !== undefined) closeSync(fd);
@@ -254,12 +269,15 @@ function invokeBridge(hermes, home, request) {
 }
 
 function loadPluginConfig(configPath) {
-  const text = readLimited(configPath, MAX_CONFIG_BYTES, "OpenClaw config");
+  // Same resolved-path + next-step diagnostic as the cli.mjs commands (#106).
+  const text = readLimited(configPath, MAX_CONFIG_BYTES, "OpenClaw config", {
+    describe: (error) => describeOpenclawConfigError(error, configPath),
+  });
   let config;
   try {
     config = JSON.parse(text);
-  } catch {
-    fail("OpenClaw config is malformed JSON");
+  } catch (error) {
+    fail(describeOpenclawConfigError(error, configPath));
   }
   return config?.plugins?.entries?.["multi-clawd"]?.config;
 }