@workerdeck/ui 0.16.0 → 0.17.0

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
 }
 
@@ -223,6 +242,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,7 +259,15 @@ 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[] {
@@ -246,10 +279,30 @@ function buildClusters(
     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) !== undefined) 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 +320,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) === undefined) {
       closeSegment()
       marks.push({ kind: 'user', itemIndex: index, rowIndex: rowIndexFor(index) })
     } else if (item.kind === 'turn_result') {
@@ -277,13 +345,44 @@ 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) {
@@ -309,8 +408,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 })

package/src/components/terminal/tool-run.ts

@@ -17,6 +17,7 @@
  * `result-preview.ts` exists. Two spellings would be two different heights.
  */
 import type { TranscriptItem } from '@workerdeck/react'
+import { toolInputPreview } from '../../lib/format.ts'
 import { isShellTool } from '../../lib/tool-icon.ts'
 
 type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
@@ -89,3 +90,135 @@ export function runSummary(items: readonly ToolCallItem[], busy: boolean): strin
   // read, 1 shell" reads as though the sentence ended and then carried on.
   return `${verb}${n} tool${n === 1 ? '' : 's'} · ${breakdown}${tail}`
 }
+
+/* ── The task block's one line ─────────────────────────────────────────────
+ *
+ * A `Task` call and everything its subagent produced collapse to one row (see
+ * `blocks.ts`), and these are that row's words. Same contract as `runSummary`:
+ * `height.ts` wraps these exact strings to predict the row's pixel height with
+ * no DOM, so the component must render them verbatim — two spellings would be
+ * two different heights.
+ */
+
+const clip = (text: string, max = 80): string =>
+  text.length > max ? text.slice(0, max - 1) + '…' : text
+
+const trimmed = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+
+/**
+ * The row's identity half: which task this is.
+ *
+ * The Claude SDK's `Task` input carries `subagent_type` (e.g. "Explore") and a
+ * 3–5 word `description`, and both are worth the line: parallel tasks are the
+ * whole reason the block exists, and two rows both reading `Task(…)` answer
+ * nothing. `Task(Explore · find the auth check)` — falling back to the
+ * ordinary input preview when an engine sends neither, so the header is never
+ * emptier than a plain tool row's.
+ */
+export function taskLabel(task: ToolCallItem): string {
+  const input = task.input as { description?: unknown; subagent_type?: unknown } | null
+  const description = trimmed(input?.description)
+  const agent = trimmed(input?.subagent_type)
+  const inner =
+    agent && description
+      ? `${agent} · ${clip(description)}`
+      : (agent ?? (description ? clip(description) : toolInputPreview(task.input)))
+  return `${task.name}(${inner})`
+}
+
+const callBusy = (call: ToolCallItem): boolean =>
+  call.status === 'running' || call.status === 'pending'
+
+/** Did this one call fail? Both spellings are 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 the reducer has not settled yet. */
+export const callFailed = (call: ToolCallItem): boolean =>
+  call.status === 'failed' || call.result?.isError === true
+
+/**
+ * Does a folded run colour red? **Only when its last call failed.**
+ *
+ * It used to be `some`, on the argument that a failure should colour the block
+ * rather than fragment it. The argument was right about not fragmenting and
+ * wrong about `some`: a run is a sequence the model worked through, and a
+ * failure it recovered from two calls later is how work goes — a grep that
+ * matched nothing, a build fixed on the second go. Reddening the whole run for
+ * it means a normal working session is painted red, which spends the colour
+ * that should have been left for the one thing still broken.
+ *
+ * The last call is the run's *outcome*, and an outcome is what a collapsed row
+ * can honestly claim. The failures inside it are not hidden — they are one
+ * press away, each red on its own row, and the recap counts every one. The
+ * **scrubber agrees with this rule** rather than overriding it: it marks a
+ * failed call only when the call is its row's outcome, which for a run is
+ * exactly this one. It used to mark every member on the argument that the
+ * rail asks a different question; against a real session that was nine alarms
+ * on the rail for a transcript reddening one row.
+ */
+export function runFailed(items: readonly ToolCallItem[]): boolean {
+  const last = items[items.length - 1]
+  return last !== undefined && callFailed(last)
+}
+
+/** Is anything inside still going? The call itself, normally — the Task
+ * settles only when its subagent finishes — but a bridged or deferred child
+ * can outlive it, and a pulse that stopped while a child still worked would
+ * read as a hang. */
+export function taskBusy(task: ToolCallItem, children: readonly TranscriptItem[]): boolean {
+  return callBusy(task) || children.some((child) => child.kind === 'tool_call' && callBusy(child))
+}
+
+/**
+ * Does the row colour red? **The task's own outcome, and nothing else.**
+ *
+ * It used to be "or any child call's", which does not survive contact with a
+ * real subagent: an agent that ran a hundred calls, one of them a grep that
+ * matched nothing, came back with a red line saying it had failed. It had not —
+ * it had done exactly what it was asked, and the transcript said otherwise in
+ * the one colour reserved for things that need a human.
+ *
+ * This is the call `SubagentInfo.status` already makes, and it made it for this
+ * reason (see `packages/protocol`): the sub-agent's **own** `tool_result`
+ * `is_error`, deliberately not `taskFailed`. The argument there was that a
+ * nothing-matched grep must not read as a failed run *beside a session name*;
+ * what a hundred-call agent shows is that it must not read that way beside the
+ * `Task` row either. Two surfaces, one rule, one spelling.
+ *
+ * Nothing is concealed by this. A failed child is red on its own row, one press
+ * away, and the recap counts it. The **scrubber follows this rule too** and no
+ * longer marks such a child: a red tick on the rail says precisely what this
+ * row is forbidden from saying. The sub-agent band still says an agent ran
+ * here, and the task's own red tick still says it came back broken — which is
+ * what the two channels are for.
+ */
+export function taskFailed(task: ToolCallItem): boolean {
+  return callFailed(task)
+}
+
+/**
+ * The collapsed task row's one line: identity, then scale.
+ *
+ * `Task(Explore · find the auth check) · 7 tools…` while the subagent works —
+ * the count grows as it does, which is the row's progress reading, and the
+ * trailing ellipsis is the same in-flight signal `runSummary` uses (the pulse
+ * in the gutter carries the beat). Settled, the ellipsis drops:
+ * `… · 7 tools`. "Tools" and not "tool calls" because `runSummary` already
+ * chose that word for the same count one row over.
+ *
+ * The counts are counted from the absorbed children, never read from the
+ * engine's structured Task output — WorkerDeck does not plumb structured tool
+ * results to clients, so a transcript replayed tomorrow must spell the same
+ * line from the same items it holds today.
+ *
+ * With no tool calls yet — the subagent thinking, or only its brief arrived —
+ * the line says `working…`, because `0 tools…` reads as a stall; settled with
+ * none it says `done`.
+ */
+export function taskSummary(task: ToolCallItem, children: readonly TranscriptItem[]): string {
+  const busy = taskBusy(task, children)
+  const calls = children.reduce((n, child) => n + (child.kind === 'tool_call' ? 1 : 0), 0)
+  const label = taskLabel(task)
+  if (calls === 0) return busy ? `${label} · working…` : `${label} · done`
+  return `${label} · ${calls} tool${calls === 1 ? '' : 's'}${busy ? '…' : ''}`
+}

package/src/index.ts

@@ -180,7 +180,8 @@ export {
 export { SessionStatusIcon } from './components/agent/SessionBrowser.tsx'
 // Lifted out of the VS Code sidebar once the dashboard grew a collapsed rail
 // that needs the same glyph — two copies of a trademark set is one too many.
-export { EngineIcon } from './components/agent/EngineIcon.tsx'
+export { EngineIcon, engineMark } from './components/agent/EngineIcon.tsx'
+export { ProjectIcon } from './components/agent/ProjectIcon.tsx'
 export {
   SessionEmptyState,
   type SessionEmptyStateProps,

package/src/styles/terminal.css

@@ -99,6 +99,13 @@
   /* The user's own prompt row. */
   --term-user-bg: rgb(255 255 255 / 0.05);
   --term-row-hover: rgb(255 255 255 / 0.05);
+  /* Behind an OPEN block. Yellow, not neutral, and the theme's one deliberate
+     reuse of that tone for something other than "waiting on you": an open block
+     is a state the reader put the transcript into, and on the phone it wants
+     the same colour as the rail mark that says so. Kept very low — this washes
+     whole regions, and at band strength an opened run would shout louder than
+     anything inside it. */
+  --term-open-wash: rgb(215 186 125 / 0.1);
 }
 
 [data-theme='light'] [data-terminal],
@@ -125,6 +132,7 @@
   --term-band-bg: rgb(0 0 0 / 0.04);
   --term-user-bg: rgb(0 0 0 / 0.05);
   --term-row-hover: rgb(0 0 0 / 0.04);
+  --term-open-wash: rgb(215 186 125 / 0.25);
 }
 
 /* ── Rows ────────────────────────────────────────────────────────────────────
@@ -284,11 +292,30 @@
    stack without a step. (The other half is `useRevealOnOpen`, which brings that
    first line back when it has gone above the fold.) */
 [data-terminal] .term-open {
-  background: var(--term-row-hover);
+  background: var(--term-open-wash);
   margin-inline: calc(-1 * var(--term-bleed, 0px));
   padding-inline: var(--term-bleed, 0px);
 }
 
+/* Another frame of reference: the rows a subagent produced, inside the `Task`
+   that spawned them.
+
+   Two cells of indent, whole — the theme's rule is that horizontal measures are
+   `ch`, and these rows carry markers in a gutter that has to keep landing on the
+   grid the rows above it use. The rule itself is drawn *inside* that padding
+   with an inset shadow rather than as a border, which is what makes the 2ch
+   exact: a 1px border is layout, and would put every nested glyph one pixel off
+   the column for the sake of chrome.
+
+   `--term-faint` rather than the cards `--border` token, and that is the whole
+   reason this class exists: the nested block sits on the *open* block's wash,
+   and a border colour tuned for the base ground resolved to rgb(31,31,31) on it
+   — a rule nobody could see. The same trap `row-hover` is alpha to avoid. */
+[data-terminal] .term-nested {
+  padding-left: 2ch;
+  box-shadow: inset 1px 0 0 var(--term-faint);
+}
+
 .term-hoverable {
   position: relative;
 }
@@ -920,8 +947,8 @@
    as long without a tall solid bar shouting over the rail. A minimum-height
    mark shows only the solid segment, so short and long marks need no separate
    rules; the *lane* stays the pointer's target, so a 2px mark is still
-   findable. Full-width annotations (error, approval) stay solid: they are
-   alarms, not extents. */
+   findable. The alarms (error, approval) stay solid: they are alarms, not
+   extents. */
 .term-scrubber .term-scrub-mark[data-kind='user'] {
   background: linear-gradient(
     to bottom,
@@ -929,6 +956,19 @@
     color-mix(in srgb, var(--term-blue) 25%, transparent) 2px
   );
 }
+/* A sub-agent's stretch of the transcript, in the input lane: green, because
+   every other colour on this rail is already spoken for and none of them means
+   "somebody else's working" — blue is you, white is the answer, red is an
+   alarm, magenta is your bookmark, yellow is the session waiting on you. Drawn
+   as an extent (2px head, 25% tail) like the two marks it shares its geometry
+   with: collapsed it is a tick, expanded it is the band the sub-agent covers. */
+.term-scrubber .term-scrub-mark[data-kind='subagent'] {
+  background: linear-gradient(
+    to bottom,
+    var(--term-green) 0 2px,
+    color-mix(in srgb, var(--term-green) 25%, transparent) 2px
+  );
+}
 .term-scrubber .term-scrub-mark[data-kind='turn'] {
   background: linear-gradient(
     to bottom,
@@ -944,8 +984,8 @@
   );
 }
 .term-scrubber .term-scrub-mark[data-kind='error'] { background: var(--term-red); }
-/* A failed tool call is an alarm, so it is full-width and solid like the rest of
-   them — but at 55%, which is the one thing keeping the rail readable. A session
+/* A failed tool call is an alarm, so it is solid like the rest of them — in the
+   response lane, since it is something the run produced — but at 55%, which is the one thing keeping the rail readable. A session
    error is rare and a turn failure rarer; a tool that failed and was recovered
    from is routine (a grep that matched nothing, a build fixed on the second go),
    and at full strength a normal working session paints the rail solid red and
@@ -1009,3 +1049,33 @@
 [data-term-scrubber-host]::-webkit-scrollbar {
   display: none;
 }
+
+/* ── Images ──────────────────────────────────────────────────────────────────
+ *
+ * A picture a tool returned, drawn in a box of whole lines (`IMAGE_BOX_LINES`,
+ * set inline by `TerminalImage` so the constant has one spelling across the
+ * renderer and the height calculator). The height is on the element and nothing
+ * here may add to it: no margin, no border, no padding — a box that is not
+ * exactly N lines is a row the virtualizer was told the wrong size for.
+ *
+ * `object-fit: contain` with a top-left origin rather than a centred one: the
+ * grid's origin is the top-left of the body cell, and a screenshot floating in
+ * the middle of its box reads as a figure in a document instead of output on a
+ * line. */
+.term-image {
+  display: block;
+  overflow: hidden;
+}
+.term-image > img {
+  max-width: 100%;
+  height: 100%;
+  object-fit: contain;
+  object-position: left top;
+}
+/* The wash is the placeholder's whole visual: it says "something is reserved
+   here" for as long as the bytes are in flight, and it says it at the same
+   height the picture will occupy. */
+.term-image[data-state='pending'],
+.term-image[data-state='failed'] {
+  background: var(--term-band-bg);
+}