@clearlysh/beehaven 0.8.31 → 0.8.33

package/dist/agents-md-text.js

@@ -0,0 +1,64 @@
+/**
+ * agents-md-text — the Clearly block for a PROJECT's AGENTS.md, as `beehaven agents-md` writes it
+ * (CAN2-66).
+ *
+ * ⚠⚠ A COPY, PINNED. The source of truth is the monorepo's `lib/connections/agentsMd.ts`, which the
+ * Integrations page, each agent's details and the MCP `clearly-agents-md` prompt render. This
+ * package cannot import it (it ships on its own), so the text is repeated here and the monorepo's
+ * `lib/__tests__/agentsMdCliParity.test.mjs` compares the two OUTPUTS, name argument included.
+ * Change both or the test fails — a stale copy does not render wrong, it instructs wrong.
+ *
+ * ⚠ NO IMPORTS, so that test can load this file directly.
+ */
+export const CLI_BLOCK_START = '<!-- clearly:cli:start -->';
+export const CLI_BLOCK_END = '<!-- clearly:cli:end -->';
+export const MCP_BLOCK_START = '<!-- clearly:mcp:start -->';
+export const MCP_BLOCK_END = '<!-- clearly:mcp:end -->';
+/** What goes in CLAUDE.md so Claude Code reads the AGENTS.md block too. */
+export const CLAUDE_MD_IMPORT = '@AGENTS.md';
+/** The block for agents that use the `beehaven` CLI. */
+export function agentsMdCliBlock(agentName) {
+    const name = (agentName ?? '').trim();
+    const login = name
+        ? `\`beehaven agent login ${name} --label "<what you are doing>"\` — you are ${name} in this workspace.`
+        : '`beehaven agent login <name> --label "<what you are doing>"`, using your own name (claude, codex, gemini).';
+    return [
+        CLI_BLOCK_START,
+        '<!-- managed-by: clearly. Run `beehaven agents-md` to update; edit outside this block. -->',
+        '',
+        '## Clearly workspace',
+        '',
+        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `beehaven` CLI',
+        'for anything the team should see, not files in this repo.',
+        '',
+        `- Sign in once per session: ${login}`,
+        '  If it says the daemon is not running: `beehaven start --headless`.',
+        '- Read the `clearly-agent` skill before anything else, and `clearly-canvas` before design work',
+        '  (`beehaven skills install` puts them in place).',
+        '- `beehaven actions` lists what you can call; `beehaven call <action> \'<json>\'` calls it.',
+        '- Search before you create, file work in the project it belongs to, and end the session with',
+        '  `beehaven agent handoff "what you did · what is next"` so the next one starts there.',
+        CLI_BLOCK_END,
+    ].join('\n');
+}
+/** The block for agents connected over MCP (the `clearly` server). */
+export function agentsMdMcpBlock() {
+    return [
+        MCP_BLOCK_START,
+        '<!-- managed-by: clearly-mcp. Re-run the `clearly-agents-md` prompt to update; edit outside this block. -->',
+        '',
+        '## Clearly workspace (connected over MCP as `clearly`)',
+        '',
+        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `clearly_*`',
+        'tools, not files in this repo, for anything the team should see.',
+        '',
+        '- Start with `clearly_catalog` to see what exists; search with `clearly_grep` / `clearly_glob`.',
+        '- Read with `clearly_read`, make new work with `clearly_create`, change it with `clearly_edit`,',
+        '  and discuss it with `clearly_comment`. They take a `target`: a path (`~/Q1/Plan.md`), a key',
+        '  (`CLR-42`), an id or an exact title. The extension names the type (`.md` document, `.csv`',
+        '  sheet, `.board.json` board); a trailing slash means a project.',
+        '- Search before you write, and write decisions back so the next session inherits them.',
+        '- If a job is not covered by a listed tool, say so rather than guessing an action name.',
+        MCP_BLOCK_END,
+    ].join('\n');
+}

package/dist/browser-login.js

@@ -265,7 +265,12 @@ export function persistBrowserLogin(captured) {
             userId: captured.userId,
             email: captured.email ?? null,
             displayName: captured.displayName ?? null,
-            tokenStorage: 'keychain',
+            /**
+             * ⚠ SAY WHERE THE TOKEN REALLY IS (CAN2-65). This was always 'keychain', so on Windows —
+             * which has no keychain here — `whoami` reported a keychain that did not exist, and
+             * `Relay.loadConfig` / the refresh path shelled out to macOS `security` on every load.
+             */
+            tokenStorage: keychain.available ? 'keychain' : 'file',
             refreshToken: captured.refreshToken,
             token: captured.idToken,
             endpoint: dialUrl,

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 = '3767a788c0ee';
+export const BUILD_SHA = '8f7eef9e12ce';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-13T06:40Z';
+export const BUILD_TIME = '2026-10-15T07:24Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -143,6 +143,7 @@ function printHelp() {
 
     beehaven guide                             Agent-first setup and signup handoff
     beehaven signup                            Create a free Clearly account
+    beehaven agents-md                         Add Clearly to this project's AGENTS.md
 
   Personal workspace:
     beehaven cd home
@@ -956,6 +957,11 @@ const AGENT_LOGIN_EXEMPT = new Set([
      * would refuse the one person it is for — the agent whose user has not signed up yet (SGS-73).
      */
     'handoff',
+    /**
+     * ⚠ `agents-md` WRITES A FILE IN THIS REPO AND NOTHING ELSE — it never opens a workspace, and it is
+     * part of setting a project up, which must not require the login it helps a teammate do (CAN2-66).
+     */
+    'agents-md',
 ]);
 /**
  * ⚠ ALIAS → CANONICAL VERB, for the activity log's `source` column only.
@@ -1371,6 +1377,9 @@ async function run() {
             state: { type: 'string' },
             goal: { type: 'string' },
             remove: { type: 'boolean', default: false },
+            // `agents-md`: the MCP block instead of the CLI one; print it instead of writing it (CAN2-66).
+            mcp: { type: 'boolean', default: false },
+            print: { type: 'boolean', default: false },
             /**
              * ⚠⚠ `beehaven sheet` / `beehaven slides` — AND AN UNDECLARED FLAG IS A FATAL, NOT A NO-OP.
              *
@@ -3145,6 +3154,15 @@ async function run() {
             console.log('  (or quit and relaunch the Hive Mac app if it owns the daemon).');
             break;
         }
+        case 'agents-md': {
+            const { cmdAgentsMd } = await import('./commands/agents-md.js');
+            process.exitCode = cmdAgentsMd(positionals[1], {
+                mcp: !!values.mcp,
+                print: !!values.print,
+                remove: !!values.remove,
+            });
+            break;
+        }
         case 'handoff': {
             const { cmdHandoff } = await import('./commands/handoff.js');
             process.exitCode = await cmdHandoff(positionals[1], {

package/dist/commands/agents-md.js

@@ -0,0 +1,118 @@
+/**
+ * beehaven agents-md — put the Clearly block in THIS project's AGENTS.md (CAN2-66).
+ *
+ * ⚠⚠ TWO FILES, TWO AUDIENCES. `beehaven login` already writes a GLOBAL block into
+ * ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.gemini/GEMINI.md (agent-instructions.ts), so every
+ * agent on THIS machine knows Clearly. A project's AGENTS.md is for everyone else who opens the
+ * repo — a teammate's Codex, a cloud agent, CI — and it is committed and shared. That is why this
+ * is its own command the person (or their agent, asked first) runs, not a side effect of install.
+ *
+ * ⚠ THE MARKERS ARE THE UPDATE MECHANISM, as on every other surface (lib/connections/agentsMd.ts):
+ * re-running replaces only what lies between our markers and leaves the rest byte for byte. The
+ * CLI and MCP blocks have their own markers, so a repo used both ways keeps both.
+ *
+ * ⚠ AGENTS.md IS THE FILE; CLAUDE.md POINTS AT IT with one `@AGENTS.md` line — one copy to keep
+ * current. An existing CLAUDE.md gains the line only if it lacks it; nothing else in it is touched.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { execFileSync } from 'child_process';
+import { color } from '../spinner.js';
+import { CLI_BLOCK_START, CLI_BLOCK_END, MCP_BLOCK_START, MCP_BLOCK_END, CLAUDE_MD_IMPORT, agentsMdCliBlock, agentsMdMcpBlock, } from '../agents-md-text.js';
+/** Our block replaced between its markers, or appended after one blank line. Keeps CRLF files CRLF. */
+export function spliceBlock(text, block, start, end) {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const b = block.split('\n').join(eol);
+    const i = text.indexOf(start);
+    const j = i >= 0 ? text.indexOf(end, i) : -1;
+    if (i >= 0 && j >= 0)
+        return text.slice(0, i) + b + text.slice(j + end.length);
+    if (!text.trim())
+        return b + eol;
+    return text.replace(/\s*$/, '') + eol + eol + b + eol;
+}
+/** Our block taken out, with the blank line that separated it. Everything else stays. */
+export function removeBlock(text, start, end) {
+    const i = text.indexOf(start);
+    const j = i >= 0 ? text.indexOf(end, i) : -1;
+    if (i < 0 || j < 0)
+        return text;
+    const before = text.slice(0, i).replace(/(\r?\n)*$/, '');
+    const after = text.slice(j + end.length).replace(/^(\r?\n)*/, '');
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    if (!before)
+        return after;
+    return after ? before + eol + eol + after : before + eol;
+}
+/** The repository root when `dir` is inside a git work tree, else `dir` itself. */
+export function projectRoot(dir) {
+    try {
+        const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, timeout: 5_000,
+        }).trim();
+        return top || dir;
+    }
+    catch {
+        return dir;
+    }
+}
+/** Write (or remove) the block in `<root>/AGENTS.md` and make CLAUDE.md import it. */
+export function writeProjectAgentsMd(opts) {
+    const root = projectRoot(resolve(opts.dir));
+    const [start, end] = opts.mcp ? [MCP_BLOCK_START, MCP_BLOCK_END] : [CLI_BLOCK_START, CLI_BLOCK_END];
+    const agentsPath = join(root, 'AGENTS.md');
+    const claudePath = join(root, 'CLAUDE.md');
+    const files = [];
+    const had = existsSync(agentsPath);
+    const before = had ? readFileSync(agentsPath, 'utf8') : '';
+    if (opts.remove) {
+        const next = removeBlock(before, start, end);
+        if (next !== before)
+            writeFileSync(agentsPath, next);
+        files.push({ path: agentsPath, change: next !== before ? 'removed' : 'absent' });
+        return { root, files };
+    }
+    const next = spliceBlock(before, opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock(), start, end);
+    if (next !== before)
+        writeFileSync(agentsPath, next);
+    files.push({ path: agentsPath, change: !had ? 'created' : next !== before ? 'updated' : 'current' });
+    const claude = existsSync(claudePath) ? readFileSync(claudePath, 'utf8') : null;
+    if (claude === null) {
+        writeFileSync(claudePath, CLAUDE_MD_IMPORT + '\n');
+        files.push({ path: claudePath, change: 'created' });
+    }
+    else if (!claude.split(/\r?\n/).some((l) => l.trim() === CLAUDE_MD_IMPORT)) {
+        const eol = claude.includes('\r\n') ? '\r\n' : '\n';
+        writeFileSync(claudePath, claude.replace(/\s*$/, '') + (claude.trim() ? eol + eol : '') + CLAUDE_MD_IMPORT + eol);
+        files.push({ path: claudePath, change: 'updated' });
+    }
+    else {
+        files.push({ path: claudePath, change: 'current' });
+    }
+    return { root, files };
+}
+export function cmdAgentsMd(dir, opts) {
+    if (opts.print) {
+        process.stdout.write((opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock()) + '\n');
+        return 0;
+    }
+    let r;
+    try {
+        r = writeProjectAgentsMd({ dir: dir ?? process.cwd(), mcp: opts.mcp, remove: opts.remove });
+    }
+    catch (err) {
+        console.error(`  ${color.red('✗')} ${err?.message ?? err}`);
+        return 1;
+    }
+    console.log('');
+    for (const f of r.files) {
+        const mark = f.change === 'current' || f.change === 'absent' ? color.dim('·') : color.green('✓');
+        console.log(`  ${mark} ${f.path}  ${color.dim(f.change)}`);
+    }
+    const changed = r.files.some((f) => f.change !== 'current' && f.change !== 'absent');
+    if (changed && !opts.remove) {
+        console.log(color.dim(`\n  Commit ${r.files.map((f) => f.path.slice(r.root.length + 1)).join(' and ')} so every agent that opens this project knows the workspace.`));
+    }
+    console.log('');
+    return 0;
+}

package/dist/commands/help.js

@@ -413,6 +413,27 @@ const PAGES = {
     \`beehaven login\` to connect the CLI to it.`,
         related: ['login', 'guide'],
     },
+    'agents-md': {
+        synopsis: 'beehaven agents-md [dir] [--mcp] [--print] [--remove]',
+        description: `Add the Clearly block to this project's AGENTS.md, so every agent that opens the
+    repository — a teammate's Codex or Claude Code, a cloud agent, CI — knows the workspace and how
+    to reach it. Writes at the git root (or the directory given), and makes CLAUDE.md import it with
+    one \`@AGENTS.md\` line. Needs no login.
+
+    The block sits between Clearly's markers: run it again to update the block, and everything
+    else in the file stays as it was. \`beehaven login\` already teaches the agents on THIS machine
+    (their global instruction files); this is the shared, committed copy for everyone else.`,
+        flags: [
+            { name: '--mcp', desc: 'Write the block for agents connected over MCP instead of the CLI' },
+            { name: '--print', desc: 'Print the block and write nothing' },
+            { name: '--remove', desc: 'Take the block out again' },
+        ],
+        examples: [
+            { cmd: 'beehaven agents-md', note: 'AGENTS.md + CLAUDE.md at the repository root' },
+            { cmd: 'beehaven agents-md --mcp', note: 'for a team that connects over MCP' },
+        ],
+        related: ['skills', 'login'],
+    },
     handoff: {
         synopsis: 'beehaven handoff [file.md|-] [--tasks tasks.md|json] [--csv data.csv]… [--title "…"] [--wait] [--json]',
         description: `Give a person your work when they have no Clearly account yet. Needs no login.

package/dist/daemon.js

@@ -4116,7 +4116,7 @@ export async function startDaemon(opts) {
                 // so browser frontends become virtual IPC clients — same
                 // pipeline, app-rpc, broadcast fan-out as Claude's path.
                 dashboard.setAppBridge({
-                    createVirtualClient: (send, subs) => ipc.createVirtualClient(send, subs),
+                    createVirtualClient: (send, subs, scope) => ipc.createVirtualClient(send, subs, scope),
                     injectMessage: (id, msg) => ipc.injectMessage(id, msg),
                     releaseVirtualClient: (id) => ipc.releaseVirtualClient(id),
                 });
@@ -4141,15 +4141,29 @@ export async function startDaemon(opts) {
         }
     })();
     // ── Dashboard (local observability UI) ──────────────────────────────
-    dashboard = new Dashboard({
-        port: config.dashboardPort ?? 9800,
-        host: '127.0.0.1',
-        explorerTarget: `http://127.0.0.1:${config.devPort ?? 8787}`,
-        explorerSecret: config.explorerSecret ?? config.adminSecret ?? '',
-        projectDir: config.linkedProject ?? '',
-    });
+    /**
+     * ⚠⚠ A LOOPBACK HTTP SERVER IS OPEN TO EVERY USER AND PROGRAM ON THE MACHINE (CAN2-64), so a
+     * daemon opens one only when something will use it. The Mac app's daemon does (the avatar UI
+     * talks over /apps/ws); a HEADLESS daemon — the CLI on Windows and Linux, CI, servers — has no
+     * window to show it in and, on a shared Windows machine, would hand every other signed-in user
+     * a port into this one's daemon. It starts there only on request: BEEHAVEN_DASHBOARD=1,
+     * `"dashboard": true` in ~/.beehaven/config.json, or developer mode.
+     */
+    const headlessDaemon = process.env.BEEHAVEN_HEADLESS === '1' || process.env.BEEHAVEN_HEADLESS === 'true';
+    const dashboardWanted = !headlessDaemon || developerMode || config.dashboard === true || process.env.BEEHAVEN_DASHBOARD === '1';
+    if (!dashboardWanted) {
+        console.log('  [dashboard] off in a headless daemon (set BEEHAVEN_DASHBOARD=1 to open it on 127.0.0.1)');
+    }
+    if (dashboardWanted)
+        dashboard = new Dashboard({
+            port: config.dashboardPort ?? 9800,
+            host: '127.0.0.1',
+            explorerTarget: `http://127.0.0.1:${config.devPort ?? 8787}`,
+            explorerSecret: config.explorerSecret ?? config.adminSecret ?? '',
+            projectDir: config.linkedProject ?? '',
+        });
     dashboard
-        .start()
+        ?.start()
         .then(() => {
         console.log(`  [dashboard] Beehaven Dashboard at ${dashboard.url}`);
     })
@@ -4158,7 +4172,7 @@ export async function startDaemon(opts) {
     });
     // Forward daemon events to dashboard
     watcher.on('event', (event) => {
-        dashboard.pushEvent({
+        dashboard?.pushEvent({
             type: event.hook_event_name || event.type || 'unknown',
             timestamp: event.timestamp || Date.now(),
             data: {

package/dist/dashboard.js

@@ -17,6 +17,59 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
+// ── Who may talk to this server (CAN2-64) ───────────────────────────────────
+/**
+ * ⚠⚠ A LOOPBACK PORT IS NOT A PRIVATE CHANNEL. Every web page the person opens can dial
+ * `ws://127.0.0.1:9800` — WebSockets ignore CORS — and so can every program on the machine,
+ * another Windows or macOS user's included. `/apps/ws` used to hand EVERY connection a
+ * developer-scope IPC client with no check at all (a comment in ipc-server.ts claimed a session
+ * cookie and an origin check that did not exist), so any website could ask the daemon for the
+ * signed-in Firebase token, run `sql`/`shell`, or install a package. Proven against a live
+ * daemon on 2026-10-13 with `Origin: https://evil.example`. The rules now:
+ *
+ *   1. The Host header must name this loopback server — a DNS-rebound hostname is refused.
+ *   2. `/apps/ws`: a PAGE must come from this server (an installed hive's frontend) or be a
+ *      `file://` page (the Mac app loads the avatar UI with `loadFile`; a web page cannot claim
+ *      `file://`), and it gets CONSUMER scope. A PROGRAM (no Origin) starts unauthenticated and
+ *      must present the daemon's IPC token with `{type:'auth'}` — the pipe's own boundary. Any
+ *      other origin, `null` included (sandboxed iframes send it), is refused at the upgrade.
+ *   3. JSON routes answer CORS only to loopback origins (a dev server on localhost). Browser
+ *      building modules stay `*`: clearly.sh imports that public code cross-origin.
+ */
+export function isLoopbackHostHeader(host, port) {
+    const h = (host ?? '').toLowerCase();
+    return h === `127.0.0.1:${port}` || h === `localhost:${port}` || h === `[::1]:${port}`;
+}
+/** `http://localhost:N`, `http://127.0.0.1:N` or `http://[::1]:N` — a page served on this machine. */
+export function isLoopbackOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const u = new URL(origin);
+        return u.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** A page served by THIS server. */
+export function isSelfOrigin(origin, port) {
+    return (origin === `http://127.0.0.1:${port}` ||
+        origin === `http://localhost:${port}` ||
+        origin === `http://[::1]:${port}`);
+}
+/** How a `/apps/ws` connection starts: `consumer` scope, unauthenticated (`token`), or refused (null). */
+export function appBridgeTrust(origin, port) {
+    if (!origin)
+        return 'token';
+    if (origin === 'file://' || isSelfOrigin(origin, port))
+        return 'consumer';
+    return null;
+}
+/** `/ws` streams events and accepts console logs: loopback or file pages, or programs. */
+export function metricsSocketAllowed(origin) {
+    return !origin || origin === 'file://' || isLoopbackOrigin(origin);
+}
 // ── Fallback HTML ───────────────────────────────────────────────────────────
 const FALLBACK_HTML = `<!DOCTYPE html>
 <html lang="en">
@@ -150,11 +203,28 @@ export class Dashboard {
         // first WSS's listener — both listeners fire on every upgrade event.
         // Instead we accept all upgrades and route by req.url in the
         // connection handler.
-        this._wss = new WebSocketServer({ server: this._server });
+        //
+        // Every upgrade is judged BEFORE it is accepted (see "Who may talk to this server").
+        this._wss = new WebSocketServer({
+            server: this._server,
+            verifyClient: (info, done) => {
+                const req = info.req;
+                const url = req.url ?? '';
+                const origin = req.headers.origin;
+                if (!isLoopbackHostHeader(req.headers.host, this.port))
+                    return done(false, 403, 'Forbidden');
+                if (url.startsWith('/apps/ws')) {
+                    return appBridgeTrust(origin, this.port) ? done(true) : done(false, 403, 'Forbidden');
+                }
+                if (url.startsWith('/ws'))
+                    return metricsSocketAllowed(origin) ? done(true) : done(false, 403, 'Forbidden');
+                return done(false, 404, 'Not Found');
+            },
+        });
         this._wss.on('connection', (ws, req) => {
             const url = req.url ?? '';
             if (url.startsWith('/apps/ws')) {
-                this._handleAppWsConnection(ws);
+                this._handleAppWsConnection(ws, appBridgeTrust(req.headers.origin, this.port));
             }
             else if (url.startsWith('/ws')) {
                 this._handleWSConnection(ws, req);
@@ -255,8 +325,10 @@ export class Dashboard {
     get url() {
         return `http://${this._config.host}:${this._config.port}`;
     }
+    /** The port actually bound (config 0 picks one), which the Host and Origin checks compare to. */
     get port() {
-        return this._config.port;
+        const addr = this._server?.address();
+        return addr && typeof addr === 'object' ? addr.port : this._config.port;
     }
     get running() {
         return this._server !== null;
@@ -268,6 +340,30 @@ export class Dashboard {
     _handleHTTP(req, res) {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
+        const origin = req.headers.origin;
+        // A DNS-rebound name pointing at 127.0.0.1 carries its own Host — refuse it on every route.
+        if (!isLoopbackHostHeader(req.headers.host, this.port)) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end('Forbidden');
+            return;
+        }
+        /**
+         * ⚠ ONE CHOKEPOINT FOR CORS. The handlers below were written to answer `*`; every response now
+         * passes through here, which keeps `*` only for browser building modules (public code that
+         * clearly.sh imports cross-origin) and otherwise reflects a loopback origin or sends none.
+         */
+        const publicModule = /^\/apps\/[^/]+\/buildings\/[^/]+\.js$/.test(url);
+        const allowOrigin = publicModule ? '*' : isLoopbackOrigin(origin) ? origin : null;
+        const writeHead = res.writeHead.bind(res);
+        res.writeHead = (status, ...rest) => {
+            const headers = rest.find((r) => r && typeof r === 'object');
+            if (headers && 'Access-Control-Allow-Origin' in headers) {
+                delete headers['Access-Control-Allow-Origin'];
+                if (allowOrigin)
+                    Object.assign(headers, { 'Access-Control-Allow-Origin': allowOrigin, Vary: 'Origin' });
+            }
+            return writeHead(status, ...rest);
+        };
         // Handle CORS preflight
         if (method === 'OPTIONS') {
             res.writeHead(204, {
@@ -280,8 +376,14 @@ export class Dashboard {
             return;
         }
         try {
-            // Explorer API proxy — forward /api/explorer/* to the Worker
+            // Explorer API proxy — forward /api/explorer/* to the Worker. It adds the admin secret, so
+            // only this server's own explorer page (or a program, which sends no Origin) may use it.
             if (url.startsWith('/api/explorer')) {
+                if (origin && !isSelfOrigin(origin, this.port)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 this._proxyExplorer(req, res, url);
                 return;
             }
@@ -350,6 +452,11 @@ export class Dashboard {
                 }
             }
             if (method === 'POST' && url === '/api/console') {
+                if (!metricsSocketAllowed(origin)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 this._handleConsolePost(req, res);
                 return;
             }
@@ -702,7 +809,11 @@ export class Dashboard {
             : { installed: [], available: [] };
         this._serveJSON(res, payload);
     }
-    _handleAppWsConnection(ws) {
+    _handleAppWsConnection(ws, trust) {
+        if (!trust) {
+            ws.close(1008, 'forbidden');
+            return;
+        }
         if (!this._appBridge) {
             ws.close(1011, 'app bridge not configured');
             return;
@@ -720,7 +831,8 @@ export class Dashboard {
         // Subscribe broadly by default — browser UIs usually want to see
         // everything (pipeline:*, broadcast:*, etc.). Clients can tighten this
         // by sending their own { type: 'subscribe', patterns: [...] } message.
-        const virtId = bridge.createVirtualClient(send, ['*']);
+        // Consumer scope at most: a page never gets developer verbs (get-token, shell, sql, installs).
+        const virtId = bridge.createVirtualClient(send, ['*'], trust === 'consumer' ? 'consumer' : null);
         ws.on('message', (raw) => {
             let msg;
             try {

package/dist/ipc-server.js

@@ -602,20 +602,23 @@ export class IpcServer extends EventEmitter {
     // IPC bus so the same pipeline/app-rpc handlers serve both Claude and
     // the human UI.
     /** Register a virtual client and return its id. */
-    createVirtualClient(virtualSend, initialSubscriptions = ['*']) {
+    createVirtualClient(virtualSend, initialSubscriptions = ['*'], scope = null) {
         const id = `virt_${++this.virtualClientCounter}`;
+        /**
+         * ⚠⚠ A VIRTUAL CLIENT IS ONLY AS TRUSTED AS WHOEVER IS ON THE OTHER END OF IT (CAN2-64).
+         * This used to be `authenticated: true, scope: 'developer'` for everyone, justified by "the
+         * dashboard bridge enforces its own auth (session cookie, origin check)". It enforced none,
+         * so any web page that opened ws://127.0.0.1:9800/apps/ws could call get-token. The bridge
+         * now judges the connection (dashboard.ts `appBridgeTrust`) and passes 'consumer' or null;
+         * a null client must authenticate with the IPC token, exactly like a socket client.
+         */
         const client = {
             id,
             virtualSend,
             subscriptions: initialSubscriptions,
             buffer: '',
-            // Virtual clients are in-process — they're already inside the trust
-            // boundary. The dashboard /apps/ws bridge enforces its own auth
-            // (session cookie, origin check) before creating the virtual client,
-            // so we hand them developer scope to mirror what a logged-in tray
-            // user can already do.
-            authenticated: true,
-            scope: 'developer',
+            authenticated: scope !== null,
+            scope,
         };
         this.clients.set(id, client);
         // Mimic the on-connect status frame real clients receive so the bridge

package/dist/verb-surface.js

@@ -60,6 +60,7 @@ export const VERB_SURFACE = {
     logout: { cls: 'STRUCTURAL', why: 'clears local credentials' },
     signup: { cls: 'STRUCTURAL', why: 'opens a browser' },
     handoff: { cls: 'STRUCTURAL', why: 'posts a local file to the anonymous door; no account, no workspace' },
+    'agents-md': { cls: 'STRUCTURAL', why: "writes the Clearly block into this repo's AGENTS.md; no workspace" },
     whoami: { cls: 'STRUCTURAL', why: 'reads local credentials' },
     start: { cls: 'STRUCTURAL', why: 'spawns the daemon `call` needs' },
     stop: { cls: 'STRUCTURAL', why: 'daemon lifecycle' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearlysh/beehaven",
-  "version": "0.8.31",
+  "version": "0.8.33",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/skills/agent-doodle-space/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-doodle-space
-description: Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
 ---
 
 # Agent Soul + Doodle Space

package/skills/agent-home/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-home
-description: Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
 ---
 
 # Agent Home memory apartment

package/skills/brand-identity/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: brand-identity
 description: >-
+  Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead.
   Design the requested logo or brand identity on a Clearly canvas —
   brief, mark, wordmark, lockups and clear space, palette, type system,
   applications, and a spec board someone else can build from. Use when asked