@drakon-systems/multi-clawd 1.5.4 → 1.7.0

package/README.md

@@ -30,6 +30,7 @@ multi-clawd update    # install (or update) the OpenClaw plugin — right flags,
 multi-clawd setup     # guided wizard: accounts, isolated second login, pool, watchdog
 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 chain     # audit your model routing — what actually serves each turn
 multi-clawd doctor    # health check (add --probe for a live end-to-end turn)
 ```
 
@@ -188,7 +189,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/v1.5.4/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.7.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.
 

package/dist/chain-audit.js

@@ -164,6 +164,69 @@ export function auditEffectiveChain(config, poolId) {
     }
     return findings;
 }
+function primaryOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object") {
+        const p = value.primary;
+        if (typeof p === "string")
+            return p;
+    }
+    return undefined;
+}
+function collectAgentModelBlocks(config) {
+    const cfg = (config ?? {});
+    const agents = (cfg.agents ?? {});
+    const out = [];
+    for (const [name, v] of Object.entries(agents)) {
+        if (RESERVED_AGENT_KEYS.has(name))
+            continue;
+        if (!v || typeof v !== "object")
+            continue;
+        const agent = v;
+        if ("model" in agent)
+            out.push({ agent: name, surface: `agents.${name}.model`, model: agent.model });
+    }
+    if (Array.isArray(agents.list)) {
+        agents.list.forEach((a, i) => {
+            if (!a || typeof a !== "object")
+                return;
+            const agent = a;
+            if (!("model" in agent))
+                return;
+            const label = typeof agent.id === "string" ? agent.id : String(i);
+            out.push({ agent: label, surface: `agents.list[${label}].model`, model: agent.model });
+        });
+    }
+    return out;
+}
+export function auditChainShadowing(config) {
+    const cfg = (config ?? {});
+    const agents = (cfg.agents ?? {});
+    const defaults = (agents.defaults ?? {});
+    const defaultPrimary = primaryOf(defaults.model);
+    const findings = [];
+    for (const { agent, surface, model } of collectAgentModelBlocks(config)) {
+        const agentPrimary = primaryOf(model);
+        const diverges = agentPrimary !== undefined && agentPrimary !== defaultPrimary;
+        findings.push({
+            surface,
+            ref: agentPrimary ?? "(no primary)",
+            severity: diverges ? "warn" : "note",
+            agent,
+            defaultPrimary,
+            agentPrimary,
+            reason: diverges
+                ? `agent "${agent}" has its OWN chain, so it serves ${agentPrimary} — NOT the ` +
+                    `${defaultPrimary ?? "(unset)"} in agents.defaults.model. Editing the defaults will not ` +
+                    `change this agent. Fix: update this block too, or delete it to inherit the defaults`
+                : `agent "${agent}" repeats the default chain — harmless, but it will silently ` +
+                    `stop tracking agents.defaults.model the next time you change it. Fix: delete this ` +
+                    `block to inherit the defaults`,
+        });
+    }
+    return findings;
+}
 const POOL_PROVIDER = "clawd";
 export function auditSessionOverrides(sessions, poolConfigured) {
     if (!poolConfigured)

package/dist/index.js

@@ -15,6 +15,7 @@ import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js
 import { resolveSecretRefValues } from "openclaw/plugin-sdk/secret-ref-runtime";
 import { addAlert, clearAlert, pendingAlertText } from "./alerts.js";
 import { buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
+import { diffCatalogModels, formatNewModelNotice, } from "./model-currency.js";
 import { checkAccountCredential, createRefProbeTracker, } from "./login-health.js";
 import { execFileSync } from "node:child_process";
 const BASE_ARGS = [
@@ -231,6 +232,54 @@ const SHIM_PATH = fileURLToPath(new URL("./shim.js", import.meta.url));
 export function healthStateFile(accountId) {
     return join(homedir(), ".openclaw", "state", "multi-clawd", `${accountId}.json`);
 }
+function knownModelsFile() {
+    return join(homedir(), ".openclaw", "state", "multi-clawd", "known-models.json");
+}
+function readChainRefs() {
+    try {
+        const cfg = JSON.parse(readFileSync(join(homedir(), ".openclaw", "openclaw.json"), "utf8"));
+        const m = cfg?.agents?.defaults?.model;
+        const refs = [];
+        if (typeof m?.primary === "string")
+            refs.push(m.primary);
+        if (Array.isArray(m?.fallbacks)) {
+            for (const f of m.fallbacks)
+                if (typeof f === "string")
+                    refs.push(f);
+        }
+        return refs;
+    }
+    catch {
+        return [];
+    }
+}
+function checkModelCurrency(catalogIds, chainRefs, poolId) {
+    try {
+        const file = knownModelsFile();
+        let stored;
+        try {
+            stored = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+        }
+        const result = diffCatalogModels(stored, catalogIds, chainRefs, Date.now());
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp`;
+        writeFileSync(tmp, JSON.stringify(result.nextState, null, 2), { mode: 0o600 });
+        renameSync(tmp, file);
+        const notice = formatNewModelNotice(result.unusedNewIds, poolId);
+        if (notice) {
+            raiseAlert({
+                key: `new-models:${result.unusedNewIds.join(",")}`,
+                severity: "info",
+                text: notice,
+                ttlMs: 24 * 60 * 60 * 1000,
+            });
+        }
+    }
+    catch {
+    }
+}
 export function buildBackend(account, execMode) {
     return {
         id: account.id,
@@ -520,4 +569,11 @@ function registerPoolBackend(api, pool, accounts, registeredIds, execMode) {
     api.registerProvider(buildCatalogProvider(poolAccount));
     registeredIds.add(poolId);
     logger.info(`[multi-clawd] pool "${poolId}" active — accounts: ${memberIds.join(" → ")}, threshold: ${options.utilizationThreshold ?? 0.85}`);
+    void (async () => {
+        try {
+            checkModelCurrency(await resolveBaseModelIds(), readChainRefs(), poolId);
+        }
+        catch {
+        }
+    })();
 }

package/dist/model-currency.js

@@ -0,0 +1,26 @@
+import { isModernClaudeModelId } from "./models.js";
+function modelIdOf(ref) {
+    const i = ref.indexOf("/");
+    return i < 0 ? ref : ref.slice(i + 1);
+}
+export function diffCatalogModels(stored, catalogIds, chainRefs, nowMs) {
+    const claudeIds = [...new Set(catalogIds.filter(isModernClaudeModelId))].sort();
+    const nextState = { ids: claudeIds, updatedAt: nowMs };
+    const firstRun = !stored || !Array.isArray(stored.ids) || stored.ids.length === 0;
+    if (firstRun)
+        return { newIds: [], unusedNewIds: [], nextState, firstRun: true };
+    const seen = new Set(stored.ids);
+    const newIds = claudeIds.filter((id) => !seen.has(id));
+    const referenced = new Set(chainRefs.map(modelIdOf));
+    const unusedNewIds = newIds.filter((id) => !referenced.has(id));
+    return { newIds, unusedNewIds, nextState, firstRun: false };
+}
+export function formatNewModelNotice(unusedNewIds, poolId) {
+    if (unusedNewIds.length === 0)
+        return undefined;
+    const list = unusedNewIds.map((id) => `${poolId}/${id}`).join(", ");
+    const subject = unusedNewIds.length === 1 ? "A new Claude model is" : "New Claude models are";
+    return (`${subject} available on your accounts but not referenced in your chain: ${list}. ` +
+        `Whether it belongs as your primary, a fallback, or nowhere is your call — ` +
+        `run \`multi-clawd chain\` to see your current routing.`);
+}

package/dist/update-core.js

@@ -15,6 +15,48 @@ export function decideUpdateAction(opts) {
         return "unknown";
     return compareVersions(opts.installed, opts.latest) < 0 ? "update" : "up-to-date";
 }
+export function classifyCliSkew(opts) {
+    if (opts.pluginVersion === undefined)
+        return "plugin-missing";
+    const d = compareVersions(opts.cliVersion, opts.pluginVersion);
+    if (d === 0)
+        return "aligned";
+    return d < 0 ? "cli-behind" : "cli-ahead";
+}
+export function detectCliInstallKind(cliDir) {
+    if (/[/\\]_npx[/\\]/.test(cliDir))
+        return "npx";
+    if (/[/\\]node_modules[/\\]/.test(cliDir))
+        return "global";
+    return "source";
+}
+export function cliUpdateCommand(kind, pkg) {
+    switch (kind) {
+        case "global":
+            return `npm i -g ${pkg}@latest`;
+        case "npx":
+            return `npx ${pkg}@latest <command>`;
+        case "source":
+            return "git pull && npm run build";
+    }
+}
+export function formatCliSkew(opts) {
+    const skew = classifyCliSkew(opts);
+    const fix = cliUpdateCommand(opts.installKind, opts.pkg);
+    switch (skew) {
+        case "aligned":
+            return undefined;
+        case "plugin-missing":
+            return undefined;
+        case "cli-behind":
+            return (`CLI v${opts.cliVersion} is older than the installed plugin v${opts.pluginVersion} — ` +
+                `\`doctor\`/\`setup\` run from the CLI, so this one reports on the plugin using ` +
+                `older logic. Fix: ${fix}`);
+        case "cli-ahead":
+            return (`CLI v${opts.cliVersion} is newer than the installed plugin v${opts.pluginVersion} — ` +
+                `the plugin serving your turns is behind. Fix: multi-clawd update`);
+    }
+}
 export function formatUpdateBanner(opts) {
     const action = decideUpdateAction(opts);
     switch (action) {

package/openclaw.plugin.json

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

package/package.json

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

package/scripts/cli.mjs

@@ -35,6 +35,7 @@ ${BOLD}🦞 multi-clawd${RESET} — multi-account Claude failover for OpenClaw
   ${BOLD}setup${RESET}     guided setup wizard (accounts, pool, watchdog)
   ${BOLD}login${RESET}     log a configured account in (or re-auth it) — right dir, right env
   ${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}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
@@ -88,6 +89,138 @@ async function askYes(question, dflt = true) {
   return a.startsWith("y");
 }
 
+/** This package's own version (the CLI half). */
+function cliVersion() {
+  return JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf8")).version;
+}
+
+/**
+ * Skew advice for the current install, or undefined when the two halves agree.
+ * Loads the pure classifier from dist; stays silent if dist is unavailable so
+ * a missing build can never turn an informational note into a hard failure.
+ */
+async function cliSkewNote(cli = cliVersion(), plugin = installedVersion()) {
+  try {
+    const uc = await import(resolve(__dirname, "..", "dist", "update-core.js"));
+    return uc.formatCliSkew({
+      cliVersion: cli,
+      pluginVersion: plugin,
+      installKind: uc.detectCliInstallKind(resolve(__dirname, "..")),
+      pkg: PKG,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `chain` — one place that answers "what actually serves my turns, and does it
+ * match what I meant?".
+ *
+ * Every routing fault this project has hit was config that no longer matched
+ * intent: a per-agent chain shadowing the defaults, sessions pinned off-pool,
+ * allowlist rungs naming retired providers. Each was individually invisible and
+ * each defeated cross-account failover — the entire point of the product. The
+ * audits already existed for doctor; this gives them a home where the fix is
+ * printed next to the finding.
+ */
+async function chain(args = []) {
+  const { readFileSync: rf, existsSync, readdirSync } = await import("node:fs");
+  const { homedir } = await import("node:os");
+  const raw = args.includes("--raw");
+
+  let ca;
+  try {
+    ca = await import(resolve(__dirname, "..", "dist", "chain-audit.js"));
+  } catch {
+    console.error("chain: built dist/ is missing — reinstall the package.");
+    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 pc = config?.plugins?.entries?.["multi-clawd"]?.config ?? {};
+  const poolId = pc.pool?.id?.trim() || (pc.pool ? "clawd" : undefined);
+  const chainCfg = config?.agents?.defaults?.model;
+
+  console.log(`\n${BOLD}🦞 multi-clawd — model routing${RESET}\n`);
+
+  console.log(`${BOLD}DEFAULT CHAIN${RESET}  ${DIM}(agents.defaults.model)${RESET}`);
+  const rungs = [chainCfg?.primary, ...(chainCfg?.fallbacks ?? [])].filter(
+    (r) => typeof r === "string",
+  );
+  if (rungs.length === 0) console.log("  (none configured)");
+  rungs.forEach((r, i) => {
+    const pooled = poolId && r.startsWith(`${poolId}/`);
+    console.log(`  ${i + 1}. ${r}${pooled ? `  ${DIM}→ pooled${RESET}` : ""}`);
+  });
+  console.log("");
+
+  let problems = 0;
+  const section = (title, findings, renderRef) => {
+    if (findings.length === 0) return;
+    console.log(`${BOLD}${title}${RESET}`);
+    for (const f of findings) {
+      const icon = f.severity === "warn" ? "⚠️ " : "ℹ️ ";
+      if (f.severity === "warn") problems++;
+      console.log(`  ${icon} ${renderRef(f)}`);
+      console.log(`      ${DIM}${f.reason}${RESET}`);
+    }
+    console.log("");
+  };
+
+  section("AGENTS WITH THEIR OWN CHAIN", ca.auditChainShadowing(config), (f) =>
+    `${f.surface} → ${f.ref}`,
+  );
+
+  const configFindings = ca.auditEffectiveChain(config, poolId);
+  section(
+    "OFF-POOL REFERENCES",
+    configFindings.filter((f) => f.severity === "warn"),
+    (f) => `${f.surface}: ${f.ref}`,
+  );
+  const notes = configFindings.filter((f) => f.severity === "note");
+  if (notes.length > 0) {
+    console.log(
+      `${DIM}  (${notes.length} allowlist entr${notes.length === 1 ? "y" : "ies"} name a non-pool Claude ref — registered, not a live tier)${RESET}\n`,
+    );
+  }
+
+  // Session pins, across every agent's session store.
+  const sessionFindings = [];
+  const agentsDir = join(homedir(), ".openclaw", "agents");
+  try {
+    for (const agent of readdirSync(agentsDir)) {
+      const p = join(agentsDir, agent, "sessions", "sessions.json");
+      if (!existsSync(p)) continue;
+      try {
+        sessionFindings.push(...ca.auditSessionOverrides(JSON.parse(rf(p, "utf8")), Boolean(poolId)));
+      } catch {
+        /* unreadable store — skip, doctor reports install health */
+      }
+    }
+  } catch {
+    /* no agents dir */
+  }
+  section("SESSION PINS", sessionFindings, (f) =>
+    raw ? f.surface : f.surface.replace(/^session (.*)$/, (_, k) => `session ${ca.maskSessionKey(k)}`),
+  );
+
+  if (problems === 0) {
+    console.log(`✅ routing is consistent — every live Claude tier goes through the pool.\n`);
+  } else {
+    console.log(
+      `${problems} thing${problems === 1 ? "" : "s"} to look at. ${DIM}Session ids are masked; --raw shows them in full.${RESET}\n`,
+    );
+  }
+}
+
 async function update() {
   let uc;
   try {
@@ -130,6 +263,7 @@ async function update() {
     console.log("  ⏳ remember: the new version loads on the next gateway restart.");
   }
   await healWatchdogUnit();
+  await offerCliSelfUpdate(uc);
   console.log(`\n${BOLD}  health check${RESET}`);
   const doc = spawnSync(process.execPath, [join(__dirname, "doctor.mjs")], { stdio: "inherit" });
   if (doc.status !== 0) {
@@ -139,6 +273,46 @@ async function update() {
   console.log(`\n  ✅ done — now on v${installedVersion() ?? "?"}`);
 }
 
+/**
+ * `update` upgrades the PLUGIN; this finishes the job by offering to upgrade
+ * the CLI too, so "update" means what a user reasonably assumes it means.
+ *
+ * Runs LAST in the update flow on purpose: `npm i -g` replaces this package's
+ * own directory, so nothing may dynamically import from it afterwards. Skipped
+ * silently when the halves already agree, and never forced — a global install
+ * can need permissions we shouldn't assume, and npx users have nothing to
+ * update at all.
+ */
+async function offerCliSelfUpdate(uc) {
+  const cli = cliVersion();
+  const plugin = installedVersion();
+  if (uc.classifyCliSkew({ cliVersion: cli, pluginVersion: plugin }) !== "cli-behind") return;
+
+  const kind = uc.detectCliInstallKind(resolve(__dirname, ".."));
+  const fix = uc.cliUpdateCommand(kind, PKG);
+  console.log(
+    `\n  ⚠️  Your ${BOLD}multi-clawd${RESET} command is v${cli} but the plugin is now v${plugin}.`,
+  );
+  console.log(
+    `     ${DIM}doctor and setup run from the command, so they'd report on the new plugin using old logic.${RESET}`,
+  );
+
+  if (kind !== "global") {
+    console.log(`     Bring it up to date with: ${BOLD}${fix}${RESET}`);
+    return;
+  }
+  if (!(await askYes(`     Update the command now? (${fix})`))) {
+    console.log(`     ${DIM}Skipped — run \`${fix}\` when you're ready.${RESET}`);
+    return;
+  }
+  const r = spawnSync("npm", ["i", "-g", `${PKG}@latest`], { stdio: "inherit" });
+  if (r.status === 0) {
+    console.log(`  ✅ command updated — the new version applies from your next run.`);
+  } else {
+    console.log(`  ⚠ that failed (permissions?) — run it yourself: ${BOLD}${fix}${RESET}`);
+  }
+}
+
 /**
  * Self-heal the scheduled watchdog after an update: the npm install dir is
  * regenerated on every update, so a unit pointing into it just orphaned.
@@ -374,6 +548,9 @@ switch (cmd) {
   case "explain":
     await explain();
     break;
+  case "chain":
+    await chain(rest);
+    break;
   case "doctor":
     runSibling("doctor.mjs", rest);
     break;
@@ -386,8 +563,13 @@ switch (cmd) {
     const cliVersion = JSON.parse(
       readFileSync(resolve(__dirname, "..", "package.json"), "utf8"),
     ).version;
+    const pluginVersion = installedVersion();
     console.log(`cli: v${cliVersion}`);
-    console.log(`installed plugin: ${installedVersion() ? `v${installedVersion()}` : "(not installed)"}`);
+    console.log(`installed plugin: ${pluginVersion ? `v${pluginVersion}` : "(not installed)"}`);
+    // Two versions printed side by side invite exactly one question — "is that
+    // a problem?" — so answer it here rather than leaving the reader to guess.
+    const skewNote = await cliSkewNote(cliVersion, pluginVersion);
+    if (skewNote) console.log(`\n⚠️  ${skewNote}`);
     break;
   }
   default:

package/scripts/doctor.mjs

@@ -114,6 +114,31 @@ const entry = config?.plugins?.entries?.["multi-clawd"];
 const pluginConfig = entry?.config ?? {};
 if (!manifest) bad(`no installed manifest at ${EXT_DIR}`);
 else ok(`installed at ${EXT_DIR}`);
+
+// Doctor itself ships in the CLI half, so a stale CLI means these very
+// findings were produced by older logic than the plugin they describe. That
+// has to be the first thing reported, or every line below is suspect.
+{
+  // REPO_DIR first, unlike the health imports below: this is CLI-side logic and
+  // doctor IS the CLI half, so it must use its own copy. Reaching for the
+  // plugin's copy would ask a possibly-older artifact whether it is older.
+  const uc = await import(join(REPO_DIR, "dist", "update-core.js")).catch(() =>
+    import(join(EXT_DIR, "dist", "update-core.js")).catch(() => undefined),
+  );
+  const cliVer = readJson(join(REPO_DIR, "package.json"))?.version;
+  const pluginVer = manifest?.version;
+  const note =
+    uc && cliVer && typeof uc.formatCliSkew === "function"
+      ? uc.formatCliSkew({
+          cliVersion: cliVer,
+          pluginVersion: pluginVer,
+          installKind: uc.detectCliInstallKind(REPO_DIR),
+          pkg: "@drakon-systems/multi-clawd",
+        })
+      : undefined;
+  if (note) warn(note);
+  else if (cliVer && pluginVer) ok(`CLI and plugin both v${cliVer}`);
+}
 if (!entry) bad("no plugins.entries[\"multi-clawd\"] in openclaw.json");
 else if (entry.enabled !== true) bad("plugin entry present but not enabled");
 else ok("plugin entry enabled");