@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/session-bus/format.ts

@@ -0,0 +1,101 @@
+/**
+ * Model-facing text for the session bus.
+ *
+ * Everything that came from another session is untrusted text: it is sanitized
+ * before it reaches the transcript, and paths/labels are rendered as one line.
+ */
+
+import { sanitizeLine } from "../../lib/format.ts";
+import type { BusMessage, ClaimConflict, ClaimRecord, SessionStatus } from "./types.ts";
+/**
+ * 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));
+}
+
+function claimLine(claim: ClaimRecord): string {
+	return `${sanitizeLine(claim.path)} · ${sanitizeLine(claim.ownerLabel)}`;
+}
+
+/** The status listing: sessions, unread counts, claims, and this session's alerts. */
+export function formatStatus(status: SessionStatus): string {
+	const sessions = status.sessions.map((session) => {
+		const unread = session.unread > 0 ? ` · ${session.unread} unread` : "";
+		const label = sanitizeLine(session.label);
+		const cwd = sanitizeLine(session.cwd);
+		return `- ${label} (${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)" : ""}`] : [];
+	return [
+		`Sessions (${status.sessions.length})`,
+		...(sessions.length > 0 ? sessions : ["- none"]),
+		"",
+		`Claims (${status.claims.length})`,
+		...(claims.length > 0 ? claims : ["- none"]),
+		...(alerts.length > 0 ? ["", ...alerts] : []),
+		"",
+		`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 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.
+ */
+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
+		? `${who}, listening: a new message raises one turn.`
+		: `${who}, listening: new messages appear at your next turn.`;
+}
+
+/** One consumed inbox, oldest first. */
+export function formatInbox(messages: readonly BusMessage[]): string {
+	if (messages.length === 0) return "Inbox empty.";
+	return messages
+		.map((message, index) => {
+			const paths = message.paths?.length
+				? `\n   paths: ${message.paths.map((path) => sanitizeLine(path)).join(", ")}`
+				: "";
+			const from = sanitizeLine(message.fromLabel);
+			return `${index + 1}. ${from} · ${sanitizeLine(message.kind)} · ${sanitizeLine(message.text)}${paths}`;
+		})
+		.join("\n");
+}
+
+/** Confirmation for a send. */
+export function formatSend(delivered: readonly string[], messageId: string): string {
+	if (delivered.length === 0) return "Delivered to 0 sessions.";
+	const names = delivered.map((label) => sanitizeLine(label)).join(", ");
+	return `Delivered to ${names} (${sanitizeLine(messageId)}).`;
+}
+
+/** Claim result, including the owner that blocked it. */
+export function formatClaim(claimed: readonly string[], conflicts: readonly ClaimConflict[]): string {
+	const lines: string[] = [];
+	if (claimed.length > 0) lines.push(`Claimed: ${claimed.map((path) => sanitizeLine(path)).join(", ")}.`);
+	for (const conflict of conflicts) {
+		const owner = sanitizeLine(conflict.ownerLabel);
+		lines.push(`${sanitizeLine(conflict.path)} is owned by ${owner} (${idSuffix(conflict.owner)}).`);
+	}
+	return lines.length > 0 ? lines.join("\n") : "Nothing claimed.";
+}
+
+/** Release result. */
+export function formatRelease(released: readonly string[], notOwned: readonly string[]): string {
+	const lines: string[] = [];
+	if (released.length > 0) lines.push(`Released: ${released.map((path) => sanitizeLine(path)).join(", ")}.`);
+	if (notOwned.length > 0) lines.push(`Not yours: ${notOwned.map((path) => sanitizeLine(path)).join(", ")}.`);
+	return lines.length > 0 ? lines.join("\n") : "Nothing to release.";
+}

package/extensions/session-bus/index.ts

@@ -0,0 +1,75 @@
+/**
+ * session-bus — coordinate parallel Pi sessions on one repository.
+ *
+ * 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
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { messageOf } from "../../lib/errors.ts";
+import { createPendingReporter, registerPendingChannel } from "../../lib/report.ts";
+import { registerCommands } from "./commands.ts";
+import { registerJoinRequests } from "./join-request.ts";
+import { createSessionBus, type SessionBus } from "./runtime.ts";
+import { registerTools } from "./tools.ts";
+import { mailNotice } from "./notice.ts";
+import type { BusMessage } from "./types.ts";
+
+export interface SessionBusDeps {
+	/** Test seam: a runtime with a temp dir and fixed clock. */
+	bus?: SessionBus;
+}
+
+export default function sessionBus(pi: ExtensionAPI, deps: SessionBusDeps = {}): void {
+	if (!isExtensionEnabled("session-bus")) return;
+	const bus = deps.bus ?? createSessionBus(pi);
+
+	const reporter = createPendingReporter<BusMessage>({
+		wake: (notice) => pi.sendMessage(notice, { triggerTurn: true }),
+		pending: () => bus.pending(),
+		markReported: (messages) => bus.markReported(messages.map((message) => message.id)),
+		buildNotice: mailNotice,
+		source: "session-bus",
+		wakeRequested: () => bus.wantsWake(),
+	});
+
+	registerTools(pi, bus);
+	registerCommands(pi, bus);
+	// `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,
+		runtime: {
+			// A start failure is reported once and leaves the runtime retryable: the next
+			// tool call starts it again, and a bus that never started simply never polls.
+			load: async (ctx) => {
+				try {
+					await bus.start(ctx);
+				} catch (error) {
+					ctx.ui.notify(`Session bus did not start: ${messageOf(error)}`, "warning");
+				}
+			},
+			shutdown: () => bus.stop(),
+		},
+		// A reload or a replaced session reuses the runtime, so the mail trigger is
+		// armed on every session start and cleared before the runtime releases.
+		onSessionStart: () => {
+			bus.onWake = () => reporter.report();
+		},
+		onSessionShutdown: () => {
+			bus.onWake = undefined;
+		},
+	});
+}

package/extensions/session-bus/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

@@ -0,0 +1,86 @@
+/**
+ * The mail notice: what the model reads when an armed session has new mail, and
+ * the rows bytefly draws from the same burst.
+ *
+ * The message bodies came from another session, so they are sanitized here before
+ * they reach either audience.
+ */
+
+import { sanitizeLine } from "../../lib/format.ts";
+import { burstText, noticeMessage, type NoticeItem, type NoticeMessage } from "../../lib/notice.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import type { BusMessage } from "./types.ts";
+
+/** Marker embedded in the injected mail context. */
+const BUS_CONTEXT_MARKER = "[SESSION BUS]";
+
+/** Messages previewed in the model-facing text. The renderer shows its own cap. */
+const MAX_NOTICE_LINES = 5;
+
+/** A message body is clipped to this many characters in a preview. */
+const MAX_PREVIEW = 200;
+
+/**
+ * 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 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}`;
+}
+
+/**
+ * The shared notice for pending mail: model text plus renderer details.
+ *
+ * The model reads five lines, so a burst stays bounded in its context; every
+ * message is passed to the renderer, whose own cap draws the `… N more` row. The
+ * two caps are deliberately separate — one is a context budget, the other a
+ * screen height.
+ *
+ * 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;
+	const shown = messages.slice(0, MAX_NOTICE_LINES);
+	const more = count - shown.length;
+	const items: NoticeItem[] = messages.map((message) => ({
+		label: `${sanitizeLine(message.fromLabel)}${SEPARATORS.item}${sanitizeLine(message.kind)}`,
+		detail: sanitizeLine(message.text).slice(0, MAX_PREVIEW),
+		severity: message.kind === "event" ? "warn" : "info",
+	}));
+	const headline = headlineOf(messages);
+	return noticeMessage({
+		content: burstText({
+			marker: BUS_CONTEXT_MARKER,
+			headline,
+			lines: shown.map((message) => `- ${previewOf(message)}`),
+			...(more > 0 ? { more: `… ${more} more` } : {}),
+			hint: messages.some((message) => message.kind === "handoff")
+				? HANDOFF_HINT
+				: "Run `session inbox` to read and consume them.",
+		}),
+		details: { source: "session-bus", title: headline, items },
+	});
+}

package/extensions/session-bus/overlap.ts

@@ -0,0 +1,36 @@
+/**
+ * Claim overlap (pure).
+ *
+ * The bus's one answer to "do these paths collide?": the runtime checks it before
+ * a claim is written, and the store checks it when a claim is read back. Two
+ * copies would let a claim succeed here and read back as a conflict there, which
+ * teaches the user that a claim is arbitrary.
+ *
+ * One export. `normalizeClaimPath` is the predicate's own step — a spellings rule
+ * with a single caller, inside this module — so a caller cannot normalize a path
+ * one way and compare it another.
+ *
+ * A claim on a directory covers every file below it, in either direction, and a
+ * claim is always a repository-relative, posix-separated path: both sides are
+ * normalized here, because a Windows spelling (`a\b`) and a posix one (`a/b`)
+ * naming the same file must not read as two claims.
+ */
+
+/** A repository-relative path with one separator and no trailing slash. */
+function normalizeClaimPath(raw: string): string {
+	const posix = raw.trim().replace(/\\/g, "/");
+	const trimmed = posix
+		.replace(/^\.\//, "")
+		.replace(/\/{2,}/g, "/")
+		.replace(/\/+$/, "");
+	return trimmed === "." ? "" : trimmed;
+}
+
+/** Whether one claim covers the other path in either direction. */
+export function claimsConflict(a: string, b: string): boolean {
+	const left = normalizeClaimPath(a);
+	const right = normalizeClaimPath(b);
+	// The root claim (an empty path, or ".") covers everything below it.
+	if (left === "" || right === "") return true;
+	return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}

package/extensions/session-bus/protocol.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure protocol rules for the session bus.
+ *
+ * No filesystem or process access lives here: labels, targets, claim paths, and
+ * validation are testable without a runtime. `store.ts` owns the files.
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { MAX_MESSAGE_TEXT } from "../../lib/session-tool.ts";
+import { SESSION_TOOL } from "../../lib/tool-names.ts";
+
+/**
+ * The label rules live in `lib/` because a label is shared vocabulary: the board
+ * records one on a card it claims, and `session-bus` settles the one it is
+ * addressed by. Re-exported here so every module in this extension keeps
+ * importing its rules from the protocol they belong to.
+ */
+export { defaultLabel, MAX_LABEL, normalizeLabel, shortId } from "../../lib/session-label.ts";
+
+export const TOOL_NAME = SESSION_TOOL;
+export const COMMAND_NAME = "sessions";
+/**
+ * The text cap, from `lib/session-tool.ts`, where the callers that clip to it live.
+ * Re-exported the way the label rules are, so this extension imports its protocol's
+ * constants from one place and two extensions cannot drift apart on the number.
+ */
+export const MAX_TEXT = MAX_MESSAGE_TEXT;
+export const MAX_PATHS = 20;
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 50;
+
+export type SessionMode = "tui" | "rpc" | "json" | "print" | "unknown";
+export type SessionAction = "status" | "send" | "inbox" | "claim" | "release" | "join";
+export type MessageKind = "message" | "event" | "ask" | "handoff";
+
+const ACTIONS: readonly SessionAction[] = ["status", "send", "inbox", "claim", "release", "join"];
+const KINDS: readonly MessageKind[] = ["message", "event", "ask", "handoff"];
+
+/** The session mode as the record stores it. */
+export function sessionMode(mode: string | undefined): SessionMode {
+	return mode === "tui" || mode === "rpc" || mode === "json" || mode === "print" ? mode : "unknown";
+}
+
+/** An action, or undefined when the model sent an unknown one. */
+export function normalizeAction(raw: unknown): SessionAction | undefined {
+	return typeof raw === "string" && ACTIONS.includes(raw as SessionAction) ? (raw as SessionAction) : undefined;
+}
+
+/** A message kind; `message` is the default. */
+export function normalizeKind(raw: unknown): MessageKind {
+	return typeof raw === "string" && KINDS.includes(raw as MessageKind) ? (raw as MessageKind) : "message";
+}
+
+/** Trimmed message text, or an error message. */
+export function normalizeText(raw: unknown): { text: string } | { error: string } {
+	if (typeof raw !== "string" || raw.trim() === "") return { error: "text is required." };
+	const text = raw.trim();
+	if (text.length > MAX_TEXT) return { error: `text must be at most ${MAX_TEXT} characters.` };
+	return { text };
+}
+
+/** A shared inbox limit. */
+export function normalizeLimit(raw: unknown): number {
+	if (typeof raw !== "number" || !Number.isFinite(raw)) return DEFAULT_LIMIT;
+	return Math.min(MAX_LIMIT, Math.max(1, Math.floor(raw)));
+}
+
+/** Repository-relative, posix-normalized paths, or an error. */
+export function normalizePaths(repoRoot: string, cwd: string, raw: unknown): { paths: string[] } | { error: string } {
+	if (!Array.isArray(raw) || raw.length === 0) return { error: "paths must contain at least one path." };
+	if (raw.length > MAX_PATHS) return { error: `at most ${MAX_PATHS} paths are allowed.` };
+	const paths: string[] = [];
+	for (const entry of raw) {
+		if (typeof entry !== "string" || entry.trim() === "") return { error: "every path must be a non-empty string." };
+		const absolute = resolve(cwd, entry.trim());
+		const rel = relative(repoRoot, absolute);
+		if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+			return { error: `path "${entry}" is outside the repository.` };
+		}
+		const normalized = rel.split(sep).join("/");
+		if (!paths.includes(normalized)) paths.push(normalized);
+	}
+	return { paths };
+}
+
+/** Resolve `to` to active sessions; `*` is broadcast and excludes the sender. */
+export function resolveRecipients(
+	sessions: readonly { id: string; label: string }[],
+	to: string,
+	from: string,
+): { recipients: Array<{ id: string; label: string }> } | { error: string } {
+	const target = to.trim();
+	if (target === "") return { error: "to is required." };
+	if (target === "*") {
+		const recipients = sessions.filter((session) => session.id !== from);
+		return recipients.length === 0 ? { error: "there are no other active sessions." } : { recipients };
+	}
+	const exact = sessions.find((session) => session.id === target);
+	if (exact) return { recipients: [exact] };
+	const byLabel = sessions.filter((session) => session.label.toLowerCase() === target.toLowerCase());
+	if (byLabel.length === 1) return { recipients: byLabel };
+	if (byLabel.length > 1) return { error: `the label "${target}" is ambiguous; use a session id.` };
+	return { error: `no active session "${target}".` };
+}

package/extensions/session-bus/resolve.ts

@@ -0,0 +1,67 @@
+/**
+ * A claim path as the store keeps it: repository-relative, posix, canonical.
+ *
+ * A path is data — it is resolved against the repository root, and canonicalised
+ * through its real target before it is compared or stored — so a symlinked
+ * spelling inside the repository and the file it names are one claim, and a path
+ * that leaves the repository is refused before anything is written.
+ *
+ * `lib/path.ts` owns the containment predicates; this owns the claim's shape.
+ */
+
+import { isAbsolute, join, relative, sep } from "node:path";
+import { isInside, realPathOfNearest } from "../../lib/path.ts";
+
+/** A path this module declined, with the reason a caller can print. */
+export interface ClaimPathError {
+	/** The path as the caller passed it, so a refusal names what it read. */
+	path: string;
+	/** Why it cannot be a claim. */
+	reason: string;
+}
+
+/** Every path resolved and deduplicated, or the first one refused. */
+export type ResolvedClaimPaths = { paths: string[] } | { error: ClaimPathError };
+
+/**
+ * The wording of the one refusal, shared so approval and the bus cannot phrase it
+ * two ways: the caller prefixes the subject it knows (a unit, or a session's call).
+ */
+export function claimPathMessage(error: ClaimPathError): string {
+	return `path "${error.path}" ${error.reason}.`;
+}
+
+/**
+ * What the root itself resolves to, which is never a claim: it would cover every
+ * file in the repository, so a unit that lists it owns the repository.
+ */
+const ROOT_ITSELF = "is the repository, not a path in it";
+
+/** What a path outside the root resolves to. */
+const OUTSIDE = "does not resolve to a file in the repository";
+
+/** What an absolute path is refused for: it is not the claim's to place. */
+const ABSOLUTE = "is absolute; a claim is relative to the repository root";
+
+/**
+ * Resolve `paths` against `root`, or refuse the first one that is not in it.
+ *
+ * A path that does not exist yet is accepted: `realPathOfNearest` resolves the
+ * nearest existing ancestor, so a unit may name the directory its work creates.
+ */
+export function resolveClaimPaths(root: string, paths: readonly string[]): ResolvedClaimPaths {
+	const realRoot = realPathOfNearest(root);
+	const canonical: string[] = [];
+	for (const path of paths) {
+		// `join` would re-root an absolute path under the repository, which is not what
+		// a caller meant: refuse it rather than claim a directory it never named.
+		if (isAbsolute(path)) return { error: { path, reason: ABSOLUTE } };
+		const target = realPathOfNearest(join(root, path));
+		const rel = relative(realRoot, target);
+		if (rel === "") return { error: { path, reason: ROOT_ITSELF } };
+		if (!isInside(realRoot, target)) return { error: { path, reason: OUTSIDE } };
+		const normalized = rel.split(sep).join("/");
+		if (!canonical.includes(normalized)) canonical.push(normalized);
+	}
+	return { paths: canonical };
+}