@clearlysh/beehaven 0.8.29 → 0.8.30

package/dist/browser-login.js

@@ -93,10 +93,15 @@ async function warnIfLocalDevDown() {
  * Linux; start on Windows. Failure is SURFACED — silent failure was the bug — so the person can
  * paste the URL themselves.
  */
-function openInBrowser(url) {
+export function openInBrowser(url) {
     try {
-        const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-        const proc = spawn(opener, [url], { stdio: 'ignore', detached: true });
+        // ⚠ Windows: `start` is a cmd.exe BUILTIN, not a program, so spawning it always failed (ENOENT)
+        // and login fell back to "paste this URL". The URL protocol handler is a real executable, and
+        // passing the URL as an argv entry keeps cmd from splitting it at `&` (CAN2-56).
+        const [opener, args] = process.platform === 'darwin' ? ['open', [url]]
+            : process.platform === 'win32' ? ['rundll32.exe', ['url.dll,FileProtocolHandler', url]]
+                : ['xdg-open', [url]];
+        const proc = spawn(opener, args, { stdio: 'ignore', detached: true, windowsHide: true });
         proc.unref();
         proc.on('error', (err) => {
             console.log(`  ${color.yellow('!')} Couldn't auto-open browser: ${err.message}`);

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = 'd733c0004e58-dirty';
+export const BUILD_SHA = '2c7d78e7c945';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-10T21:21Z';
+export const BUILD_TIME = '2026-10-13T06:00Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/claude-bridge.js

@@ -15,12 +15,13 @@
  *   await bridge.callApp('recorder', 'record', { source: 'mic' });
  */
 import { createConnection } from 'net';
+import { request as httpRequest } from 'http';
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { EventEmitter } from 'events';
 import { activeAgentWrap } from './agent-attribution.js';
-const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+import { ipcSocketPath, watcherSocketPath, socketMayExist } from './ipc-path.js';
 const CONFIG_DIR = join(homedir(), '.beehaven');
 export class ClaudeBridge extends EventEmitter {
     socket = null;
@@ -39,11 +40,12 @@ export class ClaudeBridge extends EventEmitter {
     async connect() {
         if (this.connected)
             return true;
-        if (!existsSync(IPC_SOCKET_PATH))
+        const ipcPath = ipcSocketPath();
+        if (!socketMayExist(ipcPath))
             return false;
         return new Promise((resolve) => {
             const timeout = setTimeout(() => resolve(false), 5_000);
-            const socket = createConnection({ path: IPC_SOCKET_PATH });
+            const socket = createConnection({ path: ipcPath });
             this.socket = socket;
             socket.on('connect', () => {
                 this.connected = true;
@@ -198,11 +200,12 @@ export class ClaudeBridge extends EventEmitter {
     }
     // ── Internal ───────────────────────────────────────────────────────
     sendEvent(hookEvent, extra = {}) {
-        // Send via the watcher socket (HTTP POST to /tmp/beehaven.sock)
-        // This is the same protocol mwah uses.
-        if (!existsSync('/tmp/beehaven.sock'))
+        // Send via the watcher socket (HTTP POST to /event) — the same protocol mwah uses.
+        // ⚠ `http` is IMPORTED: this was `require('http')`, which is undefined in this ESM package,
+        // so every event threw a ReferenceError once the socket existed (CAN2-56).
+        const watcherPath = watcherSocketPath();
+        if (!socketMayExist(watcherPath))
             return;
-        const http = require('http');
         const body = JSON.stringify({
             hook_event_name: hookEvent,
             session_id: this.sessionId,
@@ -211,8 +214,8 @@ export class ClaudeBridge extends EventEmitter {
             source: 'claude-code',
             ...extra,
         });
-        const req = http.request({
-            socketPath: '/tmp/beehaven.sock',
+        const req = httpRequest({
+            socketPath: watcherPath,
             path: '/event',
             method: 'POST',
             headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },

package/dist/clearly.js

@@ -26,6 +26,7 @@
  * product promises. GitHub / Linear / Slack ingestion is a separate project; nothing here
  * pretends otherwise, and `status` says so out loud.
  */
+import './windows-hide.js'; // FIRST: no console windows flashing on Windows (CAN2-56)
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -47,12 +48,12 @@ const c = {
     red: (s) => `\x1b[31m${s}\x1b[0m`,
 };
 /**
- * ⚠ THE AGENT TURN IS THE SLOW PART. The server's `RESPOND_TIMEOUT_MS` is 300s (clearly CDS-90, was
- * 180s); this waits that plus the report's tail, so a turn that finishes on time is never abandoned
+ * ⚠ THE AGENT JOB IS THE SLOW PART. The server's `RESPOND_TIMEOUT_MS` is 900s (WDP3-62);
+ * this waits that plus the report's tail, so a turn that finishes on time is never abandoned
  * by its caller and a timeout here still means the turn itself ran out. The relay-forward window
  * follows the `_timeout` sent with the call.
  */
-export const TURN_MS = 330_000;
+export const TURN_MS = 930_000;
 /**
  * ⚠ STDERR IS CAPTURED, NOT INHERITED. A failing probe is normal here — `HEAD~30` does not exist in
  * a repo with two commits — and with inherited stderr git printed

package/dist/cli.js

@@ -16,6 +16,7 @@
 if (!process.env.BEEHAVEN_IPC_SCOPE) {
     process.env.BEEHAVEN_IPC_SCOPE = 'developer';
 }
+import './windows-hide.js'; // FIRST: no console windows flashing on Windows (CAN2-56)
 import { parseArgs } from 'node:util';
 import { devModeAvailable, buildLabel, PUBLIC_BUILD } from './build-channel.js';
 import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, } from 'fs';
@@ -448,8 +449,9 @@ ${DEV_ONLY_HELP ? `
 
   Note: if you also run the Hive menu-bar app, the tray is the
   primary owner of the daemon. CLI start/stop only act when the tray
-  isn't running its own daemon. The same socket (/tmp/beehaven-ipc.sock)
-  is shared in both modes — never two daemons at once.
+  isn't running its own daemon. The same socket (/tmp/beehaven-ipc.sock;
+  a per-user named pipe on Windows) is shared in both modes — never two
+  daemons at once.
 
   ─────────────────────────────────────────────────────────────────────
   OPTIONS
@@ -3171,11 +3173,10 @@ async function run() {
             console.log(`  Sign up at ${color.cyan(signupUrl)}.`);
             console.log('  Then run "beehaven login" to wire the CLI to your account.');
             console.log('');
-            try {
-                const { spawn } = await import('child_process');
-                spawn('open', [signupUrl], { stdio: 'ignore', detached: true }).unref();
-            }
-            catch { }
+            // The shared opener: per-platform (Windows has no `open`), and a spawn failure prints the
+            // URL instead of crashing on an unhandled child 'error' event.
+            const { openInBrowser } = await import('./browser-login.js');
+            openInBrowser(signupUrl);
             break;
         }
         case 'treehouse': {

package/dist/commands/daemon-cmd.js

@@ -42,6 +42,8 @@ export function spawnStandaloneDaemon(values) {
     const child = spawn(process.execPath, [entry], {
         detached: true,
         stdio: 'ignore',
+        // Windows: a detached child gets its OWN console window — closing it kills the daemon. Hide it.
+        windowsHide: true,
         // BEEHAVEN_HEADLESS=1 is REQUIRED, not optional: daemon-entry.ts runs a
         // parent-death watchdog (polls process.ppid, self-exits ~3s after the parent
         // is gone) to enforce the tray-coupled lifecycle. A detached CLI-spawned

package/dist/commands/workspace.js

@@ -26,8 +26,8 @@ import { resolveActiveAgent } from '../agent-state.js';
 import { isAgentRuntime } from '../agent-scope.js';
 import { getTarget } from '../cli-state.js';
 import { attachShellCwd, absorbShellCwd, shellTargetKey } from '../shell-session.js';
-/** Workspace-agent turns wait for the server's turn ceiling (300s) plus the report's tail. */
-export const AGENT_TURN_TIMEOUT_MS = 330_000;
+/** Workspace-agent jobs wait for the server's ceiling (900s) plus the report's tail. */
+export const AGENT_TURN_TIMEOUT_MS = 930_000;
 const AGENT_TURN_ACTIONS = new Set(['agent-prompt', 'agent-turn']);
 export function getTimeout(values, action) {
     // Precedence: explicit --timeout flag → BEEHAVEN_RPC_TIMEOUT_MS env → default.
@@ -40,7 +40,7 @@ export function getTimeout(values, action) {
     const env = process.env.BEEHAVEN_RPC_TIMEOUT_MS;
     if (env && Number.isFinite(Number(env)) && Number(env) > 0)
         return parseInt(env, 10);
-    // An agent turn may run to the server's 300s ceiling (clearly CDS-90); waiting less abandons it.
+    // An agent job may run to the server's 900s ceiling (WDP3-62); waiting less abandons it.
     return action && AGENT_TURN_ACTIONS.has(action) ? AGENT_TURN_TIMEOUT_MS : 180_000;
 }
 /**

package/dist/daemon-client.js

@@ -15,17 +15,16 @@
  *   }
  */
 import net from 'net';
-import { existsSync } from 'fs';
 import { resolveClientAuthToken } from './ipc-auth.js';
 import { activeAgentWrap } from './agent-attribution.js';
-const SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+import { ipcSocketPath, socketMayExist } from './ipc-path.js';
 const TIMEOUT_MS = 60_000;
 const AUTH_TIMEOUT_MS = 3_000;
 /** One attempt. Resolves, never rejects. */
 function probeOnce(deadlineMs) {
     return new Promise((resolve) => {
         let connected = false;
-        const sock = net.createConnection(SOCKET_PATH);
+        const sock = net.createConnection(ipcSocketPath());
         const timer = setTimeout(() => {
             sock.destroy();
             // ⚠ CONNECTED-BUT-SILENT IS NOT "DOWN". The kernel accepted us, so a listener exists.
@@ -65,7 +64,7 @@ const PROBE_BACKOFF_MS = 150;
  * that "down" is the original defect.
  */
 export async function probeDaemon() {
-    if (!existsSync(SOCKET_PATH))
+    if (!socketMayExist(ipcSocketPath()))
         return { state: 'down', attempts: 0 };
     let sawListener = false;
     let last = { state: 'down', attempts: 0 };
@@ -74,6 +73,11 @@ export async function probeDaemon() {
         last = { ...r, attempts: i };
         if (r.state === 'up')
             return last;
+        // Nothing at the address (no socket file, or no such Windows pipe): permanent, like the
+        // missing-file check above — a named pipe cannot be checked before connecting, so this is
+        // where "nothing is running" is learned on Windows. Retrying would only add ~300 ms.
+        if (r.code === 'ENOENT' && !sawListener)
+            return last;
         if (r.state === 'silent')
             sawListener = true;
         if (i < PROBE_ATTEMPTS)
@@ -165,7 +169,7 @@ function handshake(socket) {
                          * ⚠ `start --headless` NOW WAITS for the socket (see `daemon-cmd.ts`), so a script
                          * that uses it should no longer reach this at all.
                          */
-                        (existsSync(SOCKET_PATH)
+                        (socketMayExist(ipcSocketPath())
                             ? '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. ' +
@@ -192,7 +196,7 @@ function handshake(socket) {
 }
 /** Open a socket, complete auth handshake, run a single request, close. */
 async function withSocket(fn) {
-    const socket = net.createConnection(SOCKET_PATH);
+    const socket = net.createConnection(ipcSocketPath());
     await new Promise((resolve, reject) => {
         socket.once('connect', () => resolve());
         socket.once('error', reject);

package/dist/daemon-entry.js

@@ -23,6 +23,7 @@
  *     startup errors (those usually need user intervention — expired token,
  *     missing config, etc).
  */
+import './windows-hide.js'; // FIRST: no console windows flashing on Windows (CAN2-56)
 import { startDaemon } from './daemon.js';
 // ── Parent-watcher (tray-coupled enforcement) ──
 // The daemon is documented as tray-coupled: it must not outlive the

package/dist/daemon-process.js

@@ -0,0 +1,125 @@
+/**
+ * daemon-process — "is this process a beehaven daemon?", on every platform (CAN2-56).
+ *
+ * Split out of `daemon.ts` so the rule is testable without importing the daemon, and so Windows has
+ * an answer at all: `findLiveDaemons` read a command line with `ps` (macOS) or `/proc/<pid>/cmdline`
+ * (Linux) and found orphans with `pgrep`. Windows has none of those, so every lookup threw, was
+ * swallowed as "not ours", and `stop` / `restart` / the single-instance guard never saw a running
+ * daemon. Windows reads command lines from one CIM query instead.
+ */
+import { execFileSync } from 'child_process';
+/**
+ * Whether a full command line is a beehaven daemon or CLI process.
+ *
+ * Strict two-condition test (unchanged on macOS/Linux):
+ *   1. argv[0] is a node/tsx/beehaven binary — not a shell, an editor, a grep, etc.;
+ *   2. a later argument is a beehaven cli/daemon-entry script (under a beehaven* directory OR a
+ *      Clearly*.app bundle).
+ *
+ * ⚠ WINDOWS COMMAND LINES ARE NORMALISED FIRST: argv[0] arrives quoted with backslashes, spaces and
+ * an extension (`"C:\Program Files\nodejs\node.exe" C:\…\daemon-entry.js`). It is reduced to the
+ * Unix shape (`C:/Program_Files/nodejs/node …`) so the same two conditions apply, unquoted.
+ */
+export function isBeehavenCommandLine(raw, platform = process.platform) {
+    let cmd = (raw ?? '').trim();
+    if (!cmd)
+        return false;
+    if (platform === 'win32') {
+        const m = /^"([^"]*)"\s*(.*)$/s.exec(cmd) ?? /^(\S+)\s*(.*)$/s.exec(cmd);
+        if (!m)
+            return false;
+        const argv0 = m[1].replace(/\\/g, '/').replace(/\.(exe|cmd)$/i, '').replace(/\s+/g, '_').toLowerCase();
+        cmd = `${argv0} ${m[2].replace(/"/g, '')}`.trim();
+    }
+    // Condition 1: argv[0] must be a node/tsx/beehaven-wrapper binary. Anchored 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;
+    // ⚠⚠ ON WINDOWS ONLY THE DAEMON ENTRY COUNTS. The `cli.js` patterns below exist for LEGACY daemons
+    // (`node cli.js start`, before daemon-entry.js) — and on macOS `pgrep` never surfaced ordinary CLI
+    // runs anyway (it reads its pattern as a BASIC regex, where `(js|ts)` matches nothing). Windows
+    // lists every node process, so with them a `start --headless` parent waiting for its child was
+    // "another daemon" (the child refused to start — the second Windows CI run), and `stop` would
+    // have killed an agent's in-flight `beehaven call`. There are no legacy Windows daemons to find.
+    if (platform === 'win32')
+        return /[/\\]\.?beehaven([-_]sdk)?[/\\].*daemon-entry\.(js|ts)\b/.test(cmd);
+    // Condition 2: a subsequent argument must reference a beehaven script.
+    //
+    // NOTE THE `\.?` — the directory may be `beehaven/` OR the DOTFILE `.beehaven/`. And `[-_]sdk`:
+    // the monorepo checkout is `beehaven_sdk/`, but a clone of the GitHub repo is `beehaven-sdk/` —
+    // the first Windows CI run could not find its own daemon for exactly that reason (CAN2-56).
+    // `public/install.sh` installs to `~/.beehaven/cli/`, the canonical location for every
+    // `curl … | sh` user; requiring exactly "beehaven" once made the CLI blind to its own standard
+    // install (`stop` said "No daemon running" while one was).
+    return (
+    // Dedicated daemon entry — what the Mac app tray and `start --headless` spawn.
+    /[/\\]\.?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));
+}
+/** Parse `ConvertTo-Json` output of `{ProcessId, CommandLine}` rows (one object, or an array). */
+export function parseWindowsProcessJson(out) {
+    const text = (out ?? '').trim();
+    if (!text)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const rows = Array.isArray(parsed) ? parsed : [parsed];
+    const result = [];
+    for (const r of rows) {
+        const pid = Number(r?.ProcessId);
+        if (Number.isFinite(pid) && pid > 0)
+            result.push([pid, typeof r?.CommandLine === 'string' ? r.CommandLine : '']);
+    }
+    return result;
+}
+/**
+ * Node processes on Windows with their command lines — one `Get-CimInstance` call (~0.5–1 s, so it
+ * runs only on start/stop/status paths, never per RPC). `pid` narrows it to one process.
+ * Returns `null` when the query itself failed (no PowerShell, blocked by policy, timed out) — which
+ * is NOT the same as "no node processes", and `selectWindowsDaemons` treats it differently.
+ */
+export function windowsNodeProcesses(pid) {
+    const filter = pid ? `ProcessId=${Math.trunc(pid)}` : "Name='node.exe'";
+    const script = `Get-CimInstance Win32_Process -Filter "${filter}" | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress`;
+    try {
+        const out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 8000,
+            windowsHide: true,
+        });
+        return parseWindowsProcessJson(out);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Which of these Windows processes are beehaven daemons (never this process).
+ *
+ * ⚠ WHEN THE PROCESS QUERY FAILED (`rows === null`), THE PID FILE IS THE ONLY WITNESS LEFT. Seeing
+ * nothing would make `stop` say "No daemon running" over a live one and let `start` spawn a second
+ * daemon beside it — the failure the first Windows CI run showed. A live process at the recorded
+ * PID is trusted then, and only then: with a working query, the command line decides, so a PID
+ * recycled by an unrelated program is never taken for the daemon.
+ */
+export function selectWindowsDaemons(rows, opts) {
+    if (rows === null) {
+        const p = opts.pidFilePid;
+        return p && p > 0 && p !== opts.selfPid && opts.isAlive(p) ? [p] : [];
+    }
+    return rows.filter(([pid, cmd]) => pid !== opts.selfPid && isBeehavenCommandLine(cmd, 'win32')).map(([pid]) => pid);
+}

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.
@@ -1104,41 +1106,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 +1129,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 +1289,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');

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

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 */
     /**

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/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": "@clearlysh/beehaven",
-  "version": "0.8.29",
+  "version": "0.8.30",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/skills/brand-identity/SKILL.md

@@ -64,15 +64,31 @@ handover. A mark of hand-placed béziers does not, and it shows.
 | **Counter-form** | the shape is the NEGATIVE space between forms | clever marks that survive one colour |
 | **Modular** | one unit repeated/rotated on a grid | systems, networks, collectives |
 
-**Build it as an `svg` node with a stated viewBox and derived numbers:**
+**Build it from native layers, every number derived from the construction** — the way an
+identity designer works in Figma, so each part of the mark stays a named, editable layer in the
+brand colour (never one generated or hand-written SVG):
 
 ```jsonc
-{"action":"canvas.create-node","args":{"name":"mark","type":"svg","x":120,"y":120,"w":240,"h":240,
- "svg":"<svg viewBox='0 0 240 240' xmlns='http://www.w3.org/2000/svg'>…</svg>"}}
+{"batch":[
+ {"action":"frame.create","args":{"name":"Mark","x":120,"y":120,"w":240,"h":240}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/ring","parentId":"Mark",
+   "x":20,"y":20,"w":200,"h":200,"fill":"#1B4DFF"}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/counter","parentId":"Mark",
+   "x":70,"y":70,"w":100,"h":100,"fill":"#FFFFFF"}},
+ {"action":"vector.create","args":{"name":"mark/blade","parentId":"Mark","closed":true,"fill":"#1B4DFF",
+   "points":[{"x":120,"y":20},{"x":220,"y":120},{"x":120,"y":120}]}},
+ {"action":"canvas.group","args":{"ids":["mark/ring","mark/counter","mark/blade"],"name":"mark"}}
+]}
 ```
 
-⚠ **`<text>` inside an `svg` node does NOT render headlessly** — no system fonts are loaded.
-Wordmarks are real text nodes, or outlined paths. Never live `<text>` in the mark.
+Here R = 100: the counter is R/2, the blade's corners sit on the circle. Curves are
+`vector.create` points with `hIn`/`hOut` control points (absolute coordinates) placed where the
+construction says; a quarter-circle's handle sits 0.552·R from its anchor. A counter-form is a
+ground-colour shape layered on top; `vector.boolean` makes a true cut-out when an editor is open.
+Raw SVG (`type:"svg"`) is only for importing a mark the client already has.
+
+⚠ **Wordmarks are real text nodes, or outlined paths** — and `<text>` inside an imported `svg`
+node does NOT render headlessly (no system fonts are loaded).
 
 **Test the mark against these before going further. A mark that fails any of them is not done:**
 

package/skills/clearly-canvas/SKILL.md

@@ -110,10 +110,19 @@ can read and edit artifact records, while canvas-specific actions use the CLI.
 beehaven env
 beehaven connect home
 beehaven agent login <name> --label "Design <artifact>" --client cli
-beehaven call canvas-perceive '{"compositionId":"<id>","format":"json"}'
+beehaven call canvas-perceive '{"compositionId":"<id>","outline":true}'
 beehaven call canvas-catalog '{"query":"create-node"}'
 ```
 
+Read a canvas the way you read a repository: `canvas-perceive {outline:true}` is `tree` (artboards,
+sections, layer counts, first copy, EMPTY sections — a few hundred bytes); `{frame:"<id or name>"}`
+opens one frame like a file (its layers indented, positions relative to their parent);
+`{find:"Start free"}` is `grep` (copy, layer names or `#hex`, with each match's frame path). Use
+`format:"json"` only when you need every field of every node. Every `canvas-act` write returns
+`diagnostics` — a lint of the artboards it touched (text overflow, collisions, covered text,
+contrast) — treat them like compiler errors and fix them in the next batch. `canvas.review` is still
+the pixel check and the ticket gate.
+
 A canvas is planned like a git repository: its own plan board, a WORK TICKET for the request, and
 COMMITS — one ticket per coherent layer or section of a larger change.
 `design-start {title, brandId?}` makes a PRIVATE DRAFT canvas, bound to the brand, with its private
@@ -133,7 +142,7 @@ builds on the last and can be reviewed alone. Build ONE commit per canvas-act ba
 `canvas.review` of the artboard and carries
 `"ticket":{"id":"<key>","status":"done","resolution":"<what changed>"}` — it lands only if that
 review is clean or look; `result.ticket` says whether it did, and the ticket logs the canvas
-revision and the layers the commit changed. Auto-layout, gradients, shadows and SVG placeholders:
+revision and the layers the commit changed. Auto-layout, gradients, shadows, drawing and placeholders:
 see "Technique" in [authoring.md](authoring.md).
 
 `composition-board-get {compositionId}` reads the plan back. `design-start` with a project, ticket or
@@ -195,8 +204,11 @@ hand-author hundreds of coordinates in a chat message.
   Check contrast on the actual ground. Use the user's real brand assets.
 - Choose relevant imagery, a meaningful diagram, a product view or a deliberate
   typographic treatment. Decorative blobs and random stock photos do not prove a
-  product claim. Native SVG/paths suit diagrams and vector art; raster generation
-  suits imagery when an image tool is available.
+  product claim. Draw marks, icons, illustrations and diagrams yourself from native
+  layers (shapes, vector.create pen paths, text, groups), the way a designer works in
+  Figma, so every part stays named and editable. Raster generation suits photographic
+  imagery when an image tool is available. Raw SVG (an svg node, or a generated SVG)
+  is for importing an existing file or a requested SVG, never the default.
 - Define repeated components once. Vary composition where the content changes.
   A deck of identical cards has little rhythm even when every card aligns.
 - Keep important copy and layers editable. Do not flatten the whole composition

package/skills/clearly-canvas/authoring.md

@@ -123,14 +123,15 @@ deliverable requires them, with content order and hierarchy reconsidered for the
 
 The same rules the in-app assistant works to (canvas-catalog returns them as `technique`).
 
-- AUTO-LAYOUT: rows and stacks (nav links, button groups, card rows, form fields) are a frame whose children you create in reading order, then canvas.auto-layout { id, direction, gap, padding, align, justify, hug }. hug:false keeps the frame size, which a full-width bar needs with justify:"space-between"; set a child to layoutSizingH/V "fill" | "hug" | "fixed" with canvas.update-nodes.
+- AUTO-LAYOUT: rows and stacks (nav links, button groups, card rows, form fields) are a frame whose children you create in reading order, then canvas.auto-layout { id, direction, gap, padding, align, justify, hug }. hug:false keeps the frame size, which a full-width bar needs with justify:"space-between"; set a child to layoutSizingH/V "fill" | "hug" | "fixed" with canvas.update-nodes. The frame stays live: create more children into it (parentId) and they flow in; layoutPositioning:"absolute" takes one out of the flow.
 - GRADIENTS: gradient { kind, angle, stops: [{ offset, color }] } replaces the solid fill. angle is the direction the colour travels: 0 = left to right, 90 = top to bottom, 45 = top-left to bottom-right (not CSS degrees). Use two or three stops from the brand palette, and keep text off a busy gradient or check its contrast in canvas.review.
 - SHADOWS AND BLUR: effects on any node. A soft card shadow is { type: "drop-shadow", x: 0, y: 4, blur: 16, spread: 0, color: "#0000001F" }; frosted glass is { type: "background-blur", blur: 16 }. Never fake a shadow with an extra rectangle.
-- SVG PLACEHOLDERS: until real imagery exists, draw it as an svg node at its final size in a muted tone from the brand palette, never a flat accent block, e.g. for a 400×240 slot svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 240"><rect width="400" height="240" rx="12" fill="#EDE6DF"/><circle cx="170" cy="96" r="14" fill="#CDBFB2"/><path d="M150 168l40-48 30 34 22-20 40 34z" fill="#CDBFB2"/></svg>' — <svg viewBox="0 0 W H"> always matches the node w and h. Put a label in its own text node and name the svg "<section> image placeholder". Hand-write only simple marks like this (placeholders, dividers, UI icons); logos, illustrations and finished artwork come from svg-make.
+- DRAWING: build every mark, icon, illustration and diagram shape from native layers, as a designer does in Figma, never as one generated SVG file. Primitives are canvas.create-node rect and ellipse; curves are pen paths, vector.create { name, parentId, points: [{ x, y, hIn?: { x, y }, hOut?: { x, y } }], closed, fill or stroke, strokeWidth }, where hIn/hOut are absolute control points: use few anchors with smooth handles, and refine with vector.read, vector.vertex.move and vector.handle.set. Round caps and joins: canvas.update-nodes patch { strokeCap: "round", strokeJoin: "round" }. Work back to front: ground, big silhouettes in flat brand colours, then features, then details and highlights; check the silhouette in canvas.review before detailing. Name layers by part ("fox/ear-left"), group each figure with canvas.group { ids, name } and set overlap with canvas.order { ids, op }. Make a cut-out by layering a ground-colour shape on top; vector.boolean { op } on selected paths needs an open editor. Keep one stroke weight per drawing. Photographic or painterly imagery is a placed raster. Raw SVG stays supported but is never the default: when an SVG is asked for, write the markup yourself as an svg node, canvas.create-node { type: "svg", name, w, h, svg } with <svg viewBox="0 0 W H"> matching w and h, or import existing markup the same way; never an SVG generation pipeline.
+- PLACEHOLDERS: until real imagery exists, draw a native placeholder at the final size in a muted brand tone, never a flat accent block: a rect with the slot radius plus a simple motif (an ellipse sun, a vector.create mountain), grouped with canvas.group and named "<section> image placeholder", with any label in its own text node.
 - SECTIONS: one frame per page section, named exactly as its ticket says, inside the page artboard. Build a section in one canvas-act batch that ends with canvas.review of the artboard and carries ticket: { id: "<its key>", status: "done", resolution: "<what changed>" }. The ticket moves only when that review is clean or look; result.ticket says whether it did. Then start the next section.
 
 Use `arrow.create {from,to,routing,label}` for connected diagrams, so arrows remain bound
-when nodes move. Use native shapes and SVG for custom vector details. Keep labels as
+when nodes move. Draw custom vector details natively (shapes, vector.create pen paths); raw SVG only imports an existing file. Keep labels as
 native text so they remain editable and measurable.
 
 Use `canvas.place {kind,id,x,y,w,h,name,parentId?}` to put a workspace object (document,

package/skills/index.json

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "7d79406b37f611a8"
+    "sha": "b942eebe6f0397fb"
   },
   {
     "name": "agent-home",
@@ -53,7 +53,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "cd891499599ccb7b"
+    "sha": "755db2d1ab8c759f"
   },
   {
     "name": "pair-on-canvas",