pi-crew 0.9.68 → 0.10.2

package/src/ui/inline-panel/crew-editor.ts

@@ -0,0 +1,192 @@
+/**
+ * crew-editor.ts — the inline agent panel's keyboard half.
+ *
+ * A `CustomEditor` wrapper (pi-subtask's `SubtaskEditor` pattern): pressing
+ * `↓` on an empty prompt moves the cursor into the agent rows rendered by the
+ * crew widget; `↑`/`↓` navigate, `enter` opens the agent's live transcript
+ * pane, `x` cancels/dismisses, `escape` returns to typing.
+ *
+ * While an agent is viewed, typed text goes to the viewed agent (Claude
+ * Code's `@name` convention — the editor border is relabeled), pageUp/
+ * pageDown scroll, and `enter` steers. Normally the FULL-SCREEN overlay
+ * (agent-view-overlay.ts) owns the keyboard while open; this branch is the
+ * fallback for when the overlay could not spawn (e.g. a stale ctx between
+ * keypress and open), so the user is never stuck viewing an agent neither
+ * surface controls. Neither path is a session switch: the main conversation
+ * is never torn down to look at an agent.
+ *
+ * Every unhandled key falls through to `super.handleInput`, so the user is
+ * never trapped in a mode. All state lives in panel-store (shared with the
+ * widget renderer); this class only translates keys into state changes and
+ * host calls.
+ */
+
+import type { KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { type EditorTheme, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { PanelKeys, PanelTarget } from "./panel-selection.ts";
+import { dispatchPanelKey } from "./panel-selection.ts";
+import { getPanelSelection, getViewedAgent, panelRows, setPanelSelection } from "./panel-store.ts";
+
+export const AGENT_LABEL_MAX = 24;
+
+export interface CrewEditorOptions {
+	/** Open the transcript pane on the given agent. */
+	onOpenPane: (target: PanelTarget) => void;
+	/** Close the pane and return to the main conversation. */
+	onClosePane: () => void;
+	/** Scroll the open pane by ±wrapped lines. */
+	onScrollPane: (delta: number) => void;
+	/** Steer the viewed agent with the typed message. */
+	onSteer: (target: PanelTarget, message: string) => void;
+	/** `x`: cancel a running agent's run, or dismiss a finished one. */
+	onAct: (target: PanelTarget, finished: boolean) => void;
+}
+
+export class CrewInlineEditor extends CustomEditor {
+	private readonly options: CrewEditorOptions;
+
+	constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, options: CrewEditorOptions) {
+		super(tui, theme, keybindings);
+		this.options = options;
+	}
+
+	private panelKeys(data: string): PanelKeys {
+		return {
+			up: matchesKey(data, "up"),
+			down: matchesKey(data, "down"),
+			enter: matchesKey(data, "return"),
+			escape: matchesKey(data, "escape"),
+			act: matchesKey(data, "x"),
+		};
+	}
+
+	/**
+	 * Apply a dispatch result. `closePaneOnMain` is true while the pane is open:
+	 * `enter` on the main row then closes the pane instead of doing nothing.
+	 */
+	private applyDispatch(data: string, rows: ReturnType<typeof panelRows>, keys: PanelKeys, closePaneOnMain: boolean): void {
+		const selection = getPanelSelection();
+		const result = dispatchPanelKey(keys, rows, selection, { holdAtMain: closePaneOnMain });
+		switch (result.action.kind) {
+			case "none": {
+				// Not a navigation key: hand the editor the exact key and clear
+				// the cursor so typing proceeds normally (pi-subtask §2.5).
+				setPanelSelection(null);
+				super.handleInput(data);
+				return;
+			}
+			case "consumed": {
+				setPanelSelection(result.selection);
+				return;
+			}
+			case "open": {
+				setPanelSelection(null);
+				const target = result.action.target;
+				if (target) this.options.onOpenPane(target);
+				else if (closePaneOnMain) this.options.onClosePane();
+				return;
+			}
+			case "act": {
+				setPanelSelection(result.selection);
+				const target = result.action.target;
+				const row = rows.find((r) => r.runId === target.runId && r.taskId === target.taskId);
+				this.options.onAct(target, row?.finished ?? false);
+				return;
+			}
+		}
+	}
+
+	handleInput(data: string): void {
+		const rows = panelRows();
+		const viewed = getViewedAgent();
+
+		// ── Pane open: typing goes to the viewed agent ─────────────────────
+		// Navigation still works inside the pane: move the cursor over the
+		// rows and `enter` switches the pane to another agent (or closes it
+		// on the main row) — in place, no session involved.
+		if (viewed) {
+			if (getPanelSelection() !== null) {
+				this.applyDispatch(data, rows, this.panelKeys(data), true);
+				return;
+			}
+			if (matchesKey(data, "down") && this.getText() === "" && rows.length > 0) {
+				setPanelSelection("main");
+				return;
+			}
+			if (matchesKey(data, "escape")) {
+				this.options.onClosePane();
+				return;
+			}
+			if (matchesKey(data, "pageUp")) {
+				this.options.onScrollPane(10);
+				return;
+			}
+			if (matchesKey(data, "pageDown")) {
+				this.options.onScrollPane(-10);
+				return;
+			}
+			if (matchesKey(data, "return")) {
+				const text = (this.getExpandedText?.() ?? this.getText()).trim();
+				if (!text) {
+					// Empty enter: hand it back to the editor rather than
+					// swallowing the key (keeps the "never stick" contract).
+					super.handleInput(data);
+					return;
+				}
+				if (text.startsWith("/")) {
+					// Slash commands still act on the main session's command
+					// executor, like Claude Code's transcript view.
+					super.handleInput(data);
+					return;
+				}
+				// Shift+Enter (newline) never reaches here: matchesKey
+				// distinguishes the shifted sequence from plain return.
+				this.setText("");
+				this.options.onSteer(viewed, text);
+				return;
+			}
+			super.handleInput(data);
+			return;
+		}
+
+		// ── Idle: `↓` on an empty prompt enters the panel ──────────────────
+		if (getPanelSelection() === null) {
+			if (matchesKey(data, "down") && this.getText() === "" && rows.length > 0) {
+				// dispatch enters at the MAIN row; the widget renders that row
+				// with its own ❯ marker so the very first press is visible
+				// (pi-subtask's selectRow(rows, 0)).
+				const result = dispatchPanelKey(this.panelKeys(data), rows, null);
+				setPanelSelection(result.selection);
+				return;
+			}
+			super.handleInput(data);
+			return;
+		}
+
+		// ── Navigating: consume or fall through ────────────────────────────
+		this.applyDispatch(data, rows, this.panelKeys(data), false);
+	}
+
+	/**
+	 * Relabel the editor's top border with the viewed agent, so it is
+	 * unambiguous where typed text lands — pi-subtask's `@name` marker.
+	 */
+	render(width: number): string[] {
+		const lines = super.render(width);
+		const viewed = getViewedAgent();
+		if (!viewed) return lines;
+		const rows = panelRows();
+		const row = rows.find((r) => r.runId === viewed.runId && r.taskId === viewed.taskId);
+		const name = row?.name ?? viewed.taskId.slice(-AGENT_LABEL_MAX);
+		if (name && lines.length > 0) {
+			const label = ` @${truncateToWidth(name.replace(/\s+/g, " "), AGENT_LABEL_MAX)} `;
+			const labelWidth = visibleWidth(label);
+			if (visibleWidth(lines[0]) >= labelWidth + 4) {
+				lines[0] = truncateToWidth(lines[0], width - labelWidth - 2, "") + label + "──";
+			}
+		}
+		return lines;
+	}
+}

package/src/ui/inline-panel/index.ts

@@ -0,0 +1,290 @@
+/**
+ * inline-panel/index.ts — install/uninstall of the inline agent panel.
+ *
+ * Owns the two half-mounted surfaces:
+ *  - the `CrewInlineEditor` wrapper (installed via `setEditorComponent` when no
+ *    other extension owns the editor), which translates ↓/↑/enter/x/escape
+ *    into panel-store changes and host calls;
+ *  - the FULL-SCREEN agent view overlay (`ctx.ui.custom` with `overlay:
+ *    true`, width "100%"), the LIVE transcript of the viewed agent.
+ *
+ * Entering an agent row takes over the whole terminal with that agent's live
+ * transcript — a separate view, not content appended under the main session.
+ * The overlay tails the agent's on-disk event log (events.jsonl, appended in
+ * real time by the running child pi worker) and renders through pi's own
+ * transcript components. The main session is never switched, resumed, or torn
+ * down to look at an agent, so viewing can never kill a run or strand the
+ * editor. (The previous design — copy the worker's session file and
+ * `switchSession` to it, re-switching every few seconds — cancelled live runs
+ * on teardown, froze at the copy timestamp, and crashed on stale extension
+ * ctxs; see the "fix(view)" chain in git history.)
+ *
+ * All heavy team-tool interaction (steer, cancel) is lazy-imported so this
+ * module never pulls the runtime chain at startup (AGENTS.md lazy boundary).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { CrewUiConfig } from "../../config/types.ts";
+import { isToolError, type PiTeamsToolResult, textFromToolResult } from "../../extension/tool-result.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { requestRender } from "../pi-ui-compat.ts";
+import type { CrewAgentPane } from "./agent-pane.ts";
+import { resetAllAgentTranscriptCursors } from "./agent-transcript.ts";
+import { CrewAgentOverlay } from "./agent-view-overlay.ts";
+import { CrewInlineEditor } from "./crew-editor.ts";
+import type { PanelTarget } from "./panel-selection.ts";
+import { resetPanelStore, setViewedAgent } from "./panel-store.ts";
+
+/**
+ * Live repaint cadence while the view is open. The pane re-reads the agent's
+ * event log during render() (throttled internally), so a periodic
+ * requestRender keeps it following the worker even when pi's own repaints
+ * are idle (no spinner, no typing). pi-subtask drives this from child RPC
+ * events; our workers write to disk, so the pane is disk-tailed instead.
+ */
+const PANE_LIVE_TICK_MS = 700;
+
+let livePane: CrewAgentPane | undefined;
+let liveOverlay: CrewAgentOverlay | undefined;
+let paneTickTimer: ReturnType<typeof setInterval> | undefined;
+let editorInstalled = false;
+/** Guards the one-time per-process event hooks. */
+let hooksRegistered = false;
+
+function startPaneTicker(): void {
+	if (paneTickTimer) return;
+	paneTickTimer = setInterval(() => livePane?.requestRender(), PANE_LIVE_TICK_MS);
+	paneTickTimer.unref?.();
+}
+
+function stopPaneTicker(): void {
+	if (paneTickTimer) {
+		clearInterval(paneTickTimer);
+		paneTickTimer = undefined;
+	}
+	livePane = undefined;
+}
+
+async function runTeamTool(params: Record<string, unknown>, ctx: ExtensionContext): Promise<PiTeamsToolResult> {
+	// LAZY: team-tool.ts pulls in the entire runtime chain (same boundary as
+	// run-action-dispatcher.ts).
+	// LAZY: (marker on the import line's previous line, per check-lazy-imports)
+	const { handleTeamTool } = await import("../../extension/team-tool.ts");
+	return handleTeamTool(params as never, ctx);
+}
+
+function notifyResult(ctx: ExtensionContext, result: PiTeamsToolResult): void {
+	const text = textFromToolResult(result);
+	ctx.ui.notify(isToolError(result) ? `panel: ${text}` : text, isToolError(result) ? "error" : "info");
+}
+
+/**
+ * Open the viewed agent's LIVE transcript as a FULL-SCREEN overlay (or, when
+ * one is already open, just re-target it — the pane follows the panel store).
+ * Pure overlay wiring — no session is touched, so there is nothing to settle,
+ * detach, or guard: the view works in every session state, for foreground and
+ * async runs alike, and closing it never affects the run.
+ */
+function openPane(ctx: ExtensionContext, target: PanelTarget): void {
+	setViewedAgent(target);
+	if (!liveOverlay) {
+		try {
+			void ctx.ui
+				.custom(
+					(tui, theme, _keybindings, done) => {
+						const overlay = new CrewAgentOverlay(tui as never, theme as never, ctx.cwd, {
+							close: () => {
+								liveOverlay = undefined;
+								livePane = undefined;
+								setViewedAgent(undefined);
+								stopPaneTicker();
+								try {
+									done(undefined);
+								} catch {
+									/* already closed by the host */
+								}
+							},
+							steer: (steerTarget, message) => void steerAgent(ctx, steerTarget, message),
+						});
+						liveOverlay = overlay;
+						livePane = overlay.pane;
+						return overlay as never;
+					},
+					{
+						overlay: true,
+						overlayOptions: { width: "100%", margin: 0, maxHeight: "100%", anchor: "top-left" },
+					},
+				)
+				.catch((error) => {
+					// Factory throw or the host tearing the overlay down: drop the
+					// view state so the dock does not point at a view that no
+					// longer exists.
+					liveOverlay = undefined;
+					livePane = undefined;
+					setViewedAgent(undefined);
+					stopPaneTicker();
+					logInternalError("view.openOverlay", error, target.taskId);
+				});
+		} catch (error) {
+			// A stale ctx (session replaced between keypress and here) drops the
+			// overlay spawn; the fallback editor path still closes cleanly.
+			logInternalError("view.openPane", error, target.taskId);
+		}
+	}
+	startPaneTicker();
+	try {
+		requestRender(ctx);
+	} catch {
+		/* stale ctx — nothing to repaint */
+	}
+}
+
+/** Close the view and return to the main conversation. Never touches the run. */
+function closePane(_ctx: ExtensionContext): void {
+	if (liveOverlay) {
+		// The overlay owns its teardown (state reset + host `done()`); the
+		// requestClose path is idempotent.
+		liveOverlay.requestClose();
+		return;
+	}
+	setViewedAgent(undefined);
+	stopPaneTicker();
+}
+
+async function steerAgent(ctx: ExtensionContext, target: PanelTarget, message: string): Promise<void> {
+	try {
+		notifyResult(ctx, await runTeamTool({ action: "steer", runId: target.runId, taskId: target.taskId, message }, ctx));
+		// Delivery is at the child's next turn boundary, not mid-tool-call;
+		// say so explicitly so the user does not read silence as a dropped message.
+		ctx.ui.notify("Will be delivered at the worker's next turn boundary.", "info");
+	} catch (error) {
+		ctx.ui.notify(`panel: steer failed — ${error instanceof Error ? error.message : String(error)}`, "error");
+	}
+}
+
+async function actOnAgent(ctx: ExtensionContext, target: PanelTarget, finished: boolean): Promise<void> {
+	if (finished) {
+		// Finished rows age out of the linger window on their own. `x` here
+		// only returns focus to typing; resume/inspect stays in the dashboard
+		// so a single keystroke never mutates anything.
+		ctx.ui.notify("Agent is finished — use /team-dashboard to inspect or resume.", "info");
+		return;
+	}
+	// Cancel is run-level in the team tool, so a single-keystroke `x` must not
+	// silently destroy a whole run: confirm first.
+	const confirmed = await ctx.ui.confirm(
+		"Cancel entire run?",
+		`This cancels run ${target.runId} and all its workers. Ongoing work stops; resume re-queues what was left.`,
+	);
+	if (!confirmed) {
+		ctx.ui.notify("Cancel aborted.", "info");
+		return;
+	}
+	try {
+		notifyResult(ctx, await runTeamTool({ action: "cancel", runId: target.runId }, ctx));
+	} catch (error) {
+		ctx.ui.notify(`panel: cancel failed — ${error instanceof Error ? error.message : String(error)}`, "error");
+	}
+}
+
+// ── Agent view commands ────────────────────────────────────────────────
+//
+// `/crew-view <runId> <taskId>` and `/crew-back` are thin aliases for the
+// pane wiring above (open / close). They never switch sessions — the dock's
+// enter key takes the same path.
+
+async function handleCrewViewCommand(args: string, ctx: ExtensionContext): Promise<void> {
+	const tokens = args.trim().split(/\s+/).filter(Boolean);
+	if (tokens.length < 2) {
+		ctx.ui.notify("Usage: /crew-view <runId> <taskId>", "error");
+		return;
+	}
+	const [runId, taskId] = tokens;
+	// LAZY: state-store is runtime state, not a UI dependency.
+	// LAZY: (marker on the import line's previous line, per check-lazy-imports)
+	const { loadRunManifestById } = await import("../../state/stores/state-store.ts");
+	if (!loadRunManifestById(ctx.cwd, runId)) {
+		ctx.ui.notify(`No run ${runId} in this project.`, "error");
+		return;
+	}
+	openPane(ctx, { runId, taskId });
+}
+
+async function handleCrewBackCommand(_args: string, ctx: ExtensionContext): Promise<void> {
+	closePane(ctx);
+}
+
+/**
+ * Install the panel for a session. Call from session_start AFTER the widget
+ * has been registered, with the already-loaded UI config.
+ *
+ * Yields to any other extension that owns the editor component (pi-subtask
+ * rule §2.6): without the editor wrapper there is no keyboard access, so the
+ * panel stays display-only and /team-dashboard remains the full path.
+ */
+export function installInlinePanel(pi: ExtensionAPI, ctx: ExtensionContext, uiConfig?: CrewUiConfig): void {
+	if (!ctx.hasUI) return;
+
+	const enabled = uiConfig?.inlinePanel !== false;
+	try {
+		if (enabled && !editorInstalled && !ctx.ui.getEditorComponent()) {
+			ctx.ui.setEditorComponent((tui, theme, kb) => {
+				// Fresh instance per session; options close over the current ctx.
+				return new CrewInlineEditor(tui, theme, kb, {
+					onOpenPane: (target) => openPane(ctx, target),
+					onClosePane: () => closePane(ctx),
+					onScrollPane: (delta) => livePane?.scrollBy(delta),
+					onSteer: (target, message) => void steerAgent(ctx, target, message),
+					onAct: (target, finished) => void actOnAgent(ctx, target, finished),
+				});
+			});
+			editorInstalled = true;
+		}
+	} catch {
+		/* editor context can be transient across session replacement */
+	}
+
+	// Commands must be re-registered for EVERY session: pi rebuilds the
+	// extension command table on session replacement. registerCommand is
+	// idempotent on the current session's runner.
+	pi.registerCommand("crew-view", {
+		description: "Open an agent's live full-screen transcript view (usage: crew-view <runId> <taskId>)",
+		handler: handleCrewViewCommand,
+	});
+	pi.registerCommand("crew-back", {
+		description: "Close the agent transcript view and return to the main conversation",
+		handler: handleCrewBackCommand,
+	});
+
+	if (!hooksRegistered) {
+		hooksRegistered = true;
+		pi.on("session_shutdown", () => {
+			stopPaneTicker();
+			livePane = undefined;
+			liveOverlay = undefined;
+			resetPanelStore();
+			resetAllAgentTranscriptCursors();
+		});
+		pi.on("session_start", () => {
+			// pi may have replaced or dropped its editor between sessions; the
+			// "installed" flag is reset so the next install re-registers the
+			// factory. The open overlay outlives the session swap (it belongs
+			// to the interactive-mode UI, not the session's ctx) — keep it, but
+			// stop ticking until it is re-targeted.
+			editorInstalled = false;
+			stopPaneTicker();
+		});
+	}
+}
+
+/** Test hook: force the next install to re-attempt the editor. */
+export function __resetInlinePanelForTest(): void {
+	editorInstalled = false;
+	liveOverlay = undefined;
+	stopPaneTicker();
+}
+
+/** Test seam for openPane (the panel wires it as the dock's Enter action). */
+/** Test seam for closePane. */
+export { closePane as __test__closePane, openPane as __test__openPane };

package/src/ui/inline-panel/panel-rows.ts

@@ -0,0 +1,37 @@
+/**
+ * panel-rows.ts — project the widget's run list into navigable panel rows.
+ *
+ * The order here MUST match what the widget paints, otherwise the cursor index
+ * drifts from the visible rows and `enter`/`x` act on the wrong agent. Both
+ * sides therefore call the same `orderWidgetAgents` helper; this module only
+ * flattens the per-run sections into one list.
+ */
+
+import { isFinishedRunStatus } from "../../runtime/process-status.ts";
+import { orderWidgetAgents } from "../widget/widget-renderer.ts";
+import type { WidgetRun } from "../widget/widget-types.ts";
+import type { PanelRow } from "./panel-selection.ts";
+
+/**
+ * Flatten runs → rows in paint order: per run, active agents (running > queued >
+ * waiting) followed by the finished agents still inside their linger window.
+ */
+export function panelRowsFromRuns(runs: readonly WidgetRun[], now = Date.now()): PanelRow[] {
+	const rows: PanelRow[] = [];
+	for (const entry of runs) {
+		const { active, finished } = orderWidgetAgents(entry, now);
+		for (const agent of active) {
+			rows.push({ runId: entry.run.runId, taskId: agent.taskId, finished: false, name: agent.agent });
+		}
+		for (const agent of finished) {
+			rows.push({ runId: entry.run.runId, taskId: agent.taskId, finished: true, name: agent.agent });
+		}
+	}
+	return rows;
+}
+
+/** True when the row's run has reached a terminal status (nothing left to cancel). */
+export function isRunFinished(runs: readonly WidgetRun[], runId: string): boolean {
+	const entry = runs.find((item) => item.run.runId === runId);
+	return entry ? isFinishedRunStatus(entry.run.status) : true;
+}

package/src/ui/inline-panel/panel-selection.ts

@@ -0,0 +1,157 @@
+/**
+ * panel-selection.ts — pure cursor state machine for the inline agent panel.
+ *
+ * No I/O, no TUI types: the editor wrapper feeds it a key and the current row
+ * list, and gets back an action to perform. That keeps the whole navigation
+ * contract unit-testable against a synthetic row list.
+ *
+ * Row 0 is always `main` (the conversation itself); agents occupy 1..n.
+ *
+ * The cursor is stored as an **identity**, not an index. Rows reorder while the
+ * user is navigating — a cancelled agent sinks from the active section into the
+ * finished one — and an index cursor would silently retarget whichever agent
+ * took the vacated row. Storing the taskId means a second keystroke acts on the
+ * same agent the first one did.
+ */
+
+/** A concrete agent the panel can act on. */
+export interface PanelTarget {
+	runId: string;
+	taskId: string;
+}
+
+/** One navigable agent row, as projected from the widget's run list. */
+export interface PanelRow extends PanelTarget {
+	/** Terminal statuses are dismissed by `x`; live ones are cancelled. */
+	finished: boolean;
+	/** Agent name, used for the editor's `@<name>` label while its pane is open. */
+	name: string;
+}
+
+/**
+ * `null` means the editor owns the cursor (normal typing). `"main"` is the
+ * conversation row. Anything else is an agent.
+ */
+export type PanelSelection = "main" | PanelTarget | null;
+
+export type PanelAction =
+	/** Not a navigation key — the caller must forward it to the editor. */
+	| { kind: "none" }
+	/** Cursor moved or selection cleared; repaint and swallow the key. */
+	| { kind: "consumed" }
+	/** `enter`: open the target's pane, or return to `main` when undefined. */
+	| { kind: "open"; target: PanelTarget | undefined }
+	/** `x`: cancel a running agent, or dismiss a finished one. */
+	| { kind: "act"; target: PanelTarget };
+
+export interface PanelKeys {
+	up: boolean;
+	down: boolean;
+	enter: boolean;
+	escape: boolean;
+	act: boolean;
+}
+
+export interface DispatchOptions {
+	/**
+	 * When true, `up` at the main row keeps the cursor there instead of handing
+	 * focus back to the editor. Used while a transcript pane is open, so one
+	 * `down` + `enter` is always a reliable way back to the conversation.
+	 */
+	holdAtMain?: boolean;
+}
+
+export interface DispatchResult {
+	action: PanelAction;
+	selection: PanelSelection;
+}
+
+function sameTarget(a: PanelTarget, b: PanelTarget): boolean {
+	return a.runId === b.runId && a.taskId === b.taskId;
+}
+
+/** True when `selection` points at a concrete agent (not `main`/editor). */
+export function isAgentSelection(selection: PanelSelection): selection is PanelTarget {
+	return selection !== null && selection !== "main";
+}
+
+/**
+ * Numeric cursor position for the current rows, or `null` when the editor owns
+ * the cursor. A selection whose agent has disappeared (dismissed, aged out of
+ * the linger window) resolves to the main row rather than to a stranger.
+ */
+export function resolveIndex(rows: readonly PanelRow[], selection: PanelSelection): number | null {
+	if (selection === null) return null;
+	if (selection === "main") return 0;
+	const found = rows.findIndex((row) => sameTarget(row, selection));
+	return found >= 0 ? found + 1 : 0;
+}
+
+/** Selection for a numeric position, clamped into range. Index 0 is `main`. */
+export function selectionAtIndex(rows: readonly PanelRow[], index: number): PanelSelection {
+	const clamped = Math.max(0, Math.min(rows.length, index));
+	if (clamped === 0) return "main";
+	const row = rows[clamped - 1];
+	return row ? { runId: row.runId, taskId: row.taskId } : "main";
+}
+
+/** The row a selection currently points at, if it is still present. */
+export function rowFor(rows: readonly PanelRow[], selection: PanelSelection): PanelRow | undefined {
+	if (!isAgentSelection(selection)) return undefined;
+	return rows.find((row) => sameTarget(row, selection));
+}
+
+/**
+ * Apply one keypress.
+ *
+ * Any key that is not a navigation key returns `{ kind: "none" }` with the
+ * selection cleared, so the caller can forward it to the editor and the user is
+ * never trapped in a mode.
+ */
+export function dispatchPanelKey(
+	keys: PanelKeys,
+	rows: readonly PanelRow[],
+	selection: PanelSelection,
+	options: DispatchOptions = {},
+): DispatchResult {
+	// Editor owns the cursor: the only panel key that makes sense is `down`,
+	// entering at the main row (pi-subtask: selectRow(rows, 0)). The main row
+	// is a real rendered row with its own ❯ marker, so this first press is
+	// visible immediately — no dead-key feeling. Everything else falls
+	// through untouched.
+	if (selection === null) {
+		if (keys.down) return { action: { kind: "consumed" }, selection: "main" };
+		return { action: { kind: "none" }, selection: null };
+	}
+
+	const index = resolveIndex(rows, selection) ?? 0;
+
+	if (keys.up) {
+		if (index === 0 && options.holdAtMain !== true) return { action: { kind: "consumed" }, selection: null };
+		return { action: { kind: "consumed" }, selection: selectionAtIndex(rows, index - 1) };
+	}
+	if (keys.down) {
+		return { action: { kind: "consumed" }, selection: selectionAtIndex(rows, index + 1) };
+	}
+	if (keys.escape) {
+		return { action: { kind: "consumed" }, selection: null };
+	}
+	if (keys.enter) {
+		const target = index > 0 ? rows[index - 1] : undefined;
+		return {
+			action: { kind: "open", target: target ? { runId: target.runId, taskId: target.taskId } : undefined },
+			selection: null,
+		};
+	}
+	if (keys.act && index > 0) {
+		const target = rows[index - 1];
+		if (!target) return { action: { kind: "consumed" }, selection: selectionAtIndex(rows, 0) };
+		// Selection stays on the SAME agent so a follow-up keystroke acts on it
+		// again rather than on whichever row the reorder promoted.
+		return {
+			action: { kind: "act", target: { runId: target.runId, taskId: target.taskId } },
+			selection: { runId: target.runId, taskId: target.taskId },
+		};
+	}
+	return { action: { kind: "none" }, selection: null };
+}