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

package/lib/board/card.ts

@@ -30,12 +30,25 @@ export const MAX_PATH = 200;
 /** Longest recorded plan path, in characters. */
 export const MAX_PLAN = 300;
 
+/** Longest sentence saying what a blocked card is waiting on: one line, so it fits a row. */
+export const MAX_BLOCKED = 200;
+
 /** Longest single note, in characters. */
 export const MAX_NOTE = 1000;
 
 /** How many notes one card keeps; the oldest drops past this, counted in `notesDropped`. */
 export const MAX_NOTES = 8;
 
+/**
+ * How many lane transitions one card keeps; the oldest drops past this, counted in
+ * `logDropped`.
+ *
+ * Bounded at write time rather than by a janitor, because nothing prunes a board: the
+ * log is the only record of when a lane was entered, so it has to stay small enough
+ * that every card can afford one.
+ */
+export const MAX_LOG = 8;
+
 /** How many other cards one card may wait on. */
 export const MAX_DEPENDS = 6;
 
@@ -69,6 +82,33 @@ export interface CardNote {
 	text: string;
 }
 
+/**
+ * One lane a card has been in, when it got there, and who moved it.
+ *
+ * `updatedAt` moves on every write, so it answers "when was this last touched", not
+ * "how long has this been blocked": a note filed against a blocked card resets it. A
+ * transition is recorded only when the lane actually changes, which is the fact the
+ * page needs and the one a reader has no way to reconstruct.
+ */
+export interface CardTransition {
+	status: CardStatus;
+	at: number;
+	by: string;
+}
+
+/**
+ * What a finished card landed as.
+ *
+ * A `done` card cannot say which change closed it from its own text, and `done` is
+ * terminal, so the commit is recorded once, where the move that finished it happens.
+ */
+export interface CardLanded {
+	/** The commit at the move to `done`, as git resolves `HEAD` there. */
+	commit: string;
+	/** When the card was finished. */
+	at: number;
+}
+
 /** One feature on the board. */
 export interface Card {
 	/** Schema version; an unknown value is refused rather than guessed at. */
@@ -83,6 +123,25 @@ export interface Card {
 	paths: string[];
 	/** The plan file being executed, once one is recorded. */
 	plan?: string;
+	/**
+	 * What a blocked card is waiting on: the decision, in one line.
+	 *
+	 * `blocked` exists to say a human has to decide something — a dependency is a
+	 * different thing, and `waits` is what refuses a claim. Absent means the card was
+	 * blocked without saying why, which is a state the tool allows and the page names.
+	 */
+	blockedBy?: string;
+	/** What closed a finished card: the commit at the move to `done`, and when. */
+	landed?: CardLanded;
+	/**
+	 * When this card was last offered to the team, and nobody has taken it.
+	 *
+	 * An offer is a bus event, and an event leaves nothing behind: a card offered to three
+	 * sessions that all ignored it read exactly like one nobody had looked at. This is the
+	 * one fact an offer can leave, and every answer to it — a claim, an assignment, a
+	 * release, a move — clears it, so a record here means the offer is still open.
+	 */
+	offeredAt?: number;
 	/** How urgent the feature is; absent reads as {@link DEFAULT_PRIORITY}. */
 	priority?: Priority;
 	/** Ids of the cards this one waits for; absent reads as none. */
@@ -91,6 +150,15 @@ export interface Card {
 	notes: CardNote[];
 	/** How many notes dropped off the front, so a reader knows history was elided. */
 	notesDropped: number;
+	/**
+	 * The lanes this card has been in, oldest first: the last {@link MAX_LOG} transitions.
+	 *
+	 * Absent on a card written before this field existed, which is why every reader goes
+	 * through {@link laneSince} rather than reading the list directly.
+	 */
+	log?: CardTransition[];
+	/** How many transitions dropped off the front, so a reader knows the log was elided. */
+	logDropped?: number;
 	/** Bumped per write; the compare-and-set guard a concurrent writer loses on. */
 	rev: number;
 	createdAt: number;
@@ -99,6 +167,47 @@ export interface Card {
 	by: string;
 }
 
+/**
+ * What a card left behind when it was dropped: the record that its id is spent.
+ *
+ * A card's id is how a note, a handoff, or another card names one feature, so an id
+ * that comes back is worse than an id that is gone — the same number would answer for
+ * two different features. The store keeps one of these per ended card, writes it
+ * before the card file goes, and never allocates its id again.
+ */
+export interface EndedCard {
+	/** Schema version for the record itself; a reader refuses what it does not know. */
+	v: 1;
+	/** The id that is now spent, without padding. */
+	id: string;
+	/** What the card was called, so a note that names its id still reads. */
+	title: string;
+	/** The lane it was in when it ended. */
+	status: CardStatus;
+	/** Who ended it. */
+	by: string;
+	/** The owner it had, when it had one. */
+	owner?: CardOwner;
+	/** When it ended. */
+	at: number;
+	/** Why it ended: the operation, which is `drop` today. */
+	why: "dropped";
+}
+
+/** Whether `value` is an ended-card record this build can trust. */
+export function isEndedCard(value: unknown): value is EndedCard {
+	if (typeof value !== "object" || value === null) return false;
+	const ended = value as Record<string, unknown>;
+	if (ended.v !== CARD_VERSION) return false;
+	if (typeof ended.id !== "string" || !/^[0-9]+$/.test(ended.id)) return false;
+	if (typeof ended.title !== "string" || ended.title === "") return false;
+	if (!CARD_STATUSES.includes(ended.status as CardStatus)) return false;
+	if (typeof ended.by !== "string" || ended.by === "") return false;
+	if (!isOwner(ended.owner)) return false;
+	if (typeof ended.at !== "number" || !Number.isInteger(ended.at)) return false;
+	return ended.why === "dropped";
+}
+
 /** A rejected field, phrased for the model: what was wrong, not that something was. */
 export type FieldError = { error: string };
 
@@ -163,25 +272,50 @@ export function dependsOf(card: Card): readonly string[] {
 	return card.dependsOn ?? [];
 }
 
+/**
+ * When the card entered the lane it is in now, or `undefined` when its history does not
+ * say.
+ *
+ * Two ways to know nothing: a card written before the log existed, and one whose entry
+ * for the current lane has dropped off the front of a full log. Both read the same to a
+ * caller — the page draws no age — rather than a guess from `updatedAt`, which is a
+ * different fact and would be wrong exactly when a card is being worked on.
+ */
+export function laneSince(card: Card): number | undefined {
+	const last = card.log?.at(-1);
+	return last !== undefined && last.status === card.status ? last.at : undefined;
+}
+
 /** Where a card's priority sits in {@link PRIORITIES}: the lane sort's first key after the lane. */
 export function priorityRank(card: Card): number {
 	return PRIORITIES.indexOf(priorityOf(card));
 }
 
 /**
- * Whether `query` names `card`: its title, one of its path hints, or its holder.
+ * Whether `query` names `card`: its title, its holder, a path hint, its plan, or a note.
  *
  * The page's filter and `board list`'s `query` are the same question, so they are the
- * same rule here — a reader who finds a card in the browser finds it in the tool.
+ * same rule here — and the same *body*: this function's source is spliced into the
+ * browser bundle as `MATCHES_QUERY_JS`, which is why it is written with concatenation
+ * and no backtick. A second copy in the page is exactly what drifted before.
+ *
+ * The order is the answer's weight: a title hit is what a reader meant, then who holds
+ * it, then where it lives, and only then the reasoning — a plan path and the notes,
+ * which are the two fields that make a card findable by what it says.
  */
 export function matchesQuery(card: Card, query: string): boolean {
 	const needle = query.trim().toLowerCase();
 	if (needle === "") return true;
 	if (card.title.toLowerCase().includes(needle)) return true;
 	if (card.owner !== undefined && card.owner.label.toLowerCase().includes(needle)) return true;
-	return card.paths.some((path) => path.toLowerCase().includes(needle));
+	if (card.paths.some((path) => path.toLowerCase().includes(needle))) return true;
+	if (card.plan !== undefined && card.plan.toLowerCase().includes(needle)) return true;
+	return card.notes.some((note) => note.text.toLowerCase().includes(needle));
 }
 
+/** The same body, as the browser receives it: one rule for the tool and the filter box. */
+export const MATCHES_QUERY_JS = String(matchesQuery);
+
 /** One note's text: a single sanitized line, or the reason it cannot be one. */
 export function normalizeNote(raw: unknown): { text: string } | FieldError {
 	if (typeof raw !== "string") return { error: "text is required." };
@@ -205,6 +339,22 @@ export function normalizePlanPath(raw: unknown): { path: string } | FieldError {
 	return { path };
 }
 
+/**
+ * The sentence a block records: one line, and nothing more.
+ *
+ * The board never resolves it against anything — it is the reader's explanation of what
+ * a person has to decide — so this only keeps it to a length a row can hold.
+ */
+export function normalizeBlockedBy(raw: unknown): { blockedBy: string } | FieldError {
+	if (typeof raw !== "string") return { error: "blockedBy must be text." };
+	const blockedBy = sanitizeLine(raw).trim();
+	if (blockedBy === "") return { error: "blockedBy must say what the card waits on." };
+	if (blockedBy.length > MAX_BLOCKED) {
+		return { error: `blockedBy must be at most ${MAX_BLOCKED} characters.` };
+	}
+	return { blockedBy };
+}
+
 /** A card id as a caller writes it (`4`, `#4`), or undefined when it is not one. */
 export function normalizeCardId(raw: unknown): string | undefined {
 	if (typeof raw !== "string") return undefined;
@@ -250,17 +400,38 @@ export function isCard(value: unknown): value is Card {
 	if (!Array.isArray(card.paths) || card.paths.length > MAX_PATHS) return false;
 	if (!card.paths.every((path) => typeof path === "string")) return false;
 	if (card.plan !== undefined && typeof card.plan !== "string") return false;
+	if (card.blockedBy !== undefined && !isBlockedBy(card.blockedBy)) return false;
+	if (card.landed !== undefined && !isLanded(card.landed)) return false;
+	if (card.offeredAt !== undefined && (typeof card.offeredAt !== "number" || !Number.isInteger(card.offeredAt))) {
+		return false;
+	}
 	if (card.priority !== undefined && !PRIORITIES.includes(card.priority as Priority)) return false;
 	if (card.dependsOn !== undefined && !isDepends(card.dependsOn)) return false;
 	if (!Array.isArray(card.notes) || card.notes.length > MAX_NOTES) return false;
 	if (!card.notes.every(isNote)) return false;
 	if (typeof card.notesDropped !== "number") return false;
+	if (card.log !== undefined && (!Array.isArray(card.log) || card.log.length > MAX_LOG)) return false;
+	if (Array.isArray(card.log) && !card.log.every(isTransition)) return false;
+	if (card.logDropped !== undefined && !isCount(card.logDropped)) return false;
 	if (typeof card.rev !== "number" || !Number.isInteger(card.rev) || card.rev < 1) return false;
 	if (typeof card.createdAt !== "number" || typeof card.updatedAt !== "number") return false;
 	if (typeof card.by !== "string") return false;
 	return (card.status === "todo") === (card.owner === undefined);
 }
 
+/** A recorded block: one line the reader can hold, within the cap this build writes. */
+function isBlockedBy(value: unknown): value is string {
+	return typeof value === "string" && value !== "" && value.length <= MAX_BLOCKED;
+}
+
+/** A recorded landing: a commit id and the moment it closed the card. */
+function isLanded(value: unknown): value is CardLanded {
+	if (typeof value !== "object" || value === null) return false;
+	const landed = value as Record<string, unknown>;
+	if (typeof landed.commit !== "string" || !/^[0-9a-f]{4,40}$/.test(landed.commit)) return false;
+	return typeof landed.at === "number" && Number.isInteger(landed.at);
+}
+
 function isOwner(value: unknown): boolean {
 	if (value === undefined) return true;
 	if (typeof value !== "object" || value === null) return false;
@@ -283,6 +454,24 @@ function isDepends(value: unknown): boolean {
 	return true;
 }
 
+/** A recorded lane change: a lane, a moment, and who moved it. */
+function isTransition(value: unknown): value is CardTransition {
+	if (typeof value !== "object" || value === null) return false;
+	const entry = value as Record<string, unknown>;
+	return (
+		CARD_STATUSES.includes(entry.status as CardStatus) &&
+		typeof entry.at === "number" &&
+		Number.isInteger(entry.at) &&
+		typeof entry.by === "string" &&
+		entry.by !== ""
+	);
+}
+
+/** A count a reader can trust: a whole number that never ran backwards past zero. */
+function isCount(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
 function isNote(value: unknown): boolean {
 	if (typeof value !== "object" || value === null) return false;
 	const note = value as Record<string, unknown>;

package/lib/board/links.ts

@@ -39,17 +39,41 @@ export function blockersOf(card: Card, board: BoardIndex): Card[] {
 		.filter((other): other is Card => other !== undefined && other.status !== "done");
 }
 
+/**
+ * A list of cards as a reader meets it: `#2 (doing), #3 (blocked)`.
+ *
+ * The lane is what turns ids into a decision — a finished card is about to start, a
+ * `doing` one is to leave alone — so it is never left out. One wording serves the
+ * refusal sentence, the page's reason line, and the mirror question of what a card is
+ * holding up: every one of them is a list of cards read to decide something, so a second
+ * formatter would be a second way for the same list to read.
+ */
+export function lanesText(cards: readonly Card[]): string {
+	return cards.map((card) => `${cardRef(card.id)} (${card.status})`).join(", ");
+}
+
 /** The cards that wait on `id`, oldest id first, so a report reads in board order. */
 export function dependentsOf(id: string, board: BoardIndex): Card[] {
 	return [...board.values()].filter((card) => dependsOf(card).includes(id)).sort((a, b) => Number(a.id) - Number(b.id));
 }
 
+/**
+ * The cards still waiting on `id`: the work this card is holding up.
+ *
+ * The mirror of {@link blockersOf}, and for the same reason — a finished dependent has
+ * stopped waiting, so it stops counting here and a card whose only dependents are done
+ * reads as one nothing waits on. `dependentsOf` keeps every edge, because the drop
+ * refusal is about a link that would be stranded rather than about work that is held up.
+ */
+export function openDependentsOf(id: string, board: BoardIndex): Card[] {
+	return dependentsOf(id, board).filter((card) => card.status !== "done");
+}
+
 /** The sentence a claim, a move, or an assignment is refused with while `card` waits, or undefined. */
 export function waitingOn(card: Card, board: BoardIndex): string | undefined {
 	const blockers = blockersOf(card, board);
 	if (blockers.length === 0) return undefined;
-	const named = blockers.map((blocker) => `${cardRef(blocker.id)} (${blocker.status})`).join(", ");
-	return `${cardRef(card.id)} waits on ${named}.`;
+	return `${cardRef(card.id)} waits on ${lanesText(blockers)}.`;
 }
 
 /** The sentence a drop is refused with while another card waits on `id`, or undefined. */

package/lib/board/page-pointer.ts

@@ -3,8 +3,8 @@
  *
  * A page is one loopback server owned by one session's process, so nothing about it is
  * discoverable without a note left where the repository's state already lives. That note
- * is `<board>/page.json`: the port, the seat serving it, and a *view* token — never the
- * write token, which stays in the URL the lead's own browser was opened at.
+ * is `<board>/page.json`: the port, the seat serving it, and the token the page reads by.
+ * The page cannot change a card, so the note carries nothing a reader could misuse.
  *
  * Two rules make the file safe to trust:
  *
@@ -22,18 +22,25 @@
 import { access, link, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { hasErrorCode } from "../errors.ts";
+import { abortableSleep } from "../timer.ts";
 
 /** The file, beside the board's `cards/` directory. */
 export const PAGE_FILE = "page.json";
 
-/** How long a probe waits before it calls the page gone. */
-export const PROBE_MS = 600;
+/**
+ * How long a probe waits before it calls the page gone.
+ *
+ * Long enough for a page that is busy answering a browser: the probe shares the event
+ * loop with the snapshot route, and a page declared dead while it is merely slow is taken
+ * over — two servers, one note.
+ */
+export const PROBE_MS = 1_500;
 
-/** The port, the seat, and the credential a viewer may hold. */
+/** The port, the seat, and the credential the page reads by. */
 export interface PagePointer {
 	port: number;
-	/** A token that satisfies every read and no write. */
-	viewToken: string;
+	/** The page's one token: every read, and nothing else to authorise. */
+	token: string;
 	/** The seat the page writes as. */
 	seat: { id?: string; label: string };
 	/** When the page started, so a reader can tell a fresh note from a stale one. */
@@ -41,11 +48,11 @@ export interface PagePointer {
 }
 
 /** The fetch a probe uses: the global one in production, a stub in a test. */
-export type ProbeFetch = (url: string, init: { signal: AbortSignal }) => Promise<{ ok: boolean }>;
+export type ProbeFetch = (url: string, init: { signal: AbortSignal }) => Promise<{ ok: boolean; status?: number }>;
 
-/** The URL a viewer opens: the page, with the credential that may only read it. */
-export function viewUrlOf(pointer: PagePointer): string {
-	return `http://127.0.0.1:${pointer.port}/?token=${pointer.viewToken}`;
+/** The URL for this page, wherever it is opened from. */
+export function urlOf(pointer: PagePointer): string {
+	return `http://127.0.0.1:${pointer.port}/?token=${pointer.token}`;
 }
 
 /**
@@ -126,9 +133,9 @@ export async function createPointer(dir: string, pointer: PagePointer): Promise<
  * findable. The move is atomic, so the file this call holds is the file that was there;
  * a note that is not the one proved dead goes back where it came from.
  */
-export async function clearPointer(dir: string, viewToken: string): Promise<boolean> {
+export async function clearPointer(dir: string, token: string): Promise<boolean> {
 	const pointer = await readPointer(dir);
-	if (pointer === undefined || pointer.viewToken !== viewToken) return false;
+	if (pointer === undefined || pointer.token !== token) return false;
 	const target = join(dir, PAGE_FILE);
 	const held = `${target}.gone-${process.pid}-${Math.random().toString(16).slice(2, 10)}`;
 	try {
@@ -138,7 +145,7 @@ export async function clearPointer(dir: string, viewToken: string): Promise<bool
 		return false;
 	}
 	const moved = await readPointerAt(held);
-	if (moved === undefined || moved.viewToken !== viewToken) {
+	if (moved === undefined || moved.token !== token) {
 		await putBack(held, target);
 		return false;
 	}
@@ -164,6 +171,14 @@ async function putBack(held: string, target: string): Promise<void> {
 /** How many times a caller tries to own the note before it gives up for good. */
 export const NOTE_ATTEMPTS = 3;
 
+/** How long a page that has written its note but does not answer yet is given, in steps. */
+export const YOUNG_POLLS = 8;
+const YOUNG_POLL_MS = 75;
+
+/** How many times a caller looks again at a name that is momentarily free. */
+const EMPTY_LOOKS = 20;
+const EMPTY_LOOK_MS = 25;
+
 /** What one `/board` found where the note should be. */
 export type PointerOutcome =
 	| { kind: "written"; took?: PagePointer }
@@ -191,46 +206,82 @@ export type PointerOutcome =
  */
 export async function settlePointer(dir: string, note: PagePointer, probe?: ProbeFetch): Promise<PointerOutcome> {
 	let took: PagePointer | undefined;
-	for (let attempt = 0; attempt < NOTE_ATTEMPTS; attempt++) {
+	let attempts = 0;
+	let looks = 0;
+	while (attempts < NOTE_ATTEMPTS) {
 		// A retry writes a fresh `startedAt`, so a reader can tell it from the first attempt.
-		const candidate = attempt === 0 ? note : { ...note, startedAt: note.startedAt + attempt };
+		const candidate = attempts === 0 ? note : { ...note, startedAt: note.startedAt + attempts };
 		if (await createPointer(dir, candidate))
 			return took === undefined ? { kind: "written" } : { kind: "written", took };
 		const winner = await readPointer(dir);
 		if (winner === undefined) {
-			// No note at all means the page that had it cleared it in this instant: try again
-			// rather than reporting a file that is not there. Only a file that stays, and
-			// cannot be read, is the caller's dead end.
-			if (!(await noteExists(dir))) continue;
-			return { kind: "unreadable" };
+			// No note at all means a page is between clearing its note and writing the next one.
+			// That is a few microseconds of somebody else's work, not a takeover attempt of this
+			// caller's, so the name is chased without spending one; a file that stays, and cannot
+			// be read, is the caller's dead end.
+			if (await noteExists(dir)) return { kind: "unreadable" };
+			if (looks >= EMPTY_LOOKS) return { kind: "busy" };
+			looks += 1;
+			await abortableSleep(EMPTY_LOOK_MS);
+			continue;
 		}
-		if (await probePage(winner, probe)) return { kind: "attached", pointer: winner };
+		attempts += 1;
+		if (await answerOrWait(winner, probe)) return { kind: "attached", pointer: winner };
 		// Only that exact note: a note a newer page wrote is not this caller's to take. A
 		// refused clear means somebody else got there first, so the next attempt re-reads.
-		if (await clearPointer(dir, winner.viewToken)) took = winner;
+		if (await clearPointer(dir, winner.token)) took = winner;
 	}
 	const last = await readPointer(dir);
 	if (last !== undefined) return { kind: "stale", pointer: last };
 	return (await noteExists(dir)) ? { kind: "unreadable" } : { kind: "busy" };
 }
 
+/**
+ * Whether the winner answers, giving a page that is still coming up its full probe window.
+ *
+ * A note is written before its server can accept a connection, so the loser of a simultaneous
+ * start reads a note whose page is a few milliseconds behind it. One refused connection is
+ * therefore not proof of death: stealing that note serves a second page, and calling it stale
+ * reports a page that exists as one that did not start. The poll is bounded at the same
+ * 600 ms a probe itself may spend, so a note whose page is really gone is still taken over.
+ */
+async function answerOrWait(pointer: PagePointer, probe?: ProbeFetch): Promise<boolean> {
+	for (let attempt = 0; attempt < YOUNG_POLLS; attempt++) {
+		if (await probePage(pointer, probe)) return true;
+		await abortableSleep(YOUNG_POLL_MS);
+	}
+	return false;
+}
+
 /**
  * Whether the page a pointer names is answering.
  *
- * A page that answers with anything but a 200 to the snapshot request is not one to
- * attach to: a port reused by another program, a server shutting down, and a page that
- * refuses the token all read the same, and all mean "serve your own".
+ * The question goes to the cheap liveness route, not to the snapshot: a probe runs while
+ * another session may be serving a browser, and asking for the snapshot would make a busy
+ * page look like a dead one — the very race that costs a takeover and leaves two servers.
+ * A page from a build without that route answers 404 there and is asked for its snapshot
+ * once, so an upgrade mid-session attaches instead of stealing the seat.
+ *
+ * A page that answers with anything but a 200 is not one to attach to: a port reused by
+ * another program, a server shutting down, and a page that refuses the token all read the
+ * same, and all mean "serve your own".
  */
 export async function probePage(
 	pointer: PagePointer,
 	fetchLike: ProbeFetch = (url, init) => fetch(url, init),
 	timeoutMs: number = PROBE_MS,
 ): Promise<boolean> {
-	try {
-		const response = await fetchLike(`http://127.0.0.1:${pointer.port}/api/board?token=${pointer.viewToken}`, {
+	const ask = (path: string): Promise<{ ok: boolean; status?: number }> =>
+		fetchLike(`http://127.0.0.1:${pointer.port}${path}?token=${pointer.token}`, {
 			signal: AbortSignal.timeout(timeoutMs),
 		});
-		return response.ok;
+	try {
+		const ping = await ask("/api/ping");
+		if (ping.ok) return true;
+		// A page this build started always answers the ping; a 404 is one started by an
+		// older build, whose only liveness answer is its snapshot.
+		if (ping.status !== 404) return false;
+		return (await ask("/api/board")).ok;
 	} catch {
 		return false;
 	}
@@ -239,9 +290,12 @@ export async function probePage(
 /** A parsed file as a pointer, or undefined when it is not one this build can trust. */
 function asPointer(value: unknown): PagePointer | undefined {
 	if (typeof value !== "object" || value === null) return undefined;
-	const { port, viewToken, seat, startedAt } = value as Record<string, unknown>;
+	const { port, seat, startedAt } = value as Record<string, unknown>;
+	// A note written by the build with two tokens carries `viewToken`; it is this page's
+	// only credential now, so an upgrade reads it instead of refusing to serve its own note.
+	const { token = (value as { viewToken?: unknown }).viewToken } = value as { token?: unknown };
 	if (typeof port !== "number" || !Number.isInteger(port) || port <= 0 || port > 65_535) return undefined;
-	if (typeof viewToken !== "string" || viewToken === "") return undefined;
+	if (typeof token !== "string" || token === "") return undefined;
 	if (typeof startedAt !== "number") return undefined;
 	if (typeof seat !== "object" || seat === null) return undefined;
 	const { id, label } = seat as Record<string, unknown>;
@@ -249,7 +303,7 @@ function asPointer(value: unknown): PagePointer | undefined {
 	if (id !== undefined && typeof id !== "string") return undefined;
 	return {
 		port,
-		viewToken,
+		token,
 		seat: id === undefined ? { label } : { id, label },
 		startedAt,
 	};

package/lib/board/round-text.ts

@@ -47,11 +47,20 @@ export function formatRound(cards: readonly Card[], round: RoundSummary): string
 	return lines.join("\n");
 }
 
-/** `1 owner`, `2 owners`. */
+/**
+ * `1 owner`, `2 owners`.
+ *
+ * Written as concatenation rather than a template, because the page's bundle carries
+ * this function's *source*: a backtick or an interpolation in it would end the string it
+ * is spliced into. `round-text.test.ts` pins both, and `PLURAL_JS` is how it crosses.
+ */
 export function plural(count: number, noun: string): string {
-	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+	return count + " " + noun + (count === 1 ? "" : "s");
 }
 
+/** The same body, as the browser receives it: one wording for `1 card`, not two. */
+export const PLURAL_JS = String(plural);
+
 /** `#4 doing planned`, the brief a rollup group needs. */
 function brief(card: Card): string {
 	const planned = card.status === "doing" ? (card.plan === undefined ? " unplanned" : " planned") : "";

package/lib/board/round.ts

@@ -8,8 +8,8 @@
  * know — nobody has touched it in half an hour — not that its owner's process is
  * gone.
  *
- * The groups overlap on purpose. A `doing` card with no plan and no touch for an
- * hour is both `unplanned` and `idle`, and hiding it in one of the two would lose
+ * The groups overlap on purpose. A `doing` card with no plan and no touch for half
+ * an hour is both `unplanned` and `idle`, and hiding it in one of the two would lose
  * half the reason a lead should look at it.
  *
  * Pure: no I/O and no clock of its own.
@@ -20,28 +20,33 @@ import type { Card } from "./card.ts";
 /** How long a `doing` card may go untouched before the rollup calls it idle. */
 export const IDLE_MS = 30 * 60 * 1_000;
 
-/** One owner, the live cards it holds, and the ones it finished. */
-export interface RoundGroup {
+/**
+ * One owner, the live cards it holds, and the ones it finished.
+ *
+ * `T` is what the caller handed in: the rollup never builds a card, so a snapshot whose
+ * cards carry derived facts hands them back on the same terms it received them.
+ */
+export interface RoundGroup<T extends Card = Card> {
 	label: string;
-	cards: Card[];
+	cards: T[];
 	/** This owner's finished cards: history, kept so a teammate who is done is not erased. */
-	done: Card[];
+	done: T[];
 }
 
 /** The lead's rollup of one board. */
-export interface RoundSummary {
+export interface RoundSummary<T extends Card = Card> {
 	/** Every owner with at least one unfinished card, ordered by label. */
-	owners: RoundGroup[];
+	owners: RoundGroup<T>[];
 	/** `todo` cards: nobody has taken them yet. */
-	unassigned: Card[];
+	unassigned: T[];
 	/** `doing` cards with no plan recorded: work started before it was planned. */
-	unplanned: Card[];
+	unplanned: T[];
 	/** `blocked` cards, and the note that says why. */
-	blocked: Card[];
+	blocked: T[];
 	/** `doing` cards untouched for {@link IDLE_MS}: possibly a dead owner. */
-	idle: Card[];
+	idle: T[];
 	/** Finished cards, oldest first, kept as history. */
-	done: Card[];
+	done: T[];
 }
 
 /**
@@ -55,13 +60,13 @@ export interface RoundSummary {
  * whose labels differ only by case are one owner — a name is case-insensitive when
  * it is a send target, so it is here too — and the first spelling seen is kept.
  */
-export function buildRound(cards: readonly Card[], now: number): RoundSummary {
-	const groups = new Map<string, RoundGroup>();
-	const unassigned: Card[] = [];
-	const unplanned: Card[] = [];
-	const blocked: Card[] = [];
-	const idle: Card[] = [];
-	const done: Card[] = [];
+export function buildRound<T extends Card = Card>(cards: readonly T[], now: number): RoundSummary<T> {
+	const groups = new Map<string, RoundGroup<T>>();
+	const unassigned: T[] = [];
+	const unplanned: T[] = [];
+	const blocked: T[] = [];
+	const idle: T[] = [];
+	const done: T[] = [];
 
 	for (const card of cards) {
 		if (card.status === "todo") unassigned.push(card);