beehaven 0.8.16

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "beehaven",
+  "version": "0.8.16",
+  "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "beehaven": "dist/cli.js",
+    "clearly": "dist/clearly.js"
+  },
+  "main": "dist/cli.js",
+  "files": [
+    "dist",
+    "python",
+    "README.md",
+    "LICENSE",
+    "scripts/",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "dev": "tsx watch src/cli.ts",
+    "build": "tsc && node scripts/stamp-build-channel.mjs && node scripts/sync-installed.mjs",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:json-capable": "vitest run src/__tests__/json-capable.test.ts",
+    "test:limit-capable": "vitest run src/__tests__/limit-capable.test.ts",
+    "test:out-capable": "vitest run src/__tests__/out-capable.test.ts",
+    "test:script-citations": "vitest run src/__tests__/script-citations.test.ts",
+    "prepublishOnly": "BEEHAVEN_PUBLIC_BUILD=1 BEEHAVEN_NO_SYNC=1 npm run build",
+    "sync:skills": "node scripts/sync-skills.mjs",
+    "prepack": "node scripts/sync-skills.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.141",
+    "bplist-parser": "^0.3.2",
+    "chokidar": "4.0.0",
+    "fflate": "^0.8.3",
+    "ws": "8.18.0"
+  },
+  "peerDependencies": {
+    "@clearly-sh/beehaven-core": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@clearly-sh/beehaven-core": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "11.0.0",
+    "node-pty": "1.0.0",
+    "open": "10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.7",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.0"
+  },
+  "keywords": [
+    "beehaven",
+    "clearly",
+    "cli",
+    "ai-agents",
+    "agent-workspace",
+    "claude-code",
+    "codex",
+    "agent-tools",
+    "design-canvas",
+    "mcp"
+  ],
+  "license": "MIT",
+  "homepage": "https://www.clearly.sh/docs/cli",
+  "bugs": {
+    "url": "https://github.com/clearly-sh/clearly/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clearly-sh/clearly.git"
+  }
+}

package/python/qwen3_tts.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+qwen3_tts.py — the MLX side of the `qwen3-mlx` TTS provider for `beehaven speak`.
+
+WHY THIS EXISTS. Every other voice path `speak` can take is a network call
+(cloud Kokoro, ElevenLabs) or a canned system voice (macOS `say`). None of them
+can speak in *your* voice, and the cloud ones need a relay + a live token. This
+script is the on-device path: Alibaba's Qwen3-TTS running under Apple's MLX,
+which does 3-second voice cloning locally on Apple Silicon. No relay, no API
+key, no audio leaves the machine.
+
+CONTRACT WITH THE NODE SIDE (`src/tts-qwen3.ts`).
+  - One JSON request object on **stdin**, one JSON response object on **stdout**.
+  - stdout carries NOTHING ELSE. mlx-audio prints progress, tokens/sec, and
+    "✅ Audio successfully generated" to stdout unconditionally, so every call
+    into it is wrapped in `redirect_stdout(sys.stderr)`. The Node side parses
+    stdout strictly, so a single stray print would corrupt the response.
+  - Failures come back as `{"ok": false, "error": "..."}` with exit code 1 —
+    the caller gets a message, never a Python traceback in the user's terminal.
+
+COMMANDS
+  probe       {}                          -> versions + whether Metal is usable
+  transcribe  {audio}                     -> {text}         (whisper, clone-time only)
+  speak       {text, out, ...}            -> {path, ...}    (synthesis)
+
+WHY TRANSCRIBE IS A SEPARATE COMMAND. Qwen3-TTS clones via in-context learning:
+it needs the reference audio AND a transcript of it. mlx-audio will happily
+auto-transcribe at synthesis time, but that loads whisper-large-v3-turbo
+(~1.6 GB) on *every* utterance. We transcribe ONCE when the voice is cloned,
+persist the transcript in the voice profile, and pass `ref_text` on every
+subsequent `speak` — so whisper never loads again and the profile stays a
+self-contained, portable description of the voice.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+import wave
+from contextlib import redirect_stdout
+from pathlib import Path
+
+# Model families. Voice CLONING requires a `-Base` checkpoint: CustomVoice is
+# fixed predefined speakers and VoiceDesign builds a voice from a text
+# description — neither accepts a reference recording.
+DEFAULT_MODEL = "mlx-community/Qwen3-TTS-12Hz-0.6B-Base-4bit"
+DEFAULT_STT_MODEL = "mlx-community/whisper-large-v3-turbo-asr-fp16"
+
+
+def _fail(msg: str) -> None:
+    """Emit the error envelope on stdout and leave with a non-zero status."""
+    json.dump({"ok": False, "error": str(msg)}, sys.stdout)
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    sys.exit(1)
+
+
+def _ok(payload: dict) -> None:
+    json.dump({"ok": True, **payload}, sys.stdout)
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+def cmd_probe(_req: dict) -> dict:
+    import importlib.metadata as md
+
+    import mlx.core as mx
+
+    def _ver(pkg: str) -> str:
+        try:
+            return md.version(pkg)
+        except Exception:
+            return "?"
+
+    # Touching the default device is the cheapest proof Metal actually
+    # initializes — an x86 Python under Rosetta imports mlx fine and then dies
+    # at the first kernel launch.
+    device = str(mx.default_device())
+    return {
+        "python": sys.version.split()[0],
+        "mlxAudio": _ver("mlx-audio"),
+        "mlx": _ver("mlx"),
+        "device": device,
+        "defaultModel": DEFAULT_MODEL,
+        "sttModel": DEFAULT_STT_MODEL,
+    }
+
+
+def cmd_transcribe(req: dict) -> dict:
+    audio = req.get("audio")
+    if not audio:
+        raise ValueError("transcribe requires `audio`")
+    audio_path = Path(audio).expanduser()
+    if not audio_path.exists():
+        raise FileNotFoundError(f"reference audio not found: {audio_path}")
+
+    model_id = req.get("sttModel") or DEFAULT_STT_MODEL
+    started = time.time()
+    with redirect_stdout(sys.stderr):
+        from mlx_audio.stt import load as load_stt
+
+        stt = load_stt(model_id)
+        # whisper takes the path directly and handles decode + resample, so we
+        # don't have to guess the TTS model's sample rate here.
+        result = stt.generate(str(audio_path), language=req.get("language"))
+    text = (getattr(result, "text", "") or "").strip()
+    if not text:
+        raise RuntimeError(
+            "transcription came back empty — is the reference audio silent or music-only?"
+        )
+    return {"text": text, "model": model_id, "elapsedSec": round(time.time() - started, 2)}
+
+
+def cmd_speak(req: dict) -> dict:
+    text = (req.get("text") or "").strip()
+    if not text:
+        raise ValueError("speak requires `text`")
+    out = req.get("out")
+    if not out:
+        raise ValueError("speak requires `out` (destination .wav path)")
+
+    out_path = Path(out).expanduser()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    ref_audio = req.get("refAudio")
+    ref_text = req.get("refText")
+    if ref_audio:
+        ref_audio = str(Path(ref_audio).expanduser())
+        if not Path(ref_audio).exists():
+            raise FileNotFoundError(f"reference audio not found: {ref_audio}")
+
+    kwargs = {
+        "text": text,
+        "model": req.get("model") or DEFAULT_MODEL,
+        # `join_audio` makes mlx-audio write exactly ONE file at
+        # "<file_prefix>.<audio_format>" instead of one file per sentence
+        # segment — that predictable name is how we find the result.
+        "join_audio": True,
+        "output_path": str(out_path.parent),
+        "file_prefix": out_path.stem,
+        "audio_format": out_path.suffix.lstrip(".") or "wav",
+        "verbose": False,
+        "play": False,
+        "temperature": float(req.get("temperature", 0.7)),
+        "speed": float(req.get("speed", 1.0)),
+        "lang_code": req.get("langCode") or "en",
+    }
+    if ref_audio:
+        kwargs["ref_audio"] = ref_audio
+        # A Base checkpoint in ICL mode takes its identity entirely from the
+        # reference, so blank the speaker — otherwise mlx-audio's `af_heart`
+        # default (a Kokoro speaker name) rides along and muddies the logs.
+        kwargs["voice"] = None
+        # Passing ref_text keeps mlx-audio from loading whisper. When a caller
+        # skips it (bare `--ref-audio` with no cached profile) mlx-audio falls
+        # back to transcribing, which is slow but correct.
+        if ref_text:
+            kwargs["ref_text"] = ref_text
+        else:
+            kwargs["stt_model"] = req.get("sttModel") or DEFAULT_STT_MODEL
+    elif req.get("voice"):
+        # No reference recording: a predefined speaker (CustomVoice checkpoints).
+        kwargs["voice"] = req["voice"]
+    if req.get("instruct"):
+        kwargs["instruct"] = req["instruct"]
+    if req.get("maxTokens"):
+        kwargs["max_tokens"] = int(req["maxTokens"])
+
+    started = time.time()
+    with redirect_stdout(sys.stderr):
+        from mlx_audio.tts.generate import generate_audio
+
+        generate_audio(**kwargs)
+
+    if not out_path.exists():
+        raise RuntimeError(
+            f"synthesis reported success but produced no file at {out_path}"
+        )
+
+    duration = None
+    try:
+        with wave.open(str(out_path), "rb") as wf:
+            duration = round(wf.getnframes() / float(wf.getframerate()), 2)
+    except Exception:
+        # Non-wav container (flac/mp3) — duration is a nicety, not a contract.
+        pass
+
+    elapsed = round(time.time() - started, 2)
+    return {
+        "path": str(out_path),
+        "bytes": out_path.stat().st_size,
+        "durationSec": duration,
+        "elapsedSec": elapsed,
+        # <1.0 means we generated faster than real time — the number that
+        # decides whether this provider is usable interactively.
+        "realTimeFactor": round(elapsed / duration, 2) if duration else None,
+        "model": kwargs["model"],
+        "cloned": bool(ref_audio),
+    }
+
+
+COMMANDS = {"probe": cmd_probe, "transcribe": cmd_transcribe, "speak": cmd_speak}
+
+
+def main() -> None:
+    command = sys.argv[1] if len(sys.argv) > 1 else ""
+    handler = COMMANDS.get(command)
+    if handler is None:
+        _fail(f"unknown command {command!r} — expected one of {', '.join(COMMANDS)}")
+        return
+
+    raw = sys.stdin.read().strip()
+    try:
+        req = json.loads(raw) if raw else {}
+    except json.JSONDecodeError as exc:
+        _fail(f"invalid JSON request: {exc}")
+        return
+
+    try:
+        _ok(handler(req))
+    except Exception as exc:  # noqa: BLE001 — the envelope IS the error channel
+        import traceback
+
+        traceback.print_exc(file=sys.stderr)
+        _fail(f"{type(exc).__name__}: {exc}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/stamp-build-channel.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * postbuild — declare, in the emitted bundle, whether this is a PUBLIC build.
+ *
+ * ⚠⚠ WHAT THIS DECIDES. `PUBLIC_BUILD` is what makes `HIVE_DEV_MODE=1` inert. Developer scope
+ * mints a second IPC token that unlocks `get-token` (the user's Firebase ID token), `shell`, `sql`,
+ * `marketplace:install`, the `admin:*` proxies, and — on the relay path — `bash` /
+ * `workspace-exec`, i.e. arbitrary local command execution. None of that belongs in a build handed
+ * to `curl … | sh` users.
+ *
+ * ⚠ IT REWRITES `dist/`, NEVER `src/`. Stamping the source would leave the working tree dirty after
+ * a publish and, far worse, could be committed — shipping a checkout that silently cannot enable
+ * developer mode, with no error to explain it.
+ *
+ * ⚠ THE DEFAULT IS NOT PUBLIC. An ordinary `npm run build` writes `false`, so a checkout behaves as
+ * it always has. `scripts/publish-beehaven-cli.sh` sets `BEEHAVEN_PUBLIC_BUILD=1`. Defaulting the
+ * other way would mean one forgotten flag ships a developer build to everyone, silently.
+ *
+ * ⚠ IT FAILS THE BUILD RATHER THAN WARNING. A stamp that quietly did nothing is exactly the shape
+ * of bug this exists to prevent: the tarball would look fine and carry the capability.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+/**
+ * ⚠ `BEEHAVEN_STAMP_FILE` IS A TEST SEAM, and it exists because the refusal below is the script's
+ * whole safety property — an unstamped build looks perfect and carries the wrong answer. The only
+ * way to prove the refusal fires is to run this script against a deliberately-broken file, and
+ * doing that to the real `dist/` would break every other test that execs the built CLI. Unset in
+ * every real build, so the default path is unchanged.
+ */
+const FILE = process.env.BEEHAVEN_STAMP_FILE || join(ROOT, 'dist', 'build-channel.js');
+
+const truthy = (v) => ['1', 'true', 'yes', 'on'].includes(String(v ?? '').trim().toLowerCase());
+const isPublic = truthy(process.env.BEEHAVEN_PUBLIC_BUILD);
+
+/**
+ * WHICH BUILD — CBH2-145. A commit and a build time, so `--version` can tell two builds of 0.8.2
+ * apart. Before this, the Mac app's bundled `cli.js` and the repo build both said `0.8.2`, differed
+ * by 9 KB, and disagreed about which verbs exist.
+ *
+ * ⚠⚠ GIT IS OPTIONAL, AND THAT IS NOT LAZINESS. A user who unpacks the published tarball and runs
+ * `npm run build` has no `.git`, and failing their build to protect a diagnostic field would be a
+ * strictly worse outcome than an unstamped sha. The TIMESTAMP has no such dependency, so the
+ * "which build" question is answered either way — which is why there are two fields and not one.
+ *
+ * ⚠ `-dirty` IS SCOPED TO THIS PACKAGE (`git status --porcelain -- <pkgRoot>`). Against the whole
+ * monorepo the marker would be on in essentially every dev build and would therefore carry no
+ * information. Scoped, it means precisely "the sha does not identify these bytes".
+ *
+ * ⚠ ITS BOUND, STATED: the CLI also links `@clearly-sh/beehaven-core`, whose sources live outside
+ * this path. A core-only change leaves the marker clean. The sha still identifies the CLI sources,
+ * which is what this file is emitted from.
+ */
+function gitSha() {
+  const git = (args) =>
+    execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  try {
+    const sha = git(['rev-parse', '--short=12', 'HEAD']);
+    if (!sha) return '';
+    const dirty = git(['status', '--porcelain', '--', ROOT]).length > 0;
+    return dirty ? `${sha}-dirty` : sha;
+  } catch {
+    return ''; // no git, no repo, shallow checkout — all legitimate
+  }
+}
+
+const sha = gitSha();
+// ⚠ Minute precision, UTC. Seconds add noise to a field a human reads; a timezone adds ambiguity.
+const builtAt = new Date().toISOString().replace(/:\d\d\.\d+Z$/, 'Z');
+
+if (!existsSync(FILE)) {
+  console.error(`stamp-build-channel: ${FILE} does not exist — did tsc emit? Refusing to continue.`);
+  process.exit(1);
+}
+
+const src = readFileSync(FILE, 'utf8');
+
+/**
+ * ⚠ EVERY STAMP IS ANCHORED ON THE DECLARATION TSC EMITS, so a rename fails loudly instead of
+ * stamping nothing. That refusal is the whole safety property of this script — an unstamped build
+ * looks perfect and carries the wrong answer — so a NEW field gets the same treatment rather than a
+ * best-effort `replace`.
+ */
+const STAMPS = [
+  { name: 'PUBLIC_BUILD', decl: /export const PUBLIC_BUILD = (?:true|false);/, next: `export const PUBLIC_BUILD = ${isPublic};` },
+  { name: 'BUILD_SHA', decl: /export const BUILD_SHA = '[^']*';/, next: `export const BUILD_SHA = '${sha}';` },
+  { name: 'BUILD_TIME', decl: /export const BUILD_TIME = '[^']*';/, next: `export const BUILD_TIME = '${builtAt}';` },
+];
+
+let out = src;
+for (const s of STAMPS) {
+  if (!s.decl.test(out)) {
+    console.error(`stamp-build-channel: could not find the ${s.name} declaration in the emitted `
+      + 'build-channel.js. The export was renamed or the emit shape changed — fix this script rather '
+      + 'than shipping an unstamped build.');
+    process.exit(1);
+  }
+  out = out.replace(s.decl, s.next);
+}
+writeFileSync(FILE, out);
+
+// ⚠ Read it BACK. The whole point is that the shipped bytes say what we think they say.
+const after = readFileSync(FILE, 'utf8');
+for (const s of STAMPS) {
+  if (!after.includes(s.next)) {
+    console.error(`stamp-build-channel: the ${s.name} stamp did not take. Refusing to continue.`);
+    process.exit(1);
+  }
+}
+if (isPublic) console.log('  build channel: PUBLIC — Developer Mode is compiled out');
+console.log(`  build id: ${sha || '(no git)'}  ${builtAt}`);

package/scripts/sync-installed.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * postbuild — keep the INSTALLED cli in step with the one you just built.
+ *
+ * ── THE TRAP THIS CLOSES ─────────────────────────────────────────────────────────────
+ * `curl … install.sh` writes `~/.local/bin/beehaven`, a wrapper that execs
+ * `~/.beehaven/cli/dist/cli.js`. `~/.local/bin` precedes the npm prefix on PATH, so after
+ * `npm run build` in this package the binary named `beehaven` is STILL the installed copy —
+ * and both report the same version, because the number comes from a package.json neither
+ * build bumps on a rebuild.
+ *
+ * The failure mode is not a broken CLI, it is a LYING one: you fix a bug, rebuild, re-run,
+ * observe the old behaviour, and conclude the fix didn't work. That happened during this
+ * feature's own development and cost a verified-correct fix an extra debugging cycle.
+ *
+ * ── WHAT THIS DOES ───────────────────────────────────────────────────────────────────
+ * If (and only if) `~/.beehaven/cli` already exists — i.e. this machine has an installed
+ * copy — mirror the freshly-built `dist/`, `skills/`, and `package.json` into it. A machine with no
+ * install is untouched, so this is a no-op in CI and on a fresh clone.
+ *
+ * It deliberately does NOT create the install: writing a new CLI into a user's home on the
+ * strength of a `npm run build` would be a side effect nobody asked for. It only keeps an
+ * EXISTING one honest.
+ *
+ * Opt out with BEEHAVEN_NO_SYNC=1 (e.g. when you are deliberately testing an older install).
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, '..');
+const installed = join(homedir(), '.beehaven', 'cli');
+
+if (process.env.BEEHAVEN_NO_SYNC === '1') {
+  console.log('  postbuild: sync skipped (BEEHAVEN_NO_SYNC=1)');
+  process.exit(0);
+}
+/**
+ * ⚠⚠ A THIRD COPY THIS SCRIPT DOES NOT OWN: THE MAC APP'S BUNDLE.
+ *
+ * The header above describes closing the `~/.local/bin` trap by syncing `~/.beehaven/cli`. That is
+ * still right and still incomplete — on a machine with the Mac app installed, the wrapper at
+ * `~/.local/bin/beehaven` says `managed-by: clearly-mac-app` and `overwritten on every app launch`,
+ * and it execs the app's OWN bundled `cli.js`. So the binary named `beehaven` is neither this build
+ * nor the one we just synced.
+ *
+ * ⚠ IT IS THE EXACT FAILURE THE HEADER NAMES — "you fix a bug, rebuild, re-run, observe the old
+ * behaviour, and conclude the fix didn't work" — and it cost a cycle again on 2026-09-01, on a
+ * daemon-startup fix that was correct and simply was not the code being run.
+ *
+ * ⚠ WE WARN RATHER THAN WRITE. Copying into `/Applications` on every build is invasive, needs
+ * permissions this script should not want, and would be undone by the next app launch anyway. What
+ * the reader needs is to know which binary they are about to test.
+ */
+const wrapper = join(homedir(), '.local', 'bin', 'beehaven');
+try {
+  if (existsSync(wrapper)) {
+    const body = readFileSync(wrapper, 'utf8');
+    if (/managed-by:\s*clearly-mac-app/.test(body)) {
+      console.warn(
+        '  postbuild: ⚠ `beehaven` on your PATH is the MAC APP\'s bundled CLI, which this build does\n' +
+        '             not update. Test this build with `node dist/cli.js …`, or relaunch the app\n' +
+        '             after copying, or the old behaviour will look like your fix failing.'
+      );
+    }
+  }
+} catch { /* a warning must never fail a build */ }
+
+if (!existsSync(installed)) {
+  // No install on this machine — nothing to keep in step. Silent: this is the normal state
+  // in CI, and a warning nobody can act on is noise on every build.
+  process.exit(0);
+}
+
+try {
+  const distSrc = join(pkgRoot, 'dist');
+  if (!existsSync(distSrc)) {
+    console.error('  postbuild: dist/ missing — did tsc fail? Installed copy left alone.');
+    process.exit(0);
+  }
+  const distDst = join(installed, 'dist');
+  rmSync(distDst, { recursive: true, force: true });
+  mkdirSync(distDst, { recursive: true });
+  cpSync(distSrc, distDst, { recursive: true });
+  cpSync(join(pkgRoot, 'package.json'), join(installed, 'package.json'));
+  /**
+   * THE SKILLS ARE PART OF THE CLI RELEASE, NOT OPTIONAL CACHE.
+   *
+   * `agent-skills.ts` resolves its source relative to the running installed `dist/`, so syncing
+   * only code left `~/.beehaven/cli/skills` on the previous release. `skills install` then compared
+   * every agent home against that stale manifest, confidently reported "current", and never
+   * delivered documentation fixes made in the same build. Mirror the directory atomically enough
+   * for this local postbuild path: remove the old bundle, copy the just-synced hashed bundle, then
+   * let the normal installer preserve locally edited destination skills.
+   */
+  const skillsSrc = join(pkgRoot, 'skills');
+  const skillsDst = join(installed, 'skills');
+  if (existsSync(skillsSrc)) {
+    rmSync(skillsDst, { recursive: true, force: true });
+    cpSync(skillsSrc, skillsDst, { recursive: true });
+  }
+  // `python/` carries the local-TTS bridge; without it a synced install reports an
+  // incomplete qwen3-mlx runtime rather than working. Copy it when the source has it.
+  const py = join(pkgRoot, 'python');
+  if (existsSync(py)) cpSync(py, join(installed, 'python'), { recursive: true });
+  /**
+   * LINK THE OPTIONAL PEER DEP.
+   *
+   * `agent-identity-daemon` does a bare `await import('@clearly-sh/beehaven-core/server')`
+   * with no fallback. The monorepo resolves that through a workspace symlink; the standalone
+   * install does NOT have the package at all — so local agent minting fails there with
+   * "Cannot find package", which surfaces to a user as "Could not mint identity. Is the
+   * daemon running?" — a message about the wrong thing entirely.
+   *
+   * Copying dist without this leaves an install whose daemon cannot mint. So the sync links
+   * it, from the monorepo that just built it. Safe by construction: this whole script only
+   * runs on a machine that has BOTH an install and this source tree.
+   */
+  const coreSrc = join(pkgRoot, '..', 'core');
+  const scopeDir = join(installed, 'node_modules', '@clearly-sh');
+  if (existsSync(coreSrc)) {
+    try {
+      mkdirSync(scopeDir, { recursive: true });
+      const link = join(scopeDir, 'beehaven-core');
+      rmSync(link, { recursive: true, force: true });
+      symlinkSync(coreSrc, link, 'dir');
+    } catch (e) {
+      console.error(`  postbuild: could not link @clearly-sh/beehaven-core (${e?.message ?? e})`);
+    }
+  }
+
+  // VERIFY BEFORE CLAIMING. A sync that leaves a CLI which cannot start is worse than a stale
+  // one, because the staleness at least still works. Run the synced entry point; if it can't
+  // even print its version, say so loudly rather than reporting success.
+  try {
+    execFileSync(process.execPath, [join(distDst, 'cli.js'), '--version'], { stdio: 'pipe', timeout: 20_000 });
+  } catch (e) {
+    console.error('  postbuild: SYNCED BUILD DOES NOT RUN — the installed CLI may be broken.');
+    console.error(`             ${String(e?.stderr ?? e?.message ?? e).slice(0, 300)}`);
+    process.exit(0);
+  }
+
+  // A marker the CLI can read to say WHERE the installed bytes came from, so
+  // `beehaven --version` on the installed copy can name its origin instead of implying it is
+  // a release.
+  writeFileSync(
+    join(installed, '.synced-from'),
+    JSON.stringify({ from: pkgRoot, at: new Date().toISOString() }, null, 2),
+  );
+  console.log(`  postbuild: synced → ${installed}`);
+  console.log(`             Verify selection with \`beehaven --version\`; an equal/newer Mac bundle may still win.`);
+} catch (err) {
+  // Never fail the build over this. A stale install is a nuisance; a red build over a copy
+  // is worse, and the runtime staleness warning still catches the case.
+  console.error(`  postbuild: sync failed (${err?.message ?? err}) — installed copy may be stale.`);
+}