@drakon-systems/multi-clawd 1.10.1 → 2.1.0

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, overdueProbeAccount, } from "./health.js";
+import { allCredentialFailed, classifyAccountHealth, 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";
@@ -19,14 +19,16 @@ import { addAlert, alertKeysWithPrefix, clearAlert, pendingAlertText, } from "./
 import { healthStateFile, usageStateFile, clearAccountCredentialFailure } from "./credential-state.js";
 import { createUsagePollController, effectiveUsagePollInterval, effectiveUsageWarnThreshold, usageAlertPrefix, usagePoolAlertKey, } from "./usage-poll.js";
 export { healthStateFile, usageStateFile, clearAccountCredentialFailure };
-import { accountConfigDir, buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
+import { accountConfigDir, AccountCredentialError, buildAccountChildEnv, credentialFailureText, parseSetupTokenFile, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
 import { diffCatalogModels, formatNewModelNotice, } from "./model-currency.js";
-import { checkAccountCredential, keychainServiceForConfigDir, createRefProbeTracker, } from "./login-health.js";
-import { execFileSync } from "node:child_process";
+import { assessAccountCredential, createRefProbeTracker, } from "./login-health.js";
+import { createSystemCredentialIo } from "./credential-store.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,
@@ -156,21 +158,7 @@ function ingestAlertSpool() {
 }
 const LOGIN_PROBE_INTERVAL_MS = 15 * 60 * 1000;
 const LOGIN_PROBE_INITIAL_DELAY_MS = 45 * 1000;
-const realCredentialIo = {
-    readFile: (p) => readFileSync(expandHome(p), "utf8"),
-    keychainHasClaudeCredentials: () => keychainHasService("Claude Code-credentials"),
-    keychainHasClaudeCredentialsForDir: (dir) => keychainHasService(keychainServiceForConfigDir(expandHome(dir))),
-    platform: process.platform,
-};
-function keychainHasService(service) {
-    try {
-        execFileSync("security", ["find-generic-password", "-s", service], { stdio: "ignore" });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+let realCredentialIo;
 const refProbeTrackers = new Map();
 const lastProbeStatus = new Map();
 function recordAccountCredentialFailure(accountId, reason, nowMs) {
@@ -195,7 +183,8 @@ function recordAccountCredentialFailure(accountId, reason, nowMs) {
 export async function runLoginHealthProbe(accounts, logger, deps = {}) {
     const now = deps.nowMs ?? Date.now();
     const resolver = deps.resolver ?? activeTokenResolver;
-    const io = deps.io ?? realCredentialIo;
+    const io = deps.io ?? (realCredentialIo ??= createSystemCredentialIo());
+    const readHealth = deps.readHealth ?? readHealthState;
     for (const account of accounts) {
         let status;
         let reason;
@@ -215,9 +204,12 @@ export async function runLoginHealthProbe(accounts, logger, deps = {}) {
             cause = outcome.cause;
         }
         else {
-            const check = checkAccountCredential(account, io);
+            const check = assessAccountCredential(account, io, {
+                proof: { lastSuccessAt: lastAuthSuccessAt(readHealth(account.id)) },
+                nowMs: now,
+            });
             status = check.status;
-            reason = check.reason;
+            reason = check.status === "ok" ? check.detail : check.reason;
         }
         const previous = lastProbeStatus.get(account.id);
         lastProbeStatus.set(account.id, status);
@@ -243,14 +235,30 @@ export async function runLoginHealthProbe(accounts, logger, deps = {}) {
             logger.error(`[multi-clawd] ${text}`);
             raiseAlert({ key: `login:${account.id}`, severity: "error", text });
         }
+        else if (status === "unverified" && previous !== "unverified") {
+            logger.info(`[multi-clawd] account "${account.id}" login unverified: ${reason ?? "unproven"}`);
+        }
+        else if (status === "unknown" && previous !== "unknown" && reason) {
+            logger.info(`[multi-clawd] account "${account.id}" login could not be checked: ${reason}`);
+        }
         else if (status === "degraded" && previous !== "degraded") {
             logger.info(`[multi-clawd] account "${account.id}" login degraded: ${reason ?? "resolver error"}`);
         }
+        else if (status === "ok" && previous === "unverified") {
+            logger.info(`[multi-clawd] account "${account.id}" login verified: ${reason ?? "ok"}`);
+        }
         else if (status === "ok" && (previous === "broken" || previous === "degraded")) {
             logger.info(`[multi-clawd] account "${account.id}" login recovered`);
             alertState = clearAlert(alertState, `login:${account.id}`);
             alertState = clearAlert(alertState, `login-resolver:${account.id}`);
         }
+        if (status === "ok") {
+            alertState = clearAlert(alertState, `login:${account.id}`);
+            alertState = clearAlert(alertState, `login-resolver:${account.id}`);
+        }
+        else if ((status === "unverified" || status === "unknown") && cause === undefined) {
+            alertState = clearAlert(alertState, `login:${account.id}`);
+        }
     }
 }
 export function startLoginHealthProbe(accounts, logger) {
@@ -290,7 +298,20 @@ function peekToken(account) {
     if (account.oauthTokenFile) {
         const path = expandHome(account.oauthTokenFile);
         warnIfTokenFileExposed(path);
-        return readFileSync(path, "utf8").trim();
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch (err) {
+            const code = err.code;
+            throw new AccountCredentialError(`[multi-clawd] account "${account.id}": token file ${account.oauthTokenFile} unreadable` +
+                (typeof code === "string" ? ` (${code})` : ""));
+        }
+        const read = parseSetupTokenFile(raw, `token file ${account.oauthTokenFile}`);
+        if ("error" in read) {
+            throw new AccountCredentialError(`[multi-clawd] account "${account.id}": ${read.error}`);
+        }
+        return read.token;
     }
     if (isSecretRefShape(account.oauthTokenRef)) {
         return activeTokenResolver?.peek(account.oauthTokenRef);
@@ -340,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");
 }
@@ -388,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: {
@@ -400,6 +487,7 @@ export function buildBackend(account, execMode) {
                 binaryName: "claude",
             },
         },
+        ...(verified ? { runtimeArtifact: CLAUDE_RUNTIME_ARTIFACT } : {}),
         bundleMcp: true,
         bundleMcpMode: "claude-config-file",
         nativeToolMode: "selectable",
@@ -408,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",
@@ -438,25 +526,30 @@ 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) {
         if (member.id === launchedId)
             continue;
-        if (member.oauthTokenFile || member.oauthTokenRef)
+        const tokenFile = !member.native && member.oauthTokenFile ? expandHome(member.oauthTokenFile) : undefined;
+        if (!member.native && !tokenFile && member.oauthTokenRef)
+            continue;
+        if (!member.native && !tokenFile && !member.configDir)
             continue;
         const stateFile = healthStateFile(member.id);
-        const env = buildAccountChildEnv(member, undefined, stateFile);
+        const env = buildAccountChildEnv({ ...member, oauthTokenFile: undefined, oauthTokenRef: undefined }, undefined, stateFile);
         delete env.MULTI_CLAWD_ACCOUNT_ID;
         delete env.MULTI_CLAWD_STATE_FILE;
-        roster.push({ id: member.id, stateFile, env });
+        roster.push({ id: member.id, stateFile, env, ...(tokenFile ? { tokenFile } : {}) });
     }
     return roster;
 }
@@ -539,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();
@@ -555,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 {
@@ -674,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;
@@ -716,6 +824,10 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
                 `launching on ${decision.account} to re-test a rejection last seen ` +
                 `${Math.round((now - observedAt) / 3600000)}h ago`);
         }
+        else if (poolVerdicts.find((v) => v.id === decision.account)?.verdict === "credential_unverified") {
+            logger.info(`[multi-clawd] pool ${poolId}: no proven account can serve ${requestedModel} — ` +
+                `launching on ${decision.account} to re-test a login last rejected by the Claude CLI`);
+        }
         else if (decision.account !== previousAccount) {
             const home = verdicts[0];
             const line = decision.account === members[0].id
@@ -760,6 +872,13 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
                     text: `pool ${poolId}: account "${v.id}" is excluded — ${v.health.reason ?? "its login was rejected by the Claude CLI"}. Fix with \`multi-clawd login ${v.id}\`.`,
                 });
             }
+            else if (v.health.verdict === "credential_unverified") {
+                raiseAlert({
+                    key,
+                    severity: "error",
+                    text: `pool ${poolId}: account "${v.id}" is unproven — ${v.health.reason ?? "its login was last rejected by the Claude CLI"}. Fix with \`multi-clawd login ${v.id}\`.`,
+                });
+            }
             else {
                 alertState = clearAlert(alertState, key);
             }
@@ -774,6 +893,7 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             try {
                 env = await buildAccountEnv(candidate, deps?.resolver);
                 launched = candidate;
+                alertState = clearAlert(alertState, `credential-unresolved:${candidate.id}`);
                 if (candidate.id !== chosen.id) {
                     logger.warn(`[multi-clawd] pool ${poolId}: ${chosen.id}'s credential did not resolve — ` +
                         `launching on ${candidate.id} instead (account not benched; secret provider may be down)`);
@@ -781,7 +901,14 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
                 break;
             }
             catch (err) {
-                unresolved.push(`${candidate.id} (${err.message})`);
+                const why = credentialFailureText(err);
+                unresolved.push(`${candidate.id} (${why})`);
+                raiseAlert({
+                    key: `credential-unresolved:${candidate.id}`,
+                    severity: "error",
+                    text: `pool ${poolId}: account "${candidate.id}" was skipped — its declared credential did ` +
+                        `not resolve, so it will not launch on any other login (${why})`,
+                });
             }
         }
         if (!env) {
@@ -810,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}`);
@@ -820,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));
@@ -927,9 +1059,11 @@ export function stopUsagePoll() {
     usageInitial = undefined;
     usageController = undefined;
 }
+export const USAGE_TOKEN_ACCOUNT_REASON = "setup-token login — the usage endpoint needs the user:profile scope and setup-tokens carry only " +
+    "user:inference, so usage comes from stream telemetry only";
 export function usagePollCredentialsFile(account) {
     if (account.oauthTokenFile || account.oauthTokenRef) {
-        return { reason: "token-based login — usage is read from its own stream telemetry only" };
+        return { reason: USAGE_TOKEN_ACCOUNT_REASON };
     }
     if (!account.native && !account.configDir) {
         return { reason: "no login dir to read credentials from" };

package/dist/login-health.js

@@ -1,8 +1,98 @@
+import { parseSetupTokenFile } from "./account-env.js";
 import { createHash } from "node:crypto";
+export const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+export function claudeKeychainAccount(env, userInfo) {
+    try {
+        return env.USER || userInfo().username;
+    }
+    catch {
+        return "claude-code-user";
+    }
+}
 export function keychainServiceForConfigDir(absDir) {
     const hash = createHash("sha256").update(absDir).digest("hex").slice(0, 8);
     return `Claude Code-credentials-${hash}`;
 }
+export const AUTH_PROOF_FRESH_MS = 24 * 60 * 60 * 1000;
+export const ACCESS_TOKEN_EXPIRY_SKEW_MS = 60 * 1000;
+const MAX_PLAUSIBLE_EXPIRY_MS = 253402300799000;
+export function parseOauthCredential(raw) {
+    let text = raw.trim();
+    if (/^(?:[0-9a-f]{2})+$/i.test(text)) {
+        text = Buffer.from(text, "hex").toString("utf8").trim();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const oauth = parsed?.claudeAiOauth;
+    if (!oauth || typeof oauth !== "object")
+        return undefined;
+    const o = oauth;
+    const present = (v) => typeof v === "string" && v.trim().length > 0;
+    let expiresAt;
+    if (typeof o.expiresAt === "number" && Number.isFinite(o.expiresAt) && o.expiresAt > 0) {
+        const ms = o.expiresAt < 1e12 ? o.expiresAt * 1000 : o.expiresAt;
+        if (ms < MAX_PLAUSIBLE_EXPIRY_MS)
+            expiresAt = ms;
+    }
+    return {
+        hasAccessToken: present(o.accessToken),
+        hasRefreshToken: present(o.refreshToken),
+        expiresAt,
+    };
+}
+function ago(ms) {
+    const min = Math.max(0, Math.round(ms / 60000));
+    return min < 90 ? `${min}m` : `${Math.round(min / 60)}h`;
+}
+export function judgeOauthCredential(meta, source, proof, nowMs) {
+    const base = { source, expiresAt: meta.expiresAt };
+    if (!meta.hasAccessToken) {
+        return { ...base, status: "broken", reason: `${source}: access token is blank` };
+    }
+    if (meta.expiresAt !== undefined && meta.expiresAt - ACCESS_TOKEN_EXPIRY_SKEW_MS > nowMs) {
+        return {
+            ...base,
+            status: "ok",
+            detail: `access token valid until ${new Date(meta.expiresAt).toISOString()}`,
+        };
+    }
+    if (meta.expiresAt === undefined) {
+        return {
+            ...base,
+            status: "unverified",
+            reason: `${source}: records no access-token expiry, so it cannot be judged at rest`,
+        };
+    }
+    const expiry = `access token expired ${new Date(meta.expiresAt).toISOString()}`;
+    const success = proof.lastSuccessAt;
+    if (success !== undefined &&
+        success <= nowMs &&
+        nowMs - success <= AUTH_PROOF_FRESH_MS &&
+        success >= meta.expiresAt) {
+        return {
+            ...base,
+            status: "ok",
+            detail: `${expiry}; a successful turn ${ago(nowMs - success)} ago proves the refresh works`,
+        };
+    }
+    if (!meta.hasRefreshToken) {
+        return {
+            ...base,
+            status: "broken",
+            reason: `${source}: ${expiry} and no refresh token is stored`,
+        };
+    }
+    return {
+        ...base,
+        status: "unverified",
+        reason: `${source}: ${expiry} and no successful turn since proves the refresh works`,
+    };
+}
 export function createRefProbeTracker(options = {}) {
     const deadAfterConsecutive = options.deadAfterConsecutive ?? 3;
     const deadAfterMs = options.deadAfterMs ?? 10 * 60 * 1000;
@@ -42,29 +132,40 @@ export function createRefProbeTracker(options = {}) {
         },
     };
 }
-function looksLikeSetupToken(value) {
-    return /^sk-ant-[a-z0-9]+-/.test(value.trim());
-}
-function checkCredentialsJson(io, dir) {
+function assessCredentialsJson(io, path, proof, nowMs) {
     let raw;
     try {
-        raw = io.readFile(`${dir}/.credentials.json`);
+        raw = io.readFile(path);
     }
     catch {
-        return { status: "broken", reason: `${dir}/.credentials.json unreadable` };
+        return undefined;
     }
-    try {
-        const parsed = JSON.parse(raw);
-        const token = parsed?.claudeAiOauth?.accessToken;
-        if (typeof token === "string" && token.trim().length > 0)
-            return { status: "ok" };
-        return { status: "broken", reason: `${dir}/.credentials.json access token is blank` };
+    const meta = parseOauthCredential(raw);
+    if (!meta) {
+        return { status: "broken", reason: `${path} holds no Claude OAuth credential`, source: path };
     }
-    catch {
-        return { status: "broken", reason: `${dir}/.credentials.json is not valid JSON` };
+    return judgeOauthCredential(meta, path, proof, nowMs);
+}
+function assessKeychain(io, service, proof, nowMs) {
+    const read = io.readKeychainItem(service, io.keychainAccount);
+    if (read.status === "absent")
+        return undefined;
+    const source = `keychain "${service}"`;
+    if (read.status === "unreadable") {
+        return {
+            status: "unknown",
+            reason: `${source} could not be read (Keychain locked, access refused or timed out) — not judged`,
+            source,
+        };
     }
+    const meta = parseOauthCredential(read.data);
+    if (!meta)
+        return { status: "broken", reason: `${source} holds no Claude OAuth credential`, source };
+    return judgeOauthCredential(meta, source, proof, nowMs);
 }
-export function checkAccountCredential(account, io) {
+export function assessAccountCredential(account, io, options = {}) {
+    const proof = options.proof ?? {};
+    const nowMs = options.nowMs ?? Date.now();
     if (account.oauthTokenFile) {
         let raw;
         try {
@@ -73,35 +174,31 @@ export function checkAccountCredential(account, io) {
         catch {
             return { status: "broken", reason: `${account.oauthTokenFile} unreadable` };
         }
-        if (looksLikeSetupToken(raw))
-            return { status: "ok" };
-        return {
-            status: "broken",
-            reason: `${account.oauthTokenFile} does not contain a setup-token`,
-        };
+        const read = parseSetupTokenFile(raw, account.oauthTokenFile);
+        if ("token" in read)
+            return { status: "ok", detail: "setup-token present" };
+        return { status: "broken", reason: read.error };
     }
     if (account.oauthTokenRef) {
         return { status: "unknown" };
     }
-    if (account.native) {
-        if (io.platform === "darwin") {
-            return io.keychainHasClaudeCredentials()
-                ? { status: "ok" }
-                : { status: "broken", reason: "keychain has no Claude Code credentials" };
-        }
-        return checkCredentialsJson(io, "~/.claude");
-    }
-    if (account.configDir) {
-        if (io.platform === "darwin" && io.keychainHasClaudeCredentialsForDir(account.configDir)) {
-            return { status: "ok" };
-        }
-        const file = checkCredentialsJson(io, account.configDir);
-        if (file.status === "ok" || io.platform !== "darwin")
-            return file;
-        return {
+    const dir = account.native ? "~/.claude" : account.configDir;
+    if (!dir)
+        return { status: "unknown" };
+    const path = `${dir.replace(/\/+$/, "")}/.credentials.json`;
+    if (io.platform !== "darwin") {
+        return (assessCredentialsJson(io, path, proof, nowMs) ?? {
             status: "broken",
-            reason: `keychain has no Claude Code credentials for ${account.configDir} and ${file.reason}`,
-        };
+            reason: `${path} unreadable`,
+            source: path,
+        });
     }
-    return { status: "unknown" };
+    const service = account.native
+        ? CLAUDE_KEYCHAIN_SERVICE
+        : keychainServiceForConfigDir(io.expandHome(dir));
+    return (assessKeychain(io, service, proof, nowMs) ??
+        assessCredentialsJson(io, path, proof, nowMs) ?? {
+        status: "broken",
+        reason: `keychain has no Claude Code credentials for ${account.native ? "the default login" : dir} and ${path} unreadable`,
+    });
 }

package/dist/retry-plan.js

@@ -1,7 +1,9 @@
 import { classifyAccountHealth, overdueProbeAccount, } from "./health.js";
+import { parseSetupTokenFile } from "./account-env.js";
 import { resumeSessionId } from "./session-handover.js";
 export const RETRY_ROSTER_ENV = "MULTI_CLAWD_RETRY_ACCOUNTS";
 const CREDENTIAL_ENV_KEYS = ["CLAUDE_CONFIG_DIR", "CLAUDE_CODE_OAUTH_TOKEN"];
+const ROSTER_ENV_KEYS = ["CLAUDE_CONFIG_DIR"];
 export function parseRetryRoster(raw) {
     if (!raw)
         return [];
@@ -26,11 +28,12 @@ export function parseRetryRoster(raw) {
         const env = {};
         if (e.env && typeof e.env === "object") {
             for (const [k, v] of Object.entries(e.env)) {
-                if (typeof v === "string")
+                if (typeof v === "string" && ROSTER_ENV_KEYS.includes(k))
                     env[k] = v;
             }
         }
-        out.push({ id: e.id, stateFile: e.stateFile, env });
+        const tokenFile = typeof e.tokenFile === "string" && e.tokenFile ? e.tokenFile : undefined;
+        out.push({ id: e.id, stateFile: e.stateFile, env, ...(tokenFile ? { tokenFile } : {}) });
     }
     return out;
 }
@@ -40,7 +43,7 @@ export function isResumeLaunch(argv) {
 }
 export function retryArming(argv, roster, opts = {}) {
     if (roster.length === 0) {
-        return { armed: false, reason: "no secret-free sibling account to retry onto" };
+        return { armed: false, reason: "no sibling account the shim can retry onto" };
     }
     if (isResumeLaunch(argv) && !opts.resumeReady) {
         return {
@@ -77,3 +80,35 @@ export function buildRetryEnv(base, account) {
     env[RETRY_ROSTER_ENV] = "";
     return env;
 }
+export function materializeRetryAccount(account, readFile) {
+    if (!account.tokenFile)
+        return { account };
+    let raw;
+    try {
+        raw = readFile(account.tokenFile);
+    }
+    catch (err) {
+        const code = err.code;
+        return { error: `token file unreadable${typeof code === "string" && /^E[A-Z]+$/.test(code) ? ` (${code})` : ""}` };
+    }
+    const read = parseSetupTokenFile(raw, "token file");
+    if ("error" in read)
+        return { error: read.error };
+    return {
+        account: { ...account, env: { ...account.env, CLAUDE_CODE_OAUTH_TOKEN: read.token } },
+    };
+}
+export function chooseLaunchableRetryAccount(params) {
+    let remaining = params.roster;
+    while (remaining.length > 0) {
+        const pick = chooseRetryAccount({ ...params, roster: remaining });
+        if (!pick)
+            return undefined;
+        const ready = params.materialize(pick);
+        if ("account" in ready)
+            return ready.account;
+        params.onSkip?.(pick.id, ready.error);
+        remaining = remaining.filter((a) => a !== pick);
+    }
+    return undefined;
+}