@clearlysh/beehaven 0.8.16

package/dist/commands/ticket.js

@@ -0,0 +1,1301 @@
+/**
+ * `beehaven ticket` AND `beehaven board` — the work verbs.
+ *
+ * ⚠⚠ WHY THESE EXIST WHEN `call` ALREADY WORKED. Measured on `agent_activity`: `ticket-create` 400,
+ * `ticket-update` 330, `board-list` 240 — **1,062 calls across tickets and boards, the second-largest
+ * domain in the workspace after the canvas** — against ZERO CLI verbs. Every ticket filed during the
+ * 2026-09-04 session was `beehaven call ticket-create '{…}'`, not by preference but because there was
+ * nothing else, and because the verb that sounds like it (`task`) calls `note-create` and makes a
+ * NOTE. One word, two objects, and the wrong one is what you got.
+ *
+ * ⚠ THIS IS NOT SYMMETRY. There is deliberately no `project` verb: a project IS a folder, `mkdir`
+ * already creates one and `ls` / `mv` / `cp -r` / `rm -r` cover the rest, and project traffic is ~85
+ * calls against 1,062. A `project` verb would be a second door to `mkdir` at a ninth of the usage —
+ * the failure this repo names over and over. Project METADATA stays `call project-update`.
+ *
+ * ⚠ AND NO `board show`. `cat ~/Sprint 1.board.json` already prints the board WITH its tickets; a
+ * second reader would be two doors to one read. What is here is what the filesystem cannot express.
+ *
+ * ⚠⚠ THE VERBS EXIST TO MAKE THE TRAPS UNTYPEABLE. Each one below is a documented, silent,
+ * already-shipped defect in this exact API, and a flag is the only place to kill it for good:
+ *
+ *   · PRIORITY IS 0-3 AND **3 IS MOST URGENT** — the OPPOSITE of the P0/P1 convention people write
+ *     in tags. A card meant to be top priority, filed as `priority: 0`, becomes the LEAST urgent
+ *     thing on the board and nothing says so. So this verb takes WORDS ONLY and never a number.
+ *   · `issueType`, NEVER `type` — the wire uses `type` as the ACTION discriminator, so a payload
+ *     field of that name is overwritten before the handler sees it. Measured once: every card sent
+ *     as `type:'epic'` stored `task`, and the whole hierarchy feature was inert while looking like
+ *     it worked.
+ *   · `body`, NEVER `description` — an unknown key is stripped by validation, so the card is
+ *     created with a title and nothing else.
+ *   · `boardId` IS REQUIRED — `ticket-create` refuses without one, because a ticket with no board
+ *     is a card you made, were told about, and cannot find.
+ */
+/**
+ * ⚠⚠ `agentRpc`, NOT `rpcOnce` — a bare `rpcOnce` runs as the ACCOUNT OWNER, not as the signed-in
+ * agent. It skips `agent-invoke`, and with it the per-agent gate and the activity log. Measured:
+ * two comments on one card seconds apart came back authored `agent:jinri-claude` (via
+ * `beehaven call`) and as a raw uid (via this verb) before this was fixed.
+ */
+import { agentRpc as rpcOnce } from './workspace.js';
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+};
+function getTimeout(values) {
+    const t = Number(values?.timeout);
+    return Number.isFinite(t) && t > 0 ? t : 30_000;
+}
+/** ⚠ `rpcOnce` returns `{ error }` as a VALUE and never throws — see `rpcFailure` in workspace.ts. */
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return null;
+    if (typeof res.error === 'string' && res.error)
+        return res.error;
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+function die(msg, hint) {
+    console.error(`  Error: ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+/**
+ * ⚠⚠ WORDS IN, NUMBER OUT — AND THE SCALE IS INVERTED FROM WHAT PEOPLE WRITE.
+ *
+ * `0 Low · 1 Medium · 2 High · 3 Urgent`. Anyone who has used a tracker writes P0 for "drop
+ * everything", so a number reaching this API unmediated is a coin flip on the most consequential
+ * field a card has (it drives the SLA: 3=1h, 2=4h, 1=24h, 0=72h). The verb therefore refuses a
+ * bare number rather than passing one through — a refusal is recoverable, a silently de-prioritised
+ * card is not.
+ */
+const PRIORITY = { low: 0, medium: 1, normal: 1, high: 2, urgent: 3, critical: 3 };
+/**
+ * ⚠⚠ THE READ SIDE AND THE WRITE SIDE MUST SHARE ONE TABLE, OR THE VERB CONTRADICTS ITSELF.
+ *
+ * `ticket show` printed `priority 3` — handing back the raw number that `resolvePriority`
+ * REFUSES on the way in, with the inversion explained at length. So the verb whose stated reason
+ * for existing is "make the 0-3 trap untypeable" was the one surface re-exposing it: a reader who
+ * files `high` and later sees `priority 2` has every reason to read that as P2, i.e. lowish —
+ * the precise misreading the guard was built to prevent.
+ *
+ * ⚠ DERIVED FROM `PRIORITY`, NOT A SECOND LITERAL LIST. A hand-written `['low','medium',…]` beside
+ * the map is two tables for one scale, and the day someone renumbers one the other keeps printing
+ * the old word with nothing to notice.
+ *
+ * ⚠ `normal` AND `critical` ARE ALIASES ON THE WAY IN AND MUST NOT WIN ON THE WAY OUT. They share
+ * numbers with `medium` and `urgent`, so the label is taken from the FIRST word that maps to each
+ * value — the canonical four the help text advertises.
+ */
+export const PRIORITY_LABELS = (() => {
+    const out = [];
+    for (const [word, n] of Object.entries(PRIORITY))
+        if (out[n] === undefined)
+            out[n] = word;
+    return out;
+})();
+/**
+ * The word for a stored priority.
+ *
+ * ⚠ AN OFF-SCALE VALUE IS SHOWN, NOT GUESSED. Clamping 7 to `urgent` would invent a fact; printing
+ * `7 (off-scale — 0 low … 3 urgent)` says exactly what is stored and what the scale is, which is
+ * the one thing a reader of a surprising number needs.
+ */
+export function priorityLabel(v) {
+    const n = typeof v === 'number' ? v : Number(String(v ?? '').trim());
+    const word = Number.isInteger(n) ? PRIORITY_LABELS[n] : undefined;
+    if (word)
+        return word;
+    return `${v} (off-scale — 0 ${PRIORITY_LABELS[0]} … ${PRIORITY_LABELS.length - 1} ${PRIORITY_LABELS[PRIORITY_LABELS.length - 1]})`;
+}
+/**
+ * The date for a stored `dueAt`.
+ *
+ * ⚠ `0` IS "NO DUE DATE", AND PRINTING IT RAW READS AS A DATE IN 1970 — or, worse, as a field the
+ * reader has to decode. Every card without a due date carried `dueAt 0`.
+ *
+ * ⚠ AN UNPARSEABLE VALUE IS RETURNED AS ITSELF. Guessing between seconds and milliseconds would
+ * put a card's deadline half a century out with nothing to say so; showing the raw value is
+ * recoverable.
+ */
+export function dueLabel(v) {
+    if (v === 0 || v === '0' || v === undefined || v === null || v === '')
+        return 'none';
+    const n = typeof v === 'number' ? v : Number(String(v).trim());
+    if (!Number.isFinite(n))
+        return String(v);
+    const d = new Date(n);
+    if (Number.isNaN(d.getTime()))
+        return String(v);
+    return `${d.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+function resolvePriority(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const s = String(v).trim().toLowerCase();
+    if (s in PRIORITY)
+        return PRIORITY[s];
+    if (/^\d+$/.test(s)) {
+        die(`--priority takes a word, not a number (you passed ${s}).`, 'The scale is inverted from P0/P1: 0 is LOW and 3 is URGENT. Use low | medium | high | urgent.');
+    }
+    die(`unknown priority "${v}"`, 'Use one of: low, medium, high, urgent.');
+}
+const STATUSES = ['todo', 'in-progress', 'in-review', 'done'];
+const TYPES = ['epic', 'story', 'task', 'bug', 'subtask'];
+const SPRINT_STATES = ['planned', 'active', 'completed'];
+const REPORT_KINDS = ['summary', 'velocity', 'burndown', 'cycle-time'];
+/**
+ * ⚠⚠ `--due` MUST REACH THE WIRE AS A NUMBER, AND THE TWO VERBS DISAGREED ABOUT THAT — CBH2-109.
+ *
+ * `ticket-create` writes `due_at: input.dueAt || 0` with no coercion, so a string goes STRAIGHT
+ * INTO the column. `ticket-update` writes it only `if (typeof input.updates.dueAt === 'number')`,
+ * so a string is silently dropped. One flag, two handlers, two different wrong answers:
+ *
+ *     beehaven call ticket-create '{…,"dueAt":"2026-10-01"}'
+ *     → SELECT due_at, typeof(due_at)  →  "2026-10-01" | text     (measured, 2026-09-06)
+ *
+ * The column is epoch milliseconds everywhere else — `dueLabel` above renders it as one and
+ * `response_due_at` is computed in ms — so a text value there is a deadline no comparison can
+ * see. This verb parses ONCE, on the way in, for both create and edit.
+ *
+ * ⚠ A BARE NUMBER IS TAKEN AS EPOCH MS, NOT GUESSED BETWEEN SECONDS AND MILLISECONDS. `dueLabel`
+ * already refuses to guess on the way out for the same reason: a factor-of-1000 mistake puts a
+ * deadline half a century away and looks like a plausible date.
+ *
+ * ⚠ AN UNPARSEABLE VALUE IS REFUSED, NOT PASSED THROUGH. Passing it through is exactly what
+ * produced the text row above.
+ */
+export function resolveDue(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    const s = String(v).trim();
+    if (/^\d+$/.test(s))
+        return Number(s);
+    const ms = Date.parse(s);
+    if (Number.isFinite(ms))
+        return ms;
+    die(`--due "${s}" is not a date`, 'Use an ISO date (2026-10-01), a full timestamp (2026-10-01T09:00:00Z), or epoch milliseconds.');
+}
+/**
+ * ⚠⚠ THE CARD LIST WAS CAPPED AT 100 IN THE CLIENT WITH NOTHING SAID — CBH2-112.
+ *
+ * `rows.slice(0, 100)` printed a hundred cards and then a truthful-looking `N card(s)` count, so
+ * a 300-card board was INDISTINGUISHABLE from a 100-card board. The server was never the
+ * constraint: `ticket-list` defaults to 100 and caps at 500, and takes a `limit`.
+ *
+ * ⚠ THE CEILING IS CLAMPED AND ANNOUNCED, NOT SILENTLY APPLIED. The server does
+ * `Math.min(input.limit ?? 100, 500)` with no notice of its own, so asking for 900 and being
+ * handed 500 is the original defect one layer down. Every clamp prints.
+ */
+const LIST_DEFAULT = 100;
+/** The server's own ceiling — `Math.min(input.limit ?? 100, 500)` in `ticketList`. */
+export const LIST_MAX = 500;
+export function resolveLimit(v) {
+    if (v === undefined || v === null || v === '')
+        return { limit: LIST_DEFAULT, clamped: false };
+    const s = String(v).trim();
+    const n = Number(s);
+    if (!Number.isInteger(n) || n < 1) {
+        die(`--limit takes a whole number of cards (you passed ${s}).`, `Between 1 and ${LIST_MAX}.`);
+    }
+    return n > LIST_MAX ? { limit: LIST_MAX, clamped: true } : { limit: n, clamped: false };
+}
+/**
+ * A sprint, by id OR by name.
+ *
+ * ⚠ NAMES, BECAUSE A SPRINT ID IS A UUID AND NOTHING ELSE EVER SHOWS YOU ONE. `sprint-create`
+ * returns `{ id, name }` and `sprint-list` prints both, but the thing a person or an agent says
+ * out loud is "Sprint 3". Requiring the uuid is the trap `resolveBoard` exists to close for
+ * boards, one object over.
+ *
+ * ⚠ AMBIGUITY IS REFUSED, NEVER GUESSED. Auto-numbering means two boards routinely both hold a
+ * "Sprint 1"; picking one would start or DELETE the wrong sprint. `--board` narrows it.
+ */
+async function resolveSprint(ref, values) {
+    const t = getTimeout(values);
+    const wanted = String(ref ?? '').trim();
+    if (!wanted)
+        die('a sprint is required', 'beehaven sprint list — to see the names');
+    const board = values.board ? await resolveBoard(values) : null;
+    const res = await rpcOnce('sprint-list', { ...(board ? { boardId: board.id } : {}) }, t);
+    const f = failure(res);
+    if (f)
+        die(f);
+    const rows = res?.sprints ?? [];
+    const byId = rows.find((s) => String(s.id) === wanted);
+    if (byId)
+        return { id: String(byId.id), name: String(byId.name ?? ''), state: String(byId.state ?? '') };
+    const named = rows.filter((s) => String(s.name ?? '').toLowerCase() === wanted.toLowerCase());
+    if (named.length === 1) {
+        return { id: String(named[0].id), name: String(named[0].name ?? ''), state: String(named[0].state ?? '') };
+    }
+    if (named.length > 1) {
+        die(`"${wanted}" names ${named.length} sprints`, 'Narrow it with --board <board>, or pass the sprint id (beehaven sprint list).');
+    }
+    const names = rows.map((s) => String(s.name ?? '')).filter(Boolean);
+    die(`no sprint called "${wanted}"`, names.length
+        ? `Sprints: ${names.slice(0, 10).join(', ')}${names.length > 10 ? ` … and ${names.length - 10} more` : ''}`
+        : 'There are no sprints yet — beehaven sprint create "Sprint 1" --board <board>');
+}
+/**
+ * ⚠⚠ `sprint-plan` TAKES ROW IDS AND REPORTS SUCCESS FOR A KEY IT NEVER MOVED. MEASURED:
+ *
+ *     beehaven call sprint-plan '{"sprintId":"a53e…","add":["CBH2-107"]}'
+ *     → { ok: true, moved: 1 }        …and `SELECT sprint_id` on that card is still ''.
+ *
+ * The handler does `this.updateRow('tickets', id, …)` inside a `try`, increments its counter
+ * unconditionally, and swallows the miss. A key is the ONLY address anybody quotes — it is what
+ * `ticket-create` returns and what this file's own receipts print — so the natural call is the
+ * one that silently does nothing while answering `ok`.
+ *
+ * So this verb resolves every reference to a ROW id first and REFUSES on one it cannot find,
+ * naming it. A planning verb that reports moving work it did not move is worse than one that
+ * refuses.
+ *
+ * ⚠ `ticket-get` PER CARD, not a list scan: it resolves a key or a row id already (`resolveTicketRef`),
+ * so one call answers both shapes and cannot disagree with the server about what a key means.
+ */
+async function resolveCardIds(refs, values) {
+    const t = getTimeout(values);
+    const out = [];
+    for (const ref of refs) {
+        const res = await rpcOnce('ticket-get', { id: ref }, t);
+        const f = failure(res);
+        if (f)
+            die(`${ref}: ${f}`, 'Cards are addressed by key (CLR-42) or row id — beehaven ticket list');
+        const id = String(res?.id ?? '');
+        if (!id)
+            die(`no card called "${ref}"`, 'beehaven ticket list — to see the keys');
+        out.push({ id, key: String(res?.key ?? ref) });
+    }
+    return out;
+}
+/**
+ * ⚠⚠ THE ONE BOARD-RESOLUTION RULE — oldest non-archived board, else create one.
+ *
+ * `ticket-create` refuses a null `boardId`, and four client call sites each invented their own
+ * answer to that before this rule was written down (three of them sent nothing and would have
+ * broken silently in production). This is that rule, in the CLI, once.
+ *
+ * ⚠ IT PREFERS THE OLDEST, not the newest. A workspace's first board is the one people mean by
+ * "the board"; the newest is whatever some script made last.
+ */
+/**
+ * ⚠⚠ `opts.named` IS WHAT KEEPS A DESTRUCTIVE VERB OFF THE FALLBACK. With no `--board` this
+ * function picks the OLDEST board in the workspace — exactly right for filing a card, and
+ * catastrophic for `board delete`, which would then destroy a board nobody named. A caller that
+ * cannot survive a guess passes `named: true` and gets a refusal instead.
+ *
+ * ⚠ `includeArchived` EXISTS FOR THE SAME VERB. Archiving is how boards are retired today, so the
+ * boards most worth deleting are precisely the ones the default filter hides — a delete that
+ * cannot see them can only ever grow the collection.
+ */
+async function resolveBoard(values, opts = {}) {
+    const t = getTimeout(values);
+    const wanted = typeof values.board === 'string' ? values.board.trim() : '';
+    if (opts.named && !wanted) {
+        die('name the board', 'beehaven board list — then pass its title or id.');
+    }
+    const list = await rpcOnce('board-list', opts.includeArchived ? { includeArchived: true } : {}, t);
+    const f = failure(list);
+    if (f)
+        die(f);
+    const isArchived = (b) => String(b?.is_archived ?? '') === 'true';
+    const boards = (list?.boards ?? list?.rows ?? list?.items ?? [])
+        .filter((b) => opts.includeArchived || !isArchived(b));
+    if (wanted) {
+        const hit = boards.find((b) => String(b.id) === wanted)
+            ?? boards.find((b) => String(b.title ?? '').toLowerCase() === wanted.toLowerCase());
+        if (!hit) {
+            /**
+             * ⚠ CAPPED. This workspace has 60+ boards and the uncapped version printed every title on
+             * one line — a "help" message longer than the terminal, which is the same as no help. Ten
+             * names plus a count is readable; `board list` is where the full set belongs.
+             */
+            const names = boards.map((b) => String(b.title ?? '')).filter(Boolean);
+            const shown = names.slice(0, 10).join(', ');
+            die(`no board called "${wanted}"`, names.length
+                ? `Boards: ${shown}${names.length > 10 ? ` … and ${names.length - 10} more (beehaven board list)` : ''}`
+                : 'There are no boards yet — one will be made for you if you omit --board.');
+        }
+        return { id: String(hit.id), title: String(hit.title ?? ''), archived: isArchived(hit) };
+    }
+    if (boards.length) {
+        /**
+         * ⚠ OLDEST, NOT NEWEST — a workspace's first board is what people mean by "the board"; the
+         * newest is whatever a script made last. Same rule the four client call sites follow.
+         *
+         * ⚠ AND THE CALLER IS TOLD WHICH. With no project context this is a guess across every board
+         * in the workspace, so the card's receipt names the board (`Filed SOU-8 · Sources`) — a card
+         * filed somewhere you did not choose and were not told about is the invisible-ticket failure
+         * `ticket-create` started refusing null boards to prevent.
+         */
+        const oldest = boards.slice().sort((a, b) => Number(a.created_at ?? 0) - Number(b.created_at ?? 0))[0];
+        return { id: String(oldest.id), title: String(oldest.title ?? ''), archived: isArchived(oldest) };
+    }
+    // ⚠ CREATED, NOT REFUSED. Nobody sets out to make an empty board — they set out to write down a
+    //   piece of work, and a refusal here would make the first ticket in a workspace impossible.
+    const made = await rpcOnce('board-create', { title: 'Backlog', personal: true }, t);
+    const mf = failure(made);
+    if (mf)
+        die(mf, 'Could not create a board to put this ticket on.');
+    return { id: String(made?.id ?? made?.board?.id ?? ''), title: 'Backlog', archived: false };
+}
+export async function cmdTicket(sub, rest, values) {
+    const t = getTimeout(values);
+    if (!sub || sub === 'help') {
+        console.log(`
+  ${c.cyan('beehaven ticket')} — cards on a board
+
+    ticket create "<title>"     Open a card  (--board --body --type --priority --status --assignee
+                                --due --allow-duplicate)
+    ticket list                 Cards on a board  (--board --status --text --key --assignee --limit, max ${LIST_MAX})
+    ticket move <key> [status]  ${STATUSES.join(' | ')}   (--board to move it to another board)
+    ticket edit <key>           Change a card  (--title --body --type --priority --assignee --due
+                                --points --epic --parent --sprint --resolution)
+    ticket show <key>           One card
+    ticket comment <key> "…"     Leave a note  (--reply <id>)
+    ticket comments <key>       Read the notes  (--all for resolved)
+    ticket delete <key>         Destroy a card  (shows it; needs --yes to go through)
+
+  ${c.dim(`--priority takes a WORD: low | medium | high | urgent.`)}
+  ${c.dim(`--type takes: ${TYPES.join(' | ')}.`)}
+  ${c.dim('WHERE a card is lives on `move` (status and board); WHAT it says lives on `edit`.')}
+  ${c.dim('Read a whole board including its cards with:  cat "~/<Board>.board.json"')}
+`);
+        return;
+    }
+    if (sub === 'create') {
+        const title = rest.join(' ').trim();
+        if (!title)
+            die('a title is required', 'beehaven ticket create "Fix the login redirect"');
+        const board = await resolveBoard(values);
+        const issueType = typeof values.type === 'string' ? values.type.trim().toLowerCase() : '';
+        if (issueType && !TYPES.includes(issueType))
+            die(`unknown type "${issueType}"`, `Use one of: ${TYPES.join(', ')}.`);
+        const status = typeof values.status === 'string' ? values.status.trim().toLowerCase() : '';
+        if (status && !STATUSES.includes(status))
+            die(`unknown status "${status}"`, `Use one of: ${STATUSES.join(', ')}.`);
+        const priority = resolvePriority(values.priority);
+        const due = resolveDue(values.due);
+        const res = await rpcOnce('ticket-create', {
+            boardId: board.id,
+            title,
+            // ⚠ `body`, NEVER `description` — an unknown key is stripped and the card loses its detail.
+            ...(values.body ? { body: String(values.body) } : {}),
+            // ⚠ `issueType`, NEVER `type` — `type` is the wire's action discriminator.
+            ...(issueType ? { issueType } : {}),
+            ...(status ? { status } : {}),
+            ...(priority !== undefined ? { priority } : {}),
+            ...(values.assignee ? { assignee: String(values.assignee) } : {}),
+            // ⚠ A NUMBER, NEVER THE RAW STRING — see `resolveDue`. `ticket-create` writes this column
+            //   with no coercion at all, so `--due 2026-10-01` used to store TEXT in an epoch-ms column.
+            ...(due !== undefined ? { dueAt: due } : {}),
+            /**
+             * ⚠⚠ THE FLAG THE NEXT FEW LINES ADVERTISE HAS TO EXIST — CBH2-110. The duplicate branch
+             * below printed *"Pass --allow-duplicate if you meant a second card"* while `parseArgs`
+             * had no such option and FATALS on an undeclared one, so following the CLI's own printed
+             * instruction exited 1. Printing an instruction a caller cannot carry out is worse than
+             * printing nothing; the server has supported `allowDuplicate` throughout.
+             */
+            ...(values['allow-duplicate'] ? { allowDuplicate: true } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        /**
+         * ⚠ SAY THE BOARD, NOT ONLY THE KEY. A ticket's key records where it was BORN and never
+         * follows it between boards, so `ticket-create` returns the CURRENT board beside the key
+         * precisely so a caller can print both without a second lookup. Dropping it here would be
+         * throwing away the mitigation.
+         */
+        const key = String(res?.key ?? '');
+        const where = String(res?.board ?? board.title ?? '');
+        if (res?.duplicate) {
+            // ⚠ A duplicate is `ok: true` — reporting it as a fresh create is how you get two people
+            //   working the same card believing they each opened one.
+            console.log(`  ${c.yellow('Already open')}: ${c.cyan(key)}${where ? ` · ${where}` : ''}`);
+            console.log(c.dim('  Pass --allow-duplicate if you meant a second card.'));
+            return;
+        }
+        console.log(`  Filed ${c.cyan(key)}${where ? ` · ${where}` : ''}`);
+        if (res?.priorityCoerced) {
+            const p = res.priorityCoerced;
+            console.log(c.dim(`  priority ${p.sent} stored as ${p.stored} — ${p.scale}`));
+        }
+        return;
+    }
+    if (sub === 'list') {
+        const board = values.board ? await resolveBoard(values) : null;
+        const { limit, clamped } = resolveLimit(values.limit);
+        const res = await rpcOnce('ticket-list', {
+            ...(board ? { boardId: board.id } : {}),
+            ...(values.status ? { status: String(values.status) } : {}),
+            ...(values.text ? { text: String(values.text) } : {}),
+            ...(values.key ? { key: String(values.key) } : {}),
+            ...(values.assignee ? { assignee: String(values.assignee) } : {}),
+            ...(values.cursor ? { cursor: String(values.cursor) } : {}),
+            ...(values.fields ? { fields: String(values.fields).split(',').map((s) => s.trim()).filter(Boolean) } : {}),
+            ...(values.summary ? { summary: true } : {}),
+            ...(values['count-only'] || values.countOnly ? { countOnly: true } : {}),
+            limit,
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        if (res?.summary) {
+            console.log(JSON.stringify(res.summary, null, 2));
+            if (res.nextCursor)
+                console.log(c.dim(`  next cursor: ${res.nextCursor}`));
+            return;
+        }
+        if (values['count-only'] || values.countOnly) {
+            console.log(`  ${res?.count ?? 0} card(s)`);
+            return;
+        }
+        const rows = res?.tickets ?? res?.rows ?? res?.items ?? [];
+        if (!rows.length) {
+            console.log('  No cards.');
+            return;
+        }
+        console.log('');
+        /**
+         * ⚠⚠ EVERY RETURNED ROW IS PRINTED. The old `rows.slice(0, 100)` was a SECOND, invisible cap
+         * underneath the server's — it printed a hundred cards and then a `N card(s)` count that
+         * looked like the whole answer. The bound is the one the caller asked for, and it is stated.
+         */
+        for (const r of rows) {
+            const key = String(r.key ?? '').padEnd(9);
+            const st = String(r.status ?? '').padEnd(12);
+            console.log(`  ${c.cyan(key)} ${c.dim(st)} ${String(r.title ?? '')}`);
+        }
+        console.log(c.dim(`\n  ${rows.length} card(s)`));
+        if (clamped) {
+            console.log(c.dim(`  --limit was clamped to ${LIST_MAX} — ticket-list will not return more in one call.`));
+        }
+        /**
+         * ⚠⚠ A FULL PAGE IS NOT AN ANSWER, AND SAYING SO IS THE WHOLE FIX. `rows.length === limit`
+         * means the list stopped because it ran out of budget, not because it ran out of cards — the
+         * one state the old output could not distinguish from a complete board.
+         *
+         * ⚠ THE HINT MUST BE FOLLOWABLE. At the ceiling there is no bigger `--limit` to suggest, so it
+         * names the filters instead; below the ceiling it names the flag.
+         */
+        if (res?.nextCursor)
+            console.log(c.dim(`  next cursor: ${res.nextCursor}`));
+        if (rows.length >= limit) {
+            console.log(c.dim(limit >= LIST_MAX
+                ? `  that is the whole page — ${LIST_MAX} is ticket-list's ceiling, so narrow with --board or --status to see the rest.`
+                : `  that is the whole page — there may be more. Raise it with --limit (max ${LIST_MAX}).`));
+        }
+        return;
+    }
+    /**
+     * ⚠⚠ ONE VERB, TWO AXES — AND THERE IS DELIBERATELY NO `board move`.
+     *
+     * A column and a board are both "where the card is", and the thing that MOVES is the TICKET.
+     * `board move` would name the wrong object — it reads as moving the board. `mv` in a shell
+     * relocates and renames through one verb for the same reason.
+     *
+     *   ticket move <key> done                 column
+     *   ticket move <key> --board "Sprint 2"   board
+     *   ticket move <key> done --board "…"     both
+     */
+    if (sub === 'move') {
+        const key = rest[0];
+        const status = (rest[1] ?? '').trim().toLowerCase();
+        const toBoard = typeof values.board === 'string' && values.board.trim() ? values.board.trim() : '';
+        if (!key)
+            die('usage: beehaven ticket move <key> [<status>] [--board <board>]', `Statuses: ${STATUSES.join(' | ')}`);
+        if (!status && !toBoard) {
+            die('nothing to move it to', `Pass a status (${STATUSES.join(' | ')}) or --board <board>.`);
+        }
+        if (status && !STATUSES.includes(status))
+            die(`unknown status "${status}"`, `Use one of: ${STATUSES.join(', ')}.`);
+        const board = toBoard ? await resolveBoard({ ...values, board: toBoard }) : null;
+        // ⚠ `updates` IS A NESTED PARTIAL — a flat `{ id, status }` is silently ignored by the handler.
+        const res = await rpcOnce('ticket-update', {
+            id: key,
+            updates: { ...(status ? { status } : {}), ...(board ? { boardId: board.id } : {}) },
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const parts = [status, board ? `board ${board.title}` : ''].filter(Boolean);
+        console.log(`  ${c.cyan(key)} → ${parts.join(' · ')}`);
+        /**
+         * ⚠⚠ THE KEY DOES NOT FOLLOW THE CARD, AND THIS IS THE ONLY PLACE ANYONE SEES THAT.
+         *
+         * `tickets.key` forbids re-keying — a key that comes back pointing at different work turns
+         * every historical mention of it into a quiet lie — so the PREFIX records where a card was
+         * BORN, never where it lives now. Verified: MA-1 moved from "MoveTest A" to "MoveTest B" and
+         * stayed MA-1. Silently, that reads as the move having failed.
+         */
+        if (board) {
+            console.log(c.dim(`  keeps the key ${key} — a key records where a card was created, not where it lives`));
+        }
+        return;
+    }
+    if (sub === 'show') {
+        const key = rest[0];
+        if (!key)
+            die('usage: beehaven ticket show <key>');
+        /**
+         * ⚠⚠ `ticket-get`, NOT A CLIENT-SIDE FILTER OVER `ticket-list`. This verb originally listed
+         * EVERY card in the workspace and picked one out in JS, because on 2026-09-04 there was no
+         * single-card read at all — `ticket-list` was the only way in. Writing that workaround is what
+         * revealed the verb was MISSING rather than badly named, and `ticket-get` was added for it.
+         *
+         * ⚠ The server also returns the card's CURRENT board, which a client-side filter had no cheap
+         * way to resolve — a key records where a card was born and never follows it between boards.
+         */
+        const res = await rpcOnce('ticket-get', { id: key }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log('');
+        /**
+         * ⚠ `issueType`, never `type` — the transport envelope's `type: 'ack'` shadows it.
+         *
+         * ⚠⚠ TWO FIELDS ARE STORED AS NUMBERS AND MEAN WORDS. `String(v)` was correct for the other
+         * seven and silently wrong for these two: `priority 3` re-exposes the inverted scale this verb
+         * exists to hide, and `dueAt 0` shows a sentinel where "none" is meant. The renderers are
+         * exported so the mapping is asserted by running it, not by grepping this loop.
+         */
+        const RENDER = { priority: priorityLabel, dueAt: dueLabel };
+        for (const k of ['key', 'title', 'board', 'status', 'issueType', 'priority', 'assignee', 'dueAt', 'body']) {
+            const v = res[k];
+            if (v === undefined || v === null || v === '')
+                continue;
+            console.log(`  ${c.dim(k.padEnd(10))} ${RENDER[k] ? RENDER[k](v) : String(v)}`);
+        }
+        console.log('');
+        return;
+    }
+    /**
+     * ⚠⚠ A CARD COULD BE FILED AND NEVER REMOVED — CBH2-141. `ticket-delete` has been registered and
+     * allowlisted throughout; there was simply no verb, so the CLI could create cards forever and
+     * take none back. Same shape as CBH2-111 for boards, one object down.
+     *
+     * ⚠⚠ IT WAS LEFT OUT OF CBH2-111 RATHER THAN SWEPT IN, because the safe shape was a DECISION and
+     * the action's one-line description ("Delete a board card (ticket) by id.") answers none of it.
+     * The four facts below were established by CALLING it against a real workspace on 2026-09-06,
+     * not read off the schema — and one of them contradicts what a reader would assume:
+     *
+     *   1. IT RESOLVES A KEY. `{"id":"CBH2-146"}` deleted the card and returned BOTH `id` and `key`.
+     *      So this verb takes the same reference every other `ticket` subcommand takes, and does NOT
+     *      have the row-id-only trap CBH2-137 records for `sprint-plan`.
+     *   2. IT IS A HARD DELETE. The row is gone from `tickets` — verified by SQL, not inferred from
+     *      the reply. There is no archive flag, no trash, and nothing to restore from.
+     *   3. IT IS NOT IDEMPOTENT. A second delete answers `ok:false, code:'not-found'`, identical to
+     *      a typo'd key. So a retry after a timeout cannot be distinguished from a wrong key.
+     *   4. ⚠⚠ COMMENTS ARE ORPHANED, NOT REMOVED. A comment left on a deleted card survives in
+     *      `ticket-comments`, addressed to a ticket id that resolves to nothing — unreachable and
+     *      permanent. Filed separately; the preview states it because the person about to destroy
+     *      the card is the only one who can decide whether that matters.
+     *
+     * ⚠⚠ SO IT PREVIEWS BY DEFAULT AND NEEDS `--yes`, WHICH IS NOT THE `board delete` SHAPE. Board
+     * deletion is safe to fire because the SERVER refuses while any card references it; nothing
+     * equivalent protects a card, and (2)+(3) together mean a mistake is unrecoverable AND
+     * indistinguishable from a typo afterwards. The same dry-run-by-default rule the workspace's own
+     * destructive operator verbs follow (`thought-vacuum`, `notes-repair-timestamps`).
+     *
+     * ⚠ THE PREVIEW SHOWS THE CARD, IT DOES NOT MERELY REFUSE. A key is opaque — `CBH2-146` and
+     * `CBH2-147` differ by one character and name different work — so the one thing a confirmation
+     * must do here is prove the key names what the caller thinks it does. A bare "pass --yes" makes
+     * the second attempt exactly as blind as the first.
+     */
+    if (sub === 'delete') {
+        const key = rest[0];
+        if (!key)
+            die('usage: beehaven ticket delete <key> --yes', 'The key is the one `ticket list` prints.');
+        /**
+         * ⚠ RESOLVED FIRST, ON BOTH PATHS. Without this, `--yes` on a mistyped key reaches the server
+         * and comes back `not-found` — the same answer a card someone else already deleted gives, and
+         * neither tells you which happened. Reading it first turns that into "no such card" BEFORE
+         * anything is destroyed.
+         */
+        const got = await rpcOnce('ticket-get', { id: key }, t);
+        const gf = failure(got);
+        if (gf)
+            die(gf, `Is that the key \`ticket list\` prints? Nothing was deleted.`);
+        const label = `${c.cyan(String(got.key ?? key))}  ${String(got.title ?? '')}`.trim();
+        const board = got.board ? `  ${c.dim(`board ${got.board}`)}` : '';
+        if (!values.yes) {
+            console.log('');
+            console.log(`  Would delete  ${label}${board}`);
+            console.log('');
+            console.log(`  ${c.yellow('This is permanent')} — the row is destroyed, not archived, and there is no restore.`);
+            console.log(`  ${c.dim('Its comments are NOT removed with it; they survive addressed to a card that no longer exists.')}`);
+            console.log('');
+            console.log(`  ${c.dim(`Go ahead with:  beehaven ticket delete ${got.key ?? key} --yes`)}`);
+            console.log('');
+            process.exit(1);
+        }
+        const res = await rpcOnce('ticket-delete', { id: key }, t);
+        const f = failure(res);
+        /**
+         * ⚠ A `not-found` HERE MEANS SOMETHING ELSE THAN IT DID ABOVE. The card resolved moments ago,
+         * so it was deleted in between — worth saying, because the bare server text reads as a typo.
+         */
+        if (f)
+            die(f, `It resolved a moment ago, so it was removed between the read and the delete.`);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Deleted ${label}${board}`);
+        return;
+    }
+    /**
+     * ⚠⚠ A CARD COULD BE CREATED AND NEVER CHANGED — CBH2-109.
+     *
+     * `ticket move` was the CLI's only update path and it sends `{ status?, boardId? }` and nothing
+     * else, so `--body`, `--priority`, `--assignee`, `--due` and `--type` were settable ONLY at
+     * create time and points / epic / parent had no flag at all. The web has full edit; the server
+     * has accepted all of it throughout (`UPDATABLE` in `ticketUpdate`). This was a CLI-side hole.
+     *
+     * ⚠⚠ IT DELIBERATELY TAKES NEITHER `--status` NOR `--board` — those are `ticket move`, and two
+     * verbs writing one field is the two-doors failure this file names in its own header. The split
+     * is WHERE a card is (move) against WHAT it says (edit), which is also why `move` keeps both of
+     * its axes rather than shedding `--board` to here.
+     *
+     * ⚠ AN EMPTY EDIT IS REFUSED. The server answers `no-updates` with a helpful hint, but a round
+     * trip to be told you typed nothing is a round trip; and `ticket edit CLR-42` with no flags is
+     * far more likely to be a forgotten flag than a deliberate no-op.
+     */
+    if (sub === 'edit') {
+        const key = rest[0];
+        if (!key) {
+            die('usage: beehaven ticket edit <key> [--title …] [--body …] [--priority …]', 'Status and board live on `ticket move` — this verb changes what a card SAYS.');
+        }
+        if (values.status !== undefined || values.board !== undefined) {
+            die('`ticket edit` does not move a card', `Use: beehaven ticket move ${key} <${STATUSES.join('|')}> [--board <board>]`);
+        }
+        const issueType = typeof values.type === 'string' ? values.type.trim().toLowerCase() : '';
+        if (issueType && !TYPES.includes(issueType))
+            die(`unknown type "${issueType}"`, `Use one of: ${TYPES.join(', ')}.`);
+        const priority = resolvePriority(values.priority);
+        const due = resolveDue(values.due);
+        /**
+         * ⚠ `points` IS A TOP-LEVEL COLUMN, and a non-number there is what makes `board-report` read
+         * zero for a board somebody carefully sized — the report's own docstring records that trap.
+         */
+        let points;
+        if (values.points !== undefined && values.points !== '') {
+            const n = Number(String(values.points).trim());
+            if (!Number.isFinite(n) || n < 0)
+                die(`--points takes a number (you passed ${String(values.points)}).`);
+            points = n;
+        }
+        const updates = {
+            ...(values.title ? { title: String(values.title) } : {}),
+            // ⚠ `body`, NEVER `description` — an unknown key is stripped and the edit silently does nothing.
+            ...(values.body ? { body: String(values.body) } : {}),
+            // ⚠ `issueType`, NEVER `type` — `type` is the wire's action discriminator.
+            ...(issueType ? { issueType } : {}),
+            ...(priority !== undefined ? { priority } : {}),
+            ...(values.assignee ? { assignee: String(values.assignee) } : {}),
+            ...(due !== undefined ? { dueAt: due } : {}),
+            ...(points !== undefined ? { points } : {}),
+            ...(values.epic ? { epicId: String(values.epic) } : {}),
+            ...(values.parent ? { parentId: String(values.parent) } : {}),
+            ...(values.sprint ? { sprintId: String(values.sprint) } : {}),
+            /**
+             * ⚠ `resolution` EXISTS BECAUSE A CARD CLOSED WITH NO REASON IS INDISTINGUISHABLE FROM ONE
+             * LOST. The column sat unreachable until 2026-08-25 and the reason had to go in `body`,
+             * where it is indistinguishable from the original report on every future read.
+             */
+            ...(values.resolution ? { resolution: String(values.resolution) } : {}),
+        };
+        if (!Object.keys(updates).length) {
+            die('nothing to change', 'Pass at least one of --title --body --type --priority --assignee --due --points --epic --parent --sprint --resolution.');
+        }
+        // ⚠ `updates` IS A NESTED PARTIAL — a flat `{ id, title }` is lifted by the handler, but only
+        //   for fields on its own allowlist; nesting is the shape the server documents.
+        const res = await rpcOnce('ticket-update', { id: key, updates }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        /**
+         * ⚠ SAY WHAT MOVED, NOT "updated". A field list is the only thing that distinguishes an edit
+         * that landed from one whose flag was misspelled into a different field.
+         */
+        const changed = Object.keys(updates).map((k) => (k === 'dueAt' ? `due ${dueLabel(updates[k])}`
+            : k === 'priority' ? `priority ${priorityLabel(updates[k])}` : k));
+        console.log(`  ${c.cyan(key)} · ${changed.join(' · ')}`);
+        return;
+    }
+    /**
+     * ⚠ COMMENTS ARE A CARD'S THREAD, NOT A SECOND OBJECT. `board-item-comments` is a DIFFERENT
+     * table (the older board-items system); tickets had no comment surface until 2026-09-04.
+     */
+    if (sub === 'comment') {
+        const key = rest[0];
+        const text = rest.slice(1).join(' ').trim();
+        if (!key || !text)
+            die('usage: beehaven ticket comment <key> "<note>"');
+        const res = await rpcOnce('ticket-comment', {
+            id: key, body: text, ...(values.reply ? { parentId: String(values.reply) } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Noted on ${c.cyan(String(res?.ticket ?? key))}`);
+        // ⚠ SS-41 — say who the @s reached, and which reached nobody.
+        const { printMentionReceipt } = await import('./mention.js');
+        printMentionReceipt(res);
+        return;
+    }
+    if (sub === 'comments') {
+        const key = rest[0];
+        if (!key)
+            die('usage: beehaven ticket comments <key>');
+        const res = await rpcOnce('ticket-comments', {
+            id: key, ...(values.all ? { includeResolved: true } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = res?.comments ?? [];
+        if (!rows.length) {
+            console.log('  No comments.');
+            return;
+        }
+        console.log('');
+        for (const r of rows)
+            console.log(`  ${c.cyan(String(r.author))}  ${String(r.body)}`);
+        /** ⚠ SAY HOW MANY ARE HIDDEN — resolved notes are part of the record, not deleted. */
+        const hidden = Number(res?.resolved ?? 0);
+        console.log(c.dim(`\n  ${rows.length} shown${hidden && !values.all ? ` · ${hidden} resolved (--all)` : ''}`));
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven ticket help');
+}
+export async function cmdBoard(sub, rest, values) {
+    const t = getTimeout(values);
+    if (!sub || sub === 'help') {
+        console.log(`
+  ${c.cyan('beehaven board')} — where cards live
+
+    board list                  Every board
+    board create "<title>"      A new board  (--project <id>)
+    board delete "<title|id>"   Remove an EMPTY board  (refuses while cards are on it)
+    board columns ["<title>"]   Its workflow, and which cards no column can hold
+    board report ["<title>"]    Tracker metrics  (--kind ${REPORT_KINDS.join('|')} --sprint <id>)
+    board backlog ["<title>"]   Cards on the board that are in no sprint
+
+  ${c.dim('To READ a board with its cards:  cat "~/<Board>.board.json"')}
+  ${c.dim('To move a card:                  beehaven ticket move <key> <status>')}
+  ${c.dim('To plan a sprint:                beehaven sprint help')}
+`);
+        return;
+    }
+    if (sub === 'list') {
+        const res = await rpcOnce('board-list', {}, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = (res?.boards ?? res?.rows ?? res?.items ?? [])
+            .filter((b) => String(b?.is_archived ?? '') !== 'true');
+        if (!rows.length) {
+            console.log('  No boards.');
+            return;
+        }
+        console.log('');
+        for (const b of rows)
+            console.log(`  ${c.cyan(String(b.title ?? 'Untitled'))} ${c.dim(String(b.id ?? ''))}`);
+        console.log(c.dim(`\n  ${rows.length} board(s) · read one with: cat "~/<title>.board.json"`));
+        return;
+    }
+    if (sub === 'create') {
+        const title = rest.join(' ').trim();
+        if (!title)
+            die('a title is required', 'beehaven board create "Sprint 2"');
+        const res = await rpcOnce('board-create', {
+            title, ...(values.project ? { projectId: String(values.project) } : {}),
+            ...(!values.project ? { personal: true } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Created board ${c.cyan(title)}`);
+        return;
+    }
+    /**
+     * ⚠⚠ BOARDS COULD ONLY EVER ACCUMULATE — CBH2-111. The web creates and archives them and has no
+     * delete call site at all; the CLI had no verb. `board-delete` has been registered, allowlisted
+     * and guarded throughout, so this is a DOOR, not a new capability — and deliberately the same
+     * door as `board list` / `board create` rather than a second one somewhere else.
+     *
+     * ⚠⚠ THE SERVER IS WHAT MAKES THIS SAFE, AND THE CLI MUST NOT SOFTEN IT. `board-delete` refuses
+     * while ANY ticket still references the board — including closed ones — because unpinning them
+     * would leave real cards on no board, which is the invisible-card state `ticket-create` started
+     * requiring a board to prevent. The refusal names the counts; it is printed verbatim.
+     *
+     * ⚠ IT REQUIRES A NAME (`named: true`). With no `--board`, `resolveBoard` falls back to the
+     * OLDEST board in the workspace — correct when filing a card, catastrophic here.
+     *
+     * ⚠ AND IT SEES ARCHIVED BOARDS. Archiving is how boards are retired today, so the ones most
+     * worth deleting are exactly the ones the default filter hides.
+     */
+    if (sub === 'delete') {
+        const named = rest.join(' ').trim();
+        const board = await resolveBoard({ ...values, board: named || values.board }, { named: true, includeArchived: true });
+        const res = await rpcOnce('board-delete', { id: board.id }, t);
+        const f = failure(res);
+        if (f) {
+            /**
+             * ⚠ THE OCCUPIED-BOARD REFUSAL IS AN ANSWER, NOT AN ERROR. It already names the counts and
+             * the fix (`ticket-update { id, boardId }`), so it is passed through with the CLI's own
+             * verb beside it rather than being restated in worse words.
+             */
+            die(f, `Move them first:  beehaven ticket move <key> --board "<other board>"`);
+        }
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        if (res?.alreadyDeleted) {
+            console.log(`  ${c.yellow('Already gone')}: ${c.cyan(board.title || board.id)}`);
+            return;
+        }
+        console.log(`  Deleted board ${c.cyan(board.title || board.id)}`);
+        return;
+    }
+    /**
+     * ⚠⚠ A BOARD'S WORKFLOW WAS WRITABLE BY AN AGENT AND READABLE BY NOBODY — CBH2-130.
+     *
+     * `board-columns-set` is registered, allowlisted and exposed as an MCP tool, and has NO caller on
+     * any human surface — not the web app, not a CLI verb. Its own description says "there is no UI
+     * for this". So the columns are the vocabulary a person works in every day, and the only
+     * principal that could change them was the one that does not look at them.
+     *
+     * ⚠⚠ THIS IS THE READ HALF ONLY, AND THE OMISSION IS DELIBERATE. **CBH2-143 is `in-review` right
+     * now** and is changing what `board-columns-set` does about stranded cards — report, refuse, or
+     * migrate. The entire value a CLI writer would add over `beehaven call board-columns-set` IS that
+     * check, so writing one today puts two implementations of one safety rule in flight at once, in
+     * the direction where disagreeing is most expensive. `call` remains the door for the write until
+     * that lands.
+     *
+     * ⚠⚠ AND THE READ IS WHAT MAKES THE `call` SAFE IN THE MEANTIME, which is why it is worth having
+     * on its own. CBH2-143's finding is that removing a column leaves every card holding that status
+     * word in NO column — "40 in-review cards … draw in no column, and are now unreachable by drag"
+     * — and until now there was no way to ask, from any surface, which cards those would be. This
+     * answers it before the call rather than after.
+     *
+     * ⚠ IT EARNS ITS PLACE ON `BEYOND`, not on convenience (`verb-surface.ts`). It is a MULTI-CALL
+     * FLOW no single action performs: `board-get` for the definition, `ticket-list` for the
+     * occupancy, joined. `beehaven call board-get` returns `columns` as a JSON STRING inside a raw
+     * row — beside `is_archived: "false"`, the truthy-string trap — and answers nothing about cards.
+     *
+     * ⚠ THE BOARD IS RESOLVED BY NAME (the `resolveBoard` ladder), which is the client-side STATE a
+     * raw `call` cannot express: `board-columns-set` takes `boardId`, "note: `boardId`, not `id`",
+     * and nothing in a terminal knows a board's uuid.
+     */
+    if (sub === 'columns') {
+        const named = rest.join(' ').trim();
+        const board = await resolveBoard({ ...values, board: named || values.board }, { includeArchived: true });
+        const got = await rpcOnce('board-get', { id: board.id }, t);
+        const gf = failure(got);
+        if (gf)
+            die(gf);
+        /**
+         * ⚠⚠ `columns` COMES BACK AS A JSON **STRING**, not an array — it is a `json` column, which is
+         * a TYPE HINT and not a serializer. Reading it as an array yields nothing and reports a board
+         * with no workflow, which is indistinguishable from a real defect.
+         */
+        const raw = (got?.board ?? got)?.columns;
+        let cols = [];
+        try {
+            cols = typeof raw === 'string' ? JSON.parse(raw) : Array.isArray(raw) ? raw : [];
+        }
+        catch {
+            die('the board\'s columns are not readable JSON', `Raw value: ${String(raw).slice(0, 120)}`);
+        }
+        /**
+         * ⚠ THE CARDS ARE FETCHED AT THE SERVER'S CEILING, and a full page is REPORTED rather than
+         * silently trusted. A stranded-card count taken from a truncated list is a confident wrong
+         * answer about exactly the thing this verb exists to surface — the CBH2-112 defect, one verb
+         * over.
+         */
+        const listed = await rpcOnce('ticket-list', { boardId: board.id, limit: LIST_MAX }, t);
+        const lf = failure(listed);
+        if (lf)
+            die(lf);
+        const cards = listed?.tickets ?? listed?.items ?? listed?.rows ?? [];
+        const keys = new Set(cols.map((c2) => String(c2.key)));
+        const held = new Map();
+        for (const card of cards) {
+            const s = String(card?.status ?? '');
+            held.set(s, (held.get(s) ?? 0) + 1);
+        }
+        const stranded = [...held.entries()].filter(([s]) => s && !keys.has(s));
+        if (values.json) {
+            console.log(JSON.stringify({
+                board: { id: board.id, title: board.title },
+                columns: cols,
+                cards: cards.length,
+                truncated: cards.length >= LIST_MAX,
+                stranded: stranded.map(([status, count]) => ({ status, count })),
+            }, null, 2));
+            return;
+        }
+        console.log('');
+        console.log(`  ${c.cyan(board.title || board.id)}`);
+        console.log('');
+        if (!cols.length)
+            console.log(`  ${c.yellow('No columns defined')} — cards on this board draw nowhere.`);
+        for (const col of cols) {
+            const key = String(col.key ?? '');
+            const n = held.get(key) ?? 0;
+            const cat = col.category ? c.dim(` ${String(col.category)}`) : '';
+            const wip = col.wipLimit ? c.dim(` wip ${col.wipLimit}`) : '';
+            console.log(`  ${key.padEnd(14)} ${String(col.label ?? key).padEnd(16)} ${String(n).padStart(4)} card(s)${cat}${wip}`);
+        }
+        console.log('');
+        if (stranded.length) {
+            /**
+             * ⚠ NAMED, NOT COUNTED. "3 stranded" is not actionable; the STATUS WORD is what a caller
+             * passes to `ticket move` to rescue them, so it is the thing to print.
+             */
+            console.log(`  ${c.yellow('Stranded')} — no column holds these, so the cards draw nowhere and cannot be dragged:`);
+            for (const [status, count] of stranded) {
+                console.log(`    ${c.cyan(status.padEnd(14))} ${count} card(s)  ${c.dim(`beehaven ticket move <key> <a column above>`)}`);
+            }
+            console.log('');
+        }
+        if (cards.length >= LIST_MAX) {
+            console.log(c.dim(`  ⚠ ${cards.length} cards is a full page — the counts above may be incomplete.`));
+            console.log('');
+        }
+        console.log(c.dim(`  The workflow is changed with:  beehaven call board-columns-set '{"boardId":"${board.id}","columns":[…]}'`));
+        console.log(c.dim(`  ⚠ It migrates nothing — a card whose status word you remove keeps it and lands here as stranded.`));
+        console.log('');
+        return;
+    }
+    /**
+     * ⚠ REPORTS ARE BOARD-SCOPED, WHICH IS WHY THEY LIVE HERE AND NOT ON `sprint`. `board-report`
+     * takes a `boardId` and refuses without one; `--sprint` only narrows a burndown.
+     *
+     * ⚠ `burndown` AND `velocity` ARE ALIASES OF THIS ACTION SERVER-SIDE, and the daemon's own agent
+     * prompt tells agents to call `burndown`. They are `--kind` values here rather than subcommands,
+     * so there is one door to one action.
+     */
+    if (sub === 'report') {
+        const named = rest.join(' ').trim();
+        const board = await resolveBoard({ ...values, board: named || values.board });
+        const kind = typeof values.kind === 'string' ? values.kind.trim().toLowerCase() : '';
+        if (kind && !REPORT_KINDS.includes(kind))
+            die(`unknown --kind "${kind}"`, `Use one of: ${REPORT_KINDS.join(', ')}.`);
+        const res = await rpcOnce('board-report', {
+            boardId: board.id,
+            ...(kind ? { kind } : {}),
+            ...(values.sprint ? { sprintId: String(values.sprint) } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log('');
+        console.log(`  ${c.cyan(board.title || board.id)} · ${String(res?.kind ?? (kind || 'summary'))}`);
+        /**
+         * ⚠ THE SHAPE DIFFERS PER KIND (summary counts · velocity per sprint · burndown series ·
+         * cycle-time), so this prints the payload rather than inventing four renderers that would each
+         * go stale independently. `--json` is the same bytes without the heading.
+         */
+        const { ok: _ok, type: _type, requestId: _rid, kind: _kind, boardId: _bid, ...rest2 } = (res ?? {});
+        console.log(JSON.stringify(rest2, null, 2).split('\n').map((l) => `  ${l}`).join('\n'));
+        console.log('');
+        /** ⚠ POINTS COME FROM THE `points` COLUMN — a board nobody sized reports zero, truthfully. */
+        if (Number(res?.points ?? 0) === 0 && String(res?.kind ?? 'summary') === 'summary') {
+            console.log(c.dim('  points read 0 because no card is sized — beehaven ticket edit <key> --points N'));
+        }
+        return;
+    }
+    /**
+     * ⚠ `--limit` IS DELIBERATELY NOT WIRED HERE. `backlog-list`'s `limit` bounds the ticket SCAN
+     * (default 500), not the number returned — the opposite of what `--limit` means on `ticket list`.
+     * One flag with two meanings across two verbs is how a caller learns the wrong one; the scan
+     * default stands, and `board` stays off `LIMIT_CAPABLE` so the flag is refused rather than
+     * quietly reinterpreted.
+     */
+    if (sub === 'backlog') {
+        const named = rest.join(' ').trim();
+        const board = await resolveBoard({ ...values, board: named || values.board });
+        const res = await rpcOnce('backlog-list', { boardId: board.id }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const backlog = res?.backlog ?? [];
+        console.log('');
+        console.log(`  ${c.cyan(board.title || board.id)} · backlog`);
+        if (!backlog.length)
+            console.log(c.dim('  nothing unplanned'));
+        for (const card of backlog) {
+            const key = String(card.key ?? '').padEnd(9);
+            const st = String(card.status ?? '').padEnd(12);
+            console.log(`  ${c.cyan(key)} ${c.dim(st)} ${String(card.title ?? '')}`);
+        }
+        /**
+         * ⚠⚠ SAY THAT THE BACKLOG IS NOT FILTERED BY STATUS. `backlog-list` has no status predicate,
+         * so finished cards that were never put in a sprint sit in this list too — reading its length
+         * as "work remaining" is wrong, and nothing else on screen says so.
+         */
+        console.log(c.dim(`\n  ${backlog.length} unplanned card(s) · ${Number(res?.backlogPoints ?? 0)} points`
+            + ' — NOT status-filtered, so finished cards appear here too'));
+        for (const s of (res?.sprints ?? [])) {
+            console.log(c.dim(`  ${String(s.name ?? '')} (${String(s.state ?? '')}) · ${(s.cards ?? []).length} card(s) · ${Number(s.points ?? 0)} points`));
+        }
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven board help');
+}
+/**
+ * `beehaven sprint` — the planning cycle.
+ *
+ * ⚠⚠ WHY THIS EXISTS: THE DAEMON'S OWN AGENT PROMPT SENDS AGENTS HERE AND THERE WAS NOTHING TO
+ * FIND — CBH2-107. `daemon-omni-company.ts` instructs agents to call `sprint-create`,
+ * `sprint-plan`, `sprint-start`, `sprint-complete` and `burndown`; all six sprint actions plus
+ * `backlog-list` and `board-report` were registered, allowlisted and reachable ONLY as
+ * `beehaven call <action> '{…}'`. A shipped prompt naming a verb the CLI does not have is the
+ * same defect already recorded at `commands/omni.ts:138` for `ticket-link`.
+ *
+ * ⚠ SO THIS IS A DOOR, NOT A CAPABILITY. Every action here already existed on
+ * `USER_ACTION_ALLOWLIST` with an `ACTION_DESCRIPTIONS` entry — nothing was granted for it.
+ *
+ * ⚠⚠ AND IT EXISTS TO MAKE TWO MEASURED TRAPS UNTYPEABLE, the same reason `ticket` does:
+ *   · A SPRINT IS ADDRESSED BY UUID and nothing ever shows you one in prose. `resolveSprint`
+ *     takes the name people actually say, and REFUSES an ambiguous one rather than starting or
+ *     deleting whichever sprint sorted first — auto-numbering means two boards routinely both
+ *     hold a "Sprint 1".
+ *   · `sprint-plan` TAKES ROW IDS AND ANSWERS `ok:true, moved:1` FOR A KEY IT NEVER MOVED. See
+ *     `resolveCardIds` — this verb resolves every reference first and refuses on a miss.
+ */
+export async function cmdSprint(sub, rest, values) {
+    const t = getTimeout(values);
+    if (!sub || sub === 'help') {
+        console.log(`
+  ${c.cyan('beehaven sprint')} — plan, run and close a sprint
+
+    sprint list                 Sprints  (--board <b> --state ${SPRINT_STATES.join('|')})
+    sprint create ["<name>"]    A new sprint, state ${c.dim('planned')}  (--board <b> --goal "…")
+    sprint plan <s> <key…>      Put cards IN  (--remove to send them back to the backlog)
+    sprint start <s>            planned → active  (one active sprint per board)
+    sprint complete <s>         active → completed  (--sprint <id> for the unfinished cards)
+    sprint delete <s>           Discard it — its cards go back to the backlog  (--force if active)
+
+  ${c.dim('A sprint is named or addressed by id. Names must be unique — narrow with --board.')}
+  ${c.dim('What is not in a sprint:  beehaven board backlog "<board>"')}
+  ${c.dim('How it went:              beehaven board report "<board>" --kind velocity')}
+  ${c.dim('⚠ delete, not complete, discards a mistake — a COMPLETED sprint is a permanent')}
+  ${c.dim('  velocity datapoint that board-report averages over.')}
+`);
+        return;
+    }
+    if (sub === 'list') {
+        const board = values.board ? await resolveBoard(values) : null;
+        const state = typeof values.state === 'string' ? values.state.trim().toLowerCase() : '';
+        if (state && !SPRINT_STATES.includes(state)) {
+            die(`unknown --state "${state}"`, `Use one of: ${SPRINT_STATES.join(', ')}.`);
+        }
+        const res = await rpcOnce('sprint-list', {
+            ...(board ? { boardId: board.id } : {}),
+            ...(state ? { state } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = res?.sprints ?? [];
+        if (!rows.length) {
+            console.log('  No sprints.');
+            return;
+        }
+        console.log('');
+        for (const s of rows) {
+            const st = String(s.state ?? '').padEnd(10);
+            const pts = `${Number(s.completedPoints ?? 0)}/${Number(s.committedPoints ?? 0)} pts`;
+            console.log(`  ${c.cyan(String(s.name ?? '').padEnd(24))} ${c.dim(st)} ${c.dim(pts)}  ${c.dim(String(s.id ?? ''))}`);
+        }
+        console.log(c.dim(`\n  ${rows.length} sprint(s)`));
+        return;
+    }
+    if (sub === 'create') {
+        // ⚠ `boardId` IS REQUIRED — `sprint-create` refuses without one. Same rule as a ticket, and
+        //   the same resolver, so a sprint cannot land somewhere the caller was not told about.
+        const board = await resolveBoard(values);
+        const name = rest.join(' ').trim();
+        const res = await rpcOnce('sprint-create', {
+            boardId: board.id,
+            ...(name ? { name } : {}),
+            ...(values.goal ? { goal: String(values.goal) } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        /** ⚠ SAY THE BOARD, for the reason `ticket create` does: with no --board this was a guess. */
+        console.log(`  Created ${c.cyan(String(res?.name ?? name))} · ${board.title || board.id} · ${c.dim('planned')}`);
+        console.log(c.dim(`  beehaven sprint start "${String(res?.name ?? name)}"  — when you are ready to run it`));
+        return;
+    }
+    /**
+     * ⚠⚠ ONE VERB, TWO DIRECTIONS — the shape `ticket move` already uses. Removing a card FROM a
+     * sprint IS returning it to the backlog server-side (`sprint_id: ''`), so `--remove` covers
+     * both and there is no second `sprint backlog` verb naming the same write.
+     */
+    if (sub === 'plan') {
+        const sprintRef = rest[0];
+        const cardRefs = rest.slice(1).filter(Boolean);
+        if (!sprintRef || !cardRefs.length) {
+            die('usage: beehaven sprint plan <sprint> <key> [<key>…] [--remove]', 'Keys look like CLR-42. `--remove` sends them back to the backlog.');
+        }
+        const sprint = await resolveSprint(sprintRef, values);
+        const cards = await resolveCardIds(cardRefs, values);
+        const ids = cards.map((x) => x.id);
+        const res = await rpcOnce('sprint-plan', {
+            sprintId: sprint.id,
+            ...(values.remove ? { remove: ids } : { add: ids }),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const dir = values.remove ? 'out of' : 'into';
+        console.log(`  ${cards.map((x) => x.key).join(', ')} ${dir} ${c.cyan(sprint.name)}`);
+        /**
+         * ⚠⚠ RECONCILE THE SERVER'S COUNT AGAINST WHAT WAS ASKED FOR. `sprint-plan` increments its
+         * counter inside a `try` and swallows a failed write, so `moved` can be smaller than the
+         * request with nothing else saying so. Every card here resolved to a real row id first, so a
+         * shortfall is a genuine server-side miss and must be visible.
+         */
+        const moved = Number(res?.moved ?? 0);
+        if (moved !== ids.length) {
+            console.log(c.yellow(`  the server moved ${moved} of ${ids.length} — re-check with: beehaven ticket show ${cards[0].key}`));
+        }
+        return;
+    }
+    if (sub === 'start') {
+        const sprint = await resolveSprint(rest.join(' ').trim(), values);
+        const res = await rpcOnce('sprint-start', { id: sprint.id }, t);
+        const f = failure(res);
+        /**
+         * ⚠ THE "ANOTHER SPRINT IS ACTIVE" REFUSAL IS THE COMMON ONE and it names the blocker, so it
+         * is passed through with the verb that clears it rather than restated.
+         */
+        if (f)
+            die(f, 'One sprint per board runs at a time — beehaven sprint complete "<the active one>"');
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  ${c.cyan(sprint.name)} → ${c.dim('active')} · ${Number(res?.cards ?? 0)} card(s) · ${Number(res?.committedPoints ?? 0)} points committed`);
+        /**
+         * ⚠ COMMITTED POINTS ARE FROZEN HERE AND NEVER RECOMPUTED — that is what makes velocity
+         * honest, and it means a card sized AFTER this moment does not count. Nothing else says so.
+         */
+        if (Number(res?.committedPoints ?? 0) === 0 && Number(res?.cards ?? 0) > 0) {
+            console.log(c.dim('  0 points committed — size the cards BEFORE starting, the commitment is frozen now'));
+        }
+        return;
+    }
+    if (sub === 'complete') {
+        const sprint = await resolveSprint(rest.join(' ').trim(), values);
+        const res = await rpcOnce('sprint-complete', {
+            id: sprint.id,
+            // ⚠ Omitted means "back to the backlog" — the server's default, and the safe one.
+            ...(values.sprint ? { moveUnfinishedTo: String(values.sprint) } : {}),
+        }, t);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  ${c.cyan(sprint.name)} → ${c.dim('completed')}`);
+        console.log(`  ${String(res?.message ?? '')}`);
+        /**
+         * ⚠⚠ COMPLETING IS PERMANENT AND IS NOT THE UNDO. A completed sprint is a velocity datapoint
+         * `board-report` averages over — so completing a junk sprint corrupts the metric rather than
+         * discarding it. `sprint delete` is the discard.
+         */
+        console.log(c.dim('  recorded as a velocity datapoint — beehaven board report --kind velocity'));
+        return;
+    }
+    if (sub === 'delete') {
+        const sprint = await resolveSprint(rest.join(' ').trim(), values);
+        const res = await rpcOnce('sprint-delete', {
+            id: sprint.id, ...(values.force ? { force: true } : {}),
+        }, t);
+        const f = failure(res);
+        // ⚠ An ACTIVE sprint refuses without --force, deliberately. Name the flag.
+        if (f)
+            die(f, sprint.state === 'active' ? 'Pass --force to delete the sprint people are working in.' : undefined);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Deleted ${c.cyan(sprint.name)}`);
+        /** ⚠ THE CARDS SURVIVE — they go back to the backlog, and saying so is the point. */
+        console.log(c.dim(`  ${String(res?.message ?? '')}`));
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven sprint help');
+}