@byokit/openclaw 0.13.0 → 0.14.0

package/dist/auth-store.d.ts

@@ -53,6 +53,8 @@ export declare class AuthStore {
      *  and in `home` exactly the sealed paths — regenerable caches and the directories still holding them are left in place. */
     private remove;
     private sealObjects;
+    /** Re-attach held-back sealed paths a damaged index kept out of the live inventory. */
+    private mergeHeldBack;
     private persist;
     /** `mkdir -p` for a restore target that records the parent of every directory it creates: a new directory
      *  changes its parent's entries, so the parent needs a directory fsync too. Stops at the store root (it exists)

package/dist/auth-store.js

@@ -8,7 +8,8 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import { createHash } from 'node:crypto';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { EngineAlreadyRunningError, pidAlive as live } from "./engine-status.js";
-import { removedAccountAgents, sweepOrphans } from "./accounts.js";
+import { damagedAccountMembers, heldBackAgent, removedAccountAgents, sweepOrphans } from "./accounts.js";
+const agentDirOf = (path) => path.startsWith('state/agents/') ? path.split('/')[2] : undefined;
 const encoder = new TextEncoder();
 const archive = (name) => !name.endsWith('.sealed') && (/^(auth-profiles|auth-state|auth|oauth)\.json\.(migrated-.+|sqlite-import\..+\.bak)$/.test(name)
     || name.endsWith('.moved-to-engine'));
@@ -322,8 +323,12 @@ export class AuthStore {
         catch {
             throw new AuthStoreUnreadableError('invalid-snapshot');
         }
+        // Removed agents leave the sealed store; damaged-index agents stay sealed (held back) until their index is repaired.
         const gone = removedAccountAgents(this.o.root);
-        const keep = (path) => !path.startsWith('state/agents/') || !gone.has(path.split('/')[2]);
+        const keep = (path) => {
+            const agent = agentDirOf(path);
+            return agent === undefined || !gone.has(agent);
+        };
         const kept = { v: 1, dirs: saved.dirs.filter(keep), files: saved.files.filter(([path]) => keep(path)) };
         if (kept.dirs.length !== saved.dirs.length || kept.files.length !== saved.files.length) {
             this.seal(this.file, JSON.stringify(kept));
@@ -375,10 +380,16 @@ export class AuthStore {
         let total = 0;
         const root = realpathSync(this.o.root);
         const gone = removedAccountAgents(this.o.root);
+        const damaged = damagedAccountMembers(this.o.root);
         const walk = (path) => {
             const name = relative(this.o.root, path).split('\\').join('/');
-            if (name.startsWith('state/agents/') && gone.has(name.split('/')[2]))
-                return; // a late refresh never enters a seal
+            if (name.startsWith('state/agents/')) {
+                const agent = name.split('/')[2];
+                if (gone.has(agent))
+                    return; // a late refresh never enters a seal
+                if (heldBackAgent(agent, damaged))
+                    return; // damaged index: leave sealed copy; never reseal a late live write
+            }
             if (name.startsWith('home/') && nonCredential(name))
                 return; // regenerable home caches stay on disk; skipping a directory skips its subtree
             let stat;
@@ -449,7 +460,7 @@ export class AuthStore {
         return { dirs, files, objects };
     }
     collect() {
-        sweepOrphans(this.o.root);
+        sweepOrphans(this.o.root, this.o.log);
         const { dirs, files, objects } = this.inventory();
         for (const dir of dirs) {
             try {
@@ -536,10 +547,48 @@ export class AuthStore {
             this.seal(target, payload);
             this.objectHashes.set(object, hash);
         }
+        // Held-back agent objects stay sealed while their index is damaged (inventory skipped their live trees).
+        const damaged = damagedAccountMembers(this.o.root);
+        if (damaged.size) {
+            for (const entry of readdirSync(this.objects)) {
+                if (keep.has(entry))
+                    continue;
+                try {
+                    const agent = agentDirOf(this.readObject(join(this.objects, entry))[0]);
+                    if (agent !== undefined && heldBackAgent(agent, damaged))
+                        keep.add(entry);
+                }
+                catch { /* unreadable object: leave for the next start's auth-store check */ }
+            }
+        }
         for (const entry of readdirSync(this.objects))
             if (!keep.has(entry))
                 rmSync(join(this.objects, entry), { force: true });
     }
+    /** Re-attach held-back sealed paths a damaged index kept out of the live inventory. */
+    mergeHeldBack(previous, saved) {
+        if (!previous)
+            return;
+        const damaged = damagedAccountMembers(this.o.root);
+        if (!damaged.size)
+            return;
+        const held = (path) => {
+            const agent = agentDirOf(path);
+            return agent !== undefined && heldBackAgent(agent, damaged);
+        };
+        const dirs = new Set(saved.dirs);
+        for (const dir of previous.dirs)
+            if (held(dir) && !dirs.has(dir)) {
+                saved.dirs.push(dir);
+                dirs.add(dir);
+            }
+        const files = new Set(saved.files.map(([path]) => path));
+        for (const entry of previous.files)
+            if (held(entry[0]) && !files.has(entry[0])) {
+                saved.files.push(entry);
+                files.add(entry[0]);
+            }
+    }
     async persist() {
         if (!this.o.seal)
             return;
@@ -557,6 +606,7 @@ export class AuthStore {
         // A running engine always leaves files behind (its SQLite stores), so a genuine sign-out still re-seals.
         if (!saved.files.length && !objects.length && previous)
             return;
+        this.mergeHeldBack(previous, saved);
         // The payload is built exactly once; verification decrypts the sealed bytes and compares to it.
         this.seal(this.file, JSON.stringify(saved));
         if (previous?.dirs.some(nonCredential))
@@ -582,14 +632,25 @@ export class AuthStore {
         if (!this.o.seal)
             return;
         const saved = await this.read();
+        const damaged = damagedAccountMembers(this.o.root);
+        const skipHeld = (path) => {
+            const agent = agentDirOf(path);
+            return agent !== undefined && heldBackAgent(agent, damaged);
+        };
         // A crashed host may leave a newer live state; prepare seals that before restore.
         put(this.restoring, encoder.encode('1'));
         const changed = new Set();
         if (saved) {
-            for (const dir of saved.dirs.sort((a, b) => a.split('/').length - b.split('/').length))
+            for (const dir of saved.dirs.sort((a, b) => a.split('/').length - b.split('/').length)) {
+                if (skipHeld(dir))
+                    continue;
                 this.ensureRestoreDirs(join(this.o.root, dir), changed);
-            for (const [path, data] of saved.files)
+            }
+            for (const [path, data] of saved.files) {
+                if (skipHeld(path))
+                    continue;
                 putRestore(join(this.o.root, path), Buffer.from(data, 'base64'), changed);
+            }
         }
         if (existsSync(this.objects)) {
             for (const entry of readdirSync(this.objects)) {
@@ -598,6 +659,8 @@ export class AuthStore {
                 // no hash, so the next seal reseals it in the current mode even when unchanged.
                 if (!this.o.seal.upgrade?.(bytes))
                     this.objectHashes.set(entry, objectHash(payload));
+                if (skipHeld(path))
+                    continue;
                 // An object path can be several directories below an existing one, and those directories are not in
                 // `saved.dirs` (they sit in a non-credential subtree). Create them through ensureRestoreDirs so the
                 // parent of every directory this restore creates — not just each object's own directory — is fsynced
@@ -667,7 +730,9 @@ export class AuthStore {
             // keeps the sealed credentials instead of replacing them with an empty snapshot.
             if (!saved.files.length && !objects.length && previous)
                 return;
+            this.mergeHeldBack(previous, saved);
             this.seal(this.file, JSON.stringify(saved));
+            // Database objects stay at their last stop-time seal; only the credential blob is refreshed here.
         });
     }
     start() {

package/dist/engine.d.ts

@@ -1,3 +1,4 @@
+import { remoteCliHost } from '@byokit/accounts/cli';
 import { AuthStore, AuthStoreSealSizeError } from './auth-store.ts';
 import type { KitOptions } from './kit.ts';
 import type { KitState, ToolSpec } from './types.ts';
@@ -28,6 +29,10 @@ export declare class Engine {
     private starting?;
     readonly authStore: AuthStore;
     private stopping;
+    private stopOwner;
+    private claudeLogin?;
+    private claudeAccounts?;
+    private claudeReset?;
     private credentialsLocked;
     private repaired;
     private prepared?;
@@ -49,6 +54,10 @@ export declare class Engine {
         entry: string;
         env: Record<string, string>;
     };
+    /** The engine's own shutdown signal; aborted by stop() and replaced by the next start(). */
+    get stopSignal(): AbortSignal;
+    nativeClaudeLogin(): ReturnType<typeof remoteCliHost>;
+    resetNativeClaudeLogin(): Promise<void>;
     doctor(timeoutMs: number): {
         status: number | null;
     };

package/dist/engine.js

@@ -1,10 +1,11 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes, generateKeyPairSync, randomUUID } from 'node:crypto';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } from 'node:fs';
+import { accessSync, constants, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, copyFileSync, rmSync, realpathSync, statSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { basename, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
+import { cliAccounts, remoteCliHost } from '@byokit/accounts/cli';
 import { AuthStore, AuthStoreUnreadableError, AuthStoreSealSizeError } from "./auth-store.js";
 import { EngineAlreadyRunningError, pidAlive, StartedProcesses } from "./engine-status.js";
 import { EnginePatchError, atomic, prepareEngineSet, processStartTime, readPatchSet, sha256, verifyEngineSet } from "./engine-patches.js";
@@ -76,6 +77,13 @@ export class Engine {
     starting;
     authStore;
     stopping = false;
+    // Aborted by stop(): a sign-in drive that has not reached its commit point then declines at once, the key paste
+    // included (it has no native host signal of its own). start() replaces it, so an earlier shutdown cannot decline
+    // a later drive.
+    stopOwner = new AbortController();
+    claudeLogin;
+    claudeAccounts;
+    claudeReset;
     credentialsLocked = false;
     repaired = false;
     prepared;
@@ -285,6 +293,42 @@ export class Engine {
                 BYOKIT_APP_OWNED_SESSION_PREFIXES: JSON.stringify(this.appOwnedSessionPrefixes),
             } };
     }
+    /** The engine's own shutdown signal; aborted by stop() and replaced by the next start(). */
+    get stopSignal() { return this.stopOwner.signal; }
+    nativeClaudeLogin() {
+        if (this.claudeLogin)
+            return this.claudeLogin;
+        const { env } = this.doctorContext();
+        const bin = env.PATH.split(':').map(path => join(path, 'claude')).find(path => { try {
+            accessSync(path, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        } });
+        const bins = bin ? { claude: bin } : {};
+        // The login runs in its own HOME: CLAUDE_CONFIG_DIR points it at the engine's folder, which accounts refuses as a HOME's default login.
+        for (const dir of ['home', 'login-home'])
+            mkdirSync(join(this.root, dir), { recursive: true, mode: 0o700 });
+        const cli = cliAccounts({ stateDir: this.root, bins, env: { PATH: env.PATH, HOME: join(this.root, 'login-home'), LANG: env.LANG, TMPDIR: env.TMPDIR, XDG_CONFIG_HOME: env.XDG_CONFIG_HOME, XDG_CACHE_HOME: env.XDG_CACHE_HOME, XDG_DATA_HOME: env.XDG_DATA_HOME, XDG_STATE_HOME: env.XDG_STATE_HOME, }, managedFolders: { claude: env.CLAUDE_CONFIG_DIR } });
+        this.claudeAccounts = cli;
+        this.claudeLogin = remoteCliHost({ cli, bins });
+        return this.claudeLogin;
+    }
+    resetNativeClaudeLogin() {
+        if (this.claudeReset)
+            return this.claudeReset;
+        const cli = this.claudeAccounts, host = this.claudeLogin;
+        if (!cli || !host || host.signal.aborted)
+            return Promise.resolve();
+        this.claudeReset = (async () => { for (const row of await cli.list()) {
+            if (host.signal.aborted)
+                return;
+            if (row.provider === 'claude' && row.state === 'ready' && cli.folderOf(row.id) === join(this.root, 'home', '.claude'))
+                await cli.remove(row.id);
+        } })().finally(() => { this.claudeReset = undefined; });
+        return this.claudeReset;
+    }
     doctor(timeoutMs) {
         const { entry, env } = this.doctorContext();
         if (this.o.spawnEngine)
@@ -355,11 +399,12 @@ export class Engine {
     }
     // The account orphan sweep (5.15): a late engine write after a removal cannot be ruled out by a bounded check, so
     // prepare and the sealed restore remove each `<root>/state/agents/<member>--<hex6>` directory a removal recorded as
-    // gone and no index names. No roster here: the gateway is down, and no add is in flight while preparing (an entry
-    // is written before its agent is created, so an account being added is named).
+    // gone and no index names, and drop member-store auth profiles a removal recorded as `dropped`. No roster here: the
+    // gateway is down, and no add is in flight while preparing (an entry is written before its agent is created, so an
+    // account being added is named).
     sweepAccountOrphans() {
         try {
-            sweepOrphans(this.root);
+            sweepOrphans(this.root, this.o.log);
         }
         catch (error) {
             this.o.log?.(`prepare: orphans are not swept: ${String(error.message).slice(0, 200)}`);
@@ -369,6 +414,7 @@ export class Engine {
         if (this.starting)
             return this.starting;
         this.stopping = false;
+        this.stopOwner = new AbortController();
         const pending = this.startOnce();
         this.starting = pending;
         void pending.finally(() => { if (this.starting === pending)
@@ -514,6 +560,11 @@ export class Engine {
     withAuthStore(task) { return this.authStore.offline(task); }
     async stop() {
         this.stopping = true;
+        this.stopOwner.abort();
+        await this.claudeLogin?.close();
+        await this.claudeReset?.catch(() => { });
+        this.claudeLogin = undefined;
+        this.claudeAccounts = undefined;
         await this.starting?.catch(() => { });
         const child = this.child;
         await this.started.terminate(delay);

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
-export type { AddKeyResult, KeyFailureReason } from './keys.ts';
+export type { AddKeyHandle, AddKeyResult, KeyFailureReason } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { chooseAccount, consider, resolveSelection, type RoomOf } from './pick.ts';
 export { AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.ts';

package/dist/keys.d.ts

@@ -1,4 +1,5 @@
 import { type ActivationCtx } from './activation.ts';
+import { type RouteView } from './routes.ts';
 import type { Member, ModelInfo } from './types.ts';
 export type KeyFailureReason = 'auth' | 'billing' | 'empty' | 'model' | 'network' | 'engine' | 'inference' | 'busy';
 export type AddKeyResult = {
@@ -7,6 +8,10 @@ export type AddKeyResult = {
     status: 'invalid' | 'not_included' | 'retry';
     reason: KeyFailureReason;
 };
+/** The add resolves like a Promise; `cancel()` stops a pending add and clears any partial key (retry/busy). */
+export type AddKeyHandle = Promise<AddKeyResult> & {
+    cancel(): void;
+};
 export declare function createKeys(ctx: ActivationCtx & {
     root: string;
     ensure(member: Member): Promise<{
@@ -14,6 +19,9 @@ export declare function createKeys(ctx: ActivationCtx & {
     }>;
     restarting?(): boolean;
     prepareOwner(agentId: string): Promise<void>;
+    indexLane(member: Member, route: RouteView): Promise<void>;
+    dropLane(member: Member, provider?: string): Promise<void>;
+    backfillLane(member: Member, model: string | undefined): Promise<void>;
 }): {
     models: (member: Member, o: {
         authChoice: string;
@@ -23,12 +31,15 @@ export declare function createKeys(ctx: ActivationCtx & {
         authChoice: string;
         apiKey: string;
         model?: string;
-    }): Promise<AddKeyResult>;
+    }): AddKeyHandle;
     ready(member: Member, o?: {
         once?: boolean;
     }): Promise<{
         agentId: string;
         model: string;
     } | undefined>;
-    sweep(): Promise<boolean>;
+    remove(member: Member, o?: {
+        provider?: string;
+    }): Promise<void>;
+    sweep(clear: boolean): Promise<boolean>;
 };

package/dist/keys.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { activate } from "./activation.js";
 import { keyAgentId, MEMBER_ID, KEY_PREFIX, untilListed } from "./members.js";
+import { providerOf } from "./pick.js";
 import { routes } from "./routes.js";
 import { modelsOf } from "./accounts.js";
 import { LIVE_CATALOGS } from "./constants.js";
@@ -73,62 +74,82 @@ export function createKeys(ctx) {
     return {
         models,
         exclusive,
-        async add(member, o) {
-            if (!check(member))
-                throw new Error('Choose your own member.');
-            if (!o.apiKey.trim())
-                return failure('invalid', 'empty');
-            const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
-            if (!route || (o.model !== undefined && !LIVE_CATALOGS.includes(route.provider)))
-                return failure('not_included', 'model');
-            return exclusive(member, async () => {
-                let sent = false;
-                // A key the engine may have taken but not sealed is cleared (prepare already emptied the agent); if the clear
-                // does not reach the engine, the key stays unsealed and unusable until the next key add or kit start, so runs
-                // fail closed.
-                const abandon = async (result) => {
-                    await control(member, 'clear').catch(() => undefined);
-                    return result;
-                };
-                try {
-                    await ctx.ensure(member);
-                    const agentId = keyAgentId(member);
-                    const list = await ctx.request('agents.list');
-                    if (!list.agents.some((a) => a.id === agentId))
-                        await ctx.request('agents.create', { name: agentId, workspace: join(ctx.root, 'key-workspaces', member) });
-                    // Creation answers before the runtime roster/owners publish, just as for ordinary members.
-                    await untilListed(ctx.request, agentId);
-                    if (!(await control(member, 'prepare', route.provider)).ok)
-                        return failure('retry', 'engine');
-                    // The public pin's typed API-key path, never a CLI-login import. Discard the engine's lines/errors.
-                    sent = true;
-                    const result = await activate(ctx, { kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey }, { timeoutMs: 180_000 });
-                    if (!result.ok && !result.late)
-                        return abandon(probeResult(result.status));
-                    if (result.late)
-                        return abandon(failure('retry', 'busy'));
-                    if (o.model !== undefined && !(await models(member, o)).some((m) => m.id === o.model && m.available))
-                        return abandon(failure('not_included', 'model'));
-                    // Prepare before publishing the ready marker: failed preparation remains unusable even if clear fails.
+        add(member, o) {
+            const ac = new AbortController();
+            const cancel = () => { if (!ac.signal.aborted)
+                ac.abort(); };
+            const done = (async () => {
+                if (!check(member))
+                    throw new Error('Choose your own member.');
+                if (!o.apiKey.trim())
+                    return failure('invalid', 'empty');
+                const route = routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
+                if (!route || (o.model !== undefined && !LIVE_CATALOGS.includes(route.provider)))
+                    return failure('not_included', 'model');
+                if (ac.signal.aborted)
+                    return failure('retry', 'busy');
+                return exclusive(member, async () => {
+                    let sent = false;
+                    // A key the engine may have taken but not sealed is cleared (prepare already emptied the agent); if the clear
+                    // does not reach the engine, the key stays unsealed and unusable until the next key add or kit start, so runs
+                    // fail closed.
+                    const abandon = async (result) => {
+                        await control(member, 'clear').catch(() => undefined);
+                        return result;
+                    };
+                    const cancelled = () => failure('retry', 'busy');
                     try {
-                        await ctx.prepareOwner(agentId);
+                        if (ac.signal.aborted)
+                            return cancelled();
+                        await ctx.ensure(member);
+                        const agentId = keyAgentId(member);
+                        const list = await ctx.request('agents.list');
+                        if (!list.agents.some((a) => a.id === agentId))
+                            await ctx.request('agents.create', { name: agentId, workspace: join(ctx.root, 'key-workspaces', member) });
+                        // Creation answers before the runtime roster/owners publish, just as for ordinary members.
+                        await untilListed(ctx.request, agentId);
+                        if (ac.signal.aborted)
+                            return cancelled();
+                        if (!(await control(member, 'prepare', route.provider)).ok)
+                            return failure('retry', 'engine');
+                        // The public pin's typed API-key path, never a CLI-login import. Discard the engine's lines/errors.
+                        sent = true;
+                        if (ac.signal.aborted)
+                            return abandon(cancelled());
+                        const result = await activate(ctx, { kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey }, { timeoutMs: 180_000, signal: ac.signal });
+                        if (ac.signal.aborted)
+                            return abandon(cancelled());
+                        if (!result.ok && !result.late)
+                            return abandon(probeResult(result.status));
+                        if (result.late)
+                            return abandon(failure('retry', 'busy'));
+                        if (o.model !== undefined && !(await models(member, o)).some((m) => m.id === o.model && m.available))
+                            return abandon(failure('not_included', 'model'));
+                        // Prepare before publishing the ready marker: failed preparation remains unusable even if clear fails.
+                        try {
+                            await ctx.prepareOwner(agentId);
+                        }
+                        catch {
+                            return abandon(failure('retry', 'engine'));
+                        }
+                        if (ac.signal.aborted)
+                            return abandon(cancelled());
+                        if (o.model !== undefined && LIVE_CATALOGS.includes(route.provider) && !(await registered(route.provider, o.model)))
+                            return abandon(failure('retry', 'model'));
+                        if (!(await control(member, 'seal', undefined, o.model)).ok)
+                            return abandon(failure('retry', 'engine'));
+                        await ctx.indexLane(member, route);
+                        return { status: 'ok' };
                     }
-                    catch {
-                        return abandon(failure('retry', 'engine'));
+                    catch (error) {
+                        const reason = errorReason(error, sent);
+                        if (sent)
+                            return abandon(failure('retry', reason));
+                        return failure('retry', reason);
                     }
-                    if (o.model !== undefined && LIVE_CATALOGS.includes(route.provider) && !(await registered(route.provider, o.model)))
-                        return abandon(failure('retry', 'model'));
-                    if ((await control(member, 'seal', undefined, o.model)).ok)
-                        return { status: 'ok' };
-                    return abandon(failure('retry', 'engine'));
-                }
-                catch (error) {
-                    const reason = errorReason(error, sent);
-                    if (sent)
-                        return abandon(failure('retry', reason));
-                    return failure('retry', reason);
-                }
-            });
+                });
+            })();
+            return Object.assign(done, { cancel });
         },
         async ready(member, o = {}) {
             if (!check(member))
@@ -147,11 +168,37 @@ export function createKeys(ctx) {
                 }
             }
         },
-        // Kit start calls this once the gateway is ready: a failed add whose abandon clear never reached the engine
-        // leaves an unsealed key with no ready marker, so drop it. A single ready read per key agent, no retries; an add
-        // in flight for that member is waited for. Only an absent marker is cleared; a refused read or clear (the gateway
-        // left ready) makes the sweep incomplete. Resolves true once every key agent was read.
-        async sweep() {
+        // Remove this member's saved key: the key agent's store and its ready marker, so the lane reads signed out and
+        // stays signed out, plus its `<provider>.key` index entry, so the accounts list stops naming the removed key.
+        // `provider` scopes it to the key actually saved for that provider (the member agent's own
+        // sign-out never reaches this lane), so signing out of one provider never drops another's key. A lane that reads
+        // not ready has nothing saved to remove; a refused read or clear is a typed refusal, never raw engine text.
+        // Serialized with adds and key runs like every other key change.
+        async remove(member, o = {}) {
+            if (!check(member))
+                throw new Error('Choose your own member.');
+            await exclusive(member, async () => {
+                const refused = () => { throw new Error('The key could not be removed.'); };
+                if (o.provider !== undefined) {
+                    // An unreadable lane cannot name its provider, so removal never guesses and risks another provider's key.
+                    const ready = await control(member, 'ready').catch(() => undefined);
+                    if (!ready)
+                        refused();
+                    else if (ready.ok !== true || providerOf(ready.model ?? '') !== o.provider)
+                        return;
+                }
+                const cleared = await control(member, 'clear').catch(() => undefined);
+                if (cleared?.ok !== true && cleared?.absent !== true)
+                    refused();
+                await ctx.dropLane(member, o.provider);
+            });
+        },
+        // Kit connect calls this once the gateway is ready: a failed add whose abandon clear never reached the engine
+        // leaves an unsealed key with no ready marker, so drop it (`clear`, until a sweep completes). A single ready read
+        // per key agent, no retries; an add in flight for that member is waited for. Only an absent marker is cleared; a
+        // refused read or clear (the gateway left ready) makes the sweep incomplete. A sealed lane is backfilled on every
+        // call. Resolves true once every key agent was read.
+        async sweep(clear) {
             let agents;
             try {
                 agents = (await ctx.request('agents.list')).agents;
@@ -168,7 +215,11 @@ export function createKeys(ctx) {
                     continue;
                 await exclusive(member, async () => {
                     const ready = await control(member, 'ready').catch(() => undefined);
-                    if (ready?.ok === true)
+                    if (ready?.ok === true) {
+                        await ctx.backfillLane(member, ready.model);
+                        return;
+                    }
+                    if (!clear)
                         return;
                     if (ready?.absent !== true) {
                         complete = false;

package/dist/kit.d.ts

@@ -1,5 +1,5 @@
 import type { SealingAdapter } from '@byokit/secrets';
-import { type AddKeyResult } from './keys.ts';
+import { type AddKeyHandle } from './keys.ts';
 import { type RouteView } from './routes.ts';
 import type { BrowserHost, BrowserOptions } from './browser.ts';
 import type { Account, AccountId, AccountPick, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, MoveResult, Room, RunEnd, RunEvent, RunRef, RunSelection, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ToolHost, ToolSpec } from './types.ts';
@@ -158,7 +158,16 @@ export declare class OpenClawKit {
         authChoice: string;
         apiKey: string;
         model?: string;
-    }): Promise<AddKeyResult>;
+    }): AddKeyHandle;
+    private indexKeyLane;
+    /** Remove this member's saved key (the `byokit-key-<member>` lane: its credential store and ready marker), so
+     * `signedIn` is false for it and a restart cannot revive it. `provider` removes only that provider's saved key;
+     * with no saved key the call resolves without doing anything. */
+    removeKey(member: Member, o?: {
+        provider?: string;
+    }): Promise<void>;
+    private dropKeyLane;
+    private backfillKeyLane;
     private prepareKeyOwner;
     private syncCatalogs;
     migrateRetainedLogin(member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;