@clearlysh/beehaven 0.8.16

package/dist/verb-surface.js

@@ -0,0 +1,331 @@
+/**
+ * THE VERB SURFACE — what each verb is, and why it is allowed to exist.
+ *
+ * ⚠⚠ THIS FILE EXISTS BECAUSE THE QUESTION "should this all just be `call <action> <json>`?" HAD
+ * NO ANSWER, ONLY OPINIONS. The CLI carries 113 case labels / ~98 distinct verbs; `beehaven call`
+ * already reaches every one of ~1,000 registered actions; and nothing anywhere recorded which of
+ * the two doors people actually use. `agent_activity.source` now records it — but a column that
+ * fills up is only half a decision procedure. This is the other half: the RULE, written down
+ * before the data arrives, so the answer is not chosen after the fact to suit whatever the numbers
+ * happen to say.
+ *
+ * ⚠ MODELLED ON `EAGER_TOOLS`, DELIBERATELY. That list solved the same problem for MCP — 139 tools
+ * cut to 20 — by making every survivor state its reason, and the cut was decided on
+ * `mcp_tool_calls` rather than taste. Same shape here.
+ *
+ * ── THE EARNING TEST ────────────────────────────────────────────────────────────────────────
+ *
+ * A verb that reaches the workspace survives only if it does at least one of:
+ *
+ *   STATE     it carries client-side state `call` structurally cannot — a cwd, argument quoting,
+ *             a fallback ladder. `beehaven ls` is not sugar: it threads a per-target cwd through
+ *             `shell-session.ts` and quotes arguments that a remote tokenizer would re-split.
+ *   TRAFFIC   it is in the measured top-20 by real traffic. Concentration is extreme — 20 actions
+ *             carry 84.7% of 16,161 calls — so this is a short list by construction.
+ *   BEYOND    it expresses something no single action can: a multi-call flow, a local file, an
+ *             interactive loop.
+ *
+ * ⚠⚠ "IT READS NICER" IS NOT ON THE LIST, and that is the whole point of writing the test down.
+ * Every verb reads nicer than `call`; if that counted, nothing would ever be retired and the
+ * surface would only grow — which is how it reached 98.
+ *
+ * ⚠ `STRUCTURAL` IS NOT AN EARNING CATEGORY — IT IS THE FLOOR. Those verbs never reach the
+ * workspace at all (`call` presupposes them: a daemon, an account, an identity, a target, the
+ * local disk, a transport, an audio device), so the test does not apply and cannot retire them.
+ * `AGENT_LOGIN_EXEMPT` in `cli.ts` was derived independently, for the same reason, and the two
+ * lists agreeing is the evidence that the boundary is real rather than taste.
+ *
+ * ⚠⚠ NOTHING IS RETIRED BY THIS FILE. `PROVISIONAL` verbs are the candidates — every one of them
+ * is a remote verb with no STATE/BEYOND claim, whose fate rests on TRAFFIC, and traffic per DOOR
+ * has been measurable for exactly as long as `agent_activity.source` has existed. Retiring them
+ * now would be doing the thing this file was written to stop: deciding on taste and calling it
+ * measurement. Re-run `verbTrafficQuery()` once the column has a few weeks on it.
+ */
+/**
+ * ⚠ EVERY top-level `case` label in `cli.ts` must appear here — `verb-surface.test.ts` reads the
+ * switch and fails on any label this file does not classify. A new verb therefore cannot ship
+ * without stating what it is, which is the only mechanism that stops the surface drifting back.
+ */
+export const VERB_SURFACE = {
+    // ── The floor: `call` cannot run without these ────────────────────────────────────────────
+    connect: { cls: 'STRUCTURAL', why: 'sets the target every other call routes to' },
+    cd: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'connect' },
+    nav: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'connect' },
+    navigate: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'connect' },
+    disconnect: { cls: 'STRUCTURAL', why: 'clears the target' },
+    pwd: { cls: 'STRUCTURAL', why: 'reports local session state' },
+    where: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'pwd' },
+    env: { cls: 'STRUCTURAL', why: 'chooses which relay the daemon dials' },
+    login: { cls: 'STRUCTURAL', why: 'browser OAuth + keychain' },
+    logout: { cls: 'STRUCTURAL', why: 'clears local credentials' },
+    signup: { cls: 'STRUCTURAL', why: 'opens a browser' },
+    whoami: { cls: 'STRUCTURAL', why: 'reads local credentials' },
+    start: { cls: 'STRUCTURAL', why: 'spawns the daemon `call` needs' },
+    stop: { cls: 'STRUCTURAL', why: 'daemon lifecycle' },
+    restart: { cls: 'STRUCTURAL', why: 'daemon lifecycle' },
+    daemon: { cls: 'STRUCTURAL', why: 'daemon lifecycle' },
+    status: { cls: 'STRUCTURAL', why: 'probes the socket and the relay — cannot use either' },
+    doctor: { cls: 'STRUCTURAL', why: 'diagnoses the transport `call` rides on' },
+    update: { cls: 'STRUCTURAL', why: 'replaces this binary' },
+    completions: { cls: 'STRUCTURAL', why: 'emits a shell script' },
+    help: { cls: 'STRUCTURAL', why: 'local text' },
+    agent: { cls: 'STRUCTURAL', why: 'mints and activates the identity every call is attributed to' },
+    install: { cls: 'STRUCTURAL', why: 'writes hives to local disk' },
+    app: { cls: 'STRUCTURAL', why: 'installs/packs/uninstalls local hives' },
+    hive: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'app' },
+    apps: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'app' },
+    skills: { cls: 'STRUCTURAL', why: 'writes SKILL.md into local agent homes' },
+    marketplace: { cls: 'STRUCTURAL', why: 'installs to local disk' },
+    mcp: { cls: 'STRUCTURAL', why: 'writes client config files and mints tokens' },
+    'mcp-config': { cls: 'STRUCTURAL', why: 'prints a client config block' },
+    link: { cls: 'STRUCTURAL', why: 'binds a local folder to a project' },
+    unlink: { cls: 'STRUCTURAL', why: 'unbinds a local folder' },
+    init: { cls: 'STRUCTURAL', why: 'scaffolds files on disk' },
+    dev: { cls: 'STRUCTURAL', why: 'runs a local server' },
+    deploy: { cls: 'STRUCTURAL', why: 'shells out to wrangler' },
+    rollback: { cls: 'STRUCTURAL', why: 'shells out to wrangler' },
+    versions: { cls: 'STRUCTURAL', why: 'shells out to wrangler' },
+    codegen: { cls: 'STRUCTURAL', why: 'writes generated types to disk' },
+    seed: { cls: 'STRUCTURAL', why: 'local project command' },
+    migrate: { cls: 'STRUCTURAL', why: 'local project command' },
+    test: { cls: 'STRUCTURAL', why: 'local project command' },
+    d1: { cls: 'STRUCTURAL', why: 'shells out to wrangler with the local CF token' },
+    secrets: { cls: 'STRUCTURAL', why: 'shells out to wrangler' },
+    compose: { cls: 'STRUCTURAL', why: 'reads and pushes local composition repos' },
+    sync: { cls: 'STRUCTURAL', why: 'uploads local session files' },
+    teleport: { cls: 'STRUCTURAL', why: 'reads a file off the local disk' },
+    doc: { cls: 'STRUCTURAL', why: 'reads a local file and indexes it' },
+    context: { cls: 'STRUCTURAL', why: 'writes .clearly/CLAUDE.md locally' },
+    voice: { cls: 'STRUCTURAL', why: 'local audio devices and on-device TTS' },
+    say: { cls: 'STRUCTURAL', why: 'drives the local avatar surface' },
+    avatar: { cls: 'STRUCTURAL', why: 'drives the local avatar expression surface' },
+    speak: { cls: 'STRUCTURAL', why: 'local audio output' },
+    pipe: { cls: 'STRUCTURAL', why: 'IS a transport — JSON-RPC over stdio' },
+    devices: { cls: 'STRUCTURAL', why: 'local device identity' },
+    swarm: { cls: 'STRUCTURAL', why: 'this node\'s role and identity in the mesh' },
+    characters: { cls: 'STRUCTURAL', why: 'Mac-app character shop; `call` cannot serve it' },
+    moni: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'characters' },
+    treehouse: { cls: 'STRUCTURAL', why: 'opens a local window' },
+    claude: { cls: 'STRUCTURAL', why: 'spawns a local Claude session' },
+    omni: { cls: 'STRUCTURAL', why: 'interactive local REPL' },
+    shell: { cls: 'STRUCTURAL', why: 'interactive loop' },
+    watch: { cls: 'STRUCTURAL', why: 'holds a stream open' },
+    buildings: { cls: 'STRUCTURAL', why: 'enumerates reachable targets — needed to pick one' },
+    workspaces: { cls: 'STRUCTURAL', why: 'enumerates memberships — needed to pick a target' },
+    ws: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'workspaces' },
+    // ── Earn their place: client-side state ───────────────────────────────────────────────────
+    ls: { cls: 'STATE', why: 'per-target cwd + arg quoting + notes-shell→VFS fallback' },
+    cat: { cls: 'STATE', why: 'cwd + quoting; a multi-word title is one argument' },
+    grep: { cls: 'STATE', why: 'cwd + quoting; a pattern with spaces is one argument' },
+    tree: { cls: 'STATE', why: 'cwd' },
+    find: { cls: 'STATE', why: 'cwd' },
+    head: { cls: 'STATE', why: 'cwd' },
+    tail: { cls: 'STATE', why: 'cwd' },
+    wc: { cls: 'STATE', why: 'cwd' },
+    jq: { cls: 'STATE', why: 'cwd' },
+    rm: { cls: 'STATE', why: 'cwd' },
+    mv: { cls: 'STATE', why: 'cwd' },
+    cp: { cls: 'STATE', why: 'cwd' },
+    mkdir: { cls: 'STATE', why: 'cwd' },
+    write: { cls: 'STATE', why: 'cwd + the notes-shell/VFS routing decision' },
+    edit: { cls: 'STATE', why: 'cwd + the notes-shell/VFS routing decision' },
+    sql: { cls: 'STATE', why: 'rest-of-line quoting — quoting the statement makes the guard refuse it' },
+    // ── Earn their place: beyond one action ───────────────────────────────────────────────────
+    call: { cls: 'BEYOND', why: 'IS the escape hatch — the floor of the CLI' },
+    batch: { cls: 'BEYOND', why: 'scripts multiple workspace actions in one canonical call' },
+    'code-run': { cls: 'BEYOND', why: 'computes between workspace actions in a sandboxed call' },
+    actions: { cls: 'BEYOND', why: 'discovery; without it `call` is unusable' },
+    explain: { cls: 'BEYOND', why: 'discovery; the authority on an action\'s arguments' },
+    describe: { cls: 'BEYOND', why: 'alias', aliasOf: 'explain' },
+    rpc: { cls: 'BEYOND', why: 'the raw gateway envelope, below `call`' },
+    ticket: { cls: 'BEYOND', why: 'resolves a board before creating, and refuses a numeric priority the API inverts' },
+    comment: { cls: 'BEYOND', why: 'addresses ANY surface by key/title and turns per-surface anchor flags into one call; prints who the @s reached' },
+    comments: { cls: 'BEYOND', why: 'served by the comment module', aliasOf: 'comment' },
+    mention: { cls: 'BEYOND', why: 'resolves an 8-char id prefix before acking, and reads your mention queue as whichever identity you are' },
+    mentions: { cls: 'BEYOND', why: 'served by the mention module', aliasOf: 'mention' },
+    board: { cls: 'BEYOND', why: 'served by the ticket module', aliasOf: 'ticket' },
+    /**
+     * ⚠ `sprint` EARNS ITS PLACE ON RESOLUTION, NOT ON REACH. A sprint is addressed by uuid and
+     * nothing ever prints one in prose, so the verb resolves a NAME and refuses an ambiguous one;
+     * and `sprint plan` resolves card KEYS to row ids before calling, because `sprint-plan` reports
+     * `moved: 1` for a key it never moved (measured 2026-09-06).
+     */
+    sprint: { cls: 'BEYOND', why: 'served by the ticket module', aliasOf: 'ticket' },
+    /**
+     * ⚠⚠ `restore` EARNS BEYOND ON A DANGEROUS DEFAULT, NOT ON PARSING. `document-archive` treats an
+     * OMITTED `archived` as **true**, so the raw one-liner's default is the exact OPPOSITE of what
+     * this verb means: a caller who forgets the field archives the thing they asked to restore, and
+     * the output is indistinguishable from success. Supplying `archived: false` where the action's
+     * default inverts the intent is the same claim `slides move` makes by taking the required `to`
+     * positionally — a shape the raw call gets silently wrong.
+     *
+     * ⚠ It also reports the handler's `unchanged: true` as a NO-OP rather than as "restored".
+     */
+    restore: { cls: 'BEYOND', why: 'supplies archived:false — the raw action DEFAULTS to true, inverting the intent' },
+    /**
+     * ⚠ `trash` IS PROVISIONAL, AND THAT IS THE HONEST CLASS FOR IT. It is a listing over
+     * `document-list { archived: true }`; the clamp-announcing and the "that is the whole page" line
+     * are good manners, not a shape the raw action refuses. Its fate rests on traffic, like every
+     * other verb here with no STATE/BEYOND claim.
+     *
+     * ⚠⚠ BUT IT IS COUPLED TO `restore` AND MUST NOT BE RETIRED ALONE. Both exist because `rm`
+     * archives and CBH2-34's reproduction was `beehaven help | grep -iE 'restore|trash'` returning
+     * NOTHING. `restore` needs a key, and `trash` is the only surface that prints one. Retire the
+     * pair or neither — retiring `trash` on its own leaves an undo nobody can address.
+     */
+    trash: { cls: 'PROVISIONAL', why: 'a listing; kept because it is the only surface that prints an archived key for `restore`' },
+    /**
+     * ⚠ `sheet` AND `slides` PARSE ON THE CALLER'S BEHALF, which is what puts them here rather than
+     * in PROVISIONAL: `sheet set` turns TSV into the `rows` array `sheet-set` wants and supplies the
+     * `at` anchor; `slides add` splits `--bullets` on `|`; `slides move` takes the REQUIRED `to`
+     * positionally so it cannot be omitted. Each of those is a shape the raw action refuses or
+     * silently ignores, and none of it is expressible as one `call`.
+     */
+    sheet: { cls: 'BEYOND', why: 'parses TSV into rows + anchor; `sheet-set` takes neither as text' },
+    sheets: { cls: 'BEYOND', why: 'alias', aliasOf: 'sheet' },
+    slides: { cls: 'BEYOND', why: 'splits bullets, positions the required `to`, separates show from export' },
+    deck: { cls: 'BEYOND', why: 'alias', aliasOf: 'slides' },
+    /**
+     * ⚠ `brand` EARNS ITS PLACE BY REFUSING THE PALETTE-WIPING SHAPE: `brand set <b> color.accent #…`
+     * always sends the role MAP, never the array that replaces every colour; it also resolves a name
+     * to an id for history/revert. `component` writes `render -o` files and types `place` numbers.
+     */
+    brand: { cls: 'BEYOND', why: 'builds role-merge patches (never the palette-replacing array); resolves names for history/revert' },
+    brands: { cls: 'BEYOND', why: 'alias', aliasOf: 'brand' },
+    component: { cls: 'BEYOND', why: 'writes render -o SVG files, types place coordinates, reads spec/patch JSON from @file' },
+    components: { cls: 'BEYOND', why: 'alias', aliasOf: 'component' },
+    open: { cls: 'BEYOND', why: 'resolves an id across four kinds, then drives an open tab' },
+    ask: { cls: 'BEYOND', why: 'a conversation, not a call' },
+    shop: { cls: 'BEYOND', why: 'multi-step protocol (find→search→get→checkout) with a safety rule' },
+    admin: { cls: 'BEYOND', why: '24 operator subcommands, several multi-call' },
+    broadcast: { cls: 'BEYOND', why: 'fans one message across targets' },
+    /**
+     * ── ⚠⚠ NOT REMOTE AT ALL — CBH2-81 ────────────────────────────────────────────────────────
+     *
+     * These three were classified as verbs that reach the workspace. They do not, so their
+     * `agent_activity` zero is REAL — and retiring them on that zero would be right by accident and
+     * wrong by reasoning, which is exactly what this file exists to prevent. Verified by reading each
+     * module: `commands/composition.ts` and `commands/tool.ts` contain **zero** `daemonRpc` /
+     * `rpcOnce` / `connectClient` calls between them, and `commands/explore.ts` builds every URL as
+     * `http://127.0.0.1:${port}`.
+     *
+     * ⚠ STRUCTURAL, WHICH IS THE FLOOR AND NOT AN EARNING CLAIM. `call` cannot serve a file on this
+     * machine or a dev server on this machine, so the earning test does not apply to them and cannot
+     * retire them. Same reasoning the header already gives for `pwd` reporting local session state.
+     */
+    composition: { cls: 'STRUCTURAL', why: 'reads ~/.clearly/composition-repos.json — a local file; no RPC in the module' },
+    comp: { cls: 'STRUCTURAL', why: 'alias', aliasOf: 'composition' },
+    tool: { cls: 'STRUCTURAL', why: 'reads ~/.beehaven/tools on local disk; no RPC in the module' },
+    explore: { cls: 'STRUCTURAL', why: 'targets a LOCAL dev server (127.0.0.1:8787, `beehaven dev`), never the workspace' },
+    /**
+     * ── ⚠ A DIFFERENT AUTHENTICATION SURFACE — CBH2-81 ────────────────────────────────────────
+     *
+     * `webhook` and `user` go through `getAdminClient` (`lib/admin-client.ts`): plain HTTP with a
+     * worker secret, carrying NO agent identity. So they never pass through `agent-invoke` and
+     * structurally cannot write an `agent_activity` row, however much they are used.
+     *
+     * ⚠ THEIR ZERO MEASURES THE TRANSPORT, NOT THE DEMAND. Left as PROVISIONAL they sit on a
+     * retirement list whose criterion cannot see them — the exact failure `ask` is called out for in
+     * CBH2-82, one door over. `ADMIN_HTTP` says so, so the traffic reader skips them by class
+     * instead of anyone remembering the exception.
+     */
+    user: { cls: 'ADMIN_HTTP', why: 'getAdminClient — HTTP + worker secret, no agent identity' },
+    webhook: { cls: 'ADMIN_HTTP', why: 'getAdminClient — HTTP + worker secret, no agent identity' },
+    webhooks: { cls: 'ADMIN_HTTP', why: 'alias', aliasOf: 'webhook' },
+    // ── Candidates: no STATE/BEYOND claim; fate rests on measured traffic per door ─────────────
+    canvas: { cls: 'PROVISIONAL', why: 'wraps canvas-act/-perceive; `call` reaches both' },
+    conversations: { cls: 'PROVISIONAL', why: 'wraps conversation-list' },
+    convo: { cls: 'PROVISIONAL', why: 'alias', aliasOf: 'conversations' },
+    conv: { cls: 'PROVISIONAL', why: 'alias', aliasOf: 'conversations' },
+    library: { cls: 'PROVISIONAL', why: 'wraps library RPCs' },
+    lib: { cls: 'PROVISIONAL', why: 'alias', aliasOf: 'library' },
+    remember: { cls: 'PROVISIONAL', why: 'one call to agent-memory-remember' },
+    recall: { cls: 'PROVISIONAL', why: 'one call to agent-memory-recall' },
+    search: { cls: 'PROVISIONAL', why: 'one call; `bash "grep …"` covers the same job' },
+    task: { cls: 'PROVISIONAL', why: 'one call to note-create — and its name collides with `ticket`' },
+    workspace: { cls: 'PROVISIONAL', why: 'one overview call' },
+    logs: { cls: 'PROVISIONAL', why: 'one call' },
+    costs: { cls: 'PROVISIONAL', why: 'one call' },
+    compliance: { cls: 'PROVISIONAL', why: 'thin wrapper' },
+    publish: { cls: 'PROVISIONAL', why: 'one call' },
+    'store-query': { cls: 'PROVISIONAL', why: 'one call' },
+};
+/**
+ * The SQL that decides a PROVISIONAL verb's fate, once `agent_activity.source` has run for long
+ * enough to be worth reading.
+ *
+ * ⚠ IT COUNTS THE DOOR, NOT THE ACTION. `ticket-create` is busy either way; the only question is
+ * how much of that arrived as `beehaven ticket create` rather than `beehaven call ticket-create`,
+ * and before the `source` column nothing could tell them apart.
+ *
+ * ⚠ A verb with NO rows is not automatically dead — it may simply postdate the column. Check
+ * `MIN(timestamp) WHERE source <> ''` before reading a zero as a verdict.
+ *
+ * ⚠⚠ AND THREE CLASSES OF VERB ARE UNMEASURABLE BY THIS QUERY, SO THEY ARE EXCLUDED FROM IT RATHER
+ * THAN LEFT TO BE MISREAD AS DISUSE (CBH2-81, CBH2-82). The exclusion is DERIVED from
+ * `VERB_SURFACE` below, not typed here, so a future verb of the same kind is covered on the day it
+ * is classified — a hand-kept exception list is how this file's own advice goes stale.
+ *
+ *   · `STRUCTURAL` — never reaches the workspace at all (local disk, a local dev server, the
+ *     daemon). There is nothing to count and the earning test does not apply.
+ *   · `ADMIN_HTTP` — `getAdminClient`, plain HTTP with an operator secret and NO agent identity,
+ *     so it cannot pass through `agent-invoke` and cannot write a row however heavily it is used.
+ *
+ * ⚠⚠ THE THIRD IS `ask`, AND IT IS THE DANGEROUS ONE, BECAUSE ITS COUNT IS NOT ZERO. `cmdAsk`
+ * fires `agent:message` — an IPC `send` frame, not an `rpc` — which the DO records in
+ * `conversation_messages` and never in `agent_activity`. **But since 2026-09-04 it falls back to
+ * `rpcOnce('agent-prompt', { wait: true })` when the broadcast produces nothing**, and THAT path
+ * attributes normally. Measured 2026-09-06: two `ask` invocations took `cli:ask` from 1 to 2.
+ *
+ * So `cli:ask` counts **how often the stream path failed**, not how often anyone asked. With the
+ * Mac app driving a live socket the turn succeeds on the broadcast and writes nothing; headless it
+ * falls back and writes a row. ⚠ A PARTIAL, ENVIRONMENT-DEPENDENT COUNT IS WORSE THAN A ZERO — a
+ * zero is obviously unusable, whereas `2` looks like a measurement and will be read as one. `ask`
+ * is `BEYOND`, so no retirement rests on it either way; it is excluded so nobody derives a
+ * usage claim from a number that means something else.
+ */
+export function verbTrafficQuery() {
+    /**
+     * ⚠⚠ ONE DERIVATION, NOT TWO (CBH2-100). This filter used to be computed here AND, separately,
+     * inside `unmeasurableVerbs()` — the same predicate written twice, with nothing asserting the
+     * two agreed. Proved by narrowing `unmeasurableVerbs` to STRUCTURAL alone and leaving this
+     * untouched: `verb-surface-measurability` stayed at 30/30 while the query went on excluding
+     * `user` / `webhook` / `webhooks` from the door table and the report no longer explained why
+     * they were absent — i.e. exactly the silent drop that function's own docstring exists to
+     * prevent, arriving through the function meant to prevent it.
+     *
+     * The REPORTED reason and the APPLIED exclusion are now the same list by construction.
+     */
+    const unmeasurable = unmeasurableVerbs().map((e) => e.verb).sort();
+    const notIn = unmeasurable.map((v) => `'cli:${v}'`).join(', ');
+    return [
+        'SELECT source, COUNT(*) n, COUNT(DISTINCT action) actions',
+        'FROM agent_activity',
+        "WHERE source LIKE 'cli:%'",
+        `AND source NOT IN (${notIn})`,
+        'GROUP BY source ORDER BY n DESC',
+    ].join(' ');
+}
+/**
+ * The verbs `verbTrafficQuery()` deliberately cannot see, with the reason each one is invisible.
+ *
+ * ⚠ EXPORTED SO THE EXCLUSION IS REPORTABLE, NOT JUST APPLIED. A query that silently drops rows is
+ * the same shape as the defects this whole cluster is about; anyone reading the door table needs
+ * to be able to say WHY a verb is absent from it.
+ */
+export function unmeasurableVerbs() {
+    const out = Object.entries(VERB_SURFACE)
+        .filter(([, f]) => f.cls === 'STRUCTURAL' || f.cls === 'ADMIN_HTTP')
+        .map(([verb, f]) => ({
+        verb,
+        why: f.cls === 'ADMIN_HTTP'
+            ? 'getAdminClient — no agent identity, so no agent_activity row is ever written'
+            : 'never reaches the workspace',
+    }));
+    out.push({
+        verb: 'ask',
+        why: 'agent:message writes no row; the agent-prompt FALLBACK does — so the count measures '
+            + 'stream failures, not usage',
+    });
+    return out.sort((a, b) => a.verb.localeCompare(b.verb));
+}

package/dist/version-utils.js

@@ -0,0 +1,85 @@
+/**
+ * The sha256 an update manifest commits to, or null when it doesn't
+ * commit to one.
+ *
+ * `null` means DO NOT AUTO-UPDATE. The daemon used to execute
+ * `curl … | sh` on an hourly timer as soon as `latest.json` advertised a
+ * newer version — no digest, no signature, no prompt — so whatever the
+ * bucket served became code on every machine. An update that cannot be
+ * verified is now simply not installed; the user is told to run the
+ * installer deliberately instead.
+ *
+ * Strict on purpose: a truncated, upper-case-mixed or non-hex value is
+ * treated as absent rather than coerced, because "almost a digest" must
+ * never satisfy a check whose entire job is exactness.
+ */
+export function usableUpdateDigest(manifest) {
+    if (!manifest || typeof manifest !== 'object')
+        return null;
+    const raw = manifest.sha256;
+    if (typeof raw !== 'string')
+        return null;
+    const lowered = raw.trim().toLowerCase();
+    return /^[0-9a-f]{64}$/.test(lowered) ? lowered : null;
+}
+/**
+ * Compare two semver strings: >0 if a > b, <0 if a < b, 0 if equal.
+ *
+ * ⚠⚠ IT COULD NOT READ A PRERELEASE, AND THE FAILURE WAS SILENT AND BACKWARDS.
+ * `'0.7.7-rc.1'.split('.')` yields `['0','7','7-rc','1']`, `Number('7-rc')` is NaN, and `NaN || 0`
+ * is 0 — so a release candidate parsed as **0.7.0**. The consequences all point the wrong way:
+ * `rc.2` and `rc.1` compared EQUAL so an RC could never update to a later RC, and `0.8.0-rc.1`
+ * compared equal to the finished `0.8.0` so an RC machine would never come back to stable. This
+ * function gates `checkAndAutoUpdate`, so "equal" means "do nothing, forever".
+ *
+ * ⚠ A PRERELEASE IS LESS THAN ITS RELEASE — that is the whole point of the notation, and it is the
+ * rule that lets an RC upgrade INTO the stable build of the same number. Handled explicitly,
+ * because numeric comparison alone cannot express it: `1.0.0-rc.1` and `1.0.0` have identical
+ * numeric parts.
+ *
+ * ⚠ IDENTIFIERS COMPARE NUMERICALLY WHEN BOTH ARE NUMERIC, otherwise as strings — so `rc.10` sorts
+ * after `rc.9` rather than before it, which a plain string compare gets wrong.
+ *
+ * ⚠ THERE WAS A SECOND COPY of this in `first-party-hives.ts` that stripped the prerelease with
+ * `split('-')[0]` — different behaviour, same name, and neither knew about the other. It imports
+ * this one now.
+ */
+export function compareVersions(a, b) {
+    const split = (v) => {
+        const [core, ...rest] = String(v).trim().split('-');
+        return { nums: core.split('.').map((n) => Number(n) || 0), pre: rest.join('-') };
+    };
+    const x = split(a), y = split(b);
+    for (let i = 0; i < 3; i++) {
+        const diff = (x.nums[i] || 0) - (y.nums[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    // Numeric parts equal: absence of a prerelease wins.
+    if (!x.pre && !y.pre)
+        return 0;
+    if (!x.pre)
+        return 1;
+    if (!y.pre)
+        return -1;
+    const xi = x.pre.split('.'), yi = y.pre.split('.');
+    for (let i = 0; i < Math.max(xi.length, yi.length); i++) {
+        const p = xi[i], q = yi[i];
+        if (p === undefined)
+            return -1; // a shorter set of identifiers has lower precedence
+        if (q === undefined)
+            return 1;
+        const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+        if (pn && qn) {
+            const d = Number(p) - Number(q);
+            if (d !== 0)
+                return d;
+            continue;
+        }
+        if (pn !== qn)
+            return pn ? -1 : 1; // numeric identifiers are lower than alphanumeric ones
+        if (p !== q)
+            return p < q ? -1 : 1;
+    }
+    return 0;
+}

package/dist/watcher.js

@@ -0,0 +1,207 @@
+// ============================================================================
+// Beehaven Office - Claude Code Event Watcher
+// Primary: Unix domain socket HTTP server at /tmp/beehaven.sock
+// Fallback: Watches the JSONL events file written by the hook script
+// ============================================================================
+// chokidar is imported lazily so a missing bundle (e.g. when the daemon ships
+// inside an Electron app whose node_modules layout doesn't include chokidar)
+// degrades the file-watcher to a no-op rather than crashing the whole daemon.
+// The primary Unix-socket path does not depend on chokidar.
+import { createReadStream, existsSync, writeFileSync, statSync, renameSync, unlinkSync, chmodSync, watch as fsWatch, } from 'fs';
+import { createInterface } from 'readline';
+import { createServer } from 'http';
+import { EventEmitter } from 'events';
+const EVENTS_FILE = '/tmp/beehaven-events.jsonl';
+const SOCKET_PATH = '/tmp/beehaven.sock';
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+export { SOCKET_PATH };
+export class ClaudeWatcher extends EventEmitter {
+    lastSize = 0;
+    processing = false;
+    fsWatcher = null;
+    socketServer = null;
+    start() {
+        this.startSocket();
+        this.startFileWatcher();
+    }
+    /** Stop watching for events */
+    stop() {
+        this.stopSocket();
+        this.stopFileWatcher();
+    }
+    // ── Unix Domain Socket ───────────────────────────────────────────────
+    /** Start HTTP server on Unix domain socket for direct event delivery */
+    startSocket() {
+        // Remove stale socket file
+        try {
+            if (existsSync(SOCKET_PATH))
+                unlinkSync(SOCKET_PATH);
+        }
+        catch {
+            /* may not exist */
+        }
+        this.socketServer = createServer((req, res) => {
+            if (req.method !== 'POST' || req.url !== '/event') {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                try {
+                    const body = Buffer.concat(chunks).toString('utf8');
+                    const event = JSON.parse(body);
+                    this.emit('event', event);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end('{"ok":true}');
+                }
+                catch {
+                    res.writeHead(400);
+                    res.end('{"error":"invalid json"}');
+                }
+            });
+        });
+        this.socketServer.on('error', (err) => {
+            console.warn(`[watcher] Socket server error: ${err.message}`);
+        });
+        // Bind first, then chmod — changing process.umask is global and
+        // races with any other mkdirSync / writeFileSync happening in
+        // parallel (e.g. LocalHive creating per-building SQLite dirs
+        // during startup). A post-bind chmod achieves the same security
+        // without the race.
+        this.socketServer.listen(SOCKET_PATH, () => {
+            try {
+                chmodSync(SOCKET_PATH, 0o600);
+            }
+            catch { }
+            console.log(`[watcher] Socket listening on ${SOCKET_PATH}`);
+        });
+    }
+    /** Stop the Unix domain socket server */
+    stopSocket() {
+        if (this.socketServer) {
+            this.socketServer.close();
+            this.socketServer = null;
+        }
+        try {
+            if (existsSync(SOCKET_PATH))
+                unlinkSync(SOCKET_PATH);
+        }
+        catch {
+            /* may already be gone */
+        }
+    }
+    // ── File Watcher (fallback) ──────────────────────────────────────────
+    /** Start file watcher as fallback for when socket isn't available */
+    async startFileWatcher() {
+        // Create events file if it doesn't exist
+        if (!existsSync(EVENTS_FILE)) {
+            writeFileSync(EVENTS_FILE, '', { mode: 0o600 });
+        }
+        // Get initial file size
+        this.lastSize = statSync(EVENTS_FILE).size;
+        // Try chokidar (preferred: usePolling catches atomic writes). If it's
+        // not bundled with this daemon — e.g. running inside an Electron .app
+        // whose node_modules layout doesn't ship it — fall back to Node's
+        // built-in fs.watch. The daemon's IPC socket does not depend on this.
+        try {
+            const { watch } = await import('chokidar');
+            this.fsWatcher = watch(EVENTS_FILE, {
+                persistent: true,
+                usePolling: true,
+                interval: 100,
+            });
+            this.fsWatcher.on('change', () => {
+                this.readNewLines();
+            });
+            console.log(`[watcher] File watcher on ${EVENTS_FILE} (chokidar)`);
+        }
+        catch (err) {
+            // chokidar missing — use fs.watch instead. Less robust against
+            // editor atomic-write patterns, but good enough for a JSONL that
+            // is only ever appended to by the hook script.
+            try {
+                this.fsWatcher = fsWatch(EVENTS_FILE, { persistent: true }, () => {
+                    this.readNewLines();
+                });
+                console.log(`[watcher] File watcher on ${EVENTS_FILE} (fs.watch fallback — chokidar not bundled)`);
+            }
+            catch (e2) {
+                console.warn(`[watcher] Could not start file watcher: ${e2.message}`);
+                this.fsWatcher = null;
+            }
+        }
+        // Rotate oversized file on startup
+        this.rotateIfNeeded();
+    }
+    /** Stop file watcher */
+    stopFileWatcher() {
+        if (this.fsWatcher) {
+            this.fsWatcher.close();
+            this.fsWatcher = null;
+        }
+    }
+    // ── File rotation ────────────────────────────────────────────────────
+    /** Rotate the events file if it exceeds MAX_FILE_SIZE */
+    rotateIfNeeded() {
+        try {
+            const size = statSync(EVENTS_FILE).size;
+            if (size > MAX_FILE_SIZE) {
+                const rotated = `${EVENTS_FILE}.${Date.now()}.old`;
+                renameSync(EVENTS_FILE, rotated);
+                chmodSync(rotated, 0o600);
+                writeFileSync(EVENTS_FILE, '', { mode: 0o600 });
+                this.lastSize = 0;
+                console.log(`[watcher] Rotated events file (${(size / 1024 / 1024).toFixed(1)} MB) → ${rotated}`);
+            }
+        }
+        catch {
+            // File may not exist yet
+        }
+    }
+    async readNewLines() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        try {
+            const currentSize = statSync(EVENTS_FILE).size;
+            if (currentSize <= this.lastSize) {
+                // File was truncated or unchanged
+                if (currentSize < this.lastSize)
+                    this.lastSize = 0;
+                this.processing = false;
+                return;
+            }
+            const stream = createReadStream(EVENTS_FILE, {
+                start: this.lastSize,
+                encoding: 'utf8',
+            });
+            const rl = createInterface({ input: stream });
+            for await (const line of rl) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const event = JSON.parse(line);
+                    this.emit('event', event);
+                }
+                catch (err) {
+                    console.warn(`[watcher] Skipping malformed JSON line: ${line.slice(0, 100)}`, err.message);
+                }
+            }
+            this.lastSize = currentSize;
+            // Rotate if file has grown too large during this session
+            this.rotateIfNeeded();
+        }
+        catch (err) {
+            console.warn(`[watcher] File read error (resetting offset):`, err.message);
+            this.lastSize = 0;
+        }
+        this.processing = false;
+    }
+    /** Clear the events file */
+    clear() {
+        writeFileSync(EVENTS_FILE, '', { mode: 0o600 });
+        this.lastSize = 0;
+    }
+}