@clearlysh/beehaven 0.8.30 → 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 = '2c7d78e7c945';
+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:00Z';
+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/commands/self-update.js

@@ -43,9 +43,10 @@ import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { join, sep } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { usableUpdateDigest } from '../version-utils.js';
+import { compareVersions, usableUpdateDigest } from '../version-utils.js';
+import { npmUpdatePlan, latestNpmVersion, installedNpmVersion, installNpmVersionSync } from '../npm-update.js';
 /**
  * Which install this process is.
  *
@@ -83,8 +84,9 @@ export function updateHint(kind = installKind()) {
         return 'Run \x1b[1mbeehaven update\x1b[0m';
     if (kind === 'npx')
         return 'Run `npx @clearlysh/beehaven@latest` for the current npm release.';
+    // npm installs update themselves since CAN2-57 (the daemon hourly, `beehaven update` on demand).
     if (kind === 'npm')
-        return 'Run `npm install -g @clearlysh/beehaven@latest` to update this npm install.';
+        return 'Run \x1b[1mbeehaven update\x1b[0m (or `npm install -g @clearlysh/beehaven@latest`).';
     return 'This is a linked dev build — `npm run build` in beehaven_sdk/packages/cli.';
 }
 /**
@@ -113,9 +115,11 @@ export function runSelfUpdate(kind = installKind()) {
     if (kind === 'linked') {
         return { ok: false, message: 'This is a linked development build — refusing to overwrite it.\n  cd beehaven_sdk/packages/cli && npm run build' };
     }
-    if (kind === 'npm' || kind === 'npx') {
+    if (kind === 'npx') {
         return { ok: false, message: updateHint(kind) };
     }
+    if (kind === 'npm')
+        return runNpmSelfUpdate();
     const feed = (process.env.BEEHAVEN_CLI_FEED || 'https://downloads.clearly.sh/cli/').replace(/\/+$/, '');
     const installerUrl = process.env.BEEHAVEN_INSTALL_URL || 'https://www.clearly.sh/install.sh';
     const temp = mkdtempSync(join(tmpdir(), 'beehaven-self-update-'));
@@ -154,9 +158,32 @@ export function runSelfUpdate(kind = installKind()) {
         rmSync(temp, { recursive: true, force: true });
     }
 }
+/**
+ * ⚠ npm installs (the only Windows install) update with npm itself — see `npm-update.ts` for why
+ * it refuses rather than guessing when this copy is not npm's global install or the prefix is not
+ * writable. The daemon restarts itself after ITS hourly update; after this manual one the running
+ * daemon keeps the old code until restarted, so the message says so.
+ */
+function runNpmSelfUpdate() {
+    const manual = 'Update it by hand: npm install -g @clearlysh/beehaven@latest';
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const plan = npmUpdatePlan(pkgRoot);
+    if (!plan.ok)
+        return { ok: false, message: `Can't update this npm install here: ${plan.reason}.\n  ${manual}` };
+    const latest = latestNpmVersion(plan.npm);
+    if (!latest)
+        return { ok: false, message: `Update failed: could not read the latest version from npm.\n  ${manual}` };
+    const current = installedNpmVersion(plan.globalRoot) ?? '0.0.0';
+    if (compareVersions(latest, current) <= 0)
+        return { ok: true, message: `Already up to date (${current}).` };
+    const r = installNpmVersionSync(plan, latest);
+    return r.ok
+        ? { ok: true, message: `${r.message} A daemon that is already running keeps the old version until: beehaven restart` }
+        : { ok: false, message: `${r.message}\n  ${manual}` };
+}
 /** True when this install can update itself at all — what the notifier uses to pick its wording. */
 export function canSelfUpdate(kind = installKind()) {
-    return kind === 'user';
+    return kind === 'user' || kind === 'npm';
 }
 /**
  * Is a bundled CLI present that the shell can NEVER reach, whatever its version?

package/dist/daemon.js

@@ -46,6 +46,7 @@ import { homedir, tmpdir } from 'os';
 import { join, dirname, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { compareVersions, usableUpdateDigest } from './version-utils.js';
+import { npmUpdatePlan, installNpmVersion } from './npm-update.js';
 import { installKind } from './commands/self-update.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = join(homedir(), '.beehaven');
@@ -963,9 +964,85 @@ function updatesAreManagedExternally() {
  *
  * ⚠ NOTHING ELSE CALLS IT. The daemon's timer is still the only production caller.
  */
+/** Said once per daemon, not hourly — see the managed-updates note below. */
+let announcedNpmUpdateBlocked = false;
+/**
+ * Start the freshly installed version and leave (shared by the curl and npm update paths).
+ * A CLI-spawned headless daemon is detached, with no supervisor to interpret exit 75, so it starts
+ * the new entry in a helper that waits until this process releases the IPC socket.
+ */
+async function restartForUpdate() {
+    if (process.env.BEEHAVEN_CLI_OWNED_DAEMON === '1') {
+        const child = spawn(process.execPath, [join(__dirname, 'daemon-entry.js'), '--restart-after-update', String(process.pid)], {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env,
+        });
+        child.on('error', (error) => console.error(`  [update] Restart helper failed: ${error.message}`));
+        if (!child.pid)
+            throw new Error('could not start update restart helper');
+        child.unref();
+    }
+    if (daemonRelay?.isConnected())
+        await new Promise((r) => setTimeout(r, 500));
+    process.exit(75);
+}
+/**
+ * ⚠⚠ npm INSTALLS (THE ONLY WINDOWS INSTALL) NEVER AUTO-UPDATED (CAN2-57). This routine re-ran the
+ * bash installer, so it skipped every npm install and a Windows user stayed on their first version.
+ * They now update with npm itself — to the version the release manifest names (stable only) — when
+ * this copy IS npm's global install and its folder is writable; otherwise one line says why and
+ * what to run. No rollback file: `install.sh` cannot reinstall an npm package; a bad release is
+ * undone with `npm install -g @clearlysh/beehaven@<previous>`.
+ */
+async function checkAndAutoUpdateNpm() {
+    // A headless daemon's stdout goes nowhere, so the update story also goes to daemon.log.
+    const say = (m, level = 'info') => {
+        (level === 'error' ? console.error : console.log)(`  [update] ${m}`);
+        try {
+            logger[level]('daemon', `[update] ${m}`);
+        }
+        catch { /* logging never blocks an update */ }
+    };
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const res = await fetch(LATEST_MANIFEST, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return;
+        const latest = (await res.json())?.version;
+        if (typeof latest !== 'string')
+            return;
+        const current = getCurrentVersion();
+        if (compareVersions(latest, current) <= 0)
+            return;
+        const plan = npmUpdatePlan(join(__dirname, '..'));
+        if (!plan.ok) {
+            if (!announcedNpmUpdateBlocked) {
+                announcedNpmUpdateBlocked = true;
+                say(`${latest} is available, but this npm install cannot update itself: ${plan.reason}. Run: npm install -g @clearlysh/beehaven@latest`);
+            }
+            return;
+        }
+        say(`Updating ${current} → ${latest} with npm...`);
+        const r = await installNpmVersion(plan, latest);
+        if (!r.ok)
+            throw new Error(r.message);
+        if (getCurrentVersion() !== latest)
+            throw new Error(`npm did not install ${latest}`);
+        say(`Updated to v${latest} — restarting...`);
+        await restartForUpdate();
+    }
+    catch (error) {
+        say(`Update failed: ${error?.message ?? error}`, 'error');
+    }
+}
 export async function checkAndAutoUpdate() {
     const owner = updatesAreManagedExternally();
     const runningKind = installKind(join(__dirname, 'daemon-entry.js'));
+    if (!owner && runningKind === 'npm')
+        return checkAndAutoUpdateNpm();
     if (owner || runningKind !== 'user') {
         // Said once at startup, not hourly — a line every hour about a thing that is working as
         // designed is how a log stops being read.
@@ -1017,19 +1094,6 @@ export async function checkAndAutoUpdate() {
             throw new Error(`installer did not install ${latest}`);
         }
         console.log(`  [update] Updated to v${latest} — restarting...`);
-        if (process.env.BEEHAVEN_CLI_OWNED_DAEMON === '1') {
-            // A CLI-spawned headless daemon is detached, with no supervisor to interpret exit 75.
-            // Start the new entry in a helper that waits until this process releases the IPC socket.
-            const child = spawn(process.execPath, [join(__dirname, 'daemon-entry.js'), '--restart-after-update', String(process.pid)], {
-                detached: true,
-                stdio: 'ignore',
-                env: process.env,
-            });
-            child.on('error', (error) => console.error(`  [update] Restart helper failed: ${error.message}`));
-            if (!child.pid)
-                throw new Error('could not start update restart helper');
-            child.unref();
-        }
         // Drop the temp tarball BEFORE exiting. `process.exit` skips `finally`,
         // so cleaning up only there would leak the whole release into /tmp on every
         // SUCCESSFUL update — the one path that always runs.
@@ -1046,13 +1110,9 @@ export async function checkAndAutoUpdate() {
             catch { }
             installerPath = null;
         }
-        // Give relay a moment to flush
-        if (daemonRelay?.isConnected()) {
-            await new Promise((r) => setTimeout(r, 500));
-        }
-        // Exit with non-zero so launchd/systemd restarts with the new version
-        // (KeepAlive > SuccessfulExit > false means exit 0 stays down)
-        process.exit(75);
+        // Start the new version and exit non-zero, so launchd/systemd also restarts with it
+        // (KeepAlive > SuccessfulExit > false means exit 0 stays down).
+        await restartForUpdate();
     }
     catch (error) {
         console.error(`  [update] Update failed: ${error?.message ?? error}`);
@@ -4056,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),
                 });
@@ -4081,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}`);
     })
@@ -4098,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: {