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

package/extensions/question/dialogs.ts

@@ -6,13 +6,15 @@
  * fake and reusable by any host.
  */
 
-import { OTHER_LABEL, cancelledResult, completedResult } from "./answers.ts";
+import { OTHER_LABEL, cancelledResult, collectAnswers, completedResult } from "./answers.ts";
 import type { Answer, AskResult, Question, Selection } from "./types.ts";
 
 export interface QuestionUI {
 	select(title: string, options: string[], opts?: { signal?: AbortSignal }): Promise<string | undefined>;
 	input(title: string, placeholder?: string, opts?: { signal?: AbortSignal }): Promise<string | undefined>;
 	editor(title: string, prefill?: string): Promise<string | undefined>;
+	/** Prompt language, when the host knows it. */
+	language?(): "zh" | "en";
 }
 
 const MULTI_INSTRUCTIONS = "Enter one or more option numbers or labels, separated by commas.";
@@ -56,8 +58,96 @@ export function parseMultiSelect(question: Question, text: string): Selection |
 	return { type: "options", values, labels, indices };
 }
 
+/** The one-message prompt for a multi-question ask. */
+export function batchPrompt(questions: Question[], language: "zh" | "en" = "en"): string {
+	const zh = language === "zh";
+	const lines = [zh ? "请一次性回答所有问题：" : "Answer all questions in one message:", ""];
+	questions.forEach((question, index) => {
+		lines.push(`${index + 1}. ${question.question}`);
+		if (question.options.length === 0) {
+			lines.push(zh ? "   文字" : "   text");
+			return;
+		}
+		const options = question.options.map((option, optionIndex) => `${optionIndex + 1}. ${option.label}`).join("  ");
+		lines.push(`   ${options}${question.multiSelect ? (zh ? "（可多选）" : " (multi)") : ""}`);
+	});
+	lines.push("", zh ? "格式：1: 2；2: A, B；3: 文字" : "Format: 1: 2; 2: A, B; 3: text");
+	return lines.join("\n");
+}
+
+/**
+ * Parse one batch reply. Each line/semicolon chunk starts with the question
+ * number; a chunk with no prefix makes the whole reply ambiguous.
+ */
+export function parseBatchAnswers(questions: Question[], text: string): Map<string, Selection> | undefined {
+	const entries = new Map<number, string>();
+	for (const chunk of text.split(/[\n;]+/)) {
+		const match = /^\s*(\d+)\s*[:.)-]\s*(.*)$/.exec(chunk);
+		if (!match) {
+			if (chunk.trim() !== "") return undefined;
+			continue;
+		}
+		const index = Number.parseInt(match[1] ?? "", 10);
+		if (index < 1 || index > questions.length) return undefined;
+		entries.set(index, (match[2] ?? "").trim());
+	}
+	const selections = new Map<string, Selection>();
+	for (const [index, question] of questions.entries()) {
+		const raw = entries.get(index + 1);
+		if (raw === undefined || raw === "") return undefined;
+		if (question.options.length === 0) {
+			selections.set(question.id, { type: "custom", text: raw });
+			continue;
+		}
+		if (question.multiSelect) {
+			const selection = parseMultiSelect(question, raw);
+			if (!selection) return undefined;
+			selections.set(question.id, selection);
+			continue;
+		}
+		const asNumber = Number.parseInt(raw, 10);
+		const optionIndex =
+			String(asNumber) === raw && asNumber >= 1 && asNumber <= question.options.length
+				? asNumber - 1
+				: question.options.findIndex((option) => option.label.toLowerCase() === raw.toLowerCase());
+		if (optionIndex >= 0) {
+			const option = question.options[optionIndex];
+			if (!option) return undefined;
+			selections.set(question.id, {
+				type: "options",
+				values: [option.label],
+				labels: [option.label],
+				indices: [optionIndex + 1],
+			});
+			continue;
+		}
+		if (!question.allowOther) return undefined;
+		selections.set(question.id, { type: "custom", text: raw });
+	}
+	return selections;
+}
+
+/** One batch editor, with one retry only when the format was not understood. */
+async function askViaBatch(ui: QuestionUI, questions: Question[], signal?: AbortSignal): Promise<AskResult> {
+	const language = ui.language?.() ?? "en";
+	const prompt = batchPrompt(questions, language);
+	const first = await ui.editor(prompt, "");
+	if (first === undefined) return cancelledResult(questions);
+	const parsed = parseBatchAnswers(questions, first);
+	if (parsed) return completedResult(questions, parsed);
+	if (signal?.aborted) return cancelledResult(questions);
+	const retry = await ui.editor(
+		`${prompt}\n\n${language === "zh" ? "格式不对，请按“1: 答案”重发。" : "Please reply again as “1: answer”."}`,
+		"",
+	);
+	if (retry === undefined) return cancelledResult(questions);
+	const again = parseBatchAnswers(questions, retry);
+	return again ? completedResult(questions, again) : cancelledResult(questions, collectAnswers(questions, new Map()));
+}
+
 /** Ask every question through forwarded dialogs, stopping on cancel or abort. */
 export async function askViaDialogs(ui: QuestionUI, questions: Question[], signal?: AbortSignal): Promise<AskResult> {
+	if (questions.length > 1) return askViaBatch(ui, questions, signal);
 	const selections = new Map<string, Selection>();
 	const opts = { signal };
 

package/extensions/question/tools.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { askHuman } from "../../lib/interaction.ts";
+import { askHuman, remoteLanguage } from "../../lib/interaction.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
@@ -25,6 +25,7 @@ function dialogUI(ctx: ExtensionContext): QuestionUI {
 		select: (title, options, opts) => ui.select(title, options, opts),
 		input: (title, placeholder, opts) => ui.input(title, placeholder, opts),
 		editor: (title, prefill) => ui.editor(title, prefill),
+		language: () => remoteLanguage(ctx) ?? "en",
 	};
 }
 

package/extensions/rewind/checklist.ts

@@ -152,6 +152,8 @@ export abstract class ChecklistScreen<T> implements Component {
 		const rows = this.rows();
 		if (rows.length === 0 && this.options.emptyLabel !== undefined) {
 			return dockListFrame({
+				theme: this.theme,
+				width: w,
 				header,
 				body: emptyState(this.theme, w, { label: this.options.emptyLabel }),
 				hint: this.hint(w),
@@ -172,6 +174,8 @@ export abstract class ChecklistScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary: clip(`  ${paint(this.theme, "meta", this.summaryText())}`, w),
 			body,

package/extensions/rewind/review-tui.ts

@@ -28,7 +28,7 @@ import { SELECTION_MARKS, type PathChange, type ReviewEntry } from "./paths.ts";
 
 /** Rows a diff screen shows when the terminal height is unknown. */
 const DIFF_DEFAULT_ITEMS = 20;
-/** Header, summary, blank, blank, hint, and blank rows around the diff. */
+/** Header, summary, blank, blank, hint, and closing-rule rows around the diff. */
 const DIFF_CHROME_ROWS = 6;
 
 /** Lines one wheel notch moves in the diff pane. */
@@ -294,6 +294,8 @@ export class ReviewDiffComponent implements Component {
 		if (body.length === 0) body.push(...emptyState(this.theme, w, { label: "No textual diff." }));
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary,
 			body,

package/extensions/rewind/rewind-tui.ts

@@ -79,6 +79,8 @@ export class RewindListComponent implements Component {
 
 		if (this.points.length === 0) {
 			return dockListFrame({
+				theme: this.theme,
+				width: w,
 				header,
 				body: emptyState(this.theme, w, { label: "No prompts on this branch yet." }),
 				hint: this.hint(w),
@@ -122,6 +124,8 @@ export class RewindListComponent implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header,
 			summary: clip(`  ${paint(this.theme, "meta", `${count}${SEPARATORS.item}newest first`)}`, w),
 			body,

package/extensions/session-bus/README.md

@@ -0,0 +1,247 @@
+# session-bus — coordinate parallel Pi sessions
+
+A local coordination bus for Pi sessions on the same machine and repository.
+Sessions discover each other, exchange short messages and events, consume an
+inbox, and claim paths before editing. Delivery is pull-based, and a session can
+arm an inbox watch to be told about new mail: a report at its next turn, or —
+with `wake` — one raised turn as soon as the agent is idle, including right after
+a running turn settles. No network service, and no hidden context.
+
+<img src="../../assets/session.png" alt="The /sessions screen: a counts summary, session rows with unread and claim counts, and the focused session's cwd, claims, and identity" width="100%">
+
+```bash
+pi --extension ./extensions/session-bus   # load just this extension
+pi -e .                                   # load the whole package
+```
+
+## What it does
+
+- Registers one `session` tool and the `/sessions` command; in the TUI the command
+  opens a live board with Sessions, Inbox, and Claims scopes.
+- Stores one record per session, one file per message, and one file per claim
+  under `<agent-dir>/session-bus/<repo-key>/`; the key is the repository’s common
+  git directory, so worktrees meet on one bus.
+- A TUI session joins on `session_start`; RPC, JSON, print, and WeChat peer
+  sessions join only when the tool or `/sessions` is used. A subagent or a phone
+  peer does not appear merely because the package is loaded.
+- A heartbeat keeps a joined session visible; a stale session is pruned after ten
+  minutes, its claims are released, and inbox messages expire after 24 hours.
+- An armed inbox watch polls this session’s own inbox directory and queues what
+  arrived. It announces; `inbox` still consumes.
+- Writes are atomic and private to the OS user; there is no server, no network,
+  and no cross-user authorization.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/sessions` | Open the board: `Tab` cycles Sessions, Inbox, and Claims. `Enter` opens the focused row, `w` arms or disarms this session's inbox watch, and in Claims `x` releases a claim you hold after a y/N confirmation. A non-TUI caller prints the listing and joins. |
+| `/sessions name <label>` | Name this session for the bus and for Pi. The label is unique among active sessions, and it becomes the session name the footer shows and `/resume` lists. |
+| `/sessions watch` | Report new mail at this session’s next turn. |
+| `/sessions watch wake` | Report new mail, and raise one turn as soon as the agent is idle — including right after a running turn settles. |
+| `/sessions watch off` | Stop the inbox watch. |
+| `/sessions help` | Show the command usage. |
+
+Labels are how another session addresses you. Name one by the outcome it owns
+(`billing-core`, `integrator`, `verify-billing`), not by a layer or a role;
+duplicate labels get a short id suffix automatically.
+
+Naming also sets Pi's session name, so the footer's `[label]` and `/resume` agree
+with the bus. Because the bus derives a joining session's label from that name, a
+named session comes back under the same label after a resume.
+
+The tool's `name` action is the same rename from the model's side, so a lead can
+name itself once the roster card has told it how — the one line of the card it
+cannot get any other way.
+
+## Tools
+
+| Action | Inputs | Result |
+|---|---|---|
+| `status` | — | Active sessions with unread counts, claims, and this session’s identity, plus `units n/m` for the newest split in this repository. Prunes stale records. |
+| `send` | `to`, `text`, optional `kind`, optional `paths` | Writes one message per recipient. `to: "*"` is only valid with `kind: "event"`. |
+| `inbox` | optional `limit` | Returns and deletes up to `limit` messages, oldest first (default 20, max 50). |
+| `claim` | `paths` | Claims repository-relative files or directory prefixes; returns conflicts with their owner. |
+| `release` | `paths` | Removes claims owned by this session; reports paths owned by someone else. |
+| `join` | `team`, `unit` | Claims every path of one unit in an approved split. Needs the plan's `## Team` section, so it refuses a plan that was never split, and needs `plan.split` on. Idempotent: joining twice is the same claims. |
+| `leave` | optional `team`, `unit` | Releases that unit's paths, or every claim this session holds when neither is given. Never gated by the switch. |
+| `watch` | optional `wake`, optional `stop` | Arms this session’s inbox watch, or turns it off with `stop`. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; omitting it keeps an armed watch’s mode. |
+| `name` | `label` | Renames this session on the bus and in Pi — the same path as `/sessions name`, with the same uniqueness rule, so the footer and `/resume` agree with the record peers address. An empty label is refused rather than keeping the old one, and a label a live session holds is refused with its owner named. The result reports the label the bus settled on. |
+
+Message kinds are `message` (default), `event`, `ask`, and `handoff`. An `ask` is
+still a message: it does not block or wait for a reply. Text is capped at 4,000
+characters. Paths resolve against the caller’s working directory and are stored
+relative to its repository root; a path outside the repository is refused.
+
+A claim is all-or-nothing: if one path conflicts, nothing is claimed. A claim on
+a directory conflicts with claims below it and above it, so `src/api` and
+`src/api/routes.ts` cannot be held by different sessions. There is no `force`
+takeover; wait for the owner, ask it to release, or let the session expire.
+
+`wake` is the mode, not an arm-time switch: `/sessions watch wake` raises a turn
+for a watch that was reporting at the next turn, and `/sessions watch` — or
+`wake: false` — sets it back. The board’s `w` only arms and disarms, and it arms
+a plain watch; set `wake` with the command or the tool. Nothing arms on
+`session_start`; a session that never asks stays pull-only.
+
+## Parallel workflow
+
+1. The user names each session (`/sessions name`), and the contract (OpenAPI,
+   schema, or types) is written before parallel work starts.
+2. When the plan was approved with a split, each session `join`s its unit once —
+   that claims every path the unit owns, so nobody types a path list by hand.
+   Otherwise each session claims its paths. Then it implements its side.
+3. A contract, build, or test change goes out as an event:
+   `session({action:"send", to:"*", kind:"event", text:"contract v2: ..."})`.
+4. Other sessions consume `inbox` at the start of their next turn, or arm
+   `session({action:"watch", wake:true})` so a message raises their turn as soon
+   as they are idle; a wake that arrives mid-turn is raised once that run
+   settles, never pushed into the running turn.
+5. The lead merges the worktrees and runs the project’s full check.
+
+The bus carries coordination, not authority. The plan, todo list, contract, and
+git branch remain the source of truth.
+
+### Joining a split
+
+A plan approval can write a `## Team` table into the plan file, which is where a
+joining session reads its unit from:
+
+```text
+session({action:"join", team:"2026-11-04-1802-billing", unit:"core"})
+→ Joined 2026-11-04-1802-billing/core: claimed src/billing/core.
+```
+
+`team` is the plan file's stem, so two plans in one repository never share a team.
+The unit's paths come from the table the same module wrote, so a hand-edited or
+stale section is refused rather than half-read; an unknown unit names the units
+that exist; a taken unit names its holder; and with `plan.split` off `join`
+refuses and names the settings row. `status` reports `units 1/2 joined` with the
+holder of each unit, which is how a lead answers "has everyone started?" without
+messaging anyone.
+
+A claim belongs to the live session, not to a branch: a session that exits
+releases its unit, so a restarted owner joins again (the join is idempotent), and
+a crashed one frees the unit when its record goes stale. That is why the roster
+card asks you to name each session — an unnamed one joins under its working
+directory's name, which says nothing about the unit it holds.
+
+## Behaviour by mode
+
+| Mode | Behaviour |
+|---|---|
+| `tui` | Joins automatically on `session_start`. `/sessions` opens the board: sessions, this session's unread mail, and every claim, with `Tab` between them. |
+| `rpc`, `json`, `print` | Does not join automatically. The first `session` call or `/sessions` joins; this is how a subagent or an RPC-driven session opts in. |
+| WeChat peer | Same as `rpc`: the peer is a separate AgentSession in the bridge process and joins only on explicit use. Messages are read by that peer’s model; the bridge does not forward them to the phone. |
+
+Every mode can arm the inbox watch; the notice is a visible transcript message, so
+a `wake` raises that session’s own turn, not a phone notification.
+
+The TUI opens the board; RPC, JSON, and print print the compact listing. The board
+changes only this session's own state: `w` toggles its watch and `x` releases a
+claim it holds. Mail is previewed, not consumed — `session inbox` consumes it —
+and no view shows another session's inbox or releases its claims.
+
+## Configuration
+
+None in v1. The heartbeat (10 s), watch poll (2 s), session TTL (10 min), message
+TTL (24 h), text cap, inbox limit, and preview cap are constants in the extension.
+The bus lives under the agent directory, not the project, so it is never committed.
+
+## Limitations
+
+- **Same machine, same OS user.** Any process with that user’s file access can
+  read or write the bus; there is no authentication between sessions.
+- **Pull-based by default.** A message does not wake a session that did not arm
+  its inbox watch. Agents must call `inbox` at coordination points.
+- **Arming is per session and session-only.** It survives neither a resume nor a
+  new process; unread mail is previewed once more after `/resume`.
+- **The board acts on your own state only.** `w` arms or disarms this session's
+  inbox watch and `x` releases a claim it holds. Mail is a preview, not a consume:
+  the board never deletes a message, never marks one reported, and never touches a
+  peer's inbox or claim.
+- **Two armed peers can ping-pong.** Each reply wakes the other as soon as it is
+  idle. A wake raises one turn per burst, and `inbox` consumes, so the loop needs
+  both sides to keep replying; the answer is to disarm one of them.
+- **No broadcast history.** A broadcast reaches the sessions active at send time;
+  a session that joins later does not receive it.
+- **No forced claims.** A crashed owner blocks its paths until the session TTL
+  expires. This is deliberate; stealing a claim is worse than waiting.
+- **Bounded by TTL.** An idle session with a stopped heartbeat is pruned after
+  ten minutes; its record, its claims, and an inbox directory left empty go with
+  it, and its unread mail expires after 24 hours.
+- **A message file that does not parse is dropped.** The board's read never
+  consumes mail, but it does delete a file it cannot validate, so a truncated
+  message cannot linger on the bus.
+- **No network.** It is not a distributed bus and does not synchronize machines.
+
+## Design notes
+
+- **Common git dir as the key.** `git rev-parse --git-common-dir` gives all
+  worktrees of one repository the same bus; `--show-toplevel` normalizes claim
+  paths within each worktree. Non-repository sessions fall back to their cwd.
+- **One path, one claim.** The cwd is canonicalized at join and every claim or
+  release is re-keyed by its real target, so a working directory reached through
+  a symlink still resolves inside its own repository, a link inside the repository
+  and the file it names are the same claim, and a link that leaves the repository
+  is refused. The automatic label is the real basename of the cwd, so a session
+  started through a link named differently is named after the directory it is
+  actually in. An absolute path argument that sits outside the repository is
+  refused before it is re-keyed, and a relative one whose target leaves the
+  repository is refused by the re-keying itself.
+- **One file per item.** Sessions never append to a shared registry: each session
+  writes its own record, each message is its own file, and a claim is a temp file
+  hard-linked into place — an exclusive create no reader can see half-written.
+  This avoids a cross-process lock for the common path.
+- **Lazy join.** Loading a package extension must not make every subagent and
+  WeChat peer a team member. Auto-join only in `tui`; every other mode opts in by
+  using the tool or command.
+- **Sanitized at the boundary.** Messages are model-authored and are sanitized
+  before rendering, like other untrusted text in the transcript.
+- **Poll, not `fs.watch`.** The inbox watch reads this session's inbox directory
+  with one `readdir` every 2 s, the same trade `watch` makes for a file tail, so
+  it does not depend on a platform's event API or a filename in the event. Only
+  an armed session polls.
+- **Read the board, prune on the next call.** The open board polls a read-only
+  `snapshot()` and `peek()` that hide a session past the TTL, a claim held by one,
+  and consume nothing. The physical prune, and the claim release that goes with
+  it, happen on the next `status` or `claim` call — which is the call that reader
+  is about to make.
+- **Release by the stored path.** A claim is stored relative to the repo root of
+  the session that took it, so releasing one resolves nothing: re-resolving it
+  against a cwd below that root would target `src/src/api`. The screen refuses a
+  peer's claim before asking the store, which checks the owner again.
+- **A pane is a log or prose.** `DetailContents.text` wraps at the render width
+  and `tail: false` opens it at the top, so a message reads as prose while a job
+  log keeps following its tail.
+- **The notice reuses the shared report channel.** `lib/report.ts` already owns
+  whether an outcome may raise a turn; the bus supplies the pending mail and the
+  text, and bytefly renders the notice like a `job` or `watch` one.
+
+## Pi integration
+
+| Point | Detail |
+|---|---|
+| Tools | `session` — one action-shaped tool; `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: false`, `executionMode: "sequential"`. |
+| Commands | `/sessions` (board in `tui`, listing elsewhere), `/sessions name <label>`, `/sessions watch [off\|wake]`, `/sessions help`. |
+| UI | `tui` mounts `SessionListComponent` through `withPolledScreen` (rails suppressed, a 1 s read-only poll of `snapshot()` + `peek()`); every other mode prints through `ctx.ui.notify`. No status chip, so the watch never changes the footer. |
+| Events | `session_start` resolves the repository and joins a TUI session and arms the mail trigger; `before_agent_start` reports queued non-wake mail at the next turn, `agent_settled` retries a wake the run suppressed, and `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
+| State | Files under `<agent-dir>/session-bus/<repo-key>/`; nothing in the session branch. The armed watch is session-only. `/resume` re-registers the same session id. |
+| Lifecycle | The factory only registers. The runtime starts on `session_start`; heartbeat, watch ticker, and cleanup belong to it. Disabling `session-bus` through `PI_DISABLED_EXTENSIONS` registers nothing. |
+| Mode | Uses `ctx.mode` to decide auto-join and whether `/sessions` mounts the board; `askHuman` is not involved and no status chip is published. |
+
+## File map
+
+| File | Responsibility |
+|---|---|
+| `index.ts` | Disable guard, registration, the pending-report channel, and the session hooks. |
+| `runtime.ts` | Lifecycle, repo key, lazy join, heartbeat, inbox watch and its poll, operations. |
+| `store.ts` | Atomic JSON files, inbox, peek, claims, pruning. |
+| `protocol.ts` | Pure labels, targets, paths, validation, conflict rules. |
+| `tui.ts` | The `/sessions` board, its scopes, and the pane over one row; the row grammar is in `rows.ts`. |
+| `rows.ts` | The session/claim/message row builders and summaries shared by the board and the transcript. |
+| `result.ts` | The `session` tool's expanded result block and its collapsed line. |
+| `notice.ts` | The mail notice's model text and renderer details. |
+| `tools.ts` | The `session` tool and its renderer. |
+| `commands.ts` | `/sessions`. |
+| `format.ts` | Model-facing listing and result text. |

package/extensions/session-bus/commands.ts

@@ -0,0 +1,165 @@
+/**
+ * The `/sessions` command.
+ *
+ * In the TUI, bare `/sessions` opens the live board: `Tab` cycles Sessions,
+ * Inbox, and Claims, and `w`/`x` act on this session's own watch and claims.
+ * Every other mode prints the compact listing, because there is no dock to mount
+ * the screen in. `name <label>` gives this session a stable target and `watch
+ * [off|wake]` controls the inbox watch from either surface.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "../../lib/errors.ts";
+import { sanitizeLine } from "../../lib/format.ts";
+import { withPolledScreen } from "../../lib/screen-session.ts";
+import { formatStatus, formatWatch } from "./format.ts";
+import { COMMAND_NAME } from "./protocol.ts";
+import type { SessionBus } from "./runtime.ts";
+import { SessionListComponent } from "./tui.ts";
+
+const USAGE = "/sessions [name <label>|watch [off|wake]]";
+const WATCH_MODES = ["off", "wake"];
+
+/** How often the open board re-reads the bus. */
+const BOARD_POLL_MS = 1_000;
+
+/**
+ * One board read at a time, shared by the open screen's poll and its watch verb.
+ *
+ * A read that is still running is skipped rather than queued, and a failed read
+ * leaves the last board on screen; the bus's own heartbeat keeps this session's
+ * record fresh, so a poll never has to write. Both reads are read-only: the
+ * snapshot neither prunes nor refreshes, and the peek neither consumes nor marks.
+ */
+function createBoardReader(bus: SessionBus): (screen: SessionListComponent) => Promise<void> {
+	let busy = false;
+	return async (screen) => {
+		if (busy) return;
+		busy = true;
+		try {
+			const [status, messages] = await Promise.all([bus.snapshot(), bus.peek()]);
+			screen.setBoard({ status, messages });
+		} catch {
+			// Best-effort: the next tick tries again, and the board keeps its last read.
+		} finally {
+			busy = false;
+		}
+	};
+}
+
+/** Open the TUI board, and resolve when it closes. */
+async function openBoard(pi: ExtensionAPI, ctx: ExtensionCommandContext, bus: SessionBus): Promise<void> {
+	await bus.start(ctx);
+	const [status, messages] = await Promise.all([bus.snapshot(), bus.peek()]);
+	const first = { status, messages };
+	let read: ((screen: SessionListComponent) => Promise<void>) | undefined;
+	await withPolledScreen(
+		pi,
+		ctx,
+		(screen) => {
+			const reader = createBoardReader(bus);
+			read = reader;
+			// The verbs repaint the board they belong to; their callbacks only run after
+			// construction, so a holder keeps the wiring one-directional.
+			const holder: { screen?: SessionListComponent } = {};
+			const component = new SessionListComponent({
+				latest: () => first,
+				theme: screen.theme,
+				callbacks: {
+					toggleWatch: async (armed) => {
+						const watching = await bus.watch({ stop: armed });
+						if (holder.screen) await reader(holder.screen);
+						return formatWatch(watching);
+					},
+					releaseClaim: async (path) => {
+						const released = await bus.releaseStored(path);
+						if (holder.screen) await reader(holder.screen);
+						const name = sanitizeLine(path);
+						return released ? `Released ${name}.` : `${name} is no longer yours.`;
+					},
+				},
+				onClose: screen.close,
+				requestRender: screen.requestRender,
+				viewportRowsSource: screen.viewportRows,
+			});
+			holder.screen = component;
+			return component;
+		},
+		{ pollMs: BOARD_POLL_MS, poll: (component) => void read?.(component) },
+	);
+}
+
+async function open(ctx: ExtensionCommandContext, pi: ExtensionAPI, bus: SessionBus): Promise<void> {
+	try {
+		if (ctx.mode === "tui") {
+			await openBoard(pi, ctx, bus);
+			return;
+		}
+		await bus.start(ctx);
+		ctx.ui.notify(formatStatus(await bus.status()), "info");
+	} catch (error) {
+		ctx.ui.notify(`Session bus: ${messageOf(error)}`, "warning");
+	}
+}
+
+export function registerCommands(pi: ExtensionAPI, bus: SessionBus): void {
+	pi.registerCommand(COMMAND_NAME, {
+		description: "List parallel Pi sessions, their unread counts and claims; name this session",
+		getArgumentCompletions: (prefix) => {
+			const text = prefix.trimStart();
+			if (text.includes(" ")) return null;
+			const options = ["name", "help", "watch"].filter((value) => value.startsWith(text));
+			return options.length > 0 ? options.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args, ctx) => {
+			const [sub = "", ...rest] = args.trim().split(/\s+/).filter(Boolean);
+			if (sub === "help") {
+				ctx.ui.notify(
+					`/sessions — open the bus board\n/sessions name <label> — name this session\n` +
+						`/sessions watch [off|wake] — report new mail at the next turn, or raise one\n\n${USAGE}`,
+					"info",
+				);
+				return;
+			}
+			if (sub === "watch") {
+				const mode = rest[0] ?? "";
+				if (mode !== "" && !WATCH_MODES.includes(mode)) {
+					ctx.ui.notify(`Unknown watch mode "${mode}". Usage: /sessions watch [off|wake]`, "warning");
+					return;
+				}
+				try {
+					await bus.start(ctx);
+					const status = await bus.status();
+					const watching = await bus.watch({ stop: mode === "off", wake: mode === "wake" });
+					ctx.ui.notify(formatWatch(watching, status.me.label), "info");
+				} catch (error) {
+					ctx.ui.notify(`Session bus: ${messageOf(error)}`, "warning");
+				}
+				return;
+			}
+			if (sub === "name") {
+				const label = rest.join(" ").trim();
+				if (!label) {
+					ctx.ui.notify("Usage: /sessions name <label>", "warning");
+					return;
+				}
+				try {
+					await bus.start(ctx);
+					await bus.status();
+					const renamed = await bus.rename(label);
+					// The bus validates first, so a rejected label leaves both names alone.
+					pi.setSessionName(renamed);
+					ctx.ui.notify(`This session is now named "${renamed}".`, "info");
+				} catch (error) {
+					ctx.ui.notify(`Session bus: ${messageOf(error)}`, "warning");
+				}
+				return;
+			}
+			if (sub !== "") {
+				ctx.ui.notify(`Unknown sessions command "${sub}". Try ${USAGE}.`, "warning");
+				return;
+			}
+			await open(ctx, pi, bus);
+		},
+	});
+}