@clearlysh/beehaven 0.8.16

package/dist/commands/agent.js

@@ -0,0 +1,1310 @@
+/**
+ * `beehaven agent <sub>` — manage per-agent identities.
+ *
+ * An agent identity lets a runtime (a terminal Claude Code session, the
+ * daemon's harness, Clearly AI) "sign in" as a distinct principal and
+ * drive its own avatar. The signing secret lives only in the daemon, so
+ * `login` / `rebind` mint tokens over IPC (`agent:mint`); this command
+ * just stores the resulting record under ~/.beehaven/agents/<name>.json.
+ *
+ * Subcommands:
+ *   login <name> [--label <work>] [--client <client>] [--avatar <id>] [--avatar-skin <skin>] [--kind <k>]
+ *   use <name>            — prints `export BEEHAVEN_AGENT=<name>` (eval it)
+ *   list                  — list stored identities, mark the active one
+ *   whoami                — show the active identity
+ *   logout [<name>]       — end a session, keep the identity (default: active)
+ *   delete <name>         — archive the current workspace projection + remove this device copy
+ *   delete <name> --account --yes
+ *                         — delete the portable account identity (all workspaces) + this device copy
+ *   rebind <name> --avatar <id>  — re-bind to a different avatar
+ *
+ * Per-terminal activation is via the BEEHAVEN_AGENT env var (inherently
+ * per-tty → N windows, N agents); `--agent <name>` overrides per call.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { rpcOnce } from '../ipc-client.js';
+import { saveAgent, loadAgent, listAgents, deleteAgent, findAgentByAvatar, isValidAgentName, resolveActiveAgent, activeAgentName, saveAgentSession, clearAgentSession, decodeAgentTokenClaims, } from '../agent-state.js';
+const VALID_KINDS = ['claude-code', 'daemon-agent', 'clearly-ai'];
+export const FREE_SKINS = [
+    'classic',
+    'midnight',
+    'moss',
+    'ember',
+    'tuck-classic',
+    'tuck-midnight',
+    'tuck-moss',
+    'tuck-ember',
+    'lop',
+    'smudge',
+    'blot',
+    'dab',
+    'pip',
+];
+export function pickRandomOwnedSkinCli(excludeSkins) {
+    const excluded = new Set(excludeSkins ?? []);
+    const unassigned = FREE_SKINS.filter((s) => !excluded.has(s));
+    if (unassigned.length > 0) {
+        return unassigned[Math.floor(Math.random() * unassigned.length)];
+    }
+    return FREE_SKINS[Math.floor(Math.random() * FREE_SKINS.length)];
+}
+/** Native Mwah skin ids accepted by `--avatar-skin`; the legacy `--avatar` flag also accepts
+ * these values for backwards compatibility. */
+function normalizeCliAvatarSkin(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === 'nib')
+        return 'classic';
+    if (value === 'tuck')
+        return 'tuck-classic';
+    return FREE_SKINS.includes(value) ? value : null;
+}
+/** End the workspace session before removing its local handle. Closing the daemon's presence
+ * socket alone cannot update the Durable Object row, so logout used to leave an `active` session
+ * behind until the server's idle sweep noticed it. Best-effort keeps offline logout usable; the
+ * 30-minute server reaper is the fallback when the relay is unavailable. */
+async function endWorkspaceSession(record, summary) {
+    const sessionId = String(record?.sessionId ?? '').trim();
+    if (!sessionId)
+        return false;
+    try {
+        const response = await rpcOnce('agent-session-end', {
+            id: sessionId,
+            ...(record?.agentId ? { agentId: record.agentId } : {}),
+            summary,
+        }, 5_000);
+        const result = response?.result ?? response;
+        return result?.ok !== false && !result?.error;
+    }
+    catch {
+        return false;
+    }
+}
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+export async function cmdAgentSub(positionals, values) {
+    // positionals[0] === 'agent'; positionals[1] === subcommand
+    const sub = positionals[1];
+    const rest = positionals.slice(2);
+    switch (sub) {
+        case 'help':
+            return printAgentUsage();
+        case 'login':
+            return agentLogin(rest, values);
+        case 'use':
+            return agentUse(rest);
+        case 'list':
+        case 'ls':
+            return agentList(values);
+        case 'whoami':
+            return agentWhoami(values);
+        case 'status':
+            return agentStatus(rest, values);
+        case 'logout':
+            return agentLogout(rest, values);
+        case 'delete':
+        case 'remove':
+            return agentDelete(rest, values);
+        case 'rebind':
+            return agentRebind(rest, values);
+        case 'soul':
+            return agentSoulCommand(rest, values);
+        case 'doodle-space':
+            return agentDoodleSpaceCommand(rest, values);
+        case 'home':
+        case 'agent-home':
+            return agentHomeCommand(rest, values);
+        default:
+            console.error(`  Unknown agent subcommand: ${sub ?? '(none)'}`);
+            printAgentUsage();
+            process.exit(1);
+    }
+}
+/** Whether positionals[1] is an identity subcommand (vs. a mwah message). */
+export function isAgentIdentitySub(sub) {
+    return (sub === 'login' ||
+        sub === 'help' ||
+        sub === 'use' ||
+        sub === 'list' ||
+        sub === 'ls' ||
+        sub === 'whoami' ||
+        sub === 'status' ||
+        sub === 'logout' ||
+        sub === 'delete' ||
+        sub === 'remove' ||
+        sub === 'rebind' ||
+        sub === 'soul' ||
+        sub === 'doodle-space'
+        || sub === 'home' ||
+        sub === 'agent-home');
+}
+function printAgentUsage() {
+    console.log('');
+    console.log('  Usage: beehaven agent <command>');
+    console.log('');
+    console.log('  Identity and work-session workflow:');
+    console.log('    beehaven env');
+    console.log('    beehaven connect home');
+    console.log('    beehaven agent login <name> --label "<work>" --client cli');
+    console.log('');
+    console.log('  login mints or refreshes the account-level agent identity, binds this');
+    console.log('  terminal, starts ONE workspace work session, and prints its brief.');
+    console.log('  Do not immediately call `agent-login`: that RPC is the advanced alias');
+    console.log('  of `agent-session-start` and would create another session.');
+    console.log('');
+    console.log('    login <name> [--label <work>] [--client <client>] [--avatar <id>] [--avatar-skin <skin>] [--kind <k>]');
+    console.log('    use <name>                    activate in this terminal (eval the output)');
+    console.log('    list                          list stored identities');
+    console.log('    whoami                        show the active identity');
+    console.log('    status [<name>] --message <text>  set the persistent desktop status label');
+    console.log('    logout [<name>]               end the session, KEEP the identity (default: active)');
+    console.log('    delete <name>                 archive this workspace projection + remove this device copy');
+    console.log('    delete <name> --account --yes delete the portable account identity + this device copy');
+    console.log('    rebind <name> --avatar <id>   re-bind to a different avatar');
+    console.log('    soul get [--agent <name>]     read the opt-in Avatar Soul + baseline');
+    console.log('    soul update --svg <svg|@file> [--state <state>]');
+    console.log('    soul draft get/save            read or save a freeform pre-mint draft');
+    console.log('    doodle-space get [--session <id>]');
+    console.log('    doodle-space draw --svg <svg|@file> [--session <id>] [--title <t>]');
+    console.log('    home get [--json]                     open the persistent grid apartment');
+    console.log('    home layout --operations <json>       arrange rooms, doors, windows, and furniture');
+    console.log('    home memory --value <text> [--key <k>] place a durable memory object');
+    console.log('    home journal --entry <text>            add a private journal object');
+    console.log('    home ad --title <text> [--tagline <t>] create a mini-ad in the Doodle Studio');
+    console.log('    home avatar --room <id> --gx <n> --gy <n> move yourself inside the Home');
+    console.log('                                  (requires AGENT_SOUL_SPACE on staging)');
+    console.log('');
+}
+function actionPayload(raw) {
+    return raw?.result ?? raw;
+}
+function svgArgument(raw) {
+    const value = String(raw ?? '').trim();
+    if (!value) {
+        console.error('  --svg is required. Pass inline SVG or @/path/to/drawing.svg.');
+        process.exit(1);
+    }
+    if (!value.startsWith('@'))
+        return value;
+    try {
+        return readFileSync(value.slice(1), 'utf8').trim();
+    }
+    catch (err) {
+        console.error(`  Could not read SVG file ${value.slice(1)}: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+}
+function soulAgentId(values) {
+    const id = String(values.agent ?? '').trim();
+    return id || undefined;
+}
+function actionNumber(values, key) {
+    const raw = values[key];
+    if (raw === undefined || raw === null || String(raw).trim() === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        console.error(`  --${key} must be a finite number.`);
+        process.exit(1);
+    }
+    return value;
+}
+function printSoulAction(raw, fallback, asJson = false) {
+    const payload = actionPayload(raw);
+    if (payload?.ok === false || payload?.error || raw?.error) {
+        console.error(`  ${payload?.error ?? raw?.error ?? fallback}`);
+        process.exit(1);
+    }
+    if (asJson)
+        console.log(JSON.stringify(payload, null, 2));
+    else if (payload?.compositionId)
+        console.log(`  ${green('✓')} ${fallback}: ${cyan(String(payload.compositionId))}`);
+    else if (payload?.nodeId)
+        console.log(`  ${green('✓')} ${fallback}: ${cyan(String(payload.nodeId))}`);
+    else
+        console.log(JSON.stringify(payload, null, 2));
+}
+async function agentSoulCommand(args, values) {
+    const op = args[0] ?? 'get';
+    if (op === 'help') {
+        console.log('  Usage: beehaven agent soul get [--agent <name>]');
+        console.log('         beehaven agent soul update --svg <svg|@file> [--state <state>] [--note <text>]');
+        console.log('         beehaven agent soul draft get [--agent <name>]');
+        console.log('         beehaven agent soul draft save --svg <svg|@file> [--agent <name>]');
+        return;
+    }
+    if (op === 'draft') {
+        return agentSoulDraftCommand(args.slice(1), values);
+    }
+    const agentId = soulAgentId(values);
+    if (op === 'get') {
+        const response = await rpcOnce('agent-soul-get', agentId ? { agentId } : {}, 15_000);
+        const payload = actionPayload(response);
+        if (payload?.ok === false || payload?.error || response?.error) {
+            console.error(`  ${payload?.error ?? response?.error ?? 'Could not read Avatar Soul.'}`);
+            process.exit(1);
+        }
+        if (values.json)
+            console.log(JSON.stringify(payload, null, 2));
+        else {
+            console.log(`  ${bold('Avatar Soul')} · ${payload.displayName ?? payload.agentId}`);
+            console.log(`  ${payload.appearance ?? 'No appearance description returned.'}`);
+            console.log(`  Baseline: ${payload.baseline?.svg ? 'ready' : 'missing'} · revision ${payload.revision ?? 0}`);
+            if (payload.current?.state)
+                console.log(`  Current: ${payload.current.state}`);
+            if (payload.desktopAppearance) {
+                const d = payload.desktopAppearance;
+                console.log(`  Desktop: ${d.effectiveMode ?? d.requestedMode ?? 'preset'}${d.agentDrawnEnabled ? ' · agent drawn enabled' : ' · preset fallback'}`);
+            }
+            console.log(dim('  Use --json when you need the full SVG and soul record.'));
+        }
+        return;
+    }
+    if (op === 'update') {
+        const svg = svgArgument(values.svg);
+        const response = await rpcOnce('agent-soul-avatar-update', {
+            ...(agentId ? { agentId } : {}),
+            svg,
+            ...(values.state ? { state: String(values.state) } : {}),
+            ...(values.note ? { note: String(values.note) } : {}),
+            ...(values.session ? { sessionId: String(values.session) } : {}),
+        }, 15_000);
+        printSoulAction(response, 'Avatar Soul updated', !!values.json);
+        return;
+    }
+    console.error(`  Unknown soul operation: ${op}`);
+    console.error('  Use: get | update');
+    process.exit(1);
+}
+async function agentSoulDraftCommand(args, values) {
+    const op = args[0] ?? 'get';
+    const agentId = soulAgentId(values);
+    if (op === 'help') {
+        console.log('  Usage: beehaven agent soul draft get [--agent <name>]');
+        console.log('         beehaven agent soul draft save --svg <svg|@file> [--agent <name>] [--appearance <text>]');
+        return;
+    }
+    if (op === 'get') {
+        const response = await rpcOnce('agent-soul-draft-get', agentId ? { agentId } : {}, 15_000);
+        const payload = actionPayload(response);
+        if (payload?.ok === false || payload?.error || response?.error) {
+            console.error(`  ${payload?.error ?? response?.error ?? 'Could not read the Avatar Soul draft.'}`);
+            process.exit(1);
+        }
+        if (values.json)
+            console.log(JSON.stringify(payload, null, 2));
+        else if (payload?.draft) {
+            console.log(`  ${bold('Avatar Soul draft')} · ${payload.agentId}`);
+            console.log(`  ${payload.draft.appearance ?? 'Freeform drawing with no description yet.'}`);
+            console.log(`  SVG: ready · can seed baseline: ${payload.canSeedBaseline ? 'yes' : 'no'}`);
+        }
+        else {
+            console.log(`  No pre-mint Avatar Soul draft for ${payload.agentId}.`);
+        }
+        return;
+    }
+    if (op === 'save') {
+        const svg = svgArgument(values.svg);
+        const response = await rpcOnce('agent-soul-draft-save', {
+            ...(agentId ? { agentId } : {}),
+            svg,
+            ...(values['display-name'] ? { displayName: String(values['display-name']) } : {}),
+            ...(values.appearance ? { appearance: String(values.appearance) } : {}),
+            ...(values.note ? { note: String(values.note) } : {}),
+        }, 15_000);
+        printSoulAction(response, 'Avatar Soul draft saved', !!values.json);
+        return;
+    }
+    console.error(`  Unknown soul draft operation: ${op}`);
+    console.error('  Use: get | save');
+    process.exit(1);
+}
+async function agentDoodleSpaceCommand(args, values) {
+    const op = args[0] ?? 'get';
+    const agentId = soulAgentId(values);
+    if (op === 'help') {
+        console.log('  Usage: beehaven agent doodle-space get [--session <id>]');
+        console.log('         beehaven agent doodle-space draw --svg <svg|@file> [--session <id>] [--title <text>]');
+        return;
+    }
+    if (op === 'get') {
+        const response = await rpcOnce('agent-doodle-space-get', {
+            ...(agentId ? { agentId } : {}),
+            ...(values.session ? { sessionId: String(values.session) } : {}),
+            ...(values.title ? { title: String(values.title) } : {}),
+        }, 15_000);
+        const payload = actionPayload(response);
+        if (payload?.ok === false || payload?.error || response?.error) {
+            console.error(`  ${payload?.error ?? response?.error ?? 'Could not open Doodle Space.'}`);
+            process.exit(1);
+        }
+        if (values.json)
+            console.log(JSON.stringify(payload, null, 2));
+        else if (payload?.compositionId) {
+            console.log(`  ${green('✓')} Doodle Space: ${cyan(String(payload.compositionId))}`);
+            if (payload.viewBox)
+                console.log(`  ViewBox: ${payload.viewBox}`);
+            if (payload.latestDoodle?.svg)
+                console.log(`  Latest drawing: ready · ${payload.desktopAppearance?.doodleBannerEnabled === false ? 'banner hidden' : 'banner available'}`);
+        }
+        else
+            console.log(`  No Doodle Space exists for session ${payload?.sessionId ?? 'default'}.`);
+        return;
+    }
+    if (op === 'draw') {
+        const svg = svgArgument(values.svg);
+        const x = actionNumber(values, 'x');
+        const y = actionNumber(values, 'y');
+        const w = actionNumber(values, 'w');
+        const h = actionNumber(values, 'h');
+        const response = await rpcOnce('agent-doodle-space-draw', {
+            ...(agentId ? { agentId } : {}),
+            svg,
+            ...(values.session ? { sessionId: String(values.session) } : {}),
+            ...(values.title ? { title: String(values.title) } : {}),
+            ...(values.state ? { state: String(values.state) } : {}),
+            ...(values.note ? { note: String(values.note) } : {}),
+            ...(x !== undefined ? { x } : {}),
+            ...(y !== undefined ? { y } : {}),
+            ...(w !== undefined ? { w } : {}),
+            ...(h !== undefined ? { h } : {}),
+        }, 15_000);
+        printSoulAction(response, 'Doodle added', !!values.json);
+        return;
+    }
+    console.error(`  Unknown doodle-space operation: ${op}`);
+    console.error('  Use: get | draw');
+    process.exit(1);
+}
+function jsonArgument(raw, label) {
+    const value = String(raw ?? '').trim();
+    if (!value) {
+        console.error(`  --${label} is required.`);
+        process.exit(1);
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (err) {
+        console.error(`  --${label} must be valid JSON: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+}
+async function agentHomeCommand(args, values) {
+    const op = args[0] ?? 'get';
+    const agentId = soulAgentId(values);
+    const call = async (action, input) => {
+        const response = await rpcOnce(action, { ...(agentId ? { agentId } : {}), ...input }, 20_000);
+        const payload = actionPayload(response);
+        if (payload?.ok === false || payload?.error || response?.error) {
+            console.error(`  ${payload?.error ?? response?.error ?? `Could not run ${action}.`}`);
+            process.exit(1);
+        }
+        if (values.json)
+            console.log(JSON.stringify(payload, null, 2));
+        else {
+            const id = payload?.compositionId || payload?.memoryId || payload?.id;
+            console.log(`  ${green('✓')} ${action}${id ? `: ${cyan(String(id))}` : ''}`);
+            if (payload?.grid?.unit)
+                console.log(`  Grid: ${payload.grid.unit}px · ${payload.grid.columns}×${payload.grid.rows} cells`);
+            if (payload?.roomId)
+                console.log(`  Room: ${payload.roomId}`);
+            if (payload?.revision != null)
+                console.log(`  Revision: ${payload.revision}`);
+        }
+    };
+    if (op === 'help') {
+        console.log('  Usage: beehaven agent home get [--agent <name>]');
+        console.log('         beehaven agent home layout --operations <json> [--revision <n>]');
+        console.log('         beehaven agent home memory --value <text> [--key <key>] [--room <id>]');
+        console.log('         beehaven agent home journal --entry <text> [--title <text>] [--room <id>]');
+        console.log('         beehaven agent home ad --title <text> [--tagline <text>]');
+        console.log('         beehaven agent home avatar --room <id> --gx <n> --gy <n>');
+        return;
+    }
+    if (op === 'get') {
+        await call('agent-home-get', {
+            ...(values.title ? { title: String(values.title) } : {}),
+            ...(values.project ? { projectId: String(values.project) } : {}),
+            ...(values.create !== undefined ? { create: values.create !== 'false' } : {}),
+        });
+        return;
+    }
+    if (op === 'layout') {
+        const revision = actionNumber(values, 'revision');
+        await call('agent-home-layout', {
+            operations: jsonArgument(values.operations, 'operations'),
+            ...(revision !== undefined ? { expectedRevision: revision } : {}),
+        });
+        return;
+    }
+    if (op === 'memory') {
+        await call('agent-home-memory', {
+            value: String(values.value ?? ''),
+            ...(values.key ? { key: String(values.key) } : {}),
+            ...(values.room ? { roomId: String(values.room) } : {}),
+            ...(values.category ? { category: String(values.category) } : {}),
+            ...(values.visibility ? { visibility: String(values.visibility) } : {}),
+            ...(['gx', 'gy', 'gw', 'gh'].reduce((out, key) => { const n = actionNumber(values, key); if (n !== undefined)
+                out[key] = n; return out; }, {})),
+        });
+        return;
+    }
+    if (op === 'journal') {
+        await call('agent-home-journal', {
+            entry: String(values.entry ?? ''),
+            ...(values.title ? { title: String(values.title) } : {}),
+            ...(values.key ? { key: String(values.key) } : {}),
+            ...(values.room ? { roomId: String(values.room) } : {}),
+        });
+        return;
+    }
+    if (op === 'ad') {
+        await call('agent-home-ad', {
+            ...(values.title ? { title: String(values.title) } : {}),
+            ...(values.tagline ? { tagline: String(values.tagline) } : {}),
+            ...(values.accent ? { accent: String(values.accent) } : {}),
+            ...(values.room ? { roomId: String(values.room) } : {}),
+            ...(values.svg ? { svg: svgArgument(values.svg) } : {}),
+        });
+        return;
+    }
+    if (op === 'avatar') {
+        const gx = actionNumber(values, 'gx');
+        const gy = actionNumber(values, 'gy');
+        await call('agent-home-avatar-location', { ...(values.room ? { roomId: String(values.room) } : {}), ...(gx !== undefined ? { gx } : {}), ...(gy !== undefined ? { gy } : {}) });
+        return;
+    }
+    console.error(`  Unknown home operation: ${op}`);
+    console.error('  Use: get | layout | memory | journal | ad | avatar');
+    process.exit(1);
+}
+// ── login ────────────────────────────────────────────
+async function agentLogin(args, values) {
+    const name = args[0];
+    if (!name) {
+        console.error('  Usage: beehaven agent login <name> [--label <work>] [--client <client>] [--avatar <id>] [--avatar-skin <skin>] [--kind <k>]');
+        process.exit(1);
+    }
+    if (!isValidAgentName(name)) {
+        console.error(`  Invalid agent name "${name}" — use letters, digits, '.', '_', '-' (max 64).`);
+        process.exit(1);
+    }
+    const requestedAvatarId = String(values.avatar ?? '').trim();
+    const requestedSkinRaw = String(values['avatar-skin'] ?? '').trim();
+    const requestedSkin = requestedSkinRaw
+        ? normalizeCliAvatarSkin(requestedSkinRaw)
+        : (requestedAvatarId ? normalizeCliAvatarSkin(requestedAvatarId) : null);
+    if (requestedSkinRaw && !requestedSkin) {
+        console.error(`  Unknown avatar skin "${requestedSkinRaw}". Use: ${FREE_SKINS.join(', ')}`);
+        process.exit(1);
+    }
+    const existingRecord = loadAgent(name);
+    const kind = VALID_KINDS.includes(values.kind) ? values.kind : 'claude-code';
+    const displayName = String(values['display-name'] ?? name);
+    // Optional voice binding: --agent-voice <provider[:voiceId]> (e.g. openai:sage,
+    // kokoro:claudette, elevenlabs:EXAVITQu4vr4xnSDxMaL). Bound to the identity
+    // so this agent's avatar speaks in its own voice — carried in the token's
+    // (non-secret) meta and hydrated by the avatar building on each call.
+    /**
+     * ⚠ `--agent-voice` IS THE REAL FLAG; `--voice` IS KEPT ONLY AS A TOLERATED ALIAS.
+     * See the declaration in cli.ts — `--voice` is a boolean (push-to-talk), so the
+     * string branch here is unreachable through normal parsing and exists purely so a
+     * programmatic caller passing `{ voice: 'qwen3-mlx:ethan' }` still works.
+     */
+    const voiceRaw = typeof values['agent-voice'] === 'string' && values['agent-voice'].trim()
+        ? String(values['agent-voice']).trim()
+        : (typeof values.voice === 'string' ? values.voice.trim() : '');
+    let voice;
+    if (voiceRaw) {
+        const { parseVoiceBinding, isKnownVoiceProvider, VOICE_CHOICES } = await import('../agent-onboard.js');
+        const parsed = parseVoiceBinding(voiceRaw);
+        /**
+         * ⚠⚠ A MISSPELLED PROVIDER USED TO BIND SILENTLY AND FAIL AT SPEAK TIME.
+         *
+         * This took any string, so `--voice kokoru:claudette` minted a perfectly valid
+         * identity whose voice named an engine that does not exist. Nothing complained
+         * until the agent spoke — and even then the avatar fell through to its default
+         * provider, so the symptom was "my agent sounds wrong", noticed much later,
+         * with the cause sitting in a token nobody re-reads.
+         *
+         * ⚠ THE VOICE ID IS DELIBERATELY NOT VALIDATED. Valid ids differ per provider,
+         * change over time (ElevenLabs ids are account-scoped) and include names this
+         * file cannot know — a Qwen3 cloned-voice profile is created by the user after
+         * login. The provider is a closed set; the id is not.
+         */
+        if (!parsed || !isKnownVoiceProvider(parsed.provider)) {
+            console.error(`  Unknown voice provider "${parsed?.provider ?? voiceRaw}".`);
+            console.error(`  Expected one of: ${VOICE_CHOICES.map((v) => v.provider).join(' | ')}`);
+            console.error(`  Example: beehaven agent login ${name} --agent-voice qwen3-mlx:ethan`);
+            process.exit(1);
+        }
+        voice = parsed;
+    }
+    // Determine the persisted Mwah skin before minting so the account registry and this device use
+    // the same choice. A new identity uses its selected/auto-assigned skin as its avatar id; a
+    // re-login preserves the identity's existing routing id unless the caller explicitly changes it.
+    let chosenSkin = requestedSkin || existingRecord?.avatarSkin;
+    if (!chosenSkin) {
+        const boundSkins = new Set();
+        for (const { name: otherName, record: otherRecord } of listAgents()) {
+            if (otherName === name)
+                continue;
+            if (otherRecord.avatarSkin)
+                boundSkins.add(otherRecord.avatarSkin);
+            else if (otherRecord.avatarId && FREE_SKINS.includes(otherRecord.avatarId)) {
+                boundSkins.add(otherRecord.avatarId);
+            }
+        }
+        try {
+            const p = join(homedir(), 'Library', 'Application Support', 'clearly-desktop', 'config.json');
+            if (existsSync(p)) {
+                const c = JSON.parse(readFileSync(p, 'utf8'));
+                for (const [k, v] of Object.entries(c)) {
+                    if (k.startsWith('avatarSkin_') && typeof v === 'string')
+                        boundSkins.add(v);
+                }
+            }
+        }
+        catch { }
+        chosenSkin = pickRandomOwnedSkinCli(boundSkins);
+    }
+    const avatarId = requestedAvatarId || existingRecord?.avatarId || chosenSkin || name;
+    // Local-first avatar-collision guard (durable guard is the cloud pool).
+    const collision = findAgentByAvatar(avatarId, name);
+    if (collision) {
+        console.error(`  Avatar "${avatarId}" is already claimed by agent "${collision}".`);
+        console.error(`  Pick another: beehaven agent login ${name} --avatar <other-id>`);
+        process.exit(1);
+    }
+    let minted = null;
+    let sessionOpen = false;
+    /**
+     * ⚠⚠ ACCOUNT-LEVEL AND CLOUD-ONLY. THE LOCAL MINT FALLBACK IS GONE, DELIBERATELY.
+     *
+     * This used to try `agent-mint-token` (which resolves the agent in whatever WORKSPACE the call
+     * landed on) and, on any failure, fall through to a LOCAL `agent:mint`. That fallback is what
+     * made "✓ Signed in" a lie: the local token is not cloud-verifiable, so the workspace answered
+     * `unknown agent` on every subsequent call while the CLI insisted you were logged in. Measured
+     * on a workspace with no agents — login reported success and a session, and nothing worked.
+     *
+     * An identity now comes from `agent-account-mint`: cloud-signed, owned by the ACCOUNT, recorded
+     * in the D1 `AgentRegistry` the SDK already describes as *"sign in anywhere, get the same
+     * agent"*. It creates no workspace row and spends no agent slot — joining a workspace is
+     * `agent-admit`, which `beehaven connect` performs.
+     *
+     * ⚠ A FAILURE HERE IS FATAL AND SAYS WHY. Half a login is worse than none: it is the state that
+     * costs someone an afternoon, because every symptom points at the workspace rather than at the
+     * credential.
+     */
+    try {
+        const cloud = await rpcOnce('agent-account-mint', { agentId: name, avatarId }, 15_000);
+        const tok = cloud?.token ?? cloud?.result?.token;
+        if (tok) {
+            minted = {
+                token: tok,
+                agentId: cloud.agentId ?? cloud.result?.agentId ?? name,
+                avatarId: cloud.avatarId ?? cloud.result?.avatarId ?? avatarId,
+                displayName: cloud.displayName ?? cloud.result?.displayName ?? displayName,
+                kind,
+                // Full context injected on login — the agent's memory bundle
+                // (pinned + top memories, agent-scoped + shared) rides in here.
+                memory: cloud.memory ?? cloud.result?.memory,
+                // Opt-in Avatar Soul capability. The server omits this entirely while
+                // AGENT_SOUL_SPACE is disabled, so the login message never implies a
+                // second avatar system is available when the flag is off.
+                soul: cloud.soul ?? cloud.result?.soul,
+            };
+            try {
+                const conn = await rpcOnce('agent:connect', { agentId: minted.agentId, token: tok }, 15_000);
+                sessionOpen = !!(conn?.ok ?? conn?.result?.ok);
+            }
+            catch {
+                /* session is best-effort — the identity is still saved below */
+            }
+        }
+    }
+    catch (err) {
+        console.error(`  Could not mint identity: ${err?.message ?? err}`);
+        console.error('  Is the daemon connected? Check with: beehaven status');
+        process.exit(1);
+    }
+    /**
+     * ⚠ NO SILENT DEGRADE. There is nothing to fall back to any more, and that is the point — see
+     * the note above. An identity that the cloud did not sign cannot be attributed, cannot be
+     * revoked from the account, and is refused by every workspace.
+     */
+    if (!minted?.token) {
+        console.error(`  Could not mint identity: ${minted?.error ?? 'the server returned no token'}`);
+        if (String(minted?.code) === 'not-configured') {
+            console.error('  The deployment is missing AGENT_IDENTITY_SECRET — this is a server-side fix.');
+        }
+        process.exit(1);
+    }
+    if (!minted?.token) {
+        console.error(`  Mint failed: ${minted?.error ?? 'no token returned'}`);
+        process.exit(1);
+    }
+    /**
+     * The workspace token and the desktop token have different verifiers. The former is signed by
+     * the staging/prod worker so it can travel through workspace RPCs; the latter is signed by the
+     * local daemon's keychain secret so `app-rpc` can safely drive a local avatar. Keeping the two
+     * credentials separate prevents a cloud-signed token from being presented to a verifier that
+     * cannot know the worker's secret — the failure used to surface as AGENT_INVALID after every
+     * Mac app restart, even though `agent login` itself succeeded.
+     */
+    let localToken;
+    try {
+        const local = await rpcOnce('agent:mint', {
+            agentId: minted.agentId,
+            kind,
+            displayName,
+            avatarId: minted.avatarId,
+            permissions: ['avatar:say', 'avatar:speak', 'avatar:emote'],
+            ...(voice ? { meta: { voice } } : {}),
+        }, 15_000);
+        localToken = local?.token ?? local?.result?.token;
+        if (!localToken)
+            console.error(dim('  ⚠ local avatar credential was not returned; workspace calls remain available'));
+    }
+    catch (err) {
+        // A headless/cloud-only CLI can still use the cloud identity without a local daemon. Preserve
+        // that workflow, but make the missing local avatar leg visible instead of silently sending a
+        // token the daemon cannot verify.
+        console.error(dim(`  ⚠ local avatar credential unavailable: ${err?.message ?? err}`));
+    }
+    /**
+     * ⚠ THE BIRTHDAY IS CARRIED FORWARD, NOT RE-STAMPED.
+     *
+     * `agent login` is also how an existing identity refreshes its token, so this
+     * runs over records that already exist. Taking `new Date()` unconditionally
+     * would reset every agent's age on a routine refresh — and because `issuedAt`
+     * already moves, nothing else would be left that remembers when the agent
+     * actually began. `existingRecord` is read before the write for exactly this.
+     */
+    const birthday = existingRecord?.birthday ?? new Date().toISOString();
+    const previousSessionEnded = await endWorkspaceSession(existingRecord, 'Replaced by a new login session for this agent identity.');
+    /**
+     * ⚠⚠ FILL THE LIFETIME FIELDS FROM THE TOKEN — the cloud mint path does not
+     * return them and a record without `expiresAt` can never be seen as expired.
+     * See `decodeAgentTokenClaims` for the full failure. Envelope values win when
+     * present (the local mint returns them from verified claims); the token is the
+     * fallback, and it is the same data either way.
+     */
+    const tokenClaims = decodeAgentTokenClaims(minted.token) ?? {};
+    const userId = minted.userId ?? tokenClaims.userId;
+    const issuedAt = minted.issuedAt ?? tokenClaims.issuedAt;
+    const expiresAt = minted.expiresAt ?? tokenClaims.expiresAt;
+    const record = {
+        agentId: minted.agentId,
+        kind: minted.kind,
+        displayName: minted.displayName,
+        avatarId: minted.avatarId,
+        ...(chosenSkin ? { avatarSkin: chosenSkin } : {}),
+        userId,
+        birthday,
+        token: minted.token,
+        ...(localToken ? { localToken } : {}),
+        issuedAt,
+        expiresAt,
+        ...(voice ? { voice } : {}),
+        /**
+         * ⚠⚠ THE BINDINGS SURVIVE THE RE-MINT — the same rule `birthday` is carried forward for,
+         * applied to every DURABLE field rather than to one.
+         *
+         * This object is built from scratch on each login, so `boundScopes` was DESTROYED by it:
+         * log in from a second terminal and the first silently reverted to "not logged in" while
+         * holding a stored, valid, unexpired identity. Measured — a login here dropped an existing
+         * `claude-507a5e19c44a` binding on the floor.
+         *
+         * ⚠ `sessionId` too. `saveAgentSession` normally rewrites it moments later, so the loss only
+         * surfaces when the workspace is unreachable — offline, where losing the session you were
+         * resuming is least recoverable.
+         */
+        ...(existingRecord?.boundScopes ? { boundScopes: existingRecord.boundScopes } : {}),
+        ...(!previousSessionEnded && existingRecord?.sessionId ? { sessionId: existingRecord.sessionId } : {}),
+        ...(existingRecord?.lastLoginAt ? { lastLoginAt: existingRecord.lastLoginAt } : {}),
+    };
+    saveAgent(name, record);
+    /**
+     * ⚠⚠ THIS SESSION IS `name` FROM HERE ON, WHATEVER THE WORKSPACE SAYS NEXT.
+     *
+     * The binding used to happen only after `agent-session-start` succeeded. When the workspace
+     * refused (an archived agent), nothing was bound, and every later call resolved through the
+     * FAMILY fallback to a sibling identity — `claude` logged in, `jinri-claude` did the work. An
+     * explicit login must own its own scope, so a refused identity is refused LOUDLY on each call
+     * instead of silently replaced. The family (what un-logged-in sessions inherit) is claimed
+     * below, only once a session actually starts.
+     */
+    const { deriveAgentScope } = await import('../agent-scope.js');
+    const { bindAgentScope, agentForScope, loginSessionOutcome } = await import('../agent-state.js');
+    const scope = deriveAgentScope();
+    bindAgentScope(name, scope, { family: false });
+    // Sync to Electron store if present
+    try {
+        const p = join(homedir(), 'Library', 'Application Support', 'clearly-desktop', 'config.json');
+        if (existsSync(p)) {
+            const c = JSON.parse(readFileSync(p, 'utf8'));
+            if (chosenSkin && c[`avatarSkin_${record.agentId}`] !== chosenSkin) {
+                c[`avatarSkin_${record.agentId}`] = chosenSkin;
+                writeFileSync(p, JSON.stringify(c, null, 2), 'utf8');
+            }
+        }
+    }
+    catch { }
+    // Materialize the injected context so the agent's Claude Code session can
+    // read (and `cat`) its personal notes/memories from login. The bundle rode
+    // in on the cloud mint response; the agent can also pull live via the
+    // clearly_memory_recall / clearly_memory_search MCP tools.
+    let injectedCount = 0;
+    let contextPath = '';
+    try {
+        const mem = minted.memory;
+        if (mem?.markdown) {
+            contextPath = join(homedir(), '.beehaven', 'agents', `${name}.context.md`);
+            mkdirSync(dirname(contextPath), { recursive: true });
+            writeFileSync(contextPath, mem.markdown, { mode: 0o600 });
+            injectedCount = mem.count ?? 0;
+        }
+    }
+    catch {
+        /* context file is best-effort — memory is still live via MCP */
+    }
+    const voiceLabel = record.voice
+        ? `, voice: ${record.voice.provider}${record.voice.voiceId ? `:${record.voice.voiceId}` : ''}`
+        : '';
+    const skinLabel = record.avatarSkin ? `, skin: ${record.avatarSkin}` : '';
+    console.log('');
+    console.log(`  ${green('✓')} Signed in as agent ${cyan(name)}  (avatar: ${record.avatarId}${skinLabel}, kind: ${record.kind}${voiceLabel})`);
+    if (minted?.soul?.enabled) {
+        const appearance = String(minted.soul.appearance ?? '').trim();
+        console.log(`  ${green('✦')} Avatar Soul ready — baseline minted${appearance ? `. ${appearance}` : '.'}`);
+        console.log(dim('    Soul: agent-soul-get · agent-soul-avatar-update · agent-soul-draft-get/save · agent-doodle-space-get/draw'));
+        console.log(dim('    Home: agent-home-get · agent-home-layout · agent-home-memory/journal · agent-home-ad · agent-home-avatar-location (24px grid)'));
+    }
+    if (sessionOpen)
+        console.log(`  ${green('◆')} Live agent presence connected.`);
+    if (contextPath) {
+        const what = injectedCount > 0
+            ? `operating guide + ${injectedCount} ${injectedCount === 1 ? 'memory' : 'memories'}`
+            : 'operating guide';
+        console.log(`  ${green('✎')} Context injected (${what}) → ${cyan(`~/.beehaven/agents/${name}.context.md`)}`);
+        console.log(dim(`     Read it at the start of every session — it explains the full platform + loads ${name}'s memory.`));
+    }
+    // ── THE SESSION, AND THE DIGEST ────────────────────────────────────────────────
+    //
+    // Logging in is exactly the moment an agent needs to know what it already did here, and
+    // exactly the moment it has the least context to think of asking. So the session start
+    // rides on login and PRINTS its brief — continuity you have to remember to request is
+    // continuity most agents will not have.
+    //
+    // Best-effort for an UNREACHABLE workspace: an identity that mints but cannot reach it is still
+    // a usable identity. ⚠ A workspace that ANSWERS and refuses is a different state — see
+    // `loginSessionOutcome` — and is reported, never swallowed.
+    let started;
+    let thrown;
+    try {
+        started = await rpcOnce('agent-session-start', {
+            agentId: record.agentId,
+            client: String(values.client ?? 'cli').trim() || 'cli',
+            label: String(values.label ?? '').trim() || undefined,
+            expiresAt: record.expiresAt,
+        }, 15_000);
+    }
+    catch (err) {
+        thrown = err ?? new Error('agent-session-start failed');
+    }
+    const outcome = loginSessionOutcome(started, thrown);
+    if (outcome.kind === 'started') {
+        saveAgentSession(name, outcome.sessionId);
+        /**
+         * ⚠⚠ CLAIM THE FAMILY — the step that makes the export optional.
+         *
+         * This function used to end by PRINTING `export BEEHAVEN_AGENT=<name>` and hoping.
+         * An agent that logged in and did not export was fully authenticated and still
+         * calling as nobody: identity minted, workspace session open, and every subsequent
+         * `beehaven call` attributed to the user.
+         *
+         * The exact scope is already bound above; this adds the tool family, so a later session of
+         * the same tool that has not logged in inherits an identity the workspace actually admits.
+         */
+        try {
+            bindAgentScope(name, deriveAgentScope());
+        }
+        catch { /* binding is a convenience — never fail a good login over it */ }
+        console.log('');
+        console.log(`  ${green('◷')} Workspace work session ${cyan(outcome.sessionId.slice(0, 8))} started.`);
+        printBrief(outcome.brief);
+    }
+    else if (outcome.kind === 'refused') {
+        console.log('');
+        console.error(`  ${yellow('⚠')} Signed in, but this workspace refused ${cyan(name)}: ${outcome.reason}`);
+        if (/revoked|not active|unknown agent|not admitted/i.test(`${outcome.scope} ${outcome.reason}`)) {
+            console.error(dim(`    The agent is archived or not admitted here. Restore it in Settings → Agent access,`));
+            console.error(dim(`    or log in as an active agent (beehaven call agent-list '{}' shows the roster).`));
+        }
+        console.error(dim(`    Calls from this session run as ${name} and will be refused — they will NOT fall back to another agent.`));
+        process.exitCode = 1;
+    }
+    console.log('');
+    {
+        // ⚠ Say whether the binding took — CHECKED, not assumed. This line used to print
+        // unconditionally, including after the binding had been skipped, which is how a session
+        // "bound to claude" spent an afternoon writing as `jinri-claude`.
+        if (scope) {
+            const resolved = agentForScope(scope);
+            if (resolved === name) {
+                console.log(`  ${green('✓')} Bound to this session (${cyan(scope)}) — every call here now runs as ${cyan(name)}.`);
+                console.log(dim('    Other terminals: export BEEHAVEN_AGENT=' + name));
+            }
+            else {
+                console.error(`  ${yellow('⚠')} Could not bind this session (${scope}) to ${name}; calls resolve to ${resolved ?? 'nobody'}.`);
+                console.error(dim(`    Pin it explicitly: export BEEHAVEN_AGENT=${name}`));
+                process.exitCode = 1;
+            }
+        }
+        else {
+            console.log('  Activate in THIS terminal:');
+            console.log(`    ${cyan(`eval "$(beehaven agent use ${name})"`)}`);
+            console.log(dim(`  or: export BEEHAVEN_AGENT=${name}`));
+        }
+    }
+    console.log('');
+}
+/**
+ * The login digest.
+ *
+ * Everything here answers a question a returning colleague asks before touching anything, and
+ * NOTHING here is printed when it is empty — a brief padded with "0 sessions · 0 memories ·
+ * nothing assigned" is a wall an agent learns to skip, which costs the one thing the digest
+ * has to buy: being read.
+ */
+function printBrief(brief) {
+    if (!brief)
+        return;
+    const sessions = brief.sessions?.recent ?? [];
+    const assigned = brief.assignedToMe ?? [];
+    const pending = brief.awaitingApproval ?? [];
+    const memories = brief.memories ?? [];
+    const focus = brief.focus ?? [];
+    /**
+     * ⚠ SS-41 — ADDRESSED TO YOU, AND PRINTED FIRST. Voicemail and @mentions are somebody speaking
+     * TO this agent; everything else in the brief is ambient. Both stay until acknowledged.
+     */
+    const mentions = brief.workspace?.mentions ?? [];
+    const voicemail = brief.workspace?.voicemail ?? [];
+    if (mentions.length || voicemail.length) {
+        console.log('');
+        console.log(`  ${bold('Addressed to you')} ${dim(`(${mentions.length + voicemail.length})`)}`);
+        for (const v of voicemail.slice(0, 3)) {
+            console.log(`    ${dim('·')} ${cyan('voicemail')} from ${v.from}: ${String(v.text ?? '').replace(/\s+/g, ' ').slice(0, 100)}`);
+        }
+        for (const m of mentions.slice(0, 5)) {
+            const on = m.on ?? {};
+            console.log(`    ${dim('·')} ${cyan('@mention')} from ${m.from} on ${on.kind || 'item'} “${on.title || on.id || ''}” ${dim(String(m.id).slice(0, 8))}`);
+            console.log(`      ${String(m.text ?? '').replace(/\s+/g, ' ').slice(0, 120)}`);
+        }
+        if (mentions.length)
+            console.log(dim(`      Act, reply with \`beehaven comment <ref> "…"\`, then \`beehaven mention ack <id>\`.`));
+    }
+    if (!sessions.length && !assigned.length && !pending.length && !memories.length && !focus.length) {
+        if (!mentions.length && !voicemail.length)
+            console.log(dim('     First visit — nothing to catch up on.'));
+        return;
+    }
+    const ago = (ts) => {
+        const d = Date.now() - ts;
+        if (d < 60_000)
+            return 'just now';
+        if (d < 3_600_000)
+            return `${Math.round(d / 60_000)}m ago`;
+        if (d < 86_400_000)
+            return `${Math.round(d / 3_600_000)}h ago`;
+        return `${Math.round(d / 86_400_000)}d ago`;
+    };
+    if (sessions.length) {
+        console.log('');
+        console.log(`  ${bold('Last time you were here')}`);
+        for (const s of sessions.slice(0, 3)) {
+            const when = s.startedAt ? ago(s.startedAt) : '';
+            const counts = `${s.actions} action${s.actions === 1 ? '' : 's'}${s.errors ? `, ${s.errors} error${s.errors === 1 ? '' : 's'}` : ''}`;
+            console.log(`    ${dim('·')} ${s.label || '(unlabelled)'} ${dim(`— ${when}, ${counts}`)}`);
+            // The summary is the payload. It is the one thing carrying reasoning rather than counts.
+            if (s.summary)
+                console.log(`      ${s.summary}`);
+        }
+    }
+    if (focus.length) {
+        console.log('');
+        console.log(`  ${bold('You were working on')}`);
+        for (const f of focus.slice(0, 3)) {
+            console.log(`    ${dim('·')} ${f.title || f.id} ${dim(`(${f.kind}, ${f.selected.length} selected)`)}`);
+        }
+    }
+    if (assigned.length) {
+        console.log('');
+        console.log(`  ${bold('Assigned to you')} ${dim(`(${assigned.length})`)}`);
+        for (const t of assigned.slice(0, 5)) {
+            console.log(`    ${dim('·')} ${t.key ? cyan(t.key) + ' ' : ''}${t.title} ${dim(`[${t.status}]`)}`);
+        }
+    }
+    if (pending.length) {
+        console.log('');
+        console.log(`  ${bold('Waiting on a human')} ${dim(`(${pending.length})`)}`);
+        for (const c of pending.slice(0, 4)) {
+            console.log(`    ${dim('·')} ${c.title || c.id} ${dim(c.kind ? `(${c.kind})` : '')}`);
+        }
+    }
+    if (memories.length) {
+        console.log('');
+        console.log(`  ${bold('You noted')}`);
+        for (const m of memories.slice(0, 4)) {
+            console.log(`    ${dim('·')} ${cyan(m.key)}: ${m.value.slice(0, 90)}${m.value.length > 90 ? '…' : ''}`);
+        }
+    }
+}
+// ── use (prints the export line for eval) ────────────
+async function agentUse(args) {
+    const name = args[0];
+    if (!name) {
+        // Usage goes to STDERR so a stray `eval "$(beehaven agent use)"` doesn't eval junk.
+        console.error('  Usage: eval "$(beehaven agent use <name>)"');
+        process.exit(1);
+    }
+    const record = loadAgent(name);
+    if (!record) {
+        console.error(`  No such agent "${name}". Create it: beehaven agent login ${name}`);
+        process.exit(1);
+    }
+    // The ONLY thing on STDOUT is the eval-able export line.
+    process.stdout.write(`export BEEHAVEN_AGENT=${name}\n`);
+    // Everything human goes to STDERR so `eval "$(...)"` captures just the export.
+    console.error(dim(`# agent ${name} active (avatar ${record.avatarId})`));
+}
+// ── list ─────────────────────────────────────────────
+async function agentList(values) {
+    const agents = listAgents();
+    const active = activeAgentName(values);
+    const localNames = new Set(agents.map((a) => a.name));
+    const localIds = new Set(agents.map((a) => a.record.agentId));
+    // The WORKSPACE is the source of truth — pull its agents so the list reflects
+    // identities that exist there but aren't signed in on THIS device.
+    let workspace = [];
+    try {
+        const r = await rpcOnce('agent-list', {}, 8_000);
+        const raw = r?.agents ?? r?.result?.agents ?? [];
+        workspace = raw
+            .map((x) => ({
+            id: String(x.id ?? x.agentId ?? ''),
+            name: String(x.name ?? x.id ?? ''),
+        }))
+            .filter((x) => x.id && x.id !== 'omni');
+    }
+    catch {
+        /* daemon down / offline — show local only */
+    }
+    if (!agents.length && !workspace.length) {
+        console.log('  No agent identities yet.');
+        console.log(dim('  Create one: beehaven agent login <name>'));
+        return;
+    }
+    console.log('');
+    console.log('  Agent identities');
+    console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    if (agents.length) {
+        console.log(dim('  Signed in on this device:'));
+        for (const { name, record } of agents) {
+            const marker = name === active ? green(' ●') : '  ';
+            const ttl = formatRemaining(record.expiresAt);
+            console.log(`${marker} ${cyan(name.padEnd(16))} avatar:${record.avatarId.padEnd(14)} ${dim(record.kind.padEnd(13))} ${ttl}`);
+        }
+    }
+    const remoteOnly = workspace.filter((w) => !localIds.has(w.id) && !localNames.has(w.name));
+    if (remoteOnly.length) {
+        console.log('');
+        console.log(dim('  In the workspace — not signed in here (`agent login <name>` to use):'));
+        for (const w of remoteOnly)
+            console.log(`    ${cyan(w.name.padEnd(20))} ${dim(w.id)}`);
+    }
+    console.log('');
+    console.log(dim(`  active = $BEEHAVEN_AGENT${active ? ` (${active})` : ' (none)'}  ·  workspace = source of truth`));
+    console.log('');
+}
+// ── whoami ───────────────────────────────────────────
+function agentWhoami(values) {
+    const active = resolveActiveAgent(values);
+    if (!active) {
+        console.log('  No active agent.');
+        console.log(dim('  Activate one: eval "$(beehaven agent use <name>)"  ·  or pass --agent <name>'));
+        return;
+    }
+    const r = active.record;
+    console.log('');
+    console.log(`  Agent ${cyan(active.name)}${active.expired ? '  ' + '\x1b[31m(expired)\x1b[0m' : ''}`);
+    console.log(`    agentId:     ${r.agentId}`);
+    console.log(`    kind:        ${r.kind}`);
+    console.log(`    avatar:      ${r.avatarId}`);
+    console.log(`    displayName: ${r.displayName}`);
+    console.log(`    owner:       ${r.userId}`);
+    // ⚠ "unknown" for pre-birthday identities — see the field's note. Showing today's
+    //   date would date every legacy agent to whenever someone first ran whoami.
+    console.log(`    birthday:    ${r.birthday ? formatBirthday(r.birthday) : 'unknown (created before birthdays)'}`);
+    console.log(`    voice:       ${r.voice?.provider ? (r.voice.voiceId ? `${r.voice.provider}:${r.voice.voiceId}` : `${r.voice.provider} (base voice)`) : 'unbound — speak picks whatever is reachable'}`);
+    console.log(`    expires:     ${formatRemaining(r.expiresAt)}`);
+    if (active.expired)
+        console.log(dim(`    refresh: beehaven agent login ${active.name}`));
+    console.log('');
+}
+async function agentStatus(args, values) {
+    const active = resolveActiveAgent(values);
+    const name = args[0] ?? active?.name;
+    const record = name ? loadAgent(name) : null;
+    const message = String(values.message ?? args.slice(name ? 1 : 0).join(' ') ?? '').trim();
+    if (!record || !name) {
+        console.error('  No active agent. Usage: beehaven agent status [<name>] --message "…"');
+        process.exit(1);
+    }
+    if (!message) {
+        console.error('  --message is required. Pass an empty message only through `beehaven call agent-status-set`.');
+        process.exit(1);
+    }
+    const raw = await rpcOnce('agent-status-set', { agentId: record.agentId, message }, 8_000);
+    const result = raw?.result ?? raw;
+    if (result?.ok === false || result?.error) {
+        console.error(`  ${result.error || 'Could not update agent status.'}`);
+        process.exit(1);
+    }
+    console.log(`  ${green('✓')} ${cyan(name)} status: ${String(result.message ?? message)}`);
+}
+// ── logout ───────────────────────────────────────────
+async function agentLogout(args, values) {
+    const name = args[0] ?? activeAgentName(values);
+    if (!name) {
+        console.error('  Specify an agent name, or set $BEEHAVEN_AGENT.');
+        console.error('  Usage: beehaven agent logout [<name>]');
+        process.exit(1);
+    }
+    const record = loadAgent(name);
+    if (!record) {
+        console.log(`  No such agent "${name}" on this device.`);
+        return;
+    }
+    // End the live workspace session (best-effort). The identity is NOT deleted —
+    // it stays in the workspace (source of truth) AND on this device, so you can
+    // log back in. To remove the current workspace projection use `agent delete <name>`;
+    // to remove the portable account identity use `agent delete <name> --account --yes`.
+    await endWorkspaceSession(record, 'Agent explicitly logged out.');
+    try {
+        await rpcOnce('agent:disconnect', { agentId: record.agentId ?? name }, 5_000);
+    }
+    catch {
+        /* daemon down — nothing to close */
+    }
+    clearAgentSession(name);
+    console.log(`  ${green('✓')} Signed out agent "${name}" — session ended, identity kept.`);
+    console.log(dim(`  Log back in: beehaven agent login ${name}   ·   workspace remove: beehaven agent delete ${name}`));
+    if (activeAgentName(values) === name && !values.agent) {
+        console.log(dim(`  This was your active agent — run: unset BEEHAVEN_AGENT`));
+    }
+}
+// ── delete (destructive — removes the identity from the workspace + device) ──
+async function agentDelete(args, values) {
+    const name = args[0] ?? activeAgentName(values);
+    if (!name) {
+        console.error('  Specify an agent name to delete.');
+        console.error('  Usage: beehaven agent delete <name>');
+        process.exit(1);
+    }
+    if (values.account === true)
+        return agentAccountDelete(args, values);
+    const record = loadAgent(name);
+    await endWorkspaceSession(record, 'Agent identity deleted.');
+    // 1. Remove from the WORKSPACE (source of truth) — the `agent-delete` RPC
+    //    soft-deletes (archived). Resolve by the record's agentId, else the name.
+    let cloud = false;
+    try {
+        const r = await rpcOnce('agent-delete', { id: record?.agentId ?? name }, 10_000);
+        cloud = !!(r?.ok ?? r?.result?.ok ?? (!r?.error && !r?.result?.error));
+    }
+    catch {
+        /* daemon down / not a workspace agent — local removal still proceeds */
+    }
+    // 2. Close any live session, then remove the LOCAL credential + context file.
+    try {
+        await rpcOnce('agent:disconnect', { agentId: record?.agentId ?? name }, 5_000);
+    }
+    catch {
+        /* ignore */
+    }
+    const removedLocal = deleteAgent(name);
+    if (!cloud && !removedLocal) {
+        console.log(`  No such agent "${name}".`);
+        return;
+    }
+    const parts = [cloud ? 'workspace' : '', removedLocal ? 'this device' : '']
+        .filter(Boolean)
+        .join(' + ');
+    console.log(`  ${green('✓')} Deleted agent "${name}" from ${parts}.`);
+    if (record)
+        console.log(dim(`  Avatar ${record.avatarId} released.`));
+}
+// ── account delete (destructive — removes the portable identity) ─────────
+async function agentAccountDelete(args, values) {
+    const name = args[0] ?? activeAgentName(values);
+    if (!name) {
+        console.error('  Specify an agent name to delete from the account.');
+        console.error('  Usage: beehaven agent delete <name> --account --yes');
+        process.exit(1);
+    }
+    if (values.yes !== true) {
+        console.error(`  Account deletion permanently removes the portable identity "${name}" from the account.`);
+        console.error('  It also releases the account avatar and cannot be undone.');
+        console.error('  Re-run with: beehaven agent delete ' + name + ' --account --yes');
+        process.exit(1);
+    }
+    const record = loadAgent(name);
+    const agentId = record?.agentId ?? name;
+    let raw;
+    try {
+        raw = await rpcOnce('agent-account-delete', { agentId }, 15_000);
+    }
+    catch (err) {
+        console.error(`  Could not delete account agent "${name}": ${err?.message ?? err}`);
+        process.exit(1);
+    }
+    const result = actionPayload(raw);
+    if (result?.ok === false || result?.error) {
+        console.error(`  ${result.error || `Could not delete account agent "${name}".`}`);
+        process.exit(1);
+    }
+    await endWorkspaceSession(record, 'Account agent identity deleted.');
+    try {
+        await rpcOnce('agent:disconnect', { agentId }, 5_000);
+    }
+    catch {
+        /* ignore */
+    }
+    const removedLocal = deleteAgent(name);
+    const parts = ['account', removedLocal ? 'this device' : ''].filter(Boolean).join(' + ');
+    console.log(`  ${green('✓')} Deleted agent "${name}" from ${parts}.`);
+    console.log(dim('  This is account-wide. Use `agent delete <name>` without --account for workspace-only removal.'));
+}
+// ── rebind ───────────────────────────────────────────
+async function agentRebind(args, values) {
+    const name = args[0];
+    const newAvatar = values.avatar ? String(values.avatar).trim() : undefined;
+    if (!name || !newAvatar) {
+        console.error('  Usage: beehaven agent rebind <name> --avatar <id>');
+        process.exit(1);
+    }
+    const record = loadAgent(name);
+    if (!record) {
+        console.error(`  No such agent "${name}". Create it: beehaven agent login ${name}`);
+        process.exit(1);
+    }
+    if (newAvatar === record.avatarId) {
+        console.log(`  Agent "${name}" already drives avatar "${newAvatar}".`);
+        return;
+    }
+    const collision = findAgentByAvatar(newAvatar, name);
+    if (collision) {
+        console.error(`  Avatar "${newAvatar}" is already claimed by agent "${collision}".`);
+        process.exit(1);
+    }
+    // Refresh the portable workspace token and the device-local app-rpc token separately. The
+    // daemon cannot verify the worker-signed token, and the worker cannot verify the device token.
+    let cloudMinted;
+    try {
+        cloudMinted = await rpcOnce('agent-account-mint', {
+            agentId: record.agentId,
+            displayName: record.displayName,
+            avatarId: newAvatar,
+        }, 15_000);
+    }
+    catch (err) {
+        console.error(`  Could not refresh workspace identity: ${err.message}`);
+        process.exit(1);
+    }
+    if (!cloudMinted?.token) {
+        console.error(`  Workspace refresh failed: ${cloudMinted?.error ?? 'no token returned'}`);
+        process.exit(1);
+    }
+    let localToken = record.localToken;
+    try {
+        const local = await rpcOnce('agent:mint', {
+            agentId: record.agentId,
+            kind: record.kind,
+            displayName: record.displayName,
+            avatarId: newAvatar,
+            permissions: ['avatar:say', 'avatar:speak', 'avatar:emote'],
+            ...(record.voice ? { meta: { voice: record.voice } } : {}),
+        }, 15_000);
+        localToken = local?.token ?? local?.result?.token ?? localToken;
+    }
+    catch (err) {
+        if (record.localToken) {
+            console.error(dim(`  ⚠ local avatar rebind unavailable: ${err?.message ?? err}`));
+            process.exit(1);
+        }
+    }
+    const updated = {
+        ...record,
+        avatarId: cloudMinted.avatarId ?? newAvatar,
+        avatarSkin: newAvatar,
+        token: cloudMinted.token,
+        ...(localToken ? { localToken } : {}),
+        issuedAt: cloudMinted.issuedAt ?? record.issuedAt,
+        expiresAt: cloudMinted.expiresAt ?? record.expiresAt,
+    };
+    saveAgent(name, updated);
+    try {
+        const p = join(homedir(), 'Library', 'Application Support', 'clearly-desktop', 'config.json');
+        if (existsSync(p)) {
+            const c = JSON.parse(readFileSync(p, 'utf8'));
+            c[`avatarSkin_${updated.agentId}`] = newAvatar;
+            writeFileSync(p, JSON.stringify(c, null, 2), 'utf8');
+        }
+    }
+    catch { }
+    console.log(`  ${green('✓')} Rebound agent "${name}" → avatar ${cyan(updated.avatarId)} (was ${record.avatarId}).`);
+}
+// ── helpers ──────────────────────────────────────────
+/**
+ * "2026-08-24 (3 days old)" — the date plus how long ago, because the age is the
+ * part anyone actually wants and subtracting dates in your head is friction.
+ *
+ * ⚠ Returns the raw string for anything unparseable rather than throwing or
+ * printing "Invalid Date": a corrupt field should not take `whoami` down with it.
+ */
+function formatBirthday(iso) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return iso;
+    const days = Math.floor((Date.now() - t) / 86_400_000);
+    const date = new Date(t).toISOString().slice(0, 10);
+    if (days <= 0)
+        return `${date} (today)`;
+    if (days === 1)
+        return `${date} (1 day old)`;
+    if (days < 60)
+        return `${date} (${days} days old)`;
+    const months = Math.floor(days / 30);
+    return `${date} (${months} month${months === 1 ? '' : 's'} old)`;
+}
+function formatRemaining(expiresAt) {
+    const ms = expiresAt - Date.now();
+    if (ms <= 0)
+        return '\x1b[31mexpired\x1b[0m';
+    const days = Math.floor(ms / 86_400_000);
+    if (days >= 1)
+        return dim(`${days}d left`);
+    const hours = Math.floor(ms / 3_600_000);
+    if (hours >= 1)
+        return dim(`${hours}h left`);
+    const mins = Math.floor(ms / 60_000);
+    return dim(`${mins}m left`);
+}