@brimveyn/aimux 1.16.3 → 1.18.2

package/src/session-backend/bootstrap.ts

@@ -2,6 +2,7 @@ import { connect } from 'node:net'
 
 import type { SessionBackend } from './types'
 
+import { negotiateDaemonReexec, waitForSocketRemoval } from '../daemon/reexec-client'
 import {
   getIpcDaemonSocketPath,
   getSocketSecurityIssue,
@@ -9,8 +10,10 @@ import {
   removeTerminalManagerSocketIfExists,
 } from '../daemon/runtime-paths'
 import { logDebug } from '../debug/input-log'
+import { MANAGER_PROTOCOL_MIN_VERSION } from '../ipc/manager-protocol'
 import {
   encodeMessage,
+  IPC_CAPABILITY_HOT_REEXEC,
   IPC_PROTOCOL_MIN_VERSION,
   IPC_PROTOCOL_VERSION,
   MessageDecoder,
@@ -20,6 +23,7 @@ import {
   findIpcDaemonPid,
   findTerminalManagerPid,
   killProcess,
+  spawnDaemonReexec,
   spawnDetachedIpcDaemon,
 } from '../platform/daemon-control'
 import { LocalSessionBackend } from './local-session-backend'
@@ -30,6 +34,20 @@ interface DaemonHandshakeProbeResult {
   error?: string
   processVersion?: string
   selectedVersion?: number
+  /**
+   * Capabilities the daemon advertised during the hello phase. Empty for
+   * legacy daemons that predate the capability field. Used to gate the
+   * hot-reexec attempt — we only send `prepareReexec` to a daemon that
+   * advertises `hotReexec`.
+   */
+  capabilities?: readonly string[]
+  /**
+   * Manager-protocol version the daemon negotiated with the running TM.
+   * Undefined when the daemon hasn't reached the TM yet or predates the
+   * field. Bootstrap uses this to skip hot-reexec when the successor's
+   * MANAGER_PROTOCOL_MIN_VERSION would be higher than the live TM speaks.
+   */
+  managerSelectedVersion?: number
 }
 
 async function spawnDaemon(): Promise<void> {
@@ -89,6 +107,8 @@ export async function probeDaemonProtocolCompatibility(
     const disposeRequestId = crypto.randomUUID()
     const probeSessionId = `probe-${crypto.randomUUID()}`
     let daemonProcessVersion: string | undefined
+    let daemonCapabilities: readonly string[] = []
+    let daemonManagerSelectedVersion: number | undefined
     let settled = false
     const timer = setTimeout(() => {
       finish({ compatible: false, error: 'handshake timed out' })
@@ -138,6 +158,8 @@ export async function probeDaemonProtocolCompatibility(
             }
 
             daemonProcessVersion = message.payload.processVersion
+            daemonCapabilities = message.payload.capabilities
+            daemonManagerSelectedVersion = message.payload.managerSelectedVersion
 
             socket.write(
               encodeMessage({
@@ -176,10 +198,12 @@ export async function probeDaemonProtocolCompatibility(
               })
             )
             finish({
+              capabilities: daemonCapabilities,
               compatible,
               error: compatible
                 ? undefined
                 : `attach returned protocol v${message.payload.protocolVersion}`,
+              managerSelectedVersion: daemonManagerSelectedVersion,
               processVersion: daemonProcessVersion,
               selectedVersion: message.payload.protocolVersion,
             })
@@ -210,6 +234,30 @@ async function restartDaemon(socketPath: string): Promise<void> {
   await spawnDaemon()
 }
 
+/**
+ * Ask the running daemon to drain and rename its socket out of the way, then
+ * spawn the new daemon binary in its place. The terminal-manager (and every
+ * PTY it owns) stays alive throughout. Returns `true` if the swap succeeded
+ * AND the successor handshakes compatibly. On any failure the caller should
+ * fall through to the legacy restart path.
+ *
+ * Behind `AIMUX_HOT_REEXEC=1`. Only viable when the running daemon advertises
+ * the `hotReexec` capability — older daemons predate the wire and would
+ * respond with an unknown-request error.
+ */
+async function hotReexecAndRespawn(socketPath: string): Promise<boolean> {
+  const negotiation = await negotiateDaemonReexec(socketPath, { reason: 'protocol-mismatch' })
+  logDebug('backend.reexec.finish', {
+    ok: negotiation.ok,
+    reason: negotiation.ok ? 'ack received' : negotiation.reason,
+  })
+  if (!negotiation.ok) return false
+  // Old daemon renamed the canonical path away; wait for the dirent to be
+  // unbound (it should already be — rename is atomic) before spawning.
+  await waitForSocketRemoval(socketPath, 1_000)
+  return spawnDaemonReexec()
+}
+
 // Kill the terminal-manager and clear its socket so the restarted daemon
 // spawns a fresh one via ensureTerminalManagerReady. Without this, the new
 // daemon reconnects to the still-running old terminal-manager and the
@@ -258,7 +306,69 @@ export async function createSessionBackend(opts?: {
       error: handshake.error ?? 'incompatible daemon handshake',
       socketPath,
     })
+    // Ring 3: prefer hot-reexec over the legacy stopTM+restart path when
+    // the running daemon advertises `hotReexec` and the operator has opted
+    // in via AIMUX_HOT_REEXEC=1. The terminal-manager and every PTY stay
+    // alive; the daemon binary swaps under them — no session-loss prompt.
+    const reexecEnabled = process.env.AIMUX_HOT_REEXEC === '1'
+    const daemonSupportsReexec =
+      handshake.capabilities?.includes(IPC_CAPABILITY_HOT_REEXEC) ?? false
+    // If the successor daemon's MANAGER_PROTOCOL_MIN_VERSION > what the
+    // running TM negotiated, the reexec is doomed: the successor will crash
+    // in ensureTerminalManagerReady() before binding the canonical socket.
+    // A legacy daemon that predates managerSelectedVersion returns undefined
+    // — treat that as "unknown, don't try" to avoid a 2-second wasted round-
+    // trip on a rolling upgrade that also bumps the manager protocol.
+    const managerCompatible =
+      handshake.managerSelectedVersion !== undefined &&
+      handshake.managerSelectedVersion >= MANAGER_PROTOCOL_MIN_VERSION
+    if (reexecEnabled && daemonSupportsReexec && managerCompatible) {
+      logDebug('backend.create.tryReexec', { socketPath })
+      const reexecOk = await hotReexecAndRespawn(socketPath)
+      if (reexecOk) {
+        const afterReexec = await probeDaemonProtocolCompatibility(socketPath)
+        logDebug('backend.create.handshakeAfterReexec', {
+          compatible: afterReexec.compatible,
+          error: afterReexec.error ?? null,
+          processVersion: afterReexec.processVersion ?? null,
+          selectedVersion: afterReexec.selectedVersion ?? null,
+          socketPath,
+        })
+        if (afterReexec.compatible) {
+          logDebug('backend.create.remote', { reexec: true, socketPath })
+          return new RemoteSessionBackend()
+        }
+        // Reexec succeeded but the successor still mismatches. This is the
+        // partial-update / PATH-skew case: the on-disk binary that spawned
+        // as the successor disagrees with what this process is running.
+        // Legacy stopTM+restart is exactly the recovery path — a fresh TM
+        // + a full daemon restart re-pin both protocols against the same
+        // binary. Fall through instead of throwing.
+        logDebug('backend.create.reexec.fallback', {
+          error: afterReexec.error ?? 'incompatible protocol',
+          reason: 'post-reexec handshake still mismatches',
+        })
+      } else {
+        logDebug('backend.create.reexec.fallback', { reason: 'reexec attempt failed' })
+      }
+    } else if (reexecEnabled && daemonSupportsReexec && !managerCompatible) {
+      logDebug('backend.create.reexec.skipped', {
+        managerSelectedVersion: handshake.managerSelectedVersion ?? null,
+        minRequired: MANAGER_PROTOCOL_MIN_VERSION,
+        reason: 'manager-protocol-mismatch',
+      })
+    }
+
+    // We're about to kill the terminal-manager and every PTY — warn the UI
+    // now so the user isn't surprised. The hot-reexec branch above never
+    // reaches this point, so the callback fires only when sessions really
+    // do die.
     await opts?.onBreakingUpdateRequired?.()
+
+    // AIMUX_ALLOW_KILL_PTYS: legacy breaking-update fallback. Daemon
+    // hot-reexec (docs/developer/hot-reexec.md) preserves PTYs on ordinary
+    // daemon-only upgrades; when the TM protocol itself changes, killing
+    // the TM is still the only way to clear the mismatch.
     await stopTerminalManager()
     await restartDaemon(socketPath)
     const retriedHandshake = await probeDaemonProtocolCompatibility(socketPath)

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

@@ -132,6 +132,7 @@ export class LocalSessionBackend
     cols: number
     rows: number
     cwd?: string
+    worktreeId?: string
   }): void {
     if (!(this.currentSessionId != null && this.currentSessionId !== '')) {
       logDebug('backend.local.skipCreateWithoutSession', { tabId: options.tabId })
@@ -141,6 +142,7 @@ export class LocalSessionBackend
       sessionId: this.currentSessionId,
       tabId: options.tabId,
       title: options.title,
+      worktreeId: options.worktreeId ?? null,
     })
     this.gatePaneRender(options.tabId)
     this.sessionManager.createTab(this.currentSessionId, options)
@@ -229,4 +231,8 @@ export class LocalSessionBackend
     this.statusLoop.stop()
     this.currentSessionId = null
   }
+
+  announceWorkspaceSwitched(_sessionId: string): void {
+    // No daemon on the local backend, so there's no CLI to notify.
+  }
 }

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

@@ -45,9 +45,20 @@ export class RemoteSessionBackend
     workspaceSnapshot?: WorkspaceSnapshotV1
   } | null = null
   private selectedProtocolVersion: number | null = null
+  private daemonCapabilities: ReadonlySet<string> = new Set()
   private reconnectPromise: Promise<void> | null = null
   private shouldReconnect = false
 
+  /**
+   * Capability strings advertised by the connected daemon on the last
+   * successful `hello`. Empty before the first handshake completes, and
+   * reset on connection loss. Callers should gate optional features on
+   * `daemonAdvertises('...')` rather than on the negotiated version number.
+   */
+  daemonAdvertises(capability: string): boolean {
+    return this.daemonCapabilities.has(capability)
+  }
+
   private rejectPendingRequests(error: Error): void {
     for (const [id, pending] of this.pending.entries()) {
       clearTimeout(pending.timer)
@@ -61,6 +72,7 @@ export class RemoteSessionBackend
     this.socket = null
     this.attached = false
     this.selectedProtocolVersion = null
+    this.daemonCapabilities = new Set()
     this.decoder.reset()
     this.rejectPendingRequests(new Error(reason))
 
@@ -187,6 +199,36 @@ export class RemoteSessionBackend
         })
         this.emit('sessionActivity', message.payload.sessionId, message.payload.status)
         break
+      case 'tabAdded':
+        logDebug('backend.remote.tabAdded', {
+          sessionId: message.payload.sessionId,
+          tabId: message.payload.tab.id,
+        })
+        this.emit('tabAdded', message.payload.sessionId, message.payload.tab)
+        break
+      case 'workspaceCreateRequested':
+        this.emit(
+          'workspaceCreateRequested',
+          message.payload.name,
+          message.payload.projectPath,
+          message.payload.switch === true
+        )
+        break
+      case 'workspaceSwitchRequested':
+        this.emit('workspaceSwitchRequested', message.payload.targetSessionId)
+        break
+      case 'workspaceCloseRequested':
+        this.emit('workspaceCloseRequested', message.payload.targetSessionId)
+        break
+      case 'workspaceSwitched':
+        this.emit('workspaceSwitched', message.payload.sessionId)
+        break
+      case 'worktreeAdded':
+        this.emit('worktreeAdded', message.payload.sessionId, message.payload.worktree)
+        break
+      case 'worktreeRemoved':
+        this.emit('worktreeRemoved', message.payload.sessionId, message.payload.worktreeId)
+        break
     }
   }
 
@@ -251,6 +293,12 @@ export class RemoteSessionBackend
     }
 
     this.selectedProtocolVersion = response.payload.selectedVersion
+    this.daemonCapabilities = new Set(response.payload.capabilities)
+    logDebug('backend.remote.hello.success', {
+      capabilities: response.payload.capabilities,
+      processVersion: response.payload.processVersion,
+      selectedVersion: response.payload.selectedVersion,
+    })
   }
 
   private async performAttach(options: {
@@ -357,6 +405,7 @@ export class RemoteSessionBackend
     cols: number
     rows: number
     cwd?: string
+    worktreeId?: string
   }): void {
     if (!this.attached) {
       logDebug('backend.remote.skipCreateBeforeAttach', { tabId: options.tabId })
@@ -462,6 +511,20 @@ export class RemoteSessionBackend
     this.dispatchCommand({ id: crypto.randomUUID(), payload: {}, type: 'disposeAll' }, 'disposeAll')
   }
 
+  announceWorkspaceSwitched(sessionId: string): void {
+    // Fire-and-forget so `handleSwitchSessionEffect` doesn't block waiting on
+    // the daemon roundtrip. The daemon relays this as a `workspaceSwitched`
+    // broadcast that unblocks any `aimux workspace switch --wait` CLI.
+    this.dispatchCommand(
+      {
+        id: crypto.randomUUID(),
+        payload: { sessionId },
+        type: 'announceWorkspaceSwitched',
+      },
+      'announceWorkspaceSwitched'
+    )
+  }
+
   async destroy(keepSessions = true): Promise<void> {
     logDebug('backend.remote.destroy', { keepSessions })
     this.shouldReconnect = false

package/src/session-backend/types.ts

@@ -7,6 +7,7 @@ import type {
   TerminalModeState,
   TerminalSnapshot,
   WorkspaceSnapshotV1,
+  WorktreeRecord,
 } from '../state/types'
 
 export interface SessionBackendEvents {
@@ -15,6 +16,29 @@ export interface SessionBackendEvents {
   error: [tabId: string, message: string]
   sessionActivity: [sessionId: string, status: SessionStatus]
   tabActivity: [tabId: string, activity: TabActivity]
+  /**
+   * Fired when a tab was added by a sibling client (e.g. the CLI control
+   * plane creating a tab in the same session). The UI subscribes and
+   * dispatches `add-tab` so its store learns about the new tab before any
+   * `tabRender` event lands.
+   */
+  tabAdded: [sessionId: string, tab: TabSession]
+  /**
+   * v12 workspace-lifecycle events. Fired when a CLI issued
+   * `createWorkspace` / `switchWorkspace` / `closeWorkspace` and the daemon
+   * relays as an event because a UI is attached. The UI reducer owns the
+   * catalog write; see `backend-runtime-events.ts` for the wiring.
+   */
+  workspaceCreateRequested: [name: string, projectPath: string | undefined, doSwitch: boolean]
+  workspaceSwitchRequested: [targetSessionId: string]
+  workspaceCloseRequested: [targetSessionId: string]
+  workspaceSwitched: [sessionId: string]
+  /**
+   * v12 worktree-lifecycle events. Fired when a CLI issued
+   * `addWorktreeRecord` / `removeWorktreeRecord` and the daemon relays.
+   */
+  worktreeAdded: [sessionId: string, worktree: WorktreeRecord]
+  worktreeRemoved: [sessionId: string, worktreeId: string]
 }
 
 export interface ResizeOptions {
@@ -58,6 +82,10 @@ export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
     cols: number
     rows: number
     cwd?: string
+    /** Worktree the tab belongs to. Passed through to the daemon so its
+     *  registry surfaces the right grouping in `listTabs` for headless
+     *  consumers (CLI control plane). */
+    worktreeId?: string
   }): void
   write(tabId: string, input: string): void
   scrollViewport(tabId: string, deltaLines: number): void
@@ -68,4 +96,10 @@ export interface SessionBackend extends EventEmitter<SessionBackendEvents> {
   disposeSession(tabId: string): void
   disposeAll(): void
   destroy(keepSessions?: boolean): Promise<void> | void
+  /**
+   * v12 — the UI calls this after `handleSwitchSessionEffect` finishes so the
+   * daemon can broadcast `workspaceSwitched` and any `aimux workspace switch
+   * --wait` CLI can exit. No-op on local backends (no daemon).
+   */
+  announceWorkspaceSwitched(sessionId: string): void
 }

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

@@ -6,6 +6,7 @@ import { collectHelpEntries } from '../../input/keymap/help-entries'
 import { getActiveKeymap } from '../../input/keymap/keymap-ref'
 import { getAllAssistantOptions } from '../../pty/command-registry'
 import { filterThemeIds } from '../../ui/filter-themes'
+import { buildFlashJumpLabels } from '../../ui/flash/build-labels'
 import {
   type BaseRefOption,
   buildBaseRefOptions,
@@ -361,6 +362,30 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
         },
       }
     }
+    case 'open-flash-jump-modal': {
+      const labels = buildFlashJumpLabels(state)
+      // Even when there are zero jump targets we still open the overlay (the
+      // user pressed `S` expecting it); the next keystroke that matches
+      // nothing closes it via the empty-match path in update-command-edit.
+      return {
+        ...state,
+        modal: {
+          buffer: '',
+          cursorPos: 0,
+          editBuffer: '',
+          labels,
+          pendingJump: null,
+          selectedIndex: 0,
+          sessionTargetId: null,
+          type: 'flash-jump',
+        },
+      }
+    }
+    case 'clear-flash-jump-pending': {
+      if (state.modal.type !== 'flash-jump') return state
+      if (state.modal.pendingJump === null) return state
+      return { ...state, modal: { ...state.modal, pendingJump: null } }
+    }
     case 'open-help-modal': {
       const keymap = getActiveKeymap()
       const scope = action.scope ?? null
@@ -662,7 +687,11 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
       const closingType = state.modal.type
       // Pure overlays never flipped focusMode (they render on top of git mode),
       // so leave it alone — closing returns to whatever was underneath.
-      if (closingType === 'help' || closingType === 'worktree-move') {
+      if (
+        closingType === 'help' ||
+        closingType === 'worktree-move' ||
+        closingType === 'flash-jump'
+      ) {
         return { ...state, modal: emptyModal() }
       }
       const nextFocus: AppState['focusMode'] = closingType === 'git-commit' ? 'git' : 'navigation'
@@ -859,6 +888,42 @@ export function reduceModalState(state: AppState, action: AppAction): AppState |
       return { ...state, modal: { ...state.modal, cursorPos: next } }
     }
     case 'update-command-edit': {
+      // Flash-jump: each letter narrows the matching label set. Closing the
+      // modal on no-match mirrors the flash.nvim "miss = cancel" UX, and a
+      // unique match exposes a pendingJump for app.tsx to execute.
+      if (state.modal.type === 'flash-jump') {
+        const buffer = state.modal.buffer
+        if (action.char === '\b') {
+          if (buffer.length === 0) return state
+          return {
+            ...state,
+            modal: { ...state.modal, buffer: buffer.slice(0, -1), pendingJump: null },
+          }
+        }
+        // Restrict to single lowercase ASCII letters — anything else (digits,
+        // shift+letter, control sequences) closes the overlay rather than
+        // poisoning the buffer.
+        const ch = action.char.toLowerCase()
+        if (ch.length !== 1 || ch < 'a' || ch > 'z') {
+          return { ...state, focusMode: 'navigation', modal: emptyModal() }
+        }
+        const nextBuffer = buffer + ch
+        const matches = state.modal.labels.filter((l) => l.label.startsWith(nextBuffer))
+        if (matches.length === 0) {
+          return { ...state, focusMode: 'navigation', modal: emptyModal() }
+        }
+        const onlyMatch = matches[0]
+        if (matches.length === 1 && onlyMatch && onlyMatch.label === nextBuffer) {
+          // Single full match: keep the modal open one tick with pendingJump
+          // set — app.tsx consumes it, performs the jump, then clears the
+          // modal. Storing it on the modal keeps a single source of truth.
+          return {
+            ...state,
+            modal: { ...state.modal, buffer: nextBuffer, pendingJump: onlyMatch.target },
+          }
+        }
+        return { ...state, modal: { ...state.modal, buffer: nextBuffer, pendingJump: null } }
+      }
       if (state.modal.editBuffer === null) {
         return state
       }

package/src/state/types.ts

@@ -50,6 +50,7 @@ export type ModalType =
   | 'worktree-move'
   | 'worktree-move-confirm'
   | 'worktree-delete-confirm'
+  | 'flash-jump'
   | null
 
 export interface TerminalSpan {
@@ -483,6 +484,42 @@ export interface DirectoryResult {
   type: DirectoryResultType
 }
 
+export type FlashJumpTargetKind = 'workspace' | 'worktree' | 'tab'
+
+export interface FlashJumpTarget {
+  kind: FlashJumpTargetKind
+  /**
+   * 1-based index of the workspace in the visible session ordering — fed to
+   * the existing `switch-session-by-index` side effect when jumping.
+   */
+  sessionIndex: number
+  sessionId: string
+  /** Set for kind 'worktree' (the non-primary target) and kind 'tab' (the tab's worktree). */
+  worktreeId?: string
+  /** Set for kind 'tab'. */
+  tabId?: string
+}
+
+export interface FlashLabel {
+  /** Stable identity of the labelled row (`ws:<id>`, `wt:<id>`, `tab:<id>`). */
+  key: string
+  /** 1- or 2-char lowercase ASCII label. */
+  label: string
+  target: FlashJumpTarget
+}
+
+export interface ModalFlashJump extends ModalBase {
+  type: 'flash-jump'
+  labels: FlashLabel[]
+  /** Letters typed so far, narrowing the matching label set. */
+  buffer: string
+  /**
+   * Set by the reducer once the buffer narrows to a single match — read by
+   * app.tsx in a useEffect to perform the actual jump and close the modal.
+   */
+  pendingJump: FlashJumpTarget | null
+}
+
 export type ModalState =
   | ModalClosed
   | ModalNewTab
@@ -502,6 +539,7 @@ export type ModalState =
   | ModalWorktreeMove
   | ModalWorktreeMoveConfirm
   | ModalWorktreeDeleteConfirm
+  | ModalFlashJump
 
 export interface LayoutState {
   terminalCols: number
@@ -642,6 +680,8 @@ export type ModalAction =
       closeTabs: boolean
       force: boolean
     }
+  | { type: 'open-flash-jump-modal' }
+  | { type: 'clear-flash-jump-pending' }
 
 // -- Session actions --
 export type SessionAction =

package/src/state/validation.ts

@@ -107,7 +107,7 @@ function isStringRecord(value: unknown): boolean {
   return Object.values(value).every(isString)
 }
 
-function isWorktreeRecord(value: unknown): value is WorktreeRecord {
+export function isWorktreeRecord(value: unknown): value is WorktreeRecord {
   return (
     isObjectRecord(value) &&
     isString(value.id) &&

package/src/terminal-manager/manager-client.ts

@@ -7,6 +7,7 @@ import { getTerminalManagerSocketPath } from '../daemon/runtime-paths'
 import { logDebug } from '../debug/input-log'
 import {
   encodeManagerMessage,
+  MANAGER_CAPABILITY_SET_BROADCAST_ENABLED,
   MANAGER_PROTOCOL_BROADCAST_GATE_VERSION,
   MANAGER_PROTOCOL_MIN_VERSION,
   MANAGER_PROTOCOL_VERSION,
@@ -43,6 +44,7 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
   >()
   private readonly decoder = new MessageDecoder<ManagerResponse | ManagerEvent>(parseManagerMessage)
   private selectedProtocolVersion: number | null = null
+  private serverCapabilities: ReadonlySet<string> = new Set()
 
   private rejectPendingRequests(error: Error): void {
     for (const [id, pending] of this.pending.entries()) {
@@ -57,6 +59,7 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
     const socket = this.socket
     this.socket = null
     this.selectedProtocolVersion = null
+    this.serverCapabilities = new Set()
     this.decoder.reset()
     this.rejectPendingRequests(new Error(reason))
 
@@ -175,7 +178,9 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
     }
 
     this.selectedProtocolVersion = response.payload.selectedVersion
+    this.serverCapabilities = new Set(response.payload.capabilities)
     logDebug('managerClient.handshake.success', {
+      capabilities: response.payload.capabilities,
       processVersion: response.payload.processVersion,
       selectedVersion: this.selectedProtocolVersion,
     })
@@ -359,17 +364,20 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
 
   /**
    * Tell the TM whether to bother snapshotting and broadcasting renders.
-   * No-ops on TMs that negotiated a protocol version without the feature
-   * (older builds): the worst case is the daemon keeps receiving renders it
-   * doesn't strictly need, which matches the pre-fix behaviour.
+   * Gated on the TM advertising `setBroadcastEnabled` in its hello
+   * capabilities; TMs built before the capabilities field existed still get
+   * the call when they speak protocol v≥4 (which is where the request
+   * shipped). Below that, keep the pre-existing broadcast-always behaviour.
    */
   async setBroadcastEnabled(enabled: boolean): Promise<void> {
-    if (
-      this.selectedProtocolVersion === null ||
-      this.selectedProtocolVersion < MANAGER_PROTOCOL_BROADCAST_GATE_VERSION
-    ) {
+    const advertised = this.serverCapabilities.has(MANAGER_CAPABILITY_SET_BROADCAST_ENABLED)
+    const versionImplies =
+      this.selectedProtocolVersion !== null &&
+      this.selectedProtocolVersion >= MANAGER_PROTOCOL_BROADCAST_GATE_VERSION
+    if (!advertised && !versionImplies) {
       logDebug('managerClient.setBroadcastEnabled.skipped', {
         enabled,
+        reason: 'capability-not-advertised',
         selectedVersion: this.selectedProtocolVersion,
       })
       return
@@ -381,6 +389,15 @@ export class TerminalManagerClient extends EventEmitter<ManagerClientEvents> {
     })
   }
 
+  /**
+   * The manager-protocol version negotiated with the running TM, or `null`
+   * if no handshake has completed. Used by the daemon's helloResult so
+   * bootstrap can decide whether a hot-reexec would land on a compatible TM.
+   */
+  getSelectedProtocolVersion(): number | null {
+    return this.selectedProtocolVersion
+  }
+
   destroy(): void {
     this.resetConnection('Terminal manager client destroyed')
   }

package/src/ui/components/flash/flash-label-badge.tsx

@@ -0,0 +1,38 @@
+import { memo } from 'react'
+
+import { useFlashLabel } from '../../hooks/use-flash-label'
+import { useTheme } from '../../theme'
+
+interface FlashLabelBadgeProps {
+  rowKey: string
+}
+
+/**
+ * Tiny inline badge that renders the flash-jump letter(s) for a row.
+ * Renders nothing when no flash-jump modal is open or the row has no label.
+ * The matched prefix is dimmed; the remaining letters show in accent.
+ */
+export const FlashLabelBadge = memo(function FlashLabelBadge({ rowKey }: FlashLabelBadgeProps) {
+  const t = useTheme()
+  const view = useFlashLabel(rowKey)
+  if (view === null) return null
+  if (!view.isActive) {
+    return (
+      <text fg={t.textMuted} selectable={false} wrapMode="none">
+        {view.label}{' '}
+      </text>
+    )
+  }
+  return (
+    <box flexDirection="row" flexShrink={0}>
+      {view.matchedLen > 0 ? (
+        <text fg={t.textMuted} selectable={false} wrapMode="none">
+          {view.label.slice(0, view.matchedLen)}
+        </text>
+      ) : null}
+      <text fg={t.accent} selectable={false} wrapMode="none">
+        {view.remaining}{' '}
+      </text>
+    </box>
+  )
+})

package/src/ui/components/layout/sidebar/tab-item.tsx

@@ -7,6 +7,7 @@ import type { TabSession } from '../../../../state/types'
 import { dispatchGlobal, runSideEffectGlobal } from '../../../../state/dispatch-ref'
 import { useBusySpinner } from '../../../hooks/use-busy-spinner'
 import { getCurrentTheme, useTheme } from '../../../theme'
+import { FlashLabelBadge } from '../../flash/flash-label-badge'
 import { ContextMenuBox } from '../../overlays/context-menu/context-menu-box'
 
 interface TabItemProps {
@@ -213,6 +214,7 @@ export function TabItem({
           {indexLabel}{' '}
         </text>
       ) : null}
+      <FlashLabelBadge rowKey={`tab:${tab.id}`} />
       <text fg={active ? t.text : t.textMuted} selectable={false} wrapMode="none">
         {tab.title}
       </text>