@byokit/openclaw 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.3.5 (2026-10-01)
+
+
+
+- FIX: Failed engine starts no longer remove another live gateway’s guards or saved sign-in state. Verified dead-host gateways stop gracefully before restart; ambiguous ownership returns a typed engine-already-running error and preserves the store.
+
+## 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.

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));
@@ -217,7 +232,14 @@ before any restoration; a wrong key, tampering, or a missing adapter rejects. Fi
 have mode 0600 and directories 0700. File symlinks are sealed only when their fully resolved targets are
 regular files inside the isolated engine root; they restore as regular files at the link paths. Outside-root,
 dangling and directory symlinks (including loops), sockets, FIFOs and devices are skipped.
-One kit owns the store at a time; a live owner or orphan gateway blocks preparation instead of racing its writes.
+One kit owns the store at a time. After a host crash, preparation stops a verified same-user gateway
+only when its host lock owner is dead, waits up to three seconds for exit, then seals and restores the
+leftover state under the acquired lock. If process identity is ambiguous (including unavailable process
+inspection or a rewritten command line), another host is alive, or shutdown times out, `prepare()` and
+`start()` reject with exported `EngineAlreadyRunningError` (`code: 'engine-already-running'`). The kit reports
+`{ phase: 'failed', why: 'engine-already-running' }`; show `stateWords(kit.state)` and retry after the other
+session stops. Failed-start cleanup and `stop()` on an instance with no ownership preserve the other
+writer's pid, lock, sealed snapshot and live state.
 Sealing copies the whole store through memory, so startup and stop cost grows with session history.
 
 The migration doctor temporarily opens the same store and reseals it even when import fails. Once the gateway
@@ -259,3 +281,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/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

@@ -2,20 +2,10 @@
 // Seal the complete isolated stores, including journals, only after their writer has exited.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { EngineAlreadyRunningError, pidAlive as live } from "./engine-status.js";
 const encoder = new TextEncoder();
 const archive = (name) => /^(auth-profiles|auth-state|auth|oauth)\.json\.(migrated-.+|sqlite-import\..+\.bak)$/.test(name)
     || name.endsWith('.moved-to-engine');
-const live = (pid) => {
-    if (!Number.isSafeInteger(pid) || pid < 1)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code !== 'ESRCH';
-    }
-};
 function regular(path) {
     if (!lstatSync(path).isFile())
         throw new Error(`credential store requires regular files: ${path}`);
@@ -108,18 +98,16 @@ export class AuthStore {
             return;
         if (existsSync(this.file) && !this.o.seal)
             throw new Error('authSeal required for sealed credential store');
-        if (!this.o.seal)
-            return;
         // Never race a live gateway or another kit, including an orphan after its host crashed.
         const gateway = join(this.o.root, 'gateway.pid');
         if (existsSync(gateway) && live(Number(readFileSync(gateway, 'utf8'))))
-            throw new Error('credential store is in use');
+            throw new EngineAlreadyRunningError();
         if (existsSync(this.lock)) {
             if (!lstatSync(this.lock).isDirectory() || lstatSync(this.lock).isSymbolicLink())
                 throw new Error('invalid credential lock');
             const owner = join(this.lock, 'pid');
             if (!existsSync(owner) || live(Number(readFileSync(owner, 'utf8'))))
-                throw new Error('credential store is in use');
+                throw new EngineAlreadyRunningError();
             // Only one stale-owner recovery can proceed. Recheck after claiming it so a stale reader
             // cannot remove the lock a newer owner has just acquired.
             const recovery = join(this.lock, 'recovery');
@@ -127,17 +115,36 @@ export class AuthStore {
                 mkdirSync(recovery, { mode: 0o700 });
             }
             catch {
-                throw new Error('credential store is in use');
+                throw new EngineAlreadyRunningError();
             }
             if (!existsSync(owner) || live(Number(readFileSync(owner, 'utf8')))) {
                 rmSync(recovery, { recursive: true });
-                throw new Error('credential store is in use');
+                throw new EngineAlreadyRunningError();
             }
             rmSync(this.lock, { recursive: true });
         }
-        mkdirSync(this.lock, { mode: 0o700 });
-        writeFileSync(join(this.lock, 'pid'), String(process.pid), { mode: 0o600, flag: 'wx' });
+        try {
+            mkdirSync(this.lock, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                throw new EngineAlreadyRunningError();
+            throw error;
+        }
         this.owned = true;
+        try {
+            writeFileSync(join(this.lock, 'pid'), String(process.pid), { mode: 0o600, flag: 'wx' });
+            // Recheck under the acquired lock before removing a dead writer's guard.
+            if (existsSync(gateway)) {
+                if (live(Number(readFileSync(gateway, 'utf8'))))
+                    throw new EngineAlreadyRunningError();
+                removeMarker(gateway);
+            }
+        }
+        catch (error) {
+            this.release();
+            throw error;
+        }
     }
     release() {
         if (!this.owned)
@@ -297,7 +304,8 @@ export class AuthStore {
     }
     stop() {
         return this.serial(async () => {
-            this.acquire();
+            if (!this.owned)
+                return;
             await this.archives();
             await this.persist();
             this.active = false;

package/dist/engine-status.d.ts

@@ -0,0 +1,6 @@
+/** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
+export declare class EngineAlreadyRunningError extends Error {
+    readonly code = "engine-already-running";
+    constructor();
+}
+export declare function pidAlive(pid: number): boolean;

package/dist/engine-status.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+/** A live or unverifiable writer still owns the isolated engine state. Retry after it stops. */
+export class EngineAlreadyRunningError extends Error {
+    code = 'engine-already-running';
+    constructor() {
+        super('engine already running; credential store is in use');
+        this.name = 'EngineAlreadyRunningError';
+    }
+}
+export function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return true; // An invalid guard is ambiguous, never stale.
+    try {
+        process.kill(pid, 0);
+        // An orphan can remain a zombie until its new parent reaps it; it has no writer left.
+        if (process.platform === 'linux') {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            if (stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z '))
+                return false;
+        }
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}

package/dist/engine.d.ts

@@ -36,7 +36,8 @@ export declare class Engine {
     doctor(timeoutMs: number): {
         status: number | null;
     };
-    private stalePid;
+    private verifiedOrphan;
+    private recoverOrphan;
     start(): Promise<{
         port: number;
         token: string;
@@ -45,6 +46,7 @@ export declare class Engine {
     private locked;
     private startOnce;
     private launch;
+    private removeOwnedPid;
     withAuthStore<T>(task: () => Promise<T>): Promise<T>;
     stop(): Promise<void>;
 }

package/dist/engine.js

@@ -1,11 +1,12 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes, generateKeyPairSync } from 'node:crypto';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { AuthStore } from "./auth-store.js";
+import { EngineAlreadyRunningError, pidAlive } from "./engine-status.js";
 import { ENGINE_VERSION } from "./constants.js";
 import { reconcileConfig } from "./config.js";
 import { writePlugin, resolveBridge } from "./bridge.js";
@@ -93,6 +94,7 @@ export class Engine {
     async prepareOnce() {
         if (!this.o.authSeal && existsSync(join(this.root, 'auth-store.sealed')))
             throw new Error('authSeal required for sealed credential store');
+        await this.recoverOrphan();
         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 });
         try {
@@ -168,19 +170,67 @@ export class Engine {
         const result = spawnSync(process.execPath, [entry, 'doctor', '--fix', '--yes', '--non-interactive'], { cwd: env.HOME, env, timeout: timeoutMs, stdio: 'pipe' });
         return { status: result.status };
     }
-    stalePid() {
+    verifiedOrphan(pid) {
+        if (process.platform !== 'linux' || !process.getuid)
+            return false;
+        try {
+            const proc = `/proc/${pid}`;
+            const cmd = readFileSync(`${proc}/cmdline`, 'utf8').split('\0');
+            const env = readFileSync(`${proc}/environ`, 'utf8').split('\0');
+            const home = join(this.root, 'home');
+            const owner = join(this.root, 'auth-store.lock', 'pid');
+            return statSync(proc).uid === process.getuid()
+                && realpathSync(`${proc}/exe`) === realpathSync(process.execPath)
+                && cmd.indexOf(this.entry) > 0 && cmd[cmd.indexOf(this.entry) + 1] === 'gateway'
+                && realpathSync(`${proc}/cwd`) === realpathSync(home)
+                && env.includes(`HOME=${home}`)
+                && env.includes(`OPENCLAW_STATE_DIR=${join(this.root, 'state')}`)
+                && env.includes(`OPENCLAW_CONFIG_PATH=${join(this.root, 'openclaw.json')}`)
+                && existsSync(owner) && !pidAlive(Number(readFileSync(owner, 'utf8')));
+        }
+        catch {
+            return false;
+        }
+    }
+    async recoverOrphan() {
+        if (this.child && this.child.exitCode === null && this.child.signalCode === null)
+            return;
         const path = join(this.root, 'gateway.pid');
         if (!existsSync(path))
             return;
         const pid = Number(readFileSync(path, 'utf8'));
-        if (!Number.isSafeInteger(pid) || pid < 1)
-            return;
+        if (!pidAlive(pid))
+            return; // AuthStore removes stale guards only under its lock.
+        const occupied = () => { this.state('failed', 'engine-already-running'); return new EngineAlreadyRunningError(); };
+        if (!this.verifiedOrphan(pid))
+            throw occupied();
+        // Verify a stable process identity again immediately before signalling this pid, never its group.
+        const identity = () => {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]; // starttime, not a reusable pid alone
+        };
+        try {
+            const before = identity();
+            if (!before || !this.verifiedOrphan(pid) || before !== identity())
+                throw occupied();
+        }
+        catch {
+            if (!pidAlive(pid))
+                return;
+            throw occupied();
+        }
         try {
-            const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
-            if (cmd.includes(this.entry) && cmd.includes('gateway'))
-                process.kill(-pid, 'SIGTERM');
+            process.kill(pid, 'SIGTERM');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw occupied();
         }
-        catch { /* pid is gone or not ours */ }
+        for (let i = 0; i < 15 && pidAlive(pid); i++)
+            await delay(200);
+        if (pidAlive(pid))
+            throw occupied();
+        // The new store owner now seals crash leftovers under its lock before restoring them.
     }
     start() {
         if (this.starting)
@@ -215,7 +265,9 @@ export class Engine {
             return this.launch();
         }
         catch (error) {
-            await this.authStore.stop();
+            // A launch failure after spawn still has a writer; the caller's stop must await its exit.
+            if (!this.child)
+                await this.authStore.stop();
             throw error;
         }
     }
@@ -229,7 +281,6 @@ export class Engine {
             return { port: this.port, token: this.token, identityPath };
         if (this.child && this.child.exitCode === null)
             return { port: this.port, token: this.token, identityPath };
-        this.stalePid();
         this.state('starting');
         const { entry, env } = this.doctorContext();
         const fd = openSync(join(this.o.stateDir, 'logs', 'openclaw.log'), 'a', 0o600);
@@ -255,7 +306,7 @@ export class Engine {
             if (this.child !== child || this.stopping)
                 return;
             this.child = undefined;
-            rmSync(join(this.root, 'gateway.pid'), { force: true });
+            this.removeOwnedPid(child.pid);
             void (async () => {
                 await this.authStore.stop();
                 if (this.stopping)
@@ -275,6 +326,11 @@ export class Engine {
         });
         return { port: this.port, token: this.token, identityPath };
     }
+    removeOwnedPid(pid) {
+        const path = join(this.root, 'gateway.pid');
+        if (pid && existsSync(path) && readFileSync(path, 'utf8') === String(pid))
+            rmSync(path, { force: true });
+    }
     withAuthStore(task) { return this.authStore.offline(task); }
     async stop() {
         this.stopping = true;
@@ -299,10 +355,9 @@ export class Engine {
         if (child && child.exitCode === null && child.signalCode === null)
             throw new Error('engine did not stop; credential store still in use');
         this.child = undefined;
-        rmSync(join(this.root, 'gateway.pid'), { force: true });
+        this.removeOwnedPid(child?.pid);
         if (!this.credentialsLocked)
             await this.authStore.stop();
-        rmSync(this.bridgeSock, { force: true });
         this.state('stopped');
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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';
+export { EngineAlreadyRunningError } from './engine-status.ts';

package/dist/index.js

@@ -3,3 +3,4 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from "./constants.js";
 export { OpenClawKit } from "./kit.js";
 export { stateWords, toAccountView, words } from "./words.js";
+export { EngineAlreadyRunningError } from "./engine-status.js";

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

@@ -503,6 +503,10 @@ export class OpenClawKit {
             if (transport && this.transport === transport)
                 await this.disconnect();
             await this.engine.stop();
+            if (error instanceof Error && 'code' in error && error.code === 'engine-already-running') {
+                this.setState({ phase: 'failed', why: 'engine-already-running' });
+                throw error;
+            }
             if (needsUpdate)
                 this.setState({ phase: 'needs-update', why: 'version' });
             if (!needsUpdate && !this.stopping)

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

@@ -6,5 +6,5 @@ import type { Route } from './types.ts';
  *  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

@@ -10,7 +10,7 @@ const table = routesJson;
 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": "Requires an explicit app opt-in; the pinned Gateway does not expose this plan route",
-        "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 key (billed per use); shown only when an app explicitly asks.",
-        "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": "Requires an explicit app opt-in; the pinned Gateway does not expose this plan route",
-        "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';
 };
@@ -109,7 +115,7 @@ export type Decision = {
 };
 export type KitState = {
     phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
-    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running';
     retryAt?: number;
 };
 export type Hello = {
@@ -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

@@ -19,6 +19,8 @@ const PHASE_WORDS = {
 };
 export function stateWords(s) {
     // 'stopped' is never on screen (4.3 covers what a person can see), so 5.14 has no row for it.
+    if (s.phase === 'failed' && s.why === 'engine-already-running')
+        return words('engine.alreadyRunning');
     return s.phase === 'stopped' ? '' : words(PHASE_WORDS[s.phase]);
 }
 export function toAccountView(view, ready) {

package/dist/words.json

@@ -5,6 +5,7 @@
     "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.alreadyRunning": "Your saved sign-in is in use. Try again after the other session stops.",
     "engine.failed": "This computer couldn't start the helper. Restart the app to try again.",
     "engine.needsUpdate": "This app needs an update to keep working.",
     "member.signedOut": "Sign in with {name} to start.",
@@ -13,6 +14,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.3",
+  "version": "0.3.5",
   "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",