@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/extensions/plan/web.ts

@@ -57,7 +57,7 @@ export interface PlanReviewSession {
 export interface PlanReviewOptions {
 	/** Abort signal; aborting closes the session as cancelled. */
 	signal?: AbortSignal;
-	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	/** Whether the browser may approve the plan (only the `plan` tool's `exit` flow). */
 	canApprove?: boolean;
 	/** The section digests the previous review showed, so this page can mark changed sections. */
 	baseline?: SectionDigest[];
@@ -131,17 +131,6 @@ const DROP_GRACE_MS = 1500;
  */
 const PLAN_POLL_MS = 1000;
 
-/**
- * The deps a caller that injects its own review leaves out.
- *
- * A review needs a place on the session's server, so a caller with no wiring says so
- * rather than binding a socket of its own: the start is refused with a sentence.
- */
-export const NO_SERVER_DEPS: PlanWebReviewDeps = {
-	mount: async () => ({ kind: "refused", reason: "this review has no server wired" }),
-	session: () => "",
-};
-
 export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps): PlanWebReview {
 	const sessions = new Set<PlanReviewSession>();
 	// What each running review can do about sharing; the session itself stays the

package/extensions/question/tools.ts

@@ -14,7 +14,6 @@ import { ASK_USER_QUESTION_TOOL } from "../../lib/tool-names.ts";
 import { UNAVAILABLE_TEXT, formatAnswerText, optionSummary, questionHeaders, unavailableResult } from "./answers.ts";
 import { askViaDialogs, type QuestionUI } from "./dialogs.ts";
 import { AskUserQuestionParams, normalizeQuestions, type AskUserQuestionArgs } from "./schema.ts";
-import { askViaTui } from "./tui.ts";
 import type { AskResult } from "./types.ts";
 
 export const TOOL_NAME = ASK_USER_QUESTION_TOOL;
@@ -59,7 +58,12 @@ export function registerTools(pi: ExtensionAPI): void {
 				// A remote-answered turn falls back to dialogs; only a local TUI turn uses
 				// the full-screen questionnaire.
 				result = await askHuman(ctx, {
-					custom: () => withRailsSuppressed(pi, () => askViaTui(ctx, questions, signal)),
+					custom: async () => {
+						// The questionnaire is the TUI's: a remote or headless answer below loads
+						// neither it nor the rails wrapper.
+						const { askViaTui } = await import("./view/question-screen.ts");
+						return withRailsSuppressed(pi, () => askViaTui(ctx, questions, signal));
+					},
 					dialogs: () => askViaDialogs(dialogUI(ctx), questions, signal),
 				});
 			}

package/extensions/question/{tui.ts → view/question-screen.ts}

@@ -15,15 +15,15 @@ import {
 	type TuiMouseEvent,
 	type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
-import { sanitizeLine } from "../../lib/format.ts";
-import { flowCells } from "../../lib/tui/columns.ts";
-import { clampScroll, formatRange, keepVisible, selectionMarker, wheelDelta } from "../../lib/tui/cursor.ts";
-import { editorTheme, screenHint, type ScreenHint } from "../../lib/tui/chrome.ts";
-import { GLYPHS } from "../../lib/tui/glyphs.ts";
-import { checkbox } from "../../lib/tui/rows.ts";
-import { plainRule, titleRule } from "../../lib/tui/rules.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import { OTHER_LABEL, cancelledResult, collectAnswers, completedResult, describeSelection } from "./answers.ts";
+import { sanitizeLine } from "../../../lib/format.ts";
+import { flowCells } from "../../../lib/tui/columns.ts";
+import { clampScroll, formatRange, keepVisible, selectionMarker, wheelDelta } from "../../../lib/tui/cursor.ts";
+import { editorTheme, screenHint, type ScreenHint } from "../../../lib/tui/chrome.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import { checkbox } from "../../../lib/tui/rows.ts";
+import { plainRule, titleRule } from "../../../lib/tui/rules.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { OTHER_LABEL, cancelledResult, collectAnswers, completedResult, describeSelection } from "../answers.ts";
 import {
 	allAnswered,
 	applyCustomText,
@@ -34,8 +34,8 @@ import {
 	type Effect,
 	type KeyAction,
 	type TuiState,
-} from "./tui-state.ts";
-import type { AskResult, Question, Selection } from "./types.ts";
+} from "../tui-state.ts";
+import type { AskResult, Question, Selection } from "../types.ts";
 
 type Outcome =
 	| { type: "cancelled"; selections: Map<string, Selection> }

package/extensions/rewind/commands/commands.ts

@@ -10,15 +10,14 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { withRailsSuppressed } from "../../../lib/rails.ts";
 import { formatRewindListText, formatRewindRow } from "../text/format.ts";
-import { openReview } from "./review.ts";
-import { rewindTo } from "./rewind.ts";
 import type { RewindRuntime } from "../state/runtime.ts";
-import { RewindListComponent } from "../view/rewind-tui.ts";
 import { buildRewindPoints, type RewindPoint } from "../state/timeline.ts";
 
 /** Pick a point from the timeline, or undefined when the user cancels. */
 async function choosePoint(ctx: ExtensionCommandContext, points: RewindPoint[]): Promise<RewindPoint | undefined> {
 	if (ctx.mode === "tui") {
+		// The timeline is the TUI's: the picker below and registration load neither.
+		const { RewindListComponent } = await import("../view/rewind-tui.ts");
 		return ctx.ui.custom<RewindPoint | undefined>(
 			(tui, theme, _keybindings, done) =>
 				new RewindListComponent({
@@ -62,6 +61,9 @@ async function openRewind(pi: ExtensionAPI, runtime: RewindRuntime, ctx: Extensi
 
 	const point = await withRailsSuppressed(pi, () => choosePoint(ctx, points));
 	if (!point) return;
+	// The rewind run and the review gate both load on the verb that needs them: the
+	// listing above and registration load neither.
+	const { rewindTo } = await import("./rewind.ts");
 	await rewindTo(pi, runtime, ctx, root, point);
 }
 
@@ -76,6 +78,7 @@ export function registerCommands(pi: ExtensionAPI, runtime: RewindRuntime): void
 	pi.registerCommand("review", {
 		description: "Review the latest turn's changes and revert a file or the whole turn",
 		handler: async (_args, ctx) => {
+			const { openReview } = await import("./review.ts");
 			await openReview(pi, runtime, ctx);
 		},
 	});

package/extensions/rewind/state/runtime.ts

@@ -24,7 +24,7 @@ import { createOperationQueue } from "../transport/queue.ts";
 import { applyRestore, planRestore, type PlanResult, type RestoreInput } from "../transport/restore.ts";
 import type { PathStat } from "../text/paths.ts";
 import { createSnapshot } from "../transport/snapshot.ts";
-import { createStatusChip } from "../view/status.ts";
+import { createStatusChip } from "../status.ts";
 import { belongsToRoot, listSnapshots, pruneSnapshots } from "../transport/store.ts";
 import { createTempIndexStore } from "../transport/temp-index.ts";
 import { lastUserEntryId } from "./timeline.ts";

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

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

package/extensions/rewind/view/review-tui.ts

@@ -193,10 +193,10 @@ export class ReviewListComponent extends ChecklistScreen<ReviewEntry> {
 	protected hint(width: number): string {
 		return screenHint(this.theme, width, [
 			"Esc close",
-			{ text: "Enter diff", color: "accent" },
+			{ text: "Enter diff", color: "accent" as const },
 			"Space select",
-			{ text: "r revert", color: "warning" },
-			{ text: "R all", color: "warning" },
+			{ text: "r revert", color: "warn" },
+			{ text: "R all", color: "warn" },
 			"a/n all/none",
 		]);
 	}
@@ -314,7 +314,7 @@ export class ReviewDiffComponent implements Component {
 		return screenHint(this.theme, width, [
 			"Esc back",
 			...(this.options.canRevertHunks ? [{ text: "h hunks", color: "accent" as const }] : []),
-			{ text: "r revert file", color: "warning" },
+			{ text: "r revert file", color: "warn" },
 			"j/k scroll",
 			"g/G top/end",
 		]);

package/extensions/serve/config.ts

@@ -2,21 +2,23 @@
  * The session's one port: the `serve` section of the shared `bytefly.json` (global
  * then project, project wins).
  *
- * `0` — the default — takes one free port for the session and remembers it, which
- * is what a session that never bookmarks wants. A positive value pins the session's
- * server, so every page it serves keeps the address a bookmark already points at.
- * A pinned port that is taken fails the start rather than moving the pages out from
- * under the bookmark.
+ * `0` — the default — takes the project's own port: its repository key hashed into the
+ * band `lib/http/port.ts` holds, so a session that starts again lands where a bookmark
+ * already points and two repositories do not compete for one number. A positive value
+ * pins the session's server, so every page it serves keeps the address a bookmark
+ * already points at. Either way a port another process holds costs the start its
+ * OS-chosen fallback — unless it was pinned, which fails the start rather than moving
+ * the pages out from under the bookmark.
  *
- * Pin it in the project document when more than one repository runs pages on the
- * machine: a global value is one port for every session.
+ * Pin it in the project document when a repository needs a number of its own: a global
+ * value is one port for every session.
  */
 
 import { clampInteger, loadConfigSection } from "../../lib/config.ts";
 
 /** The `serve` section. */
 export interface ServeConfig {
-	/** TCP port on `127.0.0.1`; `0` picks one for the session, a positive value pins it. */
+	/** TCP port on `127.0.0.1`; `0` takes the project's port, a positive value pins it. */
 	port: number;
 }
 

package/extensions/serve/index.ts

@@ -5,7 +5,9 @@
  * own. `plan`, `board`, and `file-browse` ask for a path prefix on
  * {@link HTTP_MOUNT_CHANNEL} and the registry answers with the session's origin, so
  * a session has one port, one close path, and one chip instead of one socket per
- * extension. Binding happens on the first page that asks, never in the factory.
+ * extension. Binding happens on the first page that asks, never in the factory, and the
+ * port it binds is the project's own number unless `serve.port` pins another — so a
+ * bookmarked page URL survives a restart.
  *
  * Load with:  pi --extension ./extensions/serve
  */
@@ -13,7 +15,7 @@
 import { networkInterfaces } from "node:os";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
-import { HTTP_MOUNT_CHANNEL, type MountRequest } from "../../lib/http/index.ts";
+import { HTTP_MOUNT_CHANNEL, type MountRequest } from "../../lib/http/mount.ts";
 import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { loadServeConfig } from "./config.ts";
@@ -26,6 +28,9 @@ export default function serve(pi: ExtensionAPI): void {
 	/** Each session's context, which is where the port chip is drawn. */
 	const contexts = new Map<string, ExtensionContext>();
 
+	/** The directory a session serves: its config and its port both come from it. */
+	const cwdOf = (session: string): string => cwds.get(session) ?? process.cwd();
+
 	/**
 	 * Publish the session's port, or clear the chip with `undefined`. The chip belongs
 	 * to the server, not to a page: one number, shown while anything is served on it.
@@ -45,7 +50,16 @@ export default function serve(pi: ExtensionAPI): void {
 	};
 
 	const registry = createServeRegistry({
-		portFor: (session) => loadServeConfig(cwds.get(session) ?? process.cwd()).port,
+		portFor: (session) => loadServeConfig(cwdOf(session)).port,
+		pickPort: async (session) => {
+			// The repository key is a git answer, so it is paid on the first bind rather than
+			// at registration: a session that opens no page never asks for it.
+			const [{ repoKeyFor }, { projectPort }] = await Promise.all([
+				import("../../lib/repo-key.ts"),
+				import("../../lib/http/port.ts"),
+			]);
+			return projectPort((await repoKeyFor(pi, cwdOf(session))).key);
+		},
 		interfaces: () => networkInterfaces(),
 		onPort: setChip,
 	});

package/extensions/serve/registry.ts

@@ -8,26 +8,26 @@
  * and closes a session's socket with its last mount. A page that goes away takes
  * only its own prefix with it.
  *
- * Pinning is the session's, not a page's: `serve.port` belongs to the first session
- * that binds, so a second session in this process (a WeChat peer loads every other
- * extension, `extensions/wechat/peer/peer-session.ts`) falls back to an OS-chosen
+ * The port is a preference, not a reservation: a session's first bind tries the port
+ * it is pinned to, or the project's own number, and falls back to an OS-chosen one when
+ * that port is taken. Pinning is the session's, not a page's: `serve.port` belongs to the
+ * first session that binds, so a second session in this process (a WeChat peer loads every
+ * other extension, `extensions/wechat/peer/peer-session.ts`) falls back to an OS-chosen
  * port instead of failing on the host's pin, and a second *process* is told the pin
  * is in use rather than moved off the address a bookmark names.
  *
  * Value-only: every byte of state is in the returned closure.
  */
 
-import {
-	type HttpMount,
-	lanAddresses,
-	type MountOutcome,
-	type MountRequest,
-	type ServedMount,
-	type ServedServer,
-	serveHttp,
-	type SharedListener,
-	randomPort,
-	type NetworkInterfaces,
+import { lazy } from "../../lib/lazy.ts";
+import type {
+	HttpMount,
+	MountOutcome,
+	MountRequest,
+	NetworkInterfaces,
+	ServedMount,
+	ServedServer,
+	SharedListener,
 } from "../../lib/http/index.ts";
 
 /** One prefix as this session's server holds it: the mount, and the spec that remounts it. */
@@ -52,12 +52,17 @@ interface Served {
 export interface ServeRegistryDeps {
 	/** The port a session is pinned to, or `0` to pick one. */
 	portFor(session: string): number;
-	/** The candidate port for a session's first bind; defaults to the shared band. */
-	pickPort?: () => number;
+	/**
+	 * The port a session's first bind tries, before the OS-chosen fallback: the project's
+	 * own number, so a session that starts again lands on the one a bookmark names.
+	 */
+	pickPort(session: string): number | Promise<number>;
 	/** The machine's interfaces; a test injects a snapshot instead. */
 	interfaces: () => NetworkInterfaces;
 	/** Told when a session's port comes up and when it goes away, so a chip can say so. */
 	onPort?: (session: string, port: number | undefined) => void;
+	/** The served-page kit; loaded on the first bind, so registration never pays for it. */
+	loadServe?: () => Promise<typeof import("../../lib/http/index.ts")>;
 }
 
 /** The session's servers, as the extension's bus listener drives them. */
@@ -91,12 +96,15 @@ export function createServeRegistry(deps: ServeRegistryDeps): ServeRegistry {
 	const remembered = new Map<string, number>();
 	/** The session the pinned port belongs to; every later session picks its own. */
 	let pinnedBy: string | undefined;
+	/** The served-page kit: one load, on the first bind, shared by every later one. */
+	const http = lazy(deps.loadServe ?? (() => import("../../lib/http/index.ts")));
 
 	/** Bind `session`'s server on the pin when it is this session's to take. */
 	const bind = async (session: string): Promise<Opened> => {
+		const { serveHttp } = await http.get();
 		const pinned = deps.portFor(session);
 		const usePin = pinned > 0 && (pinnedBy === undefined || pinnedBy === session);
-		const preferred = remembered.get(session) ?? (deps.pickPort ?? randomPort)();
+		const preferred = remembered.get(session) ?? (await deps.pickPort(session));
 		try {
 			const server = await serveHttp({ ports: usePin ? [pinned] : [preferred, 0] });
 			if (usePin) pinnedBy = session;
@@ -163,6 +171,7 @@ export function createServeRegistry(deps: ServeRegistryDeps): ServeRegistry {
 	};
 
 	const share = async (session: string, base: string): Promise<SharedListener | undefined> => {
+		const { serveHttp, lanAddresses } = await http.get();
 		const served = sessions.get(session);
 		const held = served?.mounts.get(base);
 		if (served === undefined || held === undefined) return undefined;

package/extensions/session-bus/commands.ts

@@ -12,11 +12,9 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { messageOf } from "../../lib/errors.ts";
 import { sanitizeLine } from "../../lib/format.ts";
-import { withPolledScreen } from "../../lib/screen-session.ts";
 import { formatJoin, formatStatus } from "./format.ts";
 import { COMMAND_NAME } from "./protocol.ts";
 import type { SessionBus } from "./runtime.ts";
-import { SessionListComponent } from "./tui.ts";
 
 /** How often the open board re-reads the bus. */
 const BOARD_POLL_MS = 1_000;
@@ -29,7 +27,7 @@ const BOARD_POLL_MS = 1_000;
  * record fresh, so a poll never has to write. Both reads are read-only: the
  * snapshot neither prunes nor refreshes, and the peek neither consumes nor marks.
  */
-function createBoardReader(bus: SessionBus): (screen: SessionListComponent) => Promise<void> {
+function createBoardReader(bus: SessionBus): (screen: SessionsScreen) => Promise<void> {
 	let busy = false;
 	return async (screen) => {
 		if (busy) return;
@@ -45,12 +43,19 @@ function createBoardReader(bus: SessionBus): (screen: SessionListComponent) => P
 	};
 }
 
+/** The mounted board's type, without loading the screen at registration. */
+type SessionsScreen = InstanceType<typeof import("./view/session-list.ts")["SessionListComponent"]>;
+
 /** Open the TUI board, and resolve when it closes. */
 async function openSessionsScreen(pi: ExtensionAPI, ctx: ExtensionCommandContext, bus: SessionBus): Promise<void> {
+	// The board is the TUI's: the text paths below and registration load neither it
+	// nor the dock screen's poll loop.
+	const { withPolledScreen } = await import("../../lib/screen-session.ts");
+	const { SessionListComponent } = await import("./view/session-list.ts");
 	await bus.start(ctx);
 	const [status, messages] = await Promise.all([bus.snapshot(), bus.peek()]);
 	const first = { status, messages };
-	let read: ((screen: SessionListComponent) => Promise<void>) | undefined;
+	let read: ((screen: SessionsScreen) => Promise<void>) | undefined;
 	await withPolledScreen(
 		pi,
 		ctx,
@@ -59,9 +64,9 @@ async function openSessionsScreen(pi: ExtensionAPI, ctx: ExtensionCommandContext
 			read = reader;
 			// The verbs repaint the board they belong to; their callbacks only run after
 			// construction, so a holder keeps the wiring one-directional.
-			const holder: { screen?: SessionListComponent } = {};
+			const holder: { screen?: SessionsScreen } = {};
 			const component = new SessionListComponent({
-				latest: () => first,
+				board: first,
 				theme: screen.theme,
 				callbacks: {
 					toggleWatch: async (armed) => {

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

@@ -10,7 +10,8 @@
  * The answer always comes: every path here returns a result, including a failure, so
  * a caller never waits on a listener that threw. A caller that asks for `name` also gets
  * Pi's session name, because `/team join <label>` is the one door that means "call me
- * this from now on"; every other join leaves the footer alone.
+ * this from now on"; the footer draws the roster label after every join either way, so a
+ * plain join changes the name on the bar without renaming the session.
  *
  * The claim is the answer, not the result: the bus starts and joins asynchronously, so
  * this answers with the promise and stays claimed while it runs — which is what keeps

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

@@ -12,11 +12,14 @@
  */
 
 import type { RepeatTimer } from "../../lib/timer.ts";
-import type { BusMessage } from "./types.ts";
+import type { BusMessage, InboxPeek } from "./types.ts";
 
 export interface MailWatchOptions {
-	/** This session's unread mail, read-only: nothing is consumed or marked. */
-	peek(): Promise<BusMessage[]>;
+	/**
+	 * This session's inbox, read-only: up to a page of mail whose ids are not `known`, and
+	 * the ids of every message still there. Nothing is consumed or marked.
+	 */
+	peek(known: ReadonlySet<string>): Promise<InboxPeek>;
 	/** The repeating timer behind the poll. */
 	interval: RepeatTimer;
 	/** Poll interval; 0 disables the ticker (tests). */
@@ -54,7 +57,10 @@ export function createMailWatch(options: MailWatchOptions): MailWatch {
 	let wake = false;
 	let stopTicker: (() => void) | undefined;
 	let pendingMail: BusMessage[] = [];
-	/** Ids already queued, reported, or consumed; a broadcast shares one id. */
+	/**
+	 * Ids already queued, reported, or consumed — pruned by what is still on disk, so it
+	 * holds exactly the announced mail an `inbox` call has not removed yet.
+	 */
 	let reported = new Set<string>();
 	let onWake: (() => void) | undefined;
 
@@ -68,24 +74,27 @@ export function createMailWatch(options: MailWatchOptions): MailWatch {
 	}
 
 	/**
-	 * Queue what arrived since the last poll, once, and wake a turn when this
-	 * session asked for one.
+	 * Queue what this watch has not announced, 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.
+	 * The queue and the memory are pruned by what is still on disk, so `reported` is
+	 * bounded by the inbox rather than by a count: an id that leaves the inbox leaves the
+	 * set, and no id still on disk can be forgotten while it is there. A count was how a
+	 * backlog larger than one read made the watch forget an id it had already announced and
+	 * announce it 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.
+		const known = new Set(reported);
+		for (const message of pendingMail) known.add(message.id);
+		const { mail, unread } = await peek(known);
+		// The read names everything still in the inbox, which is a different question from
+		// what one page covered: a message that expired or was consumed leaves the queue and
+		// the memory with its file.
+		for (const id of reported) if (!unread.has(id)) reported.delete(id);
 		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 (mail.length === 0) return;
+		pendingMail = [...pendingMail, ...mail];
 		if (wake) onWake?.();
 	}
 

package/extensions/session-bus/protocol.ts

@@ -65,16 +65,28 @@ export function normalizeLimit(raw: unknown): number {
 	return Math.min(MAX_LIMIT, Math.max(1, Math.floor(raw)));
 }
 
-/** Repository-relative, posix-normalized paths, or an error. */
+/**
+ * Repository-relative, posix-normalized paths, or an error.
+ *
+ * A path that resolves to the repository root is handed on in the caller's own spelling
+ * rather than refused here: what it resolves to is the whole repository, and that
+ * refusal, with the sentence it is worded in, belongs to `resolve.ts` — one rule, one
+ * wording, and one module that owns both.
+ */
 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 given = entry.trim();
+		const absolute = resolve(cwd, given);
 		const rel = relative(repoRoot, absolute);
-		if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+		if (rel === "") {
+			if (!paths.includes(given)) paths.push(given);
+			continue;
+		}
+		if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
 			return { error: `path "${entry}" is outside the repository.` };
 		}
 		const normalized = rel.split(sep).join("/");

package/extensions/session-bus/resolve.ts

@@ -6,10 +6,14 @@
  * 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.
  *
+ * The caller hands in paths that are already relative to the repository (the
+ * spelling rule is `protocol.ts`'s), so what is decided here is what they *resolve*
+ * to: the root itself, a target outside it, or a claim.
+ *
  * `lib/path.ts` owns the containment predicates; this owns the claim's shape.
  */
 
-import { isAbsolute, join, relative, sep } from "node:path";
+import { 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. */
@@ -40,9 +44,6 @@ 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.
  *
@@ -53,9 +54,6 @@ export function resolveClaimPaths(root: string, paths: readonly string[]): Resol
 	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 } };