@starlove/orbit 1.4.1 → 2.0.0

package/lib/commands/verbs.js

@@ -0,0 +1,842 @@
+/**
+ * What each command does: reads the board through the port, changes it
+ * through the core's use cases (never by writing records itself), and says
+ * what happened in Orbit's words (./present.ts), with JSON data for --json.
+ */
+import { CLAIM_NOTE, checkpointTicket, claimNext, claimTicket, completeTicket } from "../core/agent.js";
+import { createBoard, createEntry } from "../core/boards.js";
+import { crossBlockers, crossLinksFrom, linkAcrossBoards, unlinkAcrossBoards } from "../core/cross-board.js";
+import { onBoard } from "../core/context.js";
+import { describeEvent } from "../core/describe.js";
+import { OrbitError } from "../core/errors.js";
+import { parseNebulaUrl } from "../core/nebula-link.js";
+import { createRelation, deleteRelation } from "../core/relations.js";
+import { searchTickets } from "../core/search.js";
+import { archiveTicket, createComment, createTicket, restoreTicket, updateTicket } from "../core/tickets.js";
+import { Lanes, WORK_EVENTS, blockersFromSets, currentHolder, holderFrom, isClosedLane, isHolder, labelsByTicket, unresolvedBlockers } from "../core/views.js";
+import { fail, flagList, flagOn, flagString, freeWords, noMoreWords, parseCardRef, cardLink, usageText } from "./parse.js";
+import { PRIORITY_WORDS, age, authorKey, authorText, block, cardRef, labelled, laneText as L, oneLine, plural, quoted, renderCard, renderView } from "./present.js";
+import { DEFAULT_BOARD, boardList, boardRowFor, callerPlace, hint, inShell, noBoardsText, repoChoice, repoProblemText, resolveBoard, savedDefault, setsComputerDefault } from "./session.js";
+import { asText } from "../core/text.js";
+/** A write's answer is one line of at most this many characters. */
+const ANSWER_BUDGET = 100;
+// ---------------------------------------------------------------------------
+// Lanes, priorities, types and text
+const squash = (value) => asText(value ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+/** A lane by name (any case or spacing), its role, a unique start (2+ characters) or a unique part (4+). */
+function resolveLane(states, input, slug) {
+    const wanted = asText(input ?? "").trim();
+    const names = () => states.map((s) => L(s.name)).join(", ");
+    if (!wanted)
+        fail(`Which lane? Lanes: ${names()}.`);
+    const key = squash(wanted);
+    const pick = (matches) => (matches.length === 1 ? (matches[0] ?? null) : null);
+    const found = pick(states.filter((s) => squash(s.name) === key)) ??
+        pick(states.filter((s) => s.role && squash(s.role) === key)) ??
+        (key.length >= 2 ? pick(states.filter((s) => squash(s.name).startsWith(key))) : null) ??
+        (key.length >= 4 ? pick(states.filter((s) => squash(s.name).includes(key))) : null);
+    if (!found)
+        fail(`No lane "${oneLine(wanted, 60)}" on board ${slug}. Lanes: ${names()}.`);
+    return found;
+}
+async function laneOn(bc, input) {
+    return resolveLane(await bc.data.read((r) => r.states.list()), input, bc.board.slug);
+}
+const PRIORITY_INPUT = { urgent: 4, high: 3, med: 2, medium: 2, normal: 2, low: 1, maybe: 0 };
+function parsePriority(value) {
+    const key = value.trim().toLowerCase();
+    const priority = PRIORITY_INPUT[key];
+    if (priority === undefined)
+        fail("Priority is a word: urgent, high, med, low, maybe.");
+    return priority;
+}
+const TYPES = ["task", "feature", "bug", "epic"];
+function parseType(value) {
+    const key = value.trim().toLowerCase();
+    if (!TYPES.includes(key))
+        fail(`Type is one of: ${TYPES.join(", ")}.`);
+    return key;
+}
+export const TEXT_TWICE_MESSAGE = "Text given twice: as -m/--text (or the text field) and as words on the line. Send it once: quote it, or put it all in text.";
+/**
+ * The command's long text: the text field (or -m), else the words left on the
+ * line. Both at once means a word was read as an option (`note #1 see the -m
+ * flag`), so it is refused rather than half saved.
+ */
+function textOf(args, from) {
+    const text = flagString(args, "text");
+    if (text !== undefined && args.positional.length > from)
+        fail(TEXT_TWICE_MESSAGE);
+    if (text !== undefined)
+        return text.trim();
+    return freeWords(args, from, "text").join(" ").trim();
+}
+function sendText(session) {
+    return session.transport === "cli" ? 'Add it with -m "...".' : "Send it as text.";
+}
+/** A write command written for this transport: `finish #6`, or `orbit finish 6 -m "..."`. */
+function writeHint(session, verb, n, placeholder = "") {
+    return session.transport === "cli" ? `orbit ${verb} ${n} -m "${placeholder}"` : `${verb} #${n}`;
+}
+// ---------------------------------------------------------------------------
+// Cards
+async function requireRef(session, word, usage) {
+    const shell = inShell(session);
+    if (word === undefined)
+        fail(`Which card? Usage: ${usageText(shell, usage)}${shell ? " (in a shell #12 starts a comment, so write 12)" : ""}`);
+    const ref = parseCardRef(word);
+    if (!ref) {
+        const first = (await session.c.store.boards.list())[0]?.slug ?? "board";
+        const cards = shell ? `numbers (12, or ${first}#12)` : "#n (or board#n)";
+        fail(`"${oneLine(word, 60)}" isn't a card. Cards are ${cards}. Usage: ${usageText(shell, usage)}`);
+    }
+    return ref;
+}
+/** The card a ref names, on its own board (which doesn't change the session's board). */
+async function resolveCard(session, word, args, usage) {
+    const ref = await requireRef(session, word, usage);
+    const row = await resolveBoard(session, ref.board ?? flagString(args, "board"));
+    const bc = await onBoard(session.c, row);
+    const found = await bc.data.read(async (r) => {
+        const ticket = await r.tickets.byNumber(ref.n);
+        if (!ticket)
+            return { ticket: null, top: await r.tickets.lastNumber() };
+        const lanes = await Lanes.of(r);
+        return { ticket: { ...ticket, state_name: lanes.nameOf(ticket), state_role: lanes.roleOf(ticket) }, top: 0 };
+    });
+    if (!found.ticket)
+        fail(`No card #${ref.n} on board ${row.slug}${found.top ? ` (cards go up to #${found.top})` : " (it has no cards yet)"}.`);
+    return { bc, ticket: found.ticket };
+}
+/** Comments an agent may see: not the claim note, not one a person hid from agents. */
+const visible = (comment) => !comment.omitted_for_ai && comment.body !== CLAIM_NOTE;
+async function visibleComments(bc, ticketId) {
+    const comments = await bc.data.read((r) => r.comments.list(ticketId));
+    return comments.filter(visible).map((comment) => ({ author: comment.author, kind: comment.kind, body: comment.body, at: comment.created_at }));
+}
+/**
+ * A card's links to other boards' cards, as `card` lists them: what it waits
+ * on and what it relates to. Read inside the card's own read: these read the
+ * other boards, never this one again. What waits on it from other boards
+ * shows in the person's app (it would read every board on each `card`).
+ */
+async function acrossBoards(bc, r, ticketId) {
+    const outgoing = await r.crossBoardRelations.list(ticketId);
+    if (!outgoing.length)
+        return { blockedBy: [], related: [] };
+    const brief = (card) => (card ? [{ n: card.number, title: card.title, lane: card.state_name, board: card.board_slug }] : []);
+    const [waiting, links] = await Promise.all([crossBlockers(bc, outgoing), crossLinksFrom(bc, outgoing, [], true)]);
+    return {
+        blockedBy: (waiting.get(ticketId) ?? []).flatMap(brief),
+        related: links.filter((link) => link.type === "relates_to").flatMap((link) => brief(link.other_ticket))
+    };
+}
+async function cardModel(r, bc, ticket) {
+    const lanes = await Lanes.of(r);
+    const brief = (row) => ({ n: row.number, title: row.title, lane: lanes.nameOf(row) });
+    const parent = ticket.parent_ticket_id ? await r.tickets.get(ticket.parent_ticket_id) : null;
+    const children = await r.tickets.list({ parent: ticket.id, archived: false });
+    const relations = await r.relations.list(ticket.id);
+    const others = new Map((await r.tickets.list({ ids: relations.map((x) => (x.source_ticket_id === ticket.id ? x.target_ticket_id : x.source_ticket_id)), archived: false })).map((t) => [t.id, t]));
+    const linked = relations
+        .map((relation) => ({ relation, other: others.get(relation.source_ticket_id === ticket.id ? relation.target_ticket_id : relation.source_ticket_id) }))
+        .filter((row) => row.other !== undefined)
+        .sort((a, b) => a.other.number - b.other.number);
+    const blocks = linked.filter(({ relation }) => (relation.type === "blocks" && relation.source_ticket_id === ticket.id) || (relation.type === "blocked_by" && relation.target_ticket_id === ticket.id));
+    const related = linked.filter(({ relation }) => relation.type === "relates_to");
+    const labels = (await labelsByTicket(r, [ticket.id])).get(ticket.id) ?? [];
+    const comments = await r.comments.list(ticket.id);
+    const role = lanes.roleOf(ticket);
+    const elsewhere = await acrossBoards(bc, r, ticket.id);
+    return {
+        n: ticket.number,
+        title: ticket.title,
+        type: ticket.type,
+        priority: ticket.priority,
+        lane: lanes.nameOf(ticket),
+        archived: Boolean(ticket.archived_at),
+        labels: labels.map((label) => label.name),
+        author: ticket.created_by,
+        holder: role === "in_progress" ? await currentHolder(r, ticket.id) : null,
+        link: cardLink(bc.board.slug, ticket.number),
+        parent: parent ? { n: parent.number, title: parent.title, lane: lanes.nameOf(parent) } : null,
+        children: children.map(brief),
+        blockedBy: [...(await unresolvedBlockers(r, ticket.id, lanes)).map(brief), ...elsewhere.blockedBy],
+        blocks: blocks.map(({ other }) => brief(other)),
+        related: [...related.map(({ other }) => brief(other)), ...elsewhere.related],
+        description: ticket.description,
+        plan: ticket.ai_plan,
+        summary: ticket.implementation_summary,
+        revisions: ticket.implementation_updates,
+        nebula: ticket.nebula_url,
+        commentCount: comments.filter(visible).length
+    };
+}
+function loadCard(bc, ticket) {
+    return bc.data.read((r) => cardModel(r, bc, ticket));
+}
+function cardJson(card, comments) {
+    const { priority, ...rest } = card;
+    return {
+        ...rest,
+        author: authorKey(card.author),
+        priority: PRIORITY_WORDS[priority],
+        ...(comments ? { comments: comments.map((comment) => ({ ...comment, author: authorKey(comment.author) })) } : {})
+    };
+}
+// ---------------------------------------------------------------------------
+// The board: everything the text view needs, in one read.
+async function loadBoardModel(bc) {
+    const { model, states, cross } = await bc.data.read(async (r) => {
+        const [board, states, tickets, labels, comments, relations, entries, cross] = await Promise.all([
+            r.board.get(),
+            r.states.list(),
+            r.tickets.list({ archived: false }),
+            labelsByTicket(r),
+            r.comments.countByTicket({ forAgents: true, exceptBody: CLAIM_NOTE }),
+            r.relations.list(),
+            r.entries.list(),
+            r.crossBoardRelations.list()
+        ]);
+        const lanes = new Lanes(states);
+        const inProgress = tickets.filter((t) => lanes.roleOf(t) === "in_progress").map((t) => t.id);
+        const latest = inProgress.length ? await r.events.latest(inProgress, WORK_EVENTS) : [];
+        const lastWork = new Map(latest.map((event) => [event.ticket_id, event]));
+        const open = new Map(tickets.map((t) => [t.id, t]));
+        const childrenOf = new Map();
+        for (const t of tickets)
+            if (t.parent_ticket_id)
+                childrenOf.set(t.parent_ticket_id, [...(childrenOf.get(t.parent_ticket_id) ?? []), t]);
+        const commentCount = new Map(comments.map((row) => [row.ticket_id, row.count]));
+        const columns = states.map((state) => ({ name: state.name, role: state.role, closed: isClosedLane(state), cards: [] }));
+        const columnOf = new Map(states.map((state, i) => [state.id, columns[i]]));
+        for (const t of tickets) {
+            const column = columnOf.get(t.state_id);
+            if (!column)
+                continue;
+            const holder = lanes.roleOf(t) === "in_progress" ? holderFrom(lastWork.get(t.id)) : null;
+            column.cards.push({
+                id: t.id,
+                n: t.number,
+                title: t.title,
+                type: t.type,
+                priority: t.priority,
+                labels: (labels.get(t.id) ?? []).map((label) => label.name),
+                parent: t.parent_ticket_id ? (open.get(t.parent_ticket_id)?.number ?? null) : null,
+                sub: childrenOf.get(t.id)?.length ?? 0,
+                blockedBy: column.closed ? [] : blockersFromSets(t.id, relations, open, childrenOf, lanes).map((b) => b.number),
+                holder: holder ? { name: holder.name, since: holder.since } : null,
+                comments: commentCount.get(t.id) ?? 0
+            });
+        }
+        for (const column of columns)
+            column.cards.sort((a, b) => b.priority - a.priority || a.n - b.n);
+        const model = {
+            slug: bc.board.slug,
+            name: board.name,
+            open: columns.filter((column) => !column.closed).reduce((sum, column) => sum + column.cards.length, 0),
+            hasRules: Boolean(board.agent_instructions.trim()),
+            journalCount: entries.filter((entry) => !entry.struck_at).length,
+            lanes: columns
+        };
+        return { model, states, cross };
+    });
+    // Cards waiting on other boards' cards, after this board's read: one read per other board.
+    if (cross.length) {
+        const waiting = await crossBlockers(bc, cross);
+        for (const column of model.lanes) {
+            if (column.closed)
+                continue;
+            for (const card of column.cards)
+                card.blockedBy.push(...(waiting.get(card.id) ?? []).map((other) => `${other.board_slug}#${other.number}`));
+        }
+    }
+    return { model, states };
+}
+function viewJson(model) {
+    return {
+        board: model.slug,
+        name: model.name,
+        open: model.open,
+        lanes: model.lanes.map((lane) => ({
+            name: lane.name,
+            role: lane.role,
+            closed: lane.closed,
+            count: lane.cards.length,
+            cards: lane.cards.map((card) => ({ n: card.n, title: card.title, type: card.type, labels: card.labels, parent: card.parent, sub: card.sub, blockedBy: card.blockedBy, holder: card.holder, comments: card.comments, priority: PRIORITY_WORDS[card.priority] }))
+        }))
+    };
+}
+// ---------------------------------------------------------------------------
+// Commands
+export async function cmdView(session, args) {
+    noMoreWords(args, 1, "view [board] [--all] [--lane L]");
+    const named = flagString(args, "board") ?? args.positional[0];
+    const row = await resolveBoard(session, named);
+    if (named)
+        session.board = row.slug;
+    const bc = await onBoard(session.c, row);
+    const { model, states } = await loadBoardModel(bc);
+    const laneFlag = flagString(args, "lane");
+    const lane = laneFlag ? resolveLane(states, laneFlag, row.slug).name : null;
+    const data = viewJson(model);
+    if (lane)
+        data.lanes = data.lanes.filter((column) => column.name === lane);
+    return { text: renderView(model, { all: flagOn(args, "all"), lane, hint: (line) => hint(session, line), shell: inShell(session) }), data };
+}
+export async function cmdCard(session, args) {
+    noMoreWords(args, 1, "card #n [--comments]");
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, "card #n [--comments]");
+    const card = await loadCard(bc, ticket);
+    const comments = flagOn(args, "comments") ? await visibleComments(bc, ticket.id) : null;
+    return { text: renderCard(card, { comments, hint: (line) => hint(session, line) }), data: cardJson(card, comments) };
+}
+const NO_RULES = "No board rules yet. People set them in the app: Settings, AI, Agent Instructions.";
+/** What an agent does with code when the board's rules say nothing. */
+const WORK_RULES = "work on a branch, commit locally, and never push, merge or deploy";
+/** An agent that didn't say its name writes as "agent", so its cards can't say which agent did what. */
+function isUnnamed(session) {
+    return session.actor.type === "agent" && session.actor.name === "agent";
+}
+/** How an unnamed agent names itself, in its transport's words. */
+function nameYourself(session) {
+    const how = {
+        cli: "export ORBIT_AGENT_NAME=<your name>",
+        mcp: "add ORBIT_AGENT_NAME to this server's env in the MCP config.",
+        http: "send the x-orbit-agent-name header."
+    };
+    return `Name yourself so cards say which agent did what: ${how[session.transport] ?? how.mcp ?? ""}`;
+}
+/** The overview's first lines for an agent: how to name itself (while it has no name) and the default work rules. */
+export function agentLines(session) {
+    const lines = isUnnamed(session) ? [nameYourself(session)] : [];
+    lines.push(`For code, unless the board's rules say otherwise (${hint(session, "journal")}): ${WORK_RULES}.`);
+    return lines;
+}
+async function nothingToTake(session, bc) {
+    const named = `Take a named card with \`${hint(session, "take #n")}\`.`;
+    return bc.data.read(async (r) => {
+        const lanes = await Lanes.of(r);
+        const ready = lanes.forRole("ai_ready", "AI Ready");
+        if (!ready)
+            return `Board ${bc.board.slug} has no AI Ready lane. ${named}`;
+        const waiting = (await r.tickets.list({ state: ready.id, archived: false })).sort((a, b) => b.priority - a.priority || a.number - b.number);
+        if (!waiting.length)
+            return `${L(ready.name)} is empty. ${named}`;
+        const why = [];
+        for (const t of waiting) {
+            if (t.type === "epic") {
+                why.push(`#${t.number} is an epic`);
+                continue;
+            }
+            const blockers = await unresolvedBlockers(r, t.id, lanes);
+            why.push(blockers.length ? `#${t.number} is blocked by ${blockers.map((b) => `#${b.number}`).join(",")}` : `#${t.number} can't be taken`);
+        }
+        return `Nothing in ${L(ready.name)} can be taken now: ${why.join("; ")}. ${named}`;
+    });
+}
+export async function cmdTake(session, args) {
+    const usage = "take [#n] [--force]";
+    noMoreWords(args, 1, usage);
+    const force = flagOn(args, "force");
+    let bc;
+    let number;
+    if (args.positional[0] !== undefined) {
+        const found = await resolveCard(session, args.positional[0], args, usage);
+        bc = found.bc;
+        const ticket = found.ticket;
+        number = ticket.number;
+        const again = `\`${hint(session, `take #${ticket.number} --force`)}\``;
+        if (!force) {
+            if (ticket.type === "epic") {
+                const open = await bc.data.read(async (r) => {
+                    const lanes = await Lanes.of(r);
+                    return (await r.tickets.list({ parent: ticket.id, archived: false })).filter((t) => !isClosedLane({ name: lanes.nameOf(t), role: lanes.roleOf(t) })).map((t) => `#${t.number}`);
+                });
+                const first = open[0];
+                if (first)
+                    fail(`#${ticket.number} is an epic with open sub-cards: ${open.join(", ")}. Take one of them (\`${hint(session, `take ${first}`)}\`), or ${again} to work the epic itself.`);
+            }
+            const holder = ticket.state_role === "in_progress" ? await bc.data.read((r) => currentHolder(r, ticket.id)) : null;
+            if (holder && !isHolder(holder, session.actor)) {
+                const since = age(holder.since);
+                fail(`#${ticket.number} is held by @${oneLine(holder.name, 40)}${since ? ` (${since})` : ""}. ${again} takes it over.`);
+            }
+        }
+        const result = await claimTicket(bc, { ticket_id: ticket.id, force }, { becomeHolder: true });
+        if (!result.claimed && result.reason === "blocked") {
+            const blockers = result.blockers.map((b) => cardRef({ n: b.number, title: b.title, lane: b.state_name, board: b.board_slug && b.board_id !== bc.board.id ? b.board_slug : undefined })).join("; ");
+            fail(`#${ticket.number} is blocked by ${blockers}. Finish that first, or \`${hint(session, `take #${ticket.number} --force`)}\`.`);
+        }
+        if (!result.claimed && result.reason === "already_done")
+            fail(`#${ticket.number} is in ${L(ticket.state_name)}. \`${hint(session, `take #${ticket.number} --force`)}\` reopens it.`);
+    }
+    else {
+        const row = await resolveBoard(session, flagString(args, "board"));
+        bc = await onBoard(session.c, row);
+        const type = flagString(args, "type");
+        const result = await claimNext(bc, { type: type ? parseType(type) : "" });
+        if (!result.claimed)
+            fail(await nothingToTake(session, bc));
+        const claimed = result.ticket_id;
+        number = await bc.data.read(async (r) => (await r.tickets.get(claimed))?.number ?? 0);
+    }
+    const { card, journal, rules } = await bc.data.read(async (r) => {
+        const fresh = await r.tickets.byNumber(number);
+        if (!fresh)
+            fail(`No card #${number} on board ${bc.board.slug}.`);
+        const [board, entries] = await Promise.all([r.board.get(), r.entries.list()]);
+        return { card: await cardModel(r, bc, fresh), journal: entries.filter((entry) => !entry.struck_at).length, rules: board.agent_instructions.trim() };
+    });
+    const n = card.n;
+    const ask = session.transport === "cli" ? `\`${writeHint(session, "ask", n, "what's missing")}\`` : `\`${writeHint(session, "ask", n)}\` with what's missing as text`;
+    const finish = session.transport === "cli" ? `\`${writeHint(session, "finish", n, "what changed; how you checked")}\`` : `\`${writeHint(session, "finish", n)}\` with what changed and how you checked it`;
+    const unnamed = isUnnamed(session) ? ` ${nameYourself(session)}` : "";
+    const lines = [`Took #${n}: now ${L(card.lane)}, held by you (${oneLine(session.actor.name, 40)}).${unnamed}`, renderCard(card, { hint: (line) => hint(session, line) }), ""];
+    lines.push(rules ? labelled("Board rules:", rules) : `No board rules yet, so for code: ${WORK_RULES}.`);
+    if (journal)
+        lines.push(`Journal: ${plural(journal, "entry", "entries")} (\`${hint(session, "journal")}\`).`);
+    lines.push(`Next: do the work. Goal or "done" unclear? ${ask}, then stop.`);
+    lines.push(`Milestones: \`${writeHint(session, "note", n, "...")}\`. Finished: ${finish} (it goes to Review; never Done unless the user says so).`);
+    return { text: lines.join("\n"), data: { took: n, card: cardJson(card), rules }, board: bc };
+}
+export async function cmdMove(session, args) {
+    const usage = "move #n <lane>";
+    const laneWords = freeWords(args, 1, "lane name");
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, usage);
+    if (!laneWords.length)
+        fail(`Move #${ticket.number} where? Usage: ${usageText(inShell(session), usage)}`);
+    const lane = await laneOn(bc, laneWords.join(" "));
+    if (lane.id === ticket.state_id)
+        return { text: `#${ticket.number} is already in ${L(lane.name)}.`, data: { card: ticket.number, lane: lane.name }, board: bc };
+    // A move ends an agent's hold on the card (WORK_EVENTS), so the answer says when there was one.
+    const held = (await bc.data.read((r) => currentHolder(r, ticket.id))) !== null;
+    await updateTicket(bc, ticket.id, { state_id: lane.id });
+    return { text: `#${ticket.number} ${L(ticket.state_name)} -> ${L(lane.name)}${held ? " (released)" : ""}.`, data: { card: ticket.number, from: ticket.state_name, lane: lane.name, ...(held ? { released: true } : {}) }, board: bc };
+}
+export async function cmdFinish(session, args) {
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, "finish #n (summary as text) [--pr URL] [--lane L]");
+    const summary = textOf(args, 1);
+    if (!summary)
+        fail(`finish needs a summary: what changed and how you checked it. ${sendText(session)}`);
+    const input = { ticket_id: ticket.id, summary };
+    const pr = flagString(args, "pr");
+    if (pr)
+        input.pr_url = pr;
+    const laneFlag = flagString(args, "lane");
+    if (laneFlag)
+        input.next_state = (await laneOn(bc, laneFlag)).name;
+    const after = (await completeTicket(bc, input)).ticket;
+    return { text: `#${ticket.number} ${L(ticket.state_name)} -> ${L(after.state_name)}. Summary saved.`, data: { card: ticket.number, from: ticket.state_name, lane: after.state_name }, board: bc };
+}
+export async function cmdAsk(session, args) {
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, "ask #n (what's missing, as text)");
+    const message = textOf(args, 1);
+    if (!message)
+        fail(`ask needs what's missing: the question for a person. ${sendText(session)}`);
+    const after = (await checkpointTicket(bc, { ticket_id: ticket.id, message })).ticket;
+    return { text: `#${ticket.number} ${L(ticket.state_name)} -> ${L(after.state_name)}, waiting on a person.`, data: { card: ticket.number, from: ticket.state_name, lane: after.state_name }, board: bc };
+}
+export async function cmdNote(session, args) {
+    const kind = flagOn(args, "decision") ? "decision" : flagOn(args, "lesson") ? "lesson" : null;
+    const { positional } = args;
+    if (kind) {
+        // Only #n or a link attaches the entry: a title may start with a number or a word like "C#5".
+        const attaches = positional.length > 1 && /^(\[\[|orbit:|#\d)/i.test(positional[0] ?? "") && parseCardRef(positional[0]) !== null;
+        const words = [...(attaches ? positional.slice(0, 1) : []), ...freeWords(args, attaches ? 1 : 0, "title")];
+        let bc;
+        let ticketId = null;
+        if (attaches) {
+            const found = await resolveCard(session, words.shift(), args, "note [#n] --decision <title>");
+            bc = found.bc;
+            ticketId = found.ticket.id;
+        }
+        else {
+            bc = await onBoard(session.c, await resolveBoard(session, flagString(args, "board")));
+        }
+        const title = words.join(" ").trim();
+        if (!title)
+            fail(`A journal entry needs a title: ${hint(session, `note --${kind} <title>`)}, with any detail as text.`);
+        const entry = await createEntry(bc, { type: kind, title, body: flagString(args, "text") ?? "", ticket_id: ticketId });
+        return { text: `Journal: ${kind} ${quoted(title, 60)} saved.`, data: { journal: entry.id, type: kind, title }, board: bc };
+    }
+    const { bc, ticket } = await resolveCard(session, positional[0], args, "note #n (text) | note --decision|--lesson <title>");
+    const body = textOf(args, 1);
+    if (!body)
+        fail(`note needs its text. ${sendText(session)}`);
+    await createComment(bc, ticket.id, { body });
+    return { text: `Noted on #${ticket.number}.`, data: { card: ticket.number }, board: bc };
+}
+async function parentId(session, bc, value) {
+    if (/^(none|-|null)$/i.test(value))
+        return null;
+    const ref = await requireRef(session, value, "--parent #n");
+    const parent = await bc.data.read((r) => r.tickets.byNumber(ref.n));
+    if (!parent || (ref.board && ref.board !== bc.board.slug))
+        fail(`No card #${ref.n} on board ${bc.board.slug} to be the parent.`);
+    return parent.id;
+}
+export async function cmdNew(session, args) {
+    const usage = "new <title> [--lane L] [--type T] [--priority P] [--label a,b] [--parent #n] (description as text)";
+    const title = freeWords(args, 0, "title").join(" ").trim();
+    if (!title)
+        fail(`new needs a title. Usage: ${usageText(inShell(session), usage)}`);
+    const bc = await onBoard(session.c, await resolveBoard(session, flagString(args, "board")));
+    const input = { title, description: flagString(args, "text") ?? "", labels: flagList(args, "label") ?? [] };
+    const laneFlag = flagString(args, "lane");
+    if (laneFlag)
+        input.state_id = (await laneOn(bc, laneFlag)).id;
+    const type = flagString(args, "type");
+    if (type)
+        input.type = parseType(type);
+    const priority = flagString(args, "priority");
+    if (priority)
+        input.priority = parsePriority(priority);
+    const parent = flagString(args, "parent");
+    if (parent)
+        input.parent_ticket_id = await parentId(session, bc, parent);
+    const created = await createTicket(bc, input);
+    const rest = `Created #${created.number}  in ${L(created.state_name)}.`;
+    const lines = [`Created #${created.number} ${quoted(created.title, Math.max(20, ANSWER_BUDGET - rest.length - 2))} in ${L(created.state_name)}.`];
+    // An unnamed agent hears how to name itself on its first card, before it makes the rest as "agent".
+    if (isUnnamed(session)) {
+        const made = await bc.data.read(async (r) => (await r.tickets.list()).filter((t) => t.created_by === session.actor.name).length);
+        if (made === 1)
+            lines.push(nameYourself(session));
+    }
+    return { text: lines.join("\n"), data: { card: created.number, lane: created.state_name, link: cardLink(bc.board.slug, created.number) }, board: bc };
+}
+export async function cmdEdit(session, args) {
+    const usage = "edit #n [--title T] [--type T] [--priority P] [--label a,b | --add-label x --drop-label y] [--parent #n|none] [--nebula URL|none] [--plan|--summary|--revisions] (text replaces the description, or the field named)";
+    noMoreWords(args, 1, usage, `A new description goes in text${session.transport === "cli" ? ' (-m "...")' : ""}.`);
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, usage);
+    const patch = {};
+    const changed = [];
+    const title = flagString(args, "title");
+    if (title !== undefined) {
+        patch.title = title.trim();
+        changed.push("title");
+    }
+    const type = flagString(args, "type");
+    if (type !== undefined) {
+        patch.type = parseType(type);
+        changed.push("type");
+    }
+    const priority = flagString(args, "priority");
+    if (priority !== undefined) {
+        patch.priority = parsePriority(priority);
+        changed.push("priority");
+    }
+    const set = flagList(args, "label");
+    const add = flagList(args, "add-label");
+    const drop = flagList(args, "drop-label");
+    if (set || add || drop) {
+        const current = set ?? (await bc.data.read(async (r) => ((await labelsByTicket(r, [ticket.id])).get(ticket.id) ?? []).map((label) => label.name)));
+        const dropped = new Set((drop ?? []).map((name) => name.toLowerCase()));
+        const next = [...current, ...(add ?? [])].filter((name) => !dropped.has(name.toLowerCase()));
+        patch.labels = [...new Map(next.map((name) => [name.toLowerCase(), name])).values()];
+        changed.push("labels");
+    }
+    const parent = flagString(args, "parent");
+    if (parent !== undefined) {
+        patch.parent_ticket_id = await parentId(session, bc, parent);
+        changed.push("parent");
+    }
+    const nebula = flagString(args, "nebula");
+    if (nebula !== undefined) {
+        const value = nebula.trim();
+        const kept = /^none$/i.test(value) ? "" : value ? parseNebulaUrl(value) : null;
+        if (kept === null)
+            fail("--nebula takes a web link (https://...) to a Nebula file or folder, or none to remove it.");
+        patch.nebula_url = kept;
+        changed.push("Nebula link");
+    }
+    const field = flagOn(args, "plan") ? ["ai_plan", "plan"] : flagOn(args, "summary") ? ["implementation_summary", "summary"] : flagOn(args, "revisions") ? ["implementation_updates", "revisions"] : ["description", "description"];
+    const text = flagString(args, "text");
+    if (text !== undefined) {
+        patch[field[0]] = text;
+        changed.push(field[1]);
+    }
+    else if (flagOn(args, "plan") || flagOn(args, "summary") || flagOn(args, "revisions")) {
+        fail(`--${field[1]} takes its new text as text.`);
+    }
+    if (!changed.length)
+        fail(`Nothing to change. Usage: ${usageText(inShell(session), usage)}`);
+    await updateTicket(bc, ticket.id, patch);
+    // Show the new title in what room the answer has left.
+    const plain = `#${ticket.number} updated: ${changed.join(", ")}.`;
+    const shown = typeof patch.title === "string" ? changed.map((name) => (name === "title" ? `title ${quoted(patch.title, Math.max(20, ANSWER_BUDGET - plain.length - 3))}` : name)) : changed;
+    return { text: `#${ticket.number} updated: ${shown.join(", ")}.`, data: { card: ticket.number, changed }, board: bc };
+}
+export async function cmdJournal(session, args) {
+    noMoreWords(args, 1, "journal [board]");
+    const row = await resolveBoard(session, flagString(args, "board") ?? args.positional[0]);
+    const bc = await onBoard(session.c, row);
+    const { rules, entries } = await bc.data.read(async (r) => {
+        const [board, all] = await Promise.all([r.board.get(), r.entries.list()]);
+        const live = all.filter((entry) => !entry.struck_at);
+        const ids = live.map((entry) => entry.ticket_id).filter((id) => id !== null);
+        const numbers = new Map((ids.length ? await r.tickets.list({ ids }) : []).map((t) => [t.id, t.number]));
+        return { rules: board.agent_instructions.trim(), entries: live.map((entry) => ({ ...entry, number: entry.ticket_id ? (numbers.get(entry.ticket_id) ?? null) : null })) };
+    });
+    const lines = [rules ? labelled("Board rules:", rules) : NO_RULES, ""];
+    if (!entries.length)
+        lines.push("Journal: empty.");
+    else {
+        const shown = entries.slice(-30);
+        lines.push(`Journal (${entries.length}):`);
+        if (entries.length > shown.length)
+            lines.push(`(${entries.length - shown.length} earlier entries not shown)`);
+        for (const entry of shown) {
+            const meta = [authorText(entry.created_by), entry.created_at.slice(0, 10), entry.number ? `#${entry.number}` : ""].filter(Boolean).join(", ");
+            lines.push(`- ${entry.type}: ${oneLine(entry.title, 160)} (${meta})`);
+            if (block(entry.body, ""))
+                lines.push(block(entry.body));
+        }
+    }
+    return {
+        text: lines.join("\n"),
+        data: { rules, journal: entries.map((e) => ({ type: e.type, title: e.title, body: e.body, by: authorKey(e.created_by), at: e.created_at, card: e.number })) }
+    };
+}
+export async function cmdFind(session, args) {
+    const q = freeWords(args, 0, "search").join(" ").trim();
+    if (!q)
+        fail(`Find what? Usage: ${usageText(inShell(session), "find <words>")}`);
+    const row = await resolveBoard(session, flagString(args, "board"));
+    const bc = await onBoard(session.c, row);
+    const { results } = await searchTickets(bc, { q, limit: 20, mode: "summary", max_chars_per_field: 160 });
+    if (!results.length)
+        return { text: `No card on board ${row.slug} matches "${oneLine(q, 80)}".`, data: { query: q, cards: [] } };
+    const lines = [`${plural(results.length, "card")} on board ${row.slug} ${results.length === 1 ? "matches" : "match"} "${oneLine(q, 80)}":`];
+    const hits = results.map((hit) => ({ n: Number(hit.number), title: String(hit.title), lane: String(hit.state_name), snippet: typeof hit.snippet === "string" ? hit.snippet : "" }));
+    for (const hit of hits) {
+        const snippet = oneLine(hit.snippet, 100);
+        lines.push(`${cardRef(hit)}${snippet && snippet !== hit.title ? `: ${snippet}` : ""}`);
+    }
+    return { text: lines.join("\n"), data: { query: q, cards: hits } };
+}
+/** "30m", "2h", "3d", or a date. */
+function parseSince(value, nowMs) {
+    const text = value.trim();
+    const match = /^(\d+)\s*(m|min|h|d|w)$/i.exec(text);
+    if (match) {
+        const units = { m: 60_000, min: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+        return new Date(nowMs - Number(match[1]) * (units[(match[2] ?? "m").toLowerCase()] ?? 60_000)).toISOString();
+    }
+    if (/^\d{4}-\d{2}-\d{2}/.test(text) && Number.isFinite(Date.parse(text)))
+        return new Date(Date.parse(text)).toISOString();
+    fail("--since takes a time like 30m, 2h, 3d or 2026-10-22.");
+}
+const shortStamp = (iso) => `${iso.slice(5, 10)} ${iso.slice(11, 16)}`;
+export async function cmdChanges(session, args) {
+    noMoreWords(args, 1, "changes [board] [--since 2h]");
+    const row = await resolveBoard(session, flagString(args, "board") ?? args.positional[0]);
+    const bc = await onBoard(session.c, row);
+    const since = parseSince(flagString(args, "since") ?? "24h", Date.parse(session.c.clock.now()));
+    const events = await bc.data.read(async (r) => {
+        const list = await r.events.list({ since });
+        const ids = [...new Set(list.map((e) => e.ticket_id).filter((id) => id !== null))];
+        const tickets = new Map((ids.length ? await r.tickets.list({ ids }) : []).map((t) => [t.id, t]));
+        return list.map((e) => {
+            const ticket = e.ticket_id ? tickets.get(e.ticket_id) : undefined;
+            return { ...e, number: ticket?.number ?? null, title: ticket?.title ?? null };
+        });
+    });
+    const shown = events.slice(-50);
+    if (!events.length)
+        return { text: `No changes on board ${row.slug} since ${shortStamp(since)}.`, data: { since, changes: [] } };
+    const lines = [`Changes on board ${row.slug} since ${shortStamp(since)}: ${events.length}`];
+    if (events.length > shown.length)
+        lines.push(`(${events.length - shown.length} earlier not shown; narrow --since)`);
+    for (const event of shown)
+        lines.push(`${shortStamp(event.created_at)} ${authorText(event.actor)} ${describeEvent(event)}`);
+    return {
+        text: lines.join("\n"),
+        data: { since, changes: shown.map((event) => ({ at: event.created_at, by: authorKey(event.actor), type: event.type, card: event.number, what: describeEvent(event) })) }
+    };
+}
+/** A board's open cards; "missing" when its file is gone, null when it can't be read for another reason. */
+async function openCount(session, id) {
+    try {
+        const data = await session.c.store.board(id);
+        return await data.read(async (r) => {
+            const lanes = await Lanes.of(r);
+            return (await r.tickets.list({ archived: false })).filter((t) => !isClosedLane({ name: lanes.nameOf(t), role: lanes.roleOf(t) })).length;
+        });
+    }
+    catch (error) {
+        return error instanceof OrbitError && error.code === "board_file_missing" ? "missing" : null;
+    }
+}
+export const BOARDS_USAGE = "boards | boards new <name> [--slug s] | boards use <board> | boards link <board> | boards unlink";
+export async function cmdBoards(session, args) {
+    const [sub, ...rest] = args.positional;
+    if (sub === "use") {
+        noMoreWords(args, 2, "boards use <board>");
+        const slug = rest[0];
+        if (!slug)
+            fail("Use which board? boards use <board>");
+        const row = await boardRowFor(session, slug);
+        if (!row)
+            fail(`No board "${oneLine(slug, 60)}". Boards: ${(await boardList(session)) || "none yet"}.`);
+        session.board = row.slug;
+        if (setsComputerDefault(session)) {
+            await session.c.store.settings.set(DEFAULT_BOARD, row.slug);
+            return { text: `Board ${row.slug} is now the default for every folder and agent on this computer.`, data: { board: row.slug, default: true } };
+        }
+        // One agent's choice must never move another agent's commands.
+        const text = session.transport === "cli"
+            ? `Board ${row.slug} chosen for this command only. This Orbit is shared, so set ORBIT_BOARD=${row.slug} or name the board in each command.`
+            : `Board ${row.slug} chosen for this session; the default board stays as it was.`;
+        return { text, data: { board: row.slug, default: false } };
+    }
+    if (sub === "new") {
+        const name = freeWords(args, 1, "board name").join(" ").trim();
+        if (!name)
+            fail("boards new needs a name: boards new <name> [--slug s] [--no-ai]");
+        const input = { name };
+        const slug = flagString(args, "slug");
+        if (slug)
+            input.slug = slug;
+        if (flagOn(args, "no-ai"))
+            input.ai_enabled = false;
+        const created = await createBoard(session.c, input);
+        const row = await session.c.store.boards.get(created.id);
+        if (!row)
+            fail(`Board ${created.slug} was made but isn't listed.`);
+        session.board = row.slug;
+        const bc = await onBoard(session.c, row);
+        const lanes = (await bc.data.read((r) => r.states.list())).map((s) => L(s.name));
+        // A shell forgets between commands, and an MCP session ends, so with several boards the answer says how a repo keeps it.
+        const made = `Created board ${row.slug} (${quoted(created.name, 60)})`;
+        const several = (await session.c.store.boards.list()).length > 1;
+        const text = session.transport !== "cli"
+            ? `${made} and chose it. Lanes: ${lanes.join(", ")}.${several ? ` For later sessions, let ${callerPlace(session)} name it (boards link ${row.slug} says how).` : ""}`
+            : `${made}. Lanes: ${lanes.join(", ")}.${several ? ` Name it in commands (orbit view ${row.slug}) or let ${callerPlace(session)} name it: orbit boards link ${row.slug}.` : ""}`;
+        return { text, data: { board: row.slug, lanes }, board: bc };
+    }
+    if (sub === "link" || sub === "unlink")
+        return boardsLink(session, args, sub, rest);
+    if (sub !== undefined)
+        fail(`boards takes: ${BOARDS_USAGE}.`);
+    const rows = await session.c.store.boards.list();
+    if (!rows.length)
+        return { text: noBoardsText(session), data: { boards: [] } };
+    const lines = [`Boards (${rows.length}):`];
+    const data = [];
+    const saved = (await savedDefault(session))?.slug ?? null;
+    // The board a command naming none would use, as resolveBoard picks it.
+    const repo = repoChoice(session);
+    const repoRow = repo.board ? rows.find((row) => row.slug === repo.board) : undefined;
+    const inUse = session.board ?? (repo.board || repo.problem ? repoRow?.slug : (saved ?? (rows.length === 1 ? rows[0]?.slug : null)));
+    for (const row of rows) {
+        const open = await openCount(session, row.id);
+        const current = row.slug === inUse ? "*" : " ";
+        const fromRepo = Boolean(repoRow && row.slug === repoRow.slug);
+        const notes = [row.slug === saved ? "default" : "", fromRepo ? "this repo's orbit.json" : ""].filter(Boolean);
+        const count = open === "missing" ? "file missing" : `${open ?? "?"} open`;
+        lines.push(`${current} ${row.slug} ${quoted(row.name, 60)}: ${count}${notes.length ? ` (${notes.join("; ")})` : ""}`);
+        data.push({ board: row.slug, name: row.name, open: typeof open === "number" ? open : null, ...(open === "missing" ? { file_missing: true } : {}), current: current === "*", default: row.slug === saved, repo: fromRepo });
+    }
+    if (repo.problem)
+        lines.push(repoProblemText(repo));
+    else if (repo.board && !repoRow)
+        lines.push(`This repo's orbit.json names board ${oneLine(repo.board, 60)}, which this Orbit doesn't have.`);
+    return { text: lines.join("\n"), data: { boards: data } };
+}
+/**
+ * `boards link <board>`: the repo names its board in orbit.json. Only a shell
+ * on this computer writes the file (a remote shell's client writes it after
+ * the server checks the board); elsewhere Orbit writes no files, so the
+ * answer says how.
+ */
+async function boardsLink(session, args, sub, rest) {
+    noMoreWords(args, sub === "link" ? 2 : 1, sub === "link" ? "boards link <board>" : "boards unlink");
+    const writer = setsComputerDefault(session) ? session.repo?.link : undefined;
+    let slug = null;
+    if (sub === "link") {
+        const ident = rest[0];
+        if (!ident)
+            fail(`Link which board? ${hint(session, "boards link <board>")} (boards: ${(await boardList(session)) || "none yet"}).`);
+        const row = await boardRowFor(session, ident);
+        if (!row)
+            fail(`No board "${oneLine(ident, 60)}". Boards: ${(await boardList(session)) || "none yet"}.`);
+        slug = row.slug;
+    }
+    if (writer) {
+        const result = writer(sub, slug);
+        if (!result.ok)
+            fail(result.text);
+        return { text: result.text, data: result.data };
+    }
+    const text = sub === "link"
+        ? `Orbit writes no files from here. To have the repo name board ${slug ?? ""}, run orbit boards link ${slug ?? ""} in a terminal there, or commit an orbit.json at the repo's top holding {"board": "${slug ?? ""}"}.`
+        : 'Orbit writes no files from here. To unlink, run orbit boards unlink in a terminal in the repo, or remove "board" from its orbit.json.';
+    return { text, data: { board: slug, linked: false } };
+}
+const LINK_TYPES = { blocks: "blocks", "blocked-by": "blocked_by", blockedby: "blocked_by", relates: "relates_to", "relates-to": "relates_to", related: "relates_to" };
+const LINK_WORDS = { blocks: "blocks", blocked_by: "is blocked by", relates_to: "relates to" };
+export async function cmdLink(session, args) {
+    const usage = "link #a blocks|blocked-by|relates #b";
+    noMoreWords(args, 3, usage);
+    const [first, how, second] = args.positional;
+    const type = LINK_TYPES[(how ?? "").toLowerCase()];
+    if (!type || second === undefined)
+        fail(`Link how? ${usage}`);
+    const a = await resolveCard(session, first, args, usage);
+    const b = await resolveCard(session, second, args, usage);
+    if (a.bc.board.id !== b.bc.board.id) {
+        // Across boards a link can block or relate; it lives on the card that waits.
+        await linkAcrossBoards(session.c, a.bc, a.ticket.id, b.bc, b.ticket.id, type);
+        const [from, to] = [`${a.bc.board.slug}#${a.ticket.number}`, `${b.bc.board.slug}#${b.ticket.number}`];
+        return { text: `${from} ${LINK_WORDS[type] ?? type} ${to}.`, data: { from, type, to }, board: a.bc };
+    }
+    await createRelation(a.bc, { source_ticket_id: a.ticket.id, target_ticket_id: b.ticket.id, type });
+    return { text: `#${a.ticket.number} ${LINK_WORDS[type] ?? type} #${b.ticket.number}.`, data: { from: a.ticket.number, type, to: b.ticket.number }, board: a.bc };
+}
+/** The links across boards between two cards, each with the board it lives on. */
+async function crossLinksBetween(a, b) {
+    const found = [];
+    for (const [here, there] of [[a, b], [b, a]]) {
+        const ids = await here.bc.data.read(async (r) => (await r.crossBoardRelations.list(here.ticket.id)).filter((x) => x.target_board_id === there.bc.board.id && x.target_ticket_id === there.ticket.id).map((x) => x.id));
+        for (const id of ids)
+            found.push({ bc: here.bc, id });
+    }
+    return found;
+}
+export async function cmdUnlink(session, args) {
+    const usage = "unlink #a #b";
+    noMoreWords(args, 2, usage);
+    const a = await resolveCard(session, args.positional[0], args, usage);
+    const b = await resolveCard(session, args.positional[1], args, usage);
+    if (a.bc.board.id !== b.bc.board.id) {
+        const [from, to] = [`${a.bc.board.slug}#${a.ticket.number}`, `${b.bc.board.slug}#${b.ticket.number}`];
+        const links = await crossLinksBetween(a, b);
+        if (!links.length)
+            fail(`${from} and ${to} aren't linked.`);
+        for (const link of links)
+            await unlinkAcrossBoards(link.bc, link.id);
+        return { text: `${from} and ${to} unlinked.`, data: { unlinked: [from, to] }, board: a.bc };
+    }
+    const ids = await a.bc.data.read(async (r) => (await r.relations.list(a.ticket.id))
+        .filter((x) => (x.source_ticket_id === a.ticket.id && x.target_ticket_id === b.ticket.id) || (x.source_ticket_id === b.ticket.id && x.target_ticket_id === a.ticket.id))
+        .map((x) => x.id));
+    if (!ids.length)
+        fail(`#${a.ticket.number} and #${b.ticket.number} aren't linked.`);
+    for (const id of ids)
+        await deleteRelation(a.bc, id);
+    return { text: `#${a.ticket.number} and #${b.ticket.number} unlinked.`, data: { unlinked: [a.ticket.number, b.ticket.number] }, board: a.bc };
+}
+export async function cmdArchive(session, args) {
+    noMoreWords(args, 1, "archive #n");
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, "archive #n");
+    await archiveTicket(bc, ticket.id);
+    return { text: `#${ticket.number} archived.`, data: { card: ticket.number, archived: true }, board: bc };
+}
+export async function cmdRestore(session, args) {
+    noMoreWords(args, 1, "restore #n");
+    const { bc, ticket } = await resolveCard(session, args.positional[0], args, "restore #n");
+    const after = await restoreTicket(bc, ticket.id);
+    return { text: `#${ticket.number} restored to ${L(after.state_name)}.`, data: { card: ticket.number, lane: after.state_name }, board: bc };
+}