pi-cockpit 0.9.0 → 0.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 A responsive **agent cockpit** for [Pi](https://pi.dev): wide terminals get a docked Maestro operations sidebar, narrow terminals automatically fall back to the existing Todo and Agent widgets, and every layout keeps the Starship-style footer.
 
-It is the third plugin of the `pi-maestro-flow` project (alongside `pi-maestro-flow` and `pi-maestro-teammate`). It is installed and registered with `pi-maestro-flow`, but it also runs standalone. Current version: **0.8.0**.
+It is the third plugin of the `pi-maestro-flow` project (alongside `pi-maestro-flow` and `pi-maestro-teammate`). It is installed and registered with `pi-maestro-flow`, but it also runs standalone. Current version: **0.9.1**.
 
 The dock is a non-capturing top-right overlay. Cockpit reserves its columns by wrapping the active TUI renderer at runtime, so the Pi workspace reflows instead of rendering underneath it. No Pi source files are modified.
 
@@ -25,7 +25,7 @@ The dock is a non-capturing top-right overlay. Cockpit reserves its columns by w
 `pi-cockpit` comes automatically with the orchestration layer — installing `pi-maestro-flow` pulls `pi-cockpit` and registers it into `settings.packages` on postinstall, no manual setup required. To use it on its own:
 
 ```bash
-pi install npm:pi-cockpit     # standalone from npm
+pi install npm:pi-cockpit@0.9.1     # standalone from npm
 # or, for one run:
 pi -e ./packages/pi-cockpit
 ```
@@ -122,7 +122,7 @@ The tab title is `frame + pi - <session> - <working state>`. The session part fo
 
 ## Sidebar compatibility
 
-The split-pane wrapper depends on Pi's current TUI renderer shape and is verified against Pi `0.82.1`. A render integration failure disables the split and retries the original renderer at full width.
+The split-pane wrapper depends on Pi's current TUI renderer shape and is verified against Pi `0.83.0`. A render integration failure disables the split and retries the original renderer at full width.
 
 Do not enable `pi-cockpit`'s dock and `pi-atelier@0.7.0`'s sidebar together. Both reserve columns by wrapping the same renderer, and `pi-atelier@0.7.0` does not participate in Cockpit's split-owner marker protocol. Use `"sidebar": { "mode": "off" }` when running Atelier.
 
@@ -137,6 +137,46 @@ The original mockup was a browser page; a terminal is an ANSI stream with no DOM
 | Scanlines / logo light-up animation | no overlay/animation layer | a braille spinner frame, advanced on each redraw |
 | In-stream thinking-collapse / edit progress bar / colored bash stdout | built-in message & built-in tool rendering is **not** replaceable by extensions (`renderCall`/`renderResult` only apply to tools *you* register) | the conversation stream is left to Pi's native renderer — it is context, not a cockpit deliverable |
 
+## Claude Code-style interactions (all opt-in, all default off)
+
+Three independent settings, each stored in `cockpit.json` and exposed bilingually in `/cockpit` and `/maestro-settings`:
+
+| Setting | Default | Applies | What it does |
+|---|---|---|---|
+| `doubleEscapeClearInput` | off | after `/reload` | Press Escape twice quickly to clear a non-empty input draft. The first Escape keeps its native meaning; an empty-draft double-Escape stays pi's rewind/tree action. Requires the Cockpit custom editor (`/reload`). |
+| `fullscreenInput` | off | after `/reload` | Alternate screen with the editor fixed at the bottom and an application-scrolled transcript. Wheel scrolls history while the editor stays put; `↑ n new · click to bottom` appears when new output arrives while you are scrolled up. Replaces terminal-native scrollback/search inside fullscreen. Requires the Cockpit custom editor (`/reload`). |
+| `copyOnSelect` | off | live | Drag inside the fullscreen transcript to select; the visible text is copied to the clipboard on release. Effective only while `fullscreenInput` is active. |
+
+Interaction rules:
+
+- The three settings are independent; `copyOnSelect` is inert without `fullscreenInput`.
+- The legacy `pinEditorBottom` keeps working in normal mode and is ignored inside fullscreen.
+- If another extension already owns a custom editor, `doubleEscapeClearInput` and `fullscreenInput` fail closed with one warning (they share the Cockpit custom editor) and never overwrite it.
+- A clipboard failure shows a warning and keeps the selection so you can retry.
+
+### Terminal capability matrix
+
+Fullscreen needs an alternate screen (`?1049`) and SGR mouse reporting (`1006`/`1002`); copy-on-select additionally needs drag selection to be application-owned. No universal support is claimed — this is best effort, opt-in, and `TERM=dumb`/unset is refused with a warning.
+
+| Terminal | Alternate screen | SGR mouse | Copy-on-select | Verified |
+|---|---|---|---|---|
+| iTerm2 | ✓ | ✓ | ✓ | expected |
+| Ghostty | ✓ | ✓ | ✓ | expected |
+| WezTerm | ✓ | ✓ | ✓ | expected |
+| kitty | ✓ | ✓ | ✓ | expected |
+| Windows Terminal | ✓ | ✓ | ✓ | expected |
+| VS Code integrated terminal | ✓ | ✓ | ✓ | expected |
+| tmux (no `-T` config) | depends | depends | depends | not claimed |
+| `TERM=dumb` | ✗ | ✗ | ✗ | refused with a warning |
+
+### Manual smoke checklist
+
+1. `/maestro-settings` → Cockpit → enable `doubleEscapeClearInput`, then `/reload`; type a draft and press Escape twice — the draft clears; a single Escape does nothing; with an empty draft two Escapes still open the tree selector.
+2. Enable `fullscreenInput`, `/reload`; scroll the transcript with the mouse wheel — the editor stays fixed at the bottom; while scrolled up, new output shows the `↑ n new` hint; clicking it returns to the bottom.
+3. Enable `copyOnSelect` (live, no reload); drag across transcript lines — the visible text lands on the clipboard (verify with `pbpaste` on macOS); a plain click does not copy; a copy failure (e.g. headless) shows a warning and keeps the selection.
+4. Toggle everything off and `/reload` — behavior returns to stock pi.
+5. If a terminal ever gets stuck in a blank alternate screen (crash while fullscreen), run `reset` to restore the normal screen.
+
 ## Local development
 
 ```bash

package/package.json

@@ -1,75 +1,80 @@
-{
-  "name": "pi-cockpit",
-  "version": "0.9.0",
-  "description": "Responsive Maestro operations sidebar, fallback status widgets, and footer for Pi.",
-  "type": "module",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "tui",
-    "teammate",
-    "todo"
-  ],
-  "license": "MIT",
-  "files": [
-    "src/",
-    "themes/",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node --test --experimental-transform-types tests/config.test.ts tests/public-events.test.ts tests/maestro-store.test.ts tests/split-pane.test.ts tests/editor-bottom.test.ts tests/sidebar-render.test.ts tests/sidebar-controller.test.ts tests/viewport-stability.test.ts tests/quiet-tools.test.ts tests/agents-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/settings-view.test.ts tests/thinking-fold.test.ts tests/thinking-timer.test.ts tests/tick-policy.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts tests/title-gen.test.ts tests/title-llm.test.ts tests/settings-registry.test.ts tests/settings-coordinator.test.ts tests/settings-locale.test.ts tests/settings-shell.test.ts tests/settings-cockpit-provider.test.ts tests/settings-cross-package.test.ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "pi": {
-    "extensions": [
-      "./src/extension/index.ts"
-    ],
-    "themes": [
-      "./themes"
-    ]
-  },
-  "dependencies": {
-    "pi-maestro-settings-core": "0.1.0",
-    "proper-lockfile": "4.1.2"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "pi-maestro-teammate": "^1.6.0"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-agent-core": {
-      "optional": true
-    },
-    "@earendil-works/pi-ai": {
-      "optional": true
-    },
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "@earendil-works/pi-tui": {
-      "optional": true
-    },
-    "pi-maestro-teammate": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.83.0",
-    "@earendil-works/pi-ai": "0.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@earendil-works/pi-tui": "0.83.0",
-    "@types/node": "^22.0.0",
-    "pi-maestro-teammate": "1.7.0",
-    "typescript": "^5.5.0"
-  },
-  "main": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./v1/events": "./src/public/v1/events.ts",
-    "./src/*": "./src/*"
-  }
-}
+{
+  "name": "pi-cockpit",
+  "version": "0.10.0",
+  "description": "Responsive Maestro operations sidebar, fallback status widgets, and footer for Pi.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "tui",
+    "teammate",
+    "todo"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "themes/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-transform-types tests/config.test.ts tests/public-events.test.ts tests/maestro-store.test.ts tests/split-pane.test.ts tests/editor-bottom.test.ts tests/sidebar-render.test.ts tests/sidebar-controller.test.ts tests/viewport-stability.test.ts tests/quiet-tools.test.ts tests/edit-guard.test.ts tests/agents-store.test.ts tests/supervision-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/agent-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/agent-scroll.test.ts tests/session-bar.test.ts tests/session-detail.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/input-routing.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/settings-view.test.ts tests/thinking-fold.test.ts tests/thinking-timer.test.ts tests/tick-policy.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts tests/model-picker.test.ts tests/title-gen.test.ts tests/title-llm.test.ts tests/settings-registry.test.ts tests/settings-coordinator.test.ts tests/settings-locale.test.ts tests/settings-shell.test.ts tests/settings-cockpit-provider.test.ts tests/settings-cross-package.test.ts tests/ui-primitives.test.ts tests/settings-shell-secret.test.ts tests/settings-shell-listcrud.test.ts tests/capturing-overlay.test.ts tests/claude-editor.test.ts tests/fullscreen-controller.test.ts tests/transcript-selection.test.ts tests/terminal-cleanup.test.ts tests/terminal-capability.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "dependencies": {
+    "pi-maestro-settings-core": "0.1.0",
+    "proper-lockfile": "4.1.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "pi-maestro-teammate": "^1.6.0",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "pi-maestro-teammate": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
+    "@types/node": "^22.0.0",
+    "pi-maestro-teammate": "1.8.0",
+    "typebox": "1.3.7",
+    "typescript": "^5.5.0"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./v1/events": "./src/public/v1/events.ts",
+    "./src/*": "./src/*"
+  }
+}

package/src/agent-overlay.ts

@@ -0,0 +1,337 @@
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import {
+	Key,
+	type Component,
+	type Focusable,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { effectiveAgentStatus, type AgentDisplayStatus } from "./agents-store.ts";
+import { scrollBy, type AgentScrollState } from "./agent-scroll.ts";
+import type { IconGlyphs } from "./icons.ts";
+import { visibleStart } from "./layout.ts";
+import { buildAgentTree } from "./render.ts";
+import {
+	renderSessionDetail,
+	sessionDetailBodyLength,
+	sessionDetailWindowRows,
+} from "./session-detail.ts";
+import { visibleAgentRows } from "./stack-widget.ts";
+import type { AgentRow } from "./types.ts";
+import { overlayListRows } from "./viewport.ts";
+
+export interface AgentOverlayParams {
+	getAgents: () => readonly AgentRow[];
+	getViewingId: () => string | undefined;
+	onSelect: (correlationId: string) => void;
+	onCommand: (correlationId: string, action: "interrupt" | "steer", message?: string) => void;
+	requestRender: () => void;
+	close: () => void;
+	theme: Theme;
+	glyphs: IconGlyphs;
+	getTerminalRows?: () => number | undefined;
+}
+
+const CARD_CHROME_ROWS = 5;
+const COMMAND_ACK_MS = 1_500;
+
+/** Plain letters reserved for command keys stay out of the draft. */
+function isDraftInput(data: string): boolean {
+	return data.length === 1 && data >= " ";
+}
+
+export class AgentOverlay implements Component, Focusable {
+	focused = false;
+	private selectedId: string | undefined;
+	private outputScroll: AgentScrollState = { offset: 0, following: true };
+	private detailWidth = 80;
+	private detailRows = 8;
+	private compose: { targetId: string; draft: string } | null = null;
+	private lastAck: { text: string; at: number; error?: boolean } | null = null;
+	private ackTimer: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(private readonly params: AgentOverlayParams) {
+		this.selectedId = params.getViewingId();
+	}
+
+	invalidate(): void {}
+	dispose(): void {
+		if (this.ackTimer) clearTimeout(this.ackTimer);
+		this.ackTimer = undefined;
+	}
+
+	handleInput(data: string): void {
+		if (this.compose) {
+			if (matchesKey(data, Key.escape)) {
+				this.compose = null;
+			} else if (data === "\r" || data === "\n") {
+				const targetId = this.compose.targetId;
+				const draft = this.compose.draft.trim();
+				this.compose = null;
+				// The compose target is frozen: the steer must never silently
+				// re-target another agent because the roster selection moved.
+				const target = this.entries().find((entry) => entry.row.correlationId === targetId)?.row;
+				if (!target) {
+					this.ack(`steer aborted: @${this.agentName(targetId)} is gone`, true);
+				} else if (draft) {
+					this.params.onCommand(targetId, "steer", draft);
+					this.ack(`steer @${target.name || target.role || target.agent || targetId}: ${draft}`);
+				}
+			} else if (data === "\x7f" || data === "\x08") {
+				this.compose.draft = this.compose.draft.slice(0, -1);
+			} else if (isDraftInput(data)) {
+				this.compose.draft += data;
+			}
+			this.params.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.escape)) {
+			this.params.close();
+			return;
+		}
+		if (matchesKey(data, Key.up)) {
+			this.moveSelection(-1);
+			return;
+		}
+		if (matchesKey(data, Key.down)) {
+			this.moveSelection(1);
+			return;
+		}
+		if (matchesKey(data, Key.home)) {
+			this.selectIndex(0);
+			return;
+		}
+		if (matchesKey(data, Key.end)) {
+			this.selectIndex(this.entries().length - 1);
+			return;
+		}
+		if (matchesKey(data, Key.pageUp)) {
+			this.scrollOutput(-Math.max(1, this.detailRows - 2));
+			return;
+		}
+		if (matchesKey(data, Key.pageDown)) {
+			this.scrollOutput(Math.max(1, this.detailRows - 2));
+			return;
+		}
+		if (data === "i" && this.selectedId) {
+			// Interrupt (打断): abort the current turn/tool; the agent stays alive
+			// and is told to report and continue.
+			this.params.onCommand(this.selectedId, "interrupt");
+			this.ack(`interrupt @${this.agentName(this.selectedId)}`);
+			return;
+		}
+		if (data === "s" && this.selectedId) {
+			// Steer (引导): interrupt + inject the drafted message. The target is
+			// frozen at compose time so later roster changes cannot re-target it.
+			this.compose = { targetId: this.selectedId, draft: "" };
+			this.params.requestRender();
+		}
+	}
+
+	private ack(text: string, error = false): void {
+		this.lastAck = { text, at: Date.now(), ...(error ? { error: true } : {}) };
+		if (this.ackTimer) clearTimeout(this.ackTimer);
+		this.ackTimer = setTimeout(() => {
+			this.ackTimer = undefined;
+			this.lastAck = null;
+			this.params.requestRender();
+		}, COMMAND_ACK_MS);
+		this.ackTimer.unref?.();
+		this.params.requestRender();
+	}
+
+	private agentName(correlationId: string): string {
+		const row = this.entries().find((entry) => entry.row.correlationId === correlationId)?.row;
+		return row?.name || row?.role || row?.agent || correlationId.slice(0, 8);
+	}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(1, Math.min(width, 150));
+		const entries = this.entries();
+		this.reconcileSelection(entries.map((entry) => entry.row));
+		const terminalHeight = this.params.getTerminalRows?.();
+		const heightIsCompact = terminalHeight !== undefined && Math.floor(terminalHeight * 0.9) < CARD_CHROME_ROWS + 1;
+		if (safeWidth < 20 || heightIsCompact) {
+			if (this.compose) {
+				const target = this.agentName(this.compose.targetId);
+				return [fit(`steer @${target}: ${this.compose.draft}_ · Enter · Esc`, safeWidth)];
+			}
+			const selected = entries.find((entry) => entry.row.correlationId === this.selectedId)?.row;
+			return [fit(selected ? `Agents ${entries.length} · ${agentLabel(selected)} · Esc` : "Agents · none · Esc", safeWidth)];
+		}
+		return safeWidth < 88
+			? this.renderNarrow(safeWidth, entries.map((entry) => entry.row))
+			: this.renderWide(safeWidth, entries.map((entry) => entry.row));
+	}
+
+	private renderWide(width: number, rows: AgentRow[]): string[] {
+		const inner = width - 2;
+		const leftWidth = Math.max(30, Math.floor((inner - 3) * 0.38));
+		const rightWidth = inner - leftWidth - 3;
+		const contentRows = overlayListRows(this.params.getTerminalRows?.(), CARD_CHROME_ROWS);
+		const list = this.agentLines(leftWidth, contentRows);
+		const detail = this.detailLines(rows, rightWidth, contentRows);
+		const bodyRows = Math.max(list.length, detail.length, 1);
+		const body: string[] = [this.header(inner), this.rule(inner)];
+		for (let index = 0; index < bodyRows; index++) {
+			body.push(`${pad(list[index] ?? "", leftWidth)} ${this.params.glyphs.box.vertical} ${pad(detail[index] ?? "", rightWidth)}`);
+		}
+		body.push(this.help(inner));
+		return this.card(body, width);
+	}
+
+	private renderNarrow(width: number, rows: AgentRow[]): string[] {
+		const inner = width - 2;
+		const contentRows = overlayListRows(this.params.getTerminalRows?.(), CARD_CHROME_ROWS);
+		const listRows = Math.max(1, Math.min(4, Math.floor(contentRows * 0.35)));
+		const list = this.agentLines(inner, listRows);
+		const detailRows = Math.max(2, contentRows - list.length - 1);
+		const detail = this.detailLines(rows, inner, detailRows);
+		return this.card([
+			this.header(inner),
+			this.rule(inner),
+			...list,
+			this.rule(inner),
+			...detail,
+			this.help(inner),
+		], width);
+	}
+
+	private entries() {
+		return buildAgentTree(visibleAgentRows([...this.params.getAgents()]), this.params.glyphs);
+	}
+
+	private agentLines(width: number, maxRows: number): string[] {
+		const entries = this.entries();
+		if (entries.length === 0) return [this.params.theme.fg("dim", fit("No agents", width))];
+		const selected = Math.max(0, entries.findIndex((entry) => entry.row.correlationId === this.selectedId));
+		const start = visibleStart(selected, entries.length, maxRows);
+		return entries.slice(start, start + maxRows).map(({ row, prefix }) => {
+			const status = effectiveAgentStatus(row);
+			const visual = agentVisual(status, this.params.glyphs);
+			const marker = row.correlationId === this.selectedId ? this.params.glyphs.selectMarker : " ";
+			const task = row.task ? ` · ${row.task}` : "";
+			return fit(
+				`${prefix}${marker} ${this.params.theme.fg(visual.color, visual.glyph)} ${this.params.theme.bold(agentLabel(row))}${task}`,
+				width,
+			);
+		});
+	}
+
+	private detailLines(rows: AgentRow[], width: number, maxRows: number): string[] {
+		this.detailWidth = width;
+		this.detailRows = maxRows;
+		if (!this.selectedId) return [this.params.theme.fg("dim", fit("No agent selected", width))];
+		return renderSessionDetail(
+			rows,
+			this.selectedId,
+			width,
+			this.params.theme,
+			maxRows,
+			this.outputScroll,
+			"PgUp/PgDn scroll output",
+		);
+	}
+
+	private header(width: number): string {
+		if (this.compose) {
+			const target = this.agentName(this.compose.targetId);
+			return fit(`steer @${target}: ${this.compose.draft}_`, width);
+		}
+		const rows = this.entries().map((entry) => entry.row);
+		const statuses = rows.map((row) => effectiveAgentStatus(row));
+		const active = statuses.filter((status) => status === "running" || status === "retrying").length;
+		const failed = statuses.filter((status) => status === "failed" || status === "stalled").length;
+		const ack = this.lastAck && Date.now() - this.lastAck.at < COMMAND_ACK_MS ? this.lastAck : null;
+		return fit([
+			this.params.theme.bold("Agents"),
+			`${rows.length} total`,
+			active ? `${active} active` : "",
+			failed ? `${failed} failed` : "",
+			ack
+				? this.params.theme.fg(ack.error ? "error" : "success", ack.error ? `✗ ${ack.text}` : `${this.params.glyphs.check} ${ack.text}`)
+				: "",
+		].filter(Boolean).join(" · "), width);
+	}
+
+	private help(width: number): string {
+		if (this.compose) {
+			return this.params.theme.fg("dim", fit("Enter send · Esc cancel", width));
+		}
+		return this.params.theme.fg("dim", fit("Esc close · ↑↓ agent · Home/End jump · PgUp/PgDn output · i interrupt · s steer", width));
+	}
+
+	private rule(width: number): string {
+		return this.params.theme.fg("borderMuted", this.params.glyphs.box.horizontal.repeat(Math.max(1, width)));
+	}
+
+	private card(rows: string[], width: number): string[] {
+		const box = this.params.glyphs.box;
+		const edge = box.horizontal.repeat(Math.max(0, width - 2));
+		const background = (value: string) => this.params.theme.bg("customMessageBg", value);
+		return [
+			background(this.params.theme.fg("borderMuted", `${box.topLeft}${edge}${box.topRight}`)),
+			...rows.map((row) => background(pad(` ${row}`, width))),
+			background(this.params.theme.fg("borderMuted", `${box.bottomLeft}${edge}${box.bottomRight}`)),
+		];
+	}
+
+	private moveSelection(delta: number): void {
+		const rows = this.entries().map((entry) => entry.row);
+		if (rows.length === 0) return;
+		const current = Math.max(0, rows.findIndex((row) => row.correlationId === this.selectedId));
+		this.selectRow(rows[(current + delta + rows.length) % rows.length]);
+	}
+
+	private selectIndex(index: number): void {
+		const rows = this.entries().map((entry) => entry.row);
+		if (rows.length === 0) return;
+		this.selectRow(rows[Math.max(0, Math.min(index, rows.length - 1))]);
+	}
+
+	private selectRow(row: AgentRow): void {
+		this.selectedId = row.correlationId;
+		this.outputScroll = { offset: 0, following: true };
+		this.params.onSelect(row.correlationId);
+		this.params.requestRender();
+	}
+
+	private reconcileSelection(rows: AgentRow[]): void {
+		if (rows.some((row) => row.correlationId === this.selectedId)) return;
+		this.selectedId = rows[0]?.correlationId;
+		this.outputScroll = { offset: 0, following: true };
+		if (this.selectedId) this.params.onSelect(this.selectedId);
+	}
+
+	private scrollOutput(delta: number): void {
+		if (!this.selectedId) return;
+		const rows = this.entries().map((entry) => entry.row);
+		const total = sessionDetailBodyLength(rows, this.selectedId, this.detailWidth);
+		const budget = Math.max(1, sessionDetailWindowRows(total, this.detailRows));
+		this.outputScroll = scrollBy(this.outputScroll, delta, total, budget);
+		this.params.requestRender();
+	}
+}
+
+function agentLabel(row: AgentRow): string {
+	return `@${row.name || row.role || row.agent || "agent"}`;
+}
+
+function agentVisual(status: AgentDisplayStatus, glyphs: IconGlyphs): { glyph: string; color: ThemeColor } {
+	if (status === "failed" || status === "stalled") return { glyph: glyphs.cross, color: "error" };
+	if (status === "terminated") return { glyph: glyphs.cross, color: "warning" };
+	if (status === "done" || status === "result-ready") return { glyph: glyphs.check, color: "success" };
+	if (status === "pending") return { glyph: glyphs.pending, color: "dim" };
+	if (status === "sleeping") return { glyph: glyphs.dotIdle, color: "warning" };
+	return { glyph: glyphs.dotRunning, color: "accent" };
+}
+
+function fit(value: string, width: number): string {
+	return truncateToWidth(value, Math.max(1, width), "…");
+}
+
+function pad(value: string, width: number): string {
+	const fitted = fit(value, width);
+	return `${fitted}${" ".repeat(Math.max(0, width - visibleWidth(fitted)))}`;
+}

package/src/agent-scroll.ts

@@ -0,0 +1,69 @@
+/**
+ * Agent-list scroll window.
+ *
+ * The below-input agent list is bounded by the terminal height. It follows the
+ * newest activity by default (auto-scroll as agents stream); Shift+↑/Shift+↓
+ * (with an empty composer, via a cockpit terminal-input hook) scroll up/down
+ * through the whole roster. Scrolling up pauses follow; reaching the bottom
+ * resumes it. Pure state math, no UI dependencies.
+ */
+
+import {
+	AGENT_NARROW_ROW_CAP,
+	AGENT_WIDE_ROW_CAP,
+	agentPanelRows,
+} from "./viewport.ts";
+
+export interface AgentScrollState {
+	/** Window start over the activity-ordered roster. */
+	offset: number;
+	/** When true the window tracks the newest rows (auto-scroll). */
+	following: boolean;
+}
+
+/** Window start for a state; follow pins the window to the newest rows. */
+export function scrollWindowStart(total: number, budget: number, state: AgentScrollState): number {
+	if (total <= budget) return 0;
+	if (state.following) return total - budget;
+	return Math.max(0, Math.min(state.offset, total - budget));
+}
+
+/** Move the window by `delta` rows; reaching the bottom resumes follow. */
+export function scrollBy(
+	state: AgentScrollState,
+	delta: number,
+	total: number,
+	budget: number,
+): AgentScrollState {
+	if (total <= budget) return { offset: 0, following: true };
+	const start = scrollWindowStart(total, budget, state);
+	const next = Math.max(0, Math.min(start + delta, total - budget));
+	return { offset: next, following: next >= total - budget };
+}
+
+/** Tail-following window: newest rows first. */
+export function followWindow(total: number, budget: number): AgentScrollState {
+	return { offset: Math.max(0, total - budget), following: true };
+}
+
+/**
+ * How many agent rows the panel may render. Mirrors the roster widget's own
+ * budget: eight wide / four narrow rows plus one marker row, bounded by the
+ * active-agent share unless the caller supplies a shared-surface budget.
+ */
+export function agentListWindowRows(
+	terminalColumns: number | undefined,
+	terminalRows: number | undefined,
+	total?: number,
+	panelOverride?: number,
+): number {
+	const widthCap = (terminalColumns ?? 80) < 40 ? AGENT_NARROW_ROW_CAP : AGENT_WIDE_ROW_CAP;
+	const panel = panelOverride ?? agentPanelRows(terminalRows);
+	const panelBudget = Math.min(widthCap + 1, panel ?? widthCap + 1);
+	const bodyBudget = Math.max(1, panelBudget - 1); // roster header owns one row
+	// One combined overflow marker is paid from the body budget, preserving at
+	// least one actual agent row even in the minimum three-row panel.
+	return total !== undefined && total > bodyBudget
+		? Math.max(1, bodyBudget - 1)
+		: bodyBudget;
+}