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

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 },
 	});
 }

package/{lib/claims → extensions/session-bus}/overlap.ts

@@ -1,20 +1,23 @@
 /**
  * Claim overlap (pure).
  *
- * Two things in this package need the same answer to "do these paths collide?":
- * `session-bus` when a session claims a path, and plan approval when a proposed
- * split names its units. They must agree, because a split that passes validation
- * and then conflicts at claim time — or the reverse — teaches the user that a
- * claim is arbitrary. So the predicate lives here once and both call it.
+ * 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: the caller
- * normalizes first, because a Windows spelling (`a\b`) and a posix one (`a/b`)
+ * 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. */
-export function normalizeClaimPath(raw: string): string {
+function normalizeClaimPath(raw: string): string {
 	const posix = raw.trim().replace(/\\/g, "/");
 	const trimmed = posix
 		.replace(/^\.\//, "")
@@ -31,13 +34,3 @@ export function claimsConflict(a: string, b: string): boolean {
 	if (left === "" || right === "") return true;
 	return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
 }
-
-/** The first two prefixes in `paths` that collide, if any. */
-export function findClaimOverlap(paths: readonly string[]): [string, string] | undefined {
-	for (let i = 0; i < paths.length; i++) {
-		for (let j = i + 1; j < paths.length; j++) {
-			if (claimsConflict(paths[i], paths[j])) return [paths[i], paths[j]];
-		}
-	}
-	return undefined;
-}

package/extensions/session-bus/protocol.ts

@@ -6,63 +6,41 @@
  */
 
 import { isAbsolute, relative, resolve, sep } from "node:path";
-import { sanitizeLine } from "../../lib/format.ts";
+import { MAX_MESSAGE_TEXT } from "../../lib/session-tool.ts";
+import { SESSION_TOOL } from "../../lib/tool-names.ts";
 
-export const TOOL_NAME = "session";
+/**
+ * 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";
-export const MAX_TEXT = 4_000;
+/**
+ * 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 MAX_LABEL = 40;
 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" | "leave" | "watch" | "name";
+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",
-	"leave",
-	"watch",
-	"name",
-];
+const ACTIONS: readonly SessionAction[] = ["status", "send", "inbox", "claim", "release", "join"];
 const KINDS: readonly MessageKind[] = ["message", "event", "ask", "handoff"];
 
-/** Only a terminal session is visible on the bus before it asks to join. */
-export function isAutoJoinMode(mode: string | undefined): boolean {
-	return mode === "tui";
-}
-
 /** 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";
 }
 
-/** A safe label, used both for display and as a target. */
-export function normalizeLabel(raw: string | undefined, fallback: string): string {
-	const text = sanitizeLine(raw ?? "")
-		.replace(/\s+/g, " ")
-		.trim();
-	return (text || fallback).slice(0, MAX_LABEL);
-}
-
-/** A short, display-only suffix for a session id. */
-export function shortId(id: string): string {
-	const clean = id.replace(/[^a-zA-Z0-9]/g, "");
-	return (clean || id).slice(-6);
-}
-
-/** The automatic label before uniqueness is applied. */
-export function defaultLabel(sessionName: string | undefined, cwd: string, id: string): string {
-	const base = normalizeLabel(sessionName, normalizeLabel(cwd.split(/[\\/]/).filter(Boolean).at(-1), "session"));
-	return normalizeLabel(base, `session-${shortId(id)}`);
-}
-
 /** 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;
@@ -105,14 +83,6 @@ export function normalizePaths(repoRoot: string, cwd: string, raw: unknown): { p
 	return { paths };
 }
 
-/**
- * Whether one claim covers the other path in either direction.
- *
- * The predicate is `lib/claims/overlap.ts`, because plan approval validates a
- * split with the same question; a second copy here is how the two answers drift.
- */
-export { claimsConflict } from "../../lib/claims/overlap.ts";
-
 /** Resolve `to` to active sessions; `*` is broadcast and excludes the sender. */
 export function resolveRecipients(
 	sessions: readonly { id: string; label: string }[],

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 };
+}