beehaven 0.8.16

package/dist/daemon.js

@@ -0,0 +1,4471 @@
+// ============================================================================
+// Beehaven Daemon — Clearly's Local Agent
+// Captures dev activity, relays to Clearly cloud, enables remote agent control.
+// No Express server, no browser UI — the office lives at clearly.sh/office.
+// ============================================================================
+import { ClaudeWatcher } from './watcher.js';
+import { devModeAvailable } from './build-channel.js';
+import { Relay } from './relay.js';
+// ⚠ The identity the daemon's OWN in-process tools act as — the same desktop binding its CLI
+//   spawns carry. See the `invokeRpc` note at `setClearlyTools`.
+import { daemonToolIdentity, desktopPrincipal, listAgents } from './agent-state.js';
+import { DaemonRepl } from './repl.js';
+import { browsePath } from './file-browser.js';
+import { CloudBeeProxy } from './bee/cloud-proxy.js';
+import { IpcServer, probeIpcSocket } from './ipc-server.js';
+import { mintIpcAuthTokens, clearIpcAuthToken } from './ipc-auth.js';
+/**
+ * What THIS daemon minted, so shutdown can avoid scrubbing a successor's token.
+ * ⚠ Undefined until the mint runs — a shutdown before that legitimately clears nothing of ours.
+ */
+let mintedIpcTokens;
+import { isDaemonFetchUrlAllowed, mayReceiveCredentials } from './daemon-fetch-allowlist.js';
+/**
+ * ⚠ STATIC, unlike the `await import` the deleted bootstrap used. `scanInstalledApps` is
+ * synchronous and runs on the app-registration path; this module is fs/path only, so there is no
+ * load cost to defer.
+ */
+import { bundledHiveDir } from './first-party-hives.js';
+import { isPubliclyVisibleApp } from './public-surface.js';
+import { TranscriptTailer } from './transcript-tailer.js';
+import { getLinkedFolders, FolderWatcher } from './folder-sync.js';
+import { LocalAppManager } from './local-app-manager.js';
+import { Dashboard } from './dashboard.js';
+import { logger, setLogLevel } from './logger.js';
+import { HealthMonitor } from './health.js';
+import { keychain } from './keychain.js';
+import { resolveAgentIdentitySecret, verifyAgentToken, mintAgentToken, } from './agent-identity-daemon.js';
+import { AgentSessions } from './agent-sessions.js';
+import { RELAY_PRESETS, relayUrlFromConfig, resolveRelaySelection } from './relay-presets.js';
+import { readFileSync, existsSync, mkdirSync, mkdtempSync, writeFileSync, readdirSync, chmodSync, unlinkSync, rmSync, } from 'fs';
+import { createHash } from 'crypto';
+import { execFile, execSync, spawn } from 'child_process';
+import { homedir, tmpdir } from 'os';
+import { join, dirname, relative } from 'path';
+import { fileURLToPath } from 'url';
+import { compareVersions, usableUpdateDigest } from './version-utils.js';
+import { installKind } from './commands/self-update.js';
+import { collectSystemTelemetry, collectGitStatus } from './telemetry.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_DIR = join(homedir(), '.beehaven');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const PID_FILE = join(CONFIG_DIR, 'daemon.pid');
+/**
+ * Inspect the app manager's installed catalog for any app that declares
+ * `buildings.<name>.hosted: "cloud"` matching the requested building name.
+ * Returns the resolved cloudUrl (with template vars still substituted by
+ * the caller) + the owning app's name so broadcasts can attribute the
+ * forward correctly.
+ */
+function findCloudBuildingRoute(appManager, buildingName) {
+    if (!appManager || typeof appManager.listInstalledApps !== 'function')
+        return null;
+    for (const h of appManager.listInstalledApps()) {
+        if (!h.cloudBuildings)
+            continue;
+        const match = h.cloudBuildings.find((c) => c.name === buildingName);
+        if (match)
+            return { cloudUrl: match.cloudUrl, appName: h.name };
+    }
+    return null;
+}
+/**
+ * Forward a app-rpc to a cloud-hosted building.
+ *
+ * Two paths, behind the same function:
+ *
+ *   1. Real relay forwarding — send a cloud-app-rpc message over the
+ *      existing wss://relay.clearly.sh connection, wait for a matching
+ *      cloud-app-rpc-result message, return the payload. The Cloudflare
+ *      Worker (future work) deserializes, routes to a Durable Object,
+ *      handles the request, sends the result back.
+ *
+ *   2. Local in-process simulator — when `BEEHAVEN_CLOUD_SIMULATOR=1`
+ *      (dev default), skip the relay hop and invoke a stub handler right
+ *      here in the daemon. Lets us prove the whole wire format end-to-end
+ *      before the Worker side is deployed.
+ *
+ * The contract is identical either way: the caller gets a Promise that
+ * resolves to the result or rejects with an error.
+ */
+async function forwardCloudAppRpc(params) {
+    const { relay, cloudUrl, app, building, instanceId, action, input, rid } = params;
+    // Local simulator path: any app with a :simulator URL, or the global
+    // BEEHAVEN_CLOUD_SIMULATOR flag, runs through a canned handler. This
+    // is what lets the Mac app demo Shopify without a deployed Worker.
+    const simulatorMode = process.env.BEEHAVEN_CLOUD_SIMULATOR !== '0';
+    if (simulatorMode) {
+        return simulateCloudAppRpc({ app, building, instanceId, action, input });
+    }
+    // Real relay-forwarded path. Requires the cloud side to be running
+    // and the relay WebSocket to be connected. Not wired as default yet.
+    if (!relay || !relay.isConnected?.()) {
+        throw new Error('Cloud routing unavailable — relay not connected');
+    }
+    return new Promise((resolve, reject) => {
+        const handler = (msg) => {
+            if (msg?.type === 'cloud-app-rpc-result' && msg.rid === rid) {
+                relay.offBroadcast?.(handler);
+                clearTimeout(timer);
+                if (msg.error)
+                    reject(new Error(msg.error));
+                else
+                    resolve(msg.result);
+            }
+        };
+        const timer = setTimeout(() => {
+            relay.offBroadcast?.(handler);
+            reject(new Error('Cloud app RPC timeout (30s)'));
+        }, 30000);
+        relay.onBroadcast?.(handler);
+        relay.wsSend?.({
+            type: 'cloud-app-rpc',
+            rid,
+            app,
+            building,
+            instanceId,
+            action,
+            input,
+            cloudUrl,
+        });
+    });
+}
+/**
+ * Local cloud-app simulator. Stands in for a Cloudflare Worker + DO
+ * routing layer. Every cloud app installed on this machine can provide
+ * its own simulated handlers by exporting a `cloudHandlers` map from a
+ * file at <appDir>/cloud.js, but for now we ship a hardcoded Shopify
+ * response so the end-to-end demo works.
+ */
+async function simulateCloudAppRpc(params) {
+    const { app, building, action, input } = params;
+    // Shopify stub — canned Admin API responses for the demo UI.
+    if (building === 'shopify') {
+        switch (action) {
+            case 'products-list':
+                return {
+                    products: [
+                        { id: 9187348231, title: 'Canvas Tote — Ekali Edition', stock: 42 },
+                        { id: 9187348232, title: 'Studio Notebook, A5, Charcoal', stock: 127 },
+                        { id: 9187348233, title: 'Monk Strap Hoodie — Black', stock: 8 },
+                        { id: 9187348234, title: 'Enamel Pin Set (3-pack)', stock: 219 },
+                        { id: 9187348235, title: 'Vinyl: "Nitepunk Piano" LP', stock: 64 },
+                    ],
+                    simulated: true,
+                    note: 'Local cloud simulator — would hit admin.shopify.com in prod',
+                };
+            case 'store-info':
+                return {
+                    name: 'cloudhive-demo',
+                    domain: 'cloudhive-demo.myshopify.com',
+                    plan: 'development',
+                    currency: 'USD',
+                    simulated: true,
+                };
+            default:
+                throw new Error(`shopify stub: unknown action "${action}"`);
+        }
+    }
+    throw new Error(`No simulator for cloud app "${app}" building "${building}"`);
+}
+/**
+ * Curated "available to install" app list served by /api/marketplace.
+ *
+ * This is a stub catalog. Once the cloud marketplace is live, the daemon
+ * will fetch from https://clearly.sh/apps/catalog.json instead of this
+ * hardcoded array. The installed-app set is subtracted at serve time so
+ * users don't see things they already have.
+ *
+ * Shapes roughly mirror AgentHiveCatalogEntry minus the live "registered"
+ * state — a catalog entry is a promise of what installing would give you.
+ */
+const CATALOG_URL = 'https://clearly.sh/apps/catalog.json';
+const CATALOG_CACHE_MS = 5 * 60_000; // 5 min
+let _catalogCache = null;
+let _catalogFetchedAt = 0;
+/** Fetch the app catalog from clearly.sh, falling back to the static array. */
+async function getAvailableApps() {
+    if (_catalogCache && Date.now() - _catalogFetchedAt < CATALOG_CACHE_MS) {
+        return _catalogCache;
+    }
+    let remote = [];
+    try {
+        const res = await fetch(CATALOG_URL, { signal: AbortSignal.timeout(2_000) });
+        if (res.ok) {
+            const data = (await res.json());
+            if (data.apps?.length)
+                remote = data.apps;
+        }
+    }
+    catch { }
+    // Merge: static fallback fills gaps the remote catalog doesn't have yet.
+    // Useful during development when new apps aren't deployed to clearly.sh.
+    const names = new Set(remote.map((a) => a.name));
+    const merged = [...remote, ...STATIC_FALLBACK_APPS.filter((a) => !names.has(a.name))];
+    _catalogCache = merged;
+    _catalogFetchedAt = Date.now();
+    return merged;
+}
+const STATIC_FALLBACK_APPS = [
+    {
+        name: 'ableton',
+        version: '1.0.0',
+        description: 'Ableton Live 12 controller — 140+ actions for transport, tracks, clips, devices, composition via AbletonOSC. Claude as your music producer.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['creative', 'audio', 'local'],
+        kind: 'local',
+        install: { source: 'bundled' },
+    },
+    {
+        name: 'memory-cloud',
+        version: '0.1.0',
+        description: 'Persistent memory and notes for AI agents — remember, recall, search, tag, and time-travel through version history.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['memory', 'notes', 'local'],
+        kind: 'local',
+        install: { source: 'bundled' },
+    },
+    {
+        name: 'shopify',
+        version: '0.1.0',
+        description: 'Your Shopify store as a beehaven app — products, inventory, orders, customers, Admin API. Cloud-hosted: the building runs in a Cloudflare DO and talks to your store via OAuth. Install once, use from Claude and the browser.',
+        vendor: 'Clearly',
+        tier: 'pro',
+        tags: ['commerce', 'cloud', 'api'],
+        kind: 'cloud',
+        install: { source: 'url', url: 'https://clearly.sh/apps/shopify/shopify-0.1.0.hive' },
+        frontend: { title: 'Shopify', icon: '🛍️' },
+    },
+    {
+        name: 'blender',
+        version: '0.1.0',
+        description: 'Blender 4.x controller over its scripting bridge. Create scenes, add objects, set materials, render frames. Claude as a technical director.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['creative', '3d', 'local'],
+        kind: 'local',
+        install: { source: 'url', url: 'https://clearly.sh/apps/blender/blender-0.1.0.hive' },
+        frontend: { title: 'Blender', icon: '🧊' },
+    },
+    {
+        name: 'figma',
+        version: '0.1.0',
+        description: 'Figma plugin bridge — list files, read frames, generate variants, run layout operations. Cloud app — uses your Figma API token stored in Clearly.',
+        vendor: 'Clearly',
+        tier: 'pro',
+        tags: ['design', 'cloud', 'api'],
+        kind: 'cloud',
+        install: { source: 'url', url: 'https://clearly.sh/apps/figma/figma-0.1.0.hive' },
+        frontend: { title: 'Figma', icon: '🎨' },
+    },
+    {
+        name: 'logic-pro',
+        version: '0.1.0',
+        description: 'Logic Pro via MainStage / Core MIDI. Similar action surface to the ableton app — tracks, regions, plugins, mixer. Requires Logic 11 and the Clearly Script MIDI device enabled.',
+        vendor: 'Clearly',
+        tier: 'pro',
+        tags: ['creative', 'audio', 'local'],
+        kind: 'local',
+        install: { source: 'url', url: 'https://clearly.sh/apps/logic-pro/logic-pro-0.1.0.hive' },
+        frontend: { title: 'Logic Pro', icon: '🎚️' },
+    },
+    {
+        name: 'hue',
+        version: '0.1.0',
+        description: 'Philips Hue + Matter lights — scene control, color, brightness, rooms. "Claude, set the vibe for dinner" territory.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['smart-home', 'local'],
+        kind: 'local',
+        install: { source: 'url', url: 'https://clearly.sh/apps/hue/hue-0.1.0.hive' },
+        frontend: { title: 'Philips Hue', icon: '💡' },
+    },
+    {
+        name: 'jira',
+        version: '0.1.0',
+        description: 'Jira Cloud — list issues, transition status, sprint triage, backlog grooming. Cloud-hosted, OAuth install flow.',
+        vendor: 'Clearly',
+        tier: 'pro',
+        tags: ['productivity', 'cloud', 'api'],
+        kind: 'cloud',
+        install: { source: 'url', url: 'https://clearly.sh/apps/jira/jira-0.1.0.hive' },
+        frontend: { title: 'Jira', icon: '📋' },
+    },
+    {
+        name: 'clearly-voice',
+        version: '0.1.0',
+        description: 'System-wide voice-to-text. Press Cmd+Shift+E anywhere to dictate — auto-pastes into the focused text field. Powered by Gemini STT.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['voice', 'stt', 'dictation', 'local'],
+        kind: 'local',
+        install: { source: 'bundled' },
+        frontend: { title: 'Clearly Voice', icon: '🎙️' },
+    },
+    {
+        name: 'recorder',
+        version: '0.1.0',
+        description: 'System audio recorder — capture desktop audio, mic, or both to WAV/MP3. Tag, trim, and send recordings to other apps. Built on BlackHole virtual audio.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['audio', 'recording', 'local'],
+        kind: 'local',
+        install: { source: 'bundled' },
+        frontend: { title: 'Recorder', icon: '🎤' },
+    },
+    // Internal SEO / marketing hives — used by scheduled routines on the
+    // operator's machine. `internal: true` keeps them out of the user-facing
+    // catalog unless HIVE_DEV_MODE=1 is set on the daemon. They're also
+    // excluded from the prod electron-builder bundle, so even if a prod
+    // user toggles dev mode the bundled-install path errors out cleanly.
+    {
+        name: 'gsc',
+        version: '0.1.0',
+        description: 'Google Search Console client — Search Analytics queries (top queries, deltas, page mix) via service-account or ADC auth. Used by SEO routines for daily pulse, weekly keyword refresh, monthly audit.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['seo', 'analytics', 'gsc', 'local', 'internal'],
+        kind: 'local',
+        install: { source: 'bundled' },
+        frontend: { title: 'Search Console', icon: '🔎' },
+        internal: true,
+    },
+    {
+        name: 'marketing',
+        version: '0.1.0',
+        description: 'Marketing analytics — funnel + DAU + revenue from Cloudflare Analytics Engine + Stripe. Installs / connect / link / subscription / conversion event aggregator for SEO and growth routines.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['analytics', 'marketing', 'funnel', 'revenue', 'local', 'internal'],
+        kind: 'local',
+        install: { source: 'bundled' },
+        frontend: { title: 'Marketing', icon: '📈' },
+        internal: true,
+    },
+    {
+        name: 'backlinks',
+        version: '0.1.0',
+        description: 'Backlink audit + diff — pluggable provider (DataForSEO / Ahrefs / Moz / Majestic) plus a no-API manual-crawl path. Snapshots persist locally for week-over-week diffs.',
+        vendor: 'Clearly',
+        tier: 'free',
+        tags: ['seo', 'backlinks', 'analytics', 'local', 'internal'],
+        kind: 'local',
+        install: { source: 'bundled' },
+        frontend: { title: 'Backlinks', icon: '🔗' },
+        internal: true,
+    },
+];
+/** Scan ~/.beehaven/apps/ (canonical) and ~/.beehaven/hives/ (legacy) for installed apps.
+ *  Accepts app.json or hive.json as manifest.
+ *
+ * ⚠⚠ ONE APP PER MANIFEST NAME. This deduped by DIRECTORY NAME, which is not the same question:
+ * `avatar/` and `avatar@0.1.0/` are two different directory names carrying the same
+ * `"name": "avatar"`, and both shapes exist in the wild — the bare one is the legacy install
+ * layout, the versioned one is what `ensureFirstPartyHives` writes. Observed on a real machine
+ * with both present: the daemon registered the same hive TWICE, and whichever `readdir` happened
+ * to yield first won — while the Mac app's `resolveUiDir` matched only the versioned shape and
+ * could therefore be reading the other copy entirely.
+ *
+ * That is the split this repo has already paid for once, when a `.bak-` directory shadowed a real
+ * install and "the action answered correctly while the UI that renders it did not exist". Nothing
+ * breaks loudly; the two halves simply run different code.
+ *
+ * Newest manifest version wins, and `apps/` beats legacy `hives/` at equal versions because it is
+ * the canonical root. Losers are LOGGED, never deleted — this is a user's disk, and a wrong guess
+ * about which copy mattered is not recoverable. */
+/**
+ * The hives the product itself needs, loaded from the bundle rather than installed.
+ *
+ * `avatar` is included because its daemon building is the CLI/agent route for the Mac app's
+ * on-screen companion. The overlay UI and the building both resolve from the read-only bundle;
+ * nothing is copied into ~/.beehaven.
+ */
+// The avatar building is part of the Mac app's first-party surface. Register it from the bundle
+// in place so `beehaven connect avatar` and per-agent `say` work immediately after app install;
+// this does not copy the hive into ~/.beehaven.
+const FIRST_PARTY_HIVES = ['avatar', 'vector', 'image', 'bee-canvas'];
+function bundledFirstPartyRoots() {
+    return FIRST_PARTY_HIVES
+        .map((name) => bundledHiveDir(name, __dirname))
+        .filter((dir) => !!dir);
+}
+function scanInstalledApps() {
+    const roots = [join(CONFIG_DIR, 'apps'), join(CONFIG_DIR, 'hives')];
+    const byName = new Map();
+    const dropped = [];
+    const versionRank = (v) => {
+        const p = String(v ?? '0').split('-')[0].split('.').map((n) => Number(n) || 0);
+        return (p[0] ?? 0) * 1e6 + (p[1] ?? 0) * 1e3 + (p[2] ?? 0);
+    };
+    for (let i = 0; i < roots.length; i += 1) {
+        const root = roots[i];
+        if (!existsSync(root))
+            continue;
+        try {
+            for (const entry of readdirSync(root)) {
+                if (entry.startsWith('.'))
+                    continue;
+                const dir = join(root, entry);
+                const am = join(dir, 'app.json');
+                const hm = join(dir, 'hive.json');
+                const mp = existsSync(am) ? am : existsSync(hm) ? hm : null;
+                if (!mp)
+                    continue;
+                let manifest;
+                try {
+                    manifest = JSON.parse(readFileSync(mp, 'utf8'));
+                }
+                catch {
+                    continue;
+                }
+                // The manifest's own name is the identity. Falling back to the directory name stops a
+                // manifest with no name from colliding with every other nameless one.
+                const name = typeof manifest?.name === 'string' && manifest.name ? manifest.name : entry;
+                // `roots.length - i` keeps apps/ ahead of legacy hives/ when versions tie.
+                const rank = versionRank(manifest?.version) * 10 + (roots.length - i);
+                const prev = byName.get(name);
+                if (!prev) {
+                    byName.set(name, { dir, entry, manifest, rank });
+                    continue;
+                }
+                const candidate = { dir, entry, manifest, rank };
+                const winner = rank > prev.rank ? candidate : prev;
+                const loser = rank > prev.rank ? prev : candidate;
+                byName.set(name, winner);
+                dropped.push(`${name}: using ${winner.dir}, ignoring ${loser.dir}`);
+            }
+        }
+        catch { }
+    }
+    /**
+     * ⚠⚠ FIRST-PARTY HIVES ARE READ FROM THE BUNDLE, IN PLACE — NEVER COPIED IN (2026-08-28).
+     *
+     * These used to be installed into `~/.beehaven/apps` by `ensureFirstPartyHives`, which copies a
+     * hive's WHOLE project directory: `src/`, `scripts/`, `tsconfig.json`, `package.json`, and for
+     * the avatar a `ui/` that the Mac app then RENDERED FROM. Three things followed, all observed:
+     * first-party source lived outside version control where a `cpSync(..., { force: true })` could
+     * destroy edits made to it; which copy the product ran depended on startup timing; and the
+     * daemon and the window could resolve different copies of one hive with nothing reporting it.
+     *
+     * Reading the bundle directly is the fix, and it is strictly better than a smarter copy: there
+     * is one location, it ships with the app, it is not writable by accident, and `~/.beehaven`
+     * goes back to holding only runtime state — config, credentials, logs.
+     *
+     * ⚠ ADDED LAST AND RANKED LOWEST, so a genuinely user-installed hive of the same name still
+     * wins. This adds a fallback; it takes nothing away.
+     *
+     * ⚠ AN EXPLICIT ALLOWLIST, NOT THE WHOLE DIRECTORY. In the packaged app the bundled hives dir
+     * holds two entries, but in a monorepo dev layout the same resolver finds `clearly-hives/`,
+     * which has twenty-one — scanning it wholesale would silently register every experiment in the
+     * repo as a live building.
+     */
+    for (const name of FIRST_PARTY_HIVES) {
+        if (byName.has(name))
+            continue;
+        try {
+            const dir = bundledHiveDir(name, __dirname);
+            if (!dir)
+                continue;
+            const mp = existsSync(join(dir, 'app.json')) ? join(dir, 'app.json') : join(dir, 'hive.json');
+            if (!existsSync(mp))
+                continue;
+            const manifest = JSON.parse(readFileSync(mp, 'utf8'));
+            byName.set(name, { dir, entry: name, manifest, rank: 0 });
+        }
+        catch { /* a bundled hive that cannot be read is simply absent */ }
+    }
+    if (dropped.length > 0) {
+        console.warn(`  [app] duplicate installs resolved by version:\n    ${dropped.join('\n    ')}`);
+    }
+    return [...byName.values()].map(({ dir, entry, manifest }) => ({ dir, entry, manifest }));
+}
+function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return { onboarded: false, tier: 'local' };
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+    }
+    catch {
+        return { onboarded: false, tier: 'local' };
+    }
+}
+// `relayUrlFromConfig` / `RELAY_PRESETS` / `resolveRelaySelection` moved to the
+// dependency-free ./relay-presets.js so read surfaces (whoami, admin console,
+// auth-origin selection) can derive "which relay / which env" WITHOUT importing
+// this heavy daemon module. Re-exported here for back-compat with existing
+// `import { … } from './daemon.js'` callers.
+export { RELAY_PRESETS, relayUrlFromConfig, resolveRelaySelection };
+/**
+ * Resolve the relay URL for this daemon launch. Order of precedence:
+ *   1. BEEHAVEN_RELAY_URL env var (set by the Mac app's daemon-manager,
+ *      or by a one-shot override like `BEEHAVEN_RELAY_URL=… beehaven start`)
+ *   2. config.endpoint → config.relayUrl (via relayUrlFromConfig)
+ *   3. Hard-coded prod default
+ */
+export function resolveRelayUrlForDaemon() {
+    const fromEnv = process.env.BEEHAVEN_RELAY_URL;
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return relayUrlFromConfig(loadConfig()) ?? 'wss://relay.clearly.sh';
+}
+/** Persist a chosen env (and the resolved URL) into ~/.beehaven/config.json. */
+export function saveEnvChoice(name, url) {
+    // Write the canonical dial target `endpoint` alongside the `relayUrl`/
+    // `envName` aliases so all three stay in lockstep. Previously only
+    // relayUrl/envName were written, so `endpoint` (what the relay client
+    // actually dials) drifted — `beehaven env` reported one env while the
+    // daemon stayed connected to another.
+    saveConfig({ envName: name, relayUrl: url, endpoint: url });
+}
+function saveConfig(update) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const existing = loadConfig();
+    // Pass mode to writeFileSync so the file is created with 0600 from the
+    // start — no race where another process could read it before the
+    // subsequent chmodSync lands. The chmod stays as defense-in-depth.
+    writeFileSync(CONFIG_FILE, JSON.stringify({ ...existing, ...update }, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(CONFIG_FILE, 0o600);
+    }
+    catch { }
+}
+/** Redact secrets from text before relaying to cloud */
+export function redactSecrets(text) {
+    return (text
+        // API keys, tokens, passwords in key=value or key: value format
+        .replace(/(api[_-]?key|token|secret|password|auth)\s*[:=]\s*['"]?[a-zA-Z0-9_\-./+]{8,}['"]?/gi, '$1=[REDACTED]')
+        // Bearer/Basic auth headers
+        .replace(/(Bearer|Basic)\s+[a-zA-Z0-9_\-./+=]{8,}/gi, '$1 [REDACTED]')
+        // Likely AWS access keys (20+ uppercase alphanumeric)
+        .replace(/\b(AKIA[A-Z0-9]{16})\b/g, '[REDACTED]'));
+}
+// ── Session Sync ──────────────────────────────────────────────────────────
+const SYNCED_SESSIONS_FILE = join(CONFIG_DIR, 'synced-sessions.json');
+const SESSIONS_DIR = join(CONFIG_DIR, 'sessions');
+function loadSyncedSessions() {
+    if (!existsSync(SYNCED_SESSIONS_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(SYNCED_SESSIONS_FILE, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function saveSyncedSessions(synced) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(SYNCED_SESSIONS_FILE, JSON.stringify(synced));
+}
+/** Upload un-synced local sessions to Clearly cloud. Batched, throttled, crash-safe. */
+export async function syncHistoricalSessions(relay) {
+    if (!existsSync(SESSIONS_DIR))
+        return { uploaded: 0, skipped: 0, failed: 0 };
+    const synced = loadSyncedSessions();
+    let files;
+    try {
+        files = readdirSync(SESSIONS_DIR).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return { uploaded: 0, skipped: 0, failed: 0 };
+    }
+    const unsynced = files.filter((f) => !synced[f.replace('.json', '')]);
+    if (unsynced.length === 0)
+        return { uploaded: 0, skipped: files.length, failed: 0 };
+    let uploaded = 0;
+    let failed = 0;
+    const CONCURRENCY = 2;
+    const STAGGER_MS = 500;
+    for (let i = 0; i < unsynced.length; i += CONCURRENCY) {
+        if (!relay.isConnected())
+            break;
+        const batch = unsynced.slice(i, i + CONCURRENCY);
+        await Promise.all(batch.map(async (f) => {
+            const id = f.replace('.json', '');
+            const ok = await relay.uploadSession(join(SESSIONS_DIR, f), id);
+            if (ok) {
+                synced[id] = Date.now();
+                uploaded++;
+            }
+            else {
+                failed++;
+            }
+        }));
+        saveSyncedSessions(synced);
+        if (i + CONCURRENCY < unsynced.length) {
+            await new Promise((r) => setTimeout(r, STAGGER_MS));
+        }
+    }
+    return { uploaded, skipped: files.length - unsynced.length, failed };
+}
+// Event deduplication ring buffer
+const recentEventKeys = new Set();
+const DEDUP_MAX = 200;
+function isDuplicate(event) {
+    const key = `${event.session_id}:${event.hook_event_name}:${event.tool_use_id || ''}:${event.timestamp}`;
+    if (recentEventKeys.has(key))
+        return true;
+    recentEventKeys.add(key);
+    if (recentEventKeys.size > DEDUP_MAX) {
+        const keep = Array.from(recentEventKeys).slice(-DEDUP_MAX + 50);
+        recentEventKeys.clear();
+        for (const k of keep)
+            recentEventKeys.add(k);
+    }
+    return false;
+}
+// ── Agent Metrics ─────────────────────────────────────────────────────────
+class AgentMetrics {
+    toolCalls = 0;
+    toolErrors = 0;
+    consecutiveErrors = 0;
+    lastErrorFile = '';
+    filesChanged = new Map(); // path → timestamp
+    lastEventType = '';
+    lastEventAt = 0;
+    activeSessions = new Set();
+    windowStart = Date.now();
+    /** Process a raw event and update metrics */
+    track(event) {
+        this.lastEventType = event.hook_event_name;
+        this.lastEventAt = Date.now();
+        if (event.hook_event_name === 'SessionStart') {
+            this.activeSessions.add(event.session_id);
+        }
+        if (event.hook_event_name === 'SessionEnd') {
+            this.activeSessions.delete(event.session_id);
+        }
+        if (event.hook_event_name === 'PostToolUse') {
+            this.toolCalls++;
+            this.consecutiveErrors = 0;
+            // Track file changes from Edit/Write
+            if (event.tool_name === 'Edit' || event.tool_name === 'Write') {
+                const filePath = event.tool_input?.file_path;
+                if (filePath)
+                    this.filesChanged.set(filePath, Date.now());
+            }
+        }
+        if (event.hook_event_name === 'PostToolUseFailure') {
+            this.toolCalls++;
+            this.toolErrors++;
+            this.consecutiveErrors++;
+            const filePath = event.tool_input?.file_path;
+            if (filePath)
+                this.lastErrorFile = filePath;
+        }
+        if (event.hook_event_name === 'PreToolUse') {
+            // Track file reads too for velocity
+            if (event.tool_name === 'Read' || event.tool_name === 'Glob' || event.tool_name === 'Grep') {
+                this.toolCalls++;
+            }
+        }
+    }
+    /** Get current metrics snapshot */
+    snapshot() {
+        const now = Date.now();
+        const windowMs = now - this.windowStart;
+        const windowMin = Math.max(1, windowMs / 60_000);
+        // Prune old file changes (older than 5 min)
+        const fiveMinAgo = now - 5 * 60_000;
+        for (const [path, ts] of this.filesChanged) {
+            if (ts < fiveMinAgo)
+                this.filesChanged.delete(path);
+        }
+        const recentFiles = [...this.filesChanged.keys()];
+        return {
+            activeSessions: this.activeSessions.size,
+            totalToolCalls: this.toolCalls,
+            toolCallsPerMinute: +(this.toolCalls / windowMin).toFixed(1),
+            errorRate: this.toolCalls > 0 ? +(this.toolErrors / this.toolCalls).toFixed(3) : 0,
+            filesChanged: recentFiles.slice(0, 20),
+            fileChangeVelocity: +(recentFiles.length / Math.min(5, windowMin)).toFixed(1),
+            consecutiveErrors: this.consecutiveErrors,
+            loopDetected: this.consecutiveErrors >= 5,
+            lastErrorFile: this.lastErrorFile,
+            lastEventType: this.lastEventType,
+            lastEventAge: this.lastEventAt > 0 ? Math.floor((now - this.lastEventAt) / 1000) : -1,
+        };
+    }
+    /** Reset window (called periodically) */
+    resetWindow() {
+        this.toolCalls = 0;
+        this.toolErrors = 0;
+        this.windowStart = Date.now();
+    }
+}
+/** Relay ref — set in startDaemon() */
+let daemonRelay = null;
+/** CloudBeeProxy ref — set in startDaemon() */
+let daemonAgent = null;
+/** REPL ref — set in startDaemon() */
+let daemonRepl = null;
+/** Config ref — set in startDaemon() */
+let daemonConfig = null;
+/** LocalAppManager ref — set in startDaemon() */
+let daemonAppManager = null;
+// ── Auto-Update ───────────────────────────────────────────────────────────
+// curl-only distribution — the CLI is NOT published to npm. Updates fetch the
+// versioned tarball from downloads.clearly.sh via the public installer script.
+let announcedManagedUpdates = false;
+const INSTALL_URL = process.env.BEEHAVEN_INSTALL_URL || 'https://clearly.sh/install.sh';
+/**
+ * ⚠ THE SAME OVERRIDE ITS SIBLING ALREADY HAD. `min-version.ts` reads `BEEHAVEN_CLI_FEED` so the
+ * force-update gate can be exercised against a scratch channel; the auto-updater — the half that
+ * DOWNLOADS AND INSTALLS CODE — was hardcoded, so the only way to rehearse it was against the live
+ * channel, which is the one thing `docs/FORCE_UPDATE.md` says never to do.
+ *
+ * ⚠ IT CHANGES NOTHING IN PRODUCTION: unset, this is byte-identical to the literal it replaces.
+ * What it buys is that the verify-then-install path can be run end to end with a sandboxed HOME,
+ * including the case that matters — a tarball whose digest does not match being REFUSED.
+ */
+const CLI_FEED = process.env.BEEHAVEN_CLI_FEED || 'https://downloads.clearly.sh/cli/';
+const LATEST_MANIFEST = `${CLI_FEED.replace(/\/?$/, '/')}latest.json`;
+/**
+ * ⚠⚠ THE DOWNLOAD IS PINNED TO THIS BASE AND NEVER TO `manifest.tarball` — see the note at the
+ * fetch. That is a security property, and moving the base with `BEEHAVEN_CLI_FEED` does not weaken
+ * it: the URL is still built from the VALIDATED version against a base this process was configured
+ * with, rather than followed from a remote document. A manifest still cannot redirect the fetch.
+ *
+ * ⚠ IT MOVES WITH THE MANIFEST, DELIBERATELY. A scratch feed whose tarball still resolved to the
+ * production host is not a rehearsal — it is a 404, which is what the first attempt at this
+ * measured, and which silently skips the digest check the rehearsal exists to exercise.
+ */
+const TARBALL_BASE = CLI_FEED.replace(/\/+$/, '');
+const UPDATE_CHECK_INTERVAL = 60 * 60 * 1000; // 1 hour
+const ROLLBACK_FILE = join(CONFIG_DIR, 'previous-version.json');
+/**
+ * This daemon's own version — the left-hand side of the auto-update comparison.
+ *
+ * TWO CANDIDATE PATHS, because there are two layouts and only one used to be checked:
+ *   • repo / npm install → `__dirname` is `packages/cli/dist`, so the manifest is `../`.
+ *   • Mac app bundle     → electron-builder FLATTENS `dist/` into `Resources/beehaven/`, so
+ *     `__dirname` IS that folder and the manifest sits BESIDE the code, not above it.
+ *
+ * The bundle copies `package.json` in for exactly this reason ("so getVersion() can find it
+ * after the bundle flattens dist/") — but the lookup only ever went UP, so the copy was never
+ * read and the bundled daemon reported `0.0.0`. Consequences, on every single Mac app launch:
+ * it concluded it was years out of date, downloaded the published tarball, overwrote the
+ * bundled daemon with it, and exited 75 to restart — a network install per launch, the
+ * bundled build silently replaced by whatever is published, and (observed) a window where
+ * nothing is listening on the IPC socket at all.
+ *
+ * `0.0.0` is retained as the last resort, and it still means "assume ancient, update" — that
+ * is the right behaviour for a genuinely unidentifiable install. It just must not be reached
+ * by a layout we ship.
+ */
+function getCurrentVersion() {
+    for (const candidate of [join(__dirname, 'package.json'), join(__dirname, '..', 'package.json')]) {
+        try {
+            const v = JSON.parse(readFileSync(candidate, 'utf8')).version;
+            if (v)
+                return v;
+        }
+        catch {
+            /* try the next layout */
+        }
+    }
+    return '0.0.0';
+}
+/** Save current version before an auto-update so we can rollback if needed. */
+function savePreUpdateState(version) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(ROLLBACK_FILE, JSON.stringify({
+            version,
+            timestamp: Date.now(),
+            reason: 'pre-update-backup',
+        }));
+    }
+    catch {
+        /* non-critical — update proceeds without rollback safety */
+    }
+}
+/** After startup, check if we just upgraded and verify health. */
+function runPostUpdateHealthCheck(relay) {
+    if (!existsSync(ROLLBACK_FILE))
+        return;
+    let prev;
+    try {
+        prev = JSON.parse(readFileSync(ROLLBACK_FILE, 'utf-8'));
+    }
+    catch {
+        // Corrupt file — clean up
+        try {
+            unlinkSync(ROLLBACK_FILE);
+        }
+        catch { }
+        return;
+    }
+    const current = getCurrentVersion();
+    if (prev.version === current) {
+        // Same version — not a fresh upgrade, nothing to check
+        return;
+    }
+    console.log(`  [update] Upgraded ${prev.version} → ${current} — verifying health in 30s...`);
+    setTimeout(() => {
+        if (!relay.isConnected()) {
+            console.error(`  [update] New version ${current} failed health check — relay not connected.`);
+            console.error(`  [update] To rollback: beehaven rollback`);
+        }
+        else {
+            // Update succeeded, clean up rollback file
+            try {
+                unlinkSync(ROLLBACK_FILE);
+            }
+            catch { }
+            console.log(`  [update] Upgraded ${prev.version} → ${current} — healthy`);
+        }
+    }, 30_000);
+}
+/** Install a specific version (used by rollback command). */
+export function rollbackToVersion(version) {
+    const tarball = `${TARBALL_BASE}/beehaven-${version}.tgz`;
+    console.log(`  [rollback] Installing v${version} from ${tarball}...`);
+    try {
+        // curl-only distribution (the CLI is NOT on npm): re-run the installer with
+        // BEEHAVEN_TARBALL pinned to the target version's tarball.
+        execSync(`curl -fsSL "${INSTALL_URL}" | BEEHAVEN_TARBALL="${tarball}" sh`, {
+            timeout: 120_000,
+            stdio: 'inherit',
+        });
+        // Clean up rollback file after successful rollback
+        try {
+            if (existsSync(ROLLBACK_FILE))
+                unlinkSync(ROLLBACK_FILE);
+        }
+        catch { }
+        console.log(`  [rollback] Rolled back to v${version}.`);
+        console.log(`  [rollback] Restart the daemon: quit and relaunch the Clearly Dev Mac app.`);
+        return true;
+    }
+    catch (err) {
+        console.error(`  [rollback] Failed: ${err.message}`);
+        return false;
+    }
+}
+/** Read saved previous version info (for rollback command). */
+export function getPreviousVersion() {
+    if (!existsSync(ROLLBACK_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(ROLLBACK_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Download the update tarball and prove it is the artifact the manifest
+ * describes, BEFORE any of it is executed.
+ *
+ * Returns the verified local path, or null with a logged reason.
+ *
+ * Why this exists: this function used to not. `checkAndAutoUpdate` read a
+ * version number off a JSON file and immediately ran `curl … | sh` — an
+ * unattended, hourly, unverified code-execution path. Whatever the bucket
+ * served became code on every user's machine, with no digest, no signature
+ * and no prompt.
+ */
+async function fetchVerifiedUpdateTarball(manifest) {
+    // The version string reaches BOTH a URL and a filesystem path below, and
+    // it arrives from a remote JSON document — so it is untrusted input.
+    // Unvalidated, a manifest advertising `../../../../.bashrc` would make
+    // `join(tmpdir(), …)` escape tmpdir and write wherever it liked, turning
+    // "check for updates" into an arbitrary-file-write. Constrain it to the
+    // shape a version can actually have before it is used as either.
+    const version = String(manifest?.version ?? '');
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        console.error(`  [update] Ignoring update: "${version}" is not a valid version string.`);
+        return null;
+    }
+    const expected = usableUpdateDigest(manifest);
+    if (!expected) {
+        // FAIL CLOSED. Publishing without the digest is a release-process bug
+        // (publish-beehaven-cli.sh always writes it). The manual updater also
+        // refuses an unverifiable release, so only a corrected feed can repair it.
+        console.error(`  [update] ${manifest.version} is available but its manifest carries no usable sha256 — refusing to auto-update.`);
+        console.error('  [update] The published feed must be repaired before this release can be installed.');
+        return null;
+    }
+    // Pin the download to the expected host rather than following whatever
+    // `tarball` says: a manifest that can redirect the fetch anywhere is a
+    // second injection point for the same attack.
+    // Both built from the VALIDATED `version`, never the raw manifest field.
+    const url = `${TARBALL_BASE}/beehaven-${version}.tgz`;
+    const tempDir = mkdtempSync(join(tmpdir(), 'beehaven-update-'));
+    const dest = join(tempDir, `beehaven-${version}.tgz`);
+    let verified = false;
+    try {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), 120_000);
+        let res;
+        try {
+            res = await fetch(url, { signal: controller.signal });
+        }
+        finally {
+            clearTimeout(t);
+        }
+        if (!res.ok) {
+            console.error(`  [update] Download failed: ${res.status} ${url}`);
+            return null;
+        }
+        const bytes = Buffer.from(await res.arrayBuffer());
+        const actual = createHash('sha256').update(bytes).digest('hex');
+        if (actual !== expected) {
+            // Do not retry, do not fall back — a digest mismatch is either
+            // corruption or tampering, and both mean "don't run this".
+            console.error(`  [update] REFUSING ${version}: sha256 mismatch (expected ${expected}, got ${actual}).`);
+            return null;
+        }
+        writeFileSync(dest, bytes, { mode: 0o600 });
+        verified = true;
+        return dest;
+    }
+    catch (err) {
+        console.error(`  [update] Download/verify failed: ${err?.message ?? err}`);
+        return null;
+    }
+    finally {
+        if (!verified) {
+            try {
+                rmSync(tempDir, { recursive: true, force: true });
+            }
+            catch { }
+        }
+    }
+}
+/**
+ * Is this daemon's version owned by something else?
+ *
+ * ⚠⚠ SET BY THE MAC APP WHEN IT SPAWNS THE BUNDLED DAEMON. That daemon lives inside a signed
+ * `.app` and is shipped with it, so its version is the app's to decide — and self-updating it is
+ * not merely redundant, it is destructive: `install.sh` overwrites `~/.local/bin/beehaven` with a
+ * shim that carries no ownership header, and `cli-installer` then (correctly) refuses to take the
+ * path back. The app's own CLI ends up permanently unreachable from the shell while the app keeps
+ * respawning the bundled daemon from `Resources`, so the "update" never even takes effect.
+ *
+ * ⚠ THE VALUE IS IGNORED — presence is the signal. Anything that spawns a daemon it intends to
+ * keep at a fixed version says so by setting this; there is no registry of legal owners to keep
+ * in step.
+ */
+function updatesAreManagedExternally() {
+    const owner = (process.env.BEEHAVEN_MANAGED_BY ?? '').trim();
+    return owner ? owner : null;
+}
+/**
+ * ⚠ EXPORTED FOR THE SAME REASON `refreshMinVersion` IS: the update path downloads and installs
+ * code, and the only way to rehearse it was to run a whole daemon against the LIVE channel — which
+ * is the one thing the force-update doc says never to do. Exported, it can be driven with
+ * `BEEHAVEN_CLI_FEED` pointed at a scratch feed and `HOME` sandboxed, so the case that matters
+ * (a tarball whose digest does not match is REFUSED) is actually exercised rather than assumed.
+ *
+ * ⚠ NOTHING ELSE CALLS IT. The daemon's timer is still the only production caller.
+ */
+export async function checkAndAutoUpdate() {
+    const owner = updatesAreManagedExternally();
+    const runningKind = installKind(join(__dirname, 'daemon-entry.js'));
+    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.
+        if (!announcedManagedUpdates) {
+            announcedManagedUpdates = true;
+            console.log(`  [update] skipped — this daemon is ${owner ? `managed by ${owner}` : `a ${runningKind} build`}`);
+        }
+        return;
+    }
+    let verifiedTarball = null;
+    let installerPath = null;
+    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 data = await res.json();
+        const latest = data.version;
+        if (!latest)
+            return;
+        const current = getCurrentVersion();
+        if (compareVersions(latest, current) <= 0)
+            return;
+        // Verify BEFORE executing anything. Returns null (and explains) when
+        // the artifact can't be proven, in which case we do not update.
+        verifiedTarball = await fetchVerifiedUpdateTarball(data);
+        if (!verifiedTarball)
+            return;
+        // Save current version for rollback before updating
+        savePreUpdateState(current);
+        console.log(`  [update] Updating ${current} → ${latest} (sha256 verified)...`);
+        // Download before execution. In `curl | sh`, a failed curl still leaves sh exiting 0;
+        // the daemon would announce an update and exit while still running the old install.
+        installerPath = join(dirname(verifiedTarball), 'install.sh');
+        await new Promise((resolve, reject) => {
+            execFile('curl', ['-fsSL', '--max-time', '30', '-o', installerPath, INSTALL_URL], { timeout: 35_000 }, (err) => err ? reject(err) : resolve());
+        });
+        await new Promise((resolve, reject) => {
+            execFile('/bin/sh', [installerPath], {
+                timeout: 120_000,
+                env: { ...process.env, BEEHAVEN_TARBALL: `file://${verifiedTarball}` },
+            }, (err) => err ? reject(err) : resolve());
+        });
+        if (getCurrentVersion() !== latest) {
+            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.
+        // ⚠ That used to read "~500 KB" and is now ~5 MB: the published tarball carries its own
+        //   node_modules (scripts/vendor-cli-deps.mjs), so the installer runs no npm install. Net
+        //   this makes the 120s timeout above SAFER, not tighter — a 4 MB download replaces a
+        //   registry resolution of ~105 packages, which is the step that could actually blow it.
+        cleanupVerifiedTarball();
+        if (installerPath) {
+            try {
+                if (existsSync(installerPath))
+                    unlinkSync(installerPath);
+            }
+            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);
+    }
+    catch (error) {
+        console.error(`  [update] Update failed: ${error?.message ?? error}`);
+    }
+    finally {
+        // Covers every failure path (download ok, install threw, etc).
+        cleanupVerifiedTarball();
+        if (installerPath) {
+            try {
+                if (existsSync(installerPath))
+                    unlinkSync(installerPath);
+            }
+            catch { }
+        }
+    }
+    function cleanupVerifiedTarball() {
+        if (!verifiedTarball)
+            return;
+        try {
+            rmSync(dirname(verifiedTarball), { recursive: true, force: true });
+        }
+        catch { }
+        verifiedTarball = null;
+    }
+}
+/**
+ * Check if a PID is actually a beehaven daemon (not a recycled PID, and not
+ * some other process whose arguments merely CONTAIN the beehaven path as
+ * a substring — e.g. a shell running a heredoc whose command ends up
+ * including `node .../beehaven/cli.js start`).
+ *
+ * The test requires:
+ *   1. The process's argv[0] is a node/tsx/beehaven binary — not a shell,
+ *      an editor, a grep, etc.
+ *   2. A subsequent argument is a beehaven cli script (cli.ts or cli.js
+ *      under a beehaven* directory OR under a Clearly*.app bundle).
+ *
+ * Matching both conditions catches every known launch shape:
+ *   - monorepo src:     node|tsx .../beehaven(_sdk)?/.../cli.ts
+ *   - monorepo dist:    node .../beehaven(_sdk)?/.../cli.js
+ *   - packaged Electron: node .../Clearly*.app/Contents/Resources/beehaven/cli.js
+ *   - global wrapper:   .../bin/beehaven start  (argv[0] ends with /beehaven)
+ */
+function isBeehavenProcess(pid) {
+    try {
+        let cmd;
+        if (process.platform === 'darwin') {
+            cmd = execSync(`ps -p ${pid} -o command=`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 3000,
+            }).trim();
+        }
+        else {
+            // Linux: /proc/PID/cmdline uses NULs; normalize to spaces
+            cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ').trim();
+        }
+        if (!cmd)
+            return false;
+        // Condition 1: argv[0] must be a node/tsx/beehaven-wrapper binary.
+        // Anchoring with ^ so a shell running a heredoc that contains
+        // "node .../cli.js" deeper in its argv doesn't false-positive.
+        const argv0Ok = /^(\S*\/)?node(\s|$)/.test(cmd) ||
+            /^(\S*\/)?tsx(\s|$)/.test(cmd) ||
+            /^(\S*\/)?beehaven(\s|$)/.test(cmd);
+        if (!argv0Ok)
+            return false;
+        // Condition 2: a subsequent argument must reference a beehaven script.
+        //
+        // NOTE THE `\.?` — the directory may be `beehaven/` OR the DOTFILE
+        // `.beehaven/`. `public/install.sh` installs to `~/.beehaven/cli/`, which is
+        // the canonical location for every `curl … | sh` user, and these patterns
+        // used to require a path segment of exactly "beehaven". So the CLI could not
+        // recognise its OWN standard install: `stop` reported "No daemon running"
+        // while one was running, `restart` printed a fresh PID whose process then
+        // died with "Refusing to start — IPC socket already serving connections",
+        // and the real daemon was effectively unkillable from the CLI. Only
+        // monorepo (`beehaven_sdk/`) and Mac-app installs were ever detected.
+        const scriptOk = 
+        // Dedicated daemon entry — what the Mac app tray spawns.
+        /[/\\]\.?beehaven(_sdk)?[/\\].*daemon-entry\.(js|ts)\b/.test(cmd) ||
+            /Clearly[^/\\]*\.app[/\\]Contents[/\\]Resources[/\\]beehaven[/\\]daemon-entry\.js\b/.test(cmd) ||
+            // Legacy `cli.js start` — for old bundles pre-dating daemon-entry.js.
+            /[/\\]\.?beehaven(_sdk)?[/\\].*cli\.(js|ts)\b/.test(cmd) ||
+            /Clearly[^/\\]*\.app[/\\]Contents[/\\]Resources[/\\]beehaven[/\\]cli\.js\b/.test(cmd) ||
+            // Bare `beehaven start` — wrapper already matched argv[0].
+            /^(\S*\/)?beehaven\s+start\b/.test(cmd);
+        return scriptOk;
+    }
+    catch {
+        return false; // Can't read → not our process or already dead
+    }
+}
+/**
+ * Find any running beehaven daemon process on this machine, excluding the
+ * current process. Returns PIDs discovered via pgrep, filtered by
+ * isBeehavenProcess for safety.
+ */
+export function findLiveDaemons() {
+    const found = new Set();
+    // 1. Check PID file first — the canonical source.
+    if (existsSync(PID_FILE)) {
+        try {
+            const pid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+            if (Number.isFinite(pid) && pid > 0 && pid !== process.pid) {
+                try {
+                    process.kill(pid, 0);
+                    if (isBeehavenProcess(pid))
+                        found.add(pid);
+                }
+                catch {
+                    /* dead */
+                }
+            }
+        }
+        catch { }
+    }
+    // 2. pgrep — catches orphans the PID file doesn't track.
+    //    Patterns mirror isBeehavenProcess() above. Each candidate is
+    //    re-validated by isBeehavenProcess so a broad pgrep hit still has
+    //    to pass the strict regex check before being considered ours.
+    const patterns = [
+        'beehaven.*daemon-entry\\.(js|ts)',
+        'beehaven.*cli\\.(js|ts)',
+        'Clearly.*Resources/beehaven',
+    ];
+    for (const pattern of patterns) {
+        try {
+            const out = execSync(`pgrep -f "${pattern}"`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            for (const line of out.split('\n')) {
+                const pid = parseInt(line, 10);
+                if (Number.isFinite(pid) && pid !== process.pid && isBeehavenProcess(pid)) {
+                    found.add(pid);
+                }
+            }
+        }
+        catch {
+            /* pgrep returns non-zero if no matches */
+        }
+    }
+    return [...found];
+}
+/** Wait for a PID to exit, with SIGKILL escalation. Returns true if process exited. */
+function waitForExit(pid, timeoutMs) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            process.kill(pid, 0); // Still alive
+            const end = Date.now() + 100;
+            while (Date.now() < end) {
+                /* spin */
+            }
+        }
+        catch {
+            return true; // Process exited
+        }
+    }
+    return false; // Still alive after timeout
+}
+/**
+ * Stop all beehaven daemon processes — PID file + any orphans.
+ *
+ * ⚠⚠ `quiet` EXISTS BECAUSE THIS FUNCTION'S NARRATION LEAKED INTO `login`'s. `beehaven stop` is a
+ * command ABOUT stopping, so "Stopping daemon (PID …)" / "Daemon stopped." is the answer there.
+ * Inside `login` the restart is an IMPLEMENTATION DETAIL of picking up new credentials, and these
+ * lines landed mid-sentence in an unterminated `Restarting daemon… ` prompt:
+ *
+ *     Restarting daemon…   Stopping daemon (PID 72928)...
+ *     Daemon stopped.
+ *     ✓ (PID 73532)
+ *
+ * — three lines of machinery and a tick attached to nothing, immediately after a sign-in.
+ *
+ * ⚠ A FAILURE IS STILL LOUD. `quiet` suppresses the ROUTINE narration only; a force-kill still
+ * prints, because a daemon that would not die is something the caller must hear about whatever it
+ * happened to be doing at the time.
+ */
+export function stopDaemonProcess(opts = {}) {
+    const say = opts.quiet ? (_m) => { } : (m) => console.log(m);
+    let killed = false;
+    // findLiveDaemons() walks both the PID file and pgrep patterns, and
+    // filters via isBeehavenProcess so recycled PIDs never get signaled.
+    const pidsToKill = findLiveDaemons();
+    // Always clear the PID file regardless of what we found — next start
+    // will write a fresh one.
+    if (existsSync(PID_FILE)) {
+        try {
+            unlinkSync(PID_FILE);
+        }
+        catch { }
+    }
+    if (pidsToKill.length === 0) {
+        say('  No daemon running.');
+        return false;
+    }
+    // 3. Send SIGTERM to all
+    for (const pid of pidsToKill) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            say(`  Stopping daemon (PID ${pid})…`);
+            killed = true;
+        }
+        catch { }
+    }
+    // 4. Wait up to 3s for graceful exit, then SIGKILL stragglers
+    for (const pid of pidsToKill) {
+        if (!waitForExit(pid, 3000)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+                console.log(`  Force-killed daemon (PID ${pid}) — did not exit after SIGTERM.`);
+            }
+            catch { }
+            waitForExit(pid, 1000); // Brief wait for SIGKILL to take effect
+        }
+    }
+    say('  Daemon stopped.');
+    return killed;
+}
+export async function startDaemon(opts) {
+    // ── Single-instance enforcement ─────────────────────────────────────
+    // At most one beehaven daemon per machine. This refuses to start if a
+    // live daemon is already running; the CLI's `start` command calls
+    // stopDaemonProcess() first to do a clean replacement, so user-facing
+    // `beehaven start` still "just works" — this guard only fires when the
+    // daemon is invoked directly (launchd race, double-spawn, etc).
+    const existingDaemons = findLiveDaemons();
+    if (existingDaemons.length > 0) {
+        const existingList = existingDaemons.join(', ');
+        console.error(`\n  ✗ Another beehaven daemon is already running (PID ${existingList}).`);
+        console.error(`  ✗ Quit the Clearly Dev Mac app tray to stop the existing daemon, then restart.\n`);
+        try {
+            logger.error('daemon', `Refusing to start — daemon already running at PID ${existingList}`);
+        }
+        catch { }
+        process.exit(1);
+    }
+    // Defense-in-depth: even if no PID was found, probe the IPC socket. A
+    // live server answering here means some daemon is alive that findLiveDaemons
+    // missed (e.g. different binary path, permissions edge case).
+    if (await probeIpcSocket()) {
+        console.error(`\n  ✗ Another beehaven daemon is listening on /tmp/beehaven-ipc.sock.`);
+        console.error(`  ✗ Quit the Clearly Dev Mac app tray to stop the existing daemon, then restart.\n`);
+        try {
+            logger.error('daemon', 'Refusing to start — IPC socket already serving connections');
+        }
+        catch { }
+        process.exit(1);
+    }
+    // Require login — Beehaven needs a Clearly account to relay.
+    // When started by Electron (BEEHAVEN_NO_REPL=1), skip interactive login —
+    // Electron will provision the token via provisionDaemon() after sign-in.
+    let config = loadConfig();
+    // Auto-migrate: move plaintext token to OS keychain if available
+    if (config.token && keychain.available && config.tokenStorage !== 'keychain') {
+        if (keychain.setToken(config.token)) {
+            config.tokenStorage = 'keychain';
+            delete config.token;
+            saveConfig({ tokenStorage: 'keychain', token: undefined });
+            logger.info('daemon', 'Migrated token from config file to OS keychain');
+        }
+    }
+    // Resolve token: keychain or plaintext
+    const hasToken = config.tokenStorage === 'keychain' ? !!keychain.getToken() : !!config.token;
+    if (!hasToken && !process.env.BEEHAVEN_NO_REPL) {
+        const { login } = await import('./setup-relay.js');
+        const loggedIn = await login();
+        if (!loggedIn) {
+            process.exit(1);
+        }
+        config = loadConfig();
+    }
+    // Initialize core components
+    const watcher = new ClaudeWatcher();
+    const relay = new Relay();
+    const agent = new CloudBeeProxy(relay);
+    const metrics = new AgentMetrics();
+    // Live workspace sessions for CLI-driven AgentIdentities (`agent:connect`).
+    const presenceScope = `${String(config.userId ?? config.user?.uid ?? config.user?.userId ?? 'local')}|${relay.wsBase()}`;
+    const agentSessions = new AgentSessions(() => relay.wsBase(), presenceScope);
+    /**
+     * Keep the desktop presence lease coupled to real attributed work. A daemon restart can leave
+     * the in-memory AgentSessions map empty while the signed identity and workspace session remain
+     * valid; `touch()` alone intentionally no-ops in that state. Reattach from the verified token
+     * (or the local identity record) before touching so the first post-restart action starts the
+     * 30-minute lease from the actual interaction time.
+     */
+    const ensureAgentPresence = (agentId, token = '') => {
+        const id = String(agentId || '').trim();
+        if (!id)
+            return;
+        let sessionToken = String(token || '').trim();
+        if (!sessionToken) {
+            sessionToken = String(listAgents().find((entry) => entry.record.agentId === id)?.record.token || '').trim();
+        }
+        if (!sessionToken)
+            return;
+        agentSessions.ensureConnected(id, sessionToken);
+        agentSessions.touch(id);
+    };
+    const currentVersion = getCurrentVersion();
+    const health = new HealthMonitor(() => relay.isConnected(), () => relay.pendingRequests.size, currentVersion);
+    // Configure log level from config
+    if (config.logLevel)
+        setLogLevel(config.logLevel);
+    logger.info('daemon', `Starting beehaven v${currentVersion} (pid ${process.pid})`);
+    // #105 — rehydrate stored Claude credential on startup. Without this,
+    // users have to re-connect their Anthropic API key every daemon
+    // restart (every Mac app relaunch). For api-key creds, we surface the
+    // secret to process.env.ANTHROPIC_API_KEY so the Agent SDK picks it
+    // up automatically on the next query() call. For plan-OAuth creds,
+    // the Claude CLI manages ~/.claude/.credentials.json directly and
+    // the SDK reads from there — nothing to rehydrate. Failures are
+    // silent + non-fatal: daemon should still start fine without a
+    // Claude credential (user can connect later via the onboarding gate).
+    //
+    // #111 — also remember the rehydrate metadata so the relay.onConnected
+    // handler (assigned further down) can fire a `canvas-credential-rehydrated`
+    // message to the worker the moment the WS opens. This unhides the
+    // Send button on the web UI immediately after a daemon restart
+    // instead of waiting up to 8s for the next claude-credential-status poll.
+    let rehydratedCredential = null;
+    // Claude credential rehydration removed with the daemon Claude Code integration
+    // (destroy-the-treehouse). `rehydratedCredential` stays null.
+    // Set module-level refs
+    daemonRelay = relay;
+    daemonAgent = agent;
+    daemonConfig = config;
+    // ── Tool-gate tier enforcement ──────────────────────────────────────
+    // `setTierResolver` was exported and called by NOBODY, so the
+    // `tier-restrict` policy resolved its stub ('pro') on every tool call
+    // and every user — free included — got Write/Edit/Bash/KillShell. This
+    // is the wiring that makes the gate mean something.
+    //
+    // Source of truth is the subscription plan the relay reports in its
+    // `welcome`/`heartbeat-ack` frames (worker-side `X-Auth-Tier` →
+    // subscriptionPlan). Persisted under its OWN key: `config.tier` is a
+    // different vocabulary entirely (BeeHavenTier = local|connected|team,
+    // a CONNECTION state) and is why `beehaven status` once printed
+    // "Tier: connected". Two meanings in one field is what created that;
+    // don't reuse it.
+    try {
+        const { setTierResolver, planToPolicyTier } = await import('./daemon-omni-policies.js');
+        // The resolver runs on EVERY tool call, so it must not touch the disk
+        // each time — a tool-heavy agent turn would otherwise issue a
+        // synchronous read+parse of config.json per call. Seed the last-known
+        // plan once at startup, then keep it in memory and only WRITE when it
+        // actually changes.
+        let knownPlan = String(loadConfig().productPlan ?? '');
+        setTierResolver(() => {
+            // Connected ⇒ the live plan is authoritative; persist only on change.
+            if (relay.isConnected?.()) {
+                const live = relay.getTier?.();
+                if (live) {
+                    if (live !== knownPlan) {
+                        knownPlan = live;
+                        try {
+                            saveConfig({ productPlan: live });
+                        }
+                        catch {
+                            /* cache write is best-effort — never block a tool call */
+                        }
+                    }
+                    return planToPolicyTier(live);
+                }
+            }
+            // Offline ⇒ last plan we actually saw, so a paying user working on
+            // a plane keeps the tools they bought. Never seen one ⇒ 'free':
+            // we enforce what we can prove, and absence of evidence is not
+            // evidence of a subscription.
+            return planToPolicyTier(knownPlan);
+        });
+    }
+    catch (err) {
+        logger.warn('daemon', `tier resolver not installed: ${err?.message ?? err}`);
+    }
+    // Write PID file for `beehaven stop`
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(PID_FILE, String(process.pid));
+    chmodSync(PID_FILE, 0o600);
+    // Write the running daemon's version to ~/.beehaven/daemon.version
+    // so the Mac app (or any orchestrator) can compare the bundled CLI
+    // version against what's actually live and prompt a restart when
+    // they drift. Updated on every startup; removed on graceful shutdown.
+    const VERSION_FILE = join(CONFIG_DIR, 'daemon.version');
+    try {
+        writeFileSync(VERSION_FILE, currentVersion, { mode: 0o600 });
+    }
+    catch (err) {
+        logger.warn('daemon', `Could not write version file: ${err.message}`);
+    }
+    // Graceful shutdown
+    let shuttingDown = false;
+    let repl;
+    let dashboard = null;
+    const shutdown = (signal) => {
+        if (shuttingDown) {
+            process.exit(1);
+        }
+        shuttingDown = true;
+        try {
+            repl?.stop();
+        }
+        catch { }
+        logger.info('daemon', `${signal} — shutting down`);
+        console.log(`\n  [daemon] ${signal} — shutting down...`);
+        try {
+            health.stop();
+        }
+        catch { }
+        try {
+            agent.stop();
+        }
+        catch { }
+        // The local agent presence projection must be cleared before the daemon exits. Without this,
+        // the Mac overlay keeps rendering identities from a dead daemon until the next launch or the
+        // 30-minute idle timeout, which makes an explicit daemon quit look like a live session.
+        try {
+            // A daemon replacement is not an agent logout. Keep the durable interaction clock so the
+            // next process can restore the 30-minute lease; an explicit agent:disconnect still clears it.
+            agentSessions.disconnectAll(true);
+        }
+        catch { }
+        try {
+            if (daemonAppManager?.running)
+                daemonAppManager.stop();
+        }
+        catch { }
+        try {
+            watcher.stop();
+        }
+        catch { }
+        try {
+            relay.stop();
+        }
+        catch { }
+        try {
+            dashboard?.stop();
+        }
+        catch { }
+        try {
+            if (existsSync(PID_FILE))
+                unlinkSync(PID_FILE);
+        }
+        catch { }
+        try {
+            const VERSION_FILE = join(CONFIG_DIR, 'daemon.version');
+            if (existsSync(VERSION_FILE))
+                unlinkSync(VERSION_FILE);
+        }
+        catch { }
+        // Clean shutdown also clears the tray-readable status file so the
+        // next launch isn't judged by a stale snapshot.
+        try {
+            const STATUS_FILE = join(CONFIG_DIR, 'status.json');
+            if (existsSync(STATUS_FILE))
+                unlinkSync(STATUS_FILE);
+        }
+        catch { }
+        // Scrub the IPC auth token on shutdown. A stale file on disk
+        // after crash is mostly harmless (new daemon mints a fresh token)
+        // but clearing it tightens the window in which an attacker could
+        // pair a captured token with a live socket.
+        try {
+            // ⚠ ONLY OURS — see `clearIpcAuthToken`. Passing nothing here is what deleted a newer
+            //   daemon's token during the restart `daemon.install()` performs on every sign-in.
+            clearIpcAuthToken(mintedIpcTokens);
+        }
+        catch { }
+        // Terminate every Supervised subprocess (vtracer / sam3 server /
+        // ffmpeg / flux / whisper / claude / codex) before we exit. Without
+        // this, the OS reparents descendants to launchd → orphan processes
+        // accumulate across daemon restarts. Each Supervised has its own
+        // SIGTERM → SIGKILL ladder; killAll caps total wait at 2 s.
+        //
+        // Dynamic import: @clearly-sh/beehaven-core is an *optional* peer
+        // dep on the cli package. Pre-migration daemons (no core in their
+        // node_modules) skip this block; migrated daemons get orphan-free
+        // shutdown automatically.
+        (async () => {
+            try {
+                const mod = await import('@clearly-sh/beehaven-core/server');
+                if (mod && typeof mod.SupervisedRegistry?.killAll === 'function') {
+                    await mod.SupervisedRegistry.killAll(2000);
+                }
+            }
+            catch (e) {
+                logger.warn('daemon', `SupervisedRegistry.killAll skipped: ${e?.message ?? e}`);
+            }
+        })().finally(() => {
+            setTimeout(() => process.exit(0), 500);
+        });
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    // ── Don't die of someone else's rejection ───────────────────────────
+    //
+    // The daemon had NO handler for either of these, so Node's default applied:
+    // one stray rejection anywhere in the process exits it — taking the relay,
+    // every loaded hive, the avatar overlay's backend and any in-flight work
+    // with it. That is the wrong trade for a host process. A single request
+    // failing is a request failing; the host surviving it is the whole point of
+    // being a host.
+    //
+    // Found the hard way: cancelling an in-flight daemon-claude turn made the
+    // Agent SDK's own disposal reject from inside an async generator's `finally`
+    // (`Query closed before response received`) — a place no caller can catch,
+    // because by then nobody is awaiting it. The daemon died on a supported
+    // user action.
+    //
+    // Logged LOUDLY rather than swallowed: this is still a bug every time it
+    // fires, and a silent guard would turn crashes into mysteries.
+    process.on('unhandledRejection', (reason) => {
+        const msg = reason?.stack ?? reason?.message ?? String(reason);
+        console.error(`[daemon] UNHANDLED REJECTION (surviving):\n${String(msg).slice(0, 2000)}`);
+    });
+    process.on('uncaughtException', (err) => {
+        console.error(`[daemon] UNCAUGHT EXCEPTION (surviving):\n${String(err?.stack ?? err).slice(0, 2000)}`);
+    });
+    // Interactive REPL
+    repl = new DaemonRepl(relay, agent, () => shutdown('quit'));
+    daemonRepl = repl;
+    // Cloud bee state → REPL
+    relay.onBeeStatus = (msg) => {
+        agent.updateFromCloud(msg);
+        repl.scheduleRedraw();
+    };
+    relay.onBeeThought = (thought) => {
+        repl.logBeeThought(thought);
+    };
+    agent.on('thought', (thought) => {
+        repl.logBeeThought(thought);
+    });
+    // Profile updates → save to config (including settings flags) + notify REPL
+    relay.onProfileUpdate = (profile) => {
+        const update = { user: profile };
+        // Apply settings flags from cloud profile if present
+        if ('shareTerminal' in profile)
+            update.shareTerminal = !!profile.shareTerminal;
+        if ('shareTelemetry' in profile)
+            update.shareTelemetry = !!profile.shareTelemetry;
+        saveConfig(update);
+        // Update live config ref so flags take effect immediately
+        if (daemonConfig)
+            Object.assign(daemonConfig, update);
+        repl.logProfileUpdate(profile);
+    };
+    // Handle file browse requests from the web UI
+    relay.onBrowseFiles = (path, rid) => {
+        const result = browsePath(path);
+        relay.sendBrowseFilesResult(path, result.entries, rid, result.error);
+    };
+    // ── Transcript tailer — streams full Claude Code conversations ──
+    const transcriptTailer = new TranscriptTailer();
+    // Stream transcript entries to DO and IPC clients
+    transcriptTailer.on('entry', (entry) => {
+        // Send to DO for persistent storage
+        if (relay.isConnected()) {
+            relay.wsSend({
+                type: 'transcript-entry',
+                sessionId: entry.sessionId,
+                entryType: entry.type,
+                role: entry.role,
+                content: entry.content?.slice(0, 5000), // Cap content size
+                toolName: entry.toolName,
+                uuid: entry.uuid,
+                timestamp: entry.timestamp,
+            });
+        }
+        // Forward to IPC clients (Electron avatar, office viz)
+        ipc.broadcast({
+            type: 'transcript-entry',
+            ...entry,
+            raw: undefined, // Don't send raw JSONL to IPC clients
+        });
+    });
+    // Auto-tunnel feature removed: it watched Bash output for
+    // localhost:PORT and silently exposed any dev server to the public
+    // internet via *.trycloudflare.com. Even with a random URL, that's
+    // a major scope leak — anyone who learns the URL (DO broadcast
+    // recipients, log scrapers, IPC subscribers) can hit the dev
+    // server. Tunnels are now opt-in: run `cloudflared tunnel` yourself
+    // when you actually want to share a port.
+    // Wire events: watcher → relay + REPL + transcript tailer
+    watcher.on('event', async (event) => {
+        if (isDuplicate(event))
+            return;
+        health.recordEvent();
+        // Send raw event to DO for office state computation
+        relay.sendRawEvent(event);
+        metrics.track(event);
+        repl.logEvent(event);
+        repl.trackEvent(event);
+        const cwdProject = event.cwd
+            ? event.cwd.replace(/\/+$/, '').split('/').filter(Boolean).pop() || undefined
+            : undefined;
+        // Start tailing transcript on SessionStart
+        if (event.hook_event_name === 'SessionStart' && event.transcript_path) {
+            transcriptTailer.startTailing(event.session_id, event.transcript_path);
+        }
+        // (Auto-tunnel hook removed — dev-server URLs are no longer
+        // exposed publicly by the daemon. See note above.)
+        // Stop tailing on SessionEnd
+        if (event.hook_event_name === 'SessionEnd') {
+            transcriptTailer.stopTailing(event.session_id);
+            repl.resetStats();
+        }
+    });
+    // ── IPC server for local clients (Electron, CLI tools) ──
+    //
+    // Auth model: socket file permissions are the security boundary.
+    // The daemon chmods /tmp/beehaven-ipc.sock to 0600 on bind, so only
+    // the same UNIX user can connect. Kernel-enforced; no shared-secret
+    // handshake needed.
+    //
+    // The previous model minted a token in ~/.beehaven/ipc-auth that
+    // both sides read — a symmetric shared-secret pattern that (a) didn't
+    // add any real security for same-user trust and (b) created a brittle
+    // failure mode where deleting the file killed all IPC until the Mac
+    // app was relaunched. Removed in favor of "the OS already knows who
+    // you are."
+    //
+    // Scope-aware IPC auth. Mints a consumer token always; mints a
+    // developer token only when HIVE_DEV_MODE=1. Consumer-scope clients
+    // (mwah, web bridge) get the everyday verb surface. Developer-scope
+    // clients (the full beehaven CLI) get get-token, daemon-fetch,
+    // shell, sql, marketplace:install, admin:* RPCs in addition.
+    //
+    // When dev mode is off, the developer token doesn't exist on disk
+    // and beehaven-side privileged verbs fail closed with FORBIDDEN_SCOPE.
+    // That's the intended security default for the Hive consumer build.
+    /**
+     * ⚠ ONE PREDICATE, AND IT ALSO ANSWERS *MAY* THIS BUILD. A released tarball compiles the
+     * capability out entirely — see `build-channel.ts`; the env var is inert there.
+     */
+    const developerMode = devModeAvailable();
+    const tokens = mintIpcAuthTokens({ developerMode });
+    /**
+     * ⚠ REMEMBERED SO SHUTDOWN CAN TELL ITS OWN TOKEN FROM A SUCCESSOR'S. See `clearIpcAuthToken` —
+     * an unconditional scrub during an overlapping restart deletes the LIVE daemon's token and
+     * strands it without one.
+     */
+    mintedIpcTokens = { consumer: tokens.consumer, developer: tokens.developer };
+    if (developerMode) {
+        logger.info('ipc', 'IPC auth — developer mode ENABLED; dev-scope token issued at ~/.beehaven/ipc-auth-dev');
+    }
+    else {
+        logger.debug('ipc', 'IPC auth — consumer mode; developer-scope verbs are unreachable');
+    }
+    const ipc = new IpcServer({
+        consumerAuthToken: tokens.consumer,
+        developerAuthToken: tokens.developer,
+    });
+    ipc.start();
+    // Forward the authenticated cloud-session projection to local consumers (Mac avatar, office,
+    // etc.). They must not watch the daemon's recovery file as a presence source.
+    agentSessions.setPresenceBroadcast((snapshot) => {
+        ipc.broadcast({ type: 'agent:presence', ...snapshot });
+    });
+    // ── Daemon Omni — Claude Code, hosted here, beehaven-native ─────────
+    //
+    // The Claude Agent SDK runtime (daemon-omni.ts) survived
+    // "destroy-the-treehouse" but lost every door: its `omni:prompt` IPC verb
+    // was documented in its own header and registered nowhere, so the only way
+    // in was `beehaven claude`, which runs the SDK in the CLI's OWN process. A
+    // daemon-hosted runtime that nothing daemon-hosted can reach is a library,
+    // not a runtime. These verbs are the doors.
+    //
+    // ⚠ LOCAL IPC ONLY, and that is a compliance boundary, not a shortcut.
+    // Cloud→daemon Claude orchestration is deliberately disabled (see relay.ts
+    // "Anthropic credential use policy"). The IPC socket is chmod 0600, so the
+    // kernel guarantees the caller is this UNIX user driving their own
+    // subscription. Do NOT bridge these onto `relay.onDaemonRpcRequest` or any
+    // other inbound relay path — that is precisely the shape that was switched
+    // off.
+    {
+        const omni = await import('./daemon-omni.js');
+        /**
+         * ⚠⚠ THE IN-PROCESS BRIDGE FOR HIVES. Buildings are loaded with
+         * `await import(pathToFileURL(entry))` INSIDE this process, so the avatar hive and this module
+         * share a runtime — but not a module graph: the hive is its own package and cannot resolve a
+         * path into the CLI's `src/`. A global registry is the standard bridge for that shape, and it
+         * is explicit about what is shared rather than exposing the module wholesale.
+         *
+         * ⚠⚠ WHY IT EXISTS AT ALL: the avatar chat believed it was already talking to daemon Claude.
+         * Its own comment says *"Omni IS the daemon's Claude"* — but `replyWithOmni` calls the
+         * workspace action `agent-prompt`, which refuses desktop agents outright ("headless
+         * agent-prompt runs the cloud agent (omni) only"). So the local Claude Code session was removed
+         * in favour of something that could never reach it, and every message in that panel went to the
+         * cloud on the workspace's AI pool. This is how the panel reaches the real one.
+         *
+         * ⚠ ABSENT MEANS "not running inside the daemon", which is a legitimate state (a hive loaded by
+         * a test, or a future out-of-process host). Consumers MUST degrade rather than throw.
+         */
+        globalThis.__beehavenOmni = {
+            version: 1,
+            prompt: omni.promptOmni,
+            subscribe: omni.subscribe,
+            listSessions: omni.listSessions,
+            setSessionCwd: omni.setSessionCwd,
+            interrupt: omni.interruptSession,
+            end: omni.endSession,
+        };
+        // Every session's events, fanned out to IPC subscribers as one envelope.
+        // Subscribing once at boot rather than per-prompt: a subscriber attached
+        // per turn would stack, and events that arrive between turns (a late tool
+        // result, a compaction notice) would land on a listener nobody re-added.
+        // Broadcast the OmniEvent AS-IS — its own `type` is the discriminator
+        // (`agent:text-delta`, `agent:tool-call`, `agent:done`, …), which is the
+        // channel mwah's CloudBridge already listens on. Wrapping it in an
+        // envelope would have been the obvious move and is wrong twice: the spread
+        // would overwrite the envelope's own `type`, and it would fork a second
+        // event vocabulary for the same stream.
+        omni.subscribe((event) => ipc.broadcast({ ...event, omni: true }));
+        ipc.on('omni:prompt', async ({ clientId, rid, input }) => {
+            try {
+                const prompt = String(input?.prompt ?? '').trim();
+                if (!prompt)
+                    throw new Error('prompt is required');
+                const res = await omni.promptOmni({
+                    prompt,
+                    // One session per caller-chosen id. Defaults to a single shared
+                    // 'default' thread so a client that doesn't care about session
+                    // management still gets continuity instead of amnesia per message.
+                    sessionId: String(input?.sessionId ?? 'default'),
+                    userId: String(input?.userId ?? 'local'),
+                    /**
+                     * ⚠⚠ DEFAULTS TO THE DESKTOP BINDING, AND WITHOUT IT ONE TURN WORE TWO NAMES.
+                     *
+                     * `agentName` sets `BEEHAVEN_AGENT` for the spawned Claude, so it governs every
+                     * `beehaven` call that Claude makes through Bash. It was optional and `beehaven omni`
+                     * passes none — so the shell half of the session had NO identity, and Claude did the
+                     * reasonable thing: it ran `beehaven agent login <a name it chose>` and carried on.
+                     *
+                     * Observed in one turn, after the `invokeRpc` fix: `canvas-list-compositions` filed under
+                     * `claude-sep` (the MCP tools, via the desktop binding) and `document-create` under
+                     * `jinri-claude` (the shell, via Claude's own login). One caller, one workspace, two
+                     * identities in the activity log — which is WORSE than being unattributed, because the
+                     * log then asserts something false about who did what.
+                     *
+                     * ⚠ AN EXPLICIT `agentName` STILL WINS. The avatar passes its own agent so `beehaven
+                     * speak` uses that avatar's voice; this only supplies the install's identity when the
+                     * caller expressed no opinion.
+                     */
+                    agentName: input?.agentName || desktopPrincipal(),
+                    model: input?.model,
+                    appendSystemPrompt: input?.appendSystemPrompt,
+                    cwd: input?.cwd,
+                    compositionId: input?.compositionId,
+                    compositionTitle: input?.compositionTitle,
+                    allowedTools: input?.allowedTools,
+                    continueSession: input?.continueSession,
+                    resumeSessionId: input?.resumeSessionId,
+                    additionalDirectories: input?.additionalDirectories,
+                });
+                // Resolves when the turn is ACCEPTED. The answer arrives as
+                // `omni:event` frames — a prompt that blocked until completion would
+                // hold the IPC response open for the length of a coding task.
+                ipc.sendRpcResult(clientId, rid, { ...res, accepted: true });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        /**
+         * Answer a question the turn is BLOCKED on.
+         *
+         * ⚠ NOT ROUTED THROUGH A SESSION. The ask registry is keyed by a random id,
+         * so an answer resolves the right promise regardless of which client asked —
+         * which matters because the Mac app and the avatar panel can both be
+         * attached, and either may be the one showing the card.
+         */
+        ipc.on('omni:answer', ({ clientId, rid, input }) => {
+            try {
+                const ok = omni.answerOmniAsk(String(input?.askId ?? ''), String(input?.value ?? ''), input?.outcome === 'dismissed' ? 'dismissed' : 'answered');
+                ipc.sendRpcResult(clientId, rid, { ok });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        /**
+         * A surface declaring what it can render.
+         *
+         * ⚠ RELEASED WHEN THE CLIENT DISCONNECTS, which is why the release function
+         * is held per client rather than being a bare counter. A Mac app that quits
+         * without releasing would leave the daemon believing windows are available
+         * forever, and Omni would go on reporting that it opened them.
+         */
+        ipc.on('omni:surface', ({ clientId, rid, input }) => {
+            try {
+                if (input?.windows) {
+                    const release = omni.declareWindowSurface();
+                    ipc.onClientDisconnect(clientId, release);
+                }
+                ipc.sendRpcResult(clientId, rid, { ok: true, windows: omni.hasWindowSurface() });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        /** Interrupt the turn in flight — the SDK's interrupt, not a process kill. */
+        ipc.on('omni:interrupt', async ({ clientId, rid, input }) => {
+            try {
+                await omni.interruptSession(String(input?.sessionId ?? 'default'));
+                ipc.sendRpcResult(clientId, rid, { interrupted: true });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        ipc.on('omni:end', ({ clientId, rid, input }) => {
+            try {
+                omni.endSession(String(input?.sessionId ?? 'default'));
+                ipc.sendRpcResult(clientId, rid, { ended: true });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        ipc.on('omni:sessions', ({ clientId, rid }) => {
+            try {
+                ipc.sendRpcResult(clientId, rid, {
+                    sessions: omni.listSessions(),
+                    beehavenTools: omni.clearlyToolsMounted(),
+                });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        /**
+         * ⚠⚠ COMPANY MODE'S DIAGNOSTICS, AND THEY REPORT STATE RATHER THAN EVENTS. Two failures here
+         * produce no error and no output at all: the env var never reached the DAEMON (an operator set
+         * it on the shell that talks to the daemon, not on the daemon), and the daemon drifted onto
+         * another workspace because `beehaven connect` is machine-global. A log cannot see either —
+         * it only records turns somebody ran. Same reasoning `thought-stats` exists for.
+         *
+         * ⚠ IT RESOLVES ITS OWN INPUTS HERE, where they are actually known: the identity registry, the
+         * connected building and the claude binary all live on this side. The diagnostic function is
+         * pure and takes them, so it cannot stop working at exactly the moment the thing it inspects
+         * is broken.
+         *
+         *   beehaven call --ipc omni:company-status      (or the tray's dev menu)
+         */
+        ipc.on('omni:company-status', async ({ clientId, rid }) => {
+            try {
+                const { companyDiagnostics } = await import('./daemon-omni-company.js');
+                let claudeBinary = null;
+                try {
+                    const { findClaudeBinary } = await import('./claude-credential-store.js');
+                    claudeBinary = await findClaudeBinary();
+                }
+                catch {
+                    claudeBinary = null;
+                }
+                ipc.sendRpcResult(clientId, rid, companyDiagnostics({
+                    identity: omni.omniIdentityText?.() ?? null,
+                    // ⚠ THE ID, WHICH IS ALL THIS SIDE HAS. `companyDiagnostics` matches it against
+                    //   COMPANY_WORKSPACE_ID and answers `null` — unknown — rather than "wrong" when that is
+                    //   not configured. Reporting a mismatch it cannot actually check is the worse failure.
+                    connectedWorkspace: connectedBuilding?.buildingId ?? null,
+                    claudeBinary,
+                }));
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        /**
+         * ⚠⚠ SEE AND SET THE WORKING DIRECTORY. `omni:sessions` reports `cwd` now — it did not, so the
+         * single most consequential property of a session (which files it reads, which SDK
+         * conversation resumes) was invisible to every caller.
+         *
+         * ⚠ THE THREAD DOES NOT MOVE WITH IT. Claude Code keys a conversation to a project directory
+         * derived from the cwd, so the SDK session id is cleared and the next turn starts fresh. The
+         * reply carries `threadReset` precisely so a UI can SAY that, rather than letting someone
+         * discover it by finding an agent with no memory of the last five minutes.
+         *
+         *   beehaven call --ipc omni:set-cwd '{"sessionId":"…","cwd":"~/projects/clearly"}'
+         */
+        ipc.on('omni:set-cwd', ({ clientId, rid, input }) => {
+            try {
+                ipc.sendRpcResult(clientId, rid, omni.setSessionCwd(String(input?.sessionId ?? ''), String(input?.cwd ?? '')));
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+        ipc.on('omni:branch', ({ clientId, rid, input }) => {
+            try {
+                ipc.sendRpcResult(clientId, rid, omni.branchSession({
+                    sourceSessionId: String(input?.sourceSessionId ?? 'default'),
+                    compositionId: input?.compositionId,
+                }));
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? String(err));
+            }
+        });
+    }
+    // Local client RPCs → forward to DO via relay.
+    //
+    // The relay's default request timeout is 10s, which is too short for
+    // long-running agent actions like `chat-message` (8-15s) and
+    // `admin:store-rpc → chat-message` (which adds a hop). Allow IPC
+    // clients to override the timeout by passing `_timeout` (ms) in the
+    // input object. Sensible default: 60s for arbitrary admin RPCs.
+    // ── Building session state ─────────────────────────────────────
+    // `beehaven connect type/id` stores the active building here.
+    // Subsequent `call`, `ask`, `actions` without --building route through
+    // the Home DO's FocusManager to this building.
+    let connectedBuilding = null;
+    ipc.on('rpc', ({ clientId, rid, action, input }) => {
+        // `beehaven call` sends ordinary workspace work as an agent-invoke envelope over this
+        // transport. Refresh local desktop presence before forwarding it, including when the envelope
+        // is nested inside a workspace/team proxy.
+        const nestedAgentInvoke = action === 'agent-invoke'
+            ? input
+            : (input && typeof input === 'object' && input.action === 'agent-invoke'
+                ? input.input
+                : null);
+        if (nestedAgentInvoke && typeof nestedAgentInvoke === 'object') {
+            ensureAgentPresence(String(nestedAgentInvoke.agentId || ''));
+        }
+        // ── Daemon-local building session commands ──────────────────
+        if (action === 'building:connect') {
+            const { buildingType, buildingId } = input;
+            if (!buildingType || !buildingId) {
+                ipc.sendRpcError(clientId, rid, 'buildingType and buildingId are required');
+                return;
+            }
+            connectedBuilding = { buildingType, buildingId };
+            logger.info('ipc', `Building session: connected to ${buildingType}/${buildingId}`);
+            // Tell the Home DO to focus on this building via FocusManager
+            if (relay.isConnected()) {
+                const buildingKey = `${buildingType}:${buildingId}`;
+                relay
+                    .sendRequest({ type: 'focus', buildings: [buildingKey] }, 10_000)
+                    .then((result) => {
+                    ipc.sendRpcResult(clientId, rid, {
+                        connected: true,
+                        buildingType,
+                        buildingId,
+                        actions: result?.actions ?? null,
+                    });
+                    ipc.broadcast({ type: 'building:connected', buildingType, buildingId });
+                })
+                    .catch((err) => {
+                    // Focus failed but we still store the connection for proxy routing
+                    ipc.sendRpcResult(clientId, rid, {
+                        connected: true,
+                        buildingType,
+                        buildingId,
+                        warning: `Focus failed (${err.message}) — commands will use proxy routing`,
+                    });
+                });
+            }
+            else {
+                ipc.sendRpcResult(clientId, rid, {
+                    connected: true,
+                    buildingType,
+                    buildingId,
+                    warning: 'Not connected to cloud — session stored locally',
+                });
+            }
+            return;
+        }
+        if (action === 'building:disconnect') {
+            const prev = connectedBuilding;
+            connectedBuilding = null;
+            logger.info('ipc', 'Building session: disconnected');
+            // Tell Home DO to unfocus
+            if (relay.isConnected() && prev) {
+                relay
+                    .sendRequest({ type: 'unfocus', buildings: [`${prev.buildingType}:${prev.buildingId}`] }, 5_000)
+                    .catch(() => { }); // Best-effort
+            }
+            ipc.sendRpcResult(clientId, rid, { disconnected: true });
+            ipc.broadcast({ type: 'building:disconnected' });
+            return;
+        }
+        if (action === 'building:connection') {
+            if (connectedBuilding) {
+                ipc.sendRpcResult(clientId, rid, {
+                    connected: true,
+                    buildingType: connectedBuilding.buildingType,
+                    buildingId: connectedBuilding.buildingId,
+                });
+            }
+            else {
+                ipc.sendRpcResult(clientId, rid, { connected: false });
+            }
+            return;
+        }
+        // ── Agent identity ──────────────────────────────────────────
+        // Mint a signed AgentIdentity token for the CLI's `agent login`
+        // (and `rebind`, which re-mints with a new avatarId). The daemon
+        // is the only holder of the signing secret. Owner = the signed-in
+        // user (falls back to 'local' so the local demo works signed-out).
+        if (action === 'agent:mint') {
+            const { agentId, kind, displayName, avatarId, permissions, ttlMs, meta } = (input ||
+                {});
+            if (typeof agentId !== 'string' || !agentId.trim()) {
+                ipc.sendRpcError(clientId, rid, 'agentId (string) is required');
+                return;
+            }
+            const cfg = loadConfig();
+            const userId = cfg.userId ?? cfg.user?.uid ?? cfg.user?.userId ?? 'local';
+            (async () => {
+                try {
+                    const token = await mintAgentToken({
+                        agentId: agentId.trim(),
+                        kind,
+                        displayName,
+                        avatarId,
+                        userId,
+                        permissions: Array.isArray(permissions) ? permissions : undefined,
+                        ttlMs: typeof ttlMs === 'number' ? ttlMs : undefined,
+                        ...(meta && typeof meta === 'object' ? { meta } : {}),
+                    });
+                    const claims = await verifyAgentToken(token);
+                    if (!claims) {
+                        ipc.sendRpcError(clientId, rid, 'minted token failed self-verification');
+                        return;
+                    }
+                    ipc.sendRpcResult(clientId, rid, {
+                        token,
+                        agentId: claims.agentId,
+                        kind: claims.kind,
+                        displayName: claims.displayName,
+                        avatarId: claims.avatarId,
+                        userId: claims.userId,
+                        issuedAt: claims.iat,
+                        expiresAt: claims.exp,
+                    });
+                }
+                catch (err) {
+                    ipc.sendRpcError(clientId, rid, err?.message || 'agent:mint failed');
+                }
+            })();
+            return;
+        }
+        // ── Agent workspace sessions ─────────────────────────────────
+        // Open a live `role:'agent'` session against the cloud workspace using a
+        // CLOUD-signed token (from the worker's agent-mint-token RPC). This is what
+        // makes a CLI-driven agent show up as its own session in my-devices.
+        if (action === 'agent:connect') {
+            const { agentId, token } = (input || {});
+            if (typeof agentId !== 'string' || !agentId.trim() || typeof token !== 'string' || !token) {
+                ipc.sendRpcError(clientId, rid, 'agentId + token are required');
+                return;
+            }
+            agentSessions
+                .connect(agentId.trim(), token)
+                .then((res) => res.ok
+                ? ipc.sendRpcResult(clientId, rid, { ok: true, agentId: agentId.trim() })
+                : ipc.sendRpcError(clientId, rid, res.error || 'agent:connect failed'))
+                .catch((e) => ipc.sendRpcError(clientId, rid, e?.message || 'agent:connect failed'));
+            return;
+        }
+        if (action === 'agent:disconnect') {
+            const { agentId } = (input || {});
+            agentSessions.disconnect(String(agentId || ''));
+            ipc.sendRpcResult(clientId, rid, { ok: true });
+            return;
+        }
+        // ── Session status — returns full picture for Claude + tools ──
+        if (action === 'daemon:session-status') {
+            const sessions = ipc.getSessionInfo();
+            const appStatus = daemonAppManager?.running ? daemonAppManager.status() : null;
+            ipc.sendRpcResult(clientId, rid, {
+                connectedBuilding,
+                // Relay health — the ONLY authoritative answer to "can I actually call
+                // the cloud right now". `beehaven status` used to answer that from the
+                // on-disk token alone, so it printed "Account: Connected" while every
+                // RPC failed with "relay WebSocket is down". Status is the command you
+                // run when things are broken; it must not be the one that lies.
+                relay: {
+                    connected: relay.isConnected(),
+                    configured: relay.isConfigured(),
+                    endpoint: relay.config?.endpoint ?? null,
+                },
+                agentPresence: agentSessions.snapshot(),
+                sessions,
+                localApps: appStatus
+                    ? {
+                        running: appStatus.running,
+                        port: appStatus.port,
+                        buildingTypes: appStatus.buildingTypes,
+                        activeInstances: appStatus.activeInstances,
+                    }
+                    : null,
+                clientCount: ipc.clientCount,
+            });
+            return;
+        }
+        // ── Ensure local apps are loaded + running ──────────────────
+        if (action === 'daemon:app-ensure') {
+            if (!daemonAppManager) {
+                ipc.sendRpcError(clientId, rid, 'App manager not initialized');
+                return;
+            }
+            (async () => {
+                try {
+                    if (!daemonAppManager.running) {
+                        if (daemonAppManager.status().buildingTypes.length === 0) {
+                            await daemonAppManager.loadInstalledApps();
+                            await daemonAppManager.loadInstalledApps(bundledFirstPartyRoots());
+                        }
+                        await daemonAppManager.start();
+                    }
+                    const status = daemonAppManager.status();
+                    ipc.sendRpcResult(clientId, rid, {
+                        running: status.running,
+                        port: status.port,
+                        buildingTypes: status.buildingTypes,
+                        activeInstances: status.activeInstances,
+                    });
+                }
+                catch (err) {
+                    ipc.sendRpcError(clientId, rid, err?.message ?? 'Failed to start apps');
+                }
+            })();
+            return;
+        }
+        // ── App management RPCs (for Claude + CLI) ──────────────────
+        // ── App list: installed + available catalog ──────────────────
+        if (action === 'daemon:app-list') {
+            (async () => {
+                const all = scanInstalledApps();
+                const installed = all
+                    .filter(({ manifest: m }) => isPubliclyVisibleApp(m))
+                    .map(({ entry, manifest: m }) => ({
+                    name: m.name,
+                    version: m.version,
+                    description: m.description,
+                    buildings: m.buildings ? Object.keys(m.buildings) : [],
+                    tier: m.license?.tier ?? 'free',
+                    firstParty: !!m.firstParty,
+                    agent: !!m.agent,
+                    frontend: m.frontend,
+                    dir: entry,
+                }));
+                const installedNames = new Set(installed.map((a) => a.name));
+                const catalog = await getAvailableApps();
+                const available = catalog
+                    .filter((a) => !installedNames.has(a.name))
+                    .filter((a) => isPubliclyVisibleApp(a))
+                    .map((a) => ({
+                    name: a.name,
+                    version: a.version,
+                    description: a.description,
+                    tier: a.tier,
+                    kind: a.kind,
+                    firstParty: a.firstParty ?? a.vendor === 'Clearly',
+                    agent: a.agent ?? false,
+                    frontend: a.frontend,
+                }));
+                ipc.sendRpcResult(clientId, rid, { installed, available });
+            })().catch((err) => ipc.sendRpcError(clientId, rid, err?.message ?? 'List failed'));
+            return;
+        }
+        // ── App install: by name (from catalog) or by path/URL ─────
+        if (action === 'daemon:app-install') {
+            (async () => {
+                try {
+                    const { name, source } = input;
+                    if (!name && !source) {
+                        ipc.sendRpcError(clientId, rid, 'name or source is required. Use name to install from catalog, source for a local path or URL.');
+                        return;
+                    }
+                    const appsDir = join(CONFIG_DIR, 'apps');
+                    mkdirSync(appsDir, { recursive: true });
+                    let resolvedSource = source;
+                    // Resolve name → source from catalog
+                    if (name && !source) {
+                        const catalog = await getAvailableApps();
+                        const catalogEntry = catalog.find((a) => a.name === name);
+                        if (!catalogEntry) {
+                            ipc.sendRpcError(clientId, rid, `App "${name}" not found in catalog. Available: ${catalog.map((a) => a.name).join(', ')}`);
+                            return;
+                        }
+                        if (!isPubliclyVisibleApp(catalogEntry)) {
+                            ipc.sendRpcError(clientId, rid, `App "${name}" is not publicly available.`);
+                            return;
+                        }
+                        if (catalogEntry.install.source === 'bundled') {
+                            // Bundled apps — resolve the hive source directory (catalog name IS
+                            // the hive directory name now that the mwah → avatar alias is gone).
+                            const hiveName = name;
+                            // Hives were extracted from beehaven_sdk/hives/ to the
+                            // sibling repo `clearly-hives/`. Both old (in-tree) and
+                            // new (sibling) paths are checked so older checkouts
+                            // keep working during the transition. The Mac app's
+                            // packaging script bundles clearly-hives into the .app
+                            // at `beehaven/hives/<name>` so the runtime path inside
+                            // the .app stays unchanged (no change needed there).
+                            const hiveDirs = [
+                                // Mac app bundled: beehaven/hives/<name> (same dir as cli.js)
+                                join(__dirname, 'hives', hiveName),
+                                // NEW canonical: clearly-hives sibling repo
+                                //   packages/cli/dist → ../../../clearly-hives/<name>
+                                join(dirname(dirname(dirname(__dirname))), 'clearly-hives', hiveName),
+                                //   Or relative to clearly/ root (4 levels up from dist/)
+                                join(dirname(dirname(dirname(dirname(__dirname)))), 'clearly-hives', hiveName),
+                                // LEGACY (pre-extraction): beehaven_sdk/hives/<name>.
+                                // Kept temporarily for stale checkouts; safe to remove
+                                // once all dev environments have re-cloned.
+                                join(dirname(dirname(__dirname)), 'hives', hiveName),
+                                join(__dirname, '..', '..', 'hives', hiveName),
+                                join(dirname(dirname(dirname(dirname(__dirname)))), 'hives', hiveName),
+                                // Already installed — reinstall from existing
+                                ...(() => {
+                                    const appsDir = join(CONFIG_DIR, 'apps');
+                                    const hivesDir = join(CONFIG_DIR, 'hives');
+                                    const candidates = [];
+                                    for (const root of [appsDir, hivesDir]) {
+                                        if (!existsSync(root))
+                                            continue;
+                                        try {
+                                            for (const e of readdirSync(root)) {
+                                                if (e.startsWith(`${hiveName}@`) || e === hiveName) {
+                                                    candidates.push(join(root, e));
+                                                }
+                                            }
+                                        }
+                                        catch { }
+                                    }
+                                    return candidates;
+                                })(),
+                            ];
+                            let hiveDir = null;
+                            for (const d of hiveDirs) {
+                                if (existsSync(join(d, 'app.json')) || existsSync(join(d, 'hive.json'))) {
+                                    hiveDir = d;
+                                    break;
+                                }
+                            }
+                            if (!hiveDir) {
+                                ipc.sendRpcError(clientId, rid, `Bundled app "${name}" not found in hives/. This app ships with the Clearly Mac app.`);
+                                return;
+                            }
+                            // Copy to install dir
+                            const manifest = JSON.parse(readFileSync(join(hiveDir, 'app.json'), 'utf8'));
+                            const installDir = join(appsDir, `${manifest.name}@${manifest.version}`);
+                            if (existsSync(installDir)) {
+                                rmSync(installDir, { recursive: true, force: true });
+                            }
+                            execSync(`cp -R "${hiveDir}" "${installDir}"`);
+                            // Run setup if declared
+                            if (manifest.setup) {
+                                const scriptPath = join(installDir, manifest.setup);
+                                if (existsSync(scriptPath)) {
+                                    try {
+                                        execSync(`chmod +x "${scriptPath}" && "${scriptPath}"`, {
+                                            cwd: installDir,
+                                            env: {
+                                                ...process.env,
+                                                APP_DIR: installDir,
+                                                APP_NAME: manifest.name,
+                                                APP_VERSION: manifest.version,
+                                            },
+                                            timeout: 300_000,
+                                        });
+                                    }
+                                    catch (e) {
+                                        logger.warn('daemon', `Setup: ${e.message}`);
+                                    }
+                                }
+                            }
+                            // Reload + sync to cloud
+                            if (daemonAppManager) {
+                                try {
+                                    await daemonAppManager.loadInstalledApps();
+                                }
+                                catch { }
+                            }
+                            syncInstalledAppsToCloud();
+                            ipc.broadcast({
+                                type: 'app:installed',
+                                name: manifest.name,
+                                version: manifest.version,
+                                buildings: manifest.buildings ? Object.keys(manifest.buildings) : [],
+                            });
+                            ipc.sendRpcResult(clientId, rid, {
+                                installed: `${manifest.name}@${manifest.version}`,
+                                buildings: manifest.buildings ? Object.keys(manifest.buildings) : [],
+                            });
+                            return;
+                        }
+                        if (catalogEntry.install.url) {
+                            resolvedSource = catalogEntry.install.url;
+                        }
+                        else {
+                            ipc.sendRpcError(clientId, rid, `App "${name}" has no install source`);
+                            return;
+                        }
+                    }
+                    // Download if URL
+                    let archivePath = resolvedSource;
+                    let cleanup = false;
+                    if (/^https?:\/\//.test(archivePath)) {
+                        const tmpPath = join('/tmp', `bh-app-dl-${process.pid}.hive`);
+                        cleanup = true;
+                        execSync(`curl -fsSL "${archivePath}" -o "${tmpPath}"`, { timeout: 60_000 });
+                        archivePath = tmpPath;
+                    }
+                    // Peek at manifest
+                    const manifestJson = execSync(`unzip -p "${archivePath}" app.json`, { encoding: 'utf8' });
+                    const manifest = JSON.parse(manifestJson);
+                    if (!manifest.name || !manifest.version)
+                        throw new Error('Invalid app.json');
+                    // Extract
+                    const installDir = join(appsDir, `${manifest.name}@${manifest.version}`);
+                    if (existsSync(installDir)) {
+                        rmSync(installDir, { recursive: true, force: true });
+                    }
+                    mkdirSync(installDir, { recursive: true });
+                    execSync(`unzip -q "${archivePath}" -d "${installDir}"`);
+                    if (cleanup)
+                        try {
+                            unlinkSync(archivePath);
+                        }
+                        catch { }
+                    // Run setup
+                    if (manifest.setup) {
+                        const scriptPath = join(installDir, manifest.setup);
+                        if (existsSync(scriptPath)) {
+                            try {
+                                execSync(`chmod +x "${scriptPath}" && "${scriptPath}"`, {
+                                    cwd: installDir,
+                                    env: {
+                                        ...process.env,
+                                        APP_DIR: installDir,
+                                        APP_NAME: manifest.name,
+                                        APP_VERSION: manifest.version,
+                                    },
+                                    timeout: 300_000,
+                                });
+                            }
+                            catch (e) {
+                                logger.warn('daemon', `Setup: ${e.message}`);
+                            }
+                        }
+                    }
+                    // Reload + sync to cloud
+                    if (daemonAppManager) {
+                        try {
+                            await daemonAppManager.loadInstalledApps();
+                        }
+                        catch { }
+                    }
+                    syncInstalledAppsToCloud();
+                    ipc.broadcast({
+                        type: 'app:installed',
+                        name: manifest.name,
+                        version: manifest.version,
+                        buildings: manifest.buildings ? Object.keys(manifest.buildings) : [],
+                    });
+                    ipc.sendRpcResult(clientId, rid, {
+                        installed: `${manifest.name}@${manifest.version}`,
+                        buildings: manifest.buildings ? Object.keys(manifest.buildings) : [],
+                    });
+                }
+                catch (err) {
+                    ipc.sendRpcError(clientId, rid, err?.message ?? 'Install failed');
+                }
+            })();
+            return;
+        }
+        // ── App uninstall: remove locally + sync to cloud ──────────
+        if (action === 'daemon:app-uninstall') {
+            try {
+                const { name } = input;
+                if (!name) {
+                    ipc.sendRpcError(clientId, rid, 'name is required');
+                    return;
+                }
+                const removed = [];
+                const all = scanInstalledApps();
+                for (const { dir, entry, manifest } of all) {
+                    if (manifest.name === name || entry.startsWith(`${name}@`)) {
+                        rmSync(dir, { recursive: true, force: true });
+                        removed.push(entry);
+                    }
+                }
+                if (removed.length === 0) {
+                    ipc.sendRpcError(clientId, rid, `App "${name}" not installed`);
+                    return;
+                }
+                for (const r of removed) {
+                    // Extract app name from dir entry (e.g. "avatar@0.1.0" → "avatar")
+                    const appName = r.includes('@') ? r.split('@')[0] : r;
+                    syncUninstallToCloud(appName);
+                    ipc.broadcast({ type: 'app:uninstalled', name: appName });
+                }
+                ipc.sendRpcResult(clientId, rid, { removed });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err?.message ?? 'Uninstall failed');
+            }
+            return;
+        }
+        // ── Standard cloud RPC forwarding ──────────────────────────
+        if (!relay.isConnected()) {
+            const configured = relay.isConfigured();
+            // Say WHICH failure it is. "token may have expired or the connection
+            // dropped" names both causes and neither fix, and the two fixes differ:
+            // an expired token needs `beehaven login` (a restart will NOT refresh it),
+            // a dropped socket needs `beehaven restart`. The daemon knows which — it
+            // holds the token — so it should answer rather than make the caller guess.
+            let expiredToken = false;
+            try {
+                const cfg = Relay.loadConfig();
+                if (cfg?.token) {
+                    const payload = JSON.parse(Buffer.from(cfg.token.split('.')[1], 'base64').toString());
+                    expiredToken = !payload.exp || Date.now() / 1000 > payload.exp - 60;
+                }
+            }
+            catch {
+                expiredToken = true;
+            }
+            const reason = !configured
+                ? 'Daemon has no saved relay credentials — run `beehaven login`.'
+                : expiredToken
+                    ? 'Relay is down: your token is EXPIRED. Run `beehaven login` (a restart will not refresh it).'
+                    : 'Relay is down but your token is VALID — the WebSocket dropped. Run `beehaven restart`.';
+            ipc.sendRpcError(clientId, rid, reason);
+            return;
+        }
+        // Pull out the optional _timeout flag so it doesn't pollute the
+        // forwarded request body. Spread payload first so the envelope
+        // `type: action` always wins — otherwise a payload field named
+        // `type` (e.g. team kind) silently overrides the dispatch key.
+        const { _timeout, ...payload } = (input || {});
+        const timeoutMs = typeof _timeout === 'number' && _timeout > 0 ? _timeout : 60_000;
+        logger.debug('ipc', `RPC forward: action=${action} rid=${rid} timeout=${timeoutMs}ms`);
+        relay
+            .sendRequest({ ...payload, type: action }, timeoutMs)
+            .then((result) => {
+            ipc.sendRpcResult(clientId, rid, result);
+        })
+            .catch((err) => {
+            ipc.sendRpcError(clientId, rid, err.message || 'RPC failed');
+        });
+    });
+    // Local client raw sends → forward to DO via relay
+    ipc.on('send', (msg) => {
+        if (relay.isConnected()) {
+            relay.wsSend(msg);
+        }
+    });
+    // Local client HTTP proxy: make a fetch with the daemon's Firebase ID
+    // token as bearer auth. The token never leaves this process. Used by
+    // beehaven CLI admin commands so they don't need their own credentials.
+    ipc.on('daemon-fetch', async ({ clientId, rid, method, url, body, headers }) => {
+        try {
+            // Allowlist check BEFORE touching the token. A disallowed URL
+            // should never see the Firebase bearer attached — refuse early
+            // so a log leak or downstream parser error can't expose it.
+            const allow = isDaemonFetchUrlAllowed(String(url || ''));
+            if (!allow.ok) {
+                logger.warn('ipc', `daemon-fetch rejected: ${allow.reason} (${method} ${url})`);
+                ipc.sendRpcError(clientId, rid, `daemon-fetch: ${allow.reason}`);
+                return;
+            }
+            // Being ALLOWED and being trusted with the user's credential are
+            // separate questions. Four allowlist entries (*.myshopify.com,
+            // *.firebaseapp.com, *.run.app, *.cloudfunctions.net) are
+            // registrable by third parties, and every one of them used to get
+            // a live Firebase ID token attached — the confused-deputy leak the
+            // *.workers.dev comment in the allowlist warns about. Hosts
+            // outside CREDENTIALED_HOSTS stay fetchable, just uncredentialed.
+            const credentialed = mayReceiveCredentials(String(url || ''));
+            const token = relay.config?.token;
+            if (!token && credentialed) {
+                ipc.sendRpcError(clientId, rid, 'Daemon has no Firebase token — sign in from the Clearly Dev Mac app tray.');
+                return;
+            }
+            // Refresh if expired (mirrors what relay does for its own connection).
+            // Only worth doing when we're actually going to send the token.
+            let liveToken = token;
+            if (credentialed && token) {
+                try {
+                    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());
+                    if (payload.exp && payload.exp * 1000 < Date.now() + 60_000) {
+                        const refreshed = await relay.refreshIdToken?.();
+                        if (refreshed)
+                            liveToken = relay.config?.token || token;
+                    }
+                }
+                catch {
+                    /* ignore parse errors */
+                }
+            }
+            const callerHeaders = { ...(headers || {}) };
+            if (!credentialed) {
+                // A caller must not be able to smuggle the credential back in by
+                // passing its own Authorization header for an untrusted host.
+                for (const k of Object.keys(callerHeaders)) {
+                    if (k.toLowerCase() === 'authorization')
+                        delete callerHeaders[k];
+                }
+                logger.debug('ipc', `daemon-fetch: sending UNCREDENTIALED to ${url}`);
+            }
+            const init = {
+                method,
+                headers: {
+                    ...callerHeaders,
+                    ...(credentialed ? { Authorization: `Bearer ${liveToken}` } : {}),
+                },
+            };
+            if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+                // body comes as a string from the IPC client (already JSON-encoded
+                // by the caller, or raw text for non-JSON content)
+                init.body = typeof body === 'string' ? body : JSON.stringify(body);
+                if (!init.headers['Content-Type'] && typeof body === 'string') {
+                    init.headers['Content-Type'] = 'application/json';
+                }
+            }
+            logger.debug('ipc', `daemon-fetch: ${method} ${url}`);
+            const res = await fetch(url, init);
+            const resBody = await res.text();
+            ipc.sendRpcResult(clientId, rid, {
+                status: res.status,
+                ok: res.ok,
+                headers: Object.fromEntries(res.headers.entries()),
+                body: resBody,
+            });
+        }
+        catch (err) {
+            ipc.sendRpcError(clientId, rid, err?.message || 'daemon-fetch failed');
+        }
+    });
+    // Local client wants the current Firebase ID token (for tools that
+    // need to call third-party services). Use `daemon-fetch` instead when
+    // calling worker routes — it keeps the token inside the daemon.
+    ipc.on('get-token', ({ clientId, rid }) => {
+        try {
+            const token = relay.config?.token;
+            if (!token) {
+                ipc.sendRpcError(clientId, rid, 'Daemon has no Firebase token — sign in from the Clearly Dev Mac app tray.');
+                return;
+            }
+            ipc.sendRpcResult(clientId, rid, { token });
+        }
+        catch (err) {
+            ipc.sendRpcError(clientId, rid, err?.message || 'get-token failed');
+        }
+    });
+    // Local app RPC — route to the local building's WebSocket handler.
+    // This is the fast path: IPC socket → daemon → app workspace (no cloud roundtrip).
+    // Used by `app` CLI for controlling local buildings like AbletonWorkspace.
+    ipc.on('app-rpc', async ({ clientId, rid, action, input, building, instanceId, agent }) => {
+        if (!daemonAppManager || !daemonAppManager.running) {
+            // When an agent identity is present but the local app server isn't
+            // running, the avatar hive is almost certainly gated off because the
+            // daemon is signed out (requiresAuth). Surface that explicitly rather
+            // than a generic "not running" so the CLI can tell the user to sign in.
+            if (agent && !relay.isConfigured()) {
+                ipc.sendRpcError(clientId, rid, 'AGENT_UNAVAILABLE_SIGNED_OUT: the avatar hive is offline because the daemon is signed out. Sign in via the Hive Mac app.');
+                return;
+            }
+            ipc.sendRpcError(clientId, rid, 'Local app not running');
+            return;
+        }
+        // ── Agent identity (optional) ──────────────────────────────────
+        // When the CLI carries a signed AgentIdentity token, verify it
+        // daemon-side and build a CallerContext the building can trust
+        // (same-process boundary). For avatar-directed calls, route to the
+        // agent's OWN avatar instance (instanceId = avatarId) unless the
+        // client explicitly picked an instance — this is what gives N
+        // signed-in agents N distinct on-screen avatars.
+        // Local shape (mirrors core's CallerContext — core is an optional peer
+        // dep loaded via dynamic import, so we don't statically reference its type).
+        let caller;
+        if (agent) {
+            const claims = await verifyAgentToken(agent);
+            if (!claims) {
+                ipc.sendRpcError(clientId, rid, 'AGENT_INVALID: agent identity could not be verified (expired or bad signature). Run `beehaven agent login <name>` to refresh.');
+                return;
+            }
+            caller = {
+                role: 'agent',
+                agentId: claims.agentId,
+                avatarId: claims.avatarId,
+                userId: claims.userId,
+                displayName: claims.displayName,
+                permissions: claims.permissions,
+                voice: claims.meta?.voice,
+            };
+            // Presence follows real, verified work. Reattach a local session after a daemon restart
+            // before touching it; otherwise workspace attribution succeeds while the desktop lease
+            // silently remains asleep because AgentSessions has no in-memory spec.
+            // `agent` is the DEVICE-LOCAL avatar credential. AgentSessions connects to the cloud
+            // workspace and therefore must use the stored WORKER-signed token instead; presenting the
+            // local token to the relay briefly wakes the avatar, then fails authentication and removes
+            // the session again.
+            ensureAgentPresence(caller.agentId);
+            if (building === 'avatar' &&
+                (!instanceId || instanceId === 'live' || instanceId === 'default')) {
+                instanceId = claims.avatarId;
+            }
+        }
+        // ── Cloud routing path ─────────────────────────────────────────
+        // If the target building is declared as cloud-hosted in any
+        // installed app manifest, the daemon doesn't try to instantiate
+        // a local class for it — instead it forwards the RPC over the
+        // existing relay WebSocket using the declared cloudUrl. The cloud
+        // side (Cloudflare Worker + DO router) unpacks the message and
+        // hits the right building instance.
+        //
+        // We broadcast a `cloud-app-rpc:forward` event so the browser
+        // and Claude both see "this is going to the cloud" as part of a
+        // pipeline narrative, and so dashboards can time cloud latency.
+        const cloudRoute = findCloudBuildingRoute(daemonAppManager, building);
+        if (cloudRoute) {
+            ipc.broadcast({
+                type: 'cloud-app-rpc:forward',
+                building,
+                instanceId,
+                action,
+                rid,
+                cloudUrl: cloudRoute.cloudUrl,
+                app: cloudRoute.appName,
+            });
+            try {
+                const result = await forwardCloudAppRpc({
+                    relay,
+                    cloudUrl: cloudRoute.cloudUrl,
+                    app: cloudRoute.appName,
+                    building,
+                    instanceId,
+                    action,
+                    input,
+                    rid,
+                });
+                ipc.broadcast({ type: 'cloud-app-rpc:result', building, action, rid, ok: true });
+                ipc.sendRpcResult(clientId, rid, result);
+            }
+            catch (err) {
+                ipc.broadcast({
+                    type: 'cloud-app-rpc:result',
+                    building,
+                    action,
+                    rid,
+                    ok: false,
+                    error: err?.message,
+                });
+                ipc.sendRpcError(clientId, rid, err?.message || 'Cloud app RPC failed');
+            }
+            return;
+        }
+        // ── Local building path ────────────────────────────────────────
+        const instance = daemonAppManager.getBuilding(building, instanceId);
+        if (!instance) {
+            ipc.sendRpcError(clientId, rid, `Building "${building}/${instanceId}" not found`);
+            return;
+        }
+        const { instance: workspace } = instance;
+        // Prefer direct .call() — simpler, synchronous result, always works.
+        // The virtual WebSocket path is kept as fallback for buildings that
+        // override webSocketMessage but don't expose .call().
+        if (typeof workspace.call === 'function') {
+            // Ensure the building has a broadcast function — some buildings
+            // (e.g. AvatarWorkspace) expect it to be set by the host. Wire
+            // it to the IPC bus so building events reach all connected clients.
+            if (typeof workspace.broadcast !== 'function') {
+                workspace.broadcast = (msg) => {
+                    ipc.broadcast({ ...msg, building });
+                };
+            }
+            try {
+                // Pass the verified CallerContext as the 3rd arg. Buildings that
+                // ignore it (the 2-arg majority) are unaffected; the avatar hive
+                // reads it to attribute the call to a specific agent + avatar.
+                const result = await workspace.call(action, input, caller);
+                ipc.sendRpcResult(clientId, rid, result);
+                // Broadcast post-action event for subscribers
+                ipc.broadcast({
+                    type: `${building}:${action}`,
+                    building,
+                    action,
+                    input,
+                    rid,
+                    /**
+                     * ⚠⚠ IDENTITY IS ATTACHED ONLY WHEN `verifyAgentToken` SUCCEEDED. `caller` is built a few
+                     * hundred lines up and ONLY inside `if (agent)` after the token verifies — an invalid or
+                     * expired token returns `AGENT_INVALID` and never reaches here. So the presence of
+                     * `agentId` on this frame is a claim the daemon has checked, not one the caller asserted.
+                     * Subscribers can and do gate on it (the Mac app reacts on screen), which is why it must
+                     * stay impossible to set from an unverified path.
+                     *
+                     * ⚠ `displayName` IS CARRIED so consumers can ATTRIBUTE rather than print a raw id. It
+                     * comes off the same verified claims as `agentId` — never from the input.
+                     */
+                    ...(caller?.agentId
+                        ? { agentId: caller.agentId, avatarId: caller.avatarId, displayName: caller.displayName }
+                        : {}),
+                });
+            }
+            catch (err) {
+                ipc.sendRpcError(clientId, rid, err.message || 'App RPC failed');
+            }
+            return;
+        }
+        // Fallback: virtual WebSocket dispatch
+        try {
+            const rpcMsg = JSON.stringify({ action, params: input, id: rid });
+            let responded = false;
+            const virtualWs = {
+                readyState: 1,
+                send(data) {
+                    if (responded)
+                        return;
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (parsed.id === rid) {
+                            responded = true;
+                            if (parsed.error) {
+                                ipc.sendRpcError(clientId, rid, parsed.error);
+                            }
+                            else {
+                                ipc.sendRpcResult(clientId, rid, parsed.result);
+                            }
+                        }
+                    }
+                    catch { }
+                },
+                close() { },
+                accept() { },
+                _attachment: { userId: 'ipc' },
+                serializeAttachment(d) {
+                    virtualWs._attachment = d;
+                },
+                deserializeAttachment() {
+                    return virtualWs._attachment;
+                },
+            };
+            if (!workspace._ipcConnected) {
+                workspace._ipcConnected = true;
+                if (typeof workspace.onConnect === 'function') {
+                    await workspace.onConnect('ipc', virtualWs);
+                }
+            }
+            if (typeof workspace.webSocketMessage === 'function') {
+                await workspace.webSocketMessage(virtualWs, rpcMsg);
+            }
+            setTimeout(() => {
+                if (responded) {
+                    ipc.broadcast({
+                        type: `${building}:${action}`,
+                        building,
+                        action,
+                        input,
+                        rid,
+                    });
+                }
+            }, 0);
+            setTimeout(() => {
+                if (!responded) {
+                    ipc.sendRpcError(clientId, rid, 'App RPC timeout');
+                }
+            }, 30000);
+        }
+        catch (err) {
+            ipc.sendRpcError(clientId, rid, err.message || 'App RPC failed');
+        }
+    });
+    // ── Pipeline RPC — sequential chained app-rpcs with variable binding ──
+    //
+    // Lets any client (Claude over IPC, the human UI over its own transport)
+    // submit a single `pipeline` message that fans out into N sequential
+    // app-rpcs against one or more buildings. Each step's result is bound
+    // to `$<id>` and subsequent steps can reference prior outputs via
+    // "$id.path.to.field" strings anywhere inside their input object.
+    //
+    // Every step transition emits a `pipeline:step` broadcast on the IPC
+    // socket so other clients (e.g. an open browser UI) can see the chain
+    // executing in real time — this is what makes "Claude and humans
+    // watching each other" work.
+    ipc.on('pipeline', async ({ clientId, rid, title, steps, defaultBuilding, defaultInstance, }) => {
+        if (!daemonAppManager || !daemonAppManager.running) {
+            ipc.sendRpcError(clientId, rid, 'Local app not running');
+            return;
+        }
+        const bindings = {};
+        // Resolve $id.path references recursively inside a value. Strings of
+        // the form "$id" or "$id.a.b.c" are looked up; objects and arrays are
+        // walked; everything else is returned as-is.
+        const resolveRefs = (value) => {
+            if (typeof value === 'string') {
+                const m = value.match(/^\$([a-zA-Z_][\w]*)((?:\.[\w\-]+)*)$/);
+                if (!m)
+                    return value;
+                const [, key, pathStr] = m;
+                if (!(key in bindings))
+                    throw new Error(`Pipeline reference "$${key}" — no prior step bound that name`);
+                let cur = bindings[key];
+                if (pathStr) {
+                    const parts = pathStr.slice(1).split('.');
+                    for (const p of parts) {
+                        if (cur == null)
+                            throw new Error(`Pipeline reference "$${key}${pathStr}" — null at "${p}"`);
+                        cur = cur[p];
+                    }
+                }
+                return cur;
+            }
+            if (Array.isArray(value))
+                return value.map(resolveRefs);
+            if (value && typeof value === 'object') {
+                const out = {};
+                for (const [k, v] of Object.entries(value))
+                    out[k] = resolveRefs(v);
+                return out;
+            }
+            return value;
+        };
+        // Run a single app-rpc step. Prefers direct .call() when available,
+        // falls back to virtual WebSocket dispatch.
+        const runOneStep = (stepBuilding, stepInstance, action, input, stepRid) => new Promise(async (resolve, reject) => {
+            const instance = daemonAppManager.getBuilding(stepBuilding, stepInstance);
+            if (!instance) {
+                reject(new Error(`Building "${stepBuilding}/${stepInstance}" not found`));
+                return;
+            }
+            const { instance: workspace } = instance;
+            // Direct .call() path — always preferred
+            if (typeof workspace.call === 'function') {
+                try {
+                    resolve(await workspace.call(action, input));
+                }
+                catch (err) {
+                    reject(err);
+                }
+                return;
+            }
+            // Fallback: virtual WebSocket
+            let responded = false;
+            const virtualWs = {
+                readyState: 1,
+                send(data) {
+                    if (responded)
+                        return;
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (parsed.id !== stepRid)
+                            return;
+                        responded = true;
+                        if (parsed.error)
+                            reject(new Error(parsed.error));
+                        else
+                            resolve(parsed.result);
+                    }
+                    catch { }
+                },
+                close() { },
+                accept() { },
+                _attachment: { userId: 'ipc' },
+                serializeAttachment(d) {
+                    virtualWs._attachment = d;
+                },
+                deserializeAttachment() {
+                    return virtualWs._attachment;
+                },
+            };
+            try {
+                if (!workspace._ipcConnected) {
+                    workspace._ipcConnected = true;
+                    if (typeof workspace.onConnect === 'function') {
+                        await workspace.onConnect('ipc', virtualWs);
+                    }
+                }
+                if (typeof workspace.webSocketMessage === 'function') {
+                    await workspace.webSocketMessage(virtualWs, JSON.stringify({ action, params: input, id: stepRid }));
+                }
+                setTimeout(() => {
+                    if (!responded)
+                        reject(new Error(`step "${action}" timeout`));
+                }, 30_000);
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        // Announce pipeline start to all subscribers.
+        ipc.broadcast({ type: 'pipeline:start', rid, title: title ?? null, stepCount: steps.length });
+        const results = [];
+        try {
+            for (let i = 0; i < steps.length; i++) {
+                const step = steps[i];
+                const stepBuilding = step.building || defaultBuilding;
+                const stepInstance = step.instanceId || defaultInstance;
+                const stepId = step.id ?? `step${i}`;
+                const label = step.label ?? `${stepBuilding}.${step.action}`;
+                // Emit "about to run" event so UIs can show the next step ticking.
+                ipc.broadcast({
+                    type: 'pipeline:step',
+                    rid,
+                    index: i,
+                    id: stepId,
+                    label,
+                    action: step.action,
+                    building: stepBuilding,
+                    phase: 'start',
+                });
+                let resolvedInput;
+                try {
+                    resolvedInput = resolveRefs(step.input ?? {});
+                }
+                catch (err) {
+                    ipc.broadcast({
+                        type: 'pipeline:step',
+                        rid,
+                        index: i,
+                        id: stepId,
+                        label,
+                        phase: 'error',
+                        error: err.message,
+                    });
+                    throw err;
+                }
+                let result;
+                try {
+                    result = await runOneStep(stepBuilding, stepInstance, step.action, resolvedInput, `${rid}_step${i}`);
+                }
+                catch (err) {
+                    ipc.broadcast({
+                        type: 'pipeline:step',
+                        rid,
+                        index: i,
+                        id: stepId,
+                        label,
+                        phase: 'error',
+                        error: err?.message ?? String(err),
+                    });
+                    results.push({
+                        id: stepId,
+                        action: step.action,
+                        ok: false,
+                        error: err?.message ?? String(err),
+                    });
+                    throw new Error(`Step ${i} (${label}) failed: ${err?.message ?? err}`);
+                }
+                bindings[stepId] = result;
+                results.push({ id: stepId, action: step.action, ok: true, result });
+                ipc.broadcast({
+                    type: 'pipeline:step',
+                    rid,
+                    index: i,
+                    id: stepId,
+                    label,
+                    phase: 'ok',
+                    result,
+                });
+            }
+            ipc.broadcast({ type: 'pipeline:end', rid, ok: true, stepCount: steps.length });
+            ipc.sendRpcResult(clientId, rid, { ok: true, steps: results, bindings });
+        }
+        catch (err) {
+            ipc.broadcast({ type: 'pipeline:end', rid, ok: false, error: err?.message ?? String(err) });
+            ipc.sendRpcError(clientId, rid, err?.message ?? 'Pipeline failed');
+        }
+    });
+    // ── Session lifecycle → update cloud agent context ──────────────
+    // When clients join/leave sessions, push updated status to the cloud
+    // so Claude knows what apps and buildings are currently connected.
+    const pushSessionStatus = () => {
+        if (!relay.isConnected())
+            return;
+        const sessions = ipc.getSessionInfo();
+        relay.wsSend({
+            type: 'session-status',
+            connectedBuilding,
+            sessions,
+            clientCount: ipc.clientCount,
+        });
+    };
+    /** Sync the installed apps list to the user's cloud workspace.
+     *  Calls app:register for each installed app and sends local-app-status.
+     *  The Home DO persists these in its installedApps table — cross-device. */
+    function syncInstalledAppsToCloud() {
+        if (!relay.isConnected())
+            return;
+        // Register each installed app with the Home DO
+        for (const { manifest: m } of scanInstalledApps()) {
+            if (!isPubliclyVisibleApp(m))
+                continue;
+            relay
+                .sendRequest({
+                type: 'app:register',
+                name: m.name,
+                version: m.version ?? '0.1.0',
+                description: m.description ?? '',
+                buildings: m.buildings ? Object.keys(m.buildings) : [],
+                cloudBuildings: [],
+                actions: {},
+            }, 5_000)
+                .catch(() => { });
+        }
+        // Also push the full local-app-status for the agent catalog
+        if (daemonAppManager) {
+            relay.sendLocalAppStatus(daemonAppManager.status());
+        }
+        // Capabilities may have changed (install/uninstall) — re-advertise this
+        // node's beehive record so the swarm's dispatch matching stays accurate.
+        registerBeehive();
+    }
+    // ── Distributed hive mesh — advertise this daemon as a beehive ──
+    //
+    // The node declares its ROLE (queen orchestrates / worker executes), its
+    // KIND (this Mac / a headless server / a cloud container), and its
+    // CAPABILITIES (the hives it can run — the dispatch match keys). The user's
+    // Mac defaults to QUEEN (the natural orchestrator — where the human is); a
+    // headless/container daemon defaults to WORKER. `beehaven swarm role` (config
+    // `role`) or BEEHAVEN_ROLE overrides. See rpc/swarm-rpcs.ts for the queen
+    // + dispatch side.
+    function beehiveRole() {
+        const env = (process.env.BEEHAVEN_ROLE || '').toLowerCase();
+        if (env === 'queen' || env === 'worker')
+            return env;
+        const cfgRole = String(loadConfig()?.role || '').toLowerCase();
+        if (cfgRole === 'queen' || cfgRole === 'worker')
+            return cfgRole;
+        return process.env.BEEHAVEN_HEADLESS === '1' ? 'worker' : 'queen';
+    }
+    function beehiveKind() {
+        const env = (process.env.BEEHAVEN_KIND || '').toLowerCase();
+        if (env === 'local-mac' || env === 'headless' || env === 'cloud-container')
+            return env;
+        return process.env.BEEHAVEN_HEADLESS === '1' ? 'headless' : 'local-mac';
+    }
+    function beehiveCapabilities() {
+        try {
+            const s = daemonAppManager?.status();
+            const caps = new Set(Array.isArray(s?.buildingTypes) ? s.buildingTypes : []);
+            // Surface app names too so `swarm list` reads friendly (motion-studio,
+            // voice, recorder …) even before a building instance has spun up.
+            for (const a of s?.apps ?? [])
+                if (a?.name)
+                    caps.add(String(a.name));
+            return [...caps];
+        }
+        catch {
+            return [];
+        }
+    }
+    function registerBeehive() {
+        if (!relay.isConnected())
+            return;
+        relay.sendSwarmRegister({
+            role: beehiveRole(),
+            kind: beehiveKind(),
+            capabilities: beehiveCapabilities(),
+        });
+    }
+    /** Sync a single uninstall to the Home DO. */
+    function syncUninstallToCloud(name) {
+        if (!relay.isConnected())
+            return;
+        relay.sendRequest({ type: 'app:uninstall', name }, 5_000).catch(() => { });
+    }
+    // The IPC server broadcasts session:join/leave. We listen here to
+    // relay that info to the cloud agent (separate from the normal
+    // broadcast fan-out to other IPC clients).
+    const origBroadcast = ipc.broadcast.bind(ipc);
+    /**
+     * ⚠⚠ THE WRAPPER MUST RETURN THE COUNT. `ipc.broadcast` now answers how many local clients it
+     * reached, and this decorator swallowed it — so `reached` would have been `undefined` at every
+     * call site, `=== 0` would never be true, and the browser fallback would have been dead code
+     * that looked wired. Caught by the typechecker only because the base method gained a return
+     * type; a JS-shaped patch would have shipped it silently.
+     */
+    ipc.broadcast = (msg) => {
+        const sent = origBroadcast(msg);
+        if (msg?.type === 'session:join' || msg?.type === 'session:leave') {
+            pushSessionStatus();
+        }
+        return sent;
+    };
+    // PTY output → forward to local IPC clients (Electron, etc.)
+    relay.onPtyOutput = (msg) => {
+        ipc.broadcast(msg);
+    };
+    // DO broadcasts → forward to local clients
+    /**
+     * Pull the canonical avatar_settings row from the user's
+     * ClearlyWorkspace workspace and apply it to the local avatar
+     * building. Used on every relay (re)connect so a daemon that
+     * was asleep while the user equipped a new companion on the
+     * web catches up the moment it wakes — rather than waiting
+     * for the next mutation to broadcast.
+     *
+     * Retries up to 3 times on transient failures (relay just
+     * connected, ipc not ready, avatar building still loading).
+     * Silent on terminal failure — the next reconnect will retry
+     * and the existing broadcast handler still covers in-session
+     * updates.
+     */
+    async function syncAvatarFromCloud(retry = 0) {
+        try {
+            if (!relay.isConnected())
+                return;
+            if (!daemonAppManager?.running) {
+                if (retry < 3)
+                    setTimeout(() => syncAvatarFromCloud(retry + 1).catch(() => { }), 1000);
+                return;
+            }
+            const instance = daemonAppManager.getBuilding('avatar', 'default');
+            if (!instance) {
+                if (retry < 3)
+                    setTimeout(() => syncAvatarFromCloud(retry + 1).catch(() => { }), 1000);
+                return;
+            }
+            const settings = await relay.sendRequest({ type: 'avatar:settings-get' }, 8_000);
+            if (!settings || typeof settings !== 'object')
+                return;
+            const patch = {};
+            if (typeof settings.active_skin_id === 'string')
+                patch.activeSkinId = settings.active_skin_id;
+            if (typeof settings.active_champion_id === 'string')
+                patch.activeChampionId = settings.active_champion_id;
+            if (typeof settings.avatar_name === 'string')
+                patch.avatarName = settings.avatar_name;
+            if (typeof settings.body_type === 'string')
+                patch.bodyType = settings.body_type;
+            if (typeof settings.voice_provider === 'string')
+                patch.voiceProvider = settings.voice_provider;
+            if (settings.voice_id == null || typeof settings.voice_id === 'string')
+                patch.voiceId = settings.voice_id;
+            if (typeof settings.click_through_default === 'number')
+                patch.clickThroughDefault = !!settings.click_through_default;
+            if (settings.overlay_position == null || typeof settings.overlay_position === 'string')
+                patch.overlayPosition = settings.overlay_position;
+            if (typeof settings.overlay_size === 'number')
+                patch.overlaySize = settings.overlay_size;
+            await instance.instance.call('applyCloudSettings', patch);
+            // Mirror the broadcast envelope into IPC so any embedded UI
+            // (drawer, etc.) sees a `settings-changed` frame after the
+            // initial sync — same shape it would see for a live delta.
+            ipc.broadcast({ type: 'avatar:settings-changed', settings });
+        }
+        catch (err) {
+            // Transient errors (relay disconnect mid-RPC, etc.) — retry
+            // a couple times then give up; the next onConnected fires
+            // the next attempt.
+            if (retry < 2) {
+                setTimeout(() => syncAvatarFromCloud(retry + 1).catch(() => { }), 2000);
+            }
+            else {
+                console.warn(`[daemon] avatar settings cloud sync failed: ${err?.message ?? err}`);
+            }
+        }
+    }
+    relay.onBroadcast = (msg) => {
+        /**
+         * ⚠⚠ PUT AN AGENT'S COMPOSITION ON SCREEN — THE ONE PLACE THAT ACTUALLY CAN.
+         *
+         * The server's `open` RPC broadcasts `ui:navigate`. Only the WEB client handled it, and
+         * `AgentNavigationListener` bails on `document.visibilityState === 'hidden'` BY DESIGN
+         * ("barging a background app into a new tab is worse"). So with the desktop app in the
+         * background, every tab RECEIVED the message and none acted: measured on staging, `open`
+         * reported `delivered: 4` and nothing appeared on screen. `delivered` counts RECIPIENTS,
+         * not actors — which is exactly what it had been telling us.
+         *
+         * ⚠ THE DAEMON IS THE ONLY PART OF THIS SYSTEM RUNNING ON THE PERSON'S MACHINE. A Cloudflare
+         * worker cannot open a window; a hidden renderer refuses to. So the fallback lives here.
+         *
+         * ⚠ DESKTOP FIRST, BROWSER SECOND, and the ORDER is the requirement. `clearly://composition/<id>`
+         * reaches the app's main process, which can RAISE the window and spawn a tab. Only if that
+         * fails — no app installed, no scheme handler — does it fall back to the https url, which is
+         * a plain browser tab. Opening the browser first would put the work somewhere the person's
+         * desktop app cannot see it.
+         *
+         * ⚠ ONLY WHEN THE UI DID NOT ACT. `ui:navigate` carries no delivery receipt back to the
+         * daemon, so this waits briefly and opens only if nothing claimed it — see `uiNavigateClaimed`
+         * below. Without that, a visible web tab navigating itself would ALSO get a second window
+         * thrown at it from here.
+         */
+        if (msg?.type === 'ui:navigate' && typeof msg.path === 'string') {
+            /**
+             * ⚠⚠ DESKTOP FIRST, BROWSER ONLY IF NOTHING LOCAL IS LISTENING — the order IS the
+             * requirement. The desktop app handles the forwarded frame itself: it can RAISE its window
+             * and spawn a tab, which is precisely what a hidden web renderer refuses to do. Opening a
+             * browser first would put the person's work where their desktop app cannot see it.
+             *
+             * ⚠ `ipc.broadcast` RETURNS A COUNT NOW, and that count is the whole decision. Zero means no
+             * local client at all — that is when, and only when, the daemon opens a browser itself.
+             * Guessing instead would double-open for every desktop user.
+             */
+            const reached = ipc.broadcast({ ...msg, ui: true });
+            // ⚠ An IIFE, because `onBroadcast` is a SYNCHRONOUS handler — the ladder below awaits the
+            // OS opener. Fire-and-forget with a swallowing catch: putting a window on screen is a
+            // courtesy and must never take the daemon's broadcast pump down with it.
+            void (async () => {
+                if (reached === 0) {
+                    /**
+                     * ⚠ THE BROADCAST ALREADY CARRIES AN ABSOLUTE `url` — use it rather than gluing an origin
+                     * onto `path`. Reconstructing means guessing the environment, and a staging workspace
+                     * would open a PRODUCTION page: the same class of mistake as the deep-link handler that
+                     * built `…/voice/home?note=<id>` from a stale string-strip.
+                     */
+                    const url = typeof msg.url === 'string' && /^https?:\/\//.test(msg.url)
+                        ? msg.url
+                        : `${String(msg.origin || 'https://www.clearly.sh').replace(/\/+$/, '')}${msg.path}`;
+                    /**
+                     * ⚠⚠ A THREE-STEP LADDER, AND THE MIDDLE RUNG IS THE ONE THAT WAS MISSING.
+                     *   1. a local client is listening  → it already got the broadcast above (app RUNNING)
+                     *   2. the app is INSTALLED but NOT running → the deep link LAUNCHES it
+                     *   3. no app at all → a browser tab
+                     *
+                     * Without rung 2, "desktop first" only held while the app happened to be running, and an
+                     * installed app that was merely closed sent the person's work to a browser instead — the
+                     * opposite of what they asked for, and invisible because a browser opening looks like
+                     * success.
+                     *
+                     * ⚠ INSTALLED-NESS IS PROBED BY TRYING, NOT BY GUESSING A PATH. `open` exits non-zero when
+                     * no handler is registered for a scheme, so the OS answers the question it owns. Looking
+                     * for `/Applications/Clearly.app` would miss a user-local install, a renamed bundle and
+                     * every non-macOS case.
+                     */
+                    const openWith = (target) => new Promise((resolve) => {
+                        try {
+                            const opener = process.platform === 'darwin' ? 'open'
+                                : process.platform === 'win32' ? 'start' : 'xdg-open';
+                            const child = spawn(opener, [target], { detached: true, stdio: 'ignore' });
+                            child.on('error', () => resolve(false));
+                            child.on('exit', (code) => resolve(code === 0));
+                            child.unref();
+                        }
+                        catch {
+                            resolve(false);
+                        }
+                    });
+                    const kind = String(msg.kind || '');
+                    const id = String(msg.id || '');
+                    // ⚠ Only a kind the app has a deep-link ROUTE for. Sending `clearly://board/<id>` when
+                    // main.ts has no `board` case wakes the app to do nothing, and the browser fallback is
+                    // then never tried because the launch "succeeded".
+                    const deepLinkable = new Set(['composition', 'note', 'project']);
+                    const viaApp = deepLinkable.has(kind) && id
+                        ? await openWith(`clearly://${kind}/${encodeURIComponent(id)}`)
+                        : false;
+                    if (!viaApp)
+                        await openWith(url);
+                }
+            })().catch(() => { });
+            return;
+        }
+        // Handle tool execution requests from cloud agent
+        if (msg?.type === 'tool:execute' && msg.toolName && msg.requestId) {
+            handleToolExecute(msg).catch((err) => {
+                relay.wsSend({ type: 'tool:result', requestId: msg.requestId, error: err.message });
+            });
+            return;
+        }
+        // Handle app:call:forward — cloud workspace routing an RPC to a local building
+        if (msg?.type === 'app:call:forward' && msg.building && msg.action) {
+            (async () => {
+                if (!daemonAppManager?.running) {
+                    relay.wsSend({
+                        type: 'app:call:result',
+                        requestId: msg.requestId,
+                        error: 'Local apps not running',
+                    });
+                    return;
+                }
+                const instance = daemonAppManager.getBuilding(msg.building, 'live');
+                if (!instance) {
+                    relay.wsSend({
+                        type: 'app:call:result',
+                        requestId: msg.requestId,
+                        error: `Building "${msg.building}" not found locally`,
+                    });
+                    return;
+                }
+                try {
+                    const result = await instance.instance.call(msg.action, msg.params ?? {});
+                    relay.wsSend({ type: 'app:call:result', requestId: msg.requestId, ok: true, result });
+                }
+                catch (err) {
+                    relay.wsSend({
+                        type: 'app:call:result',
+                        requestId: msg.requestId,
+                        error: err?.message ?? 'Local app call failed',
+                    });
+                }
+            })().catch(() => { });
+            return;
+        }
+        // ── agent:deps-install — dep framework installer ──
+        // Worker fires this when the user clicks "Install" in the
+        // InstallationsManager UI or when a hive's resources.required
+        // dep needs to be present. Daemon downloads + installs to the
+        // shared root (~/Library/Application Support/Clearly/{bin,models}/)
+        // and reports progress back via the deps-install-progress
+        // bidirectional message channel. See docs/HIVE-DEP-VERIFICATION.md
+        // for the full wire map.
+        if (msg?.type === 'agent:deps-install' && msg.depId && msg.spec) {
+            (async () => {
+                const { depId, spec, daemonSessionId } = msg;
+                const reportProgress = (status, pct, message, error) => {
+                    try {
+                        relay.wsSend({
+                            type: 'deps-install-status',
+                            depId,
+                            daemonSessionId,
+                            status,
+                            progress_pct: pct,
+                            progress_message: message,
+                            error: error ?? '',
+                        });
+                    }
+                    catch {
+                        /* relay may be down */
+                    }
+                };
+                try {
+                    reportProgress('downloading', 0, 'Starting…');
+                    const { installDep } = await import('./dep-installer.js');
+                    const installPath = await installDep(spec, (pct, msg) => {
+                        reportProgress('downloading', pct, msg);
+                    });
+                    reportProgress('installed', 100, 'Installed', undefined);
+                    relay.wsSend({
+                        type: 'deps-install-status',
+                        depId,
+                        daemonSessionId,
+                        status: 'installed',
+                        progress_pct: 100,
+                        progress_message: 'Installed',
+                        install_path: installPath,
+                    });
+                }
+                catch (e) {
+                    console.error(`[daemon] deps-install ${depId} failed:`, e?.message ?? e);
+                    reportProgress('failed', 0, '', String(e?.message ?? e).slice(0, 500));
+                }
+            })().catch(() => { });
+            return;
+        }
+        // ── agent:deps-uninstall — symmetric uninstall ──
+        if (msg?.type === 'agent:deps-uninstall' && msg.depId && msg.spec) {
+            (async () => {
+                const { depId, spec, daemonSessionId } = msg;
+                try {
+                    const { uninstallDep } = await import('./dep-installer.js');
+                    await uninstallDep(spec);
+                    relay.wsSend({
+                        type: 'deps-install-status',
+                        depId,
+                        daemonSessionId,
+                        status: 'not-installed',
+                        progress_pct: 0,
+                        progress_message: 'Uninstalled',
+                    });
+                }
+                catch (e) {
+                    console.error(`[daemon] deps-uninstall ${depId} failed:`, e?.message ?? e);
+                    relay.wsSend({
+                        type: 'deps-install-status',
+                        depId,
+                        daemonSessionId,
+                        status: 'failed',
+                        error: String(e?.message ?? e).slice(0, 500),
+                    });
+                }
+            })().catch(() => { });
+            return;
+        }
+        // ── Hive avatar (mwah) cloud → local sync ──
+        // ClearlyWorkspace is the canonical source for everything the user
+        // *picked* (active skin, accessories, voice, body type, name);
+        // the local AvatarWorkspace is the source for everything the
+        // overlay is *doing right now* (animation phase, speech, timers,
+        // try-on). When ClearlyWorkspace mutates settings it broadcasts
+        // `avatar:settings-changed` with the full row; we mirror that
+        // into the local building's cache so the overlay updates without
+        // the CLI / web wardrobe having to dual-write.
+        if (msg?.type === 'avatar:settings-changed' && msg.settings) {
+            (async () => {
+                if (!daemonAppManager?.running)
+                    return;
+                const instance = daemonAppManager.getBuilding('avatar', 'default');
+                if (!instance)
+                    return;
+                // Translate snake_case cloud row → camelCase local input.
+                const s = msg.settings;
+                const patch = {};
+                if (typeof s.active_skin_id === 'string')
+                    patch.activeSkinId = s.active_skin_id;
+                // active_champion_id is the companion identity (godzilla,
+                // librarian, kumo, …). The local Avatar building uses it
+                // to pick mood baselines, voice persona, and the headshot
+                // surfaced in the tray menu — without it the Mac app
+                // displays Godzilla even after the user equipped Librarian
+                // on the web.
+                if (typeof s.active_champion_id === 'string')
+                    patch.activeChampionId = s.active_champion_id;
+                if (typeof s.avatar_name === 'string')
+                    patch.avatarName = s.avatar_name;
+                if (typeof s.body_type === 'string')
+                    patch.bodyType = s.body_type;
+                if (typeof s.voice_provider === 'string')
+                    patch.voiceProvider = s.voice_provider;
+                if (s.voice_id == null || typeof s.voice_id === 'string')
+                    patch.voiceId = s.voice_id;
+                if (typeof s.click_through_default === 'number')
+                    patch.clickThroughDefault = !!s.click_through_default;
+                // P1 — overlay position + size are renderer-only fields, but
+                // forward them so the building can broadcast a single
+                // 'avatar:settings-changed' IPC frame to any embedded UI
+                // (drawer, etc.) instead of two separate broadcasts.
+                // overlay_position is JSON in the cloud row; we pass it
+                // through unparsed so the building can choose to ignore it.
+                if (s.overlay_position == null || typeof s.overlay_position === 'string')
+                    patch.overlayPosition = s.overlay_position;
+                if (typeof s.overlay_size === 'number')
+                    patch.overlaySize = s.overlay_size;
+                try {
+                    await instance.instance.call('applyCloudSettings', patch);
+                }
+                catch (err) {
+                    // Apply errors are noise — the next delta will retry. Log
+                    // once at warn so a stuck overlay can be diagnosed.
+                    console.warn(`[daemon] avatar applyCloudSettings failed: ${err?.message ?? err}`);
+                }
+            })().catch(() => { });
+            // Also forward to IPC so the drawer / Electron UI can react
+            // (e.g. show "skin updated" toast).
+            ipc.broadcast(msg);
+            return;
+        }
+        // Inventory grant — daemon forwards to IPC (drawer toast etc.);
+        // the actual settings change (auto-equip) flows through the
+        // settings-changed broadcast above.
+        if (msg?.type === 'avatar:inventory-granted') {
+            ipc.broadcast(msg);
+            return;
+        }
+        // Wallet / champion-grant deltas are pure notifications for the
+        // web (no local-building state derives from them) — just forward
+        // to any embedded IPC clients (drawer toast etc.) and stop.
+        if (msg?.type === 'avatar:wallet-changed' || msg?.type === 'avatar:champion-granted') {
+            ipc.broadcast(msg);
+            return;
+        }
+        // Try-on overlay — cloud emits when the user clicks "Try on"
+        // in the shop. Forward to the local Avatar building so the
+        // overlay swaps to the preview skin for the duration, then
+        // reverts. Without this branch the cloud RPC succeeds but the
+        // Mac overlay never changes.
+        if (msg?.type === 'avatar:tryon' && typeof msg.skinId === 'string') {
+            (async () => {
+                if (!daemonAppManager?.running)
+                    return;
+                const instance = daemonAppManager.getBuilding('avatar', 'default');
+                if (!instance)
+                    return;
+                try {
+                    await instance.instance.call('tryOnSkin', {
+                        skinId: msg.skinId,
+                        durationMs: typeof msg.durationMs === 'number' ? msg.durationMs : 60_000,
+                    });
+                }
+                catch (err) {
+                    console.warn(`[daemon] avatar tryOnSkin failed: ${err?.message ?? err}`);
+                }
+            })().catch(() => { });
+            ipc.broadcast(msg);
+            return;
+        }
+        if (msg?.type === 'avatar:tryon-end') {
+            (async () => {
+                if (!daemonAppManager?.running)
+                    return;
+                const instance = daemonAppManager.getBuilding('avatar', 'default');
+                if (!instance)
+                    return;
+                try {
+                    await instance.instance.call('endTryOn', {});
+                }
+                catch { }
+            })().catch(() => { });
+            ipc.broadcast(msg);
+            return;
+        }
+        ipc.broadcast(msg);
+    };
+    // ── Local tool execution (cloud agent → daemon → local project) ──
+    async function handleToolExecute(msg) {
+        // ── Built-in beehaven: tools ─────────────────────────────────
+        if (msg.toolName.startsWith('beehaven:')) {
+            const action = msg.toolName.replace('beehaven:', 'daemon:');
+            // Route through the same IPC RPC handlers defined above
+            try {
+                const result = await new Promise((resolve, reject) => {
+                    const fakeClientId = `tool_${msg.requestId}`;
+                    const fakeRid = msg.requestId;
+                    // Temporarily intercept the RPC result
+                    const origResult = ipc.sendRpcResult.bind(ipc);
+                    const origError = ipc.sendRpcError.bind(ipc);
+                    let handled = false;
+                    ipc.sendRpcResult = (cid, rid, result) => {
+                        if (cid === fakeClientId && rid === fakeRid) {
+                            handled = true;
+                            ipc.sendRpcResult = origResult;
+                            ipc.sendRpcError = origError;
+                            resolve(result);
+                        }
+                        else {
+                            origResult(cid, rid, result);
+                        }
+                    };
+                    ipc.sendRpcError = (cid, rid, error) => {
+                        if (cid === fakeClientId && rid === fakeRid) {
+                            handled = true;
+                            ipc.sendRpcResult = origResult;
+                            ipc.sendRpcError = origError;
+                            reject(new Error(error));
+                        }
+                        else {
+                            origError(cid, rid, error);
+                        }
+                    };
+                    // Fire the RPC handler
+                    ipc.emit('rpc', { clientId: fakeClientId, rid: fakeRid, action, input: msg.input || {} });
+                    // Safety timeout
+                    setTimeout(() => {
+                        if (!handled) {
+                            ipc.sendRpcResult = origResult;
+                            ipc.sendRpcError = origError;
+                            reject(new Error('Tool timeout'));
+                        }
+                    }, 60_000);
+                });
+                relay.wsSend({ type: 'tool:result', requestId: msg.requestId, result });
+            }
+            catch (err) {
+                relay.wsSend({ type: 'tool:result', requestId: msg.requestId, error: err.message });
+            }
+            return;
+        }
+        const { loadManifest, getManifestTools, executeCommandTool, executeEndpointTool } = await import('./manifest.js');
+        const linked = getLinkedFolders();
+        // Find the tool across all linked projects
+        for (const [projectDir, entry] of Object.entries(linked)) {
+            const manifest = loadManifest(projectDir);
+            if (!manifest?.tools)
+                continue;
+            // Tools are namespaced: "projectName:toolName"
+            const prefix = `${manifest.name}:`;
+            const toolName = msg.toolName.startsWith(prefix)
+                ? msg.toolName.slice(prefix.length)
+                : msg.toolName;
+            const tool = manifest.tools.find((t) => t.name === toolName);
+            if (!tool)
+                continue;
+            logger.info('daemon', `Executing local tool: ${msg.toolName} from ${projectDir}`);
+            try {
+                let result;
+                if (tool.command) {
+                    const { result: stdout, exitCode } = await executeCommandTool({ ...tool, projectDir }, msg.input || {});
+                    result = { stdout, exitCode };
+                }
+                else if (tool.endpoint || manifest.endpoint) {
+                    const { result: body, status } = await executeEndpointTool(tool, msg.input || {}, manifest.endpoint);
+                    result = { body, status };
+                }
+                else {
+                    result = { error: `Tool ${toolName} has no command or endpoint` };
+                }
+                relay.wsSend({ type: 'tool:result', requestId: msg.requestId, result });
+            }
+            catch (err) {
+                relay.wsSend({ type: 'tool:result', requestId: msg.requestId, error: err.message });
+            }
+            return;
+        }
+        relay.wsSend({
+            type: 'tool:result',
+            requestId: msg.requestId,
+            error: `Tool not found: ${msg.toolName}`,
+        });
+    }
+    // Register local tools with cloud DO on connect
+    relay.ws?.addEventListener?.('open', () => registerLocalTools());
+    async function registerLocalTools() {
+        const { loadManifest, toolToSchema } = await import('./manifest.js');
+        const linked = getLinkedFolders();
+        const tools = [];
+        for (const [projectDir] of Object.entries(linked)) {
+            const manifest = loadManifest(projectDir);
+            if (!manifest?.tools)
+                continue;
+            for (const tool of manifest.tools) {
+                tools.push(toolToSchema(tool, manifest.name));
+            }
+        }
+        // Built-in app management tools — always available regardless of linked projects
+        tools.push({
+            name: 'beehaven:app-list',
+            description: 'List installed Beehaven apps with their buildings and versions',
+            inputSchema: { type: 'object', properties: {} },
+        }, {
+            name: 'beehaven:app-install',
+            description: 'Install a Beehaven app from a local path or URL (.hive archive)',
+            inputSchema: {
+                type: 'object',
+                properties: { source: { type: 'string', description: 'Path or URL to .hive archive' } },
+                required: ['source'],
+            },
+        }, {
+            name: 'beehaven:app-uninstall',
+            description: 'Uninstall a Beehaven app by name',
+            inputSchema: {
+                type: 'object',
+                properties: { name: { type: 'string', description: 'App name (e.g. "avatar")' } },
+                required: ['name'],
+            },
+        }, {
+            name: 'beehaven:app-status',
+            description: 'Get daemon session status — connected building, active sessions, running apps',
+            inputSchema: { type: 'object', properties: {} },
+        });
+        if (tools.length > 0) {
+            relay.wsSend({ type: 'register-local-tools', tools });
+            logger.info('daemon', `Registered ${tools.length} local tool(s) with cloud DO`);
+        }
+        // Index documentation from linked projects
+        indexLinkedDocs();
+    }
+    async function indexLinkedDocs() {
+        try {
+            const { DocIndexer } = await import('./doc-indexer.js');
+            const { loadManifest } = await import('./manifest.js');
+            const linked = getLinkedFolders();
+            for (const [projectDir, entry] of Object.entries(linked)) {
+                const manifest = loadManifest(projectDir);
+                const docPaths = manifest?.docs ?? ['docs', 'README.md', 'CLAUDE.md'];
+                const indexer = new DocIndexer({
+                    projectDir,
+                    projectName: entry.brandId ?? manifest?.name ?? 'project',
+                    docPaths,
+                    callAction: async (action, input) => {
+                        if (!relay.isConnected())
+                            return;
+                        try {
+                            await relay.sendRequest({ ...input, type: action });
+                        }
+                        catch {
+                            /* silently skip if disconnected */
+                        }
+                    },
+                });
+                const count = await indexer.index();
+                if (count > 0) {
+                    logger.info('daemon', `Indexed ${count} doc(s) from ${projectDir}`);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn('daemon', `DocIndexer: ${err.message}`);
+        }
+    }
+    // ── Subsystem registries the shutdown handler drains ────────────────
+    //
+    // DECLARED HERE, NOT AT THEIR USE SITE, and that placement is the whole point.
+    //
+    // These used to be `const`s ~400 lines further down, while the SIGTERM/SIGINT handlers
+    // below closed over them. A signal arriving before execution reached those declarations hit
+    // the temporal dead zone: `ReferenceError: Cannot access 'clearlySyncs' before
+    // initialization`, thrown INSIDE the shutdown handler, so `origShutdown` never ran and the
+    // IPC socket was never unlinked. The daemon then died leaving `/tmp/beehaven-ipc.sock`
+    // behind, which put every later command into the loop where `beehaven <anything>` says
+    // "Cannot connect to daemon" and `beehaven start --headless` says "already running".
+    //
+    // The window looks narrow, but it is exactly when the signal arrives in practice: opening
+    // the Mac app SIGTERMs any foreign daemon the moment it launches (daemon-manager's
+    // "replace a foreign daemon" path), and a daemon that has just been spawned is still in
+    // relay-connect/token-refresh — i.e. still above the old declaration site. Reproduced on
+    // every single Mac-app launch while verifying the review dock.
+    const clearlySyncs = [];
+    const folderWatchers = [];
+    // Clean up IPC + subsystems on shutdown
+    const origShutdown = shutdown;
+    const shutdownWithCleanup = async (signal) => {
+        try {
+            ipc.stop();
+        }
+        catch { }
+        try {
+            transcriptTailer.stopAll();
+        }
+        catch { }
+        for (const sync of clearlySyncs) {
+            try {
+                sync.stop();
+            }
+            catch { }
+        }
+        for (const fw of folderWatchers) {
+            try {
+                fw.stop();
+            }
+            catch { }
+        }
+        origShutdown(signal);
+    };
+    process.removeAllListeners('SIGINT');
+    process.removeAllListeners('SIGTERM');
+    process.on('SIGINT', () => shutdownWithCleanup('SIGINT'));
+    process.on('SIGTERM', () => shutdownWithCleanup('SIGTERM'));
+    // ── Local App (hybrid node) ────────────────────────────────────────
+    // `isAuthenticated` is checked by loadInstalledApps when an app's
+    // manifest has `requiresAuth: true` (currently just the avatar
+    // hive). When the daemon is signed out the avatar hive is skipped
+    // entirely — no buildings, no IPC routes, no overlay window.
+    // After sign-out the tray restarts the daemon, which re-enters
+    // this code path with isConfigured() === false and the avatar
+    // disappears cleanly. Sign-in flips it back via the same restart.
+    const appManager = new LocalAppManager({
+        dataDir: join(CONFIG_DIR, 'apps'),
+        port: config.localAppPort ?? 9876,
+        host: '127.0.0.1',
+        // AGENT_IDENTITY_SECRET is injected so buildings CAN verify agent
+        // tokens independently if they want to; the daemon also verifies
+        // them itself on the app-rpc path and passes a CallerContext. The
+        // resolve() call also generates+persists the secret at boot so the
+        // local agent-identity flow works out of the box.
+        // `broadcast` is how a building PUSHES to its UI. LocalHive constructs
+        // buildings with the Durable Object signature — `new BuildingClass(state,
+        // env)` — so a building written to take a `{ broadcast }` options bag gets
+        // a LocalState in that slot and silently falls back to a no-op. The avatar
+        // hive did exactly that: every action worked, chat history recorded, and
+        // not one frame ever reached the overlay window. Putting the emitter on
+        // `env` puts it in the argument the host actually passes.
+        env: {
+            DAEMON: true,
+            AGENT_IDENTITY_SECRET: resolveAgentIdentitySecret(),
+            broadcast: (msg) => ipc.broadcast(msg),
+            /**
+             * How a hive reaches its WORKSPACE — the same bridge `daemon-mcp-clearly`
+             * uses, handed to buildings directly.
+             *
+             * A hive that needs a metered operation (transcription, generation) must
+             * NOT hold a provider key and call out itself: that bills the provider to
+             * the user, so the workspace AI pool never sees it and the operation
+             * earns nothing. Routing through the worker puts the key in a wrangler
+             * secret and the spend on the credit ladder, where it belongs.
+             *
+             * Generous timeout because these are agent operations — a transcription
+             * or a render, not a status ping — and the relay's 10s default would fail
+             * exactly the interesting ones.
+             */
+            callWorkspace: (action, args = {}) => relay.sendRequest({ ...args, type: action }, 120_000),
+        },
+        isAuthenticated: () => relay.isConfigured(),
+    });
+    daemonAppManager = appManager;
+    // ── Mount the beehaven surface as FIRST-PARTY TOOLS for daemon claude ──
+    //
+    // Both halves of the bridge only exist here: `relay` owns the socket to the
+    // worker, `appManager` owns the local buildings. daemon-omni owns the
+    // session. So daemon.ts does the wiring and neither module learns about the
+    // other — the same split `setTierResolver` uses.
+    //
+    // What this changes for the agent: `canvas_add_text` stops being
+    // "shell out to `beehaven call`, hope the JSON survives quoting" and becomes
+    // a typed tool with a Zod-checked signature, called in-process, that the
+    // permission gate can name. The 28 tools were written for exactly this and
+    // had never once been mounted.
+    /**
+     * EVERY TOOL CALL THE DAEMON'S OWN CLAUDE MAKES, ATTRIBUTED — see the note on `setClearlyTools`.
+     *
+     * ⚠ ONE HELPER, TWO SERVERS. `clearly` and `principal` are separate MCP servers with separate
+     * tool prefixes and separate tier rules, and they are the same CALLER. Two copies of this closure
+     * is two chances for one of them to drift back to a raw dispatch — which is exactly what the
+     * first version of this fix did, wrapping one and leaving the other.
+     */
+    const attributedRpc = (action, args) => {
+        const who = daemonToolIdentity();
+        if (!who) {
+            return Promise.reject(new Error('No agent identity for this install, so the call would run as the account owner, '
+                + 'ungated and unattributed. Run: beehaven agent login <name>'));
+        }
+        ensureAgentPresence(who.agentId);
+        return relay.sendRequest({
+            type: 'agent-invoke',
+            agentId: who.agentId,
+            action,
+            input: args ?? {},
+            ...(who.sessionId ? { sessionId: who.sessionId } : {}),
+        }, 120_000);
+    };
+    try {
+        const { setClearlyTools } = await import('./daemon-omni.js');
+        const { driveAvatarAsMonet } = await import('./daemon-avatar.js');
+        setClearlyTools({
+            // Worker RPCs. The generous timeout is deliberate: these are agent
+            // actions (generate, render, perceive), not status pings, and the
+            // relay's 10s default would fail the interesting ones.
+            /**
+             * ⚠⚠ WRAPPED IN `agent-invoke`. WITHOUT THIS THE DAEMON'S CLAUDE WAS THE LEAST ACCOUNTABLE
+             * CALLER IN THE SYSTEM (2026-08-29).
+             *
+             * This was a raw `relay.sendRequest({ ...args, type: action })`. It works, and it bypasses
+             * everything agent identity exists for: no `permission_scope` / `tool_allowlist` gate, no
+             * `agent_activity` row, no attribution. Measured before the change — `beehaven omni` asked
+             * daemon Claude to list compositions, it called `mcp__clearly__canvas_list_compositions`, and
+             * the activity table gained NOTHING. The identical action typed as `beehaven call` is
+             * attributed, gated and logged, because the CLI has routed through `agent-invoke` since
+             * 2026-08-28.
+             *
+             * So one Claude had two doors into one workspace with different privilege on each, and the
+             * more convenient door was the ungoverned one. The desktop overlay's agent-activity
+             * notifications read that same table, so daemon Claude's own work was invisible to them too —
+             * which reads as the notifications being broken rather than as the caller being anonymous.
+             *
+             * ⚠ THE IDENTITY IS THE ONE ITS CLI SPAWNS ALREADY USE — the desktop binding. An agent whose
+             * MCP calls and shell calls file under different names is worse than one that is not
+             * attributed at all, because the log then asserts something false.
+             *
+             * ⚠⚠ NO IDENTITY IS A REFUSAL, NEVER A FALL-THROUGH TO THE RAW DISPATCH. Falling back is
+             * exactly the pattern deleted from `beehaven call`, where an expired token silently
+             * ESCALATED to the account owner. `daemonToolIdentity` holds the expiry check so this site
+             * has one decision to make, and the message names the fix.
+             */
+            invokeRpc: attributedRpc,
+            // The daemon's OWN avatar, driven locally as Monet — not a relay
+            // round-trip to the cloud and back to this same machine.
+            driveAvatar: (action, args) => driveAvatarAsMonet(daemonAppManager, action, args),
+            log: (level, msg, meta) => {
+                if (level === 'error')
+                    console.warn(`  [omni-tools] ${msg}`, meta ?? '');
+            },
+        });
+        console.log('  [omni] beehaven tools mounted for daemon claude');
+        /**
+         * ── Omni's OWN surface: the principal ──
+         *
+         * These are the tools that make daemon claude OMNI rather than a generic
+         * Claude Code session — reply, ask, propose, the board, design docs, the
+         * windows on someone's screen. They lived in the Mac app and were handed to
+         * a SECOND `query()` that Electron spawned, which is what put two `claude`
+         * processes on one machine and one BYOK login.
+         *
+         * ⚠ Mounted here, beside `setClearlyTools`, for the same reason: the context
+         * they need (the relay, the session id, the emit channel) exists only in this
+         * closure. `mountPrincipalTools` takes all three at once so the sessionId on
+         * an emitted event and on a blocking question cannot disagree.
+         */
+        const { mountPrincipalTools, setOmniIdentity, hasWindowSurface, activeTurnSessionId } = await import('./daemon-omni.js');
+        // Who Omni IS, registered once so every entry point — the Mac app, the
+        // avatar panel, `beehaven agent` — gets the same agent rather than an
+        // anonymous Claude Code session holding Omni's tools.
+        const { OMNI_IDENTITY } = await import('./daemon-omni-identity.js');
+        setOmniIdentity(OMNI_IDENTITY);
+        mountPrincipalTools({
+            /**
+             * ⚠⚠ THE SAME WRAPPER, AND THIS SERVER NEEDED IT MORE. `mcp__principal__*` dispatches
+             * `document-create`, `document-append`, `ticket-create`, `ticket-update`, `work-status` and
+             * `agent-memory-remember` — every one a workspace WRITE, and the last of those is incoherent
+             * without an agent, since a memory belongs to one by definition.
+             *
+             * ⚠ IT WAS MISSED ON THE FIRST PASS and a guard caught it, which is the argument for pinning
+             * the SHAPE of the old dispatch rather than the one call site that had it.
+             *
+             * ⚠ `reply_to_principal` IS UNAFFECTED AND MUST STAY SO. It emits rather than dispatching, so
+             * it never reaches this. That matters: it is the ONLY channel to the user, and a gate that
+             * could deny it produces an agent that does its work and then cannot say anything.
+             */
+            invokeRpc: attributedRpc,
+            // One session per daemon today. When Omni becomes multi-session this must
+            // become the id of the session the tool call arrived on, not a constant.
+            // ⚠ The session the CURRENT TURN belongs to, not a constant. A hardcoded
+            // id broadcasts every reply under a session nobody is subscribed to — the
+            // tool succeeds and the user sees silence.
+            sessionId: activeTurnSessionId,
+            // Floating windows are the ONE capability a terminal user does not get.
+            // Declared by the surface (`omni:surface`), never inferred.
+            canOpenWindows: hasWindowSurface,
+        });
+        console.log('  [omni] principal tools mounted (reply · ask · board · design)');
+    }
+    catch (err) {
+        // Non-fatal by design: without this the session is plain Claude Code,
+        // which still works. Failing the daemon over a tool surface would be a
+        // worse outcome than a session with fewer tools.
+        console.warn(`  [omni] beehaven tool mount failed: ${err?.message ?? err}`);
+    }
+    appManager.on('started', ({ port, buildings }) => {
+        console.log(`  [app] Local app listening on ws://127.0.0.1:${port} — buildings: ${buildings.join(', ')}`);
+        // Announce to cloud (include session info so Claude sees the full picture)
+        const status = appManager.status();
+        status.sessions = ipc.getSessionInfo();
+        status.connectedBuilding = connectedBuilding;
+        relay.sendLocalAppStatus(status);
+    });
+    appManager.on('building-registered', (name) => {
+        console.log(`  [app] Registered building: ${name}`);
+    });
+    appManager.on('error', (err) => {
+        console.warn(`  [app] ${err.message}`);
+    });
+    appManager.on('info', (msg) => {
+        console.log(`  [app] ${msg}`);
+    });
+    // Route cloud requests to local buildings via relay
+    relay.onLocalAppFetch = async (type, id, url, method, headers, body) => {
+        if (!appManager.running || !appManager.hasBuilding(type)) {
+            return { status: 404, body: `Building "${type}" not found locally` };
+        }
+        const request = new Request(url, {
+            method,
+            headers,
+            body: method !== 'GET' ? body : undefined,
+        });
+        const response = await appManager.routeFetch(type, id, request);
+        const responseBody = await response.text();
+        const responseHeaders = {};
+        response.headers.forEach((v, k) => {
+            responseHeaders[k] = v;
+        });
+        return { status: response.status, headers: responseHeaders, body: responseBody };
+    };
+    // #74 — cross-hive RPC from the cloud Workspace. The cloud emits
+    // daemon-rpc-request, we look up the hive's default building,
+    // invoke building.call(action, input), and the relay forwards the
+    // resolved value back as daemon-rpc-response. Used for clipImport,
+    // brandSync, projectCreate, clipSearch, clipFetch — i.e. every
+    // workspace `_daemonRpc(...)` call site.
+    relay.onDaemonRpcRequest = async (hive, action, input) => {
+        const startedAt = Date.now();
+        if (!appManager.running) {
+            const err = `appManager not running — hive "${hive}" cannot be reached`;
+            console.log(`[daemon-rpc] FAIL ${hive}:${action} — ${err}`);
+            throw new Error(err);
+        }
+        if (!appManager.hasBuilding(hive)) {
+            const err = `Building "${hive}" not loaded — is the hive installed?`;
+            console.log(`[daemon-rpc] FAIL ${hive}:${action} — ${err}`);
+            throw new Error(err);
+        }
+        // Look up the default instance ("default") and call its action.
+        // Mirrors the IPC RPC path at daemon.ts:2015. Hives without an
+        // exposed `.call()` are rejected — fetch-style routing would
+        // require us to invent a URL + parse JSON bodies, defeating the
+        // point of having a typed RPC bridge.
+        const instance = appManager.getBuilding(hive, 'default');
+        if (!instance) {
+            const err = `Building "${hive}/default" not found`;
+            console.log(`[daemon-rpc] FAIL ${hive}:${action} — ${err}`);
+            throw new Error(err);
+        }
+        const { instance: workspace } = instance;
+        if (typeof workspace.call !== 'function') {
+            const err = `Hive "${hive}" does not expose .call() — only fetch-style routing supported`;
+            console.log(`[daemon-rpc] FAIL ${hive}:${action} — ${err}`);
+            throw new Error(err);
+        }
+        // Wire a broadcast function so hive events reach IPC subscribers
+        // (and AgentActivityBadge via the relay) even on this code path.
+        if (typeof workspace.broadcast !== 'function') {
+            workspace.broadcast = (msg) => {
+                ipc.broadcast({ ...msg, building: hive });
+            };
+        }
+        console.log(`[daemon-rpc] → ${hive}:${action}`);
+        try {
+            const result = await workspace.call(action, input);
+            const elapsed = Date.now() - startedAt;
+            console.log(`[daemon-rpc] ← ${hive}:${action} OK ${elapsed}ms`);
+            return result;
+        }
+        catch (err) {
+            const elapsed = Date.now() - startedAt;
+            console.log(`[daemon-rpc] ← ${hive}:${action} ERR ${elapsed}ms: ${String(err?.message ?? err).slice(0, 200)}`);
+            throw err;
+        }
+    };
+    /**
+     * ⚠⚠ THE FIRST-PARTY HIVE BOOTSTRAP IS GONE (2026-08-28) — `scanInstalledApps` reads them from
+     * the bundle IN PLACE instead. See `FIRST_PARTY_HIVES` there for the list and the reasoning.
+     *
+     * What used to be here was `ensureFirstPartyHives(['avatar','vector','image'], …)`, which
+     * `cpSync`s each hive's WHOLE project directory — `src/`, `scripts/`, `docs/`, `tsconfig.json`,
+     * `package.json`, and for the avatar a `ui/` the product then rendered from — into
+     * `~/.beehaven/apps`. That is how first-party SOURCE came to live outside version control, in a
+     * directory this same call would later overwrite with `force: true`. `~/.beehaven` holds runtime
+     * state now: config, credentials, logs.
+     *
+     * The avatar building remains available through the same in-place bundle loader, so
+     * `beehaven connect avatar` works on a fresh Mac install without a manual hive install.
+     *
+     * ⚠ `ensureFirstPartyHives` IS NOT DELETED. Third-party `.hive` installs still go through the
+     * same install path, and the function is the reference for that shape. It simply has no caller
+     * here any more.
+     */
+    // Load buildings from linked project + installed .hive packages.
+    // Either source can contribute to the same local app server; we start the
+    // app server after both have had a chance to register buildings.
+    (async () => {
+        let total = 0;
+        if (config.linkedProject) {
+            try {
+                const loaded = await appManager.loadFromProject(config.linkedProject);
+                total += loaded.length;
+            }
+            catch {
+                /* logged via appManager error event */
+            }
+        }
+        try {
+            // First-party hives live in the read-only Mac bundle and are not copied
+            // into ~/.beehaven/apps. Load them explicitly or the catalog can mention
+            // avatar while the local app server has no avatar building.
+            const bundled = await appManager.loadInstalledApps(bundledFirstPartyRoots());
+            const installed = await appManager.loadInstalledApps();
+            const allInstalled = [...bundled, ...installed];
+            total += allInstalled.reduce((n, h) => n + h.buildings.length, 0);
+            for (const h of allInstalled) {
+                console.log(`  [app] Installed: ${h.name}@${h.version}${h.frontendDir ? '  (frontend)' : ''}`);
+            }
+            // Hand the dashboard the frontend registry so it can serve
+            // /apps/<name>/ static routes. Frontends-only apps (no
+            // buildings) still get mounted via this path. The dashboard
+            // serves from the app ROOT so a UI can fetch its own shipped
+            // recipes and assets with stable /apps/<name>/... paths.
+            if (dashboard) {
+                dashboard.setAppFrontends(allInstalled.map((h) => ({
+                    name: h.name,
+                    appRoot: h.appDir,
+                    manifest: h.manifest,
+                })));
+                // Bridge the dashboard's /apps/ws WebSocket to the IPC bus
+                // 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),
+                    injectMessage: (id, msg) => ipc.injectMessage(id, msg),
+                    releaseVirtualClient: (id) => ipc.releaseVirtualClient(id),
+                });
+                // Marketplace provider — reads installed apps from the
+                // app manager and fetches available apps from clearly.sh.
+                dashboard.setMarketplaceCatalogProvider(async () => {
+                    const liveCatalog = appManager.getAgentCatalog();
+                    const installedNames = new Set(liveCatalog.map((h) => h.name));
+                    const catalog = await getAvailableApps();
+                    const available = catalog
+                        .filter((h) => isPubliclyVisibleApp(h))
+                        .filter((h) => !installedNames.has(h.name));
+                    return { installed: liveCatalog, available };
+                });
+            }
+        }
+        catch (err) {
+            console.warn(`  [app] failed to load installed apps: ${err?.message ?? err}`);
+        }
+        if (total > 0) {
+            appManager.start().catch(() => { });
+        }
+    })();
+    // ── 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 ?? '',
+    });
+    dashboard
+        .start()
+        .then(() => {
+        console.log(`  [dashboard] Beehaven Dashboard at ${dashboard.url}`);
+    })
+        .catch((err) => {
+        console.warn(`  [dashboard] Failed to start: ${err.message}`);
+    });
+    // Forward daemon events to dashboard
+    watcher.on('event', (event) => {
+        dashboard.pushEvent({
+            type: event.hook_event_name || event.type || 'unknown',
+            timestamp: event.timestamp || Date.now(),
+            data: {
+                tool: event.tool_name,
+                session: event.session_id,
+                project: event.cwd?.split('/').pop(),
+            },
+        });
+    });
+    // Forward telemetry snapshots to dashboard as metrics
+    const pushDashboardMetrics = () => {
+        if (dashboard?.running) {
+            dashboard.pushMetrics(metrics.snapshot());
+        }
+    };
+    setInterval(pushDashboardMetrics, 5_000);
+    // Write a small status file the Mac app's tray can read to compute
+    // service-level health (beyond the "process is alive" PID check). We
+    // mirror relay connectivity + pending RPC count + last error here.
+    // The tray polls this file on every menu rebuild; we refresh on a
+    // 2s tick plus on every relay state transition (below in connectWs/close).
+    const STATUS_FILE = join(CONFIG_DIR, 'status.json');
+    const { STATUS_SCHEMA_VERSION, validateStatusSnapshot } = await import('./shared/status/schema.js');
+    const writeStatusFile = () => {
+        try {
+            const snapshot = {
+                schemaVersion: STATUS_SCHEMA_VERSION,
+                pid: process.pid,
+                updatedAt: Date.now(),
+                relayConnected: relay.isConnected(),
+                relayConfigured: relay.isConfigured(),
+                relayEndpoint: relay.config?.endpoint ?? null,
+                pendingRequests: relay.pendingRequests?.size ?? 0,
+                reconnectAttempts: relay.reconnectAttempts ?? 0,
+                version: currentVersion,
+            };
+            // Self-validation: if any field drifts (wrong type from an
+            // internal getter, missing version, etc.) we'd rather surface a
+            // warning than write a snapshot the tray will reject. Cheap —
+            // the validator is ~80 lines of if-checks, runs in microseconds.
+            const v = validateStatusSnapshot(snapshot);
+            if (!v.ok) {
+                logger.warn('daemon', `status.json snapshot failed self-validation: ${v.errors.join(', ')}`);
+                return;
+            }
+            writeFileSync(STATUS_FILE, JSON.stringify(v.value, null, 2), { mode: 0o600 });
+        }
+        catch {
+            /* non-critical */
+        }
+    };
+    setInterval(writeStatusFile, 2_000);
+    writeStatusFile();
+    // Start watcher + relay + health watchdog
+    watcher.start();
+    health.startWatchdog();
+    // Pull avatar settings from the cloud on every relay (re)connect.
+    // Without this, a daemon that started while offline (or that
+    // missed a settings-changed broadcast during sleep) keeps the
+    // hardcoded godzilla-default until the user mutates settings
+    // again — which surfaces as "web shows librarian, Mac shows
+    // godzilla". The handler is idempotent: applyCloudSettings is a
+    // no-op when the patch matches current state.
+    relay.onConnected = () => {
+        // Rehydrate identities that were still logged in when this daemon was replaced. The local
+        // projection is intentionally cleared in AgentSessions' constructor, but the stored agent
+        // record is the durable intent; without this bridge a normal app/daemon restart looks exactly
+        // like two agents logging out and the desktop removes both avatars.
+        setTimeout(() => {
+            try {
+                void agentSessions.restorePersistedSessions(listAgents().map(({ record }) => record));
+            }
+            catch {
+                /* best-effort; the relay reconnect loop remains healthy */
+            }
+        }, 350);
+        // Defer one tick — the open handler still has heartbeat work
+        // queued, and the avatar building may not be loaded yet on
+        // first connect (loadInstalledApps fires in parallel). The
+        // sync retries internally if the building isn't ready.
+        setTimeout(() => {
+            syncAvatarFromCloud().catch(() => { });
+        }, 250);
+        // Register as a beehive the moment the WS opens so the node appears in
+        // the swarm immediately; syncInstalledAppsToCloud + the periodic tick
+        // below re-register with the full capability list once hives finish
+        // loading. Deferred slightly so the capability scan sees loaded hives.
+        setTimeout(() => {
+            try {
+                registerBeehive();
+            }
+            catch {
+                /* best-effort */
+            }
+        }, 500);
+        // #111 — if startup rehydrated a Claude credential from keychain,
+        // tell the worker now that the WS is open. Worker handler at
+        // `case 'canvas-credential-rehydrated':` refreshes daemon_confirmed_at
+        // on the existing claude_credentials row + broadcasts
+        // claude:credential-changed so the web Send button unhides
+        // immediately. Without this, the UI waits up to 8s for the next
+        // claude-credential-status poll after a daemon restart.
+        if (rehydratedCredential) {
+            try {
+                relay.wsSend({
+                    type: 'canvas-credential-rehydrated',
+                    credType: rehydratedCredential.credType,
+                    maskedKey: rehydratedCredential.maskedKey,
+                });
+                logger.debug('daemon', `Sent canvas-credential-rehydrated to worker (${rehydratedCredential.credType})`);
+            }
+            catch (err) {
+                logger.warn('daemon', `canvas-credential-rehydrated send failed: ${err?.message ?? err}`);
+            }
+        }
+    };
+    await relay.start();
+    // Handle expired token — retry login interactively unless headless (Electron)
+    if (relay.isConfigured() && !relay.isConnected() && !process.env.BEEHAVEN_NO_REPL) {
+        console.log('  Session expired. Please log in again.');
+        const { login } = await import('./setup-relay.js');
+        const loggedIn = await login();
+        if (!loggedIn) {
+            process.exit(1);
+        }
+        const fresh = Relay.loadConfig();
+        if (fresh) {
+            relay.configure(fresh.token, fresh.endpoint);
+            await relay.start();
+        }
+    }
+    else if (relay.isConfigured() && !relay.isConnected()) {
+        // Only self-refresh if the token is ACTUALLY expired. A valid token that merely hasn't
+        // registered a connection yet (the initial `relay.start()` is async) just needs the
+        // reconnect loop — NOT a blocking `refreshIdToken()`, whose keychain `execSync` write
+        // hangs in a headless/no-GUI context (the "stuck at attempting self-refresh" symptom).
+        let tokenExpired = true;
+        try {
+            const cfg = Relay.loadConfig();
+            if (cfg?.token) {
+                const payload = JSON.parse(Buffer.from(cfg.token.split('.')[1], 'base64').toString());
+                tokenExpired = !payload.exp || Date.now() / 1000 > payload.exp - 60;
+            }
+        }
+        catch {
+            tokenExpired = true;
+        }
+        if (tokenExpired) {
+            logger.info('relay', 'Token expired — attempting self-refresh...');
+            const refreshed = await relay.refreshIdToken();
+            if (refreshed) {
+                const fresh = Relay.loadConfig();
+                if (fresh) {
+                    relay.configure(fresh.token, fresh.endpoint);
+                    await relay.start();
+                }
+            }
+            else {
+                logger.warn('relay', 'Self-refresh failed — sign in from the Clearly Dev Mac app tray to re-authenticate');
+            }
+        }
+        else {
+            // Valid token — kick a (re)connect and let the reconnect loop settle it.
+            logger.info('relay', 'Token valid — connecting via the reconnect loop');
+            relay.start().catch(() => { });
+        }
+    }
+    // Start periodic token self-refresh (every 50 min)
+    relay.startTokenRefresh();
+    // ── .clearly/ bidirectional sync + folder sync for linked projects ──
+    // (`clearlySyncs` / `folderWatchers` are declared up by the shutdown handler — see the
+    //  note there. Re-declaring them here is what put them in the handler's dead zone.)
+    if (relay.isConnected()) {
+        const linked = getLinkedFolders();
+        for (const [folderPath, entry] of Object.entries(linked)) {
+            const brandId = entry.brandId;
+            // .clearly/ context sync (ClearlySync) — DISABLED 2026-07 (API-first).
+            // Retired in favour of writing workspace content DIRECTLY to the DO via
+            // MCP / the beehaven CLI (clearly_context_write, note-update, remember,
+            // clearly_ticket_create, …). The DO is the single source of truth; the
+            // old ".clearly/ folder ↔ DO" mirror added a SECOND source of truth plus
+            // a reconciliation surface (md5 hashes / remote versions / 2s debounce /
+            // .sync.json) for a job those tool calls already do — always fresh, no
+            // conflicts. Nothing linked folders in practice, so this was inert anyway.
+            // Re-enable ONLY if the local-file-materialisation model is deliberately
+            // revived. Local-folder strategy going forward = the daemon local-tools
+            // bridge (cloud agent → scoped local fs/exec via the daemon), NOT a mirror.
+            /*
+            try {
+              const sync = new ClearlySync({
+                projectPath: folderPath,
+                projectId: brandId,
+                callAction: (action, input) => relay.sendRequest({ ...input, type: action }),
+              });
+              sync.on('pulled', () => logger.info('sync', `Synced context for ${folderPath}`));
+              sync.on('pushed', () => logger.info('sync', `Pushed changes from ${folderPath}`));
+              sync.on('pull-error', (err) => logger.warn('sync', `Pull error: ${err}`));
+              sync.on('push-error', (err) => logger.warn('sync', `Push error: ${err}`));
+              sync.start().catch(() => {});
+              clearlySyncs.push(sync);
+            } catch (err: any) {
+              logger.warn('sync', `Failed to start sync for ${folderPath}: ${err.message}`);
+            }
+            */
+            // Folder watcher — syncs local file changes to cloud (R2 + DO)
+            try {
+                const fw = new FolderWatcher(folderPath, brandId, relay);
+                fw.on('syncing', (n) => logger.info('sync', `Uploading ${n} file(s) from ${folderPath}`));
+                fw.on('synced', (n) => logger.info('sync', `Synced ${n} file(s) from ${folderPath}`));
+                fw.on('error', (err) => logger.warn('sync', `Watcher error for ${folderPath}: ${err.message}`));
+                fw.start();
+                folderWatchers.push(fw);
+                logger.info('sync', `Watching ${folderPath} → project ${brandId}`);
+            }
+            catch (err) {
+                logger.warn('sync', `Failed to start watcher for ${folderPath}: ${err.message}`);
+            }
+        }
+    }
+    // ── Cloud→Local file sync ──
+    // When web clients upload/modify files, the DO broadcasts file-changed to daemons.
+    // Download changed files to the appropriate linked folder.
+    relay.onFileChanged = async (msg) => {
+        const { action, file, brandId } = msg;
+        if (!file?.path || !brandId)
+            return;
+        // Find the local folder linked to this brandId
+        const linked = getLinkedFolders();
+        let localRoot = null;
+        for (const [folderPath, entry] of Object.entries(linked)) {
+            if (entry.brandId === brandId) {
+                localRoot = folderPath;
+                break;
+            }
+        }
+        if (!localRoot)
+            return;
+        const localPath = join(localRoot, file.path);
+        if (action === 'delete') {
+            try {
+                unlinkSync(localPath);
+                logger.info('sync', `Deleted ${localPath}`);
+            }
+            catch { }
+            return;
+        }
+        // Download from R2
+        try {
+            const resp = await relay.sendRequest({
+                type: 'get-download-url',
+                key: file.storagePath || file.url,
+            });
+            if (!resp?.url)
+                return;
+            const dl = await fetch(resp.url, { signal: AbortSignal.timeout(30_000) });
+            if (!dl.ok)
+                return;
+            const buffer = Buffer.from(await dl.arrayBuffer());
+            // Ensure parent directory exists
+            const dir = dirname(localPath);
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(localPath, buffer);
+            // Update hash cache in folder watchers to prevent re-upload loop
+            for (const fw of folderWatchers) {
+                if (localPath.startsWith(fw.rootPath)) {
+                    const rel = relative(fw.rootPath, localPath);
+                    const hash = createHash('md5').update(buffer).digest('hex');
+                    fw.fileHashes.set(rel, hash);
+                }
+            }
+            logger.info('sync', `Downloaded ${file.path} → ${localPath} (${buffer.length} bytes)`);
+        }
+        catch (err) {
+            logger.warn('sync', `Download failed (${file.path}): ${err.message}`);
+        }
+    };
+    // Background historical session sync
+    if (relay.isConnected()) {
+        syncHistoricalSessions(relay)
+            .then((result) => {
+            if (result.uploaded > 0) {
+                logger.info('sync', `Historical sync: ${result.uploaded} sessions uploaded`);
+            }
+        })
+            .catch(() => { });
+    }
+    // Post-update health check (verifies relay connects after an auto-upgrade)
+    runPostUpdateHealthCheck(relay);
+    // Auto-update: check hourly, install when idle
+    checkAndAutoUpdate();
+    setInterval(() => checkAndAutoUpdate(), UPDATE_CHECK_INTERVAL);
+    // Telemetry: opt-in via config.shareTelemetry (default off, togglable from cloud)
+    // Sends system stats + agent metrics + git status every 2 minutes
+    let lastActiveCwd = null;
+    watcher.on('event', (e) => {
+        if (e.cwd)
+            lastActiveCwd = e.cwd;
+    });
+    const sendTelemetry = () => {
+        if (!daemonConfig?.shareTelemetry || !relay.isConnected())
+            return;
+        try {
+            const system = collectSystemTelemetry();
+            const agentSnapshot = metrics.snapshot();
+            const git = lastActiveCwd ? collectGitStatus(lastActiveCwd) : null;
+            relay.sendTelemetry({ system, git, agent: agentSnapshot });
+        }
+        catch {
+            /* non-critical */
+        }
+    };
+    setTimeout(sendTelemetry, 10_000);
+    setInterval(sendTelemetry, 120_000);
+    // Reset metrics window every 5 minutes
+    setInterval(() => metrics.resetWindow(), 5 * 60_000);
+    // Re-advertise this beehive every 2 min: refreshes last_seen and, crucially,
+    // self-heals the swarm's live routing map after a Home-DO hibernation dropped
+    // it (the WS survives hibernation, so without this the node would read
+    // "offline" until its next reconnect). Cheap — one WS frame.
+    setInterval(() => {
+        try {
+            registerBeehive();
+        }
+        catch {
+            /* best-effort */
+        }
+    }, 120_000);
+    // Start REPL
+    if (opts?.repl !== false && !process.env.BEEHAVEN_NO_REPL)
+        repl.start();
+}