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

package/extensions/board/page.ts

@@ -1,12 +1,13 @@
 /**
- * The page's lifecycle: one server per session, started by `/board` and closed by
+ * The page's lifecycle: one mount per session, started by `/board` and given back by
  * `/board stop`, by the idle grace once the last tab has been gone for a minute, or by
  * `session_shutdown`.
  *
- * Only the lifecycle lives here — the state machine, the port it remembers, the chip
- * that names it, and the three closes. What the page *reads* is `snapshot.ts`, what it
- * *writes* is `writes.ts`, and how a request reaches either is `transport/`; the router
- * knows nothing of the page's markup, and this is still the one place they meet.
+ * Only the lifecycle lives here — the state machine, the prefix it holds, the note that
+ * names it, and the three closes. The session's port belongs to `serve`, so nothing here
+ * picks one. What the page *reads* is `snapshot.ts`, and it writes nothing: how a request
+ * reaches the snapshot is `transport/`, the router knows nothing of the page's markup, and
+ * this is still the one place they meet.
  *
  * All state lives in this closure, not at module scope: Pi loads each extension with an
  * isolated module cache, so a module variable would be one copy per extension.
@@ -15,11 +16,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { BoardStore } from "../../lib/board/store.ts";
 import { openInBrowser } from "../../lib/browser.ts";
-import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
-import { paint } from "../../lib/tui/tokens.ts";
 import type { RepeatTimer } from "../../lib/timer.ts";
 import type { BoardSession } from "../../lib/board/session.ts";
 import {
+	BOARD_BASE,
 	clearPointer,
 	PAGE_FILE,
 	type PagePointer,
@@ -27,27 +27,18 @@ import {
 	probePage,
 	readPointer,
 	settlePointer,
-	viewUrlOf,
+	urlOf,
 } from "../../lib/board/page-pointer.ts";
-import { mintToken } from "../../lib/http/index.ts";
+import { mintToken, type MountSource } from "../../lib/http/index.ts";
+import { messageOf } from "../../lib/errors.ts";
+import type { IdleReason } from "../../lib/http/sink.ts";
 import { join } from "node:path";
-import { type BoardConfig, loadBoardConfig } from "./config.ts";
 import { pageActor } from "./seat.ts";
 import { viewOf } from "./snapshot.ts";
-import { writeOf } from "./writes.ts";
 import { type BoardServer, createBoardServer } from "./transport/server.ts";
 import { BOARD_CLIENT_JS } from "./view/client.ts";
 import { type PageView, renderBoardPage } from "./view/page.ts";
 
-/**
- * A free port in the range the other loopback pages use, so a session's pages cluster.
- * Only the unpinned page draws one: `board.port` in `bytefly.json` states the port a
- * bookmarked URL keeps.
- */
-export function randomPort(): number {
-	return 4780 + Math.floor(Math.random() * 1000);
-}
-
 /**
  * How long the page waits for a tab after the last one leaves.
  *
@@ -57,15 +48,32 @@ export function randomPort(): number {
  */
 export const IDLE_STOP_MS = 60_000;
 
+/**
+ * How long a page may stand with no tab ever attached.
+ *
+ * `/board` opens a browser, and a browser that does not open (a swallowed failure, a
+ * terminal on a machine with no default browser) would otherwise leave the port bound for
+ * the rest of the session. Two minutes is long enough for a person to finish reading the
+ * transcript and click the link `/board` printed.
+ */
+export const IDLE_FIRST_MS = 120_000;
+
 /** What `/board status` prints. */
 export interface BoardPageStatus {
 	running: boolean;
 	/** True when this session opened somebody else's page instead of serving one. */
 	attached?: boolean;
+	/**
+	 * True when that page no longer answers: the note is there, the process behind it is
+	 * not, and `/board stop` may drop it.
+	 */
+	stale?: boolean;
 	/** The name the page serves as: a seat, not the session that opened it. */
 	seat?: string;
 	port?: number;
 	url?: string;
+	/** The repository's name, so `status` says which board the page is. */
+	repo?: string;
 	where?: string;
 	/** How many tabs are attached, while this session serves the page. */
 	watchers?: number;
@@ -79,68 +87,104 @@ export interface BoardPageStatus {
  * page* is a third answer a `running: false` could not express.
  */
 export type PageStart =
-	| { kind: "served"; seat: string; port: number; url: string; where: string }
-	| { kind: "attached"; seat: string; port: number; url: string; where: string }
+	| { kind: "served"; seat: string; port: number; url: string; repo: string; where: string }
+	| { kind: "attached"; seat: string; port: number; url: string; repo: string; where: string }
 	| { kind: "failed"; reason: string };
 
 /** Test seams and the one place a caller may redirect the browser. */
 export interface BoardPageDeps {
 	open?: (url: string) => void;
-	pickPort?: () => number;
+	/** Where the prefix comes from: the session's server, or a suite's own. */
+	mount: MountSource;
+	/** The Pi session this page serves as, so the prefix lands on its socket. */
+	session: () => string;
 	interval?: RepeatTimer;
 	/** Grace after the last tab leaves; defaults to {@link IDLE_STOP_MS}. */
 	idleMs?: number;
+	/** Grace for a page no tab ever attached to; defaults to {@link IDLE_FIRST_MS}. */
+	firstIdleMs?: number;
 	/** Whether a page another session left a note about is answering; a test drives it. */
 	probe?: ProbeFetch;
-	/** How the `board` section answers; a test drives it without a config file. */
-	config?: (cwd: string) => BoardConfig;
 }
 
 /** The page as `/board` and `session_shutdown` drive it. */
 export interface BoardPage {
 	start: (ctx: ExtensionContext, view?: PageView) => Promise<PageStart>;
-	stop: (ctx: ExtensionContext) => Promise<boolean>;
-	status: () => BoardPageStatus;
+	/** Give the prefix back; the session's server closes with its last mount. */
+	stop: () => Promise<boolean>;
+	/** What `/board status` prints: served here, watched, watched and dead, or absent. */
+	status: () => Promise<BoardPageStatus>;
+	/** Drop the note of a page that has stopped answering. False when it still answers. */
+	dropStale: (ctx: ExtensionContext) => Promise<boolean>;
 	closeAll: () => Promise<void>;
 }
 
-export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps = {}): BoardPage {
-	let running: { server: BoardServer; store: BoardStore; viewToken: string } | undefined;
+export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): BoardPage {
+	let running: { server: BoardServer; store: BoardStore; token: string } | undefined;
 	/** The page another session serves, when this session opened that one instead. */
 	let attachedTo: PagePointer | undefined;
-	let sessionPort: number | undefined;
 	// The page is a seat, not a session: one name and one id for its whole life, so a card
 	// a browser claimed is still the seat's after the session that served it ends.
 	const seat = pageActor();
 
 	const storeOf = async (ctx: ExtensionContext): Promise<BoardStore> => runtime.store(ctx.cwd);
 
-	const stop = async (ctx: ExtensionContext): Promise<boolean> => {
-		if (!running) return false;
-		const { server, store, viewToken } = running;
+	/**
+	 * Close the page this session serves, and take its note with it.
+	 *
+	 * One close for both callers: `/board stop` has a context and clears the status line, and
+	 * a clean `session_shutdown` has none. The note must leave either way — a note nobody
+	 * answers makes every open tab reconnect forever and costs the next `/board` a probe
+	 * and a takeover before it serves.
+	 */
+	const closeRunning = async (): Promise<boolean> => {
+		if (running === undefined) return false;
+		const { server, store, token } = running;
 		running = undefined;
 		await server.close();
-		// The note is the page's, so it leaves with it: a viewer that reads a note nobody
-		// answers wastes a probe, and the next `/board` would attach to a dead port.
-		await clearPointer(store.dir, viewToken);
-		clearChip(ctx);
+		await clearPointer(store.dir, token);
+		// A page that closed is no seat: the session's next card is written as itself. This is
+		// the one place all three closes pass — `/board stop`, the idle grace, and shutdown — so
+		// a page nobody is looking at cannot leave the session serving in name only.
+		runtime.serve(undefined);
 		return true;
 	};
 
+	const stop = (): Promise<boolean> => closeRunning();
+
 	const start = async (ctx: ExtensionContext, view: PageView = "board"): Promise<PageStart> => {
-		if (running) return describe(running);
-		const store = await storeOf(ctx);
-		await store.ensure();
+		// `/board` is how the page is summoned, and a page whose tab was closed is one
+		// command away from being shown again — the same answer a viewer's `/board` gives.
+		if (running !== undefined) {
+			(deps.open ?? openInBrowser)(view === "board" ? running.server.url : `${running.server.url}&view=team`);
+			return describe(running);
+		}
+		/** One refusal for every way a start can fail, named by what failed. */
+		const failed = (error: unknown): PageStart => {
+			const reason = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`board: the page did not start (${reason})`, "error");
+			return { kind: "failed", reason };
+		};
+		// The board's own directory, then the page: both can fail on a path that exists and
+		// cannot be written, and a start that fails must leave no listener behind.
+		let store: BoardStore;
+		try {
+			store = await storeOf(ctx);
+			await store.ensure();
+		} catch (error) {
+			return failed(error);
+		}
 		const open = (url: string) => (deps.open ?? openInBrowser)(view === "board" ? url : `${url}&view=team`);
 		/** Watch the page another session serves: its note is the URL, its seat the name. */
 		const attach = (pointer: PagePointer): PageStart => {
 			attachedTo = pointer;
-			open(viewUrlOf(pointer));
+			open(urlOf(pointer));
 			return {
 				kind: "attached",
 				seat: pointer.seat.label,
 				port: pointer.port,
-				url: viewUrlOf(pointer),
+				url: urlOf(pointer),
+				repo: store.name(),
 				where: store.where(),
 			};
 		};
@@ -151,86 +195,97 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps = {})
 		attachedTo = undefined;
 		const actor = () => seat;
 		const now = () => runtime.now();
-		// Read on every start, so an edit to the section applies to the next `/board`.
-		const config = (deps.config ?? loadBoardConfig)(ctx.cwd);
-		const pinned = config.port > 0 ? config.port : undefined;
-		const preferred = pinned ?? sessionPort ?? (deps.pickPort ?? randomPort)();
-		// The viewer's credential is minted here rather than by the server, because the note
-		// this session leaves has to carry it: that is what a teammate reads to attach.
-		const viewToken = mintToken();
-		let server: BoardServer;
+		// Minted here rather than by the server: the note this session leaves has to carry it,
+		// and that is what a second session reads to attach instead of serving its own page.
+		const token = mintToken();
+		/** Whether this page has already said it cannot read the board. */
+		let blind = false;
+		// A frame the page cannot build is a dropped frame, not a crash: the ticker asks again
+		// in a second. Said once, because a failure that persists would otherwise become one
+		// notice per tick — and unsaid, a page that stopped following the board looks frozen.
+		const warnBlind = (error: unknown): void => {
+			if (blind) return;
+			blind = true;
+			ctx.ui.notify(`board: the page cannot read the board (${messageOf(error)}) — it will keep trying`, "warning");
+		};
 		try {
-			server = await createBoardServer({
-				// A pinned port is tried alone: falling back would leave the bookmark pointing
-				// at a page that moved, which is the failure the setting exists to prevent.
-				ports: pinned === undefined ? [preferred, 0] : [pinned],
-				viewToken,
+			const started = await createBoardServer({
+				mount: deps.mount,
+				session: deps.session(),
+				token,
 				...(deps.interval === undefined ? {} : { interval: deps.interval }),
+				onError: warnBlind,
 				idleMs: deps.idleMs ?? IDLE_STOP_MS,
-				onIdle: () => void stopIdle(ctx),
-				page: async (view, authority) => renderBoardPage({ view, writes: authority === "write" }),
+				firstIdleMs: deps.firstIdleMs ?? IDLE_FIRST_MS,
+				onIdle: (reason) => void stopIdle(ctx, reason),
+				page: async (view) => renderBoardPage({ view, base: BOARD_BASE }),
 				script: BOARD_CLIENT_JS,
 				view: () =>
 					viewOf({
 						store,
 						actor,
-						session: () => runtime.who(ctx, ctx.cwd),
 						now,
 						busDir: () => runtime.busDir(ctx.cwd),
 					}),
-				write: (request) => writeOf({ store, actor, now }, request),
 			});
+			if (started.kind === "refused") {
+				ctx.ui.notify(`board: the page did not start (${started.reason})`, "error");
+				return { kind: "failed", reason: started.reason };
+			}
+			const server = started.server;
+			// The note and the seat: written last, on the port the server actually bound, and only if no
+			// other session got there first: the loser of that race attaches to the page that
+			// won rather than serving a second page nobody can find. A note that answers
+			// nobody is taken over, so a page that died between its note and its server does not
+			// hold the name forever, and a note this build cannot read is named rather than
+			// blamed on a session that does not exist.
+			const note: PagePointer = {
+				port: server.port,
+				token,
+				seat: { id: seat.id, label: seat.label },
+				startedAt: runtime.now(),
+			};
+			const outcome = await settlePointer(store.dir, note, deps.probe);
+			if (outcome.kind === "attached") {
+				await server.close();
+				return attach(outcome.pointer);
+			}
+			if (outcome.kind === "written" && outcome.took !== undefined) {
+				const dead = outcome.took;
+				ctx.ui.notify(
+					`board: ${dead.seat.label} on :${dead.port} does not answer — open ${urlOf(dead)} · took its note over`,
+					"info",
+				);
+			}
+			if (outcome.kind !== "written") {
+				await server.close();
+				const path = join(store.dir, PAGE_FILE);
+				const reason =
+					outcome.kind === "stale"
+						? `${path} names ${outcome.pointer.seat.label} on :${outcome.pointer.port}, and nothing answers — remove it to serve this board`
+						: outcome.kind === "busy"
+							? `${path} kept changing hands — run /board again`
+							: `${path} is there and cannot be read — remove it to serve this board`;
+				ctx.ui.notify(`board: the page did not start (${reason})`, "error");
+				return { kind: "failed", reason };
+			}
+			running = { server, store, token };
+			open(server.url);
+			return describe(running);
 		} catch (error) {
-			const reason = failureReason(error, pinned);
-			ctx.ui.notify(`board: the page did not start (${reason})`, "error");
-			return { kind: "failed", reason };
-		}
-		// The note is written last, on the port the server actually bound, and only if no
-		// other session got there first: the loser of that race becomes a viewer of the
-		// page that won rather than a second page nobody can find. A note that answers
-		// nobody is taken over, so a page that died between its note and its server does not
-		// hold the name forever, and a note this build cannot read is named rather than
-		// blamed on a session that does not exist.
-		const note: PagePointer = {
-			port: server.port,
-			viewToken,
-			seat: { id: seat.id, label: seat.label },
-			startedAt: runtime.now(),
-		};
-		const outcome = await settlePointer(store.dir, note, deps.probe);
-		if (outcome.kind === "attached") {
-			await server.close();
-			return attach(outcome.pointer);
+			return failed(error);
 		}
-		if (outcome.kind === "written" && outcome.took !== undefined) {
-			const dead = outcome.took;
-			ctx.ui.notify(
-				`board: ${dead.seat.label} on :${dead.port} does not answer — open ${viewUrlOf(dead)} · took its note over`,
-				"info",
-			);
-		}
-		if (outcome.kind !== "written") {
-			await server.close();
-			const path = join(store.dir, PAGE_FILE);
-			const reason =
-				outcome.kind === "stale"
-					? `${path} names ${outcome.pointer.seat.label} on :${outcome.pointer.port}, and nothing answers — remove it to serve this board`
-					: outcome.kind === "busy"
-						? `${path} kept changing hands — run /board again`
-						: `${path} is there and cannot be read — remove it to serve this board`;
-			ctx.ui.notify(`board: the page did not start (${reason})`, "error");
-			return { kind: "failed", reason };
-		}
-		sessionPort = server.port;
-		running = { server, store, viewToken };
-		setChip(ctx, server.port);
-		open(server.url);
-		return describe(running);
 	};
 
-	/** The idle grace closes the page and says so, once. */
-	const stopIdle = async (ctx: ExtensionContext): Promise<void> => {
-		if (await stop(ctx)) ctx.ui.notify("board: stopped — the last page was closed", "info");
+	/** The idle grace closes the page and says which grace it was, once. */
+	const stopIdle = async (ctx: ExtensionContext, reason: IdleReason): Promise<void> => {
+		if (!(await stop())) return;
+		ctx.ui.notify(
+			reason === "first"
+				? "board: stopped — no tab ever opened; /board starts it again"
+				: "board: stopped — the last page was closed",
+			"info",
+		);
 	};
 
 	const describe = (state: { server: BoardServer; store: BoardStore }): PageStart => ({
@@ -238,75 +293,66 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps = {})
 		seat: seat.label,
 		port: state.server.port,
 		url: state.server.url,
+		repo: state.store.name(),
 		where: state.store.where(),
 	});
 
-	/** What `/board status` answers, wherever the page is: served here, watched, or absent. */
-	const statusOf = (): BoardPageStatus => {
-		if (running) {
+	/**
+	 * What `/board status` answers, wherever the page is: served here, watched, watched and
+	 * dead, or absent.
+	 *
+	 * A watched page is probed, because the note saying it exists is not the same thing as
+	 * it answering: after the lead's session ends, its note stays and the reader would
+	 * otherwise be told about a port nobody holds.
+	 */
+	const statusOf = async (): Promise<BoardPageStatus> => {
+		if (running !== undefined) {
 			return {
 				running: true,
 				seat: seat.label,
 				port: running.server.port,
 				url: running.server.url,
+				repo: running.store.name(),
 				where: running.store.where(),
 				watchers: running.server.watchers(),
 			};
 		}
-		if (attachedTo !== undefined) {
-			return {
-				running: false,
-				attached: true,
-				seat: attachedTo.seat.label,
-				port: attachedTo.port,
-				url: viewUrlOf(attachedTo),
-			};
-		}
-		return { running: false };
+		if (attachedTo === undefined) return { running: false };
+		const answers = await probePage(attachedTo, deps.probe);
+		return {
+			running: false,
+			attached: true,
+			...(answers ? {} : { stale: true }),
+			seat: attachedTo.seat.label,
+			port: attachedTo.port,
+			url: urlOf(attachedTo),
+		};
+	};
+
+	/**
+	 * Drop the note of a page that has stopped answering.
+	 *
+	 * Only a note this session watched, and only while it answers nobody: a page that came
+	 * back between the status line and this call keeps its note, and `clearPointer`'s token
+	 * check makes that true even if a new page wrote one in between.
+	 */
+	const dropStale = async (ctx: ExtensionContext): Promise<boolean> => {
+		const pointer = attachedTo;
+		if (pointer === undefined) return false;
+		if (await probePage(pointer, deps.probe)) return false;
+		const store = await storeOf(ctx);
+		if (!(await clearPointer(store.dir, pointer.token))) return false;
+		attachedTo = undefined;
+		return true;
 	};
 
 	return {
 		start,
 		stop,
 		status: statusOf,
+		dropStale,
 		closeAll: async () => {
-			if (!running) return;
-			const { server } = running;
-			running = undefined;
-			await server.close();
+			await closeRunning();
 		},
 	};
 }
-
-/**
- * Why a start failed, naming the setting when the pinned port was the reason: a
- * bind error's own text says the address, not the key that chose it.
- */
-function failureReason(error: unknown, pinned: number | undefined): string {
-	// The bind path rejects with the `listen` error, so `code` is there to read.
-	const code = (error as NodeJS.ErrnoException | undefined)?.code;
-	if (pinned !== undefined && code === "EADDRINUSE") {
-		return `port ${pinned} is in use — change "port" in the bytefly.json board section, or stop what answers on it`;
-	}
-	return error instanceof Error ? error.message : String(error);
-}
-
-/** The chip naming the port, cleared with an empty text. */
-function setChip(ctx: ExtensionContext, port: number): void {
-	try {
-		ctx.ui.setStatus(
-			STATUS_KEYS.board,
-			`${paint(ctx.ui.theme, "ok", GLYPHS.board)} ${paint(ctx.ui.theme, "accent", String(port))}`,
-		);
-	} catch {
-		// A host without a status line is not a reason to keep the page from starting.
-	}
-}
-
-function clearChip(ctx: ExtensionContext): void {
-	try {
-		ctx.ui.setStatus(STATUS_KEYS.board, undefined);
-	} catch {
-		// Same as above: nothing to clear.
-	}
-}

package/extensions/board/result.ts

@@ -8,11 +8,10 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { Component } from "@earendil-works/pi-tui";
 import { type Card, cardRef } from "../../lib/board/card.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { TailResult, type TailResultInput, type TailSection } from "../../lib/tui/tool.ts";
+import type { TailResultInput, TailSection } from "../../lib/tui/tool.ts";
 import { plural } from "../../lib/board/round-text.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { boardRowLine } from "./rows.ts";
@@ -58,6 +57,15 @@ export function resultInput(details: BoardDetails): TailResultInput<Card> | unde
  */
 export function collapsedLine(theme: Theme, details: BoardDetails): string {
 	const me = paint(theme, "faint", sanitizeLine(details.me.label));
+	const archived = details.archived;
+	if (archived !== undefined && archived.length > 0) {
+		const first = archived[0];
+		const label =
+			archived.length === 1 && first !== undefined
+				? `${cardRef(first)} archived`
+				: `${plural(archived.length, "card")} archived`;
+		return `${paint(theme, "label", label)} ${SEPARATORS.item} ${me}`;
+	}
 	if (details.dropped)
 		return `${paint(theme, "label", `${cardRef(details.dropped)} dropped`)} ${SEPARATORS.item} ${me}`;
 	const card = details.card;
@@ -75,25 +83,3 @@ function cardLine(theme: Theme, card: Card): string {
 	const lane = paint(theme, "accent", card.status);
 	return `${id} ${lane} ${SEPARATORS.item} ${paint(theme, "label", sanitizeLine(card.title))}`;
 }
-
-/** The expanded block, as a component the transcript can reuse across renders. */
-export class BoardResult implements Component {
-	private readonly view: TailResult<Card>;
-
-	constructor(input: TailResultInput<Card>, theme: Theme) {
-		this.view = new TailResult(input, theme);
-	}
-
-	/** Update in place so the transcript reuses this component. */
-	setInput(input: TailResultInput<Card>, theme: Theme): void {
-		this.view.setInput(input, theme);
-	}
-
-	invalidate(): void {
-		this.view.invalidate();
-	}
-
-	render(width: number): string[] {
-		return this.view.render(width);
-	}
-}

package/extensions/board/rows.ts

@@ -35,7 +35,7 @@ function stateOf(card: Card): string[] {
 }
 
 /** One card: the id and title, with its state trailing. */
-export function cardRowLine(card: Card, width: number, theme: Theme, options: { self?: boolean } = {}): string {
+function cardRowLine(card: Card, width: number, theme: Theme, options: { self?: boolean } = {}): string {
 	return listRow(theme, width, {
 		marker: false,
 		label: `${cardRef(card.id)} ${sanitizeLine(card.title)}`,

package/extensions/board/schema.ts

@@ -8,31 +8,40 @@
  */
 
 import { Type } from "typebox";
-import { CARD_STATUSES, PRIORITIES } from "../../lib/board/card.ts";
+import { CARD_STATUSES, MAX_NOTE, PRIORITIES } from "../../lib/board/card.ts";
 import { BOARD_ACTIONS } from "./types.ts";
 
 export const BoardParams = Type.Object({
 	action: Type.Union(
 		BOARD_ACTIONS.map((action) => Type.Literal(action)),
 		{
+			// The verbs and their meanings live in the tool description, built from
+			// `BOARD_ACTION_DOCS`; this says only what a caller needs to choose one.
 			description:
-				"`list` the board (optionally one card, one lane, a query, or the lead's rollup), `add` a card, " +
-				"`claim` one for this session, `release` it, `reclaim` it from whoever holds it, `move` it to " +
-				"another lane, `note` it, `plan` it (record the plan file being executed), `edit` what it says " +
-				"(title, paths, priority, what it waits for), or `drop` it.",
+				"`list` reads the board, or one card when `card` names it; every other verb changes it. The tool description says what each one does.",
 		},
 	),
 	card: Type.Optional(
-		Type.String({ description: 'The card id for one card, e.g. "4" or "#4". Used by every action but `list`/`add`.' }),
+		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.',
+		}),
 	),
 	status: Type.Optional(
 		Type.Union(
 			CARD_STATUSES.map((status) => Type.Literal(status)),
 			{
-				description: "`list`: show only this lane. `move`: the lane to move to (not `todo` — use `release`).",
+				description:
+					"`list`: show only this lane, and not skip the `done` cards. `move`: the lane to move to (not `todo` — use `release`).",
 			},
 		),
 	),
+	blockedBy: Type.Optional(
+		Type.String({
+			description:
+				"`move` to `blocked`: what the card waits on — the decision a person has to make, one line, at most 200 characters.",
+		}),
+	),
 	title: Type.Optional(Type.String({ description: "`add` and `edit`: the feature's outcome, one line." })),
 	paths: Type.Optional(
 		Type.Array(Type.String(), {
@@ -40,8 +49,14 @@ 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." })),
+	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; one line, at most ${MAX_NOTE} characters.` }),
+	),
 	path: Type.Optional(Type.String({ description: "`plan`: the plan file this card is executing." })),
 	priority: Type.Optional(
 		Type.Union(
@@ -64,7 +79,7 @@ export const BoardParams = Type.Object({
 	query: Type.Optional(
 		Type.String({
 			description:
-				"`list`: show only the cards whose title, path hint, or holder matches this text, case-insensitively.",
+				"`list`: show only the cards whose title, holder, path hint, plan, or a note's text matches this text, case-insensitively.",
 		}),
 	),
 	round: Type.Optional(
@@ -72,4 +87,10 @@ export const BoardParams = Type.Object({
 			description: "`list`: also return the lead's rollup — owners, unassigned, unplanned, blocked, idle.",
 		}),
 	),
+	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.",
+		}),
+	),
 });