@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/lifecycle/usage.ts

@@ -0,0 +1,60 @@
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+export type LifetimeUsage = { input: number; output: number; cacheWrite: number };
+
+/** Sum of lifetime usage components, or 0 if undefined. */
+export function getLifetimeTotal(u?: LifetimeUsage): number {
+  return u ? u.input + u.output + u.cacheWrite : 0;
+}
+
+/** Add a usage delta into a target accumulator (mutates target). */
+export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
+  into.input += delta.input;
+  into.output += delta.output;
+  into.cacheWrite += delta.cacheWrite;
+}
+
+/** Minimal shape we read from upstream `getSessionStats()`. */
+export type SessionStatsLike = {
+  tokens: { input: number; output: number; cacheWrite: number };
+  contextUsage?: { percent: number | null };
+};
+export type SessionLike = { getSessionStats(): SessionStatsLike };
+
+/**
+ * Session-scoped token count: input + output + cacheWrite as reported by
+ * upstream `getSessionStats().tokens` for the *current* session window.
+ *
+ * RESETS at compaction — upstream replaces `session.state.messages` and the
+ * stats are derived from that array. For a lifetime total that survives
+ * compaction, use `getLifetimeTotal(lifetimeUsage)` instead, which reads
+ * from an independent accumulator fed by `message_end` events.
+ *
+ * Avoids upstream's `tokens.total` field, which sums per-turn `cacheRead`
+ * and so counts the cumulative cached prefix N times across N turns
+ * (issue #38).
+ */
+export function getSessionTokens(session: SessionLike | undefined): number {
+  if (!session) return 0;
+  try {
+    const t = session.getSessionStats().tokens;
+    return t.input + t.output + t.cacheWrite;
+  } catch { return 0; }
+}
+
+/**
+ * Context-window utilization (0–100), or null when unavailable
+ * (no model contextWindow, or post-compaction before the next response).
+ */
+export function getSessionContextPercent(session: SessionLike | undefined): number | null {
+  if (!session) return null;
+  try { return session.getSessionStats().contextUsage?.percent ?? null; }
+  catch { return null; }
+}

package/src/lifecycle/workspace-bracket.ts

@@ -0,0 +1,59 @@
+/**
+ * workspace-bracket.ts — Owned prepare/dispose lifecycle for a child workspace.
+ *
+ * Captures the provider resolver (not the provider itself) so provider
+ * resolution stays lazy at run-start. The prepared Workspace is held
+ * privately; dispose() centralises the guard and addendum-unwrap so callers
+ * never reach through to workspace.dispose().resultAddendum directly.
+ *
+ * dispose() deliberately does NOT catch errors — the best-effort try/catch
+ * for failRun() belongs at the call site, preserving the per-caller semantics.
+ */
+
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+/** Owns the child workspace lifecycle: prepare at run-start, dispose at run-end. */
+export class WorkspaceBracket {
+	private prepared?: Workspace;
+
+	constructor(private readonly resolveProvider: () => WorkspaceProvider | undefined) {}
+
+	/**
+	 * Returns true when a workspace provider is currently registered.
+	 * Use to guard the `await prepare(...)` call and avoid an unnecessary
+	 * microtask boundary in the no-provider path.
+	 */
+	hasProvider(): boolean {
+		return this.resolveProvider() !== undefined;
+	}
+
+	/**
+	 * Resolve the registered provider and prepare the child workspace.
+	 * Returns the workspace's cwd, or undefined when no provider is registered
+	 * or the provider resolves to undefined.
+	 */
+	async prepare(ctx: WorkspacePrepareContext): Promise<string | undefined> {
+		const provider = this.resolveProvider();
+		if (!provider) return undefined;
+		this.prepared = await provider.prepare(ctx);
+		return this.prepared?.cwd;
+	}
+
+	/**
+	 * Dispose the prepared workspace (if any) and return the result addendum
+	 * verbatim. Returns an empty string when no workspace was prepared or when
+	 * the workspace returns no addendum.
+	 *
+	 * Throws propagate — wrap in try/catch at the call site when best-effort
+	 * disposal is desired (e.g. failRun).
+	 */
+	dispose(outcome: WorkspaceDisposeOutcome): string {
+		if (!this.prepared) return "";
+		return this.prepared.dispose(outcome)?.resultAddendum ?? "";
+	}
+}

package/src/lifecycle/workspace.ts

@@ -0,0 +1,47 @@
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+import type { SubagentOutcome } from "#src/lifecycle/subagent";
+import type { AgentInvocation, SubagentType } from "#src/types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+  agentId: string;
+  agentType: SubagentType;
+  baseCwd: string;
+  invocation?: AgentInvocation;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+  outcome: SubagentOutcome;
+  description: string;
+}
+
+/** What dispose may hand back for the core to fold into the child result. */
+export interface WorkspaceDisposeResult {
+  /** Appended verbatim to the child's result text — the provider owns the wording. */
+  resultAddendum?: string;
+}
+
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+export interface Workspace {
+  /** The working directory — already exists when the workspace is handed back. */
+  readonly cwd: string;
+  dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+
+/** The single generative seam: supplies a child's workspace. */
+export interface WorkspaceProvider {
+  prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}

package/src/observation/composite-subagent-observer.ts

@@ -0,0 +1,53 @@
+import { debugLog } from "#src/debug";
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/**
+ * Fans out SubagentManager lifecycle notifications to multiple observers.
+ *
+ * Lets the manager keep its single-observer contract while several independent
+ * consumers (event/notification dispatch, the reactive widget) subscribe.
+ * Each delegate is isolated: a throw in one does not suppress the others.
+ */
+export class CompositeSubagentObserver implements SubagentManagerObserver {
+  private readonly delegates: SubagentManagerObserver[];
+
+  constructor(delegates: SubagentManagerObserver[]) {
+    this.delegates = [...delegates];
+  }
+
+  /** Register an additional observer (breaks the widget↔manager construction cycle). */
+  add(observer: SubagentManagerObserver): void {
+    this.delegates.push(observer);
+  }
+
+  onSubagentStarted(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentStarted(record), "onSubagentStarted");
+  }
+
+  onSubagentCreated(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentCreated(record), "onSubagentCreated");
+  }
+
+  onSubagentCompleted(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentCompleted(record), "onSubagentCompleted");
+  }
+
+  onSubagentResumed(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentResumed(record), "onSubagentResumed");
+  }
+
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+    this.dispatch((o) => o.onSubagentCompacted(record, info), "onSubagentCompacted");
+  }
+
+  private dispatch(call: (o: SubagentManagerObserver) => void, label: string): void {
+    for (const o of this.delegates) {
+      try {
+        call(o);
+      } catch (err) {
+        debugLog(`CompositeSubagentObserver.${label}`, err);
+      }
+    }
+  }
+}

package/src/observation/notification.ts

@@ -0,0 +1,233 @@
+import { debugLog } from "#src/debug";
+import type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent-state";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
+import type { Subagent } from "#src/types";
+import { getOutcomeLabel } from "#src/ui/display";
+
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+  id: string;
+  description: string;
+  phase: SubagentPhase;
+  outcome?: SubagentOutcome;
+  toolUses: number;
+  invocationTurnCount: number;
+  lifetimeTurnCount: number;
+  maxTurns?: number;
+  totalTokens: number;
+  durationMs: number;
+  outputFile?: string;
+  error?: string;
+  resultPreview: string;
+}
+
+// ---- Pure helpers (exported for unit testing) ----
+
+/**
+ * Escape XML special characters to prevent injection in structured
+ * notifications. Quotes are escaped too, so values stay safe if they are ever
+ * placed in attribute position, not only element content.
+ */
+export function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** Human-readable status label for agent completion. */
+export function getStatusLabel(outcome: SubagentOutcome | undefined, error?: string): string {
+  if (outcome === "error") return `Error: ${error ?? "unknown"}`;
+  return getOutcomeLabel(outcome);
+}
+
+/** Format a structured <task-notification> XML block for the parent agent to parse. */
+export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
+  if (record.stoppedWhileQueued) return formatNeverStartedNotification(record);
+
+  const status = getStatusLabel(record.outcome, record.error);
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+  const contextPercent = record.getContextPercent();
+  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
+
+  const resultPreview = record.result
+    ? record.result.length > resultMaxLen
+      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      : record.result
+    : "No output.";
+
+  const toolCallId = record.toolCallId;
+  const outputFile = record.outputFile;
+  return joinNotificationLines([
+    "<task-notification>",
+    `<task-id>${record.id}</task-id>`,
+    toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
+    outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
+    `<status>${escapeXml(status)}</status>`,
+    `<summary>Subagent "${escapeXml(record.description)}" ${record.outcome ?? record.phase}</summary>`,
+    `<result>${escapeXml(resultPreview)}</result>`,
+    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
+    "</task-notification>",
+  ]);
+}
+
+/**
+ * Format the block for an agent stopped before the limiter admitted it. Such an
+ * agent never ran, so it has no result and no usage — reporting either (even as
+ * zeroes) would point the parent at work that does not exist.
+ */
+function formatNeverStartedNotification(record: Subagent): string {
+  const toolCallId = record.toolCallId;
+  return joinNotificationLines([
+    "<task-notification>",
+    `<task-id>${record.id}</task-id>`,
+    toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
+    "<status>Stopped before starting</status>",
+    `<summary>Subagent "${escapeXml(record.description)}" was stopped while queued and never started</summary>`,
+    "</task-notification>",
+  ]);
+}
+
+/** Join notification lines, dropping the ones a conditional element omitted. */
+function joinNotificationLines(lines: (string | null)[]): string {
+  return lines.filter(Boolean).join("\n");
+}
+
+/** Build notification details for the custom message renderer. */
+export function buildNotificationDetails(
+  record: Subagent,
+  resultMaxLen: number,
+): NotificationDetails {
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+  return {
+    id: record.id,
+    description: record.description,
+    phase: record.phase,
+    ...(record.outcome ? { outcome: record.outcome } : {}),
+    toolUses: record.toolUses,
+    invocationTurnCount: record.invocationTurnCount,
+    lifetimeTurnCount: record.lifetimeTurnCount,
+    maxTurns: record.maxTurns,
+    totalTokens,
+    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    outputFile: record.outputFile,
+    error: record.error,
+    resultPreview: buildResultPreview(record, resultMaxLen),
+  };
+}
+
+/** The renderer's preview text: the (truncated) result, or why there is none. */
+function buildResultPreview(record: Subagent, resultMaxLen: number): string {
+  if (record.stoppedWhileQueued) return "Never started — stopped while queued.";
+  if (!record.result) return "No output.";
+  return record.result.length > resultMaxLen
+    ? record.result.slice(0, resultMaxLen) + "…"
+    : record.result;
+}
+
+// ---- Notification system factory ----
+
+export interface NotificationSystem {
+  sendCompletion: (record: Subagent) => void;
+  dispose: () => void;
+}
+
+export class NotificationManager implements NotificationSystem {
+  // pi.sendMessage is fire-and-forget: while the parent's agent run is active,
+  // a followUp is handed to a queue the extension cannot recall, yet it is only
+  // delivered when the run drains that queue at turn end. A parent that pulls
+  // the result in between would receive it twice. So nudges that arrive mid-run
+  // are withheld here — where record.consumed is still consultable — and
+  // flushed once the run settles.
+  private pendingNudges = new Map<string, Subagent>();
+  private parentRunActive = false;
+  private disposed = false;
+
+  constructor(
+    private sendMessage: (
+      msg: { customType: string; content: string; display: boolean; details?: unknown },
+      opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+    ) => void,
+  ) {}
+
+  sendCompletion(record: Subagent): void {
+    // The session is gone. It is the aborts fired during shutdown that reach
+    // here, and with no parent run active a nudge would go straight out as an
+    // unrecallable followUp.
+    if (this.disposed) return;
+    // Consumption is domain state on the record; the nudge is a pure
+    // announcement. Skip if the parent already pulled the result (enqueue-time
+    // guard); emitIndividualNudge re-reads record.consumed when the nudge is
+    // actually emitted, which is what makes the flush a fresh re-check.
+    if (record.consumed) return;
+    if (this.parentRunActive) {
+      // Keyed by id, so a re-completion in the same run collapses to one nudge.
+      this.pendingNudges.set(record.id, record);
+      return;
+    }
+    this.emitIndividualNudge(record);
+  }
+
+  /** The parent's agent run became active; nudges are withheld until it settles. */
+  onParentAgentStart(): void {
+    this.parentRunActive = true;
+  }
+
+  /**
+   * The parent's agent run settled. Flush the nudges withheld during it, each
+   * re-checking consumption, so a result the parent pulled mid-run is dropped
+   * rather than announced a second time.
+   */
+  onParentAgentSettled(): void {
+    this.parentRunActive = false;
+    const withheld = [...this.pendingNudges.values()];
+    this.pendingNudges.clear();
+    for (const record of withheld) {
+      try {
+        this.emitIndividualNudge(record);
+      } catch (err) {
+        debugLog("notification render", err);
+      }
+    }
+  }
+
+  /** Terminal: the manager stops announcing anything, now and afterwards. */
+  dispose(): void {
+    this.disposed = true;
+    this.pendingNudges.clear();
+  }
+
+  private emitIndividualNudge(record: Subagent): void {
+    if (record.consumed) return;
+
+    const notification = formatTaskNotification(record, 500);
+    // A never-started agent has no transcript and nothing to collect.
+    const pointerLines = record.stoppedWhileQueued ? "" : this.buildPointerLines(record);
+
+    this.sendMessage(
+      {
+        customType: "subagent-notification",
+        content: notification + pointerLines,
+        display: true,
+        details: buildNotificationDetails(record, 500),
+      },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  }
+
+  /**
+   * The trailing pointer lines: where the transcript lives, and how to collect
+   * the result. The nudge only announces; the parent must pull to collect (and
+   * consume).
+   */
+  private buildPointerLines(record: Subagent): string {
+    const outputFile = record.outputFile;
+    const transcriptLine = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
+    return `${transcriptLine}\nCall get_subagent_result("${record.id}") to collect the full result.`;
+  }
+}

package/src/observation/record-observer.ts

@@ -0,0 +1,78 @@
+/**
+ * record-observer.ts — Subscribes to session events and accumulates SubagentState stats.
+ *
+ * Replaces the scattered callback-wrapping logic in SubagentManager's startAgent()
+ * and resume() with a single direct subscription. The observer targets the
+ * SubagentState value object directly, so it carries no dependency on Subagent;
+ * the caller forwards itself to its own lifecycle observer via onCompact.
+ */
+
+import type { SubagentState } from "#src/lifecycle/subagent-state";
+import type { CompactionInfo, SubscribableSession } from "#src/types";
+
+export interface SubagentObserverOptions {
+  onCompact?: (info: CompactionInfo) => void;
+}
+
+/**
+ * Subscribe to session events and accumulate stats on the subagent state.
+ *
+ * Handles:
+ * - `tool_execution_start` → `state.addActiveTool(name)`
+ * - `tool_execution_end` → `state.removeActiveTool(name)`, `state.incrementToolUses()`
+ * - `message_start` → `state.resetResponseText()`
+ * - `message_update` (text_delta) → `state.appendResponseText(delta)`
+ * - `message_end` (assistant, with usage) → `state.addUsage(…)`
+ * - `turn_end` → `state.incrementTurnCount()`
+ * - `compaction_end` (not aborted) → `state.incrementCompactions()`, call `onCompact`
+ *
+ * @returns An unsubscribe function.
+ */
+export function subscribeSubagentObserver(
+  session: SubscribableSession,
+  state: SubagentState,
+  options?: SubagentObserverOptions,
+): () => void {
+  return session.subscribe((event) => {
+    if (event.type === "tool_execution_start") {
+      state.addActiveTool(event.toolName);
+    }
+
+    if (event.type === "tool_execution_end") {
+      state.removeActiveTool(event.toolName);
+      state.incrementToolUses();
+    }
+
+    if (event.type === "message_start") {
+      state.resetResponseText();
+    }
+
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      state.appendResponseText(event.assistantMessageEvent.delta);
+    }
+
+    if (event.type === "turn_end") {
+      state.incrementTurnCount();
+    }
+
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      const u = event.message.usage;
+      state.addUsage({
+        input: u.input,
+        output: u.output,
+        cacheWrite: u.cacheWrite,
+      });
+    }
+
+    if (event.type === "compaction_end" && !event.aborted && event.result) {
+      state.incrementCompactions();
+      options?.onCompact?.({
+        reason: event.reason,
+        tokensBefore: event.result.tokensBefore,
+      });
+    }
+  });
+}

package/src/observation/renderer.ts

@@ -0,0 +1,106 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent-state";
+import { getStatusLabel, type NotificationDetails } from "#src/observation/notification";
+import { formatMs, formatTokens, formatTurns } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+
+/** Narrow theme interface — only the methods the renderer actually calls. */
+interface RendererTheme {
+  fg(style: string, text: string): string;
+  bold(text: string): string;
+}
+
+/** Narrow message interface — only the fields the renderer reads. */
+interface RendererMessage {
+  details?: NotificationDetails;
+}
+
+/** Narrow render options — only the fields the renderer reads. */
+interface RenderOptions {
+  expanded: boolean;
+}
+
+// ---- Pure helpers (exported for unit testing) ----
+
+/** Resolved status→presentation product: icon glyph/style and status label. */
+export interface StatusPresentation {
+  iconGlyph: string;
+  iconStyle: string;
+  statusText: string;
+}
+
+/** Decide the icon and status label for a notification's phase/outcome, once. */
+export function resolveStatusPresentation(
+  phase: SubagentPhase,
+  outcome: SubagentOutcome | undefined,
+  error?: string,
+): StatusPresentation {
+  if (outcome === "completed")
+    return { iconGlyph: GLYPHS.success, iconStyle: "success", statusText: getStatusLabel(outcome) };
+  if (outcome != null)
+    return { iconGlyph: GLYPHS.failure, iconStyle: "error", statusText: getStatusLabel(outcome, error) };
+  // Not terminal yet: queued/running notifications carry no outcome.
+  return { iconGlyph: GLYPHS.agentsActive, iconStyle: "dim", statusText: phase };
+}
+
+/** Fields `buildStatsParts` reads from a `NotificationDetails`. */
+type StatsSource = Pick<
+  NotificationDetails,
+  "invocationTurnCount" | "maxTurns" | "toolUses" | "totalTokens" | "durationMs"
+>;
+
+/** Assemble the stats-line parts (turns, tool uses, tokens, duration), omitting zero fields. */
+export function buildStatsParts(d: StatsSource): string[] {
+  const parts: string[] = [];
+  if (d.invocationTurnCount > 0) parts.push(formatTurns(d.invocationTurnCount, d.maxTurns));
+  if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+  if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
+  if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
+  return parts;
+}
+
+/**
+ * Content lines for the result preview: the whole result (capped at 30 lines)
+ * when expanded, or just the first line (capped at 80 columns) when collapsed.
+ */
+export function buildPreviewLines(resultPreview: string, expanded: boolean): string[] {
+  if (expanded) return resultPreview.split("\n").slice(0, 30);
+  return [resultPreview.split("\n")[0]?.slice(0, 80) ?? ""];
+}
+
+/**
+ * Create the notification renderer callback for `pi.registerMessageRenderer`.
+ * Returns a factory so the renderer is independently testable without the Pi SDK.
+ */
+export function createNotificationRenderer() {
+  return (message: RendererMessage, { expanded }: RenderOptions, theme: RendererTheme): Text | undefined => {
+    const d = message.details;
+    if (!d) return undefined;
+
+    const { iconGlyph, iconStyle, statusText } = resolveStatusPresentation(d.phase, d.outcome, d.error);
+
+    // Line 1: icon + agent description + status
+    let line = `${theme.fg(iconStyle, iconGlyph)} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+
+    // Line 2: stats
+    const parts = buildStatsParts(d);
+    if (parts.length) {
+      line += "\n  " + parts.map((p) => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+    }
+
+    // Line 3: result preview (collapsed) or full (expanded)
+    const previewLines = buildPreviewLines(d.resultPreview, expanded);
+    if (expanded) {
+      for (const l of previewLines) line += "\n" + theme.fg("dim", `  ${l}`);
+    } else {
+      line += "\n  " + theme.fg("dim", `${GLYPHS.subLine}  ${previewLines[0] ?? ""}`);
+    }
+
+    // Line 4: output file link (if present)
+    if (d.outputFile) {
+      line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
+    }
+
+    return new Text(line, 0, 0);
+  };
+}