@clearlysh/beehaven 0.8.23 → 0.8.25

package/dist/commands/agent.js

@@ -25,7 +25,7 @@ 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';
+import { saveAgent, loadAgent, listAgents, deleteAgent, findAgentByAvatar, isValidAgentName, resolveActiveAgent, activeAgentName, saveAgentSession, clearAgentSession, clearAgentSessionId, decodeAgentTokenClaims, } from '../agent-state.js';
 const VALID_KINDS = ['claude-code', 'daemon-agent', 'clearly-ai'];
 export const FREE_SKINS = [
     'classic',
@@ -64,6 +64,16 @@ function normalizeCliAvatarSkin(raw) {
  * 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. */
+/**
+ * End the agent's workspace work session.
+ *
+ * ⚠⚠ `summary` IS THE AGENT'S HANDOFF NOTE, NEVER A LIFECYCLE REASON (AWO-225). The next login's
+ * brief prints a session's summary as its payload — "what I did, what's next". Every lifecycle end
+ * used to pass its reason here ("Replaced by a new login session for this agent identity.",
+ * "Agent explicitly logged out."), so the payload slot only ever held boilerplate. Worse, the
+ * Worker accepts a summary on an ALREADY-ENDED session, so a login after `agent handoff` replaced
+ * the agent's real note with "Replaced by a new login session". Only `agent handoff` passes one.
+ */
 async function endWorkspaceSession(record, summary) {
     const sessionId = String(record?.sessionId ?? '').trim();
     if (!sessionId)
@@ -72,7 +82,7 @@ async function endWorkspaceSession(record, summary) {
         const response = await rpcOnce('agent-session-end', {
             id: sessionId,
             ...(record?.agentId ? { agentId: record.agentId } : {}),
-            summary,
+            ...(summary?.trim() ? { summary: summary.trim() } : {}),
         }, 5_000);
         const result = response?.result ?? response;
         return result?.ok !== false && !result?.error;
@@ -106,6 +116,8 @@ export async function cmdAgentSub(positionals, values) {
             return agentStatus(rest, values);
         case 'logout':
             return agentLogout(rest, values);
+        case 'handoff':
+            return agentHandoff(rest, values);
         case 'delete':
         case 'remove':
             return agentDelete(rest, values);
@@ -134,6 +146,7 @@ export function isAgentIdentitySub(sub) {
         sub === 'whoami' ||
         sub === 'status' ||
         sub === 'logout' ||
+        sub === 'handoff' ||
         sub === 'delete' ||
         sub === 'remove' ||
         sub === 'rebind' ||
@@ -161,6 +174,7 @@ function printAgentUsage() {
     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('    handoff "<summary>"           end the work session with a note the next login reads first');
     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');
@@ -687,7 +701,7 @@ async function agentLogin(args, values) {
      * 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.');
+    const previousSessionEnded = await endWorkspaceSession(existingRecord);
     /**
      * ⚠⚠ 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.
@@ -880,104 +894,182 @@ async function agentLogin(args, values) {
     console.log('');
 }
 /**
- * The login digest.
+ * Summaries older CLIs wrote when a session ended for a lifecycle reason. They are not handoff
+ * notes (AWO-225), so the brief does not print them as one; sessions that carry them still show
+ * their label and counts. Kept until no client in the field writes them.
+ */
+const LIFECYCLE_SUMMARIES = new Set([
+    'Replaced by a new login session for this agent identity.',
+    'Agent explicitly logged out.',
+    'Agent identity deleted.',
+    'Account agent identity deleted.',
+]);
+const briefAgo = (ts, now) => {
+    const d = 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`;
+};
+const oneLine = (v, max) => {
+    const t = String(v ?? '').replace(/\s+/g, ' ').trim();
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+};
+/**
+ * The login digest, as lines (AWO-225: pure, so it can be tested without a workspace).
  *
  * 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.
+ *
+ * Order is the order of obligation: what someone asked you, what you left yourself, what is yours
+ * to do, what is waiting on a person, then where you were and what moved while you were away.
  */
-function printBrief(brief) {
+export function formatBrief(brief, now = Date.now()) {
+    const out = [];
     if (!brief)
-        return;
+        return out;
+    const section = (title, count) => {
+        out.push('');
+        out.push(`  ${bold(title)}${count === undefined ? '' : ` ${dim(`(${count})`)}`}`);
+    };
+    const ws = brief.workspace ?? {};
     const sessions = brief.sessions?.recent ?? [];
     const assigned = brief.assignedToMe ?? [];
     const pending = brief.awaitingApproval ?? [];
     const memories = brief.memories ?? [];
     const focus = brief.focus ?? [];
+    const recents = brief.recents ?? [];
+    const drafts = brief.drafts ?? [];
+    const changed = ws.changed ?? [];
+    const otherAgents = ws.otherAgents ?? [];
+    const openDecisions = ws.decisions?.open ?? [];
+    const pressure = brief.reviewPressure;
     /**
      * ⚠ 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 ?? [];
+    const mentions = ws.mentions ?? [];
+    const voicemail = ws.voicemail ?? [];
     /** WIB-1 — people and agents writing TO this agent. Oldest first; reading one clears it. */
-    const inbox = brief.workspace?.inboxThreads ?? [];
+    const inbox = ws.inboxThreads ?? [];
     if (mentions.length || voicemail.length || inbox.length) {
-        console.log('');
-        console.log(`  ${bold('Addressed to you')} ${dim(`(${mentions.length + voicemail.length + inbox.length})`)}`);
+        section('Addressed to you', mentions.length + voicemail.length + inbox.length);
         for (const t of inbox.slice(0, 5)) {
-            console.log(`    ${dim('·')} ${cyan('message')} from ${t.from}: “${t.subject}” ${dim(`${t.unread} unread · ${t.threadId}`)}`);
-            console.log(`      ${String(t.preview ?? '').replace(/\s+/g, ' ').slice(0, 120)}`);
+            out.push(`    ${dim('·')} ${cyan('message')} from ${t.from}: “${t.subject}” ${dim(`${t.unread} unread · ${t.threadId}`)}`);
+            out.push(`      ${oneLine(t.preview, 120)}`);
         }
         if (inbox.length)
-            console.log(dim(`      Read with \`beehaven inbox read <id>\`, answer with \`beehaven inbox reply <id> "…"\`, then \`beehaven inbox done <id>\`.`));
+            out.push(dim(`      Read with \`beehaven inbox read <id>\`, answer with \`beehaven inbox reply <id> "…"\`, then \`beehaven inbox done <id>\`.`));
         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)}`);
+            out.push(`    ${dim('·')} ${cyan('voicemail')} from ${v.from}: ${oneLine(v.text, 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)}`);
+            out.push(`    ${dim('·')} ${cyan('@mention')} from ${m.from} on ${on.kind || 'item'} “${on.title || on.id || ''}” ${dim(String(m.id).slice(0, 8))}`);
+            out.push(`      ${oneLine(m.text, 120)}`);
         }
         if (mentions.length)
-            console.log(dim(`      Act, reply with \`beehaven comment <ref> "…"\`, then \`beehaven mention ack <id>\`.`));
+            out.push(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 && !inbox.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`;
-    };
+    // ── What you left yourself. The handoff note is the payload; counts are context. ──
     if (sessions.length) {
-        console.log('');
-        console.log(`  ${bold('Last time you were here')}`);
+        section('Last time you were here');
         for (const s of sessions.slice(0, 3)) {
-            const when = s.startedAt ? ago(s.startedAt) : '';
+            const when = s.startedAt ? briefAgo(s.startedAt, now) : '';
             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)`)}`);
+            out.push(`    ${dim('·')} ${s.label || '(unlabelled)'} ${dim(`— ${when}, ${counts}`)}`);
+            const note = String(s.summary ?? '').trim();
+            if (note && !LIFECYCLE_SUMMARIES.has(note))
+                out.push(`      ${cyan('handoff:')} ${oneLine(note, 400)}`);
         }
     }
     if (assigned.length) {
-        console.log('');
-        console.log(`  ${bold('Assigned to you')} ${dim(`(${assigned.length})`)}`);
+        section('Assigned to you', assigned.length);
         for (const t of assigned.slice(0, 5)) {
-            console.log(`    ${dim('·')} ${t.key ? cyan(t.key) + ' ' : ''}${t.title} ${dim(`[${t.status}]`)}`);
+            out.push(`    ${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})`)}`);
+        section('Waiting on a human', pending.length);
         for (const c of pending.slice(0, 4)) {
-            console.log(`    ${dim('·')} ${c.title || c.id} ${dim(c.kind ? `(${c.kind})` : '')}`);
+            out.push(`    ${dim('·')} ${c.title || c.id} ${dim(c.kind ? `(${c.kind})` : '')}`);
+        }
+    }
+    /** WDP-9 — decisions still waiting on a person. Current decisions are context the agent can
+     *  re-read with `agent-brief`; open ones change what it should do next. */
+    if (openDecisions.length) {
+        section('Open decisions', openDecisions.length);
+        for (const d of openDecisions.slice(0, 4)) {
+            out.push(`    ${dim('·')} ${d.key ? cyan(d.key) + ' ' : ''}${d.title} ${dim(`[${d.state}]`)}`);
+        }
+    }
+    // ── Where you were. Focus is what you had selected; recents are the things themselves. ──
+    if (focus.length) {
+        section('You were working on');
+        for (const f of focus.slice(0, 3)) {
+            out.push(`    ${dim('·')} ${f.title || f.id} ${dim(`(${f.kind}, ${f.selected.length} selected)`)}`);
         }
     }
+    const shown = new Set([...focus, ...assigned].map((x) => String(x?.id ?? '')));
+    const whereLeft = recents.filter((r) => r?.id && !shown.has(String(r.id)) && r.title).slice(0, 4);
+    if (whereLeft.length) {
+        section('Where you left off');
+        for (const r of whereLeft) {
+            const what = [r.kind, [r.reason || 'touched', r.at ? briefAgo(r.at, now) : ''].filter(Boolean).join(' ')].filter(Boolean).join(', ');
+            out.push(`    ${dim('·')} ${oneLine(r.title, 80)} ${dim(`(${what})`)}`);
+        }
+    }
+    // ── What moved while you were away, and who moved it (`by` is the useful field). ──
+    if (changed.length) {
+        const waiting = ws.waiting ?? {};
+        const total = Number(waiting.changedByPeople ?? 0) + Number(waiting.changedByAgents ?? 0) || changed.length;
+        section('Changed since you were here', total);
+        for (const c of changed.slice(0, 4)) {
+            const who = c.actor ? `${c.actor}${c.by === 'agent' ? ' (agent)' : ''}` : c.by === 'agent' ? 'an agent' : 'a person';
+            out.push(`    ${dim('·')} ${oneLine(c.title || c.id, 70)} ${dim(`(${c.kind}) — ${c.op || 'changed'} by ${who}${c.at ? `, ${briefAgo(c.at, now)}` : ''}`)}`);
+        }
+    }
+    if (otherAgents.length) {
+        const names = otherAgents.slice(0, 4).map((a) => `${a.agentId} ${dim(`(${a.actions} action${a.actions === 1 ? '' : 's'}${a.last ? `, ${briefAgo(a.last, now)}` : ''})`)}`);
+        out.push('');
+        out.push(`  ${bold('Also working here')}  ${names.join(', ')}`);
+    }
+    // ── What you have not shared yet. Filing is sharing; an unfiled draft is invisible to the team. ──
+    if (drafts.length) {
+        section('Your unfiled drafts', drafts.length);
+        for (const d of drafts.slice(0, 3)) {
+            out.push(`    ${dim('·')} ${d.key ? cyan(d.key) + ' ' : ''}${oneLine(d.title, 80)}${d.updatedAt ? dim(` — ${briefAgo(d.updatedAt, now)}`) : ''}`);
+        }
+        out.push(dim('      Private to you until filed into a project.'));
+    }
+    if (pressure?.overBudget && pressure.instruction) {
+        out.push('');
+        out.push(`  ${yellow('⚠')} ${pressure.instruction}`);
+    }
     if (memories.length) {
-        console.log('');
-        console.log(`  ${bold('You noted')}`);
+        section('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 ? '…' : ''}`);
+            out.push(`    ${dim('·')} ${cyan(m.key)}: ${oneLine(m.value, 90)}`);
         }
     }
+    if (!out.length)
+        out.push(dim('     First visit — nothing to catch up on.'));
+    // The one way a session leaves the next one something to read. Printed every time: a handoff
+    // you have to remember to write is a handoff most sessions will not leave.
+    out.push('');
+    out.push(dim(`  Before you stop: beehaven agent handoff "what you did · what is next"`));
+    return out;
+}
+function printBrief(brief) {
+    if (!brief)
+        return;
+    for (const line of formatBrief(brief))
+        console.log(line);
 }
 // ── use (prints the export line for eval) ────────────
 async function agentUse(args) {
@@ -1092,6 +1184,41 @@ async function agentStatus(args, values) {
     }
     console.log(`  ${green('✓')} ${cyan(name)} status: ${String(result.message ?? message)}`);
 }
+// ── handoff ──────────────────────────────────────────
+/**
+ * End the current work session WITH a note — the one thing the next login (this agent's, or the
+ * colleague it hands to) reads first, under "Last time you were here" (AWO-225).
+ *
+ * Unlike `logout`, the identity stays signed in and bound: an agent hands off a stretch of work,
+ * not its seat. Only the ended session's id is forgotten (`clearAgentSessionId`), so the next
+ * `agent login` starts a fresh session and this terminal still resolves to this agent.
+ */
+async function agentHandoff(args, values) {
+    const name = activeAgentName(values);
+    const summary = (args.join(' ') || String(values.summary ?? '')).trim();
+    if (!name || !summary) {
+        console.error('  Usage: beehaven agent handoff "<what you did · what is next>" [--agent <name>]');
+        if (!name)
+            console.error('  No active agent: log in first, or pass --agent <name>.');
+        process.exit(1);
+    }
+    const record = loadAgent(name);
+    if (!record?.sessionId) {
+        console.error(`  ${yellow('⚠')} ${cyan(name)} has no open work session on this device.`);
+        console.error(dim(`    Start one with: beehaven agent login ${name} --label "<work>" --client cli`));
+        process.exitCode = 1;
+        return;
+    }
+    const ended = await endWorkspaceSession(record, summary);
+    if (!ended) {
+        console.error(`  ${yellow('⚠')} The workspace did not accept the handoff; the session is still open.`);
+        console.error(dim('    Check `beehaven status`, then run the same command again.'));
+        process.exitCode = 1;
+        return;
+    }
+    clearAgentSessionId(name);
+    console.log(`  ${green('✓')} Handed off session ${cyan(String(record.sessionId).slice(0, 8))} — the next login for ${cyan(name)} reads this first.`);
+}
 // ── logout ───────────────────────────────────────────
 async function agentLogout(args, values) {
     const name = args[0] ?? activeAgentName(values);
@@ -1109,7 +1236,7 @@ async function agentLogout(args, values) {
     // 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.');
+    await endWorkspaceSession(record);
     try {
         await rpcOnce('agent:disconnect', { agentId: record.agentId ?? name }, 5_000);
     }
@@ -1134,7 +1261,7 @@ async function agentDelete(args, values) {
     if (values.account === true)
         return agentAccountDelete(args, values);
     const record = loadAgent(name);
-    await endWorkspaceSession(record, 'Agent identity deleted.');
+    await endWorkspaceSession(record);
     // 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;
@@ -1193,7 +1320,7 @@ async function agentAccountDelete(args, values) {
         console.error(`  ${result.error || `Could not delete account agent "${name}".`}`);
         process.exit(1);
     }
-    await endWorkspaceSession(record, 'Account agent identity deleted.');
+    await endWorkspaceSession(record);
     try {
         await rpcOnce('agent:disconnect', { agentId }, 5_000);
     }

package/dist/commands/canvas-image.js

@@ -25,6 +25,50 @@ function coordinateFlag(raw, label) {
         throw new Error(`${label} must be a number`);
     return value;
 }
+/**
+ * ⚠ NATIVE SIZE IS READ HERE, FROM THE FILE'S OWN HEADER. The docs promise "omit both size flags to
+ * use the image's native dimensions", but nothing measured the image, so the server's placeholder
+ * box won: a 1032×320 PNG landed as a 400×400 node with its aspect squashed (CDS-26). PNG, GIF,
+ * JPEG and WebP carry their size in the first bytes; AVIF (ISO-BMFF) falls back to the server.
+ */
+export function imageSize(buf, mime) {
+    try {
+        if (mime === 'image/png' && buf.length >= 24 && buf.toString('ascii', 12, 16) === 'IHDR') {
+            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+        }
+        if (mime === 'image/gif' && buf.length >= 10)
+            return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+        if (mime === 'image/webp' && buf.length >= 30 && buf.toString('ascii', 8, 12) === 'WEBP') {
+            const kind = buf.toString('ascii', 12, 16);
+            if (kind === 'VP8X')
+                return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) };
+            if (kind === 'VP8L') {
+                const b = buf.readUInt32LE(21);
+                return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
+            }
+            if (kind === 'VP8 ')
+                return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+        }
+        if (mime === 'image/jpeg' && buf[0] === 0xff && buf[1] === 0xd8) {
+            let i = 2;
+            while (i + 9 < buf.length) {
+                if (buf[i] !== 0xff) {
+                    i++;
+                    continue;
+                }
+                const marker = buf[i + 1];
+                const len = buf.readUInt16BE(i + 2);
+                // SOF0–SOF15 except DHT(C4), JPG(C8), DAC(CC) carry the frame size.
+                if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                    return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+                }
+                i += 2 + len;
+            }
+        }
+    }
+    catch { /* fall back to the server's default */ }
+    return null;
+}
 function absoluteRelayUrl(url) {
     if (!url.startsWith('/'))
         return url;
@@ -54,12 +98,19 @@ export async function cmdCanvasAddImage(positionals, values) {
         throw new Error(`Image must be 1 byte to 100 MB (${stat.size} bytes given)`);
     const x = coordinateFlag(values.x, '--x');
     const y = coordinateFlag(values.y, '--y');
-    const width = positiveFlag(values.width, '--width');
-    const height = positiveFlag(values.height, '--height');
+    let width = positiveFlag(values.width, '--width');
+    let height = positiveFlag(values.height, '--height');
     if ((x === undefined) !== (y === undefined))
         throw new Error('Pass --x and --y together');
     if ((width === undefined) !== (height === undefined))
         throw new Error('Pass --width and --height together');
+    if (width === undefined) {
+        const native = imageSize(readFileSync(path), mimeType);
+        if (native && native.width > 0 && native.height > 0) {
+            width = native.width;
+            height = native.height;
+        }
+    }
     // Refuse an unknown target before putting bytes in storage for a canvas that cannot use them.
     const target = await rpcOnce('composition-detail', { id: compositionId }, 30_000);
     if (target?.error || target?.composition?.id !== compositionId) {
@@ -93,7 +144,10 @@ export async function cmdCanvasAddImage(positionals, values) {
     if (placed?.ok !== true || !placed?.nodeId && !placed?.blockId) {
         throw new Error(`Image uploaded but could not be placed: ${placed?.error ?? 'unknown error'}. Asset key: ${key}`);
     }
-    const result = { ok: true, compositionId, nodeId: placed.nodeId ?? placed.blockId, imageFileId: recorded?.id, name };
+    // ⚠ `src` IS RETURNED — reusing an upload (a brand logo, a second placement) needed a scene read
+    //   to find the URL the node stores (CDS-27).
+    const src = String(placed?.src ?? placed?.url ?? placed?.node?.src ?? absoluteRelayUrl(String(intent.publicUrl)));
+    const result = { ok: true, compositionId, nodeId: placed.nodeId ?? placed.blockId, imageFileId: recorded?.id, name, src, ...(width !== undefined ? { width, height } : {}) };
     if (values.json)
         console.log(JSON.stringify(result, null, 2));
     else

package/dist/commands/canvas.js

@@ -243,7 +243,7 @@ async function cmdCanvasPublishLanding(positionals, values) {
     }
     const block = embed?.block ?? embed?.result?.block;
     console.log(`  ✓ Published: site comp ${siteCompositionId} embedded as block ${block?.id ?? '?'} on pasteboard ${targetCompositionId}`);
-    console.log(`  ✓ Open it: https://clearly.sh/c/${targetCompositionId}`);
+    console.log(`  ✓ Open it: https://www.clearly.sh/c/${targetCompositionId}`);
     return print(embed, values);
 }
 async function cmdCanvasPasteText(positionals, values) {

package/dist/commands/compose.js

@@ -401,7 +401,7 @@ export async function cmdComposePush(_values) {
     }
     console.log('');
     console.log(`  Composition live at:`);
-    console.log(`    https://clearly.sh/app/compositions/${link.compositionId}`);
+    console.log(`    https://www.clearly.sh/app/compositions/${link.compositionId}`);
     console.log('');
     console.log(`  Create a public share link with:`);
     console.log(`    beehaven compose share --password <pw>`);
@@ -466,7 +466,7 @@ export async function cmdComposeShare(values) {
             process.exit(1);
         }
         console.log(`  \u2713 Share link created`);
-        console.log(`    https://clearly.sh/r/${res.id}`);
+        console.log(`    https://www.clearly.sh/r/${res.id}`);
         if (input.password)
             console.log(`    Password: ${input.password}`);
         if (input.expiresAt)

package/dist/commands/daemon-cmd.js

@@ -138,6 +138,38 @@ export async function startHeadlessDaemon(values) {
         ? `     Ready — socket answering.`
         : `     Started, but not answering yet after ${Math.round(DAEMON_READY_TIMEOUT_MS / 1000)}s. 'beehaven status' shows state.`);
 }
+/**
+ * ⚠⚠ WHO IS ACTUALLY SERVING AFTER A RESPAWN. `restart` used to print the PID it spawned and stop
+ * there. On a Mac with the Clearly app open, the tray supervisor respawns ITS daemon the moment the
+ * old one dies — so the CLI's spawn lost the single-instance race ("Refusing to start — daemon
+ * already running"), exited, and the user was told "Daemon restarted (PID 5706)" about a process
+ * that no longer existed (observed 2026-10-01; the next call said "Cannot connect to daemon").
+ * This waits for a usable socket and reports the PID that is really live.
+ */
+export async function waitForServingDaemon(spawnedPid) {
+    const { isDaemonRunning } = await import('../daemon-client.js');
+    const alive = (pid) => { if (!pid)
+        return false; try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    let ready = false;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, DAEMON_POLL_MS));
+        if (await isDaemonRunning()) {
+            ready = true;
+            break;
+        }
+        // The spawn died and nobody else took over: no point waiting out the clock.
+        if (!alive(spawnedPid) && findLiveDaemons().length === 0)
+            break;
+    }
+    return { ready, spawnedAlive: alive(spawnedPid), livePids: findLiveDaemons() };
+}
 export async function cmdDaemon(sub, values) {
     switch (sub) {
         case 'start':

package/dist/commands/help.js

@@ -1790,6 +1790,7 @@ const PAGES = {
       agent use <name>     — prints \`export BEEHAVEN_AGENT=<name>\`; eval it
       agent list           — list stored identities, mark the active one
       agent whoami         — show the active identity + TTL
+      agent handoff "<summary>" — end the work session with a note; the next login prints it first
       agent logout [<name>]— end its local session, keep the identity
       agent delete <name>  — archive the current workspace projection + remove this device copy
       agent delete <name> --account --yes
@@ -1825,6 +1826,7 @@ const PAGES = {
             { cmd: 'beehaven say "hi from monet"', note: "speaks via monet's avatar" },
             { cmd: 'beehaven agent rebind monet --avatar studio-2' },
             { cmd: 'beehaven agent whoami' },
+            { cmd: 'beehaven agent handoff "Fixed AWO-224 login; next: release the CLI"', note: 'leave the next session a note' },
             { cmd: 'beehaven agent "what can you do?"', note: 'REPL one-shot' },
         ],
         related: ['app', 'pipe', 'pwd'],

package/dist/commands/self-update.js

@@ -6,7 +6,7 @@
  * `checkForUpdates` printed, unconditionally:
  *
  *     Update available: 0.7.6 → 0.7.8
- *     Run curl -fsSL https://clearly.sh/install.sh | sh to update
+ *     Run curl -fsSL https://www.clearly.sh/install.sh | sh to update
  *
  * For anyone whose `beehaven` comes from the Mac app — which is EVERY ordinary user, since the
  * app bundles the CLI and installs the wrapper — following that instruction used to be actively
@@ -117,7 +117,7 @@ export function runSelfUpdate(kind = installKind()) {
         return { ok: false, message: updateHint(kind) };
     }
     const feed = (process.env.BEEHAVEN_CLI_FEED || 'https://downloads.clearly.sh/cli/').replace(/\/+$/, '');
-    const installerUrl = process.env.BEEHAVEN_INSTALL_URL || 'https://clearly.sh/install.sh';
+    const installerUrl = process.env.BEEHAVEN_INSTALL_URL || 'https://www.clearly.sh/install.sh';
     const temp = mkdtempSync(join(tmpdir(), 'beehaven-self-update-'));
     try {
         const manifestPath = join(temp, 'latest.json');

package/dist/commands/workspace.js

@@ -3065,15 +3065,20 @@ export async function cmdBroadcast(rawMsg, values) {
  * calling all along (`Avatar.ts` `replyWithOmni`), which is why Omni was
  * reachable from the desktop companion and not from the terminal.
  *
- * The payload matters as much as the name: `agentId: 'omni'` selects the
- * orchestrator, and `wait: true` is what makes this a one-shot rather than a
+ * The payload matters as much as the name: `agentId: 'builtin:clearly'` selects the
+ * workspace's built-in assistant, and `wait: true` is what makes this a one-shot rather than a
  * fire-and-forget that prints an ack and exits before the reply exists.
+ *
+ * ⚠ AWO-226: it sent `'omni'`, the built-in's old name. Since PPO-291 an untyped row reads as an
+ * external identity, and workspaces old enough to carry the legacy `omni` row refused every
+ * `beehaven agent "…"` with "Omni is an external agent" (staging home, 2026-10-06).
+ * `builtin:clearly` is the id the server always resolves to the built-in, on old and new Workers.
  */
 export async function cmdAgent(prompt, values) {
     try {
         const result = await rpcOnce('agent-prompt', {
             message: prompt,
-            agentId: 'omni',
+            agentId: 'builtin:clearly',
             wait: true,
             // ⚠ NOT `cwd`. The old call passed the shell's working directory, which
             // the action does not accept — a local path is meaningless to a cloud