fix(terminal): restore the floating workspace open and maximized

The panel's open and maximized flags were never persisted, so every restart
dropped the user into a closed, default-sized panel that they reopened and
re-maximized by hand. On a typical window that is 113 columns to 211, and
113/211 is the ~55% left band in the bug report.

That column jump reflows the xterm buffer. Rows written at the narrow width
carry wrapped continuations that unwrap into the wide grid, leaving
interleaved tails and stacked status lines under a live relative-cursor TUI.
The live region recovers on the next repaint; the reflowed scrollback never
does. Correct PTY sizing cannot undo it, so the fix is to not make the jump.

Persist both flags, restore maximized geometry in the bounds initializer so
the first paint is already final, and hold the panel's terminals until the
viewport settles - the window restores its saved bounds and only then
maximizes, so mounting earlier fits terminals to a grid it is about to leave.

src/renderer/src/App.tsx

@@ -74,6 +74,10 @@ import { onOnboardingReopened } from './components/onboarding/show-onboarding-ev
 import { shouldShowOnboarding } from './components/onboarding/should-show-onboarding'
 import { MarkdownTemplatePicker } from './components/editor/MarkdownTemplatePicker'
 import { FloatingTerminalToggleButton } from './components/floating-terminal/FloatingTerminalToggleButton'
+import {
+  persistFloatingTerminalPanelOpen,
+  readPersistedFloatingTerminalPanelViewState
+} from './components/floating-terminal/floating-terminal-panel-view-state'
 import {
   TOGGLE_FLOATING_TERMINAL_EVENT,
   requestFloatingTerminalOpenMaximized
@@ -445,7 +449,11 @@ function App(): React.JSX.Element {
   const clearUnreadDockBadge = useUnreadDockBadge()
   useRadixBodyPointerEventsRecovery()
   useWebSessionTabsSync()
-  const [floatingTerminalOpen, setFloatingTerminalOpen] = useState(false)
+  // Why restored: leaving the panel closed forces the user to reopen and re-maximize it,
+  // and that size jump reflows a live TUI's buffer (see floating-terminal-panel-view-state).
+  const [floatingTerminalOpen, setFloatingTerminalOpen] = useState(
+    () => readPersistedFloatingTerminalPanelViewState()?.open === true
+  )
   const floatingWorkspaceTourInteractionSnapshotRef = useRef<{
     wasPreviouslyInteracted?: boolean
     persisted?: Promise<void>
@@ -637,6 +645,7 @@ function App(): React.JSX.Element {
         restoreFloatingTerminalReturnFocus()
       }
       setFloatingTerminalOpen(resolvedOpen)
+      persistFloatingTerminalPanelOpen(resolvedOpen)
     },
     [floatingTerminalOpen, rememberFloatingTerminalReturnFocus, restoreFloatingTerminalReturnFocus]
   )

src/renderer/src/components/floating-terminal/FloatingTerminalPanel.test.tsx

@@ -1156,14 +1156,24 @@ describe('FloatingTerminalPanel close behavior', () => {
 
     element = await renderPanel(true)
     expect(getPanelStyleBounds(element)).toEqual(getMaximizedFloatingTerminalBounds())
-    expect(getMockedLocalStorage().setItem).not.toHaveBeenCalled()
+    // Why key-scoped rather than "no writes": maximize now persists panel view state under
+    // its own key. The invariant here is that the saved NORMAL bounds are never clobbered.
+    expect(getMockedLocalStorage().setItem).not.toHaveBeenCalledWith(
+      FLOATING_TERMINAL_PANEL_BOUNDS_STORAGE_KEY,
+      expect.anything()
+    )
 
     const restoredControls = findByTypeName(element, 'FloatingTerminalWindowControls')
     ;(restoredControls.props.onToggleMaximized as () => void)()
     element = await renderPanel(true)
 
     expect(getPanelStyleBounds(element)).toEqual(savedBounds)
-    expect(getMockedLocalStorage().setItem).not.toHaveBeenCalled()
+    // Why key-scoped rather than "no writes": maximize now persists panel view state under
+    // its own key. The invariant here is that the saved NORMAL bounds are never clobbered.
+    expect(getMockedLocalStorage().setItem).not.toHaveBeenCalledWith(
+      FLOATING_TERMINAL_PANEL_BOUNDS_STORAGE_KEY,
+      expect.anything()
+    )
   })
 
   it('restores committed normal bounds after maximizing from a skinny clamp', async () => {
@@ -1198,7 +1208,12 @@ describe('FloatingTerminalPanel close behavior', () => {
       width: 920,
       height: 560
     })
-    expect(getMockedLocalStorage().setItem).not.toHaveBeenCalled()
+    // Why key-scoped rather than "no writes": maximize now persists panel view state under
+    // its own key. The invariant here is that the saved NORMAL bounds are never clobbered.
+    expect(getMockedLocalStorage().setItem).not.toHaveBeenCalledWith(
+      FLOATING_TERMINAL_PANEL_BOUNDS_STORAGE_KEY,
+      expect.anything()
+    )
   })
 
   it('does not bootstrap a terminal tab when the panel opens empty', async () => {

src/renderer/src/components/floating-terminal/FloatingTerminalPanel.tsx

@@ -94,18 +94,24 @@ export { FloatingTerminalToggleButton } from './FloatingTerminalToggleButton'
 import {
   anchorFloatingTerminalPanelBounds,
   clampFloatingTerminalBounds,
-  getDefaultFloatingTerminalCommittedBounds,
   getDefaultFloatingTerminalBounds,
+  getDefaultFloatingTerminalCommittedBounds,
   getMaximizedFloatingTerminalBounds,
   persistFloatingTerminalPanelBounds,
   readPersistedFloatingTerminalPanelBounds,
-  resolveFloatingTerminalPanelCommittedBounds,
   resolveFloatingTerminalPanelBounds,
+  resolveFloatingTerminalPanelCommittedBounds,
   shouldReconcileFloatingTerminalPanelBounds,
   type FloatingTerminalPanelBounds,
-  type FloatingTerminalPanelCommittedBounds,
-  type FloatingTerminalPanelBoundsSource
+  type FloatingTerminalPanelBoundsSource,
+  type FloatingTerminalPanelCommittedBounds
 } from './floating-terminal-panel-bounds'
+import {
+  persistFloatingTerminalPanelMaximized,
+  readPersistedFloatingTerminalPanelViewState
+} from './floating-terminal-panel-view-state'
+import { useSettledPanelViewport } from './use-settled-panel-viewport'
+import { shouldRestoreMaximizedPanelBounds } from './floating-terminal-panel-restore-geometry'
 import { translate } from '@/i18n/i18n'
 import { consumeFloatingTerminalOpenMaximizedIntent } from '@/lib/floating-terminal'
 import { selectFloatingTerminalPanelInputs } from './floating-terminal-panel-inputs'
@@ -161,6 +167,17 @@ function readInitialPanelBounds(): FloatingTerminalPanelBoundsState {
   const defaultCommittedBounds = getDefaultFloatingTerminalCommittedBounds()
   const defaultRenderedBounds = getDefaultFloatingTerminalBounds()
   const persistedBounds = readPersistedFloatingTerminalPanelBounds()
+  if (shouldRestoreMaximizedPanelBounds(readPersistedFloatingTerminalPanelViewState())) {
+    // Why maximized wins the RENDERED rect while the committed rect stays the restore
+    // target: the first paint must already be final geometry, or the panes fit at the
+    // smaller size and the later maximize reflows them. Un-maximizing still returns to
+    // the user's own bounds because those remain committed.
+    return {
+      committedBounds: persistedBounds ?? defaultCommittedBounds,
+      renderedBounds: getMaximizedFloatingTerminalBounds(),
+      source: persistedBounds ? 'user' : 'default'
+    }
+  }
   return persistedBounds
     ? {
         committedBounds: persistedBounds,
@@ -267,7 +284,10 @@ export function FloatingTerminalPanel({
     initialBoundsStateRef.current.committedBounds
   )
   const [bounds, setBounds] = useState(initialBoundsStateRef.current.renderedBounds)
-  const [maximized, setMaximized] = useState(false)
+  const [maximized, setMaximized] = useState(
+    () => readPersistedFloatingTerminalPanelViewState()?.maximized === true
+  )
+  const panelViewportSettled = useSettledPanelViewport()
   const [orchestrationDialogOpen, setOrchestrationDialogOpen] = useState(false)
   const [showOrchestrationSetup, setShowOrchestrationSetup] = useState(
     () => !hasOrchestrationSetupMarker() && !isOrchestrationSetupDismissed()
@@ -1126,6 +1146,7 @@ export function FloatingTerminalPanel({
       stagedBoundsRef.current = null
       setBounds(restoredBounds)
       setMaximized(false)
+      persistFloatingTerminalPanelMaximized(false)
       return
     }
     restoreBoundsRef.current = {
@@ -1136,6 +1157,7 @@ export function FloatingTerminalPanel({
     stagedBoundsRef.current = null
     setBounds(getMaximizedFloatingTerminalBounds())
     setMaximized(true)
+    persistFloatingTerminalPanelMaximized(true)
   }, [bounds, maximized])
 
   const maximizePanel = useCallback(() => {
@@ -1153,6 +1175,7 @@ export function FloatingTerminalPanel({
     stagedBoundsRef.current = null
     setBounds(getMaximizedFloatingTerminalBounds())
     setMaximized(true)
+    persistFloatingTerminalPanelMaximized(true)
   }, [bounds, maximized])
 
   useEffect(() => {
@@ -1830,7 +1853,11 @@ export function FloatingTerminalPanel({
             hasVisibleFloatingTabs ? 'floating-workspace-surface' : undefined
           }
         >
-          {cwd
+          {/* Why also gated on a settled viewport: a restored-maximized panel derives its
+              rect from the live viewport, so mounting terminals before the window finishes
+              maximizing fits them to a grid it is about to leave, and the correcting fit
+              reflows the buffer under a live TUI. */}
+          {cwd && panelViewportSettled
             ? tabs
                 .filter((tab) => !parkedTerminalTabIds.has(tab.id))
                 .map((tab) => {

src/renderer/src/components/floating-terminal/floating-terminal-panel-restore-geometry.ts

@@ -0,0 +1,18 @@
+import { hasUsableFloatingTerminalPanelViewport } from './floating-terminal-panel-bounds'
+import type { FloatingTerminalPanelViewState } from './floating-terminal-panel-view-state'
+
+/**
+ * Whether the panel's first rendered rect should be the maximized one.
+ *
+ * Why this is a decision and not just a flag read: maximized geometry is derived from the
+ * live viewport, so restoring it against a viewport too small to hold the panel would pin
+ * the terminals to a grid the window is about to leave — the size jump this restore exists
+ * to remove. When the viewport cannot answer yet, fall back to the committed bounds and let
+ * the ordinary reconcile path maximize once layout is real.
+ */
+export function shouldRestoreMaximizedPanelBounds(
+  viewState: FloatingTerminalPanelViewState | null,
+  hasUsableViewport: () => boolean = hasUsableFloatingTerminalPanelViewport
+): boolean {
+  return viewState?.maximized === true && hasUsableViewport()
+}

src/renderer/src/components/floating-terminal/floating-terminal-panel-view-state.test.ts

@@ -0,0 +1,81 @@
+/** @vitest-environment happy-dom */
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY,
+  persistFloatingTerminalPanelMaximized,
+  persistFloatingTerminalPanelOpen,
+  readPersistedFloatingTerminalPanelViewState
+} from './floating-terminal-panel-view-state'
+import { shouldRestoreMaximizedPanelBounds } from './floating-terminal-panel-restore-geometry'
+
+afterEach(() => {
+  window.localStorage.clear()
+})
+
+describe('floating terminal panel view state', () => {
+  it('returns null when nothing was ever persisted', () => {
+    expect(readPersistedFloatingTerminalPanelViewState()).toBeNull()
+  })
+
+  it('round-trips both flags', () => {
+    persistFloatingTerminalPanelOpen(true)
+    persistFloatingTerminalPanelMaximized(true)
+    expect(readPersistedFloatingTerminalPanelViewState()).toEqual({ open: true, maximized: true })
+  })
+
+  it('does not clobber the other owner_s flag', () => {
+    // Why: `open` is written by the app shell and `maximized` by the panel, so a
+    // whole-record write from either would drop the other's value.
+    persistFloatingTerminalPanelMaximized(true)
+    persistFloatingTerminalPanelOpen(false)
+    expect(readPersistedFloatingTerminalPanelViewState()).toEqual({ open: false, maximized: true })
+
+    persistFloatingTerminalPanelOpen(true)
+    persistFloatingTerminalPanelMaximized(false)
+    expect(readPersistedFloatingTerminalPanelViewState()).toEqual({ open: true, maximized: false })
+  })
+
+  it('restores the half a older record carries', () => {
+    // Why: a record written before the second flag existed must still restore.
+    window.localStorage.setItem(
+      FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY,
+      JSON.stringify({ open: true })
+    )
+    expect(readPersistedFloatingTerminalPanelViewState()).toEqual({ open: true, maximized: false })
+  })
+
+  it('treats malformed storage as absent instead of throwing', () => {
+    for (const value of ['not json', '[]', 'null', '"open"', '42']) {
+      window.localStorage.setItem(FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY, value)
+      expect(readPersistedFloatingTerminalPanelViewState()).toBeNull()
+    }
+  })
+
+  it('ignores non-boolean flag values rather than coercing them', () => {
+    window.localStorage.setItem(
+      FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY,
+      JSON.stringify({ open: 'yes', maximized: 1 })
+    )
+    expect(readPersistedFloatingTerminalPanelViewState()).toEqual({ open: false, maximized: false })
+  })
+})
+
+describe('shouldRestoreMaximizedPanelBounds', () => {
+  it('restores maximized geometry only when the viewport can hold it', () => {
+    expect(shouldRestoreMaximizedPanelBounds({ open: true, maximized: true }, () => true)).toBe(
+      true
+    )
+    // Why: maximized bounds come from the live viewport, so restoring against one too small
+    // pins terminals to a grid the window is about to leave - the jump this restore removes.
+    expect(shouldRestoreMaximizedPanelBounds({ open: true, maximized: true }, () => false)).toBe(
+      false
+    )
+  })
+
+  it('does not restore maximized geometry for a non-maximized or absent record', () => {
+    expect(shouldRestoreMaximizedPanelBounds({ open: true, maximized: false }, () => true)).toBe(
+      false
+    )
+    expect(shouldRestoreMaximizedPanelBounds(null, () => true)).toBe(false)
+  })
+})

src/renderer/src/components/floating-terminal/floating-terminal-panel-view-state.ts

@@ -0,0 +1,66 @@
+export const FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY =
+  'orca-floating-terminal-panel-view-state-v1'
+
+export type FloatingTerminalPanelViewState = {
+  open: boolean
+  maximized: boolean
+}
+
+function getWindowStorage(): Storage | null {
+  return typeof window === 'undefined' ? null : window.localStorage
+}
+
+/**
+ * Why persisted separately from the bounds record: maximized geometry is derived
+ * from the live viewport rather than stored, so this is view state, not a rect.
+ * Keeping it out of the bounds union also keeps that type a pure rectangle.
+ *
+ * Why it matters: an unpersisted maximize means every restart drops the user into
+ * a default-sized panel that they re-maximize by hand. That size jump reflows the
+ * xterm buffer under a live relative-cursor TUI, which unwraps its rows and leaves
+ * permanently mangled scrollback. Restoring the panel as it was removes the jump.
+ */
+export function readPersistedFloatingTerminalPanelViewState(): FloatingTerminalPanelViewState | null {
+  try {
+    const serialized = getWindowStorage()?.getItem(FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY)
+    if (!serialized) {
+      return null
+    }
+    const parsed: unknown = JSON.parse(serialized)
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return null
+    }
+    const record = parsed as Record<string, unknown>
+    // Why each flag is read independently: a record written before the other flag
+    // existed must still restore the half it does carry.
+    return {
+      open: record.open === true,
+      maximized: record.maximized === true
+    }
+  } catch {
+    return null
+  }
+}
+
+export function persistFloatingTerminalPanelViewState(state: FloatingTerminalPanelViewState): void {
+  try {
+    getWindowStorage()?.setItem(
+      FLOATING_TERMINAL_PANEL_VIEW_STATE_STORAGE_KEY,
+      JSON.stringify(state)
+    )
+  } catch {
+    // Why: storage can be unavailable or full; losing the restore is not worth a crash.
+  }
+}
+
+// Why field-scoped writers: `open` is owned by the app shell and `maximized` by the panel,
+// so a whole-record write from either side would clobber the other's flag.
+export function persistFloatingTerminalPanelOpen(open: boolean): void {
+  const current = readPersistedFloatingTerminalPanelViewState()
+  persistFloatingTerminalPanelViewState({ maximized: current?.maximized === true, open })
+}
+
+export function persistFloatingTerminalPanelMaximized(maximized: boolean): void {
+  const current = readPersistedFloatingTerminalPanelViewState()
+  persistFloatingTerminalPanelViewState({ open: current?.open === true, maximized })
+}

src/renderer/src/components/floating-terminal/use-settled-panel-viewport.ts

@@ -0,0 +1,69 @@
+import { useEffect, useState } from 'react'
+
+// Why two frames: the main window restores its saved bounds and only then maximizes, so
+// the renderer's first layout can be a size the window is about to leave. One unchanged
+// frame can land inside that gap; two straddle it.
+const REQUIRED_STABLE_FRAMES = 2
+// Why a cap: a window that never stops resizing (a drag, a display change) must not hold
+// the panel's terminals forever. Mounting at a stale size is recoverable; never mounting is not.
+const MAX_SETTLE_MS = 300
+
+function readViewport(): { width: number; height: number } {
+  return { width: window.innerWidth, height: window.innerHeight }
+}
+
+/**
+ * Reports true once the viewport has held one size across consecutive frames.
+ *
+ * Why the floating panel waits for this: its maximized rect is derived from the live
+ * viewport, so mounting terminals against a pre-maximize viewport fits them to a grid the
+ * window is about to leave. The correcting fit then reflows the xterm buffer under a live
+ * TUI, which is the damage this whole path exists to avoid. Latching true is deliberate —
+ * later resizes are ordinary user resizes and the normal fit path owns them.
+ */
+export function useSettledPanelViewport(): boolean {
+  const [settled, setSettled] = useState(false)
+
+  useEffect(() => {
+    if (settled || typeof window === 'undefined') {
+      return
+    }
+    if (typeof requestAnimationFrame !== 'function') {
+      setSettled(true)
+      return
+    }
+    let frameId: number | null = null
+    let previous = readViewport()
+    let stableFrames = 0
+    const settle = (): void => {
+      if (frameId !== null) {
+        cancelAnimationFrame(frameId)
+        frameId = null
+      }
+      setSettled(true)
+    }
+    const capId = setTimeout(settle, MAX_SETTLE_MS)
+    const step = (): void => {
+      const current = readViewport()
+      stableFrames =
+        current.width === previous.width && current.height === previous.height
+          ? stableFrames + 1
+          : 0
+      previous = current
+      if (stableFrames >= REQUIRED_STABLE_FRAMES) {
+        settle()
+        return
+      }
+      frameId = requestAnimationFrame(step)
+    }
+    frameId = requestAnimationFrame(step)
+    return () => {
+      clearTimeout(capId)
+      if (frameId !== null) {
+        cancelAnimationFrame(frameId)
+      }
+    }
+  }, [settled])
+
+  return settled
+}