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

package/extensions/session-bus/runtime.ts

@@ -1,32 +1,31 @@
 /**
  * Session-bus lifecycle and operations.
  *
- * A terminal session registers on `session_start`. RPC, JSON, print, and WeChat
- * peer sessions stay invisible until they call the tool or `/sessions`, so a
- * subagent or phone peer does not join a team merely because the package loaded.
+ * No mode joins on start. A session is invisible until it names itself, or takes
+ * an action that makes it addressable (`send`, `claim`, `join`, `watch`), so a
+ * subagent or phone peer never joins a team merely because the package loaded,
+ * and a fresh terminal session's board is empty. Reading — the board and
+ * `status` — never joins: a reader is not a member.
  * The runtime owns the heartbeat, keeps no module-level state, and uses the
  * common git directory so worktrees of one repository share one bus.
  *
- * An armed inbox watch polls this session's own inbox directory and hands what
- * arrived to the caller's `onWake`, which the extension wires to the shared
- * pending reporter. A wake that arrives while the agent is running is queued and
- * raised by that reporter once the run settles. It announces and never consumes:
- * `inbox` keeps sole ownership of deleting mail, so a wake cannot eat a message
- * the model did not read.
+ * A wake that arrives while the agent is running is queued and raised by the
+ * extension's reporter once the run settles. The watch itself — the poll, the
+ * queue, and the reported set — is `mail-watch.ts`; this module supplies one
+ * read-only peek and the actions that join.
  */
 
 import { randomBytes } from "node:crypto";
-import { join, relative, sep } from "node:path";
+import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { isInside, realPathOfNearest } from "../../lib/path.ts";
-import { SPLIT_OFF_NOTE, splitEnabled } from "../../lib/plans/setting.ts";
-import { plansDir } from "../../lib/plans/store.ts";
+import { claimPathMessage, resolveClaimPaths } from "./resolve.ts";
+import { realPathOfNearest } from "../../lib/path.ts";
 import { repoKeyFor } from "../../lib/repo-key.ts";
+import { sessionNameOf } from "../../lib/session-label.ts";
 import { defaultInterval, type RepeatTimer } from "../../lib/timer.ts";
 import {
 	defaultLabel,
-	isAutoJoinMode,
 	MAX_LABEL,
 	MAX_LIMIT,
 	normalizeKind,
@@ -36,21 +35,32 @@ import {
 	normalizeText,
 	resolveRecipients,
 	sessionMode,
-	claimsConflict,
 	shortId,
 } from "./protocol.ts";
-import { createBusStore, type BusStore } from "./store.ts";
-import { newestTeam, resolveUnit, unitHolder } from "./team.ts";
+import { createMailWatch, type WatchingState } from "./mail-watch.ts";
+import { createBusStore, releaseClaimed, type BusStore } from "./store.ts";
 import type { BusMessage, ClaimConflict, SessionRecord, SessionStatus } from "./types.ts";
+import {
+	BUS_DIR_NAME,
+	type RosterSeams,
+	type RosterState,
+	rosterStateOf,
+	SESSION_TTL_MS,
+} from "../../lib/session-roster.ts";
+import { isPidAlive, type LivenessFn, startTokenOf, type StartTokenFn } from "../../lib/spawn.ts";
 
 export interface SessionBusOptions {
 	now?: () => number;
 	/** Test seam: use this bus directory instead of the agent-dir layout. */
 	dir?: string;
+	/** Test seam: the process id this runtime registers as, so two can share one session id. */
+	pid?: number;
+	/** Test seam: whether a pid is running, so a suite never depends on the host's pids. */
+	alive?: LivenessFn;
+	/** Test seam: the start-time seam the record is stamped with. */
+	startTokenFn?: StartTokenFn;
 	/** Test seam: skip git and use this repository identity. */
 	repo?: { root: string; key: string };
-	/** Test seam: read teams from this plan store instead of the agent-dir layout. */
-	plans?: string;
 	/** Heartbeat interval; 0 disables it (tests). */
 	heartbeatMs?: number;
 	/** Inbox-watch poll interval; 0 disables it (tests). */
@@ -80,16 +90,16 @@ export interface SessionBus {
 	inbox(limit?: number): Promise<BusMessage[]>;
 	claim(paths: unknown): Promise<{ claimed: string[]; conflicts: ClaimConflict[] }>;
 	release(paths: unknown): Promise<{ released: string[]; notOwned: string[] }>;
-	/** Claim every path of one unit in a split plan. */
+	/**
+	 * Join the team: join the bus, name this session when given a label, and listen for
+	 * mail unless `listen` is false. One action, because they are one act — a session on
+	 * the bus that will not hear mail is on it, but not on the team.
+	 */
 	join(input: {
-		team?: string;
-		unit?: string;
-	}): Promise<{ team: string; unit: string; claimed: string[]; conflicts: ClaimConflict[] }>;
-	/** Release the paths of one unit, or every claim this session holds. */
-	leave(input: { team?: string; unit?: string }): Promise<{ released: string[]; notOwned: string[] }>;
-	rename(label: string): Promise<string>;
-	/** Arm or disarm this session's inbox watch. */
-	watch(input: { wake?: boolean; stop?: boolean }): Promise<{ armed: boolean; wake: boolean }>;
+		label?: string;
+		wake?: boolean;
+		listen?: boolean;
+	}): Promise<{ label: string; watching: 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. */
@@ -103,73 +113,58 @@ export interface SessionBus {
 
 const DEFAULT_HEARTBEAT_MS = 10_000;
 const DEFAULT_WATCH_MS = 2_000;
-const DEFAULT_SESSION_TTL_MS = 10 * 60_000;
 const DEFAULT_MESSAGE_TTL_MS = 24 * 60 * 60_000;
 function messageId(now: number): string {
 	return `${now}-${randomBytes(4).toString("hex")}`;
 }
 
-/** Whether a record's heartbeat is fresh: the rule the bus prunes and displays by. */
-function isLive(session: SessionRecord, at: number, ttlMs: number): boolean {
-	return at - session.lastSeen <= ttlMs;
-}
-
 /** A label with this session's short id appended, inside the label budget. */
 function suffixLabel(label: string, id: string): string {
 	const suffix = `-${shortId(id)}`;
 	return `${label.slice(0, MAX_LABEL - suffix.length)}${suffix}`;
 }
 
-/**
- * Re-key accepted paths by their real target, so a symlinked spelling inside the
- * repository and the file it names are one claim. The paths arrive relative and
- * already inside the root; a link that leaves it is refused here.
- */
-function canonicalPaths(root: string, paths: readonly string[]): { paths: string[] } | { error: string } {
-	const realRoot = realPathOfNearest(root);
-	const canonical: string[] = [];
-	for (const path of paths) {
-		const target = realPathOfNearest(join(root, path));
-		const rel = relative(realRoot, target);
-		if (rel === "" || !isInside(realRoot, target)) {
-			return { error: `path "${path}" does not resolve to a file in the repository.` };
-		}
-		const normalized = rel.split(sep).join("/");
-		if (!canonical.includes(normalized)) canonical.push(normalized);
-	}
-	return { paths: canonical };
-}
-
-function sessionName(ctx: ExtensionContext): string | undefined {
-	try {
-		return ctx.sessionManager.getSessionName();
-	} catch {
-		return undefined;
-	}
-}
-
 export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions = {}): SessionBus {
 	const now = options.now ?? Date.now;
 	const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
 	const watchMs = options.watchMs ?? DEFAULT_WATCH_MS;
 	const interval = options.interval ?? defaultInterval;
-	const sessionTtlMs = options.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+	const pid = options.pid ?? process.pid;
+	const seams: RosterSeams = { alive: options.alive ?? isPidAlive, token: options.startTokenFn ?? startTokenOf };
+	// Asked once, here: a reused pid is settled from the record afterwards, so no
+	// heartbeat tick spawns `ps`.
+	const processToken = (seams.token ?? startTokenOf)(pid);
+
+	/**
+	 * What one record says about its session.
+	 *
+	 * The rule is the roster's, not a copy: the bus writes these records and the page
+	 * reads them, and a second copy of the heartbeat rule is how a dead session keeps its
+	 * label and its claims while the screen already says it is gone.
+	 */
+	function stateOf(session: SessionRecord, at = now()): RosterState {
+		return rosterStateOf(session, at, sessionTtlMs, seams);
+	}
+
+	/** Whether a record is a session that can still answer. */
+	function isLive(session: SessionRecord, at = now()): boolean {
+		return stateOf(session, at) === "live";
+	}
+	const sessionTtlMs = options.sessionTtlMs ?? SESSION_TTL_MS;
 	const messageTtlMs = options.messageTtlMs ?? DEFAULT_MESSAGE_TTL_MS;
 
 	let store: BusStore | undefined;
-	let plansRoot: string | undefined;
 	let record: SessionRecord | undefined;
 	let joined = false;
 	let stopHeartbeat: (() => void) | undefined;
 	let starting: Promise<void> | undefined;
 
-	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;
+	/** The watch reads this session's own inbox; nothing is consumed or marked. */
+	const mailWatch = createMailWatch({
+		peek: async () => (store && record ? store.peek(record.id, MAX_LIMIT) : []),
+		interval,
+		watchMs,
+	});
 
 	const ensureStarted = async (context: ExtensionContext): Promise<void> => {
 		if (starting) return starting;
@@ -178,23 +173,24 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 			// cwd does not contain the paths a caller resolves against it.
 			const cwd = realPathOfNearest(context.cwd);
 			const repo = options.repo ?? (await repoKeyFor(pi, cwd));
-			const dir = options.dir ?? join(getAgentDir(), "session-bus", repo.key);
-			plansRoot = options.plans ?? plansDir(getAgentDir(), repo.key);
+			const dir = options.dir ?? join(getAgentDir(), BUS_DIR_NAME, repo.key);
 			store = createBusStore({ dir });
 			await store.ensure();
 			const id = context.sessionManager.getSessionId();
 			const mode = sessionMode(context.mode);
 			record = {
 				id,
-				label: defaultLabel(sessionName(context), cwd, id),
-				pid: process.pid,
+				label: defaultLabel(sessionNameOf(context), cwd, id),
+				pid,
 				cwd,
 				repoRoot: repo.root,
 				mode,
 				startedAt: now(),
 				lastSeen: now(),
+				// Asked once, here: a reused pid is settled from the record, not by this session
+				// polling `ps` for its own heartbeat.
+				...(processToken === undefined ? {} : { startToken: processToken }),
 			};
-			if (isAutoJoinMode(context.mode)) await joinBus();
 		})();
 		try {
 			await starting;
@@ -213,29 +209,38 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		await store.writeSession(record);
 		await settleLabel();
 		joined = true;
-		if (heartbeatMs > 0) {
-			stopHeartbeat = interval(heartbeatMs, () => {
-				void (async () => {
-					if (!record || !store) return;
-					record.lastSeen = now();
-					await store.writeSession(record);
-					// A heartbeat that resumed after a long pause can find its label taken; the
-					// tick is where a revived session notices and yields, after its own write.
-					await settleLabel();
-				})().catch(() => {});
-			});
-		}
+		armHeartbeat();
+	}
+
+	/**
+	 * Start the heartbeat once, whoever joins: `joinBus` on the first addressable
+	 * action, and `rename`, which is a join of its own.
+	 */
+	function armHeartbeat(): void {
+		if (heartbeatMs <= 0 || stopHeartbeat) return;
+		stopHeartbeat = interval(heartbeatMs, () => {
+			void (async () => {
+				if (!record || !store) return;
+				record.lastSeen = now();
+				await store.writeSession(record);
+				// A heartbeat that resumed after a long pause can find its label taken; the
+				// tick is where a revived session notices and yields, after its own write.
+				await settleLabel();
+			})().catch(() => {});
+		});
 	}
 
 	/** The labels other live sessions hold: a crashed session's label is not taken. */
-	async function takenLabels(bus: BusStore, mine: string): Promise<Set<string>> {
+	async function takenLabels(bus: BusStore, mine: string): Promise<Map<string, SessionRecord>> {
 		const at = now();
 		const sessions = await bus.sessions();
-		return new Set(
-			sessions
-				.filter((session) => session.id !== mine && isLive(session, at, sessionTtlMs))
-				.map((session) => session.label.toLowerCase()),
-		);
+		const taken = new Map<string, SessionRecord>();
+		// The record, not just the string: a refusal names the session that holds the label,
+		// which a set of lowercase labels could not do.
+		for (const session of sessions) {
+			if (session.id !== mine && isLive(session, at)) taken.set(session.label.toLowerCase(), session);
+		}
+		return taken;
 	}
 
 	/**
@@ -257,6 +262,27 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		await store.writeSession(me);
 	}
 
+	/**
+	 * What a prune must keep, and what it must let go.
+	 *
+	 * `live` is who can still answer, and this session is active by definition. `gone` is
+	 * who cannot: their rows survive on the heartbeat's clock, but the paths they held are
+	 * nobody's, which is the half a lead waits for.
+	 */
+	async function pruneSets(): Promise<{ live: Set<string>; gone: Set<string> }> {
+		if (!store) throw new Error("session bus is not started.");
+		const at = now();
+		const live = new Set<string>();
+		const gone = new Set<string>();
+		for (const session of await store.sessions()) {
+			const state = stateOf(session, at);
+			if (state === "live") live.add(session.id);
+			else if (state === "gone") gone.add(session.id);
+		}
+		if (record) live.add(record.id);
+		return { live, gone };
+	}
+
 	async function prepare(): Promise<void> {
 		if (!store || !record) throw new Error("session bus is not started.");
 		await joinBus();
@@ -264,12 +290,14 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		// session that finally calls a tool does not delete its own record.
 		record.lastSeen = now();
 		await store.writeSession(record);
-		const sessions = await store.sessions();
-		const active = new Set(
-			sessions.filter((session) => isLive(session, now(), sessionTtlMs)).map((session) => session.id),
-		);
-		if (record) active.add(record.id);
-		await store.prune({ now: now(), activeIds: active, sessionTtlMs, messageTtlMs });
+		const sets = await pruneSets();
+		await store.prune({
+			now: now(),
+			activeIds: sets.live,
+			goneIds: sets.gone,
+			sessionTtlMs,
+			messageTtlMs,
+		});
 	}
 
 	async function currentRecord(): Promise<SessionRecord> {
@@ -278,148 +306,70 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		return record;
 	}
 
-	/** The stored form of the paths a caller passed: validated, then keyed by target. */
-	/**
-	 * The stored form of paths a plan wrote relative to the repository.
-	 *
-	 * A unit's paths are repository-relative by construction, so they resolve
-	 * against the repo root and not the session's cwd: a session started in a
-	 * subdirectory would otherwise claim `packages/web/src/core` for a unit that
-	 * owns `src/core`.
-	 */
-	function rootedPaths(me: SessionRecord, paths: readonly string[]): string[] {
-		const keyed = canonicalPaths(
-			me.repoRoot,
-			paths.map((path) => path.replace(/^\/+/, "")),
-		);
-		if ("error" in keyed) throw new Error(keyed.error);
-		return keyed.paths;
-	}
-
 	function storedPaths(me: SessionRecord, raw: unknown): string[] {
 		const normalized = normalizePaths(me.repoRoot, me.cwd, raw);
 		if ("error" in normalized) throw new Error(normalized.error);
-		const keyed = canonicalPaths(me.repoRoot, normalized.paths);
-		if ("error" in keyed) throw new Error(keyed.error);
+		const keyed = resolveClaimPaths(me.repoRoot, normalized.paths);
+		if ("error" in keyed) throw new Error(claimPathMessage(keyed.error));
 		return keyed.paths;
 	}
 
-	async function withUnread(rows: readonly SessionRecord[]): Promise<Array<SessionRecord & { unread: number }>> {
-		return Promise.all(rows.map(async (session) => ({ ...session, unread: (await store?.unread(session.id)) ?? 0 })));
+	/** The store, for a closure that cannot see the check its caller made. */
+	function requireStore(): BusStore {
+		if (store === undefined) throw new Error("session bus is not started.");
+		return store;
+	}
+
+	async function withUnread(
+		rows: readonly SessionRecord[],
+	): Promise<Array<SessionRecord & { unread: number; state: RosterState }>> {
+		const at = now();
+		return Promise.all(
+			rows.map(async (session) => ({
+				...session,
+				unread: (await store?.unread(session.id)) ?? 0,
+				state: stateOf(session, at),
+			})),
+		);
 	}
 
 	/**
 	 * The bus as it stands, this session's own record included.
 	 *
-	 * `liveOnly` drops a session whose heartbeat went stale, and a claim held by
-	 * one, without writing or deleting anything, so a board can read it every
-	 * second. The prune itself stays with `prepare()` on the next tool or command
-	 * call, which is therefore what the screen's next action sees.
+	 * `liveOnly` drops a session whose heartbeat went stale, and the claims of one whose
+	 * process is gone, without writing or deleting anything, so a board can read it every
+	 * second. A gone session stays listed — a lead needs a face for the paths it still
+	 * holds — but its claims are nobody's, so they are not drawn. The prune itself stays
+	 * with `prepare()` on the next tool or command call, which is therefore what the
+	 * screen's next action sees.
 	 */
-	async function readStatus(me: { id: string; label: string }, liveOnly: boolean): Promise<SessionStatus> {
+	async function readStatus(
+		me: { id: string; label: string; onBus: boolean },
+		liveOnly: boolean,
+	): Promise<SessionStatus> {
 		if (!store) throw new Error("session bus is not started.");
 		const records = await store.sessions();
 		const sessions = liveOnly
-			? records.filter((session) => session.id === record?.id || isLive(session, now(), sessionTtlMs))
+			? records.filter((session) => session.id === record?.id || stateOf(session) !== "quiet")
 			: records;
-		const live = new Set(sessions.map((session) => session.id));
-		const claims = (await store.claims()).filter((claim) => !liveOnly || live.has(claim.owner));
-		// The team line is a file read plus a claim scan, so the board's repaint does
-		// not pay for it: only an explicit status call reports units.
-		const board = liveOnly || plansRoot === undefined ? undefined : newestTeam(plansRoot);
-		const units =
-			board === undefined
-				? undefined
-				: {
-						team: board.team,
-						joined: board.units.filter((unit) => unitHolder(unit, claims, claimsConflict) !== undefined).length,
-						total: board.units.length,
-						rows: board.units.map((unit) => {
-							const holder = unitHolder(unit, claims, claimsConflict);
-							return {
-								unit: unit.name,
-								...(unit.lead ? { lead: true } : {}),
-								...(holder === undefined ? {} : { holder }),
-							};
-						}),
-					};
+		const ours = new Set(sessions.filter((session) => stateOf(session) !== "gone").map((session) => session.id));
+		const claims = (await store.claims()).filter((claim) => !liveOnly || ours.has(claim.owner));
 		return {
-			me,
+			me: { id: me.id, label: me.label },
+			onBus: me.onBus,
 			sessions: await withUnread(sessions),
 			claims,
-			...(units ? { units } : {}),
-			...(armed ? { watching: { armed, wake } } : {}),
+			...(mailWatch.state().armed ? { watching: mailWatch.state() } : {}),
 		};
 	}
 
-	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 || !store || !record) return;
-		const mail = await store.peek(record.id, MAX_LIMIT);
-		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<{ armed: boolean; wake: boolean }> {
-		await currentRecord();
-		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 };
-	}
-
 	async function rename(label: string): Promise<string> {
 		if (!store || !record) throw new Error("session bus is not started.");
 		const candidate = normalizeLabel(label, record.label);
-		if ((await takenLabels(store, record.id)).has(candidate.toLowerCase())) {
-			throw new Error(`the label "${candidate}" is already in use.`);
-		}
+		// The bus's own answer to "who has it": the session record, named by its id, because
+		// the label it holds is the one the caller just asked for.
+		const holder = (await takenLabels(store, record.id)).get(candidate.toLowerCase());
+		if (holder) throw new Error(`the label "${candidate}" is already in use by session ${holder.id}.`);
 		record.label = candidate;
 		record.lastSeen = now();
 		await store.writeSession(record);
@@ -427,6 +377,7 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		// is what the caller hands to Pi as this session's name.
 		await settleLabel();
 		joined = true;
+		armHeartbeat();
 		return record.label;
 	}
 
@@ -438,11 +389,17 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		async stop() {
 			stopHeartbeat?.();
 			stopHeartbeat = undefined;
-			disarm();
-			reported = new Set();
+			mailWatch.stop();
 			if (store && record && joined) {
-				await store.releaseAll(record.id).catch(() => {});
-				await store.removeSession(record.id).catch(() => {});
+				// A `/resume` in a second pane registers the same session id twice; the record
+				// names the process that owns it, so this one releases and removes only its
+				// own. Releasing unconditionally would strip the survivor of the claims it is
+				// still working under.
+				const owner = await store.session(record.id).catch(() => undefined);
+				if (owner === undefined || owner.pid === pid) {
+					await store.releaseAll(record.id).catch(() => {});
+					await store.removeSession(record.id).catch(() => {});
+				}
 			}
 			joined = false;
 			starting = undefined;
@@ -450,23 +407,53 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 			record = undefined;
 		},
 
-		watch,
-		wantsWake: () => armed && wake,
-		poll: pollOnce,
-		pending: () => [...pendingMail],
-		markReported,
+		// Join, name, and listen as one act. Order matters the way it does everywhere else
+		// here: the name is validated by `rename` before a watch is armed, so a refused
+		// label leaves both the record and the watch exactly as they were.
+		async join(input) {
+			const me = await currentRecord();
+			const label = input.label === undefined ? me.label : await rename(input.label);
+			// `listen: false` is the one way to be on the bus without mail: the record stays,
+			// so a peer can still address this session, and only the watch is turned off.
+			const watching =
+				input.listen === false ? await mailWatch.watch({ stop: true }) : await mailWatch.watch({ wake: input.wake });
+			// Written to the record so a peer reads it from disk instead of asking: this is the
+			// fact `team` reports as "not listening", and an absent field means exactly that.
+			if (watching.armed) me.watching = { armed: true, wake: watching.wake };
+			else delete me.watching;
+			await requireStore().writeSession(me);
+			return { label, watching };
+		},
+		wantsWake: () => mailWatch.wantsWake(),
+		poll: () => mailWatch.poll(),
+		pending: () => mailWatch.pending(),
+		markReported: (ids) => mailWatch.markReported(ids),
 		set onWake(callback: (() => void) | undefined) {
-			onWake = callback;
+			mailWatch.onWake = callback;
 		},
 
 		async status() {
+			if (!store || !record) throw new Error("session bus is not started.");
+			// A reader does not join: an unjoined session prunes and reads, and is not
+			// listed by the act of looking. Only an addressable action joins.
+			if (!joined) {
+				const sets = await pruneSets();
+				await store.prune({
+					now: now(),
+					activeIds: sets.live,
+					goneIds: sets.gone,
+					sessionTtlMs,
+					messageTtlMs,
+				});
+				return readStatus({ id: record.id, label: record.label, onBus: false }, false);
+			}
 			const me = await currentRecord();
-			return readStatus({ id: me.id, label: me.label }, false);
+			return readStatus({ id: me.id, label: me.label, onBus: true }, false);
 		},
 
 		async snapshot() {
 			if (!store || !record) throw new Error("session bus is not started.");
-			return readStatus({ id: record.id, label: record.label }, true);
+			return readStatus({ id: record.id, label: record.label, onBus: joined }, true);
 		},
 
 		async peek() {
@@ -523,53 +510,19 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 			if (!store) throw new Error("session bus is not started.");
 			const messages = await store.inbox(me.id, normalizeLimit(limit));
 			// Mail read before its notice fired is never announced afterwards.
-			markReported(messages.map((message) => message.id));
+			mailWatch.markReported(messages.map((message) => message.id));
 			return messages;
 		},
 
 		async claim(rawPaths) {
 			const me = await currentRecord();
-			if (!store) throw new Error("session bus is not started.");
-			return store.claimAll(storedPaths(me, rawPaths), me.id, me.label, now());
+			return requireStore().claimAll(storedPaths(me, rawPaths), me.id, me.label, now());
 		},
 
 		async release(rawPaths) {
 			const me = await currentRecord();
-			if (!store) throw new Error("session bus is not started.");
-			const released: string[] = [];
-			const notOwned: string[] = [];
-			for (const path of storedPaths(me, rawPaths)) {
-				if (await store.release(path, me.id)) released.push(path);
-				else notOwned.push(path);
-			}
-			return { released, notOwned };
-		},
-
-		async join(input) {
-			const me = await currentRecord();
-			if (!store) throw new Error("session bus is not started.");
-			if (!splitEnabled(me.cwd, me.repoRoot)) throw new Error(SPLIT_OFF_NOTE);
-			const unit = resolveUnit(plansRoot ?? "", input, "join");
-			const claimed = await store.claimAll(rootedPaths(me, unit.paths), me.id, me.label, now());
-			return { team: unit.team, unit: unit.name, ...claimed };
-		},
-
-		async leave(input) {
-			const me = await currentRecord();
-			if (!store) throw new Error("session bus is not started.");
-			const paths =
-				input.team === undefined && input.unit === undefined
-					? (await store.claims()).filter((claim) => claim.owner === me.id).map((claim) => claim.path)
-					: rootedPaths(me, resolveUnit(plansRoot ?? "", input, "leave").paths);
-			const released: string[] = [];
-			const notOwned: string[] = [];
-			for (const path of paths) {
-				if (await store.release(path, me.id)) released.push(path);
-				else notOwned.push(path);
-			}
-			return { released, notOwned };
+			const bus = requireStore();
+			return releaseClaimed(storedPaths(me, rawPaths), (path) => bus.release(path, me.id));
 		},
-
-		rename,
 	};
 }