beehaven 0.8.27 → 0.8.33

package/dist/agents-md-text.js

@@ -0,0 +1,64 @@
+/**
+ * agents-md-text — the Clearly block for a PROJECT's AGENTS.md, as `beehaven agents-md` writes it
+ * (CAN2-66).
+ *
+ * ⚠⚠ A COPY, PINNED. The source of truth is the monorepo's `lib/connections/agentsMd.ts`, which the
+ * Integrations page, each agent's details and the MCP `clearly-agents-md` prompt render. This
+ * package cannot import it (it ships on its own), so the text is repeated here and the monorepo's
+ * `lib/__tests__/agentsMdCliParity.test.mjs` compares the two OUTPUTS, name argument included.
+ * Change both or the test fails — a stale copy does not render wrong, it instructs wrong.
+ *
+ * ⚠ NO IMPORTS, so that test can load this file directly.
+ */
+export const CLI_BLOCK_START = '<!-- clearly:cli:start -->';
+export const CLI_BLOCK_END = '<!-- clearly:cli:end -->';
+export const MCP_BLOCK_START = '<!-- clearly:mcp:start -->';
+export const MCP_BLOCK_END = '<!-- clearly:mcp:end -->';
+/** What goes in CLAUDE.md so Claude Code reads the AGENTS.md block too. */
+export const CLAUDE_MD_IMPORT = '@AGENTS.md';
+/** The block for agents that use the `beehaven` CLI. */
+export function agentsMdCliBlock(agentName) {
+    const name = (agentName ?? '').trim();
+    const login = name
+        ? `\`beehaven agent login ${name} --label "<what you are doing>"\` — you are ${name} in this workspace.`
+        : '`beehaven agent login <name> --label "<what you are doing>"`, using your own name (claude, codex, gemini).';
+    return [
+        CLI_BLOCK_START,
+        '<!-- managed-by: clearly. Run `beehaven agents-md` to update; edit outside this block. -->',
+        '',
+        '## Clearly workspace',
+        '',
+        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `beehaven` CLI',
+        'for anything the team should see, not files in this repo.',
+        '',
+        `- Sign in once per session: ${login}`,
+        '  If it says the daemon is not running: `beehaven start --headless`.',
+        '- Read the `clearly-agent` skill before anything else, and `clearly-canvas` before design work',
+        '  (`beehaven skills install` puts them in place).',
+        '- `beehaven actions` lists what you can call; `beehaven call <action> \'<json>\'` calls it.',
+        '- Search before you create, file work in the project it belongs to, and end the session with',
+        '  `beehaven agent handoff "what you did · what is next"` so the next one starts there.',
+        CLI_BLOCK_END,
+    ].join('\n');
+}
+/** The block for agents connected over MCP (the `clearly` server). */
+export function agentsMdMcpBlock() {
+    return [
+        MCP_BLOCK_START,
+        '<!-- managed-by: clearly-mcp. Re-run the `clearly-agents-md` prompt to update; edit outside this block. -->',
+        '',
+        '## Clearly workspace (connected over MCP as `clearly`)',
+        '',
+        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `clearly_*`',
+        'tools, not files in this repo, for anything the team should see.',
+        '',
+        '- Start with `clearly_catalog` to see what exists; search with `clearly_grep` / `clearly_glob`.',
+        '- Read with `clearly_read`, make new work with `clearly_create`, change it with `clearly_edit`,',
+        '  and discuss it with `clearly_comment`. They take a `target`: a path (`~/Q1/Plan.md`), a key',
+        '  (`CLR-42`), an id or an exact title. The extension names the type (`.md` document, `.csv`',
+        '  sheet, `.board.json` board); a trailing slash means a project.',
+        '- Search before you write, and write decisions back so the next session inherits them.',
+        '- If a job is not covered by a listed tool, say so rather than guessing an action name.',
+        MCP_BLOCK_END,
+    ].join('\n');
+}

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}`);
@@ -260,7 +265,12 @@ export function persistBrowserLogin(captured) {
             userId: captured.userId,
             email: captured.email ?? null,
             displayName: captured.displayName ?? null,
-            tokenStorage: 'keychain',
+            /**
+             * ⚠ SAY WHERE THE TOKEN REALLY IS (CAN2-65). This was always 'keychain', so on Windows —
+             * which has no keychain here — `whoami` reported a keychain that did not exist, and
+             * `Relay.loadConfig` / the refresh path shelled out to macOS `security` on every load.
+             */
+            tokenStorage: keychain.available ? 'keychain' : 'file',
             refreshToken: captured.refreshToken,
             token: captured.idToken,
             endpoint: dialUrl,

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 = 'db2b3eaeb90b';
+export const BUILD_SHA = '8f7eef9e12ce';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-07T02:00Z';
+export const BUILD_TIME = '2026-10-15T07:24Z';
 /**
  * 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,11 +48,12 @@ const c = {
     red: (s) => `\x1b[31m${s}\x1b[0m`,
 };
 /**
- * ⚠ THE AGENT TURN IS THE SLOW PART AND THE CLI RELAY CAPS AT 180s. `RESPOND_TIMEOUT_MS` on the
- * server is the same 180s, so a turn that outlives this was going to be killed anyway — matching
- * them means a timeout here always means the same thing it means there.
+ * ⚠ 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.
  */
-const TURN_MS = 180_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';
@@ -142,6 +143,7 @@ function printHelp() {
 
     beehaven guide                             Agent-first setup and signup handoff
     beehaven signup                            Create a free Clearly account
+    beehaven agents-md                         Add Clearly to this project's AGENTS.md
 
   Personal workspace:
     beehaven cd home
@@ -448,8 +450,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
@@ -954,6 +957,11 @@ const AGENT_LOGIN_EXEMPT = new Set([
      * would refuse the one person it is for — the agent whose user has not signed up yet (SGS-73).
      */
     'handoff',
+    /**
+     * ⚠ `agents-md` WRITES A FILE IN THIS REPO AND NOTHING ELSE — it never opens a workspace, and it is
+     * part of setting a project up, which must not require the login it helps a teammate do (CAN2-66).
+     */
+    'agents-md',
 ]);
 /**
  * ⚠ ALIAS → CANONICAL VERB, for the activity log's `source` column only.
@@ -1369,6 +1377,9 @@ async function run() {
             state: { type: 'string' },
             goal: { type: 'string' },
             remove: { type: 'boolean', default: false },
+            // `agents-md`: the MCP block instead of the CLI one; print it instead of writing it (CAN2-66).
+            mcp: { type: 'boolean', default: false },
+            print: { type: 'boolean', default: false },
             /**
              * ⚠⚠ `beehaven sheet` / `beehaven slides` — AND AN UNDECLARED FLAG IS A FATAL, NOT A NO-OP.
              *
@@ -3143,6 +3154,15 @@ async function run() {
             console.log('  (or quit and relaunch the Hive Mac app if it owns the daemon).');
             break;
         }
+        case 'agents-md': {
+            const { cmdAgentsMd } = await import('./commands/agents-md.js');
+            process.exitCode = cmdAgentsMd(positionals[1], {
+                mcp: !!values.mcp,
+                print: !!values.print,
+                remove: !!values.remove,
+            });
+            break;
+        }
         case 'handoff': {
             const { cmdHandoff } = await import('./commands/handoff.js');
             process.exitCode = await cmdHandoff(positionals[1], {
@@ -3171,11 +3191,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': {
@@ -3917,7 +3936,7 @@ complete -F _beehaven_completions beehaven`);
             console.log(`  ${r.url}`);
             // "reached" not "navigated": the frame goes to every connected surface but only the
             // VISIBLE one acts on it, so a count of sockets is not a count of things that moved.
-            console.log(color.dim(`  ${r.delivered > 0 ? `on screen (reached ${r.delivered} connected surface(s))` : 'no tab connected'}`));
+            console.log(color.dim(`  ${r.delivered > 0 ? `navigation requested (${r.delivered} connected surface(s)); editor display is not yet verified` : 'no navigation recipient connected'}`));
             // Only reach for the local browser when asked, or when nothing was
             // delivered — opening a window under someone who already has the tab
             // focused is worse than doing nothing.

package/dist/commands/agents-md.js

@@ -0,0 +1,118 @@
+/**
+ * beehaven agents-md — put the Clearly block in THIS project's AGENTS.md (CAN2-66).
+ *
+ * ⚠⚠ TWO FILES, TWO AUDIENCES. `beehaven login` already writes a GLOBAL block into
+ * ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.gemini/GEMINI.md (agent-instructions.ts), so every
+ * agent on THIS machine knows Clearly. A project's AGENTS.md is for everyone else who opens the
+ * repo — a teammate's Codex, a cloud agent, CI — and it is committed and shared. That is why this
+ * is its own command the person (or their agent, asked first) runs, not a side effect of install.
+ *
+ * ⚠ THE MARKERS ARE THE UPDATE MECHANISM, as on every other surface (lib/connections/agentsMd.ts):
+ * re-running replaces only what lies between our markers and leaves the rest byte for byte. The
+ * CLI and MCP blocks have their own markers, so a repo used both ways keeps both.
+ *
+ * ⚠ AGENTS.md IS THE FILE; CLAUDE.md POINTS AT IT with one `@AGENTS.md` line — one copy to keep
+ * current. An existing CLAUDE.md gains the line only if it lacks it; nothing else in it is touched.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { execFileSync } from 'child_process';
+import { color } from '../spinner.js';
+import { CLI_BLOCK_START, CLI_BLOCK_END, MCP_BLOCK_START, MCP_BLOCK_END, CLAUDE_MD_IMPORT, agentsMdCliBlock, agentsMdMcpBlock, } from '../agents-md-text.js';
+/** Our block replaced between its markers, or appended after one blank line. Keeps CRLF files CRLF. */
+export function spliceBlock(text, block, start, end) {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const b = block.split('\n').join(eol);
+    const i = text.indexOf(start);
+    const j = i >= 0 ? text.indexOf(end, i) : -1;
+    if (i >= 0 && j >= 0)
+        return text.slice(0, i) + b + text.slice(j + end.length);
+    if (!text.trim())
+        return b + eol;
+    return text.replace(/\s*$/, '') + eol + eol + b + eol;
+}
+/** Our block taken out, with the blank line that separated it. Everything else stays. */
+export function removeBlock(text, start, end) {
+    const i = text.indexOf(start);
+    const j = i >= 0 ? text.indexOf(end, i) : -1;
+    if (i < 0 || j < 0)
+        return text;
+    const before = text.slice(0, i).replace(/(\r?\n)*$/, '');
+    const after = text.slice(j + end.length).replace(/^(\r?\n)*/, '');
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    if (!before)
+        return after;
+    return after ? before + eol + eol + after : before + eol;
+}
+/** The repository root when `dir` is inside a git work tree, else `dir` itself. */
+export function projectRoot(dir) {
+    try {
+        const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, timeout: 5_000,
+        }).trim();
+        return top || dir;
+    }
+    catch {
+        return dir;
+    }
+}
+/** Write (or remove) the block in `<root>/AGENTS.md` and make CLAUDE.md import it. */
+export function writeProjectAgentsMd(opts) {
+    const root = projectRoot(resolve(opts.dir));
+    const [start, end] = opts.mcp ? [MCP_BLOCK_START, MCP_BLOCK_END] : [CLI_BLOCK_START, CLI_BLOCK_END];
+    const agentsPath = join(root, 'AGENTS.md');
+    const claudePath = join(root, 'CLAUDE.md');
+    const files = [];
+    const had = existsSync(agentsPath);
+    const before = had ? readFileSync(agentsPath, 'utf8') : '';
+    if (opts.remove) {
+        const next = removeBlock(before, start, end);
+        if (next !== before)
+            writeFileSync(agentsPath, next);
+        files.push({ path: agentsPath, change: next !== before ? 'removed' : 'absent' });
+        return { root, files };
+    }
+    const next = spliceBlock(before, opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock(), start, end);
+    if (next !== before)
+        writeFileSync(agentsPath, next);
+    files.push({ path: agentsPath, change: !had ? 'created' : next !== before ? 'updated' : 'current' });
+    const claude = existsSync(claudePath) ? readFileSync(claudePath, 'utf8') : null;
+    if (claude === null) {
+        writeFileSync(claudePath, CLAUDE_MD_IMPORT + '\n');
+        files.push({ path: claudePath, change: 'created' });
+    }
+    else if (!claude.split(/\r?\n/).some((l) => l.trim() === CLAUDE_MD_IMPORT)) {
+        const eol = claude.includes('\r\n') ? '\r\n' : '\n';
+        writeFileSync(claudePath, claude.replace(/\s*$/, '') + (claude.trim() ? eol + eol : '') + CLAUDE_MD_IMPORT + eol);
+        files.push({ path: claudePath, change: 'updated' });
+    }
+    else {
+        files.push({ path: claudePath, change: 'current' });
+    }
+    return { root, files };
+}
+export function cmdAgentsMd(dir, opts) {
+    if (opts.print) {
+        process.stdout.write((opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock()) + '\n');
+        return 0;
+    }
+    let r;
+    try {
+        r = writeProjectAgentsMd({ dir: dir ?? process.cwd(), mcp: opts.mcp, remove: opts.remove });
+    }
+    catch (err) {
+        console.error(`  ${color.red('✗')} ${err?.message ?? err}`);
+        return 1;
+    }
+    console.log('');
+    for (const f of r.files) {
+        const mark = f.change === 'current' || f.change === 'absent' ? color.dim('·') : color.green('✓');
+        console.log(`  ${mark} ${f.path}  ${color.dim(f.change)}`);
+    }
+    const changed = r.files.some((f) => f.change !== 'current' && f.change !== 'absent');
+    if (changed && !opts.remove) {
+        console.log(color.dim(`\n  Commit ${r.files.map((f) => f.path.slice(r.root.length + 1)).join(' and ')} so every agent that opens this project knows the workspace.`));
+    }
+    console.log('');
+    return 0;
+}

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/help.js

@@ -413,6 +413,27 @@ const PAGES = {
     \`beehaven login\` to connect the CLI to it.`,
         related: ['login', 'guide'],
     },
+    'agents-md': {
+        synopsis: 'beehaven agents-md [dir] [--mcp] [--print] [--remove]',
+        description: `Add the Clearly block to this project's AGENTS.md, so every agent that opens the
+    repository — a teammate's Codex or Claude Code, a cloud agent, CI — knows the workspace and how
+    to reach it. Writes at the git root (or the directory given), and makes CLAUDE.md import it with
+    one \`@AGENTS.md\` line. Needs no login.
+
+    The block sits between Clearly's markers: run it again to update the block, and everything
+    else in the file stays as it was. \`beehaven login\` already teaches the agents on THIS machine
+    (their global instruction files); this is the shared, committed copy for everyone else.`,
+        flags: [
+            { name: '--mcp', desc: 'Write the block for agents connected over MCP instead of the CLI' },
+            { name: '--print', desc: 'Print the block and write nothing' },
+            { name: '--remove', desc: 'Take the block out again' },
+        ],
+        examples: [
+            { cmd: 'beehaven agents-md', note: 'AGENTS.md + CLAUDE.md at the repository root' },
+            { cmd: 'beehaven agents-md --mcp', note: 'for a team that connects over MCP' },
+        ],
+        related: ['skills', 'login'],
+    },
     handoff: {
         synopsis: 'beehaven handoff [file.md|-] [--tasks tasks.md|json] [--csv data.csv]… [--title "…"] [--wait] [--json]',
         description: `Give a person your work when they have no Clearly account yet. Needs no login.

package/dist/commands/self-update.js

@@ -43,9 +43,10 @@ import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { join, sep } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { usableUpdateDigest } from '../version-utils.js';
+import { compareVersions, usableUpdateDigest } from '../version-utils.js';
+import { npmUpdatePlan, latestNpmVersion, installedNpmVersion, installNpmVersionSync } from '../npm-update.js';
 /**
  * Which install this process is.
  *
@@ -83,8 +84,9 @@ export function updateHint(kind = installKind()) {
         return 'Run \x1b[1mbeehaven update\x1b[0m';
     if (kind === 'npx')
         return 'Run `npx @clearlysh/beehaven@latest` for the current npm release.';
+    // npm installs update themselves since CAN2-57 (the daemon hourly, `beehaven update` on demand).
     if (kind === 'npm')
-        return 'Run `npm install -g @clearlysh/beehaven@latest` to update this npm install.';
+        return 'Run \x1b[1mbeehaven update\x1b[0m (or `npm install -g @clearlysh/beehaven@latest`).';
     return 'This is a linked dev build — `npm run build` in beehaven_sdk/packages/cli.';
 }
 /**
@@ -113,9 +115,11 @@ export function runSelfUpdate(kind = installKind()) {
     if (kind === 'linked') {
         return { ok: false, message: 'This is a linked development build — refusing to overwrite it.\n  cd beehaven_sdk/packages/cli && npm run build' };
     }
-    if (kind === 'npm' || kind === 'npx') {
+    if (kind === 'npx') {
         return { ok: false, message: updateHint(kind) };
     }
+    if (kind === 'npm')
+        return runNpmSelfUpdate();
     const feed = (process.env.BEEHAVEN_CLI_FEED || 'https://downloads.clearly.sh/cli/').replace(/\/+$/, '');
     const installerUrl = process.env.BEEHAVEN_INSTALL_URL || 'https://www.clearly.sh/install.sh';
     const temp = mkdtempSync(join(tmpdir(), 'beehaven-self-update-'));
@@ -154,9 +158,32 @@ export function runSelfUpdate(kind = installKind()) {
         rmSync(temp, { recursive: true, force: true });
     }
 }
+/**
+ * ⚠ npm installs (the only Windows install) update with npm itself — see `npm-update.ts` for why
+ * it refuses rather than guessing when this copy is not npm's global install or the prefix is not
+ * writable. The daemon restarts itself after ITS hourly update; after this manual one the running
+ * daemon keeps the old code until restarted, so the message says so.
+ */
+function runNpmSelfUpdate() {
+    const manual = 'Update it by hand: npm install -g @clearlysh/beehaven@latest';
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const plan = npmUpdatePlan(pkgRoot);
+    if (!plan.ok)
+        return { ok: false, message: `Can't update this npm install here: ${plan.reason}.\n  ${manual}` };
+    const latest = latestNpmVersion(plan.npm);
+    if (!latest)
+        return { ok: false, message: `Update failed: could not read the latest version from npm.\n  ${manual}` };
+    const current = installedNpmVersion(plan.globalRoot) ?? '0.0.0';
+    if (compareVersions(latest, current) <= 0)
+        return { ok: true, message: `Already up to date (${current}).` };
+    const r = installNpmVersionSync(plan, latest);
+    return r.ok
+        ? { ok: true, message: `${r.message} A daemon that is already running keeps the old version until: beehaven restart` }
+        : { ok: false, message: `${r.message}\n  ${manual}` };
+}
 /** True when this install can update itself at all — what the notifier uses to pick its wording. */
 export function canSelfUpdate(kind = installKind()) {
-    return kind === 'user';
+    return kind === 'user' || kind === 'npm';
 }
 /**
  * Is a bundled CLI present that the shell can NEVER reach, whatever its version?

package/dist/commands/workspace.js

@@ -26,7 +26,10 @@ 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';
-export function getTimeout(values) {
+/** 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.
     // The default is generous because real jobs (sticker-sheet gen, renders,
     // long agent turns) routinely run well past the old 30s and shouldn't need a
@@ -37,7 +40,8 @@ export function getTimeout(values) {
     const env = process.env.BEEHAVEN_RPC_TIMEOUT_MS;
     if (env && Number.isFinite(Number(env)) && Number(env) > 0)
         return parseInt(env, 10);
-    return 180_000;
+    // 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;
 }
 /**
  * True when `msg` says `action` isn't available on the target DO.
@@ -618,11 +622,24 @@ export async function cmdActions(values, positional) {
                 grouped.set(cat, []);
             grouped.get(cat).push(action);
         }
+        if (!values.verbose && !values.category && !values.search) {
+            for (const [category, entries] of grouped) {
+                console.log(`  ${category.padEnd(18)} ${String(entries.length).padStart(3)} actions · ${entries.slice(0, 3).map(a => a.name).join(', ')}${entries.length > 3 ? ', …' : ''}`);
+            }
+            console.log('');
+            console.log('  Find an action: beehaven actions --search <term>');
+            console.log('  List a category: beehaven actions --category <name>');
+            console.log('  Exact schema: beehaven explain <action>');
+            console.log('  Complete inventory: beehaven actions --verbose or --format full --json');
+            return;
+        }
         for (const [category, catActions] of grouped) {
             const catLabel = category.charAt(0).toUpperCase() + category.slice(1);
             console.log(`  \x1b[36m${catLabel}\x1b[0m (${catActions.length})`);
             for (const a of catActions) {
-                const desc = a.description ? `  \x1b[90m${a.description}\x1b[0m` : '';
+                const description = String(a.description || '');
+                const display = values.verbose || description.length <= 160 ? description : `${description.slice(0, 157)}…`;
+                const desc = display ? `  \x1b[90m${display}\x1b[0m` : '';
                 const aliasLabel = Array.isArray(a.aliases) && a.aliases.length > 0
                     ? `  \x1b[2m(also: ${a.aliases.join(', ')})\x1b[0m`
                     : '';
@@ -1088,7 +1105,7 @@ export async function cmdCall(action, rawInput, values) {
         console.error(`\x1b[2m→ ${target}  ${action}${who}\x1b[0m`);
     }
     try {
-        const raw = await rpcOnce(resolved.action, resolved.input, getTimeout(values));
+        const raw = await rpcOnce(resolved.action, resolved.input, getTimeout(values, action));
         // Unwrap proxy envelope: admin:*-rpc wraps results in { type: 'ack', result: ... }
         const result = raw?.type === 'ack' && raw?.result !== undefined
             ? raw.result
@@ -3090,7 +3107,7 @@ export async function cmdAgent(prompt, values) {
                 : {}),
         }, 
         // Omni runs tools; the CLI default is far too short for a real turn.
-        getTimeout(values) || 180_000);
+        getTimeout(values, 'agent-turn'));
         /**
          * Print the REPLY, not the envelope. The whole response is still available
          * with `--json` — but a verb whose entire purpose is "ask a question and read

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