@drakon-systems/multi-clawd 2.3.0 → 2.5.0

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?.();
+    }
+}

package/dist/health.js

@@ -1,4 +1,5 @@
 import { modelWindowApplies, modelWindowKey } from "./shim-core.js";
+import { spreadBefore } from "./spread.js";
 export const DEFAULT_UTILIZATION_THRESHOLD = 0.85;
 const DEFAULT_STALE_AFTER_MS = 6 * 60 * 60 * 1000;
 export const MODEL_REJECTED_TTL_MS = 60 * 60 * 1000;
@@ -223,7 +224,7 @@ export function summarizeWindowUsage(state, options, nowMs) {
     return usage.sort((a, b) => (b.resetsAt ?? 0) - (a.resetsAt ?? 0));
 }
 export function poolStrategy(value) {
-    return value === "reset-aware" ? "reset-aware" : "ordered";
+    return value === "reset-aware" || value === "spread" ? value : "ordered";
 }
 export function sevenDayReset(state, options, nowMs) {
     const usage = summarizeWindowUsage(state, options, nowMs);
@@ -243,6 +244,17 @@ export function choosePoolAccount(pool, strategy = "ordered") {
         if (best?.sevenDayResetsAt !== undefined)
             return best.id;
     }
+    if (strategy === "spread") {
+        let best;
+        for (const member of pool) {
+            if (member.verdict !== "ok" && member.verdict !== "no_data")
+                continue;
+            if (!best || spreadBefore(member, best))
+                best = member;
+        }
+        if (best)
+            return best.id;
+    }
     const usable = pool.find((a) => a.verdict === "ok" || a.verdict === "no_data");
     if (usable)
         return usable.id;

package/dist/history.js

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { acquireShimLock } from "./shim-lock.js";
+export const HISTORY_FILE = "history.jsonl";
+export const HISTORY_MAX_BYTES = 64 * 1024;
+export const HISTORY_MAX_EVENTS = 500;
+export function historyFile(stateFile) {
+    return join(dirname(stateFile), HISTORY_FILE);
+}
+const safeAccount = (value) => typeof value === "string" &&
+    value.length > 0 && value.length <= 100 && !/[\x00-\x1f\x7f]/.test(value);
+const safeModel = (value) => typeof value === "string" &&
+    value.length > 0 && value.length <= 100 && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/.test(value);
+function valid(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const e = raw;
+    if (typeof e.at !== "string" || !Number.isFinite(Date.parse(e.at)) ||
+        !["served", "retry", "rotation"].includes(String(e.kind)) || !safeAccount(e.accountId) ||
+        (e.toAccountId !== undefined && !safeAccount(e.toAccountId)) ||
+        (e.reason !== undefined && !["model_limit", "auth_failure", "transient", "pool_selection"].includes(String(e.reason))))
+        return undefined;
+    return { at: e.at, kind: e.kind, accountId: e.accountId,
+        ...(e.toAccountId ? { toAccountId: e.toAccountId } : {}),
+        ...(safeModel(e.modelId) ? { modelId: e.modelId } : {}),
+        ...(e.reason ? { reason: e.reason } : {}) };
+}
+export function readHistory(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    return raw.split("\n").flatMap((line) => {
+        try {
+            const event = valid(JSON.parse(line));
+            return event ? [event] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function recordHistory(stateFile, event) {
+    if (!stateFile)
+        return;
+    let release;
+    let tmp;
+    try {
+        const checked = valid(event);
+        if (!checked)
+            return;
+        const file = historyFile(stateFile);
+        release = acquireShimLock(file);
+        if (!release)
+            return;
+        const events = [...readHistory(file), checked].slice(-HISTORY_MAX_EVENTS);
+        let lines = events.map((e) => JSON.stringify(e) + "\n");
+        let bytes = lines.reduce((sum, line) => sum + Buffer.byteLength(line), 0);
+        while (bytes > HISTORY_MAX_BYTES && lines.length)
+            bytes -= Buffer.byteLength(lines.shift());
+        mkdirSync(dirname(file), { recursive: true });
+        tmp = `${file}.tmp-${process.pid}-${randomUUID()}`;
+        writeFileSync(tmp, lines.join(""), { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch { }
+    finally {
+        if (tmp)
+            try {
+                unlinkSync(tmp);
+            }
+            catch { }
+        release?.();
+    }
+}
+export function parseHistorySince(value) {
+    const match = /^(\d+)([dh])$/.exec(value);
+    if (!match || Number(match[1]) < 1 || Number(match[1]) > 3650) {
+        throw new Error("--since must be a positive duration such as 7d or 24h");
+    }
+    return Number(match[1]) * (match[2] === "d" ? 86_400_000 : 3_600_000);
+}
+export function renderHistory(events, accountIds, since, nowMs = Date.now()) {
+    const cutoff = nowMs - parseHistorySince(since);
+    const recent = events.filter((e) => Date.parse(e.at) >= cutoff && Date.parse(e.at) <= nowMs);
+    const ids = [...new Set([...accountIds, ...recent.map((e) => e.accountId)])];
+    const lines = [`Account history (last ${since}):`];
+    if (!ids.length)
+        return [...lines, "  No accounts configured."].join("\n");
+    for (const id of ids) {
+        const own = recent.filter((e) => e.accountId === id);
+        const count = (kind) => own.filter((e) => e.kind === kind).length;
+        const last = own.filter((e) => e.kind === "served")
+            .reduce((latest, e) => !latest || Date.parse(e.at) > Date.parse(latest) ? e.at : latest, undefined);
+        const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
+        lines.push(`  ${id}: ${n(count("served"), "served launch", "served launches")}, ${n(count("retry"), "retry", "retries")}, ${n(count("rotation"), "rotation", "rotations")}; last served ${last ?? "never in this window"}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.js

@@ -7,8 +7,11 @@ import { MODEL_ALIASES, buildCatalogEntries, canonicalModelId, isModernClaudeMod
 import { decideDegradation, matchesPin } from "./degrade.js";
 import { resolveExecMode, permissionModeArgs } from "./exec-policy.js";
 import { resolveBaseModelIds } from "./catalog-source.js";
-import { allCredentialFailed, classifyAccountHealth, credentialFailureFor, lastAuthSuccessAt, overdueProbeAccount, sevenDayReset, } from "./health.js";
+import { allCredentialFailed, classifyAccountHealth, credentialFailureFor, lastAuthSuccessAt, overdueProbeAccount, poolStrategy, sevenDayReset, } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
+import { HISTORY_FILE, readHistory, recordHistory } from "./history.js";
+import { spreadStatsFromHistory, spreadWindowMs, withSpreadStats } from "./spread.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";
@@ -17,6 +20,7 @@ import { RETRY_ROSTER_ENV } from "./retry-plan.js";
 import { SESSION_DIRS_ENV } from "./session-handover.js";
 import { addAlert, alertKeysWithPrefix, clearAlert, pendingAlertText, } from "./alerts.js";
 import { healthStateFile, usageStateFile, clearAccountCredentialFailure } from "./credential-state.js";
+import { persistHealthState, readHealthStateFile } from "./health-journal.js";
 import { createUsagePollController, effectiveUsagePollInterval, effectiveUsageWarnThreshold, usageAlertPrefix, usagePoolAlertKey, } from "./usage-poll.js";
 export { healthStateFile, usageStateFile, clearAccountCredentialFailure };
 import { accountConfigDir, AccountCredentialError, buildAccountChildEnv, credentialFailureText, parseSetupTokenFile, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
@@ -187,22 +191,8 @@ const refProbeTrackers = new Map();
 const lastProbeStatus = new Map();
 function recordAccountCredentialFailure(accountId, reason, nowMs) {
     const file = healthStateFile(accountId);
-    let state;
-    try {
-        state = parseStoredState(readFileSync(file, "utf8")) ?? { accountId, windows: {} };
-    }
-    catch {
-        state = { accountId, windows: {} };
-    }
-    const next = mergeHealthStates(state, recordCredentialFailure(state, reason, nowMs), nowMs);
-    try {
-        mkdirSync(dirname(file), { recursive: true });
-        const tmp = `${file}.tmp-${process.pid}`;
-        writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
-        renameSync(tmp, file);
-    }
-    catch {
-    }
+    const state = readHealthStateFile(file) ?? { accountId, windows: {} };
+    persistHealthState(file, recordCredentialFailure(state, reason, nowMs));
 }
 export async function runLoginHealthProbe(accounts, logger, deps = {}) {
     const now = deps.nowMs ?? Date.now();
@@ -436,6 +426,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 +563,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;
@@ -736,7 +729,7 @@ export default definePluginEntry({
     },
 });
 function readHealthState(accountId) {
-    return mergeStoredHealth(readStateFileLenient(healthStateFile(accountId)), readStateFileLenient(usageStateFile(accountId)));
+    return mergeStoredHealth(readHealthStateFile(healthStateFile(accountId)), readStateFileLenient(usageStateFile(accountId)));
 }
 function readStateFileLenient(file) {
     try {
@@ -753,6 +746,9 @@ function mergeStoredHealth(shim, usage) {
         return shim;
     return mergeHealthStates(shim, usage);
 }
+function poolHistoryFile() {
+    return join(homedir(), ".openclaw", "state", "multi-clawd", HISTORY_FILE);
+}
 function readStickyEntry(file) {
     try {
         const parsed = JSON.parse(readFileSync(file, "utf8"));
@@ -785,9 +781,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 +792,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;
     }
@@ -816,10 +816,17 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
         defaultModel: pool.defaultModel,
     };
     const minDwellMs = pool.minDwellMs;
+    const strategy = poolStrategy(pool.strategy);
+    const affinityOn = pool.sessionAffinity === true || strategy === "spread";
+    if (strategy === "spread" && pool.sessionAffinity === false) {
+        logger.warn(`[multi-clawd] pool "${poolId}": strategy "spread" keeps each session on the account that first served it — sessionAffinity: false is ignored`);
+    }
     const stickyFile = join(homedir(), ".openclaw", "state", "multi-clawd", `pool-${poolId}.sticky.json`);
     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) }));
@@ -839,20 +846,23 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             throw new Error(`[multi-clawd] ${text}`);
         }
         const previousSticky = readStickyEntry(stickyFile);
-        const poolVerdicts = verdicts.map((v) => ({
+        const rawVerdicts = verdicts.map((v) => ({
             id: v.id,
             verdict: v.health.verdict,
             observedAt: v.health.observedAt,
-            sevenDayResetsAt: pool.strategy === "reset-aware"
+            sevenDayResetsAt: strategy === "reset-aware"
                 ? sevenDayReset(states.find((s) => s.id === v.id)?.state, options, now)
                 : undefined,
         }));
+        const poolVerdicts = strategy === "spread"
+            ? withSpreadStats(rawVerdicts, spreadStatsFromHistory(readHistory(poolHistoryFile()), now, spreadWindowMs(pool.spreadWindowMs)))
+            : rawVerdicts;
         const decision = decideStickySelection({
             verdicts: poolVerdicts,
             sticky: previousSticky,
             nowMs: now,
             minDwellMs,
-            strategy: pool.strategy,
+            strategy,
         });
         const chosen = members.find((a) => a.id === decision.account) ?? members[0];
         const previousAccount = previousSticky?.account ?? members[0].id;
@@ -868,7 +878,9 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             logger.info(`[multi-clawd] pool ${poolId}: no proven account can serve ${requestedModel} — ` +
                 `launching on ${decision.account} to re-test a login last rejected by the Claude CLI`);
         }
-        else if (decision.account !== previousAccount) {
+        else if (strategy !== "spread" && decision.account !== previousAccount) {
+            recordHistory(join(homedir(), ".openclaw", "state", "multi-clawd", `${previousAccount}.json`), { at: new Date(now).toISOString(), kind: "rotation", accountId: previousAccount,
+                toAccountId: decision.account, modelId: requestedModel, reason: "pool_selection" });
             const home = verdicts[0];
             const line = decision.account === members[0].id
                 ? `pool ${poolId}: returning home to ${decision.account}`
@@ -964,7 +976,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 (affinityOn) {
+            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 +1014,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 = affinityOn && 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 +1084,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,12 +1108,13 @@ 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,
         minDwellMs: params.pool?.minDwellMs,
         strategy: params.pool?.strategy,
+        spreadWindowMs: params.pool?.spreadWindowMs,
         command: params.directRoute?.openclawCommand,
     });
     if (directController?.signature === signature && directTimer) {
@@ -1071,6 +1130,8 @@ export function startDirectOrderSync(params) {
         healthOptions,
         minDwellMs: params.pool?.minDwellMs,
         strategy: params.pool?.strategy,
+        readHistory: () => readHistory(poolHistoryFile()),
+        spreadWindowMs: params.pool?.spreadWindowMs,
         configOrder: params.configOrder,
         readSticky: () => readStickyEntry(stickyFile),
         writeSticky: (entry) => writeStickyEntry(stickyFile, entry, logger),
@@ -1172,17 +1233,7 @@ export function startUsagePoll(params) {
                 }
             },
             readHealth: (id) => {
-                let shim;
-                try {
-                    shim = parseStoredState(readFileSync(healthStateFile(id), "utf8"));
-                    if (!shim)
-                        throw new Error("not valid health-state JSON");
-                }
-                catch (err) {
-                    if (err.code !== "ENOENT")
-                        throw err;
-                    shim = undefined;
-                }
+                const shim = readHealthStateFile(healthStateFile(id), { strictSnapshot: true });
                 let usage;
                 try {
                     usage = parseStoredState(readFileSync(usageStateFile(id), "utf8"));

package/dist/retry-plan.js

@@ -66,6 +66,8 @@ export function chooseRetryAccount(params) {
             return account;
         verdicts.push({ id: account.id, verdict: health.verdict, observedAt: health.observedAt });
     }
+    if (params.allowOverdueProbe === false)
+        return undefined;
     const probe = overdueProbeAccount(verdicts, params.nowMs);
     return probe ? params.roster.find((a) => a.id === probe) : undefined;
 }

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 { }
+        }
+    }
+}