@drakon-systems/multi-clawd 2.6.0 → 2.6.2

package/README.md

@@ -416,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.6.0/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.6.2/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/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "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.6.0",
+  "version": "2.6.2",
   "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

@@ -189,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.
@@ -268,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`);
@@ -397,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);
@@ -731,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
@@ -844,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;
@@ -984,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.");
@@ -1080,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"));
@@ -1115,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;
@@ -1128,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/doctor.mjs

@@ -1055,17 +1055,35 @@ if (accounts.some((a) => a && a.direct !== undefined && a.direct !== false)) {
 // ── 9. watchdog ─────────────────────────────────────────────────────────────
 console.log("eviction watchdog");
 let watchdogFound = false;
+// A scheduler query that FAILS (no user session bus, no systemd, container)
+// says nothing about whether a watchdog exists. Only a query that succeeded
+// can confirm absence. Tool stderr is never inherited: it is raw noise.
+let watchdogQueried = false;
+const WATCHDOG_NAME = /multi-?clawd|eviction/;
 try {
-  const out = execFileSync("launchctl", ["list"], { encoding: "utf8" });
+  const out = execFileSync("launchctl", ["list"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  watchdogQueried = true;
   if (out.includes("multiclawd")) watchdogFound = true;
 } catch {
-  /* not macOS */
+  /* not macOS, or launchctl could not be queried */
 }
 try {
-  const out = execFileSync("systemctl", ["--user", "list-timers", "--all"], { encoding: "utf8" });
-  if (out.includes("multi-clawd") || out.includes("multiclawd") || out.includes("eviction")) watchdogFound = true;
+  const out = execFileSync("systemctl", ["--user", "list-timers", "--all"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  watchdogQueried = true;
+  if (WATCHDOG_NAME.test(out)) watchdogFound = true;
 } catch {
-  /* not systemd */
+  /* not systemd, or the user manager could not be queried */
+}
+if (!watchdogFound && !watchdogQueried) {
+  // Query unavailable: fall back to the unit files on disk, which need no
+  // running manager.
+  for (const d of [join(HOME, "Library", "LaunchAgents"), join(HOME, ".config", "systemd", "user")]) {
+    try {
+      if (readdirSync(d).some((f) => /\.(plist|service|timer)$/.test(f) && WATCHDOG_NAME.test(f))) watchdogFound = true;
+    } catch {
+      /* no such directory */
+    }
+  }
 }
 if (watchdogFound) {
   // "Scheduled" is not enough: the unit points at a script INSIDE an install
@@ -1108,7 +1126,11 @@ if (watchdogFound) {
       `watchdog unit ${orphan.file} points at a MISSING script (${orphan.target}) — it fails silently every tick. Repoint it at ${join(EXT_DIR, "scripts", "eviction-watchdog.mjs")} or run the setup wizard to repair.`,
     );
   } else ok("watchdog scheduled");
-} else warn("no watchdog found (needed until openclaw#107596 ships — see README)");
+} else if (watchdogQueried) {
+  warn("no watchdog found (needed until openclaw#107596 ships — see README)");
+} else {
+  note("could not query the scheduler (no user session or no systemd/launchd) and found no watchdog unit file — watchdog state unknown. Run doctor from a normal login session to confirm.");
+}
 
 // ── 10. optional live probe ─────────────────────────────────────────────────
 if (args.has("--probe")) {

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