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

package/extensions/board/lazy-page.ts

@@ -0,0 +1,40 @@
+/**
+ * The board's page, loaded when `/board` first needs it.
+ *
+ * The page module owns the HTTP surface, the snapshots, and the view; none of it
+ * is needed to register the command or the tool. The factory therefore returns a
+ * proxy over `lib/lazy`: every command path loads the real page once, and
+ * `closeAll` on shutdown only closes a page that was already opened, so a
+ * session that never touched the board imports none of it.
+ *
+ * The loader is a seam: a test drives the proxy without a socket.
+ */
+
+import type { BoardSession } from "../../lib/board/session.ts";
+import { lazy } from "../../lib/lazy.ts";
+import type { BoardPage, BoardPageDeps } from "./page.ts";
+
+/** The page module, as the proxy loads it. */
+export type BoardPageModule = typeof import("./page.ts");
+
+/** How the proxy reaches the page module; production uses the dynamic import. */
+export type BoardPageLoader = () => Promise<BoardPageModule>;
+
+export function createLazyBoardPage(
+	session: BoardSession,
+	deps: BoardPageDeps,
+	load: BoardPageLoader = () => import("./page.ts"),
+): BoardPage {
+	const page = lazy(async () => (await load()).createBoardPage(session, deps));
+	return {
+		start: async (ctx, view) => (await page.get()).start(ctx, view),
+		stop: async () => (await page.get()).stop(),
+		status: async () => (await page.get()).status(),
+		dropStale: async (ctx) => (await page.get()).dropStale(ctx),
+		// Shutdown must not start a load: a page that never opened has nothing to close.
+		closeAll: async () => {
+			const opened = page.peek();
+			if (opened !== undefined) await opened.closeAll();
+		},
+	};
+}

package/extensions/board/page.ts

@@ -33,7 +33,8 @@ 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 { pageActor } from "./seat.ts";
+import type { Actor } from "../../lib/board/rules.ts";
+import { pageActor } from "../../lib/board/seat.ts";
 import { viewOf } from "./snapshot.ts";
 import { type BoardServer, createBoardServer } from "./transport/server.ts";
 import { BOARD_CLIENT_JS } from "./view/client.ts";
@@ -120,13 +121,9 @@ export interface BoardPage {
 }
 
 export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): BoardPage {
-	let running: { server: BoardServer; store: BoardStore; token: string } | undefined;
+	let running: { server: BoardServer; store: BoardStore; token: string; seat: Actor } | undefined;
 	/** The page another session serves, when this session opened that one instead. */
 	let attachedTo: PagePointer | 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);
 
 	/**
@@ -174,6 +171,11 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): Boa
 		} catch (error) {
 			return failed(error);
 		}
+		// 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. That name is
+		// the board's lead, so serving the page is what makes a session the lead — a repository
+		// that names one gets a page served under that name, and the gate accepts it.
+		const seat = pageActor(store.config().lead);
 		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 => {
@@ -218,7 +220,7 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): Boa
 				idleMs: deps.idleMs ?? IDLE_STOP_MS,
 				firstIdleMs: deps.firstIdleMs ?? IDLE_FIRST_MS,
 				onIdle: (reason) => void stopIdle(ctx, reason),
-				page: async (view) => renderBoardPage({ view, base: BOARD_BASE }),
+				page: async (view) => renderBoardPage({ view, base: BOARD_BASE, repo: store.name(), root: store.root() }),
 				script: BOARD_CLIENT_JS,
 				view: () =>
 					viewOf({
@@ -269,7 +271,7 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): Boa
 				ctx.ui.notify(`board: the page did not start (${reason})`, "error");
 				return { kind: "failed", reason };
 			}
-			running = { server, store, token };
+			running = { server, store, token, seat };
 			open(server.url);
 			return describe(running);
 		} catch (error) {
@@ -288,9 +290,9 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): Boa
 		);
 	};
 
-	const describe = (state: { server: BoardServer; store: BoardStore }): PageStart => ({
+	const describe = (state: { server: BoardServer; store: BoardStore; seat: Actor }): PageStart => ({
 		kind: "served",
-		seat: seat.label,
+		seat: state.seat.label,
 		port: state.server.port,
 		url: state.server.url,
 		repo: state.store.name(),
@@ -309,7 +311,7 @@ export function createBoardPage(runtime: BoardSession, deps: BoardPageDeps): Boa
 		if (running !== undefined) {
 			return {
 				running: true,
-				seat: seat.label,
+				seat: running.seat.label,
 				port: running.server.port,
 				url: running.server.url,
 				repo: running.store.name(),

package/extensions/board/result.ts

@@ -9,17 +9,19 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Card, cardRef } from "../../lib/board/card.ts";
+import { LANE_RULES } from "../../lib/board/lanes.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import type { TailResultInput, TailSection } from "../../lib/tui/tool.ts";
+import type { TailResultInput, TailSection, TailRowLine } 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";
+import { boardRowLineFor } from "./rows.ts";
+import { TONE_ROLE } from "./tone.ts";
 import type { BoardDetails } from "./types.ts";
 
-/** One section of the expanded block. */
-function section(label: string | undefined, cards: readonly Card[]): TailSection<Card> {
-	return { label, rows: cards, more: 0, rowLine: boardRowLine };
+/** One section of the expanded block, drawn as the session that asked for it. */
+function section(label: string | undefined, cards: readonly Card[], rowLine: TailRowLine<Card>): TailSection<Card> {
+	return { label, rows: cards, more: 0, rowLine };
 }
 
 /**
@@ -32,19 +34,25 @@ function section(label: string | undefined, cards: readonly Card[]): TailSection
  */
 export function resultInput(details: BoardDetails): TailResultInput<Card> | undefined {
 	if (details.action !== "list") return undefined;
-	if (details.card) return { kind: "list", rows: [details.card], more: 0, rowLine: boardRowLine };
+	// Only a read narrowed to this session's own cards marks them, and it marks them with
+	// the rule the filter used: the rows and the filter agree about what "mine" means.
+	const rowLine = boardRowLineFor(details.mine === true ? details.me : undefined);
+	if (details.card) return { kind: "list", rows: [details.card], more: 0, rowLine };
 	const round = details.round;
 	if (!round) {
 		const cards = details.cards ?? [];
-		return cards.length === 0 ? undefined : { kind: "list", rows: cards, more: 0, rowLine: boardRowLine };
+		return cards.length === 0 ? undefined : { kind: "list", rows: cards, more: 0, rowLine };
 	}
 	const sections: TailSection<Card>[] = [];
-	for (const group of round.owners) sections.push(section(group.label, group.cards));
-	if (round.unassigned.length > 0) sections.push(section("Unassigned", round.unassigned));
-	if (round.unplanned.length > 0) sections.push(section("Unplanned", round.unplanned));
-	if (round.blocked.length > 0) sections.push(section("Blocked", round.blocked));
-	if (round.idle.length > 0) sections.push(section("Idle", round.idle));
-	if (round.done.length > 0) sections.push(section("Done", round.done));
+	for (const group of round.owners) sections.push(section(group.label, group.cards, rowLine));
+	if (round.unassigned.length > 0) sections.push(section("Unassigned", round.unassigned, rowLine));
+	if (round.unplanned.length > 0) sections.push(section("Unplanned", round.unplanned, rowLine));
+	// The lead's queue: a contract nobody has signed is a card the flow stops on, so it is
+	// drawn in the order `formatRound` prints it rather than left to the text above.
+	if (round.unapproved.length > 0) sections.push(section("Awaiting approval", round.unapproved, rowLine));
+	if (round.blocked.length > 0) sections.push(section("Blocked", round.blocked, rowLine));
+	if (round.idle.length > 0) sections.push(section("Idle", round.idle, rowLine));
+	if (round.done.length > 0) sections.push(section("Done", round.done, rowLine));
 	return sections.length === 0 ? undefined : { kind: "sections", sections };
 }
 
@@ -77,9 +85,15 @@ export function collapsedLine(theme: Theme, details: BoardDetails): string {
 	return `${paint(theme, "label", plural(count, "card"))} ${SEPARATORS.item} ${plural(owners, "owner")} ${SEPARATORS.item} ${me}`;
 }
 
-/** `#4 doing · Billing webhook accepts orders`, clipped by the caller's row helper. */
+/**
+ * `#4 execute · Billing webhook accepts orders`, clipped by the caller's row helper.
+ *
+ * The lane wears the colour the page gives it — `LANE_RULES`' role, through the tone
+ * bridge — rather than one accent for all five.
+ */
 function cardLine(theme: Theme, card: Card): string {
 	const id = paint(theme, "meta", cardRef(card.id));
-	const lane = paint(theme, "accent", card.status);
-	return `${id} ${lane} ${SEPARATORS.item} ${paint(theme, "label", sanitizeLine(card.title))}`;
+	const lane = paint(theme, TONE_ROLE[LANE_RULES[card.lane].role], card.lane);
+	const title = paint(theme, "label", sanitizeLine(card.title));
+	return `${id} ${lane} ${SEPARATORS.item} ${title}`;
 }

package/extensions/board/rows.ts

@@ -4,45 +4,82 @@
  * Every field comes from a card file, which the model wrote and a person may have
  * edited, so it is sanitized here at the boundary that reaches the terminal, and
  * every row is clipped to the width it was given by the shared row helpers.
+ *
+ * The colours come from `lib/board/tone.ts` — the table the page reads too — through
+ * `TONE_ROLE`, so a lane's word in the transcript is the lane's colour on the page. Each
+ * word is painted on its own, which means the separator between two words is painted as
+ * well: a bare ` · ` would fall back to the terminal's default foreground between two
+ * coloured words.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { type Card, cardRef, DEFAULT_PRIORITY, priorityOf } from "../../lib/board/card.ts";
+import { type Card, cardRef, DEFAULT_PRIORITY, holds, priorityOf } from "../../lib/board/card.ts";
+import { LANE_RULES } from "../../lib/board/lanes.ts";
+import type { Actor } from "../../lib/board/rules.ts";
+import { type BoardTone, REASON_TONE } from "../../lib/board/tone.ts";
 import { sanitizeLine } from "../../lib/format.ts";
+import { clip, splitRow } from "../../lib/tui/columns.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { listRow } from "../../lib/tui/rows.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import type { TailRowLine } from "../../lib/tui/tool.ts";
+import { TONE_ROLE } from "./tone.ts";
 
-/** Who holds a card, as the row's trailing text. */
-function holderOf(card: Card): string {
-	if (card.owner === undefined) return "unassigned";
-	return sanitizeLine(card.owner.label);
+/** One fact the row states about a card, and the tone it wears. */
+interface Fact {
+	text: string;
+	tone: BoardTone;
 }
 
 /**
- * The lane, and — for work in flight — whether it was planned first, and — when it is
- * not the ordinary one — how urgent it is.
+ * Who holds a card, the lane it sits in, and — for work in flight — whether it was planned
+ * first, with the priority when it is not the ordinary one.
  *
  * A row carries the lane because a flat listing has no section heading to say it, and
- * "planned" because a `doing` card nobody planned is the one a lead looks at. The
- * priority rides along for the same reason: inside a lane the order is the priority,
- * and an order nobody can see reads as an accident.
+ * "planned" because a card nobody planned is the one a lead looks at. The priority rides
+ * along for the same reason: inside a lane the order is the priority, and an order nobody
+ * can see reads as an accident.
  */
-function stateOf(card: Card): string[] {
-	const urgency = priorityOf(card) === DEFAULT_PRIORITY ? [] : [priorityOf(card)];
-	if (card.status === "todo" || card.status === "done") return [...urgency, card.status];
-	return [...urgency, card.status, card.plan === undefined ? "unplanned" : "planned"];
+function factsOf(card: Card): Fact[] {
+	const facts: Fact[] = [
+		{
+			text: card.owner === undefined ? "unassigned" : sanitizeLine(card.owner.label),
+			tone: "muted",
+		},
+	];
+	const priority = priorityOf(card);
+	if (priority !== DEFAULT_PRIORITY) facts.push({ text: priority, tone: "muted" });
+	facts.push({ text: card.lane, tone: LANE_RULES[card.lane].role });
+	// The pool has no plan to speak of and a finished card is history, so only a lane
+	// somebody is working in says whether the work was planned first. An unplanned card
+	// wears the tone the page's reason line gives the same fact.
+	const rule = LANE_RULES[card.lane];
+	if (!rule.ownerless && !rule.terminal) {
+		facts.push(
+			card.planPath === undefined
+				? { text: "unplanned", tone: REASON_TONE.contract }
+				: { text: "planned", tone: "muted" },
+		);
+	}
+	return facts;
 }
 
-/** One card: the id and title, with its state trailing. */
-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)}`,
-		labelRole: options.self === true ? "accent" : "label",
-		trailing: [holderOf(card), ...stateOf(card)].join(SEPARATORS.item),
-	});
+/** One card: the id and title, with its facts trailing. */
+function cardRowText(card: Card, width: number, theme: Theme, self: boolean): string {
+	const head = paint(theme, self ? "accent" : "label", `${cardRef(card.id)} ${sanitizeLine(card.title)}`);
+	const gap = paint(theme, "meta", SEPARATORS.item);
+	const trailing = factsOf(card)
+		.map((fact) => paint(theme, TONE_ROLE[fact.tone], fact.text))
+		.join(gap);
+	return splitRow(head, clip(trailing, width), width);
 }
 
-/** The row renderer every board section uses. */
-export const boardRowLine: TailRowLine<Card> = (card, width, theme) => cardRowLine(card, width, theme);
+/**
+ * The row renderer every board section uses, for the session reading it.
+ *
+ * `me` matters: a `list` narrowed to this session's own cards should look like it, so the
+ * holder's rows wear the accent the page gives the card the reader is looking at. Passing
+ * no actor draws every row the same, which is what a card produced by an action gets.
+ */
+export function boardRowLineFor(me?: Actor): TailRowLine<Card> {
+	return (card, width, theme) => cardRowText(card, width, theme, me !== undefined && holds(card, me));
+}

package/extensions/board/schema.ts

@@ -8,7 +8,10 @@
  */
 
 import { Type } from "typebox";
-import { CARD_STATUSES, MAX_NOTE, 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(), {
@@ -55,9 +70,25 @@ export const BoardParams = Type.Object({
 		}),
 	),
 	text: Type.Optional(
-		Type.String({ description: `\`note\`: the note to append; one line, at most ${MAX_NOTE} characters.` }),
+		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." }),
 	),
-	path: Type.Optional(Type.String({ description: "`plan`: the plan file this card is executing." })),
 	priority: Type.Optional(
 		Type.Union(
 			PRIORITIES.map((priority) => Type.Literal(priority)),
@@ -70,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(
@@ -84,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

@@ -34,10 +34,11 @@ export async function viewOf(context: SnapshotContext): Promise<BoardView> {
 		cards,
 		now: context.now(),
 		bytes: await context.store.bytes(),
-		skipped: 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",
+};