@workerdeck/ui 0.16.0 → 0.18.0

package/src/components/terminal/items.tsx

@@ -7,10 +7,32 @@ import { CopyAction, WithActions } from './affordances.tsx'
 import { TerminalDiff } from './diff.tsx'
 import { TerminalMarkdown } from './markdown.tsx'
 import { Pressable, useRevealOnOpen } from './press.tsx'
+import { IMAGE_BOX_LINES, IMAGE_UNAVAILABLE, imagePlaceholder } from './image-box.ts'
 import { collapsedResult } from './result-preview.ts'
-import { foldsTogether, runSummary } from './tool-run.ts'
+import { useToolResultFetcher } from '../agent/tool-result-fetch.tsx'
+import { useToolResultImageSrc } from '../agent/tool-result-image.tsx'
+import { runFailed, runSummary } from './tool-run.ts'
+import { type ToolCallItem } from './blocks.ts'
 import { Band, Blank, Ink, Row, type Tone } from './row.tsx'
 
+// The pure block model — which rows exist — lives in `blocks.ts` now that a
+// task block made it non-trivial; re-exported here because this file is where
+// consumers have always found it.
+export {
+  blockNeedsBlank,
+  isRunCall,
+  needsBlank,
+  parentOf,
+  taskChildItems,
+  terminalBlocks,
+  type ItemBlock,
+  type LeafBlock,
+  type RunBlock,
+  type TaskBlock,
+  type TerminalBlock,
+  type ToolCallItem,
+} from './blocks.ts'
+
 /**
  * One transcript item, drawn as terminal rows.
  *
@@ -44,8 +66,13 @@ import { Band, Blank, Ink, Row, type Tone } from './row.tsx'
 export const PROMPT_GLYPH = '❯'
 
 /** How much the expanded row shows before offering the rest. The collapsed
- * budget is `collapsedResult`'s, shared with the height calculator. */
-const RESULT_PREVIEW_CHARS = 2000
+ * budget is `collapsedResult`'s, shared with the height calculator.
+ *
+ * Exported for one test and not from the package: protocol's
+ * `TOOL_RESULT_HEAD_CHARS` is chosen to exceed it, so that a truncated result's
+ * open state is byte-identical to an untruncated one and only the uncapped
+ * `full` press ever fetches. That relationship is asserted, not assumed. */
+export const RESULT_PREVIEW_CHARS = 2000
 
 /** Whole lines up to a character budget — never zero, because a single line
  * longer than the budget still has to be shown or the row would open onto
@@ -122,11 +149,14 @@ const TOOL_TONE: Record<string, Tone> = {
   failed: 'red',
 }
 
-export type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
-
 export function ToolRow({ item }: { item: ToolCallItem }) {
   const [open, setOpen] = useState(false)
   const [full, setFull] = useState(false)
+  // Set while the rest of a truncated result is in flight. Row-local, unlike the
+  // text itself, which lands in transcript state — this is a spinner, not a
+  // fact about the session.
+  const [fetching, setFetching] = useState(false)
+  const fetchResult = useToolResultFetcher()
   const reveal = useRevealOnOpen(open)
   const status = item.status ?? (item.result === undefined ? 'running' : 'settled')
   const busy = status === 'running' || status === 'pending'
@@ -144,7 +174,9 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
   // the virtualizer mounts rows, so it cannot help with what is inside a single
   // one. Without the clip, expanding one row commits thousands of DOM nodes and
   // the transcript stops being smooth for the rest of the session.
-  const collapsed = collapsedResult(lines)
+  // The true total when the replay delivered only a head — the row must count
+  // what is missing, not what it happens to hold.
+  const collapsed = collapsedResult(lines, item.result?.totalChars)
   const preview = open
     ? full
       ? lines
@@ -152,6 +184,11 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
     : collapsed.shown
   const hidden = lines.length - preview.length
   const clipped = open && !full && hidden > 0
+  // The replay sent a head. `full` then means "fetch the rest", not "lift the
+  // clip" — and the marker outlives the clip, because a head short enough to fit
+  // the open budget still is not the result.
+  const truncated = item.result?.truncated === true
+  const missing = truncated ? (item.result?.totalChars ?? 0) - text.length : 0
 
   const tone: Tone = isError
     ? 'red'
@@ -184,6 +221,13 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
           ) : null}
         </Row>
       </Pressable>
+      {/* Above the output, because when a call returned a picture the picture is
+          what the call was: a screenshot's result text is "took a screenshot".
+          Drawn collapsed as well as open — this is not detail behind a press,
+          it is the answer. */}
+      {item.result?.images?.map((image) => (
+        <TerminalImage key={image.partIndex} toolUseId={item.id} image={image} />
+      ))}
       {/* A file edit shows its diff, not its result prose: "The file has been
           updated" is what the *model* needed to hear, and the change is what the
           reader did. The text stays reachable by expanding. */}
@@ -214,15 +258,30 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
                 {collapsed.more}
               </Row>
             ) : null
-          ) : hidden > 0 ? (
+          ) : clipped || truncated ? (
             <Row indent={1} columns={3} tone='faint'>
-              {clipped ? (
+              {fetching ? (
+                // Never a row that does nothing when pressed: it says what it is
+                // doing instead. See `planToolCall`'s comment on the same rule.
+                <>… fetching {(item.result?.totalChars ?? 0).toLocaleString()} chars</>
+              ) : clipped || truncated ? (
                 <button
                   type='button'
                   className='term-press term-link'
-                  onClick={() => setFull(true)}>
-                  … +{hidden} line{hidden === 1 ? '' : 's'} — show all{' '}
-                  {text.length.toLocaleString()} chars
+                  onClick={() => {
+                    // One press, two acts, in the order that keeps the row
+                    // honest: lift the clip immediately (that part is local and
+                    // instant), and fetch the rest when there is a rest. The
+                    // fetched text lands in transcript state, so the row
+                    // re-renders with the marker gone.
+                    setFull(true)
+                    if (!truncated) return
+                    setFetching(true)
+                    void fetchResult(item.id).finally(() => setFetching(false))
+                  }}>
+                  {truncated
+                    ? `… +${missing.toLocaleString()} chars — fetch the rest`
+                    : `… +${hidden} line${hidden === 1 ? '' : 's'} — show all ${text.length.toLocaleString()} chars`}
                 </button>
               ) : (
                 <>
@@ -230,6 +289,10 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
                 </>
               )}
             </Row>
+          ) : hidden > 0 ? (
+            <Row indent={1} columns={3} tone='faint'>
+              … +{hidden} line{hidden === 1 ? '' : 's'}
+            </Row>
           ) : null}
         </>
       ) : null}
@@ -238,10 +301,41 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
   )
 }
 
-/** 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 {
-  return item.kind === 'tool_call'
+/** One image part of a tool result, as the reducer holds it. */
+type ToolResultImage = NonNullable<NonNullable<ToolCallItem['result']>['images']>[number]
+
+/**
+ * A picture a tool returned, in a box of {@link IMAGE_BOX_LINES} whole lines.
+ *
+ * **Three states, one height.** Before the fetch lands the box is a wash and the
+ * size the gateway declared; after it, the picture, letterboxed inside the same
+ * box; on a refusal, `image unavailable` in it. Nothing here may ever collapse
+ * to nothing — that is `HostImage`'s return-null-then-pop, which in a
+ * *virtualized* list is not a flicker but a reflow of every row below it, and
+ * the height calculator would have been lying about the row from plan time.
+ *
+ * The box is why the calculator can stay exact: it is a constant, not a function
+ * of pixels nobody has downloaded yet.
+ */
+function TerminalImage({ toolUseId, image }: { toolUseId: string; image: ToolResultImage }) {
+  const { src, failed } = useToolResultImageSrc({ toolUseId, ...image })
+  return (
+    <Row indent={1} columns={3}>
+      <div
+        className='term-image'
+        data-state={src ? 'loaded' : failed ? 'failed' : 'pending'}
+        // The one measurement in this file, and it is the shared constant
+        // spelled once — `height.ts` adds exactly this many lines for exactly
+        // this box.
+        style={{ height: `calc(var(--term-line) * ${IMAGE_BOX_LINES})` }}>
+        {src ? (
+          <img src={src} alt={imagePlaceholder(image)} />
+        ) : (
+          <Ink tone='faint'>{failed ? IMAGE_UNAVAILABLE : imagePlaceholder(image)}</Ink>
+        )}
+      </div>
+    </Row>
+  )
 }
 
 /**
@@ -254,10 +348,11 @@ export function isRunCall(item: TranscriptItem): item is ToolCallItem {
  * collapses to its count and gets out of the way — and opens, in full, the
  * moment it is the thing you actually want.
  *
- * The membership and wording rules live in `tool-run.ts`, shared with the height
- * calculator. A failed member does not break the run — it *colours* it, which is
- * the same call the scrubber makes: a failure is worth seeing, and fragmenting
- * the run around it would hide it in a longer list rather than surface it.
+ * The membership, wording and failure rules live in `tool-run.ts`, shared with
+ * the height calculator. A failure never breaks the run — fragmenting it around
+ * one would hide the failure in a longer list rather than surface it — but only
+ * the run's **last** call colours it, because that is the run's outcome and an
+ * outcome is what a collapsed row can honestly claim (see `runFailed`).
  */
 export function ToolRunRow({ items }: { items: ToolCallItem[] }) {
   const [open, setOpen] = useState(false)
@@ -266,7 +361,7 @@ export function ToolRunRow({ items }: { items: ToolCallItem[] }) {
     const status = item.status ?? (item.result === undefined ? 'running' : 'settled')
     return status === 'running' || status === 'pending'
   })
-  const failed = items.some((item) => item.status === 'failed' || item.result?.isError === true)
+  const failed = runFailed(items)
   const pulse = usePulse(busy)
 
   return (
@@ -293,49 +388,6 @@ export function ToolRunRow({ items }: { items: ToolCallItem[] }) {
   )
 }
 
-/**
- * Fold consecutive tool calls into runs, leaving everything else alone.
- *
- * Shared by both renderers — the virtualized shell in `agent/Transcript.tsx` and
- * the plain {@link TerminalTranscript} — because which rows exist is part of what
- * the theme *is*, and a client that grouped differently would be showing a
- * different transcript of the same session.
- */
-export type TerminalBlock =
-  | { key: string; item: TranscriptItem; index: number }
-  | { key: string; run: ToolCallItem[]; index: number }
-
-/**
- * @param offset  What `items[0]`'s index is in the whole transcript — the
- *   virtualized shell folds each side of the recap boundary separately, and the
- *   rows still have to say where they sit for the catch-up dimming.
- * @param fold    Whether to group at all. `false` gives one block per item,
- *   which is what the cards variant renders: this is the terminal theme's rule
- *   and must not silently reshape another renderer's row list.
- */
-export function terminalBlocks(
-  items: readonly TranscriptItem[],
-  offset = 0,
-  fold = true,
-): TerminalBlock[] {
-  const out: TerminalBlock[] = []
-  for (const [position, item] of items.entries()) {
-    const index = offset + position
-    const previous = out.at(-1)
-    if (fold && isRunCall(item)) {
-      if (previous && 'run' in previous && foldsTogether(previous.run[0]!, item)) {
-        previous.run.push(item)
-      } else {
-        // Keyed by the run's *first* call, so the key is stable as the run grows.
-        out.push({ key: `run:${item.id}`, run: [item], index })
-      }
-      continue
-    }
-    out.push({ key: `${item.kind}:${item.id}`, item, index })
-  }
-  return out
-}
-
 export function TurnResultRow({
   item,
 }: {
@@ -390,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
@@ -431,19 +483,4 @@ export function WorkingRow({
   )
 }
 
-/** Spacing between two items: a blank line, unless the pair belongs together.
- * Tool output already sits under its call, and a run of tool calls reads as one
- * block — the CLI leaves no blank line inside either. */
-export function needsBlank(previous: TranscriptItem, next: TranscriptItem): boolean {
-  if (previous.kind === 'tool_call' && next.kind === 'tool_call') return false
-  return true
-}
-
-/** The same rule over blocks: a shell run counts as the tool calls it folded. */
-export function blockNeedsBlank(previous: TerminalBlock, next: TerminalBlock): boolean {
-  const before = 'run' in previous ? 'tool_call' : previous.item.kind
-  const after = 'run' in next ? 'tool_call' : next.item.kind
-  return !(before === 'tool_call' && after === 'tool_call')
-}
-
 export { Band, Blank }

package/src/components/terminal/result-preview.ts

@@ -45,7 +45,16 @@ export type CollapsedResult = {
  * lines otherwise — a one-line JSON blob has no hidden lines to count, and
  * "+0 lines" under a visibly cut-off row is worse than saying nothing.
  */
-export function collapsedResult(lines: string[]): CollapsedResult {
+/**
+ * `totalChars` is the **untruncated** length when the replay delivered only a
+ * head (protocol's `ToolResultBlock.total_chars`). Passing it is not cosmetic:
+ * computed from the head this row would say "… +7,600 chars" where the truth is
+ * 641,003, and the wrong string is a *different pixel height* — which is exactly
+ * the drift this module exists to prevent, since `height.ts` sizes the row by
+ * wrapping this same text. Omitted for a whole result, where the lines are the
+ * whole truth.
+ */
+export function collapsedResult(lines: string[], totalChars?: number): CollapsedResult {
   const shown: string[] = []
   let chars = 0
   let cut = false
@@ -62,11 +71,16 @@ export function collapsedResult(lines: string[]): CollapsedResult {
     chars += line.length + 1
   }
 
-  if (cut) {
-    // `join` because the newlines are part of what is not being shown.
-    const hidden = lines.join('\n').length - chars
-    return { shown, more: `… +${hidden.toLocaleString()} chars` }
-  }
+  // `join` because the newlines are part of what is not being shown — and
+  // `totalChars` wins when it exists, because the lines in hand are then a head
+  // rather than the result.
+  const held = lines.join('\n').length
+  const total = totalChars ?? held
+  if (cut) return { shown, more: `… +${(total - chars).toLocaleString()} chars` }
+  // A truncated result always has more, even when its head happened to fit the
+  // line budget: the row must never claim to be showing everything.
+  if (totalChars !== undefined && total > held)
+    return { shown, more: `… +${(total - chars).toLocaleString()} chars` }
   const hidden = lines.length - shown.length
   return { shown, more: hidden > 0 ? `… +${hidden} line${hidden === 1 ? '' : 's'}` : undefined }
 }

package/src/components/terminal/scrubber.tsx

@@ -3,6 +3,7 @@ import { useStickToBottomContext } from 'use-stick-to-bottom'
 import type { PermissionRequest } from '@workerdeck/protocol'
 import type { TranscriptItem } from '@workerdeck/react'
 import { formatCost, formatDuration, toolInputPreview } from '../../lib/format.ts'
+import { parentOf } from './blocks.ts'
 import { TerminalSurface } from './surface.tsx'
 
 /**
@@ -46,6 +47,7 @@ import { TerminalSurface } from './surface.tsx'
 type Lane = 'l' | 'r' | 'f'
 type MarkKind =
   | 'user'
+  | 'subagent'
   | 'turn'
   | 'turnFailed'
   | 'toolFailed'
@@ -80,26 +82,38 @@ function nearestMember(cluster: Cluster, y: number): Mark | undefined {
 }
 
 /**
- * Two lanes and a full-width annotation, which is a claim about what a rail is
- * *for*: the two things you navigate by are what you asked and what came back,
- * so they get a lane each and split the rail evenly. Everything else — an error,
- * a waiting approval, a bookmark, the catch-up seam — is an **annotation on the
- * run** rather than a step through it, so it spans the full width and reads as
- * a different class of thing rather than as a third column of steps.
+ * The two lanes are **channels, not classes**: left is what went *in* — your
+ * prompts, and the sub-agents you dispatched — and right is what came *out* —
+ * each turn's answer, and everything that went wrong producing one. That is the
+ * question a reader actually asks of a rail ("where did I say something", "where
+ * did it go wrong"), and it puts every failure in one column instead of
+ * scattering some down the middle.
+ *
+ * Full width is reserved for what is not a channel at all: a waiting approval
+ * (which is the session asking *you*, pinned at the foot), a bookmark (the
+ * reader's own annotation) and the catch-up seam (a boundary across both).
  *
  * It also buys the marks their width back: three lanes in a 16px rail is 5px a
  * lane, which is a hard target to hit and a hard colour to see.
  */
 const LANE: Record<MarkKind, Lane> = {
   user: 'l',
+  // Delegated work is input: a sub-agent runs because you asked for it, and its
+  // stretch of the transcript is *your* dispatch rather than the session's
+  // answer. It also gives a folded `Task` its one honest signal on the rail —
+  // collapsed, sixty rows of somebody else's working are one line, and this is
+  // the mark that says the region is there at all.
+  subagent: 'l',
   turn: 'r',
   turnFailed: 'r',
-  // Full-width, like every other alarm: a failed tool call is something that
-  // went wrong *during* a step, not a step you scroll between. A lane mark would
-  // also put it in the response lane, where it would compete with the turn marks
-  // that are the rail's actual navigation.
-  toolFailed: 'f',
-  error: 'f',
+  // Output, with the answers: a failed tool call is something the run produced.
+  // It had been full-width on the argument that it is an alarm rather than a
+  // step — but "alarm" is not a lane, and half the failures ending up down the
+  // middle while `turnFailed` sat in the right lane meant no single column
+  // answered "did anything go wrong". Its rank in LOUDNESS and its 55% strength
+  // are what keep it from shouting over the turns it now sits beside.
+  toolFailed: 'r',
+  error: 'r',
   approval: 'f',
   recap: 'f',
   bookmark: 'f',
@@ -115,17 +129,22 @@ const LOUDNESS: Record<MarkKind, number> = {
   // keep the cluster. (It cannot merge with `turnFailed` — that is lane `r`, and
   // merging is per lane.) A failed tool call the model recovered from is routine
   // in a way a session error is not, hence quieter here and at 55% in the CSS.
-  // The one thing it does outrank is `bookmark`, which loses its magenta to a
-  // failure it sits beside.
+  // It now shares the response lane with the turn marks, which is the rank that
+  // matters: a failure a pixel from a turn end keeps the cluster red.
   toolFailed: 4,
   user: 3,
   turn: 2,
   bookmark: 1,
+  // Lane `l`, so this is only ever weighed against `user`, and a prompt wins:
+  // the prompt is the step you navigate by and the sub-agent band is the
+  // annotation on it. (It ties with `bookmark`, which it can never meet.)
+  subagent: 1,
   recap: 0,
 }
 
 const KIND_NAME: Record<MarkKind, string> = {
   user: 'you',
+  subagent: 'sub-agent',
   turn: 'response · turn end',
   turnFailed: 'turn failed',
   toolFailed: 'tool failed',
@@ -163,7 +182,7 @@ const MIN_MARK = 2
  * never exceed `railH` again, for any content, because `viewportH` can never
  * exceed the denominator.
  */
-function railScale(railH: number, totalSize: number, viewportH: number): number {
+export function railScale(railH: number, totalSize: number, viewportH: number): number {
   return totalSize > 0 ? railH / Math.max(totalSize, viewportH) : 0
 }
 
@@ -214,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
@@ -223,6 +255,12 @@ export interface TerminalScrubberProps {
   /** A virtual row's height in content space, same source — what a mark's own
    * height is scaled from. */
   sizeOfRow: (rowIndex: number) => number
+  /** Where an item sits inside a row shared with other items — a task block's
+   * absorbed child or a folded run's member (`positionInRow` in
+   * `agent/transcript-rows.ts`). Optional and additive: without it every mark
+   * spans its row's extent, which for an expanded task block is the whole
+   * subagent area. */
+  positionInRow?: (itemIndex: number) => { ordinal: number; count: number } | undefined
   totalSize: number
   scrollOffset: number
   viewportH: number
@@ -234,22 +272,51 @@ export interface TerminalScrubberProps {
   lineHeight?: number
 }
 
-function buildClusters(
+/**
+ * Exported for `test/scrubber.test.ts` and nothing else — it is not part of the
+ * package's surface (`index.ts` does not re-export it). Both of the bugs this
+ * function has shipped were pure-logic ones a unit test catches: a live answer
+ * with no `turn_result` yet went unmarked for the whole two minutes it was the
+ * only thing worth navigating to, and a replayed history — which carries no turn
+ * rows at all — came back with an empty right lane.
+ */
+export function buildClusters(
   props: TerminalScrubberProps,
   railH: number,
 ): Cluster[] {
   const {
     items,
     bookmarks,
+    frameParentId,
     recapRow,
     pendingApprovals,
     rowIndexFor,
     offsetOfRow,
     sizeOfRow,
+    positionInRow,
     totalSize,
     viewportH,
   } = props
   const marks: Mark[] = []
+  // Which top-level calls a sub-agent ran inside — by `parentToolUseId` and
+  // never by the spawning call's *name*: the SDK's own convention is `Task`,
+  // but it is a convention (a background agent arrives as `Agent`), and an id
+  // that other items demonstrably nest under IS a sub-agent whatever spawned
+  // it. The same membership rule `terminalBlocks` folds by, for the same reason.
+  const subagentParents = new Set<string>()
+  for (const item of items) {
+    const parent = parentOf(item)
+    if (parent !== undefined) subagentParents.add(parent)
+  }
+  // The **outcome** call of each row: the last top-level tool call the row
+  // holds. A failed call is marked only when it is one of these — see the
+  // `toolFailed` branch below for why, and note this needs no block lookup,
+  // only `rowIndexFor`.
+  const rowOutcome = new Map<number, number>()
+  items.forEach((item, index) => {
+    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
   // is closed by the next prompt, by its own turn end, or by running out of
   // items — that last one is what a replayed history is made of.
@@ -267,7 +334,22 @@ function buildClusters(
     segment = {}
   }
   items.forEach((item, index) => {
-    if (item.kind === 'user') {
+    // The dispatch itself, marked at its row — which is the folded `Task`
+    // block, so the band grows to the whole sub-agent area when it is opened
+    // and shrinks back to a tick when it is closed. Deliberately NOT part of
+    // the chain below: a `Task` whose own result errored earns a red tick in
+    // the response lane *and* this band in the input lane, which is the whole
+    // point of the two channels — one says a sub-agent ran here, the other says
+    // it came back broken. A failed child inside it still marks separately, at
+    // its own fraction of the row.
+    if (item.kind === 'tool_call' && subagentParents.has(item.id)) {
+      marks.push({ kind: 'subagent', itemIndex: index, rowIndex: rowIndexFor(index) })
+    }
+    // Top-level prompts only, like the answer check below: a subagent's brief
+    // 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) === frameParentId) {
       closeSegment()
       marks.push({ kind: 'user', itemIndex: index, rowIndex: rowIndexFor(index) })
     } else if (item.kind === 'turn_result') {
@@ -277,16 +359,58 @@ function buildClusters(
     } else if (item.kind === 'notice' && item.level === 'error') {
       marks.push({ kind: 'error', itemIndex: index, rowIndex: rowIndexFor(index) })
     } else if (
-      // The same predicate the row itself reddens with (`items.tsx`), and the
-      // same one the recap counts errors by — the two spellings are not
-      // redundant: an out-of-loop execution failure sets `status` with no
-      // `is_error` block to read, and an engine can flag `is_error` on a call
-      // this reducer has not settled yet.
+      // **The rail marks what the transcript reddens** — the whole rule, and
+      // why this is not simply the per-call predicate it used to be.
+      //
+      // The row model already decided, twice, that a routine failure the model
+      // recovered from is not a failure: `runFailed` colours a folded run by
+      // its LAST call, and `taskFailed` colours a `Task` by its OWN result and
+      // never a child's. Both were changed from `contains` for the same reason
+      // — a normal working session came back painted red, spending the colour
+      // that should have been left for the one broken thing on a grep that
+      // matched nothing. The rail was deliberately exempted, on the argument
+      // that its question ("is there anything worth navigating to") differs
+      // from the row's ("how did this end").
+      //
+      // Measured against a real session, the exemption did not survive: 178
+      // tool calls, 9 failed, EIGHT OF THE NINE recovered from inside their own
+      // run, no failed turn and no session error — nine alarms on the rail for
+      // a transcript that reddens one row. A red mark beside nothing red is
+      // worse than no mark: it sends a reader hunting for damage that is not
+      // there.
+      //
+      // One uniform test covers all three cases: a call is its row's OUTCOME
+      // when it is top level and no later top-level call shares its row. For a
+      // folded run that is exactly `runFailed`'s last member; for a lone call
+      // it is the call; and for a `Task` it is the task itself, because its
+      // children are not top level — which is `taskFailed`, spelled a third way
+      // and agreeing. A failed child inside a sub-agent is therefore no longer
+      // marked, the same call `taskFailed` makes. The sub-agent band still says
+      // it ran and its own red tick still says it came back broken, every
+      // failure is still red on its own row, and the recap still counts them
+      // all.
+      //
+      // The disjunction is unchanged and both spellings are still needed: an
+      // out-of-loop execution failure sets `status` with no `is_error` block to
+      // read, and an engine can flag `is_error` on a call this reducer has not
+      // settled yet.
       item.kind === 'tool_call' &&
-      (item.status === 'failed' || item.result?.isError === true)
+      (item.status === 'failed' || item.result?.isError === true) &&
+      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
@@ -309,8 +433,30 @@ function buildClusters(
     // A mark's height is its row's, at rail scale, floored at the hit target —
     // the row the mark *anchors* (for a turn, the final response), which is
     // where the reader lands and what they came to gauge the size of.
-    const h = Math.max(MIN_MARK, Math.round(sizeOfRow(mark.rowIndex) * scale))
-    const y = Math.min(Math.max(0, railH - h), Math.round(offsetOfRow(mark.rowIndex) * scale))
+    //
+    // EXCEPT an item that SHARES its row (a task block's absorbed child, a
+    // folded run's member): there the row's extent is mostly other items' work,
+    // and expanded it is the entire subagent area — one failed child of a
+    // hundred-call task used to paint a solid red band down the whole rail.
+    // Such a mark is a tick at its fractional position within the row.
+    // `sizeOfRow` is the virtualizer's *measurement*, so expansion is reflected
+    // with no expansion state here (which the scrubber deliberately cannot see,
+    // `height.ts`'s "unmounted is collapsed" invariant being load-bearing):
+    // collapsed, the fraction rounds onto the row's one line and siblings merge
+    // exactly as before; expanded, the ticks distribute down the block —
+    // approximately, since children differ in height, which a 12px rail cannot
+    // show and exactness would cost the scrubber the one thing it must not know.
+    // Applied here rather than per kind because a bookmark on an absorbed child
+    // has the identical bug; `recap` is `itemIndex: -1`, hence the guard.
+    const within = mark.itemIndex >= 0 ? positionInRow?.(mark.itemIndex) : undefined
+    const rowH = sizeOfRow(mark.rowIndex)
+    const h = within ? MIN_MARK : Math.max(MIN_MARK, Math.round(rowH * scale))
+    const y = Math.min(
+      Math.max(0, railH - h),
+      Math.round(
+        (offsetOfRow(mark.rowIndex) + (within ? (within.ordinal / within.count) * rowH : 0)) * scale,
+      ),
+    )
     const lane = LANE[mark.kind]
     const list = lanes.get(lane) ?? []
     list.push({ mark, y, h })