@brimveyn/aimux 1.14.8 → 1.14.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.14.8",
+  "version": "1.14.10",
   "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

@@ -57,6 +57,7 @@ import {
 } from '../state/layout-tree'
 import { filterAssistants, filterSessions, filterSnippets } from '../state/selectors'
 import { saveSessionCatalog } from '../state/session-catalog'
+import { pruneSnapshotOfWorktree } from '../state/session-persistence'
 import {
   filterTabsForActiveWorktree,
   getActiveWorktree,
@@ -795,7 +796,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 +1059,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 +1076,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 +1224,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,
@@ -1472,6 +1525,7 @@ function removeWorktreeRecordFromSession(
     activeWorktreeId: nextActive?.id,
     projectPath: nextActive?.path ?? entry.projectPath,
     updatedAt: new Date().toISOString(),
+    workspaceSnapshot: pruneSnapshotOfWorktree(entry.workspaceSnapshot, worktreeId),
     worktrees: remaining,
   }))
   saveSessionCatalog(sessions)

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/reducers/tab-state.ts

@@ -394,7 +394,12 @@ export function reduceTabState(state: AppState, action: AppAction): AppState | n
       if (state.tabs.length === 0) {
         return state
       }
-      const orderedTabs = orderTabsByWorktree(state.tabs, getCurrentSession(state))
+      const session = getCurrentSession(state)
+      const visibleTabs = filterTabsForActiveWorktree(state.tabs, session)
+      if (visibleTabs.length === 0) {
+        return state
+      }
+      const orderedTabs = orderTabsByWorktree(visibleTabs, session)
       const currentIndex = orderedTabs.findIndex((tab) => tab.id === state.activeTabId)
       const safeIndex = currentIndex === -1 ? 0 : currentIndex
       const nextIndex = (safeIndex + action.delta + orderedTabs.length) % orderedTabs.length

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,
@@ -111,6 +126,58 @@ export function restoreLayoutTrees(
   return { layoutTrees, tabGroupMap }
 }
 
+// When a worktree is removed, its tabs are killed live via disposeWorktreeTabs
+// — but the session's persisted workspaceSnapshot still references them by
+// worktreeId. Without this pruning, a subsequent load-session (session switch
+// or restart) resurrects the dead tabs and they reappear in h-l navigation.
+export function pruneSnapshotOfWorktree(
+  snapshot: WorkspaceSnapshotV1 | undefined,
+  worktreeId: string
+): WorkspaceSnapshotV1 | undefined {
+  if (!snapshot) return snapshot
+  const keptTabs = snapshot.tabs.filter((tab) => tab.worktreeId !== worktreeId)
+  if (keptTabs.length === snapshot.tabs.length) return snapshot
+  const validTabIds = new Set(keptTabs.map((tab) => tab.id))
+
+  let nextLayoutTrees: typeof snapshot.layoutTrees
+  let nextTabGroupMap: typeof snapshot.tabGroupMap
+  if (snapshot.layoutTrees) {
+    const trees: Record<string, LayoutNode> = {}
+    const groupMap: Record<string, string> = {}
+    for (const [groupId, tree] of Object.entries(snapshot.layoutTrees)) {
+      const pruned = pruneLayoutTree(tree, validTabIds)
+      if (pruned && pruned.type === 'split') {
+        trees[groupId] = pruned
+        for (const leafId of allLeafIds(pruned)) {
+          groupMap[leafId] = groupId
+        }
+      }
+    }
+    nextLayoutTrees = Object.keys(trees).length > 0 ? trees : undefined
+    nextTabGroupMap = Object.keys(groupMap).length > 0 ? groupMap : undefined
+  }
+
+  let nextLayoutTree = snapshot.layoutTree
+  if (nextLayoutTree) {
+    const pruned = pruneLayoutTree(nextLayoutTree, validTabIds)
+    nextLayoutTree = pruned && pruned.type === 'split' ? pruned : undefined
+  }
+
+  const nextActiveTabId =
+    snapshot.activeTabId != null && validTabIds.has(snapshot.activeTabId)
+      ? snapshot.activeTabId
+      : (keptTabs[0]?.id ?? null)
+
+  return {
+    ...snapshot,
+    activeTabId: nextActiveTabId,
+    layoutTree: nextLayoutTree,
+    layoutTrees: nextLayoutTrees,
+    tabGroupMap: nextTabGroupMap,
+    tabs: keptTabs,
+  }
+}
+
 export function normalizeGroupedTabOrder(
   tabs: TabSession[],
   layoutTrees: Record<string, LayoutNode>,
@@ -169,12 +236,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/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)
   })
 }