@drakon-systems/multi-clawd 2.3.0 → 2.5.0

package/README.md

@@ -30,6 +30,8 @@ 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 explain --history --since 7d   # per-account launches, retries, rotations
+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)
@@ -55,6 +57,12 @@ install anything? Every command also runs as
 
 Then `multi-clawd explain` shows you exactly what you built.
 
+`multi-clawd explain --history` adds per-account served launches, in-turn retry
+hops, rotations, and the last served time for the past seven days. Use
+`--since 24h` or another positive `Nd`/`Nh` duration to change the window.
+The local history is size capped; it records account and model IDs and short
+reason codes, never prompts, credentials, transcripts, tokens, or costs.
+
 ## Hermes Agent integration
 
 multi-clawd can also import the configured Claude subscriptions into Hermes
@@ -255,6 +263,13 @@ claude-cli/claude-fable-5        # main login
   session is handed to the sibling as it stood before the refused attempt.
   One retry. Works for config-dir, native, and setup-token-file accounts; the
   shim is handed paths only and reads a token file at the moment it retries.
+  A **transient** provider error (529 overload, 5xx, or a throttle 429 that is
+  not a spent window) gets the same single hop to an idle sibling — but
+  records nothing against the account that met it, because it is not spent,
+  and is passed through unchanged when no idle sibling exists (never onto an
+  account the pool believes is spent). The Claude CLI retries these itself
+  first; the shim keeps the hop armed through those announced retry sleeps,
+  bounded (`MULTI_CLAWD_HOLD_RETRY_MAX_MS`, default 120s, hard cap 150s).
 - 📟 **Operator alerts (v0.3)** — dead logins (probed every 15 min without
   spending quota), pool rotations, whole-pool exhaustion, and watchdog
   restarts surface through your agent's next heartbeat (e.g. straight into
@@ -302,7 +317,7 @@ argument arrays, never through a shell string. Launch mode varies by platform.
 npm i -g @drakon-systems/multi-clawd && multi-clawd update
 ```
 
-`update` runs the registry install with the right flags, offers the gateway
+`update` installs from ClawHub first, offers the gateway
 restart, and finishes with a doctor health check.
 
 > ### ⚠️ Keeping up to date: there are two halves
@@ -333,39 +348,53 @@ restart, and finishes with a doctor health check.
 > version` shows both halves, and since v1.6.0 says plainly whether the pair
 > is a problem.
 >
-> ### ⚠️ `openclaw plugins update --all` cannot move this plugin
+> ### ⚠️ Pinned installs need `multi-clawd update`
 >
-> It will tell you the plugin is up to date when it is not. We install with
-> `--pin` (OpenClaw's own security audit raises a HIGH finding for unpinned
-> install specs, so pinning is the right side of that trade), and OpenClaw
+> For a versioned ClawHub install (or npm `--pin` fallback), `openclaw plugins
+> update --all` can tell you the plugin is up to date when it is not. OpenClaw
 > resolves registry metadata *for the pinned spec* — comparing 1.6.0 against
 > 1.6.0 and returning "up to date" while a newer version sits on npm. The
 > honest "pinned to X; registry default resolves to Y" message exists in
 > OpenClaw but is built inside its `--dry-run` branch, so a real update run
 > never prints it.
 >
-> **Use `multi-clawd update`.** Since v1.7.2 `doctor` also checks the registry
+> **Use `multi-clawd update` for versioned installs.** Since v1.7.2 `doctor` also checks the registry
 > itself (cached, and silent when offline), so a lagging plugin is reported
 > rather than left to a command that reassures you wrongly.
 
 Prefer the raw form?
 
 ```bash
-openclaw plugins install @drakon-systems/multi-clawd --pin
-openclaw gateway restart
+openclaw plugins install clawhub:@drakon-systems/multi-clawd
+# Only after a successful install, and with operator approval:
+# openclaw gateway restart
 ```
 
 Either way the gateway pulls the prebuilt package — no clone, no build step,
-nothing to keep in sync. `--pin` records the exact resolved version, so an
-upgrade is a deliberate act, never a surprise. `openclaw` itself is a *peer*
+nothing to keep in sync. ClawHub is the source OpenClaw trusts; npm installs show a source caution.
+For existing installs, prefer the guarded `multi-clawd update` command rather than a raw source retry.
+
+**Raw-install fallback boundary:** use npm only after positively identifying a
+ClawHub availability failure (for example, package/version not found or registry
+unreachable), or an older OpenClaw CLI explicitly rejecting the `clawhub:` spec
+as unsupported. An old CLI version alone is not evidence of that incompatibility.
+**Stop; do not retry through npm** for moderation, security, integrity, trust,
+signature or policy failures, unknown errors, cancellation or interruption.
+These stops take precedence even if availability diagnostics appeared first.
+If the cause is unclear, stop and investigate; do not switch sources or restart
+the gateway after a failed or interrupted install.
+
+Only after the availability/unsupported-spec check above, an unversioned fresh
+install may use `openclaw plugins install @drakon-systems/multi-clawd --pin`.
+For a versioned install, retain the same selected exact target: if ClawHub was
+`clawhub:@drakon-systems/multi-clawd@X.Y.Z`, the permitted npm retry is
+`openclaw plugins install @drakon-systems/multi-clawd@X.Y.Z --pin`.
+Replace `X.Y.Z` with that same exact version; never drop it, re-resolve latest,
+or substitute a different version during fallback.
+An unversioned ClawHub spec follows newer releases; add `@X.Y.Z` to keep a specific release.
+`openclaw` itself is a *peer*
 dependency (the host provides it), so the install stays lean.
 
-**From ClawHub (alternative registry):**
-
-```bash
-openclaw plugins install clawhub:@drakon-systems/multi-clawd
-```
-
 **From source (contributors, or ahead of a release):**
 
 ```bash
@@ -386,7 +415,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.5.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.
 
@@ -411,8 +440,9 @@ host-provided peer.
 npx @drakon-systems/multi-clawd update
 ```
 
-One command: checks the registry, installs the new version with the right
-flags, offers the gateway restart, and finishes with a doctor health check.
+One command: checks the registry, installs the chosen version from ClawHub (with npm
+fallback only when ClawHub is unavailable), offers the gateway restart, and finishes with a doctor health check.
+Security, integrity, and policy failures stop the update without trying npm.
 (`npm i -g @drakon-systems/multi-clawd` once, and it's just `multi-clawd
 update` — with `multi-clawd setup`, `multi-clawd explain` (your setup in
 plain English), and `multi-clawd doctor` alongside.)
@@ -546,6 +576,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",
@@ -554,10 +585,14 @@ error.
   "pool": {
     "id": "clawd",
     "accounts": ["claw1", "claw2"],   // preference order; first = home for ordered strategy
-    "strategy": "ordered",            // optional: "reset-aware" drains healthy weekly quota that resets soonest
+    "strategy": "ordered",            // optional: "reset-aware" drains healthy weekly quota that resets soonest;
+                                      //           "spread" starts each new session on the least-served healthy account
+    // "spreadWindowMs": 3600000,     // optional, spread only: how far back served launches count (default 1h)
     "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 +613,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 +641,39 @@ 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.
 
+Set `pool.strategy` to `"spread"` when several agent lanes start sessions at
+once and you want them on different accounts instead of queueing behind one
+account's concurrency ceiling. Each **new** session starts on the healthy
+(`ok` or `no_data`) account that served the fewest launches in the last
+`spreadWindowMs` (default one hour; clamped between one minute and seven
+days), counted from the served-launch journal `explain --history` reads. On a
+tie the account served least recently wins, then pool order, so equally idle
+accounts are used in turn. Near-limit, exhausted and credential-failed
+accounts are never chosen; when no healthy account is left the pool answers
+exactly as `ordered` does. Spread keeps every session on the account that
+first served it: it switches `sessionAffinity` on for the pool (an explicit
+`sessionAffinity: false` is overridden with a warning, because without it a
+conversation would move on every turn). A pinned session moves only when its
+account stops being healthy, exactly as under `sessionAffinity`. Launches
+without a session id take the spread pick. There is no home account, no
+dwell and no rotation alert under spread; `explain`, `usage` and `doctor`
+show the strategy, the next placement and the served counts behind it. The
+direct Anthropic route orders its profiles by the same counts.
+
+`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):
 
@@ -855,15 +942,16 @@ event, and no plugin API can force a rebuild. See `DESIGN.md`.
   after the assessment or 24 hours after that turn, whichever comes first. A
   CLI login failure recorded on a real turn removes it at once.
 
-- **Shim window persistence is sequential-safe, not concurrent-writer-safe.**
-  `persistState()` in `src/shim.ts` does a read-merge-write on every save so a
-  turn that only reports one window type (say `five_hour`) doesn't clobber
-  the last-seen `seven_day` data — but the read, merge, and rename aren't
-  atomic together. Two truly concurrent shim processes for the *same*
-  account can still race each other and drop an event on last-rename-wins.
-  In practice this needs two in-flight turns on one account at once, which
-  is rare, but it's a real gap. A per-account lock/retry protocol is tracked
-  as a v0.3.x follow-up.
+- **Shim state and retry coordination is best effort under lock contention.**
+  Concurrent shims for one account use a short advisory lock around each
+  state merge and rename. A second short lock covers recording a refusal and
+  reading sibling health for the in-turn retry. Later decisions can therefore
+  see rejections already recorded by another shim. If a lock stays busy beyond
+  150 ms or filesystem locking fails, the shim proceeds without it so the
+  turn still runs; concurrent writes in that fallback can lose an observation.
+  A replacement between the lock's final ownership check and removal can
+  still remove another live holder's lock because those steps are not atomic.
+  The guard does not pace requests sent to a newly chosen sibling.
 
 ## Security
 
@@ -878,7 +966,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`, `history.jsonl` (bounded account activity), `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 +1065,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/SECURITY.md

@@ -37,6 +37,9 @@ credit you (unless you'd rather we didn't), and note it in the CHANGELOG.
 - **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.
+- **`history.jsonl` is a bounded `0600` account activity file** in the same
+  state directory. It contains timestamps, account/model IDs and short reason
+  codes, with no prompt, transcript, token, cost, credential, or environment values.
 
 ## Permissions
 

package/dist/credential-state.js

@@ -1,33 +1,17 @@
-import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { parseStoredState, mergeHealthStates, clearCredentialFailure, } from "./shim-core.js";
+import { join } from "node:path";
+import { persistHealthState, readHealthStateFile } from "./health-journal.js";
+import { clearCredentialFailure, } from "./shim-core.js";
 export function healthStateFile(accountId) {
     return join(homedir(), ".openclaw", "state", "multi-clawd", `${accountId}.json`);
 }
 export function usageStateFile(accountId) {
     return join(homedir(), ".openclaw", "state", "multi-clawd", `${accountId}.usage.json`);
 }
-export function clearAccountCredentialFailure(accountId) {
-    const file = healthStateFile(accountId);
-    let state;
-    try {
-        state = parseStoredState(readFileSync(file, "utf8")) ?? { accountId, windows: {} };
-    }
-    catch {
+export function clearAccountCredentialFailure(accountId, file = healthStateFile(accountId)) {
+    const state = readHealthStateFile(file);
+    if (state?.credential?.status !== "failed")
         return false;
-    }
-    if (state.credential?.status !== "failed")
-        return false;
-    const cleared = mergeHealthStates(state, clearCredentialFailure(state, Date.now()), Date.now());
-    try {
-        mkdirSync(dirname(file), { recursive: true });
-        const tmp = `${file}.tmp-${process.pid}`;
-        writeFileSync(tmp, JSON.stringify(cleared, null, 2), { mode: 0o600 });
-        renameSync(tmp, file);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    persistHealthState(file, clearCredentialFailure(state, Date.now()));
+    return readHealthStateFile(file)?.credential?.status === "ok";
 }

package/dist/direct-report.js

@@ -1,7 +1,10 @@
 import { classifyAccountHealth, sevenDayReset } from "./health.js";
+import { spreadStatsFor, spreadStatsFromHistory, spreadWindowMs } from "./spread.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":
@@ -19,15 +22,20 @@ export async function gatherDirectStatus(params) {
     if (members.length === 0 && problems.length === 0)
         return undefined;
     const errors = [];
+    const spread = params.strategy === "spread"
+        ? spreadStatsFromHistory(params.readHistory?.() ?? [], params.nowMs, spreadWindowMs(params.spreadWindowMs))
+        : undefined;
     const verdicts = members.map((m) => {
         const state = params.readHealth(m.accountId);
         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)
                 : undefined,
+            ...(spread ? spreadStatsFor(spread, m.accountId) : {}),
         };
     });
     const read = members.length > 0 ? await readDirectRouteSnapshot(params.runner, params.agentId) : {};
@@ -44,7 +52,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 +63,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

@@ -1,5 +1,6 @@
 import { isSecretRefShape } from "./token-resolution.js";
 import { decideStickySelection } from "./sticky.js";
+import { spreadBefore } from "./spread.js";
 export const DIRECT_PROVIDER = "anthropic";
 export const DIRECT_PROFILE_PREFIX = `${DIRECT_PROVIDER}:`;
 export const DIRECT_SETUP_TOKEN_GUIDANCE = "a native or config-dir Claude login is a rotating single-use OAuth grant — copying it into " +
@@ -115,7 +116,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,11 +129,13 @@ 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 })),
+        verdicts: members.map((m) => ({ id: m.accountId, verdict: m.verdict, sevenDayResetsAt: m.sevenDayResetsAt, servedInWindow: m.servedInWindow, lastServedAt: m.lastServedAt })),
         sticky: params.sticky,
         nowMs: params.nowMs,
         minDwellMs: params.minDwellMs,
@@ -145,9 +148,12 @@ export function planDirectOrder(params) {
         .sort((a, b) => VERDICT_RANK[a.m.verdict] - VERDICT_RANK[b.m.verdict] ||
         (params.strategy === "reset-aware" && a.m.verdict === "ok"
             ? (a.m.sevenDayResetsAt ?? Infinity) - (b.m.sevenDayResetsAt ?? Infinity)
+            : 0) ||
+        (params.strategy === "spread" && VERDICT_RANK[a.m.verdict] === 0
+            ? (spreadBefore(a.m, b.m) ? -1 : spreadBefore(b.m, a.m) ? 1 : 0)
             : 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 +163,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

@@ -1,4 +1,5 @@
 import { classifyAccountHealth, sevenDayReset } from "./health.js";
+import { spreadStatsFor, spreadStatsFromHistory, spreadWindowMs } from "./spread.js";
 import { DIRECT_PROVIDER, planDirectOrder } from "./direct-route.js";
 import { parseClaudeSetupToken } from "./hermes-core.js";
 export function safeCliError(result) {
@@ -130,6 +131,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 +215,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,
@@ -245,15 +248,20 @@ export function createDirectOrderController(deps) {
                 return { managedOrder: [], agents: [] };
             running = true;
             try {
+                const spread = deps.strategy === "spread"
+                    ? spreadStatsFromHistory(deps.readHistory?.() ?? [], nowMs, spreadWindowMs(deps.spreadWindowMs))
+                    : undefined;
                 const verdicts = deps.members.map((m) => {
                     const state = deps.readHealth(m.accountId);
                     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)
                             : undefined,
+                        ...(spread ? spreadStatsFor(spread, m.accountId) : {}),
                     };
                 });
                 const sticky = deps.readSticky();

package/dist/explain-core.js

@@ -1,5 +1,6 @@
 import { DEFAULT_UTILIZATION_THRESHOLD, choosePoolAccount, poolStrategy } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
+import { describeSpreadPick, describeWindow, spreadStatsFromHistory, spreadWindowMs, withSpreadStats } from "./spread.js";
 const WINDOW_LABELS = {
     five_hour: "5-hour",
     seven_day: "weekly",
@@ -16,6 +17,9 @@ export function relativeUntil(ms, nowMs) {
         return `~${hours}h`;
     return `~${Math.round(hours / 24)}d`;
 }
+export function relativeSince(ms, nowMs) {
+    return relativeUntil(nowMs + Math.max(0, nowMs - ms), nowMs);
+}
 export function renderUsageLine(usage, nowMs) {
     return usage
         .map((u) => {
@@ -81,7 +85,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("");
@@ -93,6 +97,12 @@ export function renderExplanation(model) {
         if (poolStrategy(model.pool.strategy) === "reset-aware") {
             lines.push("  Healthy accounts with a live seven-day reset are preferred by soonest reset.");
         }
+        else if (poolStrategy(model.pool.strategy) === "spread") {
+            lines.push(`  Each new session starts on the healthy account with the fewest served launches in the last ${describeWindow(spreadWindowMs(model.pool.spreadWindowMs))};`);
+            lines.push("  a session then stays on its account while that account is healthy (session affinity is on).");
+            if (model.pool.sessionAffinity === false)
+                lines.push("  sessionAffinity: false is ignored under spread — without it a conversation would move every turn.");
+        }
         else {
             lines.push("  Every Claude launch runs on the first account below its threshold;");
             lines.push("  the home account reclaims work");
@@ -133,12 +143,14 @@ 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 windowMs = spreadWindowMs(model.pool.spreadWindowMs);
+            const spread = strategy === "spread" ? spreadStatsFromHistory(model.history ?? [], nowMs, windowMs) : undefined;
+            const rawVerdicts = 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,
@@ -147,6 +159,7 @@ export function renderExplanation(model) {
                         ?? h?.usage?.find((u) => u.window === "seven_day" && u.resetsAt !== undefined && u.resetsAt > nowMs))?.resetsAt,
                 };
             });
+            const verdicts = spread ? withSpreadStats(rawVerdicts, spread) : rawVerdicts;
             if (verdicts.length) {
                 const preferred = choosePoolAccount(verdicts, strategy);
                 const decision = decideStickySelection({ verdicts, sticky: model.stickyEntry, nowMs, minDwellMs: model.pool.minDwellMs, strategy });
@@ -156,6 +169,8 @@ export function renderExplanation(model) {
                     reason = "sticky dwell keeps this usable account";
                 else if (strategy === "ordered")
                     reason = picked?.verdict === "near_limit" ? "first near-limit member in pool order" : "first healthy member in pool order";
+                else if (strategy === "spread")
+                    reason = picked && (picked.verdict === "ok" || picked.verdict === "no_data") ? describeSpreadPick(picked, windowMs) : "no healthy member; using the existing fallback";
                 else if (picked?.verdict === "ok" && picked.sevenDayResetsAt !== undefined)
                     reason = `seven-day window resets soonest (in ${relativeUntil(picked.sevenDayResetsAt, nowMs)})`;
                 else if (picked?.verdict === "ok")
@@ -164,16 +179,24 @@ export function renderExplanation(model) {
                     reason = "first member without live health data";
                 else
                     reason = "no healthy member; using the existing fallback";
-                lines.push(`  strategy: ${strategy} — picked ${decision.account}: ${reason}`);
+                lines.push(`  strategy: ${strategy} — ${strategy === "spread" ? "next new session on" : "picked"} ${decision.account}: ${reason}`);
+                if (spread) {
+                    for (const v of verdicts) {
+                        lines.push(`      ${v.id}: ${v.servedInWindow ?? 0} served in the last ${describeWindow(windowMs)}${v.lastServedAt !== undefined ? `, last ${relativeSince(v.lastServedAt, nowMs)} ago` : ""}`);
+                    }
+                }
             }
             else {
-                lines.push(`  strategy: ${strategy}`);
+                lines.push(`  strategy: ${strategy} — pool.accounts[].disabled: every pool member is disabled`);
             }
-            lines.push(model.stickyAccount
-                ? strategy === "reset-aware"
-                    ? `  pool is on ${model.stickyAccount} (dwell applies while it remains usable)`
-                    : `  pool is rotated onto ${model.stickyAccount} (returns home when the home window resets)`
-                : `  pool is on its home account (no rotation active)`);
+            if (strategy === "spread")
+                lines.push("  pool has no home account under spread; existing sessions keep the account that served them");
+            else
+                lines.push(model.stickyAccount
+                    ? strategy === "reset-aware"
+                        ? `  pool is on ${model.stickyAccount} (dwell applies while it remains usable)`
+                        : `  pool is rotated onto ${model.stickyAccount} (returns home when the home window resets)`
+                    : `  pool is on its home account (no rotation active)`);
         }
     }
     return lines.join("\n");