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

package/lib/http/sink.ts

@@ -22,12 +22,23 @@ export interface EventSink {
 	end(frame?: string): void;
 }
 
+/** Why a server went idle: no stream ever opened, or the last one left. */
+export type IdleReason = "first" | "last";
+
 /** The idle policy a server was given, or none. */
 export interface IdleGrace {
 	/** How long the last stream's departure is held, in ms. */
 	ms: number;
-	/** Called once no stream has been open for `ms`. */
-	onIdle: () => void;
+	/**
+	 * How long a server may stand with no stream ever opened, in ms.
+	 *
+	 * A page opened in a browser that never came up would otherwise hold its port for the
+	 * rest of the session. Omitted, the grace still waits for the first stream, which is
+	 * what a server whose page is opened by hand wants.
+	 */
+	firstMs?: number;
+	/** Called once no stream has been open for the grace that applied. */
+	onIdle: (reason: IdleReason) => void;
 }
 
 /** What the registry needs besides the streams themselves. */
@@ -44,6 +55,8 @@ export interface SinkRegistry {
 	open(response: ServerResponse): EventSink;
 	/** How many streams are open. */
 	size(): number;
+	/** Arm the grace for a server nobody may ever read. Does nothing without `firstMs`. */
+	start(): void;
 	/** End every open stream, because the server is closing. */
 	endAll(): void;
 }
@@ -52,20 +65,24 @@ export function createSinks(deps: SinkDeps = {}): SinkRegistry {
 	const streams = new Set<EventSink>();
 	const timer = deps.timer ?? defaultTimer;
 	let cancelIdle: (() => void) | undefined;
-	/** A grace armed before any page ever attached would close a server nobody opened. */
+	/** A stream has attached at least once, so a departure is one to wait on. */
 	let sawStream = false;
+	/** The server asked for the first grace, so it may go idle without a reader. */
+	let started = false;
 
 	const standDown = (): void => {
 		cancelIdle?.();
 		cancelIdle = undefined;
 	};
 
-	const arm = (): void => {
-		const idle = deps.idle;
-		if (idle === undefined || !sawStream || streams.size > 0 || cancelIdle !== undefined) return;
-		cancelIdle = timer(idle.ms, () => {
+	/** Arm `ms` from now, unless a stream is open or a grace already runs. */
+	const arm = (ms: number, reason: IdleReason): void => {
+		if (deps.idle === undefined || (!started && !sawStream) || streams.size > 0 || cancelIdle !== undefined) return;
+		cancelIdle = timer(ms, () => {
 			cancelIdle = undefined;
-			if (streams.size === 0) deps.idle?.onIdle();
+			// A tab that attached while the grace ran has already stood it down, but a
+			// second look costs nothing and keeps a race from closing a page being read.
+			if (streams.size === 0) deps.idle?.onIdle(reason);
 		});
 	};
 
@@ -74,12 +91,20 @@ export function createSinks(deps: SinkDeps = {}): SinkRegistry {
 			standDown();
 			sawStream = true;
 			const sink = createSink(response, () => {
-				if (streams.delete(sink)) arm();
+				if (!streams.delete(sink)) return;
+				const idle = deps.idle;
+				if (idle !== undefined) arm(idle.ms, "last");
 			});
 			streams.add(sink);
 			return sink;
 		},
 		size: () => streams.size,
+		start() {
+			const idle = deps.idle;
+			if (idle?.firstMs === undefined || started || sawStream) return;
+			started = true;
+			arm(idle.firstMs, "first");
+		},
 		endAll() {
 			standDown();
 			const open = [...streams];

package/lib/plan-entry.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type BusAnswer, requestOverBus } from "./bus-request.ts";
 import { isPlanModeEnabled } from "./plan-state.ts";
 import { PLAN_ENTER_TOOL } from "./tool-names.ts";
 
@@ -41,12 +42,23 @@ export const PLAN_CONSENT_SHORT =
 	"Enter read-only plan mode? Writes and mutating tools are disabled until you approve a plan.";
 export const PLAN_CONSENT_SHORT_ZH = "进入只读 plan 模式？批准计划前会禁用写入和修改。";
 
+/**
+ * The refusal a command shows when plan mode forbids what it does.
+ *
+ * Plan mode is read-only, so every extension whose command changes something says so the
+ * same way and names the action it is not doing: one sentence in `lib/`, because five
+ * copies is how the guarantee stops reading as one guarantee.
+ */
+export function planModeRefusal(action: string): string {
+	return `Plan mode is read-only. Approve the plan before ${action}.`;
+}
+
 /** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
 export interface PlanEnterRequest {
 	/** The caller's context; `plan` uses it for the footer status. */
 	ctx: ExtensionContext;
-	/** Called once, synchronously, with whether plan mode is on. */
-	respond(entered: boolean): void;
+	/** Claimed once, with whether plan mode is on; the caller settles on that claim. */
+	respond(entered: BusAnswer<boolean>): void;
 }
 
 /**
@@ -54,8 +66,8 @@ export interface PlanEnterRequest {
  *
  * Resolves `true` without asking when the branch is already planning, and
  * `false` when the `plan` tool is not registered — so `goal` loaded alone keeps
- * working and nothing waits on a listener that is not there. The listener answers
- * synchronously; the microtask is the fallback that guarantees resolution.
+ * working and nothing waits on a listener that is not there. The listener claims
+ * synchronously; the shared handshake is what guarantees a resolution.
  */
 export function requestPlanMode(
 	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
@@ -63,14 +75,9 @@ export function requestPlanMode(
 ): Promise<boolean> {
 	if (isPlanModeEnabled(ctx.sessionManager.getBranch())) return Promise.resolve(true);
 	if (!pi.getAllTools().some((tool) => tool.name === PLAN_ENTER_TOOL)) return Promise.resolve(false);
-	return new Promise<boolean>((resolve) => {
-		let settled = false;
-		const respond = (entered: boolean): void => {
-			if (settled) return;
-			settled = true;
-			resolve(entered);
-		};
-		pi.events.emit(PLAN_ENTER_REQUEST, { ctx, respond } satisfies PlanEnterRequest);
-		queueMicrotask(() => respond(false));
+	return requestOverBus<boolean, PlanEnterRequest>(pi, {
+		channel: PLAN_ENTER_REQUEST,
+		payload: (respond) => ({ ctx, respond }),
+		unclaimed: () => false,
 	});
 }

package/lib/policy.ts

@@ -15,7 +15,20 @@
  */
 
 import type { ToolAnnotations } from "@earendil-works/pi-coding-agent";
-import { READ_DOC_TOOL } from "./tool-names.ts";
+import { BOARD_READ_ACTION, READ_DOC_TOOL } from "./tool-names.ts";
+
+/**
+ * Whether a call to the `board` tool only reads it.
+ *
+ * The board is one tool over ten actions, so its `readOnlyHint` says "may write" and
+ * cannot answer this. The action can, and it travels in the call's input — and in the
+ * result's `details`, which is all a `tool_execution_end` event carries. Plan mode
+ * asks before the call and the todo nudge after it, so the answer lives here once.
+ */
+export function isBoardRead(call: unknown): boolean {
+	if (typeof call !== "object" || call === null) return false;
+	return (call as { action?: unknown }).action === BOARD_READ_ACTION;
+}
 
 /**
  * Tools that only read the workspace: the built-in structured readers and the

package/lib/requirements.ts

@@ -208,6 +208,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	todo: {},
 	goal: {},
+	serve: { notes: ["Without it `/board`, `/browse`, and `/plan review` refuse, naming it."] },
 	board: {},
 	team: { notes: ["`assign` needs `session-bus` loaded to deliver a handoff; without it the card is untouched."] },
 	check: {
@@ -256,8 +257,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	"file-open": {
 		notes: [
 			"The `/open` command and its notification need an interactive UI; the `open_path` tool works without one.",
-			"Launching the OS handler is best-effort: a launcher that fails to start, or exits non-zero on macOS and Linux, is reported; Windows `explorer` can exit non-zero after a successful open.",
-			"The tool result names the target even when the launch fails.",
+			"Launching the OS handler is best-effort — a launcher that fails to start, or exits non-zero on macOS and Linux, is reported, Windows `explorer` can exit non-zero after a successful open, and the tool result names the target either way.",
 		],
 	},
 	memory: {

package/lib/session-label.ts

@@ -1,12 +1,14 @@
 /**
  * The session label: the one name another session addresses this one by.
  *
- * `session-bus` settles a label for every session — the Pi session name, else the
- * working directory's basename, else the id — and the board records the same name
- * on a card it claims, so the two surfaces agree on who "billing-core" is without
- * the board reading the bus. The rules are here rather than in either extension
- * because a label is a shared vocabulary: it is displayed, it is a send target, and
- * it is stored in a card file that outlives one session.
+ * Two vocabularies share this module, and neither copies the other. `session-bus`
+ * settles its own label for a session that did not ask for one — the Pi session name,
+ * else the working directory's basename, else the id. The board names a session for
+ * the team instead: the page's seat, or `team-agent-` and the id's tail, which is the
+ * same name on every surface and cannot drift when a user renames a session. The rules
+ * are here rather than in either extension because a label is a shared vocabulary: it
+ * is displayed, it is a send target, and it is stored in a card file that outlives one
+ * session.
  *
  * Value-only: no state, no I/O.
  */
@@ -42,12 +44,26 @@ export function shortId(id: string): string {
  * The bus appends a suffix when two live sessions share one; that decision belongs
  * to the registry, so this is only the name a session would pick for itself.
  */
-export function defaultLabel(sessionName: string | undefined, cwd: string, id: string): string {
+export function defaultLabel(sessionName: string | undefined, cwd: string, id = "session"): string {
 	const directory = cwd.split(/[\\/]/).filter(Boolean).at(-1);
 	const base = normalizeLabel(sessionName, normalizeLabel(directory, "session"));
 	return normalizeLabel(base, `session-${shortId(id)}`);
 }
 
+/** The prefix of the team's name for a session that is not the page's seat. */
+export const TEAM_AGENT_PREFIX = "team-agent-";
+
+/**
+ * The team's name for a session: the prefix and the id's tail.
+ *
+ * A team is addressed by id, not by a name a user chose: an id is unique, so two
+ * sessions cannot settle on one name, and a rename cannot strand the card that
+ * recorded it. The seat is the one name that is a role instead.
+ */
+export function agentLabel(id: string): string {
+	return normalizeLabel(`${TEAM_AGENT_PREFIX}${shortId(id)}`, "team-agent");
+}
+
 /**
  * Pi's session name, which is the first choice for a label.
  *

package/lib/session-roster.ts

@@ -9,6 +9,10 @@
  * here once, and `session-bus` imports them, so a layout change cannot land in one
  * copy and not the other.
  *
+ * The rule answers three things, not two: a record whose process is gone is `gone` at
+ * once, rather than aging into `quiet` for ten minutes while the paths it claimed stay
+ * held and the cards it held read `idle`.
+ *
  * A missing directory is an answer, not an error: it means no session has ever
  * joined this repository, and a caller renders that differently from an empty bus.
  *
@@ -18,6 +22,7 @@
 
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { isPidAlive, type LivenessFn, startTokenOf, type StartTokenFn } from "./spawn.ts";
 
 /** The bus directory under the agent dir, `session-bus`. */
 export const BUS_DIR_NAME = "session-bus";
@@ -37,6 +42,16 @@ export interface RosterSession {
 	lastSeen: number;
 	/** Messages waiting in its inbox. */
 	mail: number;
+	/**
+	 * The process that owns the record, when the record names one.
+	 *
+	 * Absent is "cannot tell": a record written before this existed, or by a mode that
+	 * is not a local process, is judged by its heartbeat alone rather than being called
+	 * dead on no evidence.
+	 */
+	pid?: number;
+	/** That process's start time, as the bus wrote it, when the record carries it. */
+	startToken?: string;
 	/**
 	 * Whether the session is listening for mail, when its record says.
 	 *
@@ -46,9 +61,56 @@ export interface RosterSession {
 	watching?: { armed: boolean; wake: boolean };
 }
 
-/** Whether a record's heartbeat is fresh enough to call the session live. */
-export function rosterStateOf(session: RosterSession, now: number, ttlMs = SESSION_TTL_MS): "live" | "quiet" {
-	return now - session.lastSeen <= ttlMs ? "live" : "quiet";
+/** What a record's heartbeat and its process say together. */
+export type RosterState = "live" | "quiet" | "gone";
+
+/**
+ * What a record's heartbeat and its process say together.
+ *
+ * The fields the rule reads, rather than the whole roster row: `session-bus` judges its
+ * own records by the same rule without carrying a `mail` count it never shows.
+ */
+export type RosterFacts = Pick<RosterSession, "lastSeen" | "pid" | "startToken">;
+
+/**
+ * The host facts {@link rosterStateOf} reads, injectable so every branch is testable.
+ *
+ * The token spawns a process, so it is asked for only where liveness cannot decide.
+ */
+export interface RosterSeams {
+	alive?: LivenessFn;
+	token?: StartTokenFn;
+}
+
+/**
+ * What one record says about its session: alive, aged out, or attached to nothing.
+ *
+ * Three answers, in the order they are decided:
+ *
+ * - `gone` — the record names a process and that process is not running. A heartbeat
+ *   written ten seconds before a crash is not evidence the process exists, so death
+ *   outranks a fresh one.
+ * - `live` — the heartbeat is fresh. When the pid is alive too, the start token has not
+ *   been asked for yet: a session that wrote ten seconds ago is not the interesting
+ *   case for pid reuse, and `ps` costs a process.
+ * - `quiet` — the heartbeat has aged. If the pid is alive but its start time is not the
+ *   one the record wrote, the process is somebody else's and the session is `gone`
+ *   after all; a platform that cannot answer the start time leaves it at `quiet`.
+ */
+export function rosterStateOf(
+	session: RosterFacts,
+	now: number,
+	ttlMs = SESSION_TTL_MS,
+	seams: RosterSeams = {},
+): RosterState {
+	const alive = seams.alive ?? isPidAlive;
+	if (session.pid !== undefined && !alive(session.pid)) return "gone";
+	if (now - session.lastSeen <= ttlMs) return "live";
+	if (session.pid !== undefined && session.startToken !== undefined) {
+		const current = (seams.token ?? startTokenOf)(session.pid);
+		if (current !== undefined && current !== session.startToken) return "gone";
+	}
+	return "quiet";
 }
 
 /** The fields this reader trusts; anything else in the file is the bus's business. */
@@ -59,6 +121,11 @@ interface SessionPayload {
 	lastSeen: number;
 }
 
+/** A record's pid, read only when it is the shape a pid has. */
+function pidOf(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
 function isSessionPayload(value: unknown): value is SessionPayload {
 	if (typeof value !== "object" || value === null) return false;
 	const { id, label, mode, lastSeen } = value as Record<string, unknown>;
@@ -117,12 +184,16 @@ export async function readRoster(dir: string): Promise<RosterSession[] | undefin
 		if (!isSessionPayload(parsed)) continue;
 		const { id, label, mode, lastSeen } = parsed;
 		const watching = watchingOf((parsed as { watching?: unknown }).watching);
+		const pid = pidOf((parsed as { pid?: unknown }).pid);
+		const rawToken = (parsed as { startToken?: unknown }).startToken;
 		sessions.push({
 			id,
 			label,
 			mode,
 			lastSeen,
 			mail: await mailCount(dir, name.slice(0, -".json".length)),
+			...(pid === undefined ? {} : { pid }),
+			...(typeof rawToken === "string" && rawToken !== "" ? { startToken: rawToken } : {}),
 			...(watching === undefined ? {} : { watching }),
 		});
 	}

package/lib/session-tool.ts

@@ -22,6 +22,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { type BusAnswer, requestOverBus } from "./bus-request.ts";
 import { messageOf } from "./errors.ts";
 import { watchingOf } from "./session-roster.ts";
 import { SESSION_TOOL } from "./tool-names.ts";
@@ -54,14 +55,29 @@ export type JoinResult = { ok: true; label: string; watching: Watching } | { ok:
 /** EventBus channel on which a caller asks `session-bus` to join the team for it. */
 export const TEAM_JOIN_REQUEST = "my-pi-agent/team-join/request";
 
+/**
+ * What a join asks for.
+ *
+ * `label` is the name to be on the team as; without one the bus settles its own. `name`
+ * is the separate question of whether that label also becomes Pi's session name — the
+ * footer and `/resume` — and it is opt-in, because a join is not a rename: only
+ * `/team join <label>` means "call me this from now on".
+ */
+export interface TeamJoinInput {
+	label?: string;
+	wake?: boolean;
+	listen?: boolean;
+	name?: boolean;
+}
+
 /** What a caller sends on {@link TEAM_JOIN_REQUEST}. */
 export interface TeamJoinRequest {
 	/** The caller's context; the bus starts and names through it. */
 	ctx: ExtensionContext;
 	/** What to join as and how to listen. */
-	input: { label?: string; wake?: boolean; listen?: boolean };
-	/** Called once, when the bus has answered. */
-	respond(result: JoinResult): void;
+	input: TeamJoinInput;
+	/** Claimed once, with what the bus answered; the caller settles on that claim. */
+	respond(result: BusAnswer<JoinResult>): void;
 }
 
 /** What a send did. */
@@ -96,49 +112,49 @@ function nestedMessage(result: { content?: Array<{ type: string; text?: string }
 /**
  * How an extension joins the team, whatever kind of context it is holding.
  *
- * Two extensions ask — `board` when the page opens or a card is worked, `team` for
+ * Two extensions ask — `board` when the page opens or a card is claimed, `team` for
  * `/team join` — and both hold a command or a tool context, so the request is the one
  * transport that works from either.
  */
 export interface TeamJoin {
-	/** Join the team, naming this session when `label` is given. Never throws. */
-	join(ctx: ExtensionContext, label?: string): Promise<JoinResult>;
+	/** Join the team as `input.label` when given. Never throws. */
+	join(ctx: ExtensionContext, input?: TeamJoinInput): Promise<JoinResult>;
 }
 
 /** The production join, bound to one extension's `pi`. */
 export function createTeamJoin(pi: Pick<ExtensionAPI, "events" | "getAllTools">): TeamJoin {
 	return {
-		join: (ctx, label) => join(pi, ctx, label === undefined ? {} : { label }),
+		join: (ctx, input) => join(pi, ctx, input ?? {}),
 	};
 }
 
+/** What a caller is told when there is no bus to join: one sentence on both paths. */
+const NO_BUS = "the session bus is not loaded";
+
 /**
  * Join the team: on the bus, named when a label is given, and listening for mail.
  *
  * One call for all three, because that is one act — see `join` in
  * `extensions/session-bus` — and one transport for both kinds of caller: the request
- * travels on `pi.events` and the bus answers it.
+ * travels on `pi.events` and the bus answers it. Pi's session name is not one of the
+ * three: that is `input.name`, which only a caller meaning to rename asks for.
  *
  * With no bus loaded there is no listener, so the answer is the sentence the caller
  * reports rather than a promise that never settles: the `session` tool's presence is
- * the same check `lib/plan-entry.ts` makes, and the listener always answers.
+ * checked here, and the shared handshake refuses the same way if a bus is loaded but
+ * listening for nothing.
  */
 export async function join(
 	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
 	ctx: ExtensionContext,
-	input: { label?: string; wake?: boolean; listen?: boolean } = {},
+	input: TeamJoinInput = {},
 ): Promise<JoinResult> {
-	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) {
-		return { ok: false, error: "the session bus is not loaded" };
-	}
-	return new Promise<JoinResult>((resolve) => {
-		let settled = false;
-		const respond = (result: JoinResult): void => {
-			if (settled) return;
-			settled = true;
-			resolve(result);
-		};
-		pi.events.emit(TEAM_JOIN_REQUEST, { ctx, input, respond } satisfies TeamJoinRequest);
+	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) return { ok: false, error: NO_BUS };
+	return requestOverBus<JoinResult, TeamJoinRequest>(pi, {
+		channel: TEAM_JOIN_REQUEST,
+		payload: (respond) => ({ ctx, input, respond }),
+		unclaimed: () => ({ ok: false, error: NO_BUS }),
+		failed: (error) => ({ ok: false, error: messageOf(error) }),
 	});
 }
 

package/lib/spawn.ts

@@ -8,11 +8,14 @@
  *
  * IO is split from the decision: {@link spawnOptions} and {@link killPlan} are
  * pure and testable on every platform, while {@link defaultSpawn} and
- * {@link defaultKillTree} execute them. Value-only, like every `lib/` module:
- * no module state, and each caller keeps its own children.
+ * {@link defaultKillTree} execute them. The liveness pair — {@link isPidAlive}
+ * and {@link startTokenOf} — is here too, because asking whether a process is
+ * still the one a record named is the same question as killing it: `job` guards
+ * a reattached pid with it, and so does the session roster. Value-only, like
+ * every `lib/` module: no module state, and each caller keeps its own children.
  */
 
-import { spawn as nodeSpawn, spawnSync } from "node:child_process";
+import { execFileSync, spawn as nodeSpawn, spawnSync } from "node:child_process";
 import type { Readable } from "node:stream";
 
 /**
@@ -124,6 +127,37 @@ export function isPidAlive(pid: number, probe: KillProbe = process.kill): boolea
 	}
 }
 
+/** Whether a pid is still alive. */
+export type LivenessFn = (pid: number) => boolean;
+
+/**
+ * Best-effort OS start-time token for a pid, used to detect pid reuse.
+ *
+ * Returns undefined when the platform cannot provide one (for example Windows, or a
+ * process that is already gone), in which case callers fall back to liveness alone.
+ */
+export type StartTokenFn = (pid: number) => string | undefined;
+
+/**
+ * Default start-time token via `ps`. Undefined where `ps` is unavailable.
+ *
+ * It spawns a process, so a caller asks for it only where liveness alone cannot
+ * decide: a pid that is alive may be a different program than the one a record
+ * named, and nothing cheaper than the start time can tell them apart.
+ */
+export const startTokenOf: StartTokenFn = (pid) => {
+	try {
+		const out = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 2000,
+		});
+		const text = out.toString().trim();
+		return text || undefined;
+	} catch {
+		return undefined;
+	}
+};
+
 /** The host seams {@link applyKillPlan} runs through. */
 export interface KillSeams {
 	/** Signal one pid; throws when the pid is gone or not ours. */

package/lib/stray-fields.ts

@@ -0,0 +1,45 @@
+/**
+ * A field a tool call carries but its action does not act on.
+ *
+ * An action-shaped tool publishes one flat parameter object, so every field is
+ * offered to every action at once; that is harmless only while each action reads
+ * its own. A field that reaches an action which never reads it used to be dropped
+ * in silence — `board add` with `dependsOn` wrote the card without the link and
+ * answered success, and `team offer` with `to` broadcast to every live session
+ * while the caller believed it had named one. The caller could not tell what was
+ * recorded from what was ignored, and nothing in the result said which.
+ *
+ * So the table of what each action reads lives with the tool (`ACTION_FIELDS`),
+ * and this is the sentence a call is refused with: it names every stray field and
+ * the action that does take it, which makes the retry one call away. The table is
+ * keyed in the order the actions are documented, because that order is how the
+ * message lists the verbs that take a field.
+ *
+ * Value-only, as `lib/` must be: the tables are the callers'.
+ */
+
+/** The fields each action reads, keyed in the order the actions are documented. */
+export type ActionFields = Readonly<Record<string, readonly string[]>>;
+
+/**
+ * Why a call carries a field its action does not act on, or nothing when it is clean.
+ *
+ * `undefined` is not a stray: an optional field the caller left out was never passed,
+ * and a schema makes every unset one `undefined`.
+ */
+export function strayField(action: string, args: Record<string, unknown>, fields: ActionFields): string | undefined {
+	const mine = fields[action] ?? [];
+	const stray = Object.entries(args)
+		.filter(([field, value]) => value !== undefined && field !== "action" && !mine.includes(field))
+		.map(([field]) => field);
+	if (stray.length === 0) return undefined;
+	// One stray reads as "takes it"; several need their names, or the sentence stops
+	// saying which field goes where.
+	const named = (field: string): string => {
+		const taking = Object.keys(fields).filter((candidate) => fields[candidate]?.includes(field));
+		if (taking.length === 0) return `${field} belongs to no action`;
+		const verbs = taking.map((one) => `\`${one}\``).join(" and ");
+		return `${verbs} ${taking.length === 1 ? "takes" : "take"} ${stray.length === 1 ? "it" : field}`;
+	};
+	return `${action} does not act on ${stray.join(", ")}: ${stray.map(named).join("; ")}.`;
+}

package/lib/tool-names.ts

@@ -45,6 +45,19 @@ export const SESSION_TOOL = "session";
  */
 export const SUBAGENT_READ_ONLY_PARAM = "readOnly";
 
+/**
+ * The `board` tool: the shared feature list. Plan mode keeps it active because its
+ * `list` action is a read of the repository's cards, so the name is shared while the
+ * write actions stay the board's to refuse.
+ */
+export const BOARD_TOOL = "board";
+
+/**
+ * The one `board` action that reads. Plan mode admits it and refuses the rest, which
+ * is the distinction the tool's `readOnlyHint` cannot carry: the same tool writes.
+ */
+export const BOARD_READ_ACTION = "list";
+
 /**
  * The `read_doc` tool. `file-read` registers it, and the plan, rewind, and
  * subagent reader lists carry the name, so the document reader is one reader

package/lib/tui/README.md

@@ -160,9 +160,12 @@ hold themed strings in state unless `invalidate()` rebuilds them. A widget is
 derived from state, never authoritative.
 
 Pi renders the whole tree every frame, so a component that derives its lines from
-another one memoizes them with `RenderCache` (keyed on width and the source
-lines' identity) and drops the memo in `invalidate()`. Re-deriving every line per
-frame is what makes a long transcript feel slow.
+another one memoizes them with `RenderCache` — `lines()` keyed on width and the
+source lines' identity, or `keyed()` for a component with no inner component (a
+header's view, a footer's snapshot), keyed on the parts it read: primitives by
+value, an object such as the theme by identity — and drops the memo in
+`invalidate()`. Re-deriving every line per frame is what makes a long transcript
+feel slow.
 
 ## Focus
 

package/lib/tui/glyphs.ts

@@ -29,8 +29,7 @@ export const GLYPHS = {
 	jobsRunning: "▸",
 	jobsFailure: "✗",
 	stopped: "⊘",
-	browse: "◉",
-	board: "▤",
+	http: "◉",
 	delegation: "↳",
 	wechat: "✆",
 	gaugeFull: "▰",
@@ -57,10 +56,9 @@ export const GLYPHS = {
 /** Columns between a rail body glyph and its text. */
 export const GLYPH_GAP = 1;
 
-/** Padding used to join (`item`) or group (`group`) UI segments. */
+/** Padding used to join UI segments. */
 export const SEPARATORS = {
 	item: " · ",
-	group: ` ${GLYPHS.divider} `,
 } as const;
 
 /** `ctx.ui.setStatus` keys; one per extension that publishes a chip. */
@@ -71,8 +69,7 @@ export const STATUS_KEYS = {
 	jobsFailure: "jobs-failure",
 	watch: "watch",
 	watchMatches: "watch-matches",
-	browse: "browse",
-	board: "board",
+	http: "http",
 	rewind: "rewind",
 	agents: "agents",
 	wechat: "wechat",