@clearlysh/beehaven 0.8.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clearly (clearly.sh)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# beehaven
+
+The command line for **Beehaven** — the Clearly cloud. Command your workspace,
+agents, canvas and apps the way a terminal commands a filesystem, through the
+local daemon that bridges your machine (and your AI agents) to it.
+
+Beehaven is the name of the world Clearly runs in — the cloud, the hives, the
+daemon, the bees. It isn't a separate product you buy; it's where Clearly lives,
+and this is how you talk to it from a shell.
+
+## Requirements
+
+- Node.js **>= 20** (the CLI is a Node program; the published archive includes its
+  runtime dependencies)
+
+## Install
+
+For a one-off agent session with Node.js 20 or newer, run the npm package directly:
+
+```bash
+npx --yes @clearlysh/beehaven@latest guide
+```
+
+`guide` works before sign-in. It explains when Clearly is useful, gives the
+human a signup link, and shows the authenticated first artifact. `npx` uses an
+ephemeral npm install; it does not create a Clearly account or publish a file.
+The package also provides the `beehaven` binary for a global npm install:
+
+```bash
+npm install -g @clearlysh/beehaven@latest
+beehaven guide
+```
+
+The self-contained installer remains the recommended persistent install. It does
+not require npm to resolve dependencies on the user's machine:
+
+```bash
+curl -fsSL https://clearly.sh/install.sh | sh
+```
+
+That fetches a versioned tarball and writes `beehaven` to `~/.local/bin`. Published
+archives include their dependencies; older archives may require npm. Add the bin
+directory to your `PATH` if the installer says it isn't there.
+
+Verify:
+
+```bash
+beehaven --version
+beehaven doctor        # environment + daemon + relay checks
+```
+
+<details>
+<summary>Working inside the monorepo instead?</summary>
+
+```bash
+cd packages/cli && npm install && npm run build && npm link
+```
+
+`npm link` may not win: the installer writes `~/.local/bin/beehaven`, and that
+directory usually precedes the npm prefix on `PATH`. Check `which beehaven` and
+`beehaven --version` before concluding a local change didn't take.
+</details>
+
+Both npm and the installer ship the public CLI build. The installer downloads
+a versioned archive from `downloads.clearly.sh` and verifies the SHA-256 in its
+update manifest. npm verifies package integrity through the registry.
+
+## Updates
+
+Run `beehaven --version` to see both the version and the file being executed.
+The CLI checks the published version on command startup at most once an hour and
+prints a notice when it finds a newer version. This is a notice, not an interactive
+prompt. A curl-installed CLI (`~/.beehaven/cli`) can be updated by a person or an
+agent with `beehaven update`; it verifies the release archive's SHA-256 before
+installing. No workspace agent login is needed for this local command.
+An npm install updates with npm; an `npx` run can request `@latest` again.
+
+When a curl-installed CLI owns a standalone daemon, that daemon checks at startup
+and hourly, installs a verified update, and restarts itself. A daemon started by the
+Mac app leaves updates to the app. Production and staging Mac apps check on launch
+and every four hours, download in the background, and install on quit by default;
+the tray also offers **Check for updates**. A linked development build is updated
+by rebuilding its checkout. Clearly Dev.app also has no release updater; rebuild
+and reinstall that app to update its bundled CLI.
+
+## Quick start
+
+```bash
+beehaven login                # authenticate (browser OAuth)
+beehaven connect home         # set the active target — your default workspace
+beehaven agent login codex --label "my task" --client cli  # identity + one work session + brief
+beehaven actions              # what can I call here?
+beehaven call canvas-catalog '{}'   # every canvas verb + its args
+```
+
+Three commands cover almost everything: **connect** to a target, ask what
+**actions** it has, **call** one. See `beehaven help` for the full surface, or
+`beehaven help <command>` for any single verb.
+
+## Agent avatar expressions
+
+The local avatar is addressable by the active agent identity. Use the short
+flags for the primary expression surface:
+
+    beehaven --mood curious
+    beehaven --emote cheer "tests passed"
+
+Persistent moods are: neutral, happy, sad, surprised, angry, confused, curious,
+and flirty. Lifecycle values are `wake` and `sleep`, set with `--lifecycle`; thinking and
+celebrating are activity poses. One-shot emotes are: wave, cheer, hearts, laugh, dance, buzz, nod,
+shake, think, surprise, and sleep. An optional reason after an emote is capped
+at 200 characters.
+
+`--emote think` is the one-shot reaction. The compatibility command
+`beehaven avatar think` is the persistent thinking state.
+
+An active agent token routes the call to that agent's avatar; without one, the
+house avatar is used. Compatibility commands remain available:
+
+    beehaven avatar emotion curious
+    beehaven avatar react cheer "tests passed"
+
+The daemon MCP surface exposes avatar_emote for persistent emotion and
+avatar_react for one-shot reactions. Both surfaces require the avatar:emote
+permission for signed agents.
+
+See [AVATAR_EXPRESSIONS.md](../../../docs/AVATAR_EXPRESSIONS.md) for the complete
+cross-surface contract and source-of-truth locations.
+
+## Talking to the cloud — daemon + DO
+
+The CLI talks to a local **daemon** that holds the relay connection to the
+Beehaven cloud and routes RPCs to the right Durable Object.
+
+```bash
+beehaven login                # authenticate (browser OAuth) — required
+beehaven status               # connection + auth state
+beehaven connect home         # set the active target (default workspace alias)
+beehaven actions              # list callable actions on the target
+beehaven call <action> '{…}'  # invoke one
+```
+
+For scripts that need more than one workspace action, the CLI also exposes the
+server's scripting primitives without a second execution engine:
+
+```bash
+beehaven batch @steps.json --json       # {"steps":[{"action":"…","input":{}}]}
+beehaven code-run @script.mjs --json    # source file; use `-` for stdin
+```
+
+`batch` runs up to 25 sequential steps (400 actions total) and is not
+transactional; `stopOnError` defaults to true. `code-run` is a sandbox for
+computation between workspace calls (200 calls, 20 seconds, 100k source
+characters). Both adapters use the same active target, agent attribution,
+permission checks and non-zero failure semantics as `beehaven call`.
+`batch` also accepts the worker-native `{method,params}` spelling and normalizes
+both forms before dispatch.
+
+The daemon normally runs inside the Hive desktop app. For CI / servers / agents
+with no desktop, run it headless:
+
+```bash
+beehaven daemon start         # spawn a headless daemon (requires a prior `beehaven login`)
+beehaven daemon status
+```
+
+## Driving the canvas (agent surface)
+
+The CLI can review and drive the Clearly editor canvas in an open browser tab —
+the same actions a human performs in the UI, exposed to agents over the daemon.
+
+```bash
+beehaven canvas status [id]                  # compact health summary (tab connected? nodes? tool?)
+beehaven canvas perceive [id]                # read the live "room": gaze, contents, focus, chrome
+beehaven canvas actions                      # discover every callable editor action
+beehaven canvas invoke <action> '{…}'        # drive one action (returns the handler result)
+beehaven canvas verify [--composition id]    # self-test EVERY canvas action, then clean up after itself
+```
+
+`canvas verify` creates scratch nodes, exercises each action against the live
+tab, asserts the result, then deletes everything it created (it diffs against a
+baseline snapshot, so it never touches pre-existing content) and restores print
+settings. It is the smoke test for the agent/canvas surface.
+
+## Security
+
+- **Authentication is required.** Every cloud call carries an authenticated
+  identity; `canvas-invoke` / `canvas-perceive` reject unauthenticated callers
+  and only reach the caller's _own_ connected clients (no cross-account access).
+- **Allowlisted actions only.** Remote canvas control dispatches by action id
+  against a fixed registry — there is no arbitrary code execution path.
+- **Local IPC is token-guarded.** The CLI authenticates to the daemon with a
+  per-launch token from `~/.beehaven/ipc-auth`.
+
+## Documentation
+
+- Per-command help: `beehaven help <command>`
+
+## License
+
+MIT © Clearly (clearly.sh)

package/dist/__tests__/_cli-switch.js

@@ -0,0 +1,105 @@
+/**
+ * THE ONE READING OF `cli.ts`'s DISPATCH SWITCH — shared by every guard that needs it.
+ *
+ * ⚠⚠ WHY IT IS SHARED RATHER THAN COPIED (CBH2-128, and CBH2-100 one file over). Two guards had
+ * their own parser: `verb-surface.test.ts` derived the verb list to check `VERB_SURFACE` covers
+ * it, and `limit-capable.test.ts` derived case BODIES to check `LIMIT_CAPABLE` is really wired.
+ * A second copy of "what the switch contains" drifts from the first, and the whole point of both
+ * guards is that a hand-kept list beside a dispatch goes stale. A guard that goes stale the same
+ * way is worth less than no guard, because it reports a pass.
+ *
+ * ⚠ BOTH TRAPS BELOW WERE PAID FOR ONCE ALREADY AND ARE PRESERVED VERBATIM. Read the comments
+ * before touching either function; each one describes a run where the naive version silently
+ * reported the wrong answer rather than failing.
+ *
+ * Not a `.test.ts`, so vitest's default glob does not collect it.
+ */
+import { readFileSync } from 'node:fs';
+/** The dispatch, as written. */
+export const CLI_SRC = readFileSync(new URL('../cli.ts', import.meta.url), 'utf8');
+/**
+ * The dispatch with comments removed.
+ *
+ * ⚠ THIS PACKAGE HAS SHIPPED GUARDS THAT MATCHED THEIR OWN DOCSTRING — an assertion forbidding a
+ * shape passes because the shape is quoted in the prose explaining why it is forbidden.
+ */
+export const CLI_CODE = CLI_SRC
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1 ');
+/**
+ * Top-level `case` labels inside the main dispatch switch — 4-space indent, ending at `default:`.
+ *
+ * ⚠⚠ TWO PASSES, AND BOTH BOUNDS MATTER.
+ *
+ * INDENT scopes to the top-level switch: `tool`, `admin` and `compose` each open a sub-switch,
+ * whose cases (`list`, `users`, `backup`, …) are dispatch labels for a DIFFERENT switch and are
+ * not verbs. An un-anchored match pulls in 36 of them.
+ *
+ * THEN every `case '…':` ON that line, because two can share one: `case 'characters': case
+ * 'moni': {`. Anchoring alone silently drops the second and makes its entry read as a ghost.
+ *
+ * ⚠ IT READS THE RAW SOURCE, deliberately — this is the list the file DECLARES, and stripping
+ * comments first would change an answer two guards already depend on. No comment in `cli.ts`
+ * carries a 4-space-indented `case '…':`, and the count assertion in `verb-surface.test.ts` is
+ * what would notice if one ever did.
+ */
+export function switchVerbs() {
+    const start = CLI_SRC.indexOf('\n  switch (command) {');
+    const end = CLI_SRC.indexOf('\n    default: {', start);
+    if (start < 0 || end < start)
+        return [];
+    return CLI_SRC.slice(start, end).split('\n')
+        .filter((line) => /^ {4}case '/.test(line))
+        .flatMap((line) => [...line.matchAll(/case '([^']+)':/g)].map((m) => m[1]));
+}
+/**
+ * The body a `case` actually executes, from the COMMENT-STRIPPED source.
+ *
+ * ⚠⚠ FALL-THROUGH LABELS SHARE ONE BODY, AND IGNORING THAT MAKES A DETECTOR LIE. `case
+ * 'conversations': case 'convo': case 'conv': { … }` — slicing each label to the NEXT label gives
+ * the first two a body of 21 and 13 characters containing nothing but another label, so three
+ * correctly-wired verbs read as unwired.
+ *
+ * ⚠⚠ BRACE-MATCHED, NOT SLICED TO THE NEXT `case` LABEL. Two independent things break a label
+ * scan and BOTH bit on the first run of the guard this came from:
+ *   · fall-through, above;
+ *   · nesting — `case 'admin'` contains its OWN switch with ~24 `case` labels, so its body was
+ *     truncated at the first of them and the `values.limit` reads 300 lines down were invisible.
+ * A brace counter is immune to both. Strings are skipped so a `}` in a message cannot close it;
+ * comments are already gone.
+ *
+ * ⚠ A CONSEQUENCE WORTH KNOWING: fall-through labels return the SAME body, so a body-derived
+ * signal cannot tell `ticket` from `board`. Any caller distinguishing them must look at what the
+ * body does with `command`, not at the body alone.
+ */
+export function caseBody(verb) {
+    const cli = CLI_CODE;
+    const at = cli.indexOf(`case '${verb}':`);
+    if (at < 0)
+        return '';
+    const open = cli.indexOf('{', at);
+    if (open < 0)
+        return '';
+    let depth = 0;
+    for (let i = open; i < cli.length; i++) {
+        const c = cli[i];
+        if (c === "'" || c === '"' || c === '`') {
+            for (let j = i + 1; j < cli.length; j++) {
+                if (cli[j] === '\\') {
+                    j++;
+                    continue;
+                }
+                if (cli[j] === c) {
+                    i = j;
+                    break;
+                }
+            }
+            continue;
+        }
+        if (c === '{')
+            depth++;
+        else if (c === '}' && --depth === 0)
+            return cli.slice(at, i + 1);
+    }
+    return cli.slice(at);
+}

package/dist/__tests__/agent-wrap-probe.js

@@ -0,0 +1,136 @@
+/**
+ * A PROBE THAT RUNS THE WRAP — shared by every guard that used to read it.
+ *
+ * ⚠⚠ THREE SEPARATE GUARDS SCANNED SOURCE FOR THE ATTRIBUTION WRAP AND ALL THREE FAILED THE DAY IT
+ * MOVED, against builds where the behaviour was intact or improved. One of them had ALREADY been
+ * rewritten once for exactly that reason and recorded the lesson in its own comment — then broke
+ * the same way again. A scan cannot distinguish "this moved" from "this was deleted", so the same
+ * failure recurs for as long as the assertion is a scan.
+ *
+ * ⚠ A CHILD PROCESS WITH A SANDBOXED `HOME`, because `agent-state.ts` resolves the agents
+ * directory from `os.homedir()` at import time — an in-process test would read the developer's own
+ * identity and pass or fail according to whether they happened to be logged in.
+ *
+ * ⚠ IT LOADS `dist/`, not the TypeScript. That is deliberate and it is what makes this a guard on
+ * the SHIPPED artifact: the CLI users run is `dist/cli.js`. Run `npm run build` first — the repo's
+ * other child-process probes (`resolve()` in `agent-scope-persistence.test.ts`) already assume it.
+ */
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+const SRC = join(dirname(fileURLToPath(import.meta.url)), '..');
+const DIST = join(SRC, '..', 'dist');
+/**
+ * Run `activeAgentWrap` for real, with `agent` planted as the active identity (or nobody when it
+ * is `null`), and return the whole `{ action, input }` it produced.
+ */
+export function probeWrap(agent, action, input = {}, door = 'call') {
+    const home = mkdtempSync(join(tmpdir(), 'bh-wrap-'));
+    try {
+        if (agent) {
+            const dir = join(home, '.beehaven', 'agents');
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, 'tester.json'), JSON.stringify({
+                agentId: 'id-tester', kind: 'claude-code', displayName: 'tester',
+                avatarId: 'tester', userId: 'u', token: 'x', boundScopes: ['family:claude'], ...agent,
+            }));
+        }
+        const mod = JSON.stringify(join(DIST, 'agent-attribution.js'));
+        const out = execFileSync(process.execPath, [
+            '-e',
+            `const a=require(${mod});`
+                + `a.setCliDoor(${JSON.stringify(door)});`
+                + `process.stdout.write(JSON.stringify(a.activeAgentWrap(${JSON.stringify(action)},`
+                + `${JSON.stringify(input)}, {})));`,
+        ], { env: { ...process.env, HOME: home, BEEHAVEN_AGENT: 'tester' }, encoding: 'utf8' });
+        return JSON.parse(out);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+}
+/** The action a call comes out as — `agent-invoke` when it was attributed, itself when it was not. */
+export function wrapsAs(agent, action, input = {}) {
+    return probeWrap(agent, action, input).action;
+}
+/**
+ * ⚠⚠ THE END-TO-END PROBE: what `rpcOnce` PUTS ON THE WIRE.
+ *
+ * `wrapsAs` exercises the helper; this exercises the CALL SITE, and the distinction is the entire
+ * ticket. The wrap was correct for months while twelve of fifteen command modules never reached
+ * it — a guard on the helper alone would have been green throughout. So this stands up a fake IPC
+ * server, points `rpcOnce` at it, and returns the frame the daemon would have received.
+ */
+export function probeRpcFrame(agent, action, input = {}, door = 'call', 
+/**
+ * ⚠ `persistent` DRIVES THE OTHER SHAPE — a client held across calls (`omni`, `pipe`, `watch`,
+ * the interactive shell) rather than `rpcOnce`'s connect-call-disconnect. That distinction is
+ * not cosmetic: it is what made `rpcOnce` the wrong chokepoint, and a probe that only exercised
+ * the convenience wrapper would have agreed with the wrong answer.
+ */
+opts = {}) {
+    const home = mkdtempSync(join(tmpdir(), 'bh-rpc-'));
+    const sock = join(home, 'ipc.sock');
+    try {
+        if (agent) {
+            const dir = join(home, '.beehaven', 'agents');
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, 'tester.json'), JSON.stringify({
+                agentId: 'id-tester', kind: 'claude-code', displayName: 'tester',
+                avatarId: 'tester', userId: 'u', token: 'x', boundScopes: ['family:claude'], ...agent,
+            }));
+        }
+        const ipc = JSON.stringify(join(DIST, 'ipc-client.js'));
+        const attr = JSON.stringify(join(DIST, 'agent-attribution.js'));
+        /**
+         * ⚠ `requireAuth:false` IS WHY THE FAKE SERVER IS SIX LINES. `IpcClient.connect` skips the
+         * whole token handshake on that flag; a faithful auth simulation would be a second
+         * implementation of the thing under test.
+         */
+        const script = `
+const net=require('net');const fs=require('fs');
+const server=net.createServer((s)=>{
+  s.write(JSON.stringify({type:'status',clientId:'c1',daemonPid:1,requireAuth:false})+'\\n');
+  let buf='';
+  s.on('data',(d)=>{ buf+=d.toString();
+    for(const line of buf.split('\\n')){ if(!line.trim())continue;
+      let m; try{m=JSON.parse(line);}catch{continue;}
+      if(m.type==='rpc'){
+        fs.writeFileSync(${JSON.stringify(join(home, 'frame.json'))},
+          JSON.stringify({action:m.action,input:m.input}));
+        s.write(JSON.stringify({type:'rpc-result',rid:m.rid,result:{ok:true}})+'\\n');
+      }
+    }
+    buf='';
+  });
+});
+server.listen(${JSON.stringify(sock)}, async ()=>{
+  const a=require(${attr}); a.setCliDoor(${JSON.stringify(door)});
+  const c=require(${ipc});
+  try{
+    if(${opts.persistent ? 'true' : 'false'}){
+      const client = await c.connectClient();
+      try{ await client.call(${JSON.stringify(action)}, ${JSON.stringify(input)}, 4000); }
+      finally{ client.disconnect(); }
+    } else {
+      await c.rpcOnce(${JSON.stringify(action)}, ${JSON.stringify(input)}, 4000);
+    }
+  }catch(e){}
+  server.close(); process.exit(0);
+});`;
+        execFileSync(process.execPath, ['-e', script], {
+            env: {
+                ...process.env, HOME: home, BEEHAVEN_AGENT: 'tester',
+                BEEHAVEN_IPC_SOCKET: sock, BEEHAVEN_IPC_AUTH: 'unused',
+            },
+            encoding: 'utf8',
+            timeout: 20_000,
+        });
+        return JSON.parse(readFileSync(join(home, 'frame.json'), 'utf8'));
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+}

package/dist/agent-attribution.js

@@ -0,0 +1,192 @@
+/**
+ * ATTRIBUTION — who ran this, and through which door.
+ *
+ * ⚠⚠ THIS MODULE EXISTS BECAUSE PER-VERB STAMPING MISSED 28 OF 47 REMOTE VERBS.
+ *
+ * `agent_activity.source` was wired by having a verb's module import `agentRpc` instead of
+ * `rpcOnce` — three modules did (`ticket`, `sheet`, `slides`), twelve did not, and nothing
+ * anywhere reported the difference. The measured consequence was not a cosmetic gap in a report:
+ * a traffic table read "all 22 PROVISIONAL verbs have zero traffic" and the recorded retirement
+ * criterion would have deleted `task` and `search` — both demonstrably working — because they
+ * emit no activity row AT ALL. **Zero measured the instrumentation, not the usage.**
+ *
+ * ⚠ THE FIX IS THE PLACEMENT, NOT THE CODE. Everything below already existed in
+ * `commands/workspace.ts`; what changed is WHO CALLS IT — the three places an rpc frame is
+ * actually built now do, so a new verb is attributed without its author having to know this file
+ * exists:
+ *
+ *   · `IpcClient.call`   (`ipc-client.ts`)    — the transport behind `rpcOnce`, `connectClient`,
+ *                                               and every long-lived client (`omni`, `pipe`, …)
+ *   · `daemonRpc`        (`daemon-client.ts`) — the SECOND general transport: `logs`, `shop`,
+ *                                               `costs`, the `--building` gateway, the shell
+ *   · `ClaudeBridge.rpc` (`claude-bridge.ts`) — dormant, but general
+ *
+ * ⚠ `rpcOnce` WAS TRIED AS THE CHOKEPOINT AND IS ONE LEVEL TOO HIGH. It is a convenience wrapper
+ * (connect → call → disconnect); every caller that HOLDS a client goes round it. That was not a
+ * theoretical objection — `commands/omni.ts` was doing exactly that, and the guard caught it.
+ *
+ * ⚠ IT LIVES HERE rather than in `workspace.ts` only so the transports can import it without a
+ * cycle (`workspace.ts` imports `rpcOnce`). Its dependencies are `agent-state` → `agent-scope` →
+ * node builtins, and nothing else.
+ */
+import { resolveActiveAgent } from './agent-state.js';
+/**
+ * ⚠⚠ THE VERBS THAT ESTABLISH AN IDENTITY CANNOT BE WRAPPED IN ONE — a cold-start deadlock.
+ *
+ * `agentInvoke` gates every call through `_checkAgentScope`, which refuses a principal the
+ * workspace has no `agents` row for: *"unknown agent 'X'"*. An identity is per WORKSPACE — the
+ * token carries `agentId` + `userId` and no workspace, and the row lives in the workspace DO — so
+ * arriving in a new workspace you are, correctly, nobody there.
+ *
+ * The deadlock is that the way to STOP being nobody was also wrapped:
+ *
+ *   · `agent-mint-token` → refused, so `agent login` silently fell through to a LOCAL mint,
+ *     printed "✓ Signed in" and "◆ Workspace session open", and every later call failed.
+ *   · `agent-create`     → refused, because the call to create the agent ran AS that agent.
+ *
+ * Reproduced on `checkout-test-9`, which holds ZERO agents and was therefore unreachable from the
+ * CLI by any means short of dev-scope `beehaven sql`.
+ *
+ * ⚠ THIS IS NOT A HOLE IN THE GATE. These dispatch as the ACCOUNT OWNER, exactly as they did
+ * before any agent existed, and the owner is who is entitled to create an agent in their own
+ * workspace. Attribution is not lost either — there is nothing yet to attribute to.
+ *
+ * ⚠⚠ THE MEMBERSHIP TEST IS "DOES THIS VERB ESTABLISH AN IDENTITY", NOT A NUMBER. These five all
+ * do: mint one on the account, join a workspace with it, or see what is already there. Every
+ * OTHER verb must stay wrapped, or "run it as the owner instead" becomes the universal way round
+ * the per-agent scope — which is why the guard caps the set rather than merely listing it.
+ */
+export const BOOTSTRAP_ACTIONS = new Set([
+    // Account-level: mint an identity, then join a workspace with it.
+    'agent-account-mint', 'agent-admit',
+    // The workspace-scoped predecessors, kept so an older flow still bootstraps.
+    'agent-mint-token', 'agent-create', 'agent-list',
+]);
+/**
+ * ⚠⚠ ACTIONS THE DAEMON ANSWERS ITSELF — THEY NEVER REACH A WORKSPACE, SO THEY CANNOT BE WRAPPED.
+ *
+ * `IpcClient.call` sends `type:'rpc'`, and `ipc-server.ts` forwards every one of those to the
+ * relay — EXCEPT the eleven the daemon intercepts in its own `ipc.on('rpc')` handler
+ * (`daemon.ts`). Wrapping one of those in `agent-invoke` produces an action the daemon does not
+ * recognise, and it would be forwarded to the cloud instead of handled locally: `beehaven connect`
+ * would stop setting the target.
+ *
+ * ⚠⚠ ENUMERATED, NEVER A "HAS A COLON" RULE. `admin:store-rpc`, `admin:broadcast`,
+ * `admin:store-query`, `_rpc:catalog` and `vector:catalog.presets` are all namespaced AND all
+ * genuinely remote. A prefix heuristic would silently un-attribute every one of them, which is
+ * this ticket's own defect wearing a tidier shape.
+ *
+ * ⚠ MIRRORS `daemon.ts`. `attribution.test.ts` reads that file and fails if the two drift — a new
+ * daemon-local verb that is not listed here becomes an action wrapped in `agent-invoke` and shipped
+ * to the cloud, which fails in a way that names neither cause.
+ */
+export const DAEMON_LOCAL_ACTIONS = new Set([
+    'building:connect', 'building:disconnect', 'building:connection',
+    'agent:mint', 'agent:connect', 'agent:disconnect',
+    'daemon:session-status', 'daemon:app-ensure', 'daemon:app-list',
+    'daemon:app-install', 'daemon:app-uninstall',
+]);
+/**
+ * ⚠⚠ WHICH DOOR THIS PROCESS IS — `cli:call` when the user typed `beehaven call`, `cli:ticket`
+ * when they typed `beehaven ticket create`, and so on.
+ *
+ * It answers the one question `agent_activity` could not: whether a typed verb or the raw
+ * `call` escape hatch did the work. Nothing else can tell them apart — both arrive as the same
+ * action, from the same agent, over the same transport — so the CLI's ~103 verbs have never had
+ * a usage figure, and any retirement list is taste until this has run for a while.
+ *
+ * ⚠ A MODULE GLOBAL, AND THAT IS THE RIGHT SHAPE HERE. One CLI process handles exactly one
+ * command; the alternative is threading a door argument through every call site, which is ~169
+ * sites today and one forgotten site per verb added — i.e. a mirror, and mirrors in this repo
+ * drift. Set once in `cli.ts` from the parsed command, read once here.
+ *
+ * ⚠ IT IS THE VERB THE USER TYPED, NOT THE ACTION DISPATCHED. `beehaven ticket create` sends
+ * `ticket-create`, and labelling the door `cli:ticket-create` would make the column a second
+ * copy of `action` — it has to name the SURFACE, or the join that answers "verb or call?"
+ * cannot be written.
+ *
+ * ⚠ EMPTY UNTIL SET. A CLI path that never calls `setCliDoor` logs no door rather than a wrong
+ * one, and an unknown door must stay distinguishable from a real one in a `GROUP BY`.
+ */
+let CLI_DOOR = '';
+/** Called once from `cli.ts` with the verb the user actually typed. Aliases resolve to the
+ *  canonical verb by the caller, so `cd` and `connect` do not read as two surfaces. */
+export function setCliDoor(command) {
+    const v = String(command || '').trim().toLowerCase();
+    // ⚠ Bounded and charset-checked: it lands in a column and in a `GROUP BY`, and an
+    // unconstrained caller-supplied label is how a cardinality explosion gets into a report.
+    CLI_DOOR = /^[a-z0-9][a-z0-9:_-]{0,32}$/.test(v) ? `cli:${v}` : '';
+}
+export function cliDoor() {
+    return CLI_DOOR;
+}
+/**
+ * ⚠⚠ IS THIS PAYLOAD ALREADY ATTRIBUTED? — the idempotency test that lets the wrap move down to
+ * the transport without double-wrapping the paths that still wrap above it.
+ *
+ * Two shapes count as attributed, and the second is the one that is easy to miss:
+ *
+ *   · `agent-invoke` itself.
+ *   · A CROSS-DO PROXY CARRYING ONE. `cmdCall` wraps and THEN calls `resolveBuilding`, because
+ *     `agent-invoke` must travel INSIDE the proxy so the gate, the activity row and the work all
+ *     land in the addressed workspace. The wire shape is `{ <type>Id, action:'agent-invoke',
+ *     input }` (see `gatewayEnvelope`). Wrapping that again would produce
+ *     `agent-invoke(admin:team-rpc(agent-invoke(…)))` — the outer one attributing in the LOCAL
+ *     workspace's log for work performed remotely, which is precisely the ordering bug the
+ *     wrap-then-proxy sequence was introduced to fix.
+ *
+ * ⚠ ONE LEVEL, NEVER A LOOP. A proxy nested in a proxy is not a shape anything produces, and a
+ * recursive walk over caller-supplied input is unbounded work on a value we do not control. The
+ * worker's own `proxiedAction` makes the same call for the same reason.
+ */
+export function alreadyAttributed(action, input) {
+    if (action === 'agent-invoke')
+        return true;
+    if (!input || typeof input !== 'object')
+        return false;
+    return input.action === 'agent-invoke';
+}
+/**
+ * Wrap a call in `agent-invoke` when an agent is signed in — BEFORE the building envelope.
+ *
+ * ⚠⚠ THE ORDER IS THE WHOLE POINT. `agent-invoke` must travel INSIDE the proxy so it executes on
+ * the workspace being addressed; wrapped outside, it runs on the daemon's default DO and
+ * `_checkAgentScope` asks the wrong roster whether the agent is a member. See the note at the call
+ * site for the measurement.
+ *
+ * ⚠ IT RESOLVES THE AGENT ITSELF rather than taking one, because the wrap now happens earlier than
+ * the refusal checks in `cmdCall`. `resolveActiveAgent` is file reads only, and resolving twice is
+ * cheaper than threading state through a routing decision.
+ *
+ * ⚠ AN EXPIRED IDENTITY IS NOT WRAPPED HERE — it is REFUSED by `cmdCall`, with a message naming
+ * the re-login. Wrapping it would send a token the server rejects and turn a clear local error
+ * into a remote one.
+ */
+export function activeAgentWrap(action, input, values) {
+    if (alreadyAttributed(action, input))
+        return { action, input };
+    if (BOOTSTRAP_ACTIONS.has(action) || DAEMON_LOCAL_ACTIONS.has(action))
+        return { action, input };
+    let active = null;
+    try {
+        active = resolveActiveAgent(values);
+    }
+    catch {
+        return { action, input };
+    }
+    if (!active || active.expired)
+        return { action, input };
+    return {
+        action: 'agent-invoke',
+        input: {
+            agentId: active.agentId,
+            action,
+            input,
+            ...(active.record.sessionId ? { sessionId: active.record.sessionId } : {}),
+            // ⚠ WHICH DOOR — `cli:call` vs `cli:ticket` vs … See `cliDoor()` and
+            // `agent_activity.source`. Set here, at the ONE wrap every CLI path shares, so a new
+            // verb is labelled without its author having to know this exists.
+            ...(cliDoor() ? { source: cliDoor() } : {}),
+        },
+    };
+}