@brimveyn/aimux 1.14.7 → 1.14.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.14.7",
+  "version": "1.14.9",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",

package/src/app-runtime/side-effects.ts

@@ -795,7 +795,7 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
       return
     }
     case 'switch-session-by-index': {
-      handleSwitchSessionByIndex(ctx, effect.index)
+      handleSwitchSessionByIndex(ctx, effect.index, effect.worktreeId)
       return
     }
     case 'cycle-sidebar-item': {
@@ -1058,13 +1058,14 @@ async function openEditorInline(
   }
 }
 
-function handleSwitchSessionByIndex(ctx: SideEffectContext, index: number): void {
+function handleSwitchSessionByIndex(
+  ctx: SideEffectContext,
+  index: number,
+  worktreeId?: string
+): void {
   const { backend, dispatch } = ctx
   // Read fresh state. ctx.state is the snapshot from the previous render and
-  // lags behind dispatches that happened in the same JS turn (a worktree-row
-  // click first dispatches set-active-worktree then fires this side effect —
-  // we need to see that just-applied activeWorktreeId so the new session
-  // lands on the right worktree, not its last-saved one).
+  // lags behind dispatches that happened in the same JS turn.
   const state = ctx.getState()
   const ordered = [...state.sessions].sort(
     (a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER)
@@ -1074,13 +1075,60 @@ function handleSwitchSessionByIndex(ctx: SideEffectContext, index: number): void
     logInputDebug('app.sessionBar.switchOutOfRange', { index, total: ordered.length })
     return
   }
+
+  // Resolve which worktree to land on. If the caller passed an explicit
+  // `worktreeId` (workspace-row tap → its primary, worktree-row tap → that
+  // worktree), honor it; otherwise let the target session keep its persisted
+  // activeWorktreeId.
+  const resolvedWorktreeId =
+    worktreeId != null &&
+    worktreeId !== '' &&
+    (target.worktrees?.some((w) => w.id === worktreeId) ?? false)
+      ? worktreeId
+      : undefined
+  const needsWorktreeChange =
+    resolvedWorktreeId != null && resolvedWorktreeId !== target.activeWorktreeId
+
   if (target.id === state.currentSessionId) {
+    if (needsWorktreeChange) {
+      dispatch({
+        sessionId: target.id,
+        type: 'set-active-worktree',
+        worktreeId: resolvedWorktreeId,
+      })
+    }
     if (state.focusMode === 'git') {
       dispatch({ type: 'exit-git-mode' })
     }
     return
   }
-  handleSwitchSessionEffect(state, backend, dispatch, target)
+
+  // Cross-workspace: bundle the worktree change into the session record AND
+  // fold set-sessions + load-session into a SINGLE setState call. Otherwise
+  // any subscriber notification (re-render, useEffect, backend re-attach)
+  // between dispatches can re-assert the session's previously-persisted
+  // activeWorktreeId, dropping the user back on the last-visited worktree.
+  const patchedSession = needsWorktreeChange
+    ? withActiveWorktree(target, resolvedWorktreeId)
+    : target
+  const patchedState: AppState = needsWorktreeChange
+    ? {
+        ...state,
+        sessions: state.sessions.map((s) => (s.id === patchedSession.id ? patchedSession : s)),
+      }
+    : state
+  const sessions = switchSessionRecords(patchedState, patchedSession)
+  saveSessionCatalog(sessions)
+  void backend.destroy(true)
+  appStore.setState((current) => {
+    const afterSet = appReducer(current, { sessions, type: 'set-sessions' })
+    return appReducer(afterSet, {
+      forceDisconnected: false,
+      sessionId: patchedSession.id,
+      type: 'load-session',
+      workspaceSnapshot: patchedSession.workspaceSnapshot,
+    })
+  })
 }
 
 interface SidebarItem {
@@ -1175,6 +1223,10 @@ function handleCycleSidebarItem(ctx: SideEffectContext, direction: 1 | -1): void
     appStore.setState((current) => {
       const afterSet = appReducer(current, { sessions, type: 'set-sessions' })
       return appReducer(afterSet, {
+        // Daemon is alive and attach() will hydrate real statuses within a
+        // frame, so skip the snapshot's running→disconnected downgrade —
+        // otherwise the "Restored snapshot" hint flashes on every j/k cycle.
+        forceDisconnected: false,
         sessionId: patchedSession.id,
         type: 'load-session',
         workspaceSnapshot: patchedSession.workspaceSnapshot,

package/src/index.tsx

@@ -60,6 +60,11 @@ if (command === '--help' || command === '-h') {
 
 const renderer = await createCliRenderer({
   autoFocus: true,
+  // Transparent clear color so cells untouched by BoxRenderable paints (e.g.
+  // when transparent mode overrides all chrome bg tokens to alpha=0) flush to
+  // the terminal with no bg, letting the host terminal's background show
+  // through. With an opaque clear color, transparent mode is a no-op.
+  backgroundColor: '#00000000',
   consoleMode: 'disabled',
   exitOnCtrlC: false,
   screenMode: 'alternate-screen',

package/src/input/modes/types.ts

@@ -67,7 +67,7 @@ export type SideEffect =
   | { type: 'generate-auto-commit-now'; sessionId: string }
   | { type: 'git-push' }
   | { type: 'confirm-update-selection' }
-  | { type: 'switch-session-by-index'; index: number }
+  | { type: 'switch-session-by-index'; index: number; worktreeId?: string }
   | { type: 'cycle-sidebar-item'; direction: 1 | -1 }
   | { type: 'switch-tab-by-index'; index: number }
   | { type: 'delete-session'; sessionId: string }

package/src/state/reducers/session-state.ts

@@ -18,7 +18,9 @@ export function reduceSessionState(state: AppState, action: AppAction): AppState
       const snapshot =
         action.workspaceSnapshot ??
         state.sessions.find((entry) => entry.id === action.sessionId)?.workspaceSnapshot
-      const restored = restoreWorkspaceState(state, snapshot)
+      const restored = restoreWorkspaceState(state, snapshot, {
+        forceDisconnected: action.forceDisconnected ?? true,
+      })
       // The session's activeWorktreeId may have been patched right before
       // this load (e.g. the cross-workspace branch of handleCycleSidebarItem
       // sets it to the worktree the user just clicked). The snapshot's

package/src/state/session-persistence.ts

@@ -51,11 +51,26 @@ export function serializeWorkspace(state: AppState): WorkspaceSnapshotV1 {
   }
 }
 
-export function restoreTabsFromWorkspace(snapshot: WorkspaceSnapshotV1 | undefined): TabSession[] {
+export interface RestoreOptions {
+  // Force any running/starting tab to 'disconnected' on restore. True for
+  // cold-start (daemon may not own the sessions yet) and the daemon's own
+  // catalog hydration. False for live in-app workspace switches where an
+  // attach() is guaranteed to follow within a frame and hydrate-workspace
+  // will overwrite the status with daemon truth — leaving the flag on would
+  // briefly flash the "Restored snapshot" hint on every j/k cycle.
+  forceDisconnected?: boolean
+}
+
+export function restoreTabsFromWorkspace(
+  snapshot: WorkspaceSnapshotV1 | undefined,
+  options: RestoreOptions = {}
+): TabSession[] {
   if (!snapshot || snapshot.version !== 1) {
     return []
   }
 
+  const forceDisconnected = options.forceDisconnected ?? true
+
   return snapshot.tabs
     .filter(
       (tab): tab is typeof tab & { status: Exclude<typeof tab.status, 'exited'> } =>
@@ -69,7 +84,7 @@ export function restoreTabsFromWorkspace(snapshot: WorkspaceSnapshotV1 | undefin
       errorMessage: tab.errorMessage,
       exitCode: tab.exitCode,
       id: tab.id,
-      status: getDisconnectedStatus(tab.status),
+      status: forceDisconnected ? getDisconnectedStatus(tab.status) : tab.status,
       terminalModes: tab.terminalModes,
       title: tab.title,
       viewport: tab.viewport,
@@ -169,12 +184,13 @@ export function normalizeGroupedTabOrder(
 
 export function restoreWorkspaceState(
   state: AppState,
-  workspaceSnapshot: WorkspaceSnapshotV1 | undefined
+  workspaceSnapshot: WorkspaceSnapshotV1 | undefined,
+  options: RestoreOptions = {}
 ): Pick<
   AppState,
   'tabs' | 'activeTabId' | 'focusMode' | 'sidebar' | 'layoutTrees' | 'tabGroupMap'
 > {
-  const tabs = restoreTabsFromWorkspace(workspaceSnapshot)
+  const tabs = restoreTabsFromWorkspace(workspaceSnapshot, options)
   const activeTabId =
     workspaceSnapshot?.activeTabId != null &&
     workspaceSnapshot?.activeTabId !== '' &&

package/src/state/types.ts

@@ -538,7 +538,12 @@ export type ModalAction =
 
 // -- Session actions --
 export type SessionAction =
-  | { type: 'load-session'; sessionId: string; workspaceSnapshot?: WorkspaceSnapshotV1 }
+  | {
+      type: 'load-session'
+      sessionId: string
+      workspaceSnapshot?: WorkspaceSnapshotV1
+      forceDisconnected?: boolean
+    }
   | { type: 'set-sessions'; sessions: SessionRecord[] }
   | { type: 'create-session-record'; session: SessionRecord }
   | { type: 'rename-session-record'; sessionId: string; name: string }

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

@@ -144,9 +144,23 @@ export function WorkspaceList({ contentWidth }: WorkspaceListProps) {
 
     const idx = baselineOrder.indexOf(source)
     if (idx >= 0) {
-      runSideEffectGlobal({ index: idx + 1, type: 'switch-session-by-index' })
+      // The workspace row visually anchors the session's primary worktree
+      // (its branch line shows the primary's branch). Clicking it should
+      // land on the primary — same semantics as j/k cycling onto a workspace
+      // item — instead of preserving whatever non-primary worktree happened
+      // to be active last time we left this session.
+      const sourceSession = ordered.find((s) => s.id === source)
+      const sourceWorktrees = sourceSession?.worktrees ?? []
+      const sourcePrimaryId = (
+        sourceWorktrees.find((w) => w.source === 'primary') ?? sourceWorktrees[0]
+      )?.id
+      runSideEffectGlobal({
+        index: idx + 1,
+        type: 'switch-session-by-index',
+        worktreeId: sourcePrimaryId,
+      })
     }
-  }, [baselineOrder, dragOrder, draggingId])
+  }, [baselineOrder, dragOrder, draggingId, ordered])
 
   const cancelDrag = useCallback(() => {
     setDraggingId(null)

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

@@ -41,14 +41,23 @@ export const WorktreeRow = memo(function WorktreeRow({
       if (event.button !== 0) return
       event.preventDefault()
       event.stopPropagation()
-      dispatchGlobal({
-        sessionId: session.id,
-        type: 'set-active-worktree',
+      if (isCurrentSession) {
+        dispatchGlobal({
+          sessionId: session.id,
+          type: 'set-active-worktree',
+          worktreeId: worktree.id,
+        })
+        return
+      }
+      // Cross-workspace click: send the worktree id along with the switch so
+      // the side effect can apply it atomically. Splitting it into a separate
+      // dispatch+switch leaves a window where subscribers/re-renders can
+      // re-assert the target session's last-persisted worktree.
+      runSideEffectGlobal({
+        index: sessionIndex,
+        type: 'switch-session-by-index',
         worktreeId: worktree.id,
       })
-      if (!isCurrentSession) {
-        runSideEffectGlobal({ index: sessionIndex, type: 'switch-session-by-index' })
-      }
     },
     [isCurrentSession, session.id, sessionIndex, worktree.id]
   )

package/src/ui/components/layout/terminal-pane.tsx

@@ -330,6 +330,37 @@ export function TerminalPane({
   )
   const forwardScrollEvent = useCallback(
     (event: OtuiMouseEvent) => {
+      // opentui's processMouseEvent dispatches a scroll to the deepest renderable
+      // (the <text> inside this box) BEFORE bubbling up to our handler.
+      // TextBufferRenderable's built-in onMouseEvent unconditionally calls
+      // handleScroll, which mutates its private _scrollY. preventDefault on the
+      // bubbled event can't roll that back — the scroll already happened. And
+      // nothing in React ever resets _scrollY for the lifetime of the renderable.
+      //
+      // Net effect: every wheel event over the terminal nudges the rendered
+      // text away from state.viewport.lines by one wheel step. The drift
+      // accumulates until the user refreshes aimux (re-mounts the text).
+      // Reset _scrollY here, right after the child finished scrolling.
+      const scrollTarget = event.target
+      if (scrollTarget !== null && typeof scrollTarget === 'object') {
+        const currentScrollY = Reflect.get(scrollTarget, 'scrollY')
+        if (typeof currentScrollY === 'number' && currentScrollY !== 0) {
+          try {
+            Reflect.set(scrollTarget, 'scrollY', 0)
+          } catch {
+            // Not all renderables expose a setter; best-effort only.
+          }
+        }
+        const currentScrollX = Reflect.get(scrollTarget, 'scrollX')
+        if (typeof currentScrollX === 'number' && currentScrollX !== 0) {
+          try {
+            Reflect.set(scrollTarget, 'scrollX', 0)
+          } catch {
+            // Not all renderables expose a setter; best-effort only.
+          }
+        }
+      }
+
       if (!canForwardMouse && !canUseLocalScrollback) {
         return
       }

package/src/ui/components/modals/shared/modal-keybinds-overlay.tsx

@@ -1,12 +1,32 @@
 import type { ModeId } from '@brimveyn/aimux-config'
 
+import { type BoxRenderable, type OptimizedBuffer, RGBA } from '@opentui/core'
+
 import { describeBindings } from '../../../../input/keymap/describe-bindings'
 import { useKeymap } from '../../../keymap-context'
-import { useTheme } from '../../../theme'
-import { Surface } from '../../primitives/surface'
+import { useTheme, useTransparent } from '../../../theme'
 
 const KEYS_COLUMN_WIDTH = 12
 
+const TRANSPARENT_RGBA = RGBA.fromValues(0, 0, 0, 0)
+
+// Same trick as modal-shell: when our bg is transparent, BoxRenderable skips
+// its fill so the chrome chars underneath leak through. setCell bypasses alpha
+// blending and char-preservation, so we can wipe every interior cell to
+// (' ', TRANSPARENT_RGBA, TRANSPARENT_RGBA). No border on this overlay, so
+// fill the full bounds (no 1-cell inset).
+function fillBoxInteriorWithSpaces(this: BoxRenderable, buffer: OptimizedBuffer): void {
+  const x0 = this.screenX
+  const y0 = this.screenY
+  const endX = x0 + this.width
+  const endY = y0 + this.height
+  for (let y = y0; y < endY; y++) {
+    for (let x = x0; x < endX; x++) {
+      buffer.setCell(x, y, ' ', TRANSPARENT_RGBA, TRANSPARENT_RGBA)
+    }
+  }
+}
+
 interface ModalKeybindsOverlayProps {
   modeId: ModeId
   limit?: number
@@ -14,6 +34,7 @@ interface ModalKeybindsOverlayProps {
 
 export function ModalKeybindsOverlay({ limit, modeId }: ModalKeybindsOverlayProps) {
   const t = useTheme()
+  const transparent = useTransparent()
   const config = useKeymap()
   const bindings = describeBindings(config, modeId, {
     mergeAlternativesByDescription: true,
@@ -25,7 +46,14 @@ export function ModalKeybindsOverlay({ limit, modeId }: ModalKeybindsOverlayProp
 
   return (
     <box position="absolute" bottom={0} right={0}>
-      <Surface tone="elevated" paddingLeft={2} paddingRight={2} paddingTop={1} paddingBottom={1}>
+      <box
+        backgroundColor={t.backgroundElement}
+        paddingLeft={2}
+        paddingRight={2}
+        paddingTop={1}
+        paddingBottom={1}
+        renderAfter={transparent ? fillBoxInteriorWithSpaces : undefined}
+      >
         {entries.map((binding) => (
           <box key={binding.description ?? binding.keys} flexDirection="row">
             <box width={KEYS_COLUMN_WIDTH}>
@@ -34,7 +62,7 @@ export function ModalKeybindsOverlay({ limit, modeId }: ModalKeybindsOverlayProp
             <text fg={t.textMuted}>{binding.description ?? ''}</text>
           </box>
         ))}
-      </Surface>
+      </box>
     </box>
   )
 }

package/src/ui/theme-store.ts

@@ -25,27 +25,54 @@ const themeStore = createStore<ThemeStore>(() => ({
 
 let cachedId: ThemeId | null = null
 let cachedMode: ThemeMode | null = null
-let cachedResolved: ResolvedTuiTheme | null = null
-
-function derive(id: ThemeId, mode: ThemeMode): ResolvedTuiTheme {
-  if (cachedResolved && cachedId === id && cachedMode === mode) return cachedResolved
+let cachedBase: ResolvedTuiTheme | null = null
+let cachedTransparent: boolean | null = null
+let cachedFinal: 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
+// in setCellWithAlphaBlending) and the host terminal background shows through
+// every chrome site (root, sidebar, tabs, status bar, modals, …) without
+// patching ~30 components one-by-one.
+const CHROME_BG_TOKENS = [
+  'background',
+  'backgroundPanel',
+  'backgroundElement',
+  'backgroundMenu',
+] as const
+
+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)
+  }
   cachedId = id
   cachedMode = mode
-  const json = TUI_THEMES[id] ?? TUI_THEMES.aimux
-  if (!json) throw new Error(`No theme JSON for ${id}`)
-  cachedResolved = resolveTuiTheme(json, mode)
-  return cachedResolved
+  cachedTransparent = transparent
+
+  if (transparent) {
+    const overlay: ResolvedTuiTheme = { ...cachedBase }
+    for (const key of CHROME_BG_TOKENS) overlay[key] = 'transparent'
+    cachedFinal = overlay
+  } else {
+    cachedFinal = cachedBase
+  }
+  return cachedFinal
 }
 
-/** Subscribe to the resolved TUI theme for the active id+mode. */
+/** Subscribe to the resolved TUI theme for the active id+mode (+transparent overlay). */
 export function useTheme(): ResolvedTuiTheme {
-  return useStore(themeStore, (s) => derive(s.id, s.mode))
+  return useStore(themeStore, (s) => derive(s.id, s.mode, s.transparent))
 }
 
 /** Synchronous snapshot of the resolved theme for non-React callers. */
 export function getCurrentTheme(): ResolvedTuiTheme {
   const s = themeStore.getState()
-  return derive(s.id, s.mode)
+  return derive(s.id, s.mode, s.transparent)
 }
 
 export function getCurrentThemeId(): ThemeId {
@@ -96,6 +123,9 @@ export function subscribeThemeChanges(
     if (s.id === lastId && s.mode === lastMode) return
     lastId = s.id
     lastMode = s.mode
-    listener(derive(s.id, s.mode), s.mode)
+    // Pass base theme (transparent=false): the only subscriber today is the
+    // Claude Code theme bridge, which has no transparency concept and wants
+    // the resolved palette.
+    listener(derive(s.id, s.mode, false), s.mode)
   })
 }