@clearlysh/beehaven 0.8.16

package/dist/feature-flags.js

@@ -0,0 +1,154 @@
+// ============================================================================
+// beehaven CLI — feature flags
+// ----------------------------------------------------------------------------
+// Gate experimental / in-flux CLI behaviors. Each flag is env-overridable so
+// it can be flipped per-invocation without a rebuild. Mirror of the app-side
+// registry entry in the main repo's `lib/featureFlags.ts` (kept in sync by
+// name) — the CLI is a separate process and can't read the web app's
+// localStorage flags, so the functional gate lives here.
+// ============================================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+/** Truthy env check — accepts `1` / `true` (case-insensitive). */
+function envOn(name) {
+    const v = process.env[name];
+    return v === '1' || (typeof v === 'string' && v.toLowerCase() === 'true');
+}
+// ── Persisted flags ─────────────────────────────────────────────────────────
+// Some flags need to survive between invocations — `beehaven speak` is one
+// command per utterance, so an env var set in one shell says nothing about the
+// next. Those live in `~/.beehaven/config.json` (the same file that holds the
+// relay endpoint + env name), read on demand rather than at import time so a
+// write inside one process is visible to the next read.
+const CONFIG_PATH = join(homedir(), '.beehaven', 'config.json');
+/** Read `~/.beehaven/config.json`. Never throws — a corrupt file reads as `{}`. */
+export function readCliConfig() {
+    try {
+        if (!existsSync(CONFIG_PATH))
+            return {};
+        return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge `patch` into `~/.beehaven/config.json`.
+ *
+ * Read-modify-write on purpose: this file also holds auth tokens and the relay
+ * endpoint, so a flag write must never clobber keys it doesn't own. Setting a
+ * key to `undefined` deletes it (that's how a flag returns to its default,
+ * rather than persisting a literal "auto" forever).
+ */
+export function patchCliConfig(patch) {
+    const cfg = readCliConfig();
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            delete cfg[k];
+        else
+            cfg[k] = v;
+    }
+    mkdirSync(join(homedir(), '.beehaven'), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+}
+// ── TTS provider ────────────────────────────────────────────────────────────
+/**
+ * Which engine `beehaven speak` synthesizes with.
+ *
+ *   auto       Resolves to `qwen3-mlx`. Kept as a distinct value because it is
+ *              what an unset flag means, and because it is the value the
+ *              resolution treats as "no opinion" — an agent's BOUND voice wins
+ *              over `auto` and loses to an explicit `--tts`.
+ *   qwen3-mlx  Qwen3-TTS running ON THIS MACHINE under Apple's MLX. Speaks in a
+ *              CLONED voice, needs neither the Mac app nor a live relay, Apple
+ *              Silicon only. Install: `beehaven voice setup`; clone a voice:
+ *              `beehaven voice clone`.
+ *   none       Don't synthesize at all — for CI and agents that must stay
+ *              silent. `speak` becomes a no-op that still honours the
+ *              workspace-interaction flag below.
+ *
+ * ⚠⚠ THERE IS NO FALLBACK BETWEEN ENGINES ANY MORE. `avatar` (the Mac app's
+ * Kokoro) and `system` (macOS `say`) were deleted on 2026-08-27 with their rungs:
+ * a voice is an IDENTITY, so substituting a different one when the first is
+ * unavailable is a wrong answer, not a degraded one. `speak` now refuses and names
+ * the fix. `cloud` and `minimax` went earlier the same day, for network reasons.
+ *
+ * ⚠⚠ THIS ARRAY IS THE GATE, AND IT MUST MATCH THE RUNG TABLE IN BOTH DIRECTIONS.
+ * `--tts <name>` is validated against it, and the resolved name is then used to
+ * INDEX `rungs` in cli.ts. So:
+ *   • a rung absent here is unreachable, silently — that is what happened to
+ *     `minimax`, which sat in the table for days behind a comment promising it was
+ *     "one flag away";
+ *   • a name here with no rung is worse: it passes validation and then indexes
+ *     `undefined`, which is a crash rather than a refusal.
+ * `speak-surface.test.ts` pins both directions. Add or remove a name and its rung
+ * in the same commit.
+ */
+export const TTS_PROVIDERS = [
+    'auto',
+    'qwen3-mlx',
+    'none',
+];
+export function isTtsProvider(v) {
+    return TTS_PROVIDERS.includes(v);
+}
+/**
+ * Resolve the active provider: `$BEEHAVEN_TTS_PROVIDER` beats the persisted
+ * `ttsProvider` in config.json, which beats `auto`. An unrecognized value
+ * degrades to `auto` rather than muting the CLI.
+ */
+export function resolveTtsProvider() {
+    const env = (process.env.BEEHAVEN_TTS_PROVIDER ?? '').trim();
+    if (env && isTtsProvider(env))
+        return env;
+    const stored = String(readCliConfig().ttsProvider ?? '').trim();
+    if (stored && isTtsProvider(stored))
+        return stored;
+    return 'auto';
+}
+/** The cloned voice `qwen3-mlx` speaks with. `$BEEHAVEN_TTS_VOICE` wins. */
+export function resolveTtsVoice() {
+    const env = (process.env.BEEHAVEN_TTS_VOICE ?? '').trim();
+    if (env)
+        return env;
+    const stored = String(readCliConfig().ttsVoice ?? '').trim();
+    return stored || undefined;
+}
+export const CLI_FEATURE_FLAGS = {
+    /**
+     * SPEAK_WORKSPACE_INTERACTION — does `beehaven speak` touch the workspace?
+     *
+     *   OFF (default) → `beehaven speak` is purely LOCAL: it synthesizes + plays
+     *                   through the desktop avatar's local Kokoro voice and never
+     *                   calls the cloud. No canvas voice-frame is written.
+     *   ON            → additionally drop a durable voice-frame card on the
+     *                   connected workspace canvas (`canvas-add-voice`, which
+     *                   synthesizes server-side via ElevenLabs).
+     *
+     * Default: OFF. Override: `BEEHAVEN_SPEAK_WORKSPACE=1` (or `=true`).
+     */
+    SPEAK_WORKSPACE_INTERACTION: envOn('BEEHAVEN_SPEAK_WORKSPACE'),
+    /**
+     * TTS_PROVIDER — which engine `beehaven speak` synthesizes with.
+     *
+     * A getter, not a snapshot: `beehaven voice provider <name>` writes the value
+     * and any later read in the same process must see it.
+     *
+     * Default: `auto`. Override: `BEEHAVEN_TTS_PROVIDER=qwen3-mlx`, or persist
+     * with `beehaven voice provider qwen3-mlx`.
+     */
+    get TTS_PROVIDER() {
+        return resolveTtsProvider();
+    },
+    /**
+     * TTS_VOICE — the cloned voice `qwen3-mlx` speaks with (a name registered by
+     * `beehaven voice clone`). Ignored by every other provider.
+     *
+     * Default: unset (Qwen3 speaks in its own base voice). Override:
+     * `BEEHAVEN_TTS_VOICE=cove`, or persist with `beehaven voice use cove`.
+     */
+    get TTS_VOICE() {
+        return resolveTtsVoice();
+    },
+};

package/dist/file-browser.js

@@ -0,0 +1,88 @@
+// ============================================================================
+// Beehaven Office - File Browser
+// Reads directory listings for the remote Finder UI.
+// ============================================================================
+import { readdirSync, statSync, realpathSync } from 'fs';
+import { join, extname } from 'path';
+import { homedir } from 'os';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '__pycache__',
+    '.next',
+    '.cache',
+    'coverage',
+    '.turbo',
+    '.vercel',
+    '.svelte-kit',
+    '.nuxt',
+    'target',
+    'vendor',
+    '.gradle',
+]);
+/**
+ * Browse a directory path and return its entries.
+ * Returns directories first, then files, both sorted alphabetically.
+ */
+export function browsePath(dirPath) {
+    const home = homedir();
+    let resolved;
+    try {
+        resolved = realpathSync(dirPath.replace(/^~/, home));
+    }
+    catch {
+        return { entries: [], error: 'Directory not found' };
+    }
+    let rawEntries;
+    try {
+        rawEntries = readdirSync(resolved, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { entries: [], error: 'Directory not found' };
+        if (err.code === 'EACCES' || err.code === 'EPERM')
+            return { entries: [], error: 'Restricted folder' };
+        if (err.code === 'ENOTDIR')
+            return { entries: [], error: 'Not a directory' };
+        return { entries: [], error: err.message || 'Unknown error' };
+    }
+    const dirs = [];
+    const files = [];
+    for (const entry of rawEntries) {
+        // Skip system/hidden files that clutter the view
+        if (entry.name === '.DS_Store' || entry.name === 'Thumbs.db')
+            continue;
+        const fullPath = join(resolved, entry.name);
+        let stat;
+        try {
+            stat = statSync(fullPath);
+        }
+        catch {
+            continue; // Skip entries we can't stat
+        }
+        if (entry.isDirectory()) {
+            dirs.push({
+                name: entry.name,
+                type: 'directory',
+                size: 0,
+                ext: '',
+                modified: stat.mtimeMs,
+            });
+        }
+        else if (entry.isFile()) {
+            files.push({
+                name: entry.name,
+                type: 'file',
+                size: stat.size,
+                ext: extname(entry.name).slice(1).toLowerCase(),
+                modified: stat.mtimeMs,
+            });
+        }
+    }
+    // Sort alphabetically, directories first
+    dirs.sort((a, b) => a.name.localeCompare(b.name));
+    files.sort((a, b) => a.name.localeCompare(b.name));
+    return { entries: [...dirs, ...files] };
+}

package/dist/first-party-hives.js

@@ -0,0 +1,211 @@
+/**
+ * first-party-hives — auto-install bundled hives on daemon startup.
+ *
+ * Vector hive (and image hive, eventually) ship inside the Mac app's
+ * bundle at Resources/beehaven/hives/. Users shouldn't have to run
+ * `beehaven app install vector` to get the editor canvas working —
+ * it's a first-party experience. This module ensures the canonical
+ * first-party set is present in ~/.beehaven/apps/ on every daemon
+ * start.
+ *
+ * Idempotent — if the hive directory already exists in apps/, skip.
+ * Quiet — no user notification, just done. Failures are logged but
+ * don't crash daemon startup (worst case: user runs the manual
+ * install verb to recover).
+ *
+ * Discovery order for the bundled source:
+ *   1. <daemon-dir>/../hives/<name>/         (Mac app: Resources/beehaven/hives/)
+ *   2. <daemon-dir>/../../hives/<name>/      (one extra level — dev linkages)
+ *   3. <daemon-dir>/../../clearly-hives/<name>/  (monorepo dev path)
+ *
+ * ## ⚠⚠ VERSION-AWARE UPGRADE — this is what makes a shipped hive change reach anybody
+ *
+ * This used to skip whenever ANY copy of the hive existed, and its own note called that
+ * "acceptable for the v0 auto-install — we can add version-aware upgrade later." Later is now,
+ * because the consequence turned out to be total: the Mac app resolves the hive from
+ * `~/.beehaven/apps` in PREFERENCE to the copy inside its own bundle (`resolveUiDir` in
+ * avatar-overlay.ts), and nothing in the product ever removes an installed one. So a release
+ * could ship a rewritten companion and every existing user would keep the old one for ever.
+ * Verified against a real install: the bundled UI and the installed UI had diverged and nothing
+ * would have reconciled them.
+ *
+ * It is worse than a stale feature because it is INVISIBLE. The build succeeds, the bundle
+ * genuinely contains the new hive, and the app quietly loads the old one — so the release looks
+ * shipped and behaves un-shipped.
+ *
+ * Now: install when absent, UPGRADE IN PLACE when the bundled manifest is newer, skip otherwise.
+ *
+ * ⚠ IN PLACE, INTO THE EXISTING DIRECTORY — not a new `name@newversion` beside it. The daemon's
+ * `scanInstalledApps` enumerates this directory and dedupes by DIRECTORY NAME, so two versioned
+ * directories register as two separate apps and whichever `readdir` yields first wins. One
+ * directory per hive is the invariant that keeps the daemon and the Mac app on the same copy.
+ *
+ * ⚠ NOTHING IS DELETED. `cpSync(force: true)` overwrites the files the bundle carries and leaves
+ * everything else, so a building's SQLite state (dataDir defaults under this same tree) survives
+ * an upgrade. Removing the old directory would look tidier and would take a user's data with it.
+ *
+ * ⚠ THE INSTALLED VERSION IS READ FROM ITS `app.json`, NOT FROM THE DIRECTORY NAME. An in-place
+ * upgrade leaves the name reading `avatar@0.1.0` while the contents are newer; trusting the name
+ * would re-copy the whole hive on every launch — and would clobber a developer's local edits to
+ * an installed hive every time the daemon started.
+ *
+ * ⚠ A HIVE'S `app.json` VERSION MUST BE BUMPED WHEN ITS CONTENT CHANGES. That is the signal this
+ * relies on, and it is the one step a person has to remember; the Mac app's release preflight
+ * checks it (`scripts/release-preflight.mjs`).
+ */
+import { existsSync, readdirSync, readFileSync, mkdirSync, cpSync } from 'fs';
+import { join, dirname } from 'path';
+/**
+ * ⚠ ONE COMPARATOR. This file carried its own, which stripped the prerelease entirely
+ * (`split('-')[0]`) — so `1.0.0-rc.1` and `1.0.0` compared EQUAL and a hive on a release
+ * candidate would never update off it. Same name, different behaviour, in two files that never
+ * referenced each other.
+ */
+import { compareVersions } from './version-utils.js';
+/**
+ * Ensure the named first-party hives are present in `appsDir`. Copies
+ * from the bundled location if missing. Idempotent.
+ *
+ * @param names      e.g. ['vector', 'image']
+ * @param appsDir    ~/.beehaven/apps/
+ * @param daemonDir  The daemon's own directory — used to find bundled hives
+ */
+export async function ensureFirstPartyHives(names, appsDir, daemonDir) {
+    const installed = [];
+    const upgraded = [];
+    const skipped = [];
+    const failed = [];
+    mkdirSync(appsDir, { recursive: true });
+    for (const name of names) {
+        try {
+            // Find the bundled source.
+            const source = findBundledHive(name, daemonDir);
+            if (!source) {
+                failed.push(name);
+                continue;
+            }
+            // Read the manifest to learn the version.
+            const manifestPath = join(source, 'app.json');
+            if (!existsSync(manifestPath)) {
+                failed.push(name);
+                continue;
+            }
+            let manifest;
+            try {
+                manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            }
+            catch {
+                failed.push(name);
+                continue;
+            }
+            const existing = installedCopies(name, appsDir);
+            // Nothing installed — first run. Fresh copy at ~/.beehaven/apps/<name>@<version>/.
+            if (existing.length === 0) {
+                const dest = join(appsDir, `${manifest.name}@${manifest.version}`);
+                cpSync(source, dest, { recursive: true, errorOnExist: false, force: false });
+                installed.push(name);
+                continue;
+            }
+            // Upgrade every copy the bundle is newer than. Usually one; a machine that has both a
+            // legacy unversioned `avatar/` and an `avatar@x.y.z/` gets both brought forward, because
+            // leaving one behind is how the daemon and the app end up reading different code.
+            const stale = existing.filter((c) => compareVersions(manifest.version, c.version) > 0);
+            if (stale.length === 0) {
+                skipped.push(name);
+                continue;
+            }
+            for (const c of stale) {
+                cpSync(source, c.dir, { recursive: true, errorOnExist: false, force: true });
+            }
+            upgraded.push(name);
+        }
+        catch (e) {
+            console.warn(`  [first-party-hives] ${name} failed: ${e?.message ?? e}`);
+            failed.push(name);
+        }
+    }
+    if (installed.length > 0) {
+        console.log(`  [first-party-hives] auto-installed: ${installed.join(', ')}`);
+    }
+    // ⚠ AN UPGRADE IS LOGGED LOUDLY. It rewrites files under the user's home directory on a
+    // daemon start they did not ask for, and it is the only evidence that a shipped hive change
+    // actually landed — which is exactly what was impossible to see before.
+    if (upgraded.length > 0) {
+        console.log(`  [first-party-hives] upgraded from the bundle: ${upgraded.join(', ')}`);
+    }
+    return { installed, upgraded, skipped, failed };
+}
+/** Every installed copy of the hive, with the version its OWN manifest claims. */
+function installedCopies(name, appsDir) {
+    if (!existsSync(appsDir))
+        return [];
+    const out = [];
+    for (const e of readdirSync(appsDir, { withFileTypes: true })) {
+        if (!e.isDirectory())
+            continue;
+        if (e.name !== name && !e.name.startsWith(`${name}@`))
+            continue;
+        const dir = join(appsDir, e.name);
+        // ⚠ THE MANIFEST, NOT THE DIRECTORY NAME — an in-place upgrade leaves the name stale, and
+        // reading the name would re-copy the hive on every launch for ever. `0.0.0` for a copy with
+        // no readable manifest, so anything bundled beats it and a corrupt install self-heals.
+        let version = '0.0.0';
+        try {
+            const m = JSON.parse(readFileSync(join(dir, 'app.json'), 'utf8'));
+            if (typeof m?.version === 'string' && m.version)
+                version = m.version;
+        }
+        catch { /* unreadable manifest — treat as ancient */ }
+        out.push({ dir, version });
+    }
+    return out;
+}
+/**
+ * Semver-ish compare: >0 when `a` is newer. Numeric per segment, because a lexicographic
+ * comparison puts 0.10.0 BEFORE 0.9.0 — the same bug `resolveUiDir` in the Mac app already had
+ * to fix in its own sort.
+ *
+ * Pre-release suffixes are ignored rather than ordered: these are first-party hives shipped
+ * inside the app, so `0.2.0-rc1` and `0.2.0` are the same release as far as this is concerned.
+ */
+/** Find the bundled source for a hive by checking known locations. */
+/**
+ * The read-only home of a bundled first-party hive, or null.
+ *
+ * ⚠⚠ EXPORTED SO BUILDINGS CAN BE LOADED IN PLACE (2026-08-28). `ensureFirstPartyHives` COPIES a
+ * hive's whole project directory — `src/`, `scripts/`, `tsconfig.json`, and for the avatar a
+ * `ui/` the product then rendered from — into `~/.beehaven/apps`. That put an editable second copy
+ * of first-party SOURCE outside version control, and made which copy ran a question of timing.
+ *
+ * Reading the bundle directly removes the copy, and with it the whole class of bug: there is one
+ * location, it ships with the app, and nothing can edit it by accident.
+ */
+export function bundledHiveDir(name, daemonDir) {
+    return findBundledHive(name, daemonDir);
+}
+function findBundledHive(name, daemonDir) {
+    const candidates = [
+        // Mac app bundle: Resources/beehaven/hives/<name>/
+        //
+        // ⚠ This is the path the comment below has always DESCRIBED and the code
+        // never checked. `daemonDir` is where daemon-entry.js lives —
+        // `Resources/beehaven` — so `dirname(daemonDir)` is `Resources`, and the
+        // next candidate resolves to `Resources/hives/<name>`, one level ABOVE
+        // where the bundle actually puts them. Nothing matched, `findBundledHive`
+        // returned null for every hive, and the bootstrap silently installed
+        // nothing. Kept the old entries below: they're what a linked/dev layout
+        // uses, and removing them would break those.
+        join(daemonDir, 'hives', name),
+        join(dirname(daemonDir), 'hives', name),
+        // One more level up — dev/linked layouts
+        join(dirname(dirname(daemonDir)), 'hives', name),
+        // Monorepo dev: clearly-hives/<name>/
+        join(dirname(dirname(daemonDir)), 'clearly-hives', name),
+        join(dirname(dirname(dirname(daemonDir))), 'clearly-hives', name),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c) && existsSync(join(c, 'app.json')))
+            return c;
+    }
+    return null;
+}

package/dist/folder-sync.js

@@ -0,0 +1,226 @@
+// ============================================================================
+// Beehaven Office - Folder Sync
+// Links local folders to Clearly projects and watches for file changes.
+// Uses native OS file watchers (fsevents/inotify) — no polling.
+// chokidar is loaded lazily in start() so a daemon without chokidar bundled
+// still boots and serves IPC — folder-sync just becomes a no-op.
+// ============================================================================
+import { EventEmitter } from 'events';
+import { createHash } from 'crypto';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
+import { extname, relative, join } from 'path';
+import { homedir, hostname } from 'os';
+const CONFIG_DIR = join(homedir(), '.beehaven');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+/** Directories and files to ignore */
+const IGNORE_PATTERNS = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/__pycache__/**',
+    '**/.next/**',
+    '**/.cache/**',
+    '**/coverage/**',
+    '**/.turbo/**',
+    '**/.DS_Store',
+    '**/.env',
+    '**/.env.*',
+    '**/package-lock.json',
+    '**/yarn.lock',
+    '**/pnpm-lock.yaml',
+    '**/*.sqlite',
+    '**/*.db',
+    '**/*.pyc',
+];
+// ── Config Helpers ──────────────────────────────────────────────────────────
+function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function saveConfig(update) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const existing = loadConfig();
+    const merged = { ...existing, ...update };
+    writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2));
+}
+/** Get all linked folders from config */
+export function getLinkedFolders() {
+    const config = loadConfig();
+    return config.linkedFolders || {};
+}
+// ── Link / Unlink Flows ─────────────────────────────────────────────────────
+/** Link the current folder to a Clearly project (brand) */
+export async function linkProject(relay, folderPath, brandId) {
+    const targetPath = folderPath || process.cwd();
+    if (!relay.isConfigured()) {
+        console.error('  Not linked to Clearly. Sign in from the Clearly Dev Mac app tray.');
+        process.exit(1);
+    }
+    // If no brandId provided, list projects and prompt
+    if (!brandId) {
+        const projects = await relay.listProjects();
+        /**
+         * ⚠ `null` MEANS THE CALL FAILED; `[]` MEANS THERE ARE NONE. Collapsing them is how this
+         * printed "No projects found" against a workspace holding 50 — see `listProjects`.
+         */
+        if (projects === null) {
+            console.error('  Could not reach your workspace to list projects.');
+            console.error('  Check `beehaven status`, then try again.');
+            process.exit(1);
+        }
+        if (projects.length === 0) {
+            console.error('  No projects found in your Clearly account.');
+            console.error('  Create a project at https://clearly.sh first.');
+            process.exit(1);
+        }
+        console.log('\n  Available projects:\n');
+        for (let i = 0; i < projects.length; i++) {
+            console.log(`    ${i + 1}. ${projects[i].name} (${projects[i].id})`);
+        }
+        // Use readline for interactive selection
+        const readline = await import('readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+            rl.question('\n  Select project number: ', resolve);
+        });
+        rl.close();
+        const idx = parseInt(answer, 10) - 1;
+        if (isNaN(idx) || idx < 0 || idx >= projects.length) {
+            console.error('  Invalid selection.');
+            process.exit(1);
+        }
+        brandId = projects[idx].id;
+        console.log(`\n  Linking to: ${projects[idx].name}`);
+    }
+    // Store link in config
+    const linked = getLinkedFolders();
+    linked[targetPath] = { brandId, linkedAt: Date.now() };
+    saveConfig({ linkedFolders: linked });
+    // Notify Clearly
+    await relay.updateBrandSync(brandId, {
+        localPath: targetPath,
+        syncDevice: hostname(),
+        syncStatus: 'connected',
+    });
+    console.log(`\n  Linked: ${targetPath} → ${brandId}`);
+    console.log('  Beehaven will sync this folder when running.\n');
+}
+/** Unlink the current folder */
+export async function unlinkProject(relay, folderPath) {
+    const targetPath = folderPath || process.cwd();
+    const linked = getLinkedFolders();
+    const entry = linked[targetPath];
+    if (!entry) {
+        console.error(`  No linked project for: ${targetPath}`);
+        process.exit(1);
+    }
+    // Clear sync status on Clearly
+    if (relay.isConfigured()) {
+        await relay.updateBrandSync(entry.brandId, {
+            syncStatus: 'disconnected',
+        });
+    }
+    delete linked[targetPath];
+    saveConfig({ linkedFolders: linked });
+    console.log(`\n  Unlinked: ${targetPath}\n`);
+}
+// ── Folder Watcher ──────────────────────────────────────────────────────────
+export class FolderWatcher extends EventEmitter {
+    rootPath;
+    relay;
+    watcher = null;
+    fileHashes = new Map();
+    pendingChanges = new Map();
+    flushTimer = null;
+    brandId;
+    constructor(rootPath, brandId, relay) {
+        super();
+        this.rootPath = rootPath;
+        this.relay = relay;
+        this.brandId = brandId;
+    }
+    async start() {
+        // All failures are swallowed to a log — folder sync is optional, and
+        // callers fire-and-forget this method. We must never reject so nothing
+        // becomes an unhandled promise rejection in the daemon process.
+        try {
+            let watch;
+            try {
+                watch = (await import('chokidar')).watch;
+            }
+            catch {
+                // Daemon running without chokidar — folder sync becomes a no-op.
+                // The rest of the daemon (IPC, relay) continues to function.
+                console.warn(`[folder-sync] chokidar not available — watcher for ${this.rootPath} disabled`);
+                return;
+            }
+            this.watcher = watch(this.rootPath, {
+                persistent: true,
+                ignoreInitial: true, // Skip initial scan to avoid EMFILE on large repos
+                ignored: IGNORE_PATTERNS,
+                depth: 5, // Reduced from 8 — deep repos exhaust file descriptors
+                usePolling: false,
+            });
+            this.watcher
+                .on('add', (path) => this.handleFile('add', path))
+                .on('change', (path) => this.handleFile('change', path))
+                .on('unlink', (path) => this.handleFile('delete', path))
+                .on('error', (err) => this.emit('error', err));
+        }
+        catch (err) {
+            console.warn(`[folder-sync] start failed for ${this.rootPath}: ${err?.message ?? err}`);
+        }
+    }
+    stop() {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.watcher?.close();
+        this.watcher = null;
+    }
+    handleFile(action, filePath) {
+        const ext = extname(filePath).slice(1).toLowerCase();
+        const relativePath = relative(this.rootPath, filePath);
+        this.pendingChanges.set(relativePath, { action, relativePath, ext });
+        // Debounce 500ms — batch rapid changes
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = setTimeout(() => this.flush(), 500);
+    }
+    async flush() {
+        const changes = Array.from(this.pendingChanges.values());
+        this.pendingChanges.clear();
+        if (changes.length === 0)
+            return;
+        this.emit('syncing', changes.length);
+        for (const change of changes) {
+            try {
+                if (change.action === 'delete') {
+                    await this.relay.syncFileDelete(this.brandId, change.relativePath);
+                }
+                else {
+                    const fullPath = join(this.rootPath, change.relativePath);
+                    if (!existsSync(fullPath))
+                        continue;
+                    const content = readFileSync(fullPath);
+                    const hash = createHash('md5').update(content).digest('hex');
+                    // Skip if unchanged
+                    if (this.fileHashes.get(change.relativePath) === hash)
+                        continue;
+                    this.fileHashes.set(change.relativePath, hash);
+                    await this.relay.syncFileUpload(this.brandId, change.relativePath, content, hash);
+                }
+            }
+            catch (err) {
+                console.error(`[folder-sync] Error syncing ${change.relativePath}: ${err.message}`);
+            }
+        }
+        this.emit('synced', changes.length);
+    }
+}