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

package/extensions/session-bus/format.ts

@@ -0,0 +1,124 @@
+/**
+ * Model-facing text for the session bus.
+ *
+ * Everything that came from another session is untrusted text: it is sanitized
+ * before it reaches the transcript, and paths/labels are rendered as one line.
+ */
+
+import { sanitizeLine } from "../../lib/format.ts";
+import type { BusMessage, ClaimConflict, ClaimRecord, SessionStatus } from "./types.ts";
+/** A short id suffix, neutralized like every other peer-supplied field. */
+export function shortId(id: string): string {
+	return sanitizeLine(id.slice(-6));
+}
+
+function claimLine(claim: ClaimRecord): string {
+	return `${sanitizeLine(claim.path)} · ${sanitizeLine(claim.ownerLabel)}`;
+}
+
+/** The status listing: sessions, unread counts, claims, and this session's alerts. */
+export function formatStatus(status: SessionStatus): string {
+	const sessions = status.sessions.map((session) => {
+		const unread = session.unread > 0 ? ` · ${session.unread} unread` : "";
+		const label = sanitizeLine(session.label);
+		const cwd = sanitizeLine(session.cwd);
+		return `- ${label} (${shortId(session.id)}) · ${cwd} · ${sanitizeLine(session.mode)}${unread}`;
+	});
+	const claims = status.claims.map((claim) => `- ${claimLine(claim)}`);
+	const alerts = status.watching ? [`Alerts: inbox watch on${status.watching.wake ? " (wake)" : ""}`] : [];
+	const units = status.units ? [unitLine(status.units)] : [];
+	return [
+		`Sessions (${status.sessions.length})`,
+		...(sessions.length > 0 ? sessions : ["- none"]),
+		"",
+		`Claims (${status.claims.length})`,
+		...(claims.length > 0 ? claims : ["- none"]),
+		...(units.length > 0 ? ["", ...units] : []),
+		...(alerts.length > 0 ? ["", ...alerts] : []),
+		"",
+		`You: ${sanitizeLine(status.me.label)} (${shortId(status.me.id)})`,
+	].join("\n");
+}
+
+/**
+ * The newest split in this repository: joined over total, then each unit with
+ * its holder. Peer-supplied labels are sanitized like every other field.
+ */
+function unitLine(units: NonNullable<SessionStatus["units"]>): string {
+	const rows = units.rows.map(
+		(row) => `${sanitizeLine(row.unit)}${row.lead ? " (lead)" : ""} · ${row.holder ? sanitizeLine(row.holder) : "—"}`,
+	);
+	return [
+		`Units ${units.joined}/${units.total} joined · ${sanitizeLine(units.team)}`,
+		...rows.map((row) => `- ${row}`),
+	].join("\n");
+}
+
+/** The rename result: the label the bus settled on, which peers now address. */
+export function formatName(label: string): string {
+	return `This session is now named "${sanitizeLine(label)}".`;
+}
+
+/** The inbox-watch result. */
+export function formatWatch(watching: { armed: boolean; wake: boolean }, name?: string): string {
+	const owner = name ? ` for "${sanitizeLine(name)}"` : "";
+	if (!watching.armed) return `Inbox watch off${owner}.`;
+	return watching.wake
+		? `Inbox watch on${owner}: a new message raises one turn.`
+		: `Inbox watch on${owner}: new messages appear at your next turn.`;
+}
+
+/** One consumed inbox, oldest first. */
+export function formatInbox(messages: readonly BusMessage[]): string {
+	if (messages.length === 0) return "Inbox empty.";
+	return messages
+		.map((message, index) => {
+			const paths = message.paths?.length
+				? `\n   paths: ${message.paths.map((path) => sanitizeLine(path)).join(", ")}`
+				: "";
+			const from = sanitizeLine(message.fromLabel);
+			return `${index + 1}. ${from} · ${sanitizeLine(message.kind)} · ${sanitizeLine(message.text)}${paths}`;
+		})
+		.join("\n");
+}
+
+/** Confirmation for a send. */
+export function formatSend(delivered: readonly string[], messageId: string): string {
+	if (delivered.length === 0) return "Delivered to 0 sessions.";
+	const names = delivered.map((label) => sanitizeLine(label)).join(", ");
+	return `Delivered to ${names} (${sanitizeLine(messageId)}).`;
+}
+
+/** Claim result, including the owner that blocked it. */
+export function formatClaim(claimed: readonly string[], conflicts: readonly ClaimConflict[]): string {
+	const lines: string[] = [];
+	if (claimed.length > 0) lines.push(`Claimed: ${claimed.map((path) => sanitizeLine(path)).join(", ")}.`);
+	for (const conflict of conflicts) {
+		const owner = sanitizeLine(conflict.ownerLabel);
+		lines.push(`${sanitizeLine(conflict.path)} is owned by ${owner} (${shortId(conflict.owner)}).`);
+	}
+	return lines.length > 0 ? lines.join("\n") : "Nothing claimed.";
+}
+
+/** Join result: which unit, and what it claimed or could not. */
+export function formatJoin(
+	team: string,
+	unit: string,
+	claimed: readonly string[],
+	conflicts: readonly ClaimConflict[],
+): string {
+	const where = `${sanitizeLine(team)}/${sanitizeLine(unit)}`;
+	if (conflicts.length > 0) {
+		return [`Could not join ${where}.`, ...formatClaim([], conflicts).split("\n").filter(Boolean)].join("\n");
+	}
+	const paths = claimed.map((path) => sanitizeLine(path)).join(", ");
+	return claimed.length > 0 ? `Joined ${where}: claimed ${paths}.` : `Joined ${where}: nothing to claim.`;
+}
+
+/** Release result. */
+export function formatRelease(released: readonly string[], notOwned: readonly string[]): string {
+	const lines: string[] = [];
+	if (released.length > 0) lines.push(`Released: ${released.map((path) => sanitizeLine(path)).join(", ")}.`);
+	if (notOwned.length > 0) lines.push(`Not yours: ${notOwned.map((path) => sanitizeLine(path)).join(", ")}.`);
+	return lines.length > 0 ? lines.join("\n") : "Nothing to release.";
+}

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 ?? "")}"`);
+	}
+}