beehaven 0.8.21 → 0.8.24

package/dist/agent-sessions.js

@@ -210,7 +210,7 @@ export class AgentSessions {
             return;
         }
         const base = this.wsBase().replace(/\/$/, '');
-        const url = `${base}/my/hive/ws?token=${encodeURIComponent(spec.token)}&clientType=agent&client=agent&wsType=workspace&deviceId=agent-${encodeURIComponent(agentId)}`;
+        const url = `${base}/my/workspace/ws?token=${encodeURIComponent(spec.token)}&clientType=agent&client=agent&deviceId=agent-${encodeURIComponent(agentId)}`;
         let ws;
         let opened = false;
         let settled = false;

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = 'f651981dfa50';
+export const BUILD_SHA = '150d0d2c336a';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-29T18:13Z';
+export const BUILD_TIME = '2026-10-02T08:34Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -309,7 +309,8 @@ ${DEV_ONLY_HELP ? `  PROJECT — build your own Durable Object backend  (HIVE_DE
     app setup <name>                       Re-run a hive's setup script
     install <pkg>                          Shorthand for "app install <pkg>"
     skills install                         Teach every agent about Clearly —
-                                           writes the shipped SKILL.md files
+                                           writes the shipped SKILL.md files + the
+                                           AGENTS.md / GEMINI.md / CLAUDE.md block
     skills <list|sync|remove>              Manage skills paired with installed hives
 
     Deep dive:  beehaven help hives        Mental model + install/connect/call loop
@@ -437,7 +438,9 @@ ${DEV_ONLY_HELP ? `
   ACCOUNT
   ─────────────────────────────────────────────────────────────────────
 
-    login                                  Sign in (browser) — primary flow
+    login                                  Sign in (browser) — primary flow; also teaches
+                                           your agents (skills + AGENTS.md block;
+                                           --no-agent-setup to skip)
     login --email <e> --password <p>       Self-hosted email/password (set BEEHAVEN_API_URL)
     logout                                 Clear local credentials + keychain
     signup                                 Open sign-up page in browser
@@ -1299,7 +1302,25 @@ async function run() {
         await shorthandCmd(rawVerb, process.argv.slice(3), {});
         return;
     }
+    /**
+     * ⚠ `--x -3000` IS A NEGATIVE COORDINATE, NOT A FLAG. node's parseArgs reads any value starting
+     * with a dash as a missing argument and dies with "Option '--x' argument is ambiguous" — which is
+     * how `beehaven canvas add-image … --x -3000` failed (CDS-25). Join a negative NUMBER onto the
+     * coordinate/size flag before it; nothing else is rewritten.
+     */
+    const NUMERIC_FLAGS = new Set(['--x', '--y', '--width', '--height', '--w', '--h', '--dx', '--dy']);
+    const argv = [];
+    for (let i = 2; i < process.argv.length; i++) {
+        const a = process.argv[i], b = process.argv[i + 1];
+        if (NUMERIC_FLAGS.has(a) && typeof b === 'string' && /^-\d+(\.\d+)?$/.test(b)) {
+            argv.push(`${a}=${b}`);
+            i++;
+            continue;
+        }
+        argv.push(a);
+    }
     const { values, positionals } = parseArgs({
+        args: argv,
         allowPositionals: true,
         options: {
             project: { type: 'string' },
@@ -1492,6 +1513,7 @@ async function run() {
             // Paired Claude Code skill install policy (see commands/skills.ts)
             'with-skills': { type: 'boolean', default: false },
             'no-skills': { type: 'boolean', default: false },
+            'no-agent-setup': { type: 'boolean', default: false },
             // ── mobile-install metadata for `beehaven teleport <build>.ipa --composition <id>`
             //    (see commands/workspace.ts — wantMobileInstall branch).
             //    Future: parse Info.plist / AndroidManifest.xml automatically
@@ -1950,6 +1972,7 @@ async function run() {
          * flag with two meanings is worse than a refusal that names the alternative.
          */
         'ticket',
+        'inbox',
         /**
          * ⚠ `trash` — CBH2-34. It pages `document-list { archived: true }` and honours `--limit` up to
          * 500, announcing the clamp when the ask is higher. Left off this list the flag is REFUSED,
@@ -2944,11 +2967,24 @@ async function run() {
             // omitted BEEHAVEN_HEADLESS=1, so the "restarted" daemon hit the
             // parent-death watchdog and exited ~3s later — restart reported a PID and
             // left you with nothing running. See spawnStandaloneDaemon's comment.
-            const { spawnStandaloneDaemon } = await import('./commands/daemon-cmd.js');
+            const { spawnStandaloneDaemon, waitForServingDaemon } = await import('./commands/daemon-cmd.js');
             const { resolveRelayUrlForDaemon } = await import('./daemon.js');
             const relayUrl = resolveRelayUrlForDaemon();
             const pid = spawnStandaloneDaemon(values);
-            console.log(`  Daemon restarted (PID ${pid}).`);
+            // ⚠ Report the daemon that is ACTUALLY serving — see waitForServingDaemon.
+            const served = await waitForServingDaemon(pid);
+            if (served.ready && served.spawnedAlive) {
+                console.log(`  Daemon restarted (PID ${pid}). Ready — socket answering.`);
+            }
+            else if (served.ready) {
+                console.log(`  Another supervisor (the Clearly app) restarted the daemon first — PID ${served.livePids.join(', ')} is serving. Ready.`);
+            }
+            else {
+                console.error(served.livePids.length
+                    ? `  Daemon process is up (PID ${served.livePids.join(', ')}) but its socket is not answering yet. 'beehaven status' shows state.`
+                    : `  The daemon did not stay up (spawned PID ${pid} exited). Run 'beehaven start --headless', or reopen the Clearly app.`);
+                process.exitCode = 1;
+            }
             console.log(`  Relay: ${color.dim(relayUrl)}`);
             break;
         }
@@ -3302,6 +3338,31 @@ async function run() {
              */
             console.log(`  ${color.green('✓')} Connected — your new sign-in is live`);
             console.log(`    Background service ${wasRunning ? 'restarted' : 'started'} (PID ${pid})`);
+            /**
+             * ⚠⚠ TEACH THE AGENTS AS PART OF SIGNING IN (PPO-190). "Install the CLI, log in, and your
+             * agents handle the rest" needs the agents to KNOW about the CLI — the skills plus the
+             * instruction block in ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and a pointer in
+             * ~/.claude/CLAUDE.md. That used to be a separate `beehaven skills install` the installer's
+             * closing text asked for, and a step people skip is a step that did not happen.
+             *
+             * ⚠ Idempotent and non-fatal: unchanged files are not rewritten, symlinked files are left
+             * alone, and a failure here never fails the sign-in. Opt out with `--no-agent-setup` or
+             * BEEHAVEN_NO_AGENT_SETUP=1; undo with `beehaven skills uninstall`.
+             */
+            if (!values['no-agent-setup'] && process.env.BEEHAVEN_NO_AGENT_SETUP !== '1') {
+                try {
+                    const { installAgentSkills } = await import('./commands/agent-skills.js');
+                    const { installAgentInstructions } = await import('./commands/agent-instructions.js');
+                    const sk = installAgentSkills();
+                    const ins = installAgentInstructions();
+                    const changed = [...sk.steps, ...ins.steps].filter((x) => /=(written|updated)$/.test(x)).length;
+                    console.log(`  ${color.green('✓')} Your agents know about Clearly${changed ? '' : color.dim(' (already set up)')}`);
+                    console.log(color.dim('    Skills + instructions for Claude Code, Codex, Gemini and pi · undo: beehaven skills uninstall'));
+                }
+                catch (err) {
+                    console.log(color.dim(`    Agent setup skipped: ${err?.message ?? err} — run: beehaven skills install`));
+                }
+            }
             console.log('');
             break;
         }
@@ -3896,7 +3957,13 @@ complete -F _beehaven_completions beehaven`);
              */
             if (sub === 'install' || sub === 'uninstall') {
                 const { installAgentSkills, removeAgentSkills, AGENT_SKILL_DIRS } = await import('./commands/agent-skills.js');
+                const { installAgentInstructions, removeAgentInstructions } = await import('./commands/agent-instructions.js');
                 const r = sub === 'install' ? installAgentSkills() : removeAgentSkills();
+                // ⚠ The instruction block travels with the skills (PPO-190) — a skill is only OFFERED;
+                // the block is what makes an agent reach for `beehaven` at all.
+                const ins = sub === 'install' ? installAgentInstructions() : removeAgentInstructions();
+                r.steps.push(...ins.steps);
+                r.warnings.push(...ins.warnings);
                 const wrote = r.steps.filter((x) => /=(written|updated)$/.test(x)).length;
                 const current = r.steps.filter((x) => x.endsWith('=current')).length;
                 const removed = r.steps.filter((x) => x.endsWith('=removed')).length;
@@ -6647,9 +6714,7 @@ complete -F _beehaven_completions beehaven`);
             break;
         }
         case 'swarm': {
-            // Distributed hive mesh — see the swarm, set THIS machine's role, and
-            // dispatch work to worker beehives. One namespace for the whole mesh
-            // (`hive`/`hives` already name the local-apps concept).
+            // Queen and Omni identity commands remain; node registry/dispatch was retired.
             const { cmdSwarm } = await import('./commands/swarm.js');
             await cmdSwarm(positionals, values);
             break;

package/dist/commands/agent-instructions.js

@@ -0,0 +1,182 @@
+/**
+ * agent-instructions — the "use the beehaven CLI" block in each agent's GLOBAL instruction file.
+ *
+ * ⚠⚠ THE MISSING HALF OF "install the CLI, log in, and your agents handle the rest" (PPO-190).
+ * `skills install` put SKILL.md files on disk, but a skill is only OFFERED to a model when its
+ * description matches. The instruction block is what makes an agent reach for `beehaven` at all
+ * when the user says "put this on my board". The Mac app has written it on every launch
+ * (`apps/electron/electron/agent-skills-installer.ts`); the CLI never did, so a CLI-only user's
+ * Codex and Gemini had skills they never used.
+ *
+ * ⚠⚠ BYTE-IDENTICAL TO THE MAC APP'S BLOCK, MARKER LINE INCLUDED. Both writers splice between the
+ * same BLOCK_START / BLOCK_END. If their text differed by one character, a machine with both would
+ * rewrite the file on every app launch and every CLI install, each undoing the other. One text
+ * means both converge and either uninstaller removes it. `agentInstructionParity.test.mjs` in the
+ * root repo pins the two copies together.
+ *
+ * ⚠ CLAUDE GETS THE SHORT POINTER — `~/.claude/CLAUDE.md` is prepended to every Claude Code
+ * session in every repository, so it carries a pointer to the skills, not a manual. Same rule as
+ * the Mac app; see its note on `AGENT_INSTRUCTION_FILES`.
+ *
+ * ⚠ ONLY OUR BLOCK IS EVER TOUCHED. Text around it is preserved byte for byte; a file with no
+ * block gets one appended; removal deletes the block and nothing else.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const MANAGED_MARKER = 'managed-by: clearly-mac-app';
+export const BLOCK_START = '<!-- clearly:beehaven-cli:start -->';
+export const BLOCK_END = '<!-- clearly:beehaven-cli:end -->';
+/** Resolved at call time so tests can point HOME at a temp dir. */
+export function agentInstructionFiles(home = os.homedir()) {
+    return [
+        { agent: 'codex', file: path.join(home, '.codex', 'AGENTS.md') },
+        { agent: 'gemini', file: path.join(home, '.gemini', 'GEMINI.md') },
+        { agent: 'claude', file: path.join(home, '.claude', 'CLAUDE.md') },
+    ];
+}
+/** The managed block appended to AGENTS.md / GEMINI.md. Keep identical to the Mac app's. */
+export function instructionBlock() {
+    return [
+        BLOCK_START,
+        `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
+        '',
+        '## Clearly — drive it with the `beehaven` CLI',
+        '',
+        'Clearly (clearly.sh) is a workspace — documents, projects, boards, tickets and a design',
+        'canvas. Reach it from the shell with the `beehaven` CLI, NOT an HTTP API you construct.',
+        '',
+        '⚠ SIGN IN FIRST. Every call is attributed to an agent identity, and without one the CLI',
+        'refuses. `login` MINTS the name if it does not exist yet, and binds this terminal:',
+        '',
+        '```sh',
+        'beehaven agent login <your-name>   # required — mints + binds, once per session',
+        'beehaven connect home              # target the personal workspace',
+        'beehaven actions                   # list every action available there',
+        'beehaven call <action> \'{...}\'',
+        '```',
+        '',
+        'Read the full skills before driving it — they carry the exact verbs and node shapes:',
+        '',
+        '- `~/.<agent>/skills/clearly-agent/SKILL.md` — **read this first**: identity, sessions, your brief',
+        '- `~/.<agent>/skills/beehaven-cli/SKILL.md` — connect / call / sql / logs, the daemon',
+        '- `~/.<agent>/skills/clearly-workspace/SKILL.md` — audit what a workspace holds and who made it',
+        '- `~/.<agent>/skills/clearly-canvas/SKILL.md` — build + perceive a canvas, comm blocks, code diffs',
+        '- `~/.<agent>/skills/design-craft/SKILL.md` — **load before any visual work**: grid, type, colour, the studio pass',
+        '- `~/.<agent>/skills/layout-systems/SKILL.md` — grids and systems across many artboards',
+        '- `~/.<agent>/skills/pair-on-canvas/SKILL.md` — drive a coding task from a spec on the canvas',
+        '- `~/.<agent>/skills/codebase-map/SKILL.md` — draw a repo’s architecture on the canvas',
+        '',
+        'If a command reports the daemon is unreachable, `beehaven login` re-auths and',
+        '`beehaven start --headless` starts a daemon when the Mac app is not running.',
+        BLOCK_END,
+    ].join('\n');
+}
+/** The short form, for `~/.claude/CLAUDE.md`. Keep identical to the Mac app's `claudeBlock()`. */
+export function claudeBlock() {
+    return [
+        BLOCK_START,
+        `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
+        '',
+        '**Clearly workspace** — drive it from the shell with the `beehaven` CLI (documents, projects,',
+        'boards, tickets, canvas). Sign in once per session first: `beehaven agent login <name>` —',
+        'it mints the identity if new. Full detail is in the skills, `clearly-agent` first.',
+        BLOCK_END,
+    ].join('\n');
+}
+/** Insert or replace our block, leaving everything around it untouched. Pure. */
+export function upsertBlock(existing, block) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+    }
+    return existing.trim() ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`;
+}
+/** Remove our block (and the blank line it was appended after). Pure. */
+export function stripBlock(existing) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start === -1 || end === -1 || end < start)
+        return existing;
+    const before = existing.slice(0, start).replace(/\n{1,2}$/, '\n');
+    const after = existing.slice(end + BLOCK_END.length).replace(/^\n/, '');
+    const out = (before + after);
+    return out.trim() ? out : '';
+}
+/**
+ * Write the block into every agent's global instruction file. Idempotent: an unchanged file is
+ * reported `=current` and not rewritten.
+ *
+ * ⚠ A SYMLINKED INSTRUCTION FILE IS LEFT ALONE. People keep dotfiles in a repo and link them in;
+ * writing through the link would silently edit their checkout. Same rule as the skills installer.
+ */
+export function installAgentInstructions(home = os.homedir()) {
+    const steps = [];
+    const warnings = [];
+    for (const { agent, file } of agentInstructionFiles(home)) {
+        try {
+            /**
+             * ⚠ ONLY FOR AGENTS THAT ARE INSTALLED. Creating `~/.gemini/GEMINI.md` for someone without
+             * Gemini invents an agent: the skills installer keys on that same directory existing, so
+             * the NEXT run would install skills for it too. Same rule as `installAgentSkills`.
+             */
+            if (!fs.existsSync(path.dirname(file))) {
+                steps.push(`${agent}/instructions=agent-absent`);
+                continue;
+            }
+            if (isSymlink(file)) {
+                steps.push(`${agent}/instructions=symlink-skipped`);
+                continue;
+            }
+            let existing = '';
+            try {
+                existing = fs.readFileSync(file, 'utf8');
+            }
+            catch { /* first run */ }
+            const next = upsertBlock(existing, agent === 'claude' ? claudeBlock() : instructionBlock());
+            if (next === existing) {
+                steps.push(`${agent}/instructions=current`);
+                continue;
+            }
+            fs.writeFileSync(file, next, { mode: 0o644 });
+            steps.push(`${agent}/instructions=${existing ? 'updated' : 'written'}`);
+        }
+        catch (e) {
+            warnings.push(`${agent}/instructions: ${e?.message ?? String(e)}`);
+        }
+    }
+    return { steps, warnings };
+}
+/** Remove only our block. A file that becomes empty is deleted only if we created all of it. */
+export function removeAgentInstructions(home = os.homedir()) {
+    const steps = [];
+    const warnings = [];
+    for (const { agent, file } of agentInstructionFiles(home)) {
+        try {
+            if (!fs.existsSync(file) || isSymlink(file))
+                continue;
+            const existing = fs.readFileSync(file, 'utf8');
+            const next = stripBlock(existing);
+            if (next === existing)
+                continue;
+            if (next)
+                fs.writeFileSync(file, next);
+            else
+                fs.unlinkSync(file);
+            steps.push(`${agent}/instructions=removed`);
+        }
+        catch (e) {
+            warnings.push(`${agent}/instructions: ${e?.message ?? String(e)}`);
+        }
+    }
+    return { steps, warnings };
+}
+function isSymlink(file) {
+    try {
+        return fs.lstatSync(file).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/agent.js

@@ -845,7 +845,11 @@ async function agentLogin(args, values) {
         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).`));
+            // ⚠ The workspace names the live identity in its refusal (PPO-190). The old advice —
+            // `beehaven call agent-list` — ran AS this refused identity and was refused in turn.
+            if (!/Log in as one:/.test(outcome.reason)) {
+                console.error(dim(`    or log in as an active agent: beehaven agent login <name> (the Settings → Agent access page lists them).`));
+            }
         }
         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;

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/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

@@ -1830,42 +1830,22 @@ const PAGES = {
         related: ['app', 'pipe', 'pwd'],
     },
     swarm: {
-        synopsis: 'beehaven swarm <list|queen|role|dispatch|bees|sample-honey|forge-omni> [args]',
-        description: `The distributed HIVE MESH + its two AI bees. A "beehive" is a
-    node running the daemon + hives (this Mac, a headless server via
-    \`start --headless\`, or a Cloudflare container). A QUEEN hive orchestrates;
-    WORKER hives execute the work the queen dispatches. This machine registers
-    itself when the daemon connects — the Mac defaults to QUEEN, a
-    headless/container node to WORKER.
-
-    Mesh subcommands:
-      list                     Every beehive: role, kind, hives, online state
-      queen                    Which NODE is orchestrating right now
-      role <queen|worker>      Make THIS machine the queen (or a worker)
-      whoami                   This machine's beehive identity
-      dispatch <cap> <action> [json]   Route work to the best worker (--target pins one)
-      forget <deviceId>        Drop a stale OFFLINE node
-
-    The bees (AI):
+        synopsis: 'beehaven swarm <bees|sample-honey|forge-omni> [args]',
+        description: `The two AI bees. The unfinished node registry and dispatch
+    protocol were retired; they do not route work.
+
       bees                     👑 Queen + 🐝 Omni status
       sample-honey             👑 Queen ingests the WHOLE workspace corpus
                                (memories, brain, prompts, brand voice) and gets fat
       forge-omni [--force]     👑 Queen distills a LEAN copy of you → 🐝 Omni,
                                your personal-assistant AI TWIN (--force re-samples)
 
-    The Queen bee runs on the queen hive — same crown, two layers (the NODE vs.
-    the AI). Omni is the owner's twin: log in as it with \`agent login omni-bee\`.
-    Distinct from \`hives\` (local apps) — a beehive is a whole NODE.`,
+    Omni is the owner's twin: log in as it with \`agent login omni-bee\`.`,
         flags: [
-            {
-                name: '--target <deviceId>',
-                desc: 'dispatch: pin to a specific beehive instead of auto-selecting',
-            },
             { name: '--force', desc: 'forge-omni: re-sample the honey before distilling' },
         ],
         examples: [
-            { cmd: 'beehaven swarm list', note: 'see the whole swarm' },
-            { cmd: 'beehaven swarm role queen', note: 'make this machine the queen' },
+            { cmd: 'beehaven swarm bees', note: 'see Queen and Omni' },
             { cmd: 'beehaven swarm sample-honey', note: 'Queen ingests everything' },
             { cmd: 'beehaven swarm forge-omni', note: 'forge your AI twin' },
             { cmd: 'beehaven agent login omni-bee', note: 'log in as your twin' },

package/dist/commands/inbox.js

@@ -82,7 +82,7 @@ async function call(action, input, values) {
 async function printList(box, values) {
     const res = await call('inbox-list', {
         box, ...(values.search ? { q: String(values.search) } : {}), ...(values.as ? { as: String(values.as) } : {}),
-        ...(values.limit ? { limit: Number(values.limit) } : {}),
+        ...(values.limit !== undefined ? { limit: Number(values.limit) } : {}),
     }, values);
     const threads = res.threads ?? [];
     const counts = res.counts ?? {};