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

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);

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/session.ts

@@ -3,9 +3,14 @@
  *
  * One store per working directory, opened on first use and kept for the session:
  * a tool call is frequent and the repository lookup shells out to git, so the
- * answer is remembered per `cwd`. The identity is the same pair a card records —
- * the session id Pi knows, and the label `session-bus` would settle by default —
- * which is why the board can name its owner without reading the bus.
+ * answer is remembered per `cwd`. The identity is the same pair a card records — the
+ * session id Pi knows, and the team name derived from it — which is why the board can
+ * name its owner without reading the bus, and why the name survives a rename.
+ *
+ * One session per *host*, not one per extension: Pi loads `board` and `team` with
+ * separate module caches, so two sessions would mean the seat `/board` sets is
+ * invisible to every write `team` makes, and one session would name its own cards
+ * two ways.
  *
  * The store and its cache live in this closure, not in a module variable: Pi loads
  * each extension with an isolated module cache, so module state would be one copy
@@ -15,16 +20,39 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { basename, join } from "node:path";
-import { defaultLabel, sessionNameOf } from "../session-label.ts";
+import { agentLabel, defaultLabel, sessionNameOf } from "../session-label.ts";
 import { BUS_DIR_NAME } from "../session-roster.ts";
+import type { JoinResult } from "../session-tool.ts";
 import type { Actor } from "./rules.ts";
 import { type BoardStore, openBoard } from "./store.ts";
 
+/**
+ * Where this session stands on the team, as the one place that keeps it.
+ *
+ * Two surfaces ask: `board` when it joins on the page or on a claim, and `team` for
+ * `/team join`. It is a standing rather than a flag because both need to *say* what
+ * happened — `/board status` names the label and whether mail is listened for — and
+ * because a failure has to be asked again while a success must not be. A failure is
+ * kept so a line can say why, and `ok` is what a caller reads to decide.
+ */
+export interface TeamStanding {
+	/** What the last join did, or undefined when this session has not asked. */
+	last(): JoinResult | undefined;
+	/** Record what an attempt did; a failed one is kept, and asked again. */
+	record(result: JoinResult): void;
+}
+
 /** What a tool, a page, and a round need from the session, without any of them owning it. */
 export interface BoardSession {
 	/** The board for `cwd`'s repository. */
 	store(cwd: string): Promise<BoardStore>;
-	/** The session a write is made as. */
+	/**
+	 * The session a write is made as: its team name, and the id a card keeps.
+	 *
+	 * The label is the seat while this session serves the page, else `team-agent-<id>`,
+	 * else — on a host that reports no id — the readable chain. One name on every
+	 * surface is the point: the card, the bus record, and the roster say the same word.
+	 */
 	who(ctx: ExtensionContext, cwd: string): Actor;
 	/** The clock, so a test drives a deadline instead of waiting on one. */
 	now(): number;
@@ -36,12 +64,23 @@ export interface BoardSession {
 	 * with `session-bus` unloaded.
 	 */
 	busDir(cwd: string): Promise<string>;
-	/** Whether this session has already joined the team, so a card write joins once. */
-	joined(): boolean;
-	/** Record that the join landed; a failed one leaves this false so the next write asks. */
-	markJoined(): void;
+	/** The seat this session serves the page as, or undefined when it is not serving. */
+	serving(): string | undefined;
+	/** Serve the page under `seat`, or stand it down when the page stops. */
+	serve(seat: string | undefined): void;
+	/** Where this session stands on the team, so a claim joins once and status can say. */
+	team: TeamStanding;
 }
 
+/**
+ * The part of a session a command needs: what it is called, and where it stands.
+ *
+ * `/board` joins, sets the seat, and reports the standing; it never opens a store or
+ * reads the bus, so a command takes this much and no more. A test drives it with four
+ * stand-ins instead of a whole session with a temp agent directory.
+ */
+export type BoardTeam = Pick<BoardSession, "who" | "serving" | "serve" | "team">;
+
 /** Test seams and the one place a caller may redirect the store. */
 export interface BoardSessionOptions {
 	now?: () => number;
@@ -49,16 +88,32 @@ export interface BoardSessionOptions {
 }
 
 /**
- * Build the session around one extension's `pi`.
+ * The key one host's session is kept under.
  *
- * Shared by `board` and `team`: both work on the same store and must name a write
- * as the same session, and two copies are how a card's owner label drifts from the
- * label the board writes.
+ * `Symbol.for` is the global registry, so the copy of this module in `board`'s cache
+ * and the copy in `team`'s agree on the key — a plain `Symbol()` would be two keys on
+ * one host, which is the drift this reuse exists to stop.
+ */
+const SESSION_KEY = Symbol.for("@gavin-hu/my-pi-agent/board-session");
+
+/** A host with this module's key on it. */
+type BoardHost = ExtensionAPI & { [SESSION_KEY]?: BoardSession };
+
+/**
+ * The session around one host, built on the first call and shared after it.
+ *
+ * `board` and `team` both work on the same store and must name a write as the same
+ * session, so the first caller's options are the ones built: a second extension joins
+ * the session that exists rather than opening a second one beside it.
  */
 export function openBoardSession(pi: ExtensionAPI, options: BoardSessionOptions = {}): BoardSession {
+	const host = pi as BoardHost;
+	const shared = host[SESSION_KEY];
+	if (shared !== undefined) return shared;
 	const stores = new Map<string, Promise<BoardStore>>();
 	const busDirs = new Map<string, Promise<string>>();
-	let teamJoined = false;
+	let seat: string | undefined;
+	let standing: JoinResult | undefined;
 	const agentDir = options.agentDir;
 	const session: BoardSession = {
 		store(cwd) {
@@ -70,7 +125,11 @@ export function openBoardSession(pi: ExtensionAPI, options: BoardSessionOptions
 		},
 		who(ctx, cwd) {
 			const id = sessionIdOf(ctx);
-			const label = defaultLabel(sessionNameOf(ctx), cwd, id ?? "session");
+			// The seat is a role and the agent name is derived from the id, so neither moves
+			// when a user renames the session — which is what keeps a card's owner readable
+			// against the roster a year later. A host that reports no id has nothing to derive
+			// from, so it keeps the bus's own readable chain.
+			const label = seat ?? (id === undefined ? defaultLabel(sessionNameOf(ctx), cwd) : agentLabel(id));
 			return id === undefined ? { label } : { id, label };
 		},
 		now: options.now ?? Date.now,
@@ -86,11 +145,18 @@ export function openBoardSession(pi: ExtensionAPI, options: BoardSessionOptions
 			busDirs.set(cwd, resolved);
 			return resolved;
 		},
-		joined: () => teamJoined,
-		markJoined: () => {
-			teamJoined = true;
+		serving: () => seat,
+		serve: (label) => {
+			seat = label;
+		},
+		team: {
+			last: () => standing,
+			record: (result) => {
+				standing = result;
+			},
 		},
 	};
+	host[SESSION_KEY] = session;
 	return session;
 }