@drakon-systems/multi-clawd 1.4.1 → 1.5.0

package/README.md

@@ -167,7 +167,7 @@ dependency (the host provides it), so the install stays lean.
 **From ClawHub (alternative registry):**
 
 ```bash
-openclaw plugins install clawhub:drakon-systems/multi-clawd
+openclaw plugins install clawhub:@drakon-systems/multi-clawd
 ```
 
 **From source (contributors, or ahead of a release):**
@@ -446,6 +446,19 @@ event, and no plugin API can force a rebuild. See `DESIGN.md`.
 
 ## Security
 
+**Full declaration of what this plugin touches — nothing else:**
+
+| Surface | What multi-clawd does |
+|---|---|
+| Network | **Zero egress of its own.** The only network activity is npm/registry traffic during `install`/`update`, and the Claude Code subprocesses talking to Anthropic exactly as the bundled backend does. No telemetry, no analytics, no vendor endpoints. |
+| Credentials | Reads each account's setup-token at launch (file, or a secret-manager reference resolved by your gateway) and passes it **only** via the child process env. Never written elsewhere, never logged, never printed — log redaction is covered by dedicated tests. |
+| Files read | `~/.openclaw/openclaw.json` (config), account config dirs you declare (e.g. `~/.claw2`), token files you declare. |
+| Files written | `~/.openclaw/state/multi-clawd/<account>.json` (local usage-health telemetry, stays on the box), config backups the wizard takes before merging, and — only if you accept the wizard's watchdog step — one systemd user unit / launchd plist pointing at the installed watchdog script. |
+| Processes | Spawns the `claude` CLI per turn (same as the bundled backend). The optional watchdog may restart the OpenClaw gateway when the eviction signature appears — that's its entire job, documented below. |
+| Consent | The wizard asks before every write, merges non-destructively, and never overwrites an existing account entry. `--dry-run` previews everything. |
+
+Housekeeping:
+
 - Tokens are never committed and never logged; `.gitignore` blocks token
   and account directories by default.
 - Prefer a secret reference (`oauthTokenRef`, v0.3) over a plaintext
@@ -488,10 +501,25 @@ Early but real — built for and dogfooded in production.
   (capped at 8d with a clock-skew alarm), reset-less windows keep TTL/decay,
   and model windows age by their own TTL independent of pool `staleAfterMs`
   — closes the quiet-pool blindness half of the no-flip failure class ✅
-- **v0.4** — standalone localhost proxy (OpenAI-compatible) so Hermes and
+- **v1.0** — the public line: published to npm as
+  [`@drakon-systems/multi-clawd`](https://www.npmjs.com/package/@drakon-systems/multi-clawd),
+  `openclaw` demoted to an optional peer, registry installs verified
+  end-to-end ✅
+- **v1.1–v1.2** — the `multi-clawd` CLI (`update` / `setup` / `doctor`);
+  wizard owns the eviction watchdog (schedules it, detects + repoints
+  orphaned units after migrations); wizard account-protection (existing
+  accounts default to keep-unchanged; suspicious secret refs challenged) ✅
+- **v1.3** — `multi-clawd explain`: the whole setup in plain English —
+  accounts, pool decisions, every fallback rung annotated, live health with
+  reset times ✅
+- **v1.4** — `multi-clawd login <account>`: the right Claude sign-in flow
+  for each account shape, verified afterwards (signed-in email shown, token
+  values never touched); ClawHub package published under
+  `@drakon-systems` ✅
+- **Next** — standalone localhost proxy (OpenAI-compatible) so Hermes and
   custom runtimes can share the pool; true per-session affinity; local
-  five-hour-window signal (turn counting)
-- **v1.0** — npm + ClawHub parity releases
+  five-hour-window signal (turn counting); per-account lock for the shim
+  persistence race
 
 See [`DESIGN.md`](./DESIGN.md) for the architecture, the three obvious
 approaches that *don't* work, and why.

package/dist/explain-core.js

@@ -1,3 +1,27 @@
+const WINDOW_LABELS = {
+    five_hour: "5-hour",
+    seven_day: "weekly",
+    seven_day_overage_included: "weekly incl. overage",
+};
+export function relativeUntil(ms, nowMs) {
+    const mins = Math.max(0, Math.round((ms - nowMs) / 60000));
+    if (mins < 90)
+        return `~${mins}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 36)
+        return `~${hours}h`;
+    return `~${Math.round(hours / 24)}d`;
+}
+export function renderUsageLine(usage, nowMs) {
+    return usage
+        .map((u) => {
+        const label = WINDOW_LABELS[u.window] ?? u.window;
+        const pct = `${Math.round(u.utilization * 100)}%`;
+        const reset = u.resetsAt !== undefined ? ` (resets ${relativeUntil(u.resetsAt, nowMs)})` : "";
+        return `${label} ${pct}${reset}`;
+    })
+        .join(" · ");
+}
 export function describeAccount(acc) {
     if (acc.native) {
         return "the machine's main `claude` login (default config dir; OS keychain on macOS)";
@@ -82,10 +106,12 @@ export function renderExplanation(model) {
     }
     lines.push("");
     if (model.health.length > 0) {
+        const nowMs = model.nowMs ?? Date.now();
         lines.push("RIGHT NOW");
         for (const h of model.health) {
             const word = VERDICT_WORDS[h.verdict] ?? h.verdict;
             lines.push(`  ${h.id}: ${word}${h.detail ? ` — ${h.detail}` : ""}`);
+            lines.push(`      usage: ${h.usage?.length ? renderUsageLine(h.usage, nowMs) : "no live telemetry"}`);
         }
         if (model.pool) {
             lines.push(model.stickyAccount

package/dist/health.js

@@ -72,6 +72,28 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
         return { verdict: "no_data" };
     return worst;
 }
+export function summarizeWindowUsage(state, options, nowMs) {
+    if (!state)
+        return [];
+    const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    const usage = [];
+    for (const [window, w] of Object.entries(state.windows)) {
+        if (window.startsWith(MODEL_WINDOW_PREFIX))
+            continue;
+        if (typeof w.utilization !== "number")
+            continue;
+        const resetMs = typeof w.resetsAt === "number" ? w.resetsAt * 1000 : undefined;
+        const resetBearing = resetMs !== undefined && resetMs > nowMs;
+        if (resetBearing && nowMs - w.seenAt > MAX_RESET_HORIZON_MS)
+            continue;
+        if (resetMs !== undefined && !resetBearing)
+            continue;
+        if (!resetBearing && nowMs - w.seenAt > staleAfterMs)
+            continue;
+        usage.push({ window, utilization: w.utilization, resetsAt: resetMs });
+    }
+    return usage.sort((a, b) => (b.resetsAt ?? 0) - (a.resetsAt ?? 0));
+}
 export function choosePoolAccount(pool) {
     const usable = pool.find((a) => a.verdict === "ok" || a.verdict === "no_data");
     if (usable)

package/dist/index.js

@@ -216,7 +216,7 @@ 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 buildBackend(account, execMode) {
+export function buildBackend(account, execMode) {
     return {
         id: account.id,
         liveTest: {
@@ -247,7 +247,7 @@ function buildBackend(account, execMode) {
             imagePathScope: "workspace",
             sessionArg: "--session-id",
             sessionMode: "always",
-            reseedFromRawTranscriptWhenUncompacted: false,
+            reseedFromRawTranscriptWhenUncompacted: true,
             sessionIdFields: ["session_id", "sessionId", "conversation_id", "conversationId"],
             systemPromptFileArg: "--append-system-prompt-file",
             systemPromptMode: "append",

package/dist/shim-core.js

@@ -1,4 +1,5 @@
 export const PRUNE_AFTER_MS = 14 * 24 * 60 * 60 * 1000;
+export const EXPIRED_REJECTED_GRACE_MS = 5 * 60 * 1000;
 const RAW_INFO_MAX_CHARS = 512;
 export function createLineScanner(onLine) {
     let buffer = "";
@@ -106,8 +107,16 @@ export function mergeHealthStates(disk, live, now, pruneAfterMs = PRUNE_AFTER_MS
     const windows = canonicalizeModelWindowKeys(merged);
     if (now !== undefined) {
         for (const [key, w] of Object.entries(windows)) {
-            if (now - w.seenAt > pruneAfterMs)
+            if (now - w.seenAt > pruneAfterMs) {
                 delete windows[key];
+                continue;
+            }
+            const resetMs = typeof w.resetsAt === "number" ? w.resetsAt * 1000 : undefined;
+            if (w.status === "rejected" &&
+                resetMs !== undefined &&
+                now - resetMs > EXPIRED_REJECTED_GRACE_MS) {
+                delete windows[key];
+            }
         }
     }
     const updatedAt = Math.max(disk.updatedAt ?? 0, live.updatedAt ?? 0);

package/openclaw.plugin.json

@@ -1,9 +1,18 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
+  "version": "1.5.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", "claw2", "clawd"],
-  "providers": ["claw1", "claw2", "clawd"],
+  "cliBackends": [
+    "claw1",
+    "claw2",
+    "clawd"
+  ],
+  "providers": [
+    "claw1",
+    "claw2",
+    "clawd"
+  ],
   "modelCatalog": {
     "runtimeAugment": true
   },
@@ -29,7 +38,9 @@
           },
           "accounts": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Account ids (from accounts[]) in preference order; the first is the home account and reclaims the pool when its usage window resets."
           },
           "utilizationThreshold": {
@@ -51,7 +62,9 @@
             "properties": {
               "ladder": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "Same-provider models to step down to, best first (e.g. [\"claude-opus-4-8\"]). Requests already at/below the ladder never degrade further."
               },
               "pins": {
@@ -61,8 +74,14 @@
                   "type": "object",
                   "additionalProperties": false,
                   "properties": {
-                    "agentDirIncludes": { "type": "string", "description": "Pin when the launching agent's dir contains this substring." },
-                    "workspaceDirIncludes": { "type": "string", "description": "Pin when the workspace dir contains this substring." }
+                    "agentDirIncludes": {
+                      "type": "string",
+                      "description": "Pin when the launching agent's dir contains this substring."
+                    },
+                    "workspaceDirIncludes": {
+                      "type": "string",
+                      "description": "Pin when the workspace dir contains this substring."
+                    }
                   }
                 }
               }
@@ -70,7 +89,9 @@
           },
           "models": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Extra model ids to expose on the pool backend."
           },
           "defaultModel": {
@@ -85,7 +106,9 @@
         "items": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["id"],
+          "required": [
+            "id"
+          ],
           "properties": {
             "id": {
               "type": "string",
@@ -112,14 +135,25 @@
               "description": "Secret reference resolving to this account's Claude Code setup-token via the gateway's configured secret providers — same shape as every other secret in openclaw.json, e.g. {\"source\":\"exec\",\"provider\":\"onepassword\",\"id\":\"op://Vault/Item/field\"}. Preferred over oauthTokenFile (no plaintext on disk). Resolution failures degrade the account (auth fails, chain steps) rather than crashing the launch.",
               "additionalProperties": true,
               "properties": {
-                "source": { "type": "string", "description": "Secret source kind: env | file | exec." },
-                "provider": { "type": "string", "description": "Configured secret provider name, e.g. \"onepassword\"." },
-                "id": { "type": "string", "description": "Provider-scoped secret id, e.g. an op:// reference." }
+                "source": {
+                  "type": "string",
+                  "description": "Secret source kind: env | file | exec."
+                },
+                "provider": {
+                  "type": "string",
+                  "description": "Configured secret provider name, e.g. \"onepassword\"."
+                },
+                "id": {
+                  "type": "string",
+                  "description": "Provider-scoped secret id, e.g. an op:// reference."
+                }
               }
             },
             "models": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Extra model ids to expose for this account beyond the mirrored claude-cli catalog (e.g. a brand-new model OpenClaw doesn't list yet). Unknown modern claude-* ids also resolve on demand without being listed here."
             },
             "defaultModel": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.4.1",
+  "version": "1.5.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",
@@ -55,7 +55,9 @@
     "test:watch": "vitest",
     "prepare": "npm run build",
     "doctor": "node scripts/doctor.mjs",
-    "setup": "node scripts/setup.mjs"
+    "setup": "node scripts/setup.mjs",
+    "sync-manifest": "node -e \"const fs=require('fs');const m=JSON.parse(fs.readFileSync('openclaw.plugin.json','utf8'));m.version=require('./package.json').version;fs.writeFileSync('openclaw.plugin.json',JSON.stringify(m,null,2)+'\\n')\"",
+    "version": "npm run sync-manifest && git add openclaw.plugin.json"
   },
   "peerDependencies": {
     "openclaw": ">=2026.6"
@@ -69,5 +71,9 @@
     "openclaw": "2026.7.1",
     "typescript": "^5.9.0",
     "vitest": "^4.1.10"
+  },
+  "homepage": "https://github.com/Drakon-Systems-Ltd/multi-clawd#readme",
+  "bugs": {
+    "url": "https://github.com/Drakon-Systems-Ltd/multi-clawd/issues"
   }
 }

package/scripts/cli.mjs

@@ -253,7 +253,11 @@ async function explain() {
     if (h.verdict === "exhausted" && h.resumeAt) {
       detail = `${h.reason ?? "limit hit"} — back in ${rel(h.resumeAt)}`;
     }
-    return { id: a.id, verdict: h.verdict, detail };
+    const usage = health.summarizeWindowUsage(state, {
+      utilizationThreshold: pool?.utilizationThreshold,
+      staleAfterMs: pool?.staleAfterMs,
+    }, now);
+    return { id: a.id, verdict: h.verdict, detail, usage };
   });
   let stickyAccount;
   if (pool) {
@@ -266,7 +270,7 @@ 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 }),
+    ec.renderExplanation({ accounts, pool, chain, health: healthRows, stickyAccount, nowMs: now }),
   );
   console.log(`\n${DIM}(health checks: multi-clawd doctor · change things: multi-clawd setup)${RESET}`);
 }