@aeondave/pi-persona 1.15.2

package/src/tools/timer.ts

@@ -0,0 +1,105 @@
+/** Session timer tool — arm a wall-clock wake. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { failureDetails } from "../extension/shared.ts";
+import { formatRemaining, type TimerScheduler } from "../core/timer.ts";
+import { parseInstant } from "../core/time.ts";
+import { readClockSnapshot } from "../extension/clock.ts";
+
+export interface TimerToolDeps {
+	get lastCtx(): ExtensionContext | undefined;
+	set lastCtx(value: ExtensionContext | undefined);
+	timerScheduler: TimerScheduler;
+}
+
+export function registerTimerTool(pi: ExtensionAPI, d: TimerToolDeps): void {
+	// ── timer tool (arm a wall-clock alarm that WAKES the session when it fires) ───
+	// Solves the "wait N minutes for a scheduled event or service window" problem WITHOUT a poll loop:
+	// arm an alarm, end your turn, and when it expires the extension injects a follow-up that
+	// resumes you (idle-gated so it starts a fresh turn instead of stranding). Up to 32 alarms may be
+	// armed; cancel/list them. In-memory per session (a reload/new session clears armed alarms).
+	const TimerToolParams = Type.Object({
+		action: Type.Union([Type.Literal("arm"), Type.Literal("cancel"), Type.Literal("list"), Type.Literal("now")], {
+			description: "arm = schedule a wakeup · cancel = drop one by id · list = show armed alarms · now = read the fresh clock",
+		}),
+		message: Type.Optional(
+			Type.String({ description: "arm: the non-empty follow-up injected into the session when the timer fires (what to do on wake, e.g. 'check the status and summarize changes'). After trimming surrounding whitespace, maximum 4000 characters. Required for arm." }),
+		),
+		delaySeconds: Type.Optional(Type.Number({ description: "arm: fire this many seconds from now; it is rounded to milliseconds and must produce a delay from 1 second through 86400 seconds. Give this OR atIso, not both." })),
+		atIso: Type.Optional(Type.String({ description: "arm: fire at this absolute ISO-8601 instant (date-time must include Z or a numeric timezone offset, e.g. '2026-07-11T19:00:00Z'). Give this OR delaySeconds, not both." })),
+		label: Type.Optional(Type.String({ description: "arm: a short human label for the alarm (e.g. 'status review')." })),
+		id: Type.Optional(Type.String({ description: "cancel: the timer id to cancel (e.g. 'timer-1')." })),
+	});
+	pi.registerTool({
+		name: "timer",
+		label: "Timer",
+		description: [
+			"Arm a wall-clock ALARM that wakes you when it fires — the token-cheap way to wait for a",
+			"fixed moment (a scheduled event, a service window, a scheduled re-check) instead of a",
+			"poll loop. `arm` with { message, delaySeconds } or { message, atIso }; end your turn; when",
+			"it expires a follow-up carrying your message is injected and you resume. `cancel` by id,",
+			"`list` the armed ones. Up to 32 alarms may be armed at once. The session must remain open;",
+			"alarms are in-memory and cleared on shutdown or reload. `now` returns a fresh UTC time plus",
+			"the local timezone and numeric offset.",
+		].join(" "),
+		parameters: TimerToolParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			d.lastCtx = ctx;
+			if (params.action === "now") {
+				const now = d.timerScheduler.now();
+				const reading = readClockSnapshot(now);
+				if (!reading) {
+					return { content: [{ type: "text", text: "timer now is unavailable because the scheduler clock is invalid." }], details: failureDetails({ action: "now", ok: false }), isError: true };
+				}
+				return { content: [{ type: "text", text: reading }], details: { action: "now", ok: true }, isError: false };
+			}
+			if (params.action === "list") {
+				const timers = d.timerScheduler.list();
+				const text =
+					timers.length === 0
+						? "(no armed timers)"
+						: `Armed timers:\n${timers
+								.map((t) => `• ${t.id} (${t.label}) — fires in ${formatRemaining(t.remainingMs)} [${new Date(t.fireAtEpochMs).toISOString()}]: ${t.message}`)
+								.join("\n")}`;
+				return { content: [{ type: "text", text }], details: { action: "list", count: timers.length, ok: true }, isError: false };
+			}
+			if (params.action === "cancel") {
+				if (!params.id) {
+					return { content: [{ type: "text", text: "timer cancel needs { id } (see `list`)." }], details: failureDetails({ action: "cancel", ok: false }), isError: true };
+				}
+				const cancelled = d.timerScheduler.cancel(params.id);
+				return cancelled
+					? { content: [{ type: "text", text: `Cancelled ${params.id}.` }], details: { action: "cancel", ok: true }, isError: false }
+					: { content: [{ type: "text", text: `No armed timer with id "${params.id}" (it may have already fired or been cancelled).` }], details: failureDetails({ action: "cancel", ok: false }), isError: true };
+			}
+			// action === "arm"
+			const message = params.message?.trim() ?? "";
+			if (!message) {
+				return { content: [{ type: "text", text: "timer arm needs { message } — the follow-up text injected on wake." }], details: failureDetails({ action: "arm", ok: false }), isError: true };
+			}
+			if (params.delaySeconds === undefined && params.atIso === undefined) {
+				return { content: [{ type: "text", text: "timer arm needs { delaySeconds } or { atIso }, not neither." }], details: failureDetails({ action: "arm", ok: false }), isError: true };
+			}
+			if (params.delaySeconds !== undefined && params.atIso !== undefined) {
+				return { content: [{ type: "text", text: "timer arm needs { delaySeconds } or { atIso }, not both." }], details: failureDetails({ action: "arm", ok: false }), isError: true };
+			}
+			const arm: { message: string; label?: string; delayMs?: number; atEpochMs?: number } = { message };
+			if (params.label !== undefined) arm.label = params.label;
+			if (params.atIso !== undefined) {
+				const at = parseInstant(params.atIso);
+				if (!Number.isFinite(at)) {
+					return { content: [{ type: "text", text: `timer atIso "${params.atIso}" is not a valid unambiguous ISO-8601 time; date-times must include Z or a numeric timezone offset.` }], details: failureDetails({ action: "arm", ok: false }), isError: true };
+				}
+				arm.atEpochMs = at;
+			}
+			if (params.delaySeconds !== undefined) arm.delayMs = Math.round(params.delaySeconds * 1000);
+			const r = d.timerScheduler.arm(arm);
+			if (!r.ok || !r.entry) {
+				return { content: [{ type: "text", text: r.error ?? "timer arm failed." }], details: failureDetails({ action: "arm", ok: false }), isError: true };
+			}
+			const e = r.entry;
+			const text = `Armed ${e.id} (${e.label}) — fires in ${formatRemaining(r.remainingMs ?? e.fireAtEpochMs - e.armedAtEpochMs)} [${new Date(e.fireAtEpochMs).toISOString()}]. On fire I'll be woken with: "${e.message}". You can end this turn now; keep the session open for the alarm.`;
+			return { content: [{ type: "text", text }], details: { action: "arm", id: e.id, fireAtEpochMs: e.fireAtEpochMs, ok: true }, isError: false };
+		},
+	});
+}

package/src/ui/agent-overlay.ts

@@ -0,0 +1,526 @@
+/**
+ * A focusable overlay over the unified agent tree, opened with ctx.ui.custom
+ * (overlay: true). ↑↓ navigate the *agents* (leaf rows; a parent like "delegate"
+ * is a non-selectable header), ⏎ drills into one — its live output in an
+ * auto-scrolling viewport sized to the terminal — `x` stops it, `s` steers it
+ * (from the list too), esc backs out / closes. Subscribes to the tree, so it
+ * re-renders live as agents stream.
+ *
+ * The pure parts (flatten/order, glyphs, scroll window) live in agent-tree.ts /
+ * model-picker.ts and are unit-tested; this file is the thin pi-tui glue
+ * (focus + keyboard + framing).
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	getKeybindings,
+	Spacer,
+	Text,
+	truncateToWidth,
+	type TUI,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+import { type AgentNode, type AgentTree, type FlatRow, flattenTree, GLYPH, runningAnnotation } from "./agent-tree.ts";
+import { LiveClock } from "./live-clock.ts";
+import { visibleWindow } from "./model-picker.ts";
+import { compactInlineText, OPEN_SEQUENCE_TAIL, sanitizeTerminalText } from "./presentation.ts";
+
+function safeInline(value: string, maxChars = 96): string {
+	return compactInlineText(value, { maxChars });
+}
+
+/** Rows the terminal has (fallback for exotic hosts). */
+function termRows(): number {
+	return process.stdout.rows && process.stdout.rows > 0 ? process.stdout.rows : 24;
+}
+
+/** Is this keystroke a single printable character (a steer-input keystroke)? */
+function isPrintable(key: string): boolean {
+	if (key.length !== 1) return false;
+	const c = key.charCodeAt(0);
+	return c >= 0x20 && c !== 0x7f;
+}
+
+/** Pure inputs for one list row: everything {@link composeAgentRow} needs and nothing it can
+ *  reach into the overlay for. Keeping this a plain function (not a method) means the frame-width
+ *  invariant is testable directly, without constructing a whole overlay. */
+export interface AgentRowInput {
+	node: AgentNode;
+	depth: number;
+	selected: boolean;
+	inner: number;
+	now: number;
+	stallMs: number;
+	theme: Theme;
+}
+
+/**
+ * One list row, guaranteed to fit within `inner` columns. The clock suffix (elapsed/stall badge)
+ * is reserved and appended *after* the label+detail body is clamped, so a tight budget always
+ * eats into the label/detail — truncating a stall badge would hide the one signal it exists to
+ * show. `safeInline` has its own internal floor (never truncates below ~16 columns), so the
+ * computed label/detail budgets are best-effort; the final clamp on the body is what makes the
+ * overall width hold regardless.
+ */
+export function composeAgentRow(input: AgentRowInput): string {
+	const { node, depth, selected, inner, now, stallMs, theme: t } = input;
+	const indent = "  ".repeat(depth);
+	const clock = runningAnnotation(node, now, stallMs);
+	// Reserve the clock's exact width plus its widest separator (" · ") up front — this portion
+	// of the row is never truncated.
+	const clockCols = clock ? visibleWidth(clock) + visibleWidth(" · ") : 0;
+	const bodyMax = Math.max(0, inner - clockCols);
+
+	const prefixCols = 2 + visibleWidth(indent); // "▸ " or "  ", then the indent
+	const avail = Math.max(0, bodyMax - prefixCols - 2); // 2 = glyph + space
+	const labelMax = Math.max(8, Math.floor(avail * 0.62));
+	const label = safeInline(node.label, labelMax) || "agent";
+	const detailMax = node.detail ? Math.max(0, avail - labelMax - 2) : 0;
+	const detail = detailMax > 0 ? safeInline(node.detail ?? "", detailMax) : "";
+	const detailText = detail ? t.fg("dim", `  ${detail}`) : "";
+
+	const labelLine = `${indent}${GLYPH[node.status]} ${label}`;
+	const prefixed = selected ? t.fg("accent", `▸ ${labelLine}`) : `  ${labelLine}`;
+	let body = `${prefixed}${detailText}`;
+	if (visibleWidth(body) > bodyMax) body = truncateToWidth(body, bodyMax, "");
+
+	const clockText = clock ? t.fg("dim", `${detail ? " · " : "  "}${clock}`) : "";
+	return `${body}${clockText}`;
+}
+
+/** Trailing callbacks and clock config for {@link AgentOverlay}, grouped as one object so a
+ *  new capability (stall threshold, injected clock) does not grow the constructor's arity. */
+export interface AgentOverlayActions {
+	onStop?: (nodeId: string) => boolean;
+	onSteer?: (nodeId: string, text: string) => boolean;
+	canSteer?: (nodeId: string) => boolean;
+	canStop?: (nodeId: string) => boolean;
+	/** Stall threshold for the ⚠ badge; 0/omitted ⇒ no badge. */
+	stallMs?: number;
+	/** Clock; tests inject a fixed one. */
+	now?: () => number;
+}
+
+export class AgentOverlay extends Container {
+	private tree: AgentTree;
+	private tui: TUI;
+	private theme: Theme;
+	private done: () => void;
+	private readonly actions: AgentOverlayActions;
+	private readonly clock: LiveClock;
+	private readonly now: () => number;
+	private notice: string | undefined;
+	private unsubscribe: () => void;
+	private selectedId: string | undefined; // the selected agent's *id*, never its row index
+	private aimLost = false; // the aimed-at agent settled: swallow the next directed keystroke
+	private listScroll = 0; // list rows scrolled off the top (keeps the selection visible)
+	private detailId: string | undefined;
+	private detailScroll = 0; // output lines scrolled up from the bottom (0 = latest)
+	private steering = false; // typing a steer message into the drilled-in agent
+	private steerBuffer = "";
+	private lastWidth = 100;
+	/** State changed since the last host paint. Rebuilding here (instead of in the tree listener)
+	 *  lets Pi-TUI's own 16ms frame coalescer absorb a burst of streamed progress snapshots. */
+	private dirty = false;
+	/** A host frame has already been requested for the current invalidation burst. */
+	private frameRequested = false;
+	private displayCache: { source: string; width: number; rows: string[] } | undefined;
+
+	constructor(tree: AgentTree, tui: TUI, theme: Theme, done: () => void, actions: AgentOverlayActions = {}) {
+		super();
+		this.tree = tree;
+		this.tui = tui;
+		this.theme = theme;
+		this.done = done;
+		this.actions = actions;
+		this.now = actions.now ?? Date.now;
+		this.clock = new LiveClock({ intervalMs: 1_000, isLive: () => tree.hasRunning(), onTick: () => this.refresh() });
+		this.unsubscribe = tree.onChange(() => {
+			// A tree change can arrive while a compose is open. If its live handle disappeared,
+			// retire the compose state now; the next key must not be interpreted with stale text
+			// while the lazy rebuild waits for the host's paint.
+			if (this.steering && this.detailId && !(this.actions.canSteer?.(this.detailId) ?? false)) {
+				this.steering = false;
+				this.steerBuffer = "";
+			}
+			this.scheduleRefresh();
+			this.clock.start(); // new work may have appeared while the clock was stopped
+		});
+		this.rebuild();
+		this.clock.start();
+	}
+
+	private refresh(): void {
+		this.scheduleRefresh();
+	}
+
+	/** Mark the component stale and ask the host for one paint. The actual rebuild happens from
+	 *  render(), so several tree changes before that paint do not repeatedly clear/recompose all
+	 *  children (or re-wrap a streamed detail buffer). */
+	private scheduleRefresh(): void {
+		this.dirty = true;
+		if (this.frameRequested) return;
+		this.frameRequested = true;
+		this.tui.requestRender();
+	}
+
+	/** Frame the panel in a box so it stands out from the chat background. */
+	override render(width: number): string[] {
+		this.frameRequested = false;
+		if (this.lastWidth !== width) this.dirty = true;
+		this.lastWidth = width;
+		if (this.dirty) {
+			this.rebuild();
+			this.dirty = false;
+		}
+		const inner = this.inner();
+		const t = this.theme;
+		const b = (s: string): string => t.fg("accent", s);
+		const framed = super.render(inner).map((line) => {
+			const pad = " ".repeat(Math.max(0, inner - visibleWidth(line)));
+			return `${b("│")} ${line}${pad} ${b("│")}`;
+		});
+		return [b(`┌${"─".repeat(inner + 2)}┐`), ...framed, b(`└${"─".repeat(inner + 2)}┘`)];
+	}
+
+	private inner(): number {
+		// Use the whole width the host gives us (the overlay itself is sized ~90% of the
+		// terminal) — a hard 100-column cap made wide terminals waste most of the screen.
+		return Math.max(24, this.lastWidth - 4);
+	}
+
+	/** Detail-output rows that fit: terminal height minus the overlay chrome. */
+	private detailViewport(): number {
+		return Math.max(8, termRows() - 12);
+	}
+
+	/** List rows that fit: terminal height minus the overlay chrome. */
+	private listViewport(): number {
+		return Math.max(6, termRows() - 10);
+	}
+
+	private leafRows(): FlatRow[] {
+		const snap = this.tree.snapshot();
+		const parents = new Set(snap.map((n) => n.parentId).filter((p): p is string => p !== undefined));
+		return flattenTree(snap).filter((r) => !parents.has(r.node.id));
+	}
+
+	/**
+	 * The selected leaf, re-anchored by id on every use. The list is recomputed from the
+	 * live tree, and agents are pruned from it as they settle: an index would slide `x`
+	 * (stop) and `s` (steer) onto a *different* agent whenever an earlier sibling went
+	 * away. When the aimed-at agent is the one that vanishes, fall back to the head of
+	 * the list, where the ▸ marker visibly shows the user their target changed — and
+	 * record that the aim was lost, for the directed keys (see `aimedLeaf`).
+	 */
+	private selectedLeaf(leaves: FlatRow[]): FlatRow | undefined {
+		const anchored = this.selectedId !== undefined ? leaves.find((r) => r.node.id === this.selectedId) : undefined;
+		const leaf = anchored ?? leaves[0];
+		if (this.selectedId !== undefined && anchored === undefined && leaf !== undefined) this.aimLost = true;
+		this.selectedId = leaf?.node.id;
+		return leaf;
+	}
+
+	/**
+	 * The leaf a *directed* key (`x` stop, `s` steer) may act on. A keystroke is always in flight
+	 * while runs settle underneath it, and stopping an agent cannot be undone — so the first such
+	 * key after the aimed-at agent vanished only re-anchors and re-renders. The user then acts on
+	 * the target the ▸ marker actually shows, rather than on whichever agent inherited the aim.
+	 */
+	private aimedLeaf(leaves: FlatRow[]): FlatRow | undefined {
+		const leaf = this.selectedLeaf(leaves);
+		if (!this.aimLost) return leaf;
+		this.aimLost = false;
+		this.refresh();
+		return undefined;
+	}
+
+	/** Move the selection by whole rows, keeping it anchored on an id. */
+	private moveSelection(leaves: FlatRow[], delta: number): void {
+		const current = this.selectedLeaf(leaves);
+		if (!current) return;
+		const index = leaves.findIndex((r) => r.node.id === current.node.id);
+		this.selectedId = leaves[Math.min(leaves.length - 1, Math.max(0, index + delta))]?.node.id;
+		this.aimLost = false; // moving the marker by hand *is* taking aim
+	}
+
+	private rebuild(): void {
+		this.clear();
+		if (this.detailId) this.renderDetail();
+		else this.renderList();
+		this.dirty = false;
+	}
+
+	private renderList(): void {
+		const t = this.theme;
+		const rows = flattenTree(this.tree.snapshot());
+		const selected = this.selectedLeaf(this.leafRows())?.node;
+		this.addChild(new Text(t.fg("accent", t.bold("Agents")), 1, 0));
+		this.addChild(new Spacer(1));
+		if (rows.length === 0) {
+			this.addChild(new Text(t.fg("dim", "(no agents running)"), 1, 0));
+		} else {
+			// Scroll window over the rows (a big fan-out must not overflow the screen);
+			// the window follows the selection, ▲/▼ markers show what's off-screen.
+			const vp = this.listViewport();
+			const selIdx = Math.max(0, rows.findIndex((r) => r.node.id === selected?.id));
+			this.listScroll = visibleWindow(selIdx, vp, rows.length, this.listScroll);
+			const end = Math.min(rows.length, this.listScroll + vp);
+			if (this.listScroll > 0) this.addChild(new Text(t.fg("dim", `▲ ${this.listScroll} above`), 1, 0));
+			for (const row of rows.slice(this.listScroll, end)) {
+				const composed = composeAgentRow({
+					node: row.node,
+					depth: row.depth,
+					selected: row.node.id === selected?.id,
+					inner: this.inner(),
+					now: this.now(),
+					stallMs: this.actions.stallMs ?? 0,
+					theme: t,
+				});
+				this.addChild(new Text(composed, 1, 0));
+			}
+			if (end < rows.length) this.addChild(new Text(t.fg("dim", `▼ ${rows.length - end} below`), 1, 0));
+		}
+		this.addChild(new Spacer(1));
+		const stoppable = selected !== undefined && this.canStopNode(selected);
+		const steerable = selected !== undefined && selected.status === "running" && (this.actions.canSteer?.(selected.id) ?? false);
+		this.addChild(new Text(t.fg("dim", `↑↓ navigate   ⏎ open${this.hintLine("list", stoppable, steerable)}   esc close`), 1, 0));
+		this.renderNotice();
+	}
+
+	/**
+	 * Wrap long lines instead of truncating — the user must be able to read the full text.
+	 * The viewport + scroll then operate over the wrapped display lines, so a long message
+	 * spans several rows rather than being cut off with an ellipsis.
+	 */
+	private wrapRows(text: string, width: number): string[] {
+		return text.split("\n").flatMap((line) => {
+			const wrapped = wrapTextWithAnsi(line, width);
+			return wrapped.length > 0 ? wrapped : [""]; // keep blank lines (paragraph spacing)
+		});
+	}
+
+	/** Rows for a run of *completed* lines: the empty string after the final \n is not a row. */
+	private settledRows(chunk: string, width: number): string[] {
+		if (!chunk) return [];
+		const lines = sanitizeTerminalText(chunk).split("\n");
+		if (lines.at(-1) === "") lines.pop();
+		return lines.flatMap((line) => this.wrapRows(line, width));
+	}
+
+	/**
+	 * Sanitized, wrapped display rows for the drilled-in buffer. A progress snapshot carries
+	 * the whole accumulated output, and one fires per streamed chunk, so redoing the entire
+	 * buffer every tick is quadratic in the report size — slow enough at a few hundred KB
+	 * that `x` (stop) and the scroll keys queue behind the rebuild. Completed lines never
+	 * change once written, so only the unfinished tail is redone.
+	 *
+	 * The seam has to fall *outside* a control sequence, or the sequence would be erased in
+	 * two halves and leak its payload. Bailing on any ESC is not enough of a rule: agents
+	 * colour their output, so a single `ESC[32m` would put every tick back on the whole
+	 * buffer. Instead the seam retreats to the line an unterminated sequence opened on, and
+	 * only a chunk that is still open after that gives up on reuse.
+	 */
+	private displayRows(raw: string, width: number): string[] {
+		const cache = this.displayCache;
+		let settled = raw.slice(0, raw.lastIndexOf("\n") + 1);
+		const reusable = cache && cache.width === width && settled.startsWith(cache.source) ? cache : undefined;
+		let added = reusable ? settled.slice(reusable.source.length) : settled;
+		if (OPEN_SEQUENCE_TAIL.test(added)) {
+			const opened = added.lastIndexOf("\u001B");
+			added = added.slice(0, added.lastIndexOf("\n", opened) + 1);
+			settled = (reusable?.source ?? "") + added;
+		}
+		if (OPEN_SEQUENCE_TAIL.test(added)) {
+			// An earlier sequence spans the whole chunk: the only sound seam is no seam.
+			this.displayCache = undefined;
+			const whole = raw.slice(0, raw.lastIndexOf("\n") + 1);
+			return this.settledRows(whole, width).concat(this.wrapRows(sanitizeTerminalText(raw.slice(whole.length)), width));
+		}
+		const rows = reusable ? reusable.rows : [];
+		for (const row of this.settledRows(added, width)) rows.push(row);
+		this.displayCache = { source: settled, width, rows };
+		return rows.concat(this.wrapRows(sanitizeTerminalText(raw.slice(settled.length)), width));
+	}
+
+	private renderDetail(): void {
+		const t = this.theme;
+		const node = this.tree.snapshot().find((n) => n.id === this.detailId);
+		if (!node) {
+			this.detailId = undefined;
+			// The compose belonged to *that* agent — drop it, or the next drill-in would
+			// re-open it pre-filled and send it to a different sub-agent. Re-rendering the
+			// list also loses the anchor (the selection *is* the drilled-in agent), so an
+			// `x` still in flight for it is refused instead of landing on the list beneath.
+			this.steering = false;
+			this.steerBuffer = "";
+			this.renderList();
+			return;
+		}
+		const live = node.status === "running";
+		this.addChild(
+			new Text(`${GLYPH[node.status]} ${t.fg("accent", t.bold(safeInline(node.label) || "agent"))}${live ? t.fg("success", "  ● live") : ""}`, 1, 0),
+		);
+		if (node.detail) this.addChild(new Text(t.fg("dim", safeInline(node.detail)), 1, 0));
+		this.addChild(new Spacer(1));
+
+		const raw = node.output?.trim()
+			? node.output
+			: live
+				? "(working… the report appears here when the agent writes text — see its current tool above)"
+				: "(no output)";
+		const w = this.inner() - 1;
+		const all = this.displayRows(raw, w);
+		const viewport = this.detailViewport();
+		const maxScroll = Math.max(0, all.length - viewport);
+		if (this.detailScroll > maxScroll) this.detailScroll = maxScroll;
+		const end = all.length - this.detailScroll;
+		const start = Math.max(0, end - viewport);
+		if (start > 0) this.addChild(new Text(t.fg("dim", `▲ ${start} earlier`), 1, 0));
+		for (const line of all.slice(start, end)) this.addChild(new Text(t.fg("toolOutput", line), 1, 0));
+		if (this.detailScroll > 0) this.addChild(new Text(t.fg("dim", `▼ ${this.detailScroll} newer`), 1, 0));
+
+		const steerable = live && (this.actions.canSteer?.(node.id) ?? false);
+		const stoppable = this.canStopNode(node);
+		if (this.steering && !steerable) this.steering = false; // agent finished mid-compose
+		this.addChild(new Spacer(1));
+		if (this.steering) {
+			// Wrap the input so a long steer message stays fully visible while typing.
+			const composed = `${t.fg("accent", "steer ▸ ")}${this.steerBuffer}${t.fg("dim", "▌")}`;
+			for (const line of wrapTextWithAnsi(composed, w)) this.addChild(new Text(line, 1, 0));
+			this.addChild(new Text(t.fg("dim", "⏎ send   ·   esc cancel"), 1, 0));
+		} else {
+			this.addChild(new Text(t.fg("dim", `esc back   ·   ↑↓ scroll${this.hintLine("detail", stoppable, steerable)}`), 1, 0));
+			this.renderNotice();
+			if (live && !steerable) {
+				this.addChild(new Text(t.fg("dim", "(steer unavailable: no live handle yet, or this engine/broker does not expose one)"), 1, 0));
+			}
+		}
+	}
+
+	handleInput(keyData: string): void {
+		const hadNotice = this.notice !== undefined;
+		this.notice = undefined; // any key clears a previous refusal notice
+		const kb = getKeybindings();
+		if (this.detailId) {
+			// Steer mode: type a message into the running agent. Capture all printable keys
+			// (so j/k/x type normally); ⏎ sends, esc cancels.
+			if (this.steering) {
+				if (kb.matches(keyData, "tui.select.cancel")) {
+					this.steering = false;
+					this.steerBuffer = "";
+					this.refresh();
+				} else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n" || keyData === "\r") {
+					const text = this.steerBuffer.trim();
+					this.steering = false;
+					this.steerBuffer = "";
+					if (text) this.actions.onSteer?.(this.detailId, text);
+					this.refresh();
+				} else if (keyData === "\x7f" || keyData === "\b") {
+					this.steerBuffer = this.steerBuffer.slice(0, -1);
+					this.refresh();
+				} else if (isPrintable(keyData)) {
+					this.steerBuffer += keyData;
+					this.refresh();
+				} else if (hadNotice) this.refresh();
+				return;
+			}
+			if (keyData === "s" && (this.actions.canSteer?.(this.detailId) ?? false)) {
+				this.steering = true;
+				this.steerBuffer = "";
+				this.refresh();
+			} else if (keyData === "x") this.tryStop(this.detailId);
+			else if (kb.matches(keyData, "tui.select.up") || keyData === "k") {
+				this.detailScroll += 1;
+				this.refresh();
+			} else if (kb.matches(keyData, "tui.select.down") || keyData === "j") {
+				this.detailScroll = Math.max(0, this.detailScroll - 1);
+				this.refresh();
+			} else if (kb.matches(keyData, "tui.select.cancel")) {
+				this.detailId = undefined;
+				this.refresh();
+			} else if (hadNotice) this.refresh(); // unhandled key: still repaint so a cleared notice disappears
+			return;
+		}
+		const leaves = this.leafRows();
+		if (kb.matches(keyData, "tui.select.up") || keyData === "k") {
+			this.moveSelection(leaves, -1);
+			this.refresh();
+		} else if (kb.matches(keyData, "tui.select.down") || keyData === "j") {
+			this.moveSelection(leaves, 1);
+			this.refresh();
+		} else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n") {
+			const leaf = this.selectedLeaf(leaves);
+			if (leaf) {
+				this.detailId = leaf.node.id;
+				this.detailScroll = 0; // open at the latest output (auto-scroll to bottom)
+				this.aimLost = false; // reading a row is harmless, and it re-takes aim on it
+				this.refresh();
+			}
+		} else if (keyData === "s") {
+			// Steer straight from the list: drill into the selected agent with the
+			// compose line already open (same gate as the detail view's `s`).
+			const leaf = this.aimedLeaf(leaves);
+			if (leaf && leaf.node.status === "running" && (this.actions.canSteer?.(leaf.node.id) ?? false)) {
+				this.detailId = leaf.node.id;
+				this.detailScroll = 0;
+				this.steering = true;
+				this.steerBuffer = "";
+				this.refresh();
+			}
+		} else if (keyData === "x") {
+			const leaf = this.aimedLeaf(leaves);
+			if (leaf) this.tryStop(leaf.node.id);
+		} else if (kb.matches(keyData, "tui.select.cancel")) {
+			this.close();
+		} else if (hadNotice) this.refresh(); // unhandled key: still repaint so a cleared notice disappears
+	}
+
+	/** Whether an agent can be stopped right now: it must be running, and the caller's `canStop`
+	 *  gate (defaulting to "yes" when omitted) must agree. Shared by both hints and `tryStop`, so
+	 *  the hint that advertises "x stop" and the handler that actually gates it never diverge. */
+	private canStopNode(node: Pick<AgentNode, "id" | "status">): boolean {
+		return node.status === "running" && (this.actions.canStop?.(node.id) ?? true);
+	}
+
+	/** The trailing "x stop"/"s steer" hint fragment for an action line — the list's three-space
+	 *  style or the detail view's " · " style, the two views' only difference here. */
+	private hintLine(kind: "list" | "detail", stoppable: boolean, steerable: boolean): string {
+		const sep = kind === "list" ? "   " : "   ·   ";
+		return `${stoppable ? `${sep}x stop` : ""}${steerable ? `${sep}s steer` : ""}`;
+	}
+
+	/** The one-line refusal notice, shown identically under the list and the detail view. */
+	private renderNotice(): void {
+		if (this.notice) this.addChild(new Text(this.theme.fg("dim", this.notice), 1, 0));
+	}
+
+	/** Stop (abort) one agent by id. A refusal — the node is gone, not stoppable, or the caller
+	 *  declines — surfaces as a one-line notice rather than doing nothing: the user pressed a key
+	 *  and deserves feedback, in the list view and the detail view alike. */
+	private tryStop(nodeId: string): void {
+		const node = this.tree.snapshot().find((n) => n.id === nodeId);
+		if (!node || !this.canStopNode(node) || !this.actions.onStop?.(nodeId)) {
+			this.notice = `nothing to stop for ${node?.label ?? nodeId}`;
+		}
+		this.refresh();
+	}
+
+	private close(): void {
+		this.dispose();
+		this.done();
+	}
+
+	dispose(): void {
+		this.clock.stop();
+		this.unsubscribe();
+	}
+
+	/** Read-only for tests: whether the live-clock tick is still armed. */
+	get clockRunning(): boolean {
+		return this.clock.running;
+	}
+}