@drakon-systems/multi-clawd 1.5.2 → 1.5.4

package/README.md

@@ -188,7 +188,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.2/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.5.4/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.
 
@@ -451,6 +451,10 @@ event, and no plugin API can force a rebuild. See `DESIGN.md`.
 
 ## Security
 
+See **[SECURITY.md](SECURITY.md)** for how to report a vulnerability, exactly
+how credentials are handled, and a table documenting every process-spawn
+callsite (the ones static scanners flag) and why each exists.
+
 **Full declaration of what this plugin touches — nothing else:**
 
 | Surface | What multi-clawd does |

package/SECURITY.md

@@ -0,0 +1,82 @@
+# Security
+
+multi-clawd handles Claude Code login credentials. That makes it worth
+explaining exactly what it touches, and worth telling you how to report a
+problem.
+
+## Reporting a vulnerability
+
+Open a [security advisory](https://github.com/Drakon-Systems-Ltd/multi-clawd/security/advisories/new)
+on the repository, or email **security@drakonsystems.com**. Please do not open
+a public issue for anything exploitable.
+
+We aim to acknowledge within 72 hours. If a fix is warranted we will ship it,
+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.
+- **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,
+  etc.), so the credential never sits in plaintext on disk.
+- **Secret-resolution failures are redacted to a fixed reason code.** The
+  message that reaches your logs contains neither the token, nor the
+  provider/id being resolved, nor the provider's own exception text — only the
+  error class, for debuggability.
+- **Plaintext token files are checked, not trusted.** If you use the legacy
+  `oauthTokenFile`, multi-clawd warns (once per process) when the file is
+  readable beyond your own user account. It warns rather than refuses: the
+  credential still works, and the fix is yours to make — `chmod 600`.
+- **Host credentials are stripped from child processes.** 22 Claude/Anthropic
+  environment variables 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.
+
+## Permissions
+
+multi-clawd never grants itself more permission than OpenClaw core grants the
+bundled `claude-cli` backend. It appends `--permission-mode bypassPermissions`
+**only** when your own config already sets `tools.exec.mode: "full"` — which is
+what core does for the bundled backend. Under any other exec mode it passes
+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.
+
+| 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. |
+
+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.
+
+## Things you should decide for yourself
+
+- **The watchdog is persistence.** `setup` schedules a user-level systemd timer
+  (or launchd agent) that can restart the OpenClaw gateway. It is optional —
+  skip it if you don't want that.
+- **The setup wizard edits `~/.openclaw/openclaw.json`.** It backs the file up
+  first and merges rather than overwrites, and `--dry-run` shows you the
+  changes without writing. Use it.
+- **The agent-install one-liner is pinned to a release tag,** not `master`, so
+  what your assistant reads and executes is fixed at a version you chose.
+  Inspect `SETUP-AGENT.md` before pointing an agent at it — that advice holds
+  for anyone's setup guide, including ours.
+
+## Scope
+
+multi-clawd runs entirely on your machine against your own Claude
+subscriptions. It has no server component, no telemetry, and **zero runtime
+dependencies** — the only third-party code in the install is whatever OpenClaw
+itself already provides.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "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.2",
+  "version": "1.5.4",
   "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",
@@ -46,6 +46,7 @@
     "scripts",
     "openclaw.plugin.json",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {

package/scripts/doctor.mjs

@@ -182,6 +182,9 @@ console.log("account credentials");
 const { checkAccountCredential } = await import(join(EXT_DIR, "dist", "login-health.js")).catch(
   () => import(join(REPO_DIR, "dist", "login-health.js")),
 );
+const { summarizeWindowUsage } = await import(join(EXT_DIR, "dist", "health.js")).catch(() =>
+  import(join(REPO_DIR, "dist", "health.js")),
+);
 const io = {
   readFile: (p) => readFileSync(expandHome(p), "utf8"),
   keychainHasClaudeCredentials: () => {
@@ -218,10 +221,32 @@ for (const account of accounts) {
     continue;
   }
   const ageMin = Math.round((Date.now() - (state.updatedAt ?? 0)) / 60000);
+  // A window whose own reset has PASSED describes the previous cycle, and the
+  // rotation logic already voids it ("a passed reset voids the observation",
+  // health.ts). Doctor used to print it raw beside a fresh `(0m old)` stamp,
+  // so a five-day-dead `seven_day@96%` read as "96% used right now" when
+  // nothing was acting on it. The age stamp is the age of the OBSERVATION,
+  // never the window's validity.
+  //
+  // `summarizeWindowUsage` is the same function `explain` uses, so all three
+  // surfaces — rotation, explain, doctor — agree on what counts as live
+  // rather than each carrying its own copy of the rule.
+  const live = new Set(
+    summarizeWindowUsage(state, { staleAfterMs: pluginConfig.pool?.staleAfterMs }, Date.now()).map(
+      (u) => u.window,
+    ),
+  );
   const windows = Object.entries(state.windows ?? {})
-    .map(([w, d]) => `${w}:${d.status}${typeof d.utilization === "number" ? `@${Math.round(d.utilization * 100)}%` : ""}`)
+    .map(([w, d]) => {
+      const hasUtil = typeof d.utilization === "number";
+      const util = hasUtil ? `@${Math.round(d.utilization * 100)}%` : "";
+      // Only utilization-bearing account windows are summarised; a window
+      // carrying a number that did NOT survive is one the pool ignores.
+      const stale = hasUtil && !w.startsWith("model:") && !live.has(w);
+      return `${w}:${d.status}${util}${stale ? " (expired — ignored)" : ""}`;
+    })
     .join(" ");
-  ok(`${account.id}: ${windows || "no windows"} (${ageMin}m old)`);
+  ok(`${account.id}: ${windows || "no windows"} (observed ${ageMin}m ago)`);
 }
 
 // ── 6. pool ─────────────────────────────────────────────────────────────────