@drakon-systems/multi-clawd 2.3.0 → 2.4.0

package/README.md

@@ -30,6 +30,7 @@ multi-clawd update    # install (or update) the OpenClaw plugin — right flags,
 multi-clawd setup     # guided wizard: accounts, isolated second login, pool, watchdog
 multi-clawd login claw2   # launch the right Claude sign-in for an account (or re-auth it)
 multi-clawd explain   # your whole setup in plain English — accounts, chain, live health
+multi-clawd account disable claw2 --dry-run  # preview benching an account
 multi-clawd chain     # audit your model routing — what actually serves each turn
 multi-clawd direct    # the direct anthropic/* route: status, or `direct sync` (v1.9, optional)
 multi-clawd doctor    # health check (add --probe for a live end-to-end turn)
@@ -386,7 +387,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.3.0/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.4.0/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.
 
@@ -546,6 +547,7 @@ error.
   "accounts": [
     { "id": "claw1", "label": "Main Claude", "native": true },
     { "id": "claw2", "label": "Second Max", "configDir": "~/.claw2",
+      // "disabled": true, // optional; default false: bench without removing the pool member
       // v0.3 preferred: resolve via your gateway's secret providers —
       // no plaintext token file on disk
       "oauthTokenRef": { "source": "exec", "provider": "onepassword",
@@ -558,6 +560,8 @@ error.
     "utilizationThreshold": 0.85,     // default hand-over; minute/hour and overage windows use this
     "weeklyUtilizationThreshold": 0.97, // optional: day/week/month quota windows at 97%
     "minDwellMs": 600000,             // v0.3: anti-flap dwell before returning home
+    "sessionAffinity": true,          // optional; default false: keep healthy CLI sessions on their serving account
+    "sessionAffinityTtlMs": 2592000000, // optional; default 30 days
     "degrade": {                      // v0.3.5: last step before provider drop
       "ladder": ["claude-opus-4-8"],  // whole pool exhausted → same account, lower tier
       "pins": [                       // contractual lanes never degrade
@@ -578,6 +582,25 @@ error.
 } }
 ```
 
+Set `accounts[].disabled: true` to bench a member while keeping it in
+`pool.accounts` and visible in `explain`, `doctor`, and `usage` as "disabled by
+operator". It is excluded from pool selection, in-turn retries, session
+affinity, and the managed direct Anthropic order. Transcript lookup still
+searches its session directory. To edit `~/.openclaw/openclaw.json` with a
+timestamped backup and without reformatting unrelated config, run
+`multi-clawd account disable <id>` or `multi-clawd account enable <id>`.
+Add `--dry-run` to preview without writing anything. If every pool member is
+disabled, pooled launches fail closed with an error naming
+`pool.accounts[].disabled`; they never fall back to a disabled member.
+On the direct `anthropic/*` route, a disabled member is left out of the order
+multi-clawd writes. If every direct member is disabled, multi-clawd stops
+managing that order and logs a warning naming `pool.accounts[].disabled`, but
+it cannot empty an order OpenClaw has already stored, so clear or edit that
+stored order yourself if the direct route must not use those profiles.
+Changes take effect when the plugin next reads its config, for example after
+a gateway reload. A turn already admitted or running continues on its selected
+account; the command does not interrupt it.
+
 `pool.strategy` defaults to `"ordered"`, which retains the configured account
 order. Set it to `"reset-aware"` to use healthy weekly quota before its
 `seven_day` window resets: among `ok` accounts with live seven-day reset data,
@@ -587,6 +610,20 @@ times keep pool order. The existing `minDwellMs` delay still holds an account
 that remains usable. Both CLI launches and the direct Anthropic route use the
 same preference. Other values are rejected by the plugin config schema.
 
+`pool.sessionAffinity: true` remembers the account that successfully served each
+Claude CLI session (`--session-id` or `--resume`) and prefers it on later turns
+while its health is `ok` or `no_data`. A near-limit or otherwise unhealthy
+account loses its pin; the successful replacement becomes the new pin. New
+sessions and launches without a session id keep normal pool selection. Pins
+live in `~/.openclaw/state/multi-clawd/pool-<id>.sessions.json`, expire after
+30 days by default (`sessionAffinityTtlMs`), and are capped at 1000 sessions.
+This applies to shimmed CLI launches; direct Anthropic and side-question
+launches keep their existing routing. The shim can switch to native,
+config-dir, and token-file accounts. On verified OpenClaw launches, the
+gateway also resolves a pinned secret-reference account at execution time.
+Legacy shim launches fall back to normal selection when a secret-reference
+pin needs a different account.
+
 How it decides, per launch (all data from each account's live
 `rate_limit_event` stream, captured by the shim):
 
@@ -878,7 +915,7 @@ callsite (the ones static scanners flag) and why each exists.
 | 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. |
+| Files written | Under `~/.openclaw/state/multi-clawd/` by default: `<id>.json`, `<id>.usage.json`, `pool-<id>.sticky.json`, `pool-<id>.sessions.json` (when affinity is enabled), `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. |
 
@@ -977,8 +1014,10 @@ Early but real — built for and dogfooded in production.
 - **v1.9** — one pool, both transports: accounts can also serve OpenClaw's
   direct `anthropic/*` route; the gateway keeps the `anthropic` auth order in
   pool-health order; `multi-clawd direct` / `direct sync` ✅
+- **Unreleased** — optional per-session affinity for shimmed Claude CLI
+  launches; health overrides the pin, with bounded expiring state ✅
 - **Next** — standalone localhost proxy (OpenAI-compatible) so Hermes and
-  custom runtimes can share the pool; true per-session affinity; local
+  custom runtimes can share the pool; local
   five-hour-window signal (turn counting); per-account lock for the shim
   persistence race
 

package/dist/direct-report.js

@@ -2,6 +2,8 @@ import { classifyAccountHealth, sevenDayReset } from "./health.js";
 import { DIRECT_PROVIDER, collectDirectMembers, } from "./direct-route.js";
 import { parseUnusableProfiles, planAgentOrder, readDirectRouteSnapshot, safeCliError, } from "./direct-sync.js";
 export function describeDirectSource(member) {
+    if (member.disabled)
+        return "disabled by operator";
     const s = member.source;
     switch (s.kind) {
         case "ref":
@@ -24,6 +26,7 @@ export async function gatherDirectStatus(params) {
         return {
             accountId: m.accountId,
             profileId: m.profileId,
+            disabled: m.disabled,
             verdict: classifyAccountHealth(state, params.healthOptions, params.nowMs).verdict,
             sevenDayResetsAt: params.strategy === "reset-aware"
                 ? sevenDayReset(state, params.healthOptions, params.nowMs)
@@ -44,7 +47,7 @@ export async function gatherDirectStatus(params) {
             errors.push(`models status ${safeCliError(status)}`);
     }
     let pendingOrder;
-    if (snapshot) {
+    if (snapshot && members.some((m) => !m.disabled)) {
         pendingOrder = planAgentOrder({
             members: verdicts,
             snapshot,
@@ -55,6 +58,9 @@ export async function gatherDirectStatus(params) {
             strategy: params.strategy,
         }).order;
     }
+    else if (members.length > 0 && members.every((m) => m.disabled)) {
+        errors.push("pool.accounts[].disabled: every direct member is disabled");
+    }
     const byProfile = new Map(unusable.map((u) => [u.profileId, u]));
     const order = snapshot?.storedOrder ?? (params.configOrder?.length ? [...params.configOrder] : snapshot ? [] : undefined);
     const orderSource = snapshot?.storedOrder

package/dist/direct-route.js

@@ -115,7 +115,7 @@ export function collectDirectMembers(accounts, poolOrder = []) {
             continue;
         }
         seenProfiles.add(profileId);
-        members.push({ accountId: account.id, profileId, source });
+        members.push({ accountId: account.id, profileId, source, disabled: account.disabled === true });
     }
     return { members, problems };
 }
@@ -128,9 +128,11 @@ const VERDICT_RANK = {
     credential_failed: 4,
 };
 export function planDirectOrder(params) {
-    const { members } = params;
-    if (members.length === 0)
+    const members = params.members.filter((m) => !m.disabled);
+    if (params.members.length === 0)
         return undefined;
+    if (members.length === 0)
+        throw new Error("pool.accounts[].disabled: every direct member is disabled");
     const decision = decideStickySelection({
         verdicts: members.map((m) => ({ id: m.accountId, verdict: m.verdict, sevenDayResetsAt: m.sevenDayResetsAt })),
         sticky: params.sticky,
@@ -147,7 +149,7 @@ export function planDirectOrder(params) {
             ? (a.m.sevenDayResetsAt ?? Infinity) - (b.m.sevenDayResetsAt ?? Infinity)
             : 0) || a.index - b.index)
         .map(({ m }) => m.profileId);
-    const managed = new Set(members.map((m) => m.profileId));
+    const managed = new Set(params.members.map((m) => m.profileId));
     const unmanaged = (params.currentOrder ?? []).filter((id, i, all) => typeof id === "string" && !managed.has(id) && all.indexOf(id) === i);
     const order = [first.profileId, ...rest, ...unmanaged];
     const current = params.currentOrder ?? [];
@@ -157,5 +159,5 @@ export function planDirectOrder(params) {
 export function directRoutePools(accounts, directRoute) {
     if (directRoute?.manageOrder === false)
         return false;
-    return collectDirectMembers(accounts).members.length >= 2;
+    return collectDirectMembers(accounts).members.filter((m) => !m.disabled).length >= 2;
 }

package/dist/direct-sync.js

@@ -130,6 +130,8 @@ export async function syncDirectProfiles(params) {
     const stored = new Set(listed.map((p) => p.id));
     const results = [];
     for (const member of params.members) {
+        if (member.disabled)
+            continue;
         const base = { accountId: member.accountId, profileId: member.profileId };
         const { source } = member;
         if (source.kind === "existing") {
@@ -212,14 +214,14 @@ function sameOrder(a, b) {
 }
 export function planAgentOrder(params) {
     const { snapshot } = params;
-    const present = params.members.filter((m) => snapshot.stored.has(m.profileId));
-    const missing = params.members.filter((m) => !snapshot.stored.has(m.profileId)).map((m) => m.profileId);
-    if (present.length === 0)
+    const present = params.members.filter((m) => !m.disabled && snapshot.stored.has(m.profileId));
+    const missing = params.members.filter((m) => !m.disabled && !snapshot.stored.has(m.profileId)).map((m) => m.profileId);
+    if (present.length === 0 && params.members.some((m) => !m.disabled))
         return { missing };
     const explicit = snapshot.storedOrder ?? (params.configOrder?.length ? [...params.configOrder] : null);
     const base = (explicit ?? [...snapshot.stored]).filter((id) => snapshot.stored.has(id));
     const plan = planDirectOrder({
-        members: present,
+        members: params.members.map((m) => ({ ...m, disabled: m.disabled || !snapshot.stored.has(m.profileId) })),
         currentOrder: base,
         sticky: params.sticky,
         nowMs: params.nowMs,
@@ -250,6 +252,7 @@ export function createDirectOrderController(deps) {
                     return {
                         accountId: m.accountId,
                         profileId: m.profileId,
+                        disabled: m.disabled,
                         verdict: classifyAccountHealth(state, deps.healthOptions, nowMs).verdict,
                         sevenDayResetsAt: deps.strategy === "reset-aware"
                             ? sevenDayReset(state, deps.healthOptions, nowMs)

package/dist/explain-core.js

@@ -81,7 +81,7 @@ export function renderExplanation(model) {
     const lines = [];
     lines.push("ACCOUNTS");
     for (const acc of model.accounts) {
-        lines.push(`  ${acc.id}${acc.label ? `  "${acc.label}"` : ""}`);
+        lines.push(`  ${acc.id}${acc.label ? `  "${acc.label}"` : ""}${acc.disabled ? " — disabled by operator" : ""}`);
         lines.push(`    → ${describeAccount(acc)}`);
     }
     lines.push("");
@@ -133,12 +133,12 @@ export function renderExplanation(model) {
         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(`  ${h.id}: ${model.accounts.find((a) => a.id === h.id)?.disabled ? "disabled by operator" : word}${h.detail ? ` — ${h.detail}` : ""}`);
             lines.push(`      usage: ${h.usage?.length ? renderUsageLine(h.usage, nowMs) : "no live telemetry"}`);
         }
         if (model.pool) {
             const strategy = poolStrategy(model.pool.strategy);
-            const verdicts = model.pool.accounts.map((id) => {
+            const verdicts = model.pool.accounts.filter((id) => !model.accounts.find((a) => a.id === id)?.disabled).map((id) => {
                 const h = model.health.find((row) => row.id === id);
                 return {
                     id,
@@ -167,7 +167,7 @@ export function renderExplanation(model) {
                 lines.push(`  strategy: ${strategy} — picked ${decision.account}: ${reason}`);
             }
             else {
-                lines.push(`  strategy: ${strategy}`);
+                lines.push(`  strategy: ${strategy} — pool.accounts[].disabled: every pool member is disabled`);
             }
             lines.push(model.stickyAccount
                 ? strategy === "reset-aware"

package/dist/index.js

@@ -9,6 +9,7 @@ import { resolveExecMode, permissionModeArgs } from "./exec-policy.js";
 import { resolveBaseModelIds } from "./catalog-source.js";
 import { allCredentialFailed, classifyAccountHealth, credentialFailureFor, lastAuthSuccessAt, overdueProbeAccount, sevenDayReset, } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
+import { DEFAULT_SESSION_AFFINITY_TTL_MS, launchSessionId, readSessionPin, SESSION_AFFINITY_ENV, } from "./session-affinity.js";
 import { mergeHealthStates, parseStoredState, recordCredentialFailure, } from "./shim-core.js";
 import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js";
 import { resolveSecretRefValues } from "openclaw/plugin-sdk/secret-ref-runtime";
@@ -436,6 +437,7 @@ export function resolveBackendLaunch(params) {
 const SHIM_ONLY_ENV = [
     RETRY_ROSTER_ENV,
     SESSION_DIRS_ENV,
+    SESSION_AFFINITY_ENV,
     "MULTI_CLAWD_MODEL_OVERRIDE",
     CLAUDE_BIN_ENV,
     CLAUDE_ARGV0_ENV,
@@ -572,6 +574,8 @@ const launchTransports = new WeakMap();
 export function buildRetryRoster(members, launchedId) {
     const roster = [];
     for (const member of members) {
+        if (member.disabled === true)
+            continue;
         if (member.id === launchedId)
             continue;
         const tokenFile = !member.native && member.oauthTokenFile ? expandHome(member.oauthTokenFile) : undefined;
@@ -785,9 +789,10 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
         return;
     const poolId = pool.id?.trim() || "clawd";
     const memberIds = (pool.accounts ?? []).filter((id) => registeredIds.has(id));
-    const members = memberIds
+    const configuredMembers = memberIds
         .map((id) => accounts.find((a) => a.id.trim() === id))
         .filter((a) => a !== undefined);
+    const members = configuredMembers.filter((a) => a.disabled !== true);
     const ladder = (pool.degrade?.ladder ?? []).filter((m) => {
         if (isModernClaudeModelId(m))
             return true;
@@ -795,7 +800,10 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
         return false;
     });
     const pins = pool.degrade?.pins ?? [];
-    if (members.length < 2 && !(members.length === 1 && ladder.length > 0)) {
+    if (members.length === 0 && memberIds.length > 0) {
+        logger.error(`[multi-clawd] pool "${poolId}": every member has pool.accounts[].disabled: true`);
+    }
+    if (members.length < 2 && !(members.length === 0 && memberIds.length > 0) && !(members.length === 1 && (ladder.length > 0 || memberIds.length > 1))) {
         logger.warn(`[multi-clawd] pool "${poolId}" has ${members.length} registered account(s) — need at least 2 (or 1 with a degrade ladder); pool not registered`);
         return;
     }
@@ -820,6 +828,8 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     const backend = buildBackend(poolAccount, execMode, deps?.launch);
     const { launch, transport } = launchTransports.get(backend);
     backend.prepareExecution = async (ctx) => {
+        if (members.length === 0)
+            throw new Error(`[multi-clawd] pool "${poolId}": every member has pool.accounts[].disabled: true`);
         const now = Date.now();
         const requestedModel = canonicalModelId(ctx.modelId) ?? ctx.modelId;
         const states = members.map((a) => ({ id: a.id, state: readHealthState(a.id) }));
@@ -964,7 +974,17 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             if (roster.length > 0)
                 env[RETRY_ROSTER_ENV] = JSON.stringify(roster);
         }
-        env[SESSION_DIRS_ENV] = JSON.stringify([...new Set(members.map(accountConfigDir))]);
+        env[SESSION_DIRS_ENV] = JSON.stringify([...new Set(configuredMembers.map(accountConfigDir))]);
+        if (pool.sessionAffinity) {
+            env[SESSION_AFFINITY_ENV] = JSON.stringify({
+                file: join(homedir(), ".openclaw", "state", "multi-clawd", `pool-${poolId}.sessions.json`),
+                ttlMs: typeof pool.sessionAffinityTtlMs === "number" &&
+                    Number.isFinite(pool.sessionAffinityTtlMs) && pool.sessionAffinityTtlMs > 0
+                    ? pool.sessionAffinityTtlMs : DEFAULT_SESSION_AFFINITY_TTL_MS,
+                verdicts: poolVerdicts.map((v) => ({ id: v.id, verdict: v.verdict })),
+                roster: buildRetryRoster(members, ""),
+            });
+        }
         if (ladder.length > 0) {
             const pinned = matchesPin(pins, {
                 agentDir: ctx.agentDir ?? "",
@@ -992,7 +1012,38 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
                 logger.info(`[multi-clawd] pool ${poolId}: pinned lane keeps ${ctx.modelId} despite exhausted pool (will fail over via the chain)`);
             }
         }
-        return preparedForLaunch(launch, ctx, env, transport);
+        const affinityTransport = pool.sessionAffinity && transport && launch.kind === "verified"
+            ? async function* (execution) {
+                const id = launchSessionId(execution.args);
+                const pin = id ? readSessionPin(join(homedir(), ".openclaw", "state", "multi-clawd", `pool-${poolId}.sessions.json`), id, Date.now(), typeof pool.sessionAffinityTtlMs === "number" && pool.sessionAffinityTtlMs > 0
+                    ? pool.sessionAffinityTtlMs : DEFAULT_SESSION_AFFINITY_TTL_MS) : undefined;
+                const member = members.find((m) => m.id === pin?.account && m.oauthTokenRef);
+                if (member && member.id !== execution.env.MULTI_CLAWD_ACCOUNT_ID &&
+                    poolVerdicts.some((v) => v.id === member.id &&
+                        (v.verdict === "ok" || v.verdict === "no_data"))) {
+                    let accountEnv;
+                    try {
+                        accountEnv = await buildAccountEnv(member, deps?.resolver);
+                    }
+                    catch {
+                    }
+                    if (accountEnv) {
+                        const selectedEnv = { ...execution.env };
+                        delete selectedEnv.CLAUDE_CODE_OAUTH_TOKEN;
+                        delete selectedEnv.CLAUDE_CONFIG_DIR;
+                        const pinnedRoster = buildRetryRoster(members, member.id);
+                        if (pinnedRoster.length > 0)
+                            selectedEnv[RETRY_ROSTER_ENV] = JSON.stringify(pinnedRoster);
+                        else
+                            delete selectedEnv[RETRY_ROSTER_ENV];
+                        yield* transport({ ...execution, env: { ...selectedEnv, ...accountEnv } });
+                        return;
+                    }
+                }
+                yield* transport(execution);
+            }
+            : transport;
+        return preparedForLaunch(launch, ctx, env, affinityTransport);
     };
     api.registerCliBackend(backend);
     api.registerProvider(buildCatalogProvider(poolAccount, members));
@@ -1031,6 +1082,11 @@ export function startDirectOrderSync(params) {
         stopDirectOrderSync();
         return { active: false, members: members.map((m) => m.accountId) };
     }
+    if (members.every((m) => m.disabled)) {
+        stopDirectOrderSync();
+        logger.warn("[multi-clawd] direct route: pool.accounts[].disabled: every direct member is disabled");
+        return { active: false, members: [] };
+    }
     const requested = params.directRoute?.agents?.length ? params.directRoute.agents : ["main"];
     const agents = requested.filter((a) => {
         if (isValidAgentId(a))
@@ -1050,7 +1106,7 @@ export function startDirectOrderSync(params) {
         rotateOnOverage: params.pool?.rotateOnOverage,
     };
     const signature = JSON.stringify({
-        members: members.map((m) => m.profileId),
+        members: members.map(({ accountId, profileId, source, disabled }) => ({ accountId, profileId, source, disabled })),
         agents,
         intervalMs,
         healthOptions,

package/dist/session-affinity.js

@@ -0,0 +1,108 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { resumeSessionId } from "./session-handover.js";
+export const SESSION_AFFINITY_ENV = "MULTI_CLAWD_SESSION_AFFINITY";
+export const DEFAULT_SESSION_AFFINITY_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const MAX_SESSION_PINS = 1000;
+export function launchSessionId(argv) {
+    const resumed = resumeSessionId(argv);
+    if (resumed)
+        return resumed;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const value = arg === "--session-id" ? argv[i + 1]
+            : arg.startsWith("--session-id=") ? arg.slice("--session-id=".length) : undefined;
+        if (value !== undefined)
+            return /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value) ? value : undefined;
+    }
+    return undefined;
+}
+export function eligibleSessionAccount(pin, currentAccount, verdicts, availableAccounts) {
+    if (!pin)
+        return undefined;
+    if (!verdicts.some((v) => v.id === pin.account &&
+        (v.verdict === "ok" || v.verdict === "no_data")))
+        return undefined;
+    return pin.account === currentAccount || availableAccounts.includes(pin.account)
+        ? pin.account : undefined;
+}
+const WRITE_CLOCK_SLACK_MS = 60_000;
+function readPins(file, now, ttlMs, futureSlackMs = 0) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const pins = {};
+        for (const [id, value] of Object.entries(parsed)) {
+            if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id))
+                continue;
+            if (!value || typeof value !== "object")
+                continue;
+            const pin = value;
+            if (typeof pin.account !== "string" || !pin.account ||
+                typeof pin.servedAt !== "number" || !Number.isFinite(pin.servedAt) ||
+                pin.servedAt > now + futureSlackMs || now - pin.servedAt >= ttlMs)
+                continue;
+            pins[id] = { account: pin.account, servedAt: pin.servedAt };
+        }
+        return pins;
+    }
+    catch {
+        return {};
+    }
+}
+export function readSessionPin(file, sessionId, now, ttlMs) {
+    return readPins(file, now, ttlMs)[sessionId];
+}
+export function recordSessionPin(file, sessionId, account, now, ttlMs) {
+    const lock = `${file}.lock`;
+    let locked = false;
+    let tmp;
+    try {
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        const deadline = Date.now() + 1000;
+        const wait = new Int32Array(new SharedArrayBuffer(4));
+        while (!locked) {
+            try {
+                closeSync(openSync(lock, "wx", 0o600));
+                locked = true;
+            }
+            catch {
+                try {
+                    if (Date.now() - statSync(lock).mtimeMs > 5000)
+                        rmSync(lock, { force: true });
+                }
+                catch { }
+                if (Date.now() >= deadline)
+                    return;
+                Atomics.wait(wait, 0, 0, 10);
+            }
+        }
+        const pins = readPins(file, now, ttlMs, WRITE_CLOCK_SLACK_MS);
+        pins[sessionId] = { account, servedAt: now };
+        const entries = Object.entries(pins);
+        const bounded = entries.length > MAX_SESSION_PINS
+            ? entries.sort((a, b) => b[1].servedAt - a[1].servedAt).slice(0, MAX_SESSION_PINS)
+            : entries;
+        tmp = `${file}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(Object.fromEntries(bounded)), { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch {
+    }
+    finally {
+        if (tmp) {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch { }
+        }
+        if (locked) {
+            try {
+                rmSync(lock, { force: true });
+            }
+            catch { }
+        }
+    }
+}

package/dist/shim.js

@@ -6,6 +6,7 @@ import { rewriteModelArg } from "./degrade.js";
 import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
 import { canonicalModelId } from "./models.js";
 import { buildRetryEnv, chooseLaunchableRetryAccount, materializeRetryAccount, parseRetryRoster, retryArming, RETRY_ROSTER_ENV, } from "./retry-plan.js";
+import { eligibleSessionAccount, launchSessionId, readSessionPin, recordSessionPin, SESSION_AFFINITY_ENV, } from "./session-affinity.js";
 import { CLAUDE_ARGV0_ENV, CLAUDE_BIN_ENV, parseClaudeBinOverride, resolveExecutable, } from "./claude-command.js";
 import { effectiveConfigDir, handoverForLaunch, handoverSnapshotTo, parseSessionDirs, SESSION_DIRS_ENV, snapshotResumeTranscript, } from "./session-handover.js";
 function resolveClaudeCommand() {
@@ -104,15 +105,53 @@ if (modelOverride) {
         process.stderr.write(`[multi-clawd shim] degrading model for this launch → ${modelOverride}\n`);
     }
 }
+const sessionId = launchSessionId(childArgs);
+let affinity;
+let launchEnv = process.env;
+try {
+    const raw = process.env[SESSION_AFFINITY_ENV];
+    if (raw && sessionId) {
+        const config = JSON.parse(raw);
+        if (typeof config.file === "string" && config.file && typeof config.ttlMs === "number" &&
+            Number.isFinite(config.ttlMs) && config.ttlMs > 0 && Array.isArray(config.verdicts)) {
+            affinity = {
+                file: config.file,
+                ttlMs: config.ttlMs,
+                verdicts: config.verdicts,
+                roster: parseRetryRoster(JSON.stringify(config.roster)),
+            };
+            const pin = readSessionPin(affinity.file, sessionId, Date.now(), affinity.ttlMs);
+            const eligible = eligibleSessionAccount(pin, accountId, affinity.verdicts, affinity.roster.map((r) => r.id));
+            if (eligible && eligible !== accountId) {
+                const member = affinity.roster.find((r) => r.id === eligible);
+                if (member) {
+                    const ready = materializeRetryAccount(member, (path) => readFileSync(path, "utf8"));
+                    if ("account" in ready) {
+                        launchEnv = buildRetryEnv(process.env, ready.account);
+                        accountId = ready.account.id;
+                        stateFile = ready.account.stateFile;
+                        state = { accountId, windows: {} };
+                    }
+                }
+            }
+        }
+    }
+}
+catch {
+    affinity = undefined;
+}
+delete launchEnv[SESSION_AFFINITY_ENV];
 {
-    const note = handoverForLaunch(childArgs, process.env);
+    const note = handoverForLaunch(childArgs, launchEnv);
     if (note)
         process.stderr.write(`[multi-clawd shim] ${note}\n`);
 }
-const retryRoster = parseRetryRoster(process.env[RETRY_ROSTER_ENV]);
+const retryRoster = affinity && launchEnv !== process.env
+    ? affinity.roster.filter((r) => r.id !== accountId)
+    : parseRetryRoster(process.env[RETRY_ROSTER_ENV]);
 delete process.env[RETRY_ROSTER_ENV];
-const resumeSnapshot = retryRoster.length > 0 && parseSessionDirs(process.env[SESSION_DIRS_ENV]).length > 0
-    ? snapshotResumeTranscript(childArgs, process.env)
+const resumeSnapshot = retryRoster.length > 0 && parseSessionDirs(launchEnv[SESSION_DIRS_ENV]).length > 0
+    ? snapshotResumeTranscript(childArgs, launchEnv)
     : undefined;
 const arming = retryArming(childArgs, retryRoster, { resumeReady: resumeSnapshot !== undefined });
 let retryArmed = arming.armed;
@@ -121,7 +160,7 @@ if (!retryArmed && retryRoster.length > 0 && arming.reason) {
 }
 let child = spawn(command, childArgs, {
     stdio: ["pipe", "pipe", "inherit"],
-    env: process.env,
+    env: launchEnv,
     ...(claudeArgv0 ? { argv0: claudeArgv0 } : {}),
 });
 const STDIN_REPLAY_CAP_BYTES = 8 * 1024 * 1024;
@@ -301,7 +340,7 @@ function attemptRetry() {
     sawSuccessResult = false;
     child = spawn(command, childArgs, {
         stdio: ["pipe", "pipe", "inherit"],
-        env: buildRetryEnv(process.env, target),
+        env: buildRetryEnv(launchEnv, target),
         ...(claudeArgv0 ? { argv0: claudeArgv0 } : {}),
     });
     attachChildHandlers();
@@ -419,6 +458,9 @@ function onChildClose(code, signal) {
     if ((code ?? 0) === 0) {
         clearRecordedAuthFailureOnSuccess();
         clearRecordedModelRejectionOnSuccess();
+        if (affinity && sessionId && sawSuccessResult && !sawAuthFailure && !sawModelLimit) {
+            recordSessionPin(affinity.file, sessionId, accountId, Date.now(), affinity.ttlMs);
+        }
     }
     process.exit(code ?? 0);
 }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.3.0",
+  "version": "2.4.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",
@@ -70,6 +70,15 @@
             "type": "number",
             "description": "After rotating away from home, stay on the rotated-to account at least this long before returning home (anti-flap hysteresis; health always overrides). Default 600000 (10min)."
           },
+          "sessionAffinity": {
+            "type": "boolean",
+            "description": "Pin a Claude CLI session to the account that last served it, while that account remains healthy. CLI launches only. Default false."
+          },
+          "sessionAffinityTtlMs": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "description": "Successful session pin lifetime in milliseconds. Default 2592000000 (30 days); only used when sessionAffinity is true."
+          },
           "usagePoll": {
             "type": "object",
             "additionalProperties": false,
@@ -152,6 +161,11 @@
               "type": "string",
               "description": "Human-friendly label shown in status/catalog."
             },
+            "disabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Exclude this account from pool selection, in-turn retries, session affinity and direct Anthropic order while keeping it configured and visible in status. Takes effect when the plugin next reads config."
+            },
             "native": {
               "type": "boolean",
               "description": "Use the machine's native Claude login (default config dir; OS keychain on macOS). Sets neither CLAUDE_CONFIG_DIR nor a token. Use this to include the main account in the rotation pool."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "2.3.0",
+  "version": "2.4.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. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",

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

@@ -36,6 +36,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
@@ -760,7 +761,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 +795,15 @@ 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") {
       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;
+      next = verdicts.length ? stickySelection.decideStickySelection({ verdicts, 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 +823,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 +839,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,6 +958,25 @@ 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();
     break;

package/scripts/doctor.mjs

@@ -354,6 +354,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 +495,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;