@workerdeck/ui 0.17.0 → 0.18.0

package/src/components/agent/Transcript.tsx

@@ -26,14 +26,17 @@ import { SessionEmptyState } from './SessionEmptyState.tsx'
 import { ToolCallCard } from './ToolCallCard.tsx'
 import { resolveAffordances, type TerminalAffordances } from '../terminal/affordances.tsx'
 import { ToolRunRow, WorkingRow, parentOf, terminalBlocks } from '../terminal/items.tsx'
-import { estimateBlockPx } from '../terminal/height.ts'
+import { subagentItems, type ToolCallItem } from '../terminal/blocks.ts'
+import { taskBrief } from '../terminal/tool-run.ts'
+import { taskBusy } from '../terminal/tool-run.ts'
+import { briefPx, estimateBlockPx } from '../terminal/height.ts'
 import { TerminalScrubber } from '../terminal/scrubber.tsx'
 import { gapBefore, positionInRow, rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
 import { useHeightEpoch } from './use-height-epoch.ts'
 import { useTranscriptJumps } from './use-transcript-jumps.ts'
 import { Row } from '../terminal/row.tsx'
 import { TerminalSurface } from '../terminal/surface.tsx'
-import { TaskRow, TerminalItemView } from '../terminal/TerminalTranscript.tsx'
+import { BriefRow, TaskRow, TerminalItemView } from '../terminal/TerminalTranscript.tsx'
 import {
   ROW_GAP,
   TranscriptVariantProvider,
@@ -300,9 +303,15 @@ function read(boundary: number | undefined, index: number): boolean {
 
 /** Rows produced inside a subagent (`parentToolUseId != null`) are stepped in
  * behind a rule, so a Task's own output reads as belonging to the tool call
- * above it rather than as the main thread carrying on. */
-function nestedClass(item: TranscriptItem): string | undefined {
-  const nested = 'parentToolUseId' in item && item.parentToolUseId != null
+ * above it rather than as the main thread carrying on.
+ *
+ * **Except inside that sub-agent's own frame**, where those same items are the
+ * top level and there is no main thread to be an aside from — stepping every row
+ * in would draw a rule down the whole surface saying "this happened somewhere
+ * else" about the only thing on screen. */
+function nestedClass(item: TranscriptItem, frameParentId?: string): string | undefined {
+  const parent = 'parentToolUseId' in item ? item.parentToolUseId : undefined
+  const nested = parent != null && parent !== frameParentId
   return nested ? 'border-l-2 border-border pl-3' : undefined
 }
 
@@ -430,6 +439,8 @@ function TranscriptRows({
   terminal,
   replaying,
   stickyPrompt,
+  frameParentId,
+  onOpenSubagent,
   gap,
   fontSize,
   lineHeight,
@@ -468,6 +479,11 @@ function TranscriptRows({
   /** Mount the overview-ruler rail (terminal theme only). */
   scrubber?: boolean
   scrubberMarks?: readonly number[]
+  /** Set when these rows are a sub-agent's frame — the id everything here was
+   *  produced inside. Only `nestedClass` needs it: inside the frame those items
+   *  are the top level and must not be stepped in. */
+  frameParentId?: string
+  onOpenSubagent?: (toolUseId: string) => void
   affordances?: TerminalAffordances | boolean
   fileUrl?: (path: string) => string
   attachmentUrl?: (attachmentId: string) => string
@@ -613,6 +629,12 @@ function TranscriptRows({
       if (terminal && epoch) {
         const row = rows[index]
         const gapPx = index > 0 && gapBefore(rows, index) ? epoch.line : 0
+        if (row && 'text' in row && row.key === 'brief')
+          // Collapsed by default and clipped to BRIEF_LINES, so its height is
+          // known before it mounts — the same discipline the task row keeps by
+          // always being collapsed when unmounted. Expanding is local state on
+          // a mounted row, which the virtualizer re-measures.
+          return briefPx(row.text, epoch) + gapPx
         if (row && !('line' in row))
           return estimateBlockPx(row, epoch) + gapPx
         return epoch.line + gapPx // recap: one Row, one line
@@ -837,7 +859,7 @@ function TranscriptRows({
               <ToolRunRow items={row.run} />
             </div>
           ) : 'item' in row ? (
-            <div className={cn(read(boundary, row.index) && 'opacity-45', nestedClass(row.item))}>
+            <div className={cn(read(boundary, row.index) && 'opacity-45', nestedClass(row.item, frameParentId))}>
               <TranscriptItemView
                 item={row.item}
                 fileUrl={fileUrl}
@@ -846,6 +868,8 @@ function TranscriptRows({
                 terminal={terminal}
               />
             </div>
+          ) : 'text' in row && row.key === 'brief' ? (
+            <BriefRow text={row.text} terminal={terminal} />
           ) : 'line' in row ? (
             <RecapRow line={row.line} since={since} terminal={terminal} />
           ) : (
@@ -854,7 +878,7 @@ function TranscriptRows({
             // is the main thread's, and stepping it in would say a `Task` call
             // happened somewhere else.
             <div className={cn(read(boundary, row.index) && 'opacity-45')}>
-              <TaskRow block={row} fileUrl={fileUrl} />
+              <TaskRow block={row} fileUrl={fileUrl} onOpenSubagent={onOpenSubagent} />
             </div>
           )
         // A prompt row's sticky lane — see the pinned-prompt comment above.
@@ -921,6 +945,7 @@ function TranscriptRows({
               pendingApprovals={pendingApprovals}
               recapRow={recapRow}
               bookmarks={scrubberMarks ?? []}
+              frameParentId={frameParentId}
               rowIndexFor={(itemIndex) => rowIndexForItem(rows, itemIndex)}
               positionInRow={(itemIndex) => positionInRow(rows, itemIndex)}
               // The public memoized measurements array — `getTotalSize()` just
@@ -1044,6 +1069,39 @@ export interface TranscriptProps {
    * would need a live closure at the other end of a postMessage bridge.
    */
   reveal?: { toolUseId: string; nonce: number }
+  /**
+   * Render **only** the work one sub-agent did, rather than the conversation —
+   * the sub-agent takeover's frame.
+   *
+   * Membership is `subagentItems` (`terminal/blocks.ts`), which is also the rule
+   * iOS will mirror: everything the agent produced, and not the spawning `Task`
+   * call itself, which *is* the frame rather than a row in it.
+   *
+   * Features are switched off internally whenever it is set, and the gate lives
+   * here rather than at the call site on purpose: each is keyed to a
+   * **full-transcript item index**, so a host that passed a frame and a catch-up
+   * boundary together would not be making a strange choice, it would be making
+   * an incoherent one. Those are the catch-up boundary and its recap row, the
+   * sticky prompt, `reveal`, and the scrubber's **bookmarks** (host indices in
+   * full-transcript space).
+   *
+   * The **scrubber itself stays**, and the distinction is the point: the rail
+   * derives every one of its inputs from the rows it is given, and inside a
+   * frame those are the sub-agent's own — so it marks that agent's prompts,
+   * answers and failures at that agent's offsets. It was originally gated with
+   * the marks, on the reasonable-looking argument that they are one feature;
+   * they are two, and a fifty-tool agent run is exactly where a rail earns its
+   * keep. What stays besides is everything that makes a long stream readable —
+   * virtualization, the height epoch, the follow spring, the replay hold.
+   */
+  frame?: { parentToolUseId: string }
+  /**
+   * Raise the takeover from a `Task` row. Absent draws no affordance, which is
+   * what the plain renderer and the cards variant get: cards folds nothing, so
+   * it has no task blocks to hang this on, and reaches the takeover from the
+   * sessions list instead.
+   */
+  onOpenSubagent?: (toolUseId: string) => void
   className?: string
 }
 
@@ -1066,9 +1124,30 @@ export function Transcript({
   jumpToRecapRef,
   repinRef,
   reveal,
+  frame,
+  onOpenSubagent,
   className,
 }: TranscriptProps) {
   const terminal = variant === 'terminal'
+  // The frame's own item list, and the single place the takeover's content is
+  // decided. Everything below reads `items` rather than `state.items`, so the
+  // row build, the empty state and the loader all describe the same surface.
+  const items = useMemo(
+    () => (frame ? subagentItems(state.items, frame.parentToolUseId) : state.items),
+    [state.items, frame],
+  )
+  // The spawning call, for the header's claim and to tell "not here yet" from
+  // "not in this transcript" — see the frame placeholder below.
+  const frameTask = useMemo(
+    () =>
+      frame
+        ? state.items.find(
+            (item): item is ToolCallItem =>
+              item.kind === 'tool_call' && item.id === frame.parentToolUseId,
+          )
+        : undefined,
+    [state.items, frame],
+  )
   const gap = ROW_GAP[variant][density]
   const runStartedAt = useRunStart(state.status)
   // A boundary at (or past) the end means nothing is new — no row, no dimming.
@@ -1083,24 +1162,40 @@ export function Transcript({
   // cannot say what you missed. Clamping it would land on `items.length` and
   // read as "nothing is new" — the same outcome, told less truthfully.
   const boundary =
-    catchUp && catchUp.from > 0 && catchUp.from < state.items.length ? catchUp.from : undefined
+    !frame && catchUp && catchUp.from > 0 && catchUp.from < state.items.length
+      ? catchUp.from
+      : undefined
   const recap = useMemo(
     () => (boundary === undefined ? undefined : recapLine(summarizeSince(state, boundary))),
     [state, boundary],
   )
+  // What this agent was asked, when the stream does not already say. A
+  // foreground `Task` forwards its brief as a real nested user message and it is
+  // already the frame's first row; a background agent forwards nothing, and
+  // without this the takeover shows an answer with the question missing. Hence
+  // the guard rather than an unconditional splice — drawn both ways, the reader
+  // would see the same instruction twice.
+  const brief = useMemo(
+    () =>
+      frame && frameTask && !items.some((item) => item.kind === 'user')
+        ? taskBrief(frameTask)
+        : undefined,
+    [frame, frameTask, items],
+  )
   const rows = useMemo<TranscriptRow[]>(() => {
     const fold = (from: number, to: number) =>
-      terminalBlocks(state.items.slice(from, to), from, terminal)
-    if (boundary === undefined || !recap) return fold(0, state.items.length)
+      terminalBlocks(items.slice(from, to), from, terminal)
+    const lead: TranscriptRow[] = brief ? [{ key: 'brief' as const, text: brief }] : []
+    if (boundary === undefined || !recap) return [...lead, ...fold(0, items.length)]
     // Each side of the boundary folds separately, so a shell run never spans it:
     // "what happened while you were away" must not hide inside a count that also
     // covers what you have already read.
     return [
       ...fold(0, boundary),
       { key: 'recap' as const, line: recap },
-      ...fold(boundary, state.items.length),
+      ...fold(boundary, items.length),
     ]
-  }, [state.items, boundary, recap, terminal])
+  }, [items, boundary, recap, terminal, brief])
   return (
     <TranscriptVariantProvider value={variant}>
       {/* The replay hold hides by VISIBILITY, never by not mounting. The rows
@@ -1121,38 +1216,62 @@ export function Transcript({
             fontSize={fontSize}
             lineHeight={lineHeight}
             affordances={affordances}>
-          {state.items.length === 0 && state.status !== 'starting' ? (
+          {frame ? (
+            // The frame's own empty states, and they are two different facts.
+            // A task that is present with nothing under it yet is simply an
+            // agent that has not spoken — the loader below says so. A task the
+            // transcript does not have is either still replaying (say nothing,
+            // the hold is up) or genuinely absent: a `/clear` retired the
+            // conversation it lived in, or the id was never this session's.
+            // **Never auto-exit on that** — navigating out from under a reader
+            // is worse than one honest line they can leave when they choose.
+            frameTask === undefined && !replaying ? (
+              <div className={cn(terminal ? 'term-row text-fg-4' : 'p-4 text-body-sm text-fg-4')}>
+                This sub-agent's work is not in this transcript.
+              </div>
+            ) : null
+          ) : items.length === 0 && state.status !== 'starting' ? (
             <SessionEmptyState
               cwd={state.cwd}
               hasCommands={!!state.commands?.length}
               hasSkills={!!state.skills?.some((s) => s.enabled)}
               canBrowseFiles={canBrowseFiles}
             />
-          ) : (
+          ) : null}
+          {frame && frameTask === undefined && !replaying ? null : (
             <TranscriptRows
               rows={rows}
               boundary={boundary}
               since={catchUp?.since}
               terminal={terminal}
               replaying={replaying}
-              stickyPrompt={stickyPrompt}
+              stickyPrompt={!frame && stickyPrompt}
               gap={gap}
               fontSize={fontSize}
               lineHeight={lineHeight}
-              items={state.items}
+              items={items}
               pendingApprovals={state.pendingApprovals}
+              /* The rail rides the frame's OWN rows, so inside a takeover it
+                 marks the sub-agent's prompts, answers and failures — the thing
+                 a long agent run most needs, and coherent because every input
+                 it takes (`items`, `rowIndexFor`, `offsetOfRow`) is the frame's.
+                 The **bookmarks are not**: those indices are the host's, in
+                 full-transcript space, and painting them here would put marks
+                 at meaningless offsets. See `frame`'s doc for the rest. */
               scrubber={scrubber}
-              scrubberMarks={scrubberMarks}
+              scrubberMarks={frame ? undefined : scrubberMarks}
               affordances={affordances}
               fileUrl={fileUrl}
               attachmentUrl={attachmentUrl}
               hostImage={hostImage}
               jumpToRecapRef={jumpToRecapRef}
               repinRef={repinRef}
-              reveal={reveal}
+              reveal={frame ? undefined : reveal}
+              frameParentId={frame?.parentToolUseId}
+              onOpenSubagent={frame ? undefined : onOpenSubagent}
             />
           )}
-          {showLoader(state) ? (
+          {(frame ? frameTask !== undefined && taskBusy(frameTask, items) : showLoader(state)) ? (
             terminal ? (
               // The CLI's own working line, and it is a *row of the transcript*
               // rather than a spinner floating over it — one blank line down,

package/src/components/agent/transcript-rows.ts

@@ -14,7 +14,15 @@ import { needsBlank, type TerminalBlock } from '../terminal/items.tsx'
  * virtualizer sees stable indices, and each row carries the key the item was
  * already React-keyed by — measurements are cached per key, so a row keeps its
  * measured height when the recap splice shifts every index after it. */
-export type TranscriptRow = TerminalBlock | { key: 'recap'; line: string }
+export type TranscriptRow =
+  | TerminalBlock
+  | { key: 'recap'; line: string }
+  /** The sub-agent's brief, spliced in as the takeover frame's first row — what
+   * the agent was asked, before what it did. Synthetic like the recap row and
+   * for the same reason: it is not a transcript item (the engine puts the
+   * instruction in the spawning call's `prompt`, never in the stream), but it
+   * has to be a row so the virtualizer can size and key it. */
+  | { key: 'brief'; text: string }
 
 /** The item a row is spaced *as*. A run stands for the calls it folded, and a
  * task block for the `Task` call it absorbed into — all tool calls, so a run,

package/src/components/terminal/TerminalTranscript.tsx

@@ -2,6 +2,7 @@ import { Fragment, useEffect, useMemo, useState } from 'react'
 import type { TranscriptItem, TranscriptState } from '@workerdeck/react'
 import { cn } from '../../lib/utils.ts'
 import type { TerminalAffordances } from './affordances.tsx'
+import { OpenSubagentAction, WithActions } from './affordances.tsx'
 import {
   AssistantRow,
   FileRow,
@@ -19,7 +20,8 @@ import {
 } from './items.tsx'
 import { usePulse } from '../agent/pulse.tsx'
 import { Pressable, useRevealOnOpen } from './press.tsx'
-import { taskBusy, taskFailed, taskSummary } from './tool-run.ts'
+import { taskBrief, taskBusy, taskFailed, taskSummary } from './tool-run.ts'
+import { BRIEF_LINES } from './height.ts'
 import { Blank, Row } from './row.tsx'
 import { TerminalSurface } from './surface.tsx'
 
@@ -105,21 +107,72 @@ export function TerminalItemView({
  * they fold among themselves: a subagent's consecutive tool calls are as much
  * an aside inside its frame as they are in the main thread.
  */
+/**
+ * **What the agent was asked** — the sub-agent's brief, clipped to
+ * {@link BRIEF_LINES} and pressable for the whole of it.
+ *
+ * It leads the takeover's frame and the inline task expansion alike, because
+ * both are answering the same question and an answer without its question is
+ * half a transcript. This is the one row here built from something other than
+ * the stream, and it exists for the case the stream does not cover: a
+ * **background** agent forwards no brief, where a foreground `Task` forwards a
+ * real nested user item that renders as an ordinary prompt row. The callers
+ * splice this in only when that row is absent. Codex draws nothing either way —
+ * its spawn message is encrypted on the wire, so there is no brief to give.
+ *
+ * `>` and blue, the prompt's own marker and colour, because that is what this
+ * is: somebody's instruction, one level in. The clip is `line-clamp`, which
+ * cuts on the same wrapped lines `briefPx` counts — one rule, so the reserved
+ * height and the drawn height cannot disagree.
+ */
+export function BriefRow({ text, terminal }: { text: string; terminal?: boolean }) {
+  const [open, setOpen] = useState(false)
+  if (!terminal) {
+    return (
+      <div data-slot='brief' className='px-4 py-2 text-body-sm whitespace-pre-wrap text-fg-2'>
+        {text}
+      </div>
+    )
+  }
+  return (
+    <div data-slot='brief'>
+      <Pressable onPress={() => setOpen((v) => !v)} expanded={open}>
+        <Row glyph='>' glyphTone='blue' tone='dim'>
+          <span
+            className={cn('whitespace-pre-wrap', !open && 'term-brief-clip')}
+            style={open ? undefined : { WebkitLineClamp: BRIEF_LINES }}>
+            {text}
+          </span>
+        </Row>
+      </Pressable>
+    </div>
+  )
+}
+
 export function TaskRow({
   block,
   fileUrl,
+  onOpenSubagent,
 }: {
   block: TaskBlock
   fileUrl?: (path: string) => string
+  /** Take over the panel with this sub-agent's own frame. Absent draws no
+   * affordance at all — the plain renderer has no surface to take over, and an
+   * action that opens nothing is worse than no action. */
+  onOpenSubagent?: (toolUseId: string) => void
 }) {
   const [open, setOpen] = useState(false)
   const reveal = useRevealOnOpen(open)
   const children = useMemo(() => taskChildItems(block), [block])
+  // Only when the sub-agent's own stream carries no brief — a foreground Task
+  // forwards one as a real user item, and two spellings of one instruction is
+  // worse than none. See `taskBrief`.
+  const brief = children.some((item) => item.kind === 'user') ? undefined : taskBrief(block.task)
   const busy = taskBusy(block.task, children)
   const failed = taskFailed(block.task)
   const pulse = usePulse(busy)
 
-  return (
+  const row = (
     <div ref={reveal} className={open ? 'term-open' : undefined}>
       <Pressable onPress={() => setOpen((v) => !v)} expanded={open}>
         {/* A marker, where a folded run of calls gets none: a run is an aside,
@@ -127,10 +180,18 @@ export function TaskRow({
             the row stands for the whole of it. The body is `taskSummary`
             verbatim — it is the string `height.ts` wraps to size this row, and
             a second spelling here would be a second height. */}
+        {/* Green means sub-agent, and it means it here for the same reason it
+            means it on the rail: every other colour is spoken for — blue is
+            you, white is the answer, red is an alarm, magenta is your bookmark,
+            yellow is the session waiting on you (see `terminal.css`). The
+            *body* is green and the marker is not: a green glyph already means
+            "wrote to the workspace" a few rows down, and one colour cannot mean
+            two things in the same gutter. Failure still outranks it — an alarm
+            is not a category. */}
         <Row
           glyph={busy ? pulse : '●'}
           glyphTone={failed ? 'red' : busy ? 'mark' : 'dim'}
-          tone={failed ? 'red' : 'fg'}>
+          tone={failed ? 'red' : 'green'}>
           {taskSummary(block.task, children)}
         </Row>
       </Pressable>
@@ -139,6 +200,9 @@ export function TaskRow({
         // sits on the open block's wash, where that border token is invisible,
         // and its 14px would take every nested marker off the cell grid.
         <div className='term-nested'>
+          {/* The brief leads the children for the same reason it leads the
+              frame: the instruction, then the work. */}
+          {brief ? <BriefRow text={brief} terminal /> : null}
           {block.children.map((leaf, index) => (
             <Fragment key={leaf.key}>
               {index > 0 && blockNeedsBlank(block.children[index - 1]!, leaf) ? <Blank /> : null}
@@ -153,6 +217,16 @@ export function TaskRow({
       ) : null}
     </div>
   )
+  // Wrapped only when there is somewhere to go. `WithActions` is a no-op when
+  // affordances are off, but wrapping unconditionally would still put an
+  // "open" glyph on a renderer that cannot honour it.
+  return onOpenSubagent === undefined ? (
+    row
+  ) : (
+    <WithActions actions={<OpenSubagentAction onOpen={() => onOpenSubagent(block.task.id)} />}>
+      {row}
+    </WithActions>
+  )
 }
 
 /** When the current run began — the clock the working line counts from. Held

package/src/components/terminal/affordances.tsx

@@ -89,6 +89,40 @@ export function WithActions({
  * else is on, and reads as a button borrowed from another application. The tick
  * replaces the glyph in place, so the confirmation costs no width either.
  */
+/**
+ * Open a sub-agent's own surface, as a character.
+ *
+ * A row **action** and not the row's press, because the press already means
+ * expand/collapse and that is the cheaper, more common intent — a reader
+ * glancing at what an agent did wants the four rows inline, not a new screen.
+ * Taking over the panel is the deliberate move, so it gets the deliberate
+ * target. Same zero-layout contract as `CopyAction`: it lives in the hover
+ * actions overlay, so a collapsed Task row is exactly as tall with it as
+ * without, which is what keeps the height book honest.
+ */
+export function OpenSubagentAction({
+  onOpen,
+  label = 'Open sub-agent',
+}: {
+  onOpen: () => void
+  label?: string
+}) {
+  return (
+    <button
+      type='button'
+      className='term-action'
+      title={label}
+      aria-label={label}
+      onClick={(event) => {
+        // The row underneath expands; opening is not expanding.
+        event.stopPropagation()
+        onOpen()
+      }}>
+      ⤢
+    </button>
+  )
+}
+
 export function CopyAction({ text, label = 'Copy' }: { text: string; label?: string }) {
   const [copied, setCopied] = useState(false)
   return (

package/src/components/terminal/blocks.ts

@@ -67,6 +67,34 @@ export function parentOf(item: TranscriptItem): string | undefined {
   return parent ?? undefined
 }
 
+/**
+ * **The frame membership rule**: the items a sub-agent produced, and nothing
+ * else — what the takeover renders instead of the whole conversation.
+ *
+ * One exported function rather than a `filter` at each call site, because this
+ * is a rule two renderers have to agree on: iOS mirrors the terminal model out
+ * of this module, and a phone that framed a sub-agent slightly differently would
+ * be a second answer to "what is this agent doing".
+ *
+ * It picks up the brief (a `user` item *with* a parent), the thinking, the
+ * streamed text (deltas are namespaced per sidechain, so `streaming:<parentId>`
+ * carries the parent like any other item), every tool call with its result, and
+ * the final report. It excludes the spawning `Task` call itself — that is the
+ * frame, not a row in it — and every other agent's work.
+ *
+ * The slice is safe to hand straight to {@link terminalBlocks} at offset 0:
+ * nothing in it is top-level, so nothing absorbs, and consecutive calls still
+ * fold into runs because {@link foldsTogether} keys on an *equal* parent rather
+ * than on absence of one. Row indices are internally consistent because the rows
+ * and the `items` they came from are the same array.
+ */
+export function subagentItems(
+  items: readonly TranscriptItem[],
+  parentToolUseId: string,
+): TranscriptItem[] {
+  return items.filter((item) => parentOf(item) === parentToolUseId)
+}
+
 /** Is this a row the transcript folds into a run? Any tool call is — see
  * `tool-run.ts` for why this is no longer shell-only. */
 export function isRunCall(item: TranscriptItem): item is ToolCallItem {

package/src/components/terminal/height.ts

@@ -132,6 +132,30 @@ export function estimateBlockPx(block: TerminalBlock, epoch: HeightEpoch): numbe
   return computed.px
 }
 
+/**
+ * How many lines of a sub-agent's brief the collapsed row shows.
+ *
+ * Four, and the number is a judgement rather than a measurement: a brief runs
+ * to thousands of characters, and an uncapped one buries the work it was asking
+ * for under its own instructions. Four is enough to recognise the task and
+ * short enough that the agent's first line stays on screen beside it.
+ */
+export const BRIEF_LINES = 4
+
+/**
+ * The collapsed brief row's height — the frame's first row, which is synthetic
+ * and so cannot go through {@link estimateBlockPx}.
+ *
+ * Clipped, so it is `min(wrapped, BRIEF_LINES)` lines plus the row the header
+ * occupies. Expanding is local state on a *mounted* row, which the virtualizer
+ * re-measures; what has to be right before it mounts is the collapsed height,
+ * exactly as a task row is always collapsed when unmounted for the same reason.
+ */
+export function briefPx(text: string, m: CellMetrics): number {
+  const cols = Math.max(1, Math.floor(m.width / m.ch + EPS))
+  return (Math.min(textLines(text, cols).lines, BRIEF_LINES) + 1) * m.line
+}
+
 /** Measure the advance of `0` on the live surface. A DOM read — call it from
  * the epoch's measurement pass (an effect / ResizeObserver callback), never
  * from render. The probe is absolutely positioned, so it contributes no layout

package/src/components/terminal/items.tsx

@@ -442,7 +442,7 @@ export function FileRow({
 }
 
 /** A once-a-second clock, running only while `on`. */
-function useTicker(on: boolean): number {
+export function useTicker(on: boolean): number {
   const [now, setNow] = useState(() => Date.now())
   useEffect(() => {
     if (!on) return

package/src/components/terminal/scrubber.tsx

@@ -233,6 +233,19 @@ export interface TerminalScrubberProps {
   recapRow?: { rowIndex: number; label: string }
   /** Bookmarked item indices. Paint only — no store, no set affordance. */
   bookmarks: readonly number[]
+  /**
+   * The sub-agent takeover's parent id, when this rail belongs to a frame.
+   *
+   * **It is what "top level" means here.** Three of the rules below mark only
+   * items at the conversation's own level, so that a sub-agent's work is
+   * represented by the one band its `Task` row gets rather than by a second set
+   * of prompts and answers scattered through the rail. Inside a frame that same
+   * test excludes *everything* — every item there has a parent by construction —
+   * and the rail came out empty: mounted, banded, and marking nothing on a
+   * hundred-tool agent. So the level is a parameter, `undefined` at the top and
+   * the frame's id inside one.
+   */
+  frameParentId?: string
   /** Item index → virtual row index (the off-by-a-fold mapping; see
    * `rowIndexForItem` in `agent/Transcript.tsx`). */
   rowIndexFor: (itemIndex: number) => number
@@ -274,6 +287,7 @@ export function buildClusters(
   const {
     items,
     bookmarks,
+    frameParentId,
     recapRow,
     pendingApprovals,
     rowIndexFor,
@@ -300,7 +314,7 @@ export function buildClusters(
   // only `rowIndexFor`.
   const rowOutcome = new Map<number, number>()
   items.forEach((item, index) => {
-    if (item.kind !== 'tool_call' || parentOf(item) !== undefined) return
+    if (item.kind !== 'tool_call' || parentOf(item) !== frameParentId) return
     rowOutcome.set(rowIndexFor(index), index)
   })
   // One right-lane mark per segment, emitted when the segment closes. A segment
@@ -335,7 +349,7 @@ export function buildClusters(
     // is a `user` item too, and it would both paint a "you" mark for something
     // nobody typed and close the segment mid-turn — which mis-anchors the turn
     // mark whenever a task runs between the prompt and the answer.
-    if (item.kind === 'user' && parentOf(item) === undefined) {
+    if (item.kind === 'user' && parentOf(item) === frameParentId) {
       closeSegment()
       marks.push({ kind: 'user', itemIndex: index, rowIndex: rowIndexFor(index) })
     } else if (item.kind === 'turn_result') {
@@ -385,7 +399,18 @@ export function buildClusters(
       rowOutcome.get(rowIndexFor(index)) === index
     ) {
       marks.push({ kind: 'toolFailed', itemIndex: index, rowIndex: rowIndexFor(index) })
-    } else if (item.kind === 'assistant_text' && item.parentToolUseId == null) {
+    } else if (item.kind === 'assistant_text' && parentOf(item) === frameParentId) {
+      if (frameParentId !== undefined) {
+        // **Inside a frame every narration step is its own mark**, where the
+        // conversation gets one per segment. The segment machinery has nothing
+        // to work with here — a sub-agent's stream carries no prompts and no
+        // `turn_result`, so every step would fold into a single mark at the
+        // final report, which is the one place a reader can already get to. An
+        // agent's rail is a list of what it said on the way, and that is what
+        // makes a fifty-step run navigable.
+        marks.push({ kind: 'turn', itemIndex: index, rowIndex: rowIndexFor(index) })
+        return
+      }
       // The live one included, deliberately: a turn in flight has no turn end
       // yet, which left a two-minute answer unrepresented on the rail for the
       // whole two minutes it was the only thing worth navigating to. The mark's