beehaven 0.8.27 → 0.8.33

package/dist/ipc-path.js

@@ -0,0 +1,92 @@
+/**
+ * ipc-path — where the daemon's local sockets live, on every platform (CAN2-56).
+ *
+ * ⚠⚠ THE ONE PLACE A SOCKET ADDRESS IS DECIDED. `/tmp/beehaven-ipc.sock` was typed out in five CLI
+ * files (server, three clients, the claude bridge) and `/tmp/beehaven.sock` in two more, each
+ * gating its connect on `existsSync`, unlinking stale files and chmod-ing to 0600. On Windows none
+ * of that works: Node's `net` listens on a NAMED PIPE (`\\.\pipe\…`), there is no `/tmp`, a pipe is
+ * not a file you can stat, unlink or chmod — so the daemon could not bind and no client could
+ * reach it. Every caller now asks this module, and the Unix addresses are byte-for-byte unchanged
+ * (the Mac app, the mwah CLI and the Electron daemon client still dial `/tmp/beehaven-ipc.sock`).
+ *
+ * ⚠ A PIPE NAME IS MACHINE-GLOBAL, so it carries the user name: two people signed in to one
+ * Windows machine get two daemons, as two Unix users do. Same-user is still the boundary that
+ * matters, and the IPC auth token (`ipc-auth.ts`) is what gates verbs on both platforms — the
+ * Unix 0600 mode is defense in depth that a pipe does not have a file-mode equivalent for.
+ *
+ * ⚠ `$BEEHAVEN_IPC_SOCKET` / `$BEEHAVEN_WATCHER_SOCKET` override the address for BOTH ends (server
+ * and clients), so a test can stand a real daemon and a real client on a private path. Read at call
+ * time, not import time, for the same reason.
+ */
+import { existsSync, unlinkSync, chmodSync, statSync } from 'fs';
+import { tmpdir, userInfo } from 'os';
+import { join } from 'path';
+export const UNIX_IPC_SOCKET = '/tmp/beehaven-ipc.sock';
+export const UNIX_WATCHER_SOCKET = '/tmp/beehaven.sock';
+export const UNIX_EVENTS_FILE = '/tmp/beehaven-events.jsonl';
+/** `\\.\pipe\…` or `\\?\pipe\…` — the forms Node accepts for a Windows named pipe. */
+export function isNamedPipe(p) {
+    return /^\\\\[.?]\\pipe\\/i.test(p);
+}
+/** The signed-in user's name, made safe for a pipe name. */
+function pipeUser(env) {
+    let name = '';
+    try {
+        name = userInfo().username;
+    }
+    catch { /* no passwd entry / sandbox */ }
+    if (!name)
+        name = env.USERNAME || env.USER || 'user';
+    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, '_').slice(0, 64) || 'user';
+}
+const pipe = (name, env) => `\\\\.\\pipe\\${name}-${pipeUser(env)}`;
+/** The daemon's IPC address: the Unix socket, or this user's named pipe on Windows. */
+export function ipcSocketPath(platform = process.platform, env = process.env) {
+    if (env.BEEHAVEN_IPC_SOCKET)
+        return env.BEEHAVEN_IPC_SOCKET;
+    return platform === 'win32' ? pipe('beehaven-ipc', env) : UNIX_IPC_SOCKET;
+}
+/** The Claude Code event watcher's HTTP-over-socket address. */
+export function watcherSocketPath(platform = process.platform, env = process.env) {
+    if (env.BEEHAVEN_WATCHER_SOCKET)
+        return env.BEEHAVEN_WATCHER_SOCKET;
+    return platform === 'win32' ? pipe('beehaven-watcher', env) : UNIX_WATCHER_SOCKET;
+}
+/** The watcher's JSONL fallback file. Windows has no `/tmp`; its temp dir is per-user already. */
+export function eventsFilePath(platform = process.platform) {
+    return platform === 'win32' ? join(tmpdir(), 'beehaven-events.jsonl') : UNIX_EVENTS_FILE;
+}
+/**
+ * Could a listener be at `p`? A socket FILE can be checked without touching it. A named pipe
+ * cannot: it exists only while a server holds it, and probing it with a filesystem call opens an
+ * instance of it. So a pipe answers `true` and the connect attempt decides (`ENOENT` = nothing).
+ */
+export function socketMayExist(p) {
+    return isNamedPipe(p) || existsSync(p);
+}
+/** Remove a stale socket file before binding. A named pipe leaves nothing behind to remove. */
+export function clearStaleSocket(p) {
+    if (isNamedPipe(p))
+        return;
+    try {
+        if (existsSync(p))
+            unlinkSync(p);
+    }
+    catch { /* already gone */ }
+}
+/**
+ * Restrict a freshly bound socket file to its owner (0600) and report the mode it really has.
+ * `applicable: false` for a named pipe, which has no file mode — its boundary is the per-user name
+ * plus the IPC token.
+ */
+export function restrictSocketToOwner(p) {
+    if (isNamedPipe(p))
+        return { applicable: false, mode: null };
+    try {
+        chmodSync(p, 0o600);
+        return { applicable: true, mode: statSync(p).mode & 0o777 };
+    }
+    catch (err) {
+        return { applicable: true, mode: null, error: String(err?.code ?? err?.message ?? err) };
+    }
+}

package/dist/ipc-server.js

@@ -2,7 +2,7 @@
  * IPC Server — bidirectional Unix socket for local clients (Electron, CLI tools).
  *
  * Provides request-response RPCs and broadcast subscriptions over a line-based
- * JSON protocol on /tmp/beehaven-ipc.sock.
+ * JSON protocol on /tmp/beehaven-ipc.sock (a per-user named pipe on Windows — see ipc-path.ts).
  *
  * Local clients send messages to the daemon, which forwards them to the DO
  * via the relay WebSocket. DO responses and broadcasts are forwarded back
@@ -24,10 +24,11 @@
  *   { "type": "status", "connected": true, "daemonPid": 1234 }
  */
 import { createConnection, createServer } from 'net';
-import { existsSync, unlinkSync, chmodSync, statSync } from 'fs';
 import { EventEmitter } from 'events';
 import { resolveAuthScope } from './ipc-auth.js';
-const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+import { ipcSocketPath, socketMayExist, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+/** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
+const IPC_SOCKET_PATH = ipcSocketPath();
 /**
  * Message types the daemon will process without authentication.
  *
@@ -114,9 +115,10 @@ export function actionChain(action, input, depth = 0) {
  */
 function probeIpcSocket(timeoutMs = 400) {
     return new Promise((resolve) => {
-        if (!existsSync(IPC_SOCKET_PATH))
+        const path = ipcSocketPath();
+        if (!socketMayExist(path))
             return resolve(false);
-        const client = createConnection(IPC_SOCKET_PATH);
+        const client = createConnection(path);
         const done = (alive) => {
             try {
                 client.destroy();
@@ -138,6 +140,8 @@ function probeIpcSocket(timeoutMs = 400) {
 export { probeIpcSocket };
 export class IpcServer extends EventEmitter {
     server = null;
+    /** The address this server bound (resolved at `start`, so an env override set before start applies). */
+    path = null;
     clients = new Map();
     clientCounter = 0;
     virtualClientCounter = 0;
@@ -157,12 +161,10 @@ export class IpcServer extends EventEmitter {
      * at this point; a live server would have been caught upstream.
      */
     start() {
-        // Clean up stale socket
-        try {
-            if (existsSync(IPC_SOCKET_PATH))
-                unlinkSync(IPC_SOCKET_PATH);
-        }
-        catch { }
+        // Clean up a stale socket file (a named pipe leaves none).
+        const path = ipcSocketPath();
+        this.path = path;
+        clearStaleSocket(path);
         this.server = createServer((socket) => {
             const clientId = `ipc_${++this.clientCounter}`;
             // Connections start unauthenticated and scope=null. The client must
@@ -235,7 +237,7 @@ export class IpcServer extends EventEmitter {
         // process-wide umask — umask changes are global and race with any
         // other mkdirSync / writeFileSync happening in parallel (e.g.
         // LocalHive pre-creating building data dirs during startup).
-        this.server.listen(IPC_SOCKET_PATH, () => {
+        this.server.listen(path, () => {
             /**
              * ⚠⚠ CHMOD, THEN **VERIFY**. This was `chmodSync(…, 0o600)` inside an empty `catch {}`, and
              * the mode it claims has been wrong on every start measured: the live socket comes up
@@ -266,19 +268,18 @@ export class IpcServer extends EventEmitter {
              * was learned once and not applied here. Import at the top; never reach for `require` in this
              * package.
              */
-            let mode = null;
-            try {
-                chmodSync(IPC_SOCKET_PATH, 0o600);
-                mode = statSync(IPC_SOCKET_PATH).mode & 0o777;
-            }
-            catch (err) {
-                console.warn(`[ipc] SECURITY: could not set 0600 on ${IPC_SOCKET_PATH} — ${err?.code ?? err?.message ?? err}`);
+            // A Windows named pipe has no file mode (`applicable: false`): its boundary is the per-user
+            // pipe name plus the IPC token — see `ipc-path.ts`.
+            const restricted = restrictSocketToOwner(path);
+            const mode = restricted.mode;
+            if (restricted.error) {
+                console.warn(`[ipc] SECURITY: could not set 0600 on ${path} — ${restricted.error}`);
             }
             if (mode !== null && mode !== 0o600) {
                 console.warn(`[ipc] SECURITY: socket mode is 0${mode.toString(8)}, expected 0600. Other-user connect is still `
                     + `blocked (no write bit), but the documented guarantee does not hold — do not weaken it further.`);
             }
-            console.log(`[ipc] Listening on ${IPC_SOCKET_PATH}${mode !== null ? ` (mode 0${mode.toString(8)})` : ''}`);
+            console.log(`[ipc] Listening on ${path}${mode !== null ? ` (mode 0${mode.toString(8)})` : ''}`);
         });
         this.server.on('error', (err) => {
             console.warn(`[ipc] Server error: ${err.message}`);
@@ -295,11 +296,7 @@ export class IpcServer extends EventEmitter {
             this.server.close();
             this.server = null;
         }
-        try {
-            if (existsSync(IPC_SOCKET_PATH))
-                unlinkSync(IPC_SOCKET_PATH);
-        }
-        catch { }
+        clearStaleSocket(this.path ?? ipcSocketPath());
     }
     /** Broadcast a message from the DO to all subscribed local clients */
     /**
@@ -605,20 +602,23 @@ export class IpcServer extends EventEmitter {
     // IPC bus so the same pipeline/app-rpc handlers serve both Claude and
     // the human UI.
     /** Register a virtual client and return its id. */
-    createVirtualClient(virtualSend, initialSubscriptions = ['*']) {
+    createVirtualClient(virtualSend, initialSubscriptions = ['*'], scope = null) {
         const id = `virt_${++this.virtualClientCounter}`;
+        /**
+         * ⚠⚠ A VIRTUAL CLIENT IS ONLY AS TRUSTED AS WHOEVER IS ON THE OTHER END OF IT (CAN2-64).
+         * This used to be `authenticated: true, scope: 'developer'` for everyone, justified by "the
+         * dashboard bridge enforces its own auth (session cookie, origin check)". It enforced none,
+         * so any web page that opened ws://127.0.0.1:9800/apps/ws could call get-token. The bridge
+         * now judges the connection (dashboard.ts `appBridgeTrust`) and passes 'consumer' or null;
+         * a null client must authenticate with the IPC token, exactly like a socket client.
+         */
         const client = {
             id,
             virtualSend,
             subscriptions: initialSubscriptions,
             buffer: '',
-            // Virtual clients are in-process — they're already inside the trust
-            // boundary. The dashboard /apps/ws bridge enforces its own auth
-            // (session cookie, origin check) before creating the virtual client,
-            // so we hand them developer scope to mirror what a logged-in tray
-            // user can already do.
-            authenticated: true,
-            scope: 'developer',
+            authenticated: scope !== null,
+            scope,
         };
         this.clients.set(id, client);
         // Mimic the on-connect status frame real clients receive so the bridge

package/dist/npm-update.js

@@ -0,0 +1,138 @@
+/**
+ * npm-update — updating a CLI that was installed with `npm install -g` (CAN2-57).
+ *
+ * ⚠⚠ npm IS THE ONLY WINDOWS INSTALL, AND IT NEVER UPDATED. The daemon's hourly updater re-runs the
+ * bash `install.sh`, so it served only `~/.beehaven/cli` installs; `beehaven update` refused npm
+ * installs and printed the npm command instead. A Windows user stayed on whatever version they
+ * first installed until they noticed the notice. Both paths now call this module.
+ *
+ * ⚠ IT UPDATES THE COPY THAT IS RUNNING, OR NOTHING. The npm that sits beside the running Node is
+ * asked for its global root; if this package is not the one installed there (an npx run, a second
+ * Node, a copied folder), installing would create a SECOND copy that shadows or is shadowed by
+ * this one — the failure `self-update.ts` documents for curl installs. So it refuses and says why.
+ *
+ * ⚠ A GLOBAL PREFIX THE USER CANNOT WRITE IS NOT "TRY sudo". Windows (`%AppData%\npm`) and
+ * Homebrew/nvm prefixes are user-writable; a system `/usr/local` usually is not, and an unattended
+ * daemon must never escalate. Not writable → the one-line manual command, nothing else.
+ *
+ * ⚠ THE EXACT VERSION, NOT `@latest`. The caller passes the version from the release manifest
+ * (`latest.json`, stable only), so the channel is decided by our publish script, never by a dist
+ * tag someone moved by hand.
+ */
+import { execFile, execFileSync } from 'child_process';
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+export const PACKAGE = '@clearlysh/beehaven';
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** The npm that belongs to the Node running this process, else whatever `npm` is on PATH. */
+export function npmCommand(platform = process.platform, execPath = process.execPath) {
+    const local = join(dirname(execPath), platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(local) ? local : platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+/** Windows `.cmd` shims cannot be spawned without a shell (Node refuses with EINVAL since 18.20/20.12). */
+const needsShell = (cmd) => /\.cmd$/i.test(cmd);
+const quoteForShell = (s) => (/[\s"&|<>^]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+/** Run npm synchronously; returns stdout. Never inside the package directory (Windows rename locks). */
+function npmSync(npm, args, timeoutMs) {
+    const shell = needsShell(npm);
+    return execFileSync(shell ? quoteForShell(npm) : npm, args, {
+        encoding: 'utf8',
+        cwd: homedir(),
+        timeout: timeoutMs,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell,
+        windowsHide: true,
+    });
+}
+/**
+ * Can this install update itself with npm? `pkgRoot` is the running package's root (the folder
+ * holding its package.json).
+ */
+export function npmUpdatePlan(pkgRoot, platform = process.platform) {
+    const npm = npmCommand(platform);
+    let globalRoot;
+    try {
+        globalRoot = npmSync(npm, ['root', '-g'], 30_000).trim();
+    }
+    catch (e) {
+        return { ok: false, npm, reason: `npm is not available (${String(e?.code ?? e?.message ?? e).slice(0, 80)})` };
+    }
+    const real = (p) => { try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    } };
+    const installed = join(globalRoot, ...PACKAGE.split('/'));
+    if (real(installed).toLowerCase() !== real(pkgRoot).toLowerCase()) {
+        return { ok: false, npm, globalRoot, reason: `this copy (${pkgRoot}) is not npm's global install (${installed})` };
+    }
+    try {
+        accessSync(globalRoot, constants.W_OK);
+        accessSync(installed, constants.W_OK);
+    }
+    catch {
+        return { ok: false, npm, globalRoot, reason: `npm's global folder is not writable by you (${globalRoot})` };
+    }
+    return { ok: true, npm, globalRoot };
+}
+/** The version npm's global install of this package reports, read from disk. */
+export function installedNpmVersion(globalRoot) {
+    try {
+        return JSON.parse(readFileSync(join(globalRoot, ...PACKAGE.split('/'), 'package.json'), 'utf8')).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The newest published version, from npm (for `beehaven update`; the daemon uses the release manifest). */
+export function latestNpmVersion(npm) {
+    try {
+        const v = npmSync(npm, ['view', PACKAGE, 'version', '--registry=https://registry.npmjs.org'], 30_000).trim();
+        return VERSION_RE.test(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The arguments that install exactly `version` globally — exported so the shape is pinned. */
+export function npmInstallArgs(version) {
+    if (!VERSION_RE.test(version))
+        throw new Error(`not a release version: ${version}`);
+    return ['install', '-g', `${PACKAGE}@${version}`, '--no-audit', '--no-fund', '--registry=https://registry.npmjs.org'];
+}
+/** Install `version` (blocking — the CLI's `update`). Verifies what landed on disk. */
+export function installNpmVersionSync(plan, version) {
+    if (!plan.ok || !plan.globalRoot)
+        return { ok: false, message: plan.reason ?? 'npm update not possible here' };
+    try {
+        npmSync(plan.npm, npmInstallArgs(version), 5 * 60_000);
+    }
+    catch (e) {
+        const detail = String(e?.stderr || e?.message || e).trim().split('\n').slice(-3).join(' ').slice(0, 240);
+        return { ok: false, message: `npm install failed: ${detail}` };
+    }
+    const got = installedNpmVersion(plan.globalRoot);
+    return got === version
+        ? { ok: true, message: `Updated to ${version}.` }
+        : { ok: false, message: `npm reported success but ${got ?? 'nothing'} is installed, not ${version}.` };
+}
+/** Install `version` without blocking the event loop (the daemon's hourly updater). */
+export function installNpmVersion(plan, version) {
+    return new Promise((resolveP) => {
+        if (!plan.ok || !plan.globalRoot)
+            return resolveP({ ok: false, message: plan.reason ?? 'npm update not possible here' });
+        const shell = needsShell(plan.npm);
+        execFile(shell ? quoteForShell(plan.npm) : plan.npm, npmInstallArgs(version), {
+            cwd: homedir(), timeout: 5 * 60_000, shell, windowsHide: true,
+        }, (err, _out, stderr) => {
+            if (err)
+                return resolveP({ ok: false, message: `npm install failed: ${String(stderr || err.message).trim().split('\n').slice(-3).join(' ').slice(0, 240)}` });
+            const got = installedNpmVersion(plan.globalRoot);
+            resolveP(got === version
+                ? { ok: true, message: `Updated to ${version}.` }
+                : { ok: false, message: `npm reported success but ${got ?? 'nothing'} is installed, not ${version}.` });
+        });
+    });
+}

package/dist/relay-presets.js

@@ -67,9 +67,8 @@ export function resolveRelaySelection(cfg) {
  *   `https://localhost:3000` (canvas.ts's `--dev` branch). They are not interchangeable: the apex
  *   301s to www, so the apex spelling handed people a link with a redirect in it.
  *
- * ⚠ STAGING RETURNS THE PRODUCTION SITE, AND THAT IS CORRECT. The frontend is prod-only — the
- * `staging.clearly-sh.pages.dev` alias is retired (CLAUDE.md) — so the staging worker's app really
- * is `www.clearly.sh`. Inventing a `staging.clearly.sh` here would be the dead-link bug again.
+ * Staging uses the local HTTPS frontend (Clearly AGENTS.md, 2026-10-08). Its workspace IDs
+ * belong to staging and must never be linked into the production frontend.
  *
  * ⚠ `custom` RETURNS undefined, DELIBERATELY. A custom relay says nothing about where its frontend
  * is, and guessing production for it is how you hand someone a link into the wrong deployment.
@@ -78,10 +77,10 @@ export function resolveRelaySelection(cfg) {
 export function appOriginForEnv(envName) {
     switch (envName) {
         case 'prod':
-        case 'staging':
             return 'https://www.clearly.sh';
         // `npm run dev` is `next dev --experimental-https`, so the local app is HTTPS, not HTTP.
         case 'dev':
+        case 'staging':
             return 'https://localhost:3000';
         default:
             return undefined;

package/dist/setup-service.js

@@ -391,8 +391,12 @@ export async function cleanupAll() {
     }
     // 3. Socket + event log
     const { existsSync, unlinkSync, readdirSync, rmSync, readFileSync, writeFileSync } = await import('node:fs');
-    const { join } = await import('node:path');
-    for (const p of ['/tmp/beehaven.sock', '/tmp/beehaven-ipc.sock', '/tmp/beehaven-events.jsonl']) {
+    const { join, dirname } = await import('node:path');
+    const { watcherSocketPath, ipcSocketPath, eventsFilePath, isNamedPipe } = await import('./ipc-path.js');
+    const eventsFile = eventsFilePath();
+    for (const p of [watcherSocketPath(), ipcSocketPath(), eventsFile]) {
+        if (isNamedPipe(p))
+            continue; // a Windows pipe disappears with the daemon that held it
         try {
             if (existsSync(p)) {
                 unlinkSync(p);
@@ -402,10 +406,11 @@ export async function cleanupAll() {
         catch { }
     }
     try {
-        for (const f of readdirSync('/tmp')) {
+        const eventsDir = dirname(eventsFile);
+        for (const f of readdirSync(eventsDir)) {
             if (f.startsWith('beehaven-events.jsonl.') && f.endsWith('.old')) {
                 try {
-                    unlinkSync(join('/tmp', f));
+                    unlinkSync(join(eventsDir, f));
                 }
                 catch { }
             }

package/dist/verb-surface.js

@@ -60,6 +60,7 @@ export const VERB_SURFACE = {
     logout: { cls: 'STRUCTURAL', why: 'clears local credentials' },
     signup: { cls: 'STRUCTURAL', why: 'opens a browser' },
     handoff: { cls: 'STRUCTURAL', why: 'posts a local file to the anonymous door; no account, no workspace' },
+    'agents-md': { cls: 'STRUCTURAL', why: "writes the Clearly block into this repo's AGENTS.md; no workspace" },
     whoami: { cls: 'STRUCTURAL', why: 'reads local credentials' },
     start: { cls: 'STRUCTURAL', why: 'spawns the daemon `call` needs' },
     stop: { cls: 'STRUCTURAL', why: 'daemon lifecycle' },

package/dist/watcher.js

@@ -1,18 +1,19 @@
 // ============================================================================
 // Beehaven Office - Claude Code Event Watcher
-// Primary: Unix domain socket HTTP server at /tmp/beehaven.sock
+// Primary: HTTP server on a local socket — /tmp/beehaven.sock, or a named pipe on Windows (ipc-path.ts)
 // Fallback: Watches the JSONL events file written by the hook script
 // ============================================================================
 // chokidar is imported lazily so a missing bundle (e.g. when the daemon ships
 // inside an Electron app whose node_modules layout doesn't include chokidar)
 // degrades the file-watcher to a no-op rather than crashing the whole daemon.
 // The primary Unix-socket path does not depend on chokidar.
-import { createReadStream, existsSync, writeFileSync, statSync, renameSync, unlinkSync, chmodSync, watch as fsWatch, } from 'fs';
+import { createReadStream, existsSync, writeFileSync, statSync, renameSync, chmodSync, watch as fsWatch, } from 'fs';
 import { createInterface } from 'readline';
 import { createServer } from 'http';
 import { EventEmitter } from 'events';
-const EVENTS_FILE = '/tmp/beehaven-events.jsonl';
-const SOCKET_PATH = '/tmp/beehaven.sock';
+import { watcherSocketPath, eventsFilePath, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+const EVENTS_FILE = eventsFilePath();
+const SOCKET_PATH = watcherSocketPath();
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
 export { SOCKET_PATH };
 export class ClaudeWatcher extends EventEmitter {
@@ -32,14 +33,8 @@ export class ClaudeWatcher extends EventEmitter {
     // ── Unix Domain Socket ───────────────────────────────────────────────
     /** Start HTTP server on Unix domain socket for direct event delivery */
     startSocket() {
-        // Remove stale socket file
-        try {
-            if (existsSync(SOCKET_PATH))
-                unlinkSync(SOCKET_PATH);
-        }
-        catch {
-            /* may not exist */
-        }
+        // Remove a stale socket file (a Windows named pipe leaves none)
+        clearStaleSocket(SOCKET_PATH);
         this.socketServer = createServer((req, res) => {
             if (req.method !== 'POST' || req.url !== '/event') {
                 res.writeHead(404);
@@ -71,10 +66,7 @@ export class ClaudeWatcher extends EventEmitter {
         // during startup). A post-bind chmod achieves the same security
         // without the race.
         this.socketServer.listen(SOCKET_PATH, () => {
-            try {
-                chmodSync(SOCKET_PATH, 0o600);
-            }
-            catch { }
+            restrictSocketToOwner(SOCKET_PATH); // no-op for a named pipe
             console.log(`[watcher] Socket listening on ${SOCKET_PATH}`);
         });
     }
@@ -84,13 +76,7 @@ export class ClaudeWatcher extends EventEmitter {
             this.socketServer.close();
             this.socketServer = null;
         }
-        try {
-            if (existsSync(SOCKET_PATH))
-                unlinkSync(SOCKET_PATH);
-        }
-        catch {
-            /* may already be gone */
-        }
+        clearStaleSocket(SOCKET_PATH);
     }
     // ── File Watcher (fallback) ──────────────────────────────────────────
     /** Start file watcher as fallback for when socket isn't available */

package/dist/windows-hide.js

@@ -0,0 +1,77 @@
+/**
+ * windows-hide — no console windows flashing open on Windows (CAN2-56).
+ *
+ * ⚠⚠ WHY WINDOWS FLASHED. A Windows process with no console of its own — the detached daemon,
+ * or `beehaven` run by an agent or an app rather than in a terminal — that starts a CONSOLE
+ * program (cmd.exe for every `exec`/`execSync`, powershell, git, node, …) makes Windows create a
+ * brand-new console window for that child. It pops up and closes as the child exits: one flash per
+ * call, and the daemon makes calls on timers. Node prevents it per call with `windowsHide: true`;
+ * the CLI had ~140 child-process calls and one of them set it.
+ *
+ * ⚠ ONE CHOKEPOINT, NOT 140 CALL SITES. Imported FIRST by every entry point (`cli.ts`,
+ * `clearly.ts`, `daemon-entry.ts`), this wraps the `child_process` functions so `windowsHide`
+ * defaults to true for every caller in the process — this package, `@beehaven/core`, and any
+ * dependency — and `syncBuiltinESMExports()` makes ESM named imports (`import { spawn } …`) see
+ * the wrappers too. An explicit `windowsHide: false` is respected. Off Windows it does nothing.
+ *
+ * ⚠ `exec` / `execFile` carry `util.promisify.custom` (so `promisify(exec)` resolves
+ * `{ stdout, stderr }`). The wrappers forward it; without that, every `promisify(exec)` caller
+ * would silently start receiving a bare string.
+ */
+import { createRequire, syncBuiltinESMExports } from 'node:module';
+import { promisify } from 'node:util';
+const require = createRequire(import.meta.url);
+const MARK = Symbol.for('beehaven.windowsHide');
+/**
+ * A child_process call's arguments with `windowsHide: true` set, unless the caller chose a value.
+ * `takesArgv` = the second parameter may be an argv array (spawn, spawnSync, execFile,
+ * execFileSync, fork). Pure — exported for tests.
+ */
+export function withWindowsHide(args, takesArgv) {
+    const a = [...args];
+    for (let i = 1; i < a.length; i++) {
+        const v = a[i];
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            if (v.windowsHide === undefined)
+                a[i] = { ...v, windowsHide: true };
+            return a;
+        }
+    }
+    // No options object: it goes after the command (and its argv array), before any callback. An
+    // explicit `undefined`/`null` options slot is filled rather than shifted.
+    const at = takesArgv && Array.isArray(a[1]) ? 2 : 1;
+    if (at < a.length && (a[at] === undefined || a[at] === null))
+        a[at] = { windowsHide: true };
+    else
+        a.splice(at, 0, { windowsHide: true });
+    return a;
+}
+const WRAPPED = [
+    ['spawn', true], ['spawnSync', true], ['execFile', true], ['execFileSync', true], ['fork', true],
+    ['exec', false], ['execSync', false],
+];
+/** Wrap `child_process` once per process. Returns whether it is installed. `force` is for tests. */
+export function installWindowsHide(opts = {}) {
+    if (process.platform !== 'win32' && !opts.force)
+        return false;
+    const cp = require('node:child_process');
+    if (cp[MARK])
+        return true;
+    for (const [name, takesArgv] of WRAPPED) {
+        const orig = cp[name];
+        if (typeof orig !== 'function')
+            continue;
+        const wrapper = function (...args) {
+            return orig.apply(this, withWindowsHide(args, takesArgv));
+        };
+        const custom = orig[promisify.custom];
+        if (typeof custom === 'function') {
+            wrapper[promisify.custom] = (...args) => custom.apply(orig, withWindowsHide(args, takesArgv));
+        }
+        cp[name] = wrapper;
+    }
+    cp[MARK] = true;
+    syncBuiltinESMExports();
+    return true;
+}
+installWindowsHide();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beehaven",
-  "version": "0.8.27",
+  "version": "0.8.33",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/scripts/sync-skills.mjs

@@ -40,6 +40,12 @@ const SOURCES = {
   'codebase-map':   'apps/mcp-server/plugin/skills/codebase-map/SKILL.md',
   'clearly-workspace': 'apps/mcp-server/plugin/skills/clearly-workspace/SKILL.md',
   'clearly-agent':     'apps/mcp-server/plugin/skills/clearly-agent/SKILL.md',
+  // CAN2-57 — the rest of the plugin's skills: one set across plugin, CLI and Mac app.
+  'visualize':         'apps/mcp-server/plugin/skills/visualize/SKILL.md',
+  'sticker-pack':      'apps/mcp-server/plugin/skills/sticker-pack/SKILL.md',
+  'clearly-docs':      'apps/mcp-server/plugin/skills/clearly-docs/SKILL.md',
+  'clearly-init':      'apps/mcp-server/plugin/skills/clearly-init/SKILL.md',
+  'clearly-workflows': 'apps/mcp-server/plugin/skills/clearly-workflows/SKILL.md',
 };
 
 let missing = 0;

package/skills/agent-doodle-space/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-doodle-space
-description: Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
 ---
 
 # Agent Soul + Doodle Space

package/skills/agent-home/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-home
-description: Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
 ---
 
 # Agent Home memory apartment

package/skills/beehaven-cli/SKILL.md

@@ -25,6 +25,18 @@ beehaven cd home                   # back to the default workspace
 beehaven disconnect                # end the session
 ```
 
+Start discovery narrowly: `beehaven explain <action>` gives one schema; `beehaven actions
+--search <term>` or `--category <name>` bounds the inventory. The default inventory is compact;
+`--verbose` or `--format full --json` requests full detail. Save large JSON once and print a
+small summary rather than repeating a call after output truncation.
+
+For ticket text search use `ticket-list {text:"…",projectId?,fields?,limit?}` (`query` and `q`
+are aliases). For a design setup, `design-start {title,projectId?,boardId?,idempotencyKey}` creates or
+resumes the linked artifacts using the normal permissions. Preserve idempotencyKey across retries;
+requestId is reserved by the transport.
+For supported canvas mutations inspect actual `updated` IDs, `outcome`, ignored/rejected fields
+and warnings. A navigation request reaching a socket is not a verified editor display.
+
 Once `cd`'d, **every** verb auto-routes to that target: `actions`, `call`, `sql`, `ls`, `cat`, `tree`, `grep`, `watch`, `logs`, `workspace`, `ask`. Switch by `cd`-ing again.
 
 ```bash