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

package/lib/board/rules.ts

@@ -31,7 +31,9 @@ import {
 	cardRef,
 	DEFAULT_PRIORITY,
 	dependsOf,
+	MAX_LOG,
 	MAX_NOTES,
+	normalizeBlockedBy,
 	normalizeNote,
 	normalizePathHints,
 	normalizePlanPath,
@@ -57,7 +59,13 @@ export type CardOp =
 	 */
 	| { kind: "assign"; to: Actor; note?: unknown }
 	| { kind: "release" }
-	| { kind: "move"; status: Exclude<CardStatus, "todo"> }
+	/**
+	 * Change lane. `blockedBy` says what a block waits on, and `landed` says which commit
+	 * closed a card: both are read only by the lane they belong to, and both are optional,
+	 * because a card may be blocked with nothing recorded and a `done` card may predate the
+	 * field or live outside a repository.
+	 */
+	| { kind: "move"; status: Exclude<CardStatus, "todo">; blockedBy?: unknown; landed?: { commit: string } }
 	// `text` and `path` are whatever the model sent: `card.ts` validates them, and the
 	// refusal it produces is the one the caller shows.
 	| { kind: "note"; text: unknown }
@@ -66,6 +74,16 @@ export type CardOp =
 	// sends the three it can show, and omitting a link must not clear it.
 	| { kind: "edit"; title: unknown; paths: unknown; priority: unknown; dependsOn: unknown }
 	| { kind: "reclaim" }
+	/**
+	 * Record that the card was offered to the team: `team offer` broadcasts it on the bus
+	 * and then writes this, because an event nobody answers otherwise leaves no trace.
+	 */
+	| { kind: "offer" }
+	/**
+	 * Set a finished card aside: the store moves its file out of the board, and the record
+	 * itself is unchanged, because the pile its file lies in is the whole of the state.
+	 */
+	| { kind: "archive" }
 	| { kind: "drop" };
 
 /** What an operation did: the new card, or the reason it was refused. */
@@ -89,6 +107,10 @@ export function createCard(
 		priority: input.priority ?? DEFAULT_PRIORITY,
 		notes: input.note === undefined ? [] : [{ by: actor.label, at: now, text: input.note }],
 		notesDropped: 0,
+		// A card is born in `todo`, and that is a transition like any other: a reader asking
+		// "how long has this been waiting" gets an answer rather than an absence.
+		log: [{ status: "todo", at: now, by: actor.label }],
+		logDropped: 0,
 		rev: 1,
 		createdAt: now,
 		updatedAt: now,
@@ -125,7 +147,7 @@ export function applyOp(card: Card, op: CardOp, actor: Actor, now: number, board
 		case "release":
 			return release(card, actor, now);
 		case "move":
-			return move(card, op.status, actor, now, board);
+			return move(card, op, actor, now, board);
 		case "note":
 			return note(card, op.text, actor, now);
 		case "plan":
@@ -134,6 +156,10 @@ export function applyOp(card: Card, op: CardOp, actor: Actor, now: number, board
 			return edit(card, op, actor, now, board);
 		case "reclaim":
 			return reclaim(card, actor, now);
+		case "offer":
+			return offer(card, actor, now, board);
+		case "archive":
+			return archive(card);
 		case "drop":
 			return drop(card, actor, board);
 	}
@@ -145,7 +171,11 @@ function claim(card: Card, actor: Actor, now: number, board: BoardIndex): OpResu
 	if (card.owner !== undefined) return { ok: false, error: heldBy(card) };
 	const waiting = waitingOn(card, board);
 	if (waiting !== undefined) return { ok: false, error: waiting };
-	return { ok: true, card: write(card, actor, now, { status: "doing", owner: ownerOf(actor) }), changed: true };
+	return {
+		ok: true,
+		card: write(card, actor, now, { status: "doing", owner: ownerOf(actor), offeredAt: undefined }),
+		changed: true,
+	};
 }
 
 function assign(card: Card, to: Actor, rawNote: unknown, actor: Actor, now: number, board: BoardIndex): OpResult {
@@ -154,7 +184,7 @@ function assign(card: Card, to: Actor, rawNote: unknown, actor: Actor, now: numb
 	if (holds(card, to) && card.status === "doing") return { ok: true, card, changed: false };
 	const waiting = waitingOn(card, board);
 	if (waiting !== undefined) return { ok: false, error: waiting };
-	const fields: Partial<Card> = { status: "doing", owner: ownerOf(to) };
+	const fields: Partial<Card> = { status: "doing", owner: ownerOf(to), offeredAt: undefined };
 	if (rawNote !== undefined) {
 		const parsed = normalizeNote(rawNote);
 		if ("error" in parsed) return { ok: false, error: parsed.error };
@@ -172,23 +202,66 @@ function release(card: Card, actor: Actor, now: number): OpResult {
 	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be released.` };
 	if (card.owner === undefined) return { ok: false, error: `${cardRef(card.id)} is not claimed.` };
 	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Release is the owner's decision.` };
-	return { ok: true, card: write(card, actor, now, { status: "todo", owner: undefined }), changed: true };
+	return {
+		ok: true,
+		card: write(card, actor, now, { status: "todo", owner: undefined, offeredAt: undefined }),
+		changed: true,
+	};
 }
 
-function move(card: Card, status: Exclude<CardStatus, "todo">, actor: Actor, now: number, board: BoardIndex): OpResult {
+function move(
+	card: Card,
+	op: Extract<CardOp, { kind: "move" }>,
+	actor: Actor,
+	now: number,
+	board: BoardIndex,
+): OpResult {
+	const status = op.status;
 	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be moved.` };
 	if (card.owner === undefined) {
 		return { ok: false, error: `${cardRef(card.id)} is unclaimed; claim it before moving it to ${status}.` };
 	}
 	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Only its owner can move it.` };
-	if (card.status === status) return { ok: true, card, changed: false };
+	// A block's reason is checked before the no-op: a caller that repeats a move with a new
+	// sentence meant to change it, and a refusal is clearer than a silent nothing.
+	let blockedBy: string | undefined;
+	if (status === "blocked" && op.blockedBy !== undefined) {
+		const parsed = normalizeBlockedBy(op.blockedBy);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		blockedBy = parsed.blockedBy;
+	}
+	if (card.status === status && blockedBy === undefined) return { ok: true, card, changed: false };
 	// Parking is what a link is for, so only the two lanes that put a card back in flight
 	// are gated: a card that waits may be blocked, it may not be taken or finished.
 	if (status !== "blocked") {
 		const waiting = waitingOn(card, board);
 		if (waiting !== undefined) return { ok: false, error: waiting };
 	}
-	return { ok: true, card: write(card, actor, now, { status }), changed: true };
+	return { ok: true, card: write(card, actor, now, laneFields(status, blockedBy, op, now)), changed: true };
+}
+
+/**
+ * The fields one lane change writes.
+ *
+ * `blockedBy` belongs to `blocked` alone: a card that leaves for `doing` or `done` has
+ * had its decision or stopped needing one, and a stale sentence would be read as a
+ * current one. `landed` belongs to `done` alone, and only when the caller could name a
+ * commit — a board outside git still finishes cards, it just cannot say with what.
+ */
+function laneFields(
+	status: Exclude<CardStatus, "todo">,
+	blockedBy: string | undefined,
+	op: Extract<CardOp, { kind: "move" }>,
+	now: number,
+): Partial<Card> {
+	const fields: Partial<Card> = { status };
+	if (status === "blocked") {
+		if (blockedBy !== undefined) fields.blockedBy = blockedBy;
+	} else {
+		fields.blockedBy = undefined;
+	}
+	if (status === "done" && op.landed !== undefined) fields.landed = { commit: op.landed.commit, at: now };
+	return fields;
 }
 
 function note(card: Card, raw: unknown, actor: Actor, now: number): OpResult {
@@ -207,6 +280,16 @@ function appendNote(card: Card, actor: Actor, now: number, text: string): Pick<C
 	};
 }
 
+/** A card's log after one more transition, with the oldest dropped and counted. */
+function appendTransition(card: Card, status: CardStatus, actor: Actor, now: number): Pick<Card, "log" | "logDropped"> {
+	const log = [...(card.log ?? []), { status, at: now, by: actor.label }];
+	const overflow = Math.max(0, log.length - MAX_LOG);
+	return {
+		log: overflow === 0 ? log : log.slice(overflow),
+		logDropped: (card.logDropped ?? 0) + overflow,
+	};
+}
+
 function plan(card: Card, raw: unknown, actor: Actor, now: number): OpResult {
 	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; its plan cannot change.` };
 	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Only its owner records a plan.` };
@@ -262,10 +345,45 @@ function edit(
 	return { ok: true, card: write(card, actor, now, fields), changed: true };
 }
 
+/**
+ * Record that the card was offered to the team, and nobody has taken it.
+ *
+ * The same preconditions a claim would meet, because the offer asks a peer to claim: a
+ * held card, a finished one, or one waiting on unfinished work is refused before anything
+ * is broadcast. Re-offering refreshes the age rather than refusing as a no-op — a lead
+ * who offers again is asking again, and the age is the record of when they last did.
+ */
+function offer(card: Card, actor: Actor, now: number, board: BoardIndex): OpResult {
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be offered.` };
+	if (card.owner !== undefined) return { ok: false, error: heldBy(card) };
+	const waiting = waitingOn(card, board);
+	if (waiting !== undefined) return { ok: false, error: waiting };
+	return { ok: true, card: write(card, actor, now, { offeredAt: now }), changed: true };
+}
+
 function reclaim(card: Card, actor: Actor, now: number): OpResult {
 	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; there is nothing to reclaim.` };
 	if (card.owner === undefined) return { ok: false, error: `${cardRef(card.id)} has no owner to reclaim.` };
-	return { ok: true, card: write(card, actor, now, { status: "todo", owner: undefined }), changed: true };
+	return {
+		ok: true,
+		card: write(card, actor, now, { status: "todo", owner: undefined, offeredAt: undefined }),
+		changed: true,
+	};
+}
+
+/**
+ * Set a finished card aside, out of the board and into the archive beside it.
+ *
+ * Only a finished card leaves this way: `done` is terminal, and a card still in flight
+ * has an owner, a plan, and a decision in it. No field moves and no transition is
+ * appended — the record is unchanged, and what changed is which pile its file lies in,
+ * which is the store's write. `changed` is still true, because the board lost a card.
+ */
+function archive(card: Card): OpResult {
+	if (card.status !== "done") {
+		return { ok: false, error: `${cardRef(card.id)} is in ${card.status}; only a finished card can be archived.` };
+	}
+	return { ok: true, card, changed: true };
 }
 
 function drop(card: Card, actor: Actor, board: BoardIndex): OpResult {
@@ -283,13 +401,28 @@ function sameList(left: readonly string[], right: readonly string[]): boolean {
 	return left.length === right.length && left.every((entry, index) => entry === right[index]);
 }
 
-/** A card with `fields` applied and its write marks moved. */
+/**
+ * A card with `fields` applied and its write marks moved.
+ *
+ * This is the one place a lane change is observed, because it is the one place every
+ * transition ends: a note, a plan, or an edit writes fields and leaves the lane alone,
+ * while a claim, an assign, a release, a reclaim, and a move all name the new one. So
+ * the log is appended from here rather than from each operation, and an operation added
+ * later cannot forget it.
+ */
 function write(card: Card, actor: Actor, now: number, fields: Partial<Card>): Card {
-	const next: Card = { ...card, ...fields, rev: card.rev + 1, updatedAt: now, by: actor.label };
+	const status = fields.status;
+	const transition =
+		status !== undefined && status !== card.status ? appendTransition(card, status, actor, now) : undefined;
+	const next: Card = { ...card, ...fields, ...transition, rev: card.rev + 1, updatedAt: now, by: actor.label };
 	// `owner: undefined` must clear the field rather than store a key holding it, so a
 	// released card reads back exactly like one that was never claimed. Only an
 	// explicit `owner` in `fields` may delete it: every other write keeps the holder.
 	if ("owner" in fields && fields.owner === undefined) delete next.owner;
+	// The same for the block: a card that left `blocked` has no reason, and a key holding
+	// undefined would be one more shape for a reader to know about.
+	if ("blockedBy" in fields && fields.blockedBy === undefined) delete next.blockedBy;
+	if ("offeredAt" in fields && fields.offeredAt === undefined) delete next.offeredAt;
 	return next;
 }
 

package/lib/board/store.ts

@@ -20,8 +20,10 @@
  * a board is tens of files, so the read is cheaper than the second source of truth a
  * cached index would be.
  *
- * Nothing prunes. A `done` card is history, the page shows the store's size, and
- * `drop` is the only deletion.
+ * Nothing prunes by itself. `cards/` is the board and `archive/` is where a finished card
+ * is set aside by `archive` — its file moved rather than rewritten, so the record is
+ * unchanged and the board stops paying for it — and `ended/` keeps the record of a `drop`
+ * alone. The page shows the store's size, and `drop` is the only deletion.
  */
 
 import { link, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
@@ -31,7 +33,16 @@ import { resolveEffectiveCwd } from "../env.ts";
 import { hasErrorCode, messageOf } from "../errors.ts";
 import { shortenPath } from "../format.ts";
 import { repoKeyFor } from "../repo-key.ts";
-import { type Card, CARD_STATUSES, cardRef, isCard, type Priority, priorityRank } from "./card.ts";
+import {
+	type Card,
+	CARD_STATUSES,
+	CARD_VERSION,
+	cardRef,
+	type EndedCard,
+	isCard,
+	type Priority,
+	priorityRank,
+} from "./card.ts";
 import { indexOf } from "./links.ts";
 import { type Actor, applyOp, type CardOp, createCard } from "./rules.ts";
 
@@ -41,6 +52,17 @@ export const BOARD_DIR_NAME = "board";
 /** The subdirectory one board's cards live in. */
 export const CARDS_DIR_NAME = "cards";
 
+/** The subdirectory a dropped card leaves its record in. */
+export const ENDED_DIR_NAME = "ended";
+
+/**
+ * The subdirectory a finished card is set aside in.
+ *
+ * A second pile, not a second state: the file is moved here unchanged, so its notes, plan,
+ * and landed commit stay readable, and the board's own reads stop opening it.
+ */
+export const ARCHIVE_DIR_NAME = "archive";
+
 /** Card files are the user's work; only their owner reads them. */
 const FILE_MODE = 0o600;
 
@@ -64,25 +86,52 @@ export interface CreateInput {
 
 /** What a mutation did, or why it was refused. */
 export type MutateResult =
-	| { ok: true; card: Card; changed: boolean; dropped: boolean }
+	| { ok: true; card: Card; changed: boolean; dropped: boolean; archived: boolean }
 	| { ok: false; error: string; card?: Card };
 
+/**
+ * A card file the reader refused, and why.
+ *
+ * The lanes skip these, so without this the board reads as if they were never there:
+ * "nobody has planned anything" instead of "this build cannot read your work".
+ */
+export interface Skip {
+	/** The file name, e.g. `0042.json`. */
+	file: string;
+	/** The id the file name spells, when it spells one, so a caller can match a refusal. */
+	id?: string;
+	/** What is wrong, phrased for a reader: `bad JSON`, `version 2`. */
+	why: string;
+}
+
 /** One repository's board, as the runtime, the router, and the tool use it. */
 export interface BoardStore {
 	/** The board's own directory, for `where` and for a refusal that names it. */
 	readonly dir: string;
 	/** Create the directories and sweep a temp file a dead process left. */
 	ensure(): Promise<void>;
-	/** Every card, in lane order: todo, doing, blocked, done. */
+	/** Every card on the board, in lane order: todo, doing, blocked, done. */
 	list(): Promise<Card[]>;
-	/** One card by its unpadded id, or undefined when it is not there. */
+	/**
+	 * The cards set aside in the archive, in the same order, and the files there this build
+	 * refused. Read only when a caller asks: no other read opens the pile.
+	 */
+	archived(): Promise<{ cards: Card[]; skipped: Skip[] }>;
+	/** How many card files the archive holds, without opening one: the count a listing prints. */
+	archivedCount(): Promise<number>;
+	/** One card by its unpadded id, from whichever pile its file lies in. */
 	read(id: string): Promise<Card | undefined>;
 	/** Add a card, allocating the next id. */
 	create(input: CreateInput, actor: Actor, now: number): Promise<Card>;
-	/** Apply one operation, re-checking it if the card changed while it was read. */
+	/**
+	 * Apply one operation, re-checking it if the card changed while it was read. A card is
+	 * found in whichever pile it lies in, and written back to that one.
+	 */
 	mutate(id: string, op: CardOp, actor: Actor, now: number): Promise<MutateResult>;
-	/** Bytes the store occupies on disk. */
+	/** Bytes the board's cards occupy on disk; the archive is not counted. */
 	bytes(): Promise<number>;
+	/** Card files this build refused to read, and why. */
+	skipped(): Promise<Skip[]>;
 	/** A short, user-facing name for the directory. */
 	where(): string;
 }
@@ -109,31 +158,64 @@ export async function openBoard(
 /** Build a store over one directory. Exported for tests and for a second backend. */
 export function createStore(dir: string): BoardStore {
 	const cardsDir = join(dir, CARDS_DIR_NAME);
+	const endedDir = join(dir, ENDED_DIR_NAME);
+	const archiveDir = join(dir, ARCHIVE_DIR_NAME);
 
 	const ensure = async (): Promise<void> => {
 		await mkdir(cardsDir, { recursive: true, mode: DIR_MODE });
 		await sweepTemps(cardsDir);
+		// An archived card that was edited leaves a temp file in its own pile, and a process
+		// that died mid-write there is the same mess as one on the board.
+		await sweepTemps(archiveDir);
 	};
 
-	const list = async (): Promise<Card[]> => {
-		const entries = await readdirSafe(cardsDir);
+	/** Every card file of one pile, read once: what it shows and what it refused. */
+	const scan = async (pileDir: string): Promise<{ cards: Card[]; skipped: Skip[] }> => {
+		const entries = await readdirSafe(pileDir);
 		const cards: Card[] = [];
+		const skipped: Skip[] = [];
 		for (const entry of entries) {
-			const card = await readCardFile(cardsDir, entry);
-			if (card) cards.push(card);
+			const read = await readCardFile(pileDir, entry);
+			if ("card" in read) cards.push(read.card);
+			// Anything that is not a card-named file is not the board's to explain.
+			else if (entry.endsWith(".json")) skipped.push(read.skip);
 		}
-		return sortForLane(cards);
+		// Sorted by file name so two reads of one board say the same thing in the same order.
+		return { cards: sortForLane(cards), skipped: skipped.sort((a, b) => a.file.localeCompare(b.file)) };
 	};
 
-	const read = async (id: string): Promise<Card | undefined> => {
-		return readCardFile(cardsDir, fileNameFor(id));
+	const list = async (): Promise<Card[]> => (await scan(cardsDir)).cards;
+
+	const archived = async (): Promise<{ cards: Card[]; skipped: Skip[] }> => scan(archiveDir);
+
+	// A directory listing and a name pattern, with no file opened: a plain `list` prints this
+	// count so the archive it left out cannot read as history that was deleted.
+	const archivedCount = async (): Promise<number> =>
+		(await readdirSafe(archiveDir)).filter((entry) => CARD_FILE.test(entry)).length;
+
+	const skipped = async (): Promise<Skip[]> => (await scan(cardsDir)).skipped;
+
+	/**
+	 * One card and the pile its file is in, the board first.
+	 *
+	 * A card is where it lies: the archive is not a state a record carries, so every read by
+	 * id has to look in both places, and every write goes back to the one it was read from.
+	 */
+	const locate = async (id: string): Promise<{ card: Card; pile: string } | undefined> => {
+		for (const pile of [cardsDir, archiveDir]) {
+			const result = await readCardFile(pile, fileNameFor(id));
+			if ("card" in result) return { card: result.card, pile };
+		}
+		return undefined;
 	};
 
+	const read = async (id: string): Promise<Card | undefined> => (await locate(id))?.card;
+
 	const create = async (input: CreateInput, actor: Actor, now: number): Promise<Card> => {
 		await ensure();
 		let lastError: unknown;
 		for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
-			const id = await nextCardId(cardsDir);
+			const id = await nextCardId(cardsDir, endedDir, archiveDir);
 			const card = createCard(id, input, actor, now);
 			const temp = tempPath(cardsDir);
 			await writeFile(temp, serialize(card), { mode: FILE_MODE });
@@ -155,22 +237,44 @@ export function createStore(dir: string): BoardStore {
 	const mutate = async (id: string, op: CardOp, actor: Actor, now: number): Promise<MutateResult> => {
 		let changedUnderneath = false;
 		for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
-			const card = await read(id);
-			if (!card) {
+			const found = await locate(id);
+			if (!found) {
+				if (changedUnderneath) return { ok: false, error: `${cardRef(id)} was dropped.` };
+				// A file that is there and refused is not a card that does not exist: the
+				// reader is told which file to look at instead of being sent to add one.
+				const skip = (await scan(cardsDir)).skipped.find((entry) => entry.id === id);
 				return {
 					ok: false,
-					error: changedUnderneath ? `${cardRef(id)} was dropped.` : `${cardRef(id)} does not exist.`,
+					error:
+						skip === undefined
+							? `${cardRef(id)} does not exist.`
+							: `${cardRef(id)} is there and this build cannot read it (${skip.file}: ${skip.why}).`,
 				};
 			}
+			const { card, pile } = found;
 			// The preconditions are checked against the card as it is *now*, and against the
 			// board as it is now, so an operation re-applied to a card that changed is refused
 			// rather than forced.
 			const result = applyOp(card, op, actor, now, indexOf(await list()));
 			if (!result.ok) return { ok: false, error: result.error, card };
-			if (!result.changed) return { ok: true, card: result.card, changed: false, dropped: false };
+			if (!result.changed) {
+				return { ok: true, card: result.card, changed: false, dropped: false, archived: false };
+			}
 			if (op.kind === "drop") {
-				await rm(join(cardsDir, fileNameFor(id)), { force: true });
-				return { ok: true, card: result.card, changed: true, dropped: true };
+				// The record lands first: a crash between the two leaves a card that still
+				// exists with a note explaining it, never a card that is gone unexplained.
+				await writeEnded(endedDir, result.card, actor, now);
+				await rm(join(pile, fileNameFor(id)), { force: true });
+				return { ok: true, card: result.card, changed: true, dropped: true, archived: false };
+			}
+			if (op.kind === "archive") {
+				// A card the board does not hold is already aside, and two sessions asking at
+				// once are one move rather than a second one.
+				if (pile === archiveDir) {
+					return { ok: true, card: result.card, changed: false, dropped: false, archived: false };
+				}
+				await moveCard(cardsDir, archiveDir, id);
+				return { ok: true, card: result.card, changed: true, dropped: false, archived: true };
 			}
 			// Last look before the rename: a writer that landed in between is the
 			// re-read the next pass applies against.
@@ -179,8 +283,8 @@ export function createStore(dir: string): BoardStore {
 				changedUnderneath = true;
 				continue;
 			}
-			await writeCardFile(cardsDir, id, result.card);
-			return { ok: true, card: result.card, changed: true, dropped: false };
+			await writeCardFile(pile, id, result.card);
+			return { ok: true, card: result.card, changed: true, dropped: false, archived: false };
 		}
 		return {
 			ok: false,
@@ -200,7 +304,19 @@ export function createStore(dir: string): BoardStore {
 		return total;
 	};
 
-	return { dir, ensure, list, read, create, mutate, bytes, where: () => shortenPath(dir) };
+	return {
+		dir,
+		ensure,
+		list,
+		archived,
+		archivedCount,
+		read,
+		create,
+		mutate,
+		bytes,
+		skipped,
+		where: () => shortenPath(dir),
+	};
 }
 
 /** `<id>.json`, zero-padded to four digits so a directory lists in card order. */
@@ -211,58 +327,129 @@ function fileNameFor(id: string): string {
 /** The card files the reader accepts. */
 const CARD_FILE = /^(\d{4,})\.json$/;
 
-/** One card file, or undefined when it is not a card this build trusts. */
-async function readCardFile(cardsDir: string, entry: string): Promise<Card | undefined> {
+/** One card file: the card, or the reason this build refused it. */
+async function readCardFile(pileDir: string, entry: string): Promise<{ card: Card } | { skip: Skip }> {
 	const match = CARD_FILE.exec(entry);
-	if (!match) return undefined;
-	const text = await readFile(join(cardsDir, entry), "utf-8").catch(() => undefined);
-	if (text === undefined) return undefined;
+	if (!match) return { skip: { file: entry, why: "not a card id" } };
+	const id = String(Number(match[1]));
+	const text = await readFile(join(pileDir, entry), "utf-8").catch(() => undefined);
+	if (text === undefined) return { skip: { file: entry, id, why: "cannot be read" } };
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(text);
 	} catch {
-		return undefined;
+		return { skip: { file: entry, id, why: "bad JSON" } };
+	}
+	// A version above this build's is the one refusal a reader can act on: the file was
+	// written by a newer build, so the board is not empty, it is not readable here.
+	const version = typeof parsed === "object" && parsed !== null ? (parsed as { v?: unknown }).v : undefined;
+	if (typeof version === "number" && version !== CARD_VERSION) {
+		return { skip: { file: entry, id, why: `version ${version}` } };
 	}
-	if (!isCard(parsed)) return undefined;
+	if (!isCard(parsed)) return { skip: { file: entry, id, why: "not a card record" } };
 	// The file name is the id's canonical spelling: a padded id inside the record
 	// (or a record moved under another name) is a disagreement, not a card.
-	if (parsed.id !== String(Number(match[1]))) return undefined;
-	return parsed;
+	if (parsed.id !== String(Number(match[1]))) {
+		return { skip: { file: entry, id, why: `names card ${parsed.id}` } };
+	}
+	return { card: parsed };
 }
 
-/** `1`, `2`, `3` … as the highest existing id plus one. */
-async function nextCardId(cardsDir: string): Promise<string> {
-	const entries = await readdirSafe(cardsDir);
+/** The highest id a directory holds, or 0 when it holds none. */
+async function highestId(dir: string): Promise<number> {
+	const entries = await readdirSafe(dir);
 	let highest = 0;
 	for (const entry of entries) {
 		const match = CARD_FILE.exec(entry);
 		if (match) highest = Math.max(highest, Number(match[1]));
 	}
-	return String(highest + 1);
+	return highest;
+}
+
+/**
+ * `1`, `2`, `3` … as the highest id the board has ever used plus one.
+ *
+ * Ended and archived cards count: a dropped card's record keeps its id spent, and an
+ * archived card's file is still named by it, so a note or a handoff that names `#29`
+ * cannot come to mean a different feature tomorrow.
+ */
+async function nextCardId(cardsDir: string, endedDir: string, archiveDir: string): Promise<string> {
+	return String(Math.max(await highestId(cardsDir), await highestId(endedDir), await highestId(archiveDir)) + 1);
+}
+
+/**
+ * Write the record of a card that has ended.
+ *
+ * Exclusive like a create, so the id ends once: a retry that finds the record already
+ * there is the same end, not a second one.
+ */
+async function writeEnded(endedDir: string, card: Card, actor: Actor, now: number): Promise<void> {
+	await mkdir(endedDir, { recursive: true, mode: DIR_MODE });
+	const ended: EndedCard = {
+		v: 1,
+		id: card.id,
+		title: card.title,
+		status: card.status,
+		by: actor.label,
+		...(card.owner === undefined ? {} : { owner: card.owner }),
+		at: now,
+		why: "dropped",
+	};
+	const temp = tempPath(endedDir);
+	await writeFile(temp, serialize(ended), { mode: FILE_MODE });
+	try {
+		await link(temp, join(endedDir, fileNameFor(card.id)));
+	} catch (error) {
+		if (!hasErrorCode(error, "EEXIST")) throw error;
+	} finally {
+		await rm(temp, { force: true });
+	}
+}
+
+/**
+ * Move one card's file into the archive.
+ *
+ * A rename, not a write: the record does not change, and the pile it lies in is the whole
+ * of what an archive means.
+ */
+async function moveCard(from: string, to: string, id: string): Promise<void> {
+	await mkdir(to, { recursive: true, mode: DIR_MODE });
+	await renameInto(join(from, fileNameFor(id)), join(to, fileNameFor(id)));
+}
+
+/**
+ * Rename one file over or onto another, with the fallback this platform needs.
+ *
+ * Windows refuses a rename onto an open file, so removing the target first is the only
+ * way through there; every caller has already read what it is replacing, which is what
+ * bounds what the removal can lose.
+ */
+async function renameInto(source: string, target: string): Promise<void> {
+	try {
+		await rename(source, target);
+	} catch (error) {
+		if (!hasErrorCode(error, "EPERM") && !hasErrorCode(error, "EACCES") && !hasErrorCode(error, "EEXIST")) throw error;
+		await rm(target, { force: true });
+		await rename(source, target);
+	}
 }
 
 /** Write one card: a temp file in the same directory, then a rename over the old one. */
-async function writeCardFile(cardsDir: string, id: string, card: Card): Promise<void> {
-	const temp = tempPath(cardsDir);
+async function writeCardFile(dir: string, id: string, card: Card): Promise<void> {
+	const temp = tempPath(dir);
 	await writeFile(temp, serialize(card), { mode: FILE_MODE });
-	const target = join(cardsDir, fileNameFor(id));
 	try {
-		await rename(temp, target);
+		await renameInto(temp, join(dir, fileNameFor(id)));
 	} catch (error) {
-		// Windows refuses a rename onto an open file; removing first is the fallback
-		// the platform needs, and the read above still bounds what can be lost.
-		if (!hasErrorCode(error, "EPERM") && !hasErrorCode(error, "EACCES") && !hasErrorCode(error, "EEXIST")) {
-			await rm(temp, { force: true });
-			throw error;
-		}
-		await rm(target, { force: true });
-		await rename(temp, target);
+		await rm(temp, { force: true });
+		throw error;
 	}
 }
 
 /** One card's bytes, ending in a newline so the file reads well in an editor. */
-function serialize(card: Card): string {
-	return `${JSON.stringify(card, null, "\t")}\n`;
+/** One record as the bytes a file holds: tab-indented JSON with a closing newline. */
+function serialize(record: Card | EndedCard): string {
+	return `${JSON.stringify(record, null, "\t")}\n`;
 }
 
 /** A temp path in the cards directory: never matched by the reader's own pattern. */