@clearlysh/beehaven 0.8.16

package/dist/commands/workspace.js

@@ -0,0 +1,3354 @@
+/**
+ * Workspace Commands — talk to the cloud DO through the daemon.
+ *
+ * These commands connect to the running daemon via IPC (/tmp/beehaven-ipc.sock)
+ * and forward RPCs to the user's cloud Durable Object.
+ *
+ * Core commands:
+ *   beehaven actions              — list available workspace actions
+ *   beehaven call <action> '{}'   — call a workspace action
+ *   beehaven workspace            — show workspace overview
+ *   beehaven pipe                 — JSON-RPC 2.0 mode for Claude Code
+ *   beehaven ls [path]            — browse workspace VFS
+ *   beehaven cat <path>           — read a file from workspace VFS
+ *   beehaven remember <k> <v>     — store agent memory
+ *   beehaven recall [query]       — retrieve agent memories
+ *   beehaven search <query>       — search notes
+ *   beehaven ask "<question>"     — chat with cloud agent
+ *   beehaven task "<title>"       — create a task
+ *   beehaven watch [patterns]     — stream live workspace events
+ *   beehaven teleport <file>      — upload file to workspace
+ */
+import { rpcOnce, connectClient } from '../ipc-client.js';
+import { assertActionAllowed } from '../blocked-actions.js';
+import { activeAgentWrap } from '../agent-attribution.js';
+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) {
+    // 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
+    // flag every time. The daemon honors the same value via the forwarded
+    // `_timeout`, so the relay-forward window matches the CLI's wait.
+    if (values.timeout)
+        return parseInt(values.timeout, 10);
+    const env = process.env.BEEHAVEN_RPC_TIMEOUT_MS;
+    if (env && Number.isFinite(Number(env)) && Number(env) > 0)
+        return parseInt(env, 10);
+    return 180_000;
+}
+/**
+ * True when `msg` says `action` isn't available on the target DO.
+ *
+ * The server has TWO ways of saying this and they don't share a prefix:
+ * `_rpc:invoke` and the admin gateways answer "Unknown action: X", while the
+ * WebSocket router answers "Unknown message type: X". Code that matched only
+ * the first string silently skipped its own fallback — `beehaven actions` had
+ * a retry-against-home path that never ran, so the command dead-ended and
+ * then advised the user to retry the same call. Match both spellings.
+ */
+/**
+ * Is this payload carrying FILE BYTES inline, whatever the verb is called?
+ *
+ * ⚠⚠ THE SHAPE, NOT A NAME LIST. The oversized-payload refusal used to give upload advice only for
+ * `file-teleport-inline|library-upload|file-uploaded`, and there are at least five other
+ * byte-carrying verbs (`canvas-upload-image`, `canvas-add-image`, `deck-add-image`,
+ * `agent-avatar-upload`, `compose-upload-init`). Measured 2026-09-02: an agent uploading sixteen
+ * screenshots used `canvas-upload-image`, fell through to the generic *"split the input"*, and
+ * re-encoded everything to JPEG — degrading the images to work around a limit that does not apply
+ * to uploads at all, while `beehaven teleport` and the presigned PUT were both available.
+ *
+ * ⚠ A NAME LIST GOES STALE ON THE NEXT UPLOAD VERB, silently, and the cost is a caller abandoning
+ * a route that works. Same reasoning as `GENERATION_SHAPE` in `actionTimeouts.ts`: match what the
+ * thing IS, and let a new verb be covered by being shaped like what it is.
+ *
+ * ⚠ IT ONLY HAS TO BE RIGHT ABOUT WHICH ADVICE TO PRINT. A false positive prints the upload route
+ * on a large non-upload call — mildly wrong; a false negative sends someone to downscale their
+ * images. The threshold is high enough that ordinary prose never trips it.
+ */
+export function carriesInlineBytes(input) {
+    if (!input || typeof input !== 'object')
+        return false;
+    const BYTES_MIN = 64 * 1024;
+    for (const v of Object.values(input)) {
+        if (typeof v !== 'string' || v.length < BYTES_MIN)
+            continue;
+        // A data: URI is unambiguous; otherwise require the head to be base64-shaped.
+        if (/^data:[^;,]*;base64,/i.test(v))
+            return true;
+        if (/^[A-Za-z0-9+/\r\n]+={0,2}$/.test(v.slice(0, 512)))
+            return true;
+    }
+    return false;
+}
+export function isMissingActionError(msg, action) {
+    if (!msg)
+        return false;
+    const s = String(msg);
+    return (s.includes(`Unknown action: ${action}`) ||
+        s.includes(`Unknown message type: ${action}`) ||
+        s.includes(`Unknown action ${action}`));
+}
+/**
+ * Throw when a resolved RPC payload is actually an error report.
+ *
+ * The daemon resolves `rpc-result` for anything the DO acked, so a body of
+ * `{error: 'Unknown message type: workspace-info'}` reaches callers as a
+ * SUCCESS. Commands that then rendered it through a display template printed
+ * a blank report and exited 0 — a missing RPC and an empty workspace looked
+ * identical, which is the failure mode that hid the unregistered discovery
+ * actions for as long as it did. Call this before rendering.
+ */
+export function assertNoRpcError(result, action) {
+    if (!result || typeof result !== 'object')
+        return;
+    const err = result.error;
+    if (!err)
+        return;
+    const msg = typeof err === 'string' ? err : (err.message ?? JSON.stringify(err));
+    const suggestions = result.suggestions;
+    const tail = Array.isArray(suggestions) && suggestions.length
+        ? ` Did you mean: ${suggestions.join(', ')}?`
+        : '';
+    throw new Error(`${action}: ${msg}${tail}`);
+}
+/**
+ * Pull a row array out of a response whatever shape it arrived in — a bare
+ * array, one of the named keys, or the numeric-keyed object an array becomes
+ * when a server spreads it into the ack envelope ({"0":…,"1":…}).
+ */
+export function normalizeRows(result, keys) {
+    if (Array.isArray(result))
+        return result;
+    if (!result || typeof result !== 'object')
+        return [];
+    for (const k of keys) {
+        if (Array.isArray(result[k]))
+            return result[k];
+    }
+    const numeric = Object.keys(result).filter((k) => /^\d+$/.test(k));
+    if (numeric.length) {
+        return numeric.sort((a, b) => Number(a) - Number(b)).map((k) => result[k]);
+    }
+    return [];
+}
+/**
+ * THE cross-DO envelope: which proxy action, and what that proxy calls the id.
+ *
+ * ⚠⚠ EVERY CALLER MUST COME THROUGH HERE. `admin:store-rpc` reads `storeId`, `admin:team-rpc`
+ * reads `teamId`, `admin:workspace-rpc` reads `workspaceId` — and this pairing was hand-written at
+ * NINE call sites across `cli.ts`, `commands/workspace.ts` and `commands/shell.ts`, every one of
+ * them hardcoding `storeId` while deriving the action from the type. So every non-store target
+ * computed the right proxy and handed it a key that proxy does not read: `beehaven connect
+ * team/<id>` followed by ANY command answered `{"error":"teamId is required"}`.
+ *
+ * ⚠ IT FAILS ONE COMMAND AFTER ITS CAUSE. `connect` succeeds and prints a session; the error lands
+ * on the next call, names a field the user never typed, on a wrapping they did not know happened.
+ * It reads as "that workspace is misconfigured", which is why it survived so long.
+ *
+ * One builder, so the pairing is stated once and a new building type either gets it right or
+ * fails in `workspace-routing.test.ts`.
+ */
+export function gatewayEnvelope(buildingType, buildingId, action, input) {
+    // `shopifyStore` is an alias for `store`; the proxy is `admin:store-rpc` either way, so the id
+    // field must be derived from the RESOLVED type or it becomes `shopifyStoreId`.
+    const alias = buildingType === 'shopifyStore' ? 'store' : buildingType;
+    /**
+     * ⚠⚠ ROUTE BY ID SHAPE, NOT BY LABEL — and this is what stops ordinary work needing Developer
+     * Mode.
+     *
+     * A 64-hex id is a canonical workspace id, whatever the caller typed in front of it: `team/<id>`
+     * and `workspace/<id>` name the SAME Durable Object, and `workspaceStub` already routes on
+     * exactly this rule for exactly this reason. Only the ENVELOPE differed, and it differed in the
+     * one way that matters — `admin:team-rpc` is `ADMIN_USER_IDS`-gated and, locally, is an
+     * `admin:`-prefixed action that the daemon's IPC scope gate refuses without a developer token.
+     *
+     * So `beehaven connect team/<canonical id>` — the address the CLI itself prints and the one this
+     * account uses — turned every subsequent call into an ADMIN operation. Agent work then either
+     * required `HIVE_DEV_MODE=1` or slipped past the scope gate by hiding inside `agent-invoke`,
+     * which is the bypass this change exists to make unnecessary.
+     *
+     * `workspace-rpc` is the member-facing sibling: it checks the account ROSTER (the same list
+     * `beehaven workspaces` renders) rather than staff membership, and it re-wraps the forwarded call
+     * as `agent-invoke` on the target so an agent survives the hop. It is the right door for both
+     * spellings.
+     *
+     * ⚠ A LEGACY NAME-ADDRESSED TEAM STILL USES `admin:team-rpc`. Those ids are not resolvable in the
+     * workspace namespace, so the staff proxy remains the only way to reach one — which is what that
+     * verb is actually for.
+     */
+    const canonicalWorkspaceId = /^[0-9a-f]{64}$/i.test(String(buildingId || ''));
+    const resolved = canonicalWorkspaceId && (alias === 'team' || alias === 'workspace')
+        ? 'workspace'
+        : alias;
+    const gateway = resolved === 'workspace' ? 'workspace-rpc' : `admin:${resolved}-rpc`;
+    return {
+        gateway,
+        payload: { [`${resolved}Id`]: buildingId, action, input },
+    };
+}
+/**
+ * Route an action to a specific building via the Home DO's proxy.
+ *
+ * ⚠ THE ROUTE IS CHOSEN BY ID SHAPE, NOT BY LABEL — see `gatewayEnvelope`. A 64-hex id is a
+ * canonical workspace id whichever noun precedes it, and it goes through the MEMBER proxy. This
+ * list said `team:<id> → admin:team-rpc` after that stopped being true, which is the two-inventories
+ * failure: a reader trusts the table over the code.
+ *
+ *   --building home                → direct (default)
+ *   --building team:<64-hex>       → workspace-rpc    (roster-gated)
+ *   --building workspace:<64-hex>  → workspace-rpc    (roster-gated)
+ *   --building team:<name>         → admin:team-rpc   (legacy name-addressed team; staff only)
+ *   --building store:<id>          → admin:store-rpc
+ *   --building shopifyStore:<id>   → admin:store-rpc  (alias)
+ *   --building <type>:<id>         → admin:<type>-rpc
+ */
+export function resolveBuilding(action, input, building) {
+    if (!building || building === 'home')
+        return { action, input };
+    const colonIdx = building.indexOf(':');
+    if (colonIdx === -1)
+        return { action, input };
+    const buildingType = building.slice(0, colonIdx);
+    const buildingId = building.slice(colonIdx + 1);
+    // ⚠ ONE builder for the proxy + its id field — see `gatewayEnvelope` for the bug that made it
+    // one. Do not re-derive `admin:<type>-rpc` here.
+    const { gateway, payload } = gatewayEnvelope(buildingType, buildingId, action, input);
+    return { action: gateway, input: payload };
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+// ── beehaven actions ─────────────────────────────────────────────────────
+/**
+ * ⚠⚠ THE COUNTING AND THE DISCLOSURE, AS A PURE FUNCTION — SO A GUARD CAN EXECUTE THEM.
+ *
+ * Both of `beehaven actions`' defects were decisions taken in one line each, buried in a render
+ * loop that needs a daemon, a relay and a live DO to reach. A test could only ever have grepped
+ * for them, and a grep passes against a build where the line has moved rather than been fixed.
+ * Extracted, the rules are callable with a plain object:
+ *
+ *   - `matchCount` reads the server's `action_count`, NOT the length of the page it was handed.
+ *     Reading the page and printing it as "available" is how a 40-row slice of 61 matches called
+ *     itself complete, five different queries in a row.
+ *   - a narrowed list SAYS it was narrowed — whether it was cut by a page bound (`truncated`) or
+ *     by reachability (`hidden`). One shape, two causes, so they are decided together.
+ *
+ * ⚠ `total` IS A FALLBACK, NOT THE FIRST CHOICE. `--building store:<id>` reaches a different DO
+ * whose `list-actions` may answer with `total`; dropping it trades this bug for "undefined
+ * available" over there.
+ */
+/**
+ * ⚠⚠ ASK FOR THE CALLABLE SET BY DEFAULT — `--all` IS THE OPT-OUT.
+ *
+ * MEASURED on staging 2026-09-05, and the cross-tabulation is the whole argument:
+ *
+ *              reachable   unreachable
+ *   described     584          142
+ *   bare            0          443
+ *
+ * 1,169 rows were listed, 585 of them registered-and-refused, with nothing on the row to say so —
+ * a caller picks one, spends a round trip, and is told the name is "outside the user action
+ * surface". And EVERY undescribed name was in the refused half, so the "62% description coverage"
+ * defect was never a documentation gap: it was this command printing rows nobody can call.
+ * Filtering takes coverage to 100% without writing a word of prose.
+ *
+ * ⚠ THE SERVER ALREADY HAD THE SWITCH AND THIS DOOR NEVER PULLED IT. `_rpc:catalog` has accepted
+ * `reachableOnly` (defaulting it ON for agents) for a while, which is why `beehaven call
+ * _rpc:catalog` answered 584 while `beehaven actions` answered 1,169 — same workspace, same
+ * session, two answers, and the bigger one was on the surface a person reads.
+ *
+ * ⚠ IT ONLY EVER NARROWS, which is what makes it safe to send from a client: nothing here can
+ * reveal something the caller could not otherwise reach.
+ *
+ * ⚠ EXPORTED SO A GUARD CAN EXECUTE IT. Inline in `cmdActions` this decision was reachable only
+ * through a daemon, a relay and a live DO, so a test could only grep for it — and a grep passes
+ * against a build where the line moved rather than got fixed.
+ */
+export function actionsListInput(values, format) {
+    return {
+        category: values.category,
+        search: values.search,
+        format,
+        ...(values.all ? {} : { reachableOnly: true }),
+    };
+}
+/**
+ * ⚠⚠ "0 available" WAS A CONFIDENT LIE ABOUT THE WORKSPACE (CBH2-62).
+ *
+ *     $ beehaven actions --category zzznope
+ *       Workspace Actions — 0 available
+ *       …the standard footer, unchanged…
+ *
+ * Nothing said a filter had been applied, nothing said it matched nothing, and nothing named a
+ * category that exists. "0 available" is a statement about the WORKSPACE; the true statement is
+ * about the FILTER. Same defect class as the rest of this cluster: a well-formed, successful,
+ * wrong answer that nothing downstream can tell from a real one. And it got easier to hit the day
+ * `beehaven actions board` started mapping a bare word onto `--category` (CBH2-23), because a
+ * mistyped bare word now reaches the category filter instead of being ignored.
+ *
+ * ⚠⚠ THE TWO CAUSES NEED DIFFERENT ANSWERS, WHICH IS WHY THIS IS NOT ONE SENTENCE. `--category
+ * bogus` and `--category board --search zzz` both return zero, and telling someone their category
+ * is wrong when it is their search sends them to fix the half that was right. So: if the category
+ * is not in the universe, say the category does not exist and offer near matches; if it IS, say
+ * the category is real and name the filter that emptied it.
+ *
+ * ⚠ THE UNIVERSE IS PASSED IN, NEVER FETCHED HERE. The server returns `categories` FILTERED, so a
+ * filtered call returns 0 or 1 of them and structurally cannot list the valid names — the caller
+ * has to make a second, unfiltered request. Keeping that in `cmdActions` leaves this function pure
+ * and executable by a guard, which is the property the rest of this module was extracted for.
+ *
+ * ⚠ AN UNKNOWN UNIVERSE IS NOT AN EMPTY ONE. `categories: undefined` means the second fetch failed
+ * or was not attempted; guessing "your category does not exist" from that would be a new confident
+ * wrong answer inside the fix for a confident wrong answer.
+ */
+export function zeroResultNotices(opts) {
+    const { category, search, categories, hidden = 0 } = opts;
+    const filters = [];
+    if (category)
+        filters.push(`--category ${category}`);
+    if (search)
+        filters.push(`--search ${search}`);
+    if (!filters.length) {
+        /** ⚠ NO FILTER AND NO ROWS IS A DIFFERENT, WORSE EVENT — the workspace answered with nothing.
+         *  Reporting it as a filter miss would hide a real outage behind a typo message. */
+        return [
+            '⚠ No filter was applied and the workspace still returned no actions. That is not a search miss — the listing itself came back empty.',
+            "Check the target with `beehaven pwd`, then `beehaven call _rpc:catalog '{}'` for the same catalog by another door.",
+        ];
+    }
+    const out = [`Nothing matched ${filters.join(' + ')}.`];
+    if (category && Array.isArray(categories)) {
+        if (!categories.includes(category)) {
+            const near = nearestCategories(category, categories);
+            out.push(near.length
+                ? `⚠ There is no category "${category}". Closest: ${near.join(', ')}.`
+                : `⚠ There is no category "${category}".`);
+            out.push(`${categories.length} categories exist — list them with \`beehaven actions --json\` and read \`categories\`.`);
+        }
+        else {
+            out.push(search
+                ? `The category "${category}" is real and has actions; it is --search ${search} that matched none of them. Drop the search first.`
+                : `The category "${category}" is real, so every action in it is filtered out for you rather than missing.`);
+        }
+    }
+    else if (category) {
+        // Universe unknown — say so rather than implying the name is wrong.
+        out.push(`Could not fetch the category list to check "${category}", so this may be a typo or a genuinely empty category.`);
+    }
+    if (search && !category) {
+        out.push(`No action name or description contains "${search}". Try a shorter stem — the match is a substring, not a fuzzy search.`);
+    }
+    if (hidden > 0) {
+        out.push(`${hidden} action(s) DO match but are not callable by you and were hidden. See them with --all.`);
+    }
+    return out;
+}
+/**
+ * Categories a typo most plausibly meant: substring either way first, then a cheap edit-distance
+ * neighbourhood. Capped at three — a list of twenty "close" matches is another wall of text.
+ *
+ * ⚠ It returns [] rather than the whole universe when nothing is close. Printing all 127 as
+ * "suggestions" is not help, and the caller already says how to list them.
+ */
+export function nearestCategories(typed, universe, limit = 3) {
+    const t = typed.toLowerCase();
+    const contains = universe.filter((c) => c.includes(t) || t.includes(c));
+    if (contains.length)
+        return contains.slice(0, limit);
+    const scored = universe
+        .map((c) => ({ c, d: editDistance(t, c) }))
+        // A third of the typed length, so short words do not match everything.
+        .filter((x) => x.d <= Math.max(1, Math.floor(t.length / 3)))
+        .sort((a, b) => a.d - b.d);
+    return scored.slice(0, limit).map((x) => x.c);
+}
+/**
+ * ⚠⚠ DAMERAU, NOT PLAIN LEVENSHTEIN — A TRANSPOSITION IS THE COMMONEST TYPO AND PLAIN
+ * LEVENSHTEIN SCORES IT 2.
+ *
+ * Measured while verifying this fix: `--category boadr` (`board` with two letters swapped) got NO
+ * suggestion, because the threshold that keeps short words from matching everything is 1 and plain
+ * edit distance calls that pair 2. Adding the adjacent-transposition case makes it 1, which is what
+ * a human means by "one typo".
+ *
+ * ⚠ The 2D table is deliberate: the space-optimised two-row form cannot see the i-2/j-2 cell a
+ * transposition needs, and category lists are ~127 short strings — this is not a hot path.
+ */
+function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return d[a.length][b.length];
+}
+export function summarizeActionsListing(result, opts = {}) {
+    const actions = result?.actions ?? [];
+    const shown = actions.length;
+    const matchCount = Number(result?.action_count ?? result?.total ?? shown);
+    const truncated = shown < matchCount;
+    const hidden = Number(result?.hidden ?? 0);
+    const unreachable = Number(result?.unreachable ?? 0);
+    const filtered = !!(opts.category || opts.search);
+    const notices = [];
+    /**
+     * ⚠ THE ZERO CASE RETURNS EARLY. Every notice below describes a NON-EMPTY listing ("N more
+     * match", "N of the rows above"), and appending them to an empty one produces sentences about
+     * rows that are not there.
+     */
+    if (matchCount === 0) {
+        return {
+            shown,
+            matchCount,
+            truncated: false,
+            heading: (label) => filtered
+                ? `${label} Actions — 0 of them match this filter`
+                : `${label} Actions — 0 available`,
+            notices: zeroResultNotices({ ...opts, hidden }),
+        };
+    }
+    if (truncated) {
+        notices.push(`⚠ ${matchCount - shown} more match and are not shown. Narrow with --search/--category, or raise the page with --json.`);
+    }
+    /**
+     * ⚠ REPORT WHAT CAME BACK, NEVER WHAT WAS SENT. `reachableOnly` is forced ON for an
+     * agent-shaped caller whatever the client asked for, so `--all` can be silently ineffective.
+     * Branching on the RESPONSE is the only version that cannot lie about its own filter.
+     */
+    if (hidden > 0) {
+        notices.push(opts.all
+            ? `⚠ ${hidden} action(s) are registered but not callable by you, and this connection hid them anyway — --all could not override it here.`
+            : `${hidden} more are registered but not callable by you (they exist and are refused — not a search miss). See them with --all.`);
+    }
+    if (unreachable > 0) {
+        notices.push(`${unreachable} of the rows above are marked [unreachable] — registered, and refused if you call them. Omit --all to hide them.`);
+    }
+    return {
+        shown,
+        matchCount,
+        truncated,
+        // ⚠ "N of M" ONLY WHEN THEY DIFFER. "40 of 40" on a complete list is noise that trains a
+        //   reader to skip the one place a real truncation will eventually be announced.
+        heading: (label) => truncated
+            ? `${label} Actions — showing ${shown} of ${matchCount} matches`
+            : `${label} Actions — ${matchCount} available`,
+        notices,
+    };
+}
+/**
+ * ⚠⚠ `beehaven actions board` WAS AN EXPENSIVE NO-OP THAT LOOKED LIKE SUCCESS.
+ *
+ * `cli.ts` calls `cmdActions(values)` with no positionals, so a bare word after the verb was
+ * dropped on the floor and the command answered with the FULL catalogue — measured at 1,169 rows
+ * / ~180 KB / ~45k tokens, byte-identical to bare `actions`, where `--category board` returns 40.
+ * Nothing errored and nothing said the argument had been ignored, so the caller pays for the
+ * whole catalogue believing they filtered it.
+ *
+ * ⚠⚠ THE ARGV SCAN IS GONE — `cli.ts` PASSES THE POSITIONAL NOW (CBH2-63). It read
+ * `process.argv` only because that call site was owned by another agent mid-sprint, and it could
+ * see just the token immediately after the verb: `actions --json board` was still missed, because
+ * a flag sat where the scan looked. A real positional has no blind spot, so the helper it was
+ * isolated into has been deleted rather than left as a second, weaker answer to one question.
+ */
+/**
+ * What a bare positional after `actions` means, and what to say about it.
+ *
+ * ⚠ INTERPRETED AS THE CATEGORY, AND SAID OUT LOUD. `actions board` is the natural first guess and
+ * `--category board` is plainly what it means, so honouring it beats refusing — but a silent
+ * REinterpretation is the same class of defect as a silent drop, so the breadcrumb names it.
+ *
+ * ⚠ AN EXPLICIT `--category` WINS AND THE CONFLICT IS REPORTED. Quietly preferring one of two
+ * filters the caller typed is a guess about intent; naming the one that was used is not.
+ */
+export function resolveActionsCategory(values, positional) {
+    if (!positional)
+        return { category: values.category, note: '' };
+    if (!values.category) {
+        return { category: positional, note: `  (reading "${positional}" as --category ${positional})` };
+    }
+    if (values.category === positional)
+        return { category: values.category, note: '' };
+    return {
+        category: values.category,
+        note: `  (ignoring "${positional}" — --category ${values.category} was given explicitly)`,
+    };
+}
+export async function cmdActions(values, positional) {
+    const format = values.format || (values.json ? 'full' : 'summary');
+    const chosen = resolveActionsCategory(values, positional);
+    values.category = chosen.category;
+    // Routing breadcrumb — tell agents (and humans) which DO this hits.
+    if (!values.json) {
+        const target = values.building ? values.building : 'home';
+        console.error(`\x1b[2m→ ${target}  list-actions${chosen.note}\x1b[0m`);
+    }
+    const listInput = actionsListInput(values, format);
+    /** Transparently retry against home when the primary target doesn't
+     *  expose list-actions. Covers the stale-routing case: agent asks
+     *  "what actions can I call?" expecting the home palette but the
+     *  daemon had a lingering shopifyStore target; that DO returns
+     *  "Unknown action: list-actions"; retry against home rather than
+     *  dead-end the agent. Only fires when no --building flag was set
+     *  (explicit --building is respected). */
+    async function fetchActions(building) {
+        const resolved = resolveBuilding('list-actions', listInput, building);
+        return rpcOnce(resolved.action, resolved.input, getTimeout(values));
+    }
+    try {
+        let raw = await fetchActions(values.building);
+        // Unwrap proxy envelope
+        let result = raw?.type === 'ack' && raw?.result !== undefined
+            ? raw.result
+            : raw?.result !== undefined && values.building
+                ? raw.result
+                : raw;
+        const firstError = raw?.type === 'error' || result?.error;
+        const firstMsg = raw?.message ?? result?.error ?? '';
+        if (firstError &&
+            isMissingActionError(firstMsg, 'list-actions') &&
+            values.building &&
+            !values.json) {
+            // Quiet retry against home — no --building explicit = we're allowed
+            // to look elsewhere. Log a breadcrumb so the agent sees it.
+            console.error(`\x1b[2m  (${values.building} doesn't expose list-actions — retrying against home)\x1b[0m`);
+            raw = await fetchActions(undefined);
+            result = raw?.type === 'ack' && raw?.result !== undefined ? raw.result : raw;
+            // Swap the label so the printed output reflects where the result came from.
+            values.building = undefined;
+        }
+        // If retry ALSO fails, or if --building was explicit and failed, take the long hint path.
+        if (raw?.type === 'error' || result?.error) {
+            const msg = raw?.message ?? result?.error ?? 'Unknown error';
+            if (isMissingActionError(msg, 'list-actions')) {
+                console.log('');
+                console.log(`  This building doesn't expose an action listing.`);
+                // ⚠ The three raw-VFS commands below all need DEVELOPER scope (they route to
+                // `shell:exec`). Lead with the one that works for everyone and label the rest,
+                // rather than sending a consumer-scope caller into a permissions error — CLR-1148.
+                console.log(`  Discover what's there:`);
+                console.log(`    beehaven ls ~                       # your notes + projects as files`);
+                console.log(`    beehaven actions --search <word>    # find a verb by name`);
+                console.log(`  Raw VFS (needs developer scope — HIVE_DEV_MODE=1 beehaven restart):`);
+                console.log(`    beehaven cat /.workspace.json       # manifest with every action + folder`);
+                console.log(`    beehaven ls /apps/                  # installed apps as files`);
+                console.log(`    beehaven tree /                     # full VFS tree`);
+                console.log(`  Then call a specific action:`);
+                console.log(`    beehaven call <action-name> '{}'`);
+                console.log(`    beehaven rpc admin:store-rpc '{"storeId":"<id>","action":"<name>","input":{}}'`);
+                console.log('');
+                return;
+            }
+            console.error(`  Error: ${msg}`);
+            console.error('');
+            console.error('  Try:');
+            console.error('    beehaven pwd                        # confirm current target');
+            console.error('    beehaven disconnect                  # fall back to home');
+            // Only suggest `--building home` when we are NOT already on home.
+            // Without this guard the hint told you to re-run, against the same DO,
+            // the exact command that had just failed — the advice looked actionable
+            // and was a no-op, which is worse than no advice at all.
+            if (values.building && values.building !== 'home') {
+                console.error("    beehaven actions --building home     # list home's actions specifically");
+            }
+            else {
+                console.error("    beehaven call _rpc:catalog '{}'      # the same catalog, direct");
+                console.error('    beehaven cat /.workspace.json        # manifest: actions + folders');
+            }
+            process.exit(1);
+        }
+        if (values.json || format === 'full' || format === 'tool-use') {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const actions = result?.actions ?? [];
+        /**
+         * ⚠⚠ THE ZERO CASE COSTS ONE EXTRA FETCH, AND ONLY THE ZERO CASE (CBH2-62). The server returns
+         * `categories` FILTERED, so the response to a filtered call carries 0 or 1 of them and cannot
+         * name the valid ones — the only way to tell "your category is a typo" from "your search
+         * emptied a real category" is to ask again without the filter. A zero-result listing is rare
+         * and already a dead end, so the round trip is free where it matters and never paid otherwise.
+         *
+         * ⚠ IT FAILS SOFT. If the second fetch throws, `categories` stays undefined and
+         * `zeroResultNotices` says it could not check rather than guessing — an unknown universe must
+         * not become a confident claim about the name.
+         */
+        let categories = Array.isArray(result?.categories) && result.categories.length
+            ? result.categories
+            : undefined;
+        const matched = Number(result?.action_count ?? result?.total ?? actions.length);
+        if (matched === 0 && (values.category || values.search)) {
+            try {
+                const probe = await rpcOnce(resolveBuilding('list-actions', { format: 'summary' }, values.building).action, resolveBuilding('list-actions', { format: 'summary' }, values.building).input, getTimeout(values));
+                const unwrapped = probe?.type === 'ack' && probe?.result !== undefined ? probe.result : probe;
+                if (Array.isArray(unwrapped?.categories) && unwrapped.categories.length)
+                    categories = unwrapped.categories;
+            }
+            catch { /* fails soft — see above */ }
+        }
+        // ⚠ THE COUNTING AND THE DISCLOSURE LIVE IN `summarizeActionsListing`, a pure function, so a
+        //   guard can EXECUTE the rules rather than grep for them. See its docstring for the two
+        //   defects it encodes.
+        const summary = summarizeActionsListing(result, {
+            all: !!values.all,
+            category: values.category,
+            search: values.search,
+            categories,
+        });
+        const label = values.building ? values.building : 'Workspace';
+        console.log('');
+        console.log(`  ${summary.heading(label)}`);
+        console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('');
+        const grouped = new Map();
+        for (const action of actions) {
+            const cat = action.category ?? 'general';
+            if (!grouped.has(cat))
+                grouped.set(cat, []);
+            grouped.get(cat).push(action);
+        }
+        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 aliasLabel = Array.isArray(a.aliases) && a.aliases.length > 0
+                    ? `  \x1b[2m(also: ${a.aliases.join(', ')})\x1b[0m`
+                    : '';
+                /**
+                 * ⚠ ONLY `--all` CAN PRODUCE THIS ROW, AND IT MUST NOT LOOK LIKE THE OTHERS. Hiding the
+                 * uncallable half by default and then handing an operator an unlabelled superset would
+                 * trade one silent list for another — the escape hatch has to distinguish what it adds,
+                 * or `--all` is just a longer version of the same lie.
+                 */
+                const unreachable = a.reachable === false ? `  \x1b[33m[unreachable]\x1b[0m` : '';
+                console.log(`    ${a.name.padEnd(30)}${unreachable}${desc}${aliasLabel}`);
+            }
+            console.log('');
+        }
+        /**
+         * ⚠⚠ A LIST THAT LEAVES THINGS OUT HAS TO SAY SO, WHICHEVER WAY IT WAS NARROWED. Both of this
+         * command's defects were the same shape — a partial answer wearing the word that means
+         * complete — so `summarizeActionsListing` decides both and this only paints them.
+         */
+        for (const n of summary.notices) {
+            console.log(n.startsWith('⚠') ? `  \x1b[33m${n}\x1b[0m` : `  \x1b[2m${n}\x1b[0m`);
+        }
+        if (summary.notices.length)
+            console.log('');
+        console.log('  ─────────────────────────────────────────────────');
+        console.log('  Call one:      beehaven call <action> \'{"key":"value"}\'');
+        console.log('  Full schemas:  beehaven actions --format full --json');
+        console.log('  Tool-use JSON: beehaven actions --format tool-use');
+        console.log('  Filter:        beehaven actions --category <cat> --search <substr>');
+        console.log('');
+        console.log('  Still lost?  beehaven pwd  ·  beehaven workspace  ·  beehaven ls /');
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        console.error('');
+        console.error('  Try:');
+        console.error('    beehaven pwd                     # confirm target + state');
+        console.error('    beehaven status                  # daemon + relay health');
+        process.exit(1);
+    }
+}
+// ── beehaven call <action> [json] ────────────────────────────────────────
+/**
+ * ⚠⚠ THE ATTRIBUTION MACHINERY MOVED TO `agent-attribution.ts` — AND THE MOVE IS THE FIX.
+ *
+ * `activeAgentWrap`, `setCliDoor`/`cliDoor` and `BOOTSTRAP_ACTIONS` all used to live here, and
+ * `rpcOnce` did not apply them: a verb was attributed only if its module remembered to import
+ * `agentRpc` instead of `rpcOnce`. Three modules remembered; twelve did not; **28 of 47 remote
+ * verbs wrote no `agent_activity` row at all** and therefore no `source`. A traffic report over
+ * that column then read their silence as "nobody uses this", and the recorded retirement criterion
+ * would have deleted `task` and `search` on the strength of it — measuring the instrumentation and
+ * calling it usage.
+ *
+ * The wrap now lives at the THREE places an rpc frame is built — `IpcClient.call`
+ * (`ipc-client.ts`), `daemonRpc` (`daemon-client.ts`) and `ClaudeBridge.rpc` — because those, not
+ * `rpcOnce`, are what every path to the workspace actually passes through. These re-exports keep
+ * `cli.ts` (`setCliDoor`) and `commands/shell.ts` (`activeAgentWrap`) importing from where they
+ * always did.
+ *
+ * ⚠ IT SITS IN ITS OWN MODULE ONLY TO AVOID A CYCLE — this file imports `rpcOnce`, so
+ * `ipc-client.ts` cannot import this one.
+ */
+export { activeAgentWrap, setCliDoor, cliDoor, alreadyAttributed, BOOTSTRAP_ACTIONS, DAEMON_LOCAL_ACTIONS } from '../agent-attribution.js';
+/**
+ * ⚠⚠ NO LONGER THE THING THAT MAKES A CALL ATTRIBUTED — `IpcClient.call` DOES THAT NOW.
+ *
+ * This was the opt-in: `beehaven call` wrapped every action in `agent-invoke`, and a verb that
+ * reached for bare `rpcOnce` did NOT, so it ran as the ACCOUNT OWNER rather than as the signed-in
+ * agent. Measured 2026-09-04 on two comments left seconds apart on one card:
+ *
+ *     beehaven call ticket-comment …   ->  author  agent:jinri-claude
+ *     beehaven ticket comment …        ->  author  oKB2ZCc3nwXwQg5ps8AQLmLkUAA2
+ *
+ * ⚠⚠ THE DIAGNOSIS WAS RIGHT AND THE REMEDY WAS THE WRONG SHAPE. "Use this in a verb, never bare
+ * `rpcOnce`" is a rule enforced by memory, and it was forgotten in twelve of fifteen modules — so
+ * the wrap moved DOWN to the transport, where forgetting is not an available failure. Both
+ * functions now do the same thing.
+ *
+ * ⚠ IT IS KEPT, NOT DELETED, AND NOT BECAUSE OF THE CALL SITES. `values` is the one thing
+ * `rpcOnce` cannot see: `resolveActiveAgent(values)` reads `--agent <name>`, so a caller that
+ * parsed flags can name a DIFFERENT identity than the ambient one. Bare `rpcOnce` resolves the
+ * ambient identity and is correct for every verb that does not offer that flag.
+ */
+export async function agentRpc(action, input, timeout, values = {}) {
+    const wrapped = activeAgentWrap(action, input, values);
+    return rpcOnce(wrapped.action, wrapped.input, timeout);
+}
+/**
+ * Does this result payload represent a failure? Mirrors `isFailurePayload` in the worker's
+ * mcp-server.ts on purpose — the CLI door and the MCP door must agree about what "failed" means,
+ * or the same call is a failure over one transport and a success over the other.
+ *
+ * ⚠ `error: ''` IS NOT A FAILURE — some handlers set the field empty on success.
+ */
+export function isFailureResult(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const d = data;
+    if (d.ok === false)
+        return true;
+    if (typeof d.error === 'string' && d.error.length > 0)
+        return true;
+    if (d.error && typeof d.error === 'object')
+        return true;
+    return false;
+}
+/**
+ * ⚠⚠ AN ARGUMENT TYPO CAME BACK AS AN INTERNAL STORAGE ERROR — CBH2-51.
+ *
+ *     $ beehaven call project-delete '{"projectId":"e1915d41-…"}'
+ *     { "error": "[projects] Primary key value is null/undefined.
+ *                 Ensure the row includes the primary key field." }
+ *
+ * The verb takes `id`. The refusal never says so — it is the storage layer complaining about a
+ * ROW, so it reads as data corruption rather than a mistyped argument, and it sends the reader to
+ * inspect a table instead of their own JSON.
+ *
+ * ⚠⚠ THE CONFUSION IS EARNED, WHICH IS WHY THIS IS NOT JUST A BAD MESSAGE. The SIBLING verb
+ * `project-copy` REQUIRES `projectId` (verified live: `required: ['projectId']`). So the two
+ * project verbs genuinely disagree about what the project argument is called, and the one that
+ * refuses is the one that will not say.
+ */
+const PK_LEAK = /primary key value is null|ensure the row includes the primary key/i;
+/** Is this refusal about the caller's ARGUMENTS rather than about their data? */
+export function looksLikeArgShapeError(errorText) {
+    const s = typeof errorText === 'string' ? errorText : '';
+    return PK_LEAK.test(s);
+}
+/** `projectId` → `project id`; lets a camelCase key be compared word-wise. */
+function words(k) {
+    return k.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+/**
+ * Which field did the caller most likely MEAN by `sent`, out of `candidates`?
+ *
+ * ⚠ NAME A SUBSTITUTION ONLY WHEN IT IS OBVIOUS. A wrong guess here is the same class of defect
+ * being fixed — a confident, actionable, false cause — so the bar is a shared word
+ * (`projectId` → `project` `id` ⊃ `id`), not a fuzzy distance that will pair anything with
+ * anything on a schema of six similar names.
+ */
+export function nearestField(sent, candidates) {
+    const sw = words(sent);
+    for (const c of candidates) {
+        if (c.toLowerCase() === sent.toLowerCase())
+            return c;
+        const cw = words(c);
+        if (cw.length && cw.every((w) => sw.includes(w)))
+            return c; // `id` ⊂ `project id`
+        if (sw.length && sw.every((w) => cw.includes(w)))
+            return c; // and the reverse
+    }
+    return null;
+}
+/**
+ * The advice, from the action's OWN schema — derived, never a hand-kept table of verb quirks.
+ *
+ * ⚠ A LIST OF KNOWN-BAD FIELD NAMES WOULD GO STALE THE WAY EVERY MIRROR IN THIS PACKAGE HAS
+ * (`JSON_CAPABLE`, the help coverage list). `describe-action` already publishes `required` and
+ * `properties`; comparing the caller's keys against them covers every verb, including ones written
+ * after this code.
+ *
+ * ⚠ IT ALSO REPORTS UNKNOWN KEYS EVEN WHEN NOTHING IS MISSING, because `z.object()` STRIPS them
+ * silently — the caller's value never reaches the handler and nothing anywhere says so.
+ *
+ * PURE: schema + input in, lines out. No daemon, no round trip.
+ */
+export function argShapeAdvice(action, input, schema) {
+    const required = Array.isArray(schema?.required) ? schema.required : [];
+    const props = Object.keys(schema?.properties ?? {});
+    if (!required.length && !props.length)
+        return [];
+    const sent = Object.keys(input ?? {});
+    const missing = required.filter((r) => !sent.includes(r));
+    const unknown = props.length ? sent.filter((s) => !props.includes(s)) : [];
+    if (!missing.length && !unknown.length)
+        return [];
+    const out = [''];
+    for (const m of missing) {
+        const mistyped = nearestField(m, unknown);
+        out.push(mistyped
+            ? `  \`${action}\` takes \`${m}\` — you sent \`${mistyped}\`.`
+            : `  \`${action}\` requires \`${m}\`, which was not in your input.`);
+    }
+    const stray = unknown.filter((u) => !missing.some((m) => nearestField(m, [u])));
+    if (stray.length) {
+        out.push(`  Ignored (not in this verb's schema, so it was stripped before the handler saw it): `
+            + stray.map((s) => `\`${s}\``).join(', '));
+    }
+    if (props.length)
+        out.push(`  Accepts: ${props.join(', ')}`);
+    out.push(`  Full schema:  beehaven explain ${action}`);
+    out.push('');
+    return out;
+}
+export async function cmdCall(action, rawInput, values) {
+    let input = {};
+    // Payload may come from a file (@path) or stdin (-) so large/escaped JSON
+    // (e.g. a markdown body, a doc) doesn't have to survive shell quoting.
+    if (rawInput === '-' || (rawInput && rawInput.startsWith('@'))) {
+        const { readFileSync } = await import('fs');
+        const { resolve } = await import('path');
+        try {
+            rawInput =
+                rawInput === '-'
+                    ? readFileSync(0, 'utf8')
+                    : readFileSync(resolve(rawInput.slice(1)), 'utf8');
+        }
+        catch (err) {
+            console.error(`  Could not read input: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (rawInput) {
+        try {
+            input = JSON.parse(rawInput);
+        }
+        catch {
+            console.error(`  Invalid JSON input: ${rawInput}`);
+            console.error('  Example: beehaven call note-create \'{"title":"My Note"}\'');
+            console.error('  Tip:     beehaven actions                   # see valid action names + schemas');
+            process.exit(1);
+        }
+    }
+    // These are plausible names for existing actions, not extra workspace RPCs.
+    // Resolve them only when DESCRIBING an action so discovery leads to the real
+    // schema without silently changing the meaning of a direct write call.
+    if (['action-describe', 'describe-action', 'explain-action'].includes(action)) {
+        const requested = String(input?.action ?? input?.name ?? '');
+        const canonical = requested === 'ticket-search' ? 'ticket-list'
+            : requested === 'document-move' ? 'note-update' : '';
+        if (canonical) {
+            if (!values.json)
+                console.error(`  ${requested} is not a workspace action; showing ${canonical}.`);
+            input = { ...input, action: canonical, name: canonical };
+        }
+    }
+    // Confirm spend BEFORE resolving a building or touching the daemon — a cancelled call must
+    // cost nothing and behave identically whether the input came from argv, a file, or stdin.
+    // It runs after the parse because the gate is input-aware: `engine:'handroll'` and any call
+    // carrying `svgContent` are free and never prompt.
+    /**
+     * ⚠⚠ REFUSE AN OVERSIZED PAYLOAD HERE, BECAUSE THE FRAME DIES BEFORE ANYONE CAN REPORT ON IT.
+     *
+     * The relay caps a WebSocket message at 1 MB. Measured against the live worker: a 900 KB
+     * `document-create` succeeds, a 1 MB one answers **"Connection closed"**, and a 3 MB one produces
+     * NO OUTPUT AT ALL — the socket drops and the promise never settles. The worker has its own
+     * size guard, and on this path it can never run: the message is discarded in transport, so the
+     * handler is never entered and there is nothing server-side left to explain the failure.
+     *
+     * ⚠ NOT A DUPLICATE OF THE SERVER CHECK — a DIFFERENT LAYER. MCP arrives over HTTP POST and does
+     * reach the handler, so that guard is what protects those callers. Deleting either one leaves a
+     * door where an oversized write fails without saying why.
+     *
+     * ⚠ IT NAMES THE ROUTE THAT WORKS. A document is NOT limited to 1 MB — only one WRITE is; a 2 MB
+     * note is reachable by appending in chunks, verified end to end. A refusal that omits that reads
+     * as "documents cannot be this big" and an agent gives up on a document it could have written.
+     *
+     * ⚠⚠ AND THE UPLOAD ADVICE IS CHOSEN BY THE PAYLOAD, NOT BY AN ALLOWLIST OF VERB NAMES.
+     *
+     * It was `/^(file-teleport-inline|library-upload|file-uploaded)$/` — three names, and there are
+     * at least five other byte-carrying verbs (`canvas-upload-image`, `canvas-add-image`,
+     * `deck-add-image`, `agent-avatar-upload`, `compose-upload-init`). Measured 2026-09-02: an agent
+     * uploading sixteen screenshots to a composition used `canvas-upload-image`, fell through to the
+     * generic *"split the input"*, and re-encoded everything to JPEG — losing quality to work around
+     * a limit that does not apply to uploads at all, while `beehaven teleport` and the presigned PUT
+     * were both available and unmentioned.
+     *
+     * A name list goes stale on the next upload verb, silently, and the failure is a caller giving up
+     * on a route that works. So it asks the INPUT whether it is carrying bytes — the same shape rule
+     * `actionTimeouts.ts` uses for slow actions, and for the same reason.
+     */
+    const MAX_CALL_BYTES = 768_000;
+    const payloadBytes = Buffer.byteLength(JSON.stringify(input ?? {}), 'utf8');
+    if (payloadBytes > MAX_CALL_BYTES) {
+        console.error(`  Payload is ${payloadBytes.toLocaleString()} bytes; one call carries at most ${MAX_CALL_BYTES.toLocaleString()}`);
+        console.error('  (the relay caps a WebSocket message at 1 MB — a larger frame is dropped in');
+        console.error('  transport, which is why an oversized call used to fail with no message at all).');
+        console.error('');
+        if (/^(document|note)-/.test(action)) {
+            console.error('  A document has no such limit — only one write does. Build it in pieces:');
+            console.error('');
+            console.error(`      beehaven call document-create '{"title":"…","markdown":"<first chunk>"}'`);
+            console.error(`      beehaven call document-append @chunk-2.json     # repeat under 768,000 chars`);
+            console.error('');
+            console.error('  A 2 MB document built that way reads back normally.');
+        }
+        else if (/^(file-teleport-inline|library-upload|file-uploaded)$/.test(action) || carriesInlineBytes(input)) {
+            // ⚠ AN UPLOAD IS NOT SIZE-LIMITED — only this ONE way of carrying it is. A refusal that
+            // stops at "too big" reads as "the workspace cannot hold this file", and the caller
+            // abandons an upload that has always been available. `teleport` picks the right carrier on
+            // its own, which is why it is named first.
+            console.error('  Uploads are NOT limited to this size — inline bytes are. Two ways through:');
+            console.error('');
+            console.error('      beehaven teleport ./the-file.pdf        # picks inline vs direct-to-R2 for you');
+            console.error('');
+            console.error('  Or drive it yourself: get-upload-url → HTTP PUT the bytes → file-uploaded.');
+            console.error('  That path streams straight to R2 and never crosses the WebSocket.');
+        }
+        else {
+            console.error('  Split the input, or write the payload to a file the workspace can read.');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    await assertActionAllowed(action, input, { yes: values.yes });
+    /**
+     * ⚠⚠ THE AGENT WRAP GOES INSIDE THE BUILDING ENVELOPE, SO ROUTING HAPPENS LAST.
+     *
+     * This used to route FIRST and then wrap the envelope in `agent-invoke`, producing
+     *   { agent-invoke → { admin:team-rpc → { document-list } } }
+     * — so `agent-invoke` itself carried NO building and executed on the daemon's DEFAULT DO, while
+     * only the inner verb was proxied onward. `_checkAgentScope` therefore asked the WRONG
+     * WORKSPACE whether the agent was a member.
+     *
+     * ⚠ IT COST FOUR WRONG HYPOTHESES, because the refusal did not name the roster it consulted.
+     * Measured once it did: the cursor said `604b981e`, the gate answered
+     * `unknown agent 'finalcheck' (workspace 17645b8e, 88 agents)`.
+     *
+     * ⚠ AND IT WAS ALREADY KNOWN ONE LAYER DOWN, in a different form. `agent-grant-rpcs.ts` unwraps
+     * `proxiedAction` precisely because the gate and the log were reading the ENVELOPE rather than
+     * the work — "a `tool_allowlist` silently stopped applying the moment a caller connected to a
+     * workspace". That was this defect seen from the server, patched where it surfaced. Nesting the
+     * other way round removes the cause: the proxy now carries `agent-invoke` to the addressed DO,
+     * so the gate, the activity log and the work all happen in one place.
+     */
+    /**
+     * ⚠⚠ ATTACH THIS LOGIN'S SHELL cwd BEFORE THE AGENT WRAP, NOT AFTER.
+     *
+     * `activeAgentWrap` nests the payload inside `agent-invoke`, so anything added afterwards lands
+     * on the ENVELOPE and never reaches the handler — the same shape as the `proxiedAction` bug
+     * documented just above, where the gate read the envelope instead of the work.
+     *
+     * ⚠ THE RAW `call` DOOR NEEDS THIS AS MUCH AS THE SHORTHAND. `beehaven ls ~` goes through
+     * `execNotesShell`, but `beehaven call bash '{"command":"cd Q1"}'` comes through here — and that
+     * is the spelling used all over this repo's own notes. Wiring only the shorthand would leave the
+     * cwd shared for exactly the callers most likely to be agents.
+     */
+    const shellTarget = shellTargetKey(values.building || getTarget()?.address);
+    input = attachShellCwd(action, input, shellTarget);
+    const wrapped = activeAgentWrap(action, input, values);
+    let resolved = resolveBuilding(wrapped.action, wrapped.input, values.building);
+    /**
+     * ⚠⚠ RUN AS THE AGENT WHEN ONE IS LOGGED IN — the last gap in the identity story.
+     *
+     * `agent login` minted an identity, opened a workspace session and stored the session id
+     * — and `beehaven call` ignored all of it. `rpcOnce` sends `{action, input}` with no
+     * principal, so every ordinary call ran as the USER. Only `say`/`speak` ever attached the
+     * token, and only against the avatar building. An agent could be fully authenticated and
+     * still leave no trace of having done anything.
+     *
+     * `agent-invoke` is the mechanism that already exists for this — it is what MCP uses for
+     * an agent-scoped token. It applies the per-agent gate (`permission_scope` /
+     * `tool_allowlist` on the agents row) and writes the activity log, so routing through it
+     * is what makes an agent's calls both ATTRIBUTED and GOVERNED rather than indistinguishable
+     * from the account owner's.
+     *
+     * ⚠ NOT WHEN `--building` IS SET: that path is already wrapped in an `admin:*-rpc`
+     * envelope, and nesting agent-invoke inside a cross-DO proxy would attribute the call in
+     * the wrong workspace's activity log.
+     */
+    /**
+     * ⚠⚠ AND THE FALL-THROUGH IS GONE — AN AGENT NEVER RUNS UN-ATTRIBUTED (2026-08-28).
+     *
+     * This used to read `if (activeForCall && !activeForCall.expired && …)` with NO else, so every
+     * way of not having a usable identity quietly dispatched the action DIRECTLY: no `agent-invoke`,
+     * no `permission_scope` / `tool_allowlist` gate, no activity row — running as the ACCOUNT OWNER.
+     * Three doors led there and each is now a refusal:
+     *
+     *   1. an agent runtime with no identity        → `beehaven agent login <name>`
+     *   2. an identity whose token has EXPIRED      → log in again
+     *   3. `--building`, which skips agent-invoke   → connect to that workspace instead
+     *
+     * ⚠⚠ (2) IS THE SHARPEST AND IS WHY THIS IS NOT COSMETIC: PRIVILEGE WENT **UP** ON EXPIRY. An
+     * agent bound by a read-only allowlist, whose token lapsed, silently became the account owner and
+     * kept working — the one state where a credential must do LESS, it did more, with nothing on
+     * screen to say so. An expired token is a re-login, never an escalation.
+     *
+     * ⚠⚠ A HUMAN IS NOT REFUSED, AND THE PREDICATE IS WHY. `isAgentRuntime()` answers only to a
+     * POSITIVE marker; `deriveAgentScope()` would have been the obvious test and is wrong, because it
+     * falls back to `pid-<ppid>` for any non-TTY — so `beehaven call … | jq`, every script and every
+     * CI step would have been told to log in as a robot to read their own workspace.
+     *
+     * ⚠ `--building` IS ONLY REFUSED WHEN AN AGENT IS ACTUALLY ACTIVE. The reason it skips
+     * agent-invoke is real and unchanged (nesting inside an `admin:*-rpc` proxy files the activity in
+     * the wrong workspace's log) — but "the attribution would be wrong there" is an argument for
+     * refusing the call, not for silently making it un-attributed. A human's `--building` is
+     * untouched.
+     */
+    const activeForCall = resolveActiveAgent(values);
+    if (activeForCall?.expired) {
+        console.error(`  Your agent identity for "${activeForCall.name}" has expired.`);
+        console.error(`  Run: beehaven agent login ${activeForCall.name}`);
+        console.error('  (Calls are not run as the account owner when an agent identity lapses.)');
+        process.exit(1);
+    }
+    if (!activeForCall && isAgentRuntime()) {
+        console.error('  No agent identity — this call would run as the account owner, ungated and unattributed.');
+        console.error('  Run: beehaven agent login <name>');
+        console.error('  Or:  beehaven agent list          # identities on this machine');
+        process.exit(1);
+    }
+    /**
+     * ⚠⚠ THE FLAG IS READ FROM `process.argv`, NOT FROM `values.building` — THEY ARE NOT THE
+     * SAME QUESTION, AND THIS GUARD SHIPPED BROKEN BECAUSE IT ASKED THE WRONG ONE.
+     *
+     * `resolveTargetBuilding()` (cli.ts) WRITES `values.building` before dispatch: from the target
+     * file when the address has a slash, and from the daemon's own focus when no target was ever
+     * set. So by the time this runs, that field usually holds a value the caller never typed — and
+     * the guard refused EVERY call the moment an agent signed in, naming a flag that was not on the
+     * command line. Reproduced live: `beehaven call get-upload-url '{...}'` as `claude`.
+     *
+     * The invariant is about INTENT ("the caller asked to proxy"), and only argv still carries it.
+     * Same lesson as every other guard in this tree: pin the claim, never a field that something
+     * upstream is also allowed to write.
+     */
+    const buildingFlagTyped = process.argv.some((a) => a === '--building' || a === '-b' || a.startsWith('--building='));
+    if (activeForCall && buildingFlagTyped) {
+        console.error(`  Cannot use --building while signed in as "${activeForCall.name}".`);
+        console.error('  A proxied call cannot be attributed to an agent in the target workspace.');
+        console.error('  Run: beehaven connect <address>   # then call it directly');
+        process.exit(1);
+    }
+    // ⚠ The wrap now happens ABOVE, before routing — see `activeAgentWrap`. Wrapping here would put
+    //   `agent-invoke` outside the building envelope again, which is the bug that cost four
+    //   hypotheses; the assignment is left out deliberately rather than reordered in place.
+    // Surface routing — one dim line at the top so agents (and humans) know
+    // exactly which DO the call lands on. Skip in --json mode to keep output
+    // machine-parseable.
+    if (!values.json) {
+        /**
+         * ⚠ THE BREADCRUMB USED TO SAY `home` WHENEVER `--building` WAS ABSENT — including when
+         * the call was about to be routed by the DAEMON's focus to somewhere else entirely. It
+         * was the one line that could have caught the wrong-workspace drift (CLR-1161) and it
+         * was asserting the very thing that was false. `resolveTargetBuilding` now guarantees
+         * that an absent `building` really does mean home, so this is finally true.
+         */
+        const target = values.building ? values.building : 'home';
+        // ⚠ Name the PRINCIPAL as well as the target. "as <agent>" is the only on-screen
+        // difference between a call the workspace attributes to an agent and one it books
+        // against the account owner, and that distinction was previously invisible.
+        // ⚠ `!activeForCall.expired` USED TO BE PART OF THIS TEST AND IS NOW DEAD — an expired
+        // identity is refused above, so it can never reach the breadcrumb. Leaving it in kept a stale
+        // guard green by accident: the suite's "an EXPIRED token does not silently act as the agent"
+        // assertion was matching THIS line rather than the routing condition it meant to pin.
+        const who = activeForCall ? `  ${'\x1b[36m'}as ${activeForCall.name}\x1b[0m\x1b[2m` : '';
+        console.error(`\x1b[2m→ ${target}  ${action}${who}\x1b[0m`);
+    }
+    try {
+        const raw = await rpcOnce(resolved.action, resolved.input, getTimeout(values));
+        // Unwrap proxy envelope: admin:*-rpc wraps results in { type: 'ack', result: ... }
+        const result = raw?.type === 'ack' && raw?.result !== undefined
+            ? raw.result
+            : raw?.result !== undefined && values.building
+                ? raw.result
+                : raw;
+        // ⚠ PERSIST BEFORE THE ERROR BRANCHES BELOW. `cd Q1 && ls nope` exits non-zero having already
+        //   moved, and the handler returns the new cwd on its failure path precisely for that reason —
+        //   absorbing only on success would silently drop a directory change the shell really made.
+        absorbShellCwd(action, result, shellTarget);
+        // Check for proxied errors
+        if (raw?.type === 'error') {
+            console.error(JSON.stringify({ error: raw.message ?? 'Action failed' }, null, 2));
+            printCallErrorHints(raw.message, action, values);
+            process.exit(1);
+        }
+        if (result && typeof result === 'object') {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(result);
+        }
+        /**
+         * ⚠⚠ A FAILURE INSIDE A SUCCESSFUL ENVELOPE IS STILL A FAILURE — `beehaven call` EXITED 0 FOR
+         * EVERYTHING.
+         *
+         * The two exits above cover a thrown transport error and a proxied `type:'error'`. Neither is
+         * the common case: an unknown action, a handler refusal and an internal SQL error all come back
+         * as an ordinary `ack` carrying `{ error }` or `{ ok:false }` in the RESULT, which landed here
+         * and exited 0. Measured — unknown action, ok:false, `code:'bad-path'`, SQL error and genuine
+         * success all returned 0, while `beehaven sql "SELECT"` and `beehaven cat <missing>` correctly
+         * returned 1. `call` is the verb the docs call canonical, and it was the one that could not be
+         * tested by a script: `beehaven call x || handle` never fired.
+         *
+         * ⚠ THE CODEBASE ALREADY DEPENDS ON THIS WORKING. The `AGENT_LOGIN_EXEMPT` note beside
+         * `case 'characters'` states that routed through `call` the Mac app "gets a login prompt on
+         * stderr and a non-zero exit" — a false premise holding up an exemption.
+         *
+         * ⚠ `error: ''` IS NOT A FAILURE. Some handlers set the field empty on success, so an
+         * emptiness check is required rather than mere presence — the same rule `isFailurePayload`
+         * follows in mcp-server.ts, which this mirrors deliberately so the two doors agree.
+         *
+         * ⚠ THE RESULT IS STILL PRINTED FIRST. The caller needs the payload to know WHY; exiting
+         * before printing would trade a silent success for a silent failure.
+         */
+        /**
+         * ⚠⚠ AN IDENTITY IS PER WORKSPACE, AND `unknown agent 'X'` IS THE SERVER SAYING SO.
+         *
+         * The credential is per-USER — the token carries `agentId` + `userId` and NO workspace — but
+         * the agent ROW lives in the workspace DO, and `_checkAgentScope` refuses a principal it has
+         * no row for. So an identity minted in workspace A is genuinely unusable in workspace B until
+         * you log in THERE, which is the act that creates the row.
+         *
+         * ⚠ THE RAW REFUSAL READS AS "THAT AGENT DOES NOT EXIST", which is the opposite of the truth:
+         * it exists, it is valid, it is simply not a member here. Reproduced live — connecting to a
+         * second workspace and calling `document-list` answered `unknown agent 'jinri-claude'` with
+         * nothing to act on, so the recovery is to re-mint under a new name or conclude the login
+         * broke.
+         *
+         * ⚠ THE HINT BELONGS ON THIS SIDE because neither half can answer alone: only the client knows
+         * the identity is present on this machine, only the server knows the workspace roster.
+         */
+        /**
+         * ⚠⚠ SELF-HEAL: ADMIT THE IDENTITY AND RETRY ONCE. Identity is minted at the ACCOUNT
+         * (`agent-account-mint`), and a workspace still decides for itself who may act in it — so the
+         * first call into a workspace you have not joined is legitimately refused. Admitting here, in
+         * the ONE routing this CLI exercises on every invocation, is what turns that into a step the
+         * person never has to know about.
+         *
+         * ⚠ THIS IS NOT AUTO-ADMISSION INTO WORKSPACES YOU DID NOT ASK FOR. It fires only on a
+         * workspace you explicitly connected to and are actively calling, and `agent-admit` still
+         * charges `maxAgents` and refuses at the cap — which is then REPORTED rather than retried.
+         *
+         * ⚠ ONCE. A second refusal is a real one (revoked identity, entitlement, a genuinely unknown
+         * name), and retrying past it turns one clear error into a loop.
+         */
+        if (result && typeof result === 'object' && result.scope === 'unknown-agent'
+            && activeForCall && !values.__admitRetry) {
+            const admit = resolveBuilding('agent-admit', { agentId: activeForCall.agentId }, values.building);
+            const ar = await rpcOnce(admit.action, admit.input, 20_000).catch(() => null);
+            const ares = ar?.result ?? ar;
+            if (ares?.ok) {
+                if (!values.json) {
+                    console.error(`  ${activeForCall.name} joined this workspace — retrying.`);
+                }
+                return await cmdCall(action, rawInput, { ...values, __admitRetry: true });
+            }
+            console.error('');
+            console.error(`  "${activeForCall.name}" could not join this workspace: ${ares?.error ?? 'unknown reason'}`);
+            if (String(ares?.code) === 'unknown-identity') {
+                console.error(`  Mint it first:  beehaven agent login ${activeForCall.name}`);
+            }
+        }
+        /**
+         * ⚠⚠ CBH2-51 — TRANSLATE A STORAGE-LAYER LEAK INTO THE ARGUMENT IT IS REALLY ABOUT.
+         *
+         * ⚠ ON FAILURE ONLY, AND ONLY FOR THIS ERROR SHAPE. It costs one `describe-action` round trip,
+         * which is free on a call that has already failed and would be a tax on every call that has
+         * not. `looksLikeArgShapeError` is what keeps it narrow.
+         *
+         * ⚠ NON-FATAL, AND SILENT WHEN IT HAS NOTHING TO ADD. If the schema cannot be fetched the
+         * caller still gets the original payload and the original exit code — an extra diagnosis must
+         * never be able to turn a reported failure into a crash, or into a second wrong cause.
+         */
+        if (isFailureResult(result) && !values.json) {
+            const errText = result?.error;
+            if (looksLikeArgShapeError(errText)) {
+                try {
+                    const d = resolveBuilding('describe-action', { name: action }, values.building);
+                    const dr = await rpcOnce(d.action, d.input, 15_000).catch(() => null);
+                    const schema = (dr?.result ?? dr)?.input;
+                    for (const line of argShapeAdvice(action, input, schema))
+                        console.error(line);
+                }
+                catch { /* the payload above is still the answer */ }
+            }
+            printKnownActionAdvice(action, input, result);
+        }
+        if (isFailureResult(result))
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(JSON.stringify({ error: err.message }, null, 2));
+        printCallErrorHints(err.message, action, values);
+        process.exit(1);
+    }
+}
+/** Give exact existing verbs for names a caller reasonably guessed. */
+function printKnownActionAdvice(action, input, result) {
+    const described = ['action-describe', 'describe-action', 'explain-action'].includes(action);
+    const requested = described ? String(input?.action ?? input?.name ?? '') : action;
+    if (result?.code === 'unknown_action') {
+        if (requested === 'ticket-search') {
+            console.error('  Search tickets with: beehaven call ticket-list \'{"text":"<query>","limit":20}\'');
+        }
+        else if (requested === 'document-move') {
+            console.error('  Move a document with: beehaven call note-update \'{"id":"<document-id>","updates":{"projectId":"<project-id>"}}\'');
+        }
+    }
+    if (action === 'ticket-get' && result?.code === 'not-found') {
+        console.error('  If this key belongs to a document, read it with document-get; ticket-get reads board cards only.');
+    }
+}
+/**
+ * Emit navigation hints for common call failures. Agents parse these to
+ * self-correct without a round-trip back to the user.
+ */
+function printCallErrorHints(msg, action, values) {
+    if (!msg)
+        return;
+    const s = String(msg).toLowerCase();
+    if (!values.json) {
+        console.error('');
+        console.error('\x1b[2m  Try:\x1b[0m');
+        if (s.includes('unknown action') || s.includes('404')) {
+            console.error(`\x1b[2m    beehaven actions --search <name>  # find the mounted action\x1b[0m`);
+            console.error(`\x1b[2m    beehaven pwd                      # confirm you\'re on the right DO\x1b[0m`);
+        }
+        else if (s.includes('timeout') || s.includes('websocket send failed')) {
+            if (action === 'document-create') {
+                console.error('  The write outcome is unknown. Search for the document title and inspect its ticket link before retrying; a blind retry can create a duplicate.');
+            }
+            else {
+                console.error(`\x1b[2m    beehaven pwd                      # confirm the target before retrying\x1b[0m`);
+            }
+            console.error(`\x1b[2m    beehaven status                   # confirm daemon + relay are up\x1b[0m`);
+        }
+        else if (s.includes('unauthorized') || s.includes('forbidden')) {
+            console.error(`\x1b[2m    beehaven pwd                      # are you on the right target?\x1b[0m`);
+            console.error(`\x1b[2m    beehaven status                   # check auth state\x1b[0m`);
+        }
+        else if (s.includes('rate limit')) {
+            console.error(`\x1b[2m    wait a few seconds and retry\x1b[0m`);
+        }
+        else {
+            console.error(`\x1b[2m    beehaven pwd                      # where am I?\x1b[0m`);
+            console.error(`\x1b[2m    beehaven actions                  # what can I call here?\x1b[0m`);
+        }
+    }
+}
+/**
+ * Execute one JSON-RPC line without tying the work to readline's lifetime.
+ *
+ * The old implementation started this promise from `rl.on('line')` and let the
+ * close handler call `process.exit(0)`. A finite stdin therefore closed the
+ * socket while the first request was still in flight. Keeping parsing and
+ * dispatch in a pure-ish helper makes the drain contract testable and keeps
+ * all methods on `client.call`, where agent attribution and target routing live.
+ */
+export async function executePipeRequest(client, line) {
+    if (!line.trim())
+        return { response: null, failed: false };
+    let request;
+    try {
+        request = JSON.parse(line);
+    }
+    catch {
+        return {
+            response: {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse error' },
+            },
+            failed: true,
+        };
+    }
+    const { id, method, params } = request ?? {};
+    if (!method) {
+        return {
+            response: {
+                jsonrpc: '2.0',
+                id: id ?? null,
+                error: { code: -32600, message: 'Missing method' },
+            },
+            failed: true,
+        };
+    }
+    try {
+        let result;
+        switch (method) {
+            case 'ping':
+                result = { pong: true, timestamp: Date.now() };
+                break;
+            case 'actions.list':
+                result = await client.call('list-actions', params || {});
+                break;
+            case 'actions.describe':
+                result = await client.call('describe-action', params || {});
+                break;
+            case 'actions.search':
+                // Agent-friendly fuzzy match: "action that creates a task" →
+                // ranks note-create with board fileType above note-update.
+                // Implemented client-side so it works on any DO with
+                // list-actions (doesn't require a server-side actions.search
+                // handler). Returns top matches with scores.
+                result = await actionsSearch(client, params || {});
+                break;
+            case 'workspace.info':
+                result = await client.call('workspace-info', params || {});
+                break;
+            default:
+                result = await client.call(method, params || {});
+                break;
+        }
+        return { response: { jsonrpc: '2.0', id, result }, failed: false };
+    }
+    catch (err) {
+        const message = err?.message ?? String(err);
+        const code = message.includes('timeout') ? -32001 : -32000;
+        return {
+            response: { jsonrpc: '2.0', id, error: { code, message } },
+            failed: true,
+        };
+    }
+}
+/**
+ * Drain a finite set of JSON-RPC lines in input order.
+ *
+ * Sequential dispatch is deliberate: callers get deterministic output and
+ * the CLI never creates unbounded in-flight requests from a large script.
+ * Errors are emitted as JSON-RPC error responses, but the remaining input is
+ * still drained; the returned boolean controls the eventual non-zero exit.
+ */
+export async function drainPipeLines(lines, client, write) {
+    let ok = true;
+    for (const line of lines) {
+        const { response, failed } = await executePipeRequest(client, line);
+        if (response)
+            write(response);
+        if (failed)
+            ok = false;
+    }
+    return ok;
+}
+/**
+ * Run the workspace's declarative batch action through the canonical call
+ * path. This is intentionally only an adapter: validation, active-target
+ * resolution, agent attribution, spend confirmation and failure handling all
+ * remain in `cmdCall`.
+ */
+export function normaliseBatchPayload(payload) {
+    if (!payload || typeof payload !== 'object' || !Array.isArray(payload.steps)) {
+        return payload;
+    }
+    return {
+        ...payload,
+        steps: payload.steps.map((step) => {
+            if (!step || typeof step !== 'object')
+                return step;
+            const source = step;
+            const method = source.method ?? source.action;
+            const params = source.params ?? source.input ?? {};
+            const canonical = { ...source, method, params };
+            delete canonical.action;
+            delete canonical.input;
+            return canonical;
+        }),
+    };
+}
+export async function cmdBatch(rawInput, values) {
+    if (!rawInput) {
+        console.error('  Usage: beehaven batch <json|@file|-> [--json]');
+        process.exit(1);
+    }
+    // The workspace action's wire format is `{ method, params }`, while every
+    // other Beehaven surface calls the pair `{ action, input }`. The first CLI
+    // release documented the latter but forwarded it untouched, so the exact
+    // example in `beehaven help batch` failed with "method is required". Accept
+    // both spellings here and send one canonical payload to every worker version.
+    let source = rawInput;
+    if (source === '-' || source.startsWith('@')) {
+        const { readFileSync } = await import('fs');
+        const { resolve } = await import('path');
+        try {
+            source = source === '-'
+                ? readFileSync(0, 'utf8')
+                : readFileSync(resolve(source.slice(1)), 'utf8');
+        }
+        catch (err) {
+            console.error(`  Could not read batch input: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    let payload;
+    try {
+        payload = JSON.parse(source);
+    }
+    catch {
+        console.error(`  Invalid JSON input: ${source}`);
+        console.error('  Example: beehaven batch \'{"steps":[{"action":"ticket-list","input":{"limit":10}}]}\'');
+        process.exit(1);
+    }
+    await cmdCall('batch', JSON.stringify(normaliseBatchPayload(payload)), values);
+}
+/** Convert source text (or a JSON code-run payload) into the server input. */
+export function codeRunPayload(source) {
+    const input = { code: source };
+    try {
+        const parsed = JSON.parse(source);
+        if (parsed && typeof parsed === 'object' && typeof parsed.code === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        /* source text, not a JSON payload */
+    }
+    return input;
+}
+/**
+ * Adapt a source file/stdin stream to the workspace's `code-run` action.
+ *
+ * A source file is the ergonomic form (`code-run @script.js` or
+ * `code-run -`). For callers that need `maxCalls`/`timeoutMs`, a JSON payload
+ * containing `code` is also accepted and passed through unchanged. Either
+ * form still enters `cmdCall`, so this command cannot create a second policy
+ * or routing path beside the normal action verb.
+ */
+export async function cmdCodeRun(rawInput, values) {
+    if (!rawInput) {
+        console.error('  Usage: beehaven code-run <file|-> [--json]');
+        process.exit(1);
+    }
+    let source = rawInput;
+    if (rawInput === '-' || rawInput.startsWith('@')) {
+        const { readFileSync } = await import('fs');
+        const { resolve } = await import('path');
+        try {
+            source = rawInput === '-'
+                ? readFileSync(0, 'utf8')
+                : readFileSync(resolve(rawInput.slice(1)), 'utf8');
+        }
+        catch (err) {
+            console.error(`  Could not read code input: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    const input = codeRunPayload(source);
+    await cmdCall('code-run', JSON.stringify(input), values);
+}
+export async function cmdPipe(values) {
+    const readline = await import('readline');
+    let client;
+    try {
+        client = await connectClient({ timeout: getTimeout(values) });
+    }
+    catch (err) {
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32000, message: err.message } }) +
+            '\n');
+        process.exitCode = 1;
+        return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    let shuttingDown = false;
+    let failed = false;
+    const writeResponse = (response) => {
+        process.stdout.write(JSON.stringify(response) + '\n');
+    };
+    client.subscribe(['*']);
+    client.on('broadcast', (msg) => {
+        if (shuttingDown)
+            return;
+        writeResponse({ jsonrpc: '2.0', method: 'workspace.broadcast', params: msg });
+    });
+    const finish = (ok) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        client.disconnect();
+        failed = failed || !ok;
+        process.exitCode = failed ? 1 : 0;
+    };
+    client.on('close', () => {
+        if (shuttingDown)
+            return;
+        failed = true;
+        writeResponse({
+            jsonrpc: '2.0',
+            method: 'workspace.disconnected',
+            params: { reason: 'Daemon connection lost' },
+        });
+        // Wake a TTY reader if the daemon disappeared while it was waiting for a
+        // line. The finite-input path will naturally finish its async iterator.
+        try {
+            rl.close();
+        }
+        catch { }
+    });
+    writeResponse({ jsonrpc: '2.0', method: 'workspace.ready', params: { pid: process.pid } });
+    if (!process.stdin.isTTY) {
+        // A pipe has finite input. Collect it before dispatching anything so EOF
+        // cannot race the first asynchronous RPC, then drain it deterministically.
+        const lines = [];
+        try {
+            for await (const line of rl) {
+                const text = String(line).trim();
+                if (text)
+                    lines.push(text);
+            }
+        }
+        catch (err) {
+            failed = true;
+            writeResponse({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32000, message: err?.message ?? String(err) },
+            });
+        }
+        const ok = await drainPipeLines(lines, client, writeResponse);
+        finish(ok);
+        return;
+    }
+    // A TTY is a long-lived stream. Pause around each request so interactive
+    // callers still get one response per line without concurrent reordering.
+    let queue = Promise.resolve();
+    let closed = false;
+    rl.on('line', (line) => {
+        rl.pause();
+        queue = queue.then(async () => {
+            const result = await executePipeRequest(client, line);
+            if (result.response)
+                writeResponse(result.response);
+            if (result.failed)
+                failed = true;
+        }).catch((err) => {
+            failed = true;
+            writeResponse({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32000, message: err?.message ?? String(err) },
+            });
+        }).finally(() => {
+            if (!closed && !shuttingDown)
+                rl.resume();
+        });
+    });
+    await new Promise((resolve) => {
+        rl.on('close', () => {
+            closed = true;
+            resolve();
+        });
+    });
+    await queue;
+    finish(!failed);
+}
+// ── beehaven watch [patterns] ────────────────────────────────────────────
+export async function cmdWatch(patterns, values) {
+    let client;
+    try {
+        client = await connectClient();
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+    client.subscribe(patterns);
+    console.error(`  Watching: ${patterns.join(', ')} (Ctrl+C to stop)`);
+    // --format tool-use: agent-friendly event shapes. Instead of the raw
+    // WebSocket broadcast message, emit structured {event, table?, id?,
+    // delta?, action?} one per line so an LLM tool reading the stream can
+    // switch on `event` without parsing `data.type`.
+    // --trace: human-readable timeline mode for lifecycle debugging. Prints
+    // one compact line per event with the elapsed-ms since the previous
+    // event, indented by causal depth so cascade patterns (RPC → trigger →
+    // broadcast) are visible at a glance.
+    // --record <path>: tees every broadcast to a JSONL file. Each line is
+    // a {ts, msg} pair suitable for replay via reshapeForToolUse or a
+    // custom test harness. Works alongside --trace / --format.
+    const format = values.format ?? 'raw';
+    const trace = values.trace === true;
+    const recordPath = typeof values.record === 'string' ? values.record : null;
+    // Open a write stream for --record if requested. Append mode so
+    // re-running the watcher with the same path extends the log instead
+    // of truncating (useful for long-running captures across restarts).
+    let recordStream = null;
+    if (recordPath) {
+        const { createWriteStream, mkdirSync } = await import('fs');
+        const { dirname } = await import('path');
+        try {
+            mkdirSync(dirname(recordPath), { recursive: true });
+        }
+        catch {
+            /* directory may already exist */
+        }
+        recordStream = createWriteStream(recordPath, { flags: 'a', encoding: 'utf-8' });
+        console.error(`  Recording → ${recordPath}`);
+    }
+    const recordEvent = (msg) => {
+        if (!recordStream)
+            return;
+        recordStream.write(JSON.stringify({ ts: Date.now(), msg }) + '\n');
+    };
+    if (trace) {
+        // ── trace mode ────────────────────────────────────────────────────
+        // Track first-event t0 + last-event tick so each new line can show
+        // `+Δms since previous`. Infer indent depth from event family:
+        //   RPC start/end = 0, row-changed / hydration = 1, session/building = 2.
+        // Not a true flame graph, but groups cascades visually in the terminal
+        // without server-side span instrumentation.
+        let lastTick = null;
+        const t0 = Date.now();
+        const divider = '  ' + '─'.repeat(60);
+        console.error(divider);
+        console.error(`  ${'time'.padEnd(12)} ${'Δms'.padStart(6)}  event`);
+        console.error(divider);
+        client.on('broadcast', (msg) => {
+            recordEvent(msg);
+            const event = reshapeForToolUse(msg);
+            if (!event)
+                return;
+            const now = Date.now();
+            const absMs = now - t0;
+            const deltaMs = lastTick == null ? 0 : now - lastTick;
+            lastTick = now;
+            const clock = new Date(now).toISOString().slice(11, 23);
+            const depth = traceDepth(event.event);
+            const indent = '  ' + '  '.repeat(depth);
+            const summary = traceSummary(event);
+            const deltaStr = deltaMs === 0 ? '   —  ' : `+${String(deltaMs).padStart(4)}ms`;
+            console.log(`${indent}${clock} ${deltaStr}  ${summary}  (t+${absMs}ms)`);
+        });
+        client.on('close', () => {
+            recordStream?.end();
+            console.error('  Connection lost.');
+            process.exit(1);
+        });
+        process.on('SIGINT', () => {
+            recordStream?.end();
+            client.disconnect();
+            process.exit(0);
+        });
+        return;
+    }
+    client.on('broadcast', (msg) => {
+        recordEvent(msg);
+        if (format === 'tool-use') {
+            const event = reshapeForToolUse(msg);
+            if (event)
+                console.log(JSON.stringify(event));
+            return;
+        }
+        const ts = new Date().toISOString().slice(11, 23);
+        console.log(JSON.stringify({ timestamp: ts, type: msg?.type || 'unknown', data: msg }));
+    });
+    client.on('close', () => {
+        recordStream?.end();
+        console.error('  Connection lost.');
+        process.exit(1);
+    });
+    process.on('SIGINT', () => {
+        recordStream?.end();
+        client.disconnect();
+        process.exit(0);
+    });
+}
+/**
+ * Heuristic indent for trace mode. Events higher in the causal chain
+ * (RPC start/end — the root that kicked off the work) sit at depth 0;
+ * the data mutations and broadcasts they triggered nest under them.
+ *
+ * Not a real call tree — the server doesn't emit parent ids on broadcasts
+ * today. But the depth grouping is useful to eyeball "this RPC fired, then
+ * 3 rows changed, then a broadcast went out" patterns in the terminal.
+ *
+ * Exported so the watch-trace tests can pin the mapping.
+ */
+export function traceDepth(event) {
+    if (event === 'other')
+        return 0;
+    if (event.startsWith('stream'))
+        return 0;
+    if (event === 'row-changed' || event === 'bulk-change')
+        return 1;
+    if (event.startsWith('session'))
+        return 2;
+    if (event.startsWith('building'))
+        return 2;
+    return 0;
+}
+/** One-line human summary of a reshaped event. Short enough to fit the trace column. */
+export function traceSummary(event) {
+    switch (event.event) {
+        case 'row-changed':
+            return `row-changed ${event.table}/${event.id} ${event.op}`;
+        case 'bulk-change':
+            return `bulk-change ${event.table} ×${event.count ?? '?'}`;
+        case 'session-join':
+            return `session-join ${event.clientId}${event.app ? ` (${event.app})` : ''}`;
+        case 'session-leave':
+            return `session-leave ${event.clientId}`;
+        case 'building-connected':
+            return `building-connected ${event.buildingType}/${event.buildingId}`;
+        case 'building-disconnected':
+            return `building-disconnected ${event.buildingType}/${event.buildingId}`;
+        case 'stream-chunk':
+            return `stream-chunk ${event.streamId}`;
+        case 'stream-complete':
+            return `stream-complete ${event.streamId}`;
+        case 'other':
+            return `other ${event.type ?? '?'}`;
+        default:
+            return event.event;
+    }
+}
+/**
+ * Normalize a broadcast message into a flat {event, ...fields} shape
+ * that LLM agents can switch on without re-parsing internals.
+ *
+ * Known event mappings (best-effort — we don't know every broadcast
+ * type the SDK emits, so unknown shapes fall through to a catch-all):
+ *
+ *   sql:delta  {table, op: 'insert'|'update'|'delete', id, delta}
+ *       → { event: 'row-changed', table, op, id, delta, ts }
+ *
+ *   sql:hydration / sql:batch
+ *       → { event: 'bulk-change', table, op: 'batch', count, ts }
+ *
+ *   session:join / session:leave
+ *       → { event: 'session-<join|leave>', clientId, label, app, ts }
+ *
+ *   building:connected / building:disconnected
+ *       → { event: 'building-<connected|disconnected>', buildingType, buildingId, ts }
+ *
+ *   anything else → { event: 'other', type, data, ts }
+ *
+ * Returns null for messages we want to suppress (heartbeats, etc.).
+ */
+export function reshapeForToolUse(msg) {
+    if (!msg || typeof msg !== 'object')
+        return null;
+    const ts = new Date().toISOString();
+    const type = msg.type;
+    // Suppress pure noise — agents don't want to see keepalives.
+    if (type === 'pong' || type === 'ping' || type === 'status')
+        return null;
+    if (type === 'sql:delta') {
+        return {
+            event: 'row-changed',
+            table: msg.table,
+            op: msg.op,
+            id: msg.id,
+            delta: msg.delta ?? msg.data,
+            ts,
+        };
+    }
+    if (type === 'sql:hydration' || type === 'sql:batch') {
+        return {
+            event: 'bulk-change',
+            table: msg.table,
+            op: 'batch',
+            count: Array.isArray(msg.rows) ? msg.rows.length : (msg.count ?? undefined),
+            ts,
+        };
+    }
+    if (type === 'session:join' || type === 'session:leave') {
+        return {
+            event: type === 'session:join' ? 'session-join' : 'session-leave',
+            clientId: msg.clientId,
+            label: msg.label,
+            app: msg.app,
+            ts,
+        };
+    }
+    if (type === 'building:connected' || type === 'building:disconnected') {
+        return {
+            event: type === 'building:connected' ? 'building-connected' : 'building-disconnected',
+            buildingType: msg.buildingType,
+            buildingId: msg.buildingId,
+            ts,
+        };
+    }
+    if (type === 'stream:chunk') {
+        return {
+            event: 'stream-chunk',
+            streamId: msg.streamId,
+            chunk: msg.chunk ?? msg.data,
+            ts,
+        };
+    }
+    if (type === 'stream:complete') {
+        return {
+            event: 'stream-complete',
+            streamId: msg.streamId,
+            result: msg.result,
+            ts,
+        };
+    }
+    // Catch-all — preserve the raw message under `data` so nothing is lost,
+    // but give the agent a stable `event: 'other'` to switch against.
+    return { event: 'other', type, data: msg, ts };
+}
+// ── beehaven workspace ───────────────────────────────────────────────────
+export async function cmdWorkspace(values) {
+    try {
+        const result = await rpcOnce('workspace-info', {}, getTimeout(values));
+        if (values.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        // A DO that answers `{error: …}` still resolves the RPC — the ack itself
+        // succeeded. Rendering that straight into the template printed an empty
+        // table list and "Total: undefined" AND EXITED 0, so a workspace that
+        // couldn't be reached was indistinguishable from one that was empty.
+        // Fail loudly instead.
+        assertNoRpcError(result, 'workspace-info');
+        console.log('');
+        console.log('  Workspace');
+        console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('');
+        console.log('  \x1b[36mTables\x1b[0m');
+        for (const [name, info] of Object.entries(result.tables || {})) {
+            const t = info;
+            console.log(`    ${name.padEnd(20)} \x1b[33m${t.count}\x1b[0m rows  \x1b[90m(${t.columns.slice(0, 5).join(', ')}${t.columns.length > 5 ? '…' : ''})\x1b[0m`);
+        }
+        console.log('');
+        console.log('  \x1b[36mActions\x1b[0m');
+        const actions = result.actions || {};
+        console.log(`    Total: \x1b[33m${actions.total}\x1b[0m`);
+        if (actions.categories) {
+            for (const [cat, count] of Object.entries(actions.categories)) {
+                console.log(`    ${cat.padEnd(20)} ${count}`);
+            }
+        }
+        console.log('');
+        if (result.agent) {
+            console.log('  \x1b[36mAgent\x1b[0m');
+            console.log(`    State: ${result.agent.state}`);
+            console.log(`    Model: ${result.agent.model}`);
+            console.log('');
+        }
+        console.log('  ─────────────────────────────────────────────────');
+        console.log('  Next steps:');
+        console.log('    beehaven pwd                  Confirm current target');
+        console.log('    beehaven actions              Browse callable RPCs');
+        console.log('    beehaven ls /                 Explore the VFS');
+        console.log('    beehaven call <action> [json] Run one');
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        console.error('');
+        console.error('  Try:');
+        console.error('    beehaven pwd                  confirm daemon + target');
+        console.error('    beehaven status                daemon / relay health');
+        process.exit(1);
+    }
+}
+// ── beehaven ls [path] ───────────────────────────────────────────────────
+export async function cmdLs(path, values) {
+    try {
+        const result = await rpcOnce('browse-vfs', { path, op: 'ls' }, getTimeout(values));
+        if (values.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (result.error) {
+            console.error(`  Error: ${result.error}`);
+            process.exit(1);
+        }
+        const entries = result.entries || result;
+        if (!Array.isArray(entries) || entries.length === 0) {
+            console.log(`  (empty) ${path}`);
+            return;
+        }
+        for (const entry of entries) {
+            const icon = entry.kind === 'dir' ? 'd' : '-';
+            const name = entry.name || entry.path?.split('/').pop() || '?';
+            const size = entry.size > 0 ? `  ${formatSize(entry.size)}` : '';
+            console.log(`  ${icon} ${name}${size}`);
+        }
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven cat <path> ──────────────────────────────────────────────────
+export async function cmdCat(path, values) {
+    try {
+        const result = await rpcOnce('browse-vfs', { path, op: 'read' }, getTimeout(values));
+        if (result.error) {
+            console.error(`  Error: ${result.error}`);
+            process.exit(1);
+        }
+        const content = result.content ?? result;
+        if (typeof content === 'string')
+            console.log(content);
+        else
+            console.log(JSON.stringify(content, null, 2));
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven remember/recall/search/ask/task ─────────────────────────────
+/**
+ * ⚠⚠ `rpcOnce` RETURNS `{ error }` AS A VALUE — IT DOES NOT THROW. A `try/catch` around it is
+ * therefore not error handling, and a `console.log('  Done')` after it reports success on failure.
+ *
+ * ⚠ THIS SHIPPED. `cmdRemember` called `rpcOnce('remember', …)` and printed "Remembered: <key>"
+ * unconditionally. `remember` is not a registered action (it was renamed `agent-memory-remember`),
+ * so every invocation got back *"Unknown action: remember"*, printed success, exited 0, and wrote
+ * nothing. Measured: 0 rows across `agent_memories`, `agent-memory` and `claude_memory`.
+ *
+ * ⚠ THE UNKNOWN-ACTION CASE IS THE ONE TO KEEP IN MIND, because it is what a RENAME produces and
+ * a rename leaves no other trace. The daemon answers, the transport succeeds, and only the payload
+ * says the verb is gone.
+ */
+function rpcFailure(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    if (typeof result.error === 'string' && result.error)
+        return result.error;
+    if (result.ok === false)
+        return String(result.message ?? result.code ?? 'the workspace refused the call');
+    return null;
+}
+export async function cmdRemember(key, value, values) {
+    try {
+        // ⚠ `agent-memory-remember`, NOT `remember` — see rpcFailure above.
+        const result = await rpcOnce('agent-memory-remember', { key, value }, getTimeout(values));
+        const failure = rpcFailure(result);
+        if (failure) {
+            console.error(`  Error: ${failure}`);
+            process.exit(1);
+        }
+        console.log(`  Remembered: ${key}`);
+        /**
+         * ⚠ THE SERVER CLAMPS `importance` TO 0..1 AND SAYS SO. Swallowing that turns a visible
+         * coercion back into a silent one, which is the exact trade `agent-memory-remember` refused.
+         */
+        if (result?.importanceCoerced) {
+            const c = result.importanceCoerced;
+            console.log(`  \x1b[33m⚠\x1b[0m importance ${c.sent} stored as ${c.stored} — scale is ${c.scale}`);
+        }
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+export async function cmdRecall(query, values) {
+    try {
+        /**
+         * ⚠⚠ TWO VERBS, AND THE QUERY DECIDES WHICH. `agent-memory-recall` takes NO query — it lists
+         * by importance. `agent-memory-search` is the one that takes `query`. Sending a query to
+         * `recall` would silently list everything and look like a search that matched broadly.
+         */
+        const result = query
+            ? await rpcOnce('agent-memory-search', { query, limit: 20 }, getTimeout(values))
+            : await rpcOnce('agent-memory-recall', { limit: 20 }, getTimeout(values));
+        const failure = rpcFailure(result);
+        if (failure) {
+            console.error(`  Error: ${failure}`);
+            process.exit(1);
+        }
+        if (values.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const memories = result.memories || result.results || [];
+        if (memories.length === 0) {
+            /**
+             * ⚠ SAY WHICH QUESTION WAS ASKED. A bare "No memories found." is what a BROKEN verb printed
+             * for weeks, and it reads as *you have no memories* rather than *nothing matched*.
+             */
+            console.log(query ? `  No memories match "${query}".` : '  No memories yet.');
+            return;
+        }
+        console.log('');
+        for (const m of memories)
+            console.log(`  \x1b[36m${m.key}\x1b[0m: ${m.value}`);
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+/** The server's own ceiling — `searchNotes` does `Math.min(input.limit ?? 20, 200)`. */
+export const SEARCH_LIMIT_MAX = 200;
+export const SEARCH_LIMIT_DEFAULT = 20;
+/**
+ * ⚠⚠ `search --limit N` WAS ACCEPTED AND IGNORED, WHICH IS WORSE THAN NOT SUPPORTING IT (CBH2-29).
+ *
+ * `limit` is declared as a GLOBAL option in `cli.ts`, so `parseArgs` takes it on every verb while
+ * only a handful read it — and `cmdSearch` sent a hardcoded `limit: 20`. Measured: `--limit 1`,
+ * `--limit 2` and `--limit 5` all returned the same 20 rows.
+ *
+ * ⚠ THE SILENCE IS THE DEFECT, NOT THE MISSING FEATURE. This CLI REJECTS an unknown flag
+ * (`--bogus-flag` → *"Unknown option"*) and REFUSES `--json` on a verb that would ignore it. Against
+ * that background, a flag accepted without complaint is a positive signal that it does something.
+ *
+ * ⚠⚠ AND THE FIX MUST NOT RE-CREATE THE CLASS ONE LAYER DOWN. Three ways to be silent again, all
+ * refused here instead:
+ *   · `--limit abc` → `Number()` is `NaN`, `NaN || 20` falls back to 20 and the caller is ignored
+ *     exactly as before, now with a validation step that looks like diligence.
+ *   · `--limit 0` / `--limit -5` → asks for nothing; falling back to 20 answers a different question.
+ *   · `--limit 500` → the SERVER clamps to 200 regardless, so accepting it quietly hands back 200
+ *     rows to a caller who asked for 500 and has no way to tell. It is clamped here and SAID.
+ *
+ * PURE, so the decision is testable without a daemon: values in, `{limit}` or `{error}` out.
+ */
+export function resolveSearchLimit(values) {
+    const raw = values?.limit;
+    if (raw === undefined || raw === null || raw === '')
+        return { limit: SEARCH_LIMIT_DEFAULT };
+    const n = Number(String(raw).trim());
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        return { error: `--limit must be a whole number of results, 1-${SEARCH_LIMIT_MAX} (got "${raw}"). Nothing was searched.` };
+    }
+    if (n > SEARCH_LIMIT_MAX) {
+        return { limit: SEARCH_LIMIT_MAX, note: `--limit ${n} exceeds the server maximum — showing ${SEARCH_LIMIT_MAX}.` };
+    }
+    return { limit: n };
+}
+export async function cmdSearch(query, values) {
+    const bound = resolveSearchLimit(values);
+    if ('error' in bound) {
+        console.error(`  ${bound.error}`);
+        process.exit(1);
+    }
+    if (bound.note)
+        console.error(`  ${bound.note}`);
+    try {
+        const result = await rpcOnce('search-notes', { query, limit: bound.limit }, getTimeout(values));
+        if (values.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        assertNoRpcError(result, 'search-notes');
+        // Accept every shape this RPC has ever returned. It used to hand back a
+        // bare ARRAY on the FTS branch (and `{results}` on the other two); the
+        // array arrived here as `{"0":…,"1":…}` after the ack envelope spread it,
+        // so neither `.results` nor `.notes` existed and search reported "No
+        // results" for documents it had just matched. Server-side both are fixed,
+        // but reading defensively costs nothing and keeps an older worker working.
+        const notes = normalizeRows(result, ['results', 'notes', 'items']);
+        if (notes.length === 0) {
+            console.log(`  No results for "${query}".`);
+            return;
+        }
+        console.log('');
+        for (const n of notes) {
+            const ts = n.updatedAt ?? n.updated_at;
+            const date = ts ? new Date(ts).toISOString().slice(0, 10) : '';
+            /**
+             * ⚠ THE KEY IS PRINTED SO A HIT CAN BE ACTED ON (CBH2-29). `search` used to print a title
+             * and a date, and a title is not an address — two notes can share one, so chaining into
+             * `cat` / `open` needed a second lookup the caller had no obvious way to perform. `CLR-42`
+             * is what `cat ~/CLR-42.md`, `document-get` and the agent in chat all accept.
+             * ⚠ An older worker returns no `key`; the column then simply does not print, rather than
+             * showing `undefined` beside every row.
+             */
+            const key = typeof n.key === 'string' && n.key ? `\x1b[90m${n.key}\x1b[0m  ` : '';
+            console.log(`  ${key}\x1b[36m${n.title || n.id}\x1b[0m  \x1b[90m${date}\x1b[0m`);
+            const preview = n.preview || n.snippet || n.matchSnippet;
+            if (preview)
+                console.log(`    ${String(preview).replace(/<\/?b>/g, '').slice(0, 120)}`);
+        }
+        console.log(`\n  ${notes.length} result${notes.length === 1 ? '' : 's'}${notes.length >= bound.limit ? ` (limit ${bound.limit} — raise it with --limit N)` : ''}\n`);
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+export async function cmdAsk(question, values) {
+    // `ask` is the one-shot face of the agent chat. On HOME it drives the SAME
+    // `agent:message` entrypoint the web FAB/canvas uses — fire it over the relay
+    // (CLI → daemon → DO) and collect the streamed `agent:*` events back, exactly
+    // like a web client. On a BUILDING (Shopify store, etc.) it falls back to that
+    // building's request/response chat action, since those live on a different DO.
+    if (values.building && values.building !== 'home') {
+        return askViaBuildingRpc(question, values);
+    }
+    return askViaAgentMessage(question, values);
+}
+/**
+ * HOME `ask` — drive the unified `agent:message` entrypoint and collect the
+ * streamed reply. This is the literal same entrypoint the browser uses; the only
+ * difference is transport (daemon relay vs. the web socket). Flow:
+ *   client.send({type:'send', msg:{type:'agent:message', …}})   ← fire-and-forget
+ *      → daemon ipc.on('send') → relay.wsSend → DO agent:message handler
+ *      → DO _runAgentChat → broadcastToWeb({type:'agent:text'|'agent:done'|…})
+ *      → reaches the daemon session → ipc.broadcast → here via on('broadcast').
+ * Correlation is by `sessionId` carried in the message body (broadcasts are not
+ * requestId-correlated), so we filter on the id we minted.
+ */
+async function askViaAgentMessage(question, values) {
+    const { randomUUID } = await import('node:crypto');
+    // --composition <id> targets a specific composition OR thread (the reply lands
+    // in THAT conversation). Reuse it as the sessionId so the turn resolves to that
+    // row and continues there — switch threads by passing a different id. Bare ask
+    // → a fresh uuid (a new chat composition).
+    const target = typeof values.composition === 'string' && values.composition.trim()
+        ? values.composition.trim()
+        : '';
+    const sessionId = target || randomUUID();
+    // --model is an OPTIONAL explicit override; omit it by default. The model is
+    // an attribute of the agent IDENTITY — a bare `ask` (no --model) carries no
+    // model field, so the DO resolves it from --agent's identity or the workspace
+    // default 'omni' agent (which is the Gemini responder), rather than the CLI
+    // hardcoding a model. Pass --model only to force a specific brain.
+    const model = typeof values.model === 'string' && values.model.trim() ? values.model.trim() : '';
+    // --agent <id|slug> targets a specific RESPONDER agent (one created in the
+    // AgentsModal). The DO's _resolveResponder turns it into that agent's OWN
+    // configured model + persona + systemPrompt, which win over --model. This
+    // mirrors what the web FAB/canvas sends (agent:message.agentId); without it
+    // the turn only honors the generic --model pick (responder=null).
+    const agentId = typeof values.agent === 'string' && values.agent.trim() ? values.agent.trim() : '';
+    const timeout = Math.max(getTimeout(values), 120_000);
+    let client;
+    try {
+        client = await connectClient({ timeout });
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        console.error('  Is the daemon running? Open the Hive Mac app, or run: beehaven status');
+        process.exit(1);
+    }
+    let answer;
+    try {
+        answer = await new Promise((resolve, reject) => {
+            let acc = '';
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                fn();
+            };
+            let timer = setTimeout(() => finish(() => reject(new Error(`No agent response after ${Math.round(timeout / 1000)}s`))), timeout);
+            /**
+             * ⚠⚠ A STREAM THAT NEVER STARTS MUST FAIL FAST — otherwise the fallback below costs the
+             * WHOLE timeout before it runs. Measured: with the fallback but no first-frame deadline,
+             * `ask` answered correctly and took **181 seconds** to do it, because it sat out the full
+             * 180s broadcast wait first. The answer was already available in one.
+             *
+             * ⚠ A STARTED STREAM KEEPS THE FULL BUDGET. The deadline is armed only until the FIRST
+             * `agent:*` frame; once the DO is talking, a long tool-heavy turn must not be cut off. That
+             * is why this re-arms `timer` rather than adding a second competing one.
+             */
+            const FIRST_FRAME_MS = 20_000;
+            let started = false;
+            const noteFirstFrame = () => {
+                if (started)
+                    return;
+                started = true;
+                clearTimeout(timer);
+                timer = setTimeout(() => finish(() => reject(new Error(`No agent response after ${Math.round(timeout / 1000)}s`))), timeout);
+            };
+            clearTimeout(timer);
+            timer = setTimeout(() => finish(() => reject(new Error(`the agent stream never opened (${FIRST_FRAME_MS / 1000}s)`))), FIRST_FRAME_MS);
+            // Subscribe + listen BEFORE sending so we never miss the first event.
+            // `error` is included so a gate rejection (e.g. a worker not yet redeployed
+            // with the agent:message daemon allowance) fails fast instead of hanging.
+            client.subscribe(['agent:*', 'error']);
+            client.on('broadcast', (msg) => {
+                if (!msg)
+                    return;
+                // Gate rejection comes back as a type:'error' frame with no sessionId.
+                if (msg.type === 'error' &&
+                    /unauthorized message type|daemon_unauthorized|unknown action/i.test(String(msg.message ?? ''))) {
+                    finish(() => reject(new Error(String(msg.message))));
+                    return;
+                }
+                if (msg.sessionId !== sessionId)
+                    return; // not our turn
+                /**
+                 * ⚠⚠ AFTER THE SESSION FILTER, NOT BEFORE. The subscription is `agent:*` — every turn in
+                 * the workspace arrives here, including other clients' — so counting ANY frame as "our
+                 * stream opened" re-armed the full 180s budget off somebody else's traffic. Measured: the
+                 * deadline never fired and `ask` still took 182s.
+                 */
+                noteFirstFrame();
+                switch (msg.type) {
+                    case 'agent:text':
+                        // The server loop emits the full text once with done:true; keep the
+                        // latest so we have a fallback if agent:done carries no finalText.
+                        if (typeof msg.text === 'string')
+                            acc = msg.text;
+                        break;
+                    case 'agent:done':
+                        finish(() => resolve(typeof msg.finalText === 'string' && msg.finalText ? msg.finalText : acc));
+                        break;
+                    case 'agent:error':
+                        finish(() => reject(new Error(msg.errorMessage || msg.error || 'agent error')));
+                        break;
+                }
+            });
+            client.on('close', () => finish(() => reject(new Error('Daemon connection lost'))));
+            client.send({
+                type: 'send',
+                msg: {
+                    type: 'agent:message',
+                    prompt: question,
+                    ...(model ? { model } : {}), // omitted unless --model — identity drives it
+                    sessionId,
+                    ...(target ? { compositionId: target } : {}),
+                    ...(agentId ? { agentId } : {}),
+                    source: 'cli-ask',
+                },
+            });
+            process.stderr.write('\x1b[2m  …thinking\x1b[0m\n');
+        });
+    }
+    catch (err) {
+        try {
+            client.disconnect();
+        }
+        catch { }
+        /**
+         * ⚠⚠ THE BROADCAST PATH CANNOT SERVE A HEADLESS CALLER, AND `agent-prompt` SAYS SO IN ITS OWN
+         * RESULT: *"Pass wait:true to await the turn and get the reply inline — REQUIRED for a headless
+         * caller, whose connection would otherwise close and let the DO hibernate mid-turn."*
+         *
+         * MEASURED 2026-09-04: `beehaven ask "Reply with the single word OK"` printed `…thinking` and
+         * then **"No agent response after 180s"**, three times. The same question through
+         * `agent-prompt { wait: true }` answered `"reply": "OK"` in ONE SECOND. The turn was never the
+         * problem — the CLI was listening on a socket the DO had stopped talking to.
+         *
+         * ⚠ THE STREAM IS TRIED FIRST AND KEPT. When a live socket DOES stay up (the Mac app is
+         * driving the same session) the broadcast gives incremental text, which is the nicer surface.
+         * This is a FALLBACK on the failure, not a replacement — so nothing that works today changes.
+         *
+         * ⚠ ONE BILLED TURN, NOT TWO. It only runs when the stream produced NOTHING; a turn that
+         * answered and then failed to close would not reach here, because `finish()` resolves on the
+         * first `agent:done`.
+         */
+        try {
+            const res = await rpcOnce('agent-prompt', {
+                message: question, wait: true, sessionId,
+                ...(target ? { compositionId: target } : {}),
+                ...(agentId ? { agentId } : {}),
+                ...(model ? { model } : {}),
+            }, timeout);
+            const inline = String(res?.reply ?? res?.text ?? '').trim();
+            if (inline) {
+                if (values.json) {
+                    console.log(JSON.stringify({ response: inline, sessionId }, null, 2));
+                    return;
+                }
+                console.log('');
+                console.log(inline);
+                console.log('');
+                return;
+            }
+            const failure = rpcFailure(res);
+            console.error(`  Error: ${failure ?? err.message}`);
+        }
+        catch (e2) {
+            console.error(`  Error: ${err.message}`);
+            if (e2?.message && e2.message !== err.message)
+                console.error(`  (fallback also failed: ${e2.message})`);
+        }
+        process.exit(1);
+    }
+    try {
+        client.disconnect();
+    }
+    catch { }
+    if (values.json) {
+        console.log(JSON.stringify({ response: answer, sessionId }, null, 2));
+        return;
+    }
+    console.log('');
+    console.log(answer);
+    console.log('');
+}
+/**
+ * BUILDING `ask` — request/response chat against a non-home DO (Shopify store,
+ * etc.). Tries that building's known chat action names in order; the first one
+ * that isn't "Unknown action" wins.
+ */
+async function askViaBuildingRpc(question, values) {
+    const chatActions = ['chat-message', 'chat', 'agent-chat', 'ask'];
+    const timeout = Math.max(getTimeout(values), 60_000);
+    for (const chatAction of chatActions) {
+        try {
+            const resolved = resolveBuilding(chatAction, { message: question }, values.building);
+            const raw = await rpcOnce(resolved.action, resolved.input, timeout);
+            // Unwrap proxy envelope
+            const result = raw?.type === 'ack' && raw?.result !== undefined
+                ? raw.result
+                : raw?.result !== undefined && values.building
+                    ? raw.result
+                    : raw;
+            // If the action doesn't exist, try the next one
+            if (raw?.type === 'error' && raw?.message?.includes('Unknown action'))
+                continue;
+            if (raw?.type === 'error') {
+                console.error(`  Error: ${raw.message ?? 'Action failed'}`);
+                process.exit(1);
+            }
+            if (values.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            const response = result?.response || result?.reply || result?.text || result?.content || result?.message;
+            if (response) {
+                console.log('');
+                console.log(response);
+                console.log('');
+            }
+            else
+                console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        catch (err) {
+            // Unknown action errors → try next. Other errors → fail.
+            if (err.message?.includes('Unknown action'))
+                continue;
+            console.error(`  Error: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    console.error('  This building does not have a chat action.');
+    console.error('  Available action names tried: ' + chatActions.join(', '));
+    process.exit(1);
+}
+export async function cmdTask(title, values) {
+    try {
+        const result = await rpcOnce('note-create', {
+            title,
+            fileType: 'board',
+            status: values.status || 'active',
+            source: 'beehaven-cli',
+        }, getTimeout(values));
+        if (values.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        /**
+         * ⚠⚠ A REFUSAL MUST NOT PRINT "Created task" (CBH2-4). `rpcOnce` resolves for an ordinary
+         * `{ ok:false, error }` payload — the transport succeeded — so without this an invalid status
+         * would be announced as a successful create, which is the same lie in a new place.
+         */
+        if (result && result.ok === false) {
+            console.error(`  Error: ${result.error ?? 'note-create refused the task'}`);
+            process.exit(1);
+        }
+        /**
+         * ⚠⚠ PRINT WHAT THE SERVER STORED, NEVER WHAT WE ASKED FOR (CBH2-4).
+         *
+         * This line was `${values.status || 'active'}` — the CLI's own argument, echoed back — while
+         * `note-create` hardcoded `'active'` on the row. So `--status shipped` printed
+         * *"Created task: … (shipped)"* over a row storing `active`, and `--status wibble` printed
+         * *(wibble)* over the same. **The receipt confirmed a write that had not happened**, which is
+         * the one shape of this bug a caller cannot detect from the terminal.
+         *
+         * ⚠ FALL BACK ONLY TO `'active'` — the server's own default — never to `values.status`. An
+         * older worker returns no `status` field, and re-echoing the request there would quietly
+         * restore the exact defect for anyone who had not upgraded.
+         */
+        const stored = typeof result?.status === 'string' && result.status
+            ? result.status
+            : 'active';
+        console.log(`  Created task: ${title} (${stored})`);
+        if (result.id)
+            console.log(`  ID: ${result.id}`);
+        else if (result.noteId)
+            console.log(`  ID: ${result.noteId}`);
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven doc add <file> — local file → searchable project document ───
+//
+// One-shot: reads a local file, mints a note (note-create) + seeds its body
+// (note-content-seed). Content lands in the workspace SQLite note-content
+// table + FTS5 index, so `search-notes` and the cloud agent can retrieve it.
+// This is the DOCUMENT path; `teleport` is the raw-blob (R2) path. Markdown is
+// stored verbatim; code is wrapped in a fenced block (with the language) so it
+// renders and stays full-text searchable.
+const DOC_LANG_BY_EXT = {
+    ts: 'ts',
+    tsx: 'tsx',
+    js: 'js',
+    jsx: 'jsx',
+    py: 'python',
+    rs: 'rust',
+    go: 'go',
+    java: 'java',
+    rb: 'ruby',
+    sh: 'bash',
+    json: 'json',
+    yaml: 'yaml',
+    yml: 'yaml',
+    toml: 'toml',
+    sql: 'sql',
+    css: 'css',
+    html: 'html',
+    c: 'c',
+    cpp: 'cpp',
+    h: 'c',
+    swift: 'swift',
+    kt: 'kotlin',
+    php: 'php',
+};
+const DOC_MAX_BYTES = 1024 * 1024; // 1MB single-document guideline
+export async function cmdDocAdd(filePath, values) {
+    if (!filePath) {
+        console.error('  Usage: beehaven doc add <file> [--project <id>] [--title <t>]');
+        process.exit(1);
+    }
+    const { readFileSync, statSync } = await import('fs');
+    const { basename, extname, resolve } = await import('path');
+    const abs = resolve(filePath);
+    let stat;
+    try {
+        stat = statSync(abs);
+    }
+    catch {
+        console.error(`  File not found: ${abs}`);
+        process.exit(1);
+    }
+    if (stat.size > DOC_MAX_BYTES) {
+        console.error(`  ${basename(abs)} is ${(stat.size / 1024).toFixed(0)}KB — over the ${DOC_MAX_BYTES / 1024}KB single-document guideline.`);
+        console.error('  Large/whole-folder content belongs in the doc-indexer (chunked, agent memory) or in R2 via `beehaven teleport`.');
+        process.exit(1);
+    }
+    const raw = readFileSync(abs, 'utf8');
+    const fileName = basename(abs);
+    const ext = extname(fileName).slice(1).toLowerCase();
+    const isMarkdown = ext === 'md' || ext === 'markdown' || ext === 'txt' || ext === '';
+    const lang = DOC_LANG_BY_EXT[ext];
+    const data = isMarkdown ? raw : '```' + (lang || ext || '') + '\n' + raw + '\n```\n';
+    const title = values.title ||
+        (isMarkdown ? raw.match(/^#\s+(.+)$/m)?.[1]?.trim() || fileName : fileName);
+    try {
+        const created = await rpcOnce('note-create', {
+            noteData: { projectId: values.project || undefined, title },
+            fileType: 'document',
+        }, getTimeout(values));
+        const noteId = created?.noteId || created?.id;
+        if (!noteId) {
+            console.error(`  note-create failed: ${JSON.stringify(created)}`);
+            process.exit(1);
+        }
+        await rpcOnce('note-content-seed', { noteId, data, title }, getTimeout(values));
+        if (values.json) {
+            console.log(JSON.stringify({
+                noteId,
+                title,
+                fileName,
+                project: values.project || null,
+                bytes: data.length,
+                kind: isMarkdown ? 'markdown' : 'code',
+            }, null, 2));
+            return;
+        }
+        console.log(`  Added ${isMarkdown ? 'document' : 'code document'}: ${title}`);
+        console.log(`  noteId: ${noteId}${values.project ? `   project: ${values.project}` : ''}`);
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven teleport <file> ─────────────────────────────────────────────
+/**
+ * Threshold above which we switch from inline base64 upload to a direct
+ * R2 PUT via a presigned URL. The relay WebSocket has a per-message size
+ * cap (~1MB in practice); base64-encoded payloads larger than that
+ * crash the WS and take the daemon's relay connection down with them.
+ *
+ * Below threshold: one `file-teleport-inline` RPC (base64 over WS).
+ * At/above: `get-upload-url` → PUT binary to R2 → `file-uploaded` to
+ *           record the row. Binary never touches the relay WS.
+ */
+const INLINE_MAX_BYTES = 900 * 1024; // 900KB — safety margin under the WS cap
+/**
+ * Formats worth projecting into a searchable document after an upload.
+ *
+ * ⚠ KEPT IN STEP WITH `DOCUMENTABLE` IN `components/gallery/GalleryGrid.tsx` — the browser's
+ * drag-drop applies the same test, and a file dropped on the grid and the same file teleported
+ * from a terminal must end up in the same state. Images, audio, video and archives are
+ * deliberately excluded: turning a PNG into a "document" fills search with rows that have no text.
+ */
+const DOCUMENTABLE_EXT = /\.(pdf|md|markdown|txt|rtf|csv|tsv|json|ya?ml|html?|xml|tex|ts|tsx|js|jsx|py|rb|go|rs|java|kt|swift|c|h|cpp|cs|php|sql|sh|toml|ini|log)$/i;
+/**
+ * ⚠⚠ THE UPLOAD IS NOT FINISHED WHEN THE BYTES LAND — THIS IS THE STEP THAT MAKES IT FINDABLE.
+ *
+ * `document-search` is FTS5 over the note BODY, so a file that never becomes a document is an
+ * opaque blob: stored, listed in `/recents`, and invisible to every search the person or the agent
+ * will actually run. The browser's grid drop has called `document-from-file` since it was
+ * re-plumbed; `beehaven teleport` never did, on either branch. Same gesture, two outcomes.
+ *
+ * ⚠ A CONVERSION FAILURE IS NOT AN UPLOAD FAILURE. The bytes are in R2 and the `files` row exists;
+ * only the searchable projection is missing. Reporting it as a failed upload would send the caller
+ * to re-upload a file that is already there. Warn, and say what is missing.
+ *
+ * ⚠ PDFs ARE EXPECTED TO PRODUCE A STUB. The worker extracts text server-side for text-y formats
+ * but mints a viewer stub for PDF — the real extraction runs client-side in the notes editor, which
+ * an agent has no equivalent of. So a teleported PDF is stored and openable but NOT searchable, and
+ * that is a known gap (server-side PDF extraction belongs in the container), not a bug in this call.
+ */
+async function projectUploadedFileAsDocument(fileId, fileName, values) {
+    if (!fileId || !DOCUMENTABLE_EXT.test(fileName))
+        return;
+    if (values['no-document'])
+        return;
+    try {
+        const res = await rpcOnce('document-from-file', { fileId, title: fileName }, getTimeout(values));
+        const out = res?.type === 'ack' && res?.result !== undefined ? res.result : res;
+        if (out?.error) {
+            console.log(`  (stored, but not searchable: ${out.error})`);
+            return;
+        }
+        const key = out?.key ? ` ${out.key}` : '';
+        console.log(`  Indexed for search as a document${key}`);
+    }
+    catch (err) {
+        console.log(`  (stored, but not searchable: ${err?.message || 'document-from-file failed'})`);
+    }
+}
+/**
+ * ⚠⚠ PRINT THE FILE ID — THE FOURTH THING `beehaven help teleport` PROMISES AND THE ONLY ONE
+ * THAT DID NOT HAPPEN (CBH2-38).
+ *
+ * That page lists what teleport does: put the bytes in R2 · insert the `files` row · index it for
+ * search · **hand back the file id**. The output was a VFS path and nothing else, which broke the
+ * two-step printed verbatim in `beehaven help sheet`:
+ *
+ *     beehaven teleport ./data.csv && beehaven sheet import <fileId>
+ *
+ * — there was no `<fileId>` to substitute. Every obvious substitute is refused (`sheet import
+ * /uploads/x.csv` → "No file with id /uploads/x.csv"), so the only route was
+ * `beehaven sql "SELECT id FROM files WHERE name LIKE …"` — dropping out of the CLI surface
+ * entirely, to the escape hatch `beehaven --help` calls *"the ESCAPE HATCH, not the workflow"*.
+ *
+ * ⚠ ONE HELPER, BOTH UPLOAD PATHS. The inline and presigned branches print their own success line
+ * and the id was available in both; a fix in one is a fix for small files only, and which branch
+ * runs depends on a size threshold the caller never sees.
+ *
+ * ⚠⚠ THE `next:` LINE IS ONLY PRINTED FOR A FILE `sheet import` CAN ACTUALLY TAKE. Suggesting it
+ * after teleporting a PNG would be a second broken two-step — this whole ticket is about a
+ * documented chain that does not complete, and answering it with another one that does not
+ * complete is worse than printing the id alone. `beehaven open <fileId>` is deliberately NOT
+ * suggested either: `open` has no route for a file (see `pathForKind`), so it would refuse.
+ *
+ * ⚠ SILENT WHEN THERE IS NO ID — a composition asset has no `files` row, and a server that
+ * returned none must not be papered over with `undefined`.
+ */
+const SHEET_IMPORTABLE = /\.(csv|tsv)$/i;
+function printTeleportedFileId(fileId, compositionId, fileName) {
+    const id = typeof fileId === 'string' ? fileId.trim() : '';
+    if (!id)
+        return;
+    console.log(`    id: ${id}`);
+    if (!compositionId && fileName && SHEET_IMPORTABLE.test(fileName)) {
+        console.log(`    next: beehaven sheet import ${id} --title "${fileName.replace(/\.[^.]+$/, '')}"`);
+    }
+}
+export async function cmdTeleport(filePath, values) {
+    const { readFileSync, statSync } = await import('fs');
+    const { basename, extname, resolve } = await import('path');
+    const absPath = resolve(filePath);
+    try {
+        statSync(absPath);
+    }
+    catch {
+        console.error(`  File not found: ${absPath}`);
+        process.exit(1);
+    }
+    const fileName = basename(absPath);
+    const ext = extname(fileName).slice(1).toLowerCase();
+    const mimeMap = {
+        txt: 'text/plain',
+        md: 'text/markdown',
+        json: 'application/json',
+        js: 'text/javascript',
+        ts: 'text/typescript',
+        html: 'text/html',
+        css: 'text/css',
+        csv: 'text/csv',
+        xml: 'application/xml',
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        svg: 'image/svg+xml',
+        webp: 'image/webp',
+        mp3: 'audio/mpeg',
+        mp4: 'video/mp4',
+        wav: 'audio/wav',
+        pdf: 'application/pdf',
+        zip: 'application/zip',
+        // Mobile builds — when teleported onto a composition these go
+        // through the mobile-install block path (see wantMobileInstall
+        // branch below) instead of the generic file upload.
+        ipa: 'application/octet-stream', // Apple iOS app archive
+        apk: 'application/vnd.android.package-archive', // Android package
+        aab: 'application/octet-stream', // Android App Bundle — rejected by finalize
+    };
+    const contentType = mimeMap[ext] || 'application/octet-stream';
+    // `--composition <id>` mode: store the file under the composition's R2
+    // prefix and register it with FileManager instead of the app-level `files`
+    // table. Two effects:
+    //   1. `beehaven call composition-fs '{"compositionId":"…","action":"list"}'`
+    //      can actually see its own internal files.
+    //   2. The asset no longer pollutes /recents with a workspace-level row
+    //      per file — the composition itself is the single entity.
+    // Without this flag, we keep the original behavior (workspace-level asset
+    // visible in /recents and the Files UI).
+    const compositionId = values.composition;
+    const rawTo = values.to;
+    // Path-traversal guard for the user-supplied --to flag. The server's
+    // FileManager also validates this (see packages/core/src/server/FileManager
+    // canonical actions — they reject '..' and leading '/'), but we should fail
+    // fast at the CLI so the error message names the actual flag the user
+    // typed instead of a cryptic server-side "Invalid key".
+    if (rawTo && (rawTo.includes('..') || rawTo.startsWith('/') || rawTo.includes('\0'))) {
+        console.error(`  Invalid --to path: ${rawTo}`);
+        console.error(`  The --to flag can't contain '..', absolute paths, or null bytes.`);
+        process.exit(1);
+    }
+    const destDir = compositionId
+        ? `compositions/${compositionId}${rawTo ? `/${String(rawTo).replace(/^\/|\/$/g, '')}` : ''}`
+        : rawTo || 'uploads';
+    const key = `${destDir.replace(/^\/|\/$/g, '')}/${fileName}`;
+    const content = readFileSync(absPath);
+    // Overall cap — R2 presigned PUT handles much more, but we stop here to
+    // avoid accidentally uploading gigabyte-sized files.
+    const MAX_BYTES = 100 * 1024 * 1024; // 100MB
+    if (content.length > MAX_BYTES) {
+        console.error(`  File too large for teleport (${(content.length / 1024 / 1024).toFixed(1)}MB, max ${MAX_BYTES / 1024 / 1024}MB)`);
+        process.exit(1);
+    }
+    const sizeKB = (content.length / 1024).toFixed(1);
+    // Precheck: --composition requires FileManager + composition-fs wired on
+    // the target DO. If those aren't there, the upload will eventually fail
+    // with "Unknown action: composition-fs" or a silent no-op. We surface a
+    // clear error before burning the upload instead. The precheck itself is
+    // best-effort — if `list-actions` is unavailable we proceed and let the
+    // teleport surface the real error (keeps us from hard-failing on DOs that
+    // disable action listing by design).
+    if (compositionId) {
+        let actions = [];
+        try {
+            const listRaw = await rpcOnce('list-actions', {}, getTimeout(values));
+            const list = listRaw?.type === 'ack' && listRaw?.result !== undefined ? listRaw.result : listRaw;
+            actions = list?.actions ?? [];
+        }
+        catch {
+            // list-actions RPC failed entirely — nothing to precheck against.
+            // Fall through; the teleport will surface the real error if the DO
+            // truly lacks composition-fs.
+        }
+        // Only block if we got a non-empty list that DOESN'T contain composition-fs.
+        // An empty list is ambiguous (DO may disable action listing) — don't hard-fail on it.
+        // The process.exit MUST be outside the try/catch above, or the catch would swallow it.
+        if (actions.length > 0 && !actions.some((a) => a.name === 'composition-fs')) {
+            console.error(`  This DO does not support compositions (no 'composition-fs' action registered).`);
+            console.error(`  Retry without --composition, or target a DO where FileManager + composition-fs are wired.`);
+            process.exit(1);
+        }
+    }
+    // ── Mobile-install branch: `.ipa` / `.apk` onto a composition turn
+    //    into a `mobile-install` block (icon + version + install QR).
+    //
+    //    Flow: upload binary via presigned URL → call mobile-build-finalize
+    //    with caller-supplied metadata (--bundle-id, --version, etc) →
+    //    call canvas-add-mobile-install to drop the block on the canvas.
+    //
+    //    Auto-trigger: any .ipa / .apk with --composition set. Override
+    //    with `--as attachment` to keep the generic opaque-file behaviour.
+    //
+    //    Metadata parsing TODO: today the dev supplies bundle-id/version
+    //    via flags (or accepts defaults). A future iteration should parse
+    //    Info.plist (binary plist) / AndroidManifest.xml (binary AXML)
+    //    client-side here so the metadata is auto-populated. Until then,
+    //    the block UI is editable so the dev can fill in gaps.
+    const ipaApk = ext === 'ipa' ? 'ios' : ext === 'apk' ? 'android' : null;
+    const explicitAs = String(values.as || '').toLowerCase();
+    const wantMobileInstall = !!compositionId && !!ipaApk && explicitAs !== 'attachment';
+    if (wantMobileInstall) {
+        if (ext === 'aab') {
+            // Belt-and-braces: finalize will also reject, but failing here
+            // saves the round-trip + upload bytes.
+            console.error(`  .aab can only be installed via Play Store. Upload an .apk for direct sideload.`);
+            process.exit(1);
+        }
+        // 1) Upload the binary via presigned URL (mobile builds are
+        //    always >900KB so the inline path is never used).
+        console.log(`  Uploading ${fileName} (${sizeKB}KB) → R2…`);
+        const intent = await rpcOnce('get-upload-url', {
+            key,
+            contentType,
+            maxSize: content.length,
+        }, getTimeout(values));
+        if (!intent?.uploadUrl) {
+            console.error(`  Failed to get upload URL: ${intent?.error || 'no uploadUrl in response'}`);
+            process.exit(1);
+        }
+        let uploadUrl = intent.uploadUrl;
+        if (uploadUrl.startsWith('/')) {
+            // Mirror the existing large-file path (line ~1115) — read
+            // `endpoint` (not `relayHost`!) from ~/.beehaven/config.json
+            // and translate wss:// → https://. The `endpoint` field
+            // honours `beehaven env staging` etc., which means PUTs go
+            // to the right host instead of always hitting prod.
+            const { readFileSync: rfs, existsSync: exf } = await import('fs');
+            const { join: jn } = await import('path');
+            const { homedir: hd } = await import('os');
+            let relayHost = 'https://relay.clearly.sh';
+            try {
+                const cfgPath = jn(hd(), '.beehaven', 'config.json');
+                if (exf(cfgPath)) {
+                    const cfg = JSON.parse(rfs(cfgPath, 'utf-8'));
+                    if (cfg.endpoint) {
+                        relayHost = String(cfg.endpoint)
+                            .replace(/^wss:/, 'https:')
+                            .replace(/^ws:/, 'http:')
+                            .replace(/\/$/, '');
+                    }
+                }
+            }
+            catch {
+                /* fall through with default */
+            }
+            uploadUrl = relayHost + uploadUrl;
+        }
+        const putRes = await fetch(uploadUrl, {
+            method: 'PUT',
+            body: content,
+            headers: { 'Content-Type': contentType },
+        });
+        if (!putRes.ok) {
+            const body = await putRes.text().catch(() => '');
+            console.error(`  R2 PUT failed: HTTP ${putRes.status}`);
+            console.error(`  url: ${uploadUrl.slice(0, 160)}…`);
+            console.error(`  body: ${body.slice(0, 240)}`);
+            process.exit(1);
+        }
+        // 2) Finalize: register the build row + (for iOS) generate the
+        //    install-manifest plist.
+        //
+        // Metadata sourcing — precedence: CLI flag → parsed from binary
+        // → filename-based default. The parser handles XML and binary
+        // Info.plist for iOS; for Android it currently no-ops and the
+        // dev fills metadata via flags.
+        const { parseMobileBinary } = await import('../lib/mobile-build-parser.js');
+        const parsed = parseMobileBinary(absPath);
+        if (parsed.ok === false) {
+            // Inside this branch parsed is ParseFailure — TS narrows on
+            // the discriminated union via the boolean comparison.
+            console.log(`  (couldn't auto-parse metadata: ${parsed.reason}${parsed.detail ? ' — ' + parsed.detail : ''})`);
+        }
+        const platform = ipaApk;
+        const displayName = values['display-name'] ||
+            (parsed.ok ? parsed.displayName : undefined) ||
+            fileName.replace(/\.(ipa|apk|aab)$/i, '');
+        const bundleId = values['bundle-id'] ||
+            (parsed.ok ? parsed.bundleId : undefined) ||
+            `com.unknown.${fileName
+                .replace(/[^a-z0-9]/gi, '')
+                .toLowerCase()
+                .slice(0, 16) || 'build'}`;
+        // `--app-version` is the mobile-build version string. `--version`
+        // is the global boolean (`beehaven --version`) — they DON'T collide
+        // because we read app-version explicitly here.
+        const version = values['app-version'] || (parsed.ok ? parsed.version : undefined) || '0.0.0';
+        const buildNumber = values.build || (parsed.ok ? parsed.buildNumber : undefined) || '1';
+        const minOsVersion = parsed.ok ? parsed.minOsVersion : undefined;
+        const signingMethod = values.signing || (platform === 'ios' ? 'adhoc' : 'release');
+        const udidsRaw = values.udids;
+        const adHocUdids = udidsRaw
+            ? String(udidsRaw)
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : [];
+        const finalize = await rpcOnce('mobile-build-finalize', {
+            platform,
+            binaryKey: key,
+            displayName,
+            bundleId,
+            version,
+            buildNumber,
+            ...(minOsVersion ? { minOsVersion } : {}),
+            signingMethod,
+            ...(adHocUdids.length ? { adHocUdids } : {}),
+            sizeBytes: content.length,
+        }, getTimeout(values));
+        if (!finalize?.ok) {
+            console.error(`  mobile-build-finalize failed: ${finalize?.error || finalize?.message || JSON.stringify(finalize)}`);
+            process.exit(1);
+        }
+        // 3) Add the block to the canvas.
+        const block = await rpcOnce('canvas-add-mobile-install', {
+            compositionId,
+            buildId: finalize.buildId,
+        }, getTimeout(values));
+        if (!block?.ok) {
+            console.error(`  canvas-add-mobile-install failed: ${block?.error || JSON.stringify(block)}`);
+            process.exit(1);
+        }
+        console.log(`  ${fileName} → ${platform} build ${finalize.buildId}`);
+        console.log(`    bundle: ${bundleId}  version: ${version} (${buildNumber})`);
+        console.log(`    block: ${block.blockId} on composition ${compositionId}`);
+        if (platform === 'ios' && !adHocUdids.length) {
+            console.log(`    Hint: pass --udids <UDID1,UDID2> so testers' devices appear in the block's allow-list.`);
+        }
+        // Only nudge the metadata-flags hint when we genuinely had to
+        // guess (no flag AND parser couldn't extract). Parser-derived
+        // values are real; flagging them as defaults is misleading.
+        const guessedBundleId = !values['bundle-id'] && !(parsed.ok && parsed.bundleId);
+        const guessedVersion = !values['app-version'] && !(parsed.ok && parsed.version);
+        if (guessedBundleId || guessedVersion) {
+            console.log(`    Hint: re-run with --bundle-id <id> --app-version <v> --build <n> --display-name "<name>" to pre-fill metadata (binary parse failed to extract everything).`);
+        }
+        else if (parsed.ok) {
+            console.log(`    Auto-detected metadata from the binary's Info.plist.`);
+        }
+        return;
+    }
+    // ── --as text: inline the file CONTENTS as a text block on the
+    //    composition canvas, instead of (or in addition to) storing as
+    //    an opaque R2 attachment. Closes the "I have a .md, I want it
+    //    ON my pasteboard" workflow without a separate canvas-add-text
+    //    round trip.
+    //
+    //    Auto-trigger: small text/markdown files with --composition set
+    //    default to text-block placement. Override with `--as attachment`
+    //    if the user explicitly wants the opaque-file behaviour.
+    //
+    //    Without --composition the flag is a no-op (we need a target
+    //    canvas; the workspace VFS path doesn't have a canvas concept).
+    const isText = contentType.startsWith('text/') ||
+        contentType === 'application/json' ||
+        contentType === 'application/xml';
+    // `explicitAs` is declared earlier (above the wantMobileInstall branch).
+    const wantTextBlock = compositionId &&
+        (explicitAs === 'text' ||
+            (explicitAs !== 'attachment' && isText && content.length <= 256 * 1024));
+    if (wantTextBlock) {
+        const text = content.toString('utf-8');
+        const lines = text.split(/\r?\n/).length;
+        // Heuristic placement: leave a comfortable margin from the origin
+        // so the block doesn't land under the chrome. Sized for ~80ch.
+        const x = 80, y = 80;
+        const width = 720;
+        const height = Math.max(120, Math.min(2400, lines * 22 + 60));
+        try {
+            const res = await rpcOnce('canvas-add-text', {
+                compositionId,
+                text,
+                x,
+                y,
+                width,
+                height,
+                // Pass through filename + mime so the block knows where it
+                // came from — useful for "open externally" + future "convert
+                // back to file" affordances. The server-side canvas-add-text
+                // already merges extras into block.data.
+                source: 'teleport',
+                sourceFilename: fileName,
+                sourceMime: contentType,
+            }, getTimeout(values));
+            if (res?.error) {
+                console.error(`  canvas-add-text failed: ${res.error}`);
+                process.exit(1);
+            }
+            const blockId = res?.blockId ?? res?.result?.blockId ?? res?.id ?? '(unknown)';
+            console.log(`  ${fileName} → text block ${blockId} on composition ${compositionId} (${lines} lines, ${sizeKB}KB)`);
+            if (explicitAs !== 'text') {
+                console.log(`  Hint: re-run with --as attachment to also store as an opaque file under the composition's R2 prefix.`);
+            }
+            return;
+        }
+        catch (err) {
+            console.error(`  Failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    console.log(`  Teleporting ${fileName} (${sizeKB}KB) → /${key}`);
+    try {
+        if (content.length <= INLINE_MAX_BYTES) {
+            // ── Small file: inline base64 over the relay WS ──────────────────
+            const b64 = content.toString('base64');
+            const result = await rpcOnce('file-teleport-inline', {
+                key,
+                name: fileName,
+                mimeType: contentType,
+                size: content.length,
+                data: b64,
+                composition: !!compositionId,
+            }, getTimeout(values));
+            if (result?.error) {
+                console.error(`  Failed: ${result.error}`);
+                process.exit(1);
+            }
+            // ⚠ `file-teleport-inline` MAY come back wrapped in an ack envelope, exactly like the
+            //   large-file path below already unwraps. Reading `result.id` raw is how the id goes
+            //   missing on one door and not the other.
+            const inlineRec = result?.type === 'ack' && result?.result !== undefined ? result.result : result;
+            console.log(`  ${fileName} → /${key}${compositionId ? '  (composition)' : ''}`);
+            printTeleportedFileId(inlineRec?.id, compositionId, fileName);
+            // A composition asset is deliberately NOT projected: it belongs to the composition's own
+            // fs surface and has no `files` row to hang a document off.
+            if (!compositionId)
+                await projectUploadedFileAsDocument(inlineRec?.id, fileName, values);
+            return;
+        }
+        // ── Large file: presigned URL → direct PUT → notify ───────────────
+        const intent = await rpcOnce('get-upload-url', {
+            key,
+            contentType,
+            maxSize: content.length,
+        }, getTimeout(values));
+        if (!intent?.uploadUrl) {
+            console.error(`  Failed to get upload URL: ${intent?.error || 'no uploadUrl in response'}`);
+            process.exit(1);
+        }
+        // Server's FileManager returns a relative path when `domain` isn't
+        // configured — absolute-ize it here using the daemon's relay host.
+        // The relay Worker handles PUT /f/upload/* and forwards to the DO.
+        let uploadUrl = intent.uploadUrl;
+        if (uploadUrl.startsWith('/')) {
+            const { readFileSync, existsSync } = await import('fs');
+            const { join } = await import('path');
+            const { homedir } = await import('os');
+            let relayHost = 'https://relay.clearly.sh';
+            try {
+                const cfgPath = join(homedir(), '.beehaven', 'config.json');
+                if (existsSync(cfgPath)) {
+                    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+                    if (cfg.endpoint) {
+                        relayHost = String(cfg.endpoint)
+                            .replace(/^wss:/, 'https:')
+                            .replace(/^ws:/, 'http:')
+                            .replace(/\/$/, '');
+                    }
+                }
+            }
+            catch {
+                /* fall back to default */
+            }
+            uploadUrl = relayHost + uploadUrl;
+        }
+        const putRes = await fetch(uploadUrl, {
+            method: 'PUT',
+            headers: { 'Content-Type': contentType },
+            body: content,
+        });
+        if (!putRes.ok) {
+            console.error(`  Upload PUT failed: ${putRes.status} ${await putRes.text().catch(() => '')}`);
+            process.exit(1);
+        }
+        const recorded = await rpcOnce('file-uploaded', {
+            key,
+            name: fileName,
+            // ⚠ `mimeType`, NOT `mime` — this sent `mime` and the handler reads `mimeType`, so every
+            // file over the inline threshold landed with a NULL `mime_type`: a generic icon in the
+            // gallery and `application/octet-stream` on download, with nothing reporting a problem.
+            // The handler now accepts both spellings; this sends the canonical one.
+            mimeType: contentType,
+            size: content.length,
+            composition: !!compositionId,
+        }, getTimeout(values));
+        if (recorded?.error) {
+            console.error(`  Uploaded to R2 but failed to record file row: ${recorded.error}`);
+            process.exit(1);
+        }
+        console.log(`  ${fileName} → /${key}  (direct R2 upload, ${sizeKB}KB${compositionId ? ', composition' : ''})`);
+        const rec = recorded?.type === 'ack' && recorded?.result !== undefined ? recorded.result : recorded;
+        printTeleportedFileId(rec?.id, compositionId, fileName);
+        if (!compositionId) {
+            await projectUploadedFileAsDocument(rec?.id, fileName, values);
+        }
+    }
+    catch (err) {
+        console.error(`  Failed: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven context — refresh .clearly/CLAUDE.md ────────────────────────
+export async function cmdContext(values) {
+    const { getLinkedFolders } = await import('../folder-sync.js');
+    const { ClearlySync } = await import('../clearly-sync.js');
+    const cwd = process.cwd();
+    const linked = getLinkedFolders();
+    const entry = linked[cwd];
+    if (!entry) {
+        console.error('  This folder is not linked to a Clearly project.');
+        console.error('  Run "beehaven link" to connect it.');
+        process.exit(1);
+    }
+    const sync = new ClearlySync({
+        projectPath: cwd,
+        projectId: entry.brandId,
+        callAction: (action, input) => rpcOnce(action, input, getTimeout(values)),
+    });
+    try {
+        await sync.pull();
+        console.log('  Context written to .clearly/CLAUDE.md');
+        console.log('  Tasks: .clearly/tasks.yaml');
+        console.log('  Memories: .clearly/memories.yaml');
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven broadcast '{json}' — admin broadcast ────────────────────────
+export async function cmdBroadcast(rawMsg, values) {
+    try {
+        const msg = JSON.parse(rawMsg);
+        const result = await rpcOnce('admin:broadcast', { message: msg }, getTimeout(values));
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven agent "<message>" — one-shot prompt to Omni ─────────────────
+/**
+ * ⚠ THE ACTION IS `agent-prompt`, NOT `admin:agent-prompt`.
+ *
+ * This dispatched `admin:agent-prompt` for its whole life, and no such action is
+ * mounted on the workspace — every invocation of the documented verb answered
+ *
+ *     Unknown message type: admin:agent-prompt. Did you mean: admin:sql …
+ *
+ * so `beehaven agent "<msg>"`, advertised in `--help` as "One-shot prompt to the
+ * cloud agent", has never once reached an agent. The working action is
+ * `agent-prompt` — which is what the avatar hive's own `/omni` route has been
+ * calling all along (`Avatar.ts` `replyWithOmni`), which is why Omni was
+ * reachable from the desktop companion and not from the terminal.
+ *
+ * The payload matters as much as the name: `agentId: 'omni'` selects the
+ * orchestrator, and `wait: true` is what makes this a one-shot rather than a
+ * fire-and-forget that prints an ack and exits before the reply exists.
+ */
+export async function cmdAgent(prompt, values) {
+    try {
+        const result = await rpcOnce('agent-prompt', {
+            message: prompt,
+            agentId: 'omni',
+            wait: true,
+            // ⚠ NOT `cwd`. The old call passed the shell's working directory, which
+            // the action does not accept — a local path is meaningless to a cloud
+            // orchestrator, and sending it only ever added a field to be ignored.
+            // Continuity comes from `conversationId`, which the caller may thread
+            // through to keep one thread across invocations.
+            ...(typeof values?.conversation === 'string' && values.conversation
+                ? { conversationId: values.conversation }
+                : {}),
+        }, 
+        // Omni runs tools; the CLI default is far too short for a real turn.
+        getTimeout(values) || 180_000);
+        /**
+         * 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
+         * the answer" should not make you pick the answer out of a JSON blob.
+         */
+        if (values?.json || !result?.reply) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(result.reply);
+        if (result.conversationId || result.compositionId) {
+            console.error(`\n  conversation: ${result.conversationId ?? result.compositionId}` +
+                `  (pass --conversation <id> to continue it)`);
+        }
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── beehaven store-query <storeId> "<SQL>" ───────────────────────────────
+export async function cmdStoreQuery(storeId, sql, values) {
+    try {
+        const result = await rpcOnce('admin:store-query', { storeId, sql }, getTimeout(values));
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── BEEHAVEN.md generation ───────────────────────────────────────────────
+/**
+ * Generate BEEHAVEN.md at the project root.
+ * Pulls the workspace manifest from the cloud DO via daemon IPC,
+ * formats it as a Claude-readable reference document.
+ */
+export async function generateBeehavenMd(projectDir) {
+    const { writeFileSync, existsSync, mkdirSync } = await import('fs');
+    const { join } = await import('path');
+    // Pull workspace info + actions from cloud DO
+    const [wsInfo, actionsResult] = await Promise.all([
+        rpcOnce('workspace-info', {}, 10_000),
+        rpcOnce('list-actions', { format: 'full' }, 10_000),
+    ]);
+    const actions = actionsResult.actions || [];
+    const tables = wsInfo.tables || {};
+    // Group actions by category
+    const grouped = new Map();
+    for (const a of actions) {
+        if (a.name.startsWith('bh:') || a.name.startsWith('_admin'))
+            continue;
+        const cat = a.category || 'other';
+        if (!grouped.has(cat))
+            grouped.set(cat, []);
+        grouped.get(cat).push(a);
+    }
+    // Curated actions Claude would actually use in a dev project
+    const CURATED_ACTIONS = new Set([
+        // Context & Memory
+        'remember',
+        'recall',
+        'forget',
+        'project-context',
+        // Notes & Search
+        'note-create',
+        'note-update',
+        'note-delete',
+        'search-notes',
+        'browse-notes',
+        // Tasks
+        'note-list',
+        // Files
+        'teleport',
+        'file-teleport-inline',
+        'get-upload-url',
+        'browse-vfs',
+        // Agent
+        'chat',
+        'get-tools',
+        // Communications
+        'send-sms',
+        'send-email',
+        // System
+        'health-check',
+        'list-actions',
+        'describe-action',
+        'workspace-info',
+        // Projects
+        'create-project',
+        'project-update',
+        'project-notes-list',
+        'project-notes-write',
+        // Teams
+        'team-create',
+        // Versioning
+        'undo',
+        'redo',
+        'snapshot-create',
+        'snapshot-list',
+    ]);
+    const curatedActions = actions.filter((a) => CURATED_ACTIONS.has(a.name));
+    // Build markdown
+    let md = `# BEEHAVEN.md
+
+This file describes the Beehaven workspace connected to this project.
+Claude Code can use \`beehaven\` CLI commands to interact with the workspace.
+
+## Commands
+
+\`\`\`bash
+beehaven remember <key> <value>               # Store memory across sessions
+beehaven recall [query]                       # Retrieve memories
+beehaven search "<query>"                     # Search notes
+beehaven call note-create '{"title":"...","content":"...","fileType":"note"}'
+beehaven task "<title>"                       # Create a task (board item)
+beehaven teleport <file>                      # Upload file to R2 storage
+beehaven ask "<question>"                     # Chat with cloud agent
+beehaven call send-email '{"to":"...","subject":"...","body":"..."}'
+beehaven call send-sms '{"to":"+1...","body":"..."}'
+beehaven workspace                            # Overview: tables, actions, agent
+beehaven actions                              # Full list of all ${actions.length} actions
+beehaven call <action> '{"key":"value"}'      # Call any action
+beehaven call --building team:<id> <action>   # Target a specific building
+\`\`\`
+
+## Key Actions
+
+| Action | Description |
+|--------|-------------|
+`;
+    for (const a of curatedActions) {
+        md += `| \`${a.name}\` | ${a.description || ''} |\n`;
+    }
+    md += `
+## Tables
+
+| Table | Rows | Key Columns |
+|-------|------|-------------|
+`;
+    for (const [name, info] of Object.entries(tables)) {
+        const t = info;
+        md += `| ${name} | ${t.count} | ${t.columns.slice(0, 5).join(', ')}${t.columns.length > 5 ? '...' : ''} |\n`;
+    }
+    md += `
+## Buildings
+
+- **home** — Personal workspace (default target for all commands)
+- **team:\<id\>** — Shared team workspace: \`beehaven call --building team:abc note-create '{}'\`
+- **store:\<id\>** — Shopify store workspace: \`beehaven call --building store:xyz search-products '{}'\`
+
+## Creating Notes
+
+\`\`\`bash
+# Create via CLI
+beehaven call note-create '{"title":"Sprint Plan","content":"## Goals\\n...","fileType":"note"}'
+
+# Write .md files to .clearly/notes/ — they sync automatically
+echo "# Sprint Plan" > .clearly/notes/sprint-plan.md
+
+# Upload files to R2 storage
+beehaven teleport report.pdf
+\`\`\`
+
+## All Actions (${actions.length} total)
+
+Run \`beehaven actions\` to see the full categorized list, or \`beehaven actions --format tool-use --json\` for tool schemas.
+
+`;
+    // Compact full list grouped by category
+    for (const [category, catActions] of grouped) {
+        const label = category.charAt(0).toUpperCase() + category.slice(1);
+        const names = catActions.map((a) => `\`${a.name}\``).join(', ');
+        md += `**${label}:** ${names}\n\n`;
+    }
+    // Write BEEHAVEN.md
+    writeFileSync(join(projectDir, 'BEEHAVEN.md'), md);
+    console.log('  Generated BEEHAVEN.md');
+    // Create .clearly/ directory structure
+    const clearlyDir = join(projectDir, '.clearly');
+    if (!existsSync(clearlyDir))
+        mkdirSync(clearlyDir, { recursive: true });
+    const notesDir = join(clearlyDir, 'notes');
+    if (!existsSync(notesDir))
+        mkdirSync(notesDir, { recursive: true });
+    // Write .clearly/CLAUDE.md (subset of BEEHAVEN.md — context for Claude)
+    const claudeMd = `# Clearly Workspace Context
+
+This project is linked to a Clearly workspace via Beehaven.
+
+## Available Commands
+- \`beehaven actions\` — list workspace actions
+- \`beehaven call <action> '{}'\` — call any action
+- \`beehaven search "<query>"\` — search notes
+- \`beehaven remember <key> <value>\` — store memory
+- \`beehaven teleport <file>\` — upload file
+- \`beehaven task "<title>"\` — create task
+
+## Creating Notes
+Write .md files to this directory's notes/ subfolder. They sync automatically.
+
+See BEEHAVEN.md in the project root for full documentation.
+`;
+    writeFileSync(join(clearlyDir, 'CLAUDE.md'), claudeMd);
+    console.log('  Generated .clearly/CLAUDE.md');
+}
+// ── actions.search — fuzzy match an intent string to action names ───────
+/**
+ * Client-side fuzzy search over the action list, so `actions.search`
+ * works on any DO that implements `list-actions` — no server handler
+ * needed. Ranks by:
+ *   1. exact match on name (weight 100)
+ *   2. exact match on alias (weight 80)
+ *   3. substring match in name (weight 40)
+ *   4. substring match in description (weight 20)
+ *   5. substring match in category (weight 10)
+ *
+ * Returns up to `limit` (default 10) top matches, each with {name,
+ * score, matchedOn} so agents can see WHY the match hit.
+ */
+export async function actionsSearch(client, params) {
+    const q = String(params.query ?? params.q ?? '')
+        .toLowerCase()
+        .trim();
+    if (!q)
+        return { query: q, matches: [] };
+    const limit = Math.max(1, Math.min(50, params.limit ?? 10));
+    const raw = await client.call('list-actions', { format: 'full' });
+    const list = Array.isArray(raw) ? raw : (raw?.actions ?? []);
+    const queryTokens = q.split(/\s+/).filter((t) => t.length > 0);
+    const scored = [];
+    for (const a of list) {
+        const name = String(a.name ?? '').toLowerCase();
+        const aliases = Array.isArray(a.aliases)
+            ? a.aliases.map((x) => String(x).toLowerCase())
+            : [];
+        const desc = String(a.description ?? '').toLowerCase();
+        const category = String(a.category ?? '').toLowerCase();
+        let score = 0;
+        const matchedOn = [];
+        if (name === q) {
+            score += 100;
+            matchedOn.push('name-exact');
+        }
+        else if (aliases.includes(q)) {
+            score += 80;
+            matchedOn.push('alias-exact');
+        }
+        for (const token of queryTokens) {
+            if (!token)
+                continue;
+            if (name.includes(token)) {
+                score += 40;
+                matchedOn.push(`name:${token}`);
+            }
+            else if (aliases.some((al) => al.includes(token))) {
+                score += 30;
+                matchedOn.push(`alias:${token}`);
+            }
+            if (desc.includes(token)) {
+                score += 20;
+                matchedOn.push(`desc:${token}`);
+            }
+            if (category === token) {
+                score += 10;
+                matchedOn.push(`cat:${token}`);
+            }
+        }
+        if (score > 0) {
+            scored.push({
+                name: a.name,
+                score,
+                matchedOn: [...new Set(matchedOn)],
+                description: a.description,
+                category: a.category,
+                aliases: a.aliases,
+            });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return { query: q, matches: scored.slice(0, limit) };
+}