@drakon-systems/multi-clawd 1.0.1 → 1.2.0

package/README.md

@@ -10,7 +10,8 @@ Pool every Claude Max account you own into a single failover chain —
 same model, next account, full harness on every hop.
 
 [![OpenClaw plugin](https://img.shields.io/badge/OpenClaw-plugin-ff4f00)](https://docs.openclaw.ai/plugins)
-[![version](https://img.shields.io/badge/version-0.3.7-4c9aff)](package.json)
+[![npm](https://img.shields.io/badge/npm-%40drakon--systems%2Fmulti--clawd-cb3837)](https://www.npmjs.com/package/@drakon-systems/multi-clawd)
+[![version](https://img.shields.io/badge/version-1.0.1-4c9aff)](CHANGELOG.md)
 [![license: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
 
@@ -112,7 +113,7 @@ Code backend runs.
 
 ## Install
 
-**From npm (recommended, v1.0+):**
+**From npm (recommended):**
 
 ```bash
 openclaw plugins install @drakon-systems/multi-clawd --pin
@@ -123,8 +124,9 @@ The gateway pulls the prebuilt package — no clone, no build step, nothing to
 keep in sync. `--pin` records the exact resolved version, so an upgrade is a
 deliberate `@latest`, never a surprise. `openclaw` itself is a *peer*
 dependency (the host provides it), so the install stays lean. Confirm with
-`openclaw plugins list` (expect `multi-clawd` enabled), then run the doctor:
-`node ~/.openclaw/extensions/multi-clawd/scripts/doctor.mjs`.
+`openclaw plugins list` (expect `multi-clawd` enabled) — it also shows the
+install path; run the doctor from there:
+`node <install-path>/scripts/doctor.mjs`.
 
 **From ClawHub (alternative registry):**
 
@@ -163,10 +165,15 @@ second Claude subscription you own.
 **Upgrading:**
 
 ```bash
-# Registry install (npm / ClawHub):
-openclaw plugins install @drakon-systems/multi-clawd@latest --force
-openclaw gateway restart
+npx @drakon-systems/multi-clawd update
+```
 
+One command: checks the registry, installs the new version with the right
+flags, offers the gateway restart, and finishes with a doctor health check.
+(`npm i -g @drakon-systems/multi-clawd` once, and it's just `multi-clawd
+update` — with `multi-clawd setup` and `multi-clawd doctor` alongside.)
+
+```bash
 # From source:
 cd multi-clawd && git pull && npm install && npm run build && npm run doctor
 ```

package/dist/update-core.js

@@ -0,0 +1,30 @@
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+export function decideUpdateAction(opts) {
+    if (opts.installed === undefined)
+        return "install";
+    if (opts.latest === undefined)
+        return "unknown";
+    return compareVersions(opts.installed, opts.latest) < 0 ? "update" : "up-to-date";
+}
+export function formatUpdateBanner(opts) {
+    const action = decideUpdateAction(opts);
+    switch (action) {
+        case "install":
+            return `not installed — latest is v${opts.latest}`;
+        case "update":
+            return `update available: v${opts.installed} → v${opts.latest}`;
+        case "up-to-date":
+            return `up to date (v${opts.installed})`;
+        case "unknown":
+            return `installed v${opts.installed} — could not reach the registry to check for updates`;
+    }
+}

package/dist/watchdog-schedule.js

@@ -0,0 +1,66 @@
+export const WATCHDOG_LAUNCHD_LABEL = "com.multi-clawd.eviction-watchdog";
+export const WATCHDOG_SYSTEMD_NAME = "multi-clawd-eviction-watchdog";
+export function renderWatchdogUnit(opts) {
+    if (opts.platform === "darwin") {
+        return [
+            {
+                path: `Library/LaunchAgents/${WATCHDOG_LAUNCHD_LABEL}.plist`,
+                content: `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${WATCHDOG_LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${opts.nodePath}</string>
+    <string>${opts.scriptPath}</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>300</integer>
+  <key>RunAtLoad</key>
+  <true/>
+</dict>
+</plist>
+`,
+            },
+        ];
+    }
+    if (opts.platform === "linux") {
+        return [
+            {
+                path: `.config/systemd/user/${WATCHDOG_SYSTEMD_NAME}.service`,
+                content: `[Unit]
+Description=multi-clawd eviction watchdog (turn-safe; openclaw#107408 mitigation)
+
+[Service]
+Type=oneshot
+ExecStart=${opts.nodePath} ${opts.scriptPath}
+`,
+            },
+            {
+                path: `.config/systemd/user/${WATCHDOG_SYSTEMD_NAME}.timer`,
+                content: `[Unit]
+Description=Run the multi-clawd eviction watchdog every 5 minutes
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=5min
+
+[Install]
+WantedBy=timers.target
+`,
+            },
+        ];
+    }
+    return [];
+}
+export function extractWatchdogTarget(unitText) {
+    const m = unitText.match(/[^<>\s="']*eviction-watchdog\.mjs/);
+    return m ? m[0] : undefined;
+}
+export function classifyWatchdogUnit(targetPath, exists) {
+    if (targetPath === undefined)
+        return "absent";
+    return exists(targetPath) ? "ok" : "orphaned";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.0.1",
+  "version": "1.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.",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,9 @@
     }
   },
   "main": "./dist/index.js",
+  "bin": {
+    "multi-clawd": "./scripts/cli.mjs"
+  },
   "publishConfig": {
     "access": "public"
   },

package/scripts/cli.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * multi-clawd CLI — the friendly front door.
+ *
+ *   npx @drakon-systems/multi-clawd setup     guided setup wizard
+ *   npx @drakon-systems/multi-clawd update    update to the latest version
+ *   npx @drakon-systems/multi-clawd doctor    health check
+ *   npx @drakon-systems/multi-clawd version   versions (CLI + installed plugin)
+ *
+ * (Installed globally via `npm i -g @drakon-systems/multi-clawd`, the same
+ * commands are just `multi-clawd setup` / `multi-clawd update` / …)
+ *
+ * `update` wraps the whole upgrade dance — registry version check, the
+ * openclaw install with the right flags, gateway restart, doctor — so nobody
+ * has to remember `--pin --force`.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline/promises";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG = "@drakon-systems/multi-clawd";
+const HOME = homedir();
+const BOLD = process.stdout.isTTY ? "\x1b[1m" : "";
+const DIM = process.stdout.isTTY ? "\x1b[2m" : "";
+const RESET = process.stdout.isTTY ? "\x1b[0m" : "";
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+function usage() {
+  console.log(`
+${BOLD}🦞 multi-clawd${RESET} — multi-account Claude failover for OpenClaw
+
+  ${BOLD}setup${RESET}     guided setup wizard (accounts, pool, watchdog)
+  ${BOLD}update${RESET}    update the plugin to the latest version
+  ${BOLD}doctor${RESET}    health check (add --probe for a live turn)
+  ${BOLD}version${RESET}   show CLI + installed plugin versions
+
+Run via npx (${DIM}npx ${PKG} <command>${RESET}) or install globally
+(${DIM}npm i -g ${PKG}${RESET}) for a bare ${DIM}multi-clawd <command>${RESET}.
+`);
+}
+
+/** Same resolution as the doctor: path install wins, else newest npm-project install. */
+function resolveInstallDir() {
+  const extDir = join(HOME, ".openclaw", "extensions", "multi-clawd");
+  if (existsSync(join(extDir, "openclaw.plugin.json"))) return extDir;
+  const projects = join(HOME, ".openclaw", "npm", "projects");
+  let best;
+  let bestM = -1;
+  try {
+    for (const p of readdirSync(projects)) {
+      if (!p.startsWith("drakon-systems-multi-clawd-")) continue;
+      const dir = join(projects, p, "node_modules", "@drakon-systems", "multi-clawd");
+      const manifest = join(dir, "openclaw.plugin.json");
+      if (!existsSync(manifest)) continue;
+      const m = statSync(manifest).mtimeMs;
+      if (m > bestM) {
+        bestM = m;
+        best = dir;
+      }
+    }
+  } catch {
+    /* no npm projects dir */
+  }
+  return best;
+}
+
+function installedVersion() {
+  const dir = resolveInstallDir();
+  if (!dir) return undefined;
+  try {
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+  } catch {
+    return undefined;
+  }
+}
+
+function latestVersion() {
+  try {
+    return execFileSync("npm", ["view", PKG, "version"], { encoding: "utf8", timeout: 15000 })
+      .trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function haveOpenclaw() {
+  try {
+    execFileSync("openclaw", ["--version"], { stdio: "pipe", timeout: 15000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runSibling(script, args) {
+  const r = spawnSync(process.execPath, [join(__dirname, script), ...args], { stdio: "inherit" });
+  process.exit(r.status ?? 1);
+}
+
+async function askYes(question, dflt = true) {
+  if (!process.stdin.isTTY) return dflt;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const a = (await rl.question(`${question} ${dflt ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+  rl.close();
+  if (!a) return dflt;
+  return a.startsWith("y");
+}
+
+async function update() {
+  let uc;
+  try {
+    uc = await import(resolve(__dirname, "..", "dist", "update-core.js"));
+  } catch {
+    console.error("update: built dist/ is missing — reinstall the package.");
+    process.exit(1);
+  }
+  console.log(`\n${BOLD}🦞 multi-clawd update${RESET}\n`);
+  if (!haveOpenclaw()) {
+    console.error("  ❌ the `openclaw` CLI is not on PATH — install OpenClaw first.");
+    process.exit(1);
+  }
+  const installed = installedVersion();
+  process.stdout.write(`  checking registry… `);
+  const latest = latestVersion();
+  console.log(latest ? `latest is v${latest}` : "unreachable");
+  const banner = uc.formatUpdateBanner({ installed, latest });
+  const action = uc.decideUpdateAction({ installed, latest });
+  console.log(`  ${action === "up-to-date" ? "✅" : action === "unknown" ? "⚠️ " : "⬆️ "} ${banner}\n`);
+  if (action === "up-to-date") return;
+  if (action === "unknown") {
+    console.log("  Check your network and try again.");
+    process.exit(1);
+  }
+  if (!(await askYes(`  ${action === "install" ? "Install" : "Update"} now?`))) return;
+
+  console.log(`\n  ${DIM}openclaw plugins install ${PKG} --pin --force${RESET}`);
+  const inst = spawnSync("openclaw", ["plugins", "install", PKG, "--pin", "--force"], {
+    stdio: "inherit",
+  });
+  if (inst.status !== 0) {
+    console.error("\n  ❌ install failed — see output above.");
+    process.exit(1);
+  }
+  if (await askYes("\n  Restart the gateway to load it? (briefly interrupts running turns)")) {
+    const r = spawnSync("openclaw", ["gateway", "restart"], { stdio: "inherit" });
+    if (r.status !== 0) console.log("  ⚠ restart failed — run `openclaw gateway restart` yourself.");
+  } else {
+    console.log("  ⏳ remember: the new version loads on the next gateway restart.");
+  }
+  console.log(`\n${BOLD}  health check${RESET}`);
+  const doc = spawnSync(process.execPath, [join(__dirname, "doctor.mjs")], { stdio: "inherit" });
+  if (doc.status !== 0) {
+    console.log(`\n  ⚠ doctor found problems — if it flagged the watchdog, run ${BOLD}multi-clawd setup${RESET} to repair it.`);
+    process.exit(doc.status ?? 1);
+  }
+  console.log(`\n  ✅ done — now on v${installedVersion() ?? "?"}`);
+}
+
+switch (cmd) {
+  case "setup":
+    runSibling("setup.mjs", rest);
+    break;
+  case "doctor":
+    runSibling("doctor.mjs", rest);
+    break;
+  case "update":
+    await update();
+    break;
+  case "version":
+  case "--version":
+  case "-v": {
+    const cliVersion = JSON.parse(
+      readFileSync(resolve(__dirname, "..", "package.json"), "utf8"),
+    ).version;
+    console.log(`cli: v${cliVersion}`);
+    console.log(`installed plugin: ${installedVersion() ? `v${installedVersion()}` : "(not installed)"}`);
+    break;
+  }
+  default:
+    usage();
+    process.exit(cmd === undefined || cmd === "help" || cmd === "--help" ? 0 : 1);
+}

package/scripts/doctor.mjs

@@ -344,8 +344,43 @@ try {
 } catch {
   /* not systemd */
 }
-if (watchdogFound) ok("watchdog scheduled");
-else warn("no watchdog found (needed until openclaw#107596 ships — see README)");
+if (watchdogFound) {
+  // "Scheduled" is not enough: the unit points at a script INSIDE an install
+  // dir, and installs move (path→registry migration, uninstall/reinstall).
+  // An orphaned unit fires every tick against a missing file — silently.
+  // Deliberately self-contained (no dist import): the check must work even
+  // when the install itself is the thing that went missing.
+  let orphan;
+  for (const d of [
+    join(HOME, "Library", "LaunchAgents"),
+    join(HOME, ".config", "systemd", "user"),
+  ]) {
+    let files = [];
+    try {
+      files = readdirSync(d);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      // Only real unit files — launchd loads *.plist, systemd *.service/*.timer;
+      // backups like *.plist.bak-... are inert and must not be flagged.
+      if (!/\.(plist|service|timer)$/.test(f)) continue;
+      let text;
+      try {
+        text = readFileSync(join(d, f), "utf8");
+      } catch {
+        continue;
+      }
+      const target = text.match(/[^<>\s="']*eviction-watchdog\.mjs/)?.[0];
+      if (target && !existsSync(target)) orphan = { file: join(d, f), target };
+    }
+  }
+  if (orphan) {
+    bad(
+      `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)");
 
 // ── 9. optional live probe ──────────────────────────────────────────────────
 if (args.has("--probe")) {

package/scripts/setup.mjs

@@ -22,7 +22,7 @@
  * The wizard never sees or stores a token value. All scaffolding logic is
  * pure and unit-tested in src/setup-core.ts; this file owns prompts and IO.
  */
-import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -33,11 +33,12 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const DRY_RUN = process.argv.includes("--dry-run");
 const CONFIG_PATH = join(homedir(), ".openclaw", "openclaw.json");
 
-let core;
+let core, wds;
 try {
   core = await import(resolve(__dirname, "..", "dist", "setup-core.js"));
+  wds = await import(resolve(__dirname, "..", "dist", "watchdog-schedule.js"));
 } catch {
-  console.error("setup: dist/setup-core.js is missing — run `npm run build` first (source checkout) or reinstall the plugin.");
+  console.error("setup: built dist/ modules are missing — run `npm run build` first (source checkout) or reinstall the plugin.");
   process.exit(1);
 }
 const { buildMainAccount, buildSecondAccount, buildPool, validateSecondConfigDir, planFromExisting, mergeSetupIntoConfig } = core;
@@ -195,25 +196,145 @@ console.log("\nPlanned changes:");
 if (changes.length === 0) console.log("  (none — config already matches)");
 for (const c of changes) console.log(`  • ${c}`);
 
-if (DRY_RUN || changes.length === 0) {
-  console.log(DRY_RUN ? "\ndry-run: nothing written." : "");
-  rl.close();
-  process.exit(0);
+let wroteConfig = false;
+if (DRY_RUN) {
+  if (changes.length > 0) console.log("\ndry-run: config not written.");
+} else if (changes.length > 0) {
+  if (!(await yes(`\nWrite these to ${CONFIG_PATH}? (backup taken first)`))) {
+    console.log("Aborted — nothing written.");
+    rl.close();
+    process.exit(0);
+  }
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  if (existsSync(CONFIG_PATH)) {
+    const backup = `${CONFIG_PATH}.bak-setup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    copyFileSync(CONFIG_PATH, backup);
+    console.log(`backup: ${backup}`);
+  }
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+  console.log(`wrote ${CONFIG_PATH}`);
+  wroteConfig = true;
+}
+
+// ── eviction watchdog: create, or repair an orphaned unit ────────────────────
+// The unit points at a script INSIDE an install dir, and installs move
+// (path→registry migration, uninstall/reinstall) — an orphaned unit fires
+// every 5 min against a missing file, silently. The wizard owns this now.
+await watchdogStep();
+
+async function watchdogStep() {
+  const platform = process.platform;
+  console.log("\nEviction watchdog (openclaw#107408 mitigation — see README):");
+  if (platform !== "darwin" && platform !== "linux") {
+    console.log("  (auto-scheduling not supported on this platform — see README for manual setup)");
+    return;
+  }
+  const scriptPath = join(__dirname, "eviction-watchdog.mjs");
+  const scanDir =
+    platform === "darwin"
+      ? join(homedir(), "Library", "LaunchAgents")
+      : join(homedir(), ".config", "systemd", "user");
+  let found;
+  try {
+    for (const f of readdirSync(scanDir)) {
+      // Only real unit files — backups like *.plist.bak-... are inert; never
+      // detect (or "repair") one of those instead of the live unit.
+      if (!/\.(plist|service|timer)$/.test(f)) continue;
+      const p = join(scanDir, f);
+      let text;
+      try {
+        text = readFileSync(p, "utf8");
+      } catch {
+        continue;
+      }
+      const target = wds.extractWatchdogTarget(text);
+      if (target) {
+        found = { file: p, target, text };
+        break;
+      }
+    }
+  } catch {
+    /* scan dir missing — treated as absent */
+  }
+  const state = wds.classifyWatchdogUnit(found?.target, existsSync);
+  if (state === "ok") {
+    console.log(`  ✅ already scheduled and healthy → ${found.target}`);
+    return;
+  }
+  if (state === "orphaned") {
+    console.log(
+      `  ⚠ ${found.file}\n    points at a MISSING script: ${found.target}\n    (an old install dir — the watchdog has been failing silently)`,
+    );
+    if (DRY_RUN) {
+      console.log(`  dry-run: would repoint it at ${scriptPath}`);
+      return;
+    }
+    if (!(await yes("  Repoint it at this install?"))) return;
+    writeFileSync(found.file, found.text.split(found.target).join(scriptPath));
+    reloadWatchdogUnit(platform, found.file);
+    console.log(`  ✅ repointed → ${scriptPath}`);
+    return;
+  }
+  if (DRY_RUN) {
+    console.log(`  dry-run: not scheduled — would offer to schedule it → ${scriptPath}`);
+    return;
+  }
+  if (!(await yes("  Not scheduled. Schedule it now (runs every 5 min)?"))) return;
+  const unitFiles = wds.renderWatchdogUnit({ platform, nodePath: process.execPath, scriptPath });
+  for (const uf of unitFiles) {
+    const abs = join(homedir(), uf.path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, uf.content);
+    console.log(`  wrote ${abs}`);
+  }
+  if (platform === "darwin") {
+    reloadWatchdogUnit(platform, join(homedir(), unitFiles[0].path));
+  } else {
+    try {
+      execFileSync("systemctl", ["--user", "daemon-reload"]);
+      execFileSync("systemctl", ["--user", "enable", "--now", `${wds.WATCHDOG_SYSTEMD_NAME}.timer`]);
+      console.log("  ✅ timer enabled");
+    } catch {
+      console.log(
+        `  ⚠ units written but enabling failed — run: systemctl --user enable --now ${wds.WATCHDOG_SYSTEMD_NAME}.timer`,
+      );
+    }
+  }
 }
 
-if (!(await yes(`\nWrite these to ${CONFIG_PATH}? (backup taken first)`))) {
-  console.log("Aborted — nothing written.");
+function reloadWatchdogUnit(platform, file) {
+  if (platform === "darwin") {
+    try {
+      execFileSync("launchctl", ["unload", file], { stdio: "ignore" });
+    } catch {
+      /* was not loaded */
+    }
+    try {
+      // launchctl can print "Load failed" to stderr and still exit 0 — merge
+      // the streams and check the text, not just the exit code.
+      const out = execFileSync("/bin/sh", ["-c", `launchctl load "${file}" 2>&1 || true`], {
+        encoding: "utf8",
+      });
+      if (/load failed|bootstrap failed/i.test(out)) throw new Error(out.trim());
+      console.log("  ✅ launchd agent (re)loaded");
+    } catch {
+      console.log(`  ⚠ plist written but load failed — run: launchctl load ${file}`);
+    }
+  } else {
+    try {
+      execFileSync("systemctl", ["--user", "daemon-reload"]);
+      console.log("  ✅ systemd reloaded");
+    } catch {
+      console.log("  ⚠ run: systemctl --user daemon-reload");
+    }
+  }
+}
+
+if (DRY_RUN || !wroteConfig) {
+  console.log(DRY_RUN ? "\ndry-run: nothing written." : "");
   rl.close();
   process.exit(0);
 }
-mkdirSync(dirname(CONFIG_PATH), { recursive: true });
-if (existsSync(CONFIG_PATH)) {
-  const backup = `${CONFIG_PATH}.bak-setup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-  copyFileSync(CONFIG_PATH, backup);
-  console.log(`backup: ${backup}`);
-}
-writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
-console.log(`wrote ${CONFIG_PATH}`);
 
 // ── next steps ───────────────────────────────────────────────────────────────
 console.log(`