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

package/extensions/rewind/{review-tui.ts → view/review-tui.ts}

@@ -13,18 +13,18 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Component, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { clip } from "../../lib/tui/columns.ts";
-import { detailBlockRows, dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
-import { sanitizeLine } from "../../lib/format.ts";
-import { fitRows, formatRange, isCloseKey, wheelDelta } from "../../lib/tui/cursor.ts";
-import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { LinePane } from "../../lib/tui/line-pane.ts";
-import { checkbox, emptyState, listRow } from "../../lib/tui/rows.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
-import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
+import { clip } from "../../../lib/tui/columns.ts";
+import { detailBlockRows, dockListFrame, screenHint, type ViewportRowsSource } from "../../../lib/tui/chrome.ts";
+import { sanitizeLine } from "../../../lib/format.ts";
+import { fitRows, formatRange, isCloseKey, wheelDelta } from "../../../lib/tui/cursor.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
+import { LinePane } from "../../../lib/tui/line-pane.ts";
+import { checkbox, emptyState, listRow } from "../../../lib/tui/rows.ts";
+import { titleRule } from "../../../lib/tui/rules.ts";
+import { paint, type TuiRole } from "../../../lib/tui/tokens.ts";
 import { ChecklistScreen } from "./checklist.ts";
-import { formatReviewDetail, formatReviewEntryCounts, formatReviewSummary } from "./format.ts";
-import { SELECTION_MARKS, type PathChange, type ReviewEntry } from "./paths.ts";
+import { formatReviewDetail, formatReviewEntryCounts, formatReviewSummary } from "../text/format.ts";
+import { SELECTION_MARKS, type PathChange, type ReviewEntry } from "../text/paths.ts";
 
 /** Rows a diff screen shows when the terminal height is unknown. */
 const DIFF_DEFAULT_ITEMS = 20;

package/extensions/rewind/{rewind-tui.ts → view/rewind-tui.ts}

@@ -10,15 +10,15 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
-import { detailBlockRows, dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
-import { clip } from "../../lib/tui/columns.ts";
-import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { emptyState, listRow } from "../../lib/tui/rows.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import { formatRewindDetail, formatRewindParts } from "./format.ts";
-import type { RewindPoint } from "./timeline.ts";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../../lib/tui/cursor.ts";
+import { detailBlockRows, dockListFrame, screenHint, type ViewportRowsSource } from "../../../lib/tui/chrome.ts";
+import { clip } from "../../../lib/tui/columns.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
+import { emptyState, listRow } from "../../../lib/tui/rows.ts";
+import { titleRule } from "../../../lib/tui/rules.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { formatRewindDetail, formatRewindParts } from "../text/format.ts";
+import type { RewindPoint } from "../state/timeline.ts";
 
 export interface RewindListOptions {
 	points: RewindPoint[];
@@ -57,7 +57,7 @@ export class RewindListComponent implements Component {
 		}
 		const count = this.points.length;
 		if (navigateList(data, this.cursor, count)) return;
-		if (matchesKey(data, Key.enter) || data === "r") {
+		if (matchesKey(data, Key.enter)) {
 			const point = this.points[this.cursor.selected];
 			if (point) this.options.onClose(point);
 		}
@@ -139,6 +139,12 @@ export class RewindListComponent implements Component {
 
 	/** The key-hint row, with the primary action in the accent role. */
 	private hint(width: number): string {
-		return screenHint(this.theme, width, ["Esc close", { text: "Enter choose", color: "accent" }, "↑/↓ or k/j select"]);
+		return screenHint(this.theme, width, [
+			"Esc close",
+			{ text: "Enter choose", color: "accent" },
+			"↑/↓ or k/j select",
+			"PgUp/PgDn",
+			"g/G or Home/End",
+		]);
 	}
 }

package/extensions/rewind/{status.ts → view/status.ts}

@@ -8,10 +8,10 @@
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import type { RewindConfig } from "./config.ts";
-import { userMessagesFromBranch } from "./timeline.ts";
+import { GLYPHS, STATUS_KEYS } from "../../../lib/tui/glyphs.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import type { RewindConfig } from "../config/config.ts";
+import { userMessagesFromBranch } from "../state/timeline.ts";
 
 const STATUS_KEY = STATUS_KEYS.rewind;
 const STATUS_GLYPH = GLYPHS.rewind;

package/extensions/session-bus/commands.ts

@@ -1,25 +1,23 @@
 /**
- * The `/sessions` command.
+ * The `/sessions` command: one act, no arguments.
  *
- * 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.
+ * In the TUI it 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. Reading is
+ * not joining, so the board is empty until this session joins — and a command
+ * context cannot name a session, so the join is `session({action:"join"})`,
+ * `/team join [<label>]`, or the board's `w`.
  */
 
 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 { formatJoin, formatStatus } 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;
 
@@ -48,7 +46,7 @@ function createBoardReader(bus: SessionBus): (screen: SessionListComponent) => P
 }
 
 /** Open the TUI board, and resolve when it closes. */
-async function openBoard(pi: ExtensionAPI, ctx: ExtensionCommandContext, bus: SessionBus): Promise<void> {
+async function openSessionsScreen(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 };
@@ -67,9 +65,10 @@ async function openBoard(pi: ExtensionAPI, ctx: ExtensionCommandContext, bus: Se
 				theme: screen.theme,
 				callbacks: {
 					toggleWatch: async (armed) => {
-						const watching = await bus.watch({ stop: armed });
+						// The board's toggle is the same act as a join, so it says the same thing.
+						const joined = await bus.join({ listen: !armed });
 						if (holder.screen) await reader(holder.screen);
-						return formatWatch(watching);
+						return formatJoin(joined.label, joined.watching);
 					},
 					releaseClaim: async (path) => {
 						const released = await bus.releaseStored(path);
@@ -92,7 +91,7 @@ async function openBoard(pi: ExtensionAPI, ctx: ExtensionCommandContext, bus: Se
 async function open(ctx: ExtensionCommandContext, pi: ExtensionAPI, bus: SessionBus): Promise<void> {
 	try {
 		if (ctx.mode === "tui") {
-			await openBoard(pi, ctx, bus);
+			await openSessionsScreen(pi, ctx, bus);
 			return;
 		}
 		await bus.start(ctx);
@@ -104,61 +103,10 @@ async function open(ctx: ExtensionCommandContext, pi: ExtensionAPI, bus: Session
 
 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;
-			}
+		description: "Open the bus board: sessions, unread mail, and path claims",
+		// One command, one act: an argument is not a sub-command, so it is ignored
+		// rather than warned about — the board is what the user asked for.
+		handler: async (_args, ctx) => {
 			await open(ctx, pi, bus);
 		},
 	});

package/extensions/session-bus/format.ts

@@ -7,8 +7,15 @@
 
 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 {
+/**
+ * The last few characters of a peer's id, as the transcript shows it.
+ *
+ * Neutralized like every other peer-supplied field, and deliberately not
+ * `lib/session-label.ts`'s `shortId`: that one keeps the id's alphanumerics to
+ * build a default *label*, while this one is the id's own tail, sanitized for a
+ * row.
+ */
+export function idSuffix(id: string): string {
 	return sanitizeLine(id.slice(-6));
 }
 
@@ -22,50 +29,35 @@ export function formatStatus(status: SessionStatus): string {
 		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}`;
+		return `- ${label} (${idSuffix(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)})`,
+		`You: ${sanitizeLine(status.me.label)} (${idSuffix(status.me.id)})${status.onBus ? "" : " \u00b7 not on the bus yet \u2014 `session join` puts you on it"}`,
 	].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.
+ * The join result: the label peers address, and whether mail will reach this session.
+ *
+ * One sentence for one act, because `join` is one action — the name and the watch are
+ * two facts about the same decision, and a reader that had to ask twice would be reading
+ * a bus the user is not supposed to operate.
  */
-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}.`;
+export function formatJoin(label: string, watching: { armed: boolean; wake: boolean }): string {
+	const who = `On the bus as "${sanitizeLine(label)}"`;
+	if (!watching.armed) return `${who}, not listening: mail waits in the inbox.`;
 	return watching.wake
-		? `Inbox watch on${owner}: a new message raises one turn.`
-		: `Inbox watch on${owner}: new messages appear at your next turn.`;
+		? `${who}, listening: a new message raises one turn.`
+		: `${who}, listening: new messages appear at your next turn.`;
 }
 
 /** One consumed inbox, oldest first. */
@@ -95,26 +87,11 @@ export function formatClaim(claimed: readonly string[], conflicts: readonly Clai
 	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)}).`);
+		lines.push(`${sanitizeLine(conflict.path)} is owned by ${owner} (${idSuffix(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[] = [];

package/extensions/session-bus/index.ts

@@ -1,13 +1,15 @@
 /**
  * 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.
+ * No session joins on start: it joins through `join`, through the first action
+ * that makes it addressable, or through `w` on its own board, in any mode.
+ * `/sessions` and `status` only read, so a fresh board is empty and a peer never
+ * appears merely because the package loaded. 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
  */
@@ -17,6 +19,7 @@ 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 { registerJoinRequests } from "./join-request.ts";
 import { createSessionBus, type SessionBus } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 import { mailNotice } from "./notice.ts";
@@ -42,6 +45,9 @@ export default function sessionBus(pi: ExtensionAPI, deps: SessionBusDeps = {}):
 
 	registerTools(pi, bus);
 	registerCommands(pi, bus);
+	// `board` and `team` join this session through one request: their commands cannot call
+	// a tool, and the user's surface for the team is theirs, not this extension's.
+	registerJoinRequests(pi, bus);
 
 	registerPendingChannel(pi, {
 		reporter,

package/extensions/session-bus/join-request.ts

@@ -0,0 +1,40 @@
+/**
+ * The join request, answered.
+ *
+ * `board` and `team` sit above the bus: `/board`, `/team join`, and a card write all
+ * put this session on the team, and none of them may import this extension. A *tool*
+ * context could reach the `session` tool and an `ExtensionCommandContext` cannot —
+ * the same limit `lib/plan-entry.ts` works around for plan mode — so the request
+ * travels on `pi.events` and this module answers it with the runtime's own `join`.
+ *
+ * The answer always comes: every path here ends in `respond`, including a failure, so
+ * a caller never waits on a listener that threw. The label also becomes Pi's session
+ * name, because a team label and the footer have to agree.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "../../lib/errors.ts";
+import { type JoinResult, TEAM_JOIN_REQUEST, type TeamJoinRequest } from "../../lib/session-tool.ts";
+import type { SessionBus } from "./runtime.ts";
+
+export function registerJoinRequests(pi: ExtensionAPI, bus: SessionBus): void {
+	pi.events.on(TEAM_JOIN_REQUEST, (data) => {
+		const request = data as TeamJoinRequest | undefined;
+		if (!request || typeof request.respond !== "function") return;
+		void answer(request);
+	});
+
+	async function answer(request: TeamJoinRequest): Promise<void> {
+		let result: JoinResult;
+		try {
+			await bus.start(request.ctx);
+			const joined = await bus.join(request.input);
+			// One identity: the bus's label is also the name Pi's footer and `/resume` show.
+			if (request.input.label !== undefined) pi.setSessionName(joined.label);
+			result = { ok: true, label: joined.label, watching: joined.watching };
+		} catch (error) {
+			result = { ok: false, error: messageOf(error) };
+		}
+		request.respond(result);
+	}
+}

package/extensions/session-bus/mail-watch.ts

@@ -0,0 +1,134 @@
+/**
+ * The armed inbox watch: polling this session's own inbox and the queue of mail
+ * that arrived and has not been reported yet.
+ *
+ * It announces and never consumes: `inbox` keeps sole ownership of deleting mail,
+ * so a wake cannot eat a message the model did not read. Nothing here knows about
+ * the store, the repository, or the transcript — the runtime supplies one read-only
+ * peek and the timer, and the extension's reporter supplies `onWake`.
+ *
+ * Polling rather than `fs.watch`, like the `watch` extension's tail: one readdir on
+ * this session's own directory stands in for a platform event API.
+ */
+
+import type { RepeatTimer } from "../../lib/timer.ts";
+import type { BusMessage } from "./types.ts";
+
+export interface MailWatchOptions {
+	/** This session's unread mail, read-only: nothing is consumed or marked. */
+	peek(): Promise<BusMessage[]>;
+	/** The repeating timer behind the poll. */
+	interval: RepeatTimer;
+	/** Poll interval; 0 disables the ticker (tests). */
+	watchMs: number;
+}
+
+/** Whether the watch is on, and whether it raises a turn. */
+export interface WatchingState {
+	armed: boolean;
+	wake: boolean;
+}
+
+export interface MailWatch {
+	/** Arm or disarm this session's inbox watch. */
+	watch(input: { wake?: boolean; stop?: boolean }): Promise<WatchingState>;
+	/** The current state, for the status line. */
+	state(): WatchingState;
+	/** Whether the armed watch asked for a triggered turn; the settle retry reads it. */
+	wantsWake(): boolean;
+	/** Read the inbox without consuming it, queueing what is new; no-op when unarmed. */
+	poll(): Promise<void>;
+	/** Mail that arrived and has not been reported yet, oldest first. */
+	pending(): BusMessage[];
+	/** Drop mail from the pending queue, once reported or consumed. */
+	markReported(ids: readonly string[]): void;
+	/** Release the ticker and the queue, on shutdown. */
+	stop(): void;
+	set onWake(callback: (() => void) | undefined);
+}
+
+export function createMailWatch(options: MailWatchOptions): MailWatch {
+	const { peek, interval, watchMs } = options;
+
+	let armed = false;
+	let wake = false;
+	let stopTicker: (() => void) | undefined;
+	let pendingMail: BusMessage[] = [];
+	/** Ids already queued, reported, or consumed; a broadcast shares one id. */
+	let reported = new Set<string>();
+	let onWake: (() => void) | undefined;
+
+	function dropFromPending(ids: ReadonlySet<string>): void {
+		pendingMail = pendingMail.filter((message) => !ids.has(message.id));
+	}
+
+	function markReported(ids: readonly string[]): void {
+		for (const id of ids) reported.add(id);
+		dropFromPending(new Set(ids));
+	}
+
+	/**
+	 * Queue what arrived since the last poll, once, and wake a turn when this
+	 * session asked for one.
+	 *
+	 * The reported set is narrowed to the mail still on disk, so it is bounded by
+	 * the unread count rather than by the session's whole history; an id is unique
+	 * for good, so a message that was consumed can never be queued again.
+	 */
+	async function pollOnce(): Promise<void> {
+		if (!armed) return;
+		const mail = await peek();
+		const unread = new Set(mail.map((message) => message.id));
+		reported = new Set([...reported].filter((id) => unread.has(id)));
+		// A message that expired or was consumed leaves the queue with its file.
+		pendingMail = pendingMail.filter((message) => unread.has(message.id));
+		const queued = new Set(pendingMail.map((message) => message.id));
+		const fresh = mail.filter((message) => !reported.has(message.id) && !queued.has(message.id));
+		if (fresh.length === 0) return;
+		pendingMail = [...pendingMail, ...fresh];
+		if (wake) onWake?.();
+	}
+
+	function disarm(): void {
+		stopTicker?.();
+		stopTicker = undefined;
+		armed = false;
+		wake = false;
+		pendingMail = [];
+	}
+
+	async function watch(input: { wake?: boolean; stop?: boolean }): Promise<WatchingState> {
+		if (input.stop) {
+			disarm();
+			return { armed: false, wake: false };
+		}
+		if (!armed) {
+			armed = true;
+			wake = input.wake === true;
+			await pollOnce();
+			if (watchMs > 0) stopTicker = interval(watchMs, () => void pollOnce().catch(() => {}));
+			return { armed, wake };
+		}
+		// The mode is a setting, not an arm-time flag: an explicit `wake` changes it
+		// under a queued notice, and an omitted one keeps it, so bare `watch` never
+		// demotes an armed session.
+		if (input.wake !== undefined) wake = input.wake;
+		// Asking for wake over mail already queued is a request for that burst too;
+		// mid-turn it is suppressed here and retried once the run settles.
+		if (wake && pendingMail.length > 0) onWake?.();
+		return { armed, wake };
+	}
+
+	return {
+		watch,
+		state: () => ({ armed, wake }),
+		wantsWake: () => armed && wake,
+		poll: pollOnce,
+		pending: () => [...pendingMail],
+		markReported,
+		stop: disarm,
+		set onWake(callback: (() => void) | undefined) {
+			onWake = callback;
+		},
+	};
+}

package/extensions/session-bus/notice.ts

@@ -20,10 +20,30 @@ const MAX_NOTICE_LINES = 5;
 /** A message body is clipped to this many characters in a preview. */
 const MAX_PREVIEW = 200;
 
+/**
+ * A handoff is clipped far less generously, because it is an instruction and not a
+ * notification: the card, its paths, and the step to take all sit past the point
+ * where a message preview would have stopped. The inbox still holds the full text.
+ */
+const HANDOFF_PREVIEW = 800;
+
+/** What a waking turn is told to do with a handoff: work it, not acknowledge it. */
+const HANDOFF_HINT =
+	"A handoff is work you now own: run `session inbox`, record the card's plan, and start — do not just acknowledge it.";
+
+/** `1 handoff`, `2 new messages` — a burst of handoffs is named as the work it is. */
+function headlineOf(messages: readonly BusMessage[]): string {
+	const count = messages.length;
+	const handoffs = messages.filter((message) => message.kind === "handoff").length;
+	if (handoffs === 0 || handoffs !== count) return `${count} new message${count === 1 ? "" : "s"}`;
+	return `${count} handoff${count === 1 ? "" : "s"}`;
+}
+
 /** 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 limit = message.kind === "handoff" ? HANDOFF_PREVIEW : MAX_PREVIEW;
+	const head = text.length > limit ? `${text.slice(0, limit)}…` : 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}`;
 }
@@ -35,6 +55,11 @@ function previewOf(message: BusMessage): string {
  * 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.
+ *
+ * A `handoff` is the one kind that assigns work, so it is the one kind the text
+ * treats as an instruction rather than as mail: the headline counts handoffs, the
+ * preview keeps enough of the body to be actionable, and the hint says to start it.
+ * Nothing else about the kind changes — it still does not block or wait for a reply.
  */
 export function mailNotice(messages: BusMessage[]): NoticeMessage {
 	const count = messages.length;
@@ -45,14 +70,17 @@ export function mailNotice(messages: BusMessage[]): NoticeMessage {
 		detail: sanitizeLine(message.text).slice(0, MAX_PREVIEW),
 		severity: message.kind === "event" ? "warn" : "info",
 	}));
+	const headline = headlineOf(messages);
 	return noticeMessage({
 		content: burstText({
 			marker: BUS_CONTEXT_MARKER,
-			headline: `${count} new message${count === 1 ? "" : "s"}`,
+			headline,
 			lines: shown.map((message) => `- ${previewOf(message)}`),
 			...(more > 0 ? { more: `… ${more} more` } : {}),
-			hint: "Run `session inbox` to read and consume them.",
+			hint: messages.some((message) => message.kind === "handoff")
+				? HANDOFF_HINT
+				: "Run `session inbox` to read and consume them.",
 		}),
-		details: { source: "session-bus", title: `${count} new message${count === 1 ? "" : "s"}`, items },
+		details: { source: "session-bus", title: headline, items },
 	});
 }