@clearlysh/beehaven 0.8.31 → 0.8.32

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 = '3152df6cf1d7-dirty';
 /** 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-13T08:55Z';
 /**
  * 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.32",
   "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

package/skills/clearly-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearly-agent
-description: Work in a Clearly workspace AS an agent — sign in with an identity, resume a session, read your brief (what changed since you were last here, your recents, your unfiled drafts), and understand whose work you are creating. TRIGGER on the first `beehaven` call of any session, on "Not an agent" / "agent login" refusals, and when the user asks "who am I acting as", "what was I doing", "what have I made", "why can't the agent see this", "why is my work invisible", or "run this as a different agent". Read this BEFORE clearly-canvas or clearly-workspace — both need an identity and neither will work without one.
+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. Work in a Clearly workspace AS an agent — sign in with an identity, resume a session, read your brief (what changed since you were last here, your recents, your unfiled drafts), and understand whose work you are creating. TRIGGER on the first `beehaven` call of any session, on "Not an agent" / "agent login" refusals, and when the user asks "who am I acting as", "what was I doing", "what have I made", "why can't the agent see this", "why is my work invisible", or "run this as a different agent". Read this BEFORE clearly-canvas or clearly-workspace — both need an identity and neither will work without one.
 ---
 
 # clearly-agent — who you are, and what that makes your work

package/skills/clearly-canvas/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clearly-canvas
 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 revise editable compositions on a Clearly canvas using the beehaven
   CLI: posters, campaigns, decks, page mockups, diagrams, spatial reviews, and
   project plans built from LIVE workspace objects (boards, tickets, documents,

package/skills/clearly-workflows/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clearly-workflows
 description: >-
+  Best with the beehaven CLI (semantic search and write-back); with only the Clearly connector, search with clearly_grep and record decisions with clearly_create.
   Use the Clearly workspace as a COMPANY BRAIN — search the org's accumulated
   context (decisions, facts, prompts, docs), write conclusions back so the next
   agent inherits them instead of re-deriving them, and inherit the team's

package/skills/clearly-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearly-workspace
-description: Understand and audit a Clearly workspace from the terminal — what it holds (documents, projects, boards, tickets, thoughts, files, agents), who authored what, and which known data defects are present. Run `survey.mjs` for the whole picture in one command. TRIGGER when the user asks "what is in this workspace", "how big is this workspace", "audit / survey / check the workspace", "what have my agents made", "is anything broken in here", "who created these", or before any cleanup, migration or backfill — the survey is what tells you whether a repair is needed and whether it worked. NOT for editing documents (use `document-*`) or drawing on a canvas (use clearly-canvas).
+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. Understand and audit a Clearly workspace from the terminal — what it holds (documents, projects, boards, tickets, thoughts, files, agents), who authored what, and which known data defects are present. Run `survey.mjs` for the whole picture in one command. TRIGGER when the user asks "what is in this workspace", "how big is this workspace", "audit / survey / check the workspace", "what have my agents made", "is anything broken in here", "who created these", or before any cleanup, migration or backfill — the survey is what tells you whether a repair is needed and whether it worked. NOT for editing documents (use `document-*`) or drawing on a canvas (use clearly-canvas).
 ---
 
 # clearly-workspace — know what you are standing in

package/skills/codebase-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-map
-description: Walk a code repository and draw a living ARCHITECTURE MAP of it on a Clearly spatial canvas — modules as frames (sized by LOC, colored by layer), key files as nodes, imports/dependencies as arrows — so the big pieces, how they depend on each other, and where the complexity sits all read at a glance. Load this when the user says "map / diagram / visualize this codebase / repo / architecture", "how is this project structured", "draw the dependency graph", "give me an architecture overview", or when you're onboarding to an unfamiliar repo and need to see its shape fast.
+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. Walk a code repository and draw a living ARCHITECTURE MAP of it on a Clearly spatial canvas — modules as frames (sized by LOC, colored by layer), key files as nodes, imports/dependencies as arrows — so the big pieces, how they depend on each other, and where the complexity sits all read at a glance. Load this when the user says "map / diagram / visualize this codebase / repo / architecture", "how is this project structured", "draw the dependency graph", "give me an architecture overview", or when you're onboarding to an unfamiliar repo and need to see its shape fast.
 ---
 
 > **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written

package/skills/index.json

@@ -17,21 +17,21 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "b942eebe6f0397fb"
+    "sha": "41327744a8cc0fe1"
   },
   {
     "name": "agent-home",
     "files": [
       "SKILL.md"
     ],
-    "sha": "0bbcdbd33cfb11a3"
+    "sha": "e1d18e7518ff4b65"
   },
   {
     "name": "agent-doodle-space",
     "files": [
       "SKILL.md"
     ],
-    "sha": "053fc1cd5a1494d4"
+    "sha": "1e1911e6d8784476"
   },
   {
     "name": "design-craft",
@@ -53,21 +53,21 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "755db2d1ab8c759f"
+    "sha": "366139b11ff11b58"
   },
   {
     "name": "pair-on-canvas",
     "files": [
       "SKILL.md"
     ],
-    "sha": "65f87e74bf3566a6"
+    "sha": "1d79147baa8c232d"
   },
   {
     "name": "codebase-map",
     "files": [
       "SKILL.md"
     ],
-    "sha": "2e80ffd32f77327f"
+    "sha": "4a4af2229b68827d"
   },
   {
     "name": "clearly-workspace",
@@ -75,28 +75,28 @@
       "SKILL.md",
       "survey.mjs"
     ],
-    "sha": "f5585be212a67c32"
+    "sha": "3a3e6fa6e3cf8717"
   },
   {
     "name": "clearly-agent",
     "files": [
       "SKILL.md"
     ],
-    "sha": "b3f47988cb9235b9"
+    "sha": "1c6425a2143e7901"
   },
   {
     "name": "visualize",
     "files": [
       "SKILL.md"
     ],
-    "sha": "ce9410c1ba7b3457"
+    "sha": "88bb6e94fb37c337"
   },
   {
     "name": "sticker-pack",
     "files": [
       "SKILL.md"
     ],
-    "sha": "f029503ebae59c64"
+    "sha": "74af254817a134d6"
   },
   {
     "name": "clearly-docs",
@@ -117,6 +117,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "f26dbbc90929ebe7"
+    "sha": "b9622f21173bab0d"
   }
 ]

package/skills/pair-on-canvas/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pair-on-canvas
-description: Use a Clearly canvas as mission control for a coding task — read the spec the human placed on the board, do the work in the repo, and report progress, diffs, and next steps back as cards they steer by inking. Load this when the user says "work the task on my canvas", "take this from the board", "what's on my Clearly canvas", "pick up the spec", "let's pair on the canvas", or whenever a human is directing your coding work spatially instead of in a chat thread.
+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 a Clearly canvas as mission control for a coding task — read the spec the human placed on the board, do the work in the repo, and report progress, diffs, and next steps back as cards they steer by inking. Load this when the user says "work the task on my canvas", "take this from the board", "what's on my Clearly canvas", "pick up the spec", "let's pair on the canvas", or whenever a human is directing your coding work spatially instead of in a chat thread.
 ---
 
 > **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written

package/skills/sticker-pack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sticker-pack
-description: Turn an idea into a printable, die-cut STICKER SHEET on a Clearly canvas — Clearly's own sticker-vending-machine pipeline surfaced as an agent skill. Generates a cohesive SET of transparent stickers, lays them out as a sheet (frame + gridded stickers + a vector kiss-cut cutline layer), and hands back a print-ready bundle. Load this when the user says "make me stickers / a sticker pack / a sticker sheet about X", "turn this into stickers", "design stickers for my brand / startup / cat", or "I want die-cut stickers". The fun, inherently-shareable corner of the canvas skill set.
+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. Turn an idea into a printable, die-cut STICKER SHEET on a Clearly canvas — Clearly's own sticker-vending-machine pipeline surfaced as an agent skill. Generates a cohesive SET of transparent stickers, lays them out as a sheet (frame + gridded stickers + a vector kiss-cut cutline layer), and hands back a print-ready bundle. Load this when the user says "make me stickers / a sticker pack / a sticker sheet about X", "turn this into stickers", "design stickers for my brand / startup / cat", or "I want die-cut stickers". The fun, inherently-shareable corner of the canvas skill set.
 ---
 
 > **⚠ CANVAS AND STICKER WORK GO THROUGH THE CLI, NOT AN MCP TOOL.** Anything written

package/skills/visualize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: visualize
-description: Turn any concept, answer, or described system into a clean DIAGRAM on a Clearly spatial canvas instead of a wall of text. Load this when the user asks to "diagram this", "draw it", "sketch it", "map it out", "visualize this",
+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. Turn any concept, answer, or described system into a clean DIAGRAM on a Clearly spatial canvas instead of a wall of text. Load this when the user asks to "diagram this", "draw it", "sketch it", "map it out", "visualize this",
   "explain visually", "show me how X works", "flowchart this", "make a diagram" — AND proactively whenever YOUR OWN answer would be clearer as a picture than a paragraph (a flow with branches, who-calls-whom, a schema, an architecture, options on axes). Picks the right diagram type for the content and builds it with the canvas primitives.
 ---