@brimveyn/aimux 1.14.3 → 1.14.5

package/src/ipc/manager-protocol.ts

@@ -17,8 +17,23 @@ import {
 // `intent`/`intents` from resize messages and the `reapplyScrollIntent`
 // message. Min is raised in lockstep so a pre-v5 peer (which could still send
 // the dropped message) can't negotiate a now-incompatible version.
-export const MANAGER_PROTOCOL_MIN_VERSION = 5
-export const MANAGER_PROTOCOL_VERSION = 5
+//
+// v6: `createTab` carries an optional `env` payload that the TM merges into
+// the spawned PTY. Daemon uses it to inject `AIMUX_HOOK_URL_FILE` /
+// `AIMUX_PANE_ID` for the Claude Code hook bridge. A pre-v6 TM silently
+// drops the field, so Min is raised in lockstep to force a fresh TM that
+// will actually forward env to the spawn.
+//
+// v7: `TerminalSpan` carries optional `fgPalette`/`bgPalette` (ANSI 0-255
+// indices) instead of pre-converting palette cells to hex. The client
+// resolves them against the host terminal's actual palette (queried via
+// OSC 4 at startup) so user themes (Ghostty, iTerm2, …) show through
+// instead of hardcoded xterm defaults. Cross-version mixing breaks colors
+// either way (pre-v7 TM → new client never sees the indices; new TM →
+// pre-v7 client ignores them and falls back to the theme default), so Min
+// is raised in lockstep to force matching binaries.
+export const MANAGER_PROTOCOL_MIN_VERSION = 7
+export const MANAGER_PROTOCOL_VERSION = 7
 /**
  * Minimum version required to send `setBroadcastEnabled`. Older TMs (v3) will
  * not understand the message; the daemon must check the negotiated version
@@ -68,6 +83,8 @@ export type ManagerRequest =
         cols: number
         rows: number
         cwd?: string
+        /** Extra env vars merged into the spawned PTY's environment. */
+        env?: Record<string, string>
       }
     }
   | { id: string; type: 'write'; payload: { sessionId: string; tabId: string; data: string } }
@@ -147,12 +164,22 @@ function isStringArray(value: unknown): value is string[] {
   return Array.isArray(value) && value.every(isString)
 }
 
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (!isObjectRecord(value)) return false
+  for (const v of Object.values(value)) {
+    if (!isString(v)) return false
+  }
+  return true
+}
+
 function isTerminalSpan(value: unknown): boolean {
   return (
     isObjectRecord(value) &&
     isString(value.text) &&
     (value.fg === undefined || isString(value.fg)) &&
     (value.bg === undefined || isString(value.bg)) &&
+    (value.fgPalette === undefined || isFiniteNumber(value.fgPalette)) &&
+    (value.bgPalette === undefined || isFiniteNumber(value.bgPalette)) &&
     (value.bold === undefined || typeof value.bold === 'boolean') &&
     (value.italic === undefined || typeof value.italic === 'boolean') &&
     (value.underline === undefined || typeof value.underline === 'boolean') &&
@@ -277,6 +304,10 @@ export function parseManagerRequest(value: unknown): ManagerRequest {
         value.payload.cwd === undefined || isString(value.payload.cwd),
         'createTab.cwd must be a string'
       )
+      assert(
+        value.payload.env === undefined || isStringRecord(value.payload.env),
+        'createTab.env must be a string-keyed string record'
+      )
       return value as ManagerRequest
     case 'write':
       assert(isString(value.payload.sessionId), 'write.sessionId must be a string')

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

@@ -0,0 +1,94 @@
+// Merges Claude Code hook events with the visual PTY detector. Hooks are
+// authoritative when fresh: they tell us exactly when a user prompt was
+// submitted, when a tool started or finished, and when Claude is idle. The
+// visual detector still runs every tick — its job is to catch states the
+// hooks don't reliably report (permission prompts that don't fire a
+// Notification, or stale "working" when the hook stream lags).
+//
+// Hooks reference: https://code.claude.com/docs/en/hooks.md
+
+import type { TabActivity } from '../state/types'
+
+/** How long a hook event keeps authority over the visual detector. */
+const HOOK_AUTHORITY_WINDOW_MS = 10_000
+
+interface HookEntry {
+  state: TabActivity
+  at: number
+}
+
+export interface RecordHookEventInput {
+  paneId: string
+  hookEventName: string
+  payload: Record<string, unknown>
+  receivedAt?: number
+}
+
+export class AssistantStatusArbiter {
+  private readonly entries = new Map<string, HookEntry>()
+
+  /**
+   * Map a Claude hook event to a `TabActivity` and record it. Returns the
+   * mapped state (or null if the event was ignored, e.g. SubagentStop on a
+   * parent agent — we don't want a subagent finishing to flip the parent
+   * pane to idle while the parent is still mid-turn).
+   */
+  recordHookEvent(input: RecordHookEventInput): TabActivity | null {
+    const at = input.receivedAt ?? Date.now()
+    const mapped = mapHookEvent(input.hookEventName, input.payload)
+    if (mapped === null) return null
+    this.entries.set(input.paneId, { at, state: mapped })
+    return mapped
+  }
+
+  /**
+   * Arbitrate between a fresh visual classification and the most recent hook
+   * event for the same pane. Hook wins for `working`/`idle`. If the visual
+   * detector saw a permission/yes-no prompt (`waiting-input`) we trust it
+   * regardless of the hook state — some prompts don't fire `Notification`,
+   * and Claude is genuinely paused on user input.
+   */
+  arbitrate(paneId: string, visual: TabActivity, now: number): TabActivity {
+    const hook = this.entries.get(paneId)
+    if (!hook || now - hook.at >= HOOK_AUTHORITY_WINDOW_MS) {
+      return visual
+    }
+    if (visual === 'waiting-input') return 'waiting-input'
+    return hook.state
+  }
+
+  forget(paneId: string): void {
+    this.entries.delete(paneId)
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}
+
+function mapHookEvent(hookEventName: string, payload: Record<string, unknown>): TabActivity | null {
+  // Anything originating inside a subagent has a non-null parent_tool_use_id.
+  // Forwarding its lifecycle to the parent pane is wrong: the parent is still
+  // working while the subagent runs.
+  const parentToolUseId = payload.parent_tool_use_id
+  if (typeof parentToolUseId === 'string' && parentToolUseId.length > 0) {
+    return null
+  }
+
+  switch (hookEventName) {
+    case 'UserPromptSubmit':
+    case 'PreToolUse':
+    case 'PostToolUse':
+      return 'working'
+    case 'Stop':
+      return 'idle'
+    case 'Notification':
+      // Permission requests and other Claude-initiated notifications pause
+      // execution until the user acts — mirror the visual detector's term.
+      return 'waiting-input'
+    case 'SubagentStop':
+      return null
+    default:
+      return null
+  }
+}

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 { AssistantStatusArbiter, type RecordHookEventInput } from './assistant-status-arbiter'
 import { AssistantStatusDetector } from './assistant-status-detector'
 
 function tailPreview(viewport: TerminalSnapshot | undefined): string {
@@ -67,6 +68,12 @@ export interface StatusDetectionLoopHandle {
    * rather than relying on the next scheduled tick.
    */
   classifyNow: (sessionId: string, tabs: LoopTabView[]) => void
+  /**
+   * Feed a Claude Code hook event into the arbiter. The next tick will
+   * combine it with the visual detector's verdict. Called by the daemon's
+   * hook HTTP server.
+   */
+  recordHookEvent: (input: RecordHookEventInput) => void
 }
 
 export function runStatusDetectionLoop(
@@ -74,6 +81,7 @@ export function runStatusDetectionLoop(
 ): StatusDetectionLoopHandle {
   const tickMs = options.tickMs ?? DEFAULT_TICK_MS
   const detector = new AssistantStatusDetector()
+  const arbiter = new AssistantStatusArbiter()
   const lastTabStatus = new Map<string, { status: TabActivity; sessionId: string }>()
   const lastSessionStatus = new Map<string, SessionStatus>()
 
@@ -99,13 +107,14 @@ export function runStatusDetectionLoop(
     let waiting = false
     for (const tab of tabs) {
       seenTabs?.add(tab.id)
-      const status = detector.classify({
+      const visual = detector.classify({
         assistant: tab.assistant,
         command: tab.command,
         now,
         tabId: tab.id,
         viewport: tab.viewport,
       })
+      const status = arbiter.arbitrate(tab.id, visual, now)
       if (status === 'working') working = true
       if (status === 'waiting-input') waiting = true
       const prev = lastTabStatus.get(tab.id)
@@ -158,6 +167,7 @@ export function runStatusDetectionLoop(
     for (const tabId of lastTabStatus.keys()) {
       if (!seenTabs.has(tabId)) {
         detector.forget(tabId)
+        arbiter.forget(tabId)
         lastTabStatus.delete(tabId)
       }
     }
@@ -174,6 +184,14 @@ export function runStatusDetectionLoop(
     },
     getSessionStatus: (sessionId) => lastSessionStatus.get(sessionId),
     getTabStatus: (tabId) => lastTabStatus.get(tabId)?.status,
+    recordHookEvent: (input) => {
+      const mapped = arbiter.recordHookEvent(input)
+      logDebug('statusLoop.recordHookEvent', {
+        hookEventName: input.hookEventName,
+        mapped,
+        paneId: input.paneId,
+      })
+    },
     snapshotSessions: () =>
       [...lastSessionStatus.entries()].map(([sessionId, status]) => ({ sessionId, status })),
     snapshotTabs: () =>
@@ -185,6 +203,7 @@ export function runStatusDetectionLoop(
     stop: () => {
       clearInterval(timer)
       detector.clear()
+      arbiter.clear()
       lastTabStatus.clear()
       lastSessionStatus.clear()
     },

package/src/pty/pty-manager.ts

@@ -238,6 +238,8 @@ export class PtyManager extends EventEmitter<PtyManagerEvents> {
     cols: number
     rows: number
     cwd?: string
+    /** Extra environment variables merged on top of `process.env` for this PTY. */
+    env?: Record<string, string>
   }): void {
     this.disposeSession(options.tabId)
     logDebug('ptyManager.create.start', {
@@ -262,7 +264,9 @@ export class PtyManager extends EventEmitter<PtyManagerEvents> {
         cwd: options.cwd ?? process.cwd(),
         env: {
           ...process.env,
+          COLORTERM: 'truecolor',
           TERM: 'xterm-256color',
+          ...options.env,
         },
         name: 'xterm-256color',
         rows: options.rows,

package/src/pty/terminal-snapshot.ts

@@ -6,66 +6,30 @@ import { getCurrentTheme } from '../ui/theme'
 
 const SNAPSHOT_TAIL_LINE_COUNT = 10
 
-const ANSI_PALETTE = [
-  '#000000',
-  '#cd0000',
-  '#00cd00',
-  '#cdcd00',
-  '#0000ee',
-  '#cd00cd',
-  '#00cdcd',
-  '#e5e5e5',
-  '#7f7f7f',
-  '#ff0000',
-  '#00ff00',
-  '#ffff00',
-  '#5c5cff',
-  '#ff00ff',
-  '#00ffff',
-  '#ffffff',
-]
+// CellColor preserves whether the cell emitted an indexed (ANSI 0-255) color
+// or an RGB color, so the renderer process can resolve indices against the
+// host terminal's actual palette (queried via OSC 4 at startup). Converting
+// indices to RGB here would lock in xterm defaults and silently override the
+// user's terminal theme — that's the very bug we're fixing.
+type CellColor = { kind: 'rgb'; hex: string } | { kind: 'palette'; index: number } | undefined
 
 function toHex(value: number): string {
   return `#${value.toString(16).padStart(6, '0')}`
 }
 
-function paletteToHex(index: number): string {
-  if (index < ANSI_PALETTE.length) {
-    return ANSI_PALETTE[index] ?? ANSI_PALETTE[0] ?? '#000000'
-  }
-
-  if (index >= 232) {
-    const shade = 8 + (index - 232) * 10
-    return toHex((shade << 16) | (shade << 8) | shade)
-  }
-
-  const normalized = index - 16
-  const r = Math.floor(normalized / 36)
-  const g = Math.floor((normalized % 36) / 6)
-  const b = normalized % 6
-  const channel = [0, 95, 135, 175, 215, 255]
-
-  return toHex(((channel[r] ?? 0) << 16) | ((channel[g] ?? 0) << 8) | (channel[b] ?? 0))
-}
-
-function getColorHex(color: number, mode: 'rgb' | 'palette' | 'default'): string | undefined {
-  if (mode === 'default') {
-    return undefined
-  }
-
-  return mode === 'rgb' ? toHex(color) : paletteToHex(color)
+function readCellColor(value: number, isRgb: boolean, isPalette: boolean): CellColor {
+  if (isRgb) return { hex: toHex(value), kind: 'rgb' }
+  if (isPalette) return { index: value, kind: 'palette' }
+  return undefined
 }
 
-function getColorMode(isRgb: boolean, isPalette: boolean): 'rgb' | 'palette' | 'default' {
-  if (isRgb) {
-    return 'rgb'
-  }
-
-  if (isPalette) {
-    return 'palette'
+function applySpanColor(span: TerminalSpan, color: CellColor, side: 'fg' | 'bg'): void {
+  if (!color) return
+  if (color.kind === 'rgb') {
+    span[side] = color.hex
+  } else {
+    span[side === 'fg' ? 'fgPalette' : 'bgPalette'] = color.index
   }
-
-  return 'default'
 }
 
 function pushSpan(spans: TerminalSpan[], span: TerminalSpan): void {
@@ -74,6 +38,8 @@ function pushSpan(spans: TerminalSpan[], span: TerminalSpan): void {
     previous &&
     previous.fg === span.fg &&
     previous.bg === span.bg &&
+    previous.fgPalette === span.fgPalette &&
+    previous.bgPalette === span.bgPalette &&
     previous.bold === span.bold &&
     previous.italic === span.italic &&
     previous.underline === span.underline &&
@@ -109,36 +75,45 @@ function buildLine(
     }
 
     const text = current.getChars() || ' '
-    const fgMode = getColorMode(current.isFgRGB(), current.isFgPalette())
-    const bgMode = getColorMode(current.isBgRGB(), current.isBgPalette())
 
-    let fg = getColorHex(current.getFgColor(), fgMode)
-    let bg = getColorHex(current.getBgColor(), bgMode)
+    let fg: CellColor = readCellColor(
+      current.getFgColor(),
+      current.isFgRGB(),
+      current.isFgPalette()
+    )
+    let bg: CellColor = readCellColor(
+      current.getBgColor(),
+      current.isBgRGB(),
+      current.isBgPalette()
+    )
 
     if (current.isInverse()) {
       const tokens = getCurrentTheme()
-      const resolvedFg = fg ?? tokens.text
-      const resolvedBg = bg ?? tokens.background
-      ;[fg, bg] = [resolvedBg, resolvedFg]
+      const resolvedFg: CellColor = fg ?? { hex: tokens.text, kind: 'rgb' }
+      const resolvedBg: CellColor = bg ?? { hex: tokens.background, kind: 'rgb' }
+      fg = resolvedBg
+      bg = resolvedFg
     }
 
     const isCursorCell = cursorVisible && cursorColumn === column
     if (isCursorCell) {
       const tokens = getCurrentTheme()
-      const resolvedFg = fg ?? tokens.text
-      const resolvedBg = bg ?? tokens.background
-      ;[fg, bg] = [resolvedBg, resolvedFg]
+      const resolvedFg: CellColor = fg ?? { hex: tokens.text, kind: 'rgb' }
+      const resolvedBg: CellColor = bg ?? { hex: tokens.background, kind: 'rgb' }
+      fg = resolvedBg
+      bg = resolvedFg
     }
 
-    pushSpan(spans, {
-      bg,
+    const span: TerminalSpan = {
       bold: current.isBold() ? true : undefined,
       cursor: isCursorCell ? true : undefined,
-      fg,
       italic: current.isItalic() ? true : undefined,
       text,
       underline: current.isUnderline() ? true : undefined,
-    })
+    }
+    applySpanColor(span, fg, 'fg')
+    applySpanColor(span, bg, 'bg')
+    pushSpan(spans, span)
 
     visualColumns += current.getWidth()
   }
@@ -238,6 +213,8 @@ function areSpansEqual(left: TerminalSpan, right: TerminalSpan): boolean {
     left.text === right.text &&
     left.fg === right.fg &&
     left.bg === right.bg &&
+    left.fgPalette === right.fgPalette &&
+    left.bgPalette === right.bgPalette &&
     left.bold === right.bold &&
     left.italic === right.italic &&
     left.underline === right.underline &&

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

@@ -1,7 +1,12 @@
 import { EventEmitter } from 'node:events'
 
-import type { AssistantId, WorkspaceSnapshotV1 } from '../state/types'
-import type { SessionBackend, SessionBackendEvents } from './types'
+import type {
+  AssistantId,
+  TerminalModeState,
+  TerminalSnapshot,
+  WorkspaceSnapshotV1,
+} from '../state/types'
+import type { ResizeOptions, SessionBackend, SessionBackendEvents } from './types'
 
 import { SessionManager } from '../daemon/session-manager'
 import { logDebug } from '../debug/input-log'
@@ -20,13 +25,31 @@ export class LocalSessionBackend
   private readonly sessionManager = new SessionManager()
   private currentSessionId: string | null = null
   private readonly statusLoop: ReturnType<typeof runStatusDetectionLoop>
+  /**
+   * Per-tab snapshot gate. While `false`, render events from the underlying
+   * `sessionManager` are buffered (latest-wins) instead of being forwarded to
+   * the UI. The frontend lifts the gate once `usePaneSizeReport` has reported
+   * the *actual* rendered pane size via `resizeTab({ confirmedFromMeasurement })`,
+   * so the first snapshot the UI ever paints is sized against the real box —
+   * never against the open-loop chrome estimate used at session create / attach.
+   * A tab without an entry here is treated as ready (legacy paths, sessions
+   * not subject to the gate). See plan: il-y-a-eu-stateful-boot.md.
+   */
+  private readonly paneReady = new Map<string, boolean>()
+  private readonly pendingRender = new Map<
+    string,
+    { viewport: TerminalSnapshot; terminalModes: TerminalModeState }
+  >()
 
   constructor() {
     super()
     this.sessionManager.on('render', (sessionId, tabId, viewport, terminalModes) => {
-      if (sessionId === this.currentSessionId) {
-        this.emit('render', tabId, viewport, terminalModes)
+      if (sessionId !== this.currentSessionId) return
+      if (this.paneReady.get(tabId) === false) {
+        this.pendingRender.set(tabId, { terminalModes, viewport })
+        return
       }
+      this.emit('render', tabId, viewport, terminalModes)
     })
     this.sessionManager.on('exit', (sessionId, tabId, exitCode) => {
       if (sessionId === this.currentSessionId) {
@@ -71,6 +94,7 @@ export class LocalSessionBackend
       const bounds = createTerminalBounds(options.cols, options.rows)
       forEachSplitPaneRect(splitTrees, bounds, (tabId, rect) => {
         const size = toTerminalContentSize(rect)
+        this.gatePaneRender(tabId)
         this.sessionManager.resizeTab(options.sessionId, tabId, size.cols, size.rows)
       })
     } else {
@@ -80,6 +104,9 @@ export class LocalSessionBackend
       options.sessionId,
       options.workspaceSnapshot
     )
+    for (const tab of attachResult.tabs) {
+      this.gatePaneRender(tab.id)
+    }
     // Run a synchronous classification pass so every tab's activity and the
     // session-status snapshot are available to embed in the reply — mirrors
     // the remote backend's behavior and keeps hydrate dispatches atomic on
@@ -115,9 +142,27 @@ export class LocalSessionBackend
       tabId: options.tabId,
       title: options.title,
     })
+    this.gatePaneRender(options.tabId)
     this.sessionManager.createTab(this.currentSessionId, options)
   }
 
+  /** Suppress render emission for this tab until the frontend acknowledges its
+   *  measured pane size via `resizeTab({ confirmedFromMeasurement: true })`. */
+  private gatePaneRender(tabId: string): void {
+    this.paneReady.set(tabId, false)
+    this.pendingRender.delete(tabId)
+  }
+
+  /** Lift the suppression and flush the most recent buffered snapshot, if any. */
+  private releasePaneRender(tabId: string): void {
+    if (this.paneReady.get(tabId) === true) return
+    this.paneReady.set(tabId, true)
+    const pending = this.pendingRender.get(tabId)
+    if (!pending) return
+    this.pendingRender.delete(tabId)
+    this.emit('render', tabId, pending.viewport, pending.terminalModes)
+  }
+
   write(tabId: string, input: string): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) {
       logDebug('backend.local.skipWriteWithoutSession', { inputLength: input.length, tabId })
@@ -147,25 +192,32 @@ export class LocalSessionBackend
     this.sessionManager.setActiveTab(this.currentSessionId, tabId)
   }
 
-  resizeAll(cols: number, rows: number, options?: { sync?: boolean }): void {
+  resizeAll(cols: number, rows: number, options?: ResizeOptions): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.resize(this.currentSessionId, cols, rows, options)
   }
 
-  resizeTab(tabId: string, cols: number, rows: number, options?: { sync?: boolean }): void {
+  resizeTab(tabId: string, cols: number, rows: number, options?: ResizeOptions): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.resizeTab(this.currentSessionId, tabId, cols, rows, options)
+    if (options?.confirmedFromMeasurement === true) {
+      this.releasePaneRender(tabId)
+    }
   }
 
   disposeSession(tabId: string): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.disposeSession', { sessionId: this.currentSessionId, tabId })
+    this.paneReady.delete(tabId)
+    this.pendingRender.delete(tabId)
     this.sessionManager.closeTab(this.currentSessionId, tabId)
   }
 
   disposeAll(): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.disposeAll', { sessionId: this.currentSessionId })
+    this.paneReady.clear()
+    this.pendingRender.clear()
     this.sessionManager.disposeSession(this.currentSessionId)
   }
 

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

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events'
 import { connect, type Socket } from 'node:net'
 
 import type { AssistantId, WorkspaceSnapshotV1 } from '../state/types'
-import type { SessionBackend, SessionBackendEvents } from './types'
+import type { ResizeOptions, SessionBackend, SessionBackendEvents } from './types'
 
 import { getIpcDaemonSocketPath } from '../daemon/runtime-paths'
 import { logDebug } from '../debug/input-log'
@@ -414,7 +414,7 @@ export class RemoteSessionBackend
     )
   }
 
-  resizeAll(cols: number, rows: number, _options?: { sync?: boolean }): void {
+  resizeAll(cols: number, rows: number, _options?: ResizeOptions): void {
     if (!this.attached) {
       logDebug('backend.remote.skipResizeBeforeAttach', { cols, rows })
       return
@@ -426,7 +426,14 @@ export class RemoteSessionBackend
     )
   }
 
-  resizeTab(tabId: string, cols: number, rows: number, _options?: { sync?: boolean }): void {
+  // The remote backend forwards every resize over IPC; the daemon-side
+  // pty-manager is the authoritative emulator. `confirmedFromMeasurement` is
+  // not yet plumbed through the wire protocol — the local backend uses it to
+  // gate the per-tab render emission, but in the remote path the daemon emits
+  // snapshots based on its own emulator state, so the flag is intentionally
+  // ignored here. If the boot-time visual desync ever shows up against a
+  // daemon, plumb the flag through the resizeTab IPC message.
+  resizeTab(tabId: string, cols: number, rows: number, _options?: ResizeOptions): void {
     if (!this.attached) {
       return
     }

package/src/session-backend/types.ts

@@ -17,6 +17,20 @@ export interface SessionBackendEvents {
   tabActivity: [tabId: string, activity: TabActivity]
 }
 
+export interface ResizeOptions {
+  /** When set, opentui's flush is invoked synchronously so the resize lands
+   *  in the same commit. Used by the chrome cascade to keep the cols/rows
+   *  state and the backend buffer in lockstep on sidebar/session-bar toggles. */
+  sync?: boolean
+  /** When true, this resize is the closed-loop measurement of the rendered
+   *  content box — the authoritative size for the visible viewport. The
+   *  `LocalSessionBackend` uses this to lift the per-tab snapshot gate that
+   *  suppresses renders between session/attach time and the first measurement,
+   *  so the frontend never paints a snapshot whose row count disagrees with
+   *  the pane's actual height. */
+  confirmedFromMeasurement?: boolean
+}
+
 export interface BackendAttachResult {
   tabs: TabSession[]
   activeTabId: string | null
@@ -49,8 +63,8 @@ export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
   scrollViewport(tabId: string, deltaLines: number): void
   scrollViewportToBottom(tabId: string): void
   setActiveTab(tabId: string | null): void
-  resizeAll(cols: number, rows: number, options?: { sync?: boolean }): void
-  resizeTab(tabId: string, cols: number, rows: number, options?: { sync?: boolean }): void
+  resizeAll(cols: number, rows: number, options?: ResizeOptions): void
+  resizeTab(tabId: string, cols: number, rows: number, options?: ResizeOptions): void
   disposeSession(tabId: string): void
   disposeAll(): void
   destroy(keepSessions?: boolean): Promise<void> | void