@gotgenes/pi-subagents 13.0.0 → 13.2.0

package/src/lifecycle/subagent-session.ts

@@ -0,0 +1,234 @@
+/**
+ * subagent-session.ts — The born-complete child-session value object (issue #265).
+ *
+ * A SubagentSession wraps one SDK AgentSession plus its turn-driving and teardown.
+ * It is born complete: `createSubagentSession()` returns a fully usable instance
+ * (session created, extensions bound, recursion guard applied), so the only thing
+ * left for `Agent` to do is coordinate — drive the turn loop, steer, dispose.
+ *
+ * Turn driving lives here, on the object that owns the AgentSession, rather than
+ * reaching through `subagentSession.session` from `Agent` (Law of Demeter).
+ */
+
+import {
+  type AgentSession,
+  type AgentSessionEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
+import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
+import { getSessionContextPercent, type SessionStatsLike } from "#src/lifecycle/usage";
+import { extractText } from "#src/session/context";
+import { getAgentConversation } from "#src/session/conversation";
+
+/** Outcome of one turn loop. */
+export interface TurnLoopResult {
+  responseText: string;
+  /** True if the agent was hard-aborted (max turns + grace exceeded). */
+  aborted: boolean;
+  /** True if the agent was steered to wrap up (soft turn limit) but finished in time. */
+  steered: boolean;
+}
+
+/** Per-call options for the initial run's turn loop. */
+export interface TurnLoopOptions {
+  /** Per-call max-turns override — highest precedence. */
+  maxTurns?: number;
+  /** Runtime-config fallback when neither per-call nor per-agent limit is set. */
+  defaultMaxTurns?: number;
+  /** Grace turns after the soft-limit steer message before a hard abort. */
+  graceTurns?: number;
+  signal?: AbortSignal;
+}
+
+/** Session-level facts known at creation, supplied by the factory. */
+export interface SubagentSessionMeta {
+  /** Path to the persisted session JSONL file, if the session was persisted. */
+  outputFile: string | undefined;
+  /** Child session directory — the registry key carried on lifecycle events. */
+  sessionDir: string;
+  agentName: string;
+  /** Per-agent max-turns from the resolved agent config — middle precedence. */
+  agentMaxTurns: number | undefined;
+  /** Parent context prepended to the run prompt, captured at spawn time. */
+  parentContext: string | undefined;
+  lifecycle: ChildLifecyclePublisher;
+}
+
+/**
+ * One child AgentSession plus its turn-driving and teardown — born complete.
+ */
+export class SubagentSession {
+  constructor(
+    private readonly _session: AgentSession,
+    private readonly meta: SubagentSessionMeta,
+  ) {}
+
+  /**
+   * Wrapped session — for lifecycle-internal use only.
+   * @internal consumers outside lifecycle/ use the delegate methods below.
+   */
+  get session(): AgentSession {
+    return this._session;
+  }
+
+  get outputFile(): string | undefined {
+    return this.meta.outputFile;
+  }
+
+  /** Drive the initial run's turn loop; emits `completed` on success. */
+  async runTurnLoop(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult> {
+    const session = this._session;
+
+    // Track turns for graceful max_turns enforcement.
+    let turnCount = 0;
+    const maxTurns = normalizeMaxTurns(
+      opts.maxTurns ?? this.meta.agentMaxTurns ?? opts.defaultMaxTurns,
+    );
+    let softLimitReached = false;
+    let aborted = false;
+
+    const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
+      if (event.type === "turn_end") {
+        turnCount++;
+        if (maxTurns != null) {
+          if (!softLimitReached && turnCount >= maxTurns) {
+            softLimitReached = true;
+            void session.steer(
+              "You have reached your turn limit. Wrap up immediately - provide your final answer now.",
+            );
+          } else if (softLimitReached && turnCount >= maxTurns + (opts.graceTurns ?? 5)) {
+            aborted = true;
+            void session.abort();
+          }
+        }
+      }
+    });
+
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, opts.signal);
+
+    // Prepend parent context if it was captured at spawn time.
+    const effectivePrompt = this.meta.parentContext
+      ? this.meta.parentContext + prompt
+      : prompt;
+
+    try {
+      await session.prompt(effectivePrompt);
+      this.meta.lifecycle.completed({
+        sessionDir: this.meta.sessionDir,
+        agentName: this.meta.agentName,
+        aborted,
+        steered: softLimitReached,
+      });
+    } finally {
+      unsubTurns();
+      collector.unsubscribe();
+      cleanupAbort();
+    }
+
+    const responseText = collector.getText().trim() || getLastAssistantText(session);
+    return { responseText, aborted, steered: softLimitReached };
+  }
+
+  /** Re-prompt the same session (resume); does not emit `completed`. */
+  async resumeTurnLoop(prompt: string, signal?: AbortSignal): Promise<string> {
+    const session = this._session;
+    const collector = collectResponseText(session);
+    const cleanupAbort = forwardAbortSignal(session, signal);
+
+    try {
+      await session.prompt(prompt);
+    } finally {
+      collector.unsubscribe();
+      cleanupAbort();
+    }
+
+    return collector.getText().trim() || getLastAssistantText(session);
+  }
+
+  /** Deliver a steer to the live session. */
+  async steer(message: string): Promise<void> {
+    await this._session.steer(message);
+  }
+
+  /** Return the session's conversation as formatted text. */
+  getConversation(): string {
+    return getAgentConversation(this._session);
+  }
+
+  /** Return the session context window utilization (0-100), or null when unavailable. */
+  getContextPercent(): number | null {
+    return getSessionContextPercent(this._session);
+  }
+
+  /** Subscribe to session events. Satisfies `SubscribableSession`. */
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void {
+    return this._session.subscribe(fn);
+  }
+
+  /** Return session token statistics. Satisfies `SessionLike`. */
+  getSessionStats(): SessionStatsLike {
+    return this._session.getSessionStats();
+  }
+
+  /** The session's message history. */
+  get messages(): readonly unknown[] {
+    return this._session.messages as readonly unknown[];
+  }
+
+  /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
+  dispose(): void {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
+    this._session.dispose?.();
+    this.meta.lifecycle.disposed({ sessionDir: this.meta.sessionDir });
+  }
+}
+
+// ── Private turn-loop helpers ───────────────────────────────────────────────────
+
+/**
+ * Subscribe to a session and collect the last assistant message text.
+ * Returns an object with a `getText()` getter and an `unsubscribe` function.
+ */
+function collectResponseText(session: AgentSession) {
+  let text = "";
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "message_start") {
+      text = "";
+    }
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      text += event.assistantMessageEvent.delta;
+    }
+  });
+  return { getText: () => text, unsubscribe };
+}
+
+/** Get the last assistant text from the completed session history. */
+function getLastAssistantText(session: AgentSession): string {
+  for (let i = session.messages.length - 1; i >= 0; i--) {
+    const msg = session.messages[i];
+    if (msg.role !== "assistant") continue;
+    const text = extractText(msg.content).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * Wire an AbortSignal to abort a session.
+ * Returns a cleanup function to remove the listener.
+ */
+function forwardAbortSignal(
+  session: AgentSession,
+  signal?: AbortSignal,
+): () => void {
+  if (!signal) return () => {};
+  const onAbort = (): void => {
+    void session.abort();
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}

package/src/lifecycle/turn-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * turn-limits.ts — Pure turn-limit normalization for subagent execution.
+ *
+ * Extracted from agent-runner.ts (issue #265) so the turn-counting policy has a
+ * focused home independent of session assembly. Consumed by the Agent tool's
+ * spawn-config resolution and by the turn loop in SubagentSession.
+ */
+
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export function normalizeMaxTurns(n: number | undefined): number | undefined {
+  if (n == null || n === 0) return undefined;
+  return Math.max(1, n);
+}

package/src/observation/notification.ts

@@ -1,5 +1,5 @@
 import { debugLog } from "#src/debug";
-import { getLifetimeTotal, getSessionContextPercent } from "#src/lifecycle/usage";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { Agent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
@@ -46,7 +46,7 @@ export function formatTaskNotification(record: Agent, resultMaxLen: number): str
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.session);
+  const contextPercent = record.getContextPercent();
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 

package/src/runtime.ts

@@ -25,7 +25,7 @@ export interface WidgetLike {
 }
 
 /**
- * Narrow config subset read by AgentManager when constructing RunOptions execution fields.
+ * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
  * Kept separate so callers can satisfy it without depending on the full runtime.
  */
 export interface RunConfig {

package/src/service/service-adapter.ts

@@ -90,13 +90,7 @@ export class SubagentsServiceAdapter implements SubagentsService {
     if (record?.status !== "running") {
       return false;
     }
-    const session = record.session;
-    if (!session) {
-      // Session not ready yet — buffer on the agent for delivery once initialized
-      record.queueSteer(message);
-      return true;
-    }
-    await session.steer(message);
+    await record.steer(message);
     return true;
   }
 

package/src/session/conversation.ts

@@ -0,0 +1,49 @@
+/**
+ * conversation.ts — Render a subagent session's messages as formatted text.
+ *
+ * Extracted from agent-runner.ts (issue #265) into the session domain, where the
+ * other message-extraction helpers (content-items, context) live. Consumed by
+ * the get_subagent_result tool's verbose output.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { extractAssistantContent } from "#src/session/content-items";
+import { extractText } from "#src/session/context";
+
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session: AgentSession): string {
+  const parts: string[] = [];
+
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      const text =
+        typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+      if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+    } else if (msg.role === "assistant") {
+      const { textParts, toolNames } = extractAssistantContent(msg.content);
+      const attribution = formatAttribution(msg);
+      if (textParts.length > 0)
+        parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
+      if (toolNames.length > 0)
+        parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
+    } else if (msg.role === "toolResult") {
+      const text = extractText(msg.content);
+      const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+      parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+  const { provider, model } = msg;
+  if (!provider && !model) return "";
+  if (provider && model) return ` (${provider}/${model})`;
+  return ` (${provider ?? model})`;
+}

package/src/session/session-config.ts

@@ -1,10 +1,10 @@
 /**
  * session-config.ts — Pure configuration assembler for agent sessions.
  *
- * `assembleSessionConfig()` is the pure core extracted from `runAgent()`.
- * It accepts resolved inputs (agent type, narrow context, run options, env info)
- * and returns everything `runAgent()` needs to create the SDK session — without
- * importing or constructing any Pi SDK types.
+ * `assembleSessionConfig()` is the pure assembly core called by
+ * `createSubagentSession()`. It accepts resolved inputs (agent type, narrow
+ * context, run options, env info) and returns everything the factory needs to
+ * create the SDK session — without importing or constructing any Pi SDK types.
  *
  * The only async IO in the assembly phase (`detectEnv`) is handled by the caller
  * before invoking this function, keeping the assembler synchronous.
@@ -22,7 +22,7 @@ import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types"
  * Bundling the IO-touching (or promptly testable) function into a single
  * interface keeps the assembler free of direct module imports and makes it
  * trivially testable without `vi.mock()` — callers inject real implementations
- * at the edge (`agent-runner.ts`) or stubs in tests.
+ * at the edge (`create-subagent-session.ts`) or stubs in tests.
  */
 export interface AssemblerIO {
   buildAgentPrompt: (
@@ -57,7 +57,7 @@ export interface AssemblerContext {
 }
 
 /**
- * Narrow slice of RunOptions execution fields consumed by the assembler.
+ * Narrow slice of per-spawn execution fields consumed by the assembler.
  * All fields are optional — callers pass only what they have.
  */
 export interface AssemblerOptions {
@@ -70,7 +70,7 @@ export interface AssemblerOptions {
 }
 
 /**
- * Assembled configuration returned to `runAgent()`.
+ * Assembled configuration returned to `createSubagentSession()`.
  * Contains everything needed to create the SDK session and filter tools —
  * with no SDK object references.
  */
@@ -173,7 +173,7 @@ export function assembleSessionConfig(
   // Thinking level: explicit option > agent config > undefined (inherit)
   const thinkingLevel = options.thinkingLevel ?? agentConfig.thinking;
 
-  // Per-agent max turns (combined with options.maxTurns and defaultMaxTurns by runAgent)
+  // Per-agent max turns (combined with per-call maxTurns and defaultMaxTurns by SubagentSession.runTurnLoop)
   const agentMaxTurns = agentConfig.maxTurns;
 
   return {

package/src/settings.ts

@@ -8,7 +8,7 @@ export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
-   * `normalizeMaxTurns()` in agent-runner.ts treats 0 → `undefined`, and the
+   * `normalizeMaxTurns()` in turn-limits.ts treats 0 → `undefined`, and the
    * `/agents` → Settings input prompt explicitly says "0 = unlimited".
    */
   defaultMaxTurns?: number;

package/src/tools/agent-tool.ts

@@ -108,7 +108,7 @@ export class AgentTool {
 					`Agent not found: "${params.resume}". It may have been cleaned up.`,
 				);
 			}
-			if (!existing.session) {
+			if (!existing.isSessionReady()) {
 				return textResult(
 					`Agent "${params.resume}" has no active session to resume.`,
 				);

package/src/tools/background-spawner.ts

@@ -53,9 +53,10 @@ export function spawnBackground(
       isBackground: true,
       invocation: execution.agentInvocation,
       observer: {
-        onSessionCreated: (_agent, session) => {
-          bgState.setSession(session);
-          subscribeUIObserver(session, bgState);
+        onSessionCreated: (agent) => {
+          const sub = agent.subagentSession!;
+          bgState.setSession(sub);
+          subscribeUIObserver(sub, bgState);
         },
       },
     });

package/src/tools/foreground-runner.ts

@@ -108,10 +108,11 @@ export async function runForeground(
         signal,
         parentSession: params.parentSession,
         observer: {
-          onSessionCreated: (agent, session) => {
-            fgState.setSession(session);
+          onSessionCreated: (agent) => {
+            const sub = agent.subagentSession!;
+            fgState.setSession(sub);
             recordRef = agent;
-            unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+            unsubUI = subscribeUIObserver(sub, fgState, streamUpdate);
             fgId = agent.id;
             agentActivity.set(agent.id, fgState);
             widget.ensureTimer();

package/src/tools/get-result-tool.ts

@@ -1,8 +1,6 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import { getAgentConversation } from "#src/lifecycle/agent-runner";
-import { getSessionContextPercent } from "#src/lifecycle/usage";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import type { Agent } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";
@@ -53,7 +51,7 @@ export class GetResultTool {
 		const displayName = getDisplayName(record.type, this.registry);
 		const duration = formatDuration(record.startedAt, record.completedAt);
 		const tokens = formatLifetimeTokens(record);
-		const contextPercent = getSessionContextPercent(record.session);
+		const contextPercent = record.getContextPercent();
 		const statsParts = [`Tool uses: ${record.toolUses}`];
 		if (tokens) statsParts.push(tokens);
 		if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
@@ -80,11 +78,9 @@ export class GetResultTool {
 		}
 
 		// Verbose: include full conversation
-		if (params.verbose && record.session) {
-			const conversation = getAgentConversation(record.session);
-			if (conversation) {
-				output += `\n\n--- Agent Conversation ---\n${conversation}`;
-			}
+		const conversation = params.verbose ? record.getConversation() : undefined;
+		if (conversation) {
+			output += `\n\n--- Agent Conversation ---\n${conversation}`;
 		}
 
 		return textResult(output);

package/src/tools/spawn-config.ts

@@ -10,7 +10,7 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentTypeRegistry } from "#src/config/agent-types";
 import { resolveAgentInvocationConfig } from "#src/config/invocation-config";
-import { normalizeMaxTurns } from "#src/lifecycle/agent-runner";
+import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
 import { resolveInvocationModel } from "#src/session/model-resolver";
 import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
 import {

package/src/tools/steer-tool.ts

@@ -1,6 +1,5 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { getSessionContextPercent } from "#src/lifecycle/usage";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import type { Agent } from "#src/types";
 
@@ -40,21 +39,16 @@ export class SteerTool {
 				`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
 			);
 		}
-		const session = record.session;
-		if (!session) {
-			// Session not ready yet — buffer on the agent for delivery once initialized
-			record.queueSteer(params.message);
-			this.events.emit("subagents:steered", { id: record.id, message: params.message });
-			return textResult(
-				`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
-			);
-		}
-
 		try {
-			await session.steer(params.message);
+			const delivered = await record.steer(params.message);
 			this.events.emit("subagents:steered", { id: record.id, message: params.message });
+			if (!delivered) {
+				return textResult(
+					`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+				);
+			}
 			const tokens = formatLifetimeTokens(record);
-			const contextPercent = getSessionContextPercent(session);
+			const contextPercent = record.getContextPercent();
 			const stateParts: string[] = [];
 			if (tokens) stateParts.push(tokens);
 			stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);

package/src/ui/agent-menu.ts

@@ -252,8 +252,7 @@ export class AgentsMenuHandler {
   }
 
   private async viewAgentConversation(ui: MenuUI, record: Agent): Promise<void> {
-    const session = record.session;
-    if (!session) {
+    if (!record.isSessionReady()) {
       ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,
         "info",
@@ -270,7 +269,6 @@ export class AgentsMenuHandler {
       (tui: any, theme: any, _keybindings: any, done: any) => {
         return new ConversationViewer({
           tui,
-          session,
           record,
           activity,
           theme,

package/src/ui/conversation-viewer.ts

@@ -5,10 +5,9 @@
  * Subscribes to session events for real-time streaming updates.
  */
 
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import { getLifetimeTotal, getSessionContextPercent } from "#src/lifecycle/usage";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { Agent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { buildInvocationTags, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "#src/ui/display";
@@ -24,7 +23,6 @@ export const VIEWPORT_HEIGHT_PCT = 70;
 
 export interface ConversationViewerOptions {
   tui: TUI;
-  session: AgentSession;
   record: Agent;
   activity: AgentActivityTracker | undefined;
   theme: Theme;
@@ -41,7 +39,6 @@ export class ConversationViewer implements Component {
   private closed = false;
 
   private tui: TUI;
-  private session: AgentSession;
   private record: Agent;
   private activity: AgentActivityTracker | undefined;
   private theme: Theme;
@@ -51,7 +48,6 @@ export class ConversationViewer implements Component {
 
   constructor({
     tui,
-    session,
     record,
     activity,
     theme,
@@ -60,14 +56,13 @@ export class ConversationViewer implements Component {
     wrapText,
   }: ConversationViewerOptions) {
     this.tui = tui;
-    this.session = session;
     this.record = record;
     this.activity = activity;
     this.theme = theme;
     this.done = done;
     this.registry = registry;
     this.wrapText = wrapText;
-    this.unsubscribe = session.subscribe(() => {
+    this.unsubscribe = record.subscribeToUpdates(() => {
       if (this.closed) return;
       this.tui.requestRender();
     });
@@ -142,7 +137,7 @@ export class ConversationViewer implements Component {
     if (toolUses > 0) headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`);
     const tokens = getLifetimeTotal(this.record.lifetimeUsage);
     if (tokens > 0) {
-      const percent = getSessionContextPercent(this.record.session);
+      const percent = this.record.getContextPercent();
       headerParts.push(formatSessionTokens(tokens, percent, th, this.record.compactionCount));
     }
 
@@ -220,7 +215,7 @@ export class ConversationViewer implements Component {
 
     const th = this.theme;
     const ctx = { theme: th, wrapText: this.wrapText };
-    const messages = this.session.messages;
+    const messages = this.record.messages;
 
     if (messages.length === 0) {
       return [th.fg("dim", "(waiting for first message...)")];
@@ -229,7 +224,7 @@ export class ConversationViewer implements Component {
     const lines: string[] = [];
     let needsSeparator = false;
     for (const msg of messages) {
-      const formatted = formatMessage(msg as unknown as { role: string; [key: string]: unknown }, width, ctx);
+      const formatted = formatMessage(msg as { role: string; [key: string]: unknown }, width, ctx);
       if (!formatted) continue;
       if (needsSeparator) lines.push(th.fg("dim", "───"));
       lines.push(...formatted);