@drakon-systems/multi-clawd 2.3.0 → 2.5.0

package/scripts/account-config.mjs

@@ -0,0 +1,115 @@
+import { constants, copyFileSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Locate JSON object properties without reserializing the operator's config. */
+export function jsonSpans(source, offset = 0) {
+  let at = offset;
+  const ws = () => { while (/\s/.test(source[at] ?? "")) at++; };
+  function string() {
+    const start = at++;
+    while (at < source.length) {
+      if (source[at] === "\\") { at += 2; continue; }
+      if (source[at++] === '"') return { value: JSON.parse(source.slice(start, at)), start, end: at };
+    }
+    throw new Error("unterminated JSON string");
+  }
+  function value() {
+    ws();
+    const start = at;
+    if (source[at] === "{") {
+      at++; ws(); const properties = [];
+      while (source[at] !== "}") {
+        const key = string(); ws();
+        if (source[at++] !== ":") throw new Error("invalid JSON object");
+        const child = value(); ws();
+        const end = at;
+        properties.push({ key: key.value, keyStart: key.start, start: child.start, end: child.end, propertyEnd: end });
+        if (source[at] !== ",") break;
+        at++; ws();
+      }
+      if (source[at++] !== "}") throw new Error("invalid JSON object");
+      return { start, end: at, properties };
+    }
+    if (source[at] === "[") {
+      at++; ws(); const items = [];
+      while (source[at] !== "]") {
+        items.push(value()); ws();
+        if (source[at] !== ",") break;
+        at++; ws();
+      }
+      if (source[at++] !== "]") throw new Error("invalid JSON array");
+      return { start, end: at, items };
+    }
+    if (source[at] === '"') return string();
+    while (at < source.length && !/[\s,}\]]/.test(source[at])) at++;
+    return { start, end: at };
+  }
+  const root = value(); ws();
+  if (offset === 0 && at !== source.length) throw new Error("trailing JSON content");
+  return root;
+}
+
+const property = (node, key) => {
+  if (!node?.properties) throw new Error("expected JSON object");
+  const matches = node.properties.filter((p) => p.key === key);
+  if (matches.length > 1) throw new Error(`duplicate ${key} property`);
+  return matches[0];
+};
+const child = (source, node, key) => {
+  const p = property(node, key);
+  return p && jsonSpans(source, p.start);
+};
+
+export function editAccountDisabled(source, id, disabled) {
+  const original = JSON.parse(source);
+  let node = jsonSpans(source);
+  for (const key of ["plugins", "entries", "multi-clawd", "config", "accounts"]) {
+    node = child(source, node, key);
+    if (!node) throw new Error(`missing plugins.entries["multi-clawd"].config.accounts`);
+  }
+  if (!node.items) throw new Error("accounts must be an array");
+  const accounts = original?.plugins?.entries?.["multi-clawd"]?.config?.accounts;
+  const matches = accounts?.map((a, i) => a?.id === id ? i : -1).filter((i) => i >= 0) ?? [];
+  if (matches.length === 0) throw new Error(`unknown account id "${id}"`);
+  if (matches.length !== 1) throw new Error(`duplicate account id "${id}"`);
+  const account = node.items[matches[0]];
+  const flag = property(account, "disabled");
+  if (flag && typeof accounts[matches[0]].disabled !== "boolean") throw new Error("disabled must be a boolean");
+  let edited;
+  if (flag) {
+    edited = source.slice(0, flag.start) + String(disabled) + source.slice(flag.end);
+  } else if (disabled) {
+    const indent = source.slice(source.lastIndexOf("\n", account.start - 1) + 1, account.start);
+    const space = source.slice(account.start + 1, account.end - 1);
+    const multiline = space.includes("\n");
+    const addition = account.properties.length
+      ? `,${multiline ? `\n${indent}  ` : " "}"disabled": true`
+      : `"disabled": true`;
+    edited = source.slice(0, account.end - 1) + addition + source.slice(account.end - 1);
+  } else {
+    return { edited: source, changed: false };
+  }
+  const expected = structuredClone(original);
+  expected.plugins.entries["multi-clawd"].config.accounts[matches[0]].disabled = disabled;
+  if (JSON.stringify(JSON.parse(edited)) !== JSON.stringify(expected)) throw new Error("targeted edit changed other config values");
+  return { edited, changed: edited !== source };
+}
+
+export function changeAccount(id, disabled, dryRun = false, configFile = join(homedir(), ".openclaw", "openclaw.json")) {
+  const source = readFileSync(configFile, "utf8");
+  const { edited, changed } = editAccountDisabled(source, id, disabled);
+  if (dryRun || !changed) return { changed, dryRun };
+  if (readFileSync(configFile, "utf8") !== source) throw new Error("config changed during edit; retry");
+  const backup = `${configFile}.backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  copyFileSync(configFile, backup, constants.COPYFILE_EXCL);
+  const temporary = `${configFile}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(temporary, edited, { mode: statSync(configFile).mode & 0o777 });
+    if (readFileSync(configFile, "utf8") !== source) throw new Error("config changed during edit; retry");
+    renameSync(temporary, configFile);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+  return { changed, dryRun, backup };
+}

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";
@@ -36,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}account${RESET}   disable or enable a pool account (add --dry-run to preview)
   ${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}direct${RESET}    the direct anthropic/* route — status, or \`direct sync\` to store profiles
@@ -52,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;
@@ -62,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 })
@@ -166,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);
@@ -216,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,
     });
@@ -472,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);
   }
@@ -509,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 ?? "?"}`);
 }
 
 /**
@@ -638,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;
@@ -703,6 +762,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);
@@ -713,9 +784,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)}`);
+  }
 }
 
 /**
@@ -760,7 +835,7 @@ async function usageCommand(args) {
   const rows = [];
   const resetById = new Map();
   for (const a of accounts) {
-    const row = { id: a.id, label: a.label };
+    const row = { id: a.id, label: a.label, ...(a.disabled === true ? { disabled: true, status: "disabled by operator" } : {}) };
     if (a.oauthTokenFile || a.oauthTokenRef) {
       row.skipped = "setup-token login — not polled: the usage endpoint needs the user:profile scope, setup-tokens carry only user:inference (stream telemetry only)";
     } else if (!a.native && !a.configDir) {
@@ -794,15 +869,24 @@ async function usageCommand(args) {
   }
   let next;
   if (pool) {
-    const verdicts = pool.accounts.map((id) => ({ id, verdict: rows.find((r) => r.id === id)?.verdict ?? "no_data",
+    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") {
+    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 = stickySelection.decideStickySelection({ verdicts, sticky, nowMs: now, minDwellMs: pool.minDwellMs, strategy: pool.strategy }).account;
+      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 = health.choosePoolAccount(verdicts);
+      next = verdicts.length ? health.choosePoolAccount(verdicts) : undefined;
     }
   }
   if (args.includes("--json")) {
@@ -822,7 +906,7 @@ async function usageCommand(args) {
   };
   console.log(`\n${BOLD}🦞 multi-clawd — live usage${RESET}  ${DIM}(rotate at ${pct(rotateAt)}${weeklyRotateAt !== undefined ? `, weekly ${pct(weeklyRotateAt)}` : ""}, warn at ${pct(warnThreshold)})${RESET}\n`);
   for (const r of rows) {
-    console.log(`  ${BOLD}${r.id}${RESET}${r.label ? ` ${DIM}— ${r.label}${RESET}` : ""}   pool verdict: ${r.verdict}${r.reason ? ` ${DIM}(${r.reason})${RESET}` : ""}`);
+    console.log(`  ${BOLD}${r.id}${RESET}${r.label ? ` ${DIM}— ${r.label}${RESET}` : ""}   pool verdict: ${r.disabled ? "disabled by operator" : r.verdict}${r.reason ? ` ${DIM}(${r.reason})${RESET}` : ""}`);
     if (r.snapshot) {
       for (const [w, u] of Object.entries(r.snapshot.windows)) {
         console.log(`     ${mark(u.utilization, w)} ${up.usageWindowLabel(w).padEnd(12)} ${pct(u.utilization).padStart(4)}${until(u.resetsAt)}`);
@@ -838,7 +922,10 @@ async function usageCommand(args) {
     console.log("");
   }
   if (pool) {
-    console.log(next ? `  next pooled launch (${pool.id}/…) runs on ${BOLD}${next}${RESET}` : `  ${BOLD}every pooled account is exhausted${RESET} — turns degrade or fall through the chain`);
+    const allDisabled = pool.accounts.length > 0 && pool.accounts.every((id) => accounts.find((a) => a.id === id)?.disabled === true);
+    console.log(next ? `  next pooled launch (${pool.id}/…) runs on ${BOLD}${next}${RESET}` : allDisabled
+      ? `  ${BOLD}pool.accounts[].disabled: every pool member is disabled${RESET}`
+      : `  ${BOLD}no selectable pool member${RESET}`);
   }
   console.log(`\n${DIM}(the gateway polls this every ${Math.round(up.effectiveUsagePollInterval(pool?.usagePoll) / 1000)}s and alerts via the heartbeat; see "Live usage" in the README)${RESET}`);
 }
@@ -954,8 +1041,27 @@ switch (cmd) {
   case "login":
     await login();
     break;
+  case "account": {
+    const [action, id, ...flags] = rest;
+    if (!["enable", "disable"].includes(action) || !id || flags.some((f) => f !== "--dry-run")) {
+      console.error("usage: multi-clawd account <enable|disable> <id> [--dry-run]");
+      process.exitCode = 1;
+      break;
+    }
+    try {
+      const { changeAccount } = await import("./account-config.mjs");
+      const result = changeAccount(id, action === "disable", flags.includes("--dry-run"));
+      console.log(`${result.dryRun ? "dry run: " : ""}${id}: ${action === "disable" ? "disabled" : "enabled"}${result.changed ? "" : " (already set)"}`);
+      if (result.backup) console.log(`backup: ${result.backup}`);
+      if (!result.dryRun && result.changed) console.log("Takes effect when the plugin next reads config (for example after gateway reload); running turns continue.");
+    } catch (err) {
+      console.error(`account: ${err.message}`);
+      process.exitCode = 1;
+    }
+    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.
@@ -354,6 +441,7 @@ const accounts = pluginConfig.accounts ?? [];
 const identities = [];
 if (accounts.length === 0) warn("no accounts configured");
 for (const account of accounts) {
+  if (account.disabled === true) note(`${account.id}: disabled by operator`);
   // WHO this account is, before WHETHER its credential works. An id is a
   // label the operator chose; the login is the thing quota is spent against,
   // and the two drift apart silently (a config dir re-logged-in as the wrong
@@ -494,8 +582,16 @@ console.log("pool");
 const pool = pluginConfig.pool;
 if (!pool) warn("no pool configured — direct backends only, no proactive rotation");
 else {
-  const members = (pool.accounts ?? []).filter((id) => accounts.some((a) => a.id === id));
-  if (members.length < 2) bad(`pool "${pool.id ?? "clawd"}" has ${members.length} valid member(s); needs ≥ 2`);
+  const configuredMembers = (pool.accounts ?? []).filter((id) => accounts.some((a) => a.id === id));
+  const members = configuredMembers.filter((id) => accounts.some((a) => a.id === id && a.disabled !== true));
+  const { isModernClaudeModelId } = await importDist("models.js", ["isModernClaudeModelId"], "cli");
+  const hasDegradeLadder = (pool.degrade?.ladder ?? []).some(isModernClaudeModelId);
+  if (members.length === 0 && configuredMembers.length > 0) bad("pool.accounts[].disabled: every pool member is disabled");
+  if (members.length === 1 && configuredMembers.length > 1) {
+    warn(`pool "${pool.id ?? "clawd"}" has 1 valid member(s); other configured members are disabled — pool remains available`);
+  } else if (members.length === 1 && hasDegradeLadder) {
+    note(`pool "${pool.id ?? "clawd"}" has 1 valid member(s) with a degrade ladder; pool remains available`);
+  } else if (members.length < 2) bad(`pool "${pool.id ?? "clawd"}" has ${members.length} valid member(s); needs ≥ 2`);
   else ok(`pool "${pool.id ?? "clawd"}": ${members.join(" → ")}`);
   const generalThreshold = pool.utilizationThreshold ?? DEFAULT_UTILIZATION_THRESHOLD;
   const weeklyThreshold = pool.weeklyUtilizationThreshold ?? generalThreshold;
@@ -537,11 +633,14 @@ 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,
         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,
@@ -554,7 +653,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(