beehaven 0.8.29 → 0.8.34

package/dist/daemon.js

@@ -13,6 +13,8 @@ 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 { ipcSocketPath } from './ipc-path.js';
+import { isBeehavenCommandLine, windowsNodeProcesses, selectWindowsDaemons } from './daemon-process.js';
 import { mintIpcAuthTokens, clearIpcAuthToken } from './ipc-auth.js';
 /**
  * What THIS daemon minted, so shutdown can avoid scrubbing a successor's token.
@@ -44,6 +46,7 @@ import { homedir, tmpdir } from 'os';
 import { join, dirname, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { compareVersions, usableUpdateDigest } from './version-utils.js';
+import { npmUpdatePlan, installNpmVersion } from './npm-update.js';
 import { installKind } from './commands/self-update.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = join(homedir(), '.beehaven');
@@ -961,9 +964,85 @@ function updatesAreManagedExternally() {
  *
  * ⚠ NOTHING ELSE CALLS IT. The daemon's timer is still the only production caller.
  */
+/** Said once per daemon, not hourly — see the managed-updates note below. */
+let announcedNpmUpdateBlocked = false;
+/**
+ * Start the freshly installed version and leave (shared by the curl and npm update paths).
+ * A CLI-spawned headless daemon is detached, with no supervisor to interpret exit 75, so it starts
+ * the new entry in a helper that waits until this process releases the IPC socket.
+ */
+async function restartForUpdate() {
+    if (process.env.BEEHAVEN_CLI_OWNED_DAEMON === '1') {
+        const child = spawn(process.execPath, [join(__dirname, 'daemon-entry.js'), '--restart-after-update', String(process.pid)], {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env,
+        });
+        child.on('error', (error) => console.error(`  [update] Restart helper failed: ${error.message}`));
+        if (!child.pid)
+            throw new Error('could not start update restart helper');
+        child.unref();
+    }
+    if (daemonRelay?.isConnected())
+        await new Promise((r) => setTimeout(r, 500));
+    process.exit(75);
+}
+/**
+ * ⚠⚠ npm INSTALLS (THE ONLY WINDOWS INSTALL) NEVER AUTO-UPDATED (CAN2-57). This routine re-ran the
+ * bash installer, so it skipped every npm install and a Windows user stayed on their first version.
+ * They now update with npm itself — to the version the release manifest names (stable only) — when
+ * this copy IS npm's global install and its folder is writable; otherwise one line says why and
+ * what to run. No rollback file: `install.sh` cannot reinstall an npm package; a bad release is
+ * undone with `npm install -g @clearlysh/beehaven@<previous>`.
+ */
+async function checkAndAutoUpdateNpm() {
+    // A headless daemon's stdout goes nowhere, so the update story also goes to daemon.log.
+    const say = (m, level = 'info') => {
+        (level === 'error' ? console.error : console.log)(`  [update] ${m}`);
+        try {
+            logger[level]('daemon', `[update] ${m}`);
+        }
+        catch { /* logging never blocks an update */ }
+    };
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const res = await fetch(LATEST_MANIFEST, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return;
+        const latest = (await res.json())?.version;
+        if (typeof latest !== 'string')
+            return;
+        const current = getCurrentVersion();
+        if (compareVersions(latest, current) <= 0)
+            return;
+        const plan = npmUpdatePlan(join(__dirname, '..'));
+        if (!plan.ok) {
+            if (!announcedNpmUpdateBlocked) {
+                announcedNpmUpdateBlocked = true;
+                say(`${latest} is available, but this npm install cannot update itself: ${plan.reason}. Run: npm install -g @clearlysh/beehaven@latest`);
+            }
+            return;
+        }
+        say(`Updating ${current} → ${latest} with npm...`);
+        const r = await installNpmVersion(plan, latest);
+        if (!r.ok)
+            throw new Error(r.message);
+        if (getCurrentVersion() !== latest)
+            throw new Error(`npm did not install ${latest}`);
+        say(`Updated to v${latest} — restarting...`);
+        await restartForUpdate();
+    }
+    catch (error) {
+        say(`Update failed: ${error?.message ?? error}`, 'error');
+    }
+}
 export async function checkAndAutoUpdate() {
     const owner = updatesAreManagedExternally();
     const runningKind = installKind(join(__dirname, 'daemon-entry.js'));
+    if (!owner && runningKind === 'npm')
+        return checkAndAutoUpdateNpm();
     if (owner || runningKind !== 'user') {
         // Said once at startup, not hourly — a line every hour about a thing that is working as
         // designed is how a log stops being read.
@@ -1015,19 +1094,6 @@ export async function checkAndAutoUpdate() {
             throw new Error(`installer did not install ${latest}`);
         }
         console.log(`  [update] Updated to v${latest} — restarting...`);
-        if (process.env.BEEHAVEN_CLI_OWNED_DAEMON === '1') {
-            // A CLI-spawned headless daemon is detached, with no supervisor to interpret exit 75.
-            // Start the new entry in a helper that waits until this process releases the IPC socket.
-            const child = spawn(process.execPath, [join(__dirname, 'daemon-entry.js'), '--restart-after-update', String(process.pid)], {
-                detached: true,
-                stdio: 'ignore',
-                env: process.env,
-            });
-            child.on('error', (error) => console.error(`  [update] Restart helper failed: ${error.message}`));
-            if (!child.pid)
-                throw new Error('could not start update restart helper');
-            child.unref();
-        }
         // Drop the temp tarball BEFORE exiting. `process.exit` skips `finally`,
         // so cleaning up only there would leak the whole release into /tmp on every
         // SUCCESSFUL update — the one path that always runs.
@@ -1044,13 +1110,9 @@ export async function checkAndAutoUpdate() {
             catch { }
             installerPath = null;
         }
-        // Give relay a moment to flush
-        if (daemonRelay?.isConnected()) {
-            await new Promise((r) => setTimeout(r, 500));
-        }
-        // Exit with non-zero so launchd/systemd restarts with the new version
-        // (KeepAlive > SuccessfulExit > false means exit 0 stays down)
-        process.exit(75);
+        // Start the new version and exit non-zero, so launchd/systemd also restarts with it
+        // (KeepAlive > SuccessfulExit > false means exit 0 stays down).
+        await restartForUpdate();
     }
     catch (error) {
         console.error(`  [update] Update failed: ${error?.message ?? error}`);
@@ -1104,41 +1166,17 @@ function isBeehavenProcess(pid) {
                 timeout: 3000,
             }).trim();
         }
+        else if (process.platform === 'win32') {
+            // No `ps` and no /proc on Windows: read the command line from CIM (CAN2-56).
+            cmd = windowsNodeProcesses(pid)?.find(([p]) => p === pid)?.[1] ?? '';
+        }
         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;
+        // The two-condition rule (argv[0] is node/tsx/beehaven AND an argument is a beehaven script)
+        // lives in daemon-process.ts, where it also understands Windows command lines.
+        return isBeehavenCommandLine(cmd);
     }
     catch {
         return false; // Can't read → not our process or already dead
@@ -1151,6 +1189,23 @@ function isBeehavenProcess(pid) {
  */
 export function findLiveDaemons() {
     const found = new Set();
+    // Windows: no PID-file trust without a command line, and no pgrep — ONE CIM query of node
+    // processes answers both "is the PID file's process ours" and "are there orphans" (CAN2-56).
+    if (process.platform === 'win32') {
+        let pidFilePid = null;
+        try {
+            pidFilePid = existsSync(PID_FILE) ? parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10) || null : null;
+        }
+        catch { }
+        const alive = (pid) => { try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        } };
+        return selectWindowsDaemons(windowsNodeProcesses(), { selfPid: process.pid, pidFilePid, isAlive: alive });
+    }
     // 1. Check PID file first — the canonical source.
     if (existsSync(PID_FILE)) {
         try {
@@ -1294,7 +1349,7 @@ export async function startDaemon(opts) {
     // 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(`\n  ✗ Another beehaven daemon is listening on ${ipcSocketPath()}.`);
         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');
@@ -4061,7 +4116,7 @@ export async function startDaemon(opts) {
                 // so browser frontends become virtual IPC clients — same
                 // pipeline, app-rpc, broadcast fan-out as Claude's path.
                 dashboard.setAppBridge({
-                    createVirtualClient: (send, subs) => ipc.createVirtualClient(send, subs),
+                    createVirtualClient: (send, subs, scope) => ipc.createVirtualClient(send, subs, scope),
                     injectMessage: (id, msg) => ipc.injectMessage(id, msg),
                     releaseVirtualClient: (id) => ipc.releaseVirtualClient(id),
                 });
@@ -4086,15 +4141,29 @@ export async function startDaemon(opts) {
         }
     })();
     // ── Dashboard (local observability UI) ──────────────────────────────
-    dashboard = new Dashboard({
-        port: config.dashboardPort ?? 9800,
-        host: '127.0.0.1',
-        explorerTarget: `http://127.0.0.1:${config.devPort ?? 8787}`,
-        explorerSecret: config.explorerSecret ?? config.adminSecret ?? '',
-        projectDir: config.linkedProject ?? '',
-    });
+    /**
+     * ⚠⚠ A LOOPBACK HTTP SERVER IS OPEN TO EVERY USER AND PROGRAM ON THE MACHINE (CAN2-64), so a
+     * daemon opens one only when something will use it. The Mac app's daemon does (the avatar UI
+     * talks over /apps/ws); a HEADLESS daemon — the CLI on Windows and Linux, CI, servers — has no
+     * window to show it in and, on a shared Windows machine, would hand every other signed-in user
+     * a port into this one's daemon. It starts there only on request: BEEHAVEN_DASHBOARD=1,
+     * `"dashboard": true` in ~/.beehaven/config.json, or developer mode.
+     */
+    const headlessDaemon = process.env.BEEHAVEN_HEADLESS === '1' || process.env.BEEHAVEN_HEADLESS === 'true';
+    const dashboardWanted = !headlessDaemon || developerMode || config.dashboard === true || process.env.BEEHAVEN_DASHBOARD === '1';
+    if (!dashboardWanted) {
+        console.log('  [dashboard] off in a headless daemon (set BEEHAVEN_DASHBOARD=1 to open it on 127.0.0.1)');
+    }
+    if (dashboardWanted)
+        dashboard = new Dashboard({
+            port: config.dashboardPort ?? 9800,
+            host: '127.0.0.1',
+            explorerTarget: `http://127.0.0.1:${config.devPort ?? 8787}`,
+            explorerSecret: config.explorerSecret ?? config.adminSecret ?? '',
+            projectDir: config.linkedProject ?? '',
+        });
     dashboard
-        .start()
+        ?.start()
         .then(() => {
         console.log(`  [dashboard] Beehaven Dashboard at ${dashboard.url}`);
     })
@@ -4103,7 +4172,7 @@ export async function startDaemon(opts) {
     });
     // Forward daemon events to dashboard
     watcher.on('event', (event) => {
-        dashboard.pushEvent({
+        dashboard?.pushEvent({
             type: event.hook_event_name || event.type || 'unknown',
             timestamp: event.timestamp || Date.now(),
             data: {

package/dist/dashboard.js

@@ -17,6 +17,59 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
+// ── Who may talk to this server (CAN2-64) ───────────────────────────────────
+/**
+ * ⚠⚠ A LOOPBACK PORT IS NOT A PRIVATE CHANNEL. Every web page the person opens can dial
+ * `ws://127.0.0.1:9800` — WebSockets ignore CORS — and so can every program on the machine,
+ * another Windows or macOS user's included. `/apps/ws` used to hand EVERY connection a
+ * developer-scope IPC client with no check at all (a comment in ipc-server.ts claimed a session
+ * cookie and an origin check that did not exist), so any website could ask the daemon for the
+ * signed-in Firebase token, run `sql`/`shell`, or install a package. Proven against a live
+ * daemon on 2026-10-13 with `Origin: https://evil.example`. The rules now:
+ *
+ *   1. The Host header must name this loopback server — a DNS-rebound hostname is refused.
+ *   2. `/apps/ws`: a PAGE must come from this server (an installed hive's frontend) or be a
+ *      `file://` page (the Mac app loads the avatar UI with `loadFile`; a web page cannot claim
+ *      `file://`), and it gets CONSUMER scope. A PROGRAM (no Origin) starts unauthenticated and
+ *      must present the daemon's IPC token with `{type:'auth'}` — the pipe's own boundary. Any
+ *      other origin, `null` included (sandboxed iframes send it), is refused at the upgrade.
+ *   3. JSON routes answer CORS only to loopback origins (a dev server on localhost). Browser
+ *      building modules stay `*`: clearly.sh imports that public code cross-origin.
+ */
+export function isLoopbackHostHeader(host, port) {
+    const h = (host ?? '').toLowerCase();
+    return h === `127.0.0.1:${port}` || h === `localhost:${port}` || h === `[::1]:${port}`;
+}
+/** `http://localhost:N`, `http://127.0.0.1:N` or `http://[::1]:N` — a page served on this machine. */
+export function isLoopbackOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const u = new URL(origin);
+        return u.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** A page served by THIS server. */
+export function isSelfOrigin(origin, port) {
+    return (origin === `http://127.0.0.1:${port}` ||
+        origin === `http://localhost:${port}` ||
+        origin === `http://[::1]:${port}`);
+}
+/** How a `/apps/ws` connection starts: `consumer` scope, unauthenticated (`token`), or refused (null). */
+export function appBridgeTrust(origin, port) {
+    if (!origin)
+        return 'token';
+    if (origin === 'file://' || isSelfOrigin(origin, port))
+        return 'consumer';
+    return null;
+}
+/** `/ws` streams events and accepts console logs: loopback or file pages, or programs. */
+export function metricsSocketAllowed(origin) {
+    return !origin || origin === 'file://' || isLoopbackOrigin(origin);
+}
 // ── Fallback HTML ───────────────────────────────────────────────────────────
 const FALLBACK_HTML = `<!DOCTYPE html>
 <html lang="en">
@@ -150,11 +203,28 @@ export class Dashboard {
         // first WSS's listener — both listeners fire on every upgrade event.
         // Instead we accept all upgrades and route by req.url in the
         // connection handler.
-        this._wss = new WebSocketServer({ server: this._server });
+        //
+        // Every upgrade is judged BEFORE it is accepted (see "Who may talk to this server").
+        this._wss = new WebSocketServer({
+            server: this._server,
+            verifyClient: (info, done) => {
+                const req = info.req;
+                const url = req.url ?? '';
+                const origin = req.headers.origin;
+                if (!isLoopbackHostHeader(req.headers.host, this.port))
+                    return done(false, 403, 'Forbidden');
+                if (url.startsWith('/apps/ws')) {
+                    return appBridgeTrust(origin, this.port) ? done(true) : done(false, 403, 'Forbidden');
+                }
+                if (url.startsWith('/ws'))
+                    return metricsSocketAllowed(origin) ? done(true) : done(false, 403, 'Forbidden');
+                return done(false, 404, 'Not Found');
+            },
+        });
         this._wss.on('connection', (ws, req) => {
             const url = req.url ?? '';
             if (url.startsWith('/apps/ws')) {
-                this._handleAppWsConnection(ws);
+                this._handleAppWsConnection(ws, appBridgeTrust(req.headers.origin, this.port));
             }
             else if (url.startsWith('/ws')) {
                 this._handleWSConnection(ws, req);
@@ -255,8 +325,10 @@ export class Dashboard {
     get url() {
         return `http://${this._config.host}:${this._config.port}`;
     }
+    /** The port actually bound (config 0 picks one), which the Host and Origin checks compare to. */
     get port() {
-        return this._config.port;
+        const addr = this._server?.address();
+        return addr && typeof addr === 'object' ? addr.port : this._config.port;
     }
     get running() {
         return this._server !== null;
@@ -268,6 +340,30 @@ export class Dashboard {
     _handleHTTP(req, res) {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
+        const origin = req.headers.origin;
+        // A DNS-rebound name pointing at 127.0.0.1 carries its own Host — refuse it on every route.
+        if (!isLoopbackHostHeader(req.headers.host, this.port)) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end('Forbidden');
+            return;
+        }
+        /**
+         * ⚠ ONE CHOKEPOINT FOR CORS. The handlers below were written to answer `*`; every response now
+         * passes through here, which keeps `*` only for browser building modules (public code that
+         * clearly.sh imports cross-origin) and otherwise reflects a loopback origin or sends none.
+         */
+        const publicModule = /^\/apps\/[^/]+\/buildings\/[^/]+\.js$/.test(url);
+        const allowOrigin = publicModule ? '*' : isLoopbackOrigin(origin) ? origin : null;
+        const writeHead = res.writeHead.bind(res);
+        res.writeHead = (status, ...rest) => {
+            const headers = rest.find((r) => r && typeof r === 'object');
+            if (headers && 'Access-Control-Allow-Origin' in headers) {
+                delete headers['Access-Control-Allow-Origin'];
+                if (allowOrigin)
+                    Object.assign(headers, { 'Access-Control-Allow-Origin': allowOrigin, Vary: 'Origin' });
+            }
+            return writeHead(status, ...rest);
+        };
         // Handle CORS preflight
         if (method === 'OPTIONS') {
             res.writeHead(204, {
@@ -280,8 +376,14 @@ export class Dashboard {
             return;
         }
         try {
-            // Explorer API proxy — forward /api/explorer/* to the Worker
+            // Explorer API proxy — forward /api/explorer/* to the Worker. It adds the admin secret, so
+            // only this server's own explorer page (or a program, which sends no Origin) may use it.
             if (url.startsWith('/api/explorer')) {
+                if (origin && !isSelfOrigin(origin, this.port)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 this._proxyExplorer(req, res, url);
                 return;
             }
@@ -350,6 +452,11 @@ export class Dashboard {
                 }
             }
             if (method === 'POST' && url === '/api/console') {
+                if (!metricsSocketAllowed(origin)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 this._handleConsolePost(req, res);
                 return;
             }
@@ -702,7 +809,11 @@ export class Dashboard {
             : { installed: [], available: [] };
         this._serveJSON(res, payload);
     }
-    _handleAppWsConnection(ws) {
+    _handleAppWsConnection(ws, trust) {
+        if (!trust) {
+            ws.close(1008, 'forbidden');
+            return;
+        }
         if (!this._appBridge) {
             ws.close(1011, 'app bridge not configured');
             return;
@@ -720,7 +831,8 @@ export class Dashboard {
         // Subscribe broadly by default — browser UIs usually want to see
         // everything (pipeline:*, broadcast:*, etc.). Clients can tighten this
         // by sending their own { type: 'subscribe', patterns: [...] } message.
-        const virtId = bridge.createVirtualClient(send, ['*']);
+        // Consumer scope at most: a page never gets developer verbs (get-token, shell, sql, installs).
+        const virtId = bridge.createVirtualClient(send, ['*'], trust === 'consumer' ? 'consumer' : null);
         ws.on('message', (raw) => {
             let msg;
             try {

package/dist/ipc-auth.js

@@ -2,7 +2,9 @@
  * IPC auth — scope-aware shared secrets between daemon and local clients.
  *
  * Threat model: any process running as the same user can connect to
- * /tmp/beehaven-ipc.sock (it's chmod 0600, which only restricts other users).
+ * /tmp/beehaven-ipc.sock (it's chmod 0600, which only restricts other users). On
+ * Windows the daemon listens on a per-user named pipe, which has no file mode at all — so on
+ * that platform these tokens ARE the boundary for same-user callers (ipc-path.ts).
  * Without per-scope auth, any same-user process can invoke privileged
  * verbs — extract the Firebase ID token via `get-token`, run arbitrary
  * SQL, install marketplace packages with code execution.

package/dist/ipc-client.js

@@ -4,14 +4,15 @@
  * Used by CLI commands (actions, call, pipe, watch, ls, cat) to communicate
  * with the running daemon, which forwards requests to the cloud DO.
  *
- * Protocol: newline-delimited JSON over /tmp/beehaven-ipc.sock
+ * Protocol: newline-delimited JSON over /tmp/beehaven-ipc.sock (a named pipe on Windows — ipc-path.ts)
  */
-import { existsSync } from 'node:fs';
 import { createConnection } from 'net';
 import { EventEmitter } from 'events';
 import { resolveClientAuthToken } from './ipc-auth.js';
+import { ipcSocketPath, socketMayExist } from './ipc-path.js';
 import { activeAgentWrap } from './agent-attribution.js';
-const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+/** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
+const IPC_SOCKET_PATH = ipcSocketPath();
 /** Default timeout for RPC calls (ms) */
 const DEFAULT_TIMEOUT = 30_000;
 /**
@@ -49,7 +50,7 @@ export class IpcClient extends EventEmitter {
          * — the only way to guard the CALL SITE rather than the helper it calls, which is the exact
          * distinction that let 28 verbs ship un-attributed. Unset, nothing changes.
          */
-        this.socketPath = opts?.socketPath ?? process.env.BEEHAVEN_IPC_SOCKET ?? IPC_SOCKET_PATH;
+        this.socketPath = opts?.socketPath ?? ipcSocketPath(); // honours $BEEHAVEN_IPC_SOCKET
         this.defaultTimeout = opts?.timeout ?? DEFAULT_TIMEOUT;
         this.explicitAuthToken = opts?.authToken;
     }
@@ -113,7 +114,7 @@ export class IpcClient extends EventEmitter {
                                 ? resolveClientAuthToken()
                                 : this.explicitAuthToken;
                             let token = readToken();
-                            if (!token && this.explicitAuthToken === undefined && existsSync(this.socketPath)) {
+                            if (!token && this.explicitAuthToken === undefined && socketMayExist(this.socketPath)) {
                                 const deadline = Date.now() + TOKEN_MINT_WAIT_MS;
                                 while (!token && Date.now() < deadline) {
                                     /**
@@ -143,7 +144,7 @@ export class IpcClient extends EventEmitter {
                                  * ⚠ THE SOCKET IS THE DISCRIMINATOR: up means "still starting, wait"; absent
                                  * means "nothing is running, start one". Opposite actions.
                                  */
-                                (existsSync(this.socketPath)
+                                (socketMayExist(this.socketPath)
                                     ? 'The daemon is still starting — its socket is up but it has not minted an IPC token yet. ' +
                                         'Wait a second and retry. (Do NOT restart: `stop` scrubs the token, which re-enters this window.)'
                                     : 'No IPC auth token and no daemon socket — nothing is running. ' +

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) };
+    }
+}