@brimveyn/aimux 1.18.4 → 1.19.1

package/src/ipc/protocol.ts

@@ -1,5 +1,6 @@
 import type {
   AssistantId,
+  QuestionKind,
   SessionStatus,
   TabActivity,
   TabSession,
@@ -29,8 +30,15 @@ import { isWorkspaceSnapshotV1, isWorktreeRecord } from '../state/validation'
 // `switchWorkspace`, `closeWorkspace`, `announceWorkspaceSwitched`) and
 // worktree record requests (`addWorktreeRecord`, `removeWorktreeRecord`),
 // plus matching broadcast events. All capability-gated; MIN stays at 10.
+//
+// v13: additive — agent-orchestration signals. Two new broadcast events,
+// `tabTurnComplete` (a tab's `idle` held long enough to call the turn done)
+// and `tabQuestion` (a tab entered `waiting-input`; carries the prompt text
+// plus best-effort parsed options), and an additive `lastLine` field on
+// `TabSessionSummary`. Gated behind `turnLifecycle`, `questionEvents`, and
+// `listTabsLastLine` respectively; MIN stays at 10.
 export const IPC_PROTOCOL_MIN_VERSION = 10
-export const IPC_PROTOCOL_VERSION = 12
+export const IPC_PROTOCOL_VERSION = 13
 
 /**
  * Capability advertised by a daemon that knows how to drain + handoff its
@@ -104,6 +112,31 @@ export const IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS = 'worktreeLifecycleEvents
  */
 export const IPC_CAPABILITY_TAB_TAIL = 'tabTail'
 
+/**
+ * v13 — capability gating the `tabTurnComplete` event. When advertised, the
+ * daemon broadcasts an authoritative end-of-turn signal once a tab's `idle`
+ * activity has held continuously for the settle window, so a driver need not
+ * poll `tabStatus` and re-confirm that idle held. Pre-cap peers never see the
+ * event and fall back to settle-polling `tabStatus`.
+ */
+export const IPC_CAPABILITY_TURN_LIFECYCLE = 'turnLifecycle'
+
+/**
+ * v13 — capability gating the `tabQuestion` event. When advertised, the daemon
+ * broadcasts the captured prompt text (plus best-effort parsed options) when a
+ * tab transitions into `waiting-input`, so a driver need not re-`snapshot` the
+ * screen and substring-match to learn what the worker is asking.
+ */
+export const IPC_CAPABILITY_QUESTION_EVENTS = 'questionEvents'
+
+/**
+ * v13 — capability gating the additive `lastLine` field on `listTabs`
+ * summaries. When advertised, each summary carries the tab's last non-blank
+ * rendered line so a fleet poll can read "what each worker is doing" without a
+ * `snapshot` round-trip per tab. Pre-cap daemons omit the field.
+ */
+export const IPC_CAPABILITY_LIST_TABS_LAST_LINE = 'listTabsLastLine'
+
 /**
  * Capabilities advertised by *this* process in its `helloResult`. Additive
  * features should be introduced as new capability strings here rather than
@@ -124,6 +157,9 @@ export const IPC_PROTOCOL_CAPABILITIES: readonly string[] = [
   IPC_CAPABILITY_WORKSPACE_LIFECYCLE,
   IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
   IPC_CAPABILITY_TAB_TAIL,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_LIST_TABS_LAST_LINE,
 ]
 
 export interface ProtocolHelloRequest {
@@ -184,6 +220,12 @@ export interface TabSessionSummary {
   activity?: TabActivity
   command: string
   worktreeId?: string
+  /**
+   * v13 / capability `listTabsLastLine`. The tab's last non-blank rendered
+   * line, trimmed. Present only when the daemon advertises the capability;
+   * omitted when the tab has produced no viewport yet.
+   */
+  lastLine?: string
 }
 
 export interface ListTabsResult {
@@ -324,6 +366,26 @@ export type ServerEvent =
   | { type: 'tabExit'; payload: { tabId: string; exitCode: number } }
   | { type: 'tabError'; payload: { tabId: string; message: string } }
   | { type: 'tabStatus'; payload: { sessionId: string; tabId: string; status: TabActivity } }
+  // v13 / capability `turnLifecycle`. Authoritative end-of-turn: broadcast
+  // once a tab's `idle` activity has held continuously for the settle window.
+  // Edge-triggered — re-armed only after the tab leaves `idle` again — so a
+  // driver gets exactly one per turn. `idleMs` is how long idle had held when
+  // the event fired.
+  | { type: 'tabTurnComplete'; payload: { sessionId: string; tabId: string; idleMs: number } }
+  // v13 / capability `questionEvents`. Broadcast when a tab transitions into
+  // `waiting-input`. `prompt` is the captured tail text (authoritative);
+  // `options` is a best-effort per-CLI parse of the choice list and may be
+  // absent even when the prompt clearly offers choices.
+  | {
+      type: 'tabQuestion'
+      payload: {
+        sessionId: string
+        tabId: string
+        kind: QuestionKind
+        prompt: string
+        options?: string[]
+      }
+    }
   | { type: 'sessionStatus'; payload: { sessionId: string; status: SessionStatus } }
   // Capability-gated on `tabLifecycleEvents`. Broadcast after a successful
   // `createTab` so every UI/CLI client attached to the same session learns
@@ -510,10 +572,15 @@ function isTabSessionSummary(value: unknown): value is TabSessionSummary {
       value.activity === 'waiting-input' ||
       value.activity === 'idle') &&
     isString(value.command) &&
-    (value.worktreeId === undefined || isString(value.worktreeId))
+    (value.worktreeId === undefined || isString(value.worktreeId)) &&
+    (value.lastLine === undefined || isString(value.lastLine))
   )
 }
 
+function isQuestionKind(value: unknown): value is QuestionKind {
+  return value === 'question' || value === 'permission'
+}
+
 function isListTabsResult(value: unknown): value is ListTabsResult {
   return (
     isObjectRecord(value) &&
@@ -786,6 +853,21 @@ export function parseServerMessage(value: unknown): ServerResponse | ServerEvent
       assert(isString(value.payload.tabId), 'tabStatus.tabId must be a string')
       assert(isTabActivity(value.payload.status), 'tabStatus.status is invalid')
       return value as ServerEvent
+    case 'tabTurnComplete':
+      assert(isString(value.payload.sessionId), 'tabTurnComplete.sessionId must be a string')
+      assert(isString(value.payload.tabId), 'tabTurnComplete.tabId must be a string')
+      assert(isFiniteNumber(value.payload.idleMs), 'tabTurnComplete.idleMs must be a number')
+      return value as ServerEvent
+    case 'tabQuestion':
+      assert(isString(value.payload.sessionId), 'tabQuestion.sessionId must be a string')
+      assert(isString(value.payload.tabId), 'tabQuestion.tabId must be a string')
+      assert(isQuestionKind(value.payload.kind), 'tabQuestion.kind is invalid')
+      assert(isString(value.payload.prompt), 'tabQuestion.prompt must be a string')
+      assert(
+        value.payload.options === undefined || isStringArray(value.payload.options),
+        'tabQuestion.options must be a string array when present'
+      )
+      return value as ServerEvent
     case 'tabAdded':
       assert(isString(value.payload.sessionId), 'tabAdded.sessionId must be a string')
       assert(isTabSession(value.payload.tab), 'tabAdded.tab is invalid')

package/src/pty/assistant-question-extractor.ts

@@ -0,0 +1,124 @@
+/**
+ * Question / permission extraction.
+ *
+ * When a tab transitions into `waiting-input`, the status detection loop calls
+ * this to turn "the worker is blocked" into a structured event: what it's
+ * asking (the captured prompt text — authoritative) plus a best-effort parse
+ * of the choice list. It reuses the detector's tail extraction so both read
+ * the screen identically.
+ *
+ * Option parsing is explicitly best-effort and per-CLI: TUIs render menus in
+ * shapes that shift between versions. `prompt` is always populated; `options`
+ * may be absent even when the screen clearly offers choices. Consumers should
+ * treat `prompt` as the source of truth and `options` as a convenience.
+ */
+import type { AssistantId, QuestionKind, TerminalSnapshot } from '../state/types'
+
+import { extractTailLines } from './assistant-status-detector'
+
+/** How many trailing non-blank lines to capture as the prompt text. Wider than
+ *  the 10-line classification tail so a multi-line permission block or a long
+ *  question is captured whole. */
+const PROMPT_TAIL_LINES = 20
+
+export interface QuestionDetail {
+  kind: QuestionKind
+  /** The captured waiting-input tail, trailing-trimmed, joined with newlines. */
+  prompt: string
+  /** Best-effort parsed choice list; omitted when none could be recognised. */
+  options?: string[]
+}
+
+/**
+ * Substrings that mark a blocked prompt as a permission / approval request
+ * rather than a free-form question. Lower-cased haystack match. Kept broad and
+ * shared across CLIs; per-CLI extras are folded in below.
+ */
+const PERMISSION_SIGNALS: readonly string[] = [
+  'do you want',
+  'permission required',
+  'permission to',
+  '△ permission',
+  'allow this',
+  'approve',
+  'grant',
+  'press enter to confirm',
+]
+
+/**
+ * Extract the structured question for a tab already classified as
+ * `waiting-input`. Returns null only when there's no viewport / no text to
+ * report; otherwise `prompt` is always present.
+ */
+export function extractQuestion(
+  assistant: AssistantId,
+  viewport: TerminalSnapshot | undefined
+): QuestionDetail | null {
+  if (!viewport) return null
+  const lines = extractTailLines(viewport, PROMPT_TAIL_LINES)
+  if (lines.length === 0) return null
+
+  const prompt = lines.join('\n')
+  const haystack = prompt.toLowerCase()
+  const kind = detectKind(assistant, haystack)
+  const options = parseOptions(lines, haystack)
+  return options ? { kind, options, prompt } : { kind, prompt }
+}
+
+function detectKind(assistant: AssistantId, haystack: string): QuestionKind {
+  for (const signal of PERMISSION_SIGNALS) {
+    if (haystack.includes(signal)) return 'permission'
+  }
+  // opencode surfaces tool approvals under a "permission" banner; codex uses an
+  // approval confirm. Both already covered by the shared signals, but keep the
+  // assistant param so future per-CLI divergence has a seam.
+  void assistant
+  return 'question'
+}
+
+/**
+ * Matches a numbered menu row: an optional selection marker (❯ › > *), a digit,
+ * a `.`/`)` separator, then the option label. Capturing the label lets us strip
+ * the marker/number so consumers get clean text.
+ */
+const NUMBERED_OPTION = /^\s*[❯›>*]?\s*\d+[.)]\s+(\S.*)$/u
+
+/**
+ * Matches an arrow-selected label with no number, e.g. Claude's `❯ Yes` /
+ * `  No` yes-no menus.
+ */
+const MARKED_OPTION = /^\s*[❯›]\s+(\S.*)$/u
+
+function parseOptions(lines: readonly string[], haystack: string): string[] | undefined {
+  const numbered: string[] = []
+  for (const line of lines) {
+    const captured = NUMBERED_OPTION.exec(line)?.[1]
+    if (captured != null && captured !== '') numbered.push(captured.trimEnd())
+  }
+  if (numbered.length >= 2) return numbered
+
+  // No numbered menu — look for a single arrow-marked choice paired with its
+  // siblings is unreliable, so fall back to explicit yes/no affordances.
+  if (
+    haystack.includes('[y/n]') ||
+    haystack.includes('(y/n)') ||
+    haystack.includes('yes/no') ||
+    haystack.includes('y/n?')
+  ) {
+    return ['Yes', 'No']
+  }
+
+  const marked = lines.map((line) => MARKED_OPTION.exec(line)?.[1]?.trimEnd()).filter(isNonEmpty)
+  if (marked.length >= 1 && numbered.length === 0) {
+    // A lone highlighted option (e.g. a confirm dialog defaulting to Yes) — only
+    // surface it when it's a short label, not a highlighted sentence.
+    const short = marked.filter((label) => label.length <= 40)
+    if (short.length >= 1) return short
+  }
+
+  return undefined
+}
+
+function isNonEmpty(value: string | undefined): value is string {
+  return value !== undefined && value.length > 0
+}

package/src/pty/assistant-status-detection-loop.ts

@@ -17,6 +17,7 @@ import type { AssistantId, SessionStatus, TabActivity, TerminalSnapshot } from '
 
 import { logDebug } from '../debug/input-log'
 import { getLineText } from '../input/terminal-text-extraction'
+import { extractQuestion } from './assistant-question-extractor'
 import { AssistantStatusArbiter, type RecordHookEventInput } from './assistant-status-arbiter'
 import { AssistantStatusDetector } from './assistant-status-detector'
 
@@ -35,6 +36,15 @@ function tailPreview(viewport: TerminalSnapshot | undefined): string {
 /** Default polling interval. Cheap — detector is a handful of substring checks. */
 const DEFAULT_TICK_MS = 500
 
+/**
+ * How long a tab's `idle` activity must hold continuously before we call the
+ * turn complete. `idle` can flash for a fraction of a second between two tool
+ * calls, so an end-of-turn signal that fired on the first idle tick would catch
+ * the worker mid-turn. Requiring idle to *hold* this long is the authoritative
+ * replacement for a driver's settle-poll loop.
+ */
+const DEFAULT_TURN_SETTLE_MS = 1500
+
 export interface LoopTabView {
   id: string
   assistant: AssistantId
@@ -49,7 +59,30 @@ export interface StatusDetectionLoopOptions {
   onTabStatus: (tabId: string, status: TabActivity, sessionId: string) => void
   /** Emitted when either flag on a session changes. */
   onSessionStatus: (sessionId: string, status: SessionStatus) => void
+  /**
+   * Emitted once per turn, when a tab's `idle` activity has held continuously
+   * for `turnSettleMs`. Edge-triggered: re-armed only after the tab leaves
+   * `idle`, so a driver receives exactly one signal per turn. `idleMs` is how
+   * long idle had held when the signal fired.
+   */
+  onTurnComplete?: (tabId: string, sessionId: string, idleMs: number) => void
+  /**
+   * Emitted when a tab transitions into `waiting-input`. Edge-triggered: fires
+   * once per transition, carrying the captured prompt text and any parsed
+   * options. Fires on both tick and attach replay so a client that attaches to
+   * an already-blocked tab still learns the question.
+   */
+  onTabQuestion?: (
+    tabId: string,
+    sessionId: string,
+    detail: { kind: 'question' | 'permission'; prompt: string; options?: string[] }
+  ) => void
   tickMs?: number
+  /** Override the turn-complete settle window (default 1500ms). */
+  turnSettleMs?: number
+  /** Override the clock. Defaults to Date.now. Tests inject a logical clock so
+   *  the wall-clock-driven turn-complete settle is deterministic. */
+  nowFn?: () => number
 }
 
 export interface StatusDetectionLoopHandle {
@@ -80,10 +113,18 @@ export function runStatusDetectionLoop(
   options: StatusDetectionLoopOptions
 ): StatusDetectionLoopHandle {
   const tickMs = options.tickMs ?? DEFAULT_TICK_MS
+  const turnSettleMs = options.turnSettleMs ?? DEFAULT_TURN_SETTLE_MS
+  const now = options.nowFn ?? Date.now
   const detector = new AssistantStatusDetector()
   const arbiter = new AssistantStatusArbiter()
   const lastTabStatus = new Map<string, { status: TabActivity; sessionId: string }>()
   const lastSessionStatus = new Map<string, SessionStatus>()
+  // Timestamp when a tab most recently entered `idle`. Cleared when it leaves
+  // idle. `turnEmitted` guards against re-firing `onTurnComplete` within the
+  // same idle episode; it's cleared alongside `idleSince` so the next turn
+  // re-arms.
+  const idleSince = new Map<string, number>()
+  const turnEmitted = new Set<string>()
 
   const timer = setInterval(() => {
     try {
@@ -134,6 +175,38 @@ export function runStatusDetectionLoop(
         lastTabStatus.set(tab.id, { sessionId, status })
         options.onTabStatus(tab.id, status, sessionId)
       }
+
+      // Turn-complete bookkeeping. The emission itself is gated to `tick` so a
+      // synchronous attach replay (`classifyNow`) never fabricates an
+      // end-of-turn — only the wall-clock-driven poll does. The idleSince /
+      // turnEmitted maps are maintained on every call so state stays coherent
+      // regardless of source.
+      if (status === 'idle') {
+        let since = idleSince.get(tab.id)
+        if (since === undefined) {
+          since = now
+          idleSince.set(tab.id, since)
+        }
+        if (source === 'tick' && !turnEmitted.has(tab.id) && now - since >= turnSettleMs) {
+          turnEmitted.add(tab.id)
+          options.onTurnComplete?.(tab.id, sessionId, now - since)
+        }
+      } else {
+        idleSince.delete(tab.id)
+        turnEmitted.delete(tab.id)
+      }
+
+      // Question extraction on the idle/working → waiting-input edge. `prev`
+      // still holds the pre-update status, so this fires exactly once per
+      // transition even though the loop broadcasts to every client.
+      if (
+        status === 'waiting-input' &&
+        (!prev || prev.status !== 'waiting-input') &&
+        options.onTabQuestion
+      ) {
+        const detail = extractQuestion(tab.assistant, tab.viewport)
+        if (detail) options.onTabQuestion(tab.id, sessionId, detail)
+      }
     }
     const next: SessionStatus = { waiting, working }
     const prevSession = lastSessionStatus.get(sessionId)
@@ -154,14 +227,14 @@ export function runStatusDetectionLoop(
   }
 
   function tick(): void {
-    const now = Date.now()
+    const ts = now()
     const sessionIds = options.listSessions()
     const seenSessions = new Set<string>()
     const seenTabs = new Set<string>()
 
     for (const sessionId of sessionIds) {
       seenSessions.add(sessionId)
-      classifySession(sessionId, options.listTabs(sessionId), now, 'tick', seenTabs)
+      classifySession(sessionId, options.listTabs(sessionId), ts, 'tick', seenTabs)
     }
 
     for (const tabId of lastTabStatus.keys()) {
@@ -169,6 +242,8 @@ export function runStatusDetectionLoop(
         detector.forget(tabId)
         arbiter.forget(tabId)
         lastTabStatus.delete(tabId)
+        idleSince.delete(tabId)
+        turnEmitted.delete(tabId)
       }
     }
     for (const sessionId of lastSessionStatus.keys()) {
@@ -180,7 +255,7 @@ export function runStatusDetectionLoop(
 
   return {
     classifyNow: (sessionId, tabs) => {
-      classifySession(sessionId, tabs, Date.now(), 'classifyNow')
+      classifySession(sessionId, tabs, now(), 'classifyNow')
     },
     getSessionStatus: (sessionId) => lastSessionStatus.get(sessionId),
     getTabStatus: (tabId) => lastTabStatus.get(tabId)?.status,
@@ -206,6 +281,8 @@ export function runStatusDetectionLoop(
       arbiter.clear()
       lastTabStatus.clear()
       lastSessionStatus.clear()
+      idleSince.clear()
+      turnEmitted.clear()
     },
   }
 }

package/src/pty/assistant-status-detector.ts

@@ -85,7 +85,14 @@ export class AssistantStatusDetector {
   }
 }
 
-function extractTailText(viewport: TerminalSnapshot, lineCount: number): string {
+/**
+ * Last `lineCount` non-blank rendered lines, trailing-trimmed, oldest-first.
+ * Shared by the status detector (10-line tail for classification) and the
+ * question extractor (larger tail for prompt capture) so both read the screen
+ * the same way. Prefers `tailLines` when the user has scrolled the viewport
+ * off the active screen.
+ */
+export function extractTailLines(viewport: TerminalSnapshot, lineCount: number): string[] {
   const isScrolledToBottom = viewport.viewportY === viewport.baseY
   const lines = isScrolledToBottom ? viewport.lines : (viewport.tailLines ?? viewport.lines)
   // Full-screen TUIs (claude, opencode) paint in the alternate buffer and
@@ -112,7 +119,11 @@ function extractTailText(viewport: TerminalSnapshot, lineCount: number): string
     if (!line) continue
     parts.push(getLineText(line).replace(/\s+$/u, ''))
   }
-  return parts.join('\n')
+  return parts
+}
+
+function extractTailText(viewport: TerminalSnapshot, lineCount: number): string {
+  return extractTailLines(viewport, lineCount).join('\n')
 }
 
 function classifyBuiltin(

package/src/pty/last-line.ts

@@ -0,0 +1,29 @@
+/**
+ * Extract a terminal viewport's last non-blank rendered line.
+ *
+ * Used by the daemon's `listTabs` handler to answer "what is this worker
+ * doing?" without a per-tab `snapshot` round-trip. Unlike the status loop's
+ * private `tailPreview`, this does NOT cap the width — the orchestrator wants
+ * the whole status line — and it returns `undefined` (rather than a sentinel)
+ * when there is nothing to show, so the field is simply omitted from the wire.
+ */
+import type { TerminalSnapshot } from '../state/types'
+
+import { getLineText } from '../input/terminal-text-extraction'
+
+/**
+ * The last non-blank line of `viewport`, trimmed. Scans rows from the bottom so
+ * trailing blank rows are skipped. Returns `undefined` when the viewport is
+ * missing or entirely blank.
+ */
+export function lastNonBlankLine(viewport: TerminalSnapshot | undefined): string | undefined {
+  if (!viewport) return undefined
+  const lines = viewport.lines
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line) continue
+    const text = getLineText(line).trim()
+    if (text.length > 0) return text
+  }
+  return undefined
+}

package/src/session-backend/remote-session-backend.ts

@@ -192,6 +192,11 @@ export class RemoteSessionBackend
         })
         this.emit('tabActivity', message.payload.tabId, message.payload.status)
         break
+      case 'tabTurnComplete':
+      case 'tabQuestion':
+        // v13 orchestration signals — consumed by the headless CLI, not the UI
+        // backend. Enumerated so the switch stays exhaustive; no UI wiring yet.
+        break
       case 'sessionStatus':
         logDebug('backend.remote.sessionStatus', {
           sessionId: message.payload.sessionId,

package/src/state/types.ts

@@ -18,6 +18,14 @@ export type LegacyPersistedTabStatus = TabStatus | 'exited'
 
 export type TabActivity = 'working' | 'waiting-input' | 'idle'
 
+/**
+ * Classifies why a tab is blocked on user input. `permission` is a tool /
+ * command approval prompt; `question` is any other prompt the assistant is
+ * waiting on. Carried by the `tabQuestion` server event so an orchestrator can
+ * branch without re-scraping the screen.
+ */
+export type QuestionKind = 'question' | 'permission'
+
 /**
  * Per-session status flags. Both can be true at once (e.g. one tab working,
  * another waiting for user input) so we keep them as independent booleans

package/src/ui/components/layout/sidebar/workspace-list.tsx

@@ -15,7 +15,7 @@ import { formatDivergence } from '../../../../state/session-worktrees'
 import { IDLE_SESSION_STATUS } from '../../../../state/types'
 import { useBusySpinner } from '../../../hooks/use-busy-spinner'
 import { moveIdToIdPosition, orderSessionsForDisplay } from '../../../session-ordering'
-import { useTheme } from '../../../theme'
+import { useBaseTheme, useTheme } from '../../../theme'
 import { FlashLabelBadge } from '../../flash/flash-label-badge'
 import { ContextMenuBox } from '../../overlays/context-menu/context-menu-box'
 import { useSidebarAutoScroll } from './use-sidebar-auto-scroll'
@@ -298,14 +298,17 @@ const WorkspaceRow = memo(function WorkspaceRow({
   status,
 }: WorkspaceRowProps) {
   const t = useTheme()
+  // Selection highlight must stay opaque in transparent mode — otherwise the
+  // cursor row visually disappears against the see-through chrome.
+  const base = useBaseTheme()
   const showSpinner = status.working
   const showWaiting = status.waiting
   const spinner = useBusySpinner(showSpinner)
   let bgColor: string | undefined
   if (dragging || isActiveItem) {
-    bgColor = t.backgroundElement
+    bgColor = base.backgroundElement
   } else if (inCurrentGroup) {
-    bgColor = t.backgroundPanel
+    bgColor = base.backgroundPanel
   }
   const workingColor = t.primary
   const waitingColor = t.warning

package/src/ui/components/layout/sidebar/worktree-row.tsx

@@ -7,7 +7,7 @@ import type { SessionRecord, WorktreeRecord } from '../../../../state/types'
 import { useAppStore } from '../../../../state/app-store'
 import { dispatchGlobal, runSideEffectGlobal } from '../../../../state/dispatch-ref'
 import { formatDivergence } from '../../../../state/session-worktrees'
-import { useTheme } from '../../../theme'
+import { useBaseTheme, useTheme } from '../../../theme'
 import { FlashLabelBadge } from '../../flash/flash-label-badge'
 import { ContextMenuBox } from '../../overlays/context-menu/context-menu-box'
 
@@ -33,6 +33,8 @@ export const WorktreeRow = memo(function WorktreeRow({
   worktree,
 }: WorktreeRowProps) {
   const t = useTheme()
+  // Selection highlight must stay opaque in transparent mode.
+  const base = useBaseTheme()
   const currentSessionId = useAppStore((s) => s.currentSessionId)
   const isCurrentSession = session.id === currentSessionId
   const divergence = useAppStore((s) => s.worktreeDivergence[worktree.id])
@@ -102,9 +104,9 @@ export const WorktreeRow = memo(function WorktreeRow({
 
   let bgColor: string | undefined
   if (isActiveItem) {
-    bgColor = t.backgroundElement
+    bgColor = base.backgroundElement
   } else if (inCurrentGroup) {
-    bgColor = t.backgroundPanel
+    bgColor = base.backgroundPanel
   }
 
   const connector = isLast ? '└─' : '├─'

package/src/ui/components/layout/status-bar.tsx

@@ -11,7 +11,7 @@ import { useAIUsageStore } from '../../../state/ai-usage-store'
 import { useAppStore } from '../../../state/app-store'
 import { useKeymap } from '../../keymap-context'
 import { getStatusBarModel, type IdentitySegment } from '../../status-bar-model'
-import { useTheme } from '../../theme'
+import { useBaseTheme, useTheme } from '../../theme'
 import { AIUsageIndicator } from '../overlays/ai-usage/ai-usage-indicator'
 
 // Powerline-style separator glyph pairs.
@@ -110,6 +110,10 @@ function Separator({ bg, fg, glyph }: { bg: string; fg: string; glyph: string })
 
 export function StatusBar() {
   const t = useTheme()
+  // Badge foregrounds (mode label, version) sit on colored tiles and would
+  // render invisible with a transparent chrome color — always use the base
+  // (opaque) background token for contrast against those tiles.
+  const base = useBaseTheme()
   const state = useAppStore((s) => s)
   const config = useKeymap()
   const model = getStatusBarModel(state, config)
@@ -139,7 +143,7 @@ export function StatusBar() {
       <box height={1} flexShrink={0} flexDirection="row" overflow="hidden">
         {/* A: mode */}
         <box backgroundColor={modeColor} paddingLeft={1} paddingRight={1}>
-          <text fg={t.background} selectable={false}>
+          <text fg={base.background} selectable={false}>
             {getModeBadge(state.focusMode)}
           </text>
         </box>
@@ -186,7 +190,7 @@ export function StatusBar() {
 
         {/* Y: version */}
         <box backgroundColor={tileY} paddingLeft={1} paddingRight={1} flexShrink={0}>
-          <text fg={t.background} selectable={false}>
+          <text fg={base.background} selectable={false}>
             v{APP_VERSION}
           </text>
         </box>

package/src/ui/theme-store.ts

@@ -26,8 +26,7 @@ const themeStore = createStore<ThemeStore>(() => ({
 let cachedId: ThemeId | null = null
 let cachedMode: ThemeMode | null = null
 let cachedBase: ResolvedTuiTheme | null = null
-let cachedTransparent: boolean | null = null
-let cachedFinal: ResolvedTuiTheme | null = null
+let cachedOverlay: ResolvedTuiTheme | null = null
 
 // Chrome surface tokens: when transparent mode is on we replace these with
 // 'transparent' so opentui's BoxRenderable skips its fill (alpha=0 early-returns
@@ -41,27 +40,27 @@ const CHROME_BG_TOKENS = [
   'backgroundMenu',
 ] as const
 
+// Both the opaque base and the transparent overlay are cached side-by-side
+// (both keyed by id+mode). A single-slot cache would thrash when useTheme() and
+// useBaseTheme() are both mounted with different transparent values — each call
+// would invalidate the other's cache, hand React a fresh object reference every
+// render, and drive an infinite update loop.
 function derive(id: ThemeId, mode: ThemeMode, transparent: boolean): ResolvedTuiTheme {
-  if (cachedFinal && cachedId === id && cachedMode === mode && cachedTransparent === transparent)
-    return cachedFinal
-
   if (!cachedBase || cachedId !== id || cachedMode !== mode) {
     const json = TUI_THEMES[id] ?? TUI_THEMES.aimux
     if (!json) throw new Error(`No theme JSON for ${id}`)
     cachedBase = resolveTuiTheme(json, mode)
+    cachedOverlay = null
+    cachedId = id
+    cachedMode = mode
   }
-  cachedId = id
-  cachedMode = mode
-  cachedTransparent = transparent
-
-  if (transparent) {
+  if (!transparent) return cachedBase
+  if (!cachedOverlay) {
     const overlay: ResolvedTuiTheme = { ...cachedBase }
     for (const key of CHROME_BG_TOKENS) overlay[key] = 'transparent'
-    cachedFinal = overlay
-  } else {
-    cachedFinal = cachedBase
+    cachedOverlay = overlay
   }
-  return cachedFinal
+  return cachedOverlay
 }
 
 /** Subscribe to the resolved TUI theme for the active id+mode (+transparent overlay). */
@@ -69,6 +68,16 @@ export function useTheme(): ResolvedTuiTheme {
   return useStore(themeStore, (s) => derive(s.id, s.mode, s.transparent))
 }
 
+/**
+ * Resolved TUI theme WITHOUT the transparent chrome overlay. Use for the rare
+ * chrome sites that must stay opaque even in transparent mode — e.g. the
+ * sidebar selection highlight (would otherwise vanish) and the status-bar
+ * badge foregrounds (would otherwise render as transparent-on-color).
+ */
+export function useBaseTheme(): ResolvedTuiTheme {
+  return useStore(themeStore, (s) => derive(s.id, s.mode, false))
+}
+
 /** Synchronous snapshot of the resolved theme for non-React callers. */
 export function getCurrentTheme(): ResolvedTuiTheme {
   const s = themeStore.getState()