@drakon-systems/multi-clawd 2.4.0 → 2.5.1

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 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)
@@ -56,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
@@ -256,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
@@ -303,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
@@ -334,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
@@ -387,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.4.0/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.5.1/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.
 
@@ -412,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.)
@@ -556,7 +585,9 @@ 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
@@ -602,7 +633,14 @@ 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
+order. In every strategy, when no `ok` or `no_data` account is left but some
+are near their limit, the launch goes to the near-limit account with the most
+headroom: the lowest fresh utilization, taking the newer of the stream and
+usage-poll records for each window. Equal figures keep pool order, an account
+with a figure outranks one without, and two without keep pool order.
+Exhausted and credential-failed accounts are never chosen. `explain` says
+"all near limit, picked X at N%" and the direct Anthropic route orders its
+near-limit profiles the same way. 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,
 the soonest reset wins. Accounts without that data follow in pool order;
 near-limit or exhausted accounts never outrank a healthy one. Equal reset
@@ -610,6 +648,25 @@ 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
@@ -637,6 +694,7 @@ How it decides, per launch (all data from each account's live
 | `allowed_warning` and **no** number, on a short window | skipped (v1.7.2) — see below |
 | `allowed_warning` and no number, on the weekly window | still used — weekly warns from ~30% and would flap |
 | no data / stale data | used — never rotate on missing evidence |
+| every usable account near its limit | the near-limit account with the most headroom (lowest fresh utilization) serves; equal figures and accounts without a number keep pool order |
 | whole pool exhausted | home account anyway → real limit error → your chain drops provider |
 
 **Why the short-window rule exists (v1.7.2).** (v1.10's live usage poll now
@@ -892,15 +950,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
 
@@ -915,7 +974,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`, `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. |
+| 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. |
 

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,4 +1,5 @@
 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) {
@@ -21,16 +22,22 @@ 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);
+        const health = classifyAccountHealth(state, params.healthOptions, params.nowMs);
         return {
             accountId: m.accountId,
             profileId: m.profileId,
             disabled: m.disabled,
-            verdict: classifyAccountHealth(state, params.healthOptions, params.nowMs).verdict,
+            verdict: health.verdict,
+            utilization: health.utilization,
             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) : {};

package/dist/direct-route.js

@@ -1,5 +1,7 @@
 import { isSecretRefShape } from "./token-resolution.js";
+import { headroomBefore } from "./health.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 " +
@@ -134,7 +136,7 @@ export function planDirectOrder(params) {
     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, utilization: m.utilization, servedInWindow: m.servedInWindow, lastServedAt: m.lastServedAt })),
         sticky: params.sticky,
         nowMs: params.nowMs,
         minDwellMs: params.minDwellMs,
@@ -147,6 +149,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.m.verdict === "near_limit" && b.m.verdict === "near_limit"
+            ? (headroomBefore(a.m, b.m) ? -1 : headroomBefore(b.m, a.m) ? 1 : 0)
             : 0) || a.index - b.index)
         .map(({ m }) => m.profileId);
     const managed = new Set(params.members.map((m) => m.profileId));

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) {
@@ -247,16 +248,22 @@ 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);
+                    const health = classifyAccountHealth(state, deps.healthOptions, nowMs);
                     return {
                         accountId: m.accountId,
                         profileId: m.profileId,
                         disabled: m.disabled,
-                        verdict: classifyAccountHealth(state, deps.healthOptions, nowMs).verdict,
+                        verdict: health.verdict,
+                        utilization: health.utilization,
                         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) => {
@@ -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");
@@ -138,15 +148,19 @@ export function renderExplanation(model) {
         }
         if (model.pool) {
             const strategy = poolStrategy(model.pool.strategy);
-            const verdicts = model.pool.accounts.filter((id) => !model.accounts.find((a) => a.id === id)?.disabled).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,
                     verdict: h?.verdict ?? "no_data",
+                    utilization: h?.utilization,
                     sevenDayResetsAt: (h?.usage?.find((u) => u.window === "usage:seven_day" && u.resetsAt !== undefined && u.resetsAt > nowMs)
                         ?? 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 });
@@ -154,8 +168,12 @@ export function renderExplanation(model) {
                 let reason;
                 if (preferred && decision.account !== preferred)
                     reason = "sticky dwell keeps this usable account";
+                else if (picked?.verdict === "near_limit")
+                    reason = describeNearLimitPick(verdicts, picked);
                 else if (strategy === "ordered")
-                    reason = picked?.verdict === "near_limit" ? "first near-limit member in pool order" : "first healthy member in pool order";
+                    reason = "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,20 +182,43 @@ 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} — 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");
 }
+export function describeNearLimitPick(verdicts, picked) {
+    const nearLimit = verdicts.filter((v) => v.verdict === "near_limit");
+    const scope = nearLimit.length === verdicts.length ? "all near limit" : "no healthy member, the rest near limit";
+    const others = nearLimit.filter((v) => v.id !== picked.id);
+    if (picked.utilization === undefined) {
+        return `${scope}, picked ${picked.id} (no utilization number; pool order)`;
+    }
+    const pct = `${Math.round(picked.utilization * 100)}%`;
+    if (others.length === 0)
+        return `${scope}, picked ${picked.id} at ${pct}`;
+    const shown = others
+        .map((v) => `${v.id} ${v.utilization === undefined ? "no number" : `${Math.round(v.utilization * 100)}%`}`)
+        .join(", ");
+    return `${scope}, picked ${picked.id} at ${pct} — most headroom (${shown})`;
+}
 export function renderDirectSection(direct, nowMs) {
     const lines = [];
     lines.push("DIRECT ROUTE  anthropic/*  (gateway → Anthropic API with each account's setup-token)");

package/dist/health-journal.js

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { acquireShimLock } from "./shim-lock.js";
+import { mergeHealthStates, parseStoredState } from "./shim-core.js";
+function pendingFiles(file) {
+    const prefix = `${basename(file)}.pending-`;
+    try {
+        return readdirSync(dirname(file)).filter((name) => name.startsWith(prefix) && /^\d+-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(name.slice(prefix.length))).map((name) => join(dirname(file), name));
+    }
+    catch {
+        return [];
+    }
+}
+function snapshot(file, onError, strict = false) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            onError?.(undefined);
+            if (strict)
+                throw err;
+        }
+        return undefined;
+    }
+    const state = parseStoredState(raw);
+    if (!state) {
+        onError?.(raw);
+        if (strict)
+            throw new Error("not valid health-state JSON");
+    }
+    return state;
+}
+export function readHealthStateFile(file, opts = {}) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let state = snapshot(file, opts.onSnapshotError, opts.strictSnapshot);
+        const files = pendingFiles(file);
+        opts.afterList?.(files);
+        let missing = false;
+        for (const pending of files) {
+            let raw;
+            try {
+                raw = readFileSync(pending, "utf8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    missing = true;
+                continue;
+            }
+            const delta = parseStoredState(raw);
+            if (delta)
+                state = state ? mergeHealthStates(state, delta) : delta;
+        }
+        if (!missing || attempt === 2)
+            return state;
+    }
+    return undefined;
+}
+function publish(file, state) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+}
+export function persistHealthState(file, state, opts = {}) {
+    const release = acquireShimLock(file);
+    try {
+        if (!release) {
+            publish(`${file}.pending-${process.pid}-${randomUUID()}`, state);
+            return state;
+        }
+        let merged = snapshot(file, opts.onSnapshotError);
+        const files = pendingFiles(file);
+        opts.afterList?.(files);
+        const folded = [];
+        for (const pending of files) {
+            let raw;
+            try {
+                raw = readFileSync(pending, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const delta = parseStoredState(raw);
+            if (!delta) {
+                try {
+                    renameSync(pending, `${pending}.corrupt-${Date.now()}`);
+                }
+                catch { }
+                continue;
+            }
+            merged = merged ? mergeHealthStates(merged, delta) : delta;
+            folded.push(pending);
+        }
+        merged = merged ? mergeHealthStates(merged, state, Date.now()) : mergeHealthStates(state, state, Date.now());
+        publish(file, merged);
+        for (const pending of folded) {
+            try {
+                unlinkSync(pending);
+            }
+            catch { }
+        }
+        return merged;
+    }
+    catch (err) {
+        process.stderr.write(`[multi-clawd shim] state write failed: ${String(err)}\n`);
+        return state;
+    }
+    finally {
+        release?.();
+    }
+}