@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/team/commands.ts

@@ -0,0 +1,112 @@
+/**
+ * `/team` — the lead's round, printed.
+ *
+ * The Team tab is the same round with a mouse; a lead reading a TUI should not have to
+ * open a browser to see what needs a decision, so the command prints the rollup the
+ * tool returns and one line saying who is live. It reads the cards and the bus's records
+ * and writes nothing: acting on the round is `team`'s tool (`assign`, `reclaim`) or
+ * `board`'s.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Card } from "../../lib/board/card.ts";
+import { buildRound } from "../../lib/board/round.ts";
+import { formatRound, plural } from "../../lib/board/round-text.ts";
+import type { BoardSession } from "../../lib/board/session.ts";
+import { createTeamJoin, type JoinResult, type TeamJoin } from "../../lib/session-tool.ts";
+import { readRoster, type RosterSession, rosterStateOf } from "../../lib/session-roster.ts";
+import { formatJoined, formatNotJoined } from "./format.ts";
+
+/** The command's name, which is also the word a user types. */
+export const TEAM_COMMAND = "team";
+
+/** The words the command accepts besides the round itself. */
+export const TEAM_WORDS = ["join"] as const;
+
+/** How many lines a round may print before it says how many it left out. */
+export const MAX_ROUND_LINES = 10;
+
+export function registerCommands(pi: ExtensionAPI, session: BoardSession, deps: { team?: TeamJoin } = {}): void {
+	const team = deps.team ?? createTeamJoin(pi);
+	pi.registerCommand(TEAM_COMMAND, {
+		description: "The lead's round: who holds what, and what needs a decision; `/team join [<label>]` joins the team",
+		getArgumentCompletions: (prefix: string) => {
+			const text = prefix.trimStart();
+			if (text.includes(" ")) return null;
+			const items = TEAM_WORDS.filter((word) => word.startsWith(text));
+			return items.length > 0 ? items.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const [word = "", ...rest] = args.trim().split(/\s+/).filter(Boolean);
+			if (word === "join") {
+				const label = rest.join(" ").trim();
+				const joined = await team.join(ctx, label === "" ? undefined : label);
+				ctx.ui.notify(joinedLine(joined), joined.ok ? "info" : "warning");
+				return;
+			}
+			if (word !== "") {
+				ctx.ui.notify(
+					`team: "${word}" is not a word this command knows — try /team, or /team join [<label>]`,
+					"warning",
+				);
+				return;
+			}
+			const store = await session.store(ctx.cwd);
+			const cards = await store.list();
+			// The roster is read as data, so a repository with no bus prints the round and
+			// says nothing about who is here rather than failing.
+			const roster = await readRoster(await session.busDir(ctx.cwd));
+			ctx.ui.notify(roundText(cards, session.now(), roster), "info");
+		},
+	});
+}
+
+/** `/team join`'s line: who this session is on the team, or why it is on none. */
+export function joinedLine(result: JoinResult): string {
+	return result.ok ? formatJoined(result.label, result.watching) : formatNotJoined(result.error);
+}
+
+/**
+ * The round as the lines a lead reads: the rollup, then who is live.
+ *
+ * Capped, because a notify is a message and not a screen: past its limit the round says
+ * how many lines it left out instead of pushing the rest of the session up the screen.
+ */
+export function roundText(cards: readonly Card[], now: number, roster?: readonly RosterSession[]): string {
+	if (cards.length === 0) return "team: nothing to report — the board is empty";
+	const round = formatRound(cards, buildRound(cards, now)).split("\n");
+	const shown = round.slice(0, MAX_ROUND_LINES);
+	if (round.length > MAX_ROUND_LINES) shown.push(`… ${plural(round.length - MAX_ROUND_LINES, "line")} more`);
+	const who = presenceLine(roster, now);
+	if (who !== undefined) shown.push(who);
+	return shown.join("\n");
+}
+
+/**
+ * `live: a, b · not listening: b · quiet: c`, or nothing when nobody is here.
+ *
+ * Three facts, and the middle one is the one a lead can act on: a live session that is
+ * not listening reads mail at its next turn rather than being woken for it. It is only
+ * named when its record says so — a session that never wrote the field is not accused of
+ * ignoring anything.
+ */
+function presenceLine(roster: readonly RosterSession[] | undefined, now: number): string | undefined {
+	if (roster === undefined || roster.length === 0) return undefined;
+	const live: string[] = [];
+	const quiet: string[] = [];
+	const silent: string[] = [];
+	for (const session of roster) {
+		if (rosterStateOf(session, now) !== "live") {
+			quiet.push(session.label);
+			continue;
+		}
+		live.push(session.label);
+		if (session.watching?.armed === false) silent.push(session.label);
+	}
+	const parts = [
+		live.length > 0 ? `live: ${live.join(", ")}` : "",
+		silent.length > 0 ? `not listening: ${silent.join(", ")}` : "",
+		quiet.length > 0 ? `quiet: ${quiet.join(", ")}` : "",
+	];
+	return parts.filter((part) => part !== "").join(" · ");
+}

package/extensions/team/dispatch.ts

@@ -0,0 +1,133 @@
+/**
+ * The handoff: what `team assign` tells the peer, and how it tells it.
+ *
+ * The peer is a session that is already running, so this is a message and not a
+ * process: `session send` writes it into the recipient's inbox, and its armed watch is
+ * what raises the turn. Nothing here starts anything, and a send that fails leaves the
+ * card exactly as it was — the order is deliberate, because a card assigned without a
+ * message is a card nobody knows about.
+ *
+ * The transport is a seam (`Dispatch`), so the tool's ordering is testable without a
+ * bus, and the one production implementation is `lib/session-tool.ts`'s.
+ */
+
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { Card } from "../../lib/board/card.ts";
+import { cardRef, type CardOwner } from "../../lib/board/card.ts";
+import { listPeers, MAX_MESSAGE_TEXT, type Peer, send as sendTo } from "../../lib/session-tool.ts";
+
+/** How a handoff reaches a peer, and what the bus can say about the peers there are. */
+export interface Dispatch {
+	/** Send the text as `kind`, and report the labels a message file was written for. Throws on failure. */
+	send(input: { kind: "handoff" | "event"; to: string; text: string }): Promise<{ delivered: string[] }>;
+	/**
+	 * Every session the bus lists, when it can say.
+	 *
+	 * Its record is what makes an assignment survive a rename — `holds` compares ids
+	 * before labels — and what makes the report able to name a peer that cannot be
+	 * woken. It never throws: a resolve that fails must not undo a handoff that landed.
+	 */
+	peers(): Promise<Peer[] | undefined>;
+}
+
+/**
+ * What the peer reads.
+ *
+ * It names the card, its outcome, and the paths, and says what to do next: record the
+ * plan, work, note, finish. It does **not** ask the peer to claim the card — `assign`
+ * has already recorded the owner, and a claim by the holder is a no-op. The claim is
+ * only for the failure path where the send landed and the assignment did not.
+ */
+export function handoffText(card: Card, to: string, note?: string): string {
+	const lines = [
+		`Handoff: ${cardRef(card.id)} "${card.title}" is yours, ${to}.`,
+		card.paths.length > 0 ? `Paths: ${card.paths.join(", ")}` : undefined,
+		card.plan === undefined ? undefined : `Plan: ${card.plan}`,
+		note === undefined ? undefined : `Note: ${note}`,
+		`It is already assigned to you — record the plan with board action "plan" if it has none, then note each phase and move it to done or blocked.`,
+	].filter((line): line is string => line !== undefined);
+	return withinLimit(lines.join("\n"));
+}
+
+/**
+ * What every live session reads when the lead offers a card instead of assigning it.
+ *
+ * An offer names no owner: the first peer to claim the card takes it, so the text says
+ * what the card is and that claiming is the next step, and it never implies the work is
+ * already somebody's.
+ */
+export function offerText(card: Card, note?: string): string {
+	const lines = [
+		`Offer: ${cardRef(card.id)} "${card.title}" is unclaimed.`,
+		card.paths.length > 0 ? `Paths: ${card.paths.join(", ")}` : undefined,
+		card.plan === undefined ? undefined : `Plan: ${card.plan}`,
+		note === undefined ? undefined : `Note: ${note}`,
+		`First to claim it takes it: run board action "claim" with card "${card.id}", then note each phase and move it to done or blocked.`,
+	].filter((line): line is string => line !== undefined);
+	return withinLimit(lines.join("\n"));
+}
+
+/**
+ * Trim to the bus's text limit, which is also this message's limit.
+ *
+ * Not `lib/tui/columns.ts`'s `clip`: that one measures terminal columns, and this one
+ * counts characters, because the bus's limit is characters. The number arrives from
+ * `lib/session-tool.ts` — one copy for the two extensions that send through it.
+ */
+function withinLimit(text: string): string {
+	return text.length > MAX_MESSAGE_TEXT ? `${text.slice(0, MAX_MESSAGE_TEXT - 1)}…` : text;
+}
+
+/** The production dispatch: `lib/session-tool.ts`, with a failure turned into a throw. */
+export function sessionDispatch(ctx: ExtensionToolContext): Dispatch {
+	return {
+		async send(input) {
+			const result = await sendTo(ctx, input);
+			// `assign` and `offer` branch on a failed send, so this seam reports it the way
+			// they read it: the bus's sentence, as the reason the card was not handed over.
+			if (!result.ok) throw new Error(result.error);
+			return { delivered: result.delivered };
+		},
+		peers: () => listPeers(ctx),
+	};
+}
+
+/**
+ * The peer `to` names: an id exactly, else a label ignoring case.
+ *
+ * The send has already proved exactly one session answers to it, so the first match is
+ * the recipient; a miss means the bus could not say, which is why the caller falls back
+ * to the label alone.
+ */
+export function peerFor(peers: readonly Peer[] | undefined, to: string): Peer | undefined {
+	if (peers === undefined) return undefined;
+	const target = to.trim();
+	const byId = peers.find((peer) => peer.id === target);
+	if (byId) return byId;
+	const wanted = target.toLowerCase();
+	return peers.find((peer) => peer.label.toLowerCase() === wanted);
+}
+
+/**
+ * The labels a message reached that cannot be woken: their record says they are not
+ * listening.
+ *
+ * A label the bus could not answer for is left out — "the record does not say" is not
+ * "nobody will read it" — and so is a peer the bus lists as listening.
+ */
+export function notListening(peers: readonly Peer[] | undefined, labels: readonly string[]): string[] {
+	if (peers === undefined) return [];
+	return labels.filter((label) => {
+		const peer = peerFor(peers, label);
+		return peer !== undefined && peer.listening === false;
+	});
+}
+
+/**
+ * The peer a handoff names, as the card records it when the bus cannot say who that
+ * is: the label a message file was written for, else the one that was asked for.
+ */
+export function ownerFor(to: string, delivered: readonly string[]): CardOwner {
+	const label = delivered[0] ?? to;
+	return { label };
+}

package/extensions/team/format.ts

@@ -0,0 +1,105 @@
+/**
+ * The model-facing text for one `team` call.
+ *
+ * A handoff is stated as what happened and what did not: `handed off` names the peer
+ * and the card, a failed send says the card is untouched, and an assignment that lost
+ * a race after the send says the peer should claim it. Nothing here claims the peer
+ * read the message — `delivered` means a message file was written for it.
+ */
+
+import { type Card, cardRef } from "../../lib/board/card.ts";
+
+/** `/team join` landed: the label peers address, and whether mail will reach this session. */
+export function formatJoined(label: string, watching: { armed: boolean }): string {
+	const state = watching.armed ? "listening for handoffs" : "not listening";
+	return `team: on the team as ${label}, ${state}.`;
+}
+
+/** `/team join` did not land, so nothing about this session changed. */
+export function formatNotJoined(reason: string): string {
+	return `team: not on the team — ${reason}`;
+}
+
+/**
+ * A card that was handed over, and the peer that got the message.
+ *
+ * `notListening` is the one fact the send cannot tell you and the record can: a peer
+ * that is not listening reads the handoff at its next turn rather than being woken for
+ * it. Saying so is the difference between "delivered" and "delivered and read".
+ */
+export function formatHandoff(
+	card: Card,
+	to: string,
+	delivered: readonly string[],
+	notListening: readonly string[] = [],
+): string {
+	const who = delivered.length > 0 ? delivered.join(", ") : to;
+	return [
+		`${cardRef(card.id)} handed off to ${who}.`,
+		`  ${card.title}`,
+		card.paths.length > 0 ? `  paths: ${card.paths.join(", ")}` : undefined,
+		"  The card is already owned by the peer; the handoff is in its inbox.",
+		notListeningLine(notListening),
+	]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+}
+
+/**
+ * The line that names a peer which will not be woken, or nothing when every peer is
+ * listening.
+ *
+ * One sentence for both verbs: what the mail does instead, and no pronoun, because the
+ * list can hold one peer or three.
+ */
+export function notListeningLine(labels: readonly string[]): string | undefined {
+	if (labels.length === 0) return undefined;
+	return `  Not listening: ${labels.join(", ")} — it reads this at its next turn.`;
+}
+
+/** The send that never landed: the card was not touched. */
+export function formatHandoffFailure(card: Card, to: string, reason: string): string {
+	return `${cardRef(card.id)} was not handed off to ${to}: ${reason}\n  The card is unchanged.`;
+}
+
+/**
+ * A card offered to the team: who heard, and that nobody holds it yet.
+ *
+ * `offer` writes nothing, so the sentence has to say the ownership question is still
+ * open — a reader who took "offered" for "assigned" would stop looking at the card.
+ */
+export function formatOffer(card: Card, delivered: readonly string[], notListening: readonly string[] = []): string {
+	const who = delivered.length > 0 ? delivered.join(", ") : "nobody";
+	return [
+		`${cardRef(card.id)} offered to ${who}.`,
+		`  ${card.title}`,
+		card.paths.length > 0 ? `  paths: ${card.paths.join(", ")}` : undefined,
+		"  The card is unowned until one of them claims it.",
+		notListeningLine(notListening),
+	]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+}
+
+/** The broadcast that never landed: no card was touched, and nobody heard. */
+export function formatOfferFailure(card: Card, reason: string): string {
+	return `${cardRef(card.id)} was not offered: ${reason}\n  The card is unchanged.`;
+}
+
+/**
+ * The send landed and the assignment then lost a race.
+ *
+ * The peer has a message telling it the card is its, so the correction names the
+ * claim rather than pretending nothing happened.
+ */
+export function formatRacedAssignment(card: Card, to: string, reason: string): string {
+	return (
+		`${cardRef(card.id)} was handed off to ${to}, but the card changed before it could be assigned: ${reason}\n` +
+		`  ${to} should run \`board\` action \`claim\` with card "${card.id}".`
+	);
+}
+
+/** A card taken back to To do. */
+export function formatReclaimed(card: Card, previous: string): string {
+	return `${cardRef(card.id)} reclaimed from ${previous} and back in To do; its notes are kept.\n  ${card.title}`;
+}

package/extensions/team/index.ts

@@ -0,0 +1,33 @@
+/**
+ * team — the lead's round over the shared board.
+ *
+ * `board` owns the cards and never touches the session bus; `team` owns the two
+ * actions that need it. `assign` hands a card to a session that is already running
+ * and sends it a handoff — dispatch cannot start a peer's turn, and the page and the
+ * docs say so — and `reclaim` takes a card back when its owner has gone quiet. Its one
+ * command, `/team`, prints the round the board's Team tab draws, without a browser.
+ *
+ * Either extension works without the other: `board` is the work list any session
+ * uses, and `team` is the lead's. The factory only registers; the store is opened on
+ * first use.
+ *
+ * Load with:  pi --extension ./extensions/team --extension ./extensions/session-bus
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type BoardSession, openBoardSession } from "../../lib/board/session.ts";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { registerCommands } from "./commands.ts";
+import { registerTools } from "./tools.ts";
+
+export interface TeamDeps {
+	/** Test seam: a session with a temp agent directory and a fixed clock. */
+	session?: BoardSession;
+}
+
+export default function team(pi: ExtensionAPI, deps: TeamDeps = {}): void {
+	if (!isExtensionEnabled("team")) return;
+	const session = deps.session ?? openBoardSession(pi);
+	registerTools(pi, session);
+	registerCommands(pi, session);
+}

package/extensions/team/schema.ts

@@ -0,0 +1,29 @@
+/**
+ * The `team` tool's parameters: two actions over one card.
+ *
+ * `assign` names the peer a handoff goes to, and `reclaim` takes a card back. Both
+ * take the card the way `board` does — `4` or `#4` — because a lead reads ids off
+ * the same board.
+ */
+
+import { Type } from "typebox";
+import { TEAM_ACTIONS } from "./types.ts";
+
+export const TeamParams = Type.Object({
+	action: Type.Union(
+		TEAM_ACTIONS.map((action) => Type.Literal(action)),
+		{
+			description:
+				"`assign` hands a card to a running session and sends it a handoff; `offer` broadcasts an unclaimed card to " +
+				"every other live session and writes nothing, so the first to claim it takes it; `reclaim` takes a card back " +
+				"to To do. A lead's three actions — use `board` to create, claim, move, note, and finish the cards themselves.",
+		},
+	),
+	card: Type.String({ description: 'The card to act on, e.g. "4" or "#4".' }),
+	to: Type.Optional(
+		Type.String({
+			description: "`assign`: the peer to hand the card to, as `/team` lists them — a teammate's label or id.",
+		}),
+	),
+	note: Type.Optional(Type.String({ description: "`assign` or `offer`: a line to include, e.g. what to do first." })),
+});

package/extensions/team/tools.ts

@@ -0,0 +1,246 @@
+/**
+ * The `team` tool: the lead's round over the same cards `board` owns.
+ *
+ * Two actions, because those are the two that need the bus. `assign` sends the
+ * handoff **first** and sets the owner **second**: a card assigned without a message
+ * is a card nobody knows about, while a message for a card that then changed is one
+ * the peer can still claim. Either failure is reported with the card as it actually
+ * is, so the lead's next call starts from the truth.
+ *
+ * `reclaim` needs no message — it is the compensation for a dispatch that did not
+ * land — and it belongs here rather than in `board` because it only makes sense in
+ * the lead's context.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
+import { type Card, cardRef, normalizeCardId } from "../../lib/board/card.ts";
+import { indexOf } from "../../lib/board/links.ts";
+import { type Actor, applyOp } from "../../lib/board/rules.ts";
+import type { BoardSession } from "../../lib/board/session.ts";
+import type { BoardStore } from "../../lib/board/store.ts";
+import { messageOf } from "../../lib/errors.ts";
+import { failedResult, type ToolFailure, textResult } from "../../lib/tool-result.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
+import { plural } from "../../lib/board/round-text.ts";
+import { type Dispatch, handoffText, notListening, offerText, ownerFor, peerFor, sessionDispatch } from "./dispatch.ts";
+import {
+	formatHandoff,
+	formatHandoffFailure,
+	formatOffer,
+	formatOfferFailure,
+	formatRacedAssignment,
+	formatReclaimed,
+} from "./format.ts";
+import { TeamParams } from "./schema.ts";
+import { normalizeTeamAction, TEAM_ACTIONS, TEAM_TOOL, type TeamAction, type TeamDetails } from "./types.ts";
+
+/** The parameters as the schema validates them. */
+type TeamArgs = Static<typeof TeamParams>;
+
+/** One refusal: the reason for the model, the state for the renderer. */
+function refusal(action: TeamAction, message: string, card?: Card): ToolFailure<TeamDetails> {
+	return failedResult(`Error: ${message}`, { action, error: message, ...(card === undefined ? {} : { card }) });
+}
+
+/** The call line's subject: the verb, the card, and the peer it names. */
+function callSubject(action: TeamAction, args: Record<string, unknown>): string {
+	const card = typeof args.card === "string" && args.card.trim() !== "" ? cardRef(args.card.trim()) : "";
+	const to = typeof args.to === "string" && args.to.trim() !== "" ? ` → ${args.to.trim()}` : "";
+	return card === "" ? action : `${action} ${card}${action === "assign" ? to : ""}`;
+}
+
+/** What the tool needs from the outside, so a suite drives it without a bus. */
+export interface TeamToolsDeps {
+	/** Test seam: the handoff transport. */
+	dispatch?: (ctx: Parameters<typeof sessionDispatch>[0]) => Dispatch;
+}
+
+export function registerTools(pi: ExtensionAPI, session: BoardSession, deps: TeamToolsDeps = {}): void {
+	const dispatchFor = deps.dispatch ?? sessionDispatch;
+
+	pi.registerTool({
+		name: TEAM_TOOL,
+		label: "Team",
+		description:
+			"Run a round of work over the shared board: `assign` hands a card to a running session and sends it a handoff " +
+			"(`to` is a teammate's label or id, as `/team` lists them); `offer` broadcasts an unclaimed card to every other " +
+			"live session and writes nothing, so the first to claim it takes it; `reclaim` takes a card back to To do and " +
+			"sends nothing, so it needs no team. Use `board` for everything else. Nothing here starts a peer's turn: a " +
+			"message waits in its inbox, and a peer that is listening reports it at its next turn.",
+		promptSnippet: "Run a round over the board: assign a card to a running session, offer one, or reclaim one.",
+		promptGuidelines: [
+			"Open the board with `/board` or work a card first, so this session and its peers are on the team.",
+			"Offer a card nobody has taken; assign one you mean a particular peer to hold.",
+			"When a result says `Not listening`, say so: the message waits for that peer's next turn.",
+			"Reclaim a card whose owner has gone quiet rather than editing someone else's work.",
+		],
+		parameters: TeamParams,
+		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const args = params as TeamArgs;
+			const action = normalizeTeamAction(args.action);
+			if (!action) {
+				return refusal("assign", `unknown action "${String(args.action)}"; use ${TEAM_ACTIONS.join(" or ")}.`);
+			}
+			const id = normalizeCardId(args.card);
+			if (id === undefined) return refusal(action, `"${String(args.card)}" is not a card id.`);
+			const me = session.who(ctx, ctx.cwd);
+			try {
+				const store = await session.store(ctx.cwd);
+				const now = session.now();
+				if (action === "reclaim") return await reclaimCard(store, me, id, now);
+				if (action === "offer") return await offerCard(store, id, args.note, now, dispatchFor(ctx));
+				const to = typeof args.to === "string" ? args.to.trim() : "";
+				if (to === "") return refusal("assign", 'assign needs a peer: pass `to`, e.g. "billing-core".');
+				return await assignCard(store, me, id, to, args.note, now, dispatchFor(ctx));
+			} catch (error) {
+				return refusal(action, messageOf(error));
+			}
+		},
+
+		renderCall(args, theme, context) {
+			const action = normalizeTeamAction(args.action) ?? "assign";
+			return callLine(theme, context.lastComponent, TEAM_TOOL, callSubject(action, args as Record<string, unknown>));
+		},
+
+		renderResult(result, _options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<TeamDetails>(result.details);
+			const outcome = detailsOrLine(theme, result, false, details);
+			text.setText("line" in outcome ? outcome.line : summaryOf(outcome.details));
+			return text;
+		},
+	});
+}
+
+/**
+ * `assign`: check the preconditions, send the handoff, then set the owner.
+ *
+ * The preconditions are checked with the same `applyOp` the store will use, so an
+ * assignment the rules would refuse never sends a message at all.
+ */
+async function assignCard(
+	store: BoardStore,
+	me: Actor,
+	id: string,
+	to: string,
+	note: string | undefined,
+	now: number,
+	dispatch: Dispatch,
+): Promise<ReturnType<typeof textResult<TeamDetails>> | ToolFailure<TeamDetails>> {
+	const card = await store.read(id);
+	if (!card) return refusal("assign", `${cardRef(id)} does not exist.`);
+	const owner: Actor = { label: to };
+	// The board, not just the card: a card that waits on unfinished work is refused here,
+	// so a handoff for it is never sent.
+	const dry = applyOp(card, { kind: "assign", to: owner }, me, now, indexOf(await store.list()));
+	if (!dry.ok) return refusal("assign", dry.error, card);
+
+	let delivered: string[];
+	try {
+		delivered = (await dispatch.send({ kind: "handoff", to, text: handoffText(card, to, note) })).delivered;
+	} catch (error) {
+		return refusal("assign", formatHandoffFailure(card, to, messageOf(error)), card);
+	}
+
+	// Ask the bus which session answers to the label: an owner recorded with its id
+	// survives the peer renaming itself, which a label alone does not — and the same read
+	// says whether that peer will be woken by the message it just got.
+	const peers = await dispatch.peers().catch(() => undefined);
+	const peer = peerFor(peers, to);
+	const applied = await store.mutate(
+		id,
+		{ kind: "assign", to: peer === undefined ? ownerFor(to, delivered) : { id: peer.id, label: peer.label } },
+		me,
+		now,
+	);
+	if (!applied.ok)
+		return refusal("assign", formatRacedAssignment(applied.card ?? card, to, applied.error), applied.card ?? card);
+	const silent = notListening(peers, delivered);
+	return textResult(formatHandoff(applied.card, to, delivered, silent), {
+		action: "assign",
+		card: applied.card,
+		assigned: applied.card.owner,
+		delivered,
+		...(silent.length === 0 ? {} : { notListening: silent }),
+	});
+}
+
+/**
+ * The actor an offer's preconditions are judged as: nobody in particular.
+ *
+ * `claim` is what the offer asks a peer to do, so the dry run is a claim by someone who
+ * holds nothing — the rules' own refusals decide whether a card may be offered at all,
+ * without a second copy of the sentences.
+ */
+const OFFER_CLAIMANT: Actor = { label: "*" };
+
+/**
+ * `offer`: check the claim's preconditions, broadcast the card, and write nothing.
+ *
+ * The order matters less here than in `assign`, because nothing is written: a failed
+ * broadcast leaves the card exactly as it was, and the first peer to claim is what makes
+ * an offer into work. Two peers racing are settled by the store's compare-and-set.
+ */
+async function offerCard(
+	store: BoardStore,
+	id: string,
+	note: string | undefined,
+	now: number,
+	dispatch: Dispatch,
+): Promise<ReturnType<typeof textResult<TeamDetails>> | ToolFailure<TeamDetails>> {
+	const card = await store.read(id);
+	if (!card) return refusal("offer", `${cardRef(id)} does not exist.`);
+	// The board, not just the card: a card that waits on unfinished work, or one somebody
+	// holds, is refused here, so a broadcast for it is never sent.
+	const dry = applyOp(card, { kind: "claim" }, OFFER_CLAIMANT, now, indexOf(await store.list()));
+	if (!dry.ok) return refusal("offer", dry.error, card);
+
+	let delivered: string[];
+	try {
+		delivered = (await dispatch.send({ kind: "event", to: "*", text: offerText(card, note) })).delivered;
+	} catch (error) {
+		return refusal("offer", formatOfferFailure(card, messageOf(error)), card);
+	}
+	const peers = await dispatch.peers().catch(() => undefined);
+	const silent = notListening(peers, delivered);
+	return textResult(formatOffer(card, delivered, silent), {
+		action: "offer",
+		card,
+		delivered,
+		...(silent.length === 0 ? {} : { notListening: silent }),
+	});
+}
+
+/** `reclaim`: the owner clears and the card returns to To do, notes and all. */
+async function reclaimCard(
+	store: BoardStore,
+	me: Actor,
+	id: string,
+	now: number,
+): Promise<ReturnType<typeof textResult<TeamDetails>> | ToolFailure<TeamDetails>> {
+	const before = await store.read(id);
+	if (!before) return refusal("reclaim", `${cardRef(id)} does not exist.`);
+	const previous = before.owner?.label;
+	if (previous === undefined) return refusal("reclaim", `${cardRef(id)} has no owner to reclaim.`, before);
+	const result = await store.mutate(id, { kind: "reclaim" }, me, now);
+	if (!result.ok) return refusal("reclaim", result.error, result.card ?? before);
+	return textResult(formatReclaimed(result.card, previous), { action: "reclaim", card: result.card });
+}
+
+/** The collapsed line for a successful call, from its details. */
+function summaryOf(details: TeamDetails): string {
+	const card = details.card;
+	if (!card) return details.action === "reclaim" ? "reclaimed" : "handed off";
+	if (details.action === "offer") {
+		const count = details.delivered?.length ?? 0;
+		return `${cardRef(card.id)} offered to ${plural(count, "session")}`;
+	}
+	const who = details.assigned?.label ?? card.owner?.label;
+	const target = details.action === "assign" && who !== undefined ? ` → ${who}` : "";
+	return `${cardRef(card.id)} ${card.status}${target}`;
+}