@signalridge/pi-subagents 1.11.1 → 1.13.0

package/src/ui/fleet-list.ts

@@ -11,17 +11,31 @@
  * can `consume` keys — gated on `getEditorText() === ""` so normal typing is untouched.
  */
 
-import { Editor, isKeyRelease, Key, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { borderedComponent } from "@signalridge/pi-ui";
+import { type Component, isKeyRelease, Key, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { borderedComponent, sanitizeDisplayText } from "@signalridge/pi-ui";
 import { renderAgentName } from "../agent-color.js";
 import type { AgentManager } from "../agent-manager.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal } from "../usage.js";
 import { type AgentActivity, type Theme } from "./agent-display.js";
-import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
-import { sanitizeDisplayText } from "./safe-text.js";
+import { ConversationViewer, getConversationOverlayOptions, getConversationViewerMode } from "./conversation-viewer.js";
+import { type OwnerGroup, OwnerGroupViewer, workflowGroupId } from "./owner-group.js";
 import { getAgentStatusColor, getAgentStatusLabel, getAgentStatusMark } from "./status-label.js";
 import type { ViewerKeybindings } from "./viewer-keys.js";
+import type { WorkflowUiClient } from "./workflow-ui-client.js";
+
+/** Immutable selection, including the attempt generation on a reusable native thread. */
+export function captureAgentSelection(manager: AgentManager, record: AgentRecord, isCurrent: () => boolean = () => true) {
+  const session = record.session;
+  const owner = record.owner ? { ...record.owner } : undefined;
+  const snapshot = { ...record, owner, lifetimeUsage: { ...record.lifetimeUsage } };
+  const current = (): AgentRecord | undefined => isCurrent() ? manager.listAgentsMutable().find(candidate =>
+    candidate.id === snapshot.id && candidate.session === session && !candidate.detached &&
+    candidate.owner?.extension === owner?.extension && candidate.owner?.runId === owner?.runId &&
+    candidate.owner?.nodeId === owner?.nodeId && candidate.owner?.attemptId === owner?.attemptId) : undefined;
+  return { snapshot, session, owner, current };
+}
+export type AgentSelection = ReturnType<typeof captureAgentSelection>;
 
 /** Widget key for the below-editor fleet list. */
 const FLEET_KEY = "fleet";
@@ -48,9 +62,10 @@ export type FleetUICtx = {
   ): Promise<T>;
 };
 
-type MainEntry = { kind: "main" };
-type AgentEntry = { kind: "agent"; record: AgentRecord };
-type FleetEntry = MainEntry | AgentEntry;
+type MainEntry = { kind: "main"; id: string };
+type AgentEntry = { kind: "agent"; id: string; record: AgentRecord };
+type GroupEntry = { kind: "group"; id: string; group: OwnerGroup };
+type FleetEntry = MainEntry | AgentEntry | GroupEntry;
 
 /** `11s` — integer seconds, no decimal/suffix (matches Claude Code, unlike formatMs). */
 export function formatFleetElapsed(ms: number): string {
@@ -91,15 +106,44 @@ export class FleetList {
   private active = false;
   /** 0 = `main`, 1..N = subagents. */
   private selectedIndex = 0;
+  private selectedId = "main";
+  private overlayGeneration = 0;
   /** Set while a conversation overlay is open; calling it closes the overlay. */
   private viewerClose: (() => void) | undefined;
   private viewingAgentId: string | undefined;
+  private workflowClient: WorkflowUiClient | undefined;
+  private externalOpening = false;
+  private externalViewingId: string | undefined;
+  private externalTimer: ReturnType<typeof setTimeout> | undefined;
+
+  setWorkflowClient(client: WorkflowUiClient | undefined): void {
+    this.workflowClient = client;
+    this.update();
+  }
+
+  /** Shared exact-attempt opener for user selections and the workflow UI endpoint. */
+  canOpenConversation(selection: AgentSelection): boolean {
+    return !!this.ui && !this.viewerClose && !!selection.session && !!selection.current();
+  }
+
+  openConversation(selection: AgentSelection, deferConstruction = false): boolean {
+    if (!this.canOpenConversation(selection)) return false;
+    this.viewingAgentId = selection.snapshot.id;
+    const mode = this.conversationMode();
+    void this.openOverlay((tui, theme, keys, done) => {
+      if (!selection.current()) { done(undefined); return { render: () => [], invalidate: () => {} }; }
+      return this.conversation(selection, tui, theme, keys, done, undefined, mode);
+    }, mode, deferConstruction);
+    return true;
+  }
 
   constructor(
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
   ) {}
 
+  conversationMode(): "fullscreen" | "overlay" { return getConversationViewerMode(this.tui); }
+
   // ---- Lifecycle ----
 
   setEnabled(enabled: boolean): void {
@@ -112,7 +156,7 @@ export class FleetList {
   /** Capture the UI context and (re)register the global input handler. */
   setUICtx(ui: FleetUICtx): void {
     if (ui === this.ui) return;
-    this.inputUnsub?.();
+    this.dispose();
     this.ui = ui;
     this.widgetRegistered = false;
     this.tui = undefined;
@@ -133,6 +177,12 @@ export class FleetList {
   }
 
   dispose(): void {
+    this.overlayGeneration++;
+    if (this.externalTimer) clearTimeout(this.externalTimer);
+    this.externalTimer = undefined;
+    this.externalOpening = false;
+    this.externalViewingId = undefined;
+    this.workflowClient = undefined;
     if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
     this.inputUnsub?.();
     this.inputUnsub = undefined;
@@ -149,7 +199,8 @@ export class FleetList {
   /** Re-register/refresh the below-editor widget; clears it when no agents remain. */
   update(): void {
     if (!this.ui) return;
-    const hasAgents = this.enabled && this.agentRecords().length > 0;
+    if (this.externalViewingId && !this.externalOpening && this.editorHasFocus()) this.externalViewingId = undefined;
+    const hasAgents = this.enabled && this.roster().length > 1;
 
     if (!hasAgents) {
       if (this.widgetRegistered) {
@@ -160,6 +211,7 @@ export class FleetList {
       if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
       this.active = false;
       this.selectedIndex = 0;
+      this.selectedId = "main";
       return;
     }
 
@@ -171,7 +223,8 @@ export class FleetList {
         this.tui = tui;
         return {
           render: (w: number) => this.renderBar(w, theme),
-          invalidate: () => { this.widgetRegistered = false; this.tui = undefined; },
+          invalidate: () => { /* no render cache; mounting/focus remain owned */ },
+          dispose: () => { if (this.tui === tui) { this.widgetRegistered = false; this.tui = undefined; } },
         };
       }, { placement: "belowEditor" });
       this.widgetRegistered = true;
@@ -193,7 +246,7 @@ export class FleetList {
   private agentRecords(): AgentRecord[] {
     const now = Date.now();
     return this.manager.listAgentsMutable()
-      .filter(a => !a.parentAgentId && a.session && (
+      .filter(a => !a.parentAgentId && !a.detached && !workflowGroupId(a) && a.session && (
         a.status === "running" || a.status === "queued"
         || a.id === this.viewingAgentId
         || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)
@@ -201,14 +254,47 @@ export class FleetList {
       .sort((a, b) => a.startedAt - b.startedAt);
   }
 
+  private groups(): OwnerGroup[] {
+    const groups = new Map<string, OwnerGroup>();
+    for (const record of this.manager.listAgentsMutable()) {
+      if (record.parentAgentId || record.detached) continue;
+      const id = workflowGroupId(record);
+      if (!id) continue;
+      let group = groups.get(id);
+      if (!group) { group = { id, runId: record.owner!.runId, records: [] }; groups.set(id, group); }
+      group.records.push(record);
+    }
+    const retained = new Set([...groups.values()].map(group => group.runId));
+    if (this.externalViewingId) retained.add(this.externalViewingId);
+    for (const run of this.workflowClient?.runs(retained) ?? []) {
+      const id = JSON.stringify(["pi-workflows", run.runId]);
+      const group = groups.get(id) ?? { id, runId: run.runId, records: [] };
+      group.summary = run;
+      groups.set(id, group);
+    }
+    for (const group of groups.values()) group.records.sort((a, b) => a.startedAt - b.startedAt || a.id.localeCompare(b.id));
+    return [...groups.values()];
+  }
+
   private roster(): FleetEntry[] {
-    return [{ kind: "main" }, ...this.agentRecords().map(record => ({ kind: "agent" as const, record }))];
+    return [
+      { kind: "main", id: "main" },
+      ...this.groups().map(group => ({ kind: "group" as const, id: `group:${group.id}`, group })),
+      ...this.agentRecords().map(record => ({ kind: "agent" as const, id: `agent:${record.id}`, record })),
+    ];
   }
 
-  private clampSelection(): void {
-    const max = this.roster().length - 1;
-    if (this.selectedIndex > max) this.selectedIndex = Math.max(0, max);
-    if (this.selectedIndex < 0) this.selectedIndex = 0;
+  private clampSelection(roster = this.roster()): void {
+    const index = roster.findIndex(entry => entry.id === this.selectedId);
+    // Missing identity returns explicitly to main, never to a different child.
+    this.selectedIndex = index >= 0 ? index : 0;
+    this.selectedId = roster[this.selectedIndex].id;
+  }
+
+  private select(index: number): void {
+    const roster = this.roster();
+    this.selectedIndex = Math.max(0, Math.min(roster.length - 1, index));
+    this.selectedId = roster[this.selectedIndex].id;
   }
 
   // ---- Key handling ----
@@ -221,38 +307,52 @@ export class FleetList {
     // tap would move/fire twice. Repeats still pass through for held-key nav.
     if (isKeyRelease(data)) return undefined;
     // While an overlay is open, let it own all input.
-    if (this.viewerClose) return undefined;
+    if (this.viewerClose || this.externalOpening) return undefined;
     // Input listeners fire BEFORE the focused component, and dialogs
     // (ctx.ui.select/confirm/input, pi's own menus) swap the prompt editor out
     // while getEditorText() still reads the detached — empty — editor. So when
     // anything but the editor owns the keyboard, stay out of its keys (#123).
     if (!this.editorHasFocus()) {
-      if (this.active) this.deactivate();
+      if (this.active && !this.externalViewingId) this.deactivate();
       return undefined;
     }
+    this.externalViewingId = undefined;
+
+    if (!this.active && this.ui.getEditorText() === "" && matchesKey(data, "ctrl+b")) {
+      const candidates = this.manager.listAgentsMutable().filter(record => !record.detached && !record.parentAgentId &&
+        !record.owner && record.isBackground === false && record.status === "running");
+      const eligible = candidates.filter(record => this.manager.canHandoff(record.id));
+      if (eligible.length > 1) this.ui.notify("Multiple foreground agents; select a conversation and press b to hand off explicitly.", "info");
+      else if (eligible.length === 1) this.handoff(captureAgentSelection(this.manager, eligible[0]));
+      else if (candidates.length) this.ui.notify(this.manager.handoffUnavailableReason(candidates[0].id) ?? "No eligible foreground agent.", "warning");
+      else return undefined;
+      return { consume: true };
+    }
 
     if (!this.active) {
       // Activate: ↓ or ← at an empty prompt moves focus into the list.
       const isActivator = matchesKey(data, "down") || matchesKey(data, "left");
-      if (isActivator && this.agentRecords().length > 0 && this.ui.getEditorText() === "") {
+      if (isActivator && this.roster().length > 1 && this.ui.getEditorText() === "") {
         this.active = true;
-        this.selectedIndex = 0;
+        this.select(0);
         this.update();
         return { consume: true };
       }
       return undefined;
     }
 
+    // Reconcile identity before both navigation and opening, even between ticks.
+    this.clampSelection();
     // Active — arrows navigate, Enter opens, Esc / Up-past-top exits.
     if (matchesKey(data, "down")) {
       const max = this.roster().length - 1;
-      this.selectedIndex = Math.min(max, this.selectedIndex + 1);
+      this.select(Math.min(max, this.selectedIndex + 1));
       this.update();
       return { consume: true };
     }
     if (matchesKey(data, "up")) {
       if (this.selectedIndex === 0) { this.deactivate(); return { consume: true }; }
-      this.selectedIndex -= 1;
+      this.select(this.selectedIndex - 1);
       this.update();
       return { consume: true };
     }
@@ -265,64 +365,129 @@ export class FleetList {
   }
 
   /**
-   * True when pi's prompt editor owns the keyboard. pi's editor is an `Editor`
-   * subclass (CustomEditor) while every dialog/selector is not, and the loader
-   * aliases pi-tui to pi's own copy, so `instanceof` is a reliable identity
-   * check. `focusedComponent` is TUI-private (no public accessor), hence the
-   * best-effort peek: unknowable focus (no tui seen yet, nothing focused)
-   * counts as the editor so activation keeps working.
+   * True when pi's prompt editor owns the keyboard. The editor is pluggable
+   * (ui.setEditorComponent) and need not extend `Editor` (#374), so match pi-tui's
+   * `EditorComponent` contract instead: `getText` + `setText`, which pi calls on
+   * every editor and none of pi's dialogs, selectors or overlays implement.
+   * Use the public structural focus getter (not present in every TUI interface
+   * declaration). Unknown focus retains the initial editor fallback.
    */
   private editorHasFocus(): boolean {
-    const focused = (this.tui as { focusedComponent?: unknown } | undefined)?.focusedComponent;
-    return focused == null || focused instanceof Editor;
+    const focusHost = this.tui as { getFocusedComponent?: () => unknown } | undefined;
+    const focused = typeof focusHost?.getFocusedComponent === "function" ? focusHost.getFocusedComponent() : undefined;
+    if (focused == null) return true;
+    const c = focused as { getText?: unknown; setText?: unknown };
+    return typeof c.getText === "function" && typeof c.setText === "function";
   }
 
   private deactivate(): void {
     this.active = false;
-    this.selectedIndex = 0;
+    this.select(0);
     this.update();
   }
 
   private openSelected(): void {
-    const entry = this.roster()[this.selectedIndex];
+    const roster = this.roster();
+    this.clampSelection(roster);
+    const entry = roster[this.selectedIndex];
     if (!entry || entry.kind === "main") {
       // `main` = return to the prompt; the native transcript is already shown.
       this.deactivate();
       return;
     }
-    const record = entry.record;
     if (!this.ui) return;
+    if (entry.kind === "group") { this.openGroup(entry.group); return; }
+    const record = entry.record;
     if (!record.session) {
       this.ui.notify(`Agent is ${record.status}; no session available.`, "info");
       return;
     }
-    const session = record.session;
-    const activity = this.agentActivity.get(record.id);
-    this.viewingAgentId = record.id;
+    this.openConversation(captureAgentSelection(this.manager, record));
+  }
 
-    void this.ui.custom<undefined>(
-      (tui, theme, keybindings, done) => {
-        this.viewerClose = () => done(undefined);
-        return borderedComponent(new ConversationViewer(
-          tui,
-          session,
-          record,
-          activity,
-          theme,
-          done,
-          () => {
-            if (this.manager.abort(record.id)) this.ui?.notify(`Stopped "${sanitizeDisplayText(record.description)}".`, "info");
-          },
-          keybindings,
-          (message: string) => this.manager.steer(record.id, message),
-          () => this.manager.getRecord?.(record.id),
-        ), (text) => theme.fg("borderAccent", text));
-      },
-      {
-        overlay: true,
-        overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
+  conversation(selection: AgentSelection, tui: TUI, theme: Theme, keys: ViewerKeybindings, done: (result: undefined) => void,
+    notify = (message: string) => this.ui?.notify(message, "info"), mode: "fullscreen" | "overlay" = "overlay"): ConversationViewer {
+    const { snapshot: record, session, owner, current } = selection;
+    if (!session || !current()) throw new Error("Conversation selection is no longer active");
+    let last = record;
+    return new ConversationViewer(tui, session, record, this.agentActivity.get(record.id), theme, done,
+      () => { if (current() && this.manager.abort(record.id)) notify(`Stopped "${sanitizeDisplayText(record.description)}".`); },
+      keys,
+      message => current() ? this.manager.steerAccepted(record.id, message, { session, owner }) : Promise.resolve(false),
+      () => {
+        const fresh = current();
+        if (fresh) { last = { ...fresh, owner, lifetimeUsage: { ...fresh.lifetimeUsage } }; return fresh; }
+        return { ...last, detached: true };
       },
-    ).then(() => this.clearViewer(), () => this.clearViewer());
+      { mode, canHandoff: () => !!current() && this.manager.canHandoff(record.id), onHandoff: () => this.handoff(selection) },
+    );
+  }
+
+  private handoff(selection: AgentSelection): boolean {
+    if (!selection.current()) return false;
+    const id = selection.snapshot.id;
+    if (!this.manager.handoff(id)) {
+      this.ui?.notify(this.manager.handoffUnavailableReason(id) ?? "Cannot hand off this agent.", "warning");
+      return false;
+    }
+    this.ui?.notify(`Agent ${sanitizeDisplayText(id)} continues in background.`, "info");
+    this.update();
+    return true;
+  }
+
+  private async openGroup(group: OwnerGroup): Promise<void> {
+    const client = this.workflowClient;
+    const ui = this.ui;
+    const generation = this.overlayGeneration;
+    if (group.summary && client) {
+      this.externalOpening = true;
+      try {
+        await client.open(group.summary);
+        if (generation === this.overlayGeneration && ui === this.ui) this.externalViewingId = group.runId;
+        // Admission precedes the peer's dialog factory. Yield through its next
+        // macrotask, then rely on public TUI focus for the entire interaction.
+        if (generation === this.overlayGeneration && ui === this.ui) {
+          this.externalTimer = setTimeout(() => { this.externalTimer = undefined; this.externalOpening = false; this.update(); }, 0);
+        }
+        return;
+      } catch {
+        if (generation !== this.overlayGeneration || ui !== this.ui) return;
+        ui?.notify("Workflow inspector unavailable; showing retained children only (no workflow controls).", "warning");
+      } finally {
+        if (!this.externalTimer && generation === this.overlayGeneration) this.externalOpening = false;
+      }
+    }
+    if (generation !== this.overlayGeneration || ui !== this.ui) return;
+    if (!group.records.length) { ui?.notify("No retained child conversations for this workflow.", "info"); return; }
+    void this.openOverlay((tui, theme, keys, done) => new OwnerGroupViewer(tui, theme, group.runId,
+      () => this.groups().find(candidate => candidate.id === group.id)?.records ?? [],
+      (record, back) => this.conversation(captureAgentSelection(this.manager, record), tui, theme, keys, back),
+      () => done(undefined), keys));
+  }
+
+  private async openOverlay(factory: (tui: TUI, theme: Theme, keys: ViewerKeybindings, done: (result: undefined) => void) => Component,
+    mode: "fullscreen" | "overlay" = "overlay", deferConstruction = false): Promise<void> {
+    const ui = this.ui;
+    if (!ui) return;
+    const generation = ++this.overlayGeneration;
+    this.viewerClose = () => {}; // reserve input during asynchronous construction
+    try {
+      if (deferConstruction) await Promise.resolve();
+      if (generation !== this.overlayGeneration || ui !== this.ui) return;
+      await ui.custom<undefined>((tui, theme, keys, done) => {
+        if (generation !== this.overlayGeneration || ui !== this.ui) {
+          done(undefined);
+          return { render: () => [], invalidate: () => {} };
+        }
+        this.viewerClose = () => done(undefined);
+        const component = factory(tui, theme, keys, done);
+        return mode === "fullscreen" ? component : borderedComponent(component, text => theme.fg("borderAccent", text));
+      }, { overlay: true, overlayOptions: getConversationOverlayOptions({ mode: mode === "fullscreen" ? "fullscreen" : undefined }) });
+    } catch {
+      if (generation === this.overlayGeneration) ui.notify("Cannot open conversation; try again.", "error");
+    } finally {
+      if (generation === this.overlayGeneration) this.clearViewer();
+    }
   }
 
   /** Reset overlay state and return to the list (on close, auto-close, or error). */
@@ -333,7 +498,7 @@ export class FleetList {
     // update()'s clamp to settle.
     if (this.viewingAgentId) {
       const idx = this.roster().findIndex(e => e.kind === "agent" && e.record.id === this.viewingAgentId);
-      if (idx >= 0) this.selectedIndex = idx;
+      if (idx >= 0) this.select(idx);
     }
     this.viewerClose = undefined;
     this.viewingAgentId = undefined;
@@ -343,9 +508,12 @@ export class FleetList {
   // ---- Rendering ----
 
   private renderBar(width: number, theme: Theme): string[] {
-    const agents = this.roster().slice(1) as AgentEntry[];
+    if (width <= 0) return [];
+    const roster = this.roster();
+    this.clampSelection(roster);
+    const agents = roster.slice(1);
     if (agents.length === 0) return [];
-    const sel = Math.min(this.selectedIndex, agents.length);
+    const sel = this.selectedIndex;
 
     // Key names read as proper nouns, the verbs after them stay lowercase, and
     // segments are separated by " · " — the same shape every hint line in the
@@ -353,9 +521,13 @@ export class FleetList {
     const hint = this.active
       ? "↑↓ navigate · Enter view · Esc back"
       : "Esc interrupt · ← agents · ↓ manage";
+    const height = Math.max(0, Math.floor((this.tui?.terminal.rows ?? 24) / 2));
+    if (height === 0) return [];
     const lines: string[] = [];
-    lines.push(truncateToWidth(`  ${theme.fg("dim", hint)}`, width));
-    lines.push("");
+    if (height >= 7) {
+      lines.push(truncateToWidth(`  ${theme.fg("dim", hint)}`, width));
+      lines.push("");
+    }
 
     const mainColor = sel === 0 ? "accent" : "dim";
     const main = sel === 0
@@ -365,18 +537,38 @@ export class FleetList {
     const mainMark = theme.fg(mainColor, getAgentStatusMark("running"));
     lines.push(truncateToWidth(`  ${mainMark} ${main} ${theme.fg("dim", "·")} ${theme.fg("dim", "current")}`, width));
 
-    const visible = Math.min(MAX_AGENT_ROWS, agents.length);
+    const rowBudget = Math.max(1, Math.floor((this.tui?.terminal.rows ?? 24) / 2) - 7);
+    const visible = Math.min(MAX_AGENT_ROWS, rowBudget, agents.length);
     const selAgent = Math.max(0, sel - 1);
     const start = selAgent < visible ? 0 : selAgent - visible + 1;
     const hiddenBelow = agents.length - (start + visible);
 
     if (start > 0) lines.push(rightAlign("", theme.fg("dim", `${start} more above`), width));
     for (let a = start; a < start + visible; a++) {
-      lines.push(this.renderAgentRow(a + 1, sel, agents[a].record, width, theme));
+      const entry = agents[a];
+      if (entry.kind === "agent") lines.push(this.renderAgentRow(a + 1, sel, entry.record, width, theme));
+      else if (entry.kind === "group") {
+        const run = entry.group.summary;
+        if (run) {
+          const selected = a + 1 === sel;
+          const status = run.status === "failed" ? "error" : run.status === "pending" || run.status === "paused" ? "queued" :
+            run.status === "stopped" || run.status === "interrupted" ? "stopped" : run.status === "completed" ? "completed" : "running";
+          const color = status === "error" ? "error" : status === "stopped" ? "warning" : selected ? "accent" : "dim";
+          const name = sanitizeDisplayText(run.name);
+          const phase = run.currentPhase ? ` · ${sanitizeDisplayText(run.currentPhase)}` : "";
+          const left = `  ${theme.fg(color, getAgentStatusMark(status))} ${theme.fg(selected ? "accent" : "muted", name)} · ${theme.fg(color, run.status)}${phase} · ${run.runningCalls}/${run.callCount} running · ${run.completedCalls} done · ${run.failedCalls} failed${run.restored ? " · restored" : ""}`;
+          const right = `${formatFleetElapsed(run.elapsedMs)}${run.tokenCount === undefined ? "" : ` · ${formatFleetTokens(run.tokenCount)}`}`;
+          lines.push(rightAlign(left, theme.fg("dim", right), width));
+        } else {
+          const label = `  ▸ Workflow ${sanitizeDisplayText(entry.group.runId)} · ${entry.group.records.length} retained children`;
+          lines.push(truncateToWidth(theme.fg(a + 1 === sel ? "accent" : "muted", label), width));
+        }
+      }
     }
     if (hiddenBelow > 0) lines.push(rightAlign("", theme.fg("dim", `${hiddenBelow} more below`), width));
 
-    return lines;
+    lines.push(""); // breathing room below the roster, including narrow terminals
+    return [...lines.slice(0, height - 1), ""].map(line => truncateToWidth(line, Math.max(0, width)));
   }
 
   private renderAgentRow(rosterIndex: number, sel: number, record: AgentRecord, width: number, theme: Theme): string {

package/src/ui/owner-group.ts

@@ -0,0 +1,110 @@
+/** Observation-only retained workflow children; no workflow engine/RPC dependency. */
+import { type Component, type Focusable, isKeyRelease, matchesKey, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import type { WorkflowUiRunSummary } from "@signalridge/pi-subagents-protocol";
+import { sanitizeDisplayText } from "@signalridge/pi-ui";
+import type { AgentRecord } from "../types.js";
+import type { Theme } from "./agent-display.js";
+import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
+
+type DisposableComponent = Component & Partial<Focusable> & { dispose?(): void };
+
+export type OwnerGroup = { id: string; runId: string; records: AgentRecord[]; summary?: WorkflowUiRunSummary };
+
+export function workflowGroupId(record: AgentRecord): string | undefined {
+  const owner = record.owner;
+  if (owner?.extension !== "pi-workflows" || typeof owner.runId !== "string" || !owner.runId.trim()) return undefined;
+  return JSON.stringify([owner.extension, owner.runId]);
+}
+
+/** A bounded child list that swaps its body for the existing conversation viewer. */
+export class OwnerGroupViewer implements Component, Focusable {
+  private hasFocus = false;
+  get focused(): boolean { return this.hasFocus; }
+  set focused(value: boolean) {
+    this.hasFocus = value;
+    if (this.child && typeof this.child.focused === "boolean") this.child.focused = value;
+  }
+  private selectedId: string | undefined;
+  private initialized = false;
+  private child: DisposableComponent | undefined;
+  private closed = false;
+  private error: string | undefined;
+  private keys: ViewerKeys;
+
+  constructor(
+    private tui: TUI,
+    private theme: Theme,
+    private runId: string,
+    private records: () => AgentRecord[],
+    private open: (record: AgentRecord, done: () => void) => DisposableComponent,
+    private done: () => void,
+    keybindings?: ViewerKeybindings,
+  ) { this.keys = createViewerKeys(keybindings); }
+
+  private roster(): AgentRecord[] {
+    const records = this.records();
+    if (!this.initialized) { this.selectedId = records[0]?.id; this.initialized = true; }
+    else if (!records.some(record => record.id === this.selectedId)) this.selectedId = undefined;
+    return records;
+  }
+
+  handleInput(data: string): void {
+    if (this.closed || isKeyRelease(data)) return;
+    if (this.child) { this.child.handleInput?.(data); return; }
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) { this.done(); return; }
+    const records = this.roster();
+    const index = records.findIndex(record => record.id === this.selectedId);
+    const page = Math.max(1, Math.floor(this.tui.terminal.rows * 0.7) - 5);
+    let next = index;
+    if (this.keys.scrollUp(data)) next--;
+    else if (this.keys.scrollDown(data)) next++;
+    else if (this.keys.pageUp(data)) next -= page;
+    else if (this.keys.pageDown(data)) next += page;
+    else if (matchesKey(data, "home")) next = 0;
+    else if (matchesKey(data, "end")) next = records.length - 1;
+    else if (matchesKey(data, "enter")) {
+      const record = records[index];
+      if (!record?.session) this.error = record ? "No session yet; child retained" : "Selection gone; use ↑↓";
+      else {
+        try {
+          this.child = this.open(record, () => {
+            this.child?.dispose?.();
+            this.child = undefined;
+            this.tui.requestRender();
+          });
+          if (typeof this.child.focused === "boolean") this.child.focused = this.focused;
+          this.error = undefined;
+        } catch { this.error = "Cannot open conversation; try again"; }
+      }
+    }
+    if (records.length && next !== index) this.selectedId = records[Math.max(0, Math.min(records.length - 1, next))].id;
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    if (this.child) return this.child.render(width);
+    const records = this.roster();
+    const selected = records.findIndex(record => record.id === this.selectedId);
+    // Reserve header, two controls rows, and the shared adapter's two borders.
+    const bodyRows = Math.max(1, Math.floor(this.tui.terminal.rows * 0.7) - 5);
+    const start = Math.max(0, selected - bodyRows + 1);
+    const labels = records.map(record => sanitizeDisplayText(record.description));
+    const counts = new Map<string, number>();
+    for (const label of labels) counts.set(label, (counts.get(label) ?? 0) + 1);
+    const lines = [this.theme.fg("accent", `Workflow ${sanitizeDisplayText(this.runId)} · ${records.length} retained children`)];
+    if (!records.length) lines.push("No retained children");
+    for (let index = start; index < Math.min(records.length, start + bodyRows); index++) {
+      const record = records[index];
+      const discriminator = (counts.get(labels[index]) ?? 0) > 1 ? ` [${sanitizeDisplayText(record.id)}]` : "";
+      // The discriminator leads the label so it survives narrow-width clipping.
+      const text = `${record.id === this.selectedId ? ">" : " "}${discriminator} ${labels[index]} · ${record.status}${record.session ? "" : " · no session yet"}`;
+      lines.push(this.theme.fg(record.id === this.selectedId ? "accent" : "muted", text));
+    }
+    lines.push(this.error ? this.theme.fg("error", this.error) : `${selected + 1}/${records.length} · ↑↓/PgUp/PgDn`);
+    lines.push(width >= 22 ? "Esc back · Enter view" : width >= 10 ? "Esc back ↵" : "Esc ↵");
+    return lines.map(line => truncateToWidth(line, Math.max(0, width)));
+  }
+
+  invalidate(): void { this.child?.invalidate(); }
+  dispose(): void { this.closed = true; this.child?.dispose?.(); this.child = undefined; }
+}