@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/board/schema.ts

@@ -8,7 +8,10 @@
  */
 
 import { Type } from "typebox";
-import { CARD_STATUSES, PRIORITIES } from "../../lib/board/card.ts";
+import { MAX_NOTE, PRIORITIES } from "../../lib/board/card.ts";
+import { listOf } from "../../lib/format.ts";
+import { BLOCKERS } from "../../lib/board/card.ts";
+import { LANES, movableLanes } from "../../lib/board/lanes.ts";
 import { BOARD_ACTIONS } from "./types.ts";
 
 export const BoardParams = Type.Object({
@@ -24,15 +27,18 @@ export const BoardParams = Type.Object({
 	card: Type.Optional(
 		Type.String({
 			description:
-				'The card id for one card, e.g. "4" or "#4". `list` reads that card; every other action but `add` acts on it.',
+				'The card id for one card, e.g. "4" or "#4". `list` reads that card, and refuses `lane`, `query`, `mine`, and `round` with it; every other action but `add` acts on it.',
 		}),
 	),
-	status: Type.Optional(
+	lane: Type.Optional(
 		Type.Union(
-			CARD_STATUSES.map((status) => Type.Literal(status)),
+			LANES.map((lane) => Type.Literal(lane)),
 			{
+				// The lanes a move may name come from the transition table, so a route added
+				// there is offered here without a second list to forget.
 				description:
-					"`list`: show only this lane, and not skip the `done` cards. `move`: the lane to move to (not `todo` — use `release`).",
+					"`list`: show only this lane, and not skip the `done` cards. " +
+					`\`move\`: the lane to move to — ${listOf(movableLanes())}; \`backlog\` is \`release\`'s, not a move's, and a card may move only where a transition exists from its own lane.`,
 			},
 		),
 	),
@@ -42,6 +48,15 @@ export const BoardParams = Type.Object({
 				"`move` to `blocked`: what the card waits on — the decision a person has to make, one line, at most 200 characters.",
 		}),
 	),
+	blocker: Type.Optional(
+		Type.Union(
+			BLOCKERS.map((blocker) => Type.Literal(blocker)),
+			{
+				description:
+					"`move` to `blocked`, required: why it is blocked — the errand, not the route. A blocked card resumes in `plan`, or in `execute` once its contract is approved.",
+			},
+		),
+	),
 	title: Type.Optional(Type.String({ description: "`add` and `edit`: the feature's outcome, one line." })),
 	paths: Type.Optional(
 		Type.Array(Type.String(), {
@@ -49,9 +64,31 @@ export const BoardParams = Type.Object({
 				"`add` and `edit`: repository-relative hints (directories or files) where the work happens. Not claims.",
 		}),
 	),
-	note: Type.Optional(Type.String({ description: "`add`: a first note, e.g. why the card exists." })),
-	text: Type.Optional(Type.String({ description: "`note`: the note to append." })),
-	path: Type.Optional(Type.String({ description: "`plan`: the plan file this card is executing." })),
+	note: Type.Optional(
+		Type.String({
+			description: `\`add\`: a first note, e.g. why the card exists; one line, at most ${MAX_NOTE} characters.`,
+		}),
+	),
+	text: Type.Optional(
+		Type.String({
+			description: `\`note\`: the note to append; \`approve\` and \`review\`: what the signer saw, recorded with the sign; one line, at most ${MAX_NOTE} characters.`,
+		}),
+	),
+	path: Type.Optional(
+		Type.String({
+			description:
+				"`contract`, required: the plan file this card is executed against — the path `plan` action `write` returned, inside this repository's plan store.",
+		}),
+	),
+	goal: Type.Optional(
+		Type.String({ description: "`contract`: what the feature is for, one line, at most 400 characters." }),
+	),
+	acceptance: Type.Optional(
+		Type.String({ description: "`contract`: how a reader can tell it is done, one line, at most 400 characters." }),
+	),
+	scopeOut: Type.Optional(
+		Type.String({ description: "`contract`: what this deliberately does not do, one line, at most 400 characters." }),
+	),
 	priority: Type.Optional(
 		Type.Union(
 			PRIORITIES.map((priority) => Type.Literal(priority)),
@@ -64,7 +101,7 @@ export const BoardParams = Type.Object({
 	dependsOn: Type.Optional(
 		Type.Array(Type.String(), {
 			description:
-				"`edit`: the cards this one waits for, as ids. It cannot be claimed or moved to doing or done while one of them is unfinished; `[]` removes every link.",
+				"`edit`: the cards this one waits for, as ids. It cannot be claimed, or moved to execute or done, while one of them is unfinished; `[]` removes every link.",
 		}),
 	),
 	mine: Type.Optional(
@@ -78,13 +115,14 @@ export const BoardParams = Type.Object({
 	),
 	round: Type.Optional(
 		Type.Boolean({
-			description: "`list`: also return the lead's rollup — owners, unassigned, unplanned, blocked, idle.",
+			description:
+				"`list`: also return the lead's rollup — owners, unassigned, unplanned, awaiting approval, blocked, idle, and done.",
 		}),
 	),
 	archived: Type.Optional(
 		Type.Boolean({
 			description:
-				"`list`: read the archive instead of the board — the finished cards `archive` set aside, which no other read opens. `query` and `mine` narrow it; `status` and `round` do not apply to a pile that is out of the board.",
+				"`list`: read the archive instead of the board — the finished cards `archive` set aside, which no other read opens. `query` and `mine` narrow it; `lane` and `round` do not apply to a pile that is out of the board.",
 		}),
 	),
 });

package/extensions/board/snapshot.ts

@@ -18,8 +18,6 @@ export interface SnapshotContext {
 	store: BoardStore;
 	/** The actor every request is made and reported as: the page's seat. */
 	actor: () => Actor;
-	/** The session serving the page, which is who is reading, not who it writes as. */
-	session?: () => Actor;
 	now: () => number;
 	/** Where this repository's bus files its records. */
 	busDir: () => Promise<string>;
@@ -28,15 +26,19 @@ export interface SnapshotContext {
 /** The snapshot the page renders, and the body of `/api/board`. */
 export async function viewOf(context: SnapshotContext): Promise<BoardView> {
 	const roster = await readRoster(await context.busDir());
-	const session = context.session?.();
+	// One read of the pile answers both: a frame that asked `list` and `skipped` separately
+	// would parse every card twice, once a second, for as long as a tab is open.
+	const { cards, skipped } = await context.store.scan();
 	return buildView({
 		me: context.actor(),
-		...(session === undefined ? {} : { session }),
-		cards: await context.store.list(),
+		cards,
 		now: context.now(),
 		bytes: await context.store.bytes(),
-		skipped: (await context.store.skipped()).length,
+		skipped,
+		repo: context.store.name(),
+		root: context.store.root(),
 		where: context.store.where(),
+		limits: context.store.config().wip,
 		...(roster === undefined ? {} : { roster }),
 	});
 }

package/extensions/board/tone.ts

@@ -0,0 +1,22 @@
+/**
+ * The terminal's word for a board tone.
+ *
+ * The tone table (`lib/board/tone.ts`) says what a lane, a reason, and a decision row mean;
+ * the page wears those words as CSS properties directly. The terminal has its own vocabulary —
+ * `lib/tui/tokens.ts`'s roles are `ok`, `warn`, `bad`, `meta`, `faint`, and deliberately not
+ * `success`, `danger`, or `muted` — so this is the one place the two are bridged, in the
+ * extension, because only the transcript speaks the terminal's words.
+ */
+
+import type { BoardTone } from "../../lib/board/tone.ts";
+import type { TuiRole } from "../../lib/tui/tokens.ts";
+
+/** The role each board tone is painted as, closest first. */
+export const TONE_ROLE: Record<BoardTone, TuiRole> = {
+	muted: "meta",
+	dim: "faint",
+	warn: "warn",
+	accent: "accent",
+	danger: "bad",
+	success: "ok",
+};

package/extensions/board/tools.ts

@@ -14,30 +14,35 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Static } from "typebox";
-import { cardRef, matchesQuery, normalizeCardId } from "../../lib/board/card.ts";
+import { type ArtifactCheck, planForContract, planForExecute } from "../../lib/board/artifact.ts";
+import { type Card, cardRef, holds, matchesQuery, normalizeCardId } from "../../lib/board/card.ts";
+import { movableLanes } from "../../lib/board/lanes.ts";
 import { indexOf } from "../../lib/board/links.ts";
-import { type CardOp, holds } from "../../lib/board/rules.ts";
+import type { CardOp } from "../../lib/board/rules.ts";
 import { buildRound } from "../../lib/board/round.ts";
+import { readRoster, type RosterSession } from "../../lib/session-roster.ts";
 import type { BoardStore } from "../../lib/board/store.ts";
 import { messageOf } from "../../lib/errors.ts";
+import { listOf } from "../../lib/format.ts";
 import { revParse } from "../../lib/git/read.ts";
 import { strayField } from "../../lib/stray-fields.ts";
 import { createExecRunner } from "../../lib/git/runner.ts";
 import { failedResult, textResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
+import { callLine, detailsOrLine, isTailResult, TailResult } from "../../lib/tui/tool.ts";
 import { formatRound } from "../../lib/board/round-text.ts";
+import { skippedText } from "../../lib/board/skipped.ts";
 import {
 	archiveNote,
+	CLAIM_NEXT,
 	formatArchive,
 	formatArchived,
 	formatBoard,
 	formatCard,
 	formatDropped,
-	formatSkipped,
 } from "./format.ts";
 import { createTeamJoin, type TeamJoin } from "../../lib/session-tool.ts";
-import { BoardResult, collapsedLine, resultInput } from "./result.ts";
+import { collapsedLine, resultInput } from "./result.ts";
 import { createInput } from "./input.ts";
 import type { BoardSession } from "../../lib/board/session.ts";
 import { BoardParams } from "./schema.ts";
@@ -45,7 +50,6 @@ import {
 	ACTION_FIELDS,
 	BOARD_ACTION_DOCS,
 	BOARD_ACTIONS,
-	BOARD_MUTATING_ACTIONS,
 	BOARD_TOOL,
 	type BoardAction,
 	type BoardDetails,
@@ -76,14 +80,14 @@ function callSubject(action: BoardAction, args: Record<string, unknown>): string
 	if (action === "list") {
 		const parts = ["list"];
 		if (args.round === true) parts.push("round");
-		if (typeof args.status === "string") parts.push(args.status);
+		if (typeof args.lane === "string") parts.push(args.lane);
 		if (typeof args.query === "string" && args.query.trim() !== "") parts.push(`"${args.query.trim()}"`);
 		if (card !== "") parts.push(card);
 		return parts.join(" ");
 	}
 	if (card === "") return action;
-	const status = typeof args.status === "string" ? ` ${args.status}` : "";
-	return `${action} ${card}${status}`;
+	const lane = typeof args.lane === "string" ? ` ${args.lane}` : "";
+	return `${action} ${card}${lane}`;
 }
 
 /** One refusal: the reason for the model, the state for the renderer. */
@@ -96,6 +100,17 @@ function refusal(action: BoardAction, me: BoardDetails["me"], message: string, c
 	});
 }
 
+/**
+ * Whether a result this tool built is a refusal.
+ *
+ * `refusal` marks one with `isError`, and the success shape (`ToolResult`) has no such
+ * field, so this is the one probe that tells the two apart — read here rather than
+ * widening the shared envelope with a flag that would then be optional everywhere.
+ */
+function refused(result: unknown): boolean {
+	return typeof result === "object" && result !== null && (result as { isError?: unknown }).isError === true;
+}
+
 /**
  * The commit at `cwd`'s `HEAD`, shortened, or nothing when there is none.
  *
@@ -116,14 +131,16 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 		label: "Board",
 		description:
 			"The shared feature list for this repository: one card per feature, which any session reads and writes. " +
-			"A card carries the feature's outcome, the session that holds it, path hints, the plan it is executing, " +
-			`its priority, what it waits for, and its notes. ${verbHelp()} A card's steps do not belong on the ` +
-			"board - they belong in the plan and in `todo`.",
+			"A card moves through five lanes - backlog, plan, execute, blocked, done - and carries the feature's " +
+			"outcome, the session that holds it, the contract it promises (goal, acceptance, scopeOut), the plan it " +
+			`is executed against, its priority, what it waits for, and its notes. ${verbHelp()} A card's steps do not ` +
+			"belong on the board - they belong in the plan and in `todo`.",
 		promptSnippet: `The shared feature list for this repository: ${BOARD_ACTIONS.join(", ")}.`,
 		promptGuidelines: [
-			"Claim a card before working on it; release or finish it when you stop, and reclaim a card whose owner is gone.",
-			"Record the plan file with `board` action `plan` once the plan is approved, then execute it.",
-			"Note each phase of the work, and move the card to `done` or `blocked` when it changes state.",
+			"Claim a card to pull it from backlog into plan, design it in plan mode, then record the contract with `contract`: goal, acceptance, scopeOut, and the plan file `plan` action `write` returned — a path outside this repository's plan store is refused. Move it to execute only once the lead (`board.lead` in `bytefly.json`, `lead` by default, the name the page serves as) has approved that contract, or the person has signed with `/board approve` — a lead releases a card before signing it.",
+			"Before a card is done, the lead records a spot-check with `review`, or the person signs with `/board review`; the plan it recorded must still be in the store, and `contract` is how it is re-recorded.",
+			"Move a card to `blocked` with a `blocker` kind and one line about what is waited on: it resumes in `plan`, or in `execute` once its contract is approved.",
+			"Note each phase of the work, and release or reclaim a card you stop holding, so the lane count means what it says.",
 			"A card that waits on another is linked with `edit` and `dependsOn`, so the order is on the board instead of in a refusal.",
 			"A feature's steps belong in `todo`, not on the board: one card is one feature, whatever it takes.",
 			"A `handoff` in your inbox is work you now own: read it with `session inbox`, record the plan, and start it.",
@@ -143,57 +160,84 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 					`unknown action "${String(args.action)}"; use ${BOARD_ACTIONS.join(", ")}.`,
 				);
 			}
-			const me = runtime.who(ctx, ctx.cwd);
+			const me = await runtime.who(ctx, ctx.cwd);
 			try {
-				// Before the join and the store: a refused call has done nothing, so it cannot
-				// have enlisted this session as a teammate on its way to the refusal.
+				// Before the join and before a card is read: a refused call has written nothing, so it
+				// cannot have enlisted this session as a teammate on its way to the refusal.
 				const stray = strayField(action, args, ACTION_FIELDS);
 				if (stray !== undefined) return refusal(action, me, stray);
-				// Working a card makes this session a teammate, once: the board is the user's
-				// surface for the team, so nobody has to know the bus exists. A failed join is
-				// not a failed card write — the board works with no bus at all — and it is not
-				// marked, so the next write asks again.
-				if (BOARD_MUTATING_ACTIONS.has(action) && !runtime.joined()) {
-					if ((await team.join(ctx)).ok) runtime.markJoined();
-				}
 				const store = await runtime.store(ctx.cwd);
 				const now = runtime.now();
 				switch (action) {
 					case "list":
-						return await read(store, action, me, args, now);
+						// The round folds the owners a bus has no record of, and the rollup is the only read
+						// that needs the bus for its own sake: a plain `list` reads no bus file beyond the
+						// record that names whoever is calling.
+						return await read(store, action, me, args, now, async () => readRoster(await runtime.busDir(ctx.cwd)));
 					case "add":
 						return await add(store, me, args, now);
-					case "claim":
-						return await mutate(store, action, me, now, args, { kind: "claim" });
+					case "claim": {
+						const claimed = await mutate(store, action, me, now, args, { kind: "claim" }, CLAIM_NEXT);
+						// Taking a card is what makes this session a teammate. It is the one action here
+						// worth being addressed about, and the board is the user's surface for the team, so
+						// nobody has to know the bus exists. A refused claim wrote nothing and enlists
+						// nobody; a refused join is not a failed claim, so the card stands and the next
+						// claim asks again.
+						if (!refused(claimed)) {
+							// Loaded here, not at registration: the join is the claim's side effect, so a
+							// session that never claims pays nothing for it.
+							const { joinOnce } = await import("../../lib/board/join.ts");
+							await joinOnce(runtime.team, team, ctx, me.label);
+						}
+						return claimed;
+					}
 					case "release":
 						return await mutate(store, action, me, now, args, { kind: "release" });
 					case "reclaim":
 						return await mutate(store, action, me, now, args, { kind: "reclaim" });
 					case "move": {
 						if (args.card === undefined) return refusal(action, me, 'card is required: pass the id, e.g. "4".');
-						const status = args.status;
-						if (status === undefined || status === "todo") {
-							return refusal(
-								action,
-								me,
-								'move needs a target lane: "doing", "blocked", or "done". Use release to return a card to todo.',
-							);
+						const lane = args.lane;
+						if (lane === undefined) {
+							return refusal(action, me, `move needs a target lane: ${listOf(movableLanes())}.`);
 						}
-						// Only the lane that has something to say reads for it: a move to `done`
-						// records the commit that closed the card, and a board outside a
-						// repository simply has none to record.
-						const landed = status === "done" ? await headCommit(pi, ctx.cwd) : undefined;
+						// Only the lanes that have something to say read for it: a move to `done`
+						// records the commit that closed the card, and both `execute` and `done` carry
+						// the proof that the plan the card recorded is still there. A board outside a
+						// repository simply has no commit to record.
+						const landed = lane === "done" ? await headCommit(pi, ctx.cwd) : undefined;
+						const proved =
+							lane === "execute" || lane === "done"
+								? await recordedPlan(runtime, ctx.cwd, store, args.card)
+								: undefined;
 						return await mutate(store, action, me, now, args, {
 							kind: "move",
-							status,
+							lane,
 							...(args.blockedBy === undefined ? {} : { blockedBy: args.blockedBy }),
+							...(args.blocker === undefined ? {} : { blocker: args.blocker }),
 							...(landed === undefined ? {} : { landed }),
+							...(proved === undefined ? {} : { artifact: proved }),
 						});
 					}
 					case "note":
 						return await mutate(store, action, me, now, args, { kind: "note", text: args.text });
-					case "plan":
-						return await mutate(store, action, me, now, args, { kind: "plan", path: args.path });
+					case "contract": {
+						// The plan is proved here, at the boundary: the state machine decides, but only
+						// a caller holding the working directory can answer whether the file is there.
+						const plan =
+							args.path === undefined ? undefined : planForContract(await runtime.planDir(ctx.cwd), args.path);
+						return await mutate(store, action, me, now, args, {
+							kind: "contract",
+							...(plan === undefined ? {} : { artifact: plan }),
+							goal: args.goal,
+							acceptance: args.acceptance,
+							scopeOut: args.scopeOut,
+						});
+					}
+					case "approve":
+						return await mutate(store, action, me, now, args, { kind: "approve", text: args.text });
+					case "review":
+						return await mutate(store, action, me, now, args, { kind: "review", text: args.text });
 					case "edit": {
 						if (
 							args.title === undefined &&
@@ -239,14 +283,50 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 				text.setText(collapsedLine(theme, outcome.details));
 				return text;
 			}
-			const view =
-				context?.lastComponent instanceof BoardResult ? context.lastComponent : new BoardResult(input, theme);
+			const previous = context?.lastComponent;
+			const view = isTailResult<Card>(previous) ? previous : new TailResult<Card>(input, theme);
 			view.setInput(input, theme);
 			return view;
 		},
 	});
 }
 
+/**
+ * The plan file a card entering `execute` recorded, proved to be there.
+ *
+ * A `move` names the card, not its plan, so the tool reads the card — one read, on the one
+ * lane whose gate needs it — and hands `steps.ts` the fact. A card with no plan recorded
+ * gets no fact and the state machine refuses it; a recorded plan that is gone, or outside
+ * this repository's store, is refused here with the sentence that names the card and the
+ * way out.
+ */
+async function recordedPlan(
+	runtime: BoardSession,
+	cwd: string,
+	store: BoardStore,
+	rawCard: string | undefined,
+): Promise<ArtifactCheck | undefined> {
+	const id = rawCard === undefined ? undefined : normalizeCardId(rawCard);
+	const card = id === undefined ? undefined : await store.read(id);
+	if (card?.planPath === undefined) return undefined;
+	return planForExecute(await runtime.planDir(cwd), card);
+}
+
+/** The `list` fields that narrow a listing, in the order a refusal names them. */
+const CARD_FILTERS = ["lane", "query", "mine", "round"] as const;
+
+/**
+ * The refusal for the filters a `list` that names a card would otherwise drop.
+ *
+ * `card` answers for that one card, so a filter beside it changes nothing — and a call that
+ * sent both meant one of them. A dropped field is what `strayField` exists to prevent one
+ * level up, so it is refused here in the same voice the archive's own reader uses.
+ */
+function cardFiltersRefusal(args: BoardArgs, fields: readonly (keyof BoardArgs)[] = CARD_FILTERS): string | undefined {
+	const given = fields.filter((field) => args[field] !== undefined);
+	return given.length === 0 ? undefined : `card does not read ${given.join(", ")}: it answers for that one card.`;
+}
+
 /** `list`: the board, one card, the lead's rollup, or the archive. */
 async function read(
 	store: BoardStore,
@@ -254,6 +334,7 @@ async function read(
 	me: BoardDetails["me"],
 	args: BoardArgs,
 	now: number,
+	roster: () => Promise<readonly RosterSession[] | undefined>,
 ): Promise<ReturnType<typeof textResult<BoardDetails>>> {
 	if (args.archived === true) return readArchive(store, action, me, args, now);
 	const cards = await store.list();
@@ -263,6 +344,8 @@ async function read(
 	// A directory listing, not a read: a listing says what it left aside without opening one.
 	const archived = await store.archivedCount();
 	if (args.card !== undefined) {
+		const ignored = cardFiltersRefusal(args);
+		if (ignored !== undefined) return refusal(action, me, ignored);
 		const id = normalizeCardId(args.card);
 		if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
 		const card = cards.find((entry) => entry.id === id);
@@ -284,7 +367,7 @@ async function read(
 	}
 	const listed = cards.filter(
 		(card) =>
-			(args.status === undefined || card.status === args.status) &&
+			(args.lane === undefined || card.lane === args.lane) &&
 			(args.query === undefined || matchesQuery(card, args.query)) &&
 			// The same rule a claim is checked against, so "mine" cannot list a card this
 			// session could not release.
@@ -294,18 +377,23 @@ async function read(
 	// repository's own board is mostly finished cards — so a listing that names no lane
 	// leaves them out and says how many. A named lane, `card`, and `round` are unchanged;
 	// the rollup counts the whole board, which is what makes it a rollup.
-	const hiddenDone = args.status === undefined ? listed.filter((card) => card.status === "done").length : 0;
-	const shown = hiddenDone === 0 ? listed : listed.filter((card) => card.status !== "done");
+	const hiddenDone = args.lane === undefined ? listed.filter((card) => card.lane === "done").length : 0;
+	const shown = hiddenDone === 0 ? listed : listed.filter((card) => card.lane !== "done");
 	if (args.round !== true) {
-		return textResult(formatBoard(shown, { hiddenDone, archived, skipped }), { action, me, cards: shown });
+		return textResult(formatBoard(shown, { hiddenDone, archived, skipped }), {
+			action,
+			me,
+			cards: shown,
+			...(args.mine === true ? { mine: true } : {}),
+		});
 	}
 	const round = buildRound(cards, now);
 	// One line under the rollup, because a reader who cannot see a card file should know why,
 	// and one for the archive, because a rollup that silently left it out would be a board
 	// smaller than the one on disk.
-	const notes = [formatSkipped(skipped), archiveNote(archived)].filter((line) => line !== "");
-	const text = [formatRound(cards, round), ...notes].join("\n");
-	return textResult(text, { action, me, cards: listed, round });
+	const notes = [skippedText(skipped), archiveNote(archived)].filter((line) => line !== "");
+	const text = [formatRound(cards, round, await roster()), ...notes].join("\n");
+	return textResult(text, { action, me, cards: listed, round, ...(args.mine === true ? { mine: true } : {}) });
 }
 
 /**
@@ -322,7 +410,7 @@ async function readArchive(
 	args: BoardArgs,
 	now: number,
 ): Promise<ReturnType<typeof textResult<BoardDetails>>> {
-	const wrong = (["status", "round"] as const).filter((field) => args[field] !== undefined);
+	const wrong = (["lane", "round"] as const).filter((field) => args[field] !== undefined);
 	if (wrong.length > 0) {
 		return refusal(
 			action,
@@ -332,6 +420,9 @@ async function readArchive(
 	}
 	const pile = await store.archived();
 	if (args.card !== undefined) {
+		// `query` and `mine` narrow the pile, not the one card it would answer for.
+		const ignored = cardFiltersRefusal(args, ["query", "mine"]);
+		if (ignored !== undefined) return refusal(action, me, ignored);
 		const id = normalizeCardId(args.card);
 		if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
 		const card = pile.cards.find((entry) => entry.id === id);
@@ -348,7 +439,12 @@ async function readArchive(
 	const shown = pile.cards.filter(
 		(card) => (args.query === undefined || matchesQuery(card, args.query)) && (args.mine !== true || holds(card, me)),
 	);
-	return textResult(formatArchive(shown, pile.skipped), { action, me, cards: shown });
+	return textResult(formatArchive(shown, pile.skipped), {
+		action,
+		me,
+		cards: shown,
+		...(args.mine === true ? { mine: true } : {}),
+	});
 }
 
 /** `add`: the only action that creates a card. */
@@ -372,13 +468,16 @@ async function mutate(
 	now: number,
 	args: BoardArgs,
 	op: CardOp,
+	/** One line a card's own text does not carry, for the action that has a next step. */
+	next?: string,
 ): Promise<ReturnType<typeof textResult<BoardDetails>>> {
 	if (args.card === undefined) return refusal(action, me, 'card is required: pass the id, e.g. "4".');
 	const id = normalizeCardId(args.card);
 	if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
 	const result = await store.mutate(id, op, me, now);
 	if (!result.ok) return refusal(action, me, result.error, result.card);
-	return textResult(formatCard(result.card), { action, me, card: result.card });
+	const lines = [formatCard(result.card), ...(next === undefined ? [] : [next])];
+	return textResult(lines.join("\n"), { action, me, card: result.card });
 }
 
 /**
@@ -403,7 +502,7 @@ async function archiveCards(
 		if (!result.changed) return textResult(`${cardRef(id)} is already archived.`, { action: "archive", me });
 		return textResult(formatArchived([id]), { action: "archive", me, card: result.card, archived: [id] });
 	}
-	const finished = (await store.list()).filter((card) => card.status === "done");
+	const finished = (await store.list()).filter((card) => card.lane === "done");
 	const moved: string[] = [];
 	const failed: Array<{ card: string; error: string }> = [];
 	for (const card of finished) {

package/extensions/board/transport/router.ts

@@ -23,6 +23,7 @@ import {
 	type ServeResponse,
 } from "../../../lib/http/index.ts";
 import type { BoardView } from "../../../lib/board/view.ts";
+import { PING_PATH, SNAPSHOT_PATH } from "../../../lib/board/page-pointer.ts";
 import { THEME_JS, THEME_JS_PATH } from "../../../lib/web/index.ts";
 import type { PageView } from "../view/page.ts";
 
@@ -45,13 +46,10 @@ export interface BoardRouterContext {
 	page: (view: PageView) => Promise<string>;
 	/** The client script. */
 	script: string;
-	/** The snapshot the page renders, and the body of `/api/board`. */
+	/** The snapshot the page renders, and the body of the snapshot route. */
 	view: () => Promise<BoardView>;
 }
 
-/** The cheap liveness route: a probe reads this, and never the snapshot. */
-export const PING_PATH = "/api/ping";
-
 /**
  * Handle one request. `method`, `rawUrl`, and `headers` are the raw HTTP values.
  */
@@ -77,7 +75,7 @@ export async function handleBoardRequest(
 	// must not pay for the snapshot, which is a store read and a roster read on the same
 	// event loop the probe is racing.
 	if (pathname === PING_PATH) return jsonResponse(200, { ok: true });
-	if (pathname === "/api/board") return jsonResponse(200, await ctx.view());
+	if (pathname === SNAPSHOT_PATH) return jsonResponse(200, await ctx.view());
 	if (pathname === "/" || pathname === "/index.html") {
 		return { status: 200, headers: pageHeaders(), body: await ctx.page(viewOf(search.get("view"))) };
 	}