@drakon-systems/multi-clawd 2.0.0 → 2.1.0

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.0/SETUP-AGENT.md
 > and follow it to set up multi-clawd on this machine. I own a second
 > Claude account — ask me when you need me to log in.
 
@@ -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
@@ -868,6 +868,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/index.js

@@ -27,6 +27,8 @@ 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,
@@ -359,6 +361,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 +466,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 +487,7 @@ export function buildBackend(account, execMode) {
                 binaryName: "claude",
             },
         },
+        ...(verified ? { runtimeArtifact: CLAUDE_RUNTIME_ARTIFACT } : {}),
         bundleMcp: true,
         bundleMcpMode: "claude-config-file",
         nativeToolMode: "selectable",
@@ -427,9 +496,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 +526,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) {
@@ -561,6 +632,20 @@ 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();
         for (const account of accounts) {
             const id = account?.id?.trim();
@@ -577,10 +662,10 @@ 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 });
         {
             const logger = api.logger;
             try {
@@ -696,7 +781,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 +937,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,7 +952,7 @@ 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));

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.0",
   "description": "Register additional Claude Code logins (Max/Pro accounts) as first-class OpenClaw CLI backends for cross-account failover, keeping the full skills/MCP harness on every account.",
   "cliBackends": [
     "claw1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",
@@ -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": {