@byokit/openclaw 0.11.1 → 0.13.0

package/dist/activation.d.ts

@@ -0,0 +1,17 @@
+import type { GatewayParams, GatewayTransport } from './types.ts';
+export type ActivationCtx = {
+    request: GatewayTransport['request'];
+    authConfig(): string;
+    restarted(authBefore: string | undefined, signal?: AbortSignal): Promise<boolean>;
+};
+export declare const LATE_RESTART = "The engine took too long to restart after this sign-in. Nothing was kept; try again.";
+export type Activation = {
+    ok: boolean;
+    late?: boolean;
+    status?: string;
+    error?: string;
+};
+export declare function activate(ctx: ActivationCtx, params: GatewayParams<'openclaw.setup.activate'>, o: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<Activation>;

package/dist/activation.js

@@ -0,0 +1,9 @@
+export const LATE_RESTART = 'The engine took too long to restart after this sign-in. Nothing was kept; try again.';
+export async function activate(ctx, params, o) {
+    const authBefore = ctx.authConfig();
+    // The request is never aborted by a cancel: its answer decides whether the engine kept the key, so cleanup waits for it.
+    const result = await ctx.request('openclaw.setup.activate', params, { timeoutMs: o.timeoutMs });
+    if (!result.ok)
+        return { ok: false, status: result.status, error: result.error };
+    return await ctx.restarted(authBefore, o.signal) ? { ok: true } : { ok: false, late: true };
+}

package/dist/approvals.d.ts

@@ -3,11 +3,13 @@ import type { Approval, Decision, GatewayTransport, Member } from './types.ts';
 export declare class Approvals {
     private readonly request;
     private readonly bridge;
+    private readonly memberOf;
     private readonly approvals;
     private readonly listeners;
     constructor(o: {
         request: GatewayTransport['request'];
         bridge: Pick<Bridge, 'resolveAsk'>;
+        memberOf: (ref: string) => Member | undefined;
     });
     handleEvent(e: {
         event: string;

package/dist/approvals.js

@@ -14,21 +14,19 @@ const REQUESTED = {
 const RESOLVED = new Set(['exec.approval.resolved', 'plugin.approval.resolved', 'question.resolved']);
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const asString = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
-const memberOfKey = (key) => {
-    const m = /^agent:([a-z][a-z0-9-]{0,31}):/.exec(key);
-    return m?.[1];
-};
 /**
- * Member attribution: the request detail's agent first, else the `agent:<member>:` session key (5.9). The real
+ * Member attribution: the request detail's agent first, else the `agent:<member>:` session key (5.9). An
+ * indexed `<member>--<hex6>` account agent attributes to `<member>` (5.15). The real
  * engine nests exec/plugin details under `request` (question events stay flat); unattributed approvals carry ''
  * so they can never match a member id (B2).
  */
-function attribute(payload) {
+function attribute(payload, memberOf) {
     const detail = isRecord(payload.request) ? payload.request : payload;
     const agent = asString(detail.agentId);
     const key = asString(detail.sessionKey);
-    const fromKey = key ? memberOfKey(key) : undefined;
-    const member = agent ?? fromKey ?? asString(detail.member) ?? '';
+    const fromAgent = agent ? memberOf(agent) : undefined;
+    const fromKey = key ? memberOf(key) : undefined;
+    const member = fromAgent ?? fromKey ?? asString(detail.member) ?? '';
     return { member, ...(key ? { sessionKey: key } : {}) };
 }
 /** Exec policy modes (`off|on-miss|always`) ride in `request.ask`; they are not something a person said (B8). */
@@ -58,11 +56,13 @@ function expiresOf(payload, fallbackMs) {
 export class Approvals {
     request;
     bridge;
+    memberOf;
     approvals = new Map();
     listeners = new Set();
     constructor(o) {
         this.request = o.request;
         this.bridge = o.bridge;
+        this.memberOf = o.memberOf;
     }
     handleEvent(e) {
         const payload = isRecord(e.payload) ? e.payload : {};
@@ -71,7 +71,7 @@ export class Approvals {
             const id = asString(payload.id) ?? randomBytes(12).toString('base64url');
             if (this.approvals.has(id))
                 return;
-            const { member, sessionKey } = attribute(payload);
+            const { member, sessionKey } = attribute(payload, this.memberOf);
             const detail = isRecord(payload.request) ? payload.request : payload;
             const now = Date.now();
             const approval = {

package/dist/attribution.d.ts

@@ -0,0 +1,3 @@
+import type { Member } from './types.ts';
+export declare function agentOf(ref: string): string | undefined;
+export declare function memberOf(ref: string): Member | undefined;

package/dist/attribution.js

@@ -0,0 +1,25 @@
+const MEMBER = /^[a-z][a-z0-9-]{0,31}$/;
+const HEX6 = /^[0-9a-f]{6}$/;
+const KEY_PREFIX = 'byokit-key-';
+export function agentOf(ref) {
+    if (!ref.startsWith('agent:'))
+        return ref;
+    return /^agent:([^:]+):/.exec(ref)?.[1];
+}
+export function memberOf(ref) {
+    const agent = agentOf(ref);
+    if (agent === undefined)
+        return undefined;
+    if (agent.startsWith(KEY_PREFIX)) {
+        const inner = agent.slice(KEY_PREFIX.length);
+        return MEMBER.test(inner) ? inner : undefined;
+    }
+    const dash = agent.lastIndexOf('--');
+    if (dash >= 0) {
+        const head = agent.slice(0, dash);
+        const tail = agent.slice(dash + 2);
+        if (MEMBER.test(head) && HEX6.test(tail))
+            return head;
+    }
+    return MEMBER.test(agent) ? agent : undefined;
+}

package/dist/auth-store.d.ts

@@ -61,6 +61,12 @@ export declare class AuthStore {
     private restore;
     archives(): Promise<void>;
     prepare(): Promise<void>;
+    /** Re-seal the credential snapshot while the engine runs (removeAccount): it drops the removed profile at once
+     *  instead of waiting for stop, and read() drops the removed agent's sealed objects. Database objects are never
+     *  read here — each keeps its last sealed copy until stop, when persist() seals the live databases. Live files
+     *  stay in place — unlike persist(), nothing is removed and no crash-transition recovery runs, so this never
+     *  deletes the tree a live engine is running on. No-op without a seal or while the store is not active. */
+    reseal(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     offline<T>(task: () => Promise<T>): Promise<T>;

package/dist/auth-store.js

@@ -8,6 +8,7 @@ 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";
 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'));
@@ -140,6 +141,11 @@ function safePath(path) {
     return typeof path === 'string' && /^(state|home)(\/[^/]+)*$/.test(path)
         && !path.split('/').some((part) => part === '.' || part === '..' || part.includes('\\') || part.includes('\0'));
 }
+// A file the live engine deletes between the directory listing and the read is simply gone: there is nothing to
+// seal, so callers skip it. Every other failure still throws.
+function vanished(error) {
+    return error.code === 'ENOENT';
+}
 function snapshot(text) {
     const s = JSON.parse(text);
     if ((s?.v !== 1 && s?.v !== 2) || !Array.isArray(s.dirs) || !Array.isArray(s.files))
@@ -206,8 +212,9 @@ export class AuthStore {
     cleanup;
     restoring;
     // Object file name -> sha256 of the plaintext payload currently sealed at that file. Kept only in memory: it
-    // never becomes on-disk metadata. Filled by restore() from what is decrypted, refreshed after each successful
-    // seal. A process that never restored starts with an empty map and reseals every object, as before.
+    // never becomes on-disk metadata. Filled by restore() from what is decrypted (except objects in an older wrap
+    // mode), refreshed after each successful seal. A process that never restored starts with an empty map and
+    // reseals every object, as before.
     objectHashes = new Map();
     constructor(privateOptions) {
         this.o = privateOptions;
@@ -315,19 +322,38 @@ export class AuthStore {
         catch {
             throw new AuthStoreUnreadableError('invalid-snapshot');
         }
-        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);
+        const gone = removedAccountAgents(this.o.root);
+        const keep = (path) => !path.startsWith('state/agents/') || !gone.has(path.split('/')[2]);
+        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));
+        }
+        else {
+            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);
+            }
+        }
+        if (gone.size && existsSync(this.objects)) {
+            for (const entry of readdirSync(this.objects)) {
+                const file = join(this.objects, entry);
+                if (keep(this.readObject(file)[0]))
+                    continue;
+                rmSync(file);
+                this.objectHashes.delete(entry);
+            }
         }
-        return saved;
+        return kept;
     }
     readObject(file) {
+        let bytes = Buffer.alloc(0);
         let text = '';
         let entry = null;
         try {
-            text = this.open(readFileSync(file));
+            bytes = readFileSync(file);
+            text = this.open(bytes);
             entry = JSON.parse(text);
         }
         catch (error) {
@@ -340,7 +366,7 @@ export class AuthStore {
         if (!safePath(path) || !apart(path) || typeof data !== 'string' || Buffer.from(data, 'base64').toString('base64') !== data) {
             throw new AuthStoreUnreadableError('invalid-snapshot');
         }
-        return [path, data, text];
+        return [path, data, text, bytes];
     }
     inventory() {
         const dirs = [];
@@ -348,15 +374,35 @@ export class AuthStore {
         const objects = [];
         let total = 0;
         const root = realpathSync(this.o.root);
+        const gone = removedAccountAgents(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('home/') && nonCredential(name))
                 return; // regenerable home caches stay on disk; skipping a directory skips its subtree
-            const stat = lstatSync(path);
+            let stat;
+            try {
+                stat = lstatSync(path);
+            }
+            catch (error) {
+                if (vanished(error))
+                    return;
+                throw error;
+            }
             if (stat.isDirectory()) {
                 if (!apart(name))
                     dirs.push(name);
-                for (const child of readdirSync(path).sort())
+                let children;
+                try {
+                    children = readdirSync(path).sort();
+                }
+                catch (error) {
+                    if (vanished(error))
+                        return;
+                    throw error;
+                }
+                for (const child of children)
                     walk(join(path, child));
                 return;
             }
@@ -374,7 +420,14 @@ export class AuthStore {
                 const rel = relative(root, file);
                 if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))
                     return;
-                target = lstatSync(file);
+                try {
+                    target = lstatSync(file);
+                }
+                catch (error) {
+                    if (vanished(error))
+                        return;
+                    throw error;
+                }
             }
             if (!target.isFile())
                 return;
@@ -396,15 +449,44 @@ export class AuthStore {
         return { dirs, files, objects };
     }
     collect() {
+        sweepOrphans(this.o.root);
         const { dirs, files, objects } = this.inventory();
-        for (const dir of dirs)
-            chmodSync(join(this.o.root, dir), 0o700);
-        // Read the checked target, but save the link's path: restore materializes a regular file there.
-        for (const { file } of [...files, ...objects])
-            chmodSync(file, 0o600);
+        for (const dir of dirs) {
+            try {
+                chmodSync(join(this.o.root, dir), 0o700);
+            }
+            catch (error) {
+                if (!vanished(error))
+                    throw error;
+            }
+        }
+        // Read the checked target, but save the link's path: restore materializes a regular file there. A file that
+        // vanishes here is skipped by the same rule as in the listing above.
+        const read = ({ name, file }) => {
+            try {
+                chmodSync(file, 0o600);
+                return [name, readFileSync(file).toString('base64')];
+            }
+            catch (error) {
+                if (vanished(error))
+                    return undefined;
+                throw error;
+            }
+        };
+        const kept = objects.filter(({ file }) => {
+            try {
+                chmodSync(file, 0o600);
+                return true;
+            }
+            catch (error) {
+                if (vanished(error))
+                    return false;
+                throw error;
+            }
+        });
         return {
-            saved: { v: 1, dirs, files: files.map(({ name, file }) => [name, readFileSync(file).toString('base64')]) },
-            objects,
+            saved: { v: 1, dirs, files: files.map(read).filter((entry) => entry !== undefined) },
+            objects: kept,
         };
     }
     /** Remove the live sealed trees: all of `state` (every file there is sealed, as a blob entry or an object),
@@ -431,10 +513,19 @@ export class AuthStore {
         mkdirSync(this.objects, { recursive: true, mode: 0o700 });
         const keep = new Set();
         for (const { name, file } of objects) {
+            let data;
+            try {
+                data = readFileSync(file).toString('base64');
+            }
+            catch (error) {
+                if (vanished(error))
+                    continue;
+                throw error;
+            }
             const object = objectName(name);
             keep.add(object);
             const target = join(this.objects, object);
-            const payload = JSON.stringify({ path: name, data: readFileSync(file).toString('base64') });
+            const payload = JSON.stringify({ path: name, data });
             // An object this process already sealed (or restored) unchanged is not resealed: its plaintext hash is
             // the same and its sealed file is still on disk, so the encrypt + verify + fsyncs are skipped. A changed
             // file, a new one, or one whose sealed file vanished falls through to the normal seal.
@@ -502,8 +593,11 @@ export class AuthStore {
         }
         if (existsSync(this.objects)) {
             for (const entry of readdirSync(this.objects)) {
-                const [path, data, payload] = this.readObject(join(this.objects, entry));
-                this.objectHashes.set(entry, objectHash(payload));
+                const [path, data, payload, bytes] = this.readObject(join(this.objects, entry));
+                // An object sealed in an older wrap mode (the adapter would upgrade it, as read() does the main file) gets
+                // 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));
                 // 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
@@ -558,6 +652,24 @@ export class AuthStore {
             }
         });
     }
+    /** Re-seal the credential snapshot while the engine runs (removeAccount): it drops the removed profile at once
+     *  instead of waiting for stop, and read() drops the removed agent's sealed objects. Database objects are never
+     *  read here — each keeps its last sealed copy until stop, when persist() seals the live databases. Live files
+     *  stay in place — unlike persist(), nothing is removed and no crash-transition recovery runs, so this never
+     *  deletes the tree a live engine is running on. No-op without a seal or while the store is not active. */
+    async reseal() {
+        return this.serial(async () => {
+            if (!this.o.seal || !this.active)
+                return;
+            const previous = await this.read();
+            const { saved, objects } = this.collect();
+            // Same debris guard as persist(): a running engine always leaves files behind, so an empty live tree
+            // keeps the sealed credentials instead of replacing them with an empty snapshot.
+            if (!saved.files.length && !objects.length && previous)
+                return;
+            this.seal(this.file, JSON.stringify(saved));
+        });
+    }
     start() {
         return this.serial(async () => {
             if (this.active)

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { Approval, Decision, RunRef, ToolHost, ToolSpec } from './types.ts';
+import type { Approval, Decision, Member, RunRef, ToolHost, ToolSpec } from './types.ts';
 /**
  * Asks must expire before the plugin's 195 s gate timeout, or the run gets a generic block while the approval
  * lingers (N3). The kit passes its `approvalTimeoutMs` through; anything above is clamped to this.
@@ -32,6 +32,7 @@ export declare class Bridge {
     private readonly tools;
     private readonly permitted;
     private readonly approvalTimeoutMs;
+    private readonly memberOf;
     private readonly onAsk;
     private readonly onAskGone;
     private readonly beforeAgentRun?;
@@ -52,6 +53,7 @@ export declare class Bridge {
         tools: ReadonlySet<string>;
         permitted: (tool: string) => boolean;
         approvalTimeoutMs: number;
+        memberOf(ref: string): Member | undefined;
         onAsk(a: Approval): void;
         onAskGone(id: string): void;
         beforeAgentRun?: (key: string, runId?: string) => Promise<boolean>;

package/dist/bridge.js

@@ -12,10 +12,6 @@ const FRAME_CAP = 1_000_000;
  */
 export const MAX_APPROVAL_TIMEOUT_MS = 190_000;
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-const memberOfKey = (key) => {
-    const m = /^agent:([a-z][a-z0-9-]{0,31}):/.exec(key);
-    return m?.[1];
-};
 export const DEFAULT_SOCKET_NAME = 'bridge.sock';
 export const DEFAULT_PARAM_PREFIX = '__byokit';
 /** Resolve the bridge naming options, validating explicit values; defaults keep prior behavior. */
@@ -66,6 +62,7 @@ export class Bridge {
     tools;
     permitted;
     approvalTimeoutMs;
+    memberOf;
     onAsk;
     onAskGone;
     beforeAgentRun;
@@ -88,6 +85,7 @@ export class Bridge {
         this.tools = o.tools;
         this.permitted = o.permitted;
         this.approvalTimeoutMs = Math.min(o.approvalTimeoutMs, MAX_APPROVAL_TIMEOUT_MS);
+        this.memberOf = o.memberOf;
         this.onAsk = o.onAsk;
         this.onAskGone = o.onAskGone;
         this.beforeAgentRun = o.beforeAgentRun;
@@ -293,7 +291,7 @@ export class Bridge {
             (!armed.input || armed.input(input))) {
             this.armed = undefined;
             // '' when unattributable: never a member id (B2).
-            const member = memberOfKey(key) ?? '';
+            const member = this.memberOf(key) ?? '';
             const runRef = { sessionKey: key, member };
             return void this.gateRun(socket, runRef, tool, input);
         }
@@ -389,7 +387,7 @@ export class Bridge {
         }
         if (!this.host)
             return this.reply(socket, { ok: false, reason: "can't run this action right now" });
-        const run = this.runs.get(key) ?? { sessionKey: key, member: memberOfKey(key) ?? '' };
+        const run = this.runs.get(key) ?? { sessionKey: key, member: this.memberOf(key) ?? '' };
         // The plugin destroys its socket when the run aborts (run abort, hook timeout); without this the host's
         // sandboxed command keeps running after the tool is gone.
         const controller = new AbortController();

package/dist/config.js

@@ -52,6 +52,16 @@ export function reconcileConfig(saved, o) {
     c.agents.defaults.authInheritance = { agentId: BASE_AGENT };
     c.agents.defaults.models ??= {};
     c.agents.defaults.models['openai/*'] = { ...c.agents.defaults.models['openai/*'], agentRuntime: { id: 'openclaw' } };
+    // With no policy record the pin reads the `models` keys above as a legacy allowlist and materializes
+    // `modelPolicy.allow: ['openai/*']` on boot, so a member's OpenCode Go (any non-OpenAI) model fell back to
+    // openai. An empty record restricts nothing; the exact list that migration wrote is dropped unless the app sets one.
+    if (!o.app?.agents?.defaults?.modelPolicy) {
+        const policy = c.agents.defaults.modelPolicy;
+        if (!object(policy))
+            c.agents.defaults.modelPolicy = {};
+        else if (Array.isArray(policy.allow) && policy.allow.length === 1 && policy.allow[0] === 'openai/*')
+            delete policy.allow;
+    }
     const allow = c.agents.defaults.modelPolicy?.allow;
     if (Array.isArray(allow) && allow.length && !allow.includes('openai/*'))
         allow.push('openai/*');

package/dist/constants.d.ts

@@ -1,3 +1,4 @@
 export declare const ENGINE_VERSION = "2026.8.35";
 export declare const PROTOCOL_VERSION = 4;
+export declare const LIVE_CATALOGS: string[];
 export declare const OPERATOR_SCOPES: readonly ["operator.read", "operator.write", "operator.admin", "operator.approvals", "operator.questions", "operator.pairing", "operator.talk"];

package/dist/constants.js

@@ -2,6 +2,8 @@
 // `needs-update`, never silently run.
 export const ENGINE_VERSION = '2026.8.35';
 export const PROTOCOL_VERSION = 4;
+// Providers whose live catalog the kit registers (5.6); key choice uses the same catalog hook.
+export const LIVE_CATALOGS = ['opencode-go'];
 export const OPERATOR_SCOPES = [
     'operator.read',
     'operator.write',

package/dist/device.d.ts

@@ -2,7 +2,7 @@ import type { BrowserDevice, SignInRefusedWhy } from './browser.ts';
 import type { DeviceLink } from '@byokit/pair';
 import type { RouteView } from './routes.ts';
 import { type AccountView } from './words.ts';
-import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView } from './types.ts';
+import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView, AccountRef } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
 export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
@@ -36,6 +36,8 @@ export type DeviceEndFrame<T = unknown> = {
 export type DeviceRunOptions<S extends OutputSchema | undefined = OutputSchema | undefined> = {
     schema?: S;
     sessionKey?: string;
+    account?: AccountRef | 'default' | 'auto';
+    needs?: string[];
     model?: string;
     auth?: 'apiKey';
     system?: string;
@@ -79,9 +81,7 @@ export type SignInNotice = {
 export declare function openSignInNotice(data: Record<string, unknown>, seed: Uint8Array): SignInNotice | null;
 /** Transient streams bypass link's durable request/answer cache: no lease nonce or frame is persisted. */
 export declare function browserDevice(link: DeviceLink): BrowserDevice;
-type DeviceRunEvent = Exclude<RunEvent, {
-    type: 'account';
-}>;
+type DeviceRunEvent = RunEvent;
 /** `openclawDevice`'s device surface: every `oc.*` op the computer answers, typed. */
 export type OpenClawDevice = {
     browser: BrowserDevice;

package/dist/device.js

@@ -1,4 +1,5 @@
 import { openBoxFromSeed, boxKeyPairFromSeed } from '@byokit/seal';
+import { memberOf } from "./attribution.js";
 import { toAccountView } from "./words.js";
 import { b64urlDecode, b64urlEncode, openNotice } from "./notices.js";
 /**
@@ -19,6 +20,13 @@ export class BrowserRefused extends LinkRefused {
     constructor(why) { super(`Sign-in refused: ${why}`); this.why = why; }
 }
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// A session key this device sends must be shaped like one: `agent:<member>:` or an
+// `<member>--<hex6>` account agent's key (5.15). Anything else is refused before it reaches the computer.
+const checkKey = (sessionKey) => {
+    if (typeof sessionKey !== 'string' || !sessionKey.startsWith('agent:') || memberOf(sessionKey) === undefined)
+        throw new LinkRefused('Invalid session key');
+    return sessionKey;
+};
 /**
  * Newline-delimited JSON frames off a link stream, in order. A host end with an error becomes a
  * LinkRefused with the host's words (a refusal arrives after the stream opens, so it cannot ride
@@ -354,7 +362,9 @@ export function openclawDevice(link) {
         },
         sessions: () => link.request('oc.sessions'),
         run: (message, o) => {
-            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: o.sessionKey } : {}),
+            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: checkKey(o.sessionKey) } : {}),
+                ...(o?.account !== undefined ? { account: o.account } : {}),
+                ...(o?.needs !== undefined ? { needs: o.needs } : {}),
                 ...(o?.model !== undefined ? { model: o.model } : {}), ...(o?.system !== undefined ? { system: o.system } : {}),
                 ...(o?.auth !== undefined ? { auth: o.auth } : {}),
                 ...(o?.images !== undefined ? { images: o.images } : {}), ...(o?.thinking !== undefined ? { thinking: o.thinking } : {}),

package/dist/engine.d.ts

@@ -54,6 +54,7 @@ export declare class Engine {
     };
     private verifiedOrphan;
     private recoverOrphan;
+    private sweepAccountOrphans;
     start(): Promise<{
         port: number;
         token: string;

package/dist/engine.js

@@ -12,6 +12,7 @@ import { ENGINE_VERSION } from "./constants.js";
 import { appendUsageBoot } from "./usage-boots.js";
 import { reconcileConfig, appRecoveryPrefixes } from "./config.js";
 import { writePlugin, resolveBridge } from "./bridge.js";
+import { sweepOrphans } from "./accounts.js";
 const kitDir = dirname(dirname(fileURLToPath(import.meta.url)));
 const putOnce = (path, data) => { if (!existsSync(path))
     writeFileSync(path, data, { mode: 0o600, flag: 'wx' }); };
@@ -161,6 +162,7 @@ export class Engine {
         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, 'usage'), join(this.root, 'install-home'), join(this.root, 'npm-cache'), join(this.o.stateDir, 'logs')])
             mkdirSync(d, { recursive: true, mode: 0o700 });
+        this.sweepAccountOrphans();
         try {
             await this.authStore.prepare();
             this.credentialsLocked = false;
@@ -256,7 +258,7 @@ export class Engine {
         const pluginDir = join(this.root, 'plugin');
         mkdirSync(pluginDir, { recursive: true, mode: 0o700 });
         // The shipped plugin follows the kit on every prepare too: a state dir from an older kit must not keep its gate.
-        for (const f of ['package.json', 'index.js', 'keys.js', 'usage.js', 'accounts.js']) {
+        for (const f of ['package.json', 'index.js', 'keys.js', 'usage.js', 'accounts.js', 'catalog.js']) {
             const source = join(kitDir, 'plugin', f);
             putChanged(join(pluginDir, f), readFileSync(source, 'utf8'));
         }
@@ -351,6 +353,18 @@ export class Engine {
             throw occupied();
         // The new store owner now seals crash leftovers under its lock before restoring them.
     }
+    // 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).
+    sweepAccountOrphans() {
+        try {
+            sweepOrphans(this.root);
+        }
+        catch (error) {
+            this.o.log?.(`prepare: orphans are not swept: ${String(error.message).slice(0, 200)}`);
+        }
+    }
     start() {
         if (this.starting)
             return this.starting;
@@ -382,6 +396,7 @@ export class Engine {
                 this.state('failed', 'auth-store-unreadable');
             throw error;
         }
+        this.sweepAccountOrphans();
         try {
             return this.launch();
         }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ 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 } from './keys.ts';
+export type { 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';