one-code-extension 0.1.3 → 0.3.0

package/extensions/subagents/panel-render.ts

@@ -0,0 +1,357 @@
+/**
+ * Pure rendering for the subagent panel — Claude Code's below-editor agent tree
+ * and its Enter-to-view child transcript. All lines are cut/padded as PLAIN
+ * text before painting so ANSI escapes never enter width accounting (pi-tui
+ * crashes on an overwide line). Wiring (widget + ctx.ui.custom) lives in
+ * index.ts; this file owns layout only, mirroring workflow/viewer.ts.
+ */
+
+import { cutPlainText as cut, formatDuration, splitCell, splitRow, visibleWidth } from "../lib/tui-render.ts";
+import { hardWrapColumns } from "../lib/text-width.ts";
+import { formatTokenCount } from "./usage.ts";
+import { type LiveRun, type LiveStatus, streamingText, type TranscriptBlock } from "./live-runs.ts";
+
+export interface Paint {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+/** A strip row: main is row 0 (synthetic), then the live children as a tree. */
+export interface PanelRow {
+	/** undefined = the synthetic `main` row. */
+	run?: LiveRun;
+	label: string;
+	activity: string;
+	status: LiveStatus;
+	startedAt?: number;
+	finishedAt?: number;
+	tokens: number;
+	/** Tree indent: 0 = spawned by main; 1+ = nested under the row above (CC's `└`). */
+	depth: number;
+}
+
+/**
+ * A finished run stays in the strip this long (its "Completed"/"Failed" beat),
+ * then drops out — Claude Code's tree only tracks live work. The run itself
+ * stays in the registry: the viewer, /agents, and SendMessage still reach it.
+ */
+export const STRIP_LINGER_MS = 5000;
+
+/**
+ * Build the row list: `main` first, then the live children as a TREE — roots
+ * newest-first, each root followed by its nested spawns (a child's own Agent
+ * calls) in spawn order, indented one level (CC's `└` rows). `mainBusy` drives
+ * main's dot. Running children always show; settled ones — done, failed, or an
+ * idle resident whose turn ended — only within STRIP_LINGER_MS of finishing
+ * (finishedAt is stamped by finish() AND settle()). A nested run whose parent
+ * already left the strip surfaces at root level rather than vanishing.
+ *
+ * `pinnedId` keeps one settled run in the strip past its linger window — the
+ * run whose transcript is currently open. Without it a finished child drops out
+ * from under an open viewer, the strip empties, and the panel clears focus,
+ * orphaning the overlay (no key then reaches read mode to close it).
+ */
+export function buildRows(runs: LiveRun[], mainBusy: boolean, now: number, pinnedId?: string): PanelRow[] {
+	const rows: PanelRow[] = [
+		{
+			label: "main",
+			activity: "",
+			status: mainBusy ? "running" : "idle",
+			tokens: 0,
+			depth: 0,
+		},
+	];
+	// `runs` arrives newest-first; children under a parent read best in spawn order.
+	const visible = runs.filter(
+		(run) => run.status === "running" || run.taskId === pinnedId || (run.finishedAt ?? now) > now - STRIP_LINGER_MS,
+	);
+	const visibleIds = new Set(visible.map((run) => run.taskId));
+	const byParent = new Map<string, LiveRun[]>();
+	const roots: LiveRun[] = [];
+	for (const run of visible) {
+		if (run.parentTaskId && visibleIds.has(run.parentTaskId)) {
+			const siblings = byParent.get(run.parentTaskId) ?? [];
+			siblings.unshift(run); // reverse the newest-first order → spawn order
+			byParent.set(run.parentTaskId, siblings);
+		} else {
+			roots.push(run);
+		}
+	}
+	const emit = (run: LiveRun, depth: number) => {
+		rows.push({
+			run,
+			label: run.agentType,
+			activity: run.activity,
+			status: run.status,
+			startedAt: run.startedAt,
+			finishedAt: run.finishedAt,
+			tokens: run.tokens.output,
+			depth,
+		});
+		for (const child of byParent.get(run.taskId) ?? []) emit(child, depth + 1);
+	};
+	for (const root of roots) emit(root, 0);
+	return rows;
+}
+
+/**
+ * The agent taskId after `taskId` in strip order, wrapping to the first and
+ * skipping the synthetic `main` row; undefined when there are no agent rows.
+ * Tab-to-next-agent in read mode uses this against the FULL row list, anchored
+ * to the viewed run — not the windowed strip selection, which `anchor()` can
+ * reassign once the viewed run scrolls past MAX_STRIP_ROWS (else Tab/x would
+ * act on the wrong agent).
+ */
+export function nextAgentTaskId(rows: PanelRow[], taskId: string | undefined): string | undefined {
+	const ids = rows.filter((row) => row.run).map((row) => row.run!.taskId);
+	if (ids.length === 0) return undefined;
+	const at = taskId ? ids.indexOf(taskId) : -1;
+	return ids[(at + 1) % ids.length];
+}
+
+const STATUS_ROW_STYLE: Partial<Record<LiveStatus, string>> = { failed: "error" };
+
+/** Terminal-status label + colour for the transcript view's bottom row (running handled separately). */
+const TERMINAL_STATUS: Partial<Record<LiveStatus, [text: string, color: string]>> = {
+	failed: ["✗ Failed", "error"],
+	stopped: ["■ Stopped", "dim"],
+	idle: ["Idle — resident", "dim"],
+};
+
+// ---------------------------------------------------------------------------
+// The strip (below-editor, always-on while agents are alive)
+// ---------------------------------------------------------------------------
+
+export const MAX_STRIP_ROWS = 6;
+
+export interface StripInput {
+	rows: PanelRow[];
+	/** Soft-focused row index; undefined when the strip is not focused. */
+	selected?: number;
+	/** A transcript view is open → the strip is in "read" mode (scroll hints). */
+	viewOpen?: boolean;
+	width: number;
+	now: number;
+}
+
+/**
+ * One line per row: `mark  agentType  activity   elapsed · ↓ tokens`. The
+ * selected row is bold and marked `❯` (Claude Code's selection caret); others
+ * are unmarked. A focus hint precedes the list (only while focused) — its keys
+ * reflect the mode: navigating the strip vs. reading an open transcript, where
+ * `←` returns to selection so a different agent can be picked. Overflow past
+ * MAX_STRIP_ROWS collapses to "+N more".
+ */
+export function renderStrip(input: StripInput, paint: Paint): string[] {
+	const width = Math.max(20, input.width);
+	const out: string[] = [];
+	if (input.selected !== undefined) {
+		const hint = input.viewOpen
+			? "↑/↓ scroll · PgUp/PgDn page · ← agents · ⇥ next · x stop · esc back"
+			: "↑/↓ select · ⏎ view · x stop · ctrl+x ctrl+k stop all · esc back";
+		out.push(paint.fg("dim", cut(hint, width)));
+	}
+	const shown = input.rows.slice(0, MAX_STRIP_ROWS);
+	for (const [index, row] of shown.entries()) {
+		const selected = input.selected === index;
+		const mark = selected ? "❯" : " ";
+		const stats = [
+			formatDuration(row.startedAt, row.finishedAt, input.now),
+			row.tokens ? `↓ ${formatTokenCount(row.tokens)} tokens` : "",
+		]
+			.filter(Boolean)
+			.join(" · ");
+		const elbow = row.depth > 0 ? `${"  ".repeat(row.depth - 1)}└ ` : "";
+		const left = `${elbow}${mark} ${row.label}${row.activity ? `  ${row.activity}` : ""}`;
+		const line = splitCell(left, stats, width);
+		if (selected) out.push(paint.fg("accent", paint.bold(line)));
+		else if (STATUS_ROW_STYLE[row.status]) out.push(paint.fg(STATUS_ROW_STYLE[row.status]!, line));
+		else out.push(row.run ? line : paint.fg("dim", line));
+	}
+	if (input.rows.length > shown.length) {
+		out.push(paint.fg("dim", cut(`  +${input.rows.length - shown.length} more — /agents`, width)));
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// The child transcript viewer (Enter-to-view)
+// ---------------------------------------------------------------------------
+
+const SPINNER_VERBS = ["Working", "Moseying", "Gusting", "Scampering", "Percolating", "Noodling", "Puttering", "Simmering"];
+
+/** A stable-ish live verb: cycles by elapsed seconds so it animates without Math.random. */
+export function spinnerVerb(startedAt: number, now: number): string {
+	const seconds = Math.max(0, Math.floor((now - startedAt) / 1000));
+	return SPINNER_VERBS[Math.floor(seconds / 3) % SPINNER_VERBS.length];
+}
+
+/**
+ * Word-aware wrap for prose (task text, assistant text): breaks at spaces,
+ * hard-breaking only words longer than the width; preserves blank lines. Plain
+ * text in, plain lines out — painting happens after, per line.
+ */
+export function wrapProse(text: string, width: number): string[] {
+	const columns = Math.max(1, width);
+	const out: string[] = [];
+	for (const raw of text.replace(/\r\n/g, "\n").split("\n")) {
+		if (raw.trim() === "") {
+			out.push("");
+			continue;
+		}
+		let line = "";
+		for (const word of raw.split(" ")) {
+			if (visibleWidth(word) > columns) {
+				// A word wider than the screen (path, hash): flush, then hard-break it.
+				// The last chunk becomes the running line so later words can join it.
+				if (line) out.push(line);
+				const chunks = hardWrapColumns(word, columns);
+				line = chunks.pop() ?? "";
+				out.push(...chunks);
+				continue;
+			}
+			const candidate = line ? `${line} ${word}` : word;
+			if (visibleWidth(candidate) > columns) {
+				out.push(line);
+				line = word;
+			} else {
+				line = candidate;
+			}
+		}
+		out.push(line);
+	}
+	return out;
+}
+
+/**
+ * Renders one prose unit (assistant text) to painted lines at width. `ref`
+ * identifies the unit across frames so implementations can cache: a settled
+ * block passes the block object, the streaming tail passes a per-run string
+ * key. The default is plain `wrapProse`; index.ts injects a pi-tui Markdown
+ * renderer (prose.ts) so the child's text matches the main transcript.
+ */
+export type ProseRenderer = (ref: object | string, text: string, width: number) => string[];
+
+const plainProse: ProseRenderer = (_ref, text, width) => wrapProse(text, width);
+
+export interface TranscriptInput {
+	run: LiveRun;
+	width: number;
+	height: number;
+	/** Lines scrolled BACK from the tail; 0 follows the stream (Claude Code style). */
+	scroll: number;
+	now: number;
+	prose?: ProseRenderer;
+}
+
+export interface TranscriptOutput {
+	lines: string[];
+	/** Largest useful `scroll` for the current width/height — the caller's clamp. */
+	maxScroll: number;
+}
+
+/**
+ * The full child session view: a synthesized identity header, the transcript
+ * (wrapped, scrollable, tail-anchored so streamed text flows in like the main
+ * session), and a live spinner (or terminal status) as the bottom row — key
+ * hints live in the strip, like Claude Code's agent tree. Exactly `height`
+ * painted lines, blank-filled between body and status — as an overlay every
+ * row must paint, or the main transcript bleeds through the gap.
+ */
+export function renderTranscript(input: TranscriptInput, paint: Paint): TranscriptOutput {
+	const { run } = input;
+	const width = Math.max(20, input.width);
+	const prose = input.prose ?? plainProse;
+	const out: string[] = [];
+
+	// Header: name + label chip, then identity, then a stats line.
+	out.push(splitPaint(paint, "accent", run.name, chip(run.label), width, paint.bold));
+	const identity = [run.agentType, run.model, run.thinking ? `${run.thinking} effort` : ""].filter(Boolean).join(" · ");
+	out.push(paint.fg("dim", cut(identity, width)));
+	const stats = [
+		`${run.toolCalls} tool call${run.toolCalls === 1 ? "" : "s"}`,
+		run.tokens.output ? `↓ ${formatTokenCount(run.tokens.output)} tokens` : "",
+		formatDuration(run.startedAt, run.finishedAt, input.now),
+	]
+		.filter(Boolean)
+		.join(" · ");
+	out.push(paint.fg("dim", cut(stats, width)));
+	out.push("");
+
+	// Body: settled blocks then the in-flight assistant text, all wrapped, then
+	// windowed ANCHORED TO THE TAIL — scroll counts lines back from the end, so
+	// the default view follows streaming like Claude Code.
+	const bodyRows = Math.max(0, input.height - out.length - 1);
+	const blockLines = run.blocks.flatMap((block) => blockToLines(block, width, paint, prose));
+	const partial = streamingText(run.streaming).trimEnd();
+	if (partial) for (const line of prose(`stream:${run.taskId}`, partial, width)) blockLines.push(line);
+	while (blockLines.length && blockLines.at(-1) === "") blockLines.pop();
+	const maxScroll = Math.max(0, blockLines.length - bodyRows);
+	const start = maxScroll - Math.max(0, Math.min(input.scroll, maxScroll));
+	const window = blockLines.slice(start, start + bodyRows);
+	for (const line of window) out.push(line);
+	while (out.length < input.height - 1) out.push(""); // fill so the status sits at the bottom edge
+
+	// Bottom row: spinner (or terminal status) on the left; when the body
+	// overflows, a dim "↑/↓ scroll" affordance right-aligned so scrolling is
+	// discoverable right where the reader is looking (key hints otherwise live in
+	// the strip). splitPaint fuses to the left alone when the hint is "" (body
+	// fits) or the row is too narrow.
+	const scrollHint = maxScroll > 0 ? "↑/↓ scroll" : "";
+	const bottomRow = (text: string, color: string): string => splitPaint(paint, color, text, scrollHint, width, undefined, "dim", false);
+	if (run.status === "running") {
+		const verb = spinnerVerb(run.startedAt, input.now);
+		const spin = `${verb}… (${formatDuration(run.startedAt, undefined, input.now)}${
+			run.tokens.output ? ` · ↓ ${formatTokenCount(run.tokens.output)} tokens` : ""
+		}${run.thinking ? ` · thinking with ${run.thinking} effort` : ""})`;
+		out.push(bottomRow(spin, "accent"));
+	} else {
+		const [text, color] = TERMINAL_STATUS[run.status] ?? ["✔ Completed", "dim"];
+		out.push(bottomRow(text, color));
+	}
+	// The header alone exceeds a very small height; trim so the "exactly
+	// `height` painted lines" contract holds for every caller, not just the
+	// one that clamps height to ≥ 8.
+	return { lines: out.slice(0, Math.max(1, input.height)), maxScroll };
+}
+
+/**
+ * A block's painted lines: assistant text goes through the prose renderer,
+ * the task prompt stays plain-dim (it is input, not markdown output); both get
+ * a trailing blank for paragraph spacing. Call/result stay one line each, a
+ * blank after the result so tool groups read like the main transcript.
+ */
+function blockToLines(block: TranscriptBlock, width: number, paint: Paint, prose: ProseRenderer): string[] {
+	if (block.kind === "task") return [...wrapProse(block.text, width).map((l) => paint.fg("dim", l)), ""];
+	if (block.kind === "text") return [...prose(block, block.text, width), ""];
+	if (block.kind === "call") return [`${paint.fg("accent", "●")} ${cut(`${block.tool}(${block.text})`, width - 2)}`];
+	const body = cut(block.text, width - 4);
+	return [`  ${paint.fg("dim", "⎿")} ${block.isError ? paint.fg("error", body) : body}`, ""];
+}
+
+/** A small inverse-video chip for the label, degrading to `[label]` when narrow. */
+function chip(label: string): string {
+	return label ? ` ${label} ` : "";
+}
+
+/**
+ * A `splitRow` layout with each half painted, dropping the right half (showing
+ * the left full-width) when the row fuses/narrows. The right half defaults to
+ * accent+bold (the header chip); callers pass `rightColor`/`boldRight` for other
+ * styles (e.g. the dim, unbold scroll hint on the transcript's bottom row).
+ */
+function splitPaint(
+	paint: Paint,
+	leftColor: string,
+	left: string,
+	right: string,
+	width: number,
+	boldLeft?: (t: string) => string,
+	rightColor = "accent",
+	boldRight = true,
+): string {
+	const paintLeft = (t: string) => paint.fg(leftColor, boldLeft ? boldLeft(t) : t);
+	const row = splitRow(left, right, width);
+	if ("fused" in row) return paintLeft(cut(left, width));
+	return `${paintLeft(row.left)}  ${paint.fg(rightColor, boldRight ? paint.bold(row.right) : row.right)}`;
+}

package/extensions/subagents/panel-widget.ts

@@ -0,0 +1,330 @@
+/**
+ * The persistent panel below the editor: Claude Code's agent tree PLUS its
+ * background-shell manager (chip → Background list → shell details, rendered
+ * by shell-panel.ts). Mirrors workflow/widget.ts: a component-overload
+ * setWidget so rows can right-align against the real width, debounced
+ * re-renders, and a 1s ticker to keep elapsed time moving. Also carries both
+ * soft-focus states for the down-arrow flow (wired in index.ts): the FIRST ↓
+ * lands on the shells chip when shells run, the next ↓ moves into the agent
+ * rows.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BackgroundTask } from "../background/registry.ts";
+import type { ShellTaskTracker } from "../lib/shell-tasks.ts";
+import { linesComponent, liveUiCtx, safeThemeBold, safeThemeInverse, safeThemePaint } from "../lib/tui-render.ts";
+import { buildRows, MAX_STRIP_ROWS, nextAgentTaskId, renderStrip, type PanelRow } from "./panel-render.ts";
+import type { LiveRunRegistry } from "./live-runs.ts";
+import {
+	anchorShellFocus,
+	renderShellSection,
+	type ShellFocus,
+	shellRows,
+	shellSectionVisible,
+} from "./shell-panel.ts";
+
+const WIDGET_KEY = "subagents";
+const DEBOUNCE_MS = 200;
+
+interface TuiLike {
+	getFocusedComponent?(): unknown;
+}
+
+export class SubagentWidget {
+	private timer: ReturnType<typeof setTimeout> | undefined;
+	private ticker: ReturnType<typeof setInterval> | undefined;
+	focusIndex: number | undefined;
+	/**
+	 * The selected row's identity — "main" or a run's taskId. Rows shift as
+	 * runs register (newest-first) and expire (linger), so every read
+	 * re-anchors focusIndex to this id; Enter/x then act on the run the user
+	 * actually selected, never on whatever slid into its slot.
+	 */
+	private focusId: string | undefined;
+	/** The shell-manager side of the panel (chip → list → details). */
+	shellFocus: ShellFocus | undefined;
+	/**
+	 * The taskId whose transcript is open, or undefined when none is (set by
+	 * index.ts). Drives the strip's scroll hints AND pins that run in the strip
+	 * so a finished child never drops out from under an open viewer.
+	 */
+	private viewedId: string | undefined;
+	tui: TuiLike | undefined;
+	editorBaseline: unknown;
+	/**
+	 * Set by dispose(). pi replaces the session (and this extension instance) on
+	 * /clear, /new and /resume, then invalidates the old ctx: every getter on it
+	 * throws. Children killed at that shutdown keep emitting registry changes for
+	 * a moment, so schedule()/render() must become no-ops the instant we are
+	 * disposed — a timer firing render() against the stale ctx crashed the whole
+	 * process (SUBAGENT-REVIEW H1).
+	 */
+	private disposed = false;
+	private readonly unsubscribes: Array<() => void> = [];
+
+	constructor(
+		private readonly registry: LiveRunRegistry,
+		private readonly getCtx: () => ExtensionContext | undefined,
+		private readonly shells?: ShellTaskTracker,
+	) {
+		this.unsubscribes.push(registry.subscribe(() => this.schedule()));
+		if (shells) this.unsubscribes.push(shells.subscribe(() => this.schedule()));
+	}
+
+	/** The ctx to paint on: none once disposed, or once pi has invalidated it (lib/tui-render.ts liveUiCtx). */
+	private liveCtx(): ExtensionContext | undefined {
+		return this.disposed ? undefined : liveUiCtx(this.getCtx());
+	}
+
+	private rows(): PanelRow[] {
+		let mainBusy = false;
+		try {
+			const ctx = this.getCtx();
+			mainBusy = ctx ? !ctx.isIdle() : false;
+		} catch {
+			mainBusy = false;
+		}
+		return buildRows(this.registry.list(), mainBusy, Date.now(), this.viewedId);
+	}
+
+	rowCount(): number {
+		return Math.min(this.rows().length, MAX_STRIP_ROWS);
+	}
+
+	/** The focused row's run (undefined for the `main` row or when unfocused). */
+	selectedRun() {
+		if (this.focusIndex === undefined) return undefined;
+		const rows = this.rows();
+		this.anchor(rows);
+		return this.focusIndex === undefined ? undefined : rows[this.focusIndex]?.run;
+	}
+
+	setFocus(index: number | undefined): void {
+		this.focusIndex = index;
+		this.focusId = index === undefined ? undefined : (this.rows()[index]?.run?.taskId ?? "main");
+		this.render();
+	}
+
+	/** index.ts sets the open transcript's taskId (or undefined on close) so the
+	 * strip switches to scroll hints and pins that run visible. Also parks the
+	 * strip highlight on the viewed run while it is within the visible window, so
+	 * the ❯ tracks what is on screen (read-mode actions target the viewed run
+	 * regardless — see selectedRun's window caveat). */
+	setView(taskId: string | undefined): void {
+		if (this.viewedId === taskId) return;
+		this.viewedId = taskId;
+		if (taskId !== undefined) {
+			const rows = this.rows();
+			const idx = rows.findIndex((r) => r.run?.taskId === taskId);
+			if (idx >= 0 && idx < Math.min(rows.length, MAX_STRIP_ROWS)) {
+				this.focusIndex = idx;
+				this.focusId = taskId;
+			}
+		}
+		this.render();
+	}
+
+	/** The taskId whose transcript is open (undefined when none). Read-mode
+	 * actions (stop, next-agent) anchor to this, not the windowed selection. */
+	viewedTaskId(): string | undefined {
+		return this.viewedId;
+	}
+
+	/** The agent to retarget to on Tab, relative to the viewed run in the FULL
+	 * row list (see nextAgentTaskId — avoids the windowed-selection desync). */
+	nextAgentAfter(taskId: string | undefined): string | undefined {
+		return nextAgentTaskId(this.rows(), taskId);
+	}
+
+	// --- Shell-manager state (Claude Code's ↓-to-manage flow) ---
+
+	/** Live shell rows for the list/details views. */
+	shellTasks(): BackgroundTask[] {
+		return this.shells ? shellRows(this.shells.list(), Date.now()) : [];
+	}
+
+	shellIds(): string[] {
+		return this.shellTasks().map((t) => t.id);
+	}
+
+	private runningShellCount(): number {
+		return this.shells?.running().length ?? 0;
+	}
+
+	/** Whether ↓ from the editor should land on the chip first — running shells
+	 * or finished ones still inside the linger window. */
+	shellChipAvailable(): boolean {
+		return this.shellTasks().length > 0;
+	}
+
+	/** `ids`, when the caller already derived the row order, skips re-deriving it. */
+	setShellFocus(focus: ShellFocus | undefined, ids?: string[]): void {
+		this.shellFocus = focus && anchorShellFocus(focus, ids ?? this.shellIds());
+		this.render();
+	}
+
+	/** The anchored current focus (the selected shell may have lingered out). */
+	anchoredShellFocus(ids?: string[]): ShellFocus | undefined {
+		if (this.shellFocus) this.shellFocus = anchorShellFocus(this.shellFocus, ids ?? this.shellIds());
+		return this.shellFocus;
+	}
+
+	/** Point lookup — no need for the linger-filtered, sorted row build. */
+	shellTaskById(id: string): BackgroundTask | undefined {
+		return this.shells?.list().find((t) => t.id === id);
+	}
+
+	selectedShellTask(): BackgroundTask | undefined {
+		const focus = this.anchoredShellFocus();
+		if (!focus || focus.stage === "chip") return undefined;
+		return this.shellTaskById(focus.selectedId);
+	}
+
+	private shellVisible(): boolean {
+		return shellSectionVisible(this.shellTasks().length, this.shellFocus);
+	}
+
+	/** Lines the shell section currently occupies (for overlay reserve math) —
+	 * measured off the real renderer so layout changes can never desync it. */
+	shellLineCount(): number {
+		return this.shellVisible() ? this.shellSectionLines(80).length : 0;
+	}
+
+	/** Re-derive focusIndex from focusId against the given rows (see focusId doc). */
+	private anchor(rows: PanelRow[]): void {
+		if (this.focusIndex === undefined || this.focusId === undefined) return;
+		const shown = Math.min(rows.length, MAX_STRIP_ROWS);
+		const idx = this.focusId === "main" ? 0 : rows.findIndex((r) => r.run?.taskId === this.focusId);
+		if (idx >= 0 && idx < shown) {
+			this.focusIndex = idx;
+		} else {
+			// The selected run left the strip — fall back to the nearest row.
+			this.focusIndex = Math.max(0, Math.min(this.focusIndex, shown - 1));
+			this.focusId = rows[this.focusIndex]?.run?.taskId ?? "main";
+		}
+	}
+
+	editorFocused(): boolean {
+		return Boolean(this.tui && this.editorBaseline && this.tui.getFocusedComponent?.() === this.editorBaseline);
+	}
+
+	/** Whether dispose() has run (for tests and callers that hold a reference). */
+	get isDisposed(): boolean {
+		return this.disposed;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		// Order matters: the widget is removed through the ctx BEFORE the flag
+		// flips (liveCtx() refuses a disposed panel), and the subscriptions go
+		// so no later registry/shell event can re-arm a timer.
+		const ctx = this.liveCtx();
+		this.disposed = true;
+		if (this.timer) clearTimeout(this.timer);
+		if (this.ticker) clearInterval(this.ticker);
+		this.timer = this.ticker = undefined;
+		for (const unsubscribe of this.unsubscribes.splice(0)) unsubscribe();
+		try {
+			ctx?.ui.setWidget(WIDGET_KEY, undefined);
+		} catch {
+			// The ctx went stale between the check and the call; nothing to remove.
+		}
+	}
+
+	private schedule(): void {
+		if (this.disposed || this.timer) return;
+		this.timer = setTimeout(() => {
+			this.timer = undefined;
+			this.render();
+		}, DEBOUNCE_MS);
+		this.timer.unref?.();
+	}
+
+	/** The shell section's lines; identity paint when only counting. */
+	private shellSectionLines(
+		width: number,
+		paint = { fg: (_c: string, t: string) => t, bold: (t: string) => t, inverse: (t: string) => t },
+	): string[] {
+		return renderShellSection(
+			{
+				rows: this.shellTasks(),
+				runningCount: this.runningShellCount(),
+				focus: this.shellFocus,
+				width,
+				now: Date.now(),
+			},
+			paint,
+		);
+	}
+
+	private render(): void {
+		const ctx = this.liveCtx();
+		if (!ctx) {
+			// No live UI to paint (headless, or the session was replaced): stop the
+			// ticker too, or it keeps waking a panel nobody can see.
+			this.syncTicker(false);
+			return;
+		}
+		const rows = this.rows();
+		const shellVisible = this.shellVisible();
+		// The chip is time-invariant while every shell runs (count changes arrive
+		// as tracker events), so the clock is needed only for the list (linger
+		// expiry) and details (runtime, live output) stages — or when finished
+		// shells are lingering, whose expiry is what hides the section.
+		const shellStage = this.shellFocus?.stage;
+		const lingering = shellVisible && this.shellTasks().length > this.runningShellCount();
+		this.syncTicker(rows.length > 1 || shellStage === "list" || shellStage === "details" || lingering);
+		// Only the synthetic `main` row exists and no shells → nothing to show yet.
+		// Never tear down while a transcript view is open (viewedId set): clearing
+		// focus here would orphan the overlay with no key path to close it.
+		if (rows.length <= 1 && !shellVisible && this.viewedId === undefined) {
+			ctx.ui.setWidget(WIDGET_KEY, undefined);
+			this.focusIndex = undefined;
+			this.focusId = undefined;
+			this.shellFocus = undefined;
+			return;
+		}
+		this.anchor(rows);
+		if (this.shellFocus) this.shellFocus = anchorShellFocus(this.shellFocus, this.shellIds());
+		const selected = this.focusIndex;
+		const showStrip = rows.length > 1;
+		const now = Date.now();
+		ctx.ui.setWidget(
+			WIDGET_KEY,
+			(tui, theme) => {
+				this.tui = tui as TuiLike;
+				const focused = (tui as TuiLike).getFocusedComponent?.();
+				if (focused && typeof (focused as { getText?: unknown }).getText === "function") {
+					this.editorBaseline = focused;
+				}
+				const paint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme), inverse: safeThemeInverse(theme) };
+				return linesComponent((width) => {
+					const lines: string[] = [];
+					if (showStrip) lines.push(...renderStrip({ rows, selected, viewOpen: this.viewedId !== undefined, width: width - 1, now }, paint));
+					if (shellVisible) {
+						if (lines.length) lines.push("");
+						lines.push(...this.shellSectionLines(width - 1, paint));
+					}
+					return lines.map((line) => ` ${line}`);
+				});
+			},
+			{ placement: "belowEditor" },
+		);
+	}
+
+	/**
+	 * Tick while any child row is shown or the shell manager is focused —
+	 * elapsed times move, finished rows expire out of the strip/list (linger
+	 * windows), and the details view's output box follows the live spool,
+	 * all without needing another registry event.
+	 */
+	private syncTicker(active: boolean): void {
+		if (active && !this.ticker && !this.disposed) {
+			this.ticker = setInterval(() => this.render(), 1000);
+			this.ticker.unref?.();
+		} else if (!active && this.ticker) {
+			clearInterval(this.ticker);
+			this.ticker = undefined;
+		}
+	}
+}