Merge pull request #272 from binaricat/feat/issue-261-terminal-encoding-switcher

feat: add terminal encoding switcher for SSH sessions (#261)

.github/workflows/build.yml

@@ -25,9 +25,6 @@ jobs:
           - name: windows
             os: windows-latest
             pack_script: pack:win
-          - name: linux-x64
-            os: ubuntu-latest
-            pack_script: pack:linux-x64
     env:
       VITE_SYNC_GITHUB_CLIENT_ID: ${{ secrets.VITE_SYNC_GITHUB_CLIENT_ID }}
       VITE_SYNC_GOOGLE_CLIENT_ID: ${{ secrets.VITE_SYNC_GOOGLE_CLIENT_ID }}
@@ -79,6 +76,59 @@ jobs:
             release/*.tar.gz
           if-no-files-found: ignore
 
+  # Dedicated job for Linux x64 — builds inside Debian Bullseye (GLIBC 2.31)
+  # to ensure native modules (node-pty, ssh2) compile correctly and to
+  # maintain GLIBC compatibility with older distros.
+  build-linux-x64:
+    name: build-linux-x64
+    runs-on: ubuntu-latest
+    container:
+      image: debian:bullseye
+    env:
+      VITE_SYNC_GITHUB_CLIENT_ID: ${{ secrets.VITE_SYNC_GITHUB_CLIENT_ID }}
+      VITE_SYNC_GOOGLE_CLIENT_ID: ${{ secrets.VITE_SYNC_GOOGLE_CLIENT_ID }}
+      VITE_SYNC_GOOGLE_CLIENT_SECRET: ${{ secrets.VITE_SYNC_GOOGLE_CLIENT_SECRET }}
+      VITE_SYNC_ONEDRIVE_CLIENT_ID: ${{ secrets.VITE_SYNC_ONEDRIVE_CLIENT_ID }}
+    steps:
+      - name: Install build dependencies
+        run: |
+          apt-get update
+          apt-get install -y curl build-essential python3 git libfuse2 file rpm
+          curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+          apt-get install -y nodejs
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install deps
+        run: npm ci
+
+      - name: Set version
+        shell: bash
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            VERSION="${GITHUB_REF_NAME#v}"
+          else
+            VERSION="${GITHUB_SHA:0:7}"
+          fi
+          echo "Setting version to ${VERSION}"
+          npm pkg set version="${VERSION}"
+
+      - name: Build package
+        env:
+          ELECTRON_BUILDER_PUBLISH: "never"
+        run: npm run pack:linux-x64
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: netcatty-linux-x64
+          path: |
+            release/*.AppImage
+            release/*.deb
+            release/*.rpm
+          if-no-files-found: ignore
+
   # Dedicated job for Linux ARM64 — builds inside Debian Bullseye (GLIBC 2.31)
   # to ensure compatibility with older distros like UOS/Deepin (GLIBC 2.28).
   # Key: GLIBC < 2.34 avoids the libpthread-merge symbol requirement.
@@ -136,7 +186,7 @@ jobs:
   release:
     name: release
     runs-on: ubuntu-latest
-    needs: [build, build-linux-arm64]
+    needs: [build, build-linux-x64, build-linux-arm64]
     if: startsWith(github.ref, 'refs/tags/') || (github.event_name == 'workflow_dispatch' && inputs.publish_release)
     permissions:
       contents: write

application/i18n/locales/en.ts

@@ -926,6 +926,9 @@ const en: Messages = {
   'terminal.composeBar.broadcasting': 'Broadcasting to all sessions',
   'terminal.toolbar.focus': 'Focus',
   'terminal.toolbar.focusMode': 'Focus Mode',
+  'terminal.toolbar.encoding': 'Terminal Encoding',
+  'terminal.toolbar.encoding.utf8': 'UTF-8',
+  'terminal.toolbar.encoding.gb18030': 'GB18030',
   'terminal.toolbar.closeSession': 'Close session',
   'terminal.toolbar.hostHighlight.title': 'Host Keyword Highlighting',
   'terminal.toolbar.hostHighlight.noRules': 'No custom highlight rules defined for this host',

application/i18n/locales/zh-CN.ts

@@ -608,6 +608,9 @@ const zhCN: Messages = {
   'terminal.composeBar.broadcasting': '正在广播到所有会话',
   'terminal.toolbar.focus': '聚焦',
   'terminal.toolbar.focusMode': '聚焦模式',
+  'terminal.toolbar.encoding': '终端编码',
+  'terminal.toolbar.encoding.utf8': 'UTF-8',
+  'terminal.toolbar.encoding.gb18030': 'GB18030',
   'terminal.toolbar.closeSession': '关闭会话',
   'terminal.toolbar.hostHighlight.title': '主机关键字高亮',
   'terminal.toolbar.hostHighlight.noRules': '此主机未定义自定义高亮规则',

application/state/sftp/errors.ts

@@ -4,31 +4,16 @@ export const isSessionError = (err: unknown): boolean => {
   return (
     msg.includes("session not found") ||
     msg.includes("sftp session") ||
-    msg.includes("not found") ||
-    msg.includes("closed") ||
-    msg.includes("connection reset")
-  );
-};
-
-/**
- * Check if an error message indicates a fatal error that should stop the entire upload.
- * This includes session errors AND target directory deletion errors.
- */
-export const isFatalUploadError = (errorMessage: string): boolean => {
-  const msg = errorMessage.toLowerCase();
-  return (
-    // Session-related errors
-    msg.includes("session not found") ||
-    msg.includes("sftp session") ||
-    msg.includes("connection") ||
-    msg.includes("disconnected") ||
-    // Target directory was deleted during upload
-    msg.includes("no such file") ||
-    msg.includes("enoent") ||
-    msg.includes("does not exist") ||
-    msg.includes("write stream error") ||
-    // Directory was removed
-    msg.includes("directory not found") ||
-    msg.includes("not a directory")
+    msg.includes("session lost") ||
+    msg.includes("channel not ready") ||
+    msg.includes("readdir is not a function") ||
+    msg.includes("channel closed") ||
+    msg.includes("connection closed") ||
+    msg.includes("connection reset") ||
+    msg.includes("write after end") ||
+    msg.includes("no response") ||
+    msg.includes("not connected") ||
+    msg.includes("client disconnected") ||
+    msg.includes("timed out")
   );
 };

application/state/useTerminalBackend.ts

@@ -78,6 +78,12 @@ export const useTerminalBackend = () => {
     bridge?.closeSession?.(sessionId);
   }, []);
 
+  const setSessionEncoding = useCallback(async (sessionId: string, encoding: string) => {
+    const bridge = netcattyBridge.get();
+    if (!bridge?.setSessionEncoding) return { ok: false, encoding };
+    return bridge.setSessionEncoding(sessionId, encoding);
+  }, []);
+
   const onSessionData = useCallback((sessionId: string, cb: (data: string) => void) => {
     const bridge = netcattyBridge.get();
     if (!bridge?.onSessionData) throw new Error("onSessionData unavailable");
@@ -148,6 +154,7 @@ export const useTerminalBackend = () => {
     writeToSession,
     resizeSession,
     closeSession,
+    setSessionEncoding,
     onSessionData,
     onSessionExit,
     onChainProgress,

components/Terminal.tsx

@@ -266,7 +266,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   snippetsRef.current = snippets;
 
   const terminalBackend = useTerminalBackend();
-  const { resizeSession } = terminalBackend;
+  const { resizeSession, setSessionEncoding } = terminalBackend;
 
 
 
@@ -297,6 +297,12 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   const dragCounterRef = useRef(0);
   const [pendingUploadEntries, setPendingUploadEntries] = useState<DropEntry[]>([]);
   const [isComposeBarOpen, setIsComposeBarOpen] = useState(false);
+  const [terminalEncoding, setTerminalEncoding] = useState<'utf-8' | 'gb18030'>(() => {
+    if (host?.charset && /^gb/i.test(String(host.charset).trim())) return 'gb18030';
+    return 'utf-8';
+  });
+  const terminalEncodingRef = useRef(terminalEncoding);
+  terminalEncodingRef.current = terminalEncoding;
 
   const terminalSearch = useTerminalSearch({ searchAddonRef, termRef });
   const {
@@ -428,6 +434,13 @@ const TerminalComponent: React.FC<TerminalProps> = ({
     setProgressValue,
     setChainProgress,
     t,
+    onSessionAttached: (id: string) => {
+      // Sync terminal encoding to SSH backend before first data arrives
+      const isSSH = host.protocol !== 'local' && host.protocol !== 'serial' && host.protocol !== 'telnet' && host.protocol !== 'mosh' && !host.moshEnabled && !host.id?.startsWith('local-') && !host.id?.startsWith('serial-') && host.hostname !== 'localhost';
+      if (isSSH) {
+        setSessionEncoding(id, terminalEncodingRef.current);
+      }
+    },
     onSessionExit,
     onTerminalDataCapture,
     onOsDetected,
@@ -909,6 +922,13 @@ const TerminalComponent: React.FC<TerminalProps> = ({
     termRef.current?.writeln("\r\n[No active SSH session]");
   };
 
+  const handleSetTerminalEncoding = (encoding: 'utf-8' | 'gb18030') => {
+    setTerminalEncoding(encoding);
+    if (sessionRef.current) {
+      setSessionEncoding(sessionRef.current, encoding);
+    }
+  };
+
   const handleOpenSFTP = async () => {
     // If SFTP is already open, toggle it off
     if (showSFTP) {
@@ -1113,6 +1133,8 @@ const TerminalComponent: React.FC<TerminalProps> = ({
       onToggleSearch={handleToggleSearch}
       isComposeBarOpen={inWorkspace ? isWorkspaceComposeBarOpen : isComposeBarOpen}
       onToggleComposeBar={inWorkspace ? onToggleComposeBar : () => setIsComposeBarOpen(prev => !prev)}
+      terminalEncoding={terminalEncoding}
+      onSetTerminalEncoding={handleSetTerminalEncoding}
     />
   );
 

components/sftp-modal/hooks/useSftpModalSession.ts

@@ -1,6 +1,7 @@
 import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { Host, RemoteFile } from "../../../types";
 import { logger } from "../../../lib/logger";
+import { isSessionError } from "../../../application/state/sftp/errors";
 import { toast } from "../../ui/toast";
 
 interface UseSftpModalSessionParams {
@@ -78,11 +79,12 @@ export const useSftpModalSession = ({
   getHomeDir,
   onClearSelection,
 }: UseSftpModalSessionParams): UseSftpModalSessionResult => {
-  const [currentPath, setCurrentPath] = useState("/");
+  const [currentPath, setCurrentPathState] = useState("/");
   const [files, setFiles] = useState<RemoteFile[]>([]);
   const [loading, setLoading] = useState(false);
   const [reconnecting, setReconnecting] = useState(false);
   const [sessionVersion, setSessionVersion] = useState(0);
+  const currentPathRef = useRef(currentPath);
   const sftpIdRef = useRef<string | null>(null);
   const closingPromiseRef = useRef<Promise<void> | null>(null);
   const initializedRef = useRef(false);
@@ -98,6 +100,10 @@ export const useSftpModalSession = ({
     Map<string, { files: RemoteFile[]; timestamp: number }>
   >(new Map());
   const loadSeqRef = useRef(0);
+  const setCurrentPath = useCallback((path: string) => {
+    currentPathRef.current = path;
+    setCurrentPathState(path);
+  }, []);
   const bumpSessionVersion = useCallback(() => {
     setSessionVersion((prev) => prev + 1);
   }, []);
@@ -187,20 +193,7 @@ export const useSftpModalSession = ({
     await currentClosePromise;
   }, [bumpSessionVersion, closeSftp, isLocalSession]);
 
-  const isSessionError = useCallback((err: unknown): boolean => {
-    if (!(err instanceof Error)) return false;
-    const msg = err.message.toLowerCase();
-    return (
-      msg.includes("session not found") ||
-      msg.includes("sftp session") ||
-      msg.includes("not found") ||
-      msg.includes("closed") ||
-      msg.includes("connection reset") ||
-      msg.includes("write after end") ||
-      msg.includes("no response") ||
-      msg.includes("client disconnected")
-    );
-  }, []);
+  // Use shared session-error classifier from errors.ts
 
   const handleSessionError = useCallback(async () => {
     if (reconnectingRef.current) return;
@@ -212,9 +205,30 @@ export const useSftpModalSession = ({
       try {
         reconnectAttemptsRef.current += 1;
         await closeSftpSession();
-        await ensureSftp();
+        const newSftpId = await ensureSftp();
         reconnectingRef.current = false;
         setReconnecting(false);
+
+        // Auto-reload current directory after successful reconnect
+        try {
+          const reloadPath = currentPathRef.current;
+          const reloadRequestId = loadSeqRef.current;
+          const list = await listSftp(newSftpId, reloadPath);
+          if (
+            reloadRequestId !== loadSeqRef.current ||
+            currentPathRef.current !== reloadPath
+          ) {
+            return;
+          }
+          onClearSelection();
+          setFiles(list);
+          dirCacheRef.current.set(`${host.id}::${reloadPath}`, {
+            files: list,
+            timestamp: Date.now(),
+          });
+        } catch {
+          // Reload failed — UI still shows old data, user can manually refresh
+        }
         return;
       } catch (err) {
         logger.warn(
@@ -230,7 +244,7 @@ export const useSftpModalSession = ({
         await new Promise((resolve) => setTimeout(resolve, 1000));
       }
     }
-  }, [closeSftpSession, ensureSftp, t]);
+  }, [closeSftpSession, ensureSftp, listSftp, host.id, onClearSelection, t]);
 
   const loadFiles = useCallback(
     async (path: string, options?: { force?: boolean }) => {
@@ -283,7 +297,7 @@ export const useSftpModalSession = ({
         }
       }
     },
-    [ensureSftp, host.id, isLocalSession, listLocalDir, listSftp, t, isSessionError, handleSessionError, files.length, onClearSelection],
+    [ensureSftp, host.id, isLocalSession, listLocalDir, listSftp, t, handleSessionError, files.length, onClearSelection],
   );
 
   useLayoutEffect(() => {
@@ -401,6 +415,7 @@ export const useSftpModalSession = ({
     loadFiles,
     onClearSelection,
     open,
+    setCurrentPath,
     t,
   ]);
 

components/sftp/SftpPaneToolbar.tsx

@@ -169,8 +169,7 @@ export const SftpPaneToolbar: React.FC<SftpPaneToolbarProps> = ({
       )}
 
       {/* Bookmark button with dropdown */}
-      {!pane.connection?.isLocal && (
-        <Popover>
+      <Popover>
           <PopoverTrigger asChild>
             <Button
               variant="ghost"
@@ -237,7 +236,6 @@ export const SftpPaneToolbar: React.FC<SftpPaneToolbarProps> = ({
             )}
           </PopoverContent>
         </Popover>
-      )}
 
       <div className="ml-auto flex items-center gap-0.5">
         {!pane.connection?.isLocal && (

components/sftp/SftpPaneView.tsx

@@ -25,6 +25,7 @@ import { useSftpPaneSorting } from "./hooks/useSftpPaneSorting";
 import { useSftpPaneVirtualList } from "./hooks/useSftpPaneVirtualList";
 import { useSftpDialogActionHandler } from "./hooks/useSftpDialogAction";
 import { useSftpBookmarks } from "./hooks/useSftpBookmarks";
+import { useLocalSftpBookmarks } from "./hooks/useLocalSftpBookmarks";
 
 interface SftpPaneWrapperProps {
   side: "left" | "right";
@@ -98,16 +99,20 @@ const SftpPaneViewInner: React.FC<SftpPaneViewProps> = ({
     (updated: Host) => updateHosts(hosts.map((h) => (h.id === updated.id ? updated : h))),
     [hosts, updateHosts],
   );
+  const remoteBookmarks = useSftpBookmarks({
+    host: currentHost,
+    currentPath: pane.connection?.currentPath,
+    onUpdateHost,
+  });
+  const localBookmarks = useLocalSftpBookmarks({
+    currentPath: pane.connection?.currentPath,
+  });
   const {
     bookmarks,
     isCurrentPathBookmarked,
     toggleBookmark,
     deleteBookmark,
-  } = useSftpBookmarks({
-    host: currentHost,
-    currentPath: pane.connection?.currentPath,
-    onUpdateHost,
-  });
+  } = pane.connection?.isLocal ? localBookmarks : remoteBookmarks;
 
   const { filteredFiles, sortedDisplayFiles } = useSftpPaneFiles({
     files: pane.files,

components/sftp/hooks/useLocalSftpBookmarks.ts

@@ -0,0 +1,73 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import type { SftpBookmark } from "../../../domain/models";
+import { localStorageAdapter } from "../../../infrastructure/persistence/localStorageAdapter";
+import { STORAGE_KEY_SFTP_LOCAL_BOOKMARKS } from "../../../infrastructure/config/storageKeys";
+
+// ── Shared external store so every hook instance sees the same bookmarks ──
+
+type Listener = () => void;
+const listeners = new Set<Listener>();
+
+let snapshot: SftpBookmark[] =
+    localStorageAdapter.read<SftpBookmark[]>(STORAGE_KEY_SFTP_LOCAL_BOOKMARKS) ?? [];
+
+function subscribe(listener: Listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
+
+function getSnapshot() {
+    return snapshot;
+}
+
+function setBookmarks(next: SftpBookmark[] | ((prev: SftpBookmark[]) => SftpBookmark[])) {
+    snapshot = typeof next === "function" ? next(snapshot) : next;
+    localStorageAdapter.write(STORAGE_KEY_SFTP_LOCAL_BOOKMARKS, snapshot);
+    for (const l of listeners) l();
+}
+
+// ── Hook ──
+
+interface UseLocalSftpBookmarksParams {
+    currentPath: string | undefined;
+}
+
+export const useLocalSftpBookmarks = ({
+    currentPath,
+}: UseLocalSftpBookmarksParams) => {
+    const bookmarks = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+    const isCurrentPathBookmarked = useMemo(
+        () => !!currentPath && bookmarks.some((b) => b.path === currentPath),
+        [currentPath, bookmarks],
+    );
+
+    const toggleBookmark = useCallback(() => {
+        if (!currentPath) return;
+        if (isCurrentPathBookmarked) {
+            setBookmarks((prev) => prev.filter((b) => b.path !== currentPath));
+        } else {
+            const isRoot = currentPath === "/" || /^[A-Za-z]:\\?$/.test(currentPath);
+            const label = isRoot
+                ? currentPath
+                : currentPath.split(/[\\/]/).filter(Boolean).pop() || currentPath;
+            const newBookmark: SftpBookmark = {
+                id: `bm-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+                path: currentPath,
+                label,
+            };
+            setBookmarks((prev) => [...prev, newBookmark]);
+        }
+    }, [currentPath, isCurrentPathBookmarked]);
+
+    const deleteBookmark = useCallback((id: string) => {
+        setBookmarks((prev) => prev.filter((b) => b.id !== id));
+    }, []);
+
+    return {
+        bookmarks,
+        isCurrentPathBookmarked,
+        toggleBookmark,
+        deleteBookmark,
+    };
+};

components/terminal/TerminalToolbar.tsx

@@ -2,12 +2,13 @@
  * Terminal Toolbar
  * Displays SFTP, Scripts, Theme, Highlight, Search buttons and close button in terminal status bar
  */
-import { FolderInput, X, Zap, Palette, Search, TextCursorInput } from 'lucide-react';
+import { Check, FolderInput, Languages, X, Zap, Palette, Search, TextCursorInput } from 'lucide-react';
 import React, { useState } from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { Snippet, Host } from '../../types';
 import { Button } from '../ui/button';
-import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover';
+import { Popover, PopoverClose, PopoverContent, PopoverTrigger } from '../ui/popover';
+import { cn } from '../../lib/utils';
 import { ScrollArea } from '../ui/scroll-area';
 import ThemeCustomizeModal from './ThemeCustomizeModal';
 import HostKeywordHighlightPopover from './HostKeywordHighlightPopover';
@@ -35,6 +36,9 @@ export interface TerminalToolbarProps {
     // Compose bar
     isComposeBarOpen?: boolean;
     onToggleComposeBar?: () => void;
+    // Terminal encoding
+    terminalEncoding?: 'utf-8' | 'gb18030';
+    onSetTerminalEncoding?: (encoding: 'utf-8' | 'gb18030') => void;
 }
 
 export const TerminalToolbar: React.FC<TerminalToolbarProps> = ({
@@ -58,6 +62,8 @@ export const TerminalToolbar: React.FC<TerminalToolbarProps> = ({
     onToggleSearch,
     isComposeBarOpen,
     onToggleComposeBar,
+    terminalEncoding,
+    onSetTerminalEncoding,
 }) => {
     const { t } = useI18n();
     const [themeModalOpen, setThemeModalOpen] = useState(false);
@@ -66,6 +72,7 @@ export const TerminalToolbar: React.FC<TerminalToolbarProps> = ({
 
     const isLocalTerminal = host?.protocol === 'local' || host?.id?.startsWith('local-');
     const isSerialTerminal = host?.protocol === 'serial' || host?.id?.startsWith('serial-');
+    const isSSHSession = !isLocalTerminal && !isSerialTerminal && host?.protocol !== 'telnet' && host?.protocol !== 'mosh' && !host?.moshEnabled && host?.hostname !== 'localhost';
     const hidesSftp = isLocalTerminal || isSerialTerminal;
 
     const currentThemeId = host?.theme || defaultThemeId;
@@ -118,6 +125,44 @@ export const TerminalToolbar: React.FC<TerminalToolbarProps> = ({
                 </Button>
             )}
 
+            {isSSHSession && onSetTerminalEncoding && (
+                <Popover>
+                    <PopoverTrigger asChild>
+                        <Button
+                            variant="secondary"
+                            size="icon"
+                            className={buttonBase}
+                            title={t("terminal.toolbar.encoding")}
+                            aria-label={t("terminal.toolbar.encoding")}
+                        >
+                            <Languages size={12} />
+                        </Button>
+                    </PopoverTrigger>
+                    <PopoverContent className="w-36 p-1" align="start">
+                        {(["utf-8", "gb18030"] as const).map((enc) => (
+                            <PopoverClose asChild key={enc}>
+                                <button
+                                    className={cn(
+                                        "w-full flex items-center gap-2 px-2 py-1.5 text-xs rounded-sm hover:bg-secondary transition-colors",
+                                        terminalEncoding === enc && "font-medium"
+                                    )}
+                                    onClick={() => onSetTerminalEncoding(enc)}
+                                >
+                                    <Check
+                                        size={12}
+                                        className={cn(
+                                            "shrink-0",
+                                            terminalEncoding === enc ? "opacity-100" : "opacity-0"
+                                        )}
+                                    />
+                                    {t(`terminal.toolbar.encoding.${enc === "utf-8" ? "utf8" : enc}`)}
+                                </button>
+                            </PopoverClose>
+                        ))}
+                    </PopoverContent>
+                </Popover>
+            )}
+
             <Popover open={isScriptsOpen} onOpenChange={setIsScriptsOpen}>
                 <PopoverTrigger asChild>
                     <Button

components/terminal/runtime/createTerminalSessionStarters.ts

@@ -91,6 +91,7 @@ export type TerminalSessionStartersContext = {
   setChainProgress: Dispatch<SetStateAction<ChainProgressState>>;
   t?: (key: string) => string;
 
+  onSessionAttached?: (sessionId: string) => void;
   onSessionExit?: (sessionId: string) => void;
   onTerminalDataCapture?: (sessionId: string, data: string) => void;
   onOsDetected?: (hostId: string, distro: string) => void;
@@ -128,6 +129,7 @@ const attachSessionToTerminal = (
   },
 ) => {
   ctx.sessionRef.current = id;
+  ctx.onSessionAttached?.(id);
 
   ctx.disposeDataRef.current = ctx.terminalBackend.onSessionData(id, (chunk) => {
     let data = chunk;
@@ -188,9 +190,9 @@ const runDistroDetection = async (
       timeout: 8000,
     });
     const data = `${res.stdout || ""}\n${res.stderr || ""}`;
-    const idMatch = data.match(/ID=([\\w\\-]+)/i);
+    const idMatch = data.match(/^ID="?([\w-]+)"?$/im);
     const distro = idMatch
-      ? idMatch[1].replace(/"/g, "")
+      ? idMatch[1]
       : (data.split(/\s+/)[0] || "").toLowerCase();
     if (distro) ctx.onOsDetected?.(ctx.host.id, distro);
   } catch (err) {

electron/bridges/sftpBridge.cjs

@@ -127,7 +127,102 @@ const encodePathForSession = (sftpId, inputPath, requestedEncoding) => {
   return encodePath(inputPath, encoding);
 };
 
-const getSftpChannel = (client) => client?.sftp || client?.client?.sftp;
+const hasSftpChannelApi = (value) =>
+  !!value &&
+  typeof value.readdir === "function" &&
+  typeof value.stat === "function" &&
+  typeof value.mkdir === "function" &&
+  typeof value.unlink === "function";
+
+const SFTP_CHANNEL_OPEN_TIMEOUT_MS = 10_000;
+
+const tryOpenSftpChannel = (client) =>
+  new Promise((resolve, reject) => {
+    const sshClient = client?.client;
+    if (!sshClient || typeof sshClient.sftp !== "function") {
+      resolve(null);
+      return;
+    }
+    let settled = false;
+    const timer = setTimeout(() => {
+      settled = true;
+      reject(new Error("SFTP channel open timed out"));
+    }, SFTP_CHANNEL_OPEN_TIMEOUT_MS);
+    try {
+      sshClient.sftp((err, sftp) => {
+        clearTimeout(timer);
+        if (settled) {
+          // Timeout already fired — close the orphaned channel to prevent leaks
+          try { sftp?.end?.(); } catch { }
+          return;
+        }
+        if (err) return reject(err);
+        resolve(sftp || null);
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      reject(err);
+    }
+  });
+
+const getSftpChannel = async (client) => {
+  if (!client) return null;
+
+  if (hasSftpChannelApi(client.sftp)) {
+    return client.sftp;
+  }
+
+  // sudo sessions must keep using the sudo-bootstrapped SFTP wrapper.
+  // Reopening with sshClient.sftp() would silently downgrade permissions.
+  if (client.__netcattySudoMode) {
+    console.warn("[SFTP] Sudo SFTP channel is unavailable; automatic recovery is disabled for sudo sessions. Please reconnect.");
+    return null;
+  }
+
+  // Do not treat ssh2's "client.sftp" method as a channel object.
+  // Re-open a fresh channel when the cached channel is stale.
+  if (!client.client || typeof client.client.sftp !== "function") {
+    return null;
+  }
+
+  // Deduplicate per-client: avoid concurrent channel re-open attempts
+  if (client._reopeningPromise) {
+    try {
+      return await client._reopeningPromise;
+    } catch {
+      return null;
+    }
+  }
+
+  client._reopeningPromise = (async () => {
+    try {
+      const reopened = await tryOpenSftpChannel(client);
+      if (hasSftpChannelApi(reopened)) {
+        client.sftp = reopened;
+        return reopened;
+      }
+    } catch (err) {
+      console.warn("[SFTP] Failed to recover SFTP channel", err?.message || String(err));
+    }
+    return null;
+  })();
+
+  try {
+    return await client._reopeningPromise;
+  } finally {
+    client._reopeningPromise = null;
+  }
+};
+
+const requireSftpChannel = async (client) => {
+  const sftp = await getSftpChannel(client);
+  if (!sftp) {
+    throw new Error("SFTP session lost. Please reconnect.");
+  }
+  return sftp;
+};
 
 const statAsync = (sftp, targetPath) =>
   new Promise((resolve, reject) => {
@@ -241,13 +336,13 @@ const ensureRemoteDirForSession = async (sftpId, dirPath, requestedEncoding) =>
 
   const encoding = resolveEncodingForRequest(sftpId, requestedEncoding);
   if (encoding === "utf-8") {
+    await requireSftpChannel(client);
     const encodedPath = encodePath(dirPath, encoding);
     await client.mkdir(encodedPath, true);
     return true;
   }
 
-  const sftp = getSftpChannel(client);
-  if (!sftp) throw new Error("SFTP channel not ready");
+  const sftp = await requireSftpChannel(client);
 
   const normalizedPath = await normalizeRemotePathString(client, dirPath);
   await ensureRemoteDirInternal(sftp, normalizedPath, encoding);
@@ -891,10 +986,7 @@ async function listSftp(event, payload) {
   const pathEncoding = resolveEncodingForRequest(payload.sftpId, requestedEncoding);
   const encodedPath = encodePath(basePath, pathEncoding);
 
-  const sftp = getSftpChannel(client);
-  if (!sftp) {
-    throw new Error("SFTP channel not ready");
-  }
+  const sftp = await requireSftpChannel(client);
 
   let list;
   try {
@@ -1015,6 +1107,7 @@ async function readSftp(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
   const buffer = await client.get(encodedPath);
@@ -1028,6 +1121,7 @@ async function readSftpBinary(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
   const buffer = await client.get(encodedPath);
@@ -1042,6 +1136,7 @@ async function writeSftp(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
   await client.put(Buffer.from(payload.content, "utf-8"), encodedPath);
@@ -1055,6 +1150,7 @@ async function writeSftpBinary(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
   await client.put(Buffer.from(payload.content), encodedPath);
@@ -1071,6 +1167,7 @@ async function writeSftpBinaryWithProgress(event, payload) {
   if (!client) throw new Error("SFTP session not found");
 
   const { sftpId, path: remotePath, content, transferId } = payload;
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(remotePath, encoding);
 
@@ -1305,6 +1402,7 @@ async function deleteSftp(event, payload) {
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
 
   if (encoding === "utf-8") {
+    await requireSftpChannel(client);
     const encodedPath = encodePath(payload.path, encoding);
     const stat = await client.stat(encodedPath);
     if (stat.isDirectory) {
@@ -1342,8 +1440,7 @@ async function deleteSftp(event, payload) {
     return true;
   }
 
-  const sftp = getSftpChannel(client);
-  if (!sftp) throw new Error("SFTP channel not ready");
+  const sftp = await requireSftpChannel(client);
   const normalizedPath = await normalizeRemotePathString(client, payload.path);
   await removeRemotePathInternal(sftp, normalizedPath, encoding);
   return true;
@@ -1356,6 +1453,7 @@ async function renameSftp(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedOldPath = encodePath(payload.oldPath, encoding);
   const encodedNewPath = encodePath(payload.newPath, encoding);
@@ -1370,6 +1468,7 @@ async function statSftp(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
   const stat = await client.stat(encodedPath);
@@ -1389,6 +1488,7 @@ async function chmodSftp(event, payload) {
   const client = sftpClients.get(payload.sftpId);
   if (!client) throw new Error("SFTP session not found");
 
+  await requireSftpChannel(client);
   const encoding = resolveEncodingForRequest(payload.sftpId, payload.encoding);
   const encodedPath = encodePath(payload.path, encoding);
   await client.chmod(encodedPath, parseInt(payload.mode, 8));
@@ -1426,6 +1526,7 @@ module.exports = {
   init,
   registerHandlers,
   getSftpClients,
+  requireSftpChannel,
   encodePathForSession,
   ensureRemoteDirForSession,
   openSftp,

electron/bridges/sshAuthHelper.cjs

@@ -1,38 +1,38 @@
- /**
-  * SSH Authentication Helper - Shared authentication logic for SSH connections
-  * Used by sshBridge, sftpBridge, and portForwardingBridge
-  */
- 
- const fs = require("node:fs");
- const path = require("node:path");
- const os = require("node:os");
- const keyboardInteractiveHandler = require("./keyboardInteractiveHandler.cjs");
+/**
+ * SSH Authentication Helper - Shared authentication logic for SSH connections
+ * Used by sshBridge, sftpBridge, and portForwardingBridge
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const keyboardInteractiveHandler = require("./keyboardInteractiveHandler.cjs");
 const passphraseHandler = require("./passphraseHandler.cjs");
- 
- // Default SSH key names in priority order
- const DEFAULT_KEY_NAMES = ["id_ed25519", "id_ecdsa", "id_rsa"];
- 
- /**
-  * Check if an SSH private key is encrypted (requires passphrase)
-  * @param {string} keyContent - The content of the private key file
-  * @returns {boolean} - True if the key is encrypted
-  */
- function isKeyEncrypted(keyContent) {
-   if (!keyContent || typeof keyContent !== "string") return false;
-  
+
+// Default SSH key names in priority order
+const DEFAULT_KEY_NAMES = ["id_ed25519", "id_ecdsa", "id_rsa"];
+
+/**
+ * Check if an SSH private key is encrypted (requires passphrase)
+ * @param {string} keyContent - The content of the private key file
+ * @returns {boolean} - True if the key is encrypted
+ */
+function isKeyEncrypted(keyContent) {
+  if (!keyContent || typeof keyContent !== "string") return false;
+
   // Check for PKCS#8 encrypted format (-----BEGIN ENCRYPTED PRIVATE KEY-----)
   if (keyContent.includes("-----BEGIN ENCRYPTED PRIVATE KEY-----")) {
     return true;
   }
-  
+
   // Check for legacy PEM format encryption (e.g., RSA PRIVATE KEY with encryption)
   if (keyContent.includes("Proc-Type:") && keyContent.includes("ENCRYPTED")) {
     return true;
   }
-  
+
   // Check for DEK-Info header (legacy PEM encryption indicator)
-   if (keyContent.includes("DEK-Info:")) return true;
-  
+  if (keyContent.includes("DEK-Info:")) return true;
+
   // Check for OpenSSH format keys
   if (keyContent.includes("-----BEGIN OPENSSH PRIVATE KEY-----")) {
     try {
@@ -43,7 +43,7 @@ const passphraseHandler = require("./passphraseHandler.cjs");
       if (base64Match) {
         const base64Content = base64Match[1].replace(/\s/g, "");
         const keyBuffer = Buffer.from(base64Content, "base64");
-        
+
         // OpenSSH key format: "openssh-key-v1\0" followed by cipher name
         // If ciphername is "none", the key is not encrypted
         const authMagic = "openssh-key-v1\0";
@@ -61,132 +61,132 @@ const passphraseHandler = require("./passphraseHandler.cjs");
       return true;
     }
   }
-  
-   return false;
- }
- 
- /**
-  * Find default SSH private key from user's ~/.ssh directory
-  * Skips encrypted keys that require a passphrase
-  * @returns {Promise<{ privateKey: string, keyPath: string, keyName: string } | null>}
-  */
- async function findDefaultPrivateKey() {
-   const sshDir = path.join(os.homedir(), ".ssh");
-   for (const name of DEFAULT_KEY_NAMES) {
-     const keyPath = path.join(sshDir, name);
-     try {
-       await fs.promises.access(keyPath, fs.constants.F_OK);
-       const privateKey = await fs.promises.readFile(keyPath, "utf8");
-       if (isKeyEncrypted(privateKey)) {
-         continue;
-       }
-       return { privateKey, keyPath, keyName: name };
-     } catch {
-       continue;
-     }
-   }
-   return null;
- }
- 
- /**
-  * Find ALL default SSH private keys from user's ~/.ssh directory
- * @param {Object} [options]
- * @param {boolean} [options.includeEncrypted=false] - If true, include encrypted keys with isEncrypted flag
- * @returns {Promise<Array<{ privateKey: string, keyPath: string, keyName: string, isEncrypted?: boolean }>>}
-  */
+
+  return false;
+}
+
+/**
+ * Find default SSH private key from user's ~/.ssh directory
+ * Skips encrypted keys that require a passphrase
+ * @returns {Promise<{ privateKey: string, keyPath: string, keyName: string } | null>}
+ */
+async function findDefaultPrivateKey() {
+  const sshDir = path.join(os.homedir(), ".ssh");
+  for (const name of DEFAULT_KEY_NAMES) {
+    const keyPath = path.join(sshDir, name);
+    try {
+      await fs.promises.access(keyPath, fs.constants.F_OK);
+      const privateKey = await fs.promises.readFile(keyPath, "utf8");
+      if (isKeyEncrypted(privateKey)) {
+        continue;
+      }
+      return { privateKey, keyPath, keyName: name };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find ALL default SSH private keys from user's ~/.ssh directory
+* @param {Object} [options]
+* @param {boolean} [options.includeEncrypted=false] - If true, include encrypted keys with isEncrypted flag
+* @returns {Promise<Array<{ privateKey: string, keyPath: string, keyName: string, isEncrypted?: boolean }>>}
+ */
 async function findAllDefaultPrivateKeys(options = {}) {
   const { includeEncrypted = false } = options;
-   const sshDir = path.join(os.homedir(), ".ssh");
+  const sshDir = path.join(os.homedir(), ".ssh");
 
-   const promises = DEFAULT_KEY_NAMES.map(async (name) => {
-     const keyPath = path.join(sshDir, name);
-     try {
-       await fs.promises.access(keyPath, fs.constants.F_OK);
-       const privateKey = await fs.promises.readFile(keyPath, "utf8");
-       const encrypted = isKeyEncrypted(privateKey);
-       if (encrypted && !includeEncrypted) {
-          return null;
-       }
-       return {
-         privateKey,
-         keyPath,
-         keyName: name,
-         ...(includeEncrypted ? { isEncrypted: encrypted } : {})
-       };
-     } catch {
-       return null;
-     }
-   });
+  const promises = DEFAULT_KEY_NAMES.map(async (name) => {
+    const keyPath = path.join(sshDir, name);
+    try {
+      await fs.promises.access(keyPath, fs.constants.F_OK);
+      const privateKey = await fs.promises.readFile(keyPath, "utf8");
+      const encrypted = isKeyEncrypted(privateKey);
+      if (encrypted && !includeEncrypted) {
+        return null;
+      }
+      return {
+        privateKey,
+        keyPath,
+        keyName: name,
+        ...(includeEncrypted ? { isEncrypted: encrypted } : {})
+      };
+    } catch {
+      return null;
+    }
+  });
 
-   const results = await Promise.all(promises);
-   return results.filter(Boolean);
- }
- 
- /**
-  * Get ssh-agent socket path based on platform
-  * @returns {string|null}
-  */
- function getSshAgentSocket() {
-   if (process.platform === "win32") {
-     return "\\\\.\\pipe\\openssh-ssh-agent";
-   }
-   return process.env.SSH_AUTH_SOCK || null;
- }
- 
- /**
-  * Build authentication handler with default key fallback support
-  * @param {Object} options
-  * @param {string} [options.privateKey] - Explicitly configured private key
-  * @param {string} [options.password] - Password for authentication
- * @param {string} [options.passphrase] - Passphrase for encrypted private key
-  * @param {Object} [options.agent] - SSH agent (NetcattyAgent or socket path)
-  * @param {string} options.username - SSH username
-  * @param {string} [options.logPrefix] - Log prefix for debugging
-  * @returns {{ authHandler: Function|Array, privateKey: string|null, agent: string|Object|null, usedDefaultKeys: boolean }}
- * @param {Array} [options.unlockedEncryptedKeys] - Array of unlocked encrypted keys with passphrases
-  */
- function buildAuthHandler(options) {
+  const results = await Promise.all(promises);
+  return results.filter(Boolean);
+}
+
+/**
+ * Get ssh-agent socket path based on platform
+ * @returns {string|null}
+ */
+function getSshAgentSocket() {
+  if (process.platform === "win32") {
+    return "\\\\.\\pipe\\openssh-ssh-agent";
+  }
+  return process.env.SSH_AUTH_SOCK || null;
+}
+
+/**
+ * Build authentication handler with default key fallback support
+ * @param {Object} options
+ * @param {string} [options.privateKey] - Explicitly configured private key
+ * @param {string} [options.password] - Password for authentication
+* @param {string} [options.passphrase] - Passphrase for encrypted private key
+ * @param {Object} [options.agent] - SSH agent (NetcattyAgent or socket path)
+ * @param {string} options.username - SSH username
+ * @param {string} [options.logPrefix] - Log prefix for debugging
+ * @returns {{ authHandler: Function|Array, privateKey: string|null, agent: string|Object|null, usedDefaultKeys: boolean }}
+* @param {Array} [options.unlockedEncryptedKeys] - Array of unlocked encrypted keys with passphrases
+ */
+function buildAuthHandler(options) {
   const { privateKey, password, passphrase, agent, username, logPrefix = "[SSH]", unlockedEncryptedKeys = [], defaultKeys = [] } = options;
-   
+
   // Determine what type of explicit auth the user configured
   const hasExplicitKey = !!privateKey;
   const hasExplicitPassword = !!password;
   const hasExplicitAgent = !!agent;
   const hasExplicitAuth = hasExplicitKey || hasExplicitPassword || hasExplicitAgent;
-  
+
   // Determine if this is a password-only or key-only connection
   const isPasswordOnly = hasExplicitPassword && !hasExplicitKey && !hasExplicitAgent;
   const isKeyOnly = hasExplicitKey && !hasExplicitAgent;
-  
-   const sshAgentSocket = getSshAgentSocket();
-   
+
+  const sshAgentSocket = getSshAgentSocket();
+
   // Only use system ssh-agent BEFORE user's auth when:
   // - User explicitly configured agent, OR
   // - No explicit auth is configured (pure fallback mode)
   // When user configured key/password, system agent should only be used AFTER as fallback
   const useAgentFirst = hasExplicitAgent || !hasExplicitAuth;
-  
+
   // Determine effective agent
   const effectiveAgent = agent || (useAgentFirst ? sshAgentSocket : null);
-  
+
   // Determine effective privateKey (user-provided takes priority)
   const effectivePrivateKey = privateKey || (!hasExplicitAuth && defaultKeys.length > 0 ? defaultKeys[0].privateKey : null);
-  
+
   // Determine fallback keys (keys to try after user's primary auth fails)
   // - If user provided a key: all default keys are fallbacks
   // - If no explicit auth: first default key is primary, rest are fallbacks  
   // - If password-only or agent-only: all default keys are fallbacks (tried after primary)
-  const fallbackKeys = hasExplicitKey 
-    ? defaultKeys 
-    : !hasExplicitAuth 
-      ? defaultKeys.slice(1) 
+  const fallbackKeys = hasExplicitKey
+    ? defaultKeys
+    : !hasExplicitAuth
+      ? defaultKeys.slice(1)
       : defaultKeys;
-  
+
   // Check if we need dynamic handler (have fallback options)
-  const hasFallbackOptions = fallbackKeys.length > 0 || 
-    (!hasExplicitAgent && sshAgentSocket) || 
+  const hasFallbackOptions = fallbackKeys.length > 0 ||
+    (!hasExplicitAgent && sshAgentSocket) ||
     (isPasswordOnly && defaultKeys.length > 0);
-  
+
   // If only simple auth methods and no fallback keys needed, use array-based handler
   if (hasExplicitAuth && !hasFallbackOptions) {
     const authMethods = [];
@@ -194,15 +194,15 @@ async function findAllDefaultPrivateKeys(options = {}) {
     if (privateKey) authMethods.push("publickey");
     if (password) authMethods.push("password");
     authMethods.push("keyboard-interactive");
-    
+
     return {
       authHandler: authMethods,
       privateKey: effectivePrivateKey,
       agent: effectiveAgent,
       usedDefaultKeys: false,
     };
-   }
-   
+  }
+
   // Build comprehensive authMethods array with all auth options
   // Order depends on what user explicitly configured:
   // - Password-only: password -> agent -> default keys -> keyboard-interactive
@@ -210,144 +210,132 @@ async function findAllDefaultPrivateKeys(options = {}) {
   // - Agent configured: agent -> user key -> password -> default keys -> keyboard-interactive
   // - No explicit auth: agent -> default keys -> keyboard-interactive
   const authMethods = [];
-  
+
   if (isPasswordOnly) {
-    // Password-only: password first, then fallbacks
+    // Password-only: respect user's explicit choice, no key/agent fallback
     authMethods.push({ type: "password", id: "password" });
-    
-    // Add agent and default keys AFTER password as fallback
-    if (sshAgentSocket) {
-      authMethods.push({ type: "agent", id: "agent" });
-    }
-    for (const keyInfo of defaultKeys) {
-      authMethods.push({ 
-        type: "publickey", 
-        key: keyInfo.privateKey, 
-        id: `publickey-default-${keyInfo.keyName}` 
-      });
-    }
   } else if (isKeyOnly) {
     // Key-only: user key first, then password (if any), then agent/default keys as fallback
-    
+
     // 1. User-provided key first
-    authMethods.push({ 
-      type: "publickey", 
-      key: privateKey, 
+    authMethods.push({
+      type: "publickey",
+      key: privateKey,
       passphrase: passphrase,
-      id: "publickey-user" 
+      id: "publickey-user"
     });
-    
+
     // 2. Password (if configured alongside key)
     if (password) {
       authMethods.push({ type: "password", id: "password" });
     }
-    
+
     // 3. System agent as fallback (AFTER user's key)
     if (sshAgentSocket) {
       authMethods.push({ type: "agent", id: "agent" });
     }
-    
+
     // 4. Default keys as fallback
     for (const keyInfo of fallbackKeys) {
-      authMethods.push({ 
-        type: "publickey", 
-        key: keyInfo.privateKey, 
-        id: `publickey-default-${keyInfo.keyName}` 
+      authMethods.push({
+        type: "publickey",
+        key: keyInfo.privateKey,
+        id: `publickey-default-${keyInfo.keyName}`
       });
     }
   } else {
     // Agent configured or no explicit auth: agent -> user key -> password -> default keys
-    
+
     // 1. Agent (user-provided or system)
     if (effectiveAgent) {
       authMethods.push({ type: "agent", id: "agent" });
     }
-    
+
     // 2. User-provided key
     if (privateKey) {
-      authMethods.push({ 
-        type: "publickey", 
-        key: privateKey, 
+      authMethods.push({
+        type: "publickey",
+        key: privateKey,
         passphrase: passphrase,
-        id: "publickey-user" 
+        id: "publickey-user"
       });
     }
-    
+
     // 3. Password (if configured)
     if (password) {
       authMethods.push({ type: "password", id: "password" });
     }
-    
+
     // 4. Default keys as fallback
     for (const keyInfo of fallbackKeys) {
-      authMethods.push({ 
-        type: "publickey", 
-        key: keyInfo.privateKey, 
-        id: `publickey-default-${keyInfo.keyName}` 
+      authMethods.push({
+        type: "publickey",
+        key: keyInfo.privateKey,
+        id: `publickey-default-${keyInfo.keyName}`
       });
     }
-    
+
     // 5. If no user key provided, add first default key at the beginning (after agent)
     if (!privateKey && defaultKeys.length > 0) {
       const insertIndex = effectiveAgent ? 1 : 0;
-      authMethods.splice(insertIndex, 0, { 
-        type: "publickey", 
-        key: defaultKeys[0].privateKey, 
-        id: `publickey-default-${defaultKeys[0].keyName}` 
+      authMethods.splice(insertIndex, 0, {
+        type: "publickey",
+        key: defaultKeys[0].privateKey,
+        id: `publickey-default-${defaultKeys[0].keyName}`
       });
     }
   }
-  
+
   // Add unlocked encrypted default keys (user provided passphrases for these)
   for (const keyInfo of unlockedEncryptedKeys) {
-    authMethods.push({ 
-      type: "publickey", 
-      key: keyInfo.privateKey, 
+    authMethods.push({
+      type: "publickey",
+      key: keyInfo.privateKey,
       passphrase: keyInfo.passphrase,
-      id: `publickey-encrypted-${keyInfo.keyName}` 
+      id: `publickey-encrypted-${keyInfo.keyName}`
     });
   }
-  
+
   // Keyboard-interactive as last resort
   authMethods.push({ type: "keyboard-interactive", id: "keyboard-interactive" });
-   
-  console.log(`${logPrefix} Auth methods configured`, { 
-      isPasswordOnly,
-      hasUserKey: !!privateKey,
-      hasPassword: !!password,
-      hasAgent: !!effectiveAgent,
-      methodCount: authMethods.length,
-      methods: authMethods.map(m => m.id),
-    });
-  
-   // Use dynamic authHandler to try all keys
-   let authIndex = 0;
-   const attemptedMethodIds = new Set();
-   
-   const authHandler = (methodsLeft, partialSuccess, callback) => {
-     const availableMethods = methodsLeft || ["publickey", "password", "keyboard-interactive", "agent"];
-     
-     while (authIndex < authMethods.length) {
-       const method = authMethods[authIndex];
-       authIndex++;
-       
-       if (attemptedMethodIds.has(method.id)) continue;
-       attemptedMethodIds.add(method.id);
-       
+
+  console.log(`${logPrefix} Auth methods configured`, {
+    isPasswordOnly,
+    hasUserKey: !!privateKey,
+    hasPassword: !!password,
+    hasAgent: !!effectiveAgent,
+    methodCount: authMethods.length,
+    methods: authMethods.map(m => m.id),
+  });
+
+  // Use dynamic authHandler to try all keys
+  let authIndex = 0;
+  const attemptedMethodIds = new Set();
+
+  const authHandler = (methodsLeft, partialSuccess, callback) => {
+    const availableMethods = methodsLeft || ["publickey", "password", "keyboard-interactive", "agent"];
+
+    while (authIndex < authMethods.length) {
+      const method = authMethods[authIndex];
+      authIndex++;
+
+      if (attemptedMethodIds.has(method.id)) continue;
+      attemptedMethodIds.add(method.id);
+
       if (method.type === "agent" && (availableMethods.includes("publickey") || availableMethods.includes("agent"))) {
         console.log(`${logPrefix} Trying agent auth`);
         return callback("agent");
       } else if (method.type === "publickey" && availableMethods.includes("publickey")) {
-         console.log(`${logPrefix} Trying publickey auth:`, method.id);
-         const pubkeyAuth = {
-           type: "publickey",
-           username,
-           key: method.key,
-         };
-         if (method.passphrase) {
-           pubkeyAuth.passphrase = method.passphrase;
-         }
-         return callback(pubkeyAuth);
+        console.log(`${logPrefix} Trying publickey auth:`, method.id);
+        const pubkeyAuth = {
+          type: "publickey",
+          username,
+          key: method.key,
+        };
+        if (method.passphrase) {
+          pubkeyAuth.passphrase = method.passphrase;
+        }
+        return callback(pubkeyAuth);
       } else if (method.type === "password" && availableMethods.includes("password")) {
         console.log(`${logPrefix} Trying password auth`);
         return callback({
@@ -355,107 +343,107 @@ async function findAllDefaultPrivateKeys(options = {}) {
           username,
           password,
         });
-       } else if (method.type === "keyboard-interactive" && availableMethods.includes("keyboard-interactive")) {
-         return callback("keyboard-interactive");
-       }
-     }
-     return callback(false);
-   };
-   
+      } else if (method.type === "keyboard-interactive" && availableMethods.includes("keyboard-interactive")) {
+        return callback("keyboard-interactive");
+      }
+    }
+    return callback(false);
+  };
+
   // Determine the agent to return - if authMethods includes agent, we need to provide the socket
   // even if effectiveAgent is null (for fallback scenarios)
   const hasAgentInMethods = authMethods.some(m => m.type === "agent");
   const returnAgent = effectiveAgent || (hasAgentInMethods ? sshAgentSocket : null);
-  
-   return {
-     authHandler,
+
+  return {
+    authHandler,
     privateKey: effectivePrivateKey,
     agent: returnAgent,
-     usedDefaultKeys: true,
-   };
- }
- 
- /**
-  * Create a keyboard-interactive event handler
-  * @param {Object} options
-  * @param {Object} options.sender - Electron webContents sender
-  * @param {string} options.sessionId - Session/connection ID
-  * @param {string} options.hostname - Host being connected to
-  * @param {string} [options.password] - Saved password for fill button
-  * @param {string} [options.logPrefix] - Log prefix for debugging
-  * @returns {Function} - Event handler for 'keyboard-interactive' event
-  */
- function createKeyboardInteractiveHandler(options) {
-   const { sender, sessionId, hostname, password, logPrefix = "[SSH]" } = options;
-   
-   return (name, instructions, instructionsLang, prompts, finish) => {
-     console.log(`${logPrefix} ${hostname} keyboard-interactive auth requested`, {
-       name,
-       instructions,
-       promptCount: prompts?.length || 0,
-     });
-     
-     // If there are no prompts, just call finish with empty array
-     if (!prompts || prompts.length === 0) {
-       console.log(`${logPrefix} No prompts, finishing keyboard-interactive`);
-       finish([]);
-       return;
-     }
-     
-     // Forward prompts to user via IPC
-     const requestId = keyboardInteractiveHandler.generateRequestId('ssh');
-     keyboardInteractiveHandler.storeRequest(requestId, (userResponses) => {
-       console.log(`${logPrefix} Received user responses, finishing keyboard-interactive`);
-       finish(userResponses);
-     }, sender.id, sessionId);
-     
-     const promptsData = prompts.map((p) => ({
-       prompt: p.prompt,
-       echo: p.echo,
-     }));
-     
-     console.log(`${logPrefix} Showing modal for ${promptsData.length} prompts`);
-     
-     safeSend(sender, "netcatty:keyboard-interactive", {
-       requestId,
-       sessionId,
-       name: name || hostname,
-       instructions: instructions || "",
-       prompts: promptsData,
+    usedDefaultKeys: true,
+  };
+}
+
+/**
+ * Create a keyboard-interactive event handler
+ * @param {Object} options
+ * @param {Object} options.sender - Electron webContents sender
+ * @param {string} options.sessionId - Session/connection ID
+ * @param {string} options.hostname - Host being connected to
+ * @param {string} [options.password] - Saved password for fill button
+ * @param {string} [options.logPrefix] - Log prefix for debugging
+ * @returns {Function} - Event handler for 'keyboard-interactive' event
+ */
+function createKeyboardInteractiveHandler(options) {
+  const { sender, sessionId, hostname, password, logPrefix = "[SSH]" } = options;
+
+  return (name, instructions, instructionsLang, prompts, finish) => {
+    console.log(`${logPrefix} ${hostname} keyboard-interactive auth requested`, {
+      name,
+      instructions,
+      promptCount: prompts?.length || 0,
+    });
+
+    // If there are no prompts, just call finish with empty array
+    if (!prompts || prompts.length === 0) {
+      console.log(`${logPrefix} No prompts, finishing keyboard-interactive`);
+      finish([]);
+      return;
+    }
+
+    // Forward prompts to user via IPC
+    const requestId = keyboardInteractiveHandler.generateRequestId('ssh');
+    keyboardInteractiveHandler.storeRequest(requestId, (userResponses) => {
+      console.log(`${logPrefix} Received user responses, finishing keyboard-interactive`);
+      finish(userResponses);
+    }, sender.id, sessionId);
+
+    const promptsData = prompts.map((p) => ({
+      prompt: p.prompt,
+      echo: p.echo,
+    }));
+
+    console.log(`${logPrefix} Showing modal for ${promptsData.length} prompts`);
+
+    safeSend(sender, "netcatty:keyboard-interactive", {
+      requestId,
+      sessionId,
+      name: name || hostname,
+      instructions: instructions || "",
+      prompts: promptsData,
       hostname: hostname,
-       savedPassword: password || null,
-     });
-   };
- }
- 
- /**
-  * Send message to renderer safely
-  */
- function safeSend(sender, channel, payload) {
-   try {
-     if (!sender || sender.isDestroyed()) return;
-     sender.send(channel, payload);
-   } catch {
-     // Ignore destroyed webContents during shutdown.
-   }
- }
- 
- /**
-  * Apply auth configuration to connection options
-  * Convenience function that combines buildAuthHandler results with connOpts
-  * @param {Object} connOpts - SSH connection options to modify
-  * @param {Object} authConfig - Auth configuration from buildAuthHandler
-  */
- function applyAuthToConnOpts(connOpts, authConfig) {
-   connOpts.authHandler = authConfig.authHandler;
-   if (authConfig.privateKey) {
-     connOpts.privateKey = authConfig.privateKey;
-   }
-   if (authConfig.agent) {
-     connOpts.agent = authConfig.agent;
-   }
- }
- 
+      savedPassword: password || null,
+    });
+  };
+}
+
+/**
+ * Send message to renderer safely
+ */
+function safeSend(sender, channel, payload) {
+  try {
+    if (!sender || sender.isDestroyed()) return;
+    sender.send(channel, payload);
+  } catch {
+    // Ignore destroyed webContents during shutdown.
+  }
+}
+
+/**
+ * Apply auth configuration to connection options
+ * Convenience function that combines buildAuthHandler results with connOpts
+ * @param {Object} connOpts - SSH connection options to modify
+ * @param {Object} authConfig - Auth configuration from buildAuthHandler
+ */
+function applyAuthToConnOpts(connOpts, authConfig) {
+  connOpts.authHandler = authConfig.authHandler;
+  if (authConfig.privateKey) {
+    connOpts.privateKey = authConfig.privateKey;
+  }
+  if (authConfig.agent) {
+    connOpts.agent = authConfig.agent;
+  }
+}
+
 /**
  * Request passphrases for encrypted default keys
  * Shows a modal for each encrypted key and collects passphrases
@@ -466,16 +454,16 @@ async function findAllDefaultPrivateKeys(options = {}) {
 async function requestPassphrasesForEncryptedKeys(sender, hostname) {
   const allKeys = await findAllDefaultPrivateKeys({ includeEncrypted: true });
   const encryptedKeys = allKeys.filter(k => k.isEncrypted);
-  
+
   if (encryptedKeys.length === 0) {
     return { keys: [], cancelled: false };
   }
-  
+
   console.log(`[SSHAuth] Found ${encryptedKeys.length} encrypted default key(s), requesting passphrases`);
-  
+
   const unlockedKeys = [];
   let wasCancelled = false;
-  
+
   for (const keyInfo of encryptedKeys) {
     const result = await passphraseHandler.requestPassphrase(
       sender,
@@ -483,27 +471,27 @@ async function requestPassphrasesForEncryptedKeys(sender, hostname) {
       keyInfo.keyName,
       hostname
     );
-    
+
     // Handle different response types
     if (!result) {
       // Timeout or error - continue with next key
       console.log(`[SSHAuth] No response for ${keyInfo.keyName}, continuing...`);
       continue;
     }
-    
+
     if (result.cancelled) {
       // User clicked Cancel - stop the entire flow
       console.log(`[SSHAuth] User cancelled passphrase flow at ${keyInfo.keyName}`);
       wasCancelled = true;
       break;
     }
-    
+
     if (result.skipped) {
       // User clicked Skip - continue with next key
       console.log(`[SSHAuth] User skipped passphrase for ${keyInfo.keyName}`);
       continue;
     }
-    
+
     if (result.passphrase) {
       // User provided passphrase
       unlockedKeys.push({
@@ -514,19 +502,19 @@ async function requestPassphrasesForEncryptedKeys(sender, hostname) {
       });
     }
   }
-  
+
   return { keys: unlockedKeys, cancelled: wasCancelled };
 }
 
- module.exports = {
-   DEFAULT_KEY_NAMES,
-   isKeyEncrypted,
-   findDefaultPrivateKey,
-   findAllDefaultPrivateKeys,
-   getSshAgentSocket,
-   buildAuthHandler,
-   createKeyboardInteractiveHandler,
-   applyAuthToConnOpts,
-   safeSend,
+module.exports = {
+  DEFAULT_KEY_NAMES,
+  isKeyEncrypted,
+  findDefaultPrivateKey,
+  findAllDefaultPrivateKeys,
+  getSshAgentSocket,
+  buildAuthHandler,
+  createKeyboardInteractiveHandler,
+  applyAuthToConnOpts,
+  safeSend,
   requestPassphrasesForEncryptedKeys,
- };
+};

electron/bridges/sshBridge.cjs

@@ -227,6 +227,31 @@ let electronModule = null;
 // Cache persists until auth failure, then cleared to retry all methods
 const authMethodCache = new Map();
 
+// Per-session terminal encoding (default: utf-8)
+const sessionEncodings = new Map();
+// Per-session stateful iconv decoders (keyed by sessionId, value: { stdout, stderr })
+const sessionDecoders = new Map();
+const iconv = require("iconv-lite");
+
+function getSessionDecoder(sessionId, stream) {
+  let decoders = sessionDecoders.get(sessionId);
+  if (!decoders) {
+    decoders = { stdout: null, stderr: null };
+    sessionDecoders.set(sessionId, decoders);
+  }
+  if (!decoders[stream]) {
+    const enc = sessionEncodings.get(sessionId) || "utf-8";
+    decoders[stream] = iconv.getDecoder(enc);
+  }
+  return decoders[stream];
+}
+
+function resetSessionDecoders(sessionId) {
+  const enc = sessionEncodings.get(sessionId) || "utf-8";
+  const decoders = { stdout: iconv.getDecoder(enc), stderr: iconv.getDecoder(enc) };
+  sessionDecoders.set(sessionId, decoders);
+}
+
 function getAuthCacheKey(username, hostname, port) {
   return `${username}@${hostname}:${port || 22}`;
 }
@@ -567,9 +592,14 @@ async function startSSHSession(event, options) {
     // If no primary auth method configured, try ssh-agent first, then ALL default keys
     if (!connectOpts.privateKey && !connectOpts.password && !connectOpts.agent) {
       // First, try to use ssh-agent if available (this is what regular SSH does)
-      const sshAgentSocket = process.platform === "win32"
-        ? "\\\\.\\pipe\\openssh-ssh-agent"
-        : process.env.SSH_AUTH_SOCK;
+      let sshAgentSocket;
+      if (process.platform === "win32") {
+        const agentStatus = await checkWindowsSshAgent();
+        log("Windows SSH Agent check", agentStatus);
+        sshAgentSocket = agentStatus.running ? "\\\\.\\pipe\\openssh-ssh-agent" : null;
+      } else {
+        sshAgentSocket = process.env.SSH_AUTH_SOCK;
+      }
 
       if (sshAgentSocket) {
         log("No auth method configured, trying ssh-agent first", { agentSocket: sshAgentSocket });
@@ -596,14 +626,23 @@ async function startSSHSession(event, options) {
 
     // Agent forwarding
     if (options.agentForwarding) {
-      connectOpts.agentForward = true;
       if (!connectOpts.agent) {
         if (process.platform === "win32") {
-          connectOpts.agent = "\\\\.\\pipe\\openssh-ssh-agent";
+          const agentStatus = await checkWindowsSshAgent();
+          log("Windows SSH Agent check (agentForwarding)", agentStatus);
+          if (agentStatus.running) {
+            connectOpts.agent = "\\\\.\\pipe\\openssh-ssh-agent";
+          }
         } else {
           connectOpts.agent = process.env.SSH_AUTH_SOCK;
         }
       }
+      // Only enable forwarding when an agent is actually available
+      if (connectOpts.agent) {
+        connectOpts.agentForward = true;
+      } else {
+        log("Agent forwarding requested but no agent available, skipping");
+      }
     }
 
     // Build authentication handler with fallback support
@@ -962,11 +1001,13 @@ async function startSSHSession(event, options) {
             };
 
             stream.on("data", (data) => {
-              bufferData(data.toString("utf8"));
+              const decoder = getSessionDecoder(sessionId, "stdout");
+              bufferData(decoder.write(data));
             });
 
             stream.stderr?.on("data", (data) => {
-              bufferData(data.toString("utf8"));
+              const decoder = getSessionDecoder(sessionId, "stderr");
+              bufferData(decoder.write(data));
             });
 
             stream.on("close", () => {
@@ -978,12 +1019,19 @@ async function startSSHSession(event, options) {
               const contents = event.sender;
               safeSend(contents, "netcatty:exit", { sessionId, exitCode: 0 });
               sessions.delete(sessionId);
+              sessionEncodings.delete(sessionId);
+              sessionDecoders.delete(sessionId);
               conn.end();
               for (const c of chainConnections) {
                 try { c.end(); } catch { }
               }
             });
 
+            // Pre-seed encoding from host charset if it's a GB variant
+            if (options.charset && /^gb/i.test(String(options.charset).trim())) {
+              sessionEncodings.set(sessionId, "gb18030");
+            }
+
             // Run startup command if specified
             if (options.startupCommand) {
               setTimeout(() => {
@@ -1325,7 +1373,9 @@ async function startSSHSessionWrapper(event, options) {
     if (isAuthError) {
       // Check if there are encrypted default keys we haven't tried yet
       // Only offer retry if no unlocked keys were provided in this attempt
-      if (!options._unlockedEncryptedKeys || options._unlockedEncryptedKeys.length === 0) {
+      const hasJumpHosts = options.jumpHosts && options.jumpHosts.length > 0;
+      const isPasswordOnly = !hasJumpHosts && !options.agentForwarding && !!options.password && !options.privateKey && !options.certificate;
+      if (!isPasswordOnly && (!options._unlockedEncryptedKeys || options._unlockedEncryptedKeys.length === 0)) {
         const allKeysWithEncrypted = await findAllDefaultPrivateKeysFromHelper({ includeEncrypted: true });
         const encryptedKeys = allKeysWithEncrypted.filter(k => k.isEncrypted);
 
@@ -1786,6 +1836,24 @@ async function getServerStats(event, payload) {
   });
 }
 
+/**
+ * Set terminal encoding for an active SSH session
+ */
+async function setSessionEncoding(_event, { sessionId, encoding }) {
+  const session = sessions?.get(sessionId);
+  if (!session || !session.stream) {
+    return { ok: false, encoding: encoding || "utf-8" };
+  }
+  const enc = String(encoding || "utf-8").toLowerCase();
+  if (!iconv.encodingExists(enc)) {
+    return { ok: false, encoding: enc };
+  }
+  sessionEncodings.set(sessionId, enc);
+  // Reset stateful decoders so new data uses the updated encoding
+  resetSessionDecoders(sessionId);
+  return { ok: true, encoding: enc };
+}
+
 /**
  * Register IPC handlers for SSH operations
  */
@@ -1795,6 +1863,7 @@ function registerHandlers(ipcMain) {
   ipcMain.handle("netcatty:ssh:pwd", getSessionPwd);
   ipcMain.handle("netcatty:ssh:stats", getServerStats);
   ipcMain.handle("netcatty:key:generate", generateKeyPair);
+  ipcMain.handle("netcatty:ssh:setEncoding", setSessionEncoding);
   ipcMain.handle("netcatty:ssh:check-agent", async () => {
     return await checkWindowsSshAgent();
   });

electron/bridges/transferBridge.cjs

@@ -6,7 +6,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const os = require("node:os");
-const { encodePathForSession, ensureRemoteDirForSession } = require("./sftpBridge.cjs");
+const { encodePathForSession, ensureRemoteDirForSession, requireSftpChannel } = require("./sftpBridge.cjs");
 
 // ── Transfer performance tuning ──────────────────────────────────────────────
 // ssh2's fastPut/fastGet send multiple SFTP read/write requests in parallel,
@@ -52,6 +52,7 @@ async function openIsolatedSftpChannel(client) {
  * Falls back to sequential stream piping if fastPut is unavailable.
  */
 async function uploadFile(localPath, remotePath, client, fileSize, transfer, sendProgress) {
+  await requireSftpChannel(client);
   const sftp = client.sftp;
   if (!sftp) throw new Error("SFTP client not ready");
 
@@ -159,6 +160,7 @@ async function uploadFile(localPath, remotePath, client, fileSize, transfer, sen
  * Falls back to sequential stream piping if fastGet is unavailable.
  */
 async function downloadFile(remotePath, localPath, client, fileSize, transfer, sendProgress) {
+  await requireSftpChannel(client);
   const sftp = client.sftp;
   if (!sftp) throw new Error("SFTP client not ready");
 
@@ -404,6 +406,7 @@ async function startTransfer(event, payload, onProgress) {
       } else if (sourceType === 'sftp') {
         const client = sftpClients.get(sourceSftpId);
         if (!client) throw new Error("Source SFTP session not found");
+        await requireSftpChannel(client);
         const encodedSourcePath = encodePathForSession(sourceSftpId, sourcePath, sourceEncoding);
         const stat = await client.stat(encodedSourcePath);
         fileSize = stat.size;

electron/preload.cjs

@@ -376,6 +376,8 @@ const api = {
   closeSession: (sessionId) => {
     ipcRenderer.send("netcatty:close", { sessionId });
   },
+  setSessionEncoding: (sessionId, encoding) =>
+    ipcRenderer.invoke("netcatty:ssh:setEncoding", { sessionId, encoding }),
   onSessionData: (sessionId, cb) => {
     if (!dataListeners.has(sessionId)) dataListeners.set(sessionId, new Set());
     dataListeners.get(sessionId).add(cb);

global.d.ts

@@ -229,6 +229,7 @@ declare global {
         }>;
       };
     }>;
+    setSessionEncoding?(sessionId: string, encoding: string): Promise<{ ok: boolean; encoding: string }>;
     writeToSession(sessionId: string, data: string): void;
     resizeSession(sessionId: string, cols: number, rows: number): void;
     closeSession(sessionId: string): void;

infrastructure/config/storageKeys.ts

@@ -41,6 +41,9 @@ export const STORAGE_KEY_UPDATE_DISMISSED_VERSION = 'netcatty_update_dismissed_v
 // SFTP File Opener Associations
 export const STORAGE_KEY_SFTP_FILE_ASSOCIATIONS = 'netcatty_sftp_file_associations_v1';
 
+// SFTP Local Bookmarks
+export const STORAGE_KEY_SFTP_LOCAL_BOOKMARKS = 'netcatty_sftp_local_bookmarks_v1';
+
 // SFTP Settings
 export const STORAGE_KEY_SFTP_DOUBLE_CLICK_BEHAVIOR = 'netcatty_sftp_double_click_behavior_v1';
 export const STORAGE_KEY_SFTP_AUTO_SYNC = 'netcatty_sftp_auto_sync_v1';