@workerdeck/ui 0.20.0 → 0.21.0

package/src/components/agent/SessionPanel.tsx

@@ -251,14 +251,51 @@ export interface SessionPanelProps {
    * need a live closure at the far end. Same shape and same reason as
    * {@link SessionPanelProps.reveal}.
    *
-   * Hosts must clear their request on a session switch: a stale one replayed at
-   * remount would open a frame the new transcript cannot answer.
+   * **Withdrawing the request closes the frame.** The prop going away without a
+   * remount is itself a request — "the conversation, plainly" — and it leaves
+   * through the same path Back takes, so the reader lands on the Task row they
+   * came from. It has to mean that, because a host that keeps its request in
+   * route state (the dashboard's `?subagent=`) has exactly one way to say it:
+   * clear the search — which is what the sidebar's plain session click already
+   * navigated with, and what the browser's Back button re-arrives on. Before
+   * this, both were silently ignored and the frame outlived the address that
+   * claimed it was gone. Still not a controlled value: the panel enters and
+   * leaves frames on its own and *reports* through
+   * {@link SessionPanelProps.onSubagentChange}; only a **change** of the prop
+   * is a request.
+   *
+   * Hosts must still clear their request on a session switch: a stale one
+   * replayed at remount would open a frame the new transcript cannot answer.
    *
    * Claude-only in practice, and gated by data rather than by a flag — codex and
    * provider sessions have no `parentToolUseId`, so they grow no task blocks and
    * no sub-agent rows, and nothing can raise this.
    */
   openSubagent?: { toolUseId: string; nonce: number }
+  /**
+   * Which sub-agent the panel now has framed, or `undefined` for the session's
+   * own conversation — the outward half of
+   * {@link SessionPanelProps.openSubagent}, and a *statement* where that one is
+   * a *request*. Deliberately not an echo: the panel enters frames the host
+   * never asked for (a Task row pressed in the transcript) and leaves them on
+   * its own (Back, Escape, a reveal), so a host that tracked only its own
+   * requests would be wrong within one click. No nonce, for the same reason —
+   * a state that arrives twice is the same state, where a request that arrives
+   * twice is two requests.
+   *
+   * Never fired for a fresh mount's initial `undefined`, and never fired from
+   * an unmount. The first would be a lie with consequences: the seeding effect
+   * consumes `openSubagent` in the same commit, so for one commit the state is
+   * `undefined` even though a frame is about to open, and a host folding
+   * reports into route state would clear the very `?subagent=` request the
+   * panel is in the middle of honouring. The second lets a panel keyed away on
+   * a session switch stomp what the host already believes about the next one.
+   * See the notify effect for the mechanics.
+   *
+   * What the sessions list's secondary selection feeds on: the row of the agent
+   * on screen takes the blue and its session's card steps back to grey.
+   */
+  onSubagentChange?: (toolUseId: string | undefined) => void
   /**
    * Terminal theme only: hold the prompt of the turn you are reading at the top
    * of the transcript, as the Claude Code CLI does. The **real row** is pinned
@@ -475,6 +512,7 @@ export function SessionPanel({
   scrubberMarks,
   reveal,
   openSubagent,
+  onSubagentChange,
   stickyPrompt = false,
   controlsSurface = 'internal',
   onControls,
@@ -548,14 +586,35 @@ export function SessionPanel({
     setReturnReveal(undefined)
   }, [sessionId])
 
-  // The host asking. Keyed on the nonce, so asking twice for the same agent
-  // works — and so a request that arrives while another frame is open swaps it
-  // in place rather than being ignored.
+  // Every way out of the frame that carries no destination of its own — Back,
+  // Escape, a withdrawn request — funnels through here, so they all land the
+  // reader on the Task row they entered from. A reveal is the one exit that
+  // doesn't: it brought its own destination.
+  const leaveSubagent = useCallback(() => {
+    setSubagentId((current) => {
+      if (current !== undefined) setReturnReveal({ toolUseId: current, nonce: Date.now() })
+      return undefined
+    })
+  }, [])
+
+  // The host asking — or withdrawing the ask. Keyed on the nonce, so asking
+  // twice for the same agent works — and so a request that arrives while
+  // another frame is open swaps it in place rather than being ignored.
+  //
+  // A withdrawn request (the prop going away without a remount) CLOSES the
+  // frame — see the prop's docblock for why a host keeping its request in
+  // route state needs that to be true. Two non-cases are worth naming because
+  // they look like hazards and are not: on a fresh mount with no request this
+  // fires once and `leaveSubagent` finds nothing framed, so first render
+  // cannot wipe anything; and a host *echoing* the panel's own report back
+  // (the dashboard folding `onSubagentChange` into `?subagent=`) re-arrives
+  // with the nonce unchanged, so this effect never re-runs for it — the echo
+  // is inert by construction, not by a same-value bail-out.
   const openSubagentNonce = openSubagent?.nonce
   const openSubagentId = openSubagent?.toolUseId
   useEffect(() => {
-    if (openSubagentId === undefined) return
-    setSubagentId(openSubagentId)
+    if (openSubagentId === undefined) leaveSubagent()
+    else setSubagentId(openSubagentId)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [openSubagentNonce])
 
@@ -569,13 +628,6 @@ export function SessionPanel({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [revealNonce])
 
-  const leaveSubagent = useCallback(() => {
-    setSubagentId((current) => {
-      if (current !== undefined) setReturnReveal({ toolUseId: current, nonce: Date.now() })
-      return undefined
-    })
-  }, [])
-
   // Escape leaves the frame — the keyboard half of Back. `defaultPrevented`
   // keeps a dialog's own Escape (and the composer's) ahead of it: this is the
   // outermost thing Escape can mean here, so it goes last.
@@ -589,6 +641,32 @@ export function SessionPanel({
     return () => window.removeEventListener('keydown', onKey)
   }, [subagentId, leaveSubagent])
 
+  // The report out — see the prop's docblock for what it claims. Fired off the
+  // STATE rather than from each exit path, because the state is the only place
+  // all four ways out and both ways in already meet; a notification hung on
+  // the affordances would go stale the first time someone added a fifth.
+  //
+  // The ref pair is the mount guard, and it is load-bearing. On a deep-linked
+  // mount, `subagentId` is `undefined` for the whole first commit — the
+  // seeding effect above runs in that same commit and its setState lands in
+  // the next one — so a naive `useEffect(..., [subagentId])` reports
+  // `undefined` first, the host clears the `?subagent=` it was asked with,
+  // and the withdrawal closes the frame the reader just requested. The ref
+  // starts at `undefined`, so the first commit is silent by construction —
+  // not by effect ordering, which is why this works wherever it sits relative
+  // to the seeding effect (and under StrictMode's double mount). No cleanup
+  // report on unmount, deliberately: hosts key this panel by session, and a
+  // departing panel announcing "nothing framed" would stomp whatever the host
+  // already holds for the next one.
+  const onSubagentChangeRef = useRef(onSubagentChange)
+  onSubagentChangeRef.current = onSubagentChange
+  const reportedSubagentId = useRef<string | undefined>(undefined)
+  useEffect(() => {
+    if (reportedSubagentId.current === subagentId) return
+    reportedSubagentId.current = subagentId
+    onSubagentChangeRef.current?.(subagentId)
+  }, [subagentId])
+
   // Catch-up is entered once, from the watermark the embedder handed over, and
   // left when dismissed or when the user sends anything (they are plainly
   // caught up at that point). Snapshotted into state rather than read from the

package/src/components/agent/SessionStatusIcon.tsx

@@ -0,0 +1,43 @@
+import { BellRing, CircleAlert, CircleSlash, Moon, PauseCircle } from 'lucide-react'
+import type { SessionRow } from '@workerdeck/protocol'
+import { Spinner } from '../ui/Spinner.tsx'
+import { cn } from '../../lib/utils.ts'
+
+/**
+ * State as one glyph — a ringing bell when it wants a human, a spinner while it
+ * works, a moon when it is only sleeping. Replaces the text badge: in a sidebar
+ * the word costs more room than it earns, and the states that matter are the two
+ * you can recognise without reading.
+ *
+ * **It reads `row.state`, not `info.status`, and that distinction is the whole
+ * point of the row model.** `sessionState` already folds in the arm this glyph
+ * cannot see for itself: a *background* sub-agent outlives its turn by design,
+ * so the turn ends, `status` comes to rest at `idle`, and the agent keeps
+ * working. Reading the raw status drew a **moon on a row filed under the
+ * "Working" header** — the list contradicting itself on one line, which is
+ * exactly what a derived view model exists to prevent. The value was in scope
+ * and unread.
+ *
+ * The terminal statuses still come off `info.status`, because `ended` collapses
+ * `failed` and `closed` into one bucket and those are worth telling apart here.
+ *
+ * It lives in its own file rather than inside the dashboard's browser because
+ * the extension's cards draw it too, and a second copy there is how the two
+ * lists last disagreed about what a parked session looks like.
+ */
+export function SessionStatusIcon({ row, className }: { row: SessionRow; className?: string }) {
+  const { info } = row
+  const size = cn('size-4 shrink-0', className)
+  if (row.state === 'attention') return <BellRing className={cn(size, 'animate-pulse text-warning')} />
+  if (row.state === 'working') return <Spinner className={cn(size, 'text-info')} />
+  switch (info.status) {
+    case 'failed':
+      return <CircleAlert className={cn(size, 'text-danger')} />
+    case 'closed':
+      return <CircleSlash className={cn(size, 'text-fg-4')} />
+    case 'parked':
+      return <PauseCircle className={cn(size, 'text-fg-3')} />
+    default:
+      return <Moon className={cn(size, 'text-fg-4')} />
+  }
+}

package/src/components/agent/SessionSteps.tsx

@@ -59,23 +59,46 @@ export type Step = {
   onSelect: () => void
 }
 
+/**
+ * The steps under one session, **agents first**.
+ *
+ * The two kinds do different things when pressed and are worth different
+ * amounts of attention: an agent has work of its own to go and read, a task is a
+ * marker in a transcript. Interleaved in dispatch order they read as one
+ * undifferentiated list, and the rows you can actually open are scattered
+ * through it. Grouped, the openable ones are a block at the top and the markers
+ * are a tail you can skip.
+ *
+ * Stable **within** each group, deliberately: dispatch order is the only order
+ * these records have that means anything (it is the order the work was started
+ * in), so the sort partitions and never reorders inside a partition.
+ *
+ * `onSelect` is handed the **kind** as well as the id, because the two kinds go
+ * to different places — see `SessionItem`, which is what routes them. Passing
+ * only the id is what let a task be opened as if it were an agent, and a framed
+ * task id matches no items, so the panel drew an **empty agent view**.
+ */
 export function sessionSteps(
   info: SessionInfo,
-  onSelectSubagent: (toolUseId: string) => void,
+  onSelect: (toolUseId: string, kind: Step['kind']) => void,
 ): Step[] {
   // The label is protocol's `subagentLabel`, not a spelling of its own: the
   // dashboard and the phone render the same rows from the same records, and two
   // spellings would be two different answers to "which agent is this".
-  return (info.subagents ?? []).map((sub) => ({
-    key: sub.toolUseId,
-    label: subagentLabel(sub),
-    noun: 'agent',
-    kind: isAgentRecord(sub) ? ('agent' as const) : ('task' as const),
-    state: stepState(sub.status),
-    detail: sub.toolCount > 0 ? String(sub.toolCount) : undefined,
-    title: `${subagentLabel(sub)} · ${sub.toolCount} tool${sub.toolCount === 1 ? '' : 's'}`,
-    onSelect: () => onSelectSubagent(sub.toolUseId),
-  }))
+  const steps = (info.subagents ?? []).map((sub) => {
+    const kind = isAgentRecord(sub) ? ('agent' as const) : ('task' as const)
+    return {
+      key: sub.toolUseId,
+      label: subagentLabel(sub),
+      noun: 'agent',
+      kind,
+      state: stepState(sub.status),
+      detail: sub.toolCount > 0 ? String(sub.toolCount) : undefined,
+      title: `${subagentLabel(sub)} · ${sub.toolCount} tool${sub.toolCount === 1 ? '' : 's'}`,
+      onSelect: () => onSelect(sub.toolUseId, kind),
+    }
+  })
+  return [...steps.filter((s) => s.kind === 'agent'), ...steps.filter((s) => s.kind === 'task')]
 }
 
 function stepState(status: SubagentInfo['status']): Step['state'] {
@@ -142,8 +165,8 @@ export function StepToggle({
         onToggle()
       }}
       className={cn(
-        'flex shrink-0 items-center gap-0.5 rounded px-0.5 outline-none',
-        'hover:bg-surface-hover hover:text-fg-2',
+        'flex shrink-0 items-center gap-0.5 rounded-[4px] py-0.5 pr-1 pl-0.5 outline-none',
+        'text-[0.75rem] leading-3 hover:bg-row-hover hover:text-fg-2',
         running > 0 ? 'text-info' : 'text-fg-4',
       )}>
       <Chevron className='size-3' />
@@ -153,20 +176,58 @@ export function StepToggle({
 }
 
 /**
- * One step under its session. Pressing an **agent** hands the panel over to that
- * agent's own work — it is not a session and never becomes one, but it does now
- * have a surface (`SessionPanel.openSubagent`). A host that cannot frame one
- * falls back to revealing its `Task` row, which was this row's only meaning
- * before the takeover existed. A **task** is not pressable at all; see
- * {@link Step.kind}.
+ * One step under its session — **pressable, all of them**, and what a press
+ * means is what tells the two kinds apart.
+ *
+ * Pressing an **agent** hands the panel over to that agent's own work
+ * (`SessionPanel.openSubagent`): it is not a session and never becomes one, but
+ * it has a surface, so it can be the selected thing. Pressing a **task** selects
+ * the *session* and travels to that task's marker inside it — a task is a
+ * reference to a place in a transcript, not a thing with a screen, so it can be
+ * followed but never held.
+ *
+ * That is a reversal, and a deliberate one. A task used to be inert markup on
+ * the argument that "a disabled-looking button still announces itself as one" —
+ * correct about the markup, wrong about the premise, because there *was* always
+ * somewhere to go and the row simply swallowed the click on its way there. A row
+ * that looks like a list item, sits in a list, and does nothing when pressed is
+ * the worse lie. So every step answers the pointer and every step answers a
+ * press; only what the press does differs.
+ *
+ * Divided from the card's header by **indentation and its own hit shape**, not
+ * by a rule. The rules came first, on the argument that at 11px an indent is not
+ * enough to say "list inside a row" — and they were right about the reading and
+ * wrong about the cost: a stack of hairlines across every open card turned the
+ * list into a ledger, and a rule cannot answer a pointer. A step that lights up
+ * under the cursor and fills when it is the one on screen says *list* far more
+ * plainly than a line between two of them, and it says it while doing the job
+ * the rule could not.
  *
- * Divided from the row's header and from each other by a rule rather than by
- * indentation: these are a list *inside* the row, and at 11px an indent is not
- * enough to say so. The rule is black at 25% so it darkens whatever the row is
- * filled with, selected or not, without needing a colour per state.
+ * **Only an agent can wear the selection**, and `active` is guarded on that here
+ * rather than trusted from the caller: a host that hands back a task's key is
+ * describing where it navigated, not what it selected, and the row must not
+ * paint itself blue for it.
+ *
+ * The hover is `--row-active` — **alpha, not a flat fill** — because this row
+ * has to answer the pointer on three different grounds: a transparent card, a
+ * blue one (its session is selected), and a grey one (a sibling agent is). A
+ * flat value tuned for any of those is wrong on the other two; a tint darkens or
+ * lifts whatever it lands on. It is the one place in the list where the alpha
+ * token earns its keep.
  */
-export function StepRow({ step, onSelect }: { step: Step; onSelect: () => void }) {
+export function StepRow({
+  step,
+  active = false,
+  onSelect,
+}: {
+  step: Step
+  /** The panel is showing this step's own work. Ignored for tasks, which cannot
+   * be the selected thing — see above. */
+  active?: boolean
+  onSelect: () => void
+}) {
   const agent = step.kind === 'agent'
+  const selected = active && agent
   // Body colour by *kind*, state carried by the icon — the rule the transcript's
   // own `TaskRow` already follows, where the body is green and the marker holds
   // the beat. Green means sub-agent across this product (it is the one hue
@@ -174,42 +235,32 @@ export function StepRow({ step, onSelect }: { step: Step; onSelect: () => void }
   // "running" here would be saying something different from the transcript
   // about the same agent. Failure still outranks it: an alarm is not a category.
   const body = step.state === 'failed' ? 'text-danger' : agent ? 'text-success' : 'text-fg-4'
-  const content = (
-    <>
-      <StepIcon state={step.state} kind={step.kind} />
-      <span className='min-w-0 flex-1 truncate'>{step.label}</span>
-      {/* The progress reading while it works, and what it cost when it is done.
-          Zero draws nothing: `0 tools` beside a thinking agent reads as a stall,
-          which is the same call `taskSummary` makes one surface over. */}
-      {step.detail ? <span className='shrink-0 tabular-nums text-fg-4'>{step.detail}</span> : null}
-      {agent ? <ArrowRight className='size-3 shrink-0 opacity-60' /> : null}
-    </>
-  )
-  const shape =
-    'flex w-full items-center gap-2 border-t border-black/25 py-1 pl-3 pr-2 text-left text-label outline-none'
-
-  // A task is not a button, in the markup and not merely in the styling: there
-  // is nothing to press, and a disabled-looking button still announces itself as
-  // one. It stops the click all the same — the whole session row is pressable
-  // underneath, so falling through would open the session from a row that says
-  // it does nothing.
-  if (!agent) {
-    return (
-      <div title={step.title} onClick={(e) => e.stopPropagation()} className={cn(shape, body)}>
-        {content}
-      </div>
-    )
-  }
   return (
     <button
       type='button'
       title={step.title}
+      aria-current={selected || undefined}
       onClick={(e) => {
+        // The whole card is pressable underneath and means "open the session".
+        // This row has its own answer — for an agent a different destination,
+        // for a task the same one plus a place to land — so it must not also
+        // fire the card's.
         e.stopPropagation()
         onSelect()
       }}
-      className={cn(shape, 'hover:bg-surface-hover', body)}>
-      {content}
+      className={cn(
+        'flex w-full items-center gap-1.5 rounded-[4px] py-1 pr-2.5 pl-3.5',
+        'text-left text-micro outline-none',
+        selected ? 'bg-row-selected' : 'hover:bg-row-active',
+        body,
+      )}>
+      <StepIcon state={step.state} kind={step.kind} />
+      <span className='min-w-0 flex-1 truncate'>{step.label}</span>
+      {/* The progress reading while it works, and what it cost when it is done.
+          Zero draws nothing: `0 tools` beside a thinking agent reads as a stall,
+          which is the same call `taskSummary` makes one surface over. */}
+      {step.detail ? <span className='shrink-0 tabular-nums text-fg-4'>{step.detail}</span> : null}
+      {agent ? <ArrowRight className='size-3.5 shrink-0 text-fg-4' /> : null}
     </button>
   )
 }
@@ -218,16 +269,16 @@ function StepIcon({ state, kind }: { state: Step['state']; kind: Step['kind'] })
   // A task that is neither running nor failed gets a neutral dot rather than a
   // tick: `done` is a claim about work, and nothing here did any.
   if (kind === 'task' && state !== 'running' && state !== 'failed') {
-    return <Dot className='size-3 shrink-0' />
+    return <Dot className='size-[11px] shrink-0' />
   }
   switch (state) {
     case 'running':
-      return <Spinner className='size-3 shrink-0' />
+      return <Spinner className='size-[11px] shrink-0' />
     case 'failed':
-      return <CircleAlert className='size-3 shrink-0' />
+      return <CircleAlert className='size-[11px] shrink-0' />
     case 'pending':
-      return <PauseCircle className='size-3 shrink-0' />
+      return <PauseCircle className='size-[11px] shrink-0' />
     default:
-      return <Check className='size-3 shrink-0' />
+      return <Check className='size-[11px] shrink-0' />
   }
 }

package/src/components/agent/SessionWorkspace.tsx

@@ -43,6 +43,13 @@ export interface SessionWorkspaceProps {
   stickyPrompt?: SessionPanelProps['stickyPrompt']
   /** Take the panel body over with one sub-agent's work — see `SessionPanel`. */
   openSubagent?: SessionPanelProps['openSubagent']
+  /** Travel to a row in the conversation without framing anything — where a
+   * **task** press lands, as opposed to `openSubagent`'s takeover. See
+   * `SessionPanel`. */
+  reveal?: SessionPanelProps['reveal']
+  /** The outward half of `openSubagent`: which sub-agent the panel now has
+   * framed, or `undefined` for the conversation — see `SessionPanel`. */
+  onSubagentChange?: SessionPanelProps['onSubagentChange']
   /** Which end of the panel the status bar sits at — see `SessionPanel`. */
   statusPlacement?: SessionPanelProps['statusPlacement']
   controlsSurface?: SessionPanelProps['controlsSurface']
@@ -106,6 +113,8 @@ export function SessionWorkspace({
   scrubberMarks,
   stickyPrompt,
   openSubagent,
+  reveal,
+  onSubagentChange,
   statusPlacement,
   controlsSurface,
   unseen,
@@ -311,6 +320,8 @@ export function SessionWorkspace({
           scrubberMarks={scrubberMarks}
           stickyPrompt={stickyPrompt}
           openSubagent={openSubagent}
+          reveal={reveal}
+          onSubagentChange={onSubagentChange}
           controlsSurface={controlsSurface}
           statusPlacement={statusPlacement}
           unseen={unseen}

package/src/index.ts

@@ -177,7 +177,11 @@ export {
   rowShapeClass,
   type SessionBrowserProps,
 } from './components/agent/SessionBrowser.tsx'
-export { SessionStatusIcon } from './components/agent/SessionBrowser.tsx'
+// The session card itself — one component, every client. `SessionBrowser` is the
+// dashboard's list *around* it; a host that wants only the card (the VS Code
+// sidebar does, because the filtering chrome above it is native) takes this.
+export { SessionItem, type SessionItemProps } from './components/agent/SessionItem.tsx'
+export { SessionStatusIcon } from './components/agent/SessionStatusIcon.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 {

package/src/styles/theme.css

@@ -30,14 +30,48 @@
   --bg-code: #f5f5f5;
   --bg-elevated: #ffffffcc;
 
-  /* A list row's hover and selected fills. **Alpha, not a flat colour**, because
-     a row sits on whatever its host paints — `bg-sidebar` in the dashboard,
-     `--vscode-sideBar-background` in the extension — and a flat value tuned for
-     one of those is invisible on the others. `--bg-surface-hover` was exactly
-     that mistake: on the dark sidebar (#131313) it lands on #141414, one step
-     of 255 away, so the hover state did not exist. */
-  --row-hover: rgb(0 0 0 / 0.05);
+  /* A list row's fills.
+
+     `--row-hover` is the **flat** value the design specifies (VS Code's
+     `list.hoverBackground`), not the alpha it used to be. The alpha existed to
+     survive an unknown host surface, and it bought that at the cost of a hover
+     that read differently on every one of them; the design draws one hover, so
+     this is one colour. The hazard the alpha was guarding against is real and
+     has a name — `--bg-surface-hover` on the dark sidebar landed one step of
+     255 from the sidebar itself, so the state did not exist — and the guard
+     against it now is that both flat values are picked against the sidebar
+     fills we actually ship (`--sidebar`), and that the extension repoints all
+     three at `--vscode-list-*` rather than inheriting them.
+
+     `--row-active` stays alpha on purpose: it is the *other three* sidebars'
+     selected fill, and those still wear the accent-bar shape `rowShapeClass`
+     draws, where the fill is a tint under a bar and not the selection itself.
+
+     `--row-selected` is new and is the session list's own: a filled card, the
+     shape the design gives selection there. Light is a tint carrying dark text;
+     dark is VS Code's `list.activeSelectionBackground` carrying light text.
+
+     `--row-selected-weak` is the **secondary** selection — "this card holds what
+     you are looking at, but the thing you are looking at is one row inside it".
+     It exists because a session card and its sub-agents are two selections at
+     two grains, and the blue can only mean one of them: when a sub-agent is
+     open, the blue belongs to that step and the card drops to this. It is VS
+     Code's `list.inactiveSelectionBackground`, which is the same idea one
+     surface over — selected, but not the thing with focus. Distinct from
+     `--row-hover` on purpose: a card that answered the pointer and a card
+     holding the open agent are different claims, and a list that painted them
+     the same colour would be lying about one of them. */
+  --row-hover: #e8e8e8;
   --row-active: rgb(0 0 0 / 0.08);
+  --row-selected: #cfe4f7;
+  --row-selected-weak: #e4e6f1;
+
+  /* A count badge that is NOT an alert. The unread badge wears `--accent`
+     because unread is a call to look; a plain count (how many sub-agents, how
+     many tasks) wears this, because a blue pill that means nothing urgent
+     spends the accent on noise. VS Code's `badge.background`. */
+  --badge: #c4c4c4;
+  --badge-fg: #333333;
 
   /* ---------- Borders ---------- */
   --border: #ebebeb;
@@ -138,8 +172,17 @@
   --bg-code: #141414;
   --bg-elevated: #0a0a0acc;
 
-  --row-hover: rgb(255 255 255 / 0.06);
+  /* See the light block for the whole argument. These two are VS Code's own
+     `list.hoverBackground` / `list.activeSelectionBackground`, which is what the
+     design was drawn against. */
+  --row-hover: #2a2d2e;
   --row-active: rgb(255 255 255 / 0.10);
+  --row-selected: #04395e;
+  --row-selected-weak: #37373d;
+
+  /* See the light block. */
+  --badge: #616161;
+  --badge-fg: #cccccc;
 
   /* ---------- Borders ---------- */
   --border: #1f1f1f;
@@ -291,6 +334,10 @@
   --color-surface-hover: var(--bg-surface-hover);
   --color-row-hover: var(--row-hover);
   --color-row-active: var(--row-active);
+  --color-row-selected: var(--row-selected);
+  --color-row-selected-weak: var(--row-selected-weak);
+  --color-badge: var(--badge);
+  --color-badge-fg: var(--badge-fg);
   /* Named code-bg (not code) so it can't shadow the --text-code font-size token:
      with a --color-code defined, `text-code` would resolve to the color namespace
      and paint text in the code *background* color — invisible in both themes. */
@@ -358,6 +405,14 @@
   --text-label: 0.75rem;
   --text-label--line-height: 1rem;
   --text-label--letter-spacing: 0.02em;
+  /* 11px. The step rows under a session card, and nothing else yet — a size
+     below `label` exists so a list *inside* a row can be visibly subordinate to
+     it without dropping to a weight nobody can read. Tracking goes NEGATIVE
+     here where `label` goes positive: `label` is a small-caps-ish UI word that
+     wants air, this is a sentence-shaped run that wants to hold together. */
+  --text-micro: 0.6875rem;
+  --text-micro--line-height: 0.875rem;
+  --text-micro--letter-spacing: -0.005em;
   --text-code: 0.84375rem;
   --text-code--line-height: 1.375rem;