@byokit/openclaw 0.11.0 → 0.12.0

package/dist/routes.json

@@ -8,7 +8,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Alibaba Model Studio: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/alibaba/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -33,7 +33,7 @@
             "id": "alibaba",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -176,7 +176,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "The pinned Gateway has no app-guided sign-in for this choice.",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/anthropic/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -610,7 +610,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "ClawRouter: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/clawrouter/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -635,7 +635,7 @@
             "id": "clawrouter",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -647,7 +647,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Cloudflare AI Gateway: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/cloudflare-ai-gateway/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -681,7 +681,7 @@
             "id": "cloudflare-ai-gateway",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -739,7 +739,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "ComfyUI: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/comfy/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -773,7 +773,7 @@
             "id": "comfy",
             "method": "cloud-api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -785,7 +785,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Billing must be supplied by the host; a server address does not determine billing.",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/copilot-proxy/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -807,7 +807,7 @@
             "id": "copilot-proxy",
             "method": "local",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -911,7 +911,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "fal: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/fal/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -936,7 +936,7 @@
             "id": "fal",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -1585,7 +1585,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "LongCat: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/longcat/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -1619,7 +1619,7 @@
             "id": "longcat",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -1677,7 +1677,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Microsoft Foundry: Cloud credentials (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/microsoft-foundry/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -1699,7 +1699,7 @@
             "id": "microsoft-foundry",
             "method": "entra-id",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -1711,7 +1711,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Microsoft Foundry: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/microsoft-foundry/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -1736,7 +1736,7 @@
             "id": "microsoft-foundry",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -2458,7 +2458,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "PixVerse: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/pixverse/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -2492,7 +2492,7 @@
             "id": "pixverse",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -2838,7 +2838,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Runway: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/runway/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -2863,7 +2863,7 @@
             "id": "runway",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -2875,7 +2875,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Local runtime; explicitly select this route.",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/sglang/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -2897,7 +2897,7 @@
             "id": "sglang",
             "method": "custom",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -3360,7 +3360,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Local runtime; explicitly select this route.",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/vllm/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -3382,7 +3382,7 @@
             "id": "vllm",
             "method": "custom",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -3440,7 +3440,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Vydra: API key (billed per use).",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "extensions/vydra/openclaw.plugin.json (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -3474,7 +3474,7 @@
             "id": "vydra",
             "method": "api-key",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     },
     {
@@ -4005,7 +4005,7 @@
         "prerequisite": null,
         "offer": false,
         "offerPolicy": "explicit",
-        "reason": "Billing must be supplied by the host; a server address does not determine billing.",
+        "reason": "The pinned Gateway has no app-guided setup for this choice.",
         "source": "src/commands/auth-choice-options.static.ts (2026.8.1)",
         "revision": "2026.8.1",
         "checked": "2026-10-02",
@@ -4030,7 +4030,7 @@
             "id": "custom",
             "method": "custom",
             "revision": "ea806575e6450e4d1efdfc72c19f04be982a1b9b",
-            "flow": "present"
+            "flow": "absent"
         }
     }
 ]

package/dist/runs.d.ts

@@ -1,4 +1,6 @@
 import type { Bridge } from './bridge.ts';
+import type { createAccounts } from './accounts.ts';
+import type { createLocks } from './locks.ts';
 import { authStatus } from './auth-status.ts';
 import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
 import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './types.ts';
@@ -18,6 +20,11 @@ export declare function createRuns(ctx: {
     }>;
     bridge: Pick<Bridge, 'register'>;
     tools: ReadonlySet<string>;
+    accounts?: Pick<ReturnType<typeof createAccounts>, 'bind' | 'keyRefusal' | 'pick' | 'rest'>;
+    locks?: ReturnType<typeof createLocks>;
+    routes: Map<string, {
+        session: string;
+    }>;
 }): {
     run<const S extends OutputSchema | undefined = undefined>(spec: RunSpec<S>, on?: (e: RunEvent) => void, keyAgent?: string, preparedOutput?: ReturnType<typeof outputSchema>): Promise<RunEnd<SchemaOutput<S>>>;
     steer(k: string, t: string): Promise<void>;

package/dist/runs.js

@@ -5,12 +5,15 @@ import { authStatus } from "./auth-status.js";
 import { outputSchema } from "./output.js";
 import { words } from "./words.js";
 import { classify } from "./classify.js";
+import { providerOf } from "./pick.js";
 // The gateway gives up on a silent run after an hour; we wait ten minutes longer for the reply frame itself.
 const WAIT_MS = 3_600_000;
 const WAIT_CLIENT_MS = 3_610_000;
 // The `agent` request's final frame lands with the run's end; a run already over waits no longer than this for it.
 const FINAL_GRACE_MS = 5_000;
 const STATUS_MS = 5_000;
+// A resting end whose message names no time rests the account this long (5.15 Runs step 7).
+const REST_MS = 300_000;
 export const USABLE = new Set(['ok', 'expiring', 'static']);
 const usable = (row) => typeof row === 'string'
     || (Array.isArray(row.profiles) && row.profiles.length > 0 ? row.profiles.some((p) => USABLE.has(String(p?.status)))
@@ -62,10 +65,10 @@ function planOf(provider, row) {
  * a session preference it may rotate away from (docs/runtime-kits.md 5.8), so the kit never sends one.
  */
 function account(model) {
-    const at = model.indexOf('/');
-    if (at <= 0 || at === model.length - 1 || /[\s@]/.test(model))
+    const provider = providerOf(model);
+    if (provider === undefined)
         throw new Error(`refused: "${model}" is not a provider/model reference`);
-    return { provider: model.slice(0, at).toLowerCase(), model: model.slice(at + 1) }; // the engine lowercases ids
+    return { provider, model: model.slice(model.indexOf('/') + 1) }; // the engine lowercases ids
 }
 export function createRuns(ctx) {
     // The plan window the engine last read for the run's provider: `models.authStatus` answers from its cache without
@@ -87,8 +90,9 @@ export function createRuns(ctx) {
         return { ok: false, ...classified, message };
     };
     const run = async (spec, on, keyAgent, preparedOutput) => {
-        // Member boundary first: a member never speaks in another member's session, refused before any request.
-        if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
+        // Member boundary first: a member never speaks in another member's session, refused before any request. A key
+        // of one of the member's account agents is the member's too; binding below checks the index names it.
+        if (!spec.sessionKey.startsWith(`agent:${spec.member}:`) && !(ctx.accounts && !keyAgent && spec.sessionKey.startsWith(`agent:${spec.member}--`)))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
         // Same validation as the pin's NonEmptyString; preserve the caller's bytes (including whitespace).
         if (spec.idempotencyKey !== undefined && (typeof spec.idempotencyKey !== 'string' || !spec.idempotencyKey.length))
@@ -97,11 +101,104 @@ export function createRuns(ctx) {
         const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
         const system = [spec.system, output?.prompt].filter(Boolean).join('\n\n');
         const picked = spec.model === undefined ? undefined : account(spec.model);
+        for (const need of spec.needs ?? [])
+            account(need);
         for (const tool of spec.tools ?? [])
             if (!ctx.tools.has(tool))
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
-        const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
-        const sessionKey = keyAgent ? `agent:${keyAgent}:${spec.sessionKey.slice(`agent:${spec.member}:`.length)}` : spec.sessionKey;
+        const tail = spec.sessionKey.slice(spec.sessionKey.indexOf(':', 'agent:'.length) + 1);
+        // Runs step 1 (5.15): every run first finds the account its session is bound to, the API-key lane included.
+        const binding = ctx.accounts ? await ctx.accounts.bind(spec.member, spec.sessionKey) : undefined;
+        // Step 2 on the API-key lane: only an API-billed conversation continues on its key; any other binding is refused.
+        if (keyAgent && ctx.accounts && binding) {
+            const message = await ctx.accounts.keyRefusal(spec.member, binding);
+            if (message !== undefined)
+                return { ok: false, kind: 'other', message };
+        }
+        // A run that waited for its agent's lock across a move (5.15) binds again under it: a changed binding means its
+        // session went to another account, so it ends before any event and the caller's retry lands there.
+        const moved = async () => !!binding && (await ctx.accounts.bind(spec.member, spec.sessionKey))?.agentId !== binding.agentId;
+        const movedEnd = { ok: false, kind: 'other', message: words('run.moved') };
+        // Step 3: with `account` and `needs` both absent, on a key no account agent holds (or an API-key run, whose
+        // binding is API-billed), exactly the run on the agent it always was (a bound key under its shared lock).
+        if ((keyAgent || binding?.id === undefined) && spec.account === undefined && !spec.needs?.length) {
+            if (keyAgent)
+                return start(spec, on, { agentId: keyAgent, sessionKey: `agent:${keyAgent}:${tail}`, idempotencyKey, system, picked, output });
+            const { agentId } = await ctx.ensure(spec.member);
+            const member = () => start(spec, on, { agentId, sessionKey: spec.sessionKey, idempotencyKey, system, picked, output });
+            if (!binding || !ctx.locks)
+                return member();
+            return ctx.locks.shared(agentId, async () => await moved() ? movedEnd : member());
+        }
+        if (keyAgent)
+            throw new Error('refused: an API-key run uses its own account');
+        if (!ctx.accounts || !ctx.locks)
+            throw new Error('gateway not ready');
+        const accounts = ctx.accounts;
+        const locks = ctx.locks;
+        const restAccount = async (id, until) => {
+            const at = until ?? Date.now() + REST_MS;
+            await accounts.rest(spec.member, id, at);
+            return at;
+        };
+        const signedIn = async (agentId, provider) => !!(await ctx.request('byokit.accounts', { action: 'ready', agentId, provider })).ok;
+        const skipped = [];
+        for (;;) {
+            // Steps 2 and 4: the selection is resolved once per attempt, before any request, narrowed by the binding; `needs`
+            // alone resolves as 'default'. A refusal (`bound`, `paid`) ends the run with its words before any room, model or agent request.
+            const { pick, agent } = await accounts.pick(spec.member, { account: spec.account ?? 'default',
+                ...(spec.model !== undefined ? { model: spec.model } : {}), ...(spec.needs ? { needs: spec.needs } : {}) }, skipped, binding);
+            if (!pick.ok) {
+                if (pick.code === 'unknown_account')
+                    throw new Error(`unknown account: ${spec.account}`); // a caller bug
+                if (pick.code === 'resting')
+                    return { ok: false, kind: 'resting', until: await restAccount(pick.account, pick.until), message: pick.reason };
+                return { ok: false, kind: pick.code === 'none' ? 'signed-out' : pick.code === 'not_included' ? 'plan' : 'other', message: pick.reason };
+            }
+            const sessionKey = `agent:${agent}:${tail}`;
+            const automatic = pick.how === 'auto' || pick.why === 'first_ready';
+            // The run goes to the picked account's agent, under the key's tail. The run holds the agent's shared
+            // lock from its ready check to its end. An automatic pick not signed in is skipped before any event; an explicit
+            // one announces itself, then ends signed-out.
+            const end = await locks.shared(agent, async () => {
+                if (await moved())
+                    return movedEnd;
+                let ready;
+                try {
+                    ready = await signedIn(agent, pick.account.provider);
+                }
+                catch (error) {
+                    return failure(error instanceof Error ? error.message : String(error));
+                }
+                if (!ready && automatic)
+                    return undefined;
+                const route = { session: sessionKey };
+                ctx.routes.set(spec.sessionKey, route);
+                try {
+                    on?.({ type: 'account', account: pick.account.id, model: pick.model, sessionKey, how: pick.how, why: pick.why, considered: pick.considered });
+                    if (!ready)
+                        return { ok: false, kind: 'signed-out', message: `${pick.account.name} is not signed in` };
+                    return await start(spec, on, { agentId: agent, sessionKey, idempotencyKey, system,
+                        picked: pick.model ? account(pick.model) : undefined, output, chosen: pick }); // '' = no override
+                }
+                finally {
+                    if (ctx.routes.get(spec.sessionKey) === route)
+                        ctx.routes.delete(spec.sessionKey);
+                }
+            });
+            if (end === undefined) {
+                skipped.push(pick.account.id);
+                continue;
+            }
+            // Step 7: a resting end rests the account, so the next Auto skips it until then.
+            if (end.ok || !('kind' in end) || end.kind !== 'resting')
+                return end;
+            const until = await restAccount(pick.account.id, end.until);
+            return { ...end, until };
+        }
+    };
+    const start = async (spec, on, t) => {
+        const { agentId, sessionKey, idempotencyKey, system, picked, output, chosen } = t;
         const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools, idempotencyKey) : undefined;
         let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
@@ -140,7 +237,7 @@ export function createRuns(ctx) {
             }
         });
         try {
-            if (picked) {
+            if (picked && !chosen) {
                 // The picked account must be the one called: check it is signed in for this member before the run, since
                 // the engine would otherwise fail the run only after admitting it. An explicit provider/model is strict on
                 // the pinned engine (never another provider or model), so this check plus the override is the guarantee.
@@ -207,7 +304,10 @@ export function createRuns(ctx) {
                 const usage = usageOf(agentMeta);
                 const planWindow = typeof agentMeta.provider === 'string'
                     ? await planWindowOf(agentId, agentMeta.provider.toLowerCase()) : undefined;
-                return { ok: true, text, ...(parsed ? { data: parsed.data } : {}), ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
+                const reported = typeof agentMeta.provider === 'string' && typeof agentMeta.model === 'string'
+                    ? `${agentMeta.provider}/${agentMeta.model}`.toLowerCase() : '';
+                return { ok: true, text, ...(parsed ? { data: parsed.data } : {}), ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}),
+                    ...(chosen ? { account: chosen.account.id, model: chosen.model || reported } : {}) };
             }
             if (result.stopReason === 'aborted' || (abortedByEngine && result.status !== 'ok'))
                 return { ok: false, aborted: true };
@@ -227,7 +327,7 @@ export function createRuns(ctx) {
     };
     return {
         run,
-        steer: (k, t) => ctx.request('sessions.steer', { sessionKey: k, message: t }),
-        abort: async (k) => { await ctx.request('chat.abort', { sessionKey: k }); },
+        steer: (k, t) => ctx.request('sessions.steer', { sessionKey: ctx.routes.get(k)?.session ?? k, message: t }),
+        abort: async (k) => { await ctx.request('chat.abort', { sessionKey: ctx.routes.get(k)?.session ?? k }); },
     };
 }

package/dist/signin.d.ts

@@ -8,6 +8,9 @@ export type SignInCtx = {
     }>;
     callbackPort: number;
     onDisconnect?(fn: () => void): () => void;
+    authConfig(): string;
+    restarted(authBefore: string | undefined, signal?: AbortSignal): Promise<boolean>;
+    fresh?: boolean;
 };
 /**
  * Drive the engine's provider-owned login. `on` sees every view the person watches; `done` resolves once, and

package/dist/signin.js

@@ -2,7 +2,9 @@
 // sign-in; OAuth credentials stay in the engine/CLI. Explicit API keys go only to engine activation (D11).
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
+import { activate, LATE_RESTART } from "./activation.js";
 import { authStatus } from "./auth-status.js";
+import { routes } from "./routes.js";
 import { signedInProviders } from "./runs.js";
 import { words } from "./words.js";
 // The pin's wizard contract (2026.8.1): steps arrive only from `wizard.next` (wizard.status answers {status, error}
@@ -15,6 +17,8 @@ const CANCEL_MS = 10_000;
 const RECONFIRM_MS = 60_000;
 const TURNS = 200;
 const PASTE_MS = 15 * 60_000;
+const KEY_UNAVAILABLE = 'This key type is not available on this engine.';
+const KEY_FAILED = 'API key activation failed';
 // Two of the pin's code routes print their code only into a note's text ("Code: X" with
 // "Code expires in N minutes", or "enter the code X." with "Expires at: <ISO>"), never as `deviceCode`.
 // Read it back so every code route reaches the caller in the one structured shape.
@@ -41,6 +45,16 @@ export function signIn(ctx, member, o, on) {
     const { signal } = owner;
     const driveOwner = new AbortController();
     const wantsCallback = via === 'browser' && o.authChoice === 'openai';
+    // The pin builds ChatGPT's authorize URL unsigned, so a fresh sign-in can ask for the login screen itself.
+    const shown = (url) => {
+        if (!ctx.fresh || !wantsCallback)
+            return url;
+        const parsed = URL.canParse(url) ? new URL(url) : undefined;
+        if (parsed?.origin !== 'https://auth.openai.com' || parsed.pathname !== '/oauth/authorize')
+            return url;
+        parsed.searchParams.set('prompt', 'login');
+        return parsed.toString();
+    };
     let server;
     let sessionId = '';
     let starting;
@@ -48,6 +62,7 @@ export function signIn(ctx, member, o, on) {
     let settleStart;
     const startingSettled = new Promise((resolve) => { settleStart = resolve; });
     let over = false;
+    let activating = false;
     let recovering = false;
     let offDisconnect;
     let agentId;
@@ -82,13 +97,21 @@ export function signIn(ctx, member, o, on) {
     let pasteIn;
     let returned;
     // Once a secret step is seen, no later gateway prose, link or code is safe to display.
-    let sensitive = o.authChoice === 'setup-token' || o.authChoice === 'apiKey';
-    const secretFailure = () => o.authChoice === 'apiKey' ? 'API key activation failed' : 'Sign-in failed. Try again.';
+    let sensitive = o.authChoice === 'setup-token';
+    const secretFailure = 'Sign-in failed. Try again.';
+    // A pasted key is scrubbed from every failure on top of the engine's own redaction.
+    const keyRoute = routes().find((r) => r.choice === o.authChoice && r.keyEntry);
+    let secret;
+    const clean = (value) => {
+        const text = value instanceof Error ? value.message : String(value);
+        return cut(secret ? text.split(secret).join('…') : text);
+    };
+    const keyFailed = (status) => status === 'unavailable' ? KEY_UNAVAILABLE : KEY_FAILED;
     const done = new Promise((resolve) => { settle = resolve; });
     const say = (v) => {
         if (!over && !recovering && !signal.aborted)
             on({ state: 'waiting', via, ...(sensitive
-                    ? { ...(v.prompt ? { prompt: v.prompt } : {}), ...(v.error ? { error: secretFailure() } : {}) }
+                    ? { ...(v.prompt ? { prompt: v.prompt } : {}), ...(v.error ? { error: secretFailure } : {}) }
                     : v) });
     };
     const closeCallback = async () => {
@@ -109,7 +132,7 @@ export function signIn(ctx, member, o, on) {
         pasteIn = undefined;
         await closeCallback();
         if (sensitive && view.state === 'failed' && view.why === 'failed')
-            view = { ...view, error: secretFailure() };
+            view = { ...view, error: secretFailure };
         on(view);
         settle(view);
     };
@@ -134,11 +157,13 @@ export function signIn(ctx, member, o, on) {
     };
     const cancel = () => {
         // Stop the drive now; the start itself is never aborted, and release waits for it to settle before cancelling,
-        // so the gateway's one setup admission is freed by a cancel that the engine can actually find.
+        // so the gateway's one setup admission is freed by a cancel that the engine can actually find. An activation in
+        // flight is not finished here: the drive returns once the engine answers, so cleanup follows the engine's answer.
         if (signal.aborted)
             return;
         owner.abort();
-        void (async () => { await release(); await finish(cancelled()); })();
+        void (async () => { await release(); if (!activating)
+            await finish(cancelled()); })();
     };
     o.signal?.addEventListener('abort', cancel, { once: true });
     if (o.signal?.aborted)
@@ -188,7 +213,9 @@ export function signIn(ctx, member, o, on) {
         }
         // Native login is completed by the person in unmodified Claude Code. The pin does not expose this
         // choice via auth.start; activation verifies the CLI route and persists it only after a live test succeeds.
-        if (o.authChoice === 'anthropic-cli' || o.authChoice === 'apiKey') {
+        // A key-entry choice (API key or plan key) is not an auth.start login either: the pin's Gateway sets it up only
+        // from the pasted key through typed activation, and refuses it there ("provider setup is not available").
+        if (o.authChoice === 'anthropic-cli' || keyRoute) {
             settleStart();
             let apiKey;
             if (o.authChoice === 'anthropic-cli') {
@@ -197,7 +224,7 @@ export function signIn(ctx, member, o, on) {
                     return { state: 'failed', via, why: 'failed', error: 'Sign in with Claude Code on this machine in the kit’s isolated HOME, then try again. The login stays in Claude Code.' };
             }
             else {
-                say({ prompt: 'API key (billed per use)' });
+                say({ prompt: keyRoute?.billing === 'api' ? 'API key (billed per use)' : 'Plan key' });
                 apiKey = returned ?? await new Promise((resolve) => {
                     const stop = (value) => { clearTimeout(timer); signal.removeEventListener('abort', abort); pasteIn = undefined; resolve(value); };
                     const abort = () => stop();
@@ -210,16 +237,23 @@ export function signIn(ctx, member, o, on) {
                 returned = undefined;
                 if (!apiKey)
                     return { state: 'failed', via, why: signal.aborted ? 'declined' : 'expired' };
+                secret = apiKey.trim() || undefined;
             }
             if (signal.aborted)
                 return { state: 'failed', via, why: 'declined' };
-            const result = await ctx.request('openclaw.setup.activate', {
+            // Done waits for the gateway restart an `auth` change causes (activation.ts); a run started before it runs on the
+            // old config. A restart that runs late or is cancelled ends failed, and the account is cleaned up by the caller.
+            activating = true;
+            const result = await activate(ctx, {
                 agentId, kind: apiKey === undefined ? 'claude-cli' : 'api-key',
-                ...(apiKey === undefined ? {} : { authChoice: 'apiKey', apiKey }),
-            }, { timeoutMs: PULL_MS, signal });
-            // API secrets must never be echoed in a view, even if the gateway returns an error containing one.
-            return result.ok ? { state: 'done', via } : { state: 'failed', via, why: 'failed',
-                error: apiKey === undefined ? cut(result.error ?? 'Claude Code activation failed') : 'API key activation failed' };
+                ...(apiKey === undefined ? {} : { authChoice: o.authChoice, apiKey }),
+            }, { timeoutMs: PULL_MS, signal }).finally(() => { activating = false; });
+            if (result.late)
+                return signal.aborted ? cancelled() : { state: 'failed', via, why: 'failed', error: LATE_RESTART };
+            if (!result.ok)
+                return { state: 'failed', via, why: 'failed',
+                    error: apiKey === undefined ? clean(result.error ?? 'Claude Code activation failed') : keyFailed(result.status) };
+            return signal.aborted ? cancelled() : { state: 'done', via };
         }
         // The client chooses the wizard id; cancellation waits for the engine to register it.
         sessionId = `byokit-${randomUUID()}`;
@@ -295,7 +329,7 @@ export function signIn(ctx, member, o, on) {
                     codeTimer = setTimeout(() => { codeExpired = true; owner.abort(); }, duration);
                 const message = deviceCode.message ?? current.message;
                 // The code is on the card; acknowledging it lets the engine poll the provider itself.
-                say({ ...(deviceCode.code ? { code: deviceCode.code } : {}), ...(current.externalUrl ? { url: current.externalUrl } : {}),
+                say({ ...(deviceCode.code ? { code: deviceCode.code } : {}), ...(current.externalUrl ? { url: shown(current.externalUrl) } : {}),
                     ...(timed ? { expiresAt: Date.now() + duration } : {}), ...(message ? { message } : {}) });
                 const next = await answer(current);
                 if (next.done) {
@@ -326,7 +360,7 @@ export function signIn(ctx, member, o, on) {
             }
             if (current.type === 'note' || current.type === 'confirm' || current.type === 'select' || current.type === 'action') {
                 if (current.externalUrl)
-                    say({ url: current.externalUrl });
+                    say({ url: shown(current.externalUrl) });
                 const next = await answer(current);
                 if (next.done) {
                     terminal = next;
@@ -418,7 +452,7 @@ export function signIn(ctx, member, o, on) {
             else if (BUSY.test(cut(error)))
                 view = { state: 'failed', via, why: 'busy' };
             else
-                view = { state: 'failed', via, why: 'failed', error: o.authChoice === 'apiKey' ? 'API key activation failed' : cut(error) };
+                view = { state: 'failed', via, why: 'failed', error: keyRoute ? KEY_FAILED : clean(error) };
         }
         settleStart();
         if (view.state !== 'done')