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

package/extensions/session-bus/store.ts

@@ -47,7 +47,13 @@ export interface BusStore {
 	releaseAll(owner: string): Promise<string[]>;
 	prune(input: {
 		now: number;
+		/** The sessions known to be live when the caller read the bus. */
 		activeIds: ReadonlySet<string>;
+		/**
+		 * Records whose process the caller found gone: they keep their row until their
+		 * heartbeat ages out, and own no path and no mail in the meantime.
+		 */
+		goneIds?: ReadonlySet<string>;
 		sessionTtlMs: number;
 		messageTtlMs: number;
 	}): Promise<void>;
@@ -85,6 +91,7 @@ function isSession(value: unknown): value is SessionRecord {
 		typeof entry.mode === "string" &&
 		typeof entry.startedAt === "number" &&
 		typeof entry.lastSeen === "number" &&
+		(entry.startToken === undefined || typeof entry.startToken === "string") &&
 		(entry.watching === undefined || isWatchingState(entry.watching))
 	);
 }
@@ -335,16 +342,21 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 			return released;
 		},
 
-		async prune({ now: at, activeIds, sessionTtlMs, messageTtlMs }) {
+		async prune({ now: at, activeIds, goneIds, sessionTtlMs, messageTtlMs }) {
 			// The caller's set can lag: a peer that joined and claimed since that read is
 			// live on disk, and its claims are its own. This read is the answer, so the
-			// set only adds to what it found rather than deciding who survives.
+			// set only adds to what it found rather than deciding who survives — except for
+			// a record whose process is gone, which the caller knows and the file cannot.
+			// That record keeps its row until the heartbeat ages out and owns nothing.
 			const live = new Set(activeIds);
+			const gone = new Set(goneIds ?? []);
 			for (const session of await readSessions()) {
 				if (at - session.lastSeen > sessionTtlMs) {
 					await rm(sessionFile(session.id), { force: true });
 					await dropIfEmpty(inboxDir(session.id));
 					live.delete(session.id);
+				} else if (gone.has(session.id)) {
+					live.delete(session.id);
 				} else {
 					live.add(session.id);
 				}

package/extensions/session-bus/tui.ts

@@ -96,7 +96,7 @@ function boardKey(board: BoardSnapshot | undefined): string {
 	return [
 		...board.status.sessions.map(
 			(session) =>
-				`${session.id}:${session.label}:${session.unread}:${session.lastSeen}:${session.mode}:${session.cwd}`,
+				`${session.id}:${session.label}:${session.unread}:${session.lastSeen}:${session.mode}:${session.cwd}:${session.state}`,
 		),
 		...board.status.claims.map((claim) => `${claim.path}:${claim.owner}:${claim.ownerLabel}:${claim.at}`),
 		board.status.watching ? `${board.status.watching.armed}:${board.status.watching.wake}` : "",

package/extensions/session-bus/types.ts

@@ -5,6 +5,7 @@
  * `store.ts` and the lifecycle in `runtime.ts`.
  */
 
+import type { RosterState } from "../../lib/session-roster.ts";
 import type { MessageKind, SessionMode } from "./protocol.ts";
 
 /** One registered Pi session. */
@@ -12,6 +13,14 @@ export interface SessionRecord {
 	id: string;
 	label: string;
 	pid: number;
+	/**
+	 * That process's start time, when the host can name one.
+	 *
+	 * It is what tells the record's process apart from an unrelated one that has since
+	 * been given the same pid, so `gone` does not have to wait for the heartbeat to age.
+	 * Absent on a platform without `ps`, and on a record written before this existed.
+	 */
+	startToken?: string;
 	/** Working directory of the session; the worktree root when there is one. */
 	cwd: string;
 	/** Repository root the session belongs to, for relative claims. */
@@ -57,7 +66,7 @@ export interface SessionStatus {
 	me: { id: string; label: string };
 	/** False while this session has only read the bus: it joins by naming itself. */
 	onBus: boolean;
-	sessions: Array<SessionRecord & { unread: number }>;
+	sessions: Array<SessionRecord & { unread: number; state: RosterState }>;
 	claims: ClaimRecord[];
 	/** Present only when this session armed its inbox watch. */
 	watching?: { armed: boolean; wake: boolean };

package/extensions/subagent/commands.ts

@@ -7,6 +7,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { planModeRefusal } from "../../lib/plan-entry.ts";
 import { isPlanModeEnabled } from "../../lib/plan-state.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import type { BackgroundRuntime } from "./background.ts";
@@ -20,7 +21,7 @@ async function openAgents(
 	ctx: ExtensionCommandContext,
 ): Promise<void> {
 	if (isPlanModeEnabled(ctx.sessionManager.getBranch())) {
-		ctx.ui.notify("Plan mode is read-only. Approve the plan before managing background runs.", "warning");
+		ctx.ui.notify(planModeRefusal("managing background runs"), "warning");
 		return;
 	}
 

package/extensions/team/commands.ts

@@ -3,13 +3,13 @@
  *
  * The Team tab is the same round with a mouse; a lead reading a TUI should not have to
  * open a browser to see what needs a decision, so the command prints the rollup the
- * tool returns and one line saying who is live. It reads the cards and the bus's records
- * and writes nothing: acting on the round is `team`'s tool (`assign`, `reclaim`) or
- * `board`'s.
+ * tool returns, the work a dead owner left behind, and one line saying who is live. It
+ * reads the cards and the bus's records and writes nothing: acting on the round is
+ * `team`'s tool (`assign`, `reclaim`) or `board`'s.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { Card } from "../../lib/board/card.ts";
+import { type Card, cardRef } from "../../lib/board/card.ts";
 import { buildRound } from "../../lib/board/round.ts";
 import { formatRound, plural } from "../../lib/board/round-text.ts";
 import type { BoardSession } from "../../lib/board/session.ts";
@@ -77,26 +77,58 @@ export function roundText(cards: readonly Card[], now: number, roster?: readonly
 	const round = formatRound(cards, buildRound(cards, now)).split("\n");
 	const shown = round.slice(0, MAX_ROUND_LINES);
 	if (round.length > MAX_ROUND_LINES) shown.push(`… ${plural(round.length - MAX_ROUND_LINES, "line")} more`);
+	for (const line of goneLines(cards, roster, now)) shown.push(line);
 	const who = presenceLine(roster, now);
 	if (who !== undefined) shown.push(who);
 	return shown.join("\n");
 }
 
 /**
- * `live: a, b · not listening: b · quiet: c`, or nothing when nobody is here.
+ * The work a dead owner left behind, as the line that says who takes it.
  *
- * Three facts, and the middle one is the one a lead can act on: a live session that is
+ * One line per gone owner that still holds cards, before the presence line: `gone: b` at
+ * the end of that line says who died, and this one says what to do about it. A card that
+ * waits on another is left to the board, whose rules would refuse the claim anyway.
+ */
+function goneLines(cards: readonly Card[], roster: readonly RosterSession[] | undefined, now: number): string[] {
+	if (roster === undefined) return [];
+	const gone = new Map<string, string>();
+	for (const session of roster) {
+		if (rosterStateOf(session, now) === "gone") gone.set(session.label.toLowerCase(), session.label);
+	}
+	if (gone.size === 0) return [];
+	const byOwner = new Map<string, string[]>();
+	for (const card of cards) {
+		if (card.owner === undefined || card.status === "done") continue;
+		const label = gone.get(card.owner.label.toLowerCase());
+		if (label === undefined) continue;
+		byOwner.set(label, [...(byOwner.get(label) ?? []), cardRef(card.id)]);
+	}
+	return [...byOwner.entries()].map(([label, refs]) => `reclaim ${refs.join(", ")} — ${label} is not running`);
+}
+
+/**
+ * `live: a, b · not listening: b · quiet: c · gone: d`, or nothing when nobody is here.
+ *
+ * Four facts, and the middle one is the one a lead can act on: a live session that is
  * not listening reads mail at its next turn rather than being woken for it. It is only
  * named when its record says so — a session that never wrote the field is not accused of
- * ignoring anything.
+ * ignoring anything. `gone` is the loudest and comes last, because it is the one a lead
+ * answers by reclaiming rather than by waiting.
  */
 function presenceLine(roster: readonly RosterSession[] | undefined, now: number): string | undefined {
 	if (roster === undefined || roster.length === 0) return undefined;
 	const live: string[] = [];
 	const quiet: string[] = [];
+	const dead: string[] = [];
 	const silent: string[] = [];
 	for (const session of roster) {
-		if (rosterStateOf(session, now) !== "live") {
+		const state = rosterStateOf(session, now);
+		if (state === "gone") {
+			dead.push(session.label);
+			continue;
+		}
+		if (state !== "live") {
 			quiet.push(session.label);
 			continue;
 		}
@@ -107,6 +139,7 @@ function presenceLine(roster: readonly RosterSession[] | undefined, now: number)
 		live.length > 0 ? `live: ${live.join(", ")}` : "",
 		silent.length > 0 ? `not listening: ${silent.join(", ")}` : "",
 		quiet.length > 0 ? `quiet: ${quiet.join(", ")}` : "",
+		dead.length > 0 ? `gone: ${dead.join(", ")}` : "",
 	];
 	return parts.filter((part) => part !== "").join(" · ");
 }

package/extensions/team/format.ts

@@ -86,6 +86,20 @@ export function formatOfferFailure(card: Card, reason: string): string {
 	return `${cardRef(card.id)} was not offered: ${reason}\n  The card is unchanged.`;
 }
 
+/**
+ * The broadcast landed and recording the offer then lost a race.
+ *
+ * The peers have an event for a card somebody else has since claimed, moved, or taken
+ * over, so the correction says the offer stands as a message and the card is what the
+ * board now says — not that nothing happened.
+ */
+export function formatRacedOffer(card: Card, reason: string): string {
+	return (
+		`${cardRef(card.id)} was offered, but the card changed before the offer could be recorded: ${reason}\n` +
+		"  The peers have the message; the card is as the board shows it now."
+	);
+}
+
 /**
  * The send landed and the assignment then lost a race.
  *

package/extensions/team/index.ts

@@ -4,7 +4,8 @@
  * `board` owns the cards and never touches the session bus; `team` owns the two
  * actions that need it. `assign` hands a card to a session that is already running
  * and sends it a handoff — dispatch cannot start a peer's turn, and the page and the
- * docs say so — and `reclaim` takes a card back when its owner has gone quiet. Its one
+ * docs say so — and `reclaim` takes a card back when its owner is gone or has gone quiet.
+ * Its one
  * command, `/team`, prints the round the board's Team tab draws, without a browser.
  *
  * Either extension works without the other: `board` is the work list any session

package/extensions/team/tools.ts

@@ -24,17 +24,26 @@ import { failedResult, type ToolFailure, textResult } from "../../lib/tool-resul
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
 import { plural } from "../../lib/board/round-text.ts";
+import { strayField } from "../../lib/stray-fields.ts";
 import { type Dispatch, handoffText, notListening, offerText, ownerFor, peerFor, sessionDispatch } from "./dispatch.ts";
 import {
 	formatHandoff,
 	formatHandoffFailure,
 	formatOffer,
 	formatOfferFailure,
+	formatRacedOffer,
 	formatRacedAssignment,
 	formatReclaimed,
 } from "./format.ts";
 import { TeamParams } from "./schema.ts";
-import { normalizeTeamAction, TEAM_ACTIONS, TEAM_TOOL, type TeamAction, type TeamDetails } from "./types.ts";
+import {
+	ACTION_FIELDS,
+	normalizeTeamAction,
+	TEAM_ACTIONS,
+	TEAM_TOOL,
+	type TeamAction,
+	type TeamDetails,
+} from "./types.ts";
 
 /** The parameters as the schema validates them. */
 type TeamArgs = Static<typeof TeamParams>;
@@ -74,7 +83,8 @@ export function registerTools(pi: ExtensionAPI, session: BoardSession, deps: Tea
 			"Open the board with `/board` or work a card first, so this session and its peers are on the team.",
 			"Offer a card nobody has taken; assign one you mean a particular peer to hold.",
 			"When a result says `Not listening`, say so: the message waits for that peer's next turn.",
-			"Reclaim a card whose owner has gone quiet rather than editing someone else's work.",
+			"Reclaim a card whose owner is gone or has gone quiet rather than editing someone else's work. A " +
+				"`gone:` owner's process is not running, so what it held is anyone's to reclaim.",
 		],
 		parameters: TeamParams,
 		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
@@ -86,6 +96,10 @@ export function registerTools(pi: ExtensionAPI, session: BoardSession, deps: Tea
 			if (!action) {
 				return refusal("assign", `unknown action "${String(args.action)}"; use ${TEAM_ACTIONS.join(" or ")}.`);
 			}
+			// Before the store and before the card: a refused call has done nothing, so it
+			// cannot have read a card or sent a message on its way to the refusal.
+			const stray = strayField(action, args, ACTION_FIELDS);
+			if (stray !== undefined) return refusal(action, stray);
 			const id = normalizeCardId(args.card);
 			if (id === undefined) return refusal(action, `"${String(args.card)}" is not a card id.`);
 			const me = session.who(ctx, ctx.cwd);
@@ -93,7 +107,7 @@ export function registerTools(pi: ExtensionAPI, session: BoardSession, deps: Tea
 				const store = await session.store(ctx.cwd);
 				const now = session.now();
 				if (action === "reclaim") return await reclaimCard(store, me, id, now);
-				if (action === "offer") return await offerCard(store, id, args.note, now, dispatchFor(ctx));
+				if (action === "offer") return await offerCard(store, me, id, args.note, now, dispatchFor(ctx));
 				const to = typeof args.to === "string" ? args.to.trim() : "";
 				if (to === "") return refusal("assign", 'assign needs a peer: pass `to`, e.g. "billing-core".');
 				return await assignCard(store, me, id, to, args.note, now, dispatchFor(ctx));
@@ -180,14 +194,17 @@ async function assignCard(
 const OFFER_CLAIMANT: Actor = { label: "*" };
 
 /**
- * `offer`: check the claim's preconditions, broadcast the card, and write nothing.
+ * `offer`: check the claim's preconditions, broadcast the card, then record the offer.
  *
- * The order matters less here than in `assign`, because nothing is written: a failed
- * broadcast leaves the card exactly as it was, and the first peer to claim is what makes
- * an offer into work. Two peers racing are settled by the store's compare-and-set.
+ * The broadcast comes first and the record second, because a record of an offer nobody
+ * received would be worse than an offer with no record: the card is unchanged by a failed
+ * send, and the first peer to claim is what makes an offer into work. What the record
+ * adds is the one thing an event cannot carry — when it was made — so a lead can tell an
+ * offer nobody took from a card nobody has looked at.
  */
 async function offerCard(
 	store: BoardStore,
+	me: Actor,
 	id: string,
 	note: string | undefined,
 	now: number,
@@ -206,11 +223,15 @@ async function offerCard(
 	} catch (error) {
 		return refusal("offer", formatOfferFailure(card, messageOf(error)), card);
 	}
+	// The peers have the event, so a card that changed underneath is reported as raced
+	// rather than refused: the message is already in their inboxes.
+	const recorded = await store.mutate(id, { kind: "offer" }, me, now);
+	if (!recorded.ok) return refusal("offer", formatRacedOffer(recorded.card ?? card, recorded.error), recorded.card);
 	const peers = await dispatch.peers().catch(() => undefined);
 	const silent = notListening(peers, delivered);
-	return textResult(formatOffer(card, delivered, silent), {
+	return textResult(formatOffer(recorded.card, delivered, silent), {
 		action: "offer",
-		card,
+		card: recorded.card,
 		delivered,
 		...(silent.length === 0 ? {} : { notListening: silent }),
 	});

package/extensions/team/types.ts

@@ -42,6 +42,23 @@ export interface TeamDetails {
 	error?: string;
 }
 
+/**
+ * The fields each action acts on: what a call may carry, per action.
+ *
+ * The parameters are one flat object, so a field is published to every action at once,
+ * and only this table stops one reaching an action that would drop it. `to` is `assign`'s
+ * alone: an `offer` that named a peer was broadcast to every live session instead, and a
+ * `reclaim` that named one took the card back from whoever held it.
+ *
+ * A test holds the other direction — every published parameter but `action` is claimed
+ * here — so a field cannot be published without an action that acts on it.
+ */
+export const ACTION_FIELDS: Record<TeamAction, readonly string[]> = {
+	assign: ["card", "to", "note"],
+	offer: ["card", "note"],
+	reclaim: ["card"],
+};
+
 /** Whether a value is one of the actions, so an unknown one is a refusal and not a crash. */
 export function normalizeTeamAction(raw: unknown): TeamAction | undefined {
 	return typeof raw === "string" && TEAM_ACTIONS.includes(raw as TeamAction) ? (raw as TeamAction) : undefined;

package/extensions/todo/index.ts

@@ -60,7 +60,10 @@ export default function todo(pi: ExtensionAPI) {
 	pi.on("tool_execution_end", (event) => {
 		if (event.isError) return;
 		const annotations = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
-		if (!isMutatingTool(event.toolName, annotations)) return;
+		// The result is the only place a call's own record of what it did survives to this
+		// event, which is why the board's read action is read from here.
+		const details = (event.result as { details?: unknown } | undefined)?.details;
+		if (!isMutatingTool(event.toolName, annotations, details)) return;
 		runtime.noteWork(isFileWrite(event.toolName, annotations));
 	});
 

package/extensions/todo/nudge.ts

@@ -14,7 +14,8 @@
  */
 
 import type { ToolAnnotations } from "@earendil-works/pi-coding-agent";
-import { TODO_TOOL } from "../../lib/tool-names.ts";
+import { isBoardRead } from "../../lib/policy.ts";
+import { BOARD_TOOL, TODO_TOOL } from "../../lib/tool-names.ts";
 import { currentTodo, hasOpenTodos } from "./state.ts";
 import type { Todo } from "./types.ts";
 
@@ -32,9 +33,14 @@ export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit"
  * Whether a finished tool call counts as work for lag detection. The `todo`
  * tool never does (it is the update itself), a known mutator always does, and
  * any other tool counts only when it explicitly declares `readOnlyHint: false`.
+ *
+ * `board` is the one mutator whose read face is provable from what the call
+ * returned: a result whose `details` say `action: "list"` read the cards and changed
+ * nothing, so it counts like every other reader.
  */
-export function isMutatingTool(toolName: string, annotations?: ToolAnnotations): boolean {
+export function isMutatingTool(toolName: string, annotations?: ToolAnnotations, details?: unknown): boolean {
 	if (toolName === TODO_TOOL) return false;
+	if (toolName === BOARD_TOOL && isBoardRead(details)) return false;
 	if (MUTATING_TOOL_NAMES.has(toolName)) return true;
 	return annotations?.readOnlyHint === false;
 }