@drakon-systems/multi-clawd 2.1.1 → 2.1.3

package/README.md

@@ -284,16 +284,15 @@ claude-cli/claude-fable-5        # main login
 
 ## Platform support
 
-multi-clawd is pure Node (no native modules, no shell-outs) and mirrors the
-bundled `claude-cli` backend 1:1 — it runs anywhere OpenClaw's normal Claude
-Code backend runs.
+multi-clawd uses Node without native modules. External commands are run with
+argument arrays, never through a shell string. Launch mode varies by platform.
 
 | Platform | Status |
 |---|---|
 | Linux | ✅ Verified in production (x64 and arm64) |
-| macOS | ✅ Supported — no platform-specific code paths |
+| macOS | ✅ Supported — reads Claude logins from the Keychain through the `security` CLI and schedules the optional watchdog with a launchd plist in `~/Library/LaunchAgents/` |
 | Windows (WSL2) | ✅ Supported — OpenClaw's recommended gateway runtime on Windows; follow the Linux instructions inside WSL |
-| Windows (native) | ⚠️ Expected to work (the gateway spawns `claude` for this plugin exactly as it does for the bundled backend), not yet verified by us — reports welcome |
+| Windows (native) | ⚠️ Not yet verified by us — verified launch is not implemented on Windows; it falls back to the legacy node + shim launch, so the v2.1.0 verified-launch fix for OpenClaw 2026.10.2 setup authority ("Ask OpenClaw") does not apply there. Reports welcome. |
 
 ## Install
 
@@ -375,6 +374,8 @@ cd multi-clawd && npm install && npm run build
 openclaw plugins install "$(pwd)"
 ```
 
+npm 10 and 11 both work here because the lockfile is committed.
+
 ```powershell
 # Windows (native, PowerShell)
 git clone https://github.com/Drakon-Systems-Ltd/multi-clawd.git
@@ -385,7 +386,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/v2.1.1/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.1.3/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.
 
@@ -745,9 +746,10 @@ What to know:
 
 - **Why a native or config-dir login needs its own token.** That login is a
   rotating one-time OAuth grant, and a copy of it breaks on the next refresh.
-  multi-clawd never reads Claude's own credential files. Run `claude
-  setup-token` signed in as that account and store the token. `setup` walks
-  you through it.
+  multi-clawd never copies that login into a direct profile. (The usage poll
+  and login checks do read Claude's credential files, but never copy or
+  rewrite them.) Run `claude setup-token` signed in as that account and store
+  the token. `setup` walks you through it.
 - **Already stored a profile yourself?** Adopt it with
   `"direct": { "profileId": "anthropic:<id>" }`. It gets ordered, never
   rewritten.
@@ -849,11 +851,11 @@ callsite (the ones static scanners flag) and why each exists.
 
 | 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. |
+| Network | The gateway plugin polls `https://api.anthropic.com/api/oauth/usage` for eligible pooled accounts on an interval (default 120000 ms / 2 minutes); `pool.usagePoll.enabled: false` disables that poll. `multi-clawd usage` requests the same endpoint on demand. `doctor` runs `npm view` when its registry cache is stale; install and update commands contact the package registry. Claude Code subprocesses make their own provider requests. No plugin telemetry or analytics endpoint. |
+| Credentials | Reads declared setup-token files or gateway-resolved `oauthTokenRef` values for Claude child launches; reads each eligible account's `.credentials.json` access token for the usage poll; reads Claude login credentials from files or the macOS Keychain via the `security` CLI for login checks and runtime auth; reads account identity for file-backed logins from `.claude.json` (`~/.claude.json` for a native login, or the account config dir). Setup tokens are passed to Claude through the child environment. |
+| Files read | `~/.openclaw/openclaw.json`, declared account config dirs and token files, Claude `.credentials.json` and `.claude.json` files as described above, and local state files. |
+| Files written | Under `~/.openclaw/state/multi-clawd/` by default: `<id>.json`, `<id>.usage.json`, `pool-<id>.sticky.json`, `direct-order.sticky.json`, `known-models.json`, `alerts-spool.jsonl`, `watchdog.json`, `registry-check.json`, `auth-profiles-<agent>.json`, `runtime/<hash>/` (copied runtime files), and `watchdog-launcher.mjs`. The watchdog state file can be redirected with `MULTI_CLAWD_WATCHDOG_STATE`. Setup writes `~/.openclaw/openclaw.json` and a dated backup. On session handover, transcript `.jsonl` files are copied between account config dirs. The optional watchdog installs `~/.config/systemd/user/multi-clawd-eviction-watchdog.service` and `.timer` on Linux, or `~/Library/LaunchAgents/com.multi-clawd.eviction-watchdog.plist` on macOS; the unit points at the state-dir launcher. |
+| Processes | Launches Claude Code and the node + shim transport; CLI, setup and doctor run npm, OpenClaw, Claude and OS scheduler commands; the optional watchdog checks OpenClaw logs and may restart the gateway; Hermes integration runs its Python bridge. See [SECURITY.md](SECURITY.md) for the process-call table. |
 | Consent | The wizard asks before every write, merges non-destructively, and never overwrites an existing account entry. `--dry-run` previews everything. |
 
 Housekeeping:

package/SECURITY.md

@@ -15,9 +15,9 @@ credit you (unless you'd rather we didn't), and note it in the CHANGELOG.
 
 ## How credentials are handled
 
-- **Tokens are never logged and never appear in a command line.** They are
-  passed to the Claude CLI child process through its environment only, so they
-  cannot leak into a process list, a shell history, or a log file.
+- **Tokens are never logged and never appear in a command line.** Claude CLI
+  child launches receive setup tokens through their environment; direct-route
+  OpenClaw commands receive them on stdin.
 - **Secret references are preferred over token files.** `oauthTokenRef` uses
   the same `{source, provider, id}` shape as the rest of `openclaw.json` and
   resolves through the gateway's own configured secret providers (1Password,
@@ -34,8 +34,9 @@ credit you (unless you'd rather we didn't), and note it in the CHANGELOG.
   environment variables covering authentication, runtime, and telemetry are
   cleared before each launch, so one account's credential cannot bleed into
   another account's session.
-- **State files are written `0600`,** atomically (temp file + rename), and
-  contain rate-limit telemetry only — never credentials.
+- **Per-account health and usage files are written `0600`,** using temporary
+  files and rename, and contain rate-limit data rather than credentials. Other
+  state files include model, alert, registry and watchdog data.
 
 ## Permissions
 
@@ -48,20 +49,25 @@ nothing and Claude keeps its default prompt-honouring behaviour.
 ## Why static scanners flag this package
 
 Automated scans flag multi-clawd for `dangerous_exec`. That is expected and
-correct: starting Claude Code processes *is* the product. Every such callsite
-is listed here so you can check them yourself.
+correct: starting Claude Code processes *is* the product. Every source file
+that calls a child-process API is listed here so you can check it yourself.
 
 | Location | What it runs | Why |
 | --- | --- | --- |
-| `dist/shim.js` | the `claude` binary | The core function: launches Claude Code for the selected account. Argv is built from a fixed base list plus your configured model; no shell. |
-| `dist/watchdog-schedule.js` | `node <bundled script>` | Runs the eviction watchdog on a timer. Path is the package's own script. |
-| `scripts/cli.mjs` | `node <bundled script>` | The CLI dispatching to its own subcommands. |
-| `scripts/setup.mjs` | `launchctl` / `systemctl` | Loads the watchdog timer during setup on macOS/Linux. |
-| `dist/openclaw-runner.js` | the `openclaw` CLI (or `directRoute.openclawCommand`) | Direct route only (v1.9, accounts with `direct`): reads and writes the `anthropic` auth profiles and order through OpenClaw's own subcommands (`models auth list`/`order get`/`order set`/`paste-token`, `secrets apply`, `models status`). A setup-token only ever travels on the child's stdin. Never spawned without `direct` configured. |
-
-None of these pass a string to a shell — they are direct process spawns with
-argument arrays, so there is no quoting or injection surface. Paths are
-package-internal or derived from your home directory, never from remote input.
+| `dist/shim.js` | selected `claude` executable | Launches Claude Code for the selected account and, when an in-turn retry is armed, relaunches it for a sibling account. |
+| `dist/shim-transport.js` | `node <shim>` | Runs the shim for an execute-transport turn. |
+| `dist/credential-store.js` | `security find-generic-password` / `security dump-keychain` | Reads a macOS Keychain login or inventories Keychain item attributes for credential checks. |
+| `dist/watchdog-schedule.js` | generated `watchdog-launcher.mjs` runs `node <bundled eviction-watchdog.mjs>` | Renders the state-dir launcher that a systemd user timer or launchd agent runs. The launcher resolves the current install before spawning its bundled watchdog script. |
+| `dist/openclaw-runner.js` | the `openclaw` CLI (or `directRoute.openclawCommand`) | Direct route only: reads and writes the `anthropic` auth profiles and order through OpenClaw subcommands. A setup token travels on the child's stdin. |
+| `scripts/cli.mjs` | `npm view` / `npm i -g`, `openclaw --version`, `openclaw` plugin install and gateway restart, `claude` login/status commands, `launchctl` / `systemctl`, and `node <bundled script>` | Checks and updates the CLI/plugin, handles account login, dispatches subcommands and repairs watchdog scheduling. |
+| `scripts/setup.mjs` | `claude --version`, `launchctl` / `systemctl` | Checks the Claude CLI and loads or repairs optional watchdog scheduling. |
+| `scripts/doctor.mjs` | `npm view`, `claude --version`, `openclaw models auth list` / `openclaw agent`, `launchctl` / `systemctl` | Checks registry version when its cache is stale, inspects auth and watchdog status, and optionally probes accounts. |
+| `scripts/eviction-watchdog.mjs` | `openclaw logs --plain` / `openclaw gateway restart` | Detects the eviction signature and restarts the gateway when the watchdog's conditions are met. |
+| `scripts/hermes.mjs` | Python interpreter with `-c` / bundled bridge | Checks Python availability and runs the Hermes bridge. |
+
+None of these pass a command string to a shell: child-process calls use an
+executable and argument array. The launcher generated by `watchdog-schedule`
+uses the same form.
 
 ## Things you should decide for yourself
 

package/dist/runtime-auth.js

@@ -1,4 +1,4 @@
-import { ACCESS_TOKEN_EXPIRY_SKEW_MS, CLAUDE_KEYCHAIN_SERVICE, assessAccountCredential, keychainServiceForConfigDir, } from "./login-health.js";
+import { ACCESS_TOKEN_EXPIRY_SKEW_MS, AUTH_PROOF_FRESH_MS, CLAUDE_KEYCHAIN_SERVICE, assessAccountCredential, keychainServiceForConfigDir, } from "./login-health.js";
 export const RUNTIME_AUTH_MARKER_PREFIX = "oauth:";
 export const LOGIN_AUTH_CACHE_TTL_MS = 30 * 1000;
 export function runtimeAuthMarker(providerId) {
@@ -61,10 +61,20 @@ export function createLoginAuthCache(options) {
         const tokenBound = check.status === "ok" && check.expiresAt !== undefined
             ? check.expiresAt - ACCESS_TOKEN_EXPIRY_SKEW_MS
             : undefined;
-        const hardUntil = tokenBound !== undefined && tokenBound > nowMs ? tokenBound : nowMs + ttlMs;
+        let hardUntil = nowMs + ttlMs;
+        if (tokenBound !== undefined && tokenBound > nowMs) {
+            hardUntil = tokenBound;
+        }
+        else if (check.status === "ok") {
+            const lastSuccessAt = health(accountId).lastSuccessAt;
+            if (lastSuccessAt !== undefined) {
+                hardUntil = Math.min(nowMs + 2 * ttlMs, lastSuccessAt + AUTH_PROOF_FRESH_MS);
+            }
+        }
         cache.set(accountId, { check, freshUntil: nowMs + ttlMs, hardUntil });
     };
     const judge = async (account, nowMs) => {
+        await Promise.resolve();
         let io = options.io;
         if (io.platform === "darwin" && options.readKeychainItemAsync) {
             const dir = account.native ? "~/.claude" : account.configDir;
@@ -103,7 +113,7 @@ export function createLoginAuthCache(options) {
             if (health(account.id).failed)
                 return undefined;
             const hit = cache.get(account.id);
-            if (!hit || hit.freshUntil <= nowMs)
+            if (!hit || hit.freshUntil <= nowMs || hit.hardUntil <= nowMs)
                 void refresh(account, nowMs);
             if (!hit || hit.hardUntil <= nowMs)
                 return undefined;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "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": "2.1.1",
+  "version": "2.1.3",
   "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. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",
@@ -61,7 +61,7 @@
     "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=process.env.npm_package_version||JSON.parse(fs.readFileSync('package.json','utf8')).version;fs.writeFileSync('openclaw.plugin.json',JSON.stringify(m,null,2)+'\\n')\"",
     "sync-readme-tag": "node scripts/sync-readme-tag.mjs",
-    "version": "npm run sync-manifest && npm run sync-readme-tag && git add openclaw.plugin.json README.md"
+    "version": "npm run sync-manifest && npm run sync-readme-tag && git add openclaw.plugin.json README.md package-lock.json"
   },
   "peerDependencies": {
     "openclaw": ">=2026.8.1"