@linxin666/dsh-ssh 0.4.2 → 0.4.4

package/src/client/api.ts

@@ -76,10 +76,83 @@ function query(params: Record<string, string | number | undefined>): string {
   return text === '' ? '' : '?' + text
 }
 
+/** The location facts a terminal socket URL is built from. */
+interface PageLocation {
+  /** Page scheme with its colon (for example `https:` or `dsh-app:`). */
+  protocol: string
+  /** Page authority, empty for a scheme that carries none. */
+  host: string
+}
+
+/**
+ * The WebSocket URL the terminal route is reached at, or undefined when this
+ * page cannot carry one.
+ *
+ * A page delivered by an application on this machine (the official DSH
+ * Desktop shell serves its Web GUI from `dsh-app://app/`) has no WebSocket
+ * transport: its scheme handler forwards HTTP requests to the local host but
+ * cannot upgrade a socket, so `ws://app/...` never connects and the terminal
+ * reports "connection error" (issue #1744). Every other page is a web page and
+ * resolves the socket against its own origin, exactly as before.
+ *
+ * A blank authority is treated the same as an application scheme: there is
+ * nothing to dial, and the caller gets the actionable reason instead of a
+ * socket that can only fail.
+ *
+ * @param location - the page location to read.
+ * @param search - the query string carrying `alias` or `session`.
+ * @returns the absolute `ws:`/`wss:` URL, or undefined when the page cannot carry one.
+ */
+export function terminalSocketUrl(location: PageLocation, search: string): string | undefined {
+  if (WEB_PAGE_PROTOCOLS.includes(location.protocol)) {
+    const scheme = location.protocol === 'https:' ? 'wss' : 'ws'
+    return scheme + '://' + location.host + SSH_API.terminal + search
+  }
+  return undefined
+}
+
+/**
+ * Schemes a network page can be delivered with. Every other scheme belongs to
+ * an application on this machine, which is the same classification the remote
+ * channel and the update seat use (`isWebPageProtocol` / `isApplicationDeliveredPage`).
+ */
+const WEB_PAGE_PROTOCOLS: readonly string[] = [
+  'http:',
+  'https:',
+  'blob:',
+  'data:',
+  'about:',
+  'filesystem:',
+]
+
+/**
+ * A terminal connection that never opened: it reports one failure once the
+ * view has attached its `onExit`, so the tab shows why instead of sitting on a
+ * spinner, and every later frame is a no-op.
+ */
+function failedTerminal(reason: string): TerminalConnection {
+  const connection: TerminalConnection = {
+    onReady: undefined,
+    onOutput: undefined,
+    onExit: undefined,
+    onAuthPrompt: undefined,
+    send: () => undefined,
+    resize: () => undefined,
+    sendAuthResponse: () => undefined,
+    detach: () => undefined,
+    close: () => undefined,
+  }
+  // The view binds onExit after the open() call returns, so the failure is
+  // delivered on the next microtask - never synchronously, which would race
+  // the handler the caller is about to assign.
+  queueMicrotask(() => { connection.onExit?.(null, reason) })
+  return connection
+}
+
 /** One open terminal connection (WebSocket JSON frames). */
 export interface TerminalConnection {
-  /** Fired on the ready frame (shell is up). */
-  onReady: (() => void) | undefined
+  /** Fired on the ready frame (shell is up); carries the host session id and alias. */
+  onReady: ((sessionId: string, alias: string) => void) | undefined
   /** Fired on every output frame. */
   onOutput: ((data: string) => void) | undefined
   /** Fired on the exit frame (or transport error). */
@@ -92,7 +165,13 @@ export interface TerminalConnection {
   resize(cols: number, rows: number): void
   /** Send interactive 2FA response codes to the remote server. */
   sendAuthResponse(responses: string[]): void
-  /** Close the socket and the remote session. */
+  /**
+   * Leave the socket while the host keeps the remote shell alive, so a later
+   * {@link SshApi.attachTerminal} picks the session up where it left off.
+   * This is what a view does on unmount; it is not a disconnect.
+   */
+  detach(): void
+  /** Close the socket and end the remote session. */
   close(): void
 }
 
@@ -344,32 +423,66 @@ export class SshApi {
   }
 
   // ------------------------------------------------------------ terminal
-  /** Open a WebSocket terminal session. */
+  /**
+   * Open a new host terminal session for the alias.
+   * @param alias - the configured host alias.
+   * @param cols - initial PTY width.
+   * @param rows - initial PTY height.
+   * @returns the live connection; its ready callback carries the session id
+   *   {@link attachTerminal} uses after a view detach.
+   */
   openTerminal(alias: string, cols: number, rows: number): TerminalConnection {
-    const scheme = window.location.protocol === 'https:' ? 'wss' : 'ws'
-    const url = scheme + '://' + window.location.host + SSH_API.terminal + query({ alias, cols, rows })
-    const socket = new WebSocket(url)
+    return this.terminalSocket(query({ alias, cols, rows }))
+  }
+
+  /**
+   * Reattach to a host-side session that outlived its view (a panel switch, a
+   * page navigation). The host replays its scrollback before the ready frame.
+   * @param sessionId - the id the previous connection reported on ready.
+   * @param cols - the view's current width.
+   * @param rows - the view's current height.
+   */
+  attachTerminal(sessionId: string, cols: number, rows: number): TerminalConnection {
+    return this.terminalSocket(query({ session: sessionId, cols, rows }))
+  }
+
+  /** One terminal socket over either an alias (open) or a session id (attach). */
+  private terminalSocket(search: string): TerminalConnection {
+    const target = terminalSocketUrl(window.location, search)
+    if (target === undefined) {
+      // This page has no WebSocket transport at all (the desktop shell's
+      // custom scheme forwards HTTP only). Say so plainly instead of opening
+      // a socket that can only report "connection error".
+      return failedTerminal(tt('terminal.noWebSocket'))
+    }
+    let socket: WebSocket
+    try {
+      socket = new WebSocket(target)
+    } catch (error) {
+      return failedTerminal(error instanceof Error ? error.message : String(error))
+    }
+    // A deliberate detach/close must not surface as a transport error: the
+    // view tears down silently, and only an UNEXPECTED close reports exit.
+    let leaving = false
+    const sendFrame = (frame: TerminalClientFrame): void => {
+      if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(frame))
+    }
     const connection: TerminalConnection = {
       onReady: undefined,
       onOutput: undefined,
       onExit: undefined,
       onAuthPrompt: undefined,
-      send: (data) => {
-        if (socket.readyState === WebSocket.OPEN) {
-          socket.send(JSON.stringify({ type: 'input', data } satisfies TerminalClientFrame))
-        }
-      },
-      resize: (cols, rows) => {
-        if (socket.readyState === WebSocket.OPEN) {
-          socket.send(JSON.stringify({ type: 'resize', cols, rows } satisfies TerminalClientFrame))
-        }
-      },
-      sendAuthResponse: (responses) => {
-        if (socket.readyState === WebSocket.OPEN) {
-          socket.send(JSON.stringify({ type: 'auth_response', responses } satisfies TerminalClientFrame))
-        }
+      send: (data) => { sendFrame({ type: 'input', data }) },
+      resize: (cols, rows) => { sendFrame({ type: 'resize', cols, rows }) },
+      sendAuthResponse: (responses) => { sendFrame({ type: 'auth_response', responses }) },
+      detach: () => {
+        leaving = true
+        sendFrame({ type: 'detach' })
+        try { socket.close() } catch { /* already closed */ }
       },
       close: () => {
+        leaving = true
+        sendFrame({ type: 'close' })
         try { socket.close() } catch { /* already closed */ }
       },
     }
@@ -380,13 +493,13 @@ export class SshApi {
       } catch {
         return
       }
-      if (frame.type === 'ready') connection.onReady?.()
+      if (frame.type === 'ready') connection.onReady?.(frame.sessionId, frame.alias)
       else if (frame.type === 'output') connection.onOutput?.(frame.data)
       else if (frame.type === 'exit') connection.onExit?.(frame.code, frame.error)
       else if (frame.type === 'auth_prompt') connection.onAuthPrompt?.(frame.name, frame.instructions, frame.prompts)
     }
-    socket.onclose = () => { connection.onExit?.(null, 'connection closed') }
-    socket.onerror = () => { connection.onExit?.(null, 'connection error') }
+    socket.onclose = () => { if (!leaving) connection.onExit?.(null, 'connection closed') }
+    socket.onerror = () => { if (!leaving) connection.onExit?.(null, 'connection error') }
     return connection
   }
 }

package/src/client/index.ts

@@ -21,12 +21,11 @@ import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
 import { SshApi } from './api.ts'
 import { en, zh, type SshKey } from './locales.ts'
-import { mountPanel } from './mount.tsx'
-import { PanelController } from './panel/controller.ts'
+import { registerSshPanel } from './native-panel.tsx'
+import { PanelController, SSH_PANEL_ID } from './panel/controller.ts'
 import type { TerminalFontSource } from './panel/helpers.ts'
 import { setRuntimeTranslate } from './panel/helpers.ts'
 import { bindSettingsReader } from './settings-binding.ts'
-import { mountSidebarEntry } from './sidebar-entry.ts'
 import { reportDailyHeartbeat } from './telemetry.ts'
 
 /** Locale namespace this plugin owns. */
@@ -55,7 +54,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Required services (fiber inject waiting — the runtime must be up first). */
-export const inject = ['slots', 'locale', 'configForms']
+export const inject = ['slots', 'locale', 'configForms', 'layout']
 
 /** Type-only surface (export discipline: no value exports beyond the plugin contract). */
 export type { PanelControllerSnapshot } from './panel/controller.ts'
@@ -90,7 +89,20 @@ export function apply(ctx: ClientContext): void {
   // follow the Language setting without a reload.
   try { setRuntimeTranslate(ctx.locale.bind(NS)) } catch { /* locale missing: document-language fallback stays */ }
 
-  const controller = new PanelController()
+  // Panel navigation belongs to the layout service: the panel asks it to
+  // select its own panel id (or the conversation) instead of taking over the
+  // center column at the DOM level. The lookup stays lazy so a selection
+  // issued before the service settles still lands once it does, and the face
+  // throws by contract before the layout root entry mounts, which the
+  // controller tolerates.
+  const controller = new PanelController({
+    panel: {
+      select: panelId => {
+        const layout = (ctx as unknown as { get?(name: string): unknown }).get?.('layout') as { selectPanel?: (id: string | null) => void } | undefined
+        layout?.selectPanel?.(panelId)
+      },
+    },
+  })
   const api = new SshApi()
   // Live terminal-font preference (issue #577): the field lives in this
   // plugin's own profile entry, whose settings page the Host generates from
@@ -107,11 +119,21 @@ export function apply(ctx: ClientContext): void {
   ctx.effect(() => () => { settings.dispose() }, 'dsh-ssh: settings binding')
   const disposers: Array<() => void> = []
   try {
-    disposers.push(mountSidebarEntry(controller, ctx.locale))
-    disposers.push(mountPanel(controller, api, terminalFont, ctx.locale))
+    disposers.push(registerSshPanel(ctx, controller, api, terminalFont))
+    // The layout's panel selection is reconciled back into the controller, so
+    // the panel follows the user clicking another panel row.
+    const layoutFace = (ctx as unknown as { get?(name: string): unknown }).get?.('layout') as { panelInfo?: { subscribe(listener: () => void): () => void; getSnapshot(): { activePanelId: unknown } } } | undefined
+    if (layoutFace?.panelInfo !== undefined) {
+      const sync = (): void => {
+        const active = layoutFace.panelInfo!.getSnapshot().activePanelId
+        controller.syncPanelSelection(active === SSH_PANEL_ID ? SSH_PANEL_ID : null)
+      }
+      sync()
+      disposers.push(layoutFace.panelInfo.subscribe(sync))
+    }
   } catch (error) {
-    // DOM failures degrade the panel, never the GUI.
-    console.warn('[dsh-ssh] mount failed:', error)
+    // Registration failures degrade the panel, never the GUI.
+    console.warn('[dsh-ssh] panel registration failed:', error)
   }
   ctx.effect(() => () => {
     for (const dispose of disposers.splice(0)) dispose()

package/src/client/locales.ts

@@ -93,6 +93,7 @@ export const zh = {
   'terminal.ready': '终端已连接（{alias}）',
   'terminal.exited': '终端已退出（{alias}）',
   'terminal.error': '终端错误：{error}',
+  'terminal.noWebSocket': '当前页面不支持 WebSocket（应用外壳只转发 HTTP），请改用浏览器打开的 Web 界面使用终端。',
   'terminal.auth.title': '二次身份验证 (2FA / 交互式认证)',
   'terminal.auth.submit': '提交验证码',
   'terminal.auth.cancel': '取消',
@@ -253,6 +254,7 @@ export const en: Record<keyof typeof zh, string> = {
   'terminal.ready': 'Terminal connected ({alias})',
   'terminal.exited': 'Terminal exited ({alias})',
   'terminal.error': 'Terminal error: {error}',
+  'terminal.noWebSocket': 'This page cannot carry a WebSocket (the application shell forwards HTTP only). Open the Web UI in a browser to use the terminal.',
   'terminal.auth.title': 'Two-Factor Authentication (2FA)',
   'terminal.auth.submit': 'Submit Code',
   'terminal.auth.cancel': 'Cancel',

package/src/client/native-panel.tsx

@@ -0,0 +1,141 @@
+/**
+ * Native panel registration for the SSH panel.
+ *
+ * The panel is an official-style center-column page, not a DOM takeover: it
+ * contributes a row into the sidebar shell's own global panel list
+ * (`sidebar.panellist`) and its page into the layout's keyed `main` slot. The
+ * shell then owns the row box, the label, the active highlight, the collapsed
+ * rail and the panel switch, exactly as it does for the shipped Plugins and
+ * Schedule pages and for the task board and the skill center.
+ *
+ * Both registrations go through `ctx.slots.inject`, which fires only once the
+ * owning shell entry has declared the seat: load order between this plugin and
+ * ui-layout / ui-sidebar therefore does not matter, and neither does a shell
+ * that cannot serve the seats (the callback simply never runs).
+ *
+ * The terminal's PTY shell lives on the host and outlives this page (see
+ * engine/terminal-sessions.ts), so the layout unmounting a deselected page
+ * costs the view its xterm instance, not the remote session: the terminal tab
+ * reattaches by session id when the page mounts again.
+ *
+ * @module @linxin666/dsh-client-ssh/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+import type { SshApi } from './api.ts'
+import { SSH_PANEL_ID, type PanelController } from './panel/controller.ts'
+import { tt, type TerminalFontSource } from './panel/helpers.ts'
+import { SshPanel } from './panel/SshPanel.tsx'
+import css from './panel/panel.module.css'
+
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { SSH_PANEL_ID }
+
+/** Row order among the shell's global panel rows (Plugins 0, Schedule 10, board 20, skill center 30). */
+const PANEL_ORDER = 40
+
+/**
+ * The sidebar row glyph the shell asks for at its own size and active state.
+ * The shell owns the button, label, tooltip and rail geometry; this component
+ * draws only the glyph, like every other panel row.
+ *
+ * The glyph carries `data-dsh-panel-entry` because it is the only DOM this
+ * panel's own code owns inside that shell-owned row: the L2 contract (skins)
+ * resolves which row belongs to which plugin through it, since the shell
+ * stamps no per-entry hook of its own (see contracts/semantic-attrs-v1.md).
+ * @param props - the shell's icon share: square edge and selection state.
+ * @returns the decorative terminal glyph.
+ */
+export function SshPanelIcon({ size }: { size: number; active: boolean }): React.ReactElement {
+  return (
+    <svg
+      data-dsh-panel-entry={SSH_PANEL_ID}
+      viewBox="0 0 16 16"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="1.75" y="2.25" width="12.5" height="11.5" rx="1.75" />
+      <path d="M4.25 5.25l2.75 2.75-2.75 2.75" />
+      <path d="M8.5 10.75h3.25" />
+    </svg>
+  )
+}
+
+/**
+ * The main-slot page. The layout mounts it only while this panel is selected;
+ * the wrapper carries the pinned `data-dsh-ssh-view` semantic anchor (L2
+ * contract, skins) the takeover container used to own.
+ * @param props - the framework main-slot share plus this entry's injected face.
+ * @returns the SSH panel page.
+ */
+export function SshPanelPage({ controller, api, terminalFont }: {
+  controller: PanelController
+  api: SshApi
+  terminalFont?: TerminalFontSource
+}): React.ReactElement {
+  return (
+    <div className={css.view} data-dsh-ssh-view="" data-dsh-plugin="ssh">
+      <SshPanel controller={controller} api={api} terminalFont={terminalFont} />
+    </div>
+  )
+}
+
+/** The injected face both registrations receive. */
+interface PanelFace {
+  controller: PanelController
+  api: SshApi
+  terminalFont?: TerminalFontSource
+}
+
+/**
+ * Register the SSH panel's sidebar row and center-column page.
+ *
+ * Both seats are declared by shell plugins this package does not depend on at
+ * runtime, so each registration is wrapped in `ctx.slots.inject`: the callback
+ * runs only after the owning entry declares the seat, and a shell that never
+ * declares it leaves the panel simply absent instead of failing boot.
+ * @param ctx - client root context (services: slots).
+ * @param controller - the controller the page and the row drive.
+ * @param api - the SSH API client the page operates through.
+ * @param terminalFont - live terminal-font setting source (issue #577).
+ * @returns disposer releasing both registrations.
+ */
+export function registerSshPanel(
+  ctx: ClientContext,
+  controller: PanelController,
+  api: SshApi,
+  terminalFont?: TerminalFontSource,
+): () => void {
+  const slots = ctx.slots as {
+    inject(key: string, callback: () => () => void): () => void
+    register(options: Record<string, unknown>, component: unknown): () => void
+  }
+  const disposers: Array<() => void> = []
+
+  disposers.push(slots.inject('sidebar.panellist', () => slots.register({
+    name: 'sidebar.panellist',
+    id: SSH_PANEL_ID,
+    order: PANEL_ORDER,
+    // The shell resolves this through resolveSlotLabel on every locale change,
+    // so the module-level translate reads the active language at call time.
+    label: () => tt('entry.label'),
+  }, SshPanelIcon)))
+
+  disposers.push(slots.inject('main', () => slots.register({
+    name: 'main',
+    key: SSH_PANEL_ID,
+    inject: (): PanelFace => ({ controller, api, terminalFont }),
+  }, SshPanelPage as never)))
+
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose()
+  }
+}

package/src/client/panel/SshPanel.tsx

@@ -1,13 +1,17 @@
 /**
  * The SSH operations panel shell: a header with a close control, a five-tab
- * bar, and the active tab's content. Tab state lives here (browser session
- * state); inactive tabs unmount, so each tab fetches its own data on
- * activation. The hosts tab's connect action switches here to the terminal
- * tab with the chosen alias preselected.
+ * bar, and the active tab's content.
+ *
+ * The active tab, the pending connect request and the live terminal session id
+ * live in the controller, not in component state: the layout mounts this page
+ * only while the panel is selected, so local state would reset the tab on
+ * every panel switch and lose the id the terminal tab needs to reattach its
+ * host-side session. Inactive tabs unmount, so each tab fetches its own data
+ * on activation.
  */
-import { useCallback, useState, useSyncExternalStore } from 'react'
+import { useCallback, useSyncExternalStore } from 'react'
 import type { SshApi } from '../api.ts'
-import type { PanelController } from './controller.ts'
+import type { PanelController, SshTab } from './controller.ts'
 import { tt, type TerminalFontSource } from './helpers.ts'
 import { ClusterTab } from './ClusterTab.tsx'
 import { HostsTab } from './HostsTab.tsx'
@@ -16,12 +20,9 @@ import { TransferTab } from './TransferTab.tsx'
 import { TunnelsTab } from './TunnelsTab.tsx'
 import css from './panel.module.css'
 
-/** The panel's tab identifiers. */
-export type SshTab = 'hosts' | 'terminal' | 'transfer' | 'tunnels' | 'cluster'
-
 /** Panel shell props. */
 export interface SshPanelProps {
-  /** The panel state owner (open/close/toggle). */
+  /** The panel state owner (open/close/toggle, active tab, terminal session). */
   controller: PanelController
   /** The SSH API client every tab operates through. */
   api: SshApi
@@ -38,25 +39,12 @@ const TABS: ReadonlyArray<{ id: SshTab; label: () => string }> = [
   { id: 'cluster', label: () => tt('tab.cluster') },
 ]
 
-/** A pending "connect this host" request handed to the terminal tab. */
-interface ConnectRequest {
-  alias: string
-  nonce: number
-}
-
 /** The tabbed SSH panel. */
 export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
-  const panelOpen = useSyncExternalStore(
+  const { panelOpen, activeTab, connectRequest, terminalSessionId } = useSyncExternalStore(
     useCallback(listener => controller.subscribe(listener), [controller]),
-    useCallback(() => controller.getSnapshot().panelOpen, [controller]),
+    useCallback(() => controller.getSnapshot(), [controller]),
   )
-  const [activeTab, setActiveTab] = useState<SshTab>('hosts')
-  const [connectRequest, setConnectRequest] = useState<ConnectRequest | null>(null)
-
-  const handleConnect = (alias: string): void => {
-    setActiveTab('terminal')
-    setConnectRequest(prev => ({ alias, nonce: (prev?.nonce ?? 0) + 1 }))
-  }
 
   return (
     <div className={css.panel} data-dsh-plugin="ssh">
@@ -76,14 +64,23 @@ export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
       </div>
       <div className={css.tabBar} role="tablist" data-dsh-part="tab-bar">
         {TABS.map(tab => (
-          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} data-dsh-part="tab" className={css.tab} onClick={() => { setActiveTab(tab.id) }}>
+          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} data-dsh-part="tab" className={css.tab} onClick={() => { controller.setActiveTab(tab.id) }}>
             {tab.label()}
           </button>
         ))}
       </div>
       <div className={css.panelContent}>
-        {activeTab === 'hosts' && <HostsTab api={api} onConnect={handleConnect} />}
-        {activeTab === 'terminal' && <TerminalTab api={api} presetAlias={connectRequest?.alias} requestId={connectRequest?.nonce} terminalFont={terminalFont} />}
+        {activeTab === 'hosts' && <HostsTab api={api} onConnect={alias => { controller.requestConnect(alias) }} />}
+        {activeTab === 'terminal' && (
+          <TerminalTab
+            api={api}
+            controller={controller}
+            presetAlias={connectRequest?.alias}
+            requestId={connectRequest?.nonce}
+            sessionId={terminalSessionId}
+            terminalFont={terminalFont}
+          />
+        )}
         {activeTab === 'transfer' && <TransferTab api={api} />}
         {activeTab === 'tunnels' && <TunnelsTab api={api} active={panelOpen} />}
         {activeTab === 'cluster' && <ClusterTab api={api} />}

package/src/client/panel/TerminalTab.tsx

@@ -10,6 +10,7 @@ import { Terminal, type IDisposable } from '@xterm/xterm'
 import { FitAddon } from '@xterm/addon-fit'
 import type { SshApi, TerminalConnection } from '../api.ts'
 import type { SshHostSummary } from '../../protocol.ts'
+import type { PanelController } from './controller.ts'
 import { XTERM_CSS } from './xterm.css.ts'
 import { errorMessage, resolveTerminalFontFamily, tt, type TerminalFontSource } from './helpers.ts'
 import css from './panel.module.css'
@@ -17,6 +18,10 @@ import css from './panel.module.css'
 /** Terminal tab props. */
 export interface TerminalTabProps {
   api: SshApi
+  /** The panel controller that owns the live host session id across mounts. */
+  controller: PanelController
+  /** Host session to reattach to on mount (survives a panel switch). */
+  sessionId?: string
   /** Alias preselected by a "connect" action from the hosts tab. */
   presetAlias?: string
   /** Monotonic id of the connect request (re-applies presetAlias). */
@@ -63,7 +68,7 @@ const NO_FONT_SOURCE: TerminalFontSource = {
 }
 
 /** The xterm terminal view. */
-export function TerminalTab({ api, presetAlias, requestId, terminalFont }: TerminalTabProps) {
+export function TerminalTab({ api, controller, sessionId, presetAlias, requestId, terminalFont }: TerminalTabProps) {
   const [hosts, setHosts] = useState<SshHostSummary[]>([])
   const [alias, setAlias] = useState(presetAlias ?? '')
   const [status, setStatus] = useState<TerminalStatus>({ kind: 'idle' })
@@ -111,7 +116,12 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     if (presetAlias !== undefined) setAlias(presetAlias)
   }, [presetAlias, requestId])
 
-  const teardown = (): void => {
+  /**
+   * Tear the view down.
+   * @param leave - `detach` leaves the host session alive for a reattach
+   *   (panel switch, unmount); `close` ends it (the disconnect control).
+   */
+  const teardown = (leave: 'detach' | 'close'): void => {
     setAuthPrompt(undefined)
     setAuthInputs([])
     const connection = connRef.current
@@ -121,7 +131,8 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
       connection.onOutput = undefined
       connection.onExit = undefined
       connection.onAuthPrompt = undefined
-      connection.close()
+      if (leave === 'detach') connection.detach()
+      else connection.close()
     }
     // Release the xterm input subscription explicitly and dispose the
     // terminal so no listener (or the terminal Renderer) survives a
@@ -133,8 +144,9 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     fitRef.current = null
   }
 
-  // Unmount cleanup (never touches state on an unmounting component).
-  useEffect(() => () => { teardown() }, [])
+  // Unmount cleanup (never touches state on an unmounting component). The
+  // host keeps the shell alive, so returning to this tab reattaches to it.
+  useEffect(() => () => { teardown('detach') }, [])
 
   // Keep the terminal fitted to its container. A window resize is only one
   // trigger: the status banner appearing after connect, panel resizes, and
@@ -170,12 +182,15 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     }
   }, [])
 
-  const connect = (): void => {
-    const target = alias
+  /**
+   * Build the xterm view and bind one connection to it.
+   * @param open - opens the transport once the terminal has a size.
+   */
+  const startSession = (open: (cols: number, rows: number) => TerminalConnection): void => {
     const container = containerRef.current
-    if (target === '' || container === null) return
+    if (container === null) return
     if (status.kind === 'connecting' || status.kind === 'connected') return
-    teardown()
+    teardown('detach')
     setStatus({ kind: 'connecting' })
     const term = new Terminal({
       convertEol: false,
@@ -188,20 +203,25 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     term.loadAddon(fit)
     term.open(container)
     fit.fit()
-    const connection = api.openTerminal(target, term.cols, term.rows)
+    const connection = open(term.cols, term.rows)
     termRef.current = term
     fitRef.current = fit
     connRef.current = connection
     let settled = false
+    let connectedAlias = ''
     dataSubRef.current = term.onData(data => { connection.send(data) })
     connection.onAuthPrompt = (name, instructions, prompts) => {
       setAuthPrompt({ name, instructions, prompts })
       setAuthInputs(prompts.map(() => ''))
     }
-    connection.onReady = () => {
+    connection.onReady = (id, readyAlias) => {
+      // Remember the host session so a later mount of this tab reattaches to
+      // the same shell instead of opening a second one.
+      connectedAlias = readyAlias
+      controller.setTerminalSession(id)
       setAuthPrompt(undefined)
       setAuthInputs([])
-      setStatus({ kind: 'connected', alias: target })
+      setStatus({ kind: 'connected', alias: readyAlias })
     }
     connection.onOutput = data => { term.write(data) }
     connection.onExit = (_code, error) => {
@@ -213,13 +233,33 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
       dataSubRef.current = null
       term.options.disableStdin = true
       connRef.current = null
+      // The session is gone: drop the id so the next mount starts fresh.
+      controller.clearTerminalSession()
       // Keep the last output visible; input is now disabled.
-      setStatus({ kind: 'exited', alias: target, detail: error })
+      setStatus({ kind: 'exited', alias: connectedAlias !== '' ? connectedAlias : alias, detail: error })
     }
   }
 
+  const connect = (): void => {
+    const target = alias
+    if (target === '') return
+    startSession((cols, rows) => api.openTerminal(target, cols, rows))
+  }
+
+  // Reattach to a host session that outlived this view (panel switch or a
+  // remount of the page). The host replays its scrollback before ready, so
+  // the terminal comes back with its history instead of a blank screen.
+  const reattachedRef = useRef<string | undefined>(undefined)
+  useEffect(() => {
+    if (sessionId === undefined || connRef.current !== null) return
+    if (reattachedRef.current === sessionId) return
+    reattachedRef.current = sessionId
+    startSession((cols, rows) => api.attachTerminal(sessionId, cols, rows))
+  }, [sessionId])
+
   const disconnect = (): void => {
-    teardown()
+    teardown('close')
+    controller.clearTerminalSession()
     setStatus({ kind: 'idle' })
   }