@byokit/openclaw 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.3.4 (2026-09-30)
+
+
+
+- FIX: Device-code sign-in waits for the engine’s code expiry instead of failing after two minutes; caller cancellation and expiry return typed outcomes with plain words.
+- Offer the native Claude Code / Agent SDK subscription route (`claude-cli`, plugin `anthropic`), keeping login in Claude Code in the isolated engine HOME. Sign-in uses engine detection and live activation; `oc.state` reports native login readiness.
+- Support explicit Anthropic API key activation with a per-use billing label and secret-safe views; never offer an API-key fallback. Direct Claude.ai OAuth and setup-token offers remain excluded.
+- Verify native and API per-run provider/model forwarding, tool events and strict refusal of `@profile` pins.
+
+## 0.3.3 (2026-09-30)
+
+- Dependency update: pins @byokit/secrets 0.5.0.
+
+- SECURITY: Opt-in dual-wrap credential upgrades are authenticated and atomically replaced under the store lock; protection is only as strong as the owner-only host-key file, which must stay out of sealed-store backups.
+- FIX: A locked or unresponsive keyring no longer throws from prepare or start. The kit reports a locked saved sign-in in plain words, preserves the sealed store and retries normally on a later start after unlock; dual-wrapped stores open through their host key without prompting.
+
+- FIX: ChatGPT subscription device pairing was blocked by the plugin allowlist unless the app added the provider plugin itself. The kit now merges every offered route's provider plugin with the bridge and caller-provided plugins, without adding plugins for unoffered routes.
+- Label the explicit Anthropic route as API key (billed per use), keeping API and plan routes off by default.
+
 ## 0.3.2 (2026-09-30)
 
 - Dependency update: pins @byokit/secrets 0.4.0.

package/README.md

@@ -33,21 +33,36 @@ the pinned engine and needs a real ChatGPT sign-in, so it is not run here):
 ```ts
 import { OpenClawKit } from '@byokit/openclaw';
 
-const kit = new OpenClawKit({ stateDir: './openclaw-state' });
+const kit = new OpenClawKit({ stateDir: './openclaw-state', config: { plugins: { allow: ['openai'] } } });
 await kit.start(); // installs the pinned engine under stateDir, spawns it, connects
 
-await kit.ensureMember('ana');
-const signIn = kit.signIn('ana', { authChoice: 'openai-device-code', via: 'code' }, (view) => console.log(view));
-await signIn.done;
+await kit.ensureMember('umer');
+const controller = new AbortController(); // call controller.abort() when Umer cancels
+const signIn = kit.signIn('umer', {
+  authChoice: 'openai-device-code', via: 'code', signal: controller.signal,
+}, (view) => { if (view.code) console.log('Open', view.url, 'and enter', view.code); });
+const signedIn = await signIn.done;
+if (signedIn.state !== 'done') {
+  console.log(signedIn.error); // plain words; why is 'expired' or 'declined' on expiry or cancellation
+  await kit.stop();
+  process.exit(0);
+}
 
 const end = await kit.run(
-  { member: 'ana', sessionKey: 'agent:ana:main', message: 'Say hello.' },
+  { member: 'umer', sessionKey: 'agent:umer:main', message: 'Say hello.' },
   (e) => { if (e.type === 'text') console.log(e.text); },
 );
 console.log(end);
 await kit.stop();
 ```
 
+Device approval can take longer than two minutes. The kit waits through the engine's advertised code lifetime
+(`expiresInMinutes` on the pin, or `expires_in` seconds when supplied), including progress pulls. If the engine
+supplies no lifetime, it owns the deadline. Ordinary wizard requests keep their 120-second timeout.
+`signIn.cancel()` or the optional caller `signal` cancels this sign-in and releases its wizard session.
+`done` returns a typed `SignInView`: `why: 'expired'` for an expired code, `why: 'declined'` for cancellation,
+with a plain sentence in `error`. `SignInOptions` is exported from the host entry.
+
 To choose which of a member's accounts a run uses, pass `model: 'provider/model'` in the run spec (for example
 `'openai/gpt-5.1'`, where `provider` is an id `kit.providers(member)` lists). That provider is the one called and billed for this run only, with no fallback to another
 provider or model. If the member isn't signed in to it, the run ends `{ ok: false, kind: 'signed-out' }` and the
@@ -77,9 +92,9 @@ const kit = new OpenClawKit({ stateDir, spawnEngine: false, transport: fakeGatew
 try {
   await kit.start();
   console.log('state:', kit.state.phase, '| protocol:', kit.hello?.protocol);
-  await kit.ensureMember('ana');
+  await kit.ensureMember('umer');
   const end = await kit.run(
-    { member: 'ana', sessionKey: 'agent:ana:main', message: 'Say hello.' },
+    { member: 'umer', sessionKey: 'agent:umer:main', message: 'Say hello.' },
     (e) => console.log('event:', JSON.stringify(e)),
   );
   console.log('end:', JSON.stringify(end));
@@ -172,8 +187,16 @@ The pinned engine has no supported hook for sealing OAuth profile writes. Its `a
 credential JSON in agent SQLite databases and a shared state database, and doctor imports leave migration
 archives. `authSeal` therefore protects the complete isolated `state` and `home` directories, including SQLite
 journals. It uses the injected `SealingAdapter` from `@byokit/secrets`. `osKeyringSeal()` automatically
-falls back to a persistent private file key when no non-interactive keyring is available, including
-locked or unresponsive Linux keyrings; existing `authSeal` calls pick up the chain unchanged.
+uses a persistent private file key for new stores when no non-interactive keyring is available.
+Opening follows the saved envelope's mode. A locked or unresponsive keyring-only store leaves
+`kit.state.phase === 'locked'`: `prepare()` and `start()` resolve, show `stateWords(kit.state)` for
+recovery, and keep the sealed snapshot unchanged without launching the engine. Call `start()` again
+after unlock to restore the same credentials, even if a fallback key directory now exists.
+
+For hosts whose keyring stays locked, opt into `osKeyringSeal({ service, dualWrap: true })`.
+While unlocked, reading an existing keyring-only snapshot atomically upgrades it to dual-wrap.
+Later starts and stops can use the host wrap without prompting. Default off: **protection is only
+as strong as the owner-only host-key file**, which must stay outside sealed-store backups.
 
 ```ts
 import { osKeyringSeal, hostKeySeal } from '@byokit/secrets';
@@ -187,7 +210,7 @@ await kit.prepare(); // seals an existing plaintext store and migration archives
 await kit.start();   // authenticates and restores the isolated files for the engine
 await kit.stop();    // waits for exit, verifies an atomic sealed snapshot, then removes plaintext
 
-// Inspect the adapter's mode for host UI: 'keyring' or 'host-key-file'.
+// Inspect the adapter's write mode: 'keyring', 'host-key-file' or opt-in 'dual-wrap'.
 // Hosts can also explicitly supply a 32-byte key kept outside stateDir and its backups:
 declare const hostKey: Uint8Array;
 const server = new OpenClawKit({
@@ -200,7 +223,8 @@ The automatic key lives in the platform state directory, separate from the engin
 on the same disk protects copied stores/backups only when the key directory is excluded; it does
 not protect against code running as the same OS user. See [secrets' rotation and threat model](../secrets/README.md#servers-and-headless-node).
 Stop the kit, acquire the host writer lock and call `seal.rotate()` with `auth-store.sealed` plus
-every retained sealed migration archive before retiring an automatic key.
+every retained sealed migration archive before retiring an automatic key. Rotate each envelope mode
+separately; dual-wrap rotation retains old wrapping keys for backups.
 
 Without `authSeal`, engine credentials remain plaintext. With it, successful `prepare()` and `stop()` leave
 only a sealed snapshot, `auth-store.sealed`, for those directories. The adapter authenticates the snapshot
@@ -250,3 +274,5 @@ frozen (docs/runtime-kits.md §5).
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
+
+Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing), with login kept in Claude Code under the kit’s isolated `HOME=<stateDir>/openclaw/home` and `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; sign in there with `claude auth login`, then call `signIn`. Activation live-tests the route; native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.

package/SECURITY.md

@@ -23,6 +23,13 @@ running as the app's user, a compromised host/engine/plugin, or readable backups
 The isolated environment and tool gate are not an OS filesystem/network sandbox.
 The app must sandbox `ToolHost.call` and judge requests in `ToolHost.gate`.
 
+A locked or unresponsive keyring leaves the sealed snapshot unchanged. `prepare()` and `start()`
+resolve with `phase: 'locked'`, do not restore plaintext or launch the engine, and a later start
+retries after unlock. Opt-in dual wrapping opens through an owner-only host key without prompting;
+its protection is only as strong as that file, which must stay outside sealed-store backups.
+Unlocked keyring-only snapshots upgrade atomically under the store's exclusive lock after verifying
+the replacement decrypts to identical contents. Other sealing failures still reject.
+
 ## Secrets at rest and in memory
 
 | Asset | Location relative to `stateDir` | Protection and consequence of theft |

package/dist/auth-status.d.ts

@@ -0,0 +1,17 @@
+import type { GatewayTransport } from './types.ts';
+export type AuthStatus = {
+    providers?: (string | {
+        provider?: unknown;
+        status?: unknown;
+        profiles?: {
+            status?: unknown;
+        }[];
+        usage?: unknown;
+    })[];
+    unavailable?: {
+        message?: unknown;
+    };
+};
+/** Native Claude login stays in Claude Code. The pin's profile status does not include this synthetic auth;
+ * setup detection asks the CLI itself, without handing credentials to the kit. */
+export declare function authStatus(request: GatewayTransport['request'], agentId: string, refresh?: boolean, native?: boolean): Promise<AuthStatus>;

package/dist/auth-status.js

@@ -0,0 +1,13 @@
+/** Native Claude login stays in Claude Code. The pin's profile status does not include this synthetic auth;
+ * setup detection asks the CLI itself, without handing credentials to the kit. */
+export async function authStatus(request, agentId, refresh = false, native = false) {
+    const status = await request('models.authStatus', { agentId, ...(refresh ? { refresh: true } : {}) }, { timeoutMs: 20_000 });
+    if (!native)
+        return status;
+    const detected = await request('openclaw.setup.detect', { agentId }, { timeoutMs: 20_000 }).catch(() => ({}));
+    const rows = (status.providers ?? []).filter((row) => (typeof row === 'string' ? row : row.provider) !== 'claude-cli');
+    if (detected.candidates?.some((candidate) => candidate.kind === 'claude-cli' && candidate.credentials === true)) {
+        return { providers: [...rows, { provider: 'claude-cli', status: 'ok' }] };
+    }
+    return { ...status, providers: rows };
+}

package/dist/auth-store.js

@@ -149,7 +149,17 @@ export class AuthStore {
         if (!existsSync(this.file))
             return undefined;
         regular(this.file);
-        return snapshot(this.o.seal.decryptString(readFileSync(this.file)));
+        const seal = this.o.seal;
+        const bytes = readFileSync(this.file);
+        const text = seal.decryptString(bytes);
+        const saved = snapshot(text);
+        const upgraded = seal.upgrade?.(bytes);
+        if (upgraded) {
+            if (seal.decryptString(Buffer.from(upgraded)) !== text)
+                throw new Error('credential upgrade verification failed');
+            put(this.file, upgraded);
+        }
+        return saved;
     }
     collect() {
         const s = { v: 1, dirs: [], files: [] };

package/dist/config.js

@@ -1,4 +1,5 @@
 import { dirname, join } from 'node:path';
+import { routes } from "./routes.js";
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const merge = (a, b) => {
     for (const [k, v] of Object.entries(b))
@@ -53,7 +54,8 @@ export function reconcileConfig(saved, o) {
     c.plugins ??= {};
     c.plugins.load ??= {};
     c.plugins.load.paths = [...new Set([...(c.plugins.load.paths ?? []).filter((p) => !p.includes('byokit-openclaw-bridge')), o.pluginDir])];
-    c.plugins.allow = [...new Set([...(c.plugins.allow ?? []), o.pluginId])];
+    c.plugins.allow = [...new Set([...(c.plugins.allow ?? []), o.pluginId,
+            ...routes().filter(route => route.offer && route.plugin).map(route => route.plugin)])];
     c.plugins.entries ??= {};
     c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
     c.security ??= {};

package/dist/engine.d.ts

@@ -16,6 +16,7 @@ export declare class Engine {
     private starting?;
     private readonly authStore;
     private stopping;
+    private credentialsLocked;
     private repaired;
     private prepared?;
     private port;
@@ -40,7 +41,8 @@ export declare class Engine {
         port: number;
         token: string;
         identityPath: string;
-    }>;
+    } | undefined>;
+    private locked;
     private startOnce;
     private launch;
     withAuthStore<T>(task: () => Promise<T>): Promise<T>;

package/dist/engine.js

@@ -52,6 +52,7 @@ export class Engine {
     starting;
     authStore;
     stopping = false;
+    credentialsLocked = false;
     repaired = false;
     prepared;
     port = 0;
@@ -94,7 +95,15 @@ export class Engine {
             throw new Error('authSeal required for sealed credential store');
         for (const d of [this.root, ...(!this.o.authSeal ? [join(this.root, 'home'), join(this.root, 'state')] : []), join(this.root, 'tmp'), join(this.root, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs'), this.dir])
             mkdirSync(d, { recursive: true, mode: 0o700 });
-        await this.authStore.prepare();
+        try {
+            await this.authStore.prepare();
+            this.credentialsLocked = false;
+        }
+        catch (error) {
+            if (this.locked(error))
+                return;
+            throw error;
+        }
         if (this.o.spawnEngine) {
             const versionPath = join(this.dir, 'node_modules', 'openclaw', 'package.json');
             if (!existsSync(this.entry) || !installMatches(this.dir)) {
@@ -183,9 +192,25 @@ export class Engine {
             this.starting = undefined; }).catch(() => { });
         return pending;
     }
+    locked(error) {
+        if (!(error instanceof Error) || error.name !== 'KeystoreError' || !('code' in error) || error.code !== 'keyring-locked')
+            return false;
+        this.credentialsLocked = true;
+        this.state('locked');
+        return true;
+    }
     async startOnce() {
         await this.prepare();
-        await this.authStore.start();
+        if (this.credentialsLocked)
+            return undefined;
+        try {
+            await this.authStore.start();
+        }
+        catch (error) {
+            if (this.locked(error))
+                return undefined;
+            throw error;
+        }
         try {
             return this.launch();
         }
@@ -275,7 +300,8 @@ export class Engine {
             throw new Error('engine did not stop; credential store still in use');
         this.child = undefined;
         rmSync(join(this.root, 'gateway.pid'), { force: true });
-        await this.authStore.stop();
+        if (!this.credentialsLocked)
+            await this.authStore.stop();
         rmSync(this.bridgeSock, { force: true });
         this.state('stopped');
     }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, RunUsage, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';

package/dist/kit.d.ts

@@ -1,5 +1,5 @@
 import type { SealingAdapter } from '@byokit/secrets';
-import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, SignInView, ToolHost, ToolSpec } from './types.ts';
+import type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, Member, Route, RunEnd, RunEvent, RunSpec, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -75,10 +75,7 @@ export declare class OpenClawKit {
     routes(): Route[];
     providers(member: Member): Promise<string[]>;
     signedIn(member: Member, provider: string): Promise<boolean>;
-    signIn(member: Member, o: {
-        authChoice: string;
-        via?: 'browser' | 'code';
-    }, on: (v: SignInView) => void): {
+    signIn(member: Member, o: SignInOptions, on: (v: SignInView) => void): {
         paste(text: string): void;
         cancel(): void;
         done: Promise<SignInView>;

package/dist/kit.js

@@ -468,7 +468,7 @@ export class OpenClawKit {
         let transport;
         try {
             const ctx = await this.engine.start();
-            if (this.stopping)
+            if (!ctx || this.stopping)
                 return;
             this.setState({ phase: 'starting' });
             transport = (this.o.transport ?? gatewayTransport)({ ...ctx, bridgeSock: this.engine.bridgeSock });

package/dist/link.js

@@ -9,6 +9,7 @@ import { reach } from '@byokit/reach';
 import { ENGINE_VERSION } from "./constants.js";
 import { b64urlDecode, sealNotice } from "./notices.js";
 import { routeFor } from "./routes.js";
+import { authStatus } from "./auth-status.js";
 import { signedInProviders } from "./runs.js";
 import { stateWords, words } from "./words.js";
 const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events']);
@@ -99,7 +100,11 @@ export function openclawLink(kit, o) {
     const signIns = async (member) => {
         try {
             const { agentId } = await kit.ensureMember(member);
-            const status = await kit.call('models.authStatus', { agentId }, { timeoutMs: 5_000 });
+            const status = await authStatus((method, params, options) => {
+                if (method === 'models.authStatus')
+                    return kit.call(method, params, options);
+                return kit.call('openclaw.setup.detect', params, options);
+            }, agentId, false, true);
             return signedInProviders(status);
         }
         catch {

package/dist/routes.d.ts

@@ -1,9 +1,10 @@
 import type { Route } from './types.ts';
 /** The pin's auth-choice table. `provider` is the id a person's account is known by (the doc's matrix), which for
  *  MiniMax's portal routes is the account-visible `minimax`, not the wizard's internal `minimax-portal`. `plugin` is
- *  the bundled plugin the app must allow for that route to start (5.6). Only the pin's bundled provider contracts are
+ *  the bundled plugin needed for that route to start (5.6); the kit allows offered routes, and the app allows any
+ *  unoffered route it explicitly uses. Only the pin's bundled provider contracts are
  *  listed: install-catalog plugins (external providers needing their own install) are not contracted by the pin and
  *  are deliberately absent. */
 export declare function routes(): Route[];
-/** The route an app should use: only an offered route counts, so an Anthropic fallback can never be picked. */
+/** The route an app should use: only an offered route counts; API billing is never picked as a fallback. */
 export declare function routeFor(provider: string, via: 'browser' | 'code'): Route | undefined;

package/dist/routes.js

@@ -3,13 +3,14 @@ import routesJson from './routes.json' with { type: 'json' };
 const table = routesJson;
 /** The pin's auth-choice table. `provider` is the id a person's account is known by (the doc's matrix), which for
  *  MiniMax's portal routes is the account-visible `minimax`, not the wizard's internal `minimax-portal`. `plugin` is
- *  the bundled plugin the app must allow for that route to start (5.6). Only the pin's bundled provider contracts are
+ *  the bundled plugin needed for that route to start (5.6); the kit allows offered routes, and the app allows any
+ *  unoffered route it explicitly uses. Only the pin's bundled provider contracts are
  *  listed: install-catalog plugins (external providers needing their own install) are not contracted by the pin and
  *  are deliberately absent. */
 export function routes() {
     return table;
 }
-/** The route an app should use: only an offered route counts, so an Anthropic fallback can never be picked. */
+/** The route an app should use: only an offered route counts; API billing is never picked as a fallback. */
 export function routeFor(provider, via) {
     return table.find((route) => route.offer && route.provider === provider && route.via === via);
 }

package/dist/routes.json

@@ -111,14 +111,17 @@
     },
     {
         "choice": "anthropic-cli",
-        "provider": "anthropic",
+        "provider": "claude-cli",
         "plugin": "anthropic",
         "billing": "subscription",
         "via": "browser",
-        "prerequisite": "the Claude CLI, signed in inside the engine's own folder",
-        "offer": false,
-        "reason": "byokit never adds Claude plan sign-in",
-        "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)"
+        "prerequisite": "Sign in through unmodified Claude Code on this machine using the kit's isolated HOME and CLAUDE_CONFIG_DIR; the login stays in Claude Code.",
+        "offer": true,
+        "reason": "Claude subscription via your own Claude Code login on this machine (Agent SDK runtime).",
+        "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)",
+        "auth": "cli",
+        "terms": "allowed",
+        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
     },
     {
         "choice": "apiKey",
@@ -128,8 +131,11 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "API billing, not a subscription; never offered (D12): no Anthropic API fallback.",
-        "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)"
+        "reason": "API key (billed per use)",
+        "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)",
+        "auth": "api_key",
+        "terms": "allowed",
+        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
     },
     {
         "choice": "clawrouter-api-key",
@@ -348,8 +354,11 @@
         "via": "browser",
         "prerequisite": null,
         "offer": false,
-        "reason": "byokit never adds Claude plan sign-in",
-        "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)"
+        "reason": "Token import is not the native Claude Code login route; direct Claude.ai OAuth remains excluded.",
+        "source": "dist/extensions/anthropic/openclaw.plugin.json (2026.8.1)",
+        "auth": "token",
+        "terms": "grey",
+        "termsUrl": "https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use"
     },
     {
         "choice": "sglang",

package/dist/runs.js

@@ -1,6 +1,7 @@
 // Runs: one Gateway run per spec, streamed through typed events, ending in a classified RunEnd (5.8, O8).
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
+import { authStatus } from "./auth-status.js";
 import { classify } from "./classify.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;
@@ -125,7 +126,7 @@ export function createRuns(ctx) {
                 // 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.
-                const status = (refresh) => ctx.request('models.authStatus', { agentId, ...(refresh ? { refresh: true } : {}) });
+                const status = (refresh) => authStatus(ctx.request, agentId, refresh, picked.provider === 'claude-cli');
                 let auth = await status(false);
                 if (auth.unavailable)
                     auth = await status(true); // no prepared snapshot yet: build it once

package/dist/signin.d.ts

@@ -1,4 +1,4 @@
-import type { GatewayTransport, Member, SignInView } from './types.ts';
+import type { GatewayTransport, Member, SignInOptions, SignInView } from './types.ts';
 export type SignInCtx = {
     request: GatewayTransport['request'];
     ensure(member: Member): Promise<{
@@ -11,14 +11,11 @@ export type SignInCtx = {
  * `paste` hands a returned browser address to a waiting wizard text step. Every exit short of done cancels this
  * session and its callback listener only.
  */
-export declare function signIn(ctx: SignInCtx, member: Member, o: {
-    authChoice: string;
-    via?: 'browser' | 'code';
-}, on: (v: SignInView) => void): {
+export declare function signIn(ctx: SignInCtx, member: Member, o: SignInOptions, on: (v: SignInView) => void): {
     paste(text: string): void;
     cancel(): void;
     done: Promise<SignInView>;
 };
-/** The providers this member's engine reports as signed in, from `models.authStatus` (a string or `{ provider }`). */
+/** Usable provider profiles plus native Claude Code readiness reported by the engine. */
 export declare function providers(ctx: SignInCtx, member: Member, refresh?: boolean): Promise<string[]>;
 export declare function signOut(ctx: SignInCtx, member: Member, provider: string): Promise<void>;

package/dist/signin.js

@@ -1,7 +1,9 @@
 // Sign-in: the kit drives OpenClaw's own setup wizard loop and holds the ChatGPT callback port during a browser
-// sign-in; credentials never pass through kit or app (D11, 5.7).
+// 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 { authStatus } from "./auth-status.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}
 // and never carries a step), and one session at a time holds the gateway's single setup admission.
@@ -31,6 +33,18 @@ export function signIn(ctx, member, o, on) {
     let settleStart;
     const startingSettled = new Promise((resolve) => { settleStart = resolve; });
     let over = false;
+    let approval = false;
+    let sawDeviceCode = false;
+    let codeExpired = false;
+    let codeTimer;
+    const stopApproval = () => {
+        approval = false;
+        if (codeTimer)
+            clearTimeout(codeTimer);
+        codeTimer = undefined;
+    };
+    const cancelled = () => ({ state: 'failed', via, why: 'declined', error: words('signin.cancelled') });
+    const expired = () => ({ state: 'failed', via, why: 'expired', error: words('signin.expired') });
     let settle;
     let pasteIn;
     let returned;
@@ -46,7 +60,11 @@ export function signIn(ctx, member, o, on) {
         if (over)
             return;
         over = true;
+        stopApproval();
+        o.signal?.removeEventListener('abort', cancel);
         owner.abort();
+        returned = undefined;
+        pasteIn = undefined;
         await closeCallback();
         on(view);
         settle(view);
@@ -63,6 +81,8 @@ export function signIn(ctx, member, o, on) {
         return releasing;
     };
     const paste = (text) => {
+        if (over)
+            return;
         if (pasteIn)
             pasteIn(text);
         else
@@ -71,9 +91,14 @@ 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.
+        if (signal.aborted)
+            return;
         owner.abort();
-        void (async () => { await release(); await finish({ state: 'failed', via, why: 'declined' }); })();
+        void (async () => { await release(); await finish(cancelled()); })();
     };
+    o.signal?.addEventListener('abort', cancel, { once: true });
+    if (o.signal?.aborted)
+        cancel();
     /** Hold 127.0.0.1:<callbackPort> for the sign-in's life; a taken port is why the sign-in cannot start. */
     const holdCallback = () => {
         let took = false;
@@ -111,8 +136,42 @@ export function signIn(ctx, member, o, on) {
                 return { state: 'failed', via, why: 'busy' };
         }
         const { agentId } = await ctx.ensure(member);
-        // The session id is the client's to choose (5.7), and the start request carries no abort signal: the engine
-        // registers the session as it settles, so a cancel waits for it (release) rather than racing it.
+        // 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') {
+            settleStart();
+            let apiKey;
+            if (o.authChoice === 'anthropic-cli') {
+                const detected = await ctx.request('openclaw.setup.detect', { agentId }, { timeoutMs: STATUS_MS });
+                if (!detected.candidates?.some((candidate) => candidate.kind === 'claude-cli' && candidate.credentials === true))
+                    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)' });
+                apiKey = returned ?? await new Promise((resolve) => {
+                    const stop = (value) => { clearTimeout(timer); signal.removeEventListener('abort', abort); pasteIn = undefined; resolve(value); };
+                    const abort = () => stop();
+                    const timer = setTimeout(abort, PASTE_MS);
+                    pasteIn = stop;
+                    signal.addEventListener('abort', abort, { once: true });
+                    if (signal.aborted)
+                        abort();
+                });
+                returned = undefined;
+                if (!apiKey)
+                    return { state: 'failed', via, why: signal.aborted ? 'declined' : 'expired' };
+            }
+            if (signal.aborted)
+                return { state: 'failed', via, why: 'declined' };
+            const result = await ctx.request('openclaw.setup.activate', {
+                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' };
+        }
+        // The client chooses the wizard id; cancellation waits for the engine to register it.
         sessionId = `byokit-${randomUUID()}`;
         let started;
         try {
@@ -125,8 +184,9 @@ export function signIn(ctx, member, o, on) {
         if (started.done)
             return { state: 'done', via };
         // wizard.next, never wizard.status: the status method answers {status, error} and carries no step.
-        const pull = () => ctx.request('wizard.next', { sessionId }, pullOptions(signal));
-        const answer = (step, value) => ctx.request('wizard.next', { sessionId, answer: { stepId: step.id, ...(value === undefined ? {} : { value }) } }, pullOptions(signal));
+        const options = () => approval ? { timeoutMs: null, signal } : pullOptions(signal);
+        const pull = () => ctx.request('wizard.next', { sessionId }, options());
+        const answer = (step, value) => ctx.request('wizard.next', { sessionId, answer: { stepId: step.id, ...(value === undefined ? {} : { value }) } }, options());
         const waitForPaste = () => new Promise((resolve) => {
             if (returned !== undefined) {
                 const text = returned;
@@ -166,6 +226,16 @@ export function signIn(ctx, member, o, on) {
             const current = step;
             step = undefined;
             if (current.deviceCode) {
+                stopApproval();
+                approval = true;
+                sawDeviceCode = true;
+                // The pin converts its provider duration to minutes. Prefer exact seconds if the engine supplies them.
+                const duration = current.deviceCode.expires_in !== undefined
+                    ? Number(current.deviceCode.expires_in) * 1_000
+                    : Number(current.deviceCode.expiresInMinutes) * 60_000;
+                if (Number.isFinite(duration) && duration >= 0) {
+                    codeTimer = setTimeout(() => { codeExpired = true; owner.abort(); }, duration);
+                }
                 // The code is on the card; acknowledging it lets the engine poll the provider itself.
                 say({ ...(current.deviceCode.code ? { code: current.deviceCode.code } : {}), ...(current.externalUrl ? { url: current.externalUrl } : {}) });
                 const next = await answer(current);
@@ -176,10 +246,12 @@ export function signIn(ctx, member, o, on) {
                 step = next.step;
                 continue;
             }
+            if (current.type !== 'progress')
+                stopApproval();
             if (current.type === 'text' && !current.sensitive) {
                 const value = await waitForPaste();
                 if (value === undefined)
-                    return { state: 'failed', via, why: signal.aborted ? 'declined' : 'expired' };
+                    return signal.aborted ? cancelled() : expired();
                 const next = await answer(current, value);
                 if (next.done) {
                     terminal = next;
@@ -212,10 +284,12 @@ export function signIn(ctx, member, o, on) {
             step = next.step;
         }
         if (signal.aborted)
-            return { state: 'failed', via, why: 'declined' };
+            return codeExpired ? expired() : cancelled();
         if (!terminal)
             return { state: 'failed', via, why: 'expired' };
         const error = String(terminal.error ?? (terminal.status === 'error' ? 'Sign-in failed' : ''));
+        if (sawDeviceCode && /expired_token|code.*expired|device.*(?:expired|timed out)/i.test(error))
+            return expired();
         return error ? { state: 'failed', via, why: 'failed', error: cut(error) } : { state: 'done', via };
     };
     void (async () => {
@@ -225,11 +299,13 @@ export function signIn(ctx, member, o, on) {
         }
         catch (error) {
             if (signal.aborted)
-                view = { state: 'failed', via, why: 'declined' };
+                view = codeExpired ? expired() : cancelled();
+            else if (sawDeviceCode && /expired_token|code.*expired|device.*(?:expired|timed out)/i.test(cut(error)))
+                view = expired();
             else if (BUSY.test(cut(error)))
                 view = { state: 'failed', via, why: 'busy' };
             else
-                view = { state: 'failed', via, why: 'failed', error: cut(error) };
+                view = { state: 'failed', via, why: 'failed', error: o.authChoice === 'apiKey' ? 'API key activation failed' : cut(error) };
         }
         settleStart();
         if (view.state !== 'done')
@@ -238,12 +314,10 @@ export function signIn(ctx, member, o, on) {
     })();
     return { paste, cancel, done };
 }
-/** The providers this member's engine reports as signed in, from `models.authStatus` (a string or `{ provider }`). */
+/** Usable provider profiles plus native Claude Code readiness reported by the engine. */
 export async function providers(ctx, member, refresh) {
     const { agentId } = await ctx.ensure(member);
-    const status = await ctx.request('models.authStatus', { agentId, ...(refresh ? { refresh: true } : {}) }, { timeoutMs: STATUS_MS });
-    const names = (status?.providers ?? []).map((entry) => (typeof entry === 'string' ? entry : entry?.provider));
-    return [...new Set(names.filter((name) => typeof name === 'string' && name !== ''))];
+    return signedInProviders(await authStatus(ctx.request, agentId, refresh, true)) ?? [];
 }
 export async function signOut(ctx, member, provider) {
     const { agentId } = await ctx.ensure(member);

package/dist/types.d.ts

@@ -83,11 +83,17 @@ export type RunEnd = {
     until?: number;
     message: string;
 };
+export type SignInOptions = {
+    authChoice: string;
+    via?: 'browser' | 'code';
+    signal?: AbortSignal;
+};
 export type SignInView = {
     state: 'waiting' | 'done' | 'failed';
     via: 'browser' | 'code';
     url?: string;
     code?: string;
+    prompt?: string;
     error?: string;
     why?: 'busy' | 'declined' | 'expired' | 'failed';
 };
@@ -108,7 +114,7 @@ export type Decision = {
     answer?: unknown;
 };
 export type KitState = {
-    phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update';
+    phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
     why?: 'install' | 'handshake' | 'exited' | 'port' | 'version';
     retryAt?: number;
 };
@@ -125,6 +131,9 @@ export type Route = {
     provider: string;
     plugin: string;
     billing: 'subscription' | 'api' | 'local';
+    auth?: 'cli' | 'api_key' | 'token';
+    terms?: 'allowed' | 'grey';
+    termsUrl?: string;
     via: 'browser' | 'code';
     prerequisite: string | null;
     offer: boolean;
@@ -134,7 +143,7 @@ export type Route = {
 export interface GatewayTransport {
     start(): Promise<Hello>;
     request(method: string, params?: unknown, o?: {
-        timeoutMs?: number;
+        timeoutMs?: number | null;
         signal?: AbortSignal;
         expectFinal?: boolean;
         onAccepted?: (payload: unknown) => void;
@@ -147,7 +156,7 @@ export interface GatewayTransport {
     stop(): Promise<void>;
 }
 export type CallOptions = {
-    timeoutMs?: number;
+    timeoutMs?: number | null;
     signal?: AbortSignal;
 };
 export type { GatewayMethod, GatewayParams, GatewayResult } from './generated/methods.ts';

package/dist/words.js

@@ -14,6 +14,7 @@ const PHASE_WORDS = {
     ready: 'engine.ready',
     restarting: 'engine.restarting',
     failed: 'engine.failed',
+    locked: 'engine.locked',
     'needs-update': 'engine.needsUpdate',
 };
 export function stateWords(s) {

package/dist/words.json

@@ -2,6 +2,7 @@
     "engine.installing": "Getting things ready on this computer. The first time takes a few minutes.",
     "engine.starting": "Starting up…",
     "engine.repairing": "Fixing a small problem with the setup. This takes a moment.",
+    "engine.locked": "Your saved sign-in is locked. Unlock your password storage, then try again.",
     "engine.ready": "Ready.",
     "engine.restarting": "Something stopped. Starting it again by itself.",
     "engine.failed": "This computer couldn't start the helper. Restart the app to try again.",
@@ -12,6 +13,7 @@
     "member.network": "Can't reach {name} right now. This keeps trying by itself.",
     "signin.returned": "Thanks. Finishing the sign-in — you can go back to the app now.",
     "signin.busy": "Another sign-in is already in progress. Finish or cancel it, then try again.",
+    "signin.cancelled": "Sign-in cancelled. You can start again whenever you are ready.",
     "signin.expired": "The sign-in took too long. Start it again.",
     "approval.ask": "{helper} wants to {summary}. Allow it?",
     "approval.expired": "Nobody answered in time, so this wasn't allowed.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -56,7 +56,7 @@
     "@byokit/relay": "0.4.2",
     "@byokit/reach": "0.4.0",
     "@byokit/seal": "0.2.0",
-    "@byokit/secrets": "0.4.0",
+    "@byokit/secrets": "0.5.0",
     "@openclaw/gateway-client": "2026.8.1",
     "@openclaw/gateway-protocol": "2026.8.1",
     "ws": "8.21.3"