pi-squire 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-26
+
+### Added
+
+- `/delegates`, also on `alt+shift+d`, opens a panel of the delegations whose
+  window is open (newest first): `enter` opens one in a tmux popup, or switches
+  to it when it is in your own session; `p` peeks at its pane in an overlay (`r` refreshes,
+  `enter` opens); `s` switches your client to it; `x` closes it, asking only
+  while it runs; `n` opens the new-delegate form. `/delegate-open <id> [--popup|--switch|--peek]` does one of
+  these directly. Popup and switch act on the most recently active client of the
+  parent's session; the parent closes a popup once its delegate's window is gone.
+  Commands and a shortcut only: the model gets no new tool.
+- `/delegate` with no arguments opens a new-delegate form: pick an agent, write
+  the task, name it, then a settings screen for model, thinking level (only the
+  levels the model supports, clamped, visibly, when the agent's default or a new model does not support it), auto-exit,
+  working directory and worktree. It launches through the same path as the
+  typed command. `/delegate-resume` with no arguments opens a picker of the
+  delegations that can be resumed, then an editor for the follow-up. Typed
+  commands and the tools are unchanged; the two commands no longer print
+  their usage when typed bare.
+- `@earendil-works/pi-ai` is now a peer dependency (`*`), supplied by Pi.
+
 ## [0.12.0] - 2026-10-26
 
 ### Changed
@@ -491,7 +513,8 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/gvanderclay/pi-squire/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/gvanderclay/pi-squire/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/gvanderclay/pi-squire/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/gvanderclay/pi-squire/compare/v0.9.5...v0.10.0

package/README.md

@@ -75,6 +75,20 @@ When the delegate finishes, its answer reaches the parent as one `[delegate]`
 message that quotes the task (see [Results](#results)), and the delegate then
 closes its own window ([auto-exit](#auto-exit)).
 
+`/delegate` with no arguments opens a form instead: pick an agent, write the
+task in the multi-line editor, give it an optional label (empty for the
+default name), then a settings screen. Its first row, Start, launches; the rows
+below it all begin at the agent's defaults: Model (a filterable list of the
+models your Pi has credentials for), Thinking (only the levels the selected
+model supports; a level the model does not support, whether from the agent's
+default or after changing the model, moves to the nearest supported one and says so), Auto-exit, Working directory (your own, to change)
+and Worktree (a new branch name, empty for none). A worktree and a changed
+working directory exclude each other; the base, source and fallbacks stay
+command-only. The form starts the delegate through the same path as the
+command, in the background, with the same start message. The label and
+directory are checked as `--label` and `--cwd` are, before anything is sent
+or opened.
+
 ## How a delegation works
 
 `/delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--cwd <dir> | --worktree <branch> [--worktree-source <dir>] [--worktree-base <commit-ish>]] [--auto-exit | --no-auto-exit] <task…>`
@@ -165,6 +179,34 @@ The values are `companion` (the default when the setting is absent) and
 `current`. The file is read at each launch. Any other value refuses the launch
 with an error naming the file, before the task is sent or a window opens.
 
+## Reaching delegates
+
+Delegate windows sit out of your way, so reach them from the parent. `/delegates`
+(or `alt+shift+d`) opens a panel of the delegations whose window is open: running,
+or done with auto-exit off, newest first. The model has no tool for any of this.
+
+| Key | Does |
+|---|---|
+| `↑` / `↓` | select a delegation; `esc` leaves the panel |
+| `enter` | open: a popup over your terminal, or a switch when the window is in the parent's own session |
+| `p` | peek: a snapshot of the window's pane (`capture-pane`) in an overlay; `r` refreshes, `enter` opens, `esc` returns to the list |
+| `s` | switch your tmux client to the window; `prefix L` returns you (tmux's last-session key) |
+| `x` | close the delegation as `delegation_close` does; asks first only while it is running |
+| `n` | new delegate: the same form `/delegate` opens with no arguments (see [First use](#first-use)) |
+
+Popup and switch act on the most recently active tmux client attached to the
+parent's session. With none attached they refuse with a notice; peek and close
+still work. The popup attaches to the window's session at that window, and
+detaching in it (`prefix d`) closes it. When the delegate's window goes, the parent
+closes the popup within one poll (up to 5 s). No tmux key bindings or options are
+added.
+
+`/delegate-open <id> [--popup|--switch|--peek]` does one of these on one
+delegation without the panel: with no flag or with `--popup`, what `enter` does (a popup, or a
+switch for a window in the parent's own session, since a popup of one's own session would show it
+inside itself); `--switch` always switches; `--peek` opens the peek overlay. Ids complete from the
+open delegations.
+
 ## Working directory
 
 `--cwd <dir>` (the `delegate` tool's `cwd`) runs the delegate in an existing
@@ -826,6 +868,15 @@ The model does the same with `delegation_resume` (`id` and `task`, optionally
 `model`, `thinking` and `auto_exit`), which returns the `delegate` tool's result
 plus `resumedFrom`. The command completes the ids that can still be resumed.
 
+`/delegate-resume` with no arguments opens a picker instead: the delegations
+that pass every check below (newest first, from one look at tmux), then the
+multi-line editor for the follow-up. The checks change nothing: it refuses as the
+command does when tmux is older than 3.2 or `windowPlacement` is invalid, and leaves out a
+delegation whose recorded thinking level is invalid or whose model and fallbacks cannot be used
+(credentials, usage limits). An exited window is left for the resume to close, and trust is
+asked only when you resume. The model, thinking level and auto-exit are the delegation's own,
+and it resumes as the command does.
+
 - The delegate's own session file is reopened with `pi --session <absolute path>`
   and the recorded `--session-dir`, in a new window named like the first. The
   delegate keeps everything it read and decided; Pi appends to the same file.
@@ -993,7 +1044,11 @@ Other extensions may rely on:
 - the `delegate`, `delegation_status`, `delegation_close` and `delegation_resume` tool names,
   parameters, the recorded `workspace` shape and the `workspaceSnapshot`
   shape in results and status;
-- the `/delegate` and `/delegate-resume` syntax and flags;
+- the `/delegate` and `/delegate-resume` syntax and flags, and their
+  no-argument forms: `/delegate` opens the new-delegate form and
+  `/delegate-resume` the resume picker;
+- the `/delegates` command and its `alt+shift+d` shortcut, and `/delegate-open <id>` with its
+  `--popup`, `--switch` and `--peek` flags;
 - the `[delegate]` result text and the closed-without-a-result text;
 - `AGENT.md`'s frontmatter keys and its location,
   `<agent dir>/squire/agents/<name>/AGENT.md`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",
@@ -44,12 +44,14 @@
 		"access": "public"
 	},
 	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": ">=1.3.0",
 		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.14",
+		"@earendil-works/pi-ai": "1.3.0",
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "26.6.3",

package/src/index.ts

@@ -53,9 +53,12 @@ import { Type } from "typebox";
 import { type Agent, isThinking, type Roster, readRoster, THINKING_LEVELS } from "./agents.ts";
 import { AGENT_ENV, AUTO_EXIT_ENV, FALLBACK_ENV, registerChild } from "./child.ts";
 import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
+import { createNavigator, OPEN_USAGE, openCompletions, parseOpen } from "./navigator.ts";
+import { type NewDelegateDeps, type NewRequest, startNewDelegate } from "./new-delegate.ts";
 import { dirtyNotice, renderDelegateCall, renderDelegateResult, resourceLine } from "./render.ts";
 import { createResults, delegateName, type WorkspaceAttempt } from "./results.ts";
 import { createResume, type ResumeRequest, resumableIds, startedLine } from "./resume.ts";
+import { pickResume } from "./resume-picker.ts";
 import { createTmuxClient, type OpenedWindow, requireTmuxVersion, type TmuxClient, WindowOpenError } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
@@ -587,19 +590,19 @@ export default function delegate(
 		return roster;
 	}
 
+	/** The refusal for an empty roster. */
+	const noAgents = (): string =>
+		`no agents are defined; add ${join(
+			getAgentDir(),
+			"squire",
+			"agents",
+			"<name>",
+			"AGENT.md",
+		)} with frontmatter description, model and thinking (optionally auto-exit, exclude-tools, tools, extensions and fallback), and the prompt as its body`;
+
 	/** The request as a start, or an error naming what to fix. */
 	async function validate(request: Parsed, roster: Roster, models: ModelRegistry): Promise<Start> {
-		if (roster.agents.length === 0) {
-			throw new Error(
-				`no agents are defined; add ${join(
-					getAgentDir(),
-					"squire",
-					"agents",
-					"<name>",
-					"AGENT.md",
-				)} with frontmatter description, model and thinking (optionally auto-exit, exclude-tools, tools, extensions and fallback), and the prompt as its body`,
-			);
-		}
+		if (roster.agents.length === 0) throw new Error(noAgents());
 		const agent = roster.agents.find((candidate) => candidate.name === request.agent);
 		if (agent === undefined) {
 			throw new Error(
@@ -1009,22 +1012,18 @@ export default function delegate(
 	const started = (launched: Launched, start: Start): string =>
 		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${inSession(launched.windowSession)}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
 
-	async function command(input: string, ctx: ExtensionContext): Promise<void> {
+	/** Start a delegate from a parsed `/delegate` or the form, telling the user how it went. */
+	async function runDelegate(parsed: Parsed, ctx: ExtensionContext): Promise<void> {
 		const fail = (message: string) => ctx.ui.notify(`delegate: ${message}`, "error");
-		const outcome = parse(input);
-		if ("error" in outcome) {
-			fail(outcome.error);
-			return;
-		}
 		try {
-			const cwd = normalizeWorkspaceValue(outcome.parsed.cwd, "--cwd");
-			const worktree_source = normalizeWorkspaceValue(outcome.parsed.worktree_source, "--worktree-source");
-			const worktree_base = normalizeWorkspaceValue(outcome.parsed.worktree_base, "--worktree-base");
-			const worktree = normalizeWorkspaceValue(outcome.parsed.worktree, "--worktree");
+			const cwd = normalizeWorkspaceValue(parsed.cwd, "--cwd");
+			const worktree_source = normalizeWorkspaceValue(parsed.worktree_source, "--worktree-source");
+			const worktree_base = normalizeWorkspaceValue(parsed.worktree_base, "--worktree-base");
+			const worktree = normalizeWorkspaceValue(parsed.worktree, "--worktree");
 			if (worktree_source !== undefined && worktree === undefined)
 				throw new Error("--worktree-source requires --worktree");
 			const start = await validate(
-				{ ...outcome.parsed, cwd, worktree, worktree_base, worktree_source },
+				{ ...parsed, cwd, worktree, worktree_base, worktree_source },
 				rosterFor(ctx),
 				ctx.modelRegistry,
 			);
@@ -1035,7 +1034,44 @@ export default function delegate(
 		}
 	}
 
+	/** What the new-delegate form needs, shared by `/delegate` and the panel's `n`. */
+	const newDelegateDeps: NewDelegateDeps = {
+		unavailable: () => (tmux.insideTmux() ? undefined : NOT_IN_TMUX),
+		roster: rosterFor,
+		noAgents,
+		labelProblem,
+		start: (request: NewRequest, context) => runDelegate(request, context),
+	};
+
+	/** `/delegate`: with no arguments the new-delegate form, otherwise the typed request. */
+	async function command(input: string, ctx: ExtensionContext): Promise<void> {
+		if (input.trim() === "") {
+			await startNewDelegate(ctx, newDelegateDeps);
+			return;
+		}
+		const outcome = parse(input);
+		if ("error" in outcome) {
+			ctx.ui.notify(`delegate: ${outcome.error}`, "error");
+			return;
+		}
+		await runDelegate(outcome.parsed, ctx);
+	}
+
 	async function resumeCommand(input: string, ctx: ExtensionContext): Promise<void> {
+		if (input.trim() === "") {
+			await pickResume(ctx, {
+				unavailable: () => (tmux.insideTmux() ? undefined : NOT_IN_TMUX),
+				eligible: resumer.eligible,
+				resume: async (request, context) => {
+					try {
+						context.ui.notify(startedLine(await resumer.resume(request, context)), "info");
+					} catch (err) {
+						context.ui.notify(`delegate: ${(err as Error).message}`, "error");
+					}
+				},
+			});
+			return;
+		}
 		const outcome = parseResume(input);
 		if ("error" in outcome) {
 			ctx.ui.notify(`delegate: ${outcome.error}`, "error");
@@ -1243,6 +1279,30 @@ export default function delegate(
 		handler: resumeCommand,
 	});
 
+	const navigator = createNavigator(results, tmux, tracking, (ctx: ExtensionContext) =>
+		startNewDelegate(ctx, newDelegateDeps),
+	);
+
+	pi.registerCommand("delegates", {
+		description: "Open the panel of delegates whose window is open: popup, peek, switch, close",
+		handler: async (_args: string, ctx: ExtensionContext) => navigator.panel(ctx),
+	});
+
+	pi.registerShortcut("alt+shift+d", {
+		description: "Open the delegates panel",
+		handler: (ctx: ExtensionContext) => navigator.panel(ctx),
+	});
+
+	pi.registerCommand("delegate-open", {
+		description: `Reach one open delegate: ${OPEN_USAGE}`,
+		getArgumentCompletions: async (prefix: string) => openCompletions(prefix, await navigator.openIds()),
+		handler: async (args: string, ctx: ExtensionContext) => {
+			const parsed = parseOpen(args);
+			if ("error" in parsed) return ctx.ui.notify(`delegate: ${parsed.error}`, "error");
+			await navigator.openDelegate(ctx, parsed.id, parsed.mode);
+		},
+	});
+
 	pi.registerCommand("delegate-clear", {
 		description: "Clear usage-limit marks: all, a provider, or a provider/model",
 		getArgumentCompletions: (prefix: string) => {

package/src/navigator.ts

@@ -0,0 +1,382 @@
+// The delegate navigator: the `/delegates` panel and `/delegate-open`. It lists
+// the delegations whose window is open and reaches one of them: a popup over
+// the user's tmux client, a switch of that client, a peek at the pane, or a
+// close. Everything here is a command or a key; the model gets no tool that
+// moves the user's terminal.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Component, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+import { type DelegationState, deriveState, isStarted, type Results, recordedName } from "./results.ts";
+import type { TmuxClient, TmuxWindow } from "./tmux.ts";
+import { listWindows, ownWindow, type Tracking } from "./tracking.ts";
+
+/** What `/delegate-open` does: `auto` is what enter does in the panel. */
+export type OpenMode = "auto" | "popup" | "switch" | "peek";
+
+export const OPEN_USAGE = "/delegate-open <id> [--popup|--switch|--peek]";
+const OPEN_FLAGS = ["--popup", "--switch", "--peek"] as const;
+
+/** One delegation whose window is open. */
+type OpenDelegate = {
+	id: string;
+	name: string;
+	agent: string;
+	state: DelegationState;
+	window: TmuxWindow;
+};
+
+/** What the panel hands back: the action the user chose on one delegation, or none. */
+type PanelResult = { action: "open" | "switch" | "close" | "peek"; id: string } | { action: "new" } | undefined;
+
+/** What the peek hands back: open the delegate, or nothing. */
+type PeekResult = { action: "open" } | undefined;
+
+const HINT = "↑↓ select · enter open · p peek · s switch · x close · n new · esc leave";
+const EMPTY = "No open delegates · n new · esc close";
+const PEEK_HINT = "r refresh · enter open · esc back";
+
+/** Where a peek shows: over the panel or the editor, not in its place. */
+const PEEK_OPTIONS = { overlay: true, overlayOptions: { width: "90%", maxHeight: "90%", anchor: "center" } } as const;
+
+type PanelTheme = { fg(color: string, text: string): string; bold(text: string): string };
+
+type Capture = { text: string; error: string | undefined; loading: boolean };
+
+/** The lines a peek shows: the captured pane's last rows, or why there is none. */
+function peekBody(peek: Capture, rows: number): string[] {
+	if (peek.loading) return ["Capturing…"];
+	if (peek.error !== undefined) return [`Could not capture the pane: ${peek.error}`];
+	return peek.text
+		.replace(/\s+$/, "")
+		.split("\n")
+		.slice(-Math.max(5, rows - 8));
+}
+
+/** The panel's list of open delegates, as a pi-tui component. */
+class Panel implements Component {
+	private selected = 0;
+	private readonly items: readonly OpenDelegate[];
+	private readonly theme: PanelTheme;
+	private readonly done: (result: PanelResult) => void;
+	private readonly redraw: () => void;
+
+	constructor(parts: {
+		items: readonly OpenDelegate[];
+		theme: PanelTheme;
+		done: (result: PanelResult) => void;
+		redraw: () => void;
+	}) {
+		this.items = parts.items;
+		this.theme = parts.theme;
+		this.done = parts.done;
+		this.redraw = parts.redraw;
+	}
+
+	invalidate(): void {}
+
+	handleInput(data: string): void {
+		const item = this.items[this.selected];
+		const count = this.items.length;
+		if (matchesKey(data, "escape")) this.done(undefined);
+		else if (matchesKey(data, "n")) this.done({ action: "new" });
+		else if (item === undefined) return;
+		else if (matchesKey(data, "up")) this.selected = (this.selected + count - 1) % count;
+		else if (matchesKey(data, "down")) this.selected = (this.selected + 1) % count;
+		else if (matchesKey(data, "enter")) this.done({ action: "open", id: item.id });
+		else if (matchesKey(data, "p")) this.done({ action: "peek", id: item.id });
+		else if (matchesKey(data, "s")) this.done({ action: "switch", id: item.id });
+		else if (matchesKey(data, "x")) this.done({ action: "close", id: item.id });
+		this.redraw();
+	}
+
+	render(width: number): string[] {
+		const fit = (text: string): string => truncateToWidth(text, Math.max(1, width));
+		if (this.items.length === 0) return [this.theme.bold("Delegates"), "", EMPTY].map(fit);
+		const lines = this.items.map((item, index) => {
+			const where = item.window.session === "" ? item.window.id : `${item.window.id} in ${item.window.session}`;
+			const row = `${item.name} · ${item.agent} · ${item.state} · ${where}`;
+			return index === this.selected ? this.theme.fg("accent", `▸ ${row}`) : `  ${row}`;
+		});
+		return [this.theme.bold("Delegates"), "", ...lines, "", this.theme.fg("dim", HINT)].map(fit);
+	}
+}
+
+/** A snapshot of one delegate's pane, shown as an overlay: `r` refreshes, enter opens, esc returns. */
+class PeekView implements Component {
+	private capture: Capture = { text: "", error: undefined, loading: true };
+	private readonly item: OpenDelegate;
+	private readonly theme: PanelTheme;
+	private readonly read: (windowId: string) => Promise<string>;
+	private readonly done: (result: PeekResult) => void;
+	private readonly redraw: () => void;
+	private readonly rows: () => number;
+
+	constructor(parts: {
+		item: OpenDelegate;
+		theme: PanelTheme;
+		read: (windowId: string) => Promise<string>;
+		done: (result: PeekResult) => void;
+		redraw: () => void;
+		rows: () => number;
+	}) {
+		this.item = parts.item;
+		this.theme = parts.theme;
+		this.read = parts.read;
+		this.done = parts.done;
+		this.redraw = parts.redraw;
+		this.rows = parts.rows;
+		this.refresh();
+	}
+
+	invalidate(): void {}
+
+	private refresh(): void {
+		this.capture = { text: "", error: undefined, loading: true };
+		void this.read(this.item.window.id).then(
+			(text) => {
+				this.capture = { text, error: undefined, loading: false };
+				this.redraw();
+			},
+			(err: unknown) => {
+				this.capture = { text: "", error: (err as Error).message, loading: false };
+				this.redraw();
+			},
+		);
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape")) this.done(undefined);
+		else if (matchesKey(data, "r")) this.refresh();
+		else if (matchesKey(data, "enter")) this.done({ action: "open" });
+		this.redraw();
+	}
+
+	render(width: number): string[] {
+		const fit = (text: string): string => truncateToWidth(text, Math.max(1, width));
+		const head = this.theme.bold(`Peek: ${this.item.name} (${this.item.window.id})`);
+		const body = peekBody(this.capture, this.rows());
+		return [head, "", ...body, "", this.theme.fg("dim", PEEK_HINT)].map(fit);
+	}
+}
+
+/** What `src/index.ts` needs from the navigator. */
+export type Navigator = {
+	/** The panel, looping back after a close. */
+	panel(ctx: ExtensionContext): Promise<void>;
+	/** One action on one open delegation, for `/delegate-open`. */
+	openDelegate(ctx: ExtensionContext, id: string, mode: OpenMode): Promise<void>;
+	/** Ids of the delegations whose window is open, for completions. */
+	openIds(): Promise<string[]>;
+};
+
+/** `/delegate-open`'s arguments: an id and at most one mode flag. */
+export function parseOpen(text: string): { id: string; mode: OpenMode } | { error: string } {
+	const words = text.trim() === "" ? [] : text.trim().split(/\s+/);
+	const flags = words.filter((word) => word.startsWith("-"));
+	const ids = words.filter((word) => !word.startsWith("-"));
+	const unknown = flags.find((flag) => !(OPEN_FLAGS as readonly string[]).includes(flag));
+	if (unknown !== undefined) return { error: `unknown flag ${unknown}; ${OPEN_USAGE}` };
+	if (flags.length > 1) return { error: `give at most one of --popup, --switch and --peek; ${OPEN_USAGE}` };
+	if (ids.length !== 1) return { error: `give one delegation id; ${OPEN_USAGE}` };
+	const flag = flags[0];
+	return { id: ids[0], mode: flag === undefined ? "auto" : (flag.slice(2) as OpenMode) };
+}
+
+/** Completions for `/delegate-open`: ids first, then the mode flags not yet given. */
+export function openCompletions(prefix: string, ids: readonly string[]): { value: string; label: string }[] | null {
+	const partial = /(?:^|\s)(\S*)$/.exec(prefix)?.[1] ?? "";
+	const head = prefix.slice(0, prefix.length - partial.length);
+	const given = head.trim() === "" ? [] : head.trim().split(/\s+/);
+	const values: string[] = [];
+	if (!given.some((word) => !word.startsWith("-"))) values.push(...ids);
+	if (!given.some((word) => word.startsWith("-"))) values.push(...OPEN_FLAGS);
+	const hits = values.filter((value) => value.startsWith(partial));
+	return hits.length > 0 ? hits.map((value) => ({ value: head + value, label: value })) : null;
+}
+
+type Env = { results: Results; tmux: TmuxClient; tracking: Pick<Tracking, "trackPopup" | "close"> };
+
+/** The open delegations, newest first, from the records and one listing; undefined when tmux cannot be asked. */
+async function openDelegates({ results, tmux }: Env): Promise<OpenDelegate[] | undefined> {
+	const windows = await listWindows(tmux);
+	if (windows === undefined) return undefined;
+	const found: OpenDelegate[] = [];
+	for (const record of results.list()) {
+		if (!isStarted(record)) continue;
+		const window = ownWindow(windows, record);
+		if (window === undefined || window.exited) continue;
+		const state = deriveState(record, "open");
+		if (state !== "running" && state !== "done") continue;
+		found.push({ id: record.id, name: recordedName(record), agent: record.agent, state, window });
+	}
+	return found.reverse();
+}
+
+/** The parent's own session name, or undefined when tmux cannot say. */
+async function ownSessionName(tmux: TmuxClient): Promise<string | undefined> {
+	try {
+		return (await tmux.ownSession())?.name;
+	} catch {
+		return undefined;
+	}
+}
+
+/** The most recently active client on the parent's session, or why there is none. */
+async function clientOf(tmux: TmuxClient): Promise<{ client: string } | { refusal: string }> {
+	const session = await ownSessionName(tmux);
+	if (session === undefined) return { refusal: "could not tell which tmux session this pane is in" };
+	try {
+		const client = await tmux.clientFor(session);
+		return client === undefined ? { refusal: `no tmux client is attached to session ${session}` } : { client };
+	} catch (err) {
+		return { refusal: `could not list tmux clients: ${(err as Error).message}` };
+	}
+}
+
+async function popup(env: Env, ctx: ExtensionContext, item: OpenDelegate): Promise<void> {
+	const found = await clientOf(env.tmux);
+	if ("refusal" in found) return ctx.ui.notify(`delegate: cannot open a popup: ${found.refusal}`, "warning");
+	// Tracked before it launches, so a popup that closes at once is forgotten too.
+	const forget = env.tracking.trackPopup({
+		windowId: item.window.id,
+		windowName: item.window.name,
+		client: found.client,
+	});
+	try {
+		// Resolves once the popup is up, not when it closes; `forget` runs when it closes.
+		await env.tmux.popup(found.client, { id: item.window.id, name: item.window.name }, forget);
+	} catch (err) {
+		forget();
+		return ctx.ui.notify(`delegate: could not open a popup: ${(err as Error).message}`, "error");
+	}
+}
+
+async function switchTo(env: Env, ctx: ExtensionContext, item: OpenDelegate): Promise<void> {
+	const found = await clientOf(env.tmux);
+	if ("refusal" in found) return ctx.ui.notify(`delegate: cannot switch: ${found.refusal}`, "warning");
+	try {
+		await env.tmux.switchTo(found.client, item.window.id);
+	} catch (err) {
+		return ctx.ui.notify(`delegate: could not switch: ${(err as Error).message}`, "error");
+	}
+	ctx.ui.notify(`delegate: switched to ${item.name} (${item.window.id}) · prefix L returns you`, "info");
+}
+
+/** Enter's behaviour: a switch inside the parent's own session, else a popup. */
+async function open(env: Env, ctx: ExtensionContext, item: OpenDelegate): Promise<void> {
+	const own = await ownSessionName(env.tmux);
+	return own !== undefined && own === item.window.session ? switchTo(env, ctx, item) : popup(env, ctx, item);
+}
+
+/** Close through the `delegation_close` path, asking first only while the delegate runs. */
+async function close(env: Env, ctx: ExtensionContext, item: OpenDelegate): Promise<void> {
+	if (item.state === "running") {
+		const message = `${item.name} is still running. Close it and kill its window?`;
+		if (!(await ctx.ui.confirm("Close delegate", message))) return;
+	}
+	try {
+		ctx.ui.notify(`delegate: ${(await env.tracking.close(item.id)).text}`, "info");
+	} catch (err) {
+		ctx.ui.notify(`delegate: ${(err as Error).message}`, "error");
+	}
+}
+
+/** Show the panel; resolves with what the user chose. */
+function show(ctx: ExtensionContext, items: readonly OpenDelegate[]): Promise<PanelResult> {
+	return ctx.ui.custom<PanelResult>(
+		(tui, theme, _keybindings, done): Panel =>
+			new Panel({
+				items,
+				theme: theme as unknown as PanelTheme,
+				done,
+				redraw: (): void => tui.requestRender(),
+			}),
+	);
+}
+
+/** Peek at a delegate's pane in an overlay; true when the user chose to open it. */
+async function peek(env: Env, ctx: ExtensionContext, item: OpenDelegate): Promise<boolean> {
+	const result = await ctx.ui.custom<PeekResult>(
+		(tui, theme, _keybindings, done): PeekView =>
+			new PeekView({
+				item,
+				theme: theme as unknown as PanelTheme,
+				read: (windowId: string): Promise<string> => env.tmux.capture(windowId),
+				done,
+				redraw: (): void => tui.requestRender(),
+				rows: (): number => tui.terminal.rows,
+			}),
+		PEEK_OPTIONS,
+	);
+	return result?.action === "open";
+}
+
+const noUi = (ctx: ExtensionContext): void => ctx.ui.notify("delegate: this needs an interactive session", "error");
+const noTmux = (ctx: ExtensionContext): void => ctx.ui.notify("delegate: could not ask tmux for its windows", "error");
+
+/** Carry out what the panel returned; true when the panel should open again. */
+async function act(
+	env: Env,
+	startNew: (ctx: ExtensionContext) => Promise<void> | void,
+	ctx: ExtensionContext,
+	items: OpenDelegate[],
+	result: PanelResult,
+): Promise<boolean> {
+	if (result === undefined) return false;
+	if (result.action === "new") {
+		await startNew(ctx);
+		return false;
+	}
+	const item = items.find((candidate) => candidate.id === result.id);
+	if (item === undefined) return false;
+	if (result.action === "close") {
+		await close(env, ctx, item);
+		return true;
+	}
+	if (result.action === "peek") {
+		if (!(await peek(env, ctx, item))) return true; // back to the panel
+		await open(env, ctx, item);
+		return false;
+	}
+	await (result.action === "switch" ? switchTo(env, ctx, item) : open(env, ctx, item));
+	return false;
+}
+
+/** One action on one open delegate, as `/delegate-open` runs it. */
+async function openOne(env: Env, ctx: ExtensionContext, id: string, mode: OpenMode): Promise<void> {
+	const items = await openDelegates(env);
+	if (items === undefined) return noTmux(ctx);
+	const item = items.find((candidate) => candidate.id === id);
+	if (item === undefined) {
+		const known = items.map((candidate) => candidate.id).join(", ") || "none";
+		return ctx.ui.notify(`delegate: no open delegate ${JSON.stringify(id)}; open: ${known}`, "error");
+	}
+	if (mode === "switch") return switchTo(env, ctx, item);
+	if (mode !== "peek") return open(env, ctx, item); // --popup follows enter's rule too
+	if (!ctx.hasUI) return noUi(ctx);
+	if (await peek(env, ctx, item)) await open(env, ctx, item);
+}
+
+/** The navigator over the records, tmux and tracking. `startNew` is the new-delegate flow, wired by the entry. */
+export function createNavigator(
+	results: Results,
+	tmux: TmuxClient,
+	tracking: Pick<Tracking, "trackPopup" | "close">,
+	startNew: (ctx: ExtensionContext) => Promise<void> | void,
+): Navigator {
+	const env: Env = { results, tmux, tracking };
+	return {
+		async panel(ctx: ExtensionContext): Promise<void> {
+			if (!ctx.hasUI) return noUi(ctx);
+			for (;;) {
+				const items = await openDelegates(env);
+				if (items === undefined) return noTmux(ctx);
+				if (!(await act(env, startNew, ctx, items, await show(ctx, items)))) return;
+			}
+		},
+		openDelegate: (ctx: ExtensionContext, id: string, mode: OpenMode): Promise<void> => openOne(env, ctx, id, mode),
+		async openIds(): Promise<string[]> {
+			return (await openDelegates(env))?.map((item) => item.id) ?? [];
+		},
+	};
+}