@gavin-hu/my-pi-agent 0.18.0 → 0.19.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,21 @@ 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, SESSION_TTL_MS } from "../../lib/session-roster.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: 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 +79,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,7 +102,6 @@ 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")}`;
@@ -120,56 +118,27 @@ function suffixLabel(label: string, id: string): string {
 	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 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 +147,21 @@ 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(),
 			};
-			if (isAutoJoinMode(context.mode)) await joinBus();
 		})();
 		try {
 			await starting;
@@ -213,18 +180,25 @@ 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. */
@@ -257,6 +231,17 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 		await store.writeSession(me);
 	}
 
+	/** The live session ids a prune must keep: this session is active by definition. */
+	async function liveIds(): Promise<Set<string>> {
+		if (!store) throw new Error("session bus is not started.");
+		const at = now();
+		const active = new Set(
+			(await store.sessions()).filter((session) => isLive(session, at, sessionTtlMs)).map((session) => session.id),
+		);
+		if (record) active.add(record.id);
+		return active;
+	}
+
 	async function prepare(): Promise<void> {
 		if (!store || !record) throw new Error("session bus is not started.");
 		await joinBus();
@@ -278,32 +263,20 @@ 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;
 	}
 
+	/** 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 }>> {
 		return Promise.all(rows.map(async (session) => ({ ...session, unread: (await store?.unread(session.id)) ?? 0 })));
 	}
@@ -316,7 +289,10 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 	 * second. 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
@@ -324,96 +300,15 @@ export function createSessionBus(pi: ExtensionAPI, options: SessionBusOptions =
 			: 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 }),
-							};
-						}),
-					};
 		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);
@@ -427,6 +322,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 +334,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 +352,46 @@ 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) {
+				await store.prune({ now: now(), activeIds: await liveIds(), 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 +448,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,
 	};
 }

package/extensions/session-bus/store.ts

@@ -11,8 +11,9 @@ import { createHash, randomBytes } from "node:crypto";
 import { mkdir, link, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { asRecord, readJson } from "../../lib/config.ts";
-import { claimsConflict } from "./protocol.ts";
+import { claimsConflict } from "./overlap.ts";
 import type { BusMessage, ClaimConflict, ClaimRecord, SessionRecord } from "./types.ts";
+import { INBOX_DIR_NAME, SESSIONS_DIR_NAME } from "../../lib/session-roster.ts";
 
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
@@ -27,6 +28,8 @@ export interface BusStore {
 	ensure(): Promise<void>;
 	writeSession(record: SessionRecord): Promise<void>;
 	sessions(): Promise<SessionRecord[]>;
+	/** One session's record, or undefined when it is not on disk. */
+	session(id: string): Promise<SessionRecord | undefined>;
 	removeSession(id: string): Promise<void>;
 	writeMessage(target: string, message: BusMessage): Promise<void>;
 	/** Read a recipient's messages without consuming them, oldest first. */
@@ -50,6 +53,24 @@ export interface BusStore {
 	}): Promise<void>;
 }
 
+/**
+ * Release each path through `release`, reporting the ones this session did not
+ * hold. One copy, because `release` and `leave` answer the same two lists, and a
+ * second loop is how the two answers drift.
+ */
+export async function releaseClaimed(
+	paths: readonly string[],
+	release: (path: string) => Promise<boolean>,
+): Promise<{ released: string[]; notOwned: string[] }> {
+	const released: string[] = [];
+	const notOwned: string[] = [];
+	for (const path of paths) {
+		if (await release(path)) released.push(path);
+		else notOwned.push(path);
+	}
+	return { released, notOwned };
+}
+
 const SHA = (value: string): string => createHash("sha256").update(value).digest("hex").slice(0, 32);
 
 function isSession(value: unknown): value is SessionRecord {
@@ -63,10 +84,17 @@ function isSession(value: unknown): value is SessionRecord {
 		typeof entry.repoRoot === "string" &&
 		typeof entry.mode === "string" &&
 		typeof entry.startedAt === "number" &&
-		typeof entry.lastSeen === "number"
+		typeof entry.lastSeen === "number" &&
+		(entry.watching === undefined || isWatchingState(entry.watching))
 	);
 }
 
+/** The optional listening field, validated only when it is there. */
+function isWatchingState(value: unknown): boolean {
+	const entry = asRecord(value);
+	return entry !== undefined && typeof entry.armed === "boolean" && typeof entry.wake === "boolean";
+}
+
 function isMessage(value: unknown): value is BusMessage {
 	const entry = asRecord(value);
 	if (!entry) return false;
@@ -136,8 +164,8 @@ async function dropIfEmpty(dir: string): Promise<void> {
 /** Create a store rooted at one repository's bus directory. */
 export function createBusStore(options: BusStoreOptions): BusStore {
 	const { dir } = options;
-	const sessionsDir = join(dir, "sessions");
-	const inboxRoot = join(dir, "inbox");
+	const sessionsDir = join(dir, SESSIONS_DIR_NAME);
+	const inboxRoot = join(dir, INBOX_DIR_NAME);
 	const claimsDir = join(dir, "claims");
 
 	const sessionFile = (id: string): string => join(sessionsDir, `${SHA(id)}.json`);
@@ -270,6 +298,8 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 
 		sessions: readSessions,
 
+		session: async (id) => readTyped(sessionFile(id), isSession),
+
 		async removeSession(id) {
 			await rm(sessionFile(id), { force: true });
 			await dropIfEmpty(inboxDir(id));
@@ -306,15 +336,21 @@ export function createBusStore(options: BusStoreOptions): BusStore {
 		},
 
 		async prune({ now: at, activeIds, sessionTtlMs, messageTtlMs }) {
+			// The caller's set can lag: a peer that joined and claimed since that read is
+			// live on disk, and its claims are its own. This read is the answer, so the
+			// set only adds to what it found rather than deciding who survives.
+			const live = new Set(activeIds);
 			for (const session of await readSessions()) {
 				if (at - session.lastSeen > sessionTtlMs) {
 					await rm(sessionFile(session.id), { force: true });
 					await dropIfEmpty(inboxDir(session.id));
-					activeIds = new Set([...activeIds].filter((id) => id !== session.id));
+					live.delete(session.id);
+				} else {
+					live.add(session.id);
 				}
 			}
 			for (const claim of await readClaims()) {
-				if (!activeIds.has(claim.owner)) await rm(claimFile(claim.path), { force: true });
+				if (!live.has(claim.owner)) await rm(claimFile(claim.path), { force: true });
 			}
 			for (const name of await readdir(inboxRoot).catch(() => [] as string[])) {
 				const directory = join(inboxRoot, name);