beehaven 0.8.16

package/dist/commands/shell.js

@@ -0,0 +1,1048 @@
+/**
+ * beehaven shell — Execute commands on a live Durable Object.
+ *
+ * The DO's pseudo-shell supports: ls, cat, grep, find, tree, echo, head, tail,
+ * wc, sort, jq, sql, mkdir, rm, mv, cp, pipes (|), redirects (> >>).
+ *
+ * Usage:
+ *   beehaven shell <building-type> <building-id> "<command>"
+ *   beehaven shell salon lunas "ls /folders/products/"
+ *   beehaven shell salon lunas "cat /folders/products/haircut.json"
+ *   beehaven shell salon lunas "sql 'SELECT * FROM products WHERE price > 50'"
+ *   beehaven shell salon lunas "grep urgent /folders/notes/"
+ *
+ * Shorthand (when building is configured in beehaven.json):
+ *   beehaven ls /folders/products/
+ *   beehaven cat /folders/products/haircut.json
+ *   beehaven sql "SELECT * FROM products"
+ *   beehaven grep draft /folders/notes/
+ *
+ * Logs:
+ *   beehaven logs <building-type> <building-id>              # syslog
+ *   beehaven logs <building-type> <building-id> --ws         # WS message log
+ *   beehaven logs <building-type> <building-id> --ops        # operation audit
+ *   beehaven logs <building-type> <building-id> --triggers   # trigger metrics
+ */
+import WebSocket from 'ws';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { daemonGetConnection } from '../daemon-client.js';
+import { getTarget, HOME_ADDRESSES } from '../cli-state.js';
+/**
+ * ⚠ A PURE LEAF, IMPORTED EAGERLY ON PURPOSE. `shell-output.ts` has no imports of its own and no
+ * side effects, and this module is itself lazily loaded by `cli.ts`, so there is nothing to defer.
+ * The eager-import budget is a rule about `cli.ts`, not about command modules.
+ */
+import { formatShellResult, formatFailure, breadcrumbAddress, grepAttributionFlags, } from './shell-output.js';
+const DEFAULT_PORT = 8787;
+/**
+ * Execute a single shell command on a DO.
+ * Connect → auth → shell:exec → print stdout → disconnect.
+ */
+export async function shell(args, opts = {}) {
+    if (args.length < 3) {
+        console.error('Usage: beehaven shell <building-type> <building-id> "<command>"');
+        console.error('  e.g. beehaven shell salon lunas "ls /folders/products/"');
+        process.exit(1);
+    }
+    const [buildingType, buildingId, ...commandParts] = args;
+    const command = commandParts.join(' ');
+    if (!command) {
+        console.error('Missing command. Usage: beehaven shell salon lunas "ls /folders/"');
+        process.exit(1);
+    }
+    const result = await execRemote(buildingType, buildingId, command, opts);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    if (result.exitCode !== 0)
+        process.exit(result.exitCode);
+}
+/**
+ * Fetch logs from a DO. Defaults to syslog (the `_log()` ring buffer that
+ * webhook handlers and worker-side RPCs write to via `this._log(level,
+ * event, detail)`). Other surfaces:
+ *
+ *   --ops        operation audit (admin-only, _opsAudit ring buffer)
+ *   --ws         WebSocket message log
+ *   --triggers   trigger metrics
+ *
+ * Target resolution: same as VFS shorthand — uses `beehaven cd` target if
+ * no <type> <id> args are given. So once you `beehaven cd home`, plain
+ * `beehaven logs` shows your home workspace's syslog (honey credits,
+ * Stripe events, errors).
+ */
+export async function logs(args, opts = {}) {
+    // Resolve target: positional <type> <id> wins, then fall through to
+    // the same resolver `beehaven ls` / `cat` / etc. use.
+    let buildingType;
+    let buildingId;
+    if (args.length >= 2) {
+        [buildingType, buildingId] = args;
+    }
+    else {
+        const resolved = await resolveDefaultBuilding();
+        buildingType = resolved.buildingType;
+        buildingId = resolved.buildingId;
+    }
+    // Mode selection. Default = syslog for human-readable event log.
+    // --ops / --ws / --triggers fall back to the original debug protocol.
+    if (opts.ops || opts.ws || opts.triggers) {
+        let debugType = 'debug:audit';
+        if (opts.ws)
+            debugType = 'debug:messages';
+        if (opts.triggers)
+            debugType = 'debug:triggers';
+        const result = await execDebug(buildingType, buildingId, debugType, opts);
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Syslog path — works for the home workspace and any DO that uses
+    // `_log()`. We read /var/log/syslog directly via the shell.exec
+    // path so this works whether or not the user is admin (cat respects
+    // the same VFS read perms as ls/grep).
+    const limit = parseInt(opts.limit ?? '50', 10) || 50;
+    // tail -n <limit> /var/log/syslog → human-readable trailing logs.
+    const cmd = `tail -n ${limit} /var/log/syslog`;
+    const result = await execRemote(buildingType, buildingId, cmd, opts);
+    if (result.exitCode === 0) {
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        return;
+    }
+    // Fallback: try the admin _admin:logs action via daemonRpc (works
+    // for the home workspace where we can't always shell-cat /var/log).
+    try {
+        const { daemonRpc, isDaemonRunning } = await import('../daemon-client.js');
+        if (await isDaemonRunning()) {
+            const r = buildingType === 'home'
+                ? await daemonRpc('_admin:logs', { limit, level: opts.level })
+                : await daemonRpc(`admin:${buildingType}-rpc`, {
+                    storeId: buildingId,
+                    action: '_admin:logs',
+                    input: { limit, level: opts.level },
+                });
+            const inner = r?.result ?? r;
+            const events = inner?.logs ?? [];
+            for (const e of events) {
+                const ts = new Date(e.timestamp).toISOString();
+                const lvl = (e.level ?? 'info').toUpperCase().padEnd(5);
+                const detail = e.detail ?? '';
+                console.log(`${ts}  ${lvl}  ${e.event}${detail ? '  ' + detail : ''}`);
+            }
+            return;
+        }
+    }
+    catch {
+        /* fall through to error */
+    }
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exit(result.exitCode || 1);
+}
+/**
+ * Shorthand: beehaven ls /folders/ → shell exec "ls /folders/"
+ *
+ * Building resolution order (first hit wins):
+ *   1. Active `beehaven connect` session — via daemon IPC. This is the
+ *      canonical path and matches what `beehaven actions` / `call` /
+ *      `workspace` use. Per CLAUDE.md: "Once connected, every other
+ *      command auto-routes to that target."
+ *   2. beehaven.json in the current directory (project-local default).
+ *   3. Legacy credentials.json (admin `--url/--secret` flow).
+ *
+ * Previously this only checked (2) and (3) — so `connect` state was
+ * silently dropped for every VFS command, and users got "Cannot
+ * determine building" even though they'd just connected successfully.
+ */
+/**
+ * ── WHICH FILESYSTEM ANSWERS ──────────────────────────────────────────────────────────────────
+ *
+ * There are two, and until now these verbs only ever reached the wrong one for the common case.
+ *
+ *   • The **VFS** (`shell:exec`) — mounts, block files, `/shop/tickets/`, `/folders/notes/`. Its
+ *     note listing is uuids: `0044f8ac-….json  005a5ecc-….json  … 929 more`.
+ *   • The **notes shell** (`bash`) — the same notes as a filesystem where paths are TITLES:
+ *     `ls ~` → `Batch demo/  Clearly SEO/  Q1/`, and `grep -ril pricing ~` works.
+ *
+ * `CLAUDE.md` used to explain that there was no notes terminal because "the prerequisite is a
+ * title-based namespace, not the shell". That namespace was built; nothing repointed these verbs
+ * at it, so `beehaven ls` kept printing uuids — a shell over 929 opaque names, which is exactly
+ * the thing that argument said was not worth shipping.
+ *
+ * ⚠ ROUTED BY PATH, NOT SWITCHED WHOLESALE. The VFS serves paths the notes shell knows nothing
+ * about, so a blanket repoint would break `/shop/...`, block files and `/folders/...`. A bare verb
+ * or a `~`-rooted / relative path is a question about NOTES; an absolute path outside the notes
+ * roots is a question about the VFS.
+ *
+ * ⚠ AND IT DEGRADES. `bash` only exists on a Clearly workspace; a generic hive has no such action.
+ * An "unknown action" answer falls back to the VFS rather than failing, so this is an upgrade for
+ * the DOs that have it and a no-op everywhere else.
+ */
+const NOTES_ROOTS = ['~', '/home', '/code', '/local'];
+/**
+ * ⚠ THE SHELL EATS `~` BEFORE THE CLI EVER SEES IT. `beehaven ls ~/Q1` arrives as
+ * `ls /Users/you/Q1`, so the one spelling every tool description teaches lands as an absolute
+ * local path, routes to the VFS, and comes back "no such file" for a folder that plainly exists.
+ * Quoting fixes it and nobody thinks to.
+ *
+ * Rewriting it back is safe because a workspace path is never a real local path in these verbs —
+ * the machine has its own namespace (`/local`). Same class of repair `normalizePath` already makes
+ * server-side for `~/~/` and `\/`: it looks like leniency and is a bug fix, because the intent is
+ * not in doubt.
+ */
+export function unexpandHome(arg) {
+    const home = homedir();
+    if (!home || arg === '-' || arg.startsWith('-'))
+        return arg;
+    if (arg === home)
+        return '~';
+    return arg.startsWith(`${home}/`) ? `~${arg.slice(home.length)}` : arg;
+}
+/**
+ * ⚠ THE PATH IS NOT ALWAYS THE FIRST ARGUMENT, and assuming it was mis-routed every `grep`.
+ * `grep PATTERN [PATH]` puts the pattern first, so `grep pricing /folders/notes/` read "pricing"
+ * as the path, saw a bare relative name, and sent a VFS question to the notes shell. Caught by the
+ * test below — which is the only place the difference is visible, because BOTH filesystems answer.
+ * One just answers about the wrong corpus.
+ */
+const PATTERN_FIRST = new Set(['grep', 'jq']);
+export function wantsNotesShell(command, args) {
+    const positional = args.filter((a) => !a.startsWith('-'));
+    const path = PATTERN_FIRST.has(command) ? positional[1] : positional[0];
+    // No path at all is a question about NOTES: bare `ls`, or `grep foo` with nothing scoping it.
+    if (!path)
+        return true;
+    if (path.startsWith('~'))
+        return true;
+    if (!path.startsWith('/'))
+        return true; // relative — the notes shell normalizes it
+    return NOTES_ROOTS.some((r) => path === r || path.startsWith(`${r}/`));
+}
+/**
+ * ⚠⚠ ONE ARGUMENT MUST SURVIVE AS ONE ARGUMENT. The caller's own shell has already stripped the
+ * quotes, so `beehaven cat "~/CLR-47 The Beaching.md"` reaches us as ONE argv entry containing
+ * spaces — and joining the array back into a command string hands the REMOTE shell three paths.
+ *
+ * Measured live on hive2 2026-08-19: `beehaven cat "/home/CLR-47 The Beaching.md"` answered
+ * `cat: The: No such file or directory`. It has always been broken for multi-word titles; it became
+ * broken for EVERY note the day filenames gained a key prefix, because `CLR-47 The Beaching.md`
+ * has a space in it by construction.
+ *
+ * ⚠ SINGLE QUOTES, WITH THE POSIX ESCAPE FOR AN EMBEDDED ONE (`'\''`). Double quotes would leave
+ * `$`, backticks and `\` live inside the string — a filename containing `$` is unusual but a
+ * filename that silently expands to something else is a data bug, not a display one.
+ *
+ * ⚠ ARGUMENTS THAT NEED NOTHING ARE LEFT BARE, so the routing breadcrumb and the notes-shell
+ * command still read like the command a person would type. Quoting everything would turn
+ * `ls ~` into `ls '~'` — and `~` must reach the remote tokenizer UNQUOTED or it stops expanding.
+ */
+/**
+ * Verbs whose argument is the REST OF THE LINE rather than a list of arguments.
+ *
+ * ⚠ A NAMED SET, NEVER A HEURISTIC ("does it look like SQL?"). Getting it wrong in one direction
+ * breaks a statement; in the other it un-quotes a filename with a space in it, which is the bug
+ * `shellQuoteArg` was written to fix.
+ */
+export const REST_OF_LINE_COMMANDS = new Set(['sql']);
+export function shellQuoteArg(arg) {
+    if (arg === '')
+        return "''";
+    // Bare when it is plainly safe: no whitespace, no quote, no shell metacharacter.
+    if (/^[A-Za-z0-9_@%+=:,.\/~^-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The command line sent to the remote shell.
+ *
+ * ⚠ EXPORTED AND PURE SO THE BEHAVIOUR CAN BE TESTED, not just the lookup table. A first version
+ * left this inline and asserted only on `REST_OF_LINE_COMMANDS`; deleting the branch that READS
+ * that set then changed nothing any test could see. The set and the branch are one claim.
+ */
+/**
+ * Wrap a whole statement as ONE argument for the remote shell.
+ *
+ * ⚠⚠ DOUBLE QUOTES, ESCAPING ONLY `"` AND `\` — NOT `shellQuoteArg`. That helper wraps in SINGLE
+ * quotes and POSIX-escapes any inner `'` as `'\''`, and SQL string literals are written with `'`:
+ * `SELECT 'a' AS y` would reach SQLite carrying literal backslashes. That is exactly why `sql` was
+ * exempted from quoting in the first place, and why the exemption then made `>` unusable.
+ */
+export function sqlQuoteStatement(stmt) {
+    return `"${stmt.replace(/(["\\])/g, '\\$1')}"`;
+}
+export function buildShellCommand(command, args) {
+    if (!REST_OF_LINE_COMMANDS.has(command)) {
+        return `${command} ${args.map(shellQuoteArg).join(' ')}`.trim();
+    }
+    /**
+     * ⚠⚠ THE STATEMENT IS QUOTED NOW, AND SENDING IT BARE MADE `>` UNUSABLE FROM THIS CLI.
+     *
+     * Measured on staging, both spellings of the same question failed:
+     *   beehaven sql "SELECT … WHERE created_at > 178…"  -> `>` was read as a shell REDIRECT
+     *   sql "SELECT …"   (quotes reaching the handler)   -> must begin with SELECT
+     * …while the identical statement through `workspace-sql` returned rows. Two shut doors on the
+     * one verb that answers what a keyword search cannot.
+     *
+     * ⚠⚠ IT REQUIRES THE WORKER THAT STRIPS THE WRAPPER — DEPLOY THAT FIRST. Against an older
+     * worker every `sql` from this CLI is refused for not beginning with SELECT. That is the
+     * standing worker-before-frontend rule, and this is a case where it genuinely bites.
+     *
+     * ⚠ AN EMPTY REST OF LINE STAYS BARE. `sql` with no statement returns the SCHEMA; `sql ""` is a
+     * quoted nothing, which is a different question.
+     */
+    const rest = args.join(' ').trim();
+    return rest ? `${command} ${sqlQuoteStatement(rest)}` : command;
+}
+export async function shorthand(command, args, opts = {}) {
+    const { buildingType, buildingId } = await resolveDefaultBuilding();
+    // ⚠ BEFORE the routing decision AND before the command string — see `unexpandHome`.
+    const shellArgs = args.map(unexpandHome);
+    /**
+     * ⚠⚠ ASK `grep` FOR THE ATTRIBUTION IT ALREADY KNOWS HOW TO SEND — see `grepAttributionFlags`.
+     * A directory target auto-recurses but the builtin only prints filenames when `-r` was TYPED,
+     * so every recursive search came back as bare lines with no way to tell which document each
+     * came from. Injected here rather than in `buildShellCommand` because it is a grep decision,
+     * not a quoting one, and `wantsNotesShell` below must still see the caller's own operands.
+     */
+    const cmdArgs = command === 'grep'
+        ? [...grepAttributionFlags(shellArgs), ...shellArgs]
+        : shellArgs;
+    /**
+     * ⚠ QUOTED, not joined raw — see `shellQuoteArg`. `wantsNotesShell` is still handed the
+     * UNQUOTED args below, because it inspects paths rather than re-parsing a command line.
+     *
+     * ⚠⚠ EXCEPT WHERE THE ARGUMENT IS THE REST OF THE LINE. `sql` does not take arguments, it takes
+     * a STATEMENT: the remote builtin reads everything after the verb verbatim, and quotes inside it
+     * are SQL syntax rather than shell syntax. Quoting the whole thing produced
+     * `sql 'SELECT 1 AS x'`, which the read-only guard then refused for *not beginning with SELECT* —
+     * an error naming the one thing the statement plainly does, about a statement typed correctly.
+     *
+     * ⚠ IT WAS HIDDEN, NOT NEW. From a connected session the call was refused earlier for developer
+     * scope and never reached the guard; on `home` it fails identically, so the bug is older than the
+     * routing that was concealing it. Measured both ways.
+     *
+     * ⚠ QUOTING REMAINS RIGHT FOR EVERYTHING ELSE. `cat "CLR-47 The Beaching.md"` is the case
+     * `shellQuoteArg` exists for, and a `grep` pattern containing spaces is genuinely ONE argument.
+     * Only a rest-of-line verb is exempt, which is why this is a named set rather than a heuristic.
+     */
+    const fullCommand = buildShellCommand(command, cmdArgs);
+    // ── The notes shell, when the path is a notes question ──
+    if (wantsNotesShell(command, shellArgs)) {
+        const viaNotes = await execNotesShell(buildingType, buildingId, fullCommand);
+        if (viaNotes.result) {
+            // ⚠ NAME THE FILESYSTEM. The two answer the same command with different worlds — titles
+            // here, uuids there — and without this the difference reads as a bug rather than a route.
+            process.stderr.write(`\x1b[2m→ ${breadcrumbAddress(buildingType, buildingId)}  ${fullCommand}  (notes)\x1b[0m\n`);
+            if (viaNotes.result.stdout)
+                process.stdout.write(viaNotes.result.stdout);
+            if (viaNotes.result.stderr)
+                process.stderr.write(viaNotes.result.stderr);
+            if (viaNotes.result.exitCode !== 0)
+                process.exit(viaNotes.result.exitCode);
+            return;
+        }
+        /**
+         * ⚠⚠ CBH2-61 — A FAILED CALL MUST NOT BE ANSWERED BY A DIFFERENT FILESYSTEM. Falling through
+         * here is what produced *"RPC shell:exec requires developer scope"* for a dropped socket: the
+         * wrong filesystem, a permission the caller does not need, and a fix that cannot help.
+         */
+        if (viaNotes.transportError) {
+            process.stderr.write(notesShellTransportRefusal(viaNotes.transportError, fullCommand));
+            process.exit(1);
+        }
+        // else: no `bash` on this DO — fall through to the VFS exactly as before.
+        /**
+         * ⚠⚠ A NULL FROM `execNotesShell` MEANS EITHER "no notes shell here" OR "no daemon", AND THE
+         * SECOND ONE MUST NOT FALL THROUGH.
+         *
+         * `resolveDefaultBuilding` now answers `home` instead of refusing, which is right — but it
+         * turned the daemon-down case into a `getWsUrl` fallback at `127.0.0.1:8787` and the message
+         * *"WebSocket error: connect ECONNREFUSED 127.0.0.1"*. That is strictly worse than the refusal
+         * it replaced: it names a local dev server the caller never asked for, on a workspace command.
+         * Caught immediately after the change by running `ls ~` against a daemon that was still coming
+         * up.
+         *
+         * ⚠ ONLY FOR `home`. A real `<type>/<id>` target may legitimately be served over `--url`
+         * without a daemon, which is what `execRemote` is for.
+         */
+        if (buildingType === 'home') {
+            const { isDaemonRunning } = await import('../daemon-client.js');
+            if (!(await isDaemonRunning())) {
+                console.error('  Cannot connect to daemon — your workspace is reached through it.');
+                console.error('');
+                console.error('    beehaven status                  # is it running, and is the relay up?');
+                console.error('    beehaven start --headless        # start one without the Mac app');
+                console.error('');
+                process.exit(1);
+            }
+        }
+    }
+    // Routing breadcrumb on stderr so the VFS output on stdout stays clean
+    // and pipeable. Agents can read this to self-correct if they're on the
+    // wrong DO.
+    process.stderr.write(`\x1b[2m→ ${breadcrumbAddress(buildingType, buildingId)}  ${fullCommand}\x1b[0m\n`);
+    const result = await execRemote(buildingType, buildingId, fullCommand, opts);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    if (result.exitCode !== 0) {
+        // Give the agent a nav hint on any VFS command failure.
+        /**
+         * ⚠ THIS USED TO SUGGEST `beehaven ls /` — CLR-1148. A leading `/` outside the four
+         * notes roots is a RAW VFS path, which routes to `shell:exec` and needs DEVELOPER
+         * scope. So a consumer-scope user following the recovery hint traded one error for a
+         * scarier one about permissions. `ls ~` is the notes shell and needs no scope.
+         */
+        process.stderr.write('\n\x1b[2m  Try:\n');
+        process.stderr.write('    beehaven pwd                  # confirm target\n');
+        process.stderr.write('    beehaven ls ~                  # the notes workspace (no extra scope)\n');
+        process.stderr.write('    beehaven ls /                  # the raw VFS (needs developer scope)\x1b[0m\n');
+        process.exit(result.exitCode);
+    }
+}
+/**
+ * beehaven write <path> <content> — overwrite a VFS file.
+ *
+ * Marshals the content to the DO pseudo-shell as `echo '<content>' > <path>`
+ * (single-quoted, so the local shell never sees a `>` redirect to mangle).
+ * On a CompositionsMount path this lands in `this.fs.write` → `writeSync` →
+ * the canvas blob. JSON content is safe; single quotes can't be escaped by the
+ * DO tokenizer, so we reject them and point at `composition-patch`.
+ */
+/**
+ * ⚠⚠ THE NOTES DOOR FOR `write`/`edit` — WITHOUT IT THEY DEMAND DEVELOPER SCOPE (fixed 2026-09-04).
+ *
+ * The read verbs (`ls`, `cat`, `grep`, `tree`, `head`, `tail`, `wc`, `sql`) and the organise verbs
+ * (`mkdir`, `cp`, `mv`) were repointed to the notes shell; `write` and `edit` were left on the OLD
+ * path, which builds `echo '<content>' > <path>` and runs it through `shell:exec`. Measured against
+ * a daemon with no `HIVE_DEV_MODE`: *"RPC 'shell:exec' requires developer scope"* on both, while
+ * every sibling verb worked. CLAUDE.md's note that these verbs no longer need dev scope is correct
+ * about the reads and silent about these two, so the gap was undocumented as well as unfixed.
+ *
+ * ⚠ `notes-write` / `notes-edit` ALREADY EXISTED, aliased `write`/`edit`, on the agent allowlist,
+ * needing no dev scope. Nothing new is built here — the CLI was calling the wrong thing.
+ *
+ * ⚠ AND IT REMOVES A REAL LIMITATION, NOT JUST A PERMISSION. The old path REFUSED any content
+ * containing a single quote, because it could not escape one into `echo '…'`. An apostrophe is
+ * ordinary English, so `write` could not write an ordinary sentence. The RPC takes the content as
+ * a JSON field, so there is nothing to escape.
+ *
+ * ⚠ IT ALSO GAINS THE THINGS THE SHELL PATH SKIPPED — version capture, FTS reindex, preview
+ * regeneration and the broadcast to open tabs — because it is the same verb the editor calls.
+ *
+ * ⚠ NON-NOTES PATHS STILL TAKE THE OLD ROUTE. `/compositions/<id>/blocks/<bid>.json` is a genuine
+ * VFS path with no notes equivalent, and that is what the usage line has always advertised.
+ */
+/**
+ * ⚠ RETURNS THE SAME THREE-STATE OUTCOME AS `execNotesShell` — CBH2-61 lived here TOO. This ended
+ * `catch { return null }` and `write`/`edit` read `null` as "no notes shell", falling through to
+ * the `echo … > path` VFS route and its developer-scope refusal. Same wrong cause, same wrong fix,
+ * on the two verbs that MUTATE — where "did it half-happen?" is the first question a caller has.
+ * The workspace's own reply rides in `result`, so the existing `{error, code, hint}` handling
+ * downstream is unchanged.
+ */
+async function notesWriteRpc(action, input) {
+    try {
+        const { isDaemonRunning, daemonRpc } = await import('../daemon-client.js');
+        // ⚠ See `execNotesShell` — no daemon stays `absent` so the `--url` fallback keeps working.
+        if (!(await isDaemonRunning()))
+            return { absent: true };
+        const { buildingType, buildingId } = await resolveDefaultBuilding();
+        let raw;
+        if (buildingType === 'home') {
+            raw = await daemonRpc(action, input);
+        }
+        else {
+            const { gatewayEnvelope } = await import('./workspace.js');
+            const gw = gatewayEnvelope(buildingType, buildingId, action, input);
+            raw = await daemonRpc(gw.gateway, gw.payload);
+        }
+        const r = raw?.result ?? raw;
+        // ⚠ Same probe `execNotesShell` uses — a DO with no notes palette must fall through, not fail.
+        if (/unknown (action|message type)/i.test(String(r?.error ?? '')))
+            return { absent: true };
+        return { result: r };
+    }
+    catch (e) {
+        // ⚠ CBH2-61 — was `return null`, i.e. a dropped socket answered as a permission problem.
+        return classifyNotesShellFailure(e);
+    }
+}
+export async function fsWrite(path, content, opts = {}) {
+    if (!path) {
+        console.error('Usage: beehaven write <path> <content>');
+        console.error('  e.g. beehaven write /compositions/<id>/blocks/<bid>.json \'{"id":"<bid>","type":"text",...}\'');
+        process.exit(1);
+    }
+    if (wantsNotesShell('write', [path])) {
+        const outcome = await notesWriteRpc('notes-write', { file_path: unexpandHome(path), content });
+        // ⚠ CBH2-61 — a failed CALL is not an absent shell, and on a mutation the caller must be told
+        // plainly that nothing was written rather than sent to fix a permission they already have.
+        if (outcome.transportError) {
+            process.stderr.write(notesShellTransportRefusal(outcome.transportError, 'write'));
+            process.exit(1);
+        }
+        const r = outcome.result;
+        if (r) {
+            const { buildingType, buildingId } = await resolveDefaultBuilding();
+            process.stderr.write(`\x1b[2m→ ${breadcrumbAddress(buildingType, buildingId)}  write ${path}  (notes)\x1b[0m\n`);
+            /**
+             * ⚠ THE SAME FORMATTER THE SHELL VERBS USE — it was dropping `hint` here and `hint` AND
+             * `code` in `fsEdit`, so two verbs in one family reported the same refusal differently and
+             * neither reported all of it. `notes-write` returns the same `{error, code, hint}` triple
+             * `mv`/`rm`/`cp` do.
+             */
+            if (r.error || r.ok === false) {
+                process.stderr.write(formatFailure(r, 'write'));
+                process.exit(1);
+            }
+            /**
+             * ⚠⚠ `file_path`, NOT `path` — AND NOT THE PATH THAT WAS TYPED. `Write` derives the title
+             * from the BODY's first line, so `write ~/Alpha.md 'first line…'` genuinely creates
+             * `~/S13-1 first line….md`; the RPC knows this and echoes where the note ACTUALLY landed.
+             * Reading a field it does not return fell back to the requested name, so the CLI printed an
+             * address that never existed and the next `cat` answered "No such file or directory" —
+             * measured on a live workspace during the 2026-09-04 sweep.
+             */
+            process.stdout.write(`wrote ${r.file_path ?? r.path ?? path}\n`);
+            return;
+        }
+    }
+    if (content.includes("'")) {
+        console.error("write: content has a single quote, which the DO shell can't escape. Use `beehaven call composition-patch` for that block.");
+        process.exit(1);
+    }
+    const { buildingType, buildingId } = await resolveDefaultBuilding();
+    process.stderr.write(`\x1b[2m→ ${breadcrumbAddress(buildingType, buildingId)}  write ${path}\x1b[0m\n`);
+    const result = await execRemote(buildingType, buildingId, `echo '${content}' > ${path}`, opts);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    if (result.exitCode !== 0)
+        process.exit(result.exitCode);
+    process.stdout.write(`wrote ${path}\n`);
+}
+/**
+ * beehaven edit <path> <old> <new> — find/replace inside a VFS file.
+ * cat → replace every occurrence of <old> with <new> → write back.
+ */
+export async function fsEdit(path, oldStr, newStr, opts = {}) {
+    if (!path || oldStr === undefined || newStr === undefined) {
+        console.error('Usage: beehaven edit <path> <old> <new>');
+        process.exit(1);
+    }
+    /**
+     * ⚠ SEE `fsWrite` — same repoint, same reason. And `notes-edit` carries a property the
+     * cat-replace-write below cannot: it matches EXACTLY ONCE OR REFUSES. The old path used
+     * `split(old).join(new)`, i.e. a silent replace-all, so an edit meant for one occurrence
+     * changed every one of them and reported success.
+     */
+    if (wantsNotesShell('edit', [path])) {
+        const outcome = await notesWriteRpc('notes-edit', {
+            file_path: unexpandHome(path), old_string: oldStr, new_string: newStr,
+        });
+        // ⚠ CBH2-61 — see `fsWrite`. Falling through here would additionally hand the caller the
+        // OLD cat-replace-write path, whose silent replace-all is the very behaviour this repoint
+        // exists to remove — so a dropped socket would have quietly changed the edit's semantics.
+        if (outcome.transportError) {
+            process.stderr.write(notesShellTransportRefusal(outcome.transportError, 'edit'));
+            process.exit(1);
+        }
+        const r = outcome.result;
+        if (r) {
+            const { buildingType, buildingId } = await resolveDefaultBuilding();
+            process.stderr.write(`\x1b[2m→ ${breadcrumbAddress(buildingType, buildingId)}  edit ${path}  (notes)\x1b[0m\n`);
+            // ⚠ See `fsWrite` — one formatter, so the two halves of this verb family agree.
+            if (r.error || r.ok === false) {
+                process.stderr.write(formatFailure(r, 'edit'));
+                process.exit(1);
+            }
+            // ⚠ `file_path` first — same reason as `fsWrite` above.
+            process.stdout.write(`edited ${r.file_path ?? r.path ?? path}\n`);
+            return;
+        }
+    }
+    const { buildingType, buildingId } = await resolveDefaultBuilding();
+    process.stderr.write(`\x1b[2m→ ${breadcrumbAddress(buildingType, buildingId)}  edit ${path}\x1b[0m\n`);
+    const read = await execRemote(buildingType, buildingId, `cat ${path}`, opts);
+    if (read.exitCode !== 0) {
+        if (read.stderr)
+            process.stderr.write(read.stderr);
+        process.exit(read.exitCode || 1);
+    }
+    const current = read.stdout.replace(/\n$/, '');
+    if (!current.includes(oldStr)) {
+        console.error(`edit: '${oldStr}' not found in ${path}`);
+        process.exit(1);
+    }
+    const next = current.split(oldStr).join(newStr);
+    if (next.includes("'")) {
+        console.error("edit: result has a single quote the DO shell can't escape. Use `beehaven call composition-patch`.");
+        process.exit(1);
+    }
+    const result = await execRemote(buildingType, buildingId, `echo '${next}' > ${path}`, opts);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    if (result.exitCode !== 0)
+        process.exit(result.exitCode);
+    process.stdout.write(`edited ${path}\n`);
+}
+// ── Internal ─────────────────────────────────────────
+async function resolveDefaultBuilding() {
+    // 1. CLI-side target file (stateless design — source of truth since the
+    //    stateless-session PR). Survives daemon restarts.
+    const target = getTarget();
+    if (target?.address?.includes('/')) {
+        const slash = target.address.indexOf('/');
+        return {
+            buildingType: target.address.slice(0, slash),
+            buildingId: target.address.slice(slash + 1),
+        };
+    }
+    // 1b. `home` is the user's default workspace alias — no `<type>/<id>` shape
+    //     because it's the default target the daemon's relay already binds
+    //     to. Surface it as a special tuple so VFS shorthand (ls, cat,
+    //     grep, tree) recognise the case in execRemote and dispatch via
+    //     daemonRpc('shell:exec', …) directly instead of the admin gateway.
+    //
+    //     `cd home` WRITES the canonical address 'workspace' (cli.ts case 'cd'),
+    //     but this only matched the literal 'home' — so immediately after a
+    //     successful `beehaven cd home`, `sql`/`ls`/`cat`/`grep`/`tree` all died
+    //     with "Cannot determine target. You need to pick one:" and told you to
+    //     run the `cd home` you had just run. Match every spelling the cd verb
+    //     accepts, and keep them in one list so a future rename can't re-split
+    //     the writer from the reader.
+    if (target?.address && HOME_ADDRESSES.has(target.address)) {
+        return { buildingType: 'home', buildingId: 'home' };
+    }
+    // 2. Legacy daemon session (for CLIs that predate the stateless design
+    //    and haven't run `cd` since the upgrade). Retained for one release.
+    try {
+        const conn = await daemonGetConnection();
+        if (conn?.buildingType && conn?.buildingId) {
+            return { buildingType: conn.buildingType, buildingId: conn.buildingId };
+        }
+    }
+    catch {
+        /* daemon not running or not connected — try fallbacks */
+    }
+    // 2. beehaven.json in current directory.
+    try {
+        const config = JSON.parse(readFileSync(join(process.cwd(), 'beehaven.json'), 'utf8'));
+        const buildings = config.buildings ?? config.cells ?? {};
+        const types = Object.keys(buildings);
+        if (types.length > 0) {
+            return { buildingType: types[0], buildingId: config.defaultId ?? 'default' };
+        }
+    }
+    catch {
+        /* no beehaven.json — try credentials */
+    }
+    // 3. Legacy ~/.beehaven/credentials.json (admin `--url/--secret` flow).
+    const creds = readCredentials();
+    if (creds.building && creds.buildingId) {
+        return { buildingType: creds.building, buildingId: creds.buildingId };
+    }
+    /**
+     * ⚠⚠ NOTHING RESOLVED ⇒ HOME. THIS USED TO REFUSE, AND TWO SURFACES DISAGREED ABOUT THE SAME
+     * STATE.
+     *
+     * Measured repeatedly on 2026-09-04, one shell, same env, seconds apart:
+     *
+     *     beehaven pwd              -> "Target: home (default workspace alias)"
+     *     beehaven call board-list  -> works
+     *     beehaven ls ~             -> "Cannot determine target. You need to pick one:"
+     *
+     * `pwd` REPORTS the home default and `call` USES it; only the shell verbs demanded an explicit
+     * target. So the CLI told the caller they had a target and then refused to act on it — and the
+     * remedy (`beehaven cd home`) is a command that writes the state `pwd` already claimed existed.
+     *
+     * ⚠ THE SECOND HALF, WHICH IS WHY IT LOOKED INTERMITTENT: the target file is scoped by AGENT
+     * NAME when one is bound and by PPID otherwise, so any script that shells out gets a different
+     * scope and silently loses the target. Defaulting to home makes that invisible rather than
+     * mysterious — and the routing breadcrumb (`→ home/home  ls ~  (notes)`) prints the target on
+     * every shell command, so an unintended home is visible rather than silent.
+     *
+     * ⚠ HOME IS ALWAYS REACHABLE — it is the caller's own workspace, not a guess at somebody's DO.
+     * A wrong GUESS would be worse than a refusal; this is the same answer the other two verbs give.
+     */
+    return { buildingType: 'home', buildingId: 'home' };
+}
+function getWsUrl(buildingType, buildingId, opts) {
+    // Explicit --url flag takes priority
+    if (opts.url) {
+        const base = opts.url.replace(/^http/, 'ws');
+        return `${base}/workspace/${buildingType}/${buildingId}/ws`;
+    }
+    // Check saved credentials (beehaven login --url)
+    const creds = readCredentials();
+    if (creds.workerUrl) {
+        const base = creds.workerUrl.replace(/^http/, 'ws');
+        return `${base}/workspace/${buildingType}/${buildingId}/ws`;
+    }
+    // Fall back to local dev server
+    const port = opts.port ?? DEFAULT_PORT;
+    return `ws://127.0.0.1:${port}/workspace/${buildingType}/${buildingId}/ws`;
+}
+function readCredentials() {
+    const home = process.env.HOME ?? homedir();
+    const credPath = join(home, '.beehaven', 'credentials.json');
+    try {
+        const creds = JSON.parse(readFileSync(credPath, 'utf8'));
+        return {
+            token: creds.token ?? creds.adminSecret ?? '',
+            workerUrl: creds.workerUrl ?? '',
+            building: creds.building,
+            buildingId: creds.buildingId,
+        };
+    }
+    catch {
+        return { token: '', workerUrl: '' };
+    }
+}
+function getToken(opts) {
+    if (opts.token)
+        return opts.token;
+    return readCredentials().token;
+}
+/** The most useful string available from a thrown value. */
+function errorText(e) {
+    if (!e)
+        return 'the connection dropped';
+    if (typeof e === 'string')
+        return e;
+    const m = e?.message;
+    return typeof m === 'string' && m ? m : String(e);
+}
+/**
+ * Absent shell, or failed call? The whole of CBH2-61 turns on this one question.
+ *
+ * ⚠ ABSENCE IS THE NARROW CASE AND MUST BE PROVEN, NOT ASSUMED. The workspace says so in its own
+ * words — `unknown action` / `unknown message type` — and nothing else counts. Defaulting the
+ * other way is exactly the old bug: an unrecognised failure became "no notes shell here" and was
+ * answered by a filesystem the caller never asked about.
+ *
+ * PURE, so the decision is testable with no daemon: a reason in, an outcome out.
+ */
+export function classifyNotesShellFailure(reason) {
+    const msg = errorText(reason);
+    if (/unknown (action|message type)/i.test(msg))
+        return { absent: true };
+    return { transportError: msg };
+}
+/**
+ * What to print when the call never reached the workspace.
+ *
+ * ⚠ IT MUST NAME A CONNECTION, NEVER A PERMISSION. The failure this replaces sent readers to
+ * `HIVE_DEV_MODE=1 beehaven restart`, which cannot help — and a restart is the user's daemon to
+ * cycle, not ours, so the advice is to LOOK first (`status`) and retry.
+ *
+ * ⚠ IT SAYS NOTHING RAN. A caller who has just been told a mutation failed needs to know whether
+ * it half-happened; on this path it did not happen at all.
+ */
+export function notesShellTransportRefusal(transportError, command) {
+    const verb = command.trim().split(/\s+/)[0] || 'the command';
+    return [
+        `  Could not reach your workspace — \`${verb}\` did not run, and nothing was changed.`,
+        '',
+        `    ${transportError}`,
+        '',
+        '  This is a connection problem, not a permission one. It is usually momentary —',
+        '  the same command often succeeds seconds later.',
+        '',
+        '    beehaven status                  # is the daemon up, and is the relay connected?',
+        '',
+    ].join('\n') + '\n';
+}
+/**
+ * Run a command through the workspace's NOTES shell (`bash`), or report why it could not.
+ *
+ * ⚠ A `bash` that RAN and failed (`no such file`) is a real answer and comes back as `result`; it
+ * must not be retried against a different filesystem, which would turn one honest "not found" into
+ * two confusing ones.
+ */
+async function execNotesShell(buildingType, buildingId, command) {
+    try {
+        const { isDaemonRunning, daemonRpc } = await import('../daemon-client.js');
+        /**
+         * ⚠ NO DAEMON IS REPORTED AS `absent`, DELIBERATELY, AND IT IS NOT A TRANSPORT ERROR IN THIS
+         * SENSE. The caller below already handles it far better than a generic message could: for
+         * `home` it prints the start-the-daemon refusal, and for a real `<type>/<id>` target it falls
+         * through to `execRemote`, which can legitimately be served over `--url` with no daemon at
+         * all. Classifying it here would BREAK that `--url` path.
+         */
+        if (!(await isDaemonRunning()))
+            return { absent: true };
+        /**
+         * ⚠ THIS LOGIN'S cwd RIDES WITH THE COMMAND — see `shell-session.ts` for why the client owns
+         * it. Keyed by TARGET as well as login, so `cd` on a team does not move `home`.
+         */
+        const { attachShellCwd, absorbShellCwd, shellTargetKey } = await import('../shell-session.js');
+        const shellTarget = shellTargetKey(buildingType === 'home' ? 'home' : `${buildingType}/${buildingId}`);
+        const payload = attachShellCwd('bash', { command }, shellTarget);
+        /**
+         * ⚠⚠ THE SHELL FAMILY RAN UNATTRIBUTED — `ls cat grep tree find head tail wc jq rm mv cp
+         * mkdir write edit sql search`, SEVENTEEN VERBS, EVERY ONE OF THEM (fixed 2026-09-05).
+         *
+         * This called `daemonRpc('bash', …)` bare, which is precisely the defect `agentRpc`'s own
+         * docstring names for `rpcOnce`: no `agent-invoke`, so no per-agent gate, no `agent_activity`
+         * row, and the work filed against the ACCOUNT OWNER rather than the signed-in agent.
+         *
+         * ⚠ MEASURED AS A BEFORE/AFTER, WHICH IS THE ONLY THING THAT PROVES IT. The identical
+         * command — `beehaven ls ~`, same agent, same target, minutes apart — wrote NO row on the
+         * old build and one row on this one.
+         *
+         * ⚠ DO NOT READ THE DOOR OFF `input_summary`. Every historical `bash` row carries an
+         * `[mcp:…]` prefix, and that prefix means only that a SESSION ID was present — which the CLI
+         * sets too. It is not evidence of the transport, and reading it as such is precisely the
+         * mistake `agent_activity.source` exists to make unnecessary.
+         *
+         * ⚠⚠ AND IT WOULD HAVE POISONED THE VERY MEASUREMENT `source` EXISTS FOR. A door column over
+         * an unattributed shell reports zero CLI traffic for the busiest verbs on the surface, and
+         * the retirement list built from it deletes them for being unused — on data we generated
+         * ourselves. The attribution has to land BEFORE the column is trusted, not after.
+         *
+         * ⚠ WRAP FIRST, ROUTE SECOND — the ordering `cmdCall` documents at length. `agent-invoke`
+         * must travel INSIDE the proxy so it executes on the workspace being addressed; wrapped
+         * outside, it runs on the daemon's default DO and `_checkAgentScope` asks the wrong roster.
+         */
+        const { activeAgentWrap } = await import('./workspace.js');
+        const wrapped = activeAgentWrap('bash', payload, {});
+        let raw;
+        if (buildingType === 'home') {
+            raw = await daemonRpc(wrapped.action, wrapped.input);
+        }
+        else {
+            const { gatewayEnvelope } = await import('./workspace.js');
+            const gw = gatewayEnvelope(buildingType, buildingId, wrapped.action, wrapped.input);
+            raw = await daemonRpc(gw.gateway, gw.payload);
+        }
+        const r = raw?.result ?? raw;
+        absorbShellCwd('bash', r, shellTarget);
+        // No notes shell on this DO — a generic hive, or one predating the palette.
+        const err = String(r?.error ?? '');
+        if (/unknown (action|message type)/i.test(err))
+            return { absent: true };
+        /**
+         * ⚠ A SHAPELESS ERROR REPLY IS A FAILED CALL, NOT AN ABSENT SHELL. This used to `return null`
+         * too, i.e. fall through to the VFS and inherit the developer-scope refusal — the same
+         * CBH2-61 defect arriving through the non-throwing door. The workspace answered SOMETHING and
+         * it was not a shell result, so report what it actually said.
+         */
+        if (r == null || (typeof r === 'object' && !('ok' in r) && !('stdout' in r) && err)) {
+            return classifyNotesShellFailure(err || 'the workspace returned no result');
+        }
+        /**
+         * ⚠⚠ THE WHOLE RESULT → TERMINAL MAPPING LIVES IN `formatShellResult`, AND THAT MOVE IS THE
+         * FIX, not a tidy-up. Inline here it could only be asserted by grepping this file, and the
+         * defect it carried was invisible to source scanning: the mapping read `stdout`, `rows` and
+         * `stderr` and dropped `error`, `code`, `hint` and every structured success field, so
+         * `mkdir`, `mv`, `cp` and `rm` printed NOTHING — on success and on failure alike. A failed
+         * `mv` was byte-identical on screen to a successful one.
+         *
+         * ⚠ `sql`'s `rows` HANDLING MOVED WITH IT, unchanged — see `formatShellResult`.
+         */
+        return { result: formatShellResult(r, command.trim().split(/\s+/)[0] ?? '') };
+    }
+    catch (e) {
+        /**
+         * ⚠⚠ THE LINE CBH2-61 IS ABOUT. It read `return null` with the comment *"transport trouble —
+         * let the VFS path report it in its own words"*. Those words described a different failure:
+         * the VFS reports a DEVELOPER-SCOPE refusal, which is not what happened and not what to do
+         * about it. The reason travels with the outcome now.
+         */
+        return classifyNotesShellFailure(e);
+    }
+}
+async function execRemote(buildingType, buildingId, command, opts) {
+    // Why the daemon path gave up, so a later fallback failure can report the
+    // ORIGINAL cause rather than whatever the fallback happened to hit.
+    let daemonError = '';
+    // ── Daemon-first path ────────────────────────────────────────────────
+    // Route through `/tmp/beehaven-ipc.sock → daemon → relay → user's workspace
+    // DO → admin:store-rpc → target DO → shell:exec`. The daemon is already
+    // authed with the user's Firebase keychain JWT, so the caller never holds
+    // a long-lived bearer.
+    //
+    // Falls back to direct WebSocket only if the daemon isn't running. The
+    // direct path uses ~/.beehaven/credentials.json (legacy bearer pattern).
+    try {
+        const { isDaemonRunning, daemonRpc } = await import('../daemon-client.js');
+        if (await isDaemonRunning()) {
+            // Special case: `home` is the user's default workspace alias. The
+            // daemon's relay is bound there by default, so we call
+            // shell:exec directly instead of going through admin:*-rpc
+            // (which would gate on ADMIN_USER_IDS and isn't the right
+            // path for a user's own workspace).
+            if (buildingType === 'home') {
+                const result = await daemonRpc('shell:exec', {
+                    command,
+                    _timeout: 60_000,
+                });
+                const innerHome = result?.result ?? result;
+                if (innerHome?.error) {
+                    return { stdout: '', stderr: innerHome.error + '\n', exitCode: 1 };
+                }
+                const out = innerHome?.stdout ?? innerHome?.output ?? innerHome ?? '';
+                const stdoutHome = typeof out === 'string' ? out : JSON.stringify(out, null, 2);
+                return {
+                    stdout: stdoutHome.endsWith('\n') ? stdoutHome : stdoutHome + '\n',
+                    stderr: innerHome?.stderr ?? '',
+                    exitCode: innerHome?.exitCode ?? 0,
+                };
+            }
+            // ⚠ ONE envelope builder — this site had its own copy hardcoding `storeId`, so every
+            // `beehaven ls` against a TEAM answered "teamId is required". See `gatewayEnvelope`.
+            const { gatewayEnvelope } = await import('./workspace.js');
+            const gw = gatewayEnvelope(buildingType, buildingId, 'shell:exec', { command, _timeout: 60_000 });
+            const result = await daemonRpc(gw.gateway, gw.payload);
+            // Unwrap the {result: ...} envelope from admin:store-rpc
+            const inner = result?.result ?? result;
+            if (inner?.error) {
+                return { stdout: '', stderr: inner.error + '\n', exitCode: 1 };
+            }
+            const output = inner?.stdout ?? inner?.output ?? inner ?? '';
+            const stdout = typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+            return {
+                stdout: stdout.endsWith('\n') ? stdout : stdout + '\n',
+                stderr: inner?.stderr ?? '',
+                exitCode: inner?.exitCode ?? 0,
+            };
+        }
+    }
+    catch (err) {
+        // Daemon path failed — fall through to direct WebSocket. Common causes:
+        // daemon not authed, ADMIN_USER_IDS doesn't include the user, the
+        // target DO doesn't support shell:exec via the gateway.
+        if (process.env.BEEHAVEN_DEBUG) {
+            console.error(`[shell] daemon path failed, falling back: ${err.message}`);
+        }
+        // …but some failures the fallback CANNOT fix. A scope or auth denial is
+        // about WHO is asking, not WHERE — retrying against a local dev worker
+        // just swaps the real message for `ECONNREFUSED 127.0.0.1:8787`, which
+        // names a port the user never mentioned and hides the one-line fix.
+        // `beehaven sql` on home reported exactly that: the true cause ("requires
+        // developer scope") was visible only under BEEHAVEN_DEBUG.
+        const reason = String(err?.message ?? '');
+        if (/developer scope|requires .* scope|unauthorized|not authenticated|token/i.test(reason)) {
+            const hint = /developer scope/i.test(reason)
+                ? '\n  Fix: HIVE_DEV_MODE=1 beehaven restart   (or enable Developer Mode in the Hive Mac app)\n'
+                : '\n  Fix: beehaven login                      (re-auth; a restart will NOT refresh an expired token)\n';
+            return { stdout: '', stderr: `${reason}${hint}`, exitCode: 1 };
+        }
+        daemonError = reason;
+    }
+    // ── Legacy direct-WebSocket path (fallback only) ─────────────────────
+    return new Promise((resolve, reject) => {
+        const token = getToken(opts);
+        const wsUrl = getWsUrl(buildingType, buildingId, opts) +
+            (token ? `?token=${encodeURIComponent(token)}` : '');
+        const ws = new WebSocket(wsUrl, ['beehaven-v1']);
+        const requestId = `shell_${Date.now()}`;
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                ws.close();
+                reject(new Error('Timeout: shell command did not respond within 30s'));
+            }
+        }, 30_000);
+        ws.on('open', () => {
+            ws.send(JSON.stringify({ type: 'shell:exec', command, requestId }));
+        });
+        ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg.requestId === requestId || msg.rid === requestId) {
+                    clearTimeout(timeout);
+                    settled = true;
+                    ws.close();
+                    if (msg.error) {
+                        resolve({ stdout: '', stderr: msg.error + '\n', exitCode: 1 });
+                    }
+                    else {
+                        const output = msg.data?.stdout ?? msg.data?.output ?? msg.data ?? '';
+                        const stdout = typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+                        resolve({
+                            stdout: stdout.endsWith('\n') ? stdout : stdout + '\n',
+                            stderr: msg.data?.stderr ?? '',
+                            exitCode: msg.data?.exitCode ?? 0,
+                        });
+                    }
+                }
+            }
+            catch { }
+        });
+        ws.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeout);
+                // The fallback dials a LOCAL dev worker when there are no saved
+                // credentials, so its failure is almost always `ECONNREFUSED
+                // 127.0.0.1:8787` — a port the user never asked about, standing in
+                // for whatever actually went wrong upstream. Lead with the daemon's
+                // reason when we have one.
+                const detail = daemonError
+                    ? `${daemonError}\n  (then the direct fallback failed too: ${err.message})`
+                    : `WebSocket error: ${err.message}`;
+                reject(new Error(detail));
+            }
+        });
+        ws.on('close', () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeout);
+                reject(new Error('Connection closed before response'));
+            }
+        });
+    });
+}
+function execDebug(buildingType, buildingId, debugType, opts) {
+    return new Promise((resolve, reject) => {
+        const token = getToken(opts);
+        const wsUrl = getWsUrl(buildingType, buildingId, opts) +
+            (token ? `?token=${encodeURIComponent(token)}` : '');
+        const ws = new WebSocket(wsUrl, ['beehaven-v1']);
+        const requestId = `debug_${Date.now()}`;
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                ws.close();
+                reject(new Error('Timeout'));
+            }
+        }, 15_000);
+        ws.on('open', () => {
+            ws.send(JSON.stringify({ type: debugType, requestId }));
+        });
+        ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg.requestId === requestId || msg.rid === requestId) {
+                    clearTimeout(timeout);
+                    settled = true;
+                    ws.close();
+                    resolve(msg.data ?? msg);
+                }
+            }
+            catch { }
+        });
+        ws.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeout);
+                reject(err);
+            }
+        });
+        ws.on('close', () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeout);
+                reject(new Error('Connection closed'));
+            }
+        });
+    });
+}