@linxin666/dsh-ssh 0.4.1 → 0.4.3

package/lib/types/client/api.d.ts

@@ -9,8 +9,8 @@ export declare class SshApiError extends Error {
 }
 /** 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). */
@@ -26,7 +26,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;
 }
 /** The browser half's only data entry point. */
@@ -74,6 +80,23 @@ export declare class SshApi {
         streamed: boolean;
         bytes: number;
     }>;
-    /** 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;
+    /**
+     * 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;
+    /** One terminal socket over either an alias (open) or a session id (attach). */
+    private terminalSocket;
 }

package/lib/types/client/native-panel.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { SshApi } from './api.ts';
+import { SSH_PANEL_ID, type PanelController } from './panel/controller.ts';
+import { type TerminalFontSource } from './panel/helpers.ts';
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { SSH_PANEL_ID };
+/**
+ * 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 declare function SshPanelIcon({ size }: {
+    size: number;
+    active: boolean;
+}): React.ReactElement;
+/**
+ * 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 declare function SshPanelPage({ controller, api, terminalFont }: {
+    controller: PanelController;
+    api: SshApi;
+    terminalFont?: TerminalFontSource;
+}): React.ReactElement;
+/**
+ * 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 declare function registerSshPanel(ctx: ClientContext, controller: PanelController, api: SshApi, terminalFont?: TerminalFontSource): () => void;

package/lib/types/client/panel/SshPanel.d.ts

@@ -1,11 +1,9 @@
 import type { SshApi } from '../api.ts';
 import type { PanelController } from './controller.ts';
 import { type TerminalFontSource } from './helpers.ts';
-/** 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;

package/lib/types/client/panel/TerminalTab.d.ts

@@ -1,8 +1,13 @@
 import type { SshApi } from '../api.ts';
+import type { PanelController } from './controller.ts';
 import { type TerminalFontSource } from './helpers.ts';
 /** 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). */
@@ -14,4 +19,4 @@ export interface TerminalTabProps {
     terminalFont?: TerminalFontSource;
 }
 /** The xterm terminal view. */
-export declare function TerminalTab({ api, presetAlias, requestId, terminalFont }: TerminalTabProps): import("react").JSX.Element;
+export declare function TerminalTab({ api, controller, sessionId, presetAlias, requestId, terminalFont }: TerminalTabProps): import("react").JSX.Element;

package/lib/types/client/panel/controller.d.ts

@@ -1,22 +1,89 @@
 /**
- * SSH panel controller: the single owner of the panel's open/closed state.
+ * SSH panel controller: the single owner of the panel's view state.
  *
  * Framework-free (structural runtime faces, task-board core/controller.ts
- * style) so the DOM mounts and the React panel share one tiny subscription
+ * style) so the sidebar row and the React panel share one tiny subscription
  * surface. The state lives only for the browser session (no persistence).
+ *
+ * The active tab, the hosts-tab connect request and the live terminal session
+ * id live here rather than inside the panel components: the layout mounts a
+ * keyed page only while its panel is selected, so component-local state would
+ * reset the tab on every panel switch and lose the id a reattach needs.
  */
+/** The panel's tab identifiers. */
+export type SshTab = 'hosts' | 'terminal' | 'transfer' | 'tunnels' | 'cluster';
+/** A "connect" action from the hosts tab, handed to the terminal tab. */
+export interface ConnectRequest {
+    alias: string;
+    /** Monotonic id so a repeated connect for the same alias still re-applies. */
+    nonce: number;
+}
+/** Stable id shared by the sidebar panel row and the main-slot page. */
+export declare const SSH_PANEL_ID = "ssh";
 /** Immutable controller snapshot for UI subscriptions. */
 export interface PanelControllerSnapshot {
+    /** Whether the center column shows this panel. */
     panelOpen: boolean;
+    /** The tab the panel is showing. */
+    activeTab: SshTab;
+    /** Pending hosts-tab connect request, or null. */
+    connectRequest: ConnectRequest | null;
+    /** Host-side terminal session the terminal tab should reattach to, if any. */
+    terminalSessionId: string | undefined;
+}
+/**
+ * The layout's panel-navigation face: selecting the panel is the layout's
+ * business, and this is the one call that asks for it (null returns the column
+ * to the conversation). Optional, so a shell-less composition keeps the pure
+ * state transitions testable.
+ */
+export interface PanelNavigationFace {
+    /** Select this panel, or null to hand the column back to the conversation. */
+    select(panelId: string | null): void;
+}
+/** Controller dependencies. */
+export interface PanelControllerDeps {
+    /** Layout panel selection; absent keeps the controller state-only. */
+    panel?: PanelNavigationFace;
 }
-/** The panel state owner the sidebar entry toggles and the view renders from. */
+/** The panel state owner the sidebar row and the view both read. */
 export declare class PanelController {
+    private readonly deps;
     private panelOpen;
+    private activeTab;
+    private connectRequest;
+    private terminalSessionId;
     private listeners;
+    /** Cached so getSnapshot is referentially stable between changes. */
+    private snapshot;
+    constructor(deps?: PanelControllerDeps);
     getSnapshot(): PanelControllerSnapshot;
     subscribe(fn: () => void): () => void;
+    /**
+     * Show the panel. The layout owns which panel the column renders, so the
+     * state flip and the selection travel together; the selection is requested
+     * after the snapshot flips, so a subscriber never observes "open" while the
+     * shell still shows the conversation.
+     */
     open(): void;
+    /** Return the column to the conversation, asking the layout explicitly. */
     close(): void;
     toggle(): void;
-    private notify;
+    /**
+     * Reflect a selection made outside this controller (the user clicked another
+     * sidebar row, or the layout dropped the panel id).
+     * @param panelId - the layout's current panel id, or null for the conversation.
+     */
+    syncPanelSelection(panelId: string | null): void;
+    /** Switch tabs, keeping every other piece of view state. */
+    setActiveTab(tab: SshTab): void;
+    /** Hand the terminal tab a host to connect to (hosts-tab "connect" action). */
+    requestConnect(alias: string): void;
+    /** Record the host-side session so a later page mount can reattach. */
+    setTerminalSession(sessionId: string): void;
+    /** Forget the session (it exited, or the user disconnected). */
+    clearTerminalSession(): void;
+    private commit;
+    /** Ask the layout to select a panel; a shell without the face is a no-op. */
+    private selectPanel;
 }

package/lib/types/engine/terminal-sessions.d.ts

@@ -0,0 +1,67 @@
+import { WebSocket } from 'ws';
+import type { KeyboardInteractiveHandler } from './connection-pool.ts';
+import type { ShellSession } from './pty.ts';
+/** What the registry needs from the engine (swappable in tests). */
+export interface TerminalSessionDeps {
+    /** Open one PTY shell for the alias (engine.openShell). */
+    openShell(alias: string, size: {
+        cols: number;
+        rows: number;
+    }, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<ShellSession>;
+    /** @returns the current time (defaults to Date.now). */
+    now?: () => number;
+    /** Bounded scrollback per session. */
+    maxBufferBytes?: number;
+    /** Idle window before a detached session is reaped. */
+    idleMs?: number;
+    /** Grace window an exited session is kept for reattaching views. */
+    exitGraceMs?: number;
+}
+/**
+ * The host's terminal session table: open one session per connect, attach any
+ * number of sockets, and keep the shell alive across detach.
+ */
+export declare class TerminalSessionRegistry {
+    private readonly sessions;
+    private readonly deps;
+    private readonly maxBufferBytes;
+    private readonly idleMs;
+    private readonly exitGraceMs;
+    constructor(deps: TerminalSessionDeps);
+    /** Open a new session for the alias and attach the requesting socket to it. */
+    open(ws: WebSocket, alias: string, size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    /**
+     * Attach a socket to an existing session, replaying its scrollback first.
+     * @returns false when the session is unknown (expired or already reaped).
+     */
+    attach(ws: WebSocket, sessionId: string, size: {
+        cols: number;
+        rows: number;
+    }): boolean;
+    /** End every session (host teardown, plugin dispose). */
+    dispose(): void;
+    /** Number of live sessions (introspection for tests and diagnostics). */
+    size(): number;
+    /** Wire one socket's frames and lifecycle onto a session. */
+    private bind;
+    /** Remove a socket from its session, keeping the shell alive. */
+    private detach;
+    /** End the session a socket is attached to (explicit close from the view). */
+    private end;
+    /** Mark a session exited and keep it briefly so a reattaching view sees it. */
+    private finish;
+    /** Append output to the replay buffer, trimmed to the byte cap. */
+    private pushOutput;
+    /** Broadcast one frame to every attached socket, honoring backpressure. */
+    private send;
+    private sendTo;
+    /** Pause while any attached socket is backed up; resume once all drained. */
+    private applyBackpressure;
+    /** Answer a keyboard-interactive challenge through whoever is attached. */
+    private keyboardInteractive;
+    private scheduleReap;
+    private clearReap;
+}

package/lib/types/mount-once.d.ts

@@ -4,19 +4,50 @@
  * the loader accepts a standalone install of the same package side by side;
  * without this guard the second instance would still re-register the same
  * webserver routes, tools, settings namespaces, and system-prompt sections
- * and fail the boot. mountOnce makes the second host apply a no-op for the
- * lifetime of the first instance (the browser half is already deduped by
- * package name in the client module host).
+ * and fail the boot. mountOnce makes a mount of an already-mounted package a
+ * no-op for as long as the first instance lives (the browser half is already
+ * deduped by package name in the client module host).
+ *
+ * A no-op is only safe while the holder is ALIVE. The holder can be disposed
+ * long after the refused mount ran its course: the Host reloads a profile by
+ * creating the new loader entries before the old ones are torn down (a
+ * plugin-manager enable/disable/install write, a settings-driven row reload,
+ * HMR), so the new aggregate shell entry mounts its family plugin while the
+ * previous entry still owns the name. Dropping that refused mount lost the
+ * plugin for good - the previous entry then disposed its own mount, releasing
+ * the name with nobody left to take it, and the family row stayed listed as
+ * active while its host routes 404ed (the task-board panel showed
+ * "board.hostError.notMounted", no degraded record appeared, and only a Host
+ * restart recovered it).
+ *
+ * The refused mount is therefore QUEUED, not dropped, and replayed the moment
+ * the holder releases the name - if the waiting fiber is still alive then. The
+ * single-instance guarantee is unchanged: exactly one mount is live per
+ * package name, and the replay re-enters the guard so a later mount still
+ * dedupes against it.
  *
  * The registry rides a global symbol so two module instances of the same
- * package (npm copy vs repository link) still share one verdict. cordis
- * `ctx.effect` runs its callback immediately and treats the callback's
+ * package (npm copy vs repository link) still share one verdict. That symbol
+ * is a CROSS-REPOSITORY contract, not this file's private state: the four
+ * satellite packages (dsh-skins / dsh-pet / dsh-presets /
+ * dsh-community-plugins) are separate repositories carrying their own copy of
+ * this guard, rebuilt on their own schedule, so the value under `MOUNTED`
+ * must keep the shape every published copy reads (a `Set` of package names
+ * with `has`/`add`/`delete`). The wait queues this guard added therefore live
+ * under their own additive key, and the registry reads back a `Set` even when
+ * some other build left a different value there. Changing `MOUNTED`'s shape
+ * in place broke that contract once: a satellite's legacy copy created a
+ * `Set`, the family's new copy read it as a `Map`, and every family row
+ * mounted after it failed with "claims.get is not a function".
+ *
+ * cordis `ctx.effect` runs its callback immediately and treats the callback's
  * return value as the fiber disposer, so the unmarker is returned, not run.
  */
 /**
  * Wrap a cordis plugin apply so the package runs at most once per process.
- * The first mount registers normally and unmarks when its fiber disposes;
- * any later mount of the same package name is a no-op.
+ * The first mount registers normally and releases the name when its fiber
+ * disposes; a mount refused while that name is held waits for the release and
+ * then runs, unless its own fiber disposes first.
  * @param packageName - npm package identity shared by every install source.
  * @param fn - the original plugin apply.
  * @returns an apply of the same shape.

package/lib/types/protocol.d.ts

@@ -172,9 +172,12 @@ export interface ApiErrorBody {
     error: string;
 }
 /** WebSocket terminal protocol frames (host -> client and client -> host). */
-export type TerminalServerFrame = {
+export type TerminalServerFrame = 
+/** The shell is up; `sessionId` reattaches to it after a view detach. */
+{
     type: 'ready';
     alias: string;
+    sessionId: string;
 } | {
     type: 'output';
     data: string;
@@ -201,6 +204,14 @@ export type TerminalClientFrame = {
 } | {
     type: 'auth_response';
     responses: string[];
+}
+/** Leave the socket while the host keeps the shell alive for a reattach. */
+ | {
+    type: 'detach';
+}
+/** End the session outright (the view's disconnect control). */
+ | {
+    type: 'close';
 };
 /** Route paths the client calls (shared literals). */
 export declare const SSH_API_BASE: "/api/dsh-ssh";

package/lib/types/routes.d.ts

@@ -8,6 +8,7 @@
  */
 import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { SshEngine } from './engine.ts';
+import { TerminalSessionRegistry } from './engine/terminal-sessions.ts';
 import type { HostStore } from './store.ts';
 /** Route family dependencies. */
 export interface SshRoutesDeps {
@@ -28,4 +29,5 @@ export interface SshRoutesDeps {
 export declare function makeRoutes(deps: SshRoutesDeps): {
     routes: WebRoute[];
     upgrade: WebUpgradeRoute;
+    terminalSessions: TerminalSessionRegistry;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-ssh",
   "description": "Remote SSH operations for the dsh web GUI: host config store (~/.dsh/dsh-ssh.json, import from ~/.ssh/config), a persistent ssh2 connection pool with jump-host support, exec / PTY web terminal / SFTP transfer / local port-forward tunnels / cluster execution, plus agent tools (ssh_list, ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "icon": "icon.svg",
   "type": "module",
   "engines": {
@@ -27,7 +27,7 @@
   },
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.7-rc.1"
+      "dsh": ">=0.1.7-rc.2"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -36,7 +36,8 @@
       "inject": [
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-renderer",
-        "@deepseek-ai/dsh-client-ui-settings"
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-layout"
       ],
       "platform": "web"
     }
@@ -49,24 +50,26 @@
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.1.7-rc.1",
+    "@deepseek-ai/dsh": ">=0.1.7-rc.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",

package/src/client/api.ts

@@ -78,8 +78,8 @@ function query(params: Record<string, string | number | undefined>): string {
 
 /** 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 +92,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 +350,56 @@ 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 {
+    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 scheme = window.location.protocol === 'https:' ? 'wss' : 'ws'
-    const url = scheme + '://' + window.location.host + SSH_API.terminal + query({ alias, cols, rows })
+    const url = scheme + '://' + window.location.host + SSH_API.terminal + search
     const socket = new WebSocket(url)
+    // 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 +410,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
   }
 }