@signalridge/pi-subagents 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.8.0
+### Minor Changes
+
+- 3c6a02e: Improve the subagent conversation viewer with a full Pi-style box border, upstream-aligned layout, and height-safe chat controls. Running agents can chat in the viewer, while `steer_subagent` and `@handle message` queue messages safely for queued runs; `/agents` can stop a queued run before it has a session, and cancelled queued resumes no longer leak messages or transcript subscriptions into later resumes.
+
 ## 1.7.0
 ### Minor Changes
 

package/README.md

@@ -11,10 +11,10 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
 - **Live FleetView UI** — one navigable list below the editor with a status mark per row, live tool activity, token counts, and text status labels. Enter opens the selected agent's conversation. Toggle via `/agents → Settings → Fleet view`
 - **FleetView** — Claude Code-style navigable list of `main` + every running subagent rendered below the editor (earliest-launched first). Press `↓` (or `←`) at an empty prompt to jump in, `↑`/`↓` to move the selection, `Enter` to open the selected agent's live, auto-updating conversation, `Esc` to return. Finished agents linger briefly before dropping out, and a viewer stays open through completion so you can read the final output. Toggle via `/agents → Settings → Fleet view`
-- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). Steer a running agent inline by pressing `Enter` to open a composer, typing, then `Enter` to send (`Esc` or an empty submit returns) — the message appears as a user message and redirects the agent after its current tool. Stop a still-running agent by pressing `x` (then `x` again to confirm) — both work for background agents too
+- **Conversation viewer** — select any retained agent with a session in `/agents` to open a live-scrolling, four-sided bordered overlay of its full conversation (auto-follows new content, scroll up to pause). Press `Enter` to chat: type a message, then `Enter` to send (`Esc` or an empty submit returns); it appears as a user message and redirects the agent after its current tool. Press `x` (then `x` again to confirm) to stop a running agent — this works for background agents too
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` or `.agents/agents/<name>.md` (project) or globally, with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Nested subagents** — opt-in, default-off delegation: a custom agent that sets `allowed_subagents` gets its own ownership-scoped `Agent`, `get_subagent_result`, and `steer_subagent` tools, depth-capped from the main session (default 2). It can control only its own children, they are stopped when it finishes, and their transcripts and token spend roll up to it. The allowlist is a privilege boundary — a child runs with its own tools, so pick it as carefully as `tools:` itself
-- **Mid-run steering** — inject messages into running agents to redirect their work without restarting
+- **Mid-run chat** — inject messages into running or queued agents to redirect their work without restarting. From the main prompt, use `@handle message` (with `@` autocomplete); configure this under `/agents → Settings → Agent mentions`.
 - **Session resume** — pick up where an agent left off, preserving full conversation context
 - **Graceful turn limits** — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
 - **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. Unknown types fall back to general-purpose with a note
@@ -135,7 +135,7 @@ The mark is a geometric shape rather than an emoji on purpose: an emoji invites
 font fallback, and a fallback glyph is usually double-width, which would push
 the rest of the row out of alignment on some terminals and not others.
 
-The list is ordered earliest-launched first, and only shows agents you can actually open (pending/queued agents with no session yet appear once they start). At an **empty prompt**, press down or left to move focus from the prompt into the list. Up and down move the selection, Enter opens the selected agent's live conversation overlay (it auto-updates as the agent works), and Esc (or up above `main`) returns to the prompt. Selecting `main` returns to the normal view. Inside the overlay, press Enter to steer the running agent — type a message and Enter to send it (Esc or an empty submit returns), and it redirects the agent the same way the `steer_subagent` tool does. A viewer stays open when its agent finishes so you can read the final output, and finished agents linger in the list for a few seconds before dropping out. Typing anything at a non-empty prompt behaves normally — the list only captures navigation keys when the prompt is empty. Disable it entirely via `/agents → Settings → Fleet view`.
+The list is ordered earliest-launched first, and only shows agents you can actually open (pending/queued agents with no session yet appear once they start). At an **empty prompt**, press down or left to move focus from the prompt into the list. Up and down move the selection, Enter opens the selected agent's live conversation overlay (it auto-updates as the agent works), and Esc (or up above `main`) returns to the prompt. Selecting `main` returns to the normal view. The conversation overlay uses a complete `╭─╮` / `│` / `╰─╯` border. Press Enter to chat with a running agent — type a message and Enter to send it (Esc or an empty submit returns). For a queued agent that has no session yet, type `@handle message` in the main prompt; the message is delivered when it starts. Press `x` twice to stop a running agent. A viewer stays open when its agent finishes so you can read the final output, and finished agents linger in the list for a few seconds before dropping out. Typing anything at a non-empty prompt behaves normally — the list only captures navigation keys when the prompt is empty. Disable it entirely via `/agents → Settings → Fleet view`.
 
 Individual agent results use restrained text status labels:
 
@@ -341,7 +341,7 @@ Cancelling a `wait: true` call (for example, with `Esc`) stops only the wait. Th
 
 ### `steer_subagent`
 
-Send a steering message to a running agent. The message interrupts after the current tool execution.
+Send a chat message to a running or queued agent. A running agent receives it after the current tool execution; a queued agent receives it when its session starts.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -364,7 +364,7 @@ Create new agent
 Settings
 ```
 
-- **Agent runs** — select any retained run to open its conversation viewer. The summary reports running, queued, completed, wrapped up, stopped, aborted, and failed buckets separately. While a run is still active, press Enter to open the steering composer, then Enter again to send a message that redirects the agent (same mechanism as the `steer_subagent` tool; Esc or an empty submit returns), or press `x` (then `x` again to confirm) to stop/abort it — including **background** agents, which a global Esc can't unambiguously target (Esc still stops a blocking foreground `Agent` call). A stopped agent reports its partial output flagged as incomplete, not as a completion.
+- **Agent runs** — select any retained run with a session to open its conversation viewer. Queued runs without a session remain listed but are not openable until they start; selecting one offers a stop confirmation, and `@handle message` queues a chat message. The summary reports running, queued, completed, wrapped up, stopped, aborted, and failed buckets separately. While a run is still active, press Enter to open the chat composer, then Enter again to send a message that redirects the agent (same mechanism as the `steer_subagent` tool; Esc or an empty submit returns), or press `x` (then `x` again to confirm) to stop/abort it — including **background** agents, which a global Esc can't unambiguously target (Esc still stops a blocking foreground `Agent` call). A stopped agent reports its partial output flagged as incomplete, not as a completion.
 - **Agent types** — unified list with textual source labels (`project`, `global`, and `disabled`). Each row shows the agent's model, and the highlighted agent's full description appears below the list. The model column flags `(unavailable, fallback: inherit)` when a configured model can't be resolved (it would silently inherit the parent model), and shows `(resolved: provider/id)` when it resolves to a different provider or version than configured. Select an agent to manage it:
   - **Default agents** (no override): Eject (export as `.md`), Disable
   - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete

package/examples/agent-tool-description.md

@@ -20,7 +20,7 @@ If the target is already known, use a direct tool — `read` for a known path, `
 - Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
 - Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
-- Use steer_subagent to send mid-run messages to a running background agent.
+- Use steer_subagent to send mid-run messages to a running or queued background agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
 - Use tier to pick the model profile for this spawn, by name. A tier overrides the agent's own default tier. Model and thinking are not callable parameters — they are what a tier resolves to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",

package/src/agent-manager.ts

@@ -2193,6 +2193,8 @@ export class AgentManager {
       onToolActivity?: (activity: { type: "start" | "end"; toolName: string }) => void;
       onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
       onCompaction?: (info: unknown) => void;
+      /** Called once a queued background resume has acquired its run slot. */
+      onStarted?: () => void;
     },
   ): Promise<AgentRecord | undefined> {
     if (this.disposed) return undefined;
@@ -2311,6 +2313,8 @@ export class AgentManager {
       onToolActivity?: (activity: { type: "start" | "end"; toolName: string }) => void;
       onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
       onCompaction?: (info: unknown) => void;
+      /** Called once a queued background resume has acquired its run slot. */
+      onStarted?: () => void;
     },
   ): Promise<string> {
     const snapshot = control.snapshot;
@@ -2340,6 +2344,28 @@ export class AgentManager {
       record.result = undefined;
       record.error = undefined;
       this.syncManagedRecord(record);
+      try {
+        options?.onStarted?.();
+      } catch {
+        // Observability hooks must not prevent the resumed agent from running.
+      }
+
+      // A queued background resume reuses an existing session, so messages
+      // sent while it waits must be flushed here rather than through the
+      // session's idle steering queue. Otherwise cancelling this queued run
+      // would leave those messages behind for a later resume.
+      const pendingSteers = record.pendingSteers;
+      record.pendingSteers = undefined;
+      if (pendingSteers?.length) {
+        for (const message of pendingSteers) {
+          if (control.controller.signal.aborted) break;
+          try {
+            await record.session!.steer(message);
+          } catch {
+            // A malformed or stale queued message must not prevent the resume.
+          }
+        }
+      }
 
       try {
         const { text, failure } = await resumeAgent(record.session!, prompt, {
@@ -2397,21 +2423,25 @@ export class AgentManager {
 
   /**
    * Send a steering message to an agent from the UI (mirrors the steer_subagent
-   * tool). A live session delivers it now — it interrupts the agent after its
-   * current tool execution and appears as a user message. If the session isn't
-   * ready yet, the message is queued on `pendingSteers` and flushed when the
-   * session is created. Returns false if the agent can't accept steering
-   * (unknown id, or no longer running/queued).
+   * tool). A running session delivers it now — it interrupts the agent after
+   * its current tool execution and appears as a user message. Queued runs keep
+   * it on `pendingSteers` until their run actually starts, including background
+   * resumes that already have an old session attached. Returns false if the
+   * agent can't accept steering (unknown id, or no longer running/queued).
    */
   steer(id: string, message: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
     if (record.status !== "running" && record.status !== "queued") return false;
-    if (record.session) {
-      record.session.steer(message).catch(() => {});
-    } else {
+    // A queued background resume already has its old session attached. Keep
+    // messages in the manager until that resume actually starts; putting them
+    // into AgentSession's idle queue would survive cancellation into a future
+    // resume of the same conversation.
+    if (record.status === "queued" || !record.session) {
       if (!record.pendingSteers) record.pendingSteers = [];
       record.pendingSteers.push(message);
+    } else {
+      record.session.steer(message).catch(() => {});
     }
     return true;
   }
@@ -2461,6 +2491,9 @@ export class AgentManager {
       resumeControl?.controller.abort();
       resumeControl?.cleanup();
       resumeControl?.deferred?.resolve("");
+      // Do not let chat messages queued for a cancelled queued run leak into
+      // the session when the same agent is resumed later.
+      record.pendingSteers = undefined;
       this.syncManagedRecord(record);
       // Queued agents have no run promise yet. Still use the normal terminal
       // callback so lifecycle consumers (including workflow waits) cannot hang.

package/src/index.ts

@@ -4,7 +4,7 @@
  * Tools:
  *   Agent             — LLM-callable: spawn a sub-agent
  *   get_subagent_result  — LLM-callable: check background agent status/result
- *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *   steer_subagent       — LLM-callable: chat with a running or queued agent
  *
  * Commands:
  *   /agents                 — Interactive agent management menu
@@ -2168,7 +2168,7 @@ Notes:
 - description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
 - Parallel work: one message, multiple Agent calls, run_in_background: true on each. You are notified when background agents finish — never poll or sleep.
 - The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
-- resume continues a previous agent by ID; steer_subagent messages a running one.
+- resume continues a previous agent by ID; steer_subagent messages a running or queued one.
 - isolation: "worktree" runs the agent in an isolated git worktree; changes land on a branch.`;
 
   const fullAgentToolDescription = `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
@@ -2193,7 +2193,7 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 - Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
 - Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
-- Use steer_subagent to send mid-run messages to a running background agent.
+- Use steer_subagent to send mid-run messages to a running or queued background agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
 - Use tier to pick the model profile for this spawn, by name. A tier overrides the agent's own default tier. Model and thinking are not callable parameters — they are what a tier resolves to.
@@ -2758,6 +2758,16 @@ Terse command-style prompts produce shallow, generic work.
             // run starts. The resumed prompt lands as an ordinary user message at
             // this index, so it is written exactly once.
             const transcriptAnchor = existing.session.messages.length ?? 0;
+            const attachTranscript = (): void => {
+              if (!existing.outputFile || existing.outputCleanup) return;
+              existing.outputCleanup = streamToOutputFile(
+                existing.session!,
+                existing.outputFile,
+                params.resume!,
+                ctx.cwd,
+                transcriptAnchor,
+              );
+            };
             const record = await manager.resume(
               params.resume,
               params.prompt,
@@ -2766,6 +2776,7 @@ Terse command-style prompts produce shallow, generic work.
                 isBackground: true,
                 onToolActivity: bgCallbacks.onToolActivity,
                 onAssistantUsage: bgCallbacks.onAssistantUsage,
+                onStarted: attachTranscript,
               },
             );
             if (!record) {
@@ -2774,17 +2785,6 @@ Terse command-style prompts produce shallow, generic work.
                   "Wait for it to settle, or steer it with steer_subagent.",
               );
             }
-            // Wire streaming once the run actually starts (immediately, or on
-            // queue drain).
-            if (existing.outputFile) {
-              existing.outputCleanup = streamToOutputFile(
-                existing.session,
-                existing.outputFile,
-                params.resume,
-                ctx.cwd,
-                transcriptAnchor,
-              );
-            }
             agentActivity.set(params.resume, bgState);
             void bgCallbacks;
             return textResult(
@@ -3128,6 +3128,9 @@ Terse command-style prompts produce shallow, generic work.
         if (record.status === "running") {
           output +=
             "Agent is still running. Use wait: true or check back later.";
+        } else if (record.status === "queued") {
+          output +=
+            "Agent is queued and has not started yet. Use wait: true or check back later.";
         } else if (record.status === "error") {
           output += `Error: ${record.error}${partialOutputSuffix(record)}`;
         } else {
@@ -3158,19 +3161,19 @@ Terse command-style prompts produce shallow, generic work.
   pi.registerTool(
     defineTool({
       name: SUBAGENT_TOOL_NAMES.STEER,
-      label: "Steer Agent",
+      label: "Chat with Agent",
       description:
-        "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
-        "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
+        "Send a chat message to a running or queued agent. A running agent receives it after its current tool execution; " +
+        "a queued agent receives it when its session starts. The message is injected into the agent's conversation.",
       promptSnippet:
-        "Send a steering message to redirect a running background agent",
+        "Chat with or redirect a running or queued background agent",
       parameters: Type.Object({
         agent_id: Type.String({
-          description: "The agent ID to steer (must be currently running).",
+          description: "The agent ID to message (must be currently running or queued).",
         }),
         message: Type.String({
           description:
-            "The steering message to send. This will appear as a user message in the agent's conversation.",
+            "The chat message to send. This will appear as a user message in the agent's conversation.",
         }),
       }),
       execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
@@ -3180,13 +3183,16 @@ Terse command-style prompts produce shallow, generic work.
             `Agent not found: "${params.agent_id}". It may have been cleaned up.`,
           );
         }
-        if (record.status !== "running") {
+        if (record.status !== "running" && record.status !== "queued") {
           return textResult(
-            `Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
+            `Agent "${params.agent_id}" is not running or queued (status: ${record.status}). Cannot send a chat message.`,
           );
         }
-        if (!record.session) {
-          // Session not ready yet — queue the steer for delivery once initialized
+        if (record.status === "queued" || !record.session) {
+          // Keep queued messages in the manager record until the run starts.
+          // This also covers a queued background resume whose old session is
+          // already attached; sending directly to that session would survive
+          // cancellation into a later resume.
           if (!record.pendingSteers) record.pendingSteers = [];
           record.pendingSteers.push(params.message);
           if (!record.detached)
@@ -3194,8 +3200,9 @@ Terse command-style prompts produce shallow, generic work.
               id: record.id,
               message: params.message,
             });
+          const delivery = record.status === "queued" ? "when the agent starts" : "once the session initializes";
           return textResult(
-            `Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+            `Chat message queued for agent ${record.id}. It will be delivered ${delivery}.`,
           );
         }
 
@@ -3220,7 +3227,7 @@ Terse command-style prompts produce shallow, generic work.
               `${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`,
             );
           return textResult(
-            `Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+            `Chat message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
               `Current state: ${stateParts.join(" · ")}`,
           );
         } catch (err) {
@@ -3492,10 +3499,20 @@ Terse command-style prompts produce shallow, generic work.
     record: AgentRecord,
   ) {
     if (!record.session) {
-      ctx.ui.notify(
-        `Agent is ${record.status === "queued" ? "queued" : "expired"}; no session available.`,
-        "info",
-      );
+      if (record.status === "queued") {
+        const handleHint = record.handle
+          ? ` Use @${record.handle} <message> to chat while it waits.`
+          : " Use steer_subagent or wait until it starts to chat.";
+        const stop = await ctx.ui.confirm(
+          "Queued agent",
+          `"${sanitizeDisplayText(record.description)}" has not started yet.${handleHint}\n\nStop this queued run?`,
+        );
+        if (stop && manager.abort(record.id)) {
+          ctx.ui.notify(`Stopped queued agent "${sanitizeDisplayText(record.description)}".`, "info");
+        }
+        return;
+      }
+      ctx.ui.notify("Agent is expired; no session available.", "info");
       return;
     }
 

package/src/nested-tools.ts

@@ -389,30 +389,32 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
 
   const steerTool = defineTool({
     name: NESTED_TOOL_NAMES[2],
-    label: "Steer Nested Agent",
-    description: "Send guidance to a running nested agent owned by this parent.",
+    label: "Chat with Nested Agent",
+    description: "Send guidance to a running or queued nested agent owned by this parent.",
     parameters: Type.Object({
       agent_id: Type.String(),
       message: Type.String(),
     }),
     execute: async (_toolCallId, params) => {
       const record = lookupRecord(context, params.agent_id);
-      if (!ownsRecord(record, context.parentAgentId) || record.status !== "running") {
-        return textResult(`Running nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+      if (!ownsRecord(record, context.parentAgentId) ||
+        (record.status !== "running" && record.status !== "queued")) {
+        return textResult(`Running or queued nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
       }
-      // Session not ready yet — queue the steer. The manager flushes pending
-      // steers when the session is created (same contract as the top-level tool).
-      if (!record.session) {
+      // Queue chat for any queued run, even when a background resume already
+      // has its old session attached. The manager flushes it only when the run
+      // actually starts, so cancellation cannot leak it into a later resume.
+      if (record.status === "queued" || !record.session) {
         if (!record.pendingSteers) record.pendingSteers = [];
         record.pendingSteers.push(params.message);
-        return textResult(`Steering message queued for nested agent ${params.agent_id}.`);
+        return textResult(`Chat message queued for nested agent ${params.agent_id}.`);
       }
       try {
         await record.session.steer(params.message);
       } catch (err) {
         return textResult(`Failed to steer nested agent: ${err instanceof Error ? err.message : String(err)}`, true);
       }
-      return textResult(`Steering message sent to nested agent ${params.agent_id}.`);
+      return textResult(`Chat message sent to nested agent ${params.agent_id}.`);
     },
   });
 

package/src/ui/conversation-viewer.ts

@@ -17,9 +17,9 @@ import { PREVIEW_SCAN_LIMIT, safeTerminalText, sanitizeDisplayText, truncateCode
 import { getAgentStatusColor, getAgentStatusLabel, getAgentStatusMark } from "./status-label.js";
 import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
 
-/** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
+/** Base lines consumed by chrome: top border + header + two separators + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
-const MIN_VIEWPORT = 3;
+const MIN_VIEWPORT = 1;
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export const VIEWPORT_HEIGHT_PCT = 70;
 
@@ -165,8 +165,14 @@ export class ConversationViewer implements Component {
   render(width: number): string[] {
     if (width < 6) return [];
     this.refreshRecord();
+    // A custom overlay is clipped by pi after rendering. At very low heights
+    // there is no room for the complete header/footer chrome, so render nothing
+    // rather than showing a misleading half-box with a missing bottom border.
+    if (this.maxOverlayRows() < this.chromeLines() + MIN_VIEWPORT) return [];
     const th = this.theme;
-    const innerW = width - 2;
+    // Match pi's overlay style: a complete box with two columns reserved for
+    // the side borders and one padding column on each side of the content.
+    const innerW = width - 4;
     this.lastInnerW = innerW;
     const lines: string[] = [];
 
@@ -176,18 +182,20 @@ export class ConversationViewer implements Component {
     };
     const row = (content: string) => {
       const fitted = truncateToWidth(pad(content, innerW), innerW, "...", true);
-      return ` ${fitted} `;
+      return `${th.fg("borderAccent", "│")} ${fitted} ${th.fg("borderAccent", "│")}`;
     };
-    // Two full-width rules, top and bottom, and none in between. The overlay
-    // floats over the transcript, so without them there is no telling where the
-    // agent's conversation ends and the parent's resumes. An inner rule would be
-    // a third horizontal line competing with the two that mark the boundary, and
-    // a four-sided box would cost two columns on every row for the same job.
-    const rule = () => th.fg("borderAccent", "─".repeat(Math.max(0, width)));
-    const hrMid = row("");
-
-    lines.push(rule());
-    lines.push(row(th.bold("Agent conversation")));
+    // Keep the border in the viewer rather than relying on the host overlay's
+    // transparent background. This makes the dialog boundary obvious and
+    // matches the reference pi-subagents viewer (╭─╮ / │ / ╰─╯).
+    const rule = (left: string, right: string) =>
+      th.fg("borderAccent", `${left}${"─".repeat(Math.max(0, width - 2))}${right}`);
+    const topRule = rule("╭", "╮");
+    const bottomRule = rule("╰", "╯");
+    // Match the reference viewer's internal separator: it keeps the header,
+    // transcript, and controls visually distinct without adding another row.
+    const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+    lines.push(topRule);
     const name = renderAgentName(this.record.type, th, { bold: true });
     const modeLabel = getPromptModeLabel(this.record.type);
     const modeTag = modeLabel ? th.fg("dim", `mode ${modeLabel}`) : undefined;
@@ -238,13 +246,13 @@ export class ConversationViewer implements Component {
       const composerLine = renderedComposer.startsWith("> ") ? renderedComposer.slice(2) : renderedComposer;
       lines.push(row(composerLine));
       const composeHint = th.fg("dim", "Enter send · Esc cancel");
-      const composeLeft = th.fg("accent", "steer");
+      const composeLeft = th.fg("accent", "chat");
       const composeGap = Math.max(1, innerW - visibleWidth(composeLeft) - visibleWidth(composeHint));
       lines.push(row(composeLeft + " ".repeat(composeGap) + composeHint));
     } else {
       const sep = th.fg("dim", " · ");
       const actions: string[] = [];
-      if (this.canSteer()) actions.push(th.fg("dim", "Enter steer"));
+      if (this.canSteer()) actions.push(th.fg("dim", "Enter chat"));
       if (this.isStoppable()) {
         actions.push(this.stopArmed ? th.fg("error", "x again to STOP") : th.fg("dim", "x stop"));
       }
@@ -262,7 +270,7 @@ export class ConversationViewer implements Component {
       const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
       lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
     }
-    lines.push(rule());
+    lines.push(bottomRule);
 
     return lines;
   }
@@ -309,11 +317,14 @@ export class ConversationViewer implements Component {
 
   // ---- Private ----
 
+  private maxOverlayRows(): number {
+    return Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+  }
+
   private viewportHeight(): number {
     // Cap mirrors the overlay's maxHeight — otherwise the viewer would render
     // more lines than the overlay shows and clip the footer.
-    const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
-    return Math.max(MIN_VIEWPORT, maxRows - this.chromeLines());
+    return Math.max(MIN_VIEWPORT, this.maxOverlayRows() - this.chromeLines());
   }
 
   private chromeLines(): number {