@drakon-systems/multi-clawd 1.10.1 → 2.1.0

package/dist/shim-core.js

@@ -137,7 +137,9 @@ export function mergeHealthStates(disk, live, now, pruneAfterMs = PRUNE_AFTER_MS
     if (live.credential && (!credential || live.credential.seenAt >= credential.seenAt)) {
         credential = live.credential;
     }
-    if (now !== undefined && credential && now - credential.seenAt > pruneAfterMs) {
+    if (now !== undefined &&
+        credential?.status === "ok" &&
+        now - credential.seenAt > pruneAfterMs) {
         credential = undefined;
     }
     const updatedAt = Math.max(disk.updatedAt ?? 0, live.updatedAt ?? 0);

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

@@ -5,22 +5,37 @@ import { classifyStateReadFailure, clearCredentialFailure, clearModelRejection,
 import { rewriteModelArg } from "./degrade.js";
 import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
 import { canonicalModelId } from "./models.js";
-import { buildRetryEnv, chooseRetryAccount, parseRetryRoster, retryArming, RETRY_ROSTER_ENV, } from "./retry-plan.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) {
@@ -95,6 +110,7 @@ if (modelOverride) {
         process.stderr.write(`[multi-clawd shim] ${note}\n`);
 }
 const retryRoster = parseRetryRoster(process.env[RETRY_ROSTER_ENV]);
+delete process.env[RETRY_ROSTER_ENV];
 const resumeSnapshot = retryRoster.length > 0 && parseSessionDirs(process.env[SESSION_DIRS_ENV]).length > 0
     ? snapshotResumeTranscript(childArgs, process.env)
     : undefined;
@@ -106,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 = [];
@@ -233,11 +250,13 @@ function attemptRetry() {
     if (!retryArmed || retryUsed)
         return false;
     const model = effectiveModelId();
-    const target = chooseRetryAccount({
+    const target = chooseLaunchableRetryAccount({
         roster: retryRoster,
         readState: readSiblingState,
         modelId: model,
         nowMs: Date.now(),
+        materialize: (account) => materializeRetryAccount(account, (path) => readFileSync(path, "utf8")),
+        onSkip: (id, reason) => process.stderr.write(`[multi-clawd shim] not retrying onto ${id}: its declared credential did not resolve (${reason})\n`),
     });
     if (!target) {
         process.stderr.write(`[multi-clawd shim] model limit on ${accountId} with no healthy sibling to retry onto — ` +
@@ -283,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": "1.10.1",
+  "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": "1.10.1",
+  "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": {

package/scripts/cli.mjs

@@ -753,7 +753,7 @@ async function usageCommand(args) {
   for (const a of accounts) {
     const row = { id: a.id, label: a.label };
     if (a.oauthTokenFile || a.oauthTokenRef) {
-      row.skipped = "token-based login — not polled (stream telemetry only)";
+      row.skipped = "setup-token login — not polled: the usage endpoint needs the user:profile scope, setup-tokens carry only user:inference (stream telemetry only)";
     } else if (!a.native && !a.configDir) {
       row.skipped = "no login dir";
     } else {

package/scripts/doctor.mjs

@@ -6,7 +6,8 @@
  *   1. plugin install + manifest/config key agreement (the --force trap)
  *   2. compiled-artifact freshness (stale dist detection)
  *   3. claude CLI availability + PATH sanity
- *   4. per-account credential-source health + which Claude login each
+ *   4. per-account credential health (judged on expiry and proof, never on
+ *      presence), credential split-store detection, and which Claude login each
  *      account actually authenticates as (and whether two share one)
  *   5. per-account rate-limit telemetry (state files, age, windows)
  *   6. pool configuration, sticky state, and the account the next turn runs on
@@ -280,55 +281,73 @@ try {
 
 // ── 4. account credentials (values never printed) ──────────────────────────
 console.log("account credentials");
-const { checkAccountCredential, keychainServiceForConfigDir } = await importDist("login-health.js", [
-  "checkAccountCredential",
-  "keychainServiceForConfigDir",
-]);
-const { summarizeWindowUsage, classifyAccountHealth, overdueProbeAccount } = await importDist("health.js", [
-  "summarizeWindowUsage",
-  "classifyAccountHealth",
-  "overdueProbeAccount",
-]);
+// "cli": judging a credential source is doctor's own diagnostic (see the
+// identity import below). The store module carries the system I/O; both must
+// come from the same build so the io matches the judge.
+const { assessAccountCredential } = await importDist(
+  "login-health.js",
+  ["assessAccountCredential"],
+  "cli",
+);
+const { createSystemCredentialIo, findCredentialCopies, describeSplitStore } = await importDist(
+  "credential-store.js",
+  ["createSystemCredentialIo", "findCredentialCopies", "describeSplitStore"],
+  "cli",
+);
+const { summarizeWindowUsage, classifyAccountHealth, overdueProbeAccount, lastAuthSuccessAt } =
+  await importDist("health.js", [
+    "summarizeWindowUsage",
+    "classifyAccountHealth",
+    "overdueProbeAccount",
+    "lastAuthSuccessAt",
+  ]);
 // "cli", like the chain audits: resolving WHICH login backs an account is
 // doctor's own diagnostic, not a description of the running plugin's
 // behaviour. Asking the installed copy meant a fix to the resolver could not
 // take effect until the plugin itself was reinstalled — so the CLI reported a
 // bug it had already been taught not to make.
-const { resolveAccountIdentity, describeIdentity, findDuplicateLogins, maskEmail } =
-  await importDist(
-    "account-identity.js",
-    ["resolveAccountIdentity", "describeIdentity", "findDuplicateLogins", "maskEmail"],
-    "cli",
-  );
+const {
+  resolveAccountIdentity,
+  describeIdentity,
+  findDuplicateLogins,
+  maskEmail,
+  nativeDefaultConfigDir,
+} = await importDist(
+  "account-identity.js",
+  ["resolveAccountIdentity", "describeIdentity", "findDuplicateLogins", "maskEmail", "nativeDefaultConfigDir"],
+  "cli",
+);
 const { decideStickySelection } = await importDist("sticky.js", ["decideStickySelection"]);
-const io = {
-  readFile: (p) => readFileSync(expandHome(p), "utf8"),
-  keychainHasClaudeCredentials: () => keychainHasService("Claude Code-credentials"),
-  keychainHasClaudeCredentialsForDir: (dir) =>
-    keychainHasService(keychainServiceForConfigDir(expandHome(dir))),
-  platform: process.platform,
-};
-// Metadata-only probe (no `-w`): the secret is never read.
-function keychainHasService(service) {
-  try {
-    execFileSync("security", ["find-generic-password", "-s", service], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
+// Keychain reads name the account the Claude CLI uses (`-a`), never just the
+// service. Token values are reduced to expiry metadata where they are read and
+// are never printed.
+const io = createSystemCredentialIo();
+// A native account's child runs with CLAUDE_CONFIG_DIR CLEARED (the pool strips
+// it before every launch), so its login lives under the real home whatever
+// this shell says. Doctor run inside an agent session served by the pool
+// inherits the serving account's dir; honouring it resolved "native" from that
+// account and reported two distinct logins as one.
+const nativeDir = nativeDefaultConfigDir(process.env, HOME);
+if (nativeDir.ignored) {
+  note(
+    `CLAUDE_CONFIG_DIR=${nativeDir.ignored} is set in this shell — ignored: a native account runs ` +
+      `with it cleared, so native is resolved from ${nativeDir.dir}`,
+  );
 }
-// A native account's child sets no CLAUDE_CONFIG_DIR, so it authenticates
-// against whatever the default dir is in the ENV THE GATEWAY RUNS IN. Doctor
-// reads the same variable and prints the path it used, so a box that exports
-// CLAUDE_CONFIG_DIR globally shows its real source rather than a guess.
 const identityIo = {
   readFile: (p) => readFileSync(expandHome(p), "utf8"),
   expandHome,
-  defaultConfigDir: process.env.CLAUDE_CONFIG_DIR
-    ? expandHome(process.env.CLAUDE_CONFIG_DIR)
-    : join(HOME, ".claude"),
+  defaultConfigDir: nativeDir.dir,
   homeDir: HOME,
 };
+/**
+ * Last time the CLI's login for this account was accepted. The shim's file
+ * only: the usage poll authenticates with the credentials FILE, which on a
+ * split store is not the copy the CLI reads, so it proves nothing here.
+ */
+function authProofAt(accountId) {
+  return lastAuthSuccessAt(readJson(join(STATE_DIR, `${accountId}.json`)));
+}
 const accounts = pluginConfig.accounts ?? [];
 const identities = [];
 if (accounts.length === 0) warn("no accounts configured");
@@ -361,24 +380,51 @@ for (const account of accounts) {
   // credential EXISTS, and #8 is exactly the case where a present credential
   // is a session the Claude CLI has already rejected. A recorded runtime
   // failure is the stronger evidence, so it is reported as such.
+  // The record stands until a successful turn (or a re-login) clears it, so
+  // its age changes the wording, never the verdict.
   const recorded = readJson(join(STATE_DIR, `${account.id}.json`))?.credential;
   if (recorded?.status === "failed") {
-    const ageMin = Math.round((Date.now() - recorded.seenAt) / 60000);
+    const ageMin = Math.max(0, Math.round((Date.now() - recorded.seenAt) / 60000));
+    const age = ageMin < 90 ? `${ageMin}m` : `${Math.round(ageMin / 60)}h`;
     bad(
-      `${account.id}: the Claude CLI rejected this login ${ageMin}m ago${
+      `${account.id}: the Claude CLI rejected this login ${age} ago${
         recorded.reason ? ` (${recorded.reason})` : ""
-      } — excluded from the pool; fix with \`multi-clawd login ${account.id}\``,
+      } and no successful turn has been seen since — ` +
+        `fix with \`multi-clawd login ${account.id}\`, or prove an out-of-band fix with ` +
+        `\`multi-clawd doctor --probe\``,
     );
-    continue;
-  }
-  if (account.oauthTokenRef) {
+  } else if (account.oauthTokenRef) {
     warn(`${account.id}: oauthTokenRef — validated by the gateway's async probe, not doctor`);
-    continue;
+  } else {
+    const check = assessAccountCredential(account, io, { proof: { lastSuccessAt: authProofAt(account.id) } });
+    if (check.status === "ok") ok(`${account.id}: credential verified — ${check.detail ?? "ok"}`);
+    else if (check.status === "unverified") {
+      // Not a failure (an idle account's access token expires routinely), and
+      // never "alive": a dead refresh token looks exactly like this at rest.
+      warn(
+        `${account.id}: credential UNVERIFIED — ${check.reason}. The next turn on it refreshes or ` +
+          `fails; prove it now with \`multi-clawd doctor --probe\``,
+      );
+    } else if (check.status === "unknown") warn(`${account.id}: cannot verify (${check.reason ?? "no source"})`);
+    else bad(`${account.id}: ${check.reason}`);
+  }
+  // Credential split-store: more than one copy of this login's OAuth
+  // credential. Refresh tokens rotate, so once the copies diverge only the one
+  // refreshed last can still refresh — and the copy a tool happens to read
+  // decides whether it sees a live login or a dead one. Warn-level: the CLI's
+  // own copy may be fine today; this is the early warning.
+  const split = findCredentialCopies(account, io);
+  if (split.status === "split") {
+    const text = describeSplitStore(split, Date.now());
+    warn(`credential split-store — ${text.headline}`);
+    for (const line of text.copies) console.log(`       · ${line}`);
+    console.log(`       remedy: ${text.remedy}`);
+  } else if (split.status !== "n/a" && VERBOSE) {
+    note(`${account.id}: credential split-store — ${split.status === "single" ? "one copy" : "no stored copy"}`);
+  }
+  if (split.incomplete) {
+    note(`${account.id}: credential split-store check incomplete — the Keychain could not be listed, so same-service duplicates may be missed`);
   }
-  const check = checkAccountCredential(account, io);
-  if (check.status === "ok") ok(`${account.id}: credential source looks alive`);
-  else if (check.status === "unknown") warn(`${account.id}: cannot verify (${check.reason ?? "no source"})`);
-  else bad(`${account.id}: ${check.reason}`);
 }
 
 // Two ids, one login. This is the failure the rest of doctor cannot see: every
@@ -449,6 +495,27 @@ else {
   const members = (pool.accounts ?? []).filter((id) => accounts.some((a) => a.id === id));
   if (members.length < 2) bad(`pool "${pool.id ?? "clawd"}" has ${members.length} valid member(s); needs ≥ 2`);
   else ok(`pool "${pool.id ?? "clawd"}": ${members.join(" → ")}`);
+  // Setup-token members: what they do and do not get, said once, plainly.
+  const tokenMembers = members
+    .map((id) => accounts.find((a) => a.id === id))
+    .filter((a) => a && !a.native && (a.oauthTokenFile || a.oauthTokenRef));
+  if (tokenMembers.length > 0 && pool.usagePoll?.enabled !== false) {
+    note(
+      `usage poll: ${tokenMembers.map((a) => a.id).join(", ")} not polled — a setup-token carries only the ` +
+        `user:inference scope and the usage endpoint needs user:profile (upstream claude-code #11985). ` +
+        `Rotation for ${tokenMembers.length === 1 ? "it" : "them"} runs on stream telemetry: each turn's ` +
+        `rate-limit events still trigger the threshold and 5-hour-warning rules, but an idle account is ` +
+        `not re-measured between turns and there is no 95% usage alert.`,
+    );
+  }
+  const refOnly = tokenMembers.filter((a) => !a.oauthTokenFile);
+  if (refOnly.length > 0) {
+    note(
+      `in-turn retry: ${refOnly.map((a) => a.id).join(", ")} (oauthTokenRef) cannot be a mid-turn retry ` +
+        `target — the shim never receives secret values, and a reference has no file it could read. ` +
+        `${refOnly.length === 1 ? "It rotates" : "They rotate"} at the next launch instead.`,
+    );
+  }
   const sticky = readJson(join(STATE_DIR, `pool-${pool.id ?? "clawd"}.sticky.json`));
 
   // WHICH ACCOUNT IS ACTUALLY BEING USED. Everything above describes the pool