@byokit/openclaw 0.11.0 → 0.12.0

package/dist/accounts.js

@@ -1,14 +1,58 @@
 // The per-member account index (5.15, O14 step S5): `<root>/accounts/<member>.json` (0600, whole-file temp
 // plus rename) is the only kit state: `{ v: 1, accounts: { [id]: { agent, name, route, addedAt, until?, model?,
-// who? } }, defaults }`. No credential, token, email or engine line. Listing, rename and defaults live here;
-// add, remove, models, room, pick and move arrive in later steps.
-import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+// who? } }, defaults }`. No credential, token, email or engine line. Listing, rename, defaults, models, room,
+// adding with its identity merge (O14 steps S6, S7), the start-of-run pick (S10), session binding (S11) and moving a
+// conversation (S12) live here; remove arrives in a later step.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { join } from 'node:path';
-import { KEY_PREFIX, MEMBER_ID } from "./members.js";
+import { providerOf, resolveSelection } from "./pick.js";
+import { agentOf, memberOf as baseMemberOf } from "./attribution.js";
+import { KEY_PREFIX, MEMBER_ID, NEW_MEMBER_ID, untilListed } from "./members.js";
 import { routes, routeFor } from "./routes.js";
+import { words } from "./words.js";
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// `models.list { agentId, view: 'default' }` rows of the account's provider, mapped to `provider/model`. The pin
+// reports no per-plan availability, so `why: 'plan'` only comes from a run ending `plan`, never from here.
+export const modelsOf = (provider, answer) => {
+    const rows = record(answer) && Array.isArray(answer.models) ? answer.models : [];
+    const out = [];
+    for (const candidate of rows) {
+        if (!record(candidate) || typeof candidate.provider !== 'string'
+            || candidate.provider.toLowerCase() !== provider.toLowerCase())
+            continue;
+        if (typeof candidate.id !== 'string' || !candidate.id || typeof candidate.name !== 'string')
+            continue;
+        const id = candidate.id.includes('/') ? candidate.id : `${candidate.provider}/${candidate.id}`;
+        if (providerOf(id) !== provider.toLowerCase())
+            continue;
+        const available = candidate.available === undefined
+            ? candidate.unavailableReason === undefined : candidate.available === true;
+        const info = { id, name: candidate.name, available };
+        if ((candidate.tier === 'strong' || candidate.tier === 'fast'))
+            info.tier = candidate.tier;
+        if (!available) {
+            if (candidate.unavailableReason === 'missing-auth' || candidate.unavailableReason === 'auth-failed')
+                info.why = 'signed_out';
+            else if (candidate.unavailableReason === 'cooldown') {
+                info.why = 'resting';
+                if (typeof candidate.unavailableUntil === 'number' && Number.isFinite(candidate.unavailableUntil))
+                    info.until = candidate.unavailableUntil;
+            }
+        }
+        out.push(info);
+    }
+    return out;
+};
 const ACCOUNT_AGENT = /^[a-z][a-z0-9-]{0,31}--[0-9a-f]{6}$/;
 const usable = (status) => status === 'ok' || status === 'expiring' || status === 'static';
+const IDENTITY = 'IDENTITY.md';
+const named = (name, op) => {
+    const trimmed = typeof name === 'string' ? name.trim() : '';
+    if (!trimmed || trimmed.length > 100 || /[\u0000-\u001f\u007f]/.test(trimmed))
+        throw new Error(`${op}: name is empty`);
+    return trimmed;
+};
 const empty = () => ({ v: 1, accounts: {}, defaults: {} });
 const validEntry = (v) => !!v && typeof v === 'object'
     && typeof v.agent === 'string' && typeof v.name === 'string'
@@ -16,39 +60,65 @@ const validEntry = (v) => !!v && typeof v === 'object'
     && (v.until === undefined || Number.isFinite(v.until))
     && (v.model === undefined || typeof v.model === 'string')
     && (v.who === undefined || typeof v.who === 'string');
+const indexPath = (root, member) => join(root, 'accounts', `${member}.json`);
+const readIndex = (root, member) => {
+    let text;
+    try {
+        text = readFileSync(indexPath(root, member), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return empty();
+        throw error;
+    }
+    const file = JSON.parse(text);
+    if (!file || typeof file !== 'object' || file.v !== 1)
+        return empty();
+    const accounts = {};
+    for (const [id, entry] of Object.entries(file.accounts ?? {}))
+        if (validEntry(entry))
+            accounts[id] = entry;
+    const raw = file.defaults && typeof file.defaults === 'object' ? file.defaults : {};
+    const defaults = {};
+    if (typeof raw.account === 'string')
+        defaults.account = raw.account;
+    if (typeof raw.model === 'string')
+        defaults.model = raw.model;
+    if (typeof raw.auto === 'boolean')
+        defaults.auto = raw.auto;
+    return { v: 1, accounts, defaults };
+};
+// Attribution (5.15, O14m): the member an agent id or `agent:<agent>:<tail>` session key belongs to. A member agent is its
+// own, and so is an agent whose workspace the kit created for it (a legacy member id may end in `--<hex6>`); any other
+// agent, an `<member>--<hex6>` account agent included, maps only while the index names it under that member. Account
+// agents share their member's workspace, so an unindexed account-shaped agent maps nowhere and stays unreachable.
+export function memberOfAccount(root, ref) {
+    const agent = agentOf(ref);
+    if (agent === undefined)
+        return undefined;
+    const member = baseMemberOf(agent);
+    if (member === undefined || agent === member)
+        return member;
+    if (MEMBER_ID.test(agent) && existsSync(join(root, 'workspaces', agent)))
+        return agent;
+    try {
+        return Object.values(readIndex(root, member).accounts).some((e) => e.agent === agent) ? member : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createAccounts(ctx) {
-    const path = (member) => join(ctx.root, 'accounts', `${member}.json`);
+    const path = (member) => indexPath(ctx.root, member);
+    const read = (member) => readIndex(ctx.root, member);
+    // Accounts whose sign-in is running, as `<member>\n<id>`, counted per add: listed `signing` until the last one ends.
+    const signing = new Map();
+    // The index file's own lock, apart from any agent's: a run's shared hold on the member agent never blocks an edit.
+    const indexLock = (member) => `${member}#index`;
     const check = (member) => {
         if (!MEMBER_ID.test(member) || member.startsWith(KEY_PREFIX))
             throw new Error(`invalid member id: ${member}`);
     };
-    const read = (member) => {
-        let text;
-        try {
-            text = readFileSync(path(member), 'utf8');
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return empty();
-            throw error;
-        }
-        const file = JSON.parse(text);
-        if (!file || typeof file !== 'object' || file.v !== 1)
-            return empty();
-        const accounts = {};
-        for (const [id, entry] of Object.entries(file.accounts ?? {}))
-            if (validEntry(entry))
-                accounts[id] = entry;
-        const raw = file.defaults && typeof file.defaults === 'object' ? file.defaults : {};
-        const defaults = {};
-        if (typeof raw.account === 'string')
-            defaults.account = raw.account;
-        if (typeof raw.model === 'string')
-            defaults.model = raw.model;
-        if (typeof raw.auto === 'boolean')
-            defaults.auto = raw.auto;
-        return { v: 1, accounts, defaults };
-    };
     const write = (member, file) => {
         mkdirSync(join(ctx.root, 'accounts'), { recursive: true, mode: 0o700 });
         const tmp = `${path(member)}.${randomUUID()}.tmp`;
@@ -105,7 +175,8 @@ export function createAccounts(ctx) {
                 file.accounts[provider] = entry;
                 dirty = true;
             }
-            if (!entry.who && typeof profiles[0]?.who === 'string') {
+            // Not while the member agent's own sign-in runs: settle decides whose that `who` is (it may be adopted away).
+            if (typeof profiles[0]?.who === 'string' && entry.who !== profiles[0].who && !signing.has(`${member}\n${provider}`)) {
                 entry.who = profiles[0].who;
                 dirty = true;
             }
@@ -134,6 +205,11 @@ export function createAccounts(ctx) {
             const provider = id.split('.')[0];
             const meta = metaOf(entry.route);
             const profiles = await profilesOf(entry.agent);
+            const who = profiles.find((p) => p.provider === provider)?.who;
+            if (!entry.who && typeof who === 'string' && !signing.has(`${member}\n${id}`)) {
+                entry.who = who;
+                dirty = true;
+            }
             agentRows.push({ id, provider, route: entry.route, name: entry.name, label: meta.label,
                 billing: meta.billing, state: stateOf(entry.route, profiles[0]?.status, entry.until),
                 ...(entry.until !== undefined ? { until: entry.until } : {}), addedAt: entry.addedAt });
@@ -141,6 +217,9 @@ export function createAccounts(ctx) {
         memberRows.sort((a, b) => a.addedAt - b.addedAt || (a.id < b.id ? -1 : 1));
         agentRows.sort((a, b) => a.addedAt - b.addedAt);
         const rows = [...memberRows, ...agentRows];
+        for (const row of rows)
+            if (signing.has(`${member}\n${row.id}`))
+                row.state = 'signing';
         if (file.defaults.account !== undefined && !rows.some((r) => r.id === file.defaults.account)) {
             delete file.defaults.account;
             dirty = true;
@@ -153,15 +232,68 @@ export function createAccounts(ctx) {
         const [roster, profiles] = await gather(agentId);
         return { ...(await build(member, agentId, file, roster, profiles)), file };
     };
+    // The account's index entry, only when `list` names it: an unindexed agent is never reachable, whatever the
+    // file holds.
+    const entryOf = async (member, id) => {
+        const row = (await list(member)).find((r) => r.id === id);
+        const entry = read(member).accounts[id];
+        if (!row || !entry)
+            throw new Error(`unknown account: ${id}`);
+        return { row, entry };
+    };
+    const spanOf = (label) => {
+        const lower = label.toLowerCase();
+        if (lower === 'session')
+            return 'session';
+        if (lower === 'weekly')
+            return 'week';
+        if (lower === 'monthly')
+            return 'month';
+        return 'tightest';
+    };
+    // The `models.authStatus { agentId }` row for the account's provider: of its `usage.windows` entries the one
+    // with the highest numeric `usedPercent` gives `left`, `resetsAt` and `span`. A window applies to every model
+    // unless the engine scopes it to models; the pin's rows carry no scope, so the demand never narrows them today
+    // (the tightest known). A window without a numeric `usedPercent` is skipped, never read as unused. `at` is left
+    // out: the pin exposes no reading age, so the kit never stamps receipt time as reading time. The kit adds no
+    // cache: every call reads live.
+    const roomOf = (provider, answer) => {
+        const unknown = { left: 'unknown' };
+        const rows = record(answer) && Array.isArray(answer.providers) ? answer.providers : undefined;
+        if (!rows)
+            return unknown;
+        const row = rows.find((r) => record(r) && typeof r.provider === 'string'
+            && r.provider.toLowerCase() === provider.toLowerCase());
+        if (!row || !record(row))
+            return unknown;
+        const windows = record(row.usage) && Array.isArray(row.usage.windows) ? row.usage.windows : undefined;
+        if (!windows)
+            return unknown;
+        let best;
+        for (const candidate of windows) {
+            if (!record(candidate))
+                continue;
+            if (typeof candidate.usedPercent !== 'number' || !Number.isFinite(candidate.usedPercent))
+                continue;
+            const span = spanOf(typeof candidate.label === 'string' ? candidate.label : '');
+            const resetAt = typeof candidate.resetAt === 'number' && Number.isFinite(candidate.resetAt)
+                ? candidate.resetAt : undefined;
+            if (!best || candidate.usedPercent > best.used)
+                best = { used: candidate.usedPercent, ...(resetAt !== undefined ? { resetAt } : {}), span };
+        }
+        if (!best)
+            return unknown;
+        return { left: 100 - best.used, span: best.span, ...(best.resetAt !== undefined ? { resetsAt: best.resetAt } : {}) };
+    };
     async function list(member) {
         check(member);
         const { agentId } = await ctx.ensure(member);
-        const first = await ctx.locks.shared(agentId, () => buildRows(member, agentId));
+        const first = await ctx.locks.shared(indexLock(member), () => buildRows(member, agentId));
         if (!first.dirty)
             return first.rows;
         // A write is needed (synthesized entry, `who` backfill or dropped default): redo it under the
         // exclusive lock so two first-lists cannot interleave their read-modify-write.
-        return ctx.locks.exclusive([agentId], async () => {
+        return ctx.locks.exclusive([indexLock(member)], async () => {
             const { rows, dirty, file } = await buildRows(member, agentId);
             if (dirty)
                 write(member, file);
@@ -170,15 +302,10 @@ export function createAccounts(ctx) {
     }
     async function rename(member, id, name) {
         check(member);
-        if (typeof name !== 'string')
-            throw new Error('renameAccount: name is empty');
-        const trimmed = name.trim();
-        if (!trimmed || trimmed.length > 100 || /[\u0000-\u001f\u007f]/.test(trimmed))
-            throw new Error('renameAccount: name is empty');
-        const { agentId } = await ctx.ensure(member);
+        const trimmed = named(name, 'renameAccount');
         if (!(await list(member)).some((r) => r.id === id))
             throw new Error(`unknown account: ${id}`);
-        await ctx.locks.exclusive([agentId], async () => {
+        await ctx.locks.exclusive([indexLock(member)], async () => {
             const file = read(member);
             const entry = file.accounts[id];
             if (!entry)
@@ -205,8 +332,8 @@ export function createAccounts(ctx) {
             throw new Error('setDefaults: defaults are invalid');
         if (d.auto !== undefined && typeof d.auto !== 'boolean')
             throw new Error('setDefaults: defaults are invalid');
-        const { agentId } = await ctx.ensure(member);
-        return ctx.locks.exclusive([agentId], async () => {
+        await ctx.ensure(member);
+        return ctx.locks.exclusive([indexLock(member)], async () => {
             const file = read(member);
             const next = {};
             if (d.account !== undefined)
@@ -218,5 +345,473 @@ export function createAccounts(ctx) {
             write(member, { ...file, defaults: next });
         });
     }
-    return { list, rename, defaults, setDefaults };
+    async function models(member, id) {
+        check(member);
+        await ctx.ensure(member);
+        const { row, entry } = await entryOf(member, id);
+        return readModels(row, entry);
+    }
+    // The shared hold covers the read, so no kit read of the agent is in flight while it is removed.
+    const readModels = (row, entry) => ctx.locks.shared(entry.agent, async () => modelsOf(row.provider, await ctx.request('models.list', { agentId: entry.agent, view: 'default' })));
+    async function room(member, id, demand) {
+        check(member);
+        await ctx.ensure(member);
+        const { row, entry } = await entryOf(member, id);
+        return readRoom(row, entry);
+    }
+    // An API-key account is used only when chosen, never by Auto: its room is always unknown, with no read. A demand
+    // never narrows the windows (see `roomOf`), so the read takes none.
+    const readRoom = (row, entry) => row.billing === 'api'
+        ? Promise.resolve({ left: 'unknown' })
+        : ctx.locks.shared(entry.agent, async () => {
+            let answer;
+            try {
+                answer = await ctx.request('models.authStatus', { agentId: entry.agent }, { timeoutMs: 20_000 });
+            }
+            catch {
+                return { left: 'unknown' };
+            }
+            return roomOf(row.provider, answer);
+        });
+    // Runs step 2 reads the index alone: the index-only refusal makes no request, and a cold index adds one account
+    // listing (the pick's late check after `list`; `keyRefusal` lists when the held account is not API-billed). This
+    // gives the accounts a binding holds, in list order, and the name a refusal shows (`account.another` when it holds none).
+    const boundOf = (file, binding) => binding.id !== undefined ? [binding.id]
+        : Object.entries(file.accounts).filter(([, e]) => e.agent === binding.agentId)
+            .sort(([a, x], [b, y]) => x.addedAt - y.addedAt || (a < b ? -1 : 1)).map(([id]) => id);
+    const nameOf = (file, ids) => {
+        const first = ids[0] === undefined ? undefined : file.accounts[ids[0]];
+        return first?.name ?? words('account.another');
+    };
+    // A pick's refusal: `bound` names an id outside the binding's accounts, `paid` an id other than an API-billed
+    // binding's own. A named id the index does not hold is left to the pick, which reports it as unknown.
+    const refusalOf = (file, binding, sel) => {
+        const named = sel.account === 'auto' || sel.account === 'default' ? undefined : sel.account;
+        if (named !== undefined && file.accounts[named] === undefined)
+            return undefined;
+        const ids = boundOf(file, binding);
+        const held = binding.id === undefined ? undefined : file.accounts[binding.id];
+        if (held && metaOf(held.route).billing === 'api' && named !== binding.id)
+            return { code: 'paid', name: held.name };
+        if (named !== undefined && !ids.includes(named))
+            return { code: 'bound', name: nameOf(file, ids) };
+        return undefined;
+    };
+    // An API-key run (Runs step 2): its key continues only an API-billed binding; any other binding is refused.
+    const keyRefusal = async (member, binding) => {
+        const held = binding.id === undefined ? undefined : read(member).accounts[binding.id];
+        if (held && metaOf(held.route).billing === 'api')
+            return undefined;
+        await list(member);
+        const file = read(member);
+        return words('account.bound', { name: nameOf(file, boundOf(file, binding)) });
+    };
+    // Runs step 1 (5.15): a key `agent:<member>--<hex6>:<tail>` of an indexed account agent is bound to that account; a
+    // key `agent:<member>:<tail>` to whichever of the member's agents holds `agent:<that agent>:<tail>` (member agent
+    // first), else unbound. Any other key is not the member's. With no account agent, the member agent and an unbound
+    // key run alike, so nothing is asked.
+    async function bind(member, sessionKey) {
+        check(member);
+        const agents = new Map(Object.entries(read(member).accounts)
+            .filter(([, e]) => ACCOUNT_AGENT.test(e.agent) && e.agent.startsWith(`${member}--`)).map(([id, e]) => [e.agent, id]));
+        if (!sessionKey.startsWith(`agent:${member}:`)) {
+            const agent = /^agent:([^:]+):/.exec(sessionKey)?.[1];
+            const id = agent === undefined ? undefined : agents.get(agent);
+            if (id === undefined)
+                throw new Error(`refused: "${sessionKey}" is not a session of member "${member}"`);
+            return { agentId: agent, id };
+        }
+        if (!agents.size)
+            return undefined;
+        const tail = sessionKey.slice(`agent:${member}:`.length);
+        const { agentId } = await ctx.ensure(member);
+        const roster = new Set((await ctx.request('agents.list')).agents.map((a) => a.id));
+        for (const [agent, id] of [[agentId, undefined], ...agents]) {
+            if (agent !== agentId && !roster.has(agent))
+                continue;
+            // The pin answers a found session with its canonical `key` and a missing one with `{ ok: false }`.
+            const found = await ctx.request('sessions.resolve', { key: `agent:${agent}:${tail}`, agentId: agent, allowMissing: true });
+            if (found.key !== undefined)
+                return id === undefined ? { agentId: agent } : { agentId: agent, id };
+        }
+        return undefined;
+    }
+    // Choosing (5.15): every listed account's room and models are read live once, then the pure `resolveSelection`
+    // decides. A binding narrows it (Runs step 2): a key bound to an account agent resolves 'auto', 'default' and no id to
+    // that account; a key bound to the member agent chooses only among its own accounts. A refusal (`bound`, `paid`) is
+    // decided from the index, after the account listing when the index is cold, and so has no `considered` rows.
+    // An unknown id stays the caller bug it always was. `agent` is the picked account's engine agent. A model unavailable
+    // only because the account is signed out or resting is still in its plan: the account's state and the run's ready
+    // check judge that.
+    // The pinned engine may hold no prepared model catalog for an agent added since it started, and refuses its models; that
+    // row's models are then unknown (`undefined`), and `resolveSelection` host-validates its membership by provider.
+    async function pick(member, sel, skip = [], binding) {
+        check(member);
+        const refused = (refusal) => ({ pick: { ok: false, code: refusal.code,
+                reason: words(`account.${refusal.code}`, { name: refusal.name }), considered: [] } });
+        const early = binding?.id !== undefined ? refusalOf(read(member), binding, sel) : undefined;
+        if (early)
+            return refused(early);
+        const listed = await list(member);
+        const file = read(member);
+        const late = binding && refusalOf(file, binding, sel);
+        if (late)
+            return refused(late);
+        const rows = listed.filter((r) => !skip.includes(r.id));
+        const named = sel.account === 'auto' || sel.account === 'default' ? undefined : sel.account;
+        const known = named === undefined || listed.some((r) => r.id === named);
+        if (binding?.id !== undefined && known)
+            sel = { ...sel, account: binding.id };
+        const bound = binding && known ? boundOf(file, binding) : undefined;
+        const reads = new Map(await Promise.all(rows.map(async (row) => {
+            const entry = file.accounts[row.id];
+            const models = await readModels(row, entry).then((ms) => ms.map((m) => (m.why ? { ...m, available: true } : m)), () => undefined);
+            return [row.id, { room: await readRoom(row, entry), models }];
+        })));
+        const chosen = resolveSelection(rows, file.defaults, sel, (a) => reads.get(a.id).room, Date.now(), (a) => reads.get(a.id).models, bound);
+        return { pick: chosen, ...(chosen.ok ? { agent: file.accounts[chosen.account.id].agent } : {}) };
+    }
+    // Moving a conversation (5.15, O14 step S12): the key binds as a run's does (with no account agent binding asks
+    // nothing, and the member agent holds it if anything does), and its `sessions.list` row decides unsupported and busy
+    // before any lock. Same agent: nothing moves, the next run names the account. Otherwise, under both agents' locks and
+    // on the row read again there, the source's whole transcript forks into `agent:<target>:<tail>` (never `chat.history`
+    // plus `chat.inject`, which drop tool rows), then the source is deleted only if it is still the session read. A
+    // refused fork leaves the source untouched; a refused delete leaves both, the new key live.
+    async function move(member, sessionKey, to) {
+        check(member);
+        const failed = (code, message, live) => ({ ok: false, code, message, ...(live === undefined ? {} : { live }) });
+        const { agentId: memberAgent } = await ctx.ensure(member);
+        const { agentId: source } = await bind(member, sessionKey) ?? { agentId: memberAgent };
+        const { row, entry } = await entryOf(member, to);
+        const tail = sessionKey.slice(sessionKey.indexOf(':', 'agent:'.length) + 1);
+        const from = `agent:${source}:${tail}`;
+        const into = `agent:${entry.agent}:${tail}`;
+        const read = async () => {
+            const listed = await ctx.request('sessions.list', { agentId: source, search: from });
+            const found = (Array.isArray(listed.sessions) ? listed.sessions : [])
+                .find((r) => record(r) && typeof r.key === 'string' && r.key.toLowerCase() === from.toLowerCase());
+            if (!found)
+                return { refused: failed('unsupported', words('move.unsupported')) };
+            const live = found.hasActiveRun === true || [...ctx.routes].some(([key, route]) => key === sessionKey || route.session === from);
+            return live ? { refused: failed('busy', words('move.busy')) } : { found };
+        };
+        const first = await read();
+        if ('refused' in first)
+            return first.refused;
+        if (row.state !== 'ready')
+            return failed('start_failed', words('move.notReady', { name: row.name }));
+        if (entry.agent === source)
+            return { ok: true, session: into };
+        return ctx.locks.exclusive([source, entry.agent], async () => {
+            const again = await read();
+            if ('refused' in again)
+                return again.refused;
+            const session = again.found;
+            // A conversation already under the target key is never overwritten: the move is refused, the source untouched.
+            const taken = await ctx.request('sessions.resolve', { key: into, agentId: entry.agent, allowMissing: true });
+            if (taken.key !== undefined)
+                return failed('start_failed', words('move.taken', { name: row.name }));
+            // The session's model when the target lists it, else the target's first available; the read takes no shared
+            // hold (this move holds the target exclusively). With no answer the fork keeps the parent's own selection.
+            const models = await ctx.request('models.list', { agentId: entry.agent, view: 'default' })
+                .then((answer) => modelsOf(row.provider, answer), () => []);
+            const current = typeof session.model !== 'string' ? undefined
+                : (typeof session.modelProvider === 'string' && !session.model.includes('/') ? `${session.modelProvider}/${session.model}` : session.model).toLowerCase();
+            const model = models.find((m) => m.id.toLowerCase() === current)?.id ?? models.find((m) => m.available)?.id;
+            try {
+                await ctx.request('sessions.create', { agentId: entry.agent, key: into, parentSessionKey: from, fork: true, ...(model ? { model } : {}) });
+            }
+            catch (error) {
+                return failed('start_failed', (error instanceof Error ? error.message : String(error)).slice(0, 200));
+            }
+            const closed = await ctx.request('sessions.delete', { key: from, agentId: source, deleteTranscript: true,
+                ...(typeof session.sessionId === 'string' ? { expectedSessionId: session.sessionId } : {}),
+                ...(typeof session.updatedAt === 'number' ? { expectedSessionUpdatedAt: session.updatedAt } : {}) })
+                .then((answer) => record(answer) && answer.deleted === true, (error) => {
+                ctx.log?.(`move: ${from} is kept: ${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            });
+            if (!closed)
+                return failed('close_failed', words('move.closeFailed', { name: row.name }), into);
+            return { ok: true, session: into };
+        });
+    }
+    // A run on the account ended resting: Auto skips it until `until` (its state reads `resting` until then).
+    const rest = (member, id, until) => edit(member, (file) => { const entry = file.accounts[id]; if (entry)
+        entry.until = until; });
+    // Index edits take the index lock, as listing's own write does.
+    const edit = (member, fn) => ctx.locks.exclusive([indexLock(member)], async () => { const file = read(member); fn(file); write(member, file); });
+    const identityOf = async (agentId) => {
+        const { file } = await ctx.request('agents.files.get', { agentId, name: IDENTITY });
+        return file.missing ? undefined : file.content;
+    };
+    const restoreIdentity = async (memberAgent, before) => {
+        if (before !== undefined && await identityOf(memberAgent) !== before)
+            await ctx.request('agents.files.set', { agentId: memberAgent, name: IDENTITY, content: before });
+    };
+    const readModel = async (agentId) => {
+        const got = await ctx.request('config.get');
+        return got.config?.agents?.entries?.[agentId]?.model;
+    };
+    // ponytail: a merge patch cannot delete a key, so a member with no model entry before its sign-in keeps the pinned one.
+    const restoreModel = async (memberAgent, model) => {
+        if (model === undefined) {
+            ctx.log?.(`addAccount: ${memberAgent} had no model entry to restore`);
+            return;
+        }
+        // A config write that lands between the read and the patch moves the hash: read and patch once more.
+        const patch = async () => {
+            const { hash } = await ctx.request('config.get');
+            await ctx.request('config.patch', { raw: JSON.stringify({ agents: { entries: { [memberAgent]: { model } } } }), baseHash: hash });
+        };
+        try {
+            await patch().catch(() => patch());
+        }
+        catch (error) {
+            ctx.log?.(`addAccount: ${memberAgent} model is not restored: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const onGateway = (agent) => untilListed(ctx.request, agent)
+        .then(() => true, () => ctx.request('agents.list')
+        .then((r) => r.agents.some((a) => a.id === agent)));
+    // A new agent whose sign-in did not finish goes with its entry (5.15); the shared workspace stays. The entry is
+    // dropped only once the agent's directory is gone, so a later removal can finish what this one could not.
+    const discard = (member, id, agent, created) => (async () => {
+        if (created) {
+            await ctx.request('byokit.accounts', { action: 'clear', agentId: agent });
+            await ctx.request('agents.delete', { agentId: agent, deleteFiles: false });
+        }
+        rmSync(join(ctx.root, 'state', 'agents', agent), { recursive: true, force: true });
+        await edit(member, (file) => { delete file.accounts[id]; });
+    })().catch((error) => ctx.log?.(`addAccount: ${agent} is not removed yet: ${error instanceof Error ? error.message : String(error)}`));
+    // Member-agent adds of one provider take turns from the sign-in's start to its settle, so a cleanup clears only the
+    // profile its own add activated, and the next add's read sees what the earlier one left.
+    const holdAdd = (member, provider) => new Promise((held) => {
+        void ctx.locks.exclusive([`add:${member}:${provider}`], () => new Promise((release) => held(release)));
+    });
+    async function add(member, o, on) {
+        check(member);
+        if (o && typeof o === 'object' && 'key' in o)
+            throw new Error('addAccount: keys are host-only');
+        if (!NEW_MEMBER_ID.test(member))
+            throw new Error(words('account.legacyMember'));
+        const choice = o?.authChoice === 'openai-codex' ? 'openai' : o?.authChoice;
+        const route = routes().find((r) => r.choice === choice && r.billing === 'subscription');
+        if (!route)
+            throw new Error(`addAccount: ${String(o?.authChoice)} is not a subscription sign-in`);
+        const name = o.name === undefined ? undefined : named(o.name, 'addAccount');
+        const provider = route.provider;
+        const { agentId: memberAgent, workspace } = await ctx.ensure(member);
+        if (o.again !== undefined && (!read(member).accounts[o.again] || o.again.split('.')[0] !== provider))
+            throw new Error(`unknown account: ${o.again}`);
+        let releaseAdd = () => { };
+        try {
+            // The member agent is the target only while it holds no local profile of the provider (5.15).
+            const holdsProvider = async () => {
+                const own = await ctx.request('byokit.accounts', { action: 'list', agentId: memberAgent });
+                if (!own.ok || !Array.isArray(own.profiles))
+                    throw new Error('addAccount: the member\'s sign-ins could not be read');
+                return own.profiles.some((p) => p.provider === provider);
+            };
+            let fresh = o.again !== undefined || await holdsProvider();
+            // Only the member-agent path clears a profile it did not create, so only it takes the provider's add lock, held to
+            // settle. The read repeats under the lock: the add that held it may have sealed its sign-in on the member agent.
+            if (!fresh) {
+                releaseAdd = await holdAdd(member, provider);
+                fresh = await holdsProvider();
+                if (fresh)
+                    releaseAdd();
+            }
+            // The member agent's primary model before this sign-in or any merge on it: restored when its profile moves away.
+            const memberModel = await readModel(memberAgent);
+            const entryOf = (file, agent) => ({ agent, route: route.choice, addedAt: Date.now(),
+                name: name ?? `${route.label} ${Object.values(file.accounts).filter((e) => e.route === route.choice).length + 1}` });
+            let id = provider;
+            let agent = memberAgent;
+            let added = false;
+            if (!fresh) {
+                await edit(member, (file) => { if (!file.accounts[id]) {
+                    file.accounts[id] = entryOf(file, agent);
+                    added = true;
+                } });
+            }
+            else {
+                // `<member>--<hex6>`, drawn again while that agent exists; its entry is written before the agent.
+                const roster = new Set((await ctx.request('agents.list')).agents.map((a) => a.id));
+                await edit(member, (file) => {
+                    const taken = new Set([...roster, ...Object.values(file.accounts).map((e) => e.agent)]);
+                    do {
+                        const hex = randomBytes(3).toString('hex');
+                        id = `${provider}.${hex}`;
+                        agent = `${member}--${hex}`;
+                    } while (taken.has(agent) || file.accounts[id]);
+                    file.accounts[id] = entryOf(file, agent);
+                });
+                added = true;
+                let created = false;
+                // The pin rewrites the shared workspace's IDENTITY.md Name line on create, so the create window is one lock per member.
+                await ctx.locks.exclusive([`${member}#identity`], async () => {
+                    let before;
+                    try {
+                        before = await identityOf(memberAgent);
+                        const made = await ctx.request('agents.create', { name: agent, workspace });
+                        created = true;
+                        if (made.agentId !== agent)
+                            throw new Error(`addAccount: agents.create answered ${String(made.agentId)}, not ${agent}`);
+                        await untilListed(ctx.request, agent);
+                        await restoreIdentity(memberAgent, before);
+                    }
+                    catch (error) {
+                        await restoreIdentity(memberAgent, before)
+                            .catch((restoreError) => ctx.log?.(`addAccount: IDENTITY.md is not restored: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}`));
+                        const exists = created || await onGateway(agent).catch((listError) => {
+                            ctx.log?.(`addAccount: ${agent} is not removed yet: ${listError instanceof Error ? listError.message : String(listError)}`);
+                            return undefined;
+                        });
+                        if (exists !== undefined)
+                            await discard(member, id, agent, exists);
+                        throw error;
+                    }
+                });
+            }
+            const key = `${member}\n${id}`;
+            signing.set(key, (signing.get(key) ?? 0) + 1);
+            const handle = ctx.signIn(agent, { authChoice: route.choice, ...(o.via ? { via: o.via } : {}) }, (v) => { if (v.state === 'waiting')
+                on(v); }, fresh);
+            // Moves the profile `who` names from `from` into `to`, under both agents' locks; refused, nothing changes.
+            const profilesOf = (agent) => ctx.request('byokit.accounts', { action: 'list', agentId: agent })
+                .then((r) => (r.ok === true && Array.isArray(r.profiles) ? r.profiles : undefined), () => undefined);
+            const profileIdOf = (profiles, who) => profiles?.find((p) => p.provider === provider && p.who === who)?.profileId;
+            const moveTo = (from, to, who) => ctx.locks.exclusive([memberAgent, from, to], async () => {
+                const sent = profileIdOf(await profilesOf(from), who);
+                const answer = await ctx.request('byokit.accounts', { action: 'adopt', from, to, provider, who })
+                    .catch(async (error) => {
+                    ctx.log?.(`addAccount: adopt has no answer: ${error instanceof Error ? error.message : String(error)}`);
+                    // A lost reply can follow a committed move: the destination holding the sign-in's own profile means it moved.
+                    const landed = sent !== undefined && profileIdOf(await profilesOf(to), who) === sent;
+                    return { ok: landed };
+                });
+                if (!answer.ok)
+                    return false;
+                if (from === memberAgent)
+                    await restoreModel(memberAgent, memberModel);
+                return true;
+            }).catch(() => false);
+            // `adopt` moves the sign-in into X's agent and clears it from the target; refused, the sign-in stays a new
+            // account and keeps its `who`.
+            const adopt = (who, to) => moveTo(agent, to, who).then(async (ok) => {
+                if (ok)
+                    return true;
+                await edit(member, (file) => { const own = file.accounts[id]; if (own)
+                    own.who = who; });
+                return false;
+            }).catch(() => false);
+            const removeEntry = () => agent !== memberAgent ? discard(member, id, agent, true)
+                : edit(member, (file) => { delete file.accounts[id]; })
+                    .catch((error) => ctx.log?.(`addAccount: ${id} entry is kept: ${error instanceof Error ? error.message : String(error)}`));
+            const drop = () => agent !== memberAgent || added ? removeEntry() : Promise.resolve();
+            // A live account holding the same `who` merges into the earliest one before the sign-in does. When the earliest is
+            // the sign-in's own row, the duplicate is discarded so the sign-in's credential survives; otherwise its profile is
+            // moved into the earliest one, then an account agent is removed and the member agent's entry dropped. A refused
+            // move keeps that duplicate, logged.
+            const collapse = async (dup, keep, who) => {
+                if (keep[0] === id) {
+                    if (dup[1].agent !== memberAgent) {
+                        await discard(member, dup[0], dup[1].agent, true);
+                        return;
+                    }
+                    ctx.log?.(`addAccount: ${dup[0]} is kept: the member agent's profile is not cleared alone`);
+                    return;
+                }
+                if (!await moveTo(dup[1].agent, keep[1].agent, who)) {
+                    ctx.log?.(`addAccount: ${dup[0]} is kept: its sign-in is not moved`);
+                    return;
+                }
+                if (dup[1].agent !== memberAgent) {
+                    await discard(member, dup[0], dup[1].agent, true);
+                    return;
+                }
+                await edit(member, (file) => { delete file.accounts[dup[0]]; })
+                    .catch((error) => ctx.log?.(`addAccount: ${dup[0]} entry is kept: ${error instanceof Error ? error.message : String(error)}`));
+            };
+            // A row holds the identity only while its agent holds it: the member's row while the member holds that `who`, an
+            // account while its agent is on the roster (a removal that stopped partway leaves an entry whose agent is gone).
+            const liveEntry = (roster, memberHolds, e) => e.agent === memberAgent ? memberHolds
+                : ACCOUNT_AGENT.test(e.agent) && e.agent.startsWith(`${member}--`) && roster.has(e.agent);
+            // Sealed before the person sees done: the agent keeps only this sign-in. Done only when sealed; anything else leaves
+            // nothing behind. Identity is its `who`, compared only
+            // within this member and provider: the live accounts holding it (the target's own included; several only from
+            // before O14) merge into the earliest `addedAt`, whatever `again` names; no `who` never merges. The email never decides.
+            const settle = async (view) => {
+                if (view.state === 'done') {
+                    const sealed = await ctx.locks.exclusive([memberAgent, agent, indexLock(member)], async () => {
+                        const answer = await ctx.request('byokit.accounts', { action: 'seal', agentId: agent, provider,
+                            ...(route.keyEntry ? { planKey: true } : {}) });
+                        if (!answer.ok)
+                            return 'Sign-in could not be saved. Try again.';
+                        const roster = await ctx.request('agents.list')
+                            .then((r) => new Set(r.agents.map((a) => a.id)), () => undefined);
+                        const held = await ctx.request('byokit.accounts', { action: 'list', agentId: memberAgent })
+                            .catch(() => undefined);
+                        const mergeable = roster !== undefined && held?.ok === true && Array.isArray(held.profiles);
+                        if (!mergeable)
+                            ctx.log?.(`addAccount: the roster or ${memberAgent} profiles are unreadable; the sign-in is kept as its own row`);
+                        const memberHolds = (held?.profiles ?? []).some((p) => p.provider === provider && p.who === answer.who);
+                        const file = read(member);
+                        if (roster && mergeable && (await build(member, memberAgent, file, roster, held?.profiles ?? [])).dirty)
+                            write(member, file);
+                        const own = file.accounts[id];
+                        const sharing = answer.who && roster && mergeable ? Object.entries(file.accounts)
+                            .filter(([other, e]) => other.split('.')[0] === provider && e.who === answer.who && liveEntry(roster, memberHolds, e))
+                            .sort(([, a], [, b]) => a.addedAt - b.addedAt) : [];
+                        const keep = sharing[0];
+                        const dups = sharing.slice(1).filter(([other]) => other !== id);
+                        if (!(keep && keep[0] !== id) && own) {
+                            if (answer.who)
+                                own.who = answer.who;
+                            else
+                                delete own.who;
+                            write(member, file);
+                        }
+                        return { ...(answer.who ? { who: answer.who } : {}), ...(keep ? { keep } : {}), dups };
+                    }).catch((error) => route.keyEntry ? 'Sign-in could not be saved. Try again.'
+                        : (error instanceof Error ? error.message : String(error)).slice(0, 200));
+                    if (typeof sealed === 'string')
+                        view = { state: 'failed', via: view.via, why: 'failed', error: sealed };
+                    else {
+                        for (const dup of sealed.dups)
+                            await collapse(dup, sealed.keep, sealed.who);
+                        const into = sealed.keep?.[0] !== id ? sealed.keep : undefined;
+                        if (!into || !await adopt(sealed.who, into[1].agent))
+                            return { view, id };
+                        await removeEntry();
+                        return { view, id: into[0] };
+                    }
+                }
+                // A member agent held no profile of this provider before a non-fresh add, so clearing the provider removes only this one.
+                if (agent === memberAgent)
+                    await ctx.request('byokit.accounts', { action: 'clear', agentId: memberAgent, provider })
+                        .catch((error) => ctx.log?.(`addAccount: ${provider} is not cleared yet: ${error instanceof Error ? error.message : String(error)}`));
+                await drop();
+                return { view, id };
+            };
+            const done = handle.done.then(settle).finally(() => {
+                releaseAdd();
+                const left = signing.get(key) - 1;
+                if (left)
+                    signing.set(key, left);
+                else
+                    signing.delete(key);
+            }).then((result) => {
+                on(result.view);
+                return result;
+            });
+            return { id, paste: handle.paste, cancel: handle.cancel, done };
+        }
+        catch (error) {
+            releaseAdd();
+            throw error;
+        }
+    }
+    return { list, add, rename, defaults, setDefaults, models, room, bind, keyRefusal, pick, rest, move };
 }