@drakon-systems/multi-clawd 2.4.0 → 2.5.1

package/scripts/cli.mjs

@@ -12,8 +12,7 @@
  * 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`.
+ * ClawHub install with npm fallback, gateway restart, doctor.
  */
 import { execFileSync, spawnSync } from "node:child_process";
 import { readFileSync, existsSync as existsSyncEarly } from "node:fs";
@@ -53,8 +52,8 @@ Run via npx (${DIM}npx ${PKG} <command>${RESET}) or install globally
 
 const { resolveInstallDir } = await import(join(__dirname, "_shared.mjs"));
 
-function installedVersion() {
-  const dir = resolveInstallDir();
+function installedVersion(installPath) {
+  const dir = installPath ?? resolveInstallDir();
   if (!dir) return undefined;
   try {
     return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
@@ -63,6 +62,18 @@ function installedVersion() {
   }
 }
 
+function trackedInstallRecord(uc) {
+  let inspected;
+  try {
+    inspected = execFileSync("openclaw", ["plugins", "inspect", "multi-clawd", "--json"], {
+      encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    // Legacy OpenClaw may expose the install only in openclaw.json.
+  }
+  return uc.parseInstallRecord(inspected, readOpenclawConfigSync());
+}
+
 function latestVersion() {
   try {
     return execFileSync("npm", ["view", PKG, "version"], { encoding: "utf8", timeout: 15000 })
@@ -167,13 +178,14 @@ async function loadDirect(config) {
   const pc = config?.plugins?.entries?.["multi-clawd"]?.config ?? {};
   const accounts = Array.isArray(pc.accounts) ? pc.accounts : [];
   if (!accounts.some((a) => a && a.direct !== undefined && a.direct !== false)) return undefined;
-  let dr, ds, rep, run, shim;
+  let dr, ds, rep, run, shim, hist;
   try {
     dr = await import(resolve(__dirname, "..", "dist", "direct-route.js"));
     ds = await import(resolve(__dirname, "..", "dist", "direct-sync.js"));
     rep = await import(resolve(__dirname, "..", "dist", "direct-report.js"));
     run = await import(resolve(__dirname, "..", "dist", "openclaw-runner.js"));
     shim = await import(resolve(__dirname, "..", "dist", "shim-core.js"));
+    hist = await import(resolve(__dirname, "..", "dist", "history.js"));
   } catch (err) {
     console.error(distFailure("direct", "direct-report.js", err));
     process.exit(1);
@@ -217,6 +229,8 @@ async function loadDirect(config) {
       sticky,
       minDwellMs: pool?.minDwellMs,
       strategy: pool?.strategy,
+      readHistory: () => { try { return hist.readHistory(join(stateDir, hist.HISTORY_FILE)); } catch { return []; } },
+      spreadWindowMs: pool?.spreadWindowMs,
       nowMs: Date.now(),
       ...opts,
     });
@@ -473,25 +487,46 @@ async function update() {
     console.error("  ❌ the `openclaw` CLI is not on PATH — install OpenClaw first.");
     process.exit(1);
   }
-  const installed = installedVersion();
+  const source = trackedInstallRecord(uc);
+  const installed = installedVersion(source?.installPath) ?? source?.version;
   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;
+  const migrating = action === "up-to-date" && source?.source === "npm";
+  if (action === "up-to-date" && !migrating) return;
+  if (migrating) console.log("  This plugin is tracked as an npm install. Reinstalling from ClawHub clears OpenClaw's npm source caution.\n");
   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) {
+  const targetVersion = migrating ? installed : latest;
+  if (!uc.exactTargetVersion(targetVersion)) {
+    console.error("  ❌ cannot install: no valid exact target version is available.");
+    process.exit(1);
+  }
+  if (!(await askYes(`  ${migrating ? "Reinstall from ClawHub" : action === "install" ? "Install" : "Update"} now?`))) return;
+  let installedOk = false;
+  for (const [index, argv] of uc.pluginInstallAttempts(PKG, targetVersion).entries()) {
+    if (index === 1) console.log("\n  ClawHub install failed; falling back to npm. OpenClaw may show a source caution for npm installs.");
+    console.log(`\n  ${DIM}openclaw ${argv.join(" ")}${RESET}`);
+    // stdin and stdout stay on the terminal so OpenClaw's install confirmation
+    // prompts still work; stderr (where OpenClaw reports failures) is captured
+    // to decide whether a ClawHub failure may fall back to npm, then echoed.
+    const result = spawnSync("openclaw", argv, { encoding: "utf8", stdio: ["inherit", "inherit", "pipe"] });
+    if (result.stderr) process.stderr.write(result.stderr);
+    if (result.status === 0 && !result.signal && !result.error) {
+      installedOk = true;
+      break;
+    }
+    if (index === 0 && uc.classifyClawhubFailure({ status: result.status, signal: result.signal, error: result.error }, `${result.stderr ?? ""}\n${result.error?.message ?? ""}`) === "stop") {
+      console.error("\n  ❌ ClawHub install failed without a confirmed availability error; npm was not tried. Review the failure above before retrying.");
+      process.exit(1);
+    }
+  }
+  if (!installedOk) {
     console.error("\n  ❌ install failed — see output above.");
     process.exit(1);
   }
@@ -510,7 +545,8 @@ async function update() {
     console.log(`\n  ⚠ doctor found problems — if it flagged the watchdog, run ${BOLD}npx ${PKG} setup${RESET} to repair it.`);
     process.exit(doc.status ?? 1);
   }
-  console.log(`\n  ✅ done — now on v${installedVersion() ?? "?"}`);
+  const updatedSource = trackedInstallRecord(uc);
+  console.log(`\n  ✅ done — now on v${installedVersion(updatedSource?.installPath) ?? updatedSource?.version ?? "?"}`);
 }
 
 /**
@@ -639,7 +675,29 @@ async function healWatchdogUnit() {
 }
 
 /** `explain` — gather config + live health, render the plain-English view. */
-async function explain() {
+async function explain(args = []) {
+  let historySince;
+  if (args.length) {
+    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]]");
+      process.exitCode = 1;
+      return;
+    }
+    historySince = args[2] ?? "7d";
+  }
+  let history;
+  if (historySince) {
+    try {
+      history = await import(resolve(__dirname, "..", "dist", "history.js"));
+      history.parseHistorySince(historySince);
+    } catch (err) {
+      console.error(`explain: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
   const { readFileSync: rf, existsSync } = await import("node:fs");
   const { homedir } = await import("node:os");
   let ec, health, shim;
@@ -691,7 +749,8 @@ async function explain() {
       weeklyUtilizationThreshold: pool?.weeklyUtilizationThreshold,
       staleAfterMs: pool?.staleAfterMs,
     }, now);
-    return { id: a.id, verdict: h.verdict, detail, usage };
+    // #93: the headroom figure the pool ranks near-limit members by.
+    return { id: a.id, verdict: h.verdict, detail, usage, utilization: h.utilization };
   });
   let stickyAccount;
   let stickyEntry;
@@ -704,6 +763,18 @@ async function explain() {
       /* no sticky state */
     }
   }
+  // #92: the spread strategy places by the served-launch journal; hand
+  // explain the same events the launch path reads so the reason shown is the
+  // reason acted on.
+  let spreadHistory;
+  if (pool?.strategy === "spread") {
+    try {
+      const hist = history ?? await import(resolve(__dirname, "..", "dist", "history.js"));
+      spreadHistory = hist.readHistory(join(stateDir, hist.HISTORY_FILE));
+    } catch {
+      /* no journal yet: every account counts as never served */
+    }
+  }
   // v1.9: the direct anthropic/* route, when any account opted in.
   let direct;
   const dctx = await loadDirect(config);
@@ -714,9 +785,13 @@ async function explain() {
   }
   console.log(`\n${BOLD}🦞 multi-clawd — your setup, in plain English${RESET}\n`);
   console.log(
-    ec.renderExplanation({ accounts, pool, chain, health: healthRows, stickyAccount, stickyEntry, nowMs: now, direct }),
+    ec.renderExplanation({ accounts, pool, chain, health: healthRows, stickyAccount, stickyEntry, nowMs: now, direct, history: spreadHistory }),
   );
   console.log(`\n${DIM}(health checks: multi-clawd doctor · change things: multi-clawd setup)${RESET}`);
+  if (history) {
+    console.log(`\n${history.renderHistory(history.readHistory(join(stateDir, history.HISTORY_FILE)),
+      accounts.map((a) => a.id), historySince, now)}`);
+  }
 }
 
 /**
@@ -790,18 +865,28 @@ async function usageCommand(args) {
     const h = health.classifyAccountHealth(state, healthOptions, now);
     row.verdict = h.verdict;
     row.reason = h.reason;
+    if (h.utilization !== undefined) row.utilization = h.utilization;
     if (pool?.strategy === "reset-aware") resetById.set(a.id, health.sevenDayReset(state, healthOptions, now));
     rows.push(row);
   }
   let next;
   if (pool) {
     const verdicts = pool.accounts.filter((id) => !accounts.find((a) => a.id === id)?.disabled).map((id) => ({ id, verdict: rows.find((r) => r.id === id)?.verdict ?? "no_data",
-      sevenDayResetsAt: resetById.get(id) }));
-    if (pool.strategy === "reset-aware") {
+      utilization: rows.find((r) => r.id === id)?.utilization, sevenDayResetsAt: resetById.get(id) }));
+    if (pool.strategy === "reset-aware" || pool.strategy === "spread") {
       const stickySelection = await import(resolve(__dirname, "..", "dist", "sticky.js"));
       let sticky;
       try { sticky = JSON.parse(rf(join(stateDir, `pool-${pool.id}.sticky.json`), "utf8")); } catch { /* none */ }
-      next = verdicts.length ? stickySelection.decideStickySelection({ verdicts, sticky, nowMs: now, minDwellMs: pool.minDwellMs, strategy: pool.strategy }).account : undefined;
+      let ranked = verdicts;
+      if (pool.strategy === "spread") {
+        // Same journal and window as the launch path (#92).
+        const hist = await import(resolve(__dirname, "..", "dist", "history.js"));
+        const spread = await import(resolve(__dirname, "..", "dist", "spread.js"));
+        let events = [];
+        try { events = hist.readHistory(join(stateDir, hist.HISTORY_FILE)); } catch { /* none */ }
+        ranked = spread.withSpreadStats(verdicts, spread.spreadStatsFromHistory(events, now, spread.spreadWindowMs(pool.spreadWindowMs)));
+      }
+      next = ranked.length ? stickySelection.decideStickySelection({ verdicts: ranked, sticky, nowMs: now, minDwellMs: pool.minDwellMs, strategy: pool.strategy }).account : undefined;
     } else {
       next = verdicts.length ? health.choosePoolAccount(verdicts) : undefined;
     }
@@ -978,7 +1063,7 @@ switch (cmd) {
     break;
   }
   case "explain":
-    await explain();
+    await explain(rest);
     break;
   case "chain":
     await chain(rest);

package/scripts/doctor.mjs

@@ -33,6 +33,60 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HOME = homedir();
+// OpenClaw's tracked install record (#85). Asking OpenClaw costs a process
+// launch (about 2 s on an idle host), so skip it for an unconfigured install.
+// Cache against the manifest and legacy record, with a one-day expiry.
+let inspectText;
+function loadInspectText(foundDir, configRecord) {
+  const cacheFile = join(HOME, ".openclaw", "state", "multi-clawd", "install-record.json");
+  const recordKey = JSON.stringify({ source: configRecord?.source, version: configRecord?.version, installPath: configRecord?.installPath });
+  let mtimeMs;
+  try {
+    mtimeMs = statSync(join(foundDir, "openclaw.plugin.json")).mtimeMs;
+  } catch {
+    /* raced with an uninstall; ask OpenClaw */
+  }
+  try {
+    const cached = JSON.parse(readFileSync(cacheFile, "utf8"));
+    if (cached?.installDir === foundDir && cached?.manifestMtimeMs === mtimeMs && cached?.recordKey === recordKey &&
+      typeof cached?.checkedAt === "number" && Date.now() - cached.checkedAt < 24 * 60 * 60 * 1000 && cached?.install) {
+      inspectText = JSON.stringify({ install: cached.install });
+      return;
+    }
+  } catch {
+    /* no cache yet */
+  }
+  try {
+    inspectText = execFileSync("openclaw", ["plugins", "inspect", "multi-clawd", "--json"], {
+      encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    // Missing or older OpenClaw: the legacy config record is checked below.
+    return;
+  }
+  try {
+    const install = JSON.parse(inspectText)?.install;
+    if (install && typeof install === "object" && typeof install.source === "string") {
+      mkdirSync(dirname(cacheFile), { recursive: true });
+      writeFileSync(
+        cacheFile,
+        JSON.stringify({ installDir: foundDir, manifestMtimeMs: mtimeMs, recordKey, checkedAt: Date.now(), install }, null, 2) + "\n",
+      );
+    }
+  } catch {
+    /* cache is an optimisation, never a requirement */
+  }
+}
+
+function trackedInstallPath(configRecord) {
+  try {
+    const inspected = JSON.parse(inspectText ?? "");
+    if (typeof inspected?.install?.installPath === "string") return inspected.install.installPath;
+  } catch {
+    // Fall back to the legacy config record.
+  }
+  return typeof configRecord?.installPath === "string" ? configRecord.installPath : undefined;
+}
 
 /**
  * Where is the plugin actually installed? Path installs land in
@@ -42,6 +96,21 @@ const HOME = homedir();
  * npm-project install carrying a manifest.
  */
 function resolveInstallDir() {
+  const found = findInstallDirOnDisk();
+  let config;
+  try { config = JSON.parse(readFileSync(join(HOME, ".openclaw", "openclaw.json"), "utf8")); } catch { /* no config */ }
+  const record = config?.plugins?.installs?.["multi-clawd"];
+  const legacyPath = typeof record?.installPath === "string" ? record.installPath : undefined;
+  const hasFound = existsSync(join(found, "openclaw.plugin.json"));
+  if (!hasFound && !record && !config?.plugins?.entries?.["multi-clawd"]) return found;
+  const candidate = !hasFound && legacyPath && existsSync(join(legacyPath, "openclaw.plugin.json")) ? legacyPath : found;
+  loadInspectText(candidate, record);
+  const tracked = trackedInstallPath(record);
+  if (tracked && existsSync(join(tracked, "openclaw.plugin.json"))) return tracked;
+  return candidate;
+}
+
+function findInstallDirOnDisk() {
   const extDir = join(HOME, ".openclaw", "extensions", "multi-clawd");
   if (existsSync(join(extDir, "openclaw.plugin.json"))) return extDir;
   const projects = join(HOME, ".openclaw", "npm", "projects");
@@ -168,7 +237,7 @@ else ok(`installed at ${EXT_DIR}`);
   );
   const cliVer = readJson(join(REPO_DIR, "package.json"))?.version;
   const pluginVer = manifest?.version;
-  const note =
+  const skewNote =
     uc && cliVer && typeof uc.formatCliSkew === "function"
       ? uc.formatCliSkew({
           cliVersion: cliVer,
@@ -177,9 +246,16 @@ else ok(`installed at ${EXT_DIR}`);
           pkg: "@drakon-systems/multi-clawd",
         })
       : undefined;
-  if (note) warn(note);
+  if (skewNote) warn(skewNote);
   else if (cliVer && pluginVer) ok(`CLI and plugin both v${cliVer}`);
 
+  if (uc && typeof uc.parseInstallRecord === "function" && typeof uc.classifyInstallSource === "function") {
+    const source = uc.classifyInstallSource(uc.parseInstallRecord(inspectText, config));
+    if (source?.level === "ok") ok(source.text);
+    else if (source?.level === "warn") warn(source.text);
+    else if (source?.level === "note") note(source.text);
+  }
+
   // Is the installed plugin behind what npm publishes? Nothing else asks:
   // `openclaw plugins update --all` compares against the PINNED spec and so
   // always reports a pinned plugin up to date (found 1 Aug 2026), and doctor
@@ -320,6 +396,17 @@ const {
   "cli",
 );
 const { decideStickySelection } = await importDist("sticky.js", ["decideStickySelection"]);
+// #92: the spread strategy ranks by the shim's served-launch journal; doctor
+// re-reads the same file with the same window so its answer is the launch's.
+// `required` names must be functions: HISTORY_FILE is a string, so it is
+// read off the module rather than listed, or the fallback would reject both
+// candidates and an install that predates history.js would fail doctor.
+const historyModule = await importDist("history.js", ["readHistory"]);
+const readHistory = historyModule.readHistory;
+const HISTORY_FILE = typeof historyModule.HISTORY_FILE === "string" ? historyModule.HISTORY_FILE : "history.jsonl";
+const { spreadStatsFromHistory, spreadWindowMs, withSpreadStats, describeWindow } = await importDist(
+  "spread.js", ["spreadStatsFromHistory", "spreadWindowMs", "withSpreadStats", "describeWindow"],
+);
 // Keychain reads name the account the Claude CLI uses (`-a`), never just the
 // service. Token values are reduced to expiry metadata where they are read and
 // are never printed.
@@ -546,11 +633,15 @@ else {
       weeklyUtilizationThreshold: pool.weeklyUtilizationThreshold,
       rotateOnOverage: pool.rotateOnOverage,
     };
-    const verdicts = members.map((id) => {
+    const rawVerdicts = members.map((id) => {
       const state = readJson(join(STATE_DIR, `${id}.json`));
-      return { id, verdict: classifyAccountHealth(state, healthOptions, now).verdict,
+      const health = classifyAccountHealth(state, healthOptions, now);
+      return { id, verdict: health.verdict, utilization: health.utilization,
         sevenDayResetsAt: pool.strategy === "reset-aware" ? sevenDayReset(state, healthOptions, now) : undefined };
     });
+    const verdicts = pool.strategy === "spread"
+      ? withSpreadStats(rawVerdicts, spreadStatsFromHistory(readHistory(join(STATE_DIR, HISTORY_FILE)), now, spreadWindowMs(pool.spreadWindowMs)))
+      : rawVerdicts;
     const decision = decideStickySelection({
       verdicts,
       sticky,
@@ -563,7 +654,15 @@ else {
       identity?.status === "resolved" ? ` (${describeIdentity(identity, { raw: RAW })})` : "";
     const verdict = verdicts.find((v) => v.id === decision.account)?.verdict ?? "no_data";
     const home = members[0];
-    if (decision.account === home) {
+    if (pool.strategy === "spread") {
+      // No home under spread: a launch off the first member is a placement,
+      // not a rotation, so it is never reported as one.
+      const picked = verdicts.find((v) => v.id === decision.account);
+      ok(
+        `next new session on ${decision.account}${who} — spread, ${picked?.servedInWindow ?? 0} served in the last ${
+          describeWindow(spreadWindowMs(pool.spreadWindowMs))}, health ${verdict}; existing sessions stay on their serving account`,
+      );
+    } else if (decision.account === home) {
       ok(`serving on ${decision.account}${who} — home account, health ${verdict}`);
       if (sticky) {
         note(