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

package/extensions/session-bus/tools.ts

@@ -2,10 +2,10 @@
  * The `session` tool.
  *
  * One action-shaped tool keeps the prompt surface small: status, send, inbox,
- * claim, release, join, leave, watch, name. The runtime owns file I/O and
- * lifecycle; this module only validates the action, calls the runtime, and hands
- * the result to the shared presentation module — one collapsed line, or the
- * board's rows on expand.
+ * claim, release, join. The runtime owns file I/O and lifecycle; this
+ * module only validates the action, calls the runtime, and hands the result to
+ * the shared presentation module — one collapsed line, or the board's rows on
+ * expand.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -14,16 +14,7 @@ import { Type, type Static } from "typebox";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { errorResult, textResult } from "../../lib/tool-result.ts";
 import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
-import {
-	formatClaim,
-	formatInbox,
-	formatJoin,
-	formatName,
-	formatRelease,
-	formatSend,
-	formatStatus,
-	formatWatch,
-} from "./format.ts";
+import { formatClaim, formatInbox, formatJoin, formatRelease, formatSend, formatStatus } from "./format.ts";
 import { normalizeAction, TOOL_NAME } from "./protocol.ts";
 import type { SessionBus } from "./runtime.ts";
 import { collapsedLine, resultSections, SessionResult } from "./result.ts";
@@ -32,8 +23,8 @@ import type { SessionDetails } from "./types.ts";
 export { TOOL_NAME };
 
 const SessionParams = Type.Object({
-	action: StringEnum(["status", "send", "inbox", "claim", "release", "join", "leave", "watch", "name"] as const, {
-		description: "status, send, inbox, claim, release, join, leave, watch, or name.",
+	action: StringEnum(["status", "send", "inbox", "claim", "release", "join"] as const, {
+		description: "status, send, inbox, claim, release, or join.",
 	}),
 	to: Type.Optional(Type.String({ description: "Target session label/id, or * for an event broadcast." })),
 	text: Type.Optional(Type.String({ description: "Message text, at most 4000 characters." })),
@@ -50,19 +41,16 @@ const SessionParams = Type.Object({
 	),
 	wake: Type.Optional(
 		Type.Boolean({
-			description:
-				"With watch: set the mode — true raises one turn per burst, false waits for the next turn, omitted keeps it.",
+			description: "With join: mail raises one turn per burst once the agent is idle; omitted waits for the next turn.",
 		}),
 	),
-	stop: Type.Optional(Type.Boolean({ description: "With watch: turn this session's inbox watch off." })),
-	team: Type.Optional(
-		Type.String({
-			description: "With join/leave: the split's name — the plan file name without `.md`.",
+	listen: Type.Optional(
+		Type.Boolean({
+			description: "With join: false joins without listening, so mail waits in the inbox until `inbox` reads it.",
 		}),
 	),
-	unit: Type.Optional(Type.String({ description: "With join/leave: the unit to claim or release, e.g. `core`." })),
 	label: Type.Optional(
-		Type.String({ description: "With name: what other sessions call this one, e.g. `billing-lead`." }),
+		Type.String({ description: "With join: what other sessions call this one, e.g. `billing-lead`." }),
 	),
 });
 
@@ -74,19 +62,14 @@ type SessionArgs = Static<typeof SessionParams>;
  * identity of the call.
  */
 function callSubject(action: string, args: Record<string, unknown>): string {
-	if (action === "name") {
+	if (action === "join") {
 		const label = typeof args.label === "string" ? args.label.trim() : "";
-		return label ? `name ${label}` : "name";
+		return label ? `join ${label}` : "join";
 	}
 	if (action === "send") {
 		const to = typeof args.to === "string" ? args.to : "";
 		return to ? `send ${to}` : "send";
 	}
-	if (action === "join" || action === "leave") {
-		const unit = typeof args.unit === "string" ? args.unit : "";
-		const team = typeof args.team === "string" ? args.team : "";
-		return [action, unit, team && !unit ? team : ""].filter(Boolean).join(" ");
-	}
 	if (action !== "claim" && action !== "release") return action;
 	const paths = Array.isArray(args.paths) ? args.paths.filter((path): path is string => typeof path === "string") : [];
 	const [first, ...rest] = paths;
@@ -99,16 +82,14 @@ export function registerTools(pi: ExtensionAPI, bus: SessionBus): void {
 		name: TOOL_NAME,
 		label: "Session bus",
 		description:
-			"Coordinate parallel Pi sessions on this repository. Actions: `status` (sessions, unread, claims, joined units), " +
+			"Coordinate parallel Pi sessions on this repository. Actions: `status` (sessions, unread, claims), " +
 			"`send` (to a label/id, or `*` for an event), `inbox` (consume messages), `claim`/`release` (paths), " +
-			"`join`/`leave` (a unit of an approved split, by `team` and `unit`), " +
-			"`watch` (report new mail at your next turn, or raise one with `wake`; `stop` turns it off). " +
-			"Delivery is pull-based unless this session arms `watch`.",
-		promptSnippet: "Coordinate parallel sessions: status, send, inbox, claim, release, join, leave, watch, name.",
+			"`join` (get on the bus under a label, and listen for mail unless `listen: false`; `wake` raises a turn). " +
+			"Delivery is pull-based unless this session joined and is listening.",
+		promptSnippet: "Coordinate parallel sessions: status, send, inbox, claim, release, join.",
 		promptGuidelines: [
-			"Check `session inbox` when starting or joining a coordinated turn.",
+			"Check `session inbox` when starting a coordinated turn.",
 			"Claim the paths you will edit before changing them; release them when done.",
-			"When a plan was approved with a split, `join` its unit once at the start of the work and `leave` it when merged.",
 			'Send `kind: "event"` for contract, build, or test changes another session needs.',
 			"Never put credentials or secrets in a session-bus message.",
 		],
@@ -161,38 +142,22 @@ export function registerTools(pi: ExtensionAPI, bus: SessionBus): void {
 						});
 					}
 					case "join": {
-						const result = await bus.join({ team: args.team, unit: args.unit });
-						return textResult(formatJoin(result.team, result.unit, result.claimed, result.conflicts), {
-							action,
-							team: result.team,
-							unit: result.unit,
-							claimed: result.claimed,
-							conflicts: result.conflicts,
+						const label = typeof args.label === "string" ? args.label.trim() : "";
+						const joined = await bus.join({
+							...(label === "" ? {} : { label }),
+							...(args.wake === undefined ? {} : { wake: args.wake }),
+							...(args.listen === undefined ? {} : { listen: args.listen }),
 						});
-					}
-					case "leave": {
-						const result = await bus.leave({ team: args.team, unit: args.unit });
-						return textResult(formatRelease(result.released, result.notOwned), {
+						// A label is the bus's name and Pi's session name in one act, so the footer,
+						// `/resume`, and the record a peer addresses agree. A bare join derives its
+						// label from the name Pi already shows and must not rename it back.
+						if (label !== "") pi.setSessionName(joined.label);
+						return textResult(formatJoin(joined.label, joined.watching), {
 							action,
-							released: result.released,
-							notOwned: result.notOwned,
-							...(args.team === undefined ? {} : { team: args.team }),
-							...(args.unit === undefined ? {} : { unit: args.unit }),
+							label: joined.label,
+							watching: joined.watching,
 						});
 					}
-					case "watch": {
-						const watching = await bus.watch({ wake: args.wake, stop: args.stop });
-						return textResult(formatWatch(watching), { action, watching });
-					}
-					case "name": {
-						const label = typeof args.label === "string" ? args.label.trim() : "";
-						if (!label) return errorResult(action, 'name requires a label, e.g. "billing-lead".');
-						const named = await bus.rename(label);
-						// The bus's label and Pi's session name are one identity: the footer,
-						// `/resume`, and the record a peer addresses have to agree.
-						pi.setSessionName(named);
-						return textResult(formatName(named), { action, label: named });
-					}
 				}
 			} catch (error) {
 				return errorResult(action, error instanceof Error ? error.message : String(error));

package/extensions/session-bus/tui.ts

@@ -17,7 +17,7 @@ import { type DetailContents, DockListScreen } from "../../lib/tui/dock-screen.t
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { keyValueRow } from "../../lib/tui/rows.ts";
 import { paint } from "../../lib/tui/tokens.ts";
-import { shortId } from "./format.ts";
+import { idSuffix } from "./format.ts";
 import {
 	type SessionRow,
 	claimRowLine,
@@ -48,7 +48,7 @@ const SCOPE_TITLE: Readonly<Record<BoardScope, string>> = {
 };
 
 const SCOPE_EMPTY: Readonly<Record<BoardScope, string>> = {
-	sessions: "No sessions on this bus.",
+	sessions: "No sessions on this bus yet. Press w to join and listen.",
 	inbox: "No unread mail.",
 	claims: "No claims.",
 };
@@ -76,7 +76,7 @@ function paneFacts(theme: Theme, row: SessionRow, now: number, width: number): s
 	const labelWidth = 10;
 	return [
 		keyValueRow(theme, width, { label: "mode", labelWidth, value: sanitizeLine(row.session.mode) }),
-		keyValueRow(theme, width, { label: "id", labelWidth, value: shortId(row.session.id) }),
+		keyValueRow(theme, width, { label: "id", labelWidth, value: idSuffix(row.session.id) }),
 		keyValueRow(theme, width, {
 			label: "last seen",
 			labelWidth,
@@ -229,7 +229,7 @@ export class SessionListComponent extends DockListScreen<BoardRow> {
 		switch (this.scope) {
 			case "sessions": {
 				const sessions = rows.flatMap((row) => (row.kind === "session" ? [row.row] : []));
-				return summaryCells(this.theme, sessions, watching);
+				return summaryCells(this.theme, sessions, watching, this.board?.status.onBus !== false);
 			}
 			case "inbox": {
 				const cells = [paint(this.theme, "meta", count(rows.length, "unread message"))];

package/extensions/session-bus/types.ts

@@ -20,6 +20,14 @@ export interface SessionRecord {
 	mode: SessionMode;
 	startedAt: number;
 	lastSeen: number;
+	/**
+	 * Whether this session is listening for mail, written when it joins.
+	 *
+	 * Absent means "not listening": a record written before this existed and a session
+	 * that stopped listening read the same way, which is the honest answer for a peer
+	 * deciding whether mail will reach it.
+	 */
+	watching?: { armed: boolean; wake: boolean };
 }
 
 /** One message waiting in a recipient's inbox. */
@@ -47,15 +55,10 @@ export interface ClaimRecord {
 /** What `session status` returns. */
 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 }>;
 	claims: ClaimRecord[];
-	/** The newest split in this repository, and who holds each unit, on an explicit status call. */
-	units?: {
-		team: string;
-		joined: number;
-		total: number;
-		rows: Array<{ unit: string; lead?: boolean; holder?: string }>;
-	};
 	/** Present only when this session armed its inbox watch. */
 	watching?: { armed: boolean; wake: boolean };
 }
@@ -78,10 +81,7 @@ export interface BoardSnapshot {
 
 /** Structured result carried in the `session` tool's details. */
 export interface SessionDetails {
-	action: "status" | "send" | "inbox" | "claim" | "release" | "join" | "leave" | "watch" | "name";
-	/** With join/leave: the split and the unit, so a resumed transcript still says which. */
-	team?: string;
-	unit?: string;
+	action: "status" | "send" | "inbox" | "claim" | "release" | "join";
 	status?: SessionStatus;
 	delivered?: string[];
 	messageId?: string;
@@ -90,9 +90,9 @@ export interface SessionDetails {
 	conflicts?: ClaimConflict[];
 	released?: string[];
 	notOwned?: string[];
-	/** Whether the inbox watch is on, and whether it raises a turn. */
+	/** Whether the inbox watch is on, and whether it raises a turn; `join` reports it. */
 	watching?: { armed: boolean; wake: boolean };
-	/** With name: the label the bus settled on, which is what this session is called. */
+	/** With join: the label the bus settled on, which is what this session is called. */
 	label?: string;
 	error?: string;
 }

package/extensions/subagent/agents.ts

@@ -16,6 +16,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { READ_DOC_TOOL, WEB_FETCH_TOOL, WEB_SEARCH_TOOL } from "../../lib/tool-names.ts";
 
 /** Where an agent definition came from. */
 export type AgentSource = "builtin" | "user" | "project";
@@ -44,7 +45,7 @@ export const BUILTIN_AGENTS: readonly AgentConfig[] = [
 	{
 		name: "explorer",
 		description: "Fast codebase recon that returns compressed context for handoff to other agents",
-		tools: ["read", "grep", "find", "ls"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL],
 		source: "builtin",
 		systemPrompt: `You are an explorer. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
 
@@ -94,7 +95,7 @@ Which file to look at first and why.`,
 		name: "planner",
 		description:
 			"Delegated implementation planning in an isolated context (headless/chain; use plan mode for interactive planning)",
-		tools: ["read", "grep", "find", "ls"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL],
 		source: "builtin",
 		systemPrompt: `You are a delegated planning specialist working in an isolated context. The caller hands you planning when it wants a plan produced without adding exploration to its own transcript — for example an explorer → planner → worker chain, or a headless run.
 
@@ -134,7 +135,7 @@ Keep the plan concrete. The worker agent will execute it verbatim.`,
 	{
 		name: "reviewer",
 		description: "Code review specialist for quality and security analysis",
-		tools: ["read", "grep", "find", "ls", "bash"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a senior code reviewer. Analyze code for quality, security, and maintainability.
 
@@ -168,7 +169,7 @@ Be specific with file paths and line numbers.`,
 	{
 		name: "worker",
 		description: "General-purpose subagent with full capabilities and an isolated context window",
-		tools: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+		tools: ["read", "write", "edit", "bash", "grep", "find", "ls", READ_DOC_TOOL],
 		source: "builtin",
 		systemPrompt: `You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
 
@@ -192,7 +193,7 @@ If handing off to another agent (e.g. reviewer), include:
 	{
 		name: "researcher",
 		description: "Web research specialist that returns sourced findings on external questions",
-		tools: ["read", "grep", "find", "ls", "web_search", "web_fetch"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL, WEB_SEARCH_TOOL, WEB_FETCH_TOOL],
 		source: "builtin",
 		systemPrompt: `You are a research specialist. You investigate questions using web_search and web_fetch, then return findings another agent can act on.
 
@@ -228,7 +229,7 @@ What the caller should do with this, in 2-3 sentences.`,
 	{
 		name: "tester",
 		description: "Writes or updates tests for a change and runs them",
-		tools: ["read", "write", "edit", "grep", "find", "ls", "bash"],
+		tools: ["read", "write", "edit", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a test engineer. You add or update tests for a change and run them.
 
@@ -260,7 +261,7 @@ What is still untested and why.`,
 	{
 		name: "debugger",
 		description: "Root-cause analysis for a failing test or bug, read-only plus running tests",
-		tools: ["read", "grep", "find", "ls", "bash"],
+		tools: ["read", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a debugging specialist. You find the root cause of a failure from evidence, not guesses.
 
@@ -295,7 +296,7 @@ What else the bug or the fix could affect.`,
 	{
 		name: "documenter",
 		description: "Updates docs, READMEs, and changelog entries to match the code",
-		tools: ["read", "write", "edit", "grep", "find", "ls", "bash"],
+		tools: ["read", "write", "edit", "grep", "find", "ls", READ_DOC_TOOL, "bash"],
 		source: "builtin",
 		systemPrompt: `You are a documentation specialist. You keep docs accurate and consistent with the code.
 

package/extensions/subagent/invocation.ts

@@ -6,13 +6,15 @@
  * import for invocation concerns.
  */
 
+import { WORKSPACE_READERS } from "../../lib/policy.ts";
+import { WEB_FETCH_TOOL, WEB_SEARCH_TOOL } from "../../lib/tool-names.ts";
 import type { AgentConfig } from "./agents.ts";
 import type { DispatchDefaults } from "./types.ts";
 
 export { getPiInvocation, type PiInvocation } from "../../lib/pi-invocation.ts";
 
-/** Tools a read-only delegation may use: structured readers and web readers only. */
-export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "web_search", "web_fetch"] as const;
+/** Tools a read-only delegation may use: structured readers, documents, and web readers only. */
+export const READ_ONLY_TOOLS = [...WORKSPACE_READERS, WEB_SEARCH_TOOL, WEB_FETCH_TOOL] as const;
 
 /** Appended to a read-only agent's system prompt; the `--tools` list is the real gate. */
 export const READ_ONLY_NOTE =

package/extensions/team/commands.ts

@@ -0,0 +1,112 @@
+/**
+ * `/team` — the lead's round, printed.
+ *
+ * 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.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Card } 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";
+import { createTeamJoin, type JoinResult, type TeamJoin } from "../../lib/session-tool.ts";
+import { readRoster, type RosterSession, rosterStateOf } from "../../lib/session-roster.ts";
+import { formatJoined, formatNotJoined } from "./format.ts";
+
+/** The command's name, which is also the word a user types. */
+export const TEAM_COMMAND = "team";
+
+/** The words the command accepts besides the round itself. */
+export const TEAM_WORDS = ["join"] as const;
+
+/** How many lines a round may print before it says how many it left out. */
+export const MAX_ROUND_LINES = 10;
+
+export function registerCommands(pi: ExtensionAPI, session: BoardSession, deps: { team?: TeamJoin } = {}): void {
+	const team = deps.team ?? createTeamJoin(pi);
+	pi.registerCommand(TEAM_COMMAND, {
+		description: "The lead's round: who holds what, and what needs a decision; `/team join [<label>]` joins the team",
+		getArgumentCompletions: (prefix: string) => {
+			const text = prefix.trimStart();
+			if (text.includes(" ")) return null;
+			const items = TEAM_WORDS.filter((word) => word.startsWith(text));
+			return items.length > 0 ? items.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const [word = "", ...rest] = args.trim().split(/\s+/).filter(Boolean);
+			if (word === "join") {
+				const label = rest.join(" ").trim();
+				const joined = await team.join(ctx, label === "" ? undefined : label);
+				ctx.ui.notify(joinedLine(joined), joined.ok ? "info" : "warning");
+				return;
+			}
+			if (word !== "") {
+				ctx.ui.notify(
+					`team: "${word}" is not a word this command knows — try /team, or /team join [<label>]`,
+					"warning",
+				);
+				return;
+			}
+			const store = await session.store(ctx.cwd);
+			const cards = await store.list();
+			// The roster is read as data, so a repository with no bus prints the round and
+			// says nothing about who is here rather than failing.
+			const roster = await readRoster(await session.busDir(ctx.cwd));
+			ctx.ui.notify(roundText(cards, session.now(), roster), "info");
+		},
+	});
+}
+
+/** `/team join`'s line: who this session is on the team, or why it is on none. */
+export function joinedLine(result: JoinResult): string {
+	return result.ok ? formatJoined(result.label, result.watching) : formatNotJoined(result.error);
+}
+
+/**
+ * The round as the lines a lead reads: the rollup, then who is live.
+ *
+ * Capped, because a notify is a message and not a screen: past its limit the round says
+ * how many lines it left out instead of pushing the rest of the session up the screen.
+ */
+export function roundText(cards: readonly Card[], now: number, roster?: readonly RosterSession[]): string {
+	if (cards.length === 0) return "team: nothing to report — the board is empty";
+	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`);
+	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.
+ *
+ * Three 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.
+ */
+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 silent: string[] = [];
+	for (const session of roster) {
+		if (rosterStateOf(session, now) !== "live") {
+			quiet.push(session.label);
+			continue;
+		}
+		live.push(session.label);
+		if (session.watching?.armed === false) silent.push(session.label);
+	}
+	const parts = [
+		live.length > 0 ? `live: ${live.join(", ")}` : "",
+		silent.length > 0 ? `not listening: ${silent.join(", ")}` : "",
+		quiet.length > 0 ? `quiet: ${quiet.join(", ")}` : "",
+	];
+	return parts.filter((part) => part !== "").join(" · ");
+}

package/extensions/team/dispatch.ts

@@ -0,0 +1,133 @@
+/**
+ * The handoff: what `team assign` tells the peer, and how it tells it.
+ *
+ * The peer is a session that is already running, so this is a message and not a
+ * process: `session send` writes it into the recipient's inbox, and its armed watch is
+ * what raises the turn. Nothing here starts anything, and a send that fails leaves the
+ * card exactly as it was — the order is deliberate, because a card assigned without a
+ * message is a card nobody knows about.
+ *
+ * The transport is a seam (`Dispatch`), so the tool's ordering is testable without a
+ * bus, and the one production implementation is `lib/session-tool.ts`'s.
+ */
+
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { Card } from "../../lib/board/card.ts";
+import { cardRef, type CardOwner } from "../../lib/board/card.ts";
+import { listPeers, MAX_MESSAGE_TEXT, type Peer, send as sendTo } from "../../lib/session-tool.ts";
+
+/** How a handoff reaches a peer, and what the bus can say about the peers there are. */
+export interface Dispatch {
+	/** Send the text as `kind`, and report the labels a message file was written for. Throws on failure. */
+	send(input: { kind: "handoff" | "event"; to: string; text: string }): Promise<{ delivered: string[] }>;
+	/**
+	 * Every session the bus lists, when it can say.
+	 *
+	 * Its record is what makes an assignment survive a rename — `holds` compares ids
+	 * before labels — and what makes the report able to name a peer that cannot be
+	 * woken. It never throws: a resolve that fails must not undo a handoff that landed.
+	 */
+	peers(): Promise<Peer[] | undefined>;
+}
+
+/**
+ * What the peer reads.
+ *
+ * It names the card, its outcome, and the paths, and says what to do next: record the
+ * plan, work, note, finish. It does **not** ask the peer to claim the card — `assign`
+ * has already recorded the owner, and a claim by the holder is a no-op. The claim is
+ * only for the failure path where the send landed and the assignment did not.
+ */
+export function handoffText(card: Card, to: string, note?: string): string {
+	const lines = [
+		`Handoff: ${cardRef(card.id)} "${card.title}" is yours, ${to}.`,
+		card.paths.length > 0 ? `Paths: ${card.paths.join(", ")}` : undefined,
+		card.plan === undefined ? undefined : `Plan: ${card.plan}`,
+		note === undefined ? undefined : `Note: ${note}`,
+		`It is already assigned to you — record the plan with board action "plan" if it has none, then note each phase and move it to done or blocked.`,
+	].filter((line): line is string => line !== undefined);
+	return withinLimit(lines.join("\n"));
+}
+
+/**
+ * What every live session reads when the lead offers a card instead of assigning it.
+ *
+ * An offer names no owner: the first peer to claim the card takes it, so the text says
+ * what the card is and that claiming is the next step, and it never implies the work is
+ * already somebody's.
+ */
+export function offerText(card: Card, note?: string): string {
+	const lines = [
+		`Offer: ${cardRef(card.id)} "${card.title}" is unclaimed.`,
+		card.paths.length > 0 ? `Paths: ${card.paths.join(", ")}` : undefined,
+		card.plan === undefined ? undefined : `Plan: ${card.plan}`,
+		note === undefined ? undefined : `Note: ${note}`,
+		`First to claim it takes it: run board action "claim" with card "${card.id}", then note each phase and move it to done or blocked.`,
+	].filter((line): line is string => line !== undefined);
+	return withinLimit(lines.join("\n"));
+}
+
+/**
+ * Trim to the bus's text limit, which is also this message's limit.
+ *
+ * Not `lib/tui/columns.ts`'s `clip`: that one measures terminal columns, and this one
+ * counts characters, because the bus's limit is characters. The number arrives from
+ * `lib/session-tool.ts` — one copy for the two extensions that send through it.
+ */
+function withinLimit(text: string): string {
+	return text.length > MAX_MESSAGE_TEXT ? `${text.slice(0, MAX_MESSAGE_TEXT - 1)}…` : text;
+}
+
+/** The production dispatch: `lib/session-tool.ts`, with a failure turned into a throw. */
+export function sessionDispatch(ctx: ExtensionToolContext): Dispatch {
+	return {
+		async send(input) {
+			const result = await sendTo(ctx, input);
+			// `assign` and `offer` branch on a failed send, so this seam reports it the way
+			// they read it: the bus's sentence, as the reason the card was not handed over.
+			if (!result.ok) throw new Error(result.error);
+			return { delivered: result.delivered };
+		},
+		peers: () => listPeers(ctx),
+	};
+}
+
+/**
+ * The peer `to` names: an id exactly, else a label ignoring case.
+ *
+ * The send has already proved exactly one session answers to it, so the first match is
+ * the recipient; a miss means the bus could not say, which is why the caller falls back
+ * to the label alone.
+ */
+export function peerFor(peers: readonly Peer[] | undefined, to: string): Peer | undefined {
+	if (peers === undefined) return undefined;
+	const target = to.trim();
+	const byId = peers.find((peer) => peer.id === target);
+	if (byId) return byId;
+	const wanted = target.toLowerCase();
+	return peers.find((peer) => peer.label.toLowerCase() === wanted);
+}
+
+/**
+ * The labels a message reached that cannot be woken: their record says they are not
+ * listening.
+ *
+ * A label the bus could not answer for is left out — "the record does not say" is not
+ * "nobody will read it" — and so is a peer the bus lists as listening.
+ */
+export function notListening(peers: readonly Peer[] | undefined, labels: readonly string[]): string[] {
+	if (peers === undefined) return [];
+	return labels.filter((label) => {
+		const peer = peerFor(peers, label);
+		return peer !== undefined && peer.listening === false;
+	});
+}
+
+/**
+ * The peer a handoff names, as the card records it when the bus cannot say who that
+ * is: the label a message file was written for, else the one that was asked for.
+ */
+export function ownerFor(to: string, delivered: readonly string[]): CardOwner {
+	const label = delivered[0] ?? to;
+	return { label };
+}