feat(tui): add hierarchical session navigation with breadcrumb UI

- Add session_child_down and session_root keybinds for vertical navigation
- Rewrite header.tsx with 3-row layout: breadcrumb trail, stats, nav hints
- Add siblings() and directChildren() memos for proper navigation
- Add moveToFirstChild() and moveToRoot() navigation functions
- Dynamic breadcrumb truncation based on terminal width
- Navigation hints show only when relevant (siblings exist, children exist, depth >= 2)

Author: NamedIdentity

packages/opencode/src/cli/cmd/tui/routes/session/header.tsx

@@ -1,5 +1,5 @@
-import { type Accessor, createMemo, createSignal, Match, Show, Switch } from "solid-js"
-import { useRouteData } from "@tui/context/route"
+import { type Accessor, createMemo, createSignal, For, Match, Show, Switch } from "solid-js"
+import { useRoute, useRouteData } from "@tui/context/route"
 import { useSync } from "@tui/context/sync"
 import { pipe, sumBy } from "remeda"
 import { useTheme } from "@tui/context/theme"
@@ -32,6 +32,7 @@ const ContextInfo = (props: { context: Accessor<string | undefined>; cost: Acces
 
 export function Header() {
   const route = useRouteData("session")
+  const { navigate } = useRoute()
   const sync = useSync()
   const session = createMemo(() => sync.session.get(route.sessionID)!)
   const messages = createMemo(() => sync.data.message[route.sessionID] ?? [])
@@ -60,12 +61,113 @@ export function Header() {
     return result
   })
 
+  // Build session path from root to current session
+  const sessionPath = createMemo(() => {
+    const path: Session[] = []
+    let current: Session | undefined = session()
+    while (current) {
+      path.unshift(current)
+      current = current.parentID ? sync.session.get(current.parentID) : undefined
+    }
+    return path
+  })
+
+  // Current depth (0 = root, 1 = first child, etc.)
+  const depth = createMemo(() => sessionPath().length - 1)
+
+  // Direct children of current session (for down navigation availability)
+  const directChildren = createMemo(() => {
+    const currentID = session()?.id
+    if (!currentID) return []
+    return sync.data.session.filter((x) => x.parentID === currentID)
+  })
+
+  // Siblings at current level (for left/right navigation availability)
+  const siblings = createMemo(() => {
+    const currentParentID = session()?.parentID
+    if (!currentParentID) return []
+    return sync.data.session.filter((x) => x.parentID === currentParentID)
+  })
+
+  // Navigation availability
+  const canGoUp = createMemo(() => !!session()?.parentID)
+  const canGoDown = createMemo(() => directChildren().length > 0)
+  const canCycleSiblings = createMemo(() => siblings().length > 1)
+
+  // Get display name for a session
+  const getSessionDisplayName = (s: Session, isRoot: boolean) => {
+    if (isRoot) {
+      // Root session: show the title
+      return s.title || s.id.slice(0, 8)
+    }
+    // Child session: extract agent name from title like "Description (@agent-name subagent)"
+    const match = s.title?.match(/\(@([^)]+?)(?:\s+subagent)?\)/)
+    if (match) {
+      // Return just the agent name without @ and "subagent"
+      return match[1]
+    }
+    // Fallback to title or shortened ID
+    return s.title || s.id.slice(0, 8)
+  }
+
+  // Get UP navigation label based on depth
+  const upLabel = createMemo(() => {
+    const d = depth()
+    if (d <= 0) return "" // Root has no parent
+    if (d === 1) return "Parent" // Depth 1 → Root
+    return `Child(L${d - 1})` // Depth N → Child(L{N-1})
+  })
+
+  // Get DOWN navigation label based on depth
+  const downLabel = createMemo(() => {
+    const d = depth()
+    return `Child(L${d + 1})` // Depth N → Child(L{N+1})
+  })
+
   const { theme } = useTheme()
   const keybind = useKeybind()
   const command = useCommandDialog()
-  const [hover, setHover] = createSignal<"parent" | "prev" | "next" | null>(null)
   const dimensions = useTerminalDimensions()
   const narrow = createMemo(() => dimensions().width < 80)
+  const [hover, setHover] = createSignal<"parent" | "root" | "prev" | "next" | "down" | "breadcrumb" | null>(null)
+  const [hoverBreadcrumbIdx, setHoverBreadcrumbIdx] = createSignal<number | null>(null)
+
+  // Calculate breadcrumb text for a set of segments
+  const calcBreadcrumbLength = (segments: Session[], truncated: boolean) => {
+    let len = 0
+    segments.forEach((s, i) => {
+      len += getSessionDisplayName(s, !s.parentID).length
+      if (i < segments.length - 1) {
+        len += truncated && i === 0 ? 9 : 3 // " > ... > " or " > "
+      }
+    })
+    return len
+  }
+
+  // Dynamic breadcrumb truncation based on available width
+  const breadcrumbSegments = createMemo(() => {
+    const path = sessionPath()
+    const availableWidth = dimensions().width - 40 // Reserve ~40 chars for right-side stats
+
+    // Try full path first
+    const fullLength = calcBreadcrumbLength(path, false)
+    if (fullLength <= availableWidth || path.length <= 2) {
+      return { truncated: false, segments: path }
+    }
+
+    // Truncate: show root + ... + last N segments that fit
+    // Start with root + last segment, add more if space allows
+    for (let keepLast = path.length - 1; keepLast >= 1; keepLast--) {
+      const segments = [path[0], ...path.slice(-keepLast)]
+      const len = calcBreadcrumbLength(segments, true)
+      if (len <= availableWidth || keepLast === 1) {
+        return { truncated: true, segments }
+      }
+    }
+
+    // Fallback: root + last segment
+    return { truncated: true, segments: [path[0], path[path.length - 1]] }
+  })
 
   return (
     <box flexShrink={0}>
@@ -82,52 +184,125 @@ export function Header() {
       >
         <Switch>
           <Match when={session()?.parentID}>
-            <box flexDirection="column" gap={1}>
-              <box flexDirection={narrow() ? "column" : "row"} justifyContent="space-between" gap={narrow() ? 1 : 0}>
-                <text fg={theme.text}>
-                  <b>Subagent session</b>
-                </text>
+            {/* Subagent session: 3-row layout */}
+            <box flexDirection="column" gap={0}>
+              {/* Row 1: Breadcrumb trail */}
+              <box flexDirection="row" gap={0}>
+                <For each={breadcrumbSegments().segments}>
+                  {(segment, index) => (
+                    <>
+                      <box
+                        onMouseOver={() => {
+                          setHover("breadcrumb")
+                          setHoverBreadcrumbIdx(index())
+                        }}
+                        onMouseOut={() => {
+                          setHover(null)
+                          setHoverBreadcrumbIdx(null)
+                        }}
+                        onMouseUp={() => {
+                          navigate({ type: "session", sessionID: segment.id })
+                        }}
+                        backgroundColor={
+                          hover() === "breadcrumb" && hoverBreadcrumbIdx() === index()
+                            ? theme.backgroundElement
+                            : theme.backgroundPanel
+                        }
+                      >
+                        <text fg={index() === breadcrumbSegments().segments.length - 1 ? theme.text : theme.textMuted}>
+                          <Show when={index() === breadcrumbSegments().segments.length - 1} fallback={getSessionDisplayName(segment, !segment.parentID)}>
+                            <b>{getSessionDisplayName(segment, !segment.parentID)}</b>
+                          </Show>
+                        </text>
+                      </box>
+                      <Show when={index() < breadcrumbSegments().segments.length - 1}>
+                        {/* Show "... >" after root when truncated */}
+                        <text fg={theme.textMuted}>
+                          {index() === 0 && breadcrumbSegments().truncated ? " > ... >" : " > "}
+                        </text>
+                      </Show>
+                    </>
+                  )}
+                </For>
+              </box>
+
+              {/* Row 2: Divider + stats */}
+              <box flexDirection="row" gap={1}>
+                <box flexGrow={1}>
+                  <text fg={theme.border}>────────────────────────────────────────</text>
+                </box>
                 <box flexDirection="row" gap={1} flexShrink={0}>
                   <ContextInfo context={context} cost={cost} />
                   <text fg={theme.textMuted}>v{Installation.VERSION}</text>
                 </box>
               </box>
+
+              {/* Row 3: Navigation hints */}
               <box flexDirection="row" gap={2}>
-                <box
-                  onMouseOver={() => setHover("parent")}
-                  onMouseOut={() => setHover(null)}
-                  onMouseUp={() => command.trigger("session.parent")}
-                  backgroundColor={hover() === "parent" ? theme.backgroundElement : theme.backgroundPanel}
-                >
-                  <text fg={theme.text}>
-                    Parent <span style={{ fg: theme.textMuted }}>{keybind.print("session_parent")}</span>
-                  </text>
-                </box>
-                <box
-                  onMouseOver={() => setHover("prev")}
-                  onMouseOut={() => setHover(null)}
-                  onMouseUp={() => command.trigger("session.child.previous")}
-                  backgroundColor={hover() === "prev" ? theme.backgroundElement : theme.backgroundPanel}
-                >
-                  <text fg={theme.text}>
-                    Prev <span style={{ fg: theme.textMuted }}>{keybind.print("session_child_cycle_reverse")}</span>
-                  </text>
-                </box>
-                <box
-                  onMouseOver={() => setHover("next")}
-                  onMouseOut={() => setHover(null)}
-                  onMouseUp={() => command.trigger("session.child.next")}
-                  backgroundColor={hover() === "next" ? theme.backgroundElement : theme.backgroundPanel}
-                >
-                  <text fg={theme.text}>
-                    Next <span style={{ fg: theme.textMuted }}>{keybind.print("session_child_cycle")}</span>
-                  </text>
-                </box>
+                <Show when={canGoUp()}>
+                  <box
+                    onMouseOver={() => setHover("parent")}
+                    onMouseOut={() => setHover(null)}
+                    onMouseUp={() => command.trigger("session.parent")}
+                    backgroundColor={hover() === "parent" ? theme.backgroundElement : theme.backgroundPanel}
+                  >
+                    <text fg={theme.text}>
+                      {upLabel()} <span style={{ fg: theme.textMuted }}>{keybind.print("session_parent")}</span>
+                    </text>
+                  </box>
+                </Show>
+                <Show when={depth() >= 2}>
+                  <box
+                    onMouseOver={() => setHover("root")}
+                    onMouseOut={() => setHover(null)}
+                    onMouseUp={() => command.trigger("session.root")}
+                    backgroundColor={hover() === "root" ? theme.backgroundElement : theme.backgroundPanel}
+                  >
+                    <text fg={theme.text}>
+                      Root <span style={{ fg: theme.textMuted }}>{keybind.print("session_root")}</span>
+                    </text>
+                  </box>
+                </Show>
+                <Show when={canCycleSiblings()}>
+                  <box
+                    onMouseOver={() => setHover("next")}
+                    onMouseOut={() => setHover(null)}
+                    onMouseUp={() => command.trigger("session.child.next")}
+                    backgroundColor={hover() === "next" ? theme.backgroundElement : theme.backgroundPanel}
+                  >
+                    <text fg={theme.text}>
+                      Next <span style={{ fg: theme.textMuted }}>{keybind.print("session_child_cycle")}</span>
+                    </text>
+                  </box>
+                  <box
+                    onMouseOver={() => setHover("prev")}
+                    onMouseOut={() => setHover(null)}
+                    onMouseUp={() => command.trigger("session.child.previous")}
+                    backgroundColor={hover() === "prev" ? theme.backgroundElement : theme.backgroundPanel}
+                  >
+                    <text fg={theme.text}>
+                      Prev <span style={{ fg: theme.textMuted }}>{keybind.print("session_child_cycle_reverse")}</span>
+                    </text>
+                  </box>
+                </Show>
+                <Show when={canGoDown()}>
+                  <box
+                    onMouseOver={() => setHover("down")}
+                    onMouseOut={() => setHover(null)}
+                    onMouseUp={() => command.trigger("session.child.down")}
+                    backgroundColor={hover() === "down" ? theme.backgroundElement : theme.backgroundPanel}
+                  >
+                    <text fg={theme.text}>
+                      {downLabel()} <span style={{ fg: theme.textMuted }}>{keybind.print("session_child_down")}</span>
+                    </text>
+                  </box>
+                </Show>
               </box>
             </box>
           </Match>
           <Match when={true}>
-            <box flexDirection={narrow() ? "column" : "row"} justifyContent="space-between" gap={1}>
+            {/* Root session: responsive layout from upstream */}
+            <box flexDirection={narrow() ? "column" : "row"} justifyContent="space-between" gap={narrow() ? 1 : 0}>
               <Title session={session} />
               <box flexDirection="row" gap={1} flexShrink={0}>
                 <ContextInfo context={context} cost={cost} />

packages/opencode/src/cli/cmd/tui/routes/session/index.tsx

@@ -118,6 +118,25 @@ export function Session() {
       .filter((x) => x.parentID === parentID || x.id === parentID)
       .toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
   })
+
+  // Siblings: sessions with the same parentID (for proper sibling cycling)
+  const siblings = createMemo(() => {
+    const currentParentID = session()?.parentID
+    if (!currentParentID) return [] // Root has no siblings
+    return sync.data.session
+      .filter((x) => x.parentID === currentParentID)
+      .toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  })
+
+  // Direct children: sessions where parentID === current session ID
+  const directChildren = createMemo(() => {
+    const currentID = session()?.id
+    if (!currentID) return []
+    return sync.data.session
+      .filter((x) => x.parentID === currentID)
+      .toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  })
+
   const messages = createMemo(() => sync.data.message[route.sessionID] ?? [])
   const permissions = createMemo(() => {
     if (session()?.parentID) return []
@@ -281,14 +300,39 @@ export function Session() {
   const local = useLocal()
 
   function moveChild(direction: number) {
-    if (children().length === 1) return
-    let next = children().findIndex((x) => x.id === session()?.id) + direction
-    if (next >= children().length) next = 0
-    if (next < 0) next = children().length - 1
-    if (children()[next]) {
+    // Use siblings for cycling (sessions with same parentID)
+    const sibs = siblings()
+    if (sibs.length <= 1) return
+    let next = sibs.findIndex((x) => x.id === session()?.id) + direction
+    if (next >= sibs.length) next = 0
+    if (next < 0) next = sibs.length - 1
+    if (sibs[next]) {
+      navigate({
+        type: "session",
+        sessionID: sibs[next].id,
+      })
+    }
+  }
+
+  function moveToFirstChild() {
+    const children = directChildren()
+    if (children.length === 0) return
+    navigate({
+      type: "session",
+      sessionID: children[0].id,
+    })
+  }
+
+  function moveToRoot() {
+    // Traverse up to find root session (no parentID)
+    let current = session()
+    while (current?.parentID) {
+      current = sync.session.get(current.parentID)
+    }
+    if (current && current.id !== session()?.id) {
       navigate({
         type: "session",
-        sessionID: children()[next].id,
+        sessionID: current.id,
       })
     }
   }
@@ -887,6 +931,28 @@ export function Session() {
         dialog.clear()
       },
     },
+    {
+      title: "Go to first child session",
+      value: "session.child.down",
+      keybind: "session_child_down",
+      category: "Session",
+      disabled: true,
+      onSelect: (dialog) => {
+        moveToFirstChild()
+        dialog.clear()
+      },
+    },
+    {
+      title: "Go to root session",
+      value: "session.root",
+      keybind: "session_root",
+      category: "Session",
+      disabled: true,
+      onSelect: (dialog) => {
+        moveToRoot()
+        dialog.clear()
+      },
+    },
   ])
 
   const revertInfo = createMemo(() => session()?.revert)