@signalridge/pi-subagents 1.12.0 → 1.14.0

package/src/ui/fleet-list.ts

@@ -18,10 +18,24 @@ 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 { 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";
@@ -97,12 +111,39 @@ export class FleetList {
   /** 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 {
@@ -137,6 +178,11 @@ 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;
@@ -153,6 +199,7 @@ export class FleetList {
   /** Re-register/refresh the below-editor widget; clears it when no agents remain. */
   update(): void {
     if (!this.ui) return;
+    if (this.externalViewingId && !this.externalOpening && this.editorHasFocus()) this.externalViewingId = undefined;
     const hasAgents = this.enabled && this.roster().length > 1;
 
     if (!hasAgents) {
@@ -217,6 +264,14 @@ export class FleetList {
       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()];
   }
@@ -252,15 +307,27 @@ 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.
@@ -335,49 +402,87 @@ export class FleetList {
       this.ui.notify(`Agent is ${record.status}; no session available.`, "info");
       return;
     }
-    this.viewingAgentId = record.id;
-    void this.openOverlay((tui, theme, keys, done) => this.conversation(record, tui, theme, keys, done));
+    this.openConversation(captureAgentSelection(this.manager, record));
   }
 
-  private conversation(record: AgentRecord, tui: TUI, theme: Theme, keys: ViewerKeybindings, done: (result: undefined) => void): ConversationViewer {
-    const session = record.session;
-    if (!session) throw new Error("No session available");
-    const owner = record.owner ? { ...record.owner } : undefined;
-    // An id can be reused for another thread attempt. Bind controls to this
-    // session and immutable owner generation, never to id alone.
-    const current = (): AgentRecord | undefined => this.manager.listAgentsMutable().find(candidate =>
-      candidate.id === record.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);
+  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)) this.ui?.notify(`Stopped "${sanitizeDisplayText(record.description)}".`, "info"); },
+      () => { if (current() && this.manager.abort(record.id)) notify(`Stopped "${sanitizeDisplayText(record.description)}".`); },
       keys,
-      message => !!current() && this.manager.steer(record.id, message),
-      () => current() ?? { ...record, status: record.status === "running" || record.status === "queued" ? "stopped" : record.status, detached: true },
+      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 };
+      },
+      { mode, canHandoff: () => !!current() && this.manager.canHandoff(record.id), onHandoff: () => this.handoff(selection) },
     );
   }
 
-  private openGroup(group: OwnerGroup): void {
+  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(record, tui, theme, keys, back),
+      (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): Promise<void> {
+  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);
-        return borderedComponent(factory(tui, theme, keys, done), text => theme.fg("borderAccent", text));
-      }, { overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` } });
+        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 {
@@ -403,6 +508,7 @@ export class FleetList {
   // ---- Rendering ----
 
   private renderBar(width: number, theme: Theme): string[] {
+    if (width <= 0) return [];
     const roster = this.roster();
     this.clampSelection(roster);
     const agents = roster.slice(1);
@@ -415,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
@@ -427,7 +537,8 @@ 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);
@@ -437,13 +548,27 @@ export class FleetList {
       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 label = `  ▸ Workflow ${sanitizeDisplayText(entry.group.runId)} · ${entry.group.records.length} retained children`;
-        lines.push(truncateToWidth(theme.fg(a + 1 === sel ? "accent" : "muted", label), width));
+        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

@@ -1,13 +1,14 @@
 /** Observation-only retained workflow children; no workflow engine/RPC dependency. */
-import { type Component, isKeyRelease, matchesKey, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+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 & { dispose?(): void };
+type DisposableComponent = Component & Partial<Focusable> & { dispose?(): void };
 
-export type OwnerGroup = { id: string; runId: string; records: AgentRecord[] };
+export type OwnerGroup = { id: string; runId: string; records: AgentRecord[]; summary?: WorkflowUiRunSummary };
 
 export function workflowGroupId(record: AgentRecord): string | undefined {
   const owner = record.owner;
@@ -16,7 +17,13 @@ export function workflowGroupId(record: AgentRecord): string | undefined {
 }
 
 /** A bounded child list that swaps its body for the existing conversation viewer. */
-export class OwnerGroupViewer implements Component {
+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;
@@ -65,6 +72,7 @@ export class OwnerGroupViewer implements Component {
             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"; }
       }

package/src/ui/workflow-ui-client.ts

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import {
+  type EventBus,
+  parseWorkflowUiSnapshot,
+  replyChannel,
+  WORKFLOW_UI_CHANNELS,
+  type WorkflowUiRunSummary,
+  type WorkflowUiSnapshot,
+} from "@signalridge/pi-subagents-protocol";
+
+function replyData(raw: unknown): unknown {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(raw))) throw new Error("Invalid workflow UI reply.");
+  const values: Record<string, unknown> = Object.create(null);
+  for (const key of Reflect.ownKeys(raw)) {
+    if (typeof key !== "string" || !["success", "data", "error"].includes(key)) throw new Error("Invalid workflow UI reply.");
+    const descriptor = Object.getOwnPropertyDescriptor(raw, key);
+    if (!descriptor || !Object.hasOwn(descriptor, "value")) throw new Error("Invalid workflow UI reply.");
+    values[key] = descriptor.value as unknown;
+  }
+  if (values.success !== true) throw new Error(typeof values.error === "string" ? values.error : "Workflow UI unavailable.");
+  return values.data;
+}
+
+const TIMEOUT_MS = 2_000;
+export const WORKFLOW_FINISHED_LINGER_MS = 4_000;
+
+export function isWorkflowTerminal(run: WorkflowUiRunSummary): boolean {
+  return ["completed", "failed", "stopped"].includes(run.status);
+}
+
+/** Optional, session/branch-bound presentation peer. No execution or model polling. */
+export class WorkflowUiClient {
+  private snapshot: WorkflowUiSnapshot | undefined;
+  private readonly finishedAt = new Map<string, number>();
+  private readonly requests = new Set<(error?: Error) => void>();
+  private readonly unsubscribe: () => void;
+  private disposed = false;
+  private revision = 0;
+  private querying = false;
+  private queryAgain = false;
+  private queryingSurface: string | undefined;
+  private candidate: WorkflowUiSnapshot | undefined;
+
+  constructor(
+    private readonly events: EventBus,
+    private readonly isCurrent: () => boolean,
+    private readonly changed: () => void,
+    private readonly retiredSurfaces: Set<string> = new Set(),
+  ) {
+    this.unsubscribe = events.on(WORKFLOW_UI_CHANNELS.changed, raw => this.accept(raw));
+    this.query();
+  }
+
+  /** Keep expired terminal identities in the bounded snapshot so repeated ticks cannot relinger them. */
+  runs(retainedRunIds: ReadonlySet<string>, now = Date.now()): WorkflowUiRunSummary[] {
+    if (!this.live()) return [];
+    return (this.snapshot?.runs ?? []).filter(run => !isWorkflowTerminal(run) || retainedRunIds.has(run.runId) ||
+      now - (this.finishedAt.get(run.runId) ?? now) < WORKFLOW_FINISHED_LINGER_MS);
+  }
+
+  async open(run: WorkflowUiRunSummary): Promise<void> {
+    if (!this.live() || this.snapshot?.surfaceId !== run.surfaceId || !this.snapshot.runs.some(item => item.runId === run.runId))
+      throw new Error("Workflow selection is no longer active.");
+    const reply = await this.request(WORKFLOW_UI_CHANNELS.open, { surfaceId: run.surfaceId, runId: run.runId });
+    if (!this.live() || this.snapshot?.surfaceId !== run.surfaceId || !reply || typeof reply !== "object" ||
+      Array.isArray(reply) || ![Object.prototype, null].includes(Object.getPrototypeOf(reply)) ||
+      Object.getOwnPropertyDescriptor(reply, "accepted")?.value !== true) throw new Error("Workflow inspector did not accept the selection.");
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.snapshot) this.retireSurface(this.snapshot.surfaceId);
+    this.unsubscribe();
+    for (const finish of [...this.requests]) finish(new Error("Workflow UI retired."));
+    this.snapshot = undefined;
+    this.candidate = undefined;
+    this.queryAgain = false;
+    this.finishedAt.clear();
+  }
+
+  private live(): boolean { return !this.disposed && this.isCurrent(); }
+
+  private accept(raw: unknown): void {
+    if (!this.live()) return;
+    let snapshot: WorkflowUiSnapshot;
+    try { snapshot = parseWorkflowUiSnapshot(raw); } catch { return; }
+    if (this.retiredSurfaces.has(snapshot.surfaceId)) return;
+    // Once a replacement follows an empty retirement, late old-source frames
+    // cannot cancel its pending ownership check. Ordinary same-source updates
+    // (including an initially empty active peer) still work without a query.
+    if (this.candidate && this.snapshot?.runs.length === 0 && this.snapshot.surfaceId === snapshot.surfaceId) return;
+    this.revision++;
+    if (this.snapshot && this.snapshot.surfaceId !== snapshot.surfaceId) {
+      // An empty retirement can arrive before the replacement's publication.
+      // Only the active peer's query responder can authorize a new source.
+      this.candidate = snapshot;
+      this.query();
+      return;
+    }
+    this.candidate = undefined;
+    this.apply(snapshot);
+  }
+
+  private retireSurface(surfaceId: string): void {
+    this.retiredSurfaces.add(surfaceId);
+    if (this.retiredSurfaces.size > 256) this.retiredSurfaces.delete(this.retiredSurfaces.values().next().value!);
+  }
+
+  private query(): void {
+    if (!this.live()) return;
+    if (this.querying) {
+      // Coalesce same-source revisions; a query sent before a new publication
+      // cannot verify that source, so schedule one fresh event-triggered query.
+      if (this.candidate?.surfaceId !== this.queryingSurface) this.queryAgain = true;
+      return;
+    }
+    this.querying = true;
+    const revision = this.revision;
+    const surfaceId = this.candidate?.surfaceId;
+    this.queryingSurface = surfaceId;
+    void this.request(WORKFLOW_UI_CHANNELS.query, {}).then(raw => {
+      if (!this.live()) return;
+      let snapshot: WorkflowUiSnapshot;
+      try { snapshot = parseWorkflowUiSnapshot(raw); } catch { return; }
+      if (this.retiredSurfaces.has(snapshot.surfaceId)) return;
+      if (surfaceId) {
+        if (this.candidate?.surfaceId !== surfaceId) return;
+        if (snapshot.surfaceId !== surfaceId) {
+          // A valid ownership reply rejects only the candidate it queried.
+          // Release the empty-peer guard without retiring the active source.
+          this.candidate = undefined;
+          this.queryAgain = false;
+          return;
+        }
+        if (this.snapshot) this.retireSurface(this.snapshot.surfaceId);
+        // The reply verifies ownership, not freshness. Later publications win.
+        const latest = this.candidate;
+        this.candidate = undefined;
+        this.apply(latest);
+      } else if (revision === this.revision) this.accept(snapshot);
+    }, () => {}).finally(() => {
+      this.querying = false;
+      this.queryingSurface = undefined;
+      const again = this.queryAgain;
+      this.queryAgain = false;
+      if (again && this.candidate && this.live()) this.query();
+    });
+  }
+
+  private apply(snapshot: WorkflowUiSnapshot): void {
+    const old = this.snapshot?.surfaceId === snapshot.surfaceId ? this.finishedAt : new Map<string, number>();
+    const next = new Map<string, number>();
+    for (const run of snapshot.runs) if (isWorkflowTerminal(run)) next.set(run.runId, old.get(run.runId) ?? Date.now());
+    this.finishedAt.clear();
+    for (const [id, time] of next) this.finishedAt.set(id, time);
+    this.snapshot = snapshot;
+    this.changed();
+  }
+
+  private request(channel: string, payload: Record<string, string>): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let unsubscribe = () => {};
+      const finish = (error?: Error, data?: unknown): void => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        unsubscribe();
+        this.requests.delete(finish);
+        if (error) reject(error); else resolve(data);
+      };
+      this.requests.add(finish);
+      if (!this.live()) { finish(new Error("Workflow UI retired.")); return; }
+      const requestId = randomUUID();
+      try {
+        unsubscribe = this.events.on(replyChannel(channel, requestId), raw => {
+          if (!this.live()) { finish(new Error("Workflow UI retired.")); return; }
+          try { finish(undefined, replyData(raw)); }
+          catch (error) { finish(error instanceof Error ? error : new Error("Invalid workflow UI reply.")); }
+        });
+        timer = setTimeout(() => finish(new Error("Workflow UI unavailable; retained children remain inspectable.")), TIMEOUT_MS);
+        this.events.emit(channel, { requestId, ...payload });
+      } catch { finish(new Error("Workflow UI unavailable.")); }
+    });
+  }
+}