@drakon-systems/multi-clawd 2.0.0 → 2.1.1

package/README.md

@@ -385,7 +385,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.0.0/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.1.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.
 
@@ -397,7 +397,7 @@ therefore executes — is fixed at a version you chose, not whatever `master`
 happens to say today. Swap the tag if you want a different release, but
 prefer a tag over a branch.
 
-**Requirements:** OpenClaw ≥ 2026.6, the `claude` CLI on `PATH`, and a
+**Requirements:** OpenClaw ≥ 2026.8.1, the `claude` CLI on `PATH`, and a
 second Claude subscription you own. The current plugin SDK contract and runtime
 registration path are tested against OpenClaw **2026.8.1**. The standalone
 `multi-clawd` CLI and Hermes commands do not require the optional OpenClaw peer
@@ -817,6 +817,18 @@ event, and no plugin API can force a rebuild. See `DESIGN.md`.
 
 ## Known limitations
 
+- **Control UI shows the pool as unavailable on OpenClaw 2026.10 (multi-clawd
+  ≤ 2.1.0).** OpenClaw 2026.10 computes model availability per provider, and
+  a plugin provider backed by a Claude *login* (a `native` or `configDir`
+  account) had no credential to show it — so **Settings → Models** greyed out
+  every `clawd/*` and `claw<N>/*` row with "missing auth" and showed a
+  different model than the configured primary, even though agent turns worked.
+  `openclaw gateway call models.list --json` shows the same rows as
+  `available: false, unavailableReason: "missing-auth"`. Fixed in **2.1.1**:
+  a usable login now reports as available, a dead one still reports
+  "missing-auth", and the direct API transport keeps refusing CLI-login
+  accounts as before. Update with `multi-clawd update`.
+
 - **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
@@ -868,6 +880,28 @@ Housekeeping:
   showing only a trailing-newline mismatch is a false alarm.
 - Use only accounts you own, within your provider's terms of service.
 
+### Security notes: verified launch (OpenClaw ≥ 2026.8.1)
+
+- **Same verification bar as the built-in backend, no stronger.** Each
+  backend's command is the `claude` executable found on the gateway's
+  `PATH`. It declares exactly the runtime artifact OpenClaw's built-in
+  `claude-cli` backend declares (`@anthropic-ai/claude-code`, native
+  executable names `claude` / `claude.exe`). For a native install, OpenClaw
+  verifies that executable by its basename, the same check it applies to its
+  own `claude-cli`. multi-clawd adds no package or binary of its own to that
+  authority and never lists `node` as a native executable.
+- **The shim runs only the verified binary.** Agent turns go through the
+  shim, which is given the realpath checked when the turn starts and runs
+  that file under the registered command name. A different command, a
+  different `argv0`, or an interpreter prefix is refused rather than
+  wrapped.
+- **`MULTI_CLAWD_CLAUDE_BIN` is operator-trusted.** When it is set in the
+  gateway's environment, the plugin uses it in place of the `PATH` lookup.
+  Whoever can set the gateway's environment already controls which binary
+  runs, so the variable widens nothing. Only point it at an executable you
+  trust. If it is set but not executable, the launch fails; nothing falls
+  back to another `claude`.
+
 ## Status & roadmap
 
 Early but real — built for and dogfooded in production.

package/dist/claude-command.js

@@ -0,0 +1,69 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+export const CLAUDE_BIN_ENV = "MULTI_CLAWD_CLAUDE_BIN";
+export const CLAUDE_ARGV0_ENV = "MULTI_CLAWD_CLAUDE_ARGV0";
+export function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findOnPath(name, pathValue) {
+    for (const dir of (pathValue ?? "").split(delimiter)) {
+        if (!dir || !isAbsolute(dir))
+            continue;
+        const candidate = resolve(join(dir, name));
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+export function parseClaudeBinOverride(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) &&
+            parsed.length > 0 &&
+            parsed.every((p) => typeof p === "string" && p.length > 0)) {
+            const [command, ...prependArgs] = parsed;
+            return { kind: "argv", command, prependArgs };
+        }
+    }
+    catch {
+    }
+    return { kind: "path", value: raw };
+}
+export function resolveExecutable(command, pathValue) {
+    if (!command.includes("/") && !command.includes("\\"))
+        return findOnPath(command, pathValue);
+    if (!isAbsolute(command))
+        return undefined;
+    const absolute = resolve(command);
+    return isExecutableFile(absolute) ? absolute : undefined;
+}
+export function resolveClaudeExecutable(env, platform = process.platform) {
+    if (platform === "win32") {
+        return { ok: false, reason: "verified launch is not implemented on Windows" };
+    }
+    const override = parseClaudeBinOverride(env[CLAUDE_BIN_ENV]);
+    if (override) {
+        if (override.kind === "argv" && override.prependArgs.length > 0) {
+            return { ok: false, reason: `${CLAUDE_BIN_ENV} is an interpreter argv, not one executable` };
+        }
+        const raw = override.kind === "argv" ? override.command : override.value;
+        const command = resolveExecutable(raw, env.PATH);
+        return command
+            ? { ok: true, command, source: "override" }
+            : { ok: false, reason: `${CLAUDE_BIN_ENV}=${raw} is not an executable file` };
+    }
+    const command = findOnPath("claude", env.PATH);
+    return command
+        ? { ok: true, command, source: "path" }
+        : { ok: false, reason: "no executable `claude` on the gateway's PATH" };
+}

package/dist/credential-store.js

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { join, resolve } from "node:path";
@@ -183,6 +183,32 @@ export function expandHomeDir(p) {
 }
 const SECURITY_TIMEOUT_MS = 10_000;
 const SECURITY_ITEM_NOT_FOUND = 44;
+function defaultExecFileAsync(file, args, options) {
+    return new Promise((resolvePromise, reject) => {
+        execFile(file, args, options, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolvePromise(String(stdout));
+        });
+    });
+}
+export async function readKeychainItemAsync(service, account, deps = {}) {
+    const exec = deps.exec ?? defaultExecFileAsync;
+    try {
+        const data = await exec("security", ["find-generic-password", "-s", service, "-a", account, "-w"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: SECURITY_TIMEOUT_MS,
+        });
+        return { status: "found", data: data.replace(/\n$/, "") };
+    }
+    catch (err) {
+        const status = err?.status ??
+            err?.code;
+        return status === SECURITY_ITEM_NOT_FOUND ? { status: "absent" } : { status: "unreadable" };
+    }
+}
 export function createSystemCredentialIo(deps = {}) {
     const exec = deps.exec ?? ((file, args, options) => execFileSync(file, args, options));
     return {

package/dist/index.js

@@ -7,7 +7,7 @@ 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, lastAuthSuccessAt, overdueProbeAccount, } from "./health.js";
+import { allCredentialFailed, classifyAccountHealth, credentialFailureFor, lastAuthSuccessAt, overdueProbeAccount, } from "./health.js";
 import { decideStickySelection } from "./sticky.js";
 import { mergeHealthStates, parseStoredState, recordCredentialFailure, } from "./shim-core.js";
 import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js";
@@ -22,11 +22,14 @@ export { healthStateFile, usageStateFile, clearAccountCredentialFailure };
 import { accountConfigDir, AccountCredentialError, buildAccountChildEnv, credentialFailureText, parseSetupTokenFile, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
 import { diffCatalogModels, formatNewModelNotice, } from "./model-currency.js";
 import { assessAccountCredential, createRefProbeTracker, } from "./login-health.js";
-import { createSystemCredentialIo } from "./credential-store.js";
+import { createSystemCredentialIo, readKeychainItemAsync } from "./credential-store.js";
+import { createLoginAuthCache, loginAuthEligible, poolRuntimeAuth, refuseRuntimeAuthMarker, } from "./runtime-auth.js";
 import { collectDirectMembers } from "./direct-route.js";
 import { createDirectOrderController, isValidAgentId } from "./direct-sync.js";
 import { createOpenclawRunner } from "./openclaw-runner.js";
 import { materialiseRuntime } from "./runtime-home.js";
+import { CLAUDE_ARGV0_ENV, CLAUDE_BIN_ENV, resolveClaudeExecutable } from "./claude-command.js";
+import { createShimExecute } from "./shim-transport.js";
 const CLI_FRESH_WATCHDOG_DEFAULTS = {
     noOutputTimeoutRatio: 0.8,
     minMs: 180_000,
@@ -157,6 +160,29 @@ function ingestAlertSpool() {
 const LOGIN_PROBE_INTERVAL_MS = 15 * 60 * 1000;
 const LOGIN_PROBE_INITIAL_DELAY_MS = 45 * 1000;
 let realCredentialIo;
+let loginAuthCache;
+let loginAuthWarm = Promise.resolve();
+function loginAuth() {
+    return (loginAuthCache ??= createLoginAuthCache({
+        io: (realCredentialIo ??= createSystemCredentialIo()),
+        readKeychainItemAsync: (service, account) => readKeychainItemAsync(service, account),
+        health: (accountId) => {
+            const state = readHealthState(accountId);
+            return {
+                lastSuccessAt: lastAuthSuccessAt(state),
+                failed: credentialFailureFor(state, Date.now()) !== undefined,
+            };
+        },
+    }));
+}
+export function warmLoginAuth(accounts) {
+    const cache = loginAuth();
+    loginAuthWarm = Promise.all(accounts.filter(loginAuthEligible).map((account) => cache.refresh(account))).then(() => undefined);
+    return loginAuthWarm;
+}
+export function loginAuthWarmed() {
+    return loginAuthWarm;
+}
 const refProbeTrackers = new Map();
 const lastProbeStatus = new Map();
 function recordAccountCredentialFailure(accountId, reason, nowMs) {
@@ -206,6 +232,8 @@ export async function runLoginHealthProbe(accounts, logger, deps = {}) {
                 proof: { lastSuccessAt: lastAuthSuccessAt(readHealth(account.id)) },
                 nowMs: now,
             });
+            if (!deps.io)
+                loginAuth().record(account.id, check, now);
             status = check.status;
             reason = check.status === "ok" ? check.detail : check.reason;
         }
@@ -318,6 +346,14 @@ function peekToken(account) {
         return undefined;
     throw new Error(`[multi-clawd] account "${account.id}" needs oauthTokenFile, oauthTokenRef, or configDir`);
 }
+function resolveAccountRuntimeAuth(account) {
+    const token = peekToken(account);
+    if (token)
+        return { apiKey: token, source: `multi-clawd ${account.id} token`, mode: "token" };
+    if (account.oauthTokenFile || isSecretRefShape(account.oauthTokenRef))
+        return undefined;
+    return loginAuth().peek(account, account.id);
+}
 async function resolveTokenAsync(account, resolver) {
     if (isSecretRefShape(account.oauthTokenRef) && !account.native && !account.oauthTokenFile) {
         return (resolver ?? activeTokenResolver)?.resolve(account.oauthTokenRef);
@@ -359,6 +395,63 @@ if (!SHIM_RUNTIME.stable) {
         `using the load path, which dies if OpenClaw prunes its plugin capture (issue #31)`);
 }
 const SHIM_PATH = SHIM_RUNTIME.shimPath;
+export const CLAUDE_RUNTIME_ARTIFACT = Object.freeze({
+    kind: "bundled-package-tree",
+    packageName: "@anthropic-ai/claude-code",
+    entrypoint: "command",
+    nativeExecutableNames: Object.freeze(["claude", "claude.exe"]),
+});
+export function hostRunsExecuteTransports(runtime) {
+    try {
+        const rt = runtime;
+        return (typeof rt?.agent?.runCommandFromIngress === "function" &&
+            typeof rt?.hooks?.dispatchHookAgentTurn === "function");
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveBackendLaunch(params) {
+    const shimPath = params.shimPath ?? SHIM_PATH;
+    if (!params.hostSupportsExecute) {
+        return {
+            kind: "legacy",
+            shimPath,
+            reason: "this OpenClaw does not expose runtime.agent.runCommandFromIngress and " +
+                "runtime.hooks.dispatchHookAgentTurn, so it is treated as not running plugin execute " +
+                "transports (needs >= 2026.8.1)",
+        };
+    }
+    const claude = resolveClaudeExecutable(params.env ?? process.env, params.platform ?? process.platform);
+    if (!claude.ok)
+        return { kind: "legacy", shimPath, reason: claude.reason };
+    return {
+        kind: "verified",
+        claudeCommand: claude.command,
+        claudeSource: claude.source,
+        shimPath,
+        ...(params.log ? { log: params.log } : {}),
+    };
+}
+const SHIM_ONLY_ENV = [
+    RETRY_ROSTER_ENV,
+    SESSION_DIRS_ENV,
+    "MULTI_CLAWD_MODEL_OVERRIDE",
+    CLAUDE_BIN_ENV,
+    CLAUDE_ARGV0_ENV,
+];
+function preparedForLaunch(launch, ctx, env, transport) {
+    if (launch.kind === "legacy")
+        return { env };
+    if (ctx.executionMode === "side-question") {
+        for (const key of SHIM_ONLY_ENV)
+            delete env[key];
+        return { env };
+    }
+    if (!transport)
+        throw new Error("[multi-clawd] verified launch is missing its shim transport");
+    return { env, execute: transport };
+}
 function knownModelsFile() {
     return join(homedir(), ".openclaw", "state", "multi-clawd", "known-models.json");
 }
@@ -407,7 +500,16 @@ function checkModelCurrency(catalogIds, chainRefs, poolId) {
     catch {
     }
 }
-export function buildBackend(account, execMode) {
+export function buildBackend(account, execMode, launch = { kind: "legacy", shimPath: SHIM_PATH }) {
+    const verified = launch.kind === "verified";
+    const shimPrefix = verified ? [] : [launch.shimPath];
+    const transport = verified
+        ? createShimExecute({
+            configuredCommand: launch.claudeCommand,
+            shimPath: launch.shimPath,
+            ...(launch.log ? { log: launch.log } : {}),
+        })
+        : undefined;
     const backend = {
         id: account.id,
         liveTest: {
@@ -419,6 +521,7 @@ export function buildBackend(account, execMode) {
                 binaryName: "claude",
             },
         },
+        ...(verified ? { runtimeArtifact: CLAUDE_RUNTIME_ARTIFACT } : {}),
         bundleMcp: true,
         bundleMcpMode: "claude-config-file",
         nativeToolMode: "selectable",
@@ -427,9 +530,9 @@ export function buildBackend(account, execMode) {
         sideQuestionToolMode: "disabled",
         ownsNativeCompaction: true,
         config: {
-            command: process.execPath,
-            args: [SHIM_PATH, ...BASE_ARGS, ...permissionModeArgs(execMode)],
-            resumeArgs: [SHIM_PATH, ...BASE_ARGS, ...permissionModeArgs(execMode), "--resume", "{sessionId}"],
+            command: verified ? launch.claudeCommand : process.execPath,
+            args: [...shimPrefix, ...BASE_ARGS, ...permissionModeArgs(execMode)],
+            resumeArgs: [...shimPrefix, ...BASE_ARGS, ...permissionModeArgs(execMode), "--resume", "{sessionId}"],
             forkArg: "--fork-session",
             resumeAtArg: "--resume-session-at",
             output: "jsonl",
@@ -457,13 +560,15 @@ export function buildBackend(account, execMode) {
             },
             serialize: true,
         },
-        async prepareExecution(_ctx) {
-            return { env: await buildAccountEnv(account) };
+        async prepareExecution(ctx) {
+            return preparedForLaunch(launch, ctx, await buildAccountEnv(account), transport);
         },
     };
+    launchTransports.set(backend, { launch, transport });
     Object.assign(backend.config, { sessionArg: "--session-id" });
     return backend;
 }
+const launchTransports = new WeakMap();
 export function buildRetryRoster(members, launchedId) {
     const roster = [];
     for (const member of members) {
@@ -490,26 +595,25 @@ export function isRuntimelessRegistration(api) {
     const mode = api?.registrationMode;
     return mode === "cli-metadata" || mode === "setup-only";
 }
-function buildCatalogProvider(account) {
+function buildCatalogProvider(account, members) {
     return {
         id: account.id,
         label: account.label ?? `Claude Code (${account.id})`,
         auth: [],
         resolveSyntheticAuth: () => {
             try {
-                const token = peekToken(account);
-                if (!token)
-                    return undefined;
-                return {
-                    apiKey: token,
-                    source: `multi-clawd ${account.id} token`,
-                    mode: "token",
-                };
+                return members
+                    ? poolRuntimeAuth(account.id, members.map((member) => () => resolveAccountRuntimeAuth(member)))
+                    : resolveAccountRuntimeAuth(account);
             }
             catch {
                 return undefined;
             }
         },
+        prepareRuntimeAuth: async (ctx) => {
+            refuseRuntimeAuthMarker(ctx);
+            return undefined;
+        },
         augmentModelCatalog: async () => buildCatalogEntries(account, await resolveBaseModelIds()),
         resolveDynamicModel: (ctx) => buildRuntimeModel(account, ctx.modelId),
     };
@@ -561,7 +665,22 @@ export default definePluginEntry({
         }
         const execMode = resolveExecMode(runtimeConfigLoader?.() ?? api.config);
         api.logger.info(`[multi-clawd] exec policy: ${execMode ?? "unknown"} → permission-mode ${permissionModeArgs(execMode).length ? "bypassPermissions" : "default (no override)"}`);
+        const launchLogger = api.logger;
+        const launch = resolveBackendLaunch({
+            hostSupportsExecute: hostRunsExecuteTransports(api.runtime),
+            log: (line) => launchLogger.info(line),
+        });
+        if (launch.kind === "verified") {
+            api.logger.info(`[multi-clawd] launch mode: verified — claude ${launch.claudeCommand} (from ${launch.claudeSource === "override" ? "MULTI_CLAWD_CLAUDE_BIN" : "PATH"}) is the backend command; host runs execute transports ` +
+                `(runtime.agent.runCommandFromIngress + runtime.hooks.dispatchHookAgentTurn present), ` +
+                `so agent turns run through shim ${launch.shimPath} and side-questions run claude directly`);
+        }
+        else {
+            api.logger.warn(`[multi-clawd] launch mode: legacy node+shim — ${launch.reason ?? "unknown reason"}; ` +
+                `failover is unchanged, but OpenClaw cannot verify this backend as a setup owner`);
+        }
         const seen = new Set();
+        loginAuthCache = undefined;
         for (const account of accounts) {
             const id = account?.id?.trim();
             if (!id) {
@@ -577,10 +696,11 @@ export default definePluginEntry({
             }
             seen.add(id);
             const normalized = { ...account, id };
-            api.registerCliBackend(buildBackend(normalized, execMode));
+            api.registerCliBackend(buildBackend(normalized, execMode, launch));
             api.registerProvider(buildCatalogProvider(normalized));
         }
-        registerPoolBackend(api, cfg.pool, accounts, seen, execMode);
+        registerPoolBackend(api, cfg.pool, accounts, seen, execMode, { launch });
+        void warmLoginAuth(accounts.filter((a) => seen.has(a.id.trim()))).catch(() => { });
         {
             const logger = api.logger;
             try {
@@ -696,7 +816,8 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     };
     const minDwellMs = pool.minDwellMs;
     const stickyFile = join(homedir(), ".openclaw", "state", "multi-clawd", `pool-${poolId}.sticky.json`);
-    const backend = buildBackend(poolAccount, execMode);
+    const backend = buildBackend(poolAccount, execMode, deps?.launch);
+    const { launch, transport } = launchTransports.get(backend);
     backend.prepareExecution = async (ctx) => {
         const now = Date.now();
         const requestedModel = canonicalModelId(ctx.modelId) ?? ctx.modelId;
@@ -851,7 +972,12 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
                     requestedModel: ctx.modelId,
                     ladder,
                 });
-            if (degradation) {
+            const runsWithoutShim = launch.kind === "verified" && ctx.executionMode === "side-question";
+            if (degradation && runsWithoutShim) {
+                logger.warn(`[multi-clawd] pool ${poolId}: side-question runs ${ctx.modelId} undegraded on ${(launched ?? chosen).id} — every account is limited for it, and the degrade ladder (${degradation.model}) ` +
+                    `can only be applied by the shim, which OpenClaw does not run for side-questions`);
+            }
+            else if (degradation) {
                 env.MULTI_CLAWD_MODEL_OVERRIDE = degradation.model;
                 const line = `pool ${poolId}: degrading ${ctx.modelId} → ${degradation.model} on ${chosen.id} (${degradation.reason})`;
                 logger.info(`[multi-clawd] ${line}`);
@@ -861,10 +987,10 @@ 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 { env };
+        return preparedForLaunch(launch, ctx, env, transport);
     };
     api.registerCliBackend(backend);
-    api.registerProvider(buildCatalogProvider(poolAccount));
+    api.registerProvider(buildCatalogProvider(poolAccount, members));
     registeredIds.add(poolId);
     logger.info(`[multi-clawd] pool "${poolId}" active — accounts: ${memberIds.join(" → ")}, threshold: ${options.utilizationThreshold ?? 0.85}`);
     void (async () => {

package/dist/runtime-auth.js

@@ -0,0 +1,124 @@
+import { ACCESS_TOKEN_EXPIRY_SKEW_MS, CLAUDE_KEYCHAIN_SERVICE, assessAccountCredential, keychainServiceForConfigDir, } from "./login-health.js";
+export const RUNTIME_AUTH_MARKER_PREFIX = "oauth:";
+export const LOGIN_AUTH_CACHE_TTL_MS = 30 * 1000;
+export function runtimeAuthMarker(providerId) {
+    return `${RUNTIME_AUTH_MARKER_PREFIX}${providerId.trim()}`;
+}
+export function isRuntimeAuthMarker(value) {
+    if (typeof value !== "string")
+        return false;
+    const trimmed = value.trim();
+    return trimmed.startsWith(RUNTIME_AUTH_MARKER_PREFIX) && trimmed.length > RUNTIME_AUTH_MARKER_PREFIX.length;
+}
+export function loginRuntimeAuth(check, ctx) {
+    if (check.status !== "ok")
+        return undefined;
+    const expiresAt = check.expiresAt !== undefined && check.expiresAt > ctx.nowMs ? check.expiresAt : undefined;
+    return {
+        apiKey: runtimeAuthMarker(ctx.providerId),
+        source: `claude login (${ctx.accountId})`,
+        mode: "oauth",
+        ...(expiresAt === undefined ? {} : { expiresAt }),
+    };
+}
+export function poolRuntimeAuth(poolId, members) {
+    for (const member of members) {
+        let result;
+        try {
+            result = member();
+        }
+        catch {
+            continue;
+        }
+        if (!result)
+            continue;
+        return {
+            apiKey: runtimeAuthMarker(poolId),
+            source: result.source,
+            mode: "oauth",
+            ...(result.expiresAt === undefined ? {} : { expiresAt: result.expiresAt }),
+        };
+    }
+    return undefined;
+}
+export function loginAuthEligible(account) {
+    return !account.oauthTokenFile && !account.oauthTokenRef && Boolean(account.native || account.configDir);
+}
+export function createLoginAuthCache(options) {
+    const ttlMs = options.ttlMs ?? LOGIN_AUTH_CACHE_TTL_MS;
+    const cache = new Map();
+    const inflight = new Map();
+    const health = (accountId) => {
+        try {
+            return options.health?.(accountId) ?? {};
+        }
+        catch {
+            return {};
+        }
+    };
+    const eligible = loginAuthEligible;
+    const store = (accountId, check, nowMs) => {
+        const tokenBound = check.status === "ok" && check.expiresAt !== undefined
+            ? check.expiresAt - ACCESS_TOKEN_EXPIRY_SKEW_MS
+            : undefined;
+        const hardUntil = tokenBound !== undefined && tokenBound > nowMs ? tokenBound : nowMs + ttlMs;
+        cache.set(accountId, { check, freshUntil: nowMs + ttlMs, hardUntil });
+    };
+    const judge = async (account, nowMs) => {
+        let io = options.io;
+        if (io.platform === "darwin" && options.readKeychainItemAsync) {
+            const dir = account.native ? "~/.claude" : account.configDir;
+            const service = account.native
+                ? CLAUDE_KEYCHAIN_SERVICE
+                : keychainServiceForConfigDir(io.expandHome(dir ?? ""));
+            const read = await options.readKeychainItemAsync(service, io.keychainAccount);
+            io = { ...io, readKeychainItem: () => read };
+        }
+        const check = assessAccountCredential(account, io, {
+            proof: { lastSuccessAt: health(account.id).lastSuccessAt },
+            nowMs,
+        });
+        store(account.id, check, nowMs);
+    };
+    const refresh = (account, nowMs = Date.now()) => {
+        if (!eligible(account))
+            return Promise.resolve();
+        const running = inflight.get(account.id);
+        if (running)
+            return running;
+        const task = judge(account, nowMs)
+            .catch(() => {
+            store(account.id, { status: "unknown", reason: "credential source could not be judged" }, nowMs);
+        })
+            .finally(() => {
+            inflight.delete(account.id);
+        });
+        inflight.set(account.id, task);
+        return task;
+    };
+    return {
+        peek(account, providerId, nowMs = Date.now()) {
+            if (!eligible(account))
+                return undefined;
+            if (health(account.id).failed)
+                return undefined;
+            const hit = cache.get(account.id);
+            if (!hit || hit.freshUntil <= nowMs)
+                void refresh(account, nowMs);
+            if (!hit || hit.hardUntil <= nowMs)
+                return undefined;
+            return loginRuntimeAuth(hit.check, { providerId, accountId: account.id, nowMs });
+        },
+        refresh,
+        record(accountId, check, nowMs = Date.now()) {
+            store(accountId, check, nowMs);
+        },
+    };
+}
+export function refuseRuntimeAuthMarker(ctx) {
+    if (!isRuntimeAuthMarker(ctx.apiKey))
+        return undefined;
+    throw new Error(`[multi-clawd] ${ctx.provider}/${ctx.modelId} runs through the Claude Code CLI backend; ` +
+        `this account is a Claude login (no setup token), so the direct API transport is not available for it. ` +
+        `Run the model as an agent turn, or give the account an oauthTokenFile/oauthTokenRef to use it directly.`);
+}

package/dist/shim-transport.js

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { createInterface } from "node:readline";
+import { CLAUDE_ARGV0_ENV, CLAUDE_BIN_ENV } from "./claude-command.js";
+const EXPECTED_FIRST_ARG = "-p";
+const SYSTEM_PROMPT_FILE_ARG = "--append-system-prompt-file";
+const STDERR_TAIL_CHARS = 8192;
+const KILL_GRACE_MS = 1000;
+const EXIT_WAIT_MS = 3000;
+export function composePromptForStdin(prompt, context) {
+    const prepended = context?.prependContext ? `${context.prependContext}\n\n${prompt}` : prompt;
+    return context?.appendContext ? `${prepended}\n\n${context.appendContext}` : prepended;
+}
+export function assertWrappableInvocation(ctx, configuredCommand) {
+    const registered = realpathOf(configuredCommand);
+    const handed = realpathOf(ctx.command);
+    if (!registered || !handed || registered !== handed) {
+        throw new Error(`[multi-clawd] refusing to run ${ctx.command} through the shim: this backend only wraps ` +
+            `its registered claude executable ${configuredCommand}`);
+    }
+    if (ctx.args[0] !== EXPECTED_FIRST_ARG) {
+        throw new Error(`[multi-clawd] refusing to wrap an invocation with a leading argv (${String(ctx.args[0])}): ` +
+            `the shim can only exec ${configuredCommand} itself`);
+    }
+    if (ctx.argv0 !== undefined && ctx.argv0 !== configuredCommand) {
+        throw new Error(`[multi-clawd] refusing argv0 ${JSON.stringify(ctx.argv0)}: only the registered command ` +
+            `${configuredCommand} may name the claude executable`);
+    }
+    return { executable: handed, argv0: configuredCommand };
+}
+function realpathOf(path) {
+    if (!isAbsolute(path))
+        return undefined;
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toError(reason, fallback) {
+    if (reason instanceof Error)
+        return reason;
+    return new Error(typeof reason === "string" && reason ? reason : fallback);
+}
+function redact(text, env) {
+    let out = text;
+    for (const [name, value] of Object.entries(env)) {
+        if (!value || value.length < 8)
+            continue;
+        if (!/TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|AUTH/i.test(name))
+            continue;
+        out = out.split(value).join("[REDACTED]");
+    }
+    return out;
+}
+function appendTail(tail, chunk) {
+    const next = tail + chunk;
+    return next.length > STDERR_TAIL_CHARS ? next.slice(-STDERR_TAIL_CHARS) : next;
+}
+function signalTree(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        if (process.platform !== "win32")
+            process.kill(-child.pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+        }
+    }
+}
+export function createShimExecute(options) {
+    const nodePath = options.nodePath ?? process.execPath;
+    return async function* executeThroughShim(ctx) {
+        const invocation = assertWrappableInvocation(ctx, options.configuredCommand);
+        ctx.assertCurrent?.();
+        ctx.abortSignal?.throwIfAborted();
+        const capability = ctx.liveSession;
+        if (capability?.restart)
+            await capability.restart();
+        ctx.assertCurrent?.();
+        let child;
+        let exited = false;
+        let resolveExit;
+        const exitPromise = new Promise((r) => (resolveExit = r));
+        let exitCode = null;
+        let exitSignal = null;
+        let spawnError;
+        let killTimer;
+        const terminate = () => {
+            if (!child || exited)
+                return;
+            signalTree(child, "SIGTERM");
+            if (!killTimer) {
+                killTimer = setTimeout(() => {
+                    if (child && !exited)
+                        signalTree(child, "SIGKILL");
+                }, KILL_GRACE_MS);
+                killTimer.unref?.();
+            }
+        };
+        const handle = capability
+            ? {
+                generation: randomUUID(),
+                fingerprint: capability.fingerprint,
+                isIdle: () => exited || !child,
+                close: () => terminate(),
+                waitForExit: () => (child ? exitPromise : Promise.resolve()),
+            }
+            : undefined;
+        let registered = false;
+        let promptDir;
+        const onAbort = () => terminate();
+        let stderrTail = "";
+        let stdoutNoise = "";
+        let stderrPartial = "";
+        try {
+            if (capability && handle) {
+                capability.register(handle);
+                registered = true;
+                capability.activate(handle);
+            }
+            const args = [...ctx.args];
+            const systemPrompt = ctx.systemPrompt.trim();
+            if (systemPrompt) {
+                promptDir = mkdtempSync(join(tmpdir(), "multi-clawd-system-prompt-"));
+                const file = join(promptDir, "system-prompt.md");
+                writeFileSync(file, systemPrompt, { mode: 0o600 });
+                args.push(SYSTEM_PROMPT_FILE_ARG, file);
+            }
+            const env = {
+                ...ctx.env,
+                [CLAUDE_BIN_ENV]: invocation.executable,
+                [CLAUDE_ARGV0_ENV]: invocation.argv0,
+            };
+            ctx.assertCurrent?.();
+            ctx.abortSignal?.throwIfAborted();
+            const spawned = spawn(nodePath, [options.shimPath, ...args], {
+                cwd: ctx.cwd,
+                env,
+                stdio: ["pipe", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+                windowsHide: true,
+            });
+            child = spawned;
+            spawned.once("error", (err) => {
+                spawnError = err;
+                exited = true;
+                resolveExit();
+            });
+            spawned.once("close", (code, signal) => {
+                exitCode = code;
+                exitSignal = signal;
+                exited = true;
+                resolveExit();
+            });
+            ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
+            spawned.stderr.setEncoding("utf8");
+            spawned.stderr.on("data", (chunk) => {
+                stderrTail = appendTail(stderrTail, chunk);
+                if (!options.log)
+                    return;
+                const text = stderrPartial + chunk;
+                const lines = text.split("\n");
+                stderrPartial = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (line.startsWith("[multi-clawd shim]"))
+                        options.log(line);
+                }
+            });
+            spawned.stdin.on("error", () => {
+            });
+            spawned.stdin.end(composePromptForStdin(ctx.prompt, ctx.promptContext));
+            const lines = createInterface({ input: spawned.stdout, crlfDelay: Infinity });
+            for await (const raw of lines) {
+                const line = raw.trim();
+                if (!line)
+                    continue;
+                let record;
+                try {
+                    record = JSON.parse(line);
+                }
+                catch {
+                    stdoutNoise = appendTail(stdoutNoise, `${line}\n`);
+                    continue;
+                }
+                if (!isPlainRecord(record)) {
+                    stdoutNoise = appendTail(stdoutNoise, `${line}\n`);
+                    continue;
+                }
+                yield record;
+            }
+            await exitPromise;
+            if (ctx.abortSignal?.aborted) {
+                throw toError(ctx.abortSignal.reason, "Claude CLI run was aborted.");
+            }
+            if (spawnError) {
+                throw new Error(`[multi-clawd] failed to start the shim: ${spawnError.message}`);
+            }
+            if (exitSignal || exitCode !== 0) {
+                const candidates = [stderrTail.trim(), stdoutNoise.trim()].filter(Boolean);
+                const detail = candidates[0] ?? `CLI failed (${exitSignal ? `signal ${exitSignal}` : `exit ${exitCode}`}).`;
+                throw new Error(redact(detail, env));
+            }
+        }
+        finally {
+            ctx.abortSignal?.removeEventListener("abort", onAbort);
+            if (child && !exited) {
+                terminate();
+                await Promise.race([
+                    exitPromise,
+                    new Promise((r) => setTimeout(r, EXIT_WAIT_MS).unref?.()),
+                ]);
+            }
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (!child)
+                resolveExit();
+            if (registered && capability && handle) {
+                try {
+                    capability.remove(handle);
+                }
+                catch {
+                }
+            }
+            if (promptDir) {
+                try {
+                    rmSync(promptDir, { recursive: true, force: true });
+                }
+                catch {
+                }
+            }
+        }
+    };
+}

package/dist/shim.js

@@ -6,21 +6,36 @@ import { rewriteModelArg } from "./degrade.js";
 import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
 import { canonicalModelId } from "./models.js";
 import { buildRetryEnv, chooseLaunchableRetryAccount, materializeRetryAccount, parseRetryRoster, retryArming, RETRY_ROSTER_ENV, } from "./retry-plan.js";
+import { CLAUDE_ARGV0_ENV, CLAUDE_BIN_ENV, parseClaudeBinOverride, resolveExecutable, } from "./claude-command.js";
 import { effectiveConfigDir, handoverForLaunch, handoverSnapshotTo, parseSessionDirs, SESSION_DIRS_ENV, snapshotResumeTranscript, } from "./session-handover.js";
 function resolveClaudeCommand() {
-    const override = process.env.MULTI_CLAWD_CLAUDE_BIN;
-    if (override) {
-        try {
-            const parsed = JSON.parse(override);
-            if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((p) => typeof p === "string")) {
-                return { command: parsed[0], prependArgs: parsed.slice(1) };
-            }
-        }
-        catch {
-        }
-        return { command: override, prependArgs: [] };
+    const raw = process.env[CLAUDE_BIN_ENV];
+    const argv0 = process.env[CLAUDE_ARGV0_ENV] || undefined;
+    delete process.env[CLAUDE_BIN_ENV];
+    delete process.env[CLAUDE_ARGV0_ENV];
+    const override = parseClaudeBinOverride(raw);
+    if (!override) {
+        if (argv0)
+            refuseLaunch(`${CLAUDE_ARGV0_ENV} is set without ${CLAUDE_BIN_ENV}`);
+        return { command: "claude", prependArgs: [] };
     }
-    return { command: "claude", prependArgs: [] };
+    const requested = override.kind === "argv" ? override.command : override.value;
+    const command = resolveExecutable(requested, process.env.PATH);
+    if (!command) {
+        refuseLaunch(`${CLAUDE_BIN_ENV}=${requested} is not an executable file`);
+    }
+    if (argv0 && override.kind === "argv" && override.prependArgs.length > 0) {
+        refuseLaunch(`${CLAUDE_ARGV0_ENV} cannot apply to an interpreter-form ${CLAUDE_BIN_ENV}`);
+    }
+    return {
+        command,
+        prependArgs: override.kind === "argv" ? override.prependArgs : [],
+        ...(argv0 ? { argv0 } : {}),
+    };
+}
+function refuseLaunch(why) {
+    process.stderr.write(`[multi-clawd shim] refusing to launch claude: ${why}\n`);
+    process.exit(127);
 }
 let stateFile = process.env.MULTI_CLAWD_STATE_FILE;
 let accountId = process.env.MULTI_CLAWD_ACCOUNT_ID ?? "unknown";
@@ -79,7 +94,7 @@ function persistState() {
         process.stderr.write(`[multi-clawd shim] state write failed: ${String(err)}\n`);
     }
 }
-const { command, prependArgs } = resolveClaudeCommand();
+const { command, prependArgs, argv0: claudeArgv0 } = resolveClaudeCommand();
 let childArgs = [...prependArgs, ...process.argv.slice(2)];
 const modelOverride = process.env.MULTI_CLAWD_MODEL_OVERRIDE;
 if (modelOverride) {
@@ -107,6 +122,7 @@ if (!retryArmed && retryRoster.length > 0 && arming.reason) {
 let child = spawn(command, childArgs, {
     stdio: ["pipe", "pipe", "inherit"],
     env: process.env,
+    ...(claudeArgv0 ? { argv0: claudeArgv0 } : {}),
 });
 const STDIN_REPLAY_CAP_BYTES = 8 * 1024 * 1024;
 let stdinReplay = [];
@@ -286,6 +302,7 @@ function attemptRetry() {
     child = spawn(command, childArgs, {
         stdio: ["pipe", "pipe", "inherit"],
         env: buildRetryEnv(process.env, target),
+        ...(claudeArgv0 ? { argv0: claudeArgv0 } : {}),
     });
     attachChildHandlers();
     for (const chunk of stdinReplay)

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Register additional Claude Code logins (Max/Pro accounts) as first-class OpenClaw CLI backends for cross-account failover, keeping the full skills/MCP harness on every account.",
   "cliBackends": [
     "claw1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,8 @@
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.3.24-beta.2",
-      "minGatewayVersion": "2026.3.24-beta.2"
+      "pluginApi": ">=2026.8.1",
+      "minGatewayVersion": "2026.8.1"
     }
   },
   "main": "./dist/index.js",
@@ -64,7 +64,7 @@
     "version": "npm run sync-manifest && npm run sync-readme-tag && git add openclaw.plugin.json README.md"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.6"
+    "openclaw": ">=2026.8.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {