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

package/extensions/session-bus/index.ts

@@ -0,0 +1,69 @@
+/**
+ * session-bus — coordinate parallel Pi sessions on one repository.
+ *
+ * A terminal session joins on `session_start`; RPC, JSON, print, and WeChat peer
+ * sessions join only when the tool or `/sessions` is used. The factory only
+ * registers; the runtime owns the heartbeat and removes the registry entry on
+ * shutdown. Nothing arms an inbox watch by itself, so delivery stays pull-based
+ * until a session asks: with the watch armed, new mail is reported at the next
+ * turn, or — with `wake` — raises one turn as soon as the agent is idle,
+ * including right after a running turn settles.
+ *
+ * Load with:  pi --extension ./extensions/session-bus
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { messageOf } from "../../lib/errors.ts";
+import { createPendingReporter, registerPendingChannel } from "../../lib/report.ts";
+import { registerCommands } from "./commands.ts";
+import { createSessionBus, type SessionBus } from "./runtime.ts";
+import { registerTools } from "./tools.ts";
+import { mailNotice } from "./notice.ts";
+import type { BusMessage } from "./types.ts";
+
+export interface SessionBusDeps {
+	/** Test seam: a runtime with a temp dir and fixed clock. */
+	bus?: SessionBus;
+}
+
+export default function sessionBus(pi: ExtensionAPI, deps: SessionBusDeps = {}): void {
+	if (!isExtensionEnabled("session-bus")) return;
+	const bus = deps.bus ?? createSessionBus(pi);
+
+	const reporter = createPendingReporter<BusMessage>({
+		wake: (notice) => pi.sendMessage(notice, { triggerTurn: true }),
+		pending: () => bus.pending(),
+		markReported: (messages) => bus.markReported(messages.map((message) => message.id)),
+		buildNotice: mailNotice,
+		source: "session-bus",
+		wakeRequested: () => bus.wantsWake(),
+	});
+
+	registerTools(pi, bus);
+	registerCommands(pi, bus);
+
+	registerPendingChannel(pi, {
+		reporter,
+		runtime: {
+			// A start failure is reported once and leaves the runtime retryable: the next
+			// tool call starts it again, and a bus that never started simply never polls.
+			load: async (ctx) => {
+				try {
+					await bus.start(ctx);
+				} catch (error) {
+					ctx.ui.notify(`Session bus did not start: ${messageOf(error)}`, "warning");
+				}
+			},
+			shutdown: () => bus.stop(),
+		},
+		// A reload or a replaced session reuses the runtime, so the mail trigger is
+		// armed on every session start and cleared before the runtime releases.
+		onSessionStart: () => {
+			bus.onWake = () => reporter.report();
+		},
+		onSessionShutdown: () => {
+			bus.onWake = undefined;
+		},
+	});
+}

package/extensions/session-bus/notice.ts

@@ -0,0 +1,58 @@
+/**
+ * The mail notice: what the model reads when an armed session has new mail, and
+ * the rows bytefly draws from the same burst.
+ *
+ * The message bodies came from another session, so they are sanitized here before
+ * they reach either audience.
+ */
+
+import { sanitizeLine } from "../../lib/format.ts";
+import { burstText, noticeMessage, type NoticeItem, type NoticeMessage } from "../../lib/notice.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import type { BusMessage } from "./types.ts";
+
+/** Marker embedded in the injected mail context. */
+const BUS_CONTEXT_MARKER = "[SESSION BUS]";
+
+/** Messages previewed in the model-facing text. The renderer shows its own cap. */
+const MAX_NOTICE_LINES = 5;
+
+/** A message body is clipped to this many characters in a preview. */
+const MAX_PREVIEW = 200;
+
+/** One message as a preview line: sender, kind, and the head of its text. */
+function previewOf(message: BusMessage): string {
+	const text = sanitizeLine(message.text);
+	const head = text.length > MAX_PREVIEW ? `${text.slice(0, MAX_PREVIEW)}…` : text;
+	const paths = message.paths?.length ? ` (${message.paths.map((path) => sanitizeLine(path)).join(", ")})` : "";
+	return `${sanitizeLine(message.fromLabel)}${SEPARATORS.item}${sanitizeLine(message.kind)}${SEPARATORS.item}${head}${paths}`;
+}
+
+/**
+ * The shared notice for pending mail: model text plus renderer details.
+ *
+ * The model reads five lines, so a burst stays bounded in its context; every
+ * message is passed to the renderer, whose own cap draws the `… N more` row. The
+ * two caps are deliberately separate — one is a context budget, the other a
+ * screen height.
+ */
+export function mailNotice(messages: BusMessage[]): NoticeMessage {
+	const count = messages.length;
+	const shown = messages.slice(0, MAX_NOTICE_LINES);
+	const more = count - shown.length;
+	const items: NoticeItem[] = messages.map((message) => ({
+		label: `${sanitizeLine(message.fromLabel)}${SEPARATORS.item}${sanitizeLine(message.kind)}`,
+		detail: sanitizeLine(message.text).slice(0, MAX_PREVIEW),
+		severity: message.kind === "event" ? "warn" : "info",
+	}));
+	return noticeMessage({
+		content: burstText({
+			marker: BUS_CONTEXT_MARKER,
+			headline: `${count} new message${count === 1 ? "" : "s"}`,
+			lines: shown.map((message) => `- ${previewOf(message)}`),
+			...(more > 0 ? { more: `… ${more} more` } : {}),
+			hint: "Run `session inbox` to read and consume them.",
+		}),
+		details: { source: "session-bus", title: `${count} new message${count === 1 ? "" : "s"}`, items },
+	});
+}

package/extensions/session-bus/protocol.ts

@@ -0,0 +1,134 @@
+/**
+ * Pure protocol rules for the session bus.
+ *
+ * No filesystem or process access lives here: labels, targets, claim paths, and
+ * validation are testable without a runtime. `store.ts` owns the files.
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { sanitizeLine } from "../../lib/format.ts";
+
+export const TOOL_NAME = "session";
+export const COMMAND_NAME = "sessions";
+export const MAX_TEXT = 4_000;
+export const MAX_PATHS = 20;
+export const MAX_LABEL = 40;
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 50;
+
+export type SessionMode = "tui" | "rpc" | "json" | "print" | "unknown";
+export type SessionAction = "status" | "send" | "inbox" | "claim" | "release" | "join" | "leave" | "watch" | "name";
+export type MessageKind = "message" | "event" | "ask" | "handoff";
+
+const ACTIONS: readonly SessionAction[] = [
+	"status",
+	"send",
+	"inbox",
+	"claim",
+	"release",
+	"join",
+	"leave",
+	"watch",
+	"name",
+];
+const KINDS: readonly MessageKind[] = ["message", "event", "ask", "handoff"];
+
+/** Only a terminal session is visible on the bus before it asks to join. */
+export function isAutoJoinMode(mode: string | undefined): boolean {
+	return mode === "tui";
+}
+
+/** The session mode as the record stores it. */
+export function sessionMode(mode: string | undefined): SessionMode {
+	return mode === "tui" || mode === "rpc" || mode === "json" || mode === "print" ? mode : "unknown";
+}
+
+/** A safe label, used both for display and as a target. */
+export function normalizeLabel(raw: string | undefined, fallback: string): string {
+	const text = sanitizeLine(raw ?? "")
+		.replace(/\s+/g, " ")
+		.trim();
+	return (text || fallback).slice(0, MAX_LABEL);
+}
+
+/** A short, display-only suffix for a session id. */
+export function shortId(id: string): string {
+	const clean = id.replace(/[^a-zA-Z0-9]/g, "");
+	return (clean || id).slice(-6);
+}
+
+/** The automatic label before uniqueness is applied. */
+export function defaultLabel(sessionName: string | undefined, cwd: string, id: string): string {
+	const base = normalizeLabel(sessionName, normalizeLabel(cwd.split(/[\\/]/).filter(Boolean).at(-1), "session"));
+	return normalizeLabel(base, `session-${shortId(id)}`);
+}
+
+/** An action, or undefined when the model sent an unknown one. */
+export function normalizeAction(raw: unknown): SessionAction | undefined {
+	return typeof raw === "string" && ACTIONS.includes(raw as SessionAction) ? (raw as SessionAction) : undefined;
+}
+
+/** A message kind; `message` is the default. */
+export function normalizeKind(raw: unknown): MessageKind {
+	return typeof raw === "string" && KINDS.includes(raw as MessageKind) ? (raw as MessageKind) : "message";
+}
+
+/** Trimmed message text, or an error message. */
+export function normalizeText(raw: unknown): { text: string } | { error: string } {
+	if (typeof raw !== "string" || raw.trim() === "") return { error: "text is required." };
+	const text = raw.trim();
+	if (text.length > MAX_TEXT) return { error: `text must be at most ${MAX_TEXT} characters.` };
+	return { text };
+}
+
+/** A shared inbox limit. */
+export function normalizeLimit(raw: unknown): number {
+	if (typeof raw !== "number" || !Number.isFinite(raw)) return DEFAULT_LIMIT;
+	return Math.min(MAX_LIMIT, Math.max(1, Math.floor(raw)));
+}
+
+/** Repository-relative, posix-normalized paths, or an error. */
+export function normalizePaths(repoRoot: string, cwd: string, raw: unknown): { paths: string[] } | { error: string } {
+	if (!Array.isArray(raw) || raw.length === 0) return { error: "paths must contain at least one path." };
+	if (raw.length > MAX_PATHS) return { error: `at most ${MAX_PATHS} paths are allowed.` };
+	const paths: string[] = [];
+	for (const entry of raw) {
+		if (typeof entry !== "string" || entry.trim() === "") return { error: "every path must be a non-empty string." };
+		const absolute = resolve(cwd, entry.trim());
+		const rel = relative(repoRoot, absolute);
+		if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+			return { error: `path "${entry}" is outside the repository.` };
+		}
+		const normalized = rel.split(sep).join("/");
+		if (!paths.includes(normalized)) paths.push(normalized);
+	}
+	return { paths };
+}
+
+/**
+ * Whether one claim covers the other path in either direction.
+ *
+ * The predicate is `lib/claims/overlap.ts`, because plan approval validates a
+ * split with the same question; a second copy here is how the two answers drift.
+ */
+export { claimsConflict } from "../../lib/claims/overlap.ts";
+
+/** Resolve `to` to active sessions; `*` is broadcast and excludes the sender. */
+export function resolveRecipients(
+	sessions: readonly { id: string; label: string }[],
+	to: string,
+	from: string,
+): { recipients: Array<{ id: string; label: string }> } | { error: string } {
+	const target = to.trim();
+	if (target === "") return { error: "to is required." };
+	if (target === "*") {
+		const recipients = sessions.filter((session) => session.id !== from);
+		return recipients.length === 0 ? { error: "there are no other active sessions." } : { recipients };
+	}
+	const exact = sessions.find((session) => session.id === target);
+	if (exact) return { recipients: [exact] };
+	const byLabel = sessions.filter((session) => session.label.toLowerCase() === target.toLowerCase());
+	if (byLabel.length === 1) return { recipients: byLabel };
+	if (byLabel.length > 1) return { error: `the label "${target}" is ambiguous; use a session id.` };
+	return { error: `no active session "${target}".` };
+}

package/extensions/session-bus/result.ts

@@ -0,0 +1,243 @@
+/**
+ * The `session` tool's transcript block: the expanded rows one section per entity
+ * group, and the one collapsed line a reader sees without expanding.
+ *
+ * The row grammar and the sanitization live in `rows.ts`; this module only decides
+ * which rows an action shows and how the failed ones read.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { sanitizeLine } from "../../lib/format.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { TailResult, type TailResultInput, type TailSection } from "../../lib/tui/tool.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { type BusRow, busRowLine, count, sessionRows } from "./rows.ts";
+import type { SessionDetails } from "./types.ts";
+
+/**
+ * The transcript block for an expanded `session` result: the shared tail block
+ * over the board's rows, one section per entity group.
+ */
+export class SessionResult implements Component {
+	private readonly view: TailResult<BusRow>;
+
+	constructor(input: TailResultInput<BusRow>, theme: Theme) {
+		this.view = new TailResult(input, theme);
+	}
+
+	/** Update in place so the transcript can reuse this component across renders. */
+	setInput(input: TailResultInput<BusRow>, theme: Theme): void {
+		this.view.setInput(input, theme);
+	}
+
+	invalidate(): void {
+		this.view.invalidate();
+	}
+
+	render(width: number): string[] {
+		return this.view.render(width);
+	}
+}
+
+/** One section of the expanded result. */
+function section(rows: BusRow[], label?: string): TailSection<BusRow> {
+	return { label, rows, more: 0, rowLine: busRowLine };
+}
+
+/**
+ * The expanded result rows for one action, in the order a reader expects: the
+ * board, the consumed mail, a conflict before the claim, released before
+ * not-owned. Returns `undefined` when the action has nothing to list.
+ */
+export function resultSections(details: SessionDetails): TailResultInput<BusRow> | undefined {
+	switch (details.action) {
+		case "status": {
+			const board = sessionRows(details.status);
+			const claims = board.flatMap((row) => row.claims);
+			const sections: TailSection<BusRow>[] = [];
+			if (board.length > 0) sections.push(section(board.map((row) => ({ kind: "session", row }))));
+			if (claims.length > 0) {
+				sections.push(
+					section(
+						claims.map((claim) => ({ kind: "claim", claim })),
+						"Claims",
+					),
+				);
+			}
+			return sections.length > 0 ? { kind: "sections", sections } : undefined;
+		}
+		case "inbox": {
+			const messages = details.messages ?? [];
+			if (messages.length === 0) return undefined;
+			return { kind: "sections", sections: [section(messages.map((message) => ({ kind: "message", message })))] };
+		}
+		case "claim": {
+			const conflicts = details.conflicts ?? [];
+			if (conflicts.length > 0) {
+				return {
+					kind: "sections",
+					sections: [
+						section(
+							conflicts.map((claim) => ({ kind: "claim", claim })),
+							"Conflicts",
+						),
+					],
+				};
+			}
+			const claimed = details.claimed ?? [];
+			if (claimed.length === 0) return undefined;
+			return {
+				kind: "sections",
+				sections: [
+					section(
+						claimed.map((label) => ({ kind: "result", label, tone: "ok" })),
+						"Claimed",
+					),
+				],
+			};
+		}
+		case "join": {
+			const conflicts = details.conflicts ?? [];
+			const claimed = details.claimed ?? [];
+			const rows: BusRow[] = [
+				...conflicts.map((claim) => ({ kind: "claim" as const, claim })),
+				...claimed.map((label) => ({ kind: "result" as const, label, tone: "ok" as const })),
+			];
+			if (rows.length === 0) return undefined;
+			return {
+				kind: "sections",
+				sections: [section(rows, conflicts.length > 0 ? "Conflicts" : "Claimed")],
+			};
+		}
+		case "release":
+		case "leave": {
+			const released = details.released ?? [];
+			const notOwned = details.notOwned ?? [];
+			const sections: TailSection<BusRow>[] = [];
+			if (released.length > 0) {
+				sections.push(
+					section(
+						released.map((label) => ({ kind: "result", label, tone: "ok" })),
+						"Released",
+					),
+				);
+			}
+			if (notOwned.length > 0) {
+				sections.push(
+					section(
+						notOwned.map((label) => ({ kind: "result", label, tone: "warn" })),
+						"Not yours",
+					),
+				);
+			}
+			return sections.length > 0 ? { kind: "sections", sections } : undefined;
+		}
+		case "send": {
+			const delivered = details.delivered ?? [];
+			if (delivered.length === 0) return undefined;
+			return {
+				kind: "sections",
+				sections: [section(delivered.map((label) => ({ kind: "result", label, tone: "ok" })))],
+			};
+		}
+		case "watch":
+			return undefined;
+		case "name":
+			return undefined;
+	}
+}
+
+/**
+ * The collapsed result line: the one thing the user needs without expanding.
+ *
+ * A conflict or a path this session does not own is worth the warning role; a
+ * successful claim, release, or send is routine, so those stay calm.
+ */
+export function collapsedLine(theme: Theme, details: SessionDetails): string {
+	const sep = SEPARATORS.item;
+	switch (details.action) {
+		case "status": {
+			const board = sessionRows(details.status);
+			const unread = board.reduce((total, row) => total + row.session.unread, 0);
+			const claims = board.reduce((total, row) => total + row.claims.length, 0);
+			const cells = [count(board.length, "session")];
+			if (unread > 0) cells.push(`${unread} unread`);
+			cells.push(count(claims, "claim"));
+			const units = details.status?.units;
+			if (units) cells.push(`${units.joined}/${units.total} units`);
+			const watching = details.status?.watching;
+			if (watching) cells.push(watching.wake ? "watch wake" : "watch on");
+			return paint(theme, "meta", cells.join(sep));
+		}
+		case "send": {
+			const delivered = details.delivered ?? [];
+			if (delivered.length === 0) return paint(theme, "meta", "Delivered to nobody");
+			return paint(theme, "ok", `Delivered to ${delivered.map((label) => sanitizeLine(label)).join(", ")}`);
+		}
+		case "inbox": {
+			const messages = details.messages ?? [];
+			if (messages.length === 0) return paint(theme, "meta", "Inbox empty");
+			const senders = [...new Set(messages.map((message) => sanitizeLine(message.fromLabel)))];
+			return paint(theme, "meta", `${count(messages.length, "message")}${sep}${senders.join(", ")}`);
+		}
+		case "claim": {
+			const conflicts = details.conflicts ?? [];
+			if (conflicts.length > 0) {
+				const [first] = conflicts;
+				const more = conflicts.length - 1;
+				const path = first ? sanitizeLine(first.path) : "a path";
+				const owner = first ? sanitizeLine(first.ownerLabel) : "a peer";
+				return paint(
+					theme,
+					"warn",
+					`${count(conflicts.length, "conflict")}${sep}${path} held by ${owner}${more > 0 ? ` +${more} more` : ""}`,
+				);
+			}
+			const claimed = details.claimed ?? [];
+			if (claimed.length === 0) return paint(theme, "meta", "Claimed nothing");
+			return paint(theme, "ok", `Claimed ${claimed.map((path) => sanitizeLine(path)).join(", ")}`);
+		}
+		case "join": {
+			const conflicts = details.conflicts ?? [];
+			const where = [details.team, details.unit]
+				.filter(Boolean)
+				.map((value) => sanitizeLine(value as string))
+				.join("/");
+			if (conflicts.length > 0) {
+				const [first] = conflicts;
+				const owner = first ? sanitizeLine(first.ownerLabel) : "a peer";
+				return paint(
+					theme,
+					"warn",
+					`Could not join ${where}${sep}${count(conflicts.length, "conflict")} held by ${owner}`,
+				);
+			}
+			const claimed = details.claimed ?? [];
+			return paint(theme, "ok", `Joined ${where}${sep}claimed ${claimed.map((path) => sanitizeLine(path)).join(", ")}`);
+		}
+		case "release":
+		case "leave": {
+			const released = details.released ?? [];
+			const notOwned = details.notOwned ?? [];
+			const parts: string[] = [];
+			if (released.length > 0)
+				parts.push(paint(theme, "ok", `Released ${released.map((path) => sanitizeLine(path)).join(", ")}`));
+			if (notOwned.length > 0) {
+				parts.push(paint(theme, "warn", `Not yours: ${notOwned.map((path) => sanitizeLine(path)).join(", ")}`));
+			}
+			return parts.length > 0 ? parts.join(paint(theme, "faint", sep)) : paint(theme, "meta", "Nothing to release");
+		}
+		case "watch": {
+			const armed = details.watching?.armed === true;
+			if (!armed) return paint(theme, "meta", "Inbox watch off");
+			return paint(
+				theme,
+				"ok",
+				details.watching?.wake === true ? "Inbox watch on: new mail wakes a turn" : "Inbox watch on",
+			);
+		}
+		case "name":
+			return paint(theme, "ok", `Named this session "${sanitizeLine(details.label ?? "")}"`);
+	}
+}

package/extensions/session-bus/rows.ts

@@ -0,0 +1,169 @@
+/**
+ * The bus row grammar: the one place a session, a held path, or a message is
+ * turned into a line, shared by the `/sessions` board and the `session` tool
+ * block's expanded result.
+ *
+ * Every field came from another session's record, message, or claim, so it is
+ * sanitized here, at the boundary that reaches the terminal, and every row is
+ * clipped to the width it is given by `listRow`/`statusRow`.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { formatDuration, sanitizeLine } from "../../lib/format.ts";
+import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { listRow, statusRow } from "../../lib/tui/rows.ts";
+import type { TailRowLine } from "../../lib/tui/tool.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { shortId } from "./format.ts";
+import type { BusMessage, ClaimRecord, SessionRecord, SessionStatus } from "./types.ts";
+
+/** Claim paths the focus block lists before it points at the pane. */
+const BLOCK_CLAIMS = 2;
+
+/** `1 claim`, `2 claims`. */
+export function count(n: number, noun: string): string {
+	return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+
+/** One session on the board, with the claims it holds. */
+export interface SessionRow {
+	session: SessionRecord & { unread: number };
+	/** Whether this row is the session reading the board. */
+	self: boolean;
+	claims: ClaimRecord[];
+}
+
+/** A row of the transcript's expanded result: one entity per action. */
+export type BusRow =
+	| { kind: "session"; row: SessionRow }
+	| { kind: "claim"; claim: Pick<ClaimRecord, "path" | "ownerLabel"> }
+	| { kind: "message"; message: BusMessage }
+	| { kind: "result"; label: string; tone: "ok" | "warn" };
+
+/** Label order by code unit, so a live re-sort is deterministic. */
+function byLabel(a: { label: string }, b: { label: string }): number {
+	return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
+}
+
+/**
+ * The board's rows: this session first, then peers by label, each with its own
+ * claims. A status without sessions (a failed read) is an empty board.
+ */
+export function sessionRows(status: SessionStatus | undefined): SessionRow[] {
+	if (!status) return [];
+	const rows = status.sessions.map((session) => ({
+		session,
+		self: session.id === status.me.id,
+		claims: status.claims
+			.filter((claim) => claim.owner === session.id)
+			.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+	}));
+	return rows.sort((a, b) => (a.self === b.self ? byLabel(a.session, b.session) : a.self ? -1 : 1));
+}
+
+/** One session row: the label, a `you` tag on this session, and its counts. */
+export function sessionRowLine(
+	row: SessionRow,
+	theme: Theme,
+	width: number,
+	options: { selected?: boolean; marker?: boolean } = {},
+): string {
+	const label = `${sanitizeLine(row.session.label)}${row.self ? " · you" : ""}`;
+	const counts = [`${row.session.unread} unread`];
+	if (row.claims.length > 0) counts.push(count(row.claims.length, "claim"));
+	return listRow(theme, width, {
+		selected: options.selected === true,
+		marker: options.marker !== false,
+		label,
+		labelRole: options.selected === true ? "accent" : "label",
+		trailing: counts.join(SEPARATORS.item),
+	});
+}
+
+/** One held path: the claim glyph, the path, and the session holding it. */
+export function claimRowLine(
+	claim: Pick<ClaimRecord, "path" | "ownerLabel">,
+	theme: Theme,
+	width: number,
+	options: { selected?: boolean; marker?: boolean; self?: boolean } = {},
+): string {
+	const owner = `${sanitizeLine(claim.ownerLabel)}${options.self === true ? " · you" : ""}`;
+	return statusRow(theme, width, {
+		selected: options.selected === true,
+		marker: options.marker !== false,
+		glyph: GLYPHS.target,
+		glyphRole: "info",
+		label: sanitizeLine(claim.path),
+		labelRole: options.selected === true ? "accent" : "label",
+		trailing: owner,
+	});
+}
+
+/** One message row: the sender and kind as meta trailing the text. */
+export function messageRowLine(
+	message: BusMessage,
+	theme: Theme,
+	width: number,
+	options: { selected?: boolean; marker?: boolean } = {},
+): string {
+	const glyph = message.kind === "event" ? GLYPHS.warn : message.kind === "ask" ? GLYPHS.unknown : GLYPHS.pending;
+	return statusRow(theme, width, {
+		selected: options.selected === true,
+		marker: options.marker !== false,
+		glyph,
+		glyphRole: message.kind === "event" ? "warn" : "info",
+		label: sanitizeLine(message.text),
+		labelRole: options.selected === true ? "accent" : "label",
+		trailing: `${sanitizeLine(message.fromLabel)}${SEPARATORS.item}${sanitizeLine(message.kind)}`,
+	});
+}
+
+/** The one row renderer the expanded transcript block uses. */
+export const busRowLine: TailRowLine<BusRow> = (row, width, theme) => {
+	switch (row.kind) {
+		case "session":
+			return sessionRowLine(row.row, theme, width, { marker: false });
+		case "claim":
+			return claimRowLine(row.claim, theme, width, { marker: false });
+		case "message":
+			return messageRowLine(row.message, theme, width, { marker: false });
+		case "result":
+			return statusRow(theme, width, {
+				marker: false,
+				glyph: row.tone === "ok" ? GLYPHS.check : GLYPHS.cross,
+				glyphRole: row.tone,
+				label: sanitizeLine(row.label),
+				trailing: "",
+			});
+	}
+};
+
+/** The summary cells: the counts a reader scans before the rows. */
+export function summaryCells(
+	theme: Theme,
+	rows: readonly SessionRow[],
+	watching: { armed: boolean; wake: boolean } | undefined,
+): string[] {
+	const unread = rows.reduce((total, row) => total + row.session.unread, 0);
+	const claims = rows.reduce((total, row) => total + row.claims.length, 0);
+	const cells = [paint(theme, "meta", count(rows.length, "session"))];
+	if (unread > 0) cells.push(paint(theme, "label", `${unread} unread`));
+	cells.push(paint(theme, "meta", count(claims, "claim")));
+	if (watching) cells.push(paint(theme, "ok", watching.wake ? "watch wake" : "watch on"));
+	return cells;
+}
+
+/** The focus block under the list: what the row does not already say. */
+export function sessionDetailBlock(row: SessionRow, now: number): string[] {
+	const lines = [`cwd: ${sanitizeLine(row.session.cwd)}`];
+	if (row.claims.length > 0) {
+		const shown = row.claims.slice(0, BLOCK_CLAIMS).map((claim) => sanitizeLine(claim.path));
+		const hidden = row.claims.length - shown.length;
+		lines.push(`claims: ${shown.join(", ")}${hidden > 0 ? ` +${hidden} more` : ""}`);
+	}
+	lines.push(
+		`mode: ${sanitizeLine(row.session.mode)}${SEPARATORS.item}id: ${shortId(row.session.id)}` +
+			`${SEPARATORS.item}last seen: ${formatDuration(Math.max(0, now - row.session.lastSeen))} ago`,
+	);
+	return lines;
+}