fix: stabilize scoped AI draft/session transitions (#724)

* fix: correct terminal AI history resume behavior

The previous implementation plan mistakenly treated reopening an old terminal AI session in a fresh or reconnected SSH tab as a scope-retargeting feature.

The intended rule is draft-first:
- a fresh or reconnected terminal opens on a blank draft
- older chats remain available in history for manual access
- selecting history does not imply automatic scope transfer into the new tab

This change is a rule correction, not a conflict between product rules.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: harden ai draft transitions

* fix ai session continuation from history

* fix: clear stale activeSessionIdMap entry when view resolves to draft

Addresses the Codex P2 review on aiPanelViewState.ts:38. When a terminal
scope mounts with a persisted activeSessionIdMap entry but no explicit
panelView and no draft, resolveDisplayedPanelView now returns the
default draft view (terminal fresh-start behavior). The sync effect
that writes into activeSessionIdMap is guarded by `if (!activeSession)
return`, so the old entry stays put. That stale entry then leaks into
activeTerminalTargetIds in every other scope, and
getSessionScopeMatchRank uses it to suppress host-matched history that
is actually resumable — so valid sessions vanish from the history
drawer until another action rewrites the map.

Add a dedicated effect that clears the scope's activeSessionIdMap
entry whenever the resolved panel view is draft but a persisted
session id is still present. This keeps the map an accurate record of
"which session each scope is currently showing" instead of a lagging
snapshot.

Also extend sessionScopeMatch.test.ts to cover the rank=2 exact-match
branch and the scope-type mismatch short-circuit, which were missing
from the original suite.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: track cross-terminal session ownership by session id, not targetId

Addresses the Codex follow-up review on commit 345244b2. When a user
resumes a session from history into a different terminal, the session's
`scope.targetId` still points at the original terminal. The previous
ownership tracking — which checked whether `session.scope.targetId`
appeared in `activeTerminalTargetIds` (derived from the keys of
`activeSessionIdMap`) — therefore:

- could not prevent the same session from being resumed in multiple
  terminals simultaneously, because the resumed session's targetId
  never matches the current scope's targetId; and
- let `pruneInactiveScopedSessions` treat a session as orphaned and
  clear its `externalSessionId` the moment the original terminal
  closed, even though another terminal was actively using it.

Switch ownership to be keyed on session id:

- `getSessionScopeMatchRank` now takes `activeTerminalSessionIds`
  (a Set of session ids currently displayed by other terminal scopes)
  and returns rank 0 when `session.id` is in that set.
- `AIChatSidePanel` derives `activeTerminalSessionIds` from the
  *values* of `activeSessionIdMap`, excluding the current scope's key.
- `pruneInactiveScopedSessions` gains an `activeSessionIds` parameter;
  sessions whose id is in this set are never reported as orphaned and
  never have their `externalSessionId` cleared, regardless of their
  stored `scope.targetId`.
- `cleanupOrphanedAISessions` computes the in-use set from the
  pre-cleanup `activeSessionIdMap`, filtered to live scopes, and
  passes it through. The map is read once and reused.

Tests cover the new id-based ownership, the rank-2 exact-match path,
the scope-type-mismatch short-circuit, and the
"resumed-elsewhere session must not be cleaned" invariant.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: bincxz <16399091+binaricat@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/workflows/build.yml

@@ -43,6 +43,21 @@ jobs:
       - name: Install deps
         run: npm ci
 
+      - name: Install cross-platform native binaries
+        shell: bash
+        run: |
+          # npm ci only installs optional deps for the host platform, but
+          # electron-builder produces both arm64 and x64 binaries, so we
+          # need the native codex-acp binary for the other architecture too.
+          # Platform-specific codex-acp packages declare cpu/os constraints,
+          # so --force is needed to install the non-host-arch binary.
+          CODEX_VER=$(node -e "console.log(require('./node_modules/@zed-industries/codex-acp/package.json').version)")
+          if [[ "${{ matrix.name }}" == "macos" ]]; then
+            npm install "@zed-industries/codex-acp-darwin-x64@${CODEX_VER}" "@zed-industries/codex-acp-darwin-arm64@${CODEX_VER}" --no-save --force
+          elif [[ "${{ matrix.name }}" == "windows" ]]; then
+            npm install "@zed-industries/codex-acp-win32-x64@${CODEX_VER}" "@zed-industries/codex-acp-win32-arm64@${CODEX_VER}" --no-save --force
+          fi
+
       - name: Set version
         shell: bash
         run: |

AGENTS.md

@@ -18,7 +18,7 @@ This project is wired around three layers: domain (pure logic), application stat
 - **UI** (`components/`, `App.tsx`): Presentation; depends on hooks and domain helpers only.
 
 ## How Things Talk
-- UI calls application hooks → hooks call domain helpers → persistence/config via infrastructure adapters.
+- UI calls application hooks -> hooks call domain helpers -> persistence/config via infrastructure adapters.
 - `App.tsx` wires hooks to components; no business logic should live in components beyond view glue.
 - Local storage keys are centralized in `infrastructure/config/storageKeys.ts`; avoid ad-hoc `localStorage` calls elsewhere.
 
@@ -44,6 +44,12 @@ This project is wired around three layers: domain (pure logic), application stat
 - Avoid direct network/fetch in components; add a service/adaptor first.
 - Maintain ASCII-only unless required by existing file content.
 
+## Review Boundaries
+- Treat `electron/cli/*`, `netcatty-tool-cli`, the CLI discovery file, and the local TCP bridge as internal Netcatty integration surfaces unless a task explicitly says otherwise.
+- Do not review those surfaces as public APIs by default, and do not assume they must support third-party callers, manual launches, or non-Netcatty agents.
+- On supported first-party paths, assume Netcatty's own launcher provides required integration environment such as `NETCATTY_TOOL_CLI_DISCOVERY_FILE`.
+- If a review concern depends on external exposure, third-party compatibility, or public API stability, call it out as out of scope unless the task explicitly includes that contract.
+
 ---
 
 ## Aside Panel Design System
@@ -54,20 +60,20 @@ VaultView subpages (Hosts, Keychain, Port Forwarding, Snippets, Known Hosts) sha
 
 Import from `./ui/aside-panel`:
 ```tsx
-import { 
-  AsidePanel, 
-  AsidePanelHeader, 
-  AsidePanelContent, 
+import {
+  AsidePanel,
+  AsidePanelHeader,
+  AsidePanelContent,
   AsidePanelFooter,
   AsideActionMenu,
-  AsideActionMenuItem 
+  AsideActionMenuItem
 } from "./ui/aside-panel";
 ```
 
 ### Basic Usage
 ```tsx
-<AsidePanel 
-  open={isOpen} 
+<AsidePanel
+  open={isOpen}
   onClose={handleClose}
   title="Panel Title"
   subtitle="Optional subtitle"

App.tsx

@@ -20,18 +20,29 @@ import { resolveHostTerminalThemeId } from './domain/terminalAppearance';
 import { collectSessionIds } from './domain/workspace';
 import { TERMINAL_THEMES } from './infrastructure/config/terminalThemes';
 import { useCustomThemes } from './application/state/customThemeStore';
-import { applySyncPayload } from './application/syncPayload';
+import type { SyncPayload } from './domain/sync';
+import { applySyncPayload, buildSyncPayload, hasMeaningfulSyncData } from './application/syncPayload';
+import {
+  applyProtectedSyncPayload,
+  ensureVersionChangeBackup,
+} from './application/localVaultBackups';
 import { getCredentialProtectionAvailability } from './infrastructure/services/credentialProtection';
 import { netcattyBridge } from './infrastructure/services/netcattyBridge';
 import { localStorageAdapter } from './infrastructure/persistence/localStorageAdapter';
-import { STORAGE_KEY_DEBUG_HOTKEYS } from './infrastructure/config/storageKeys';
+import { AlertTriangle, Download, Trash2 } from 'lucide-react';
+import {
+  STORAGE_KEY_DEBUG_HOTKEYS,
+  STORAGE_KEY_PORT_FORWARDING,
+} from './infrastructure/config/storageKeys';
+import { getEffectiveKnownHosts } from './infrastructure/syncHelpers';
 import { TopTabs } from './components/TopTabs';
 import { Button } from './components/ui/button';
-import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from './components/ui/dialog';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from './components/ui/dialog';
 import { Input } from './components/ui/input';
 import { Label } from './components/ui/label';
 import { ToastProvider, toast } from './components/ui/toast';
 import { VaultView, VaultSection } from './components/VaultView';
+import { QuickAddSnippetDialog } from './components/QuickAddSnippetDialog';
 import { KeyboardInteractiveModal, KeyboardInteractiveRequest } from './components/KeyboardInteractiveModal';
 import { PassphraseModal, PassphraseRequest } from './components/PassphraseModal';
 import { cn } from './lib/utils';
@@ -177,10 +188,12 @@ function App({ settings }: { settings: SettingsState }) {
   const [passphraseQueue, setPassphraseQueue] = useState<PassphraseRequest[]>([]);
 
   const {
+    theme,
     setTheme,
     resolvedTheme,
     terminalThemeId,
     setTerminalThemeId,
+    followAppTerminalTheme,
     currentTerminalTheme,
     terminalFontFamilyId,
     setTerminalFontFamilyId,
@@ -218,6 +231,7 @@ function App({ settings }: { settings: SettingsState }) {
   }, [workspaceFocusStyle]);
 
   const {
+    isInitialized: isVaultInitialized,
     hosts,
     keys,
     identities,
@@ -303,6 +317,12 @@ function App({ settings }: { settings: SettingsState }) {
   const activeTabId = useActiveTabId();
   const customThemes = useCustomThemes();
 
+  useEffect(() => {
+    if (!settings.showSftpTab && activeTabId === 'sftp') {
+      setActiveTabId('vault');
+    }
+  }, [settings.showSftpTab, activeTabId, setActiveTabId]);
+
   // Resolve the effective TerminalTheme for the currently focused terminal tab
   const hostById = useMemo(
     () => new Map(hosts.map((host) => [host.id, host])),
@@ -326,6 +346,11 @@ function App({ settings }: { settings: SettingsState }) {
     if (activeTabId === 'vault' || activeTabId === 'sftp') return null;
 
     const resolveTheme = (s: TerminalSession): TerminalTheme => {
+      // When "Follow Application Theme" is on, the UI-matched terminal
+      // theme overrides everything — including per-host theme overrides.
+      // This ensures all terminals match the app chrome regardless of
+      // individual host settings.
+      if (followAppTerminalTheme) return currentTerminalTheme;
       const host = hostById.get(s.hostId) ?? null;
       const themeId = resolveHostTerminalThemeId(host, currentTerminalTheme.id);
       return themeById.get(themeId) || currentTerminalTheme;
@@ -358,7 +383,7 @@ function App({ settings }: { settings: SettingsState }) {
     const session = sessionById.get(activeTabId);
     if (!session) return null;
     return resolveTheme(session);
-  }, [activeTabId, currentTerminalTheme, hostById, sessionById, themeById, workspaceById]);
+  }, [activeTabId, currentTerminalTheme, followAppTerminalTheme, hostById, sessionById, themeById, workspaceById]);
 
   useImmersiveMode({
     activeTabId,
@@ -380,8 +405,131 @@ function App({ settings }: { settings: SettingsState }) {
     [portForwardingRules],
   );
 
+  const buildCurrentSyncPayload = useCallback(() => {
+    let effectivePortForwardingRules = portForwardingRulesForSync;
+    if (effectivePortForwardingRules.length === 0) {
+      const stored = localStorageAdapter.read<typeof portForwardingRulesForSync>(
+        STORAGE_KEY_PORT_FORWARDING,
+      );
+      if (stored && Array.isArray(stored) && stored.length > 0) {
+        effectivePortForwardingRules = stored.map((rule) => ({
+          ...rule,
+          status: 'inactive' as const,
+          error: undefined,
+          lastUsedAt: undefined,
+        }));
+      }
+    }
+
+    return buildSyncPayload(
+      {
+        hosts,
+        keys,
+        identities,
+        snippets,
+        customGroups,
+        snippetPackages,
+        knownHosts: getEffectiveKnownHosts(knownHosts),
+        groupConfigs,
+      },
+      effectivePortForwardingRules,
+    );
+  }, [
+    customGroups,
+    groupConfigs,
+    hosts,
+    identities,
+    keys,
+    knownHosts,
+    portForwardingRulesForSync,
+    snippetPackages,
+    snippets,
+  ]);
+
+  const [startupSyncSafetyReady, setStartupSyncSafetyReady] = useState(false);
+  // buildCurrentSyncPayload's identity changes each time the vault
+  // settles. The retry effect below watches the underlying data arrays
+  // for hydration progress, and uses the ref to always read the latest
+  // builder without pulling buildCurrentSyncPayload itself into deps
+  // (its identity churns on unrelated state updates too).
+  const buildCurrentSyncPayloadRef = useRef(buildCurrentSyncPayload);
+  useEffect(() => {
+    buildCurrentSyncPayloadRef.current = buildCurrentSyncPayload;
+  }, [buildCurrentSyncPayload]);
+
+  const versionBackupAttemptedRef = useRef(false);
+  // Two-stage gate: once the vault has initialized we open the auto-sync
+  // gate immediately — the hook's own hasMeaningfulSyncData guard and
+  // the cross-window restore barrier prevent an empty-but-not-yet-
+  // hydrated snapshot from overwriting cloud data. The version-change
+  // backup itself is best-effort and retries below as vault data arrives.
+  useEffect(() => {
+    if (isVaultInitialized && !startupSyncSafetyReady) {
+      setStartupSyncSafetyReady(true);
+    }
+  }, [isVaultInitialized, startupSyncSafetyReady]);
+
+  // Retry the version-change backup as hosts/keys/snippets become
+  // available. ensureVersionChangeBackup refuses to advance the stored
+  // version stamp when the observed payload is empty, so running this
+  // effect repeatedly is safe and eventually latches once the vault has
+  // hydrated enough to be backed up (or the user genuinely stays empty,
+  // in which case the effect continues to no-op).
+  useEffect(() => {
+    if (!isVaultInitialized || versionBackupAttemptedRef.current) return;
+    const payload = buildCurrentSyncPayloadRef.current();
+    if (!hasMeaningfulSyncData(payload)) return;
+    versionBackupAttemptedRef.current = true;
+
+    let cancelled = false;
+    void (async () => {
+      try {
+        const info = await netcattyBridge.get()?.getAppInfo?.();
+        await ensureVersionChangeBackup(payload, info?.version ?? null);
+      } catch (error) {
+        if (!cancelled) {
+          // Reset the latch so a later data change (or the next mount)
+          // can retry. ensureVersionChangeBackup already leaves the
+          // version stamp untouched on failure, so retrying is safe.
+          versionBackupAttemptedRef.current = false;
+        }
+        console.error('[App] Failed to create version-change backup:', error);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [isVaultInitialized, hosts, keys, identities, snippets, customGroups, snippetPackages, knownHosts]);
+
+  // Memoized "apply a remote payload safely" callback. Stable identity
+  // across renders so useAutoSync's `syncNow` useCallback doesn't rebuild
+  // on unrelated App-level state changes (which would churn the debounced
+  // auto-sync useEffect dep chain).
+  const handleApplySyncPayload = useCallback(
+    (payload: SyncPayload) =>
+      applyProtectedSyncPayload({
+        buildPreApplyPayload: () => buildCurrentSyncPayload(),
+        applyPayload: () =>
+          applySyncPayload(payload, {
+            importVaultData: importDataFromString,
+            importPortForwardingRules,
+            onSettingsApplied: settings.rehydrateAllFromStorage,
+          }),
+        translateProtectiveBackupFailure: (message) =>
+          t('cloudSync.localBackups.protectiveBackupFailed', { message }),
+      }),
+    [
+      buildCurrentSyncPayload,
+      importDataFromString,
+      importPortForwardingRules,
+      settings.rehydrateAllFromStorage,
+      t,
+    ],
+  );
+
   // Auto-sync hook for cloud sync
-  const { syncNow: handleSyncNow } = useAutoSync({
+  const { syncNow: handleSyncNow, emptyVaultConflict, resolveEmptyVaultConflict } = useAutoSync({
     hosts,
     keys,
     identities,
@@ -392,13 +540,8 @@ function App({ settings }: { settings: SettingsState }) {
     knownHosts,
     groupConfigs,
     settingsVersion: settings.settingsVersion,
-    onApplyPayload: (payload) => {
-      applySyncPayload(payload, {
-        importVaultData: importDataFromString,
-        importPortForwardingRules,
-        onSettingsApplied: settings.rehydrateAllFromStorage,
-      });
-    },
+    startupReady: startupSyncSafetyReady,
+    onApplyPayload: handleApplySyncPayload,
   });
 
   const { clearAndRemoveSource, clearAndRemoveSources, unmanageSource } = useManagedSourceSync({
@@ -544,7 +687,7 @@ function App({ settings }: { settings: SettingsState }) {
       if (binding.category === 'sftp') {
         continue;
       }
-      const terminalActions = ['copy', 'paste', 'selectAll', 'clearBuffer', 'searchTerminal'];
+      const terminalActions = ['copy', 'paste', 'pasteSelection', 'selectAll', 'clearBuffer', 'searchTerminal'];
       if (terminalActions.includes(binding.action)) {
         if (isTerminalElement) {
           return;
@@ -722,6 +865,7 @@ function App({ settings }: { settings: SettingsState }) {
       // Add to queue instead of replacing - supports multiple concurrent sessions
       setKeyboardInteractiveQueue(prev => [...prev, {
         requestId: request.requestId,
+        sessionId: request.sessionId,
         name: request.name,
         instructions: request.instructions,
         prompts: request.prompts,
@@ -736,14 +880,29 @@ function App({ settings }: { settings: SettingsState }) {
   }, []);
 
   // Handle keyboard-interactive submit
-  const handleKeyboardInteractiveSubmit = useCallback((requestId: string, responses: string[]) => {
+  const handleKeyboardInteractiveSubmit = useCallback((requestId: string, responses: string[], savePassword?: string) => {
     const bridge = netcattyBridge.get();
     if (bridge?.respondKeyboardInteractive) {
       void bridge.respondKeyboardInteractive(requestId, responses, false);
     }
+    // Save password to host if requested
+    if (savePassword) {
+      const request = keyboardInteractiveQueue.find(r => r.requestId === requestId);
+      if (request?.sessionId) {
+        const session = sessions.find(s => s.id === request.sessionId);
+        // Only save when the prompting hostname matches the session's host,
+        // to avoid overwriting the destination host's password with a jump host's password
+        if (session?.hostId && (!request.hostname || request.hostname === session.hostname)) {
+          const host = hosts.find(h => h.id === session.hostId);
+          if (host) {
+            updateHosts(hosts.map(h => h.id === host.id ? { ...h, password: savePassword } : h));
+          }
+        }
+      }
+    }
     // Remove from queue by requestId
     setKeyboardInteractiveQueue(prev => prev.filter(r => r.requestId !== requestId));
-  }, []);
+  }, [keyboardInteractiveQueue, sessions, hosts, updateHosts]);
 
   // Handle keyboard-interactive cancel
   const handleKeyboardInteractiveCancel = useCallback((requestId: string) => {
@@ -868,13 +1027,18 @@ function App({ settings }: { settings: SettingsState }) {
 
   // Shared hotkey action handler - used by both global handler and terminal callback
   const executeHotkeyAction = useCallback((action: string, e: KeyboardEvent) => {
+    // Build complete tab list: vault + (sftp when visible) + sessions/workspaces.
+    // Hiding the SFTP tab must also remove it from keyboard cycling so nextTab
+    // doesn't land on a hidden tab (which would get redirected back) and so
+    // number shortcuts don't shift.
+    const allTabs = settings.showSftpTab
+      ? ['vault', 'sftp', ...orderedTabs]
+      : ['vault', ...orderedTabs];
     switch (action) {
       case 'switchToTab': {
         // Get the number key pressed (1-9)
         const num = parseInt(e.key, 10);
         if (num >= 1 && num <= 9) {
-          // Build complete tab list: vault + sftp + sessions/workspaces
-          const allTabs = ['vault', 'sftp', ...orderedTabs];
           if (num <= allTabs.length) {
             setActiveTabId(allTabs[num - 1]);
           }
@@ -882,8 +1046,6 @@ function App({ settings }: { settings: SettingsState }) {
         break;
       }
       case 'nextTab': {
-        // Build complete tab list: vault + sftp + sessions/workspaces
-        const allTabs = ['vault', 'sftp', ...orderedTabs];
         const currentId = activeTabStore.getActiveTabId();
         const currentIdx = allTabs.indexOf(currentId);
         if (currentIdx !== -1 && allTabs.length > 0) {
@@ -895,8 +1057,6 @@ function App({ settings }: { settings: SettingsState }) {
         break;
       }
       case 'prevTab': {
-        // Build complete tab list: vault + sftp + sessions/workspaces
-        const allTabs = ['vault', 'sftp', ...orderedTabs];
         const currentId = activeTabStore.getActiveTabId();
         const currentIdx = allTabs.indexOf(currentId);
         if (currentIdx !== -1 && allTabs.length > 0) {
@@ -943,7 +1103,9 @@ function App({ settings }: { settings: SettingsState }) {
         setActiveTabId('vault');
         break;
       case 'openSftp':
-        setActiveTabId('sftp');
+        if (settings.showSftpTab) {
+          setActiveTabId('sftp');
+        }
         break;
       case 'quickSwitch':
       case 'commandPalette':
@@ -969,32 +1131,32 @@ function App({ settings }: { settings: SettingsState }) {
         break;
       }
       case 'splitHorizontal': {
-        // Split current terminal horizontally (top/bottom)
         const currentId = activeTabStore.getActiveTabId();
-        // Check if it's a standalone session or we're in a workspace
         const activeSession = sessions.find(s => s.id === currentId);
         const activeWs = workspaces.find(w => w.id === currentId);
         if (activeSession && !activeSession.workspaceId) {
-          // Standalone session - split it
           splitSessionWithCurrentShell(activeSession.id, 'horizontal');
         } else if (activeWs) {
-          // In a workspace - need to determine focused session
-          // For now, we'll need the terminal to handle this via context menu
-          if (IS_DEV) console.log('[Hotkey] Split horizontal in workspace - use context menu on specific terminal');
+          const liveIds = collectSessionIds(activeWs.root);
+          const targetId = (activeWs.focusedSessionId && liveIds.includes(activeWs.focusedSessionId))
+            ? activeWs.focusedSessionId
+            : liveIds[0];
+          if (targetId) splitSessionWithCurrentShell(targetId, 'horizontal');
         }
         break;
       }
       case 'splitVertical': {
-        // Split current terminal vertically (left/right)
         const currentId = activeTabStore.getActiveTabId();
         const activeSession = sessions.find(s => s.id === currentId);
         const activeWs = workspaces.find(w => w.id === currentId);
         if (activeSession && !activeSession.workspaceId) {
-          // Standalone session - split it
           splitSessionWithCurrentShell(activeSession.id, 'vertical');
         } else if (activeWs) {
-          // In a workspace - need to determine focused session
-          if (IS_DEV) console.log('[Hotkey] Split vertical in workspace - use context menu on specific terminal');
+          const liveIds = collectSessionIds(activeWs.root);
+          const targetId = (activeWs.focusedSessionId && liveIds.includes(activeWs.focusedSessionId))
+            ? activeWs.focusedSessionId
+            : liveIds[0];
+          if (targetId) splitSessionWithCurrentShell(targetId, 'vertical');
         }
         break;
       }
@@ -1031,7 +1193,7 @@ function App({ settings }: { settings: SettingsState }) {
         break;
       }
     }
-  }, [orderedTabs, sessions, workspaces, setActiveTabId, closeSession, closeWorkspace, createLocalTerminalWithCurrentShell, splitSessionWithCurrentShell, moveFocusInWorkspace, toggleBroadcast]);
+  }, [orderedTabs, sessions, workspaces, setActiveTabId, closeSession, closeWorkspace, createLocalTerminalWithCurrentShell, splitSessionWithCurrentShell, moveFocusInWorkspace, toggleBroadcast, settings.showSftpTab]);
 
   // Callback for terminal to invoke app-level hotkey actions
   const handleHotkeyAction = useCallback((action: string, e: KeyboardEvent) => {
@@ -1285,10 +1447,24 @@ function App({ settings }: { settings: SettingsState }) {
   }, [protocolSelectHost, handleConnectToHost]);
 
   const handleToggleTheme = useCallback(() => {
-    // Toggle based on the actual rendered theme so clicking always produces a visible change,
-    // even when the stored preference is 'system'.
+    if (theme === 'system') {
+      toast.info(
+        t('topTabs.toggleTheme.systemExitMessage'),
+        {
+          title: t('topTabs.toggleTheme.systemExitTitle'),
+          actionLabel: t('topTabs.toggleTheme.openSettings'),
+          onClick: () => {
+            void (async () => {
+              const opened = await openSettingsWindow();
+              if (!opened) toast.error(t('toast.settingsUnavailable'), t('common.settings'));
+            })();
+          },
+        }
+      );
+      return;
+    }
     setTheme(resolvedTheme === 'dark' ? 'light' : 'dark');
-  }, [resolvedTheme, setTheme]);
+  }, [openSettingsWindow, resolvedTheme, setTheme, t, theme]);
 
   const handleOpenQuickSwitcher = useCallback(() => {
     setIsQuickSwitcherOpen(true);
@@ -1362,6 +1538,7 @@ function App({ settings }: { settings: SettingsState }) {
     <div className={cn("flex flex-col h-screen text-foreground font-sans netcatty-shell", activeTerminalTheme && "immersive-transition")} onContextMenu={handleRootContextMenu}>
       <TopTabs
         theme={resolvedTheme}
+        followAppTerminalTheme={followAppTerminalTheme}
         hosts={hosts}
         sessions={sessions}
         orphanSessions={orphanSessions}
@@ -1384,6 +1561,7 @@ function App({ settings }: { settings: SettingsState }) {
         onStartSessionDrag={setDraggingSessionId}
         onEndSessionDrag={handleEndSessionDrag}
         onReorderTabs={reorderTabs}
+        showSftpTab={settings.showSftpTab}
       />
 
       <div className="flex-1 relative min-h-0">
@@ -1429,6 +1607,8 @@ function App({ settings }: { settings: SettingsState }) {
             onClearUnsavedConnectionLogs={clearUnsavedConnectionLogs}
             onRunSnippet={runSnippet}
             onOpenLogView={openLogView}
+            showRecentHosts={settings.showRecentHosts}
+            showOnlyUngroupedHostsInRoot={settings.showOnlyUngroupedHostsInRoot}
             navigateToSection={navigateToSection}
             onNavigateToSectionHandled={() => setNavigateToSection(null)}
           />
@@ -1463,6 +1643,7 @@ function App({ settings }: { settings: SettingsState }) {
           knownHosts={knownHosts}
           draggingSessionId={draggingSessionId}
           terminalTheme={currentTerminalTheme}
+          followAppTerminalTheme={followAppTerminalTheme}
           terminalSettings={terminalSettings}
           terminalFontFamilyId={terminalFontFamilyId}
           fontSize={terminalFontSize}
@@ -1522,6 +1703,17 @@ function App({ settings }: { settings: SettingsState }) {
         })}
       </div>
 
+      {/* Global "quick add snippet" dialog, triggered by the
+          netcatty:snippets:add window event (from ScriptsSidePanel "+"). */}
+      <QuickAddSnippetDialog
+        snippets={snippets}
+        packages={snippetPackages}
+        onCreateSnippet={(snippet) => updateSnippets([...snippets, snippet])}
+        onCreatePackage={(pkg) =>
+          updateSnippetPackages(Array.from(new Set([...snippetPackages, pkg])))
+        }
+      />
+
       {isQuickSwitcherOpen && (
         <Suspense fallback={null}>
           <LazyQuickSwitcher
@@ -1530,6 +1722,7 @@ function App({ settings }: { settings: SettingsState }) {
             results={quickResults}
             sessions={sessions}
             workspaces={workspaces}
+            showSftpTab={settings.showSftpTab}
             onQueryChange={setQuickSearch}
             onSelect={handleHostConnectWithProtocolCheck}
             onSelectTab={(tabId) => {
@@ -1651,6 +1844,59 @@ function App({ settings }: { settings: SettingsState }) {
         onCancel={handlePassphraseCancel}
         onSkip={handlePassphraseSkip}
       />
+
+      {/* Empty vault vs cloud data confirmation dialog (#679).
+          This dialog intentionally cannot be dismissed — the user MUST
+          choose "Restore" or "Keep Empty" before the sync flow can
+          proceed. hideCloseButton removes the X button, onOpenChange
+          is a no-op so ESC also does nothing, and onInteractOutside
+          prevents click-away. */}
+      <Dialog open={!!emptyVaultConflict} onOpenChange={() => { /* intentionally non-dismissable */ }}>
+        <DialogContent className="max-w-md" hideCloseButton onInteractOutside={(e) => e.preventDefault()} onEscapeKeyDown={(e) => e.preventDefault()}>
+          <DialogHeader>
+            <DialogTitle className="flex items-center gap-2">
+              <AlertTriangle className="w-5 h-5 text-amber-500" />
+              {t('sync.autoSync.emptyVaultConflict.title')}
+            </DialogTitle>
+            <DialogDescription>
+              {t('sync.autoSync.emptyVaultConflict.description')}
+            </DialogDescription>
+          </DialogHeader>
+          {emptyVaultConflict && (
+            <div className="bg-muted/30 rounded-lg p-3 text-sm">
+              <div className="font-medium text-muted-foreground mb-1">{t('sync.autoSync.emptyVaultConflict.cloudLabel')}</div>
+              <div>{t('sync.autoSync.emptyVaultConflict.cloudSummary', {
+                hosts: emptyVaultConflict.hostCount,
+                keys: emptyVaultConflict.keyCount,
+                snippets: emptyVaultConflict.snippetCount,
+              })}</div>
+            </div>
+          )}
+          <DialogFooter className="flex-col gap-2 sm:flex-col">
+            <Button
+              onClick={() => resolveEmptyVaultConflict('restore')}
+              className="w-full justify-start gap-2"
+            >
+              <Download className="w-4 h-4" />
+              <span>
+                {t('sync.autoSync.emptyVaultConflict.restore')}
+                <span className="text-xs opacity-70 ml-1">— {t('sync.autoSync.emptyVaultConflict.restoreDesc')}</span>
+              </span>
+            </Button>
+            <Button
+              variant="outline"
+              onClick={() => resolveEmptyVaultConflict('keep-empty')}
+              className="w-full justify-start gap-2"
+            >
+              <Trash2 className="w-4 h-4" />
+              <span>
+                {t('sync.autoSync.emptyVaultConflict.keepEmpty')}
+                <span className="text-xs opacity-70 ml-1">— {t('sync.autoSync.emptyVaultConflict.keepEmptyDesc')}</span>
+              </span>
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }

application/i18n/locales/en.ts

@@ -197,9 +197,15 @@ const en: Messages = {
   'settings.application.github.subtitle': 'Source code',
   'settings.application.whatsNew': "What's new",
   'settings.application.whatsNew.subtitle': 'Show release notes',
+  'settings.application.openExternal.failedTitle': 'Cannot open link',
+  'settings.application.openExternal.failedBody': 'The link could not be opened in either the system browser or the built-in browser window.',
   'settings.vault.title': 'Vault',
   'settings.vault.showRecentHosts': 'Show recently connected hosts',
   'settings.vault.showRecentHostsDesc': 'Display a section of recently connected hosts at the top of the vault',
+  'settings.vault.showOnlyUngroupedHostsInRoot': 'Only show ungrouped hosts at root',
+  'settings.vault.showOnlyUngroupedHostsInRootDesc': 'When enabled, the root host list only shows hosts without a group. Open a group from the sidebar to see grouped hosts.',
+  'settings.vault.showSftpTab': 'Show SFTP tab',
+  'settings.vault.showSftpTabDesc': 'Display the standalone SFTP view in the top tab bar. When hidden, use the in-session SFTP side panel instead.',
 
   // Update notifications
   'update.available.title': 'Update Available',
@@ -237,9 +243,9 @@ const en: Messages = {
   'settings.appearance.themeColor.dark': 'Dark palette',
   'settings.appearance.customCss': 'Custom CSS',
   'settings.appearance.customCss.desc':
-    'Add custom CSS to personalize the app appearance. Changes apply immediately.',
+    'Add custom CSS to personalize the app appearance. Changes apply immediately. Major UI regions expose a [data-section="..."] attribute you can target — e.g. snippets-panel, host-details-panel, group-details-panel, serial-host-details-panel, ai-chat-panel, vault-sidebar, vault-main, vault-hosts-header, vault-host-list, vault-view, terminal-workspace, terminal-workspace-sidebar, top-tabs.',
   'settings.appearance.customCss.placeholder':
-    '/* Example: */\n.terminal { background: #1a1a2e !important; }\n:root { --radius: 0.25rem; }',
+    '/* Examples — use !important to beat Tailwind utility specificity */\n\n/* Make snippet sidebar text larger */\n[data-section="snippets-panel"] {\n  font-size: 14px !important;\n}\n\n/* Custom terminal background */\n.terminal { background: #1a1a2e !important; }\n\n/* Tweak global border radius */\n:root { --radius: 0.25rem; }',
   'settings.appearance.language': 'Language',
   'settings.appearance.language.desc': 'Choose the UI language',
   'settings.appearance.uiFont': 'Interface Font',
@@ -251,6 +257,8 @@ const en: Messages = {
   'settings.terminal.themeModal.darkThemes': 'Dark Themes',
   'settings.terminal.themeModal.lightThemes': 'Light Themes',
   'settings.terminal.theme.selectButton': 'Select Theme',
+  'settings.terminal.theme.followApp': 'Follow Application Theme',
+  'settings.terminal.theme.followApp.desc': 'Automatically match the terminal background to the current app theme for a seamless look.',
   'settings.terminal.section.font': 'Font',
   'settings.terminal.section.cursor': 'Cursor',
   'settings.terminal.section.keyboard': 'Keyboard',
@@ -435,13 +443,30 @@ const en: Messages = {
   'sync.toast.completedMessage': 'Sync completed successfully',
   'sync.toast.errorTitle': 'Sync Error',
   'sync.autoSync.failedTitle': 'Sync failed',
+  'sync.autoSync.inspectFailedTitle': 'Sync paused',
+  'sync.autoSync.inspectFailedMessage': 'Could not reach the cloud to check for changes. Auto-sync will retry when data changes or the app is restarted.',
   'sync.autoSync.syncedTitle': 'Synced from cloud',
   'sync.autoSync.syncedMessage': 'Your data has been updated from the cloud.',
   'sync.autoSync.noProvider': 'No cloud provider connected. Open Settings → Sync & Cloud to connect one.',
   'sync.autoSync.alreadySyncing': 'Sync is already in progress.',
+  'sync.autoSync.restoreInProgress': 'A vault restore is in progress in another window. Please wait for it to finish.',
+  'sync.autoSync.interruptedApplyTitle': 'Sync paused — previous restore interrupted',
+  'sync.autoSync.interruptedApplyMessage': 'A previous restore did not finish cleanly, so the local vault may be inconsistent. Open Settings → Sync & Cloud → Restore and apply a protective backup before auto-sync resumes.',
   'sync.autoSync.vaultLocked': 'Vault is locked. Open Settings → Sync & Cloud to unlock.',
   'sync.autoSync.conflictDetected': 'Sync conflict detected. Open Settings → Sync & Cloud to resolve.',
   'sync.autoSync.syncFailed': 'Sync failed',
+  'sync.autoSync.restoredTitle': 'Vault restored',
+  'sync.autoSync.restoredMessage': 'Your vault has been restored from the cloud.',
+  'sync.autoSync.keptLocalTitle': 'Kept local vault',
+  'sync.autoSync.keptLocalMessage': 'Your empty local vault was kept. Cloud data was not applied.',
+  'sync.autoSync.emptyVaultConflict.title': 'Empty Vault Detected',
+  'sync.autoSync.emptyVaultConflict.description': 'Your local vault is empty, but the cloud has data. This usually happens after an update or storage reset. What would you like to do?',
+  'sync.autoSync.emptyVaultConflict.cloudLabel': 'Cloud',
+  'sync.autoSync.emptyVaultConflict.restore': 'Restore from Cloud',
+  'sync.autoSync.emptyVaultConflict.restoreDesc': 'Recommended — recover your hosts, keys, and snippets from the cloud backup',
+  'sync.autoSync.emptyVaultConflict.keepEmpty': 'Keep Empty',
+  'sync.autoSync.emptyVaultConflict.keepEmptyDesc': 'Start fresh with an empty vault',
+  'sync.autoSync.emptyVaultConflict.cloudSummary': '{hosts} hosts, {keys} keys, {snippets} snippets',
   'sync.credentialsUnavailable': 'This device cannot decrypt some saved credentials. Re-enter credentials locally before syncing.',
   'time.never': 'Never',
   'time.justNow': 'Just now',
@@ -529,6 +554,7 @@ const en: Messages = {
   'vault.hosts.deselectAll': 'Deselect All',
   'vault.hosts.deleteSelected': 'Delete ({count})',
   'vault.hosts.deleteMultiple.success': 'Deleted {count} hosts',
+  'vault.hosts.moveToGroup.success': 'Moved {host} to {group}',
   'vault.hosts.empty.title': 'Set up your hosts',
   'vault.hosts.empty.desc': 'Save hosts to quickly connect to your servers, VMs, and containers.',
 
@@ -983,6 +1009,14 @@ const en: Messages = {
   'hostDetails.distro.option.almalinux': 'AlmaLinux',
   'hostDetails.distro.option.oracle': 'Oracle Linux',
   'hostDetails.distro.option.kali': 'Kali Linux',
+  'hostDetails.distro.option.cisco': 'Cisco',
+  'hostDetails.distro.option.juniper': 'Juniper Networks',
+  'hostDetails.distro.option.huawei': 'Huawei',
+  'hostDetails.distro.option.hpe': 'HPE / H3C',
+  'hostDetails.distro.option.mikrotik': 'MikroTik',
+  'hostDetails.distro.option.fortinet': 'Fortinet',
+  'hostDetails.distro.option.paloalto': 'Palo Alto Networks',
+  'hostDetails.distro.option.zyxel': 'ZyXEL',
   'hostDetails.section.mosh': 'Mosh',
   'hostDetails.username.placeholder': 'Username',
   'hostDetails.password.placeholder': 'Password',
@@ -1127,7 +1161,7 @@ const en: Messages = {
   'terminal.toolbar.library': 'Library',
   'terminal.toolbar.noSnippets': 'No snippets available',
   'terminal.toolbar.terminalSettings': 'Terminal settings',
-  'terminal.toolbar.searchTerminal': 'Search terminal (Ctrl+F)',
+  'terminal.toolbar.searchTerminal': 'Search terminal',
   'terminal.toolbar.search': 'Search',
   'terminal.toolbar.broadcast': 'Broadcast',
   'terminal.toolbar.broadcastEnable': 'Enable Broadcast Mode',
@@ -1183,6 +1217,7 @@ const en: Messages = {
   'terminal.search.nextMatch': 'Next match (Enter)',
   'terminal.menu.copy': 'Copy',
   'terminal.menu.paste': 'Paste',
+  'terminal.menu.pasteSelection': 'Paste Selection',
   'terminal.menu.selectAll': 'Select All',
   'terminal.menu.splitHorizontal': 'Split Horizontal',
   'terminal.menu.splitVertical': 'Split Vertical',
@@ -1227,6 +1262,11 @@ const en: Messages = {
   'terminal.themeModal.fontWeight': 'Font Weight',
   'terminal.themeModal.livePreview': 'Live Preview',
   'terminal.themeModal.themeType': '{type} theme',
+  'terminal.hiddenTheme.title': 'Current hidden theme',
+  'terminal.hiddenTheme.desc': 'This theme is hidden from manual picks and will be replaced when you choose another theme.',
+  'topTabs.toggleTheme.systemExitTitle': 'System theme is active',
+  'topTabs.toggleTheme.systemExitMessage': 'Open Settings to choose a fixed Light or Dark theme.',
+  'topTabs.toggleTheme.openSettings': 'Open Settings',
 
   // Custom Themes
   'terminal.customTheme.section': 'Custom Themes',
@@ -1356,6 +1396,47 @@ const en: Messages = {
   'cloudSync.history.download': 'Download',
   'cloudSync.history.resolved': 'Resolved',
   'cloudSync.history.error': 'Error',
+  'cloudSync.localBackups.title': 'Local Backup History',
+  'cloudSync.localBackups.desc': 'Netcatty keeps local restore points before app version changes and before vault restores.',
+  'cloudSync.localBackups.retentionTitle': 'Backup Retention',
+  'cloudSync.localBackups.retentionDesc': 'Choose how many local backups Netcatty should keep.',
+  'cloudSync.localBackups.maxCount': 'Max backups',
+  'cloudSync.localBackups.maxSaved': 'Saved backup retention: {count}',
+  'cloudSync.localBackups.maxInvalid': 'Please enter a number between 1 and 100.',
+  'cloudSync.localBackups.empty': 'No local backups yet.',
+  'cloudSync.localBackups.reason.appVersionChange': 'Before app version change',
+  'cloudSync.localBackups.reason.beforeRestore': 'Before restore',
+  'cloudSync.localBackups.versionChange': '{from} -> {to}',
+  'cloudSync.localBackups.counts': '{hosts} hosts, {keys} keys, {snippets} snippets',
+  'cloudSync.localBackups.restore': 'Restore',
+  'cloudSync.localBackups.restoreSuccess': 'Local backup restored.',
+  'cloudSync.localBackups.restoreFailedTitle': 'Restore failed',
+  'cloudSync.localBackups.restoreMissing': 'Backup not found.',
+  'cloudSync.localBackups.protectiveBackupFailed': 'Safety backup could not be created, so the restore was aborted to protect your current data. Resolve the underlying issue (e.g. keychain access) and try again. Details: {message}',
+  'cloudSync.localBackups.restoreConfirmTitle': 'Restore this backup?',
+  'cloudSync.localBackups.restoreConfirmDesc': 'Your current hosts, keys, snippets and settings will be replaced with the contents of this backup. A protective snapshot of your current data is taken automatically first.',
+  'cloudSync.localBackups.restoreConfirmButton': 'Restore',
+  'cloudSync.localBackups.restoreConfirmCancel': 'Cancel',
+  'cloudSync.localBackups.unavailableTitle': 'Local backups unavailable',
+  'cloudSync.localBackups.unavailableDesc': 'This platform does not expose a secure keychain to Netcatty, so local backups cannot be written safely. Install Netcatty on a system with a supported keychain to enable the local backup history.',
+  'cloudSync.localBackups.lockedTitle': 'Master key required',
+  'cloudSync.localBackups.lockedDesc': 'Set up or unlock your master key before restoring a backup, so restored credentials remain encrypted.',
+  'cloudSync.revisionHistory.viewButton': 'History',
+  'cloudSync.revisionHistory.title': 'Vault Version History',
+  'cloudSync.revisionHistory.description': 'Browse and restore previous versions of your vault from the Gist revision history.',
+  'cloudSync.revisionHistory.empty': 'No revisions found.',
+  'cloudSync.revisionHistory.current': 'Current',
+  'cloudSync.revisionHistory.revision': 'Revision',
+  'cloudSync.revisionHistory.revisionPreview': 'Revision Contents',
+  'cloudSync.revisionHistory.device': 'Device',
+  'cloudSync.revisionHistory.hosts': 'Hosts',
+  'cloudSync.revisionHistory.keys': 'Keys',
+  'cloudSync.revisionHistory.snippets': 'Snippets',
+  'cloudSync.revisionHistory.identities': 'Identities',
+  'cloudSync.revisionHistory.restoreButton': 'Restore This Version',
+  'cloudSync.revisionHistory.restored': 'Vault restored from selected revision.',
+  'cloudSync.revisionHistory.revisionNotFound': 'Revision not found or does not contain vault data.',
+  'cloudSync.revisionHistory.decryptFailed': 'Cannot decrypt this revision. It may have been encrypted with a different master password.',
   'cloudSync.changeKey.title': 'Change Master Key',
   'cloudSync.changeKey.current': 'Current Master Key',
   'cloudSync.changeKey.new': 'New Master Key',
@@ -1643,10 +1724,7 @@ const en: Messages = {
   'keyboard.interactive.enterResponse': 'Enter response',
   'keyboard.interactive.submit': 'Submit',
   'keyboard.interactive.verifying': 'Verifying...',
-  'keyboard.interactive.fill': 'Fill',
-  'keyboard.interactive.fillSaved': 'Fill with saved password',
-  'keyboard.interactive.useSaved': 'Use saved',
-  'keyboard.interactive.useSavedPassword': 'Use saved password',
+  'keyboard.interactive.savePassword': 'Save password',
 
   // Passphrase Modal for encrypted SSH keys
   'passphrase.title': 'SSH Key Passphrase',
@@ -1697,12 +1775,16 @@ const en: Messages = {
   // AI Codex
   'ai.codex': 'Codex',
   'ai.codex.title': 'Codex CLI',
-  'ai.codex.description': 'Uses codex + codex-acp for ACP protocol streaming. Login with ChatGPT subscription here, or configure an OpenAI provider API key (passed as CODEX_API_KEY).',
+  'ai.codex.description': 'Uses codex + codex-acp for ACP protocol streaming. Login with ChatGPT here, or enable an OpenAI-compatible provider API key and custom endpoint in Settings.',
   'ai.codex.detecting': 'Detecting...',
   'ai.codex.notFound': 'Not found',
   'ai.codex.awaitingLogin': 'Awaiting login',
   'ai.codex.connectedChatGPT': 'Connected via ChatGPT',
   'ai.codex.connectedApiKey': 'Connected via API key',
+  'ai.codex.connectedCustomConfig': 'Connected via ~/.codex/config.toml',
+  'ai.codex.customConfigIncomplete': 'Custom config detected (env var missing)',
+  'ai.codex.customConfigHint': 'Using custom provider "{provider}" configured in ~/.codex/config.toml — no ChatGPT login needed.',
+  'ai.codex.customConfigMissingEnvKey': 'Warning: {envKey} is not set in your shell environment. Export it (or launch netcatty from a shell that has it) so Codex can authenticate.',
   'ai.codex.notConnected': 'Not connected',
   'ai.codex.statusUnknown': 'Status unknown',
   'ai.codex.path': 'Path:',
@@ -1713,7 +1795,6 @@ const en: Messages = {
   'ai.codex.logout': 'Logout',
   'ai.codex.connectChatGPT': 'Connect ChatGPT',
   'ai.codex.refreshStatus': 'Refresh Status',
-  'ai.codex.apiKeyHint': 'Enabled OpenAI provider API key detected. Codex ACP can also authenticate without ChatGPT login.',
 
   // AI Claude Code
   'ai.claude.title': 'Claude Code',
@@ -1741,6 +1822,22 @@ const en: Messages = {
   'ai.defaultAgent': 'Default Agent',
   'ai.defaultAgent.description': 'Agent to use when starting a new AI session',
   'ai.defaultAgent.catty': 'Catty (Built-in)',
+  'ai.toolAccess.title': 'Tool Access',
+  'ai.toolAccess.mode': 'Netcatty Access Mode',
+  'ai.toolAccess.description': 'Choose how external ACP agents access Netcatty sessions. MCP exposes the built-in server, while Skills + CLI points agents to the local Netcatty skill and CLI commands.',
+  'ai.toolAccess.mode.mcp': 'MCP',
+  'ai.toolAccess.mode.skills': 'Skills + CLI',
+  'ai.userSkills.title': 'User Skills',
+  'ai.userSkills.description': 'Open the Netcatty skills folder to add your own skill directories. Netcatty scans these skills automatically and injects only lightweight indexes unless a skill clearly matches the current request.',
+  'ai.userSkills.openFolder': 'Open Skills Folder',
+  'ai.userSkills.reload': 'Reload Skills',
+  'ai.userSkills.location': 'Location',
+  'ai.userSkills.loading': 'Scanning user skills...',
+  'ai.userSkills.summary': '{ready} ready, {warnings} warnings',
+  'ai.userSkills.empty': 'No user skills found yet. Open the folder to add skill directories with a SKILL.md file.',
+  'ai.userSkills.unavailable': 'User skills are unavailable in this environment.',
+  'ai.userSkills.status.ready': 'Ready',
+  'ai.userSkills.status.warning': 'Warning',
 
   // AI Chat
   'ai.chat.noProvider': 'No AI provider is configured. Go to **Settings → AI → Providers** to add and enable a provider.',
@@ -1795,6 +1892,7 @@ const en: Messages = {
   'ai.chat.menuFiles': 'Files',
   'ai.chat.menuImage': 'Image',
   'ai.chat.menuMentionHost': 'Mention Host',
+  'ai.chat.menuUserSkills': 'User Skills',
 
   // AI Error
   'ai.codex.bridgeError': 'Codex main-process handlers are not loaded yet. Fully restart Netcatty, or restart the Electron dev process, then try again.',
@@ -1817,7 +1915,7 @@ const en: Messages = {
   // AI Safety Settings
   'ai.safety.title': 'Safety',
   'ai.safety.permissionMode': 'Permission Mode',
-  'ai.safety.permissionMode.description': 'Controls how the AI interacts with your terminals. Observer mode blocks all write operations via MCP Server, enforced for both built-in and ACP agents. Confirm mode is advisory for ACP agents (they control their own tool approval flow).',
+  'ai.safety.permissionMode.description': 'Controls how the AI interacts with your terminals. Observer mode blocks all write operations through Netcatty, enforced for both built-in and ACP agents. Confirm mode is advisory for ACP agents (they control their own tool approval flow).',
   'ai.safety.permissionMode.observer': 'Observer - Read only, no actions',
   'ai.safety.permissionMode.confirm': 'Confirm - Ask before actions',
   'ai.safety.permissionMode.autonomous': 'Autonomous - Execute freely',
@@ -1827,7 +1925,7 @@ const en: Messages = {
   'ai.safety.maxIterations': 'Max Iterations',
   'ai.safety.maxIterations.description': 'Maximum number of AI tool-use loops to prevent runaway execution. ACP agents may have their own internal iteration limits that take precedence.',
   'ai.safety.blocklist': 'Command Blocklist',
-  'ai.safety.blocklist.description': 'Regex patterns to block dangerous commands. Applies to both built-in and ACP agents via MCP Server.',
+  'ai.safety.blocklist.description': 'Regex patterns to block dangerous commands. Applies to both built-in and ACP agents through Netcatty execution.',
   'ai.safety.blocklist.placeholder': 'Regex pattern...',
   'ai.safety.blocklist.reset': 'Reset to defaults',
   'ai.safety.blocklist.add': 'Add pattern',

application/i18n/locales/zh-CN.ts

@@ -181,9 +181,15 @@ const zhCN: Messages = {
   'settings.application.github.subtitle': '源代码',
   'settings.application.whatsNew': '更新内容',
   'settings.application.whatsNew.subtitle': '查看发布说明',
+  'settings.application.openExternal.failedTitle': '无法打开链接',
+  'settings.application.openExternal.failedBody': '系统浏览器和内置浏览器窗口都无法打开该链接。',
   'settings.vault.title': '主机库',
   'settings.vault.showRecentHosts': '显示最近连接的主机',
   'settings.vault.showRecentHostsDesc': '在主机列表顶部显示最近连接过的主机',
+  'settings.vault.showOnlyUngroupedHostsInRoot': '根目录只显示未分组主机',
+  'settings.vault.showOnlyUngroupedHostsInRootDesc': '开启后，主机库根目录的主机列表只显示没有分组的主机，已分组主机请从左侧分组进入查看。',
+  'settings.vault.showSftpTab': '显示 SFTP 标签页',
+  'settings.vault.showSftpTabDesc': '在顶部标签栏显示独立的 SFTP 视图。关闭后可改用会话内左侧的 SFTP 侧栏。',
 
   // Update notifications
   'update.available.title': '发现新版本',
@@ -220,9 +226,10 @@ const zhCN: Messages = {
   'settings.appearance.themeColor.light': '浅色主题',
   'settings.appearance.themeColor.dark': '深色主题',
   'settings.appearance.customCss': '自定义 CSS',
-  'settings.appearance.customCss.desc': '使用自定义 CSS 个性化界面，修改会立即生效。',
+  'settings.appearance.customCss.desc':
+    '使用自定义 CSS 个性化界面，修改会立即生效。主要 UI 区块都暴露了 [data-section="..."] 属性供你定位，比如：snippets-panel、host-details-panel、group-details-panel、serial-host-details-panel、ai-chat-panel、vault-sidebar、vault-main、vault-hosts-header、vault-host-list、vault-view、terminal-workspace、terminal-workspace-sidebar、top-tabs。',
   'settings.appearance.customCss.placeholder':
-    '/* 示例：*/\n.terminal { background: #1a1a2e !important; }\n:root { --radius: 0.25rem; }',
+    '/* 示例 — 由于 Tailwind 优先级较高，需要使用 !important */\n\n/* 放大代码片段侧边栏字号 */\n[data-section="snippets-panel"] {\n  font-size: 14px !important;\n}\n\n/* 自定义终端背景色 */\n.terminal { background: #1a1a2e !important; }\n\n/* 调整全局圆角 */\n:root { --radius: 0.25rem; }',
   'settings.appearance.language': '语言',
   'settings.appearance.language.desc': '选择界面语言',
   'settings.appearance.uiFont': '界面字体',
@@ -255,13 +262,30 @@ const zhCN: Messages = {
   'sync.toast.completedMessage': '同步完成',
   'sync.toast.errorTitle': '同步错误',
   'sync.autoSync.failedTitle': '同步失败',
+  'sync.autoSync.inspectFailedTitle': '同步已暂停',
+  'sync.autoSync.inspectFailedMessage': '无法访问云端以检查变更。数据改动或下次启动时会自动重试。',
   'sync.autoSync.syncedTitle': '已从云端同步',
   'sync.autoSync.syncedMessage': '你的数据已从云端更新。',
   'sync.autoSync.noProvider': '未连接云同步 provider。请打开 设置 → Sync & Cloud 进行连接。',
   'sync.autoSync.alreadySyncing': '同步正在进行中。',
+  'sync.autoSync.restoreInProgress': '另一个窗口中的本地备份恢复正在进行中，请等待其完成。',
+  'sync.autoSync.interruptedApplyTitle': '同步已暂停 — 上次恢复未完成',
+  'sync.autoSync.interruptedApplyMessage': '上次本地恢复过程未正常结束，本地数据可能处于半应用状态。请打开「设置 → Sync & Cloud → 恢复」，从保护性备份中恢复后再让自动同步继续。',
   'sync.autoSync.vaultLocked': 'Vault 处于锁定状态。请打开 设置 → Sync & Cloud 解锁。',
   'sync.autoSync.conflictDetected': '检测到同步冲突。请打开 设置 → Sync & Cloud 处理。',
   'sync.autoSync.syncFailed': '同步失败',
+  'sync.autoSync.restoredTitle': '已恢复',
+  'sync.autoSync.restoredMessage': '已从云端恢复主机库数据。',
+  'sync.autoSync.keptLocalTitle': '已保留本地数据',
+  'sync.autoSync.keptLocalMessage': '保留了空的本地主机库，未应用云端数据。',
+  'sync.autoSync.emptyVaultConflict.title': '检测到空主机库',
+  'sync.autoSync.emptyVaultConflict.description': '本地主机库为空，但云端有数据。这通常发生在应用更新或存储重置之后。请选择如何处理：',
+  'sync.autoSync.emptyVaultConflict.cloudLabel': '云端',
+  'sync.autoSync.emptyVaultConflict.restore': '从云端恢复',
+  'sync.autoSync.emptyVaultConflict.restoreDesc': '推荐 — 从云端备份恢复主机、密钥和代码片段',
+  'sync.autoSync.emptyVaultConflict.keepEmpty': '保持为空',
+  'sync.autoSync.emptyVaultConflict.keepEmptyDesc': '从头开始，使用空的主机库',
+  'sync.autoSync.emptyVaultConflict.cloudSummary': '{hosts} 台主机，{keys} 个密钥，{snippets} 个代码片段',
   'sync.credentialsUnavailable': '当前设备无法解密部分已保存凭据。请先在本地重新输入凭据后再同步。',
   'time.never': '从未',
   'time.justNow': '刚刚',
@@ -349,6 +373,7 @@ const zhCN: Messages = {
   'vault.hosts.deselectAll': '取消全选',
   'vault.hosts.deleteSelected': '删除 ({count})',
   'vault.hosts.deleteMultiple.success': '已删除 {count} 个主机',
+  'vault.hosts.moveToGroup.success': '已将 {host} 移动到 {group}',
   'vault.hosts.empty.title': '设置你的主机',
   'vault.hosts.empty.desc': '保存主机以快速连接到你的服务器、虚拟机和容器。',
 
@@ -626,6 +651,14 @@ const zhCN: Messages = {
   'hostDetails.distro.option.almalinux': 'AlmaLinux',
   'hostDetails.distro.option.oracle': 'Oracle Linux',
   'hostDetails.distro.option.kali': 'Kali Linux',
+  'hostDetails.distro.option.cisco': '思科',
+  'hostDetails.distro.option.juniper': '瞻博网络',
+  'hostDetails.distro.option.huawei': '华为',
+  'hostDetails.distro.option.hpe': '慧与 / H3C',
+  'hostDetails.distro.option.mikrotik': 'MikroTik',
+  'hostDetails.distro.option.fortinet': '飞塔',
+  'hostDetails.distro.option.paloalto': 'Palo Alto Networks',
+  'hostDetails.distro.option.zyxel': '合勤',
   'hostDetails.section.mosh': 'Mosh',
   'hostDetails.username.placeholder': '用户名',
   'hostDetails.password.placeholder': '密码',
@@ -741,7 +774,7 @@ const zhCN: Messages = {
   'terminal.toolbar.library': '库',
   'terminal.toolbar.noSnippets': '暂无代码片段',
   'terminal.toolbar.terminalSettings': '终端设置',
-  'terminal.toolbar.searchTerminal': '搜索终端 (Ctrl+F)',
+  'terminal.toolbar.searchTerminal': '搜索终端',
   'terminal.toolbar.search': '搜索',
   'terminal.toolbar.broadcast': '广播',
   'terminal.toolbar.broadcastEnable': '启用广播模式',
@@ -797,6 +830,7 @@ const zhCN: Messages = {
   'terminal.search.nextMatch': '下一个匹配 (Enter)',
   'terminal.menu.copy': '复制',
   'terminal.menu.paste': '粘贴',
+  'terminal.menu.pasteSelection': '粘贴选中文本',
   'terminal.menu.selectAll': '全选',
   'terminal.menu.splitHorizontal': '水平分屏',
   'terminal.menu.splitVertical': '垂直分屏',
@@ -842,6 +876,11 @@ const zhCN: Messages = {
   'terminal.themeModal.fontWeight': '字体粗细',
   'terminal.themeModal.livePreview': '实时预览',
   'terminal.themeModal.themeType': '{type} 主题',
+  'terminal.hiddenTheme.title': '当前隐藏主题',
+  'terminal.hiddenTheme.desc': '这个主题已从手动选择列表中隐藏；当你选择其他可见主题后，它会被替换。',
+  'topTabs.toggleTheme.systemExitTitle': '当前正在跟随系统主题',
+  'topTabs.toggleTheme.systemExitMessage': '请到设置里选择固定的浅色或深色主题。',
+  'topTabs.toggleTheme.openSettings': '打开设置',
 
   // Custom Themes
   'terminal.customTheme.section': '自定义主题',
@@ -970,6 +1009,47 @@ const zhCN: Messages = {
   'cloudSync.history.download': '下载',
   'cloudSync.history.resolved': '已解决',
   'cloudSync.history.error': '错误',
+  'cloudSync.localBackups.title': '本地备份历史',
+  'cloudSync.localBackups.desc': 'Netcatty 会在版本变化前，以及恢复主机库前，自动留下一份本地恢复点。',
+  'cloudSync.localBackups.retentionTitle': '备份保留数量',
+  'cloudSync.localBackups.retentionDesc': '设置 Netcatty 最多保留多少份本地备份。',
+  'cloudSync.localBackups.maxCount': '最多保留',
+  'cloudSync.localBackups.maxSaved': '已保存保留数量：{count}',
+  'cloudSync.localBackups.maxInvalid': '请输入 1 到 100 之间的数字。',
+  'cloudSync.localBackups.empty': '还没有本地备份。',
+  'cloudSync.localBackups.reason.appVersionChange': '版本变化前',
+  'cloudSync.localBackups.reason.beforeRestore': '恢复前',
+  'cloudSync.localBackups.versionChange': '{from} -> {to}',
+  'cloudSync.localBackups.counts': '{hosts} 台主机，{keys} 个密钥，{snippets} 个代码片段',
+  'cloudSync.localBackups.restore': '恢复',
+  'cloudSync.localBackups.restoreSuccess': '已恢复本地备份。',
+  'cloudSync.localBackups.restoreFailedTitle': '恢复失败',
+  'cloudSync.localBackups.restoreMissing': '找不到这份备份。',
+  'cloudSync.localBackups.protectiveBackupFailed': '无法创建保护性备份，已中止恢复以避免覆盖当前数据。请先解决底层问题（例如钥匙串访问）后重试。详情：{message}',
+  'cloudSync.localBackups.restoreConfirmTitle': '确认恢复此备份？',
+  'cloudSync.localBackups.restoreConfirmDesc': '当前的主机、密钥、代码片段与设置将被替换为此备份中的内容。系统会先自动创建一个保护性快照，便于撤销。',
+  'cloudSync.localBackups.restoreConfirmButton': '恢复',
+  'cloudSync.localBackups.restoreConfirmCancel': '取消',
+  'cloudSync.localBackups.unavailableTitle': '无法使用本地备份',
+  'cloudSync.localBackups.unavailableDesc': '当前平台未提供受支持的安全密钥库，Netcatty 无法安全地写入本地备份。请在支持系统钥匙串的环境中运行，或改用云同步保留恢复点。',
+  'cloudSync.localBackups.lockedTitle': '需要主密钥',
+  'cloudSync.localBackups.lockedDesc': '请先配置或解锁主密钥再恢复备份，以确保恢复后的凭据仍保持加密。',
+  'cloudSync.revisionHistory.viewButton': '历史版本',
+  'cloudSync.revisionHistory.title': '主机库版本历史',
+  'cloudSync.revisionHistory.description': '浏览并恢复 Gist 修订历史中的旧版主机库数据。',
+  'cloudSync.revisionHistory.empty': '未找到修订记录。',
+  'cloudSync.revisionHistory.current': '当前版本',
+  'cloudSync.revisionHistory.revision': '修订',
+  'cloudSync.revisionHistory.revisionPreview': '修订内容',
+  'cloudSync.revisionHistory.device': '设备',
+  'cloudSync.revisionHistory.hosts': '主机',
+  'cloudSync.revisionHistory.keys': '密钥',
+  'cloudSync.revisionHistory.snippets': '代码片段',
+  'cloudSync.revisionHistory.identities': '身份',
+  'cloudSync.revisionHistory.restoreButton': '恢复此版本',
+  'cloudSync.revisionHistory.restored': '已从选中的修订恢复主机库数据。',
+  'cloudSync.revisionHistory.revisionNotFound': '修订未找到或不包含主机库数据。',
+  'cloudSync.revisionHistory.decryptFailed': '无法解密此修订。可能是使用了不同的主密钥加密的。',
   'cloudSync.changeKey.title': '更改主密钥',
   'cloudSync.changeKey.current': '当前主密钥',
   'cloudSync.changeKey.new': '新的主密钥',
@@ -1239,6 +1319,8 @@ const zhCN: Messages = {
   'settings.terminal.themeModal.darkThemes': '深色主题',
   'settings.terminal.themeModal.lightThemes': '浅色主题',
   'settings.terminal.theme.selectButton': '选择主题',
+  'settings.terminal.theme.followApp': '跟随应用主题',
+  'settings.terminal.theme.followApp.desc': '终端背景色自动匹配当前应用主题，保持视觉一致性。',
   'settings.terminal.section.font': '字体',
   'settings.terminal.section.cursor': '光标',
   'settings.terminal.section.keyboard': '键盘',
@@ -1650,10 +1732,7 @@ const zhCN: Messages = {
   'keyboard.interactive.enterResponse': '输入响应',
   'keyboard.interactive.submit': '提交',
   'keyboard.interactive.verifying': '验证中...',
-  'keyboard.interactive.fill': '填入',
-  'keyboard.interactive.fillSaved': '填入已保存的密码',
-  'keyboard.interactive.useSaved': '使用已保存',
-  'keyboard.interactive.useSavedPassword': '使用已保存的密码',
+  'keyboard.interactive.savePassword': '保存密码',
 
   // Passphrase Modal for encrypted SSH keys
   'passphrase.title': 'SSH 密钥密码',
@@ -1704,12 +1783,16 @@ const zhCN: Messages = {
   // AI Codex
   'ai.codex': 'Codex',
   'ai.codex.title': 'Codex CLI',
-  'ai.codex.description': '使用 codex + codex-acp 进行 ACP 协议流式传输。在此通过 ChatGPT 订阅登录，或配置 OpenAI 提供商的 API Key（将作为 CODEX_API_KEY 传递）。',
+  'ai.codex.description': '使用 codex + codex-acp 进行 ACP 协议流式传输。可以在这里连接 ChatGPT，也可以在设置里启用兼容 OpenAI 的 API Key 和自定义接口地址。',
   'ai.codex.detecting': '检测中...',
   'ai.codex.notFound': '未找到',
   'ai.codex.awaitingLogin': '等待登录',
   'ai.codex.connectedChatGPT': '已通过 ChatGPT 连接',
   'ai.codex.connectedApiKey': '已通过 API Key 连接',
+  'ai.codex.connectedCustomConfig': '使用 ~/.codex/config.toml 自定义 provider',
+  'ai.codex.customConfigIncomplete': '检测到自定义配置（缺少环境变量）',
+  'ai.codex.customConfigHint': '使用 ~/.codex/config.toml 中配置的自定义 provider "{provider}"，无需 ChatGPT 登录。',
+  'ai.codex.customConfigMissingEnvKey': '警告：环境变量 {envKey} 未在当前 shell 中设置。请 export 它（或从包含该变量的 shell 启动 netcatty），否则 Codex 无法鉴权。',
   'ai.codex.notConnected': '未连接',
   'ai.codex.statusUnknown': '状态未知',
   'ai.codex.path': '路径：',
@@ -1720,7 +1803,6 @@ const zhCN: Messages = {
   'ai.codex.logout': '退出登录',
   'ai.codex.connectChatGPT': '连接 ChatGPT',
   'ai.codex.refreshStatus': '刷新状态',
-  'ai.codex.apiKeyHint': '检测到已启用的 OpenAI 提供商 API Key。Codex ACP 也可以无需 ChatGPT 登录进行认证。',
 
   // AI Claude Code
   'ai.claude.title': 'Claude Code',
@@ -1748,6 +1830,22 @@ const zhCN: Messages = {
   'ai.defaultAgent': '默认 Agent',
   'ai.defaultAgent.description': '创建新 AI 会话时使用的 Agent',
   'ai.defaultAgent.catty': 'Catty（内置）',
+  'ai.toolAccess.title': '工具接入',
+  'ai.toolAccess.mode': 'Netcatty 接入模式',
+  'ai.toolAccess.description': '选择外部 ACP Agent 访问 Netcatty 会话的方式。MCP 会暴露内置服务器，Skills + CLI 会引导 Agent 读取本地 Skill 并调用 Netcatty CLI。',
+  'ai.toolAccess.mode.mcp': 'MCP',
+  'ai.toolAccess.mode.skills': 'Skills + CLI',
+  'ai.userSkills.title': '用户 Skills',
+  'ai.userSkills.description': '打开 Netcatty 的 Skills 文件夹以添加你自己的技能目录。Netcatty 会自动扫描这些 skills，默认只注入轻量索引，只有在请求明显命中某个 skill 时才展开正文。',
+  'ai.userSkills.openFolder': '打开 Skills 文件夹',
+  'ai.userSkills.reload': '重新加载 Skills',
+  'ai.userSkills.location': '位置',
+  'ai.userSkills.loading': '正在扫描用户 skills...',
+  'ai.userSkills.summary': '已就绪 {ready} 个，警告 {warnings} 个',
+  'ai.userSkills.empty': '暂未发现用户 skills。打开文件夹后可添加包含 SKILL.md 的技能目录。',
+  'ai.userSkills.unavailable': '当前环境不支持用户 skills。',
+  'ai.userSkills.status.ready': '正常',
+  'ai.userSkills.status.warning': '警告',
 
   // AI Chat
   'ai.chat.noProvider': '尚未配置 AI 提供商。请前往 **设置 → AI → 提供商** 添加并启用一个提供商。',
@@ -1802,6 +1900,7 @@ const zhCN: Messages = {
   'ai.chat.menuFiles': '文件',
   'ai.chat.menuImage': '图片',
   'ai.chat.menuMentionHost': '提及主机',
+  'ai.chat.menuUserSkills': '用户 Skills',
 
   // AI Error
   'ai.codex.bridgeError': 'Codex 主进程处理器尚未加载。请完全重启 Netcatty 或重启 Electron 开发进程，然后重试。',
@@ -1824,7 +1923,7 @@ const zhCN: Messages = {
   // AI Safety Settings
   'ai.safety.title': '安全',
   'ai.safety.permissionMode': '权限模式',
-  'ai.safety.permissionMode.description': '控制 AI 与终端的交互方式。观察者模式通过 MCP Server 阻止所有写操作，对内置和 ACP Agent 均生效。确认模式对 ACP Agent 仅为建议性（ACP Agent 有自己的工具审批流程）。',
+  'ai.safety.permissionMode.description': '控制 AI 与终端的交互方式。观察者模式会通过 Netcatty 阻止所有写操作，对内置和 ACP Agent 均生效。确认模式对 ACP Agent 仅为建议性（ACP Agent 有自己的工具审批流程）。',
   'ai.safety.permissionMode.observer': '观察者 - 只读，禁止操作',
   'ai.safety.permissionMode.confirm': '确认 - 操作前询问',
   'ai.safety.permissionMode.autonomous': '自主 - 自由执行',
@@ -1834,7 +1933,7 @@ const zhCN: Messages = {
   'ai.safety.maxIterations': '最大迭代次数',
   'ai.safety.maxIterations.description': '防止 AI 失控执行的最大工具调用循环次数。ACP Agent 可能有自己的内部迭代限制，以其为准。',
   'ai.safety.blocklist': '命令黑名单',
-  'ai.safety.blocklist.description': '用于拦截危险命令的正则表达式。通过 MCP Server 对内置和 ACP Agent 均生效。',
+  'ai.safety.blocklist.description': '用于拦截危险命令的正则表达式。通过 Netcatty 执行层对内置和 ACP Agent 均生效。',
   'ai.safety.blocklist.placeholder': '正则表达式...',
   'ai.safety.blocklist.reset': '恢复默认',
   'ai.safety.blocklist.add': '添加规则',

application/localVaultBackups.ts

@@ -0,0 +1,467 @@
+import type { SyncPayload } from '../domain/sync';
+import {
+  STORAGE_KEY_LOCAL_VAULT_BACKUP_LAST_APP_VERSION,
+  STORAGE_KEY_LOCAL_VAULT_BACKUP_MAX_COUNT,
+  STORAGE_KEY_VAULT_APPLY_IN_PROGRESS,
+  STORAGE_KEY_VAULT_RESTORE_IN_PROGRESS_UNTIL,
+} from '../infrastructure/config/storageKeys';
+import { localStorageAdapter } from '../infrastructure/persistence/localStorageAdapter';
+import { netcattyBridge } from '../infrastructure/services/netcattyBridge';
+import { hasMeaningfulSyncData } from './syncPayload';
+
+export type LocalVaultBackupReason = 'app_version_change' | 'before_restore';
+
+export interface LocalVaultBackupPreview {
+  id: string;
+  createdAt: number;
+  reason: LocalVaultBackupReason;
+  sourceAppVersion?: string;
+  targetAppVersion?: string;
+  fingerprint: string;
+  preview: {
+    hostCount: number;
+    keyCount: number;
+    snippetCount: number;
+    identityCount: number;
+    portForwardingRuleCount: number;
+  };
+}
+
+export interface LocalVaultBackupDetails {
+  backup: LocalVaultBackupPreview;
+  payload: SyncPayload;
+}
+
+export const DEFAULT_LOCAL_VAULT_BACKUP_MAX_COUNT = 20;
+export const MIN_LOCAL_VAULT_BACKUP_MAX_COUNT = 1;
+export const MAX_LOCAL_VAULT_BACKUP_MAX_COUNT = 100;
+
+export const sanitizeLocalVaultBackupMaxCount = (value: number): number => {
+  if (!Number.isFinite(value)) return DEFAULT_LOCAL_VAULT_BACKUP_MAX_COUNT;
+  return Math.max(
+    MIN_LOCAL_VAULT_BACKUP_MAX_COUNT,
+    Math.min(MAX_LOCAL_VAULT_BACKUP_MAX_COUNT, Math.round(value)),
+  );
+};
+
+export const getLocalVaultBackupMaxCount = (): number => {
+  const stored = localStorageAdapter.readNumber(STORAGE_KEY_LOCAL_VAULT_BACKUP_MAX_COUNT);
+  return sanitizeLocalVaultBackupMaxCount(
+    stored ?? DEFAULT_LOCAL_VAULT_BACKUP_MAX_COUNT,
+  );
+};
+
+export const setLocalVaultBackupMaxCount = (value: number): number => {
+  const sanitized = sanitizeLocalVaultBackupMaxCount(value);
+  localStorageAdapter.writeNumber(STORAGE_KEY_LOCAL_VAULT_BACKUP_MAX_COUNT, sanitized);
+  return sanitized;
+};
+
+export async function trimLocalVaultBackups(maxCount = getLocalVaultBackupMaxCount()): Promise<void> {
+  const bridge = netcattyBridge.get();
+  await bridge?.trimVaultBackups?.({ maxCount });
+}
+
+export async function getLocalVaultBackupCapabilities(): Promise<{
+  encryptionAvailable: boolean;
+}> {
+  const bridge = netcattyBridge.get();
+  const caps = await bridge?.getVaultBackupCapabilities?.();
+  // Conservatively treat a missing bridge (non-Electron environments, early
+  // boot) as unavailable so callers fall back to the locked-down UI path
+  // instead of assuming capabilities they can't verify.
+  return { encryptionAvailable: Boolean(caps?.encryptionAvailable) };
+}
+
+export async function listLocalVaultBackups(): Promise<LocalVaultBackupPreview[]> {
+  const bridge = netcattyBridge.get();
+  const entries = await bridge?.listVaultBackups?.();
+  return Array.isArray(entries) ? entries : [];
+}
+
+export async function readLocalVaultBackup(id: string): Promise<LocalVaultBackupDetails | null> {
+  const bridge = netcattyBridge.get();
+  if (!bridge?.readVaultBackup) return null;
+  return bridge.readVaultBackup({ id });
+}
+
+export async function openLocalVaultBackupDir(): Promise<void> {
+  const bridge = netcattyBridge.get();
+  await bridge?.openVaultBackupDir?.();
+}
+
+export async function createLocalVaultBackup(
+  payload: SyncPayload,
+  options: {
+    reason: LocalVaultBackupReason;
+    sourceAppVersion?: string;
+    targetAppVersion?: string;
+    maxCount?: number;
+  },
+): Promise<LocalVaultBackupPreview | null> {
+  // Intentional: an empty-vault backup has nothing to restore from, so we
+  // early-return instead of writing a zero-entry record. Callers that rely
+  // on a backup (protective-before-restore, version-change on first run)
+  // must treat `null` as "no safety net this time" and continue — blocking
+  // the user's flow on a missing backup would be worse than allowing the
+  // apply to proceed without one.
+  if (!hasMeaningfulSyncData(payload)) {
+    return null;
+  }
+
+  const bridge = netcattyBridge.get();
+  if (!bridge?.createVaultBackup) {
+    return null;
+  }
+
+  try {
+    const result = await bridge.createVaultBackup({
+      payload,
+      reason: options.reason,
+      sourceAppVersion: options.sourceAppVersion,
+      targetAppVersion: options.targetAppVersion,
+      maxCount: options.maxCount ?? getLocalVaultBackupMaxCount(),
+    });
+    return result?.backup ?? null;
+  } catch (error) {
+    // The main-process bridge refuses to write backups when safeStorage is
+    // unavailable (VAULT_BACKUP_ENCRYPTION_UNAVAILABLE) because SyncPayload
+    // carries plaintext credentials that must never touch disk unencrypted.
+    // Callers (startup version-change, protective-before-restore) intentionally
+    // continue without a backup rather than blocking the user's flow, so we
+    // log and return null here.
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn('[localVaultBackups] Backup skipped:', message);
+    return null;
+  }
+}
+
+/**
+ * Thrown when a caller requires a protective backup and the backup
+ * couldn't be written — safeStorage unavailable, bridge missing,
+ * main-process rejection, disk error.
+ *
+ * Callers should surface this as a user-visible abort rather than
+ * proceeding with the destructive apply. Separate from "nothing to
+ * back up" (empty vault) which is returned as `null`.
+ */
+export class ProtectiveBackupUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ProtectiveBackupUnavailableError';
+  }
+}
+
+/**
+ * Create a protective local backup before a destructive apply (restore
+ * from backup list, restore from Gist revision, cloud download applied
+ * over meaningful local state).
+ *
+ * Returns `null` when there is nothing meaningful to back up — in that
+ * case the caller can safely proceed with the apply, because there is
+ * no local data to lose.
+ *
+ * Throws `ProtectiveBackupUnavailableError` when pre-apply state IS
+ * meaningful but the backup attempt failed. Callers MUST abort the
+ * destructive apply in that case and surface the error to the user,
+ * otherwise we regress the exact safety contract the backup system
+ * was added to enforce (the `console.error`-and-proceed pattern that
+ * previously swallowed safeStorage/keychain failures and continued).
+ */
+export async function createRequiredProtectiveLocalVaultBackup(
+  payload: SyncPayload,
+): Promise<LocalVaultBackupPreview | null> {
+  if (!hasMeaningfulSyncData(payload)) {
+    // Nothing to protect — an empty-vault backup would produce a
+    // useless record, not a safety net.
+    return null;
+  }
+
+  const bridge = netcattyBridge.get();
+  if (!bridge?.createVaultBackup) {
+    throw new ProtectiveBackupUnavailableError(
+      'Vault backup bridge is not available in this environment.',
+    );
+  }
+
+  try {
+    const result = await bridge.createVaultBackup({
+      payload,
+      reason: 'before_restore',
+      maxCount: getLocalVaultBackupMaxCount(),
+    });
+    return result?.backup ?? null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ProtectiveBackupUnavailableError(message);
+  }
+}
+
+/**
+ * How long each heartbeat extends the cross-window restore barrier.
+ * Short enough that an abandoned lock (crashed window, hung task)
+ * clears itself quickly without user intervention. The heartbeat
+ * interval below refreshes the deadline as long as the caller's task
+ * is still running, so large vaults or slow keychain unlocks cannot
+ * expose a mid-apply window to concurrent auto-sync even when the
+ * total apply time exceeds this value.
+ */
+const RESTORE_BARRIER_HOLD_MS = 60_000;
+
+/**
+ * How often the heartbeat refreshes the barrier. Picked to ensure at
+ * least two refreshes land before the current deadline would expire,
+ * so a single missed tick (event-loop stall, GC pause) cannot drop
+ * the barrier prematurely.
+ */
+const RESTORE_BARRIER_HEARTBEAT_MS = Math.max(1_000, Math.floor(RESTORE_BARRIER_HOLD_MS / 3));
+
+/**
+ * Run `task` while holding a cross-window "restore in progress" barrier.
+ *
+ * The barrier is a localStorage key readable by every window of the same
+ * origin. useAutoSync reads it on each auto-sync and on each data-change
+ * debounce tick, refusing to push while the deadline is still in the
+ * future. We write a time-bounded deadline (rather than a boolean) so a
+ * crashed window can never leave sync permanently wedged.
+ *
+ * While the task runs, a heartbeat timer re-writes the deadline so a
+ * slow apply (large vault, slow keychain) keeps the barrier held rather
+ * than exposing a post-deadline window to concurrent auto-sync. The
+ * heartbeat is cleared and the barrier is released in a finally block
+ * so success, throw, and unexpected early-return all converge on the
+ * same cleanup.
+ */
+export async function withRestoreBarrier<T>(
+  task: () => Promise<T>,
+  holdMs: number = RESTORE_BARRIER_HOLD_MS,
+): Promise<T> {
+  const writeDeadline = () => {
+    try {
+      localStorageAdapter.writeNumber(
+        STORAGE_KEY_VAULT_RESTORE_IN_PROGRESS_UNTIL,
+        Date.now() + holdMs,
+      );
+    } catch (error) {
+      // If we can't write the barrier we still proceed — the UI-side
+      // `isSyncBusy` guard and same-window debounce cancellation are a
+      // secondary defense. Better to complete the restore than refuse on
+      // a broken localStorage.
+      console.warn('[localVaultBackups] Failed to set restore barrier:', error);
+    }
+  };
+
+  writeDeadline();
+  const heartbeat = setInterval(
+    writeDeadline,
+    Math.max(1_000, Math.min(holdMs / 3, RESTORE_BARRIER_HEARTBEAT_MS)),
+  );
+
+  try {
+    return await task();
+  } finally {
+    clearInterval(heartbeat);
+    try {
+      localStorageAdapter.writeNumber(STORAGE_KEY_VAULT_RESTORE_IN_PROGRESS_UNTIL, 0);
+    } catch {
+      /* ignore — the deadline will expire naturally */
+    }
+  }
+}
+
+/**
+ * Shape of the apply-in-progress sentinel record. Persisted as JSON in
+ * `STORAGE_KEY_VAULT_APPLY_IN_PROGRESS` so the next session can
+ * distinguish "the last apply completed cleanly" from "the last apply
+ * crashed mid-way and the local vault is a partial mix of states."
+ */
+export interface VaultApplyInProgressRecord {
+  startedAt: number;
+  protectiveBackupId: string | null;
+}
+
+/**
+ * Returns the persisted apply-in-progress record if a previous apply
+ * was interrupted before clearing it. Callers (notably auto-sync) use
+ * this to refuse to push a partial-apply local state over an intact
+ * cloud copy. See `applyProtectedSyncPayload` for the write side.
+ *
+ * `null` here means "no interrupted apply detected" — either nothing
+ * was ever applied, or the last apply finished cleanly.
+ */
+export function readInterruptedVaultApply(): VaultApplyInProgressRecord | null {
+  try {
+    const raw = localStorageAdapter.readString(STORAGE_KEY_VAULT_APPLY_IN_PROGRESS);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    const startedAt = typeof parsed.startedAt === 'number' ? parsed.startedAt : 0;
+    const protectiveBackupId =
+      typeof parsed.protectiveBackupId === 'string' ? parsed.protectiveBackupId : null;
+    if (!startedAt) return null;
+    return { startedAt, protectiveBackupId };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clears the apply-in-progress sentinel. The normal completion path
+ * inside `applyProtectedSyncPayload` clears it automatically; this
+ * export exists so the user's explicit recovery action ("I've restored
+ * from a backup, resume sync") can acknowledge the interrupted state
+ * from the UI without re-running an apply.
+ */
+export function clearInterruptedVaultApply(): void {
+  try {
+    localStorageAdapter.remove(STORAGE_KEY_VAULT_APPLY_IN_PROGRESS);
+  } catch {
+    /* ignore — next clean apply will overwrite */
+  }
+}
+
+function writeApplyInProgressSentinel(record: VaultApplyInProgressRecord): void {
+  try {
+    localStorageAdapter.writeString(
+      STORAGE_KEY_VAULT_APPLY_IN_PROGRESS,
+      JSON.stringify(record),
+    );
+  } catch (error) {
+    // Sentinel write is best-effort: a failure here means a later crash
+    // won't be detected, but does NOT compromise the apply itself.
+    // Log so a systematic storage outage is diagnosable.
+    console.warn('[localVaultBackups] Failed to set apply-in-progress sentinel:', error);
+  }
+}
+
+/**
+ * Shared "apply a remote-sourced payload safely" helper.
+ *
+ * Holds the cross-window restore barrier, snapshots the pre-apply vault
+ * into a protective backup, persists an apply-in-progress sentinel, and
+ * only then runs the supplied `applyPayload` callback. Every destructive
+ * apply path (startup merge, conflict resolution, empty-vault restore,
+ * manual Gist-revision restore) must go through this so the protections
+ * can't drift out of sync between the main window and the settings
+ * window.
+ *
+ * The sentinel closes the partial-apply-then-crash window: `applyPayload`
+ * writes to several localStorage keys non-atomically (hosts, keys, port-
+ * forwarding rules, settings). A crash mid-sequence leaves the vault in
+ * a state that is neither pre-apply nor post-apply, and the next
+ * auto-sync would otherwise push that partial state over an intact cloud
+ * copy. The sentinel flags "local may be inconsistent" for the next
+ * session; `readInterruptedVaultApply` exposes that to callers that
+ * enforce "don't auto-push a half-applied vault."
+ *
+ * `buildPreApplyPayload` is invoked *before* the apply to snapshot the
+ * current vault. Callers pass their own React-closure builder (hosts,
+ * keys, port-forwarding rules) because the caller owns that state.
+ *
+ * `translateProtectiveBackupFailure` converts the
+ * `ProtectiveBackupUnavailableError` into a user-visible message in the
+ * caller's locale. It runs only on the thrown-and-caught path.
+ */
+export function applyProtectedSyncPayload(options: {
+  buildPreApplyPayload: () => SyncPayload;
+  applyPayload: () => void | Promise<void>;
+  translateProtectiveBackupFailure: (message: string) => string;
+}): Promise<void> {
+  const { buildPreApplyPayload, applyPayload, translateProtectiveBackupFailure } = options;
+  return withRestoreBarrier(async () => {
+    const pre = buildPreApplyPayload();
+    let protectiveBackupId: string | null = null;
+    try {
+      const backup = await createRequiredProtectiveLocalVaultBackup(pre);
+      protectiveBackupId = backup?.id ?? null;
+    } catch (error) {
+      // Destructive apply without a working safety net is exactly the
+      // overwrite-without-recovery regression this module was added to
+      // prevent. Surface the failure to the caller; every call site
+      // currently aborts the apply and shows a user-visible error.
+      if (error instanceof ProtectiveBackupUnavailableError) {
+        throw new Error(translateProtectiveBackupFailure(error.message));
+      }
+      throw error;
+    }
+
+    // Mark the apply as in-progress. If the renderer crashes between
+    // the first localStorage write inside `applyPayload` and the
+    // successful completion below, the next session will observe this
+    // sentinel and refuse to auto-sync the partial state.
+    writeApplyInProgressSentinel({
+      startedAt: Date.now(),
+      protectiveBackupId,
+    });
+
+    // Only clear the sentinel on successful completion. A throw from
+    // `applyPayload` deliberately leaves the sentinel set: the partial
+    // write is still on disk, and the next session must observe the
+    // flag so auto-sync refuses to push the half-applied state.
+    await applyPayload();
+    clearInterruptedVaultApply();
+  });
+}
+
+export async function ensureVersionChangeBackup(
+  payload: SyncPayload,
+  currentAppVersion: string | null | undefined,
+): Promise<{ created: boolean; backup: LocalVaultBackupPreview | null }> {
+  const normalizedVersion = currentAppVersion?.trim() || '';
+  if (!normalizedVersion) {
+    return { created: false, backup: null };
+  }
+
+  const previousVersion =
+    localStorageAdapter.readString(STORAGE_KEY_LOCAL_VAULT_BACKUP_LAST_APP_VERSION)?.trim() || '';
+
+  if (!previousVersion) {
+    localStorageAdapter.writeString(STORAGE_KEY_LOCAL_VAULT_BACKUP_LAST_APP_VERSION, normalizedVersion);
+    return { created: false, backup: null };
+  }
+
+  if (previousVersion === normalizedVersion) {
+    return { created: false, backup: null };
+  }
+
+  let backup: LocalVaultBackupPreview | null = null;
+  const payloadIsMeaningful = hasMeaningfulSyncData(payload);
+  if (payloadIsMeaningful) {
+    backup = await createLocalVaultBackup(payload, {
+      reason: 'app_version_change',
+      sourceAppVersion: previousVersion,
+      targetAppVersion: normalizedVersion,
+    });
+  }
+
+  // Only advance the stored version stamp when we actually wrote a
+  // backup. Two failure modes we must NOT collapse into "advance":
+  //
+  //   1. Meaningful payload + backup failed (transient keychain lock,
+  //      disk error) — leaving the stamp unchanged means the next
+  //      launch retries, instead of turning a transient error into a
+  //      permanent "the version-change backup never happened" hole.
+  //
+  //   2. Non-meaningful payload at the moment we checked — on startup
+  //      the async vault rehydrate may not have finished yet, so
+  //      `hasMeaningfulSyncData` can return false transiently even
+  //      though the user has real data. Advancing in that window would
+  //      burn the one-shot upgrade opportunity; holding keeps the
+  //      retry available on the next launch when rehydrate has
+  //      completed (or when the user genuinely starts from empty and
+  //      the next migration-boundary arrives).
+  //
+  // Trade-off: a user who truly starts empty and never adds data will
+  // hit this branch on every launch until they do. That's cheap (a
+  // single meaningful-data check) and strictly safer than silently
+  // skipping the first real upgrade backup.
+  const shouldAdvanceVersion = payloadIsMeaningful && backup !== null;
+  if (shouldAdvanceVersion) {
+    localStorageAdapter.writeString(STORAGE_KEY_LOCAL_VAULT_BACKUP_LAST_APP_VERSION, normalizedVersion);
+  }
+
+  return {
+    created: Boolean(backup),
+    backup,
+  };
+}

application/state/aiDraftState.test.ts

@@ -0,0 +1,307 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  activateDraftView,
+  bumpDraftMutationVersionState,
+  bumpDraftUploadGenerationState,
+  clearScopeDraftState,
+  createEmptyDraft,
+  ensureDraftForScopeState,
+  getDraftMutationVersionState,
+  getDraftUploadGenerationState,
+  pruneTerminalScopeState,
+  pruneTerminalTransientState,
+  resolvePanelView,
+  setDraftView,
+  setSessionView,
+  updateDraftForScope,
+} from "./aiDraftState.ts";
+
+test("createEmptyDraft seeds selected agent and empty inputs", () => {
+  const draft = createEmptyDraft("agent-alpha");
+
+  assert.equal(draft.agentId, "agent-alpha");
+  assert.equal(draft.text, "");
+  assert.deepEqual(draft.attachments, []);
+  assert.deepEqual(draft.selectedUserSkillSlugs, []);
+  assert.equal(typeof draft.updatedAt, "number");
+});
+
+test("resolvePanelView defaults to draft when no explicit view exists", () => {
+  assert.deepEqual(resolvePanelView({}, "terminal:123"), { mode: "draft" });
+});
+
+test("setDraftView records draft mode", () => {
+  assert.deepEqual(setDraftView({}, "terminal:123"), {
+    "terminal:123": { mode: "draft" },
+  });
+});
+
+test("activateDraftView clears the terminal scope's active session owner", () => {
+  const activeSessionIdMap = {
+    "terminal:123": "session-123",
+    "workspace:abc": "session-workspace",
+  };
+  const panelViewByScope = {
+    "terminal:123": { mode: "session", sessionId: "session-123" },
+    "workspace:abc": { mode: "session", sessionId: "session-workspace" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = activateDraftView(
+    activeSessionIdMap,
+    panelViewByScope,
+    "terminal:123",
+  );
+
+  assert.deepEqual(next.activeSessionIdMap, {
+    "workspace:abc": "session-workspace",
+  });
+  assert.deepEqual(next.panelViewByScope, {
+    "terminal:123": { mode: "draft" },
+    "workspace:abc": panelViewByScope["workspace:abc"],
+  });
+});
+
+test("activateDraftView is a no-op when the scope already has explicit draft view", () => {
+  const activeSessionIdMap = {
+    "workspace:abc": "session-workspace",
+  };
+  const panelViewByScope = {
+    "terminal:123": { mode: "draft" },
+    "workspace:abc": { mode: "session", sessionId: "session-workspace" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = activateDraftView(
+    activeSessionIdMap,
+    panelViewByScope,
+    "terminal:123",
+  );
+
+  assert.equal(next.activeSessionIdMap, activeSessionIdMap);
+  assert.equal(next.panelViewByScope, panelViewByScope);
+});
+
+test("setSessionView records target session id", () => {
+  assert.deepEqual(setSessionView({}, "workspace:abc", "session-123"), {
+    "workspace:abc": { mode: "session", sessionId: "session-123" },
+  });
+});
+
+test("clearScopeDraftState removes both the draft and current panel view", () => {
+  const draftsByScope = {
+    "terminal:1": createEmptyDraft("agent-alpha"),
+    "workspace:2": createEmptyDraft("agent-beta"),
+  };
+  const panelViewByScope = {
+    "terminal:1": { mode: "session", sessionId: "session-123" },
+    "workspace:2": { mode: "draft" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = clearScopeDraftState(draftsByScope, panelViewByScope, "terminal:1");
+
+  assert.deepEqual(next.draftsByScope, {
+    "workspace:2": draftsByScope["workspace:2"],
+  });
+  assert.deepEqual(next.panelViewByScope, {
+    "workspace:2": panelViewByScope["workspace:2"],
+  });
+});
+
+test("clearScopeDraftState is a no-op when the scope is already cleared", () => {
+  const draftsByScope = {
+    "workspace:2": createEmptyDraft("agent-beta"),
+  };
+  const panelViewByScope = {
+    "workspace:2": { mode: "draft" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = clearScopeDraftState(draftsByScope, panelViewByScope, "terminal:closed");
+
+  assert.equal(next.draftsByScope, draftsByScope);
+  assert.equal(next.panelViewByScope, panelViewByScope);
+});
+
+test("updateDraftForScope creates a draft on first write and keeps other scopes untouched", () => {
+  const draftsByScope = {
+    "workspace:2": createEmptyDraft("agent-beta"),
+  };
+
+  const next = updateDraftForScope(
+    draftsByScope,
+    "terminal:1",
+    "agent-alpha",
+    (draft) => ({
+      ...draft,
+      text: "hello world",
+    }),
+  );
+
+  assert.equal(next["terminal:1"].agentId, "agent-alpha");
+  assert.equal(next["terminal:1"].text, "hello world");
+  assert.equal(next["workspace:2"], draftsByScope["workspace:2"]);
+});
+
+test("ensureDraftForScopeState adds the missing scope without dropping siblings", () => {
+  const draftsByScope = {
+    "workspace:2": createEmptyDraft("agent-beta"),
+  };
+
+  const next = ensureDraftForScopeState(
+    draftsByScope,
+    "terminal:1",
+    "agent-alpha",
+  );
+
+  assert.equal(next["terminal:1"].agentId, "agent-alpha");
+  assert.equal(next["terminal:1"].text, "");
+  assert.equal(next["workspace:2"], draftsByScope["workspace:2"]);
+});
+
+test("ensureDraftForScopeState returns the original ref when the scope already exists", () => {
+  const draftsByScope = {
+    "terminal:1": createEmptyDraft("agent-alpha"),
+  };
+
+  const next = ensureDraftForScopeState(
+    draftsByScope,
+    "terminal:1",
+    "agent-beta",
+  );
+
+  assert.equal(next, draftsByScope);
+});
+
+test("draft mutation version increments on every mutation for the same scope", () => {
+  const scopeKey = "terminal:1";
+  const initialVersion = getDraftMutationVersionState({}, scopeKey);
+  const nextVersions = bumpDraftMutationVersionState({}, scopeKey);
+  const finalVersions = bumpDraftMutationVersionState(nextVersions, scopeKey);
+
+  assert.equal(initialVersion, 0);
+  assert.equal(getDraftMutationVersionState(nextVersions, scopeKey), 1);
+  assert.equal(getDraftMutationVersionState(finalVersions, scopeKey), 2);
+});
+
+test("draft upload generation only increments when the draft lifecycle rolls over", () => {
+  const scopeKey = "terminal:1";
+  const initialGeneration = getDraftUploadGenerationState({}, scopeKey);
+  const nextGenerations = bumpDraftUploadGenerationState({}, scopeKey);
+  const finalGenerations = bumpDraftUploadGenerationState(nextGenerations, scopeKey);
+
+  assert.equal(initialGeneration, 0);
+  assert.equal(getDraftUploadGenerationState(nextGenerations, scopeKey), 1);
+  assert.equal(getDraftUploadGenerationState(finalGenerations, scopeKey), 2);
+});
+
+test("pruneTerminalScopeState removes closed terminal drafts and views only", () => {
+  const draftsByScope = {
+    "terminal:closed": createEmptyDraft("agent-alpha"),
+    "terminal:open": createEmptyDraft("agent-beta"),
+    "workspace:keep": createEmptyDraft("agent-gamma"),
+  };
+  const panelViewByScope = {
+    "terminal:closed": { mode: "draft" },
+    "terminal:open": { mode: "session", sessionId: "session-open" },
+    "workspace:keep": { mode: "session", sessionId: "session-workspace" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = pruneTerminalScopeState(
+    draftsByScope,
+    panelViewByScope,
+    new Set(["open"]),
+  );
+
+  assert.deepEqual(next.draftsByScope, {
+    "terminal:open": draftsByScope["terminal:open"],
+    "workspace:keep": draftsByScope["workspace:keep"],
+  });
+  assert.deepEqual(next.panelViewByScope, {
+    "terminal:open": panelViewByScope["terminal:open"],
+    "workspace:keep": panelViewByScope["workspace:keep"],
+  });
+});
+
+test("pruneTerminalScopeState returns original refs when nothing is pruned", () => {
+  const draftsByScope = {
+    "terminal:open": createEmptyDraft("agent-alpha"),
+    "workspace:keep": createEmptyDraft("agent-beta"),
+  };
+  const panelViewByScope = {
+    "terminal:open": { mode: "draft" },
+    "workspace:keep": { mode: "session", sessionId: "session-1" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = pruneTerminalScopeState(
+    draftsByScope,
+    panelViewByScope,
+    new Set(["open"]),
+  );
+
+  assert.equal(next.draftsByScope, draftsByScope);
+  assert.equal(next.panelViewByScope, panelViewByScope);
+});
+
+test("pruneTerminalTransientState clears closed terminal active session, draft, and view state only", () => {
+  const activeSessionIdMap = {
+    "terminal:closed": "session-closed",
+    "terminal:open": "session-open",
+    "workspace:keep": "session-workspace",
+  };
+  const draftsByScope = {
+    "terminal:closed": createEmptyDraft("agent-alpha"),
+    "terminal:open": createEmptyDraft("agent-beta"),
+    "workspace:keep": createEmptyDraft("agent-gamma"),
+  };
+  const panelViewByScope = {
+    "terminal:closed": { mode: "draft" },
+    "terminal:open": { mode: "session", sessionId: "session-open" },
+    "workspace:keep": { mode: "session", sessionId: "session-workspace" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = pruneTerminalTransientState(
+    activeSessionIdMap,
+    draftsByScope,
+    panelViewByScope,
+    new Set(["open"]),
+  );
+
+  assert.deepEqual(next.activeSessionIdMap, {
+    "terminal:open": "session-open",
+    "workspace:keep": "session-workspace",
+  });
+  assert.deepEqual(next.draftsByScope, {
+    "terminal:open": draftsByScope["terminal:open"],
+    "workspace:keep": draftsByScope["workspace:keep"],
+  });
+  assert.deepEqual(next.panelViewByScope, {
+    "terminal:open": panelViewByScope["terminal:open"],
+    "workspace:keep": panelViewByScope["workspace:keep"],
+  });
+});
+
+test("pruneTerminalTransientState returns original refs when no terminal scopes close", () => {
+  const activeSessionIdMap = {
+    "terminal:open": "session-open",
+    "workspace:keep": "session-workspace",
+  };
+  const draftsByScope = {
+    "terminal:open": createEmptyDraft("agent-alpha"),
+    "workspace:keep": createEmptyDraft("agent-beta"),
+  };
+  const panelViewByScope = {
+    "terminal:open": { mode: "draft" },
+    "workspace:keep": { mode: "session", sessionId: "session-workspace" },
+  } satisfies Record<string, { mode: "draft" } | { mode: "session"; sessionId: string }>;
+
+  const next = pruneTerminalTransientState(
+    activeSessionIdMap,
+    draftsByScope,
+    panelViewByScope,
+    new Set(["open"]),
+  );
+
+  assert.equal(next.activeSessionIdMap, activeSessionIdMap);
+  assert.equal(next.draftsByScope, draftsByScope);
+  assert.equal(next.panelViewByScope, panelViewByScope);
+});

application/state/aiDraftState.ts

@@ -0,0 +1,257 @@
+import type {
+  AIDraft,
+  AIPanelView,
+} from '../../infrastructure/ai/types';
+
+type DraftsByScope = Partial<Record<string, AIDraft>>;
+type PanelViewByScope = Partial<Record<string, AIPanelView>>;
+type ActiveSessionIdMap = Record<string, string | null>;
+type DraftMutationVersionByScope = Record<string, number>;
+type DraftUploadGenerationByScope = Record<string, number>;
+
+const DEFAULT_PANEL_VIEW: AIPanelView = { mode: 'draft' };
+
+export function createEmptyDraft(agentId: string): AIDraft {
+  return {
+    text: '',
+    agentId,
+    attachments: [],
+    selectedUserSkillSlugs: [],
+    updatedAt: Date.now(),
+  };
+}
+
+export function getDraftMutationVersionState(
+  versionsByScope: DraftMutationVersionByScope,
+  scopeKey: string,
+): number {
+  return versionsByScope[scopeKey] ?? 0;
+}
+
+export function bumpDraftMutationVersionState(
+  versionsByScope: DraftMutationVersionByScope,
+  scopeKey: string,
+): DraftMutationVersionByScope {
+  return {
+    ...versionsByScope,
+    [scopeKey]: getDraftMutationVersionState(versionsByScope, scopeKey) + 1,
+  };
+}
+
+export function getDraftUploadGenerationState(
+  generationsByScope: DraftUploadGenerationByScope,
+  scopeKey: string,
+): number {
+  return generationsByScope[scopeKey] ?? 0;
+}
+
+export function bumpDraftUploadGenerationState(
+  generationsByScope: DraftUploadGenerationByScope,
+  scopeKey: string,
+): DraftUploadGenerationByScope {
+  return {
+    ...generationsByScope,
+    [scopeKey]: getDraftUploadGenerationState(generationsByScope, scopeKey) + 1,
+  };
+}
+
+export function resolvePanelView(
+  panelViewByScope: PanelViewByScope,
+  scopeKey: string,
+): AIPanelView {
+  return panelViewByScope[scopeKey] ?? DEFAULT_PANEL_VIEW;
+}
+
+export function setDraftView(
+  panelViewByScope: PanelViewByScope,
+  scopeKey: string,
+): PanelViewByScope {
+  const currentPanelView = panelViewByScope[scopeKey];
+  if (currentPanelView?.mode === 'draft') {
+    return panelViewByScope;
+  }
+
+  return {
+    ...panelViewByScope,
+    [scopeKey]: DEFAULT_PANEL_VIEW,
+  };
+}
+
+export function activateDraftView(
+  activeSessionIdMap: ActiveSessionIdMap,
+  panelViewByScope: PanelViewByScope,
+  scopeKey: string,
+): {
+  activeSessionIdMap: ActiveSessionIdMap;
+  panelViewByScope: PanelViewByScope;
+} {
+  const nextPanelViewByScope = setDraftView(panelViewByScope, scopeKey);
+  const hasActiveSession = activeSessionIdMap[scopeKey] != null;
+
+  if (!hasActiveSession) {
+    return {
+      activeSessionIdMap,
+      panelViewByScope: nextPanelViewByScope,
+    };
+  }
+
+  const nextActiveSessionIdMap = { ...activeSessionIdMap };
+  delete nextActiveSessionIdMap[scopeKey];
+
+  return {
+    activeSessionIdMap: nextActiveSessionIdMap,
+    panelViewByScope: nextPanelViewByScope,
+  };
+}
+
+export function setSessionView(
+  panelViewByScope: PanelViewByScope,
+  scopeKey: string,
+  sessionId: string,
+): PanelViewByScope {
+  return {
+    ...panelViewByScope,
+    [scopeKey]: { mode: 'session', sessionId },
+  };
+}
+
+export function updateDraftForScope(
+  draftsByScope: DraftsByScope,
+  scopeKey: string,
+  fallbackAgentId: string,
+  updater: (draft: AIDraft) => AIDraft,
+): DraftsByScope {
+  const currentDraft = draftsByScope[scopeKey] ?? createEmptyDraft(fallbackAgentId);
+  const nextDraft = updater(currentDraft);
+
+  return {
+    ...draftsByScope,
+    [scopeKey]: nextDraft,
+  };
+}
+
+export function ensureDraftForScopeState(
+  draftsByScope: DraftsByScope,
+  scopeKey: string,
+  agentId: string,
+): DraftsByScope {
+  if (draftsByScope[scopeKey]) {
+    return draftsByScope;
+  }
+
+  return {
+    ...draftsByScope,
+    [scopeKey]: createEmptyDraft(agentId),
+  };
+}
+
+export function clearScopeDraftState(
+  draftsByScope: DraftsByScope,
+  panelViewByScope: PanelViewByScope,
+  scopeKey: string,
+): {
+  draftsByScope: DraftsByScope;
+  panelViewByScope: PanelViewByScope;
+} {
+  const hasDraft = Object.prototype.hasOwnProperty.call(draftsByScope, scopeKey);
+  const hasPanelView = Object.prototype.hasOwnProperty.call(panelViewByScope, scopeKey);
+
+  if (!hasDraft && !hasPanelView) {
+    return {
+      draftsByScope,
+      panelViewByScope,
+    };
+  }
+
+  return {
+    draftsByScope: hasDraft
+      ? (() => {
+          const nextDrafts = { ...draftsByScope };
+          delete nextDrafts[scopeKey];
+          return nextDrafts;
+        })()
+      : draftsByScope,
+    panelViewByScope: hasPanelView
+      ? (() => {
+          const nextPanelViews = { ...panelViewByScope };
+          delete nextPanelViews[scopeKey];
+          return nextPanelViews;
+        })()
+      : panelViewByScope,
+  };
+}
+
+function isClosedTerminalScope(scopeKey: string, activeTerminalTargetIds: Set<string>) {
+  if (!scopeKey.startsWith('terminal:')) return false;
+
+  const targetId = scopeKey.slice('terminal:'.length);
+  if (!targetId) return false;
+
+  return !activeTerminalTargetIds.has(targetId);
+}
+
+export function pruneTerminalScopeState(
+  draftsByScope: DraftsByScope,
+  panelViewByScope: PanelViewByScope,
+  activeTerminalTargetIds: Set<string>,
+): {
+  draftsByScope: DraftsByScope;
+  panelViewByScope: PanelViewByScope;
+} {
+  const nextDraftsByScope = { ...draftsByScope };
+  const nextPanelViewByScope = { ...panelViewByScope };
+  let draftsChanged = false;
+  let panelViewsChanged = false;
+
+  for (const scopeKey of Object.keys(nextDraftsByScope)) {
+    if (!isClosedTerminalScope(scopeKey, activeTerminalTargetIds)) continue;
+    delete nextDraftsByScope[scopeKey];
+    draftsChanged = true;
+  }
+
+  for (const scopeKey of Object.keys(nextPanelViewByScope)) {
+    if (!isClosedTerminalScope(scopeKey, activeTerminalTargetIds)) continue;
+    delete nextPanelViewByScope[scopeKey];
+    panelViewsChanged = true;
+  }
+
+  return {
+    draftsByScope: draftsChanged ? nextDraftsByScope : draftsByScope,
+    panelViewByScope: panelViewsChanged ? nextPanelViewByScope : panelViewByScope,
+  };
+}
+
+export function pruneTerminalTransientState(
+  activeSessionIdMap: ActiveSessionIdMap,
+  draftsByScope: DraftsByScope,
+  panelViewByScope: PanelViewByScope,
+  activeTerminalTargetIds: Set<string>,
+): {
+  activeSessionIdMap: ActiveSessionIdMap;
+  draftsByScope: DraftsByScope;
+  panelViewByScope: PanelViewByScope;
+} {
+  let activeSessionMapChanged = false;
+  const nextActiveSessionIdMap: ActiveSessionIdMap = {};
+
+  for (const [scopeKey, sessionId] of Object.entries(activeSessionIdMap)) {
+    if (isClosedTerminalScope(scopeKey, activeTerminalTargetIds)) {
+      activeSessionMapChanged = true;
+      continue;
+    }
+
+    nextActiveSessionIdMap[scopeKey] = sessionId;
+  }
+
+  const nextTerminalScopeState = pruneTerminalScopeState(
+    draftsByScope,
+    panelViewByScope,
+    activeTerminalTargetIds,
+  );
+
+  return {
+    activeSessionIdMap: activeSessionMapChanged ? nextActiveSessionIdMap : activeSessionIdMap,
+    draftsByScope: nextTerminalScopeState.draftsByScope,
+    panelViewByScope: nextTerminalScopeState.panelViewByScope,
+  };
+}

application/state/aiScopeCleanup.test.ts

@@ -0,0 +1,163 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import type {
+  AIPanelView,
+  AISession,
+} from "../../infrastructure/ai/types.ts";
+import { createEmptyDraft } from "./aiDraftState.ts";
+import {
+  pruneInactiveScopedSessions,
+  pruneInactiveScopedTransientState,
+} from "./aiScopeCleanup.ts";
+
+function createSession(id: string, scope: AISession["scope"], externalSessionId?: string): AISession {
+  return {
+    id,
+    title: id,
+    agentId: "catty",
+    scope,
+    messages: [],
+    externalSessionId,
+    createdAt: 1,
+    updatedAt: 1,
+  };
+}
+
+test("pruneInactiveScopedTransientState removes closed workspace and terminal scope state", () => {
+  const activeSessionIdMap = {
+    "terminal:open-terminal": "session-open",
+    "terminal:closed-terminal": "session-closed-terminal",
+    "workspace:open-workspace": "session-open-workspace",
+    "workspace:closed-workspace": "session-closed-workspace",
+  };
+  const draftsByScope = {
+    "terminal:open-terminal": createEmptyDraft("catty"),
+    "terminal:closed-terminal": createEmptyDraft("catty"),
+    "workspace:open-workspace": createEmptyDraft("catty"),
+    "workspace:closed-workspace": createEmptyDraft("catty"),
+  };
+  const panelViewByScope = {
+    "terminal:open-terminal": { mode: "draft" },
+    "terminal:closed-terminal": { mode: "session", sessionId: "session-closed-terminal" },
+    "workspace:open-workspace": { mode: "draft" },
+    "workspace:closed-workspace": { mode: "session", sessionId: "session-closed-workspace" },
+  } satisfies Record<string, AIPanelView>;
+
+  const next = pruneInactiveScopedTransientState(
+    activeSessionIdMap,
+    draftsByScope,
+    panelViewByScope,
+    new Set(["open-terminal", "open-workspace"]),
+  );
+
+  assert.deepEqual(next.activeSessionIdMap, {
+    "terminal:open-terminal": "session-open",
+    "workspace:open-workspace": "session-open-workspace",
+  });
+  assert.deepEqual(next.draftsByScope, {
+    "terminal:open-terminal": draftsByScope["terminal:open-terminal"],
+    "workspace:open-workspace": draftsByScope["workspace:open-workspace"],
+  });
+  assert.deepEqual(next.panelViewByScope, {
+    "terminal:open-terminal": panelViewByScope["terminal:open-terminal"],
+    "workspace:open-workspace": panelViewByScope["workspace:open-workspace"],
+  });
+});
+
+test("pruneInactiveScopedSessions removes non-restorable terminal chats and closed workspaces", () => {
+  const sessions = [
+    createSession("terminal-restorable", {
+      type: "terminal",
+      targetId: "closed-restorable",
+      hostIds: ["host-1"],
+    }, "ext-1"),
+    createSession("terminal-local", {
+      type: "terminal",
+      targetId: "closed-local",
+      hostIds: ["local-shell"],
+    }, "ext-2"),
+    createSession("workspace-closed", {
+      type: "workspace",
+      targetId: "closed-workspace",
+    }, "ext-3"),
+    createSession("terminal-open", {
+      type: "terminal",
+      targetId: "open-terminal",
+      hostIds: ["host-2"],
+    }, "ext-4"),
+  ];
+
+  const next = pruneInactiveScopedSessions(
+    sessions,
+    new Set(["open-terminal"]),
+  );
+
+  assert.deepEqual(next.orphanedSessionIds, [
+    "terminal-restorable",
+    "terminal-local",
+    "workspace-closed",
+  ]);
+  assert.deepEqual(next.sessions, [
+    {
+      ...sessions[0],
+      externalSessionId: undefined,
+    },
+    sessions[3],
+  ]);
+});
+
+test("pruneInactiveScopedSessions preserves original sessions when orphaned restorable chats are already detached", () => {
+  const sessions = [
+    createSession("terminal-restorable", {
+      type: "terminal",
+      targetId: "closed-restorable",
+      hostIds: ["host-1"],
+    }),
+    createSession("terminal-open", {
+      type: "terminal",
+      targetId: "open-terminal",
+      hostIds: ["host-2"],
+    }, "ext-4"),
+  ];
+
+  const next = pruneInactiveScopedSessions(
+    sessions,
+    new Set(["open-terminal"]),
+  );
+
+  assert.deepEqual(next.orphanedSessionIds, ["terminal-restorable"]);
+  assert.equal(next.sessions, sessions);
+});
+
+test("pruneInactiveScopedSessions treats sessions displayed elsewhere as in-use, not orphaned", () => {
+  // terminal-restorable's original scope (terminal-closed-A) is gone, but
+  // the user resumed it into terminal-open-B from history. The session's
+  // externalSessionId must be preserved and it must not appear in the
+  // orphaned list, otherwise the active chat loses ACP continuity.
+  const resumedElsewhere = createSession("terminal-restorable", {
+    type: "terminal",
+    targetId: "terminal-closed-A",
+    hostIds: ["host-1"],
+  }, "ext-resumed");
+
+  const trulyOrphaned = createSession("terminal-stale", {
+    type: "terminal",
+    targetId: "terminal-closed-C",
+    hostIds: ["host-2"],
+  }, "ext-stale");
+
+  const sessions = [resumedElsewhere, trulyOrphaned];
+
+  const next = pruneInactiveScopedSessions(
+    sessions,
+    new Set(["terminal-open-B"]),
+    new Set(["terminal-restorable"]),
+  );
+
+  // Only the one not being displayed anywhere should show up as orphaned.
+  assert.deepEqual(next.orphanedSessionIds, ["terminal-stale"]);
+  // The resumed session must retain its externalSessionId.
+  const resumedNext = next.sessions.find((s) => s.id === "terminal-restorable");
+  assert.equal(resumedNext?.externalSessionId, "ext-resumed");
+});

application/state/aiScopeCleanup.ts

@@ -0,0 +1,153 @@
+import type {
+  AIDraft,
+  AIPanelView,
+  AISession,
+} from "../../infrastructure/ai/types";
+
+type DraftsByScope = Partial<Record<string, AIDraft>>;
+type PanelViewByScope = Partial<Record<string, AIPanelView>>;
+type ActiveSessionIdMap = Record<string, string | null>;
+
+function isInactiveScopedTarget(
+  scopeKey: string,
+  activeTargetIds: Set<string>,
+): boolean {
+  const separatorIndex = scopeKey.indexOf(":");
+  if (separatorIndex === -1) return false;
+
+  const scopeType = scopeKey.slice(0, separatorIndex);
+  if (scopeType !== "terminal" && scopeType !== "workspace") return false;
+
+  const targetId = scopeKey.slice(separatorIndex + 1);
+  if (!targetId) return false;
+
+  return !activeTargetIds.has(targetId);
+}
+
+export function pruneInactiveScopedState(
+  draftsByScope: DraftsByScope,
+  panelViewByScope: PanelViewByScope,
+  activeTargetIds: Set<string>,
+): {
+  draftsByScope: DraftsByScope;
+  panelViewByScope: PanelViewByScope;
+} {
+  const nextDraftsByScope = { ...draftsByScope };
+  const nextPanelViewByScope = { ...panelViewByScope };
+  let draftsChanged = false;
+  let panelViewsChanged = false;
+
+  for (const scopeKey of Object.keys(nextDraftsByScope)) {
+    if (!isInactiveScopedTarget(scopeKey, activeTargetIds)) continue;
+    delete nextDraftsByScope[scopeKey];
+    draftsChanged = true;
+  }
+
+  for (const scopeKey of Object.keys(nextPanelViewByScope)) {
+    if (!isInactiveScopedTarget(scopeKey, activeTargetIds)) continue;
+    delete nextPanelViewByScope[scopeKey];
+    panelViewsChanged = true;
+  }
+
+  return {
+    draftsByScope: draftsChanged ? nextDraftsByScope : draftsByScope,
+    panelViewByScope: panelViewsChanged ? nextPanelViewByScope : panelViewByScope,
+  };
+}
+
+export function pruneInactiveScopedTransientState(
+  activeSessionIdMap: ActiveSessionIdMap,
+  draftsByScope: DraftsByScope,
+  panelViewByScope: PanelViewByScope,
+  activeTargetIds: Set<string>,
+): {
+  activeSessionIdMap: ActiveSessionIdMap;
+  draftsByScope: DraftsByScope;
+  panelViewByScope: PanelViewByScope;
+} {
+  let activeSessionMapChanged = false;
+  const nextActiveSessionIdMap: ActiveSessionIdMap = {};
+
+  for (const [scopeKey, sessionId] of Object.entries(activeSessionIdMap)) {
+    if (isInactiveScopedTarget(scopeKey, activeTargetIds)) {
+      activeSessionMapChanged = true;
+      continue;
+    }
+
+    nextActiveSessionIdMap[scopeKey] = sessionId;
+  }
+
+  const nextScopedState = pruneInactiveScopedState(
+    draftsByScope,
+    panelViewByScope,
+    activeTargetIds,
+  );
+
+  return {
+    activeSessionIdMap: activeSessionMapChanged ? nextActiveSessionIdMap : activeSessionIdMap,
+    draftsByScope: nextScopedState.draftsByScope,
+    panelViewByScope: nextScopedState.panelViewByScope,
+  };
+}
+
+function isRestorableTerminalSession(session: AISession): boolean {
+  return session.scope.type === "terminal"
+    && !!session.scope.hostIds?.length
+    && session.scope.hostIds.some((id) => !id.startsWith("local-") && !id.startsWith("serial-"));
+}
+
+export function pruneInactiveScopedSessions(
+  sessions: AISession[],
+  activeTargetIds: Set<string>,
+  /**
+   * Session ids currently displayed by any live scope. A session whose
+   * `scope.targetId` is inactive but whose id is still in use somewhere
+   * (e.g. resumed from history into a different terminal) must not be
+   * treated as orphaned — clearing its `externalSessionId` or deleting
+   * it outright would break the chat the user is actively continuing.
+   */
+  activeSessionIds: Set<string> = new Set(),
+): {
+  sessions: AISession[];
+  orphanedSessionIds: string[];
+} {
+  const orphanedSessionIds = sessions
+    .filter((session) => session.scope.targetId && !activeTargetIds.has(session.scope.targetId))
+    .filter((session) => !activeSessionIds.has(session.id))
+    .map((session) => session.id);
+
+  if (orphanedSessionIds.length === 0) {
+    return {
+      sessions,
+      orphanedSessionIds,
+    };
+  }
+
+  const orphanedSessionIdSet = new Set(orphanedSessionIds);
+  let sessionsChanged = false;
+
+  const nextSessions = sessions.flatMap((session) => {
+    if (!orphanedSessionIdSet.has(session.id)) {
+      return [session];
+    }
+
+    if (!isRestorableTerminalSession(session)) {
+      sessionsChanged = true;
+      return [];
+    }
+
+    if (!session.externalSessionId) {
+      return [session];
+    }
+
+    sessionsChanged = true;
+    return [
+      { ...session, externalSessionId: undefined },
+    ];
+  });
+
+  return {
+    sessions: sessionsChanged ? nextSessions : sessions,
+    orphanedSessionIds,
+  };
+}

application/state/customThemeStore.ts

@@ -75,7 +75,6 @@ class CustomThemeStore {
                 if (payload.key === STORAGE_KEY_CUSTOM_THEMES) {
                     // Another window changed custom themes — reload from localStorage
                     this.loadFromStorage();
-                    this.notify();
                 }
             });
         } catch {
@@ -129,6 +128,13 @@ class CustomThemeStore {
         this.notify();
         this.broadcastChange();
     };
+
+    replaceThemes = (themes: TerminalTheme[]) => {
+        this.themes = themes.map((theme) => ({ ...theme, colors: { ...theme.colors }, isCustom: true }));
+        this.saveToStorage();
+        this.notify();
+        this.broadcastChange();
+    };
 }
 
 // Singleton
@@ -172,5 +178,9 @@ export const useCustomThemeActions = () => {
         customThemeStore.deleteTheme(id);
     }, []);
 
-    return { addTheme, updateTheme, deleteTheme };
+    const replaceThemes = useCallback((themes: TerminalTheme[]) => {
+        customThemeStore.replaceThemes(themes);
+    }, []);
+
+    return { addTheme, updateTheme, deleteTheme, replaceThemes };
 };

application/state/sftp/useSftpConnections.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from "react";
+import React, { useCallback, useEffect, useRef } from "react";
 import type { MutableRefObject } from "react";
 import { netcattyBridge } from "../../../infrastructure/services/netcattyBridge";
 import type { Host, Identity, SftpConnection, SftpFileEntry, SftpFilenameEncoding, SSHKey } from "../../../domain/models";

application/state/sftp/useSftpPaneActions.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from "react";
+import React, { useCallback, useRef } from "react";
 import type { Host, SftpFileEntry, SftpFilenameEncoding } from "../../../domain/models";
 import { netcattyBridge } from "../../../infrastructure/services/netcattyBridge";
 import { logger } from "../../../lib/logger";

application/state/useAIState.ts

@@ -5,6 +5,7 @@ import {
   STORAGE_KEY_AI_ACTIVE_PROVIDER,
   STORAGE_KEY_AI_ACTIVE_MODEL,
   STORAGE_KEY_AI_PERMISSION_MODE,
+  STORAGE_KEY_AI_TOOL_INTEGRATION_MODE,
   STORAGE_KEY_AI_HOST_PERMISSIONS,
   STORAGE_KEY_AI_EXTERNAL_AGENTS,
   STORAGE_KEY_AI_DEFAULT_AGENT,
@@ -17,8 +18,11 @@ import {
   STORAGE_KEY_AI_WEB_SEARCH,
 } from '../../infrastructure/config/storageKeys';
 import type {
+  AIDraft,
+  AIPanelView,
   AISession,
   AIPermissionMode,
+  AIToolIntegrationMode,
   ProviderConfig,
   HostAIPermission,
   ExternalAgentConfig,
@@ -27,13 +31,42 @@ import type {
   WebSearchConfig,
 } from '../../infrastructure/ai/types';
 import { DEFAULT_COMMAND_BLOCKLIST } from '../../infrastructure/ai/types';
+import {
+  activateDraftView,
+  bumpDraftMutationVersionState,
+  bumpDraftUploadGenerationState,
+  clearScopeDraftState,
+  ensureDraftForScopeState,
+  getDraftUploadGenerationState,
+  setSessionView,
+  updateDraftForScope,
+} from './aiDraftState';
+import {
+  pruneInactiveScopedSessions,
+  pruneInactiveScopedTransientState,
+} from './aiScopeCleanup';
+import { convertFilesToUploads } from './useFileUpload';
 
 /** Typed accessor for the Electron IPC bridge exposed on `window.netcatty`. */
+interface AIBridge {
+  aiAcpCleanup?: (chatSessionId: string) => Promise<{ ok: boolean }>;
+  aiMcpSetPermissionMode?: (mode: AIPermissionMode) => Promise<unknown> | unknown;
+  aiMcpSetToolIntegrationMode?: (mode: AIToolIntegrationMode) => Promise<unknown> | unknown;
+  aiMcpSetCommandBlocklist?: (blocklist: string[]) => Promise<unknown> | unknown;
+  aiMcpSetCommandTimeout?: (timeout: number) => Promise<unknown> | unknown;
+  aiMcpSetMaxIterations?: (maxIterations: number) => Promise<unknown> | unknown;
+}
+
 function getAIBridge() {
-  return (window as unknown as { netcatty?: Record<string, (...args: unknown[]) => unknown> }).netcatty;
+  return (window as unknown as { netcatty?: AIBridge }).netcatty;
 }
 
 const AI_STATE_CHANGED_EVENT = 'netcatty:ai-state-changed';
+const AI_STATE_CHANGED_DRAFTS_BY_SCOPE = 'netcatty:ai-drafts-by-scope';
+const AI_STATE_CHANGED_PANEL_VIEW_BY_SCOPE = 'netcatty:ai-panel-view-by-scope';
+
+type DraftsByScope = Partial<Record<string, AIDraft>>;
+type PanelViewByScope = Partial<Record<string, AIPanelView>>;
 
 function emitAIStateChanged(key: string) {
   window.dispatchEvent(new CustomEvent<{ key: string }>(AI_STATE_CHANGED_EVENT, { detail: { key } }));
@@ -61,53 +94,42 @@ export function cleanupOrphanedAISessions(activeTargetIds: Set<string>) {
   const currentSessions = latestAISessionsSnapshot
     ?? localStorageAdapter.read<AISession[]>(STORAGE_KEY_AI_SESSIONS)
     ?? [];
-  const orphanedSessionIds = currentSessions
-    .filter((session) => session.scope.targetId && !activeTargetIds.has(session.scope.targetId))
-    .map((session) => session.id);
 
-  if (orphanedSessionIds.length > 0) {
-    const orphanedSessionIdSet = new Set(orphanedSessionIds);
-
-    // Determine which sessions can be restored via host-based matching
-    const preservedIds = new Set<string>();
-    for (const session of currentSessions) {
-      if (!orphanedSessionIdSet.has(session.id)) continue;
-      // Only preserve remote terminal sessions with real hostIds
-      const isRestorable = session.scope.type === 'terminal'
-        && session.scope.hostIds?.length
-        && session.scope.hostIds.some((id) => !id.startsWith('local-') && !id.startsWith('serial-'));
-      if (isRestorable) {
-        preservedIds.add(session.id);
-      }
-    }
-
-    // Cleanup ACP sessions for all orphans (both deleted and preserved).
-    // Preserved sessions will get a new externalSessionId on next use,
-    // so cleaning the old one is safe and prevents subprocess leaks.
-    cleanupAcpSessions(orphanedSessionIds);
-
-    const nextSessions = currentSessions
-      .filter((session) => !orphanedSessionIdSet.has(session.id) || preservedIds.has(session.id))
-      .map((session) => {
-        if (!preservedIds.has(session.id) || !session.externalSessionId) {
-          return session;
-        }
-        // Drop transient ACP session handles so the next turn starts cleanly.
-        return { ...session, externalSessionId: undefined };
-      });
-
-    const sessionsChanged = nextSessions.length !== currentSessions.length
-      || nextSessions.some((session, index) => session !== currentSessions[index]);
-    if (sessionsChanged) {
-      setLatestAISessionsSnapshot(nextSessions);
-      localStorageAdapter.write(STORAGE_KEY_AI_SESSIONS, pruneSessionsForStorage(nextSessions));
-      emitAIStateChanged(STORAGE_KEY_AI_SESSIONS);
-    }
-  }
-
-  const activeSessionIdMap = latestAIActiveSessionMapSnapshot
+  // Sessions shown by a still-live scope must be protected from cleanup
+  // even when their own `scope.targetId` points at a closed terminal —
+  // history can be resumed into a different terminal and we must not
+  // clear its `externalSessionId` (or delete it outright) while it's
+  // actively being used.
+  const preCleanupActiveSessionMap = latestAIActiveSessionMapSnapshot
     ?? localStorageAdapter.read<Record<string, string | null>>(STORAGE_KEY_AI_ACTIVE_SESSION_MAP)
     ?? {};
+  const activeSessionIds = new Set<string>();
+  for (const [scopeKey, sessionId] of Object.entries(preCleanupActiveSessionMap)) {
+    if (!sessionId) continue;
+    if (!isScopeKeyActive(scopeKey, activeTargetIds)) continue;
+    activeSessionIds.add(sessionId);
+  }
+
+  const nextSessionCleanup = pruneInactiveScopedSessions(
+    currentSessions,
+    activeTargetIds,
+    activeSessionIds,
+  );
+
+  if (nextSessionCleanup.orphanedSessionIds.length > 0) {
+    cleanupAcpSessions(nextSessionCleanup.orphanedSessionIds);
+  }
+
+  if (nextSessionCleanup.sessions !== currentSessions) {
+    setLatestAISessionsSnapshot(nextSessionCleanup.sessions);
+    localStorageAdapter.write(
+      STORAGE_KEY_AI_SESSIONS,
+      pruneSessionsForStorage(nextSessionCleanup.sessions),
+    );
+    emitAIStateChanged(STORAGE_KEY_AI_SESSIONS);
+  }
+
+  const activeSessionIdMap = preCleanupActiveSessionMap;
   let activeSessionMapChanged = false;
   const nextActiveSessionIdMap = { ...activeSessionIdMap };
 
@@ -122,6 +144,46 @@ export function cleanupOrphanedAISessions(activeTargetIds: Set<string>) {
     localStorageAdapter.write(STORAGE_KEY_AI_ACTIVE_SESSION_MAP, nextActiveSessionIdMap);
     emitAIStateChanged(STORAGE_KEY_AI_ACTIVE_SESSION_MAP);
   }
+
+  const currentActiveSessionIdMap = activeSessionMapChanged
+    ? nextActiveSessionIdMap
+    : activeSessionIdMap;
+  const currentDraftsByScope = latestAIDraftsByScopeSnapshot ?? {};
+  const currentPanelViewByScope = latestAIPanelViewByScopeSnapshot ?? {};
+  const prunedScopedTransientState = pruneInactiveScopedTransientState(
+    currentActiveSessionIdMap,
+    currentDraftsByScope,
+    currentPanelViewByScope,
+    activeTargetIds,
+  );
+
+  if (prunedScopedTransientState.activeSessionIdMap !== currentActiveSessionIdMap) {
+    setLatestAIActiveSessionMapSnapshot(prunedScopedTransientState.activeSessionIdMap);
+    localStorageAdapter.write(
+      STORAGE_KEY_AI_ACTIVE_SESSION_MAP,
+      prunedScopedTransientState.activeSessionIdMap,
+    );
+    emitAIStateChanged(STORAGE_KEY_AI_ACTIVE_SESSION_MAP);
+  }
+
+  if (prunedScopedTransientState.draftsByScope !== currentDraftsByScope) {
+    for (const scopeKey of Object.keys(currentDraftsByScope)) {
+      if (scopeKey in prunedScopedTransientState.draftsByScope) continue;
+      bumpDraftMutationVersion(scopeKey);
+      bumpDraftUploadGeneration(scopeKey);
+    }
+    setLatestAIDraftsByScopeSnapshot(prunedScopedTransientState.draftsByScope);
+    emitAIStateChanged(AI_STATE_CHANGED_DRAFTS_BY_SCOPE);
+  }
+
+  if (prunedScopedTransientState.panelViewByScope !== currentPanelViewByScope) {
+    for (const scopeKey of Object.keys(currentPanelViewByScope)) {
+      if (scopeKey in prunedScopedTransientState.panelViewByScope) continue;
+      bumpDraftMutationVersion(scopeKey);
+    }
+    setLatestAIPanelViewByScopeSnapshot(prunedScopedTransientState.panelViewByScope);
+    emitAIStateChanged(AI_STATE_CHANGED_PANEL_VIEW_BY_SCOPE);
+  }
 }
 
 
@@ -152,6 +214,10 @@ function pruneSessionsForStorage(sessions: AISession[]): AISession[] {
 
 let latestAISessionsSnapshot: AISession[] | null = null;
 let latestAIActiveSessionMapSnapshot: Record<string, string | null> | null = null;
+let latestAIDraftsByScopeSnapshot: DraftsByScope | null = null;
+let latestAIPanelViewByScopeSnapshot: PanelViewByScope | null = null;
+let latestAIDraftMutationVersionByScopeSnapshot: Record<string, number> = {};
+let latestAIDraftUploadGenerationByScopeSnapshot: Record<string, number> = {};
 
 function setLatestAISessionsSnapshot(sessions: AISession[]) {
   latestAISessionsSnapshot = sessions;
@@ -161,17 +227,33 @@ function setLatestAIActiveSessionMapSnapshot(activeSessionIdMap: Record<string,
   latestAIActiveSessionMapSnapshot = activeSessionIdMap;
 }
 
-function buildScopeKey(scope: AISessionScope) {
-  return `${scope.type}:${scope.targetId ?? ''}`;
+function setLatestAIDraftsByScopeSnapshot(draftsByScope: DraftsByScope) {
+  latestAIDraftsByScopeSnapshot = draftsByScope;
 }
 
-function areHostIdsEqual(left?: string[], right?: string[]) {
-  const leftIds = left ?? [];
-  const rightIds = right ?? [];
-  if (leftIds.length !== rightIds.length) return false;
+function setLatestAIPanelViewByScopeSnapshot(panelViewByScope: PanelViewByScope) {
+  latestAIPanelViewByScopeSnapshot = panelViewByScope;
+}
 
-  const rightSet = new Set(rightIds);
-  return leftIds.every((hostId) => rightSet.has(hostId));
+function bumpDraftMutationVersion(scopeKey: string) {
+  latestAIDraftMutationVersionByScopeSnapshot = bumpDraftMutationVersionState(
+    latestAIDraftMutationVersionByScopeSnapshot,
+    scopeKey,
+  );
+}
+
+function getDraftUploadGeneration(scopeKey: string) {
+  return getDraftUploadGenerationState(
+    latestAIDraftUploadGenerationByScopeSnapshot,
+    scopeKey,
+  );
+}
+
+function bumpDraftUploadGeneration(scopeKey: string) {
+  latestAIDraftUploadGenerationByScopeSnapshot = bumpDraftUploadGenerationState(
+    latestAIDraftUploadGenerationByScopeSnapshot,
+    scopeKey,
+  );
 }
 
 export function useAIState() {
@@ -192,6 +274,10 @@ export function useAIState() {
     if (stored === 'observer' || stored === 'confirm' || stored === 'autonomous') return stored;
     return 'confirm';
   });
+  const [toolIntegrationMode, setToolIntegrationModeRaw] = useState<AIToolIntegrationMode>(() => {
+    const stored = localStorageAdapter.readString(STORAGE_KEY_AI_TOOL_INTEGRATION_MODE);
+    return stored === 'skills' ? 'skills' : 'mcp';
+  });
   const [hostPermissions, setHostPermissionsRaw] = useState<HostAIPermission[]>(() =>
     localStorageAdapter.read<HostAIPermission[]>(STORAGE_KEY_AI_HOST_PERMISSIONS) ?? []
   );
@@ -228,6 +314,14 @@ export function useAIState() {
   const [activeSessionIdMap, setActiveSessionIdMapRaw] = useState<Record<string, string | null>>(() =>
     localStorageAdapter.read<Record<string, string | null>>(STORAGE_KEY_AI_ACTIVE_SESSION_MAP) ?? {}
   );
+  // Per-scope draft/view state is intentionally memory-only so a relaunch
+  // does not restore stale composer input or panel intent against new history.
+  const [draftsByScope, setDraftsByScopeRaw] = useState<DraftsByScope>(() =>
+    latestAIDraftsByScopeSnapshot ?? {}
+  );
+  const [panelViewByScope, setPanelViewByScopeRaw] = useState<PanelViewByScope>(() =>
+    latestAIPanelViewByScopeSnapshot ?? {}
+  );
 
   // Per-agent model selection: remembers last selected model per agent
   const [agentModelMap, setAgentModelMapRaw] = useState<Record<string, string>>(() =>
@@ -247,12 +341,20 @@ export function useAIState() {
     setLatestAIActiveSessionMapSnapshot(activeSessionIdMap);
   }, [activeSessionIdMap]);
 
+  useEffect(() => {
+    setLatestAIDraftsByScopeSnapshot(draftsByScope);
+  }, [draftsByScope]);
+
+  useEffect(() => {
+    setLatestAIPanelViewByScopeSnapshot(panelViewByScope);
+  }, [panelViewByScope]);
+
   useEffect(() => {
     const validSessionIds = new Set(sessions.map((session) => session.id));
     let changed = false;
     const nextActiveSessionIdMap: Record<string, string | null> = {};
 
-    for (const [scopeKey, sessionId] of Object.entries(activeSessionIdMap)) {
+    for (const [scopeKey, sessionId] of Object.entries(activeSessionIdMap) as Array<[string, string | null]>) {
       const nextSessionId = sessionId && validSessionIds.has(sessionId) ? sessionId : null;
       nextActiveSessionIdMap[scopeKey] = nextSessionId;
       if (nextSessionId !== sessionId) {
@@ -269,13 +371,39 @@ export function useAIState() {
   }, [sessions, activeSessionIdMap]);
 
   const setActiveSessionId = useCallback((scopeKey: string, id: string | null) => {
+    let nextActiveSessionIdMap: Record<string, string | null> | null = null;
+
     setActiveSessionIdMapRaw(prev => {
+      if (prev[scopeKey] === id) {
+        return prev;
+      }
+
       const next = { ...prev, [scopeKey]: id };
-      setLatestAIActiveSessionMapSnapshot(next);
-      localStorageAdapter.write(STORAGE_KEY_AI_ACTIVE_SESSION_MAP, next);
-      emitAIStateChanged(STORAGE_KEY_AI_ACTIVE_SESSION_MAP);
+      nextActiveSessionIdMap = next;
       return next;
     });
+
+    if (!nextActiveSessionIdMap) return;
+
+    setLatestAIActiveSessionMapSnapshot(nextActiveSessionIdMap);
+    localStorageAdapter.write(STORAGE_KEY_AI_ACTIVE_SESSION_MAP, nextActiveSessionIdMap);
+    emitAIStateChanged(STORAGE_KEY_AI_ACTIVE_SESSION_MAP);
+  }, []);
+
+  const setPanelViewByScope = useCallback((value: PanelViewByScope | ((prev: PanelViewByScope) => PanelViewByScope)) => {
+    let nextPanelViewByScope: PanelViewByScope | null = null;
+
+    setPanelViewByScopeRaw((prev) => {
+      const next = typeof value === 'function' ? value(prev) : value;
+      if (next === prev) return prev;
+      nextPanelViewByScope = next;
+      return next;
+    });
+
+    if (!nextPanelViewByScope) return;
+
+    setLatestAIPanelViewByScopeSnapshot(nextPanelViewByScope);
+    emitAIStateChanged(AI_STATE_CHANGED_PANEL_VIEW_BY_SCOPE);
   }, []);
 
   const setAgentModel = useCallback((agentId: string, modelId: string) => {
@@ -330,6 +458,13 @@ export function useAIState() {
     });
   }, []);
 
+  const setToolIntegrationMode = useCallback((mode: AIToolIntegrationMode) => {
+    setToolIntegrationModeRaw(mode);
+    localStorageAdapter.writeString(STORAGE_KEY_AI_TOOL_INTEGRATION_MODE, mode);
+    const bridge = getAIBridge();
+    bridge?.aiMcpSetToolIntegrationMode?.(mode);
+  }, []);
+
   const setExternalAgents = useCallback((value: ExternalAgentConfig[] | ((prev: ExternalAgentConfig[]) => ExternalAgentConfig[])) => {
     setExternalAgentsRaw(prev => {
       const next = typeof value === 'function' ? value(prev) : value;
@@ -396,6 +531,15 @@ export function useAIState() {
             }
             break;
           }
+          case STORAGE_KEY_AI_TOOL_INTEGRATION_MODE:
+            {
+              const mode = localStorageAdapter.readString(STORAGE_KEY_AI_TOOL_INTEGRATION_MODE) === 'skills'
+                ? 'skills'
+                : 'mcp';
+              setToolIntegrationModeRaw(mode);
+              getAIBridge()?.aiMcpSetToolIntegrationMode?.(mode);
+            }
+            break;
           case STORAGE_KEY_AI_EXTERNAL_AGENTS: {
             const agents = localStorageAdapter.read<ExternalAgentConfig[]>(STORAGE_KEY_AI_EXTERNAL_AGENTS);
             if (agents != null && !Array.isArray(agents)) {
@@ -491,6 +635,12 @@ export function useAIState() {
               ?? {},
           );
           return;
+        case AI_STATE_CHANGED_DRAFTS_BY_SCOPE:
+          setDraftsByScopeRaw(latestAIDraftsByScopeSnapshot ?? {});
+          return;
+        case AI_STATE_CHANGED_PANEL_VIEW_BY_SCOPE:
+          setPanelViewByScopeRaw(latestAIPanelViewByScopeSnapshot ?? {});
+          return;
         default:
           handleStorage({ key } as StorageEvent);
       }
@@ -511,8 +661,17 @@ export function useAIState() {
     bridge?.aiMcpSetCommandTimeout?.(initialTimeout);
     const initialMaxIter = localStorageAdapter.readNumber(STORAGE_KEY_AI_MAX_ITERATIONS) ?? 20;
     bridge?.aiMcpSetMaxIterations?.(initialMaxIter);
-    const initialPermMode = localStorageAdapter.readString(STORAGE_KEY_AI_PERMISSION_MODE) ?? 'confirm';
+    const storedPermMode = localStorageAdapter.readString(STORAGE_KEY_AI_PERMISSION_MODE);
+    const initialPermMode: AIPermissionMode =
+      storedPermMode === 'observer' || storedPermMode === 'confirm' || storedPermMode === 'autonomous'
+        ? storedPermMode
+        : 'confirm';
     bridge?.aiMcpSetPermissionMode?.(initialPermMode);
+    const initialToolMode: AIToolIntegrationMode =
+      localStorageAdapter.readString(STORAGE_KEY_AI_TOOL_INTEGRATION_MODE) === 'skills'
+        ? 'skills'
+        : 'mcp';
+    bridge?.aiMcpSetToolIntegrationMode?.(initialToolMode);
   }, []);
 
   // ── Session CRUD ──
@@ -646,61 +805,6 @@ export function useAIState() {
     });
   }, [debouncedPersistSessions]);
 
-  const retargetSessionScope = useCallback((sessionId: string, scope: AISessionScope) => {
-    const currentSession = sessionsRef.current.find((session) => session.id === sessionId);
-    if (!currentSession) return;
-
-    const currentScope = currentSession.scope;
-    const scopeChanged =
-      currentScope.type !== scope.type
-      || currentScope.targetId !== scope.targetId
-      || !areHostIdsEqual(currentScope.hostIds, scope.hostIds);
-
-    const nextScopeKey = buildScopeKey(scope);
-    const currentScopeKey = buildScopeKey(currentScope);
-
-    if (scopeChanged) {
-      setSessionsRaw((prev) => {
-        let changed = false;
-        const next = prev.map((session) => {
-          if (session.id !== sessionId) return session;
-          changed = true;
-          // Clear stale ACP handle — retarget may run before orphan cleanup
-          return { ...session, scope, externalSessionId: undefined };
-        });
-
-        if (!changed) return prev;
-
-        sessionsRef.current = next;
-        setLatestAISessionsSnapshot(next);
-        persistSessions(next);
-        return next;
-      });
-    }
-
-    setActiveSessionIdMapRaw((prev) => {
-      let changed = false;
-      const next = { ...prev };
-
-      if (currentScopeKey !== nextScopeKey && next[currentScopeKey] === sessionId) {
-        delete next[currentScopeKey];
-        changed = true;
-      }
-
-      if (next[nextScopeKey] !== sessionId) {
-        next[nextScopeKey] = sessionId;
-        changed = true;
-      }
-
-      if (!changed) return prev;
-
-      setLatestAIActiveSessionMapSnapshot(next);
-      localStorageAdapter.write(STORAGE_KEY_AI_ACTIVE_SESSION_MAP, next);
-      emitAIStateChanged(STORAGE_KEY_AI_ACTIVE_SESSION_MAP);
-      return next;
-    });
-  }, [persistSessions]);
-
   // Maximum messages per session to prevent unbounded memory growth
   const MAX_MESSAGES_PER_SESSION = 500;
 
@@ -768,14 +872,193 @@ export function useAIState() {
     });
   }, [persistSessions]);
 
+  const ensureDraftForScope = useCallback((scopeKey: string, agentId: string): void => {
+    let nextDraftsByScope: DraftsByScope | null = null;
+
+    setDraftsByScopeRaw((prev) => {
+      const next = ensureDraftForScopeState(prev, scopeKey, agentId);
+      if (next === prev) return prev;
+      nextDraftsByScope = next;
+      return next;
+    });
+
+    if (!nextDraftsByScope) return;
+
+    bumpDraftMutationVersion(scopeKey);
+    setLatestAIDraftsByScopeSnapshot(nextDraftsByScope);
+    emitAIStateChanged(AI_STATE_CHANGED_DRAFTS_BY_SCOPE);
+  }, []);
+
+  const updateDraft = useCallback((
+    scopeKey: string,
+    fallbackAgentId: string,
+    updater: (draft: AIDraft) => AIDraft,
+  ): void => {
+    setDraftsByScopeRaw((prev) => {
+      const next = updateDraftForScope(
+        prev,
+        scopeKey,
+        fallbackAgentId,
+        (draft) => {
+          return {
+            ...updater(draft),
+            updatedAt: Date.now(),
+          };
+        },
+      );
+      setLatestAIDraftsByScopeSnapshot(next);
+      emitAIStateChanged(AI_STATE_CHANGED_DRAFTS_BY_SCOPE);
+      return next;
+    });
+    bumpDraftMutationVersion(scopeKey);
+  }, []);
+
+  const updateDraftIfPresent = useCallback((
+    scopeKey: string,
+    updater: (draft: AIDraft) => AIDraft,
+  ): void => {
+    let updated = false;
+
+    setDraftsByScopeRaw((prev) => {
+      const currentDraft = prev[scopeKey];
+      if (!currentDraft) return prev;
+
+      const nextDraft = {
+        ...updater(currentDraft),
+        updatedAt: Date.now(),
+      };
+      const next = {
+        ...prev,
+        [scopeKey]: nextDraft,
+      };
+      updated = true;
+      setLatestAIDraftsByScopeSnapshot(next);
+      emitAIStateChanged(AI_STATE_CHANGED_DRAFTS_BY_SCOPE);
+      return next;
+    });
+
+    if (updated) {
+      bumpDraftMutationVersion(scopeKey);
+    }
+  }, []);
+
+  const showDraftView = useCallback((scopeKey: string) => {
+    const currentPanelViewByScope = latestAIPanelViewByScopeSnapshot ?? panelViewByScope;
+    let nextActiveSessionIdMap: Record<string, string | null> | null = null;
+    let nextPanelViewByScope: PanelViewByScope | null = null;
+    let activeSessionMapChanged = false;
+    let panelViewChanged = false;
+
+    setActiveSessionIdMapRaw((prevActiveSessionIdMap) => {
+      const next = activateDraftView(
+        prevActiveSessionIdMap,
+        currentPanelViewByScope,
+        scopeKey,
+      );
+      activeSessionMapChanged = next.activeSessionIdMap !== prevActiveSessionIdMap;
+      panelViewChanged = next.panelViewByScope !== currentPanelViewByScope;
+      nextActiveSessionIdMap = next.activeSessionIdMap;
+      nextPanelViewByScope = next.panelViewByScope;
+      return activeSessionMapChanged ? next.activeSessionIdMap : prevActiveSessionIdMap;
+    });
+
+    if (activeSessionMapChanged && nextActiveSessionIdMap) {
+      setLatestAIActiveSessionMapSnapshot(nextActiveSessionIdMap);
+      localStorageAdapter.write(STORAGE_KEY_AI_ACTIVE_SESSION_MAP, nextActiveSessionIdMap);
+      emitAIStateChanged(STORAGE_KEY_AI_ACTIVE_SESSION_MAP);
+    }
+
+    if (panelViewChanged && nextPanelViewByScope) {
+      setLatestAIPanelViewByScopeSnapshot(nextPanelViewByScope);
+      setPanelViewByScopeRaw(nextPanelViewByScope);
+      emitAIStateChanged(AI_STATE_CHANGED_PANEL_VIEW_BY_SCOPE);
+    }
+  }, [panelViewByScope]);
+
+  const showSessionView = useCallback((scopeKey: string, sessionId: string) => {
+    setPanelViewByScope((prev) => setSessionView(prev, scopeKey, sessionId));
+  }, [setPanelViewByScope]);
+
+  const clearDraftForScope = useCallback((scopeKey: string) => {
+    const currentPanelViewByScope = latestAIPanelViewByScopeSnapshot ?? panelViewByScope;
+    let nextDraftsByScope: DraftsByScope | null = null;
+    let nextPanelViewByScope: PanelViewByScope | null = null;
+    let draftsChanged = false;
+    let panelViewChanged = false;
+
+    setDraftsByScopeRaw((prevDraftsByScope) => {
+      const next = clearScopeDraftState(
+        prevDraftsByScope,
+        currentPanelViewByScope,
+        scopeKey,
+      );
+      draftsChanged = next.draftsByScope !== prevDraftsByScope;
+      panelViewChanged = next.panelViewByScope !== currentPanelViewByScope;
+      nextDraftsByScope = next.draftsByScope;
+      nextPanelViewByScope = next.panelViewByScope;
+      return draftsChanged ? next.draftsByScope : prevDraftsByScope;
+    });
+
+    if (!draftsChanged && !panelViewChanged) return;
+
+    bumpDraftMutationVersion(scopeKey);
+    bumpDraftUploadGeneration(scopeKey);
+
+    if (draftsChanged && nextDraftsByScope) {
+      setLatestAIDraftsByScopeSnapshot(nextDraftsByScope);
+      emitAIStateChanged(AI_STATE_CHANGED_DRAFTS_BY_SCOPE);
+    }
+
+    if (panelViewChanged && nextPanelViewByScope) {
+      setLatestAIPanelViewByScopeSnapshot(nextPanelViewByScope);
+      setPanelViewByScopeRaw(nextPanelViewByScope);
+      emitAIStateChanged(AI_STATE_CHANGED_PANEL_VIEW_BY_SCOPE);
+    }
+  }, [panelViewByScope]);
+
+  const addDraftFiles = useCallback(async (
+    scopeKey: string,
+    fallbackAgentId: string,
+    inputFiles: File[],
+  ) => {
+    ensureDraftForScope(scopeKey, fallbackAgentId);
+    const initialUploadGeneration = getDraftUploadGeneration(scopeKey);
+    const uploads = await convertFilesToUploads(inputFiles);
+    if (uploads.length === 0) return;
+
+    if (getDraftUploadGeneration(scopeKey) !== initialUploadGeneration) {
+      return;
+    }
+
+    updateDraftIfPresent(scopeKey, (draft) => ({
+      ...draft,
+      attachments: [...draft.attachments, ...uploads],
+    }));
+  }, [ensureDraftForScope, updateDraftIfPresent]);
+
+  const removeDraftFile = useCallback((scopeKey: string, fallbackAgentId: string, fileId: string) => {
+    updateDraft(scopeKey, fallbackAgentId, (draft) => ({
+      ...draft,
+      attachments: draft.attachments.filter((file) => file.id !== fileId),
+    }));
+  }, [updateDraft]);
+
   const cleanupOrphanedSessions = useCallback((activeTargetIds: Set<string>) => {
     cleanupOrphanedAISessions(activeTargetIds);
-    setSessionsRaw(latestAISessionsSnapshot ?? localStorageAdapter.read<AISession[]>(STORAGE_KEY_AI_SESSIONS) ?? []);
+
+    const nextSessions =
+      latestAISessionsSnapshot
+      ?? localStorageAdapter.read<AISession[]>(STORAGE_KEY_AI_SESSIONS)
+      ?? [];
+    sessionsRef.current = nextSessions;
+    setSessionsRaw(nextSessions);
     setActiveSessionIdMapRaw(
       latestAIActiveSessionMapSnapshot
         ?? localStorageAdapter.read<Record<string, string | null>>(STORAGE_KEY_AI_ACTIVE_SESSION_MAP)
         ?? {},
     );
+    setDraftsByScopeRaw(latestAIDraftsByScopeSnapshot ?? {});
+    setPanelViewByScopeRaw(latestAIPanelViewByScopeSnapshot ?? {});
   }, []);
 
   // ── Provider CRUD helpers ──
@@ -819,6 +1102,8 @@ export function useAIState() {
     // Permission model
     globalPermissionMode,
     setGlobalPermissionMode,
+    toolIntegrationMode,
+    setToolIntegrationMode,
     hostPermissions,
     setHostPermissions,
 
@@ -847,13 +1132,21 @@ export function useAIState() {
     // Sessions (per-scope active session)
     sessions,
     activeSessionIdMap,
+    draftsByScope,
+    panelViewByScope,
     setActiveSessionId,
+    ensureDraftForScope,
+    updateDraft,
+    showDraftView,
+    showSessionView,
+    clearDraftForScope,
+    addDraftFiles,
+    removeDraftFile,
     createSession,
     deleteSession,
     deleteSessionsByTarget,
     updateSessionTitle,
     updateSessionExternalSessionId,
-    retargetSessionScope,
     addMessageToSession,
     updateLastMessage,
     updateMessageById,

application/state/useApplicationBackend.ts

@@ -15,15 +15,15 @@ export type SshAgentStatus = {
 
 export const useApplicationBackend = () => {
   const openExternal = useCallback(async (url: string) => {
-    try {
-      const bridge = netcattyBridge.get();
-      if (bridge?.openExternal) {
-        await bridge.openExternal(url);
-        return;
-      }
-    } catch {
-      // Ignore and fall back below
+    const bridge = netcattyBridge.get();
+    if (bridge?.openExternal) {
+      // Bridge resolves on success (either via system browser or in-app
+      // fallback window) and rejects only when both paths fail. Let the
+      // rejection propagate so callers can present a user-facing message.
+      await bridge.openExternal(url);
+      return;
     }
+    // Fallback for non-Electron environments (tests, dev server, etc.).
     window.open(url, "_blank", "noopener,noreferrer");
   }, []);
 

application/state/useAutoSync.ts

@@ -16,8 +16,12 @@ import {
   findSyncPayloadEncryptedCredentialPaths,
 } from '../../domain/credentials';
 import { isProviderReadyForSync, type CloudProvider, type SyncPayload } from '../../domain/sync';
-import { collectSyncableSettings } from '../syncPayload';
-import { STORAGE_KEY_PORT_FORWARDING } from '../../infrastructure/config/storageKeys';
+import { collectSyncableSettings, hasMeaningfulSyncData } from '../syncPayload';
+import { readInterruptedVaultApply } from '../localVaultBackups';
+import {
+  STORAGE_KEY_PORT_FORWARDING,
+  STORAGE_KEY_VAULT_RESTORE_IN_PROGRESS_UNTIL,
+} from '../../infrastructure/config/storageKeys';
 import { localStorageAdapter } from '../../infrastructure/persistence/localStorageAdapter';
 import { getEffectiveKnownHosts } from '../../infrastructure/syncHelpers';
 import { notify } from '../notification';
@@ -35,15 +39,24 @@ interface AutoSyncConfig {
   groupConfigs?: SyncPayload['groupConfigs'];
   /** Opaque token that changes whenever a synced setting changes. */
   settingsVersion?: number;
+  startupReady?: boolean;
 
   // Callbacks
-  onApplyPayload: (payload: SyncPayload) => void;
+  onApplyPayload: (payload: SyncPayload) => void | Promise<void>;
 }
 
 // Get manager singleton for direct state access
 const manager = getCloudSyncManager();
 const AUTO_SYNC_PROVIDER_ORDER: CloudProvider[] = ['github', 'google', 'onedrive', 'webdav', 's3'];
 
+// Cross-window restore barrier: stored as an epoch-ms deadline. Any value
+// in the future means a restore is applying in some window and auto-sync
+// must not push concurrently.
+const isRestoreInProgress = (): boolean => {
+  const raw = localStorageAdapter.readNumber(STORAGE_KEY_VAULT_RESTORE_IN_PROGRESS_UNTIL);
+  return typeof raw === 'number' && raw > Date.now();
+};
+
 type SyncTrigger = 'auto' | 'manual';
 
 interface SyncNowOptions {
@@ -57,10 +70,27 @@ export const useAutoSync = (config: AutoSyncConfig) => {
   const syncTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const lastSyncedDataRef = useRef<string>('');
   const hasCheckedRemoteRef = useRef(false);
+  /** True once checkRemoteVersion has completed (success or failure). Until
+   *  this is set, the debounced auto-sync effect will not fire, preventing
+   *  an empty local vault from racing ahead and overwriting a non-empty
+   *  cloud vault before the startup pull has run. See #679. */
+  const remoteCheckDoneRef = useRef(false);
   const isInitializedRef = useRef(false);
   const isSyncRunningRef = useRef(false);
   const skipNextSyncRef = useRef(false);
 
+  // State for the empty-vault-vs-cloud confirmation dialog (Fix D).
+  // When checkRemoteVersion detects that the local vault is empty but
+  // the cloud has data, it pauses and exposes this state so the root
+  // component can render a confirmation dialog.
+  const [emptyVaultConflict, setEmptyVaultConflict] = useState<{
+    remotePayload: SyncPayload;
+    hostCount: number;
+    keyCount: number;
+    snippetCount: number;
+  } | null>(null);
+  const emptyVaultResolveRef = useRef<((action: 'restore' | 'keep-empty') => void) | null>(null);
+
   // Listen for SFTP bookmark changes to trigger auto-sync
   const [bookmarksVersion, setBookmarksVersion] = useState(0);
   useEffect(() => {
@@ -147,6 +177,50 @@ export const useAutoSync = (config: AutoSyncConfig) => {
         throw new Error(t('sync.autoSync.alreadySyncing'));
       }
 
+      // Cross-window guard: another window may be in the middle of
+      // applying a local vault restore. If we push right now we'd upload
+      // the pre-restore snapshot (the main window's React state hasn't
+      // observed the localStorage writes yet), clobbering the just-
+      // restored cloud copy. Skip silently on auto triggers and fail
+      // loudly on manual ones so the user understands why their click
+      // did nothing.
+      //
+      // Pairs with `withRestoreBarrier` in application/localVaultBackups.ts
+      // (the writer) and with the matching early-return in the
+      // debounced-sync effect below (the other reader, which prevents
+      // scheduling a push while the barrier is held).
+      if (isRestoreInProgress()) {
+        if (trigger === 'auto') {
+          console.info('[AutoSync] Skipping: a vault restore is in progress in another window.');
+          return;
+        }
+        throw new Error(t('sync.autoSync.restoreInProgress'));
+      }
+
+      // Refuse to auto-push when a previous apply crashed mid-way and
+      // left the vault in a partial state. `applyProtectedSyncPayload`
+      // sets a sentinel before its non-atomic localStorage writes and
+      // clears it on successful completion; the sentinel's presence
+      // here means the renderer crashed between a first write and the
+      // clean-up, so the in-memory payload is a mix of pre-apply and
+      // post-apply entries. Pushing that would silently overwrite an
+      // intact cloud copy with corrupted data.
+      //
+      // Manual triggers surface a user-visible error that points the
+      // user at the Restore UI; auto triggers return quietly (the
+      // next startup toast below flags the state).
+      const interruptedApply = readInterruptedVaultApply();
+      if (interruptedApply) {
+        if (trigger === 'auto') {
+          console.warn(
+            '[AutoSync] Skipping: previous apply was interrupted — refusing to push partial state.',
+            interruptedApply,
+          );
+          return;
+        }
+        throw new Error(t('sync.autoSync.interruptedApplyMessage'));
+      }
+
       // If another window unlocked, reuse the in-memory session password from main process.
       if (state.securityState !== 'UNLOCKED') {
         const bridge = netcattyBridge.get();
@@ -173,13 +247,28 @@ export const useAutoSync = (config: AutoSyncConfig) => {
         throw new Error(t('sync.credentialsUnavailable'));
       }
 
+      // Prevent pushing an empty vault to cloud. This is almost always
+      // a sign that the local state was lost (update, import failure,
+      // storage corruption) rather than a deliberate "delete everything".
+      // We only block auto-sync — manual trigger from Settings can still
+      // push if the user explicitly wants to.
+      //
+      // This pairs with the inspect-failure "fail open" behavior in
+      // checkRemoteVersion below: if inspect transiently errors we still
+      // let auto-sync run, trusting this guard to refuse if local is
+      // truly empty rather than letting an empty state clobber remote.
+      if (!hasMeaningfulSyncData(payload) && trigger === 'auto') {
+        console.warn('[AutoSync] Blocked: refusing to auto-sync an empty vault to cloud');
+        return;
+      }
+
       const results = await sync.syncNow(payload);
 
       // Apply merged payloads first (before checking for failures) so local
       // state gets updated even when some providers failed
       for (const result of results.values()) {
         if (result.mergedPayload) {
-          onApplyPayload(result.mergedPayload);
+          await Promise.resolve(onApplyPayload(result.mergedPayload));
           skipNextSyncRef.current = true;
           break; // All providers share the same merged payload
         }
@@ -195,6 +284,18 @@ export const useAutoSync = (config: AutoSyncConfig) => {
       }
 
       lastSyncedDataRef.current = dataHash;
+
+      // Successful sync implies a successful per-provider
+      // `checkProviderConflict` (which inspects remote) — equivalent
+      // to a successful startup reconciliation from the auto-sync
+      // gate's point of view. Opening the gate here is the escape
+      // hatch when a network outage exhausted the startup retry
+      // timer: a user-triggered manual sync (or any first successful
+      // auto sync that somehow ran anyway) resumes auto-sync for the
+      // rest of the session. Without this, a degraded-startup session
+      // would require the user to manually sync after every edit.
+      hasCheckedRemoteRef.current = true;
+      remoteCheckDoneRef.current = true;
     } catch (error) {
       if (trigger === 'manual') {
         throw error;
@@ -208,46 +309,219 @@ export const useAutoSync = (config: AutoSyncConfig) => {
       isSyncRunningRef.current = false;
     }
   }, [sync, buildPayload, getDataHash, onApplyPayload, t]);
-  
+
+  // One-shot toast per mount when a previous apply was interrupted, so the
+  // user understands why auto-sync is silently paused and where to go to
+  // recover. `applyProtectedSyncPayload` clears the sentinel on a clean
+  // apply, so this only fires once per genuine crash and naturally stops
+  // after the user completes a recovery.
+  const interruptedApplyNotifiedRef = useRef(false);
+  useEffect(() => {
+    if (interruptedApplyNotifiedRef.current) return;
+    if (!sync.isUnlocked) return;
+    const interrupted = readInterruptedVaultApply();
+    if (!interrupted) return;
+    interruptedApplyNotifiedRef.current = true;
+    notify.error(
+      t('sync.autoSync.interruptedApplyMessage'),
+      t('sync.autoSync.interruptedApplyTitle'),
+    );
+  }, [sync.isUnlocked, t]);
+
+  // Stabilize the fields `checkRemoteVersion` reads from `config`.
+  // AutoSyncConfig is a fresh object literal on every App render, so a
+  // naive `config` dep would rebuild `checkRemoteVersion`'s identity on
+  // every unrelated state change — re-firing the retry effect with
+  // `attempt=0` and spawning overlapping in-flight inspections. The
+  // refs below let `checkRemoteVersion` read the latest callback and
+  // readiness flag without pulling the object identity into deps.
+  const onApplyPayloadRef = useRef(config.onApplyPayload);
+  useEffect(() => {
+    onApplyPayloadRef.current = config.onApplyPayload;
+  }, [config.onApplyPayload]);
+  const startupReadyRef = useRef(config.startupReady);
+  useEffect(() => {
+    startupReadyRef.current = config.startupReady;
+  }, [config.startupReady]);
+  // `buildPayload` closes over live React state so its identity flips
+  // on every vault edit; route it through a ref so `checkRemoteVersion`
+  // can read the latest builder without churning its memo identity.
+  const buildPayloadRef = useRef(buildPayload);
+  useEffect(() => {
+    buildPayloadRef.current = buildPayload;
+  }, [buildPayload]);
+
+  // Serialize `checkRemoteVersion` invocations. Overlapping runs would
+  // race on `commitRemoteInspection` + `onApplyPayload`: two merges
+  // could both write-then-clear the apply-in-progress sentinel around
+  // interleaved applies, and both could push post-merge snapshots to
+  // remote. The cross-window `withRestoreBarrier` protects other
+  // windows but does NOT serialize same-window re-entry, so this
+  // in-flight guard closes that gap at the top of the call.
+  const checkRemoteInFlightRef = useRef(false);
+
   // Check remote version and pull if newer (on startup)
   const checkRemoteVersion = useCallback(async () => {
+    if (checkRemoteInFlightRef.current) {
+      return;
+    }
     const state = manager.getState();
     const hasProvider = Object.values(state.providers).some((provider) => isProviderReadyForSync(provider));
     const unlocked = state.securityState === 'UNLOCKED';
-    
-    if (!hasProvider || !unlocked || hasCheckedRemoteRef.current) {
+
+    if (!hasProvider || !unlocked || hasCheckedRemoteRef.current || startupReadyRef.current === false) {
       return;
     }
-    
-    hasCheckedRemoteRef.current = true;
-    
-    // Find connected provider
+
+    // Find connected provider BEFORE acquiring the in-flight lock so the
+    // "nothing to check" early return doesn't leak the lock and wedge
+    // the retry timer. Any path that takes the lock MUST reach the
+    // finally-release below.
     const connectedProvider = AUTO_SYNC_PROVIDER_ORDER.find((provider) =>
       isProviderReadyForSync(state.providers[provider]),
     ) ?? null;
-    
-    if (!connectedProvider) return;
-    
+
+    if (!connectedProvider) {
+      // Nothing to check — mark as done so the auto-sync gate opens.
+      remoteCheckDoneRef.current = true;
+      return;
+    }
+
+    checkRemoteInFlightRef.current = true;
+
+    // Track whether the startup path completed in a state where the anchor/base
+    // are consistent with the local vault. Only then should we latch
+    // hasCheckedRemoteRef so that transient failures are retryable.
+    let startupConsistent = false;
     try {
-      // Load base BEFORE downloading (downloadFromProvider overwrites the base)
+      // Load base BEFORE observing the remote payload (commitRemoteInspection overwrites the base).
       const base = await manager.loadSyncBase(connectedProvider);
-      const remotePayload = await sync.downloadFromProvider(connectedProvider);
+      const inspection = await manager.inspectProviderRemote(connectedProvider);
 
-      if (remotePayload && remotePayload.syncedAt > state.localUpdatedAt) {
-        const { mergeSyncPayloads } = await import('../../domain/syncMerge');
-        const localPayload = buildPayload();
-        const mergeResult = mergeSyncPayloads(base, localPayload, remotePayload);
+      if (!inspection.payload || !inspection.remoteChanged || !inspection.remoteFile) {
+        // Remote unchanged (or empty) — no local mutation needed; anchor/base
+        // are already in sync with remote from a previous run.
+        startupConsistent = true;
+        return;
+      }
 
-        config.onApplyPayload(mergeResult.payload);
-        // Don't save base or skip auto-sync — let the data-change effect
-        // naturally trigger an upload of the merged payload (which will
-        // go through syncAllProviders and save base on success).
-        notify.success(t('sync.autoSync.syncedMessage'), t('sync.autoSync.syncedTitle'));
+      const remoteFile = inspection.remoteFile;
+      const remotePayload = inspection.payload;
+      const localPayload = buildPayloadRef.current();
+      const localIsEmpty = !hasMeaningfulSyncData(localPayload);
+      const remoteHasData = hasMeaningfulSyncData(remotePayload);
+
+      // If local vault is empty but cloud has data, this almost certainly
+      // means the user's data was lost (update, storage corruption, etc.).
+      // Pause and ask the user what to do instead of silently merging.
+      if (localIsEmpty && remoteHasData) {
+        const userAction = await new Promise<'restore' | 'keep-empty'>((resolve) => {
+          emptyVaultResolveRef.current = resolve;
+          setEmptyVaultConflict({
+            remotePayload,
+            hostCount: remotePayload.hosts?.length ?? 0,
+            keyCount: remotePayload.keys?.length ?? 0,
+            snippetCount: remotePayload.snippets?.length ?? 0,
+          });
+        });
+        setEmptyVaultConflict(null);
+        emptyVaultResolveRef.current = null;
+
+        if (userAction === 'restore') {
+          // Apply remote FIRST; only commit anchor/base after the UI-side
+          // state has accepted the remote payload, otherwise a failure
+          // between commit and apply would leave the anchor pointing at
+          // remote while local is still empty — the exact overwrite window
+          // we're trying to close.
+          await Promise.resolve(onApplyPayloadRef.current(remotePayload));
+          await manager.commitRemoteInspection(connectedProvider, remoteFile, remotePayload);
+          skipNextSyncRef.current = true;
+          startupConsistent = true;
+          notify.success(t('sync.autoSync.restoredMessage'), t('sync.autoSync.restoredTitle'));
+        } else {
+          // User chose to keep the empty vault. Deliberately do NOT advance
+          // the anchor or base — the next sync must still treat remote as
+          // "unseen" so the empty-vault-push guard (`hasMeaningfulSyncData`)
+          // keeps protecting the cloud copy. startupConsistent stays false
+          // so hasCheckedRemoteRef is not latched and the next startup will
+          // re-prompt if the user still has not added anything.
+          notify.info(t('sync.autoSync.keptLocalMessage'), t('sync.autoSync.keptLocalTitle'));
+        }
+        return;
+      }
+
+      const { mergeSyncPayloads } = await import('../../domain/syncMerge');
+      const mergeResult = mergeSyncPayloads(base, localPayload, remotePayload);
+
+      // Apply merged payload to local state BEFORE committing. If the apply
+      // throws, the next startup will re-run the merge with fresh data.
+      await Promise.resolve(onApplyPayloadRef.current(mergeResult.payload));
+      // Base is the last-agreed remote snapshot; `commitRemoteInspection`
+      // stores remotePayload as the base so the next diff is computed
+      // against what the cloud actually has, not against the merged
+      // local-only state.
+      await manager.commitRemoteInspection(connectedProvider, remoteFile, remotePayload);
+      startupConsistent = true;
+      notify.success(t('sync.autoSync.syncedMessage'), t('sync.autoSync.syncedTitle'));
+
+      // If the three-way merge introduced any local-only additions that the
+      // remote does not yet have, we MUST round-trip those to the cloud.
+      // Previously this branch stopped after applying merge locally, so the
+      // merged-in additions lived only on the device that ran the merge
+      // until the user's next edit.
+      //
+      // We push the merged payload *directly* through the manager rather
+      // than going through the React-state-driven `syncNow`. syncNow
+      // rebuilds the payload from hooks state, which may not yet reflect
+      // the onApplyPayload we awaited above (React commit phase is async
+      // relative to the awaited promise resolution). Passing mergeResult
+      // in explicitly removes the race entirely and avoids a setTimeout(0)
+      // that only approximated the correct ordering.
+      if (mergeResult.payload) {
+        try {
+          await manager.syncAllProviders(mergeResult.payload);
+          // Suppress the debounced follow-up tick that otherwise fires
+          // once React commits the applied state, since we've just
+          // already pushed that exact payload upstream.
+          skipNextSyncRef.current = true;
+        } catch (error) {
+          // Non-fatal: the next user edit will drive another sync cycle.
+          console.warn('[AutoSync] Post-merge round-trip push failed:', error);
+        }
       }
     } catch (error) {
       console.error('[AutoSync] Failed to check remote version:', error);
+      // Surface a degraded-sync hint to the user rather than silently
+      // opening the auto-sync gate. Auto-sync will still retry on next
+      // data change (see finally block), but without this toast the user
+      // has no visible signal that startup reconciliation failed.
+      notify.error(
+        t('sync.autoSync.inspectFailedMessage'),
+        t('sync.autoSync.inspectFailedTitle'),
+      );
+      // Leave hasCheckedRemoteRef=false so the next startup (or the next
+      // provider/unlock transition) can retry.
+    } finally {
+      if (startupConsistent) {
+        hasCheckedRemoteRef.current = true;
+        // Only open the auto-sync gate when the inspect actually
+        // validated the remote state. Leaving the gate closed on
+        // inspect failure is intentional: an edit made during a
+        // degraded startup must not race ahead and push a partially-
+        // hydrated vault over an intact remote. The retry effect
+        // below re-fires checkRemoteVersion on the next provider/
+        // unlock/startupReady transition, and a manual sync from
+        // Settings remains available as an escape hatch.
+        remoteCheckDoneRef.current = true;
+      }
+      checkRemoteInFlightRef.current = false;
     }
-  }, [sync, config, buildPayload, t]);
+    // Intentionally minimal deps: `buildPayload`, `config.onApplyPayload`,
+    // and `config.startupReady` are read through refs above so their
+    // identity flips (every vault edit produces a fresh `buildPayload`
+    // and a fresh AutoSyncConfig literal) cannot re-memoize this
+    // callback and restart the retry-timer's exponential backoff.
+  }, [t]);
   
   // Debounced auto-sync when data changes
   useEffect(() => {
@@ -255,7 +529,15 @@ export const useAutoSync = (config: AutoSyncConfig) => {
     if (!sync.hasAnyConnectedProvider || !sync.autoSyncEnabled || !sync.isUnlocked) {
       return;
     }
-    
+
+    // Don't auto-sync until the startup remote check has completed.
+    // Without this gate, an empty local vault can push to the cloud
+    // before checkRemoteVersion even runs, overwriting a non-empty
+    // remote vault — the exact bug described in #679.
+    if (!remoteCheckDoneRef.current) {
+      return;
+    }
+
     // Skip initial render
     if (!isInitializedRef.current) {
       isInitializedRef.current = true;
@@ -283,6 +565,23 @@ export const useAutoSync = (config: AutoSyncConfig) => {
     if (sync.isSyncing || isSyncRunningRef.current) {
       return;
     }
+
+    // Hold off on scheduling a new push while another window is applying
+    // a restore — the restore is about to land via localStorage and the
+    // debounce-fired syncNow would otherwise race it. The next data-
+    // change tick after the restore barrier clears will re-enter here.
+    if (isRestoreInProgress()) {
+      return;
+    }
+
+    // Don't even schedule a push while the apply-in-progress sentinel
+    // is held. The syncNow path re-checks and refuses too, but dropping
+    // the debounced schedule here avoids spinning a 3-second timer for
+    // every keystroke while the user is in the Restore UI working
+    // through recovery.
+    if (readInterruptedVaultApply()) {
+      return;
+    }
     
     // Clear existing timeout
     if (syncTimeoutRef.current) {
@@ -301,31 +600,111 @@ export const useAutoSync = (config: AutoSyncConfig) => {
     };
   }, [sync.hasAnyConnectedProvider, sync.autoSyncEnabled, sync.isUnlocked, sync.isSyncing, getDataHash, syncNow, config.settingsVersion, bookmarksVersion]);
   
-  // Check remote version on startup/unlock
+  // Check remote version on startup/unlock, then retry with backoff
+  // while the inspect keeps failing. Without the timer-based retry,
+  // a failure that doesn't coincide with a dep change would wedge the
+  // auto-sync gate closed until the user restarts or manually triggers
+  // sync from Settings — the 30s/60s/90s cadence below lets a short
+  // outage (network blip, provider rate-limit) self-heal.
   useEffect(() => {
-    if (sync.hasAnyConnectedProvider && sync.isUnlocked && !hasCheckedRemoteRef.current) {
-      // Delay check to ensure everything is loaded
-      const timer = setTimeout(() => {
-        checkRemoteVersion();
-      }, 1000);
-      
-      return () => clearTimeout(timer);
+    if (
+      !sync.hasAnyConnectedProvider ||
+      !sync.isUnlocked ||
+      hasCheckedRemoteRef.current ||
+      config.startupReady === false
+    ) {
+      return;
     }
-  }, [sync.hasAnyConnectedProvider, sync.isUnlocked, checkRemoteVersion]);
+
+    let cancelled = false;
+    let attempt = 0;
+    let timerId: NodeJS.Timeout | null = null;
+
+    const tick = () => {
+      if (cancelled) return;
+      void (async () => {
+        await checkRemoteVersion();
+        if (cancelled || hasCheckedRemoteRef.current) return;
+        // Cap retries at ~5 minutes total (30s + 60s + 120s + 240s). A
+        // persistent failure beyond that is almost certainly a
+        // misconfiguration that needs user action rather than more
+        // auto-retries.
+        //
+        // When retries exhaust we deliberately leave the auto-sync gate
+        // CLOSED. Opening it here would allow a partially-lost local
+        // vault to silently clobber an unchanged remote: anchor still
+        // matches, `checkProviderConflict` sees no remote change,
+        // `hasMeaningfulSyncData` doesn't flag non-empty-but-partial
+        // local, and the empty-vault prompt never fires.
+        //
+        // Escape hatch: a successful manual sync from Settings opens
+        // the gate via `syncNow`'s success path. That path runs the
+        // same per-provider inspect we use here, so a successful
+        // manual sync is equivalent to a successful startup inspect
+        // from the gate's point of view — the user's explicit click
+        // authorizes both the push and the subsequent auto-sync
+        // resumption. Until then, auto-sync stays paused and the
+        // "sync paused" toast is the user's signal to act.
+        if (attempt >= 4) return;
+        const delayMs = Math.min(240_000, 30_000 * 2 ** attempt);
+        attempt += 1;
+        timerId = setTimeout(tick, delayMs);
+      })();
+    };
+
+    tick();
+
+    return () => {
+      cancelled = true;
+      if (timerId) clearTimeout(timerId);
+    };
+  }, [sync.hasAnyConnectedProvider, sync.isUnlocked, config.startupReady, checkRemoteVersion]);
   
-  // Reset check flag when provider disconnects
+  // Reset check flags when provider disconnects
   useEffect(() => {
     if (!sync.hasAnyConnectedProvider) {
       hasCheckedRemoteRef.current = false;
+      remoteCheckDoneRef.current = false;
     }
   }, [sync.hasAnyConnectedProvider]);
+
+  // On unmount, release any pending empty-vault confirmation. Without
+  // this, an unmount mid-dialog (window close, workspace switch) leaves
+  // the resolver promise dangling forever and the `checkRemoteVersion`
+  // finally block never sets remoteCheckDoneRef — in practice React
+  // tears down the hook first, but leaking the resolve callback and
+  // referenced remotePayload keeps them pinned by the awaiter until
+  // the next reload. Resolving with 'keep-empty' is the safe default:
+  // it mirrors the "don't touch remote" choice and leaves the version
+  // stamp untouched so the next mount re-prompts.
+  useEffect(() => {
+    return () => {
+      const resolve = emptyVaultResolveRef.current;
+      if (resolve) {
+        emptyVaultResolveRef.current = null;
+        resolve('keep-empty');
+      }
+    };
+  }, []);
   
+  const resolveEmptyVaultConflict = useCallback((action: 'restore' | 'keep-empty') => {
+    // Guard: resolve only once (prevents double-click from entering an
+    // inconsistent state). The ref is nulled immediately so subsequent
+    // calls are no-ops.
+    const resolve = emptyVaultResolveRef.current;
+    if (!resolve) return;
+    emptyVaultResolveRef.current = null;
+    resolve(action);
+  }, []);
+
   return {
     syncNow,
     buildPayload,
     isSyncing: sync.isSyncing,
     isConnected: sync.hasAnyConnectedProvider,
     autoSyncEnabled: sync.autoSyncEnabled,
+    emptyVaultConflict,
+    resolveEmptyVaultConflict,
   };
 };
 

application/state/useCloudSync.ts

@@ -90,7 +90,21 @@ export interface CloudSyncHook {
   syncToProvider: (provider: CloudProvider, payload: SyncPayload) => Promise<SyncResult>;
   downloadFromProvider: (provider: CloudProvider) => Promise<SyncPayload | null>;
   resolveConflict: (resolution: ConflictResolution) => Promise<SyncPayload | null>;
-  
+
+  // Gist Revision History
+  getGistRevisionHistory: () => Promise<Array<{ version: string; date: Date }>>;
+  downloadGistRevision: (sha: string) => Promise<{
+    payload: SyncPayload;
+    meta: import('../../domain/sync').SyncFileMeta;
+    preview: {
+      hostCount: number;
+      keyCount: number;
+      snippetCount: number;
+      identityCount: number;
+      portForwardingRuleCount: number;
+    };
+  } | null>;
+
   // Settings
   setAutoSync: (enabled: boolean, intervalMinutes?: number) => void;
   setDeviceName: (name: string) => void;
@@ -475,6 +489,10 @@ export const useCloudSync = (): CloudSyncHook => {
     syncToProvider: syncToProviderWithUnlock,
     downloadFromProvider: downloadFromProviderWithUnlock,
     resolveConflict: resolveConflictWithUnlock,
+
+    // Gist Revision History (#679)
+    getGistRevisionHistory: manager.getGistRevisionHistory.bind(manager),
+    downloadGistRevision: manager.downloadGistRevision.bind(manager),
     
     // Settings
     setAutoSync,

application/state/useFileUpload.ts

@@ -1,20 +1,13 @@
 /**
- * useFileUpload - Handle file paste/drop with base64 conversion
+ * File upload conversion helpers for AI draft attachments.
  *
  * Supports images, PDFs, and other document types.
  * Ported from 1code's use-agents-file-upload.ts
  */
-import { useCallback, useState } from 'react';
+import type { UploadedFile } from '../../infrastructure/ai/types';
 import { getPathForFile } from '../../lib/sftpFileUtils';
 
-export interface UploadedFile {
-  id: string;
-  filename: string;
-  dataUrl: string;      // data:...;base64,... for preview
-  base64Data: string;   // raw base64 for API
-  mediaType: string;    // MIME type e.g. "image/png", "application/pdf"
-  filePath?: string;    // original filesystem path (Electron only)
-}
+export type { UploadedFile } from '../../infrastructure/ai/types';
 
 /** Reject only known binary blobs that AI models can't process */
 const REJECTED_MIME_PREFIXES = ['video/', 'audio/'];
@@ -38,42 +31,32 @@ async function fileToDataUrl(file: File): Promise<{ dataUrl: string; base64: str
   });
 }
 
-export function useFileUpload() {
-  const [files, setFiles] = useState<UploadedFile[]>([]);
+export async function convertFilesToUploads(inputFiles: File[]): Promise<UploadedFile[]> {
+  const supported = inputFiles.filter(isSupportedFile);
+  if (supported.length === 0) return [];
 
-  const addFiles = useCallback(async (inputFiles: File[]) => {
-    const supported = inputFiles.filter(isSupportedFile);
-    if (supported.length === 0) return;
-
-    const newFiles: UploadedFile[] = await Promise.all(
-      supported.map(async (file) => {
-        const id = crypto.randomUUID();
-        const filename = file.name || `file-${Date.now()}`;
-        const mediaType = file.type || 'application/octet-stream';
-        let dataUrl = '';
-        let base64Data = '';
-        try {
-          const result = await fileToDataUrl(file);
-          dataUrl = result.dataUrl;
-          base64Data = result.base64;
-        } catch (err) {
-          console.error('[useFileUpload] Failed to convert:', err);
-        }
+  const uploads: Array<UploadedFile | null> = await Promise.all(
+    supported.map(async (file) => {
+      const id = crypto.randomUUID();
+      const filename = file.name || `file-${Date.now()}`;
+      const mediaType = file.type || 'application/octet-stream';
+      try {
+        const result = await fileToDataUrl(file);
         const filePath = getPathForFile(file);
-        return { id, filename, dataUrl, base64Data, mediaType, filePath };
-      }),
-    );
+        return {
+          id,
+          filename,
+          dataUrl: result.dataUrl,
+          base64Data: result.base64,
+          mediaType,
+          filePath,
+        };
+      } catch (err) {
+        console.error('[useFileUpload] Failed to convert:', err);
+        return null;
+      }
+    }),
+  );
 
-    setFiles((prev) => [...prev, ...newFiles]);
-  }, []);
-
-  const removeFile = useCallback((id: string) => {
-    setFiles((prev) => prev.filter((f) => f.id !== id));
-  }, []);
-
-  const clearFiles = useCallback(() => {
-    setFiles([]);
-  }, []);
-
-  return { files, addFiles, removeFile, clearFiles };
+  return uploads.filter((upload): upload is UploadedFile => upload !== null);
 }

application/state/useGlobalHotkeys.ts

@@ -77,6 +77,7 @@ export const getTerminalPassthroughActions = (): Set<string> => {
   return new Set([
     'copy',
     'paste',
+    'pasteSelection',
     'selectAll',
     'clearBuffer',
     'searchTerminal',

application/state/useImmersiveMode.ts

@@ -144,6 +144,7 @@ function applyImmersiveStyle(css: string, isDark: boolean, bg: string) {
 
 function removeImmersiveStyle() {
   document.getElementById(STYLE_ID)?.remove();
+  delete document.documentElement.dataset.immersiveTheme;
 }
 
 // ---------------------------------------------------------------------------
@@ -174,6 +175,7 @@ export function useImmersiveMode({
       overrideActiveRef.current = true;
       appliedFpRef.current = fp;
       applyImmersiveStyle(getImmersiveCss(activeTerminalTheme), activeTerminalTheme.type === 'dark', activeTerminalTheme.colors.background);
+      document.documentElement.dataset.immersiveTheme = fp;
     }
   }, [isTerminalTab, activeTerminalTheme]);
 

application/state/useLocalVaultBackups.ts

@@ -0,0 +1,95 @@
+import { useCallback, useEffect, useState } from 'react';
+import {
+  type LocalVaultBackupPreview,
+  getLocalVaultBackupCapabilities,
+  getLocalVaultBackupMaxCount,
+  listLocalVaultBackups,
+  openLocalVaultBackupDir,
+  readLocalVaultBackup,
+  setLocalVaultBackupMaxCount,
+  trimLocalVaultBackups,
+} from '../localVaultBackups';
+import { netcattyBridge } from '../../infrastructure/services/netcattyBridge';
+
+export function useLocalVaultBackups() {
+  const [backups, setBackups] = useState<LocalVaultBackupPreview[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [maxBackups, setMaxBackupsState] = useState(() => getLocalVaultBackupMaxCount());
+  // `null` while we're still asking the main process. The UI should treat
+  // `null` as "unknown, don't render restore controls yet" so we never expose
+  // a destructive action that might later be disabled.
+  const [encryptionAvailable, setEncryptionAvailable] = useState<boolean | null>(null);
+
+  const refreshBackups = useCallback(async () => {
+    setIsLoading(true);
+    try {
+      const next = await listLocalVaultBackups();
+      setBackups(next);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const caps = await getLocalVaultBackupCapabilities();
+        if (!cancelled) {
+          setEncryptionAvailable(caps.encryptionAvailable);
+        }
+      } catch {
+        if (!cancelled) {
+          setEncryptionAvailable(false);
+        }
+      }
+    })();
+    void refreshBackups();
+    return () => {
+      cancelled = true;
+    };
+  }, [refreshBackups]);
+
+  // Cross-window live refresh: the main process broadcasts when any
+  // renderer's createBackup or trimBackups actually mutated the on-disk
+  // set. Without this subscription, a protective backup written by the
+  // main window wouldn't show up in the Settings window's list until
+  // the user manually navigated away and back, silently under-reporting
+  // the most recent recovery points.
+  useEffect(() => {
+    const bridge = netcattyBridge.get();
+    const subscribe = bridge?.onVaultBackupsChanged;
+    if (typeof subscribe !== 'function') return undefined;
+    const unsubscribe = subscribe(() => {
+      void refreshBackups();
+    });
+    return () => {
+      try { unsubscribe?.(); } catch { /* ignore */ }
+    };
+  }, [refreshBackups]);
+
+  const updateMaxBackups = useCallback(async (value: number) => {
+    const sanitized = setLocalVaultBackupMaxCount(value);
+    setMaxBackupsState(sanitized);
+    await trimLocalVaultBackups(sanitized);
+    await refreshBackups();
+    return sanitized;
+  }, [refreshBackups]);
+
+  const openBackupDirectory = useCallback(async () => {
+    await openLocalVaultBackupDir();
+  }, []);
+
+  return {
+    backups,
+    isLoading,
+    maxBackups,
+    encryptionAvailable,
+    refreshBackups,
+    readBackup: readLocalVaultBackup,
+    setMaxBackups: updateMaxBackups,
+    openBackupDirectory,
+  };
+}
+
+export default useLocalVaultBackups;

application/state/useSettingsState.ts

@@ -4,6 +4,7 @@ import {
   STORAGE_KEY_COLOR,
   STORAGE_KEY_SYNC,
   STORAGE_KEY_TERM_THEME,
+  STORAGE_KEY_TERM_FOLLOW_APP_THEME,
   STORAGE_KEY_THEME,
   STORAGE_KEY_TERM_FONT_FAMILY,
   STORAGE_KEY_TERM_FONT_SIZE,
@@ -33,10 +34,13 @@ import {
   STORAGE_KEY_GLOBAL_HOTKEY_ENABLED,
   STORAGE_KEY_AUTO_UPDATE_ENABLED,
   STORAGE_KEY_WORKSPACE_FOCUS_STYLE,
-
+  STORAGE_KEY_SHOW_RECENT_HOSTS,
+  STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT,
+  STORAGE_KEY_SHOW_SFTP_TAB,
 } from '../../infrastructure/config/storageKeys';
 import { DEFAULT_UI_LOCALE, resolveSupportedLocale } from '../../infrastructure/config/i18n';
 import { TERMINAL_THEMES } from '../../infrastructure/config/terminalThemes';
+import { getTerminalThemeForUiTheme } from '../../domain/terminalAppearance';
 import { customThemeStore, useCustomThemes } from '../state/customThemeStore';
 import { DEFAULT_FONT_SIZE } from '../../infrastructure/config/fonts';
 import { DARK_UI_THEMES, LIGHT_UI_THEMES, UiThemeTokens, getUiThemeById } from '../../infrastructure/config/uiThemes';
@@ -69,6 +73,9 @@ const DEFAULT_SFTP_SHOW_HIDDEN_FILES = false;
 const DEFAULT_SFTP_USE_COMPRESSED_UPLOAD = true;
 const DEFAULT_SFTP_AUTO_OPEN_SIDEBAR = false;
 const DEFAULT_SFTP_DEFAULT_VIEW_MODE: 'list' | 'tree' = 'list';
+const DEFAULT_SHOW_RECENT_HOSTS = true;
+const DEFAULT_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT = false;
+const DEFAULT_SHOW_SFTP_TAB = true;
 
 // Editor defaults
 const DEFAULT_EDITOR_WORD_WRAP = false;
@@ -195,6 +202,17 @@ export const useSettingsState = () => {
   });
   const [syncConfig, setSyncConfig] = useState<SyncConfig | null>(() => localStorageAdapter.read<SyncConfig>(STORAGE_KEY_SYNC));
   const [terminalThemeId, setTerminalThemeId] = useState<string>(() => localStorageAdapter.readString(STORAGE_KEY_TERM_THEME) || DEFAULT_TERMINAL_THEME);
+  const [followAppTerminalTheme, setFollowAppTerminalThemeState] = useState<boolean>(() => {
+    const stored = localStorageAdapter.readString(STORAGE_KEY_TERM_FOLLOW_APP_THEME);
+    if (stored !== null) return stored === 'true';
+    // First time seeing this key. For genuinely fresh installs (no existing
+    // terminal theme in storage) default ON so the terminal matches the app
+    // theme out of the box. For upgrades from an older version (existing
+    // terminal theme present) default OFF to avoid silently overriding the
+    // user's manual choice.
+    const isUpgrade = !!localStorageAdapter.readString(STORAGE_KEY_TERM_THEME);
+    return !isUpgrade;
+  });
   const [terminalFontFamilyId, setTerminalFontFamilyId] = useState<string>(() => localStorageAdapter.readString(STORAGE_KEY_TERM_FONT_FAMILY) || DEFAULT_FONT_FAMILY);
   const [terminalFontSize, setTerminalFontSize] = useState<number>(() => localStorageAdapter.readNumber(STORAGE_KEY_TERM_FONT_SIZE) || DEFAULT_FONT_SIZE);
   const [uiLanguage, setUiLanguage] = useState<UILanguage>(() => {
@@ -247,6 +265,18 @@ export const useSettingsState = () => {
     const stored = readStoredString(STORAGE_KEY_SFTP_DEFAULT_VIEW_MODE);
     return (stored === 'list' || stored === 'tree') ? stored : DEFAULT_SFTP_DEFAULT_VIEW_MODE;
   });
+  const [showRecentHosts, setShowRecentHostsState] = useState<boolean>(() => {
+    const stored = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_RECENT_HOSTS);
+    return stored ?? DEFAULT_SHOW_RECENT_HOSTS;
+  });
+  const [showOnlyUngroupedHostsInRoot, setShowOnlyUngroupedHostsInRootState] = useState<boolean>(() => {
+    const stored = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT);
+    return stored ?? DEFAULT_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT;
+  });
+  const [showSftpTab, setShowSftpTabState] = useState<boolean>(() => {
+    const stored = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_SFTP_TAB);
+    return stored ?? DEFAULT_SHOW_SFTP_TAB;
+  });
   const [sftpTransferConcurrency, setSftpTransferConcurrencyState] = useState<number>(() => {
     const stored = localStorageAdapter.readNumber(STORAGE_KEY_SFTP_TRANSFER_CONCURRENCY);
     return stored != null && stored >= 1 && stored <= 16 ? stored : 4;
@@ -450,6 +480,12 @@ export const useSettingsState = () => {
     if (storedAutoOpenSidebar === 'true' || storedAutoOpenSidebar === 'false') setSftpAutoOpenSidebar(storedAutoOpenSidebar === 'true');
     const storedDefaultViewMode = readStoredString(STORAGE_KEY_SFTP_DEFAULT_VIEW_MODE);
     if (storedDefaultViewMode === 'list' || storedDefaultViewMode === 'tree') setSftpDefaultViewMode(storedDefaultViewMode);
+    const storedShowRecentHosts = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_RECENT_HOSTS);
+    setShowRecentHostsState(storedShowRecentHosts ?? DEFAULT_SHOW_RECENT_HOSTS);
+    const storedShowOnlyUngroupedHostsInRoot = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT);
+    setShowOnlyUngroupedHostsInRootState(storedShowOnlyUngroupedHostsInRoot ?? DEFAULT_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT);
+    const storedShowSftpTab = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_SFTP_TAB);
+    setShowSftpTabState(storedShowSftpTab ?? DEFAULT_SHOW_SFTP_TAB);
 
     // Workspace focus style
     const storedFocusStyle = readStoredString(STORAGE_KEY_WORKSPACE_FOCUS_STYLE);
@@ -539,6 +575,10 @@ export const useSettingsState = () => {
       if (key === STORAGE_KEY_TERM_THEME && typeof value === 'string') {
         setTerminalThemeId(value);
       }
+      if (key === STORAGE_KEY_TERM_FOLLOW_APP_THEME) {
+        const next = value === true || value === 'true';
+        setFollowAppTerminalThemeState((prev) => (prev === next ? prev : next));
+      }
       if (key === STORAGE_KEY_TERM_FONT_FAMILY && typeof value === 'string') {
         setTerminalFontFamilyId(value);
       }
@@ -642,18 +682,20 @@ export const useSettingsState = () => {
   const settingsSnapshotRef = useRef({
     theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent,
     customCSS, uiFontFamilyId, hotkeyScheme, uiLanguage,
-    terminalThemeId, terminalFontFamilyId, terminalFontSize,
+    terminalThemeId, followAppTerminalTheme, terminalFontFamilyId, terminalFontSize,
     sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles,
     sftpUseCompressedUpload, sftpAutoOpenSidebar, sftpDefaultViewMode,
+    showRecentHosts, showOnlyUngroupedHostsInRoot, showSftpTab,
     editorWordWrap, sessionLogsEnabled, sessionLogsDir, sessionLogsFormat,
     globalHotkeyEnabled, autoUpdateEnabled,
   });
   settingsSnapshotRef.current = {
     theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent,
     customCSS, uiFontFamilyId, hotkeyScheme, uiLanguage,
-    terminalThemeId, terminalFontFamilyId, terminalFontSize,
+    terminalThemeId, followAppTerminalTheme, terminalFontFamilyId, terminalFontSize,
     sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles,
     sftpUseCompressedUpload, sftpAutoOpenSidebar, sftpDefaultViewMode,
+    showRecentHosts, showOnlyUngroupedHostsInRoot, showSftpTab,
     editorWordWrap, sessionLogsEnabled, sessionLogsDir, sessionLogsFormat,
     globalHotkeyEnabled, autoUpdateEnabled,
   };
@@ -732,6 +774,13 @@ export const useSettingsState = () => {
           setTerminalThemeId(e.newValue);
         }
       }
+      // Sync follow-app-theme toggle from other windows
+      if (e.key === STORAGE_KEY_TERM_FOLLOW_APP_THEME && e.newValue) {
+        const next = e.newValue === 'true';
+        if (next !== s.followAppTerminalTheme) {
+          setFollowAppTerminalThemeState(next);
+        }
+      }
       // Sync terminal font family from other windows
       if (e.key === STORAGE_KEY_TERM_FONT_FAMILY && e.newValue) {
         if (e.newValue !== s.terminalFontFamilyId) {
@@ -810,6 +859,24 @@ export const useSettingsState = () => {
           setSftpDefaultViewMode(e.newValue);
         }
       }
+      if (e.key === STORAGE_KEY_SHOW_RECENT_HOSTS && e.newValue !== null) {
+        const newValue = e.newValue === 'true';
+        if (newValue !== s.showRecentHosts) {
+          setShowRecentHostsState(newValue);
+        }
+      }
+      if (e.key === STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT && e.newValue !== null) {
+        const newValue = e.newValue === 'true';
+        if (newValue !== s.showOnlyUngroupedHostsInRoot) {
+          setShowOnlyUngroupedHostsInRootState(newValue);
+        }
+      }
+      if (e.key === STORAGE_KEY_SHOW_SFTP_TAB && e.newValue !== null) {
+        const newValue = e.newValue === 'true';
+        if (newValue !== s.showSftpTab) {
+          setShowSftpTabState(newValue);
+        }
+      }
       // Sync global hotkey enabled setting from other windows
       if (e.key === STORAGE_KEY_GLOBAL_HOTKEY_ENABLED && e.newValue !== null) {
         const newValue = e.newValue === 'true';
@@ -849,6 +916,12 @@ export const useSettingsState = () => {
     notifySettingsChanged(STORAGE_KEY_TERM_THEME, terminalThemeId);
   }, [terminalThemeId, notifySettingsChanged]);
 
+  useEffect(() => {
+    localStorageAdapter.writeString(STORAGE_KEY_TERM_FOLLOW_APP_THEME, String(followAppTerminalTheme));
+    if (!persistMountedRef.current) return;
+    notifySettingsChanged(STORAGE_KEY_TERM_FOLLOW_APP_THEME, String(followAppTerminalTheme));
+  }, [followAppTerminalTheme, notifySettingsChanged]);
+
   useEffect(() => {
     localStorageAdapter.writeString(STORAGE_KEY_TERM_FONT_FAMILY, terminalFontFamilyId);
     if (!persistMountedRef.current) return;
@@ -893,6 +966,27 @@ export const useSettingsState = () => {
     notifySettingsChanged(STORAGE_KEY_HOTKEY_RECORDING, isRecording);
   }, [notifySettingsChanged]);
 
+  const setShowRecentHosts = useCallback((enabled: boolean) => {
+    setShowRecentHostsState(enabled);
+    localStorageAdapter.writeBoolean(STORAGE_KEY_SHOW_RECENT_HOSTS, enabled);
+    if (!persistMountedRef.current) return;
+    notifySettingsChanged(STORAGE_KEY_SHOW_RECENT_HOSTS, enabled);
+  }, [notifySettingsChanged]);
+
+  const setShowOnlyUngroupedHostsInRoot = useCallback((enabled: boolean) => {
+    setShowOnlyUngroupedHostsInRootState(enabled);
+    localStorageAdapter.writeBoolean(STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT, enabled);
+    if (!persistMountedRef.current) return;
+    notifySettingsChanged(STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT, enabled);
+  }, [notifySettingsChanged]);
+
+  const setShowSftpTab = useCallback((enabled: boolean) => {
+    setShowSftpTabState(enabled);
+    localStorageAdapter.writeBoolean(STORAGE_KEY_SHOW_SFTP_TAB, enabled);
+    if (!persistMountedRef.current) return;
+    notifySettingsChanged(STORAGE_KEY_SHOW_SFTP_TAB, enabled);
+  }, [notifySettingsChanged]);
+
   // Apply and persist custom CSS
   useEffect(() => {
     // Always apply CSS to document (needed on mount)
@@ -1116,12 +1210,21 @@ export const useSettingsState = () => {
   // Subscribe to custom theme changes so editing in-place triggers re-render
   const customThemes = useCustomThemes();
 
-  const currentTerminalTheme = useMemo(
-    () => TERMINAL_THEMES.find(t => t.id === terminalThemeId)
+  const currentTerminalTheme = useMemo(() => {
+    // When "Follow Application Theme" is enabled, pick the terminal theme
+    // whose background matches the active UI theme preset.
+    if (followAppTerminalTheme) {
+      const activeUiThemeId = resolvedTheme === 'dark' ? darkUiThemeId : lightUiThemeId;
+      const mapped = getTerminalThemeForUiTheme(activeUiThemeId);
+      if (mapped) {
+        const found = TERMINAL_THEMES.find(t => t.id === mapped);
+        if (found) return found;
+      }
+    }
+    return TERMINAL_THEMES.find(t => t.id === terminalThemeId)
       || customThemes.find(t => t.id === terminalThemeId)
-      || TERMINAL_THEMES[0],
-    [terminalThemeId, customThemes]
-  );
+      || TERMINAL_THEMES[0];
+  }, [terminalThemeId, customThemes, followAppTerminalTheme, resolvedTheme, lightUiThemeId, darkUiThemeId]);
 
   const updateTerminalSetting = useCallback(<K extends keyof TerminalSettings>(
     key: K,
@@ -1156,6 +1259,8 @@ export const useSettingsState = () => {
     setUiLanguage,
     terminalThemeId,
     setTerminalThemeId,
+    followAppTerminalTheme,
+    setFollowAppTerminalTheme: setFollowAppTerminalThemeState,
     currentTerminalTheme,
     terminalFontFamilyId,
     setTerminalFontFamilyId,
@@ -1187,6 +1292,12 @@ export const useSettingsState = () => {
     setSftpAutoOpenSidebar,
     sftpDefaultViewMode,
     setSftpDefaultViewMode,
+    showRecentHosts,
+    setShowRecentHosts,
+    showOnlyUngroupedHostsInRoot,
+    setShowOnlyUngroupedHostsInRoot,
+    showSftpTab,
+    setShowSftpTab,
     sftpTransferConcurrency,
     setSftpTransferConcurrency,
     // Editor Settings
@@ -1225,6 +1336,7 @@ export const useSettingsState = () => {
       terminalThemeId, terminalFontFamilyId, terminalFontSize, terminalSettings,
       customKeyBindings, editorWordWrap,
       sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles, sftpUseCompressedUpload, sftpAutoOpenSidebar, sftpDefaultViewMode,
+      showRecentHosts, showOnlyUngroupedHostsInRoot, showSftpTab,
       customThemes, workspaceFocusStyle,
     ]),
   };

application/state/useTerminalBackend.ts

@@ -128,6 +128,22 @@ export const useTerminalBackend = () => {
     return bridge.getSessionPwd(sessionId);
   }, []);
 
+  const getSessionRemoteInfo = useCallback(async (sessionId: string) => {
+    const bridge = netcattyBridge.get();
+    if (!bridge?.getSessionRemoteInfo) {
+      return { success: false, error: 'getSessionRemoteInfo unavailable' };
+    }
+    return bridge.getSessionRemoteInfo(sessionId);
+  }, []);
+
+  const getSessionDistroInfo = useCallback(async (sessionId: string) => {
+    const bridge = netcattyBridge.get();
+    if (!bridge?.getSessionDistroInfo) {
+      return { success: false, error: 'getSessionDistroInfo unavailable' };
+    }
+    return bridge.getSessionDistroInfo(sessionId);
+  }, []);
+
   const getServerStats = useCallback(async (sessionId: string) => {
     const bridge = netcattyBridge.get();
     if (!bridge?.getServerStats) return { success: false, error: 'getServerStats unavailable' };
@@ -150,6 +166,8 @@ export const useTerminalBackend = () => {
     listSerialPorts,
     execCommand,
     getSessionPwd,
+    getSessionRemoteInfo,
+    getSessionDistroInfo,
     getServerStats,
     writeToSession,
     resizeSession,

application/state/useVaultState.ts

@@ -102,6 +102,7 @@ const safeParse = <T,>(value: string | null): T | null => {
 };
 
 export const useVaultState = () => {
+  const [isInitialized, setIsInitialized] = useState(false);
   const [hosts, setHosts] = useState<Host[]>([]);
   const [keys, setKeys] = useState<SSHKey[]>([]);
   const [identities, setIdentities] = useState<Identity[]>([]);
@@ -339,129 +340,133 @@ export const useVaultState = () => {
 
   useEffect(() => {
     const init = async () => {
-      const savedHosts = localStorageAdapter.read<Host[]>(STORAGE_KEY_HOSTS);
+      try {
+        const savedHosts = localStorageAdapter.read<Host[]>(STORAGE_KEY_HOSTS);
 
-      if (savedHosts) {
-        // Capture version before the async gap so that any write occurring
-        // during decryption (storage event, user edit) advances the counter
-        // and causes this stale result to be discarded.
-        const ver = ++hostsWriteVersion.current;
-        const decrypted = await decryptHosts(savedHosts);
-        if (ver === hostsWriteVersion.current) {
-          const sanitized = decrypted.map(sanitizeHost);
-          setHosts(sanitized);
-          encryptHosts(sanitized).then((enc) => {
-            if (ver === hostsWriteVersion.current)
-              localStorageAdapter.write(STORAGE_KEY_HOSTS, enc);
-          });
+        if (savedHosts) {
+          // Capture version before the async gap so that any write occurring
+          // during decryption (storage event, user edit) advances the counter
+          // and causes this stale result to be discarded.
+          const ver = ++hostsWriteVersion.current;
+          const decrypted = await decryptHosts(savedHosts);
+          if (ver === hostsWriteVersion.current) {
+            const sanitized = decrypted.map(sanitizeHost);
+            setHosts(sanitized);
+            encryptHosts(sanitized).then((enc) => {
+              if (ver === hostsWriteVersion.current)
+                localStorageAdapter.write(STORAGE_KEY_HOSTS, enc);
+            });
+          }
+        } else {
+          updateHosts(INITIAL_HOSTS);
         }
-      } else {
-        updateHosts(INITIAL_HOSTS);
-      }
 
-      // Read keys fresh here (not before the hosts await) so we don't apply
-      // a stale snapshot if keys were updated during host decryption.
-      const savedKeysRaw = localStorageAdapter.read<unknown[]>(STORAGE_KEY_KEYS);
+        // Read keys fresh here (not before the hosts await) so we don't apply
+        // a stale snapshot if keys were updated during host decryption.
+        const savedKeysRaw = localStorageAdapter.read<unknown[]>(STORAGE_KEY_KEYS);
 
-      // Migrate old keys to new format with source/category fields
-      if (savedKeysRaw?.length) {
-        const migratedKeys: SSHKey[] = [];
-        const legacyKeys: LegacyKeyRecord[] = [];
+        // Migrate old keys to new format with source/category fields
+        if (savedKeysRaw?.length) {
+          const migratedKeys: SSHKey[] = [];
+          const legacyKeys: LegacyKeyRecord[] = [];
 
-        for (const entry of savedKeysRaw) {
-          const record =
-            entry && typeof entry === "object" ? (entry as LegacyKeyRecord) : null;
-          if (!record) continue;
+          for (const entry of savedKeysRaw) {
+            const record =
+              entry && typeof entry === "object" ? (entry as LegacyKeyRecord) : null;
+            if (!record) continue;
 
-          if (isLegacyUnsupportedKey(record)) {
-            legacyKeys.push(record);
-            continue;
+            if (isLegacyUnsupportedKey(record)) {
+              legacyKeys.push(record);
+              continue;
+            }
+
+            migratedKeys.push(migrateKey(record as Partial<SSHKey>));
           }
 
-          migratedKeys.push(migrateKey(record as Partial<SSHKey>));
+          // Decrypt sensitive fields (passphrase, privateKey)
+          const keyVer = ++keysWriteVersion.current;
+          const decryptedKeys = await decryptKeys(migratedKeys);
+          if (keyVer === keysWriteVersion.current) {
+            setKeys(decryptedKeys);
+            encryptKeys(decryptedKeys).then((enc) => {
+              if (keyVer === keysWriteVersion.current)
+                localStorageAdapter.write(STORAGE_KEY_KEYS, enc);
+            });
+          }
+          if (legacyKeys.length) {
+            localStorageAdapter.write(STORAGE_KEY_LEGACY_KEYS, legacyKeys);
+          }
         }
 
-        // Decrypt sensitive fields (passphrase, privateKey)
-        const keyVer = ++keysWriteVersion.current;
-        const decryptedKeys = await decryptKeys(migratedKeys);
-        if (keyVer === keysWriteVersion.current) {
-          setKeys(decryptedKeys);
-          encryptKeys(decryptedKeys).then((enc) => {
-            if (keyVer === keysWriteVersion.current)
-              localStorageAdapter.write(STORAGE_KEY_KEYS, enc);
-          });
+        // Read identities fresh here (not before the hosts/keys awaits) so we
+        // don't apply a stale snapshot if identities were updated during prior decryption.
+        const savedIdentities =
+          localStorageAdapter.read<Identity[]>(STORAGE_KEY_IDENTITIES);
+        if (savedIdentities) {
+          const idVer = ++identitiesWriteVersion.current;
+          const decryptedIds = await decryptIdentities(savedIdentities);
+          if (idVer === identitiesWriteVersion.current) {
+            setIdentities(decryptedIds);
+            encryptIdentities(decryptedIds).then((enc) => {
+              if (idVer === identitiesWriteVersion.current)
+                localStorageAdapter.write(STORAGE_KEY_IDENTITIES, enc);
+            });
+          }
         }
-        if (legacyKeys.length) {
-          localStorageAdapter.write(STORAGE_KEY_LEGACY_KEYS, legacyKeys);
-        }
-      }
-
-      // Read identities fresh here (not before the hosts/keys awaits) so we
-      // don't apply a stale snapshot if identities were updated during prior decryption.
-      const savedIdentities =
-        localStorageAdapter.read<Identity[]>(STORAGE_KEY_IDENTITIES);
-      if (savedIdentities) {
-        const idVer = ++identitiesWriteVersion.current;
-        const decryptedIds = await decryptIdentities(savedIdentities);
-        if (idVer === identitiesWriteVersion.current) {
-          setIdentities(decryptedIds);
-          encryptIdentities(decryptedIds).then((enc) => {
-            if (idVer === identitiesWriteVersion.current)
-              localStorageAdapter.write(STORAGE_KEY_IDENTITIES, enc);
-          });
-        }
-      }
-
-      // Read remaining non-encrypted data fresh after all async gaps above
-      const savedGroups = localStorageAdapter.read<string[]>(STORAGE_KEY_GROUPS);
-      const savedSnippets =
-        localStorageAdapter.read<Snippet[]>(STORAGE_KEY_SNIPPETS);
-      const savedSnippetPackages = localStorageAdapter.read<string[]>(
-        STORAGE_KEY_SNIPPET_PACKAGES,
-      );
-
-      if (savedSnippets) setSnippets(savedSnippets);
-      else updateSnippets(INITIAL_SNIPPETS);
-
-      if (savedGroups) setCustomGroups(savedGroups);
-      if (savedSnippetPackages) setSnippetPackages(savedSnippetPackages);
-
-      // Load known hosts
-      const savedKnownHosts = localStorageAdapter.read<KnownHost[]>(
-        STORAGE_KEY_KNOWN_HOSTS,
-      );
-      if (savedKnownHosts) setKnownHosts(savedKnownHosts);
-
-      // Load shell history
-      const savedShellHistory = localStorageAdapter.read<ShellHistoryEntry[]>(
-        STORAGE_KEY_SHELL_HISTORY,
-      );
-      if (savedShellHistory) setShellHistory(savedShellHistory);
-
-      // Load connection logs
-      const savedConnectionLogs = localStorageAdapter.read<ConnectionLog[]>(
-        STORAGE_KEY_CONNECTION_LOGS,
-      );
-      if (savedConnectionLogs) setConnectionLogs(savedConnectionLogs);
-
-      // Load managed sources
-      const savedManagedSources = localStorageAdapter.read<ManagedSource[]>(
-        STORAGE_KEY_MANAGED_SOURCES,
-      );
-      if (savedManagedSources) setManagedSources(savedManagedSources);
-
-      // Load group configs
-      const savedGroupConfigs = localStorageAdapter.read<GroupConfig[]>(STORAGE_KEY_GROUP_CONFIGS);
-      if (savedGroupConfigs) {
-        const gcVer = ++groupConfigsWriteVersion.current;
-        const decryptedGC = await decryptGroupConfigs(savedGroupConfigs);
-        if (gcVer === groupConfigsWriteVersion.current) {
-          setGroupConfigs(decryptedGC);
-          encryptGroupConfigs(decryptedGC).then((enc) => {
-            if (gcVer === groupConfigsWriteVersion.current)
-              localStorageAdapter.write(STORAGE_KEY_GROUP_CONFIGS, enc);
-          });
+
+        // Read remaining non-encrypted data fresh after all async gaps above
+        const savedGroups = localStorageAdapter.read<string[]>(STORAGE_KEY_GROUPS);
+        const savedSnippets =
+          localStorageAdapter.read<Snippet[]>(STORAGE_KEY_SNIPPETS);
+        const savedSnippetPackages = localStorageAdapter.read<string[]>(
+          STORAGE_KEY_SNIPPET_PACKAGES,
+        );
+
+        if (savedSnippets) setSnippets(savedSnippets);
+        else updateSnippets(INITIAL_SNIPPETS);
+
+        if (savedGroups) setCustomGroups(savedGroups);
+        if (savedSnippetPackages) setSnippetPackages(savedSnippetPackages);
+
+        // Load known hosts
+        const savedKnownHosts = localStorageAdapter.read<KnownHost[]>(
+          STORAGE_KEY_KNOWN_HOSTS,
+        );
+        if (savedKnownHosts) setKnownHosts(savedKnownHosts);
+
+        // Load shell history
+        const savedShellHistory = localStorageAdapter.read<ShellHistoryEntry[]>(
+          STORAGE_KEY_SHELL_HISTORY,
+        );
+        if (savedShellHistory) setShellHistory(savedShellHistory);
+
+        // Load connection logs
+        const savedConnectionLogs = localStorageAdapter.read<ConnectionLog[]>(
+          STORAGE_KEY_CONNECTION_LOGS,
+        );
+        if (savedConnectionLogs) setConnectionLogs(savedConnectionLogs);
+
+        // Load managed sources
+        const savedManagedSources = localStorageAdapter.read<ManagedSource[]>(
+          STORAGE_KEY_MANAGED_SOURCES,
+        );
+        if (savedManagedSources) setManagedSources(savedManagedSources);
+
+        // Load group configs
+        const savedGroupConfigs = localStorageAdapter.read<GroupConfig[]>(STORAGE_KEY_GROUP_CONFIGS);
+        if (savedGroupConfigs) {
+          const gcVer = ++groupConfigsWriteVersion.current;
+          const decryptedGC = await decryptGroupConfigs(savedGroupConfigs);
+          if (gcVer === groupConfigsWriteVersion.current) {
+            setGroupConfigs(decryptedGC);
+            encryptGroupConfigs(decryptedGC).then((enc) => {
+              if (gcVer === groupConfigsWriteVersion.current)
+                localStorageAdapter.write(STORAGE_KEY_GROUP_CONFIGS, enc);
+            });
+          }
         }
+      } finally {
+        setIsInitialized(true);
       }
     };
 
@@ -657,6 +662,7 @@ export const useVaultState = () => {
   );
 
   return {
+    isInitialized,
     hosts,
     keys,
     identities,

application/syncPayload.ts

@@ -43,6 +43,8 @@ import {
   STORAGE_KEY_SFTP_GLOBAL_BOOKMARKS,
   STORAGE_KEY_CUSTOM_THEMES,
   STORAGE_KEY_SHOW_RECENT_HOSTS,
+  STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT,
+  STORAGE_KEY_SHOW_SFTP_TAB,
 } from '../infrastructure/config/storageKeys';
 
 // ---------------------------------------------------------------------------
@@ -61,6 +63,29 @@ export interface SyncableVaultData {
   groupConfigs?: GroupConfig[];
 }
 
+/**
+ * Returns true when the payload contains any meaningful user data worth
+ * protecting or syncing.
+ */
+export function hasMeaningfulSyncData(payload: SyncPayload): boolean {
+  const hasEntities =
+    (payload.hosts?.length ?? 0) > 0 ||
+    (payload.keys?.length ?? 0) > 0 ||
+    (payload.snippets?.length ?? 0) > 0 ||
+    (payload.identities?.length ?? 0) > 0 ||
+    (payload.customGroups?.length ?? 0) > 0 ||
+    (payload.snippetPackages?.length ?? 0) > 0 ||
+    (payload.portForwardingRules?.length ?? 0) > 0 ||
+    (payload.knownHosts?.length ?? 0) > 0 ||
+    (payload.groupConfigs?.length ?? 0) > 0;
+
+  if (hasEntities) return true;
+
+  return Boolean(
+    payload.settings && Object.values(payload.settings).some((value) => value !== undefined),
+  );
+}
+
 /** Callbacks used by `applySyncPayload` to import data into local state. */
 interface SyncPayloadImporters {
   /** Import vault data (hosts, keys, identities, snippets, customGroups, snippetPackages, knownHosts). */
@@ -173,6 +198,10 @@ export function collectSyncableSettings(): SyncPayload['settings'] {
 
   const showRecent = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_RECENT_HOSTS);
   if (showRecent != null) settings.showRecentHosts = showRecent;
+  const showOnlyUngroupedHostsInRoot = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT);
+  if (showOnlyUngroupedHostsInRoot != null) settings.showOnlyUngroupedHostsInRoot = showOnlyUngroupedHostsInRoot;
+  const showSftpTab = localStorageAdapter.readBoolean(STORAGE_KEY_SHOW_SFTP_TAB);
+  if (showSftpTab != null) settings.showSftpTab = showSftpTab;
 
   return Object.keys(settings).length > 0 ? settings : undefined;
 }
@@ -238,6 +267,15 @@ function applySyncableSettings(settings: NonNullable<SyncPayload['settings']>):
 
   // Immersive mode (legacy — always enabled, ignore incoming value)
   if (settings.showRecentHosts != null) localStorageAdapter.writeBoolean(STORAGE_KEY_SHOW_RECENT_HOSTS, settings.showRecentHosts);
+  if (settings.showOnlyUngroupedHostsInRoot != null) {
+    localStorageAdapter.writeBoolean(
+      STORAGE_KEY_SHOW_ONLY_UNGROUPED_HOSTS_IN_ROOT,
+      settings.showOnlyUngroupedHostsInRoot,
+    );
+  }
+  if (settings.showSftpTab != null) {
+    localStorageAdapter.writeBoolean(STORAGE_KEY_SHOW_SFTP_TAB, settings.showSftpTab);
+  }
 }
 
 // ---------------------------------------------------------------------------

components/CloudSyncSettings.tsx

@@ -17,11 +17,13 @@ import {
     Download,
     Database,
     ExternalLink,
+    FolderOpen,
     Eye,
     EyeOff,
     Github,
     Key,
     Loader2,
+    History,
     RefreshCw,
     Settings,
     Server,
@@ -31,6 +33,12 @@ import {
     X,
 } from 'lucide-react';
 import { useCloudSync } from '../application/state/useCloudSync';
+import { useLocalVaultBackups } from '../application/state/useLocalVaultBackups';
+import {
+    MAX_LOCAL_VAULT_BACKUP_MAX_COUNT,
+    MIN_LOCAL_VAULT_BACKUP_MAX_COUNT,
+    withRestoreBarrier,
+} from '../application/localVaultBackups';
 import { useI18n } from '../application/i18n/I18nProvider';
 import {
     findSyncPayloadEncryptedCredentialPaths,
@@ -285,6 +293,7 @@ interface ProviderCardProps {
     onCancelConnect?: () => void;
     onDisconnect: () => void;
     onSync: () => void;
+    extraActions?: React.ReactNode;
 }
 
 const ProviderCard: React.FC<ProviderCardProps> = ({
@@ -303,6 +312,7 @@ const ProviderCard: React.FC<ProviderCardProps> = ({
     onCancelConnect,
     onDisconnect,
     onSync,
+    extraActions,
 }) => {
     const { t } = useI18n();
     const formatLastSync = (timestamp?: number): string => {
@@ -395,6 +405,7 @@ const ProviderCard: React.FC<ProviderCardProps> = ({
                             )}
                             {t('cloudSync.provider.sync')}
                         </Button>
+                        {extraActions}
                         {onEdit && (
                             <Button
                                 size="sm"
@@ -624,10 +635,395 @@ const ConflictModal: React.FC<ConflictModalProps> = ({
 
 interface SyncDashboardProps {
     onBuildPayload: () => SyncPayload;
-    onApplyPayload: (payload: SyncPayload) => void;
+    onApplyPayload: (payload: SyncPayload) => void | Promise<void>;
     onClearLocalData?: () => void;
 }
 
+interface LocalBackupsPanelProps {
+    onApplyPayload: (payload: SyncPayload) => void | Promise<void>;
+    /**
+     * When true, the panel hides the Restore button entirely — e.g. while the
+     * master key has not been configured yet, a restore would land credentials
+     * on disk in plaintext (I3). Listing is still allowed so users can see that
+     * their history exists.
+     */
+    restoreDisabledReason?: 'no-master-key' | null;
+}
+
+const LocalBackupsPanel: React.FC<LocalBackupsPanelProps> = ({
+    onApplyPayload,
+    restoreDisabledReason = null,
+}) => {
+    const { t, resolvedLocale } = useI18n();
+    const {
+        backups,
+        isLoading,
+        maxBackups,
+        encryptionAvailable,
+        refreshBackups,
+        readBackup,
+        setMaxBackups,
+        openBackupDirectory,
+    } = useLocalVaultBackups();
+    const [maxBackupsInput, setMaxBackupsInput] = useState(String(maxBackups));
+    const [isSavingMaxBackups, setIsSavingMaxBackups] = useState(false);
+    const [restoringBackupId, setRestoringBackupId] = useState<string | null>(null);
+    // Backup chosen in the list but not yet confirmed. A two-step flow keeps
+    // users from wiping their vault with a single accidental click (I2).
+    const [pendingRestoreBackup, setPendingRestoreBackup] = useState<
+        (typeof backups)[number] | null
+    >(null);
+
+    useEffect(() => {
+        setMaxBackupsInput(String(maxBackups));
+    }, [maxBackups]);
+
+    const formatTimestamp = (timestamp: number) =>
+        new Date(timestamp).toLocaleString(resolvedLocale || undefined);
+
+    const getReasonLabel = (reason: 'app_version_change' | 'before_restore') =>
+        reason === 'app_version_change'
+            ? t('cloudSync.localBackups.reason.appVersionChange')
+            : t('cloudSync.localBackups.reason.beforeRestore');
+
+    const handleSaveMaxBackups = async () => {
+        // Validate BEFORE calling setMaxBackups, which hands off to the
+        // renderer's `sanitizeLocalVaultBackupMaxCount` clamp. Two failure
+        // modes must be surfaced rather than silently clamped, because
+        // both produce a misleading "saved" toast:
+        //
+        //   1. Empty / non-numeric input — `Number("")` coerces to 0 and
+        //      sanitize clamps to the default (20). A user who meant to
+        //      clear the field then re-type would see their retention
+        //      silently reset to 20 with a success message.
+        //
+        //   2. Out-of-range input (e.g. 500) — sanitize clamps to 100 and
+        //      still reports success, but the visible error string says
+        //      "between 1 and 100", so the user has no idea their value
+        //      was changed. Reject explicitly instead.
+        //
+        // The 1..MAX range check mirrors the main-process `sanitizeMaxCount`
+        // in vaultBackupBridge.cjs so renderer and bridge agree.
+        const parsed = Number(maxBackupsInput);
+        const inRange =
+            Number.isFinite(parsed) &&
+            parsed >= MIN_LOCAL_VAULT_BACKUP_MAX_COUNT &&
+            parsed <= MAX_LOCAL_VAULT_BACKUP_MAX_COUNT;
+        if (!inRange || maxBackupsInput.trim() === '') {
+            toast.error(
+                t('cloudSync.localBackups.maxInvalid'),
+                t('sync.toast.errorTitle'),
+            );
+            return;
+        }
+        setIsSavingMaxBackups(true);
+        try {
+            const next = await setMaxBackups(parsed);
+            setMaxBackupsInput(String(next));
+            toast.success(t('cloudSync.localBackups.maxSaved', { count: String(next) }));
+        } catch (error) {
+            toast.error(
+                error instanceof Error ? error.message : t('common.unknownError'),
+                t('sync.toast.errorTitle'),
+            );
+        } finally {
+            setIsSavingMaxBackups(false);
+        }
+    };
+
+    const handleOpenBackupDirectory = async () => {
+        try {
+            await openBackupDirectory();
+        } catch (error) {
+            toast.error(
+                error instanceof Error ? error.message : t('common.unknownError'),
+                t('sync.toast.errorTitle'),
+            );
+        }
+    };
+
+    const performRestore = async (backupId: string) => {
+        setRestoringBackupId(backupId);
+        try {
+            // Hold the cross-window restore barrier around both the load
+            // and the apply so another window's auto-sync cannot push a
+            // pre-restore snapshot concurrently. See `withRestoreBarrier`
+            // in application/localVaultBackups.ts for the read-side in
+            // useAutoSync.
+            //
+            // In-memory React state refresh is implicit: `onApplyPayload`
+            // (supplied by the hosting screen) routes through
+            // `applySyncPayload` → `importDataFromString` → store writes
+            // → the hook-store listeners in `useVaultState` /
+            // `useCustomThemes` / etc. We do NOT explicitly re-pull host
+            // lists here because a future refactor that decouples those
+            // stores from the apply path would silently break the UI
+            // refresh in a way that's only visible after a manual
+            // restart. Any change to that chain must either preserve
+            // store-listener notification OR add an explicit
+            // `rehydrateAllFromStorage` call here — do not assume
+            // restore is "just" a payload swap.
+            await withRestoreBarrier(async () => {
+                const detail = await readBackup(backupId);
+                if (!detail) {
+                    throw new Error(t('cloudSync.localBackups.restoreMissing'));
+                }
+                await Promise.resolve(onApplyPayload(detail.payload));
+            });
+            await refreshBackups();
+            toast.success(t('cloudSync.localBackups.restoreSuccess'));
+        } catch (error) {
+            toast.error(
+                error instanceof Error ? error.message : t('common.unknownError'),
+                t('cloudSync.localBackups.restoreFailedTitle'),
+            );
+        } finally {
+            setRestoringBackupId(null);
+        }
+    };
+
+    const restoreAllowed = restoreDisabledReason === null;
+    // While encryptionAvailable is still `null` we're mid-probe — render the
+    // restore button as disabled so the user never sees a path they can't
+    // actually take (I1 surface). Once resolved, `false` hides the panel body
+    // via the unavailable banner below.
+    const encryptionResolved = encryptionAvailable !== null;
+    const encryptionUsable = encryptionAvailable === true;
+
+    // safeStorage probe finished and returned "not available" → disable the
+    // panel entirely; the main process refuses to write in this state (I1).
+    if (encryptionResolved && !encryptionUsable) {
+        return (
+            <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-4 space-y-2">
+                <div className="flex items-center gap-2 text-amber-600 dark:text-amber-400">
+                    <AlertTriangle size={16} />
+                    <span className="text-sm font-medium">
+                        {t('cloudSync.localBackups.unavailableTitle')}
+                    </span>
+                </div>
+                <div className="text-xs text-muted-foreground">
+                    {t('cloudSync.localBackups.unavailableDesc')}
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="space-y-4">
+            <div className="rounded-lg border bg-card p-4">
+                <div className="flex flex-col gap-4 md:flex-row md:items-start md:justify-between">
+                    <div className="max-w-lg">
+                        <div className="text-sm font-medium">{t('cloudSync.localBackups.retentionTitle')}</div>
+                        <div className="text-xs text-muted-foreground mt-1">
+                            {t('cloudSync.localBackups.retentionDesc')}
+                        </div>
+                    </div>
+                    <div className="space-y-2 md:min-w-[260px] md:shrink-0">
+                        <div className="flex items-end gap-2 md:justify-end">
+                            <Input
+                                type="number"
+                                min={1}
+                                max={100}
+                                value={maxBackupsInput}
+                                onChange={(e) => setMaxBackupsInput(e.target.value)}
+                                className="w-28"
+                            />
+                            <Button
+                                variant="outline"
+                                onClick={() => void handleSaveMaxBackups()}
+                                disabled={isSavingMaxBackups}
+                                className="gap-2"
+                            >
+                                {isSavingMaxBackups && <Loader2 size={14} className="animate-spin" />}
+                                {t('common.save')}
+                            </Button>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            {!restoreAllowed && (
+                <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-3 text-xs text-muted-foreground">
+                    <div className="flex items-center gap-2 text-amber-600 dark:text-amber-400 mb-1">
+                        <AlertTriangle size={14} />
+                        <span className="font-medium">
+                            {t('cloudSync.localBackups.lockedTitle')}
+                        </span>
+                    </div>
+                    {t('cloudSync.localBackups.lockedDesc')}
+                </div>
+            )}
+
+            <div className="rounded-lg border bg-card p-4 space-y-4">
+                <div className="flex items-start justify-between gap-3">
+                    <div>
+                        <div className="text-sm font-medium">{t('cloudSync.localBackups.title')}</div>
+                        <div className="text-xs text-muted-foreground mt-1">
+                            {t('cloudSync.localBackups.desc')}
+                        </div>
+                    </div>
+                    <div className="flex items-center gap-2">
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => void refreshBackups()}
+                            disabled={isLoading}
+                            className="gap-1"
+                        >
+                            <RefreshCw size={14} className={cn(isLoading && 'animate-spin')} />
+                            {t('settings.system.refresh')}
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => void handleOpenBackupDirectory()}
+                            className="gap-1"
+                        >
+                            <FolderOpen size={14} />
+                            {t('settings.system.openFolder')}
+                        </Button>
+                    </div>
+                </div>
+
+                {backups.length === 0 ? (
+                    <div className="rounded-lg border border-dashed border-border/60 p-4 text-sm text-muted-foreground">
+                        {t('cloudSync.localBackups.empty')}
+                    </div>
+                ) : (
+                    <div className="space-y-2">
+                        {backups.map((backup) => (
+                            <div
+                                key={backup.id}
+                                className="flex items-center gap-3 rounded-lg border border-border/60 p-3"
+                            >
+                                <div className="flex-1 min-w-0">
+                                    <div className="flex items-center gap-2 flex-wrap">
+                                        <span className="text-sm font-medium">
+                                            {getReasonLabel(backup.reason)}
+                                        </span>
+                                        <span className="text-xs text-muted-foreground">
+                                            {formatTimestamp(backup.createdAt)}
+                                        </span>
+                                        {backup.sourceAppVersion && backup.targetAppVersion && (
+                                            <span className="text-xs text-muted-foreground">
+                                                {t('cloudSync.localBackups.versionChange', {
+                                                    from: backup.sourceAppVersion,
+                                                    to: backup.targetAppVersion,
+                                                })}
+                                            </span>
+                                        )}
+                                    </div>
+                                    <div className="text-xs text-muted-foreground mt-1">
+                                        {t('cloudSync.localBackups.counts', {
+                                            hosts: String(backup.preview.hostCount),
+                                            keys: String(backup.preview.keyCount),
+                                            snippets: String(backup.preview.snippetCount),
+                                        })}
+                                    </div>
+                                </div>
+                                {restoreAllowed && (
+                                    <Button
+                                        size="sm"
+                                        variant="outline"
+                                        onClick={() => setPendingRestoreBackup(backup)}
+                                        // Disable every row while ANY restore is in
+                                        // flight. Each restore runs a full
+                                        // `applyProtectedSyncPayload` — multiple
+                                        // localStorage writes + the apply-in-progress
+                                        // sentinel. `withRestoreBarrier` serializes
+                                        // across windows but does NOT serialize
+                                        // same-window re-entry, so two overlapping
+                                        // clicks here would interleave destructive
+                                        // writes and the second run's sentinel-clear
+                                        // could mask a still-partial first apply.
+                                        disabled={restoringBackupId !== null}
+                                        className="gap-2"
+                                    >
+                                        {restoringBackupId === backup.id ? (
+                                            <Loader2 size={14} className="animate-spin" />
+                                        ) : (
+                                            <Download size={14} />
+                                        )}
+                                        {t('cloudSync.localBackups.restore')}
+                                    </Button>
+                                )}
+                            </div>
+                        ))}
+                    </div>
+                )}
+            </div>
+
+            {/* Restore confirmation dialog (I2). Keeps the destructive action
+                gated behind an explicit second click, mirroring the clear-local
+                dialog elsewhere in this screen. */}
+            <Dialog
+                open={pendingRestoreBackup !== null}
+                onOpenChange={(open) => {
+                    if (!open) setPendingRestoreBackup(null);
+                }}
+            >
+                <DialogContent className="sm:max-w-[440px] z-[70]">
+                    <DialogHeader>
+                        <DialogTitle className="flex items-center gap-2 text-destructive">
+                            <AlertTriangle size={20} />
+                            {t('cloudSync.localBackups.restoreConfirmTitle')}
+                        </DialogTitle>
+                        <DialogDescription>
+                            {t('cloudSync.localBackups.restoreConfirmDesc')}
+                        </DialogDescription>
+                    </DialogHeader>
+                    {pendingRestoreBackup && (
+                        <div className="rounded-lg border border-border/60 bg-muted/30 p-3 text-xs space-y-1">
+                            <div className="flex items-center gap-2 flex-wrap">
+                                <span className="font-medium">
+                                    {getReasonLabel(pendingRestoreBackup.reason)}
+                                </span>
+                                <span className="text-muted-foreground">
+                                    {formatTimestamp(pendingRestoreBackup.createdAt)}
+                                </span>
+                            </div>
+                            <div className="text-muted-foreground">
+                                {t('cloudSync.localBackups.counts', {
+                                    hosts: String(pendingRestoreBackup.preview.hostCount),
+                                    keys: String(pendingRestoreBackup.preview.keyCount),
+                                    snippets: String(pendingRestoreBackup.preview.snippetCount),
+                                })}
+                            </div>
+                        </div>
+                    )}
+                    <DialogFooter className="gap-2 sm:gap-0">
+                        <Button
+                            variant="outline"
+                            onClick={() => setPendingRestoreBackup(null)}
+                            disabled={restoringBackupId !== null}
+                        >
+                            {t('cloudSync.localBackups.restoreConfirmCancel')}
+                        </Button>
+                        <Button
+                            variant="destructive"
+                            onClick={async () => {
+                                const target = pendingRestoreBackup;
+                                if (!target) return;
+                                setPendingRestoreBackup(null);
+                                await performRestore(target.id);
+                            }}
+                            disabled={restoringBackupId !== null}
+                            className="gap-2"
+                        >
+                            {restoringBackupId !== null ? (
+                                <Loader2 size={14} className="animate-spin" />
+                            ) : (
+                                <Download size={14} />
+                            )}
+                            {t('cloudSync.localBackups.restoreConfirmButton')}
+                        </Button>
+                    </DialogFooter>
+                </DialogContent>
+            </Dialog>
+        </div>
+    );
+};
+
 const SyncDashboard: React.FC<SyncDashboardProps> = ({
     onBuildPayload,
     onApplyPayload,
@@ -715,6 +1111,20 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
     // Conflict modal
     const [showConflictModal, setShowConflictModal] = useState(false);
 
+    // Gist revision history (#679)
+    const [showHistoryModal, setShowHistoryModal] = useState(false);
+    const [historyRevisions, setHistoryRevisions] = useState<Array<{ version: string; date: Date }>>([]);
+    const [historyLoading, setHistoryLoading] = useState(false);
+    const [historyPreview, setHistoryPreview] = useState<{
+      sha: string;
+      payload: SyncPayload;
+      preview: { hostCount: number; keyCount: number; snippetCount: number; identityCount: number; portForwardingRuleCount: number };
+      deviceName?: string;
+      version?: number;
+    } | null>(null);
+    const [historyPreviewLoading, setHistoryPreviewLoading] = useState(false);
+    const [historyError, setHistoryError] = useState<string | null>(null);
+
     // Change master key dialog
     const [showChangeKeyDialog, setShowChangeKeyDialog] = useState(false);
     const [currentMasterKey, setCurrentMasterKey] = useState('');
@@ -994,7 +1404,7 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
             if (result.success) {
                 // Apply merged data if a three-way merge happened
                 if (result.mergedPayload && onApplyPayload) {
-                    onApplyPayload(result.mergedPayload);
+                    await Promise.resolve(onApplyPayload(result.mergedPayload));
                 }
                 toast.success(t('cloudSync.sync.success', { provider }));
             } else if (result.conflictDetected) {
@@ -1012,13 +1422,28 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
         try {
             const payload = await sync.resolveConflict(resolution);
             if (payload && resolution === 'USE_REMOTE') {
-                onApplyPayload(payload);
+                // USE_REMOTE applies cloud data over local — same data-loss
+                // shape as a local backup restore, so gate auto-sync in
+                // every other window the same way.
+                await withRestoreBarrier(async () => {
+                    await Promise.resolve(onApplyPayload(payload));
+                });
                 toast.success(t('cloudSync.resolve.downloaded'));
             } else if (resolution === 'USE_LOCAL') {
-                // Re-sync with local data
+                // Re-sync with local data. Hold the same cross-window
+                // restore barrier that USE_REMOTE uses: without it, a
+                // concurrent auto-sync tick in another window can slip
+                // between our conflict resolution and the upload,
+                // producing a second upload path with stale state that
+                // races against this push. USE_LOCAL doesn't mutate the
+                // renderer's in-memory state (no onApplyPayload call), so
+                // the barrier is belt-and-suspenders against the other
+                // window's push, not ours.
                 const localPayload = onBuildPayload();
                 if (!ensureSyncablePayload(localPayload)) return;
-                await sync.syncNow(localPayload);
+                await withRestoreBarrier(async () => {
+                    await sync.syncNow(localPayload);
+                });
                 toast.success(t('cloudSync.resolve.uploaded'));
             }
             setShowConflictModal(false);
@@ -1030,6 +1455,65 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
         }
     };
 
+    // -- Gist revision history handlers --
+
+    const handleOpenHistory = async () => {
+        setShowHistoryModal(true);
+        setHistoryLoading(true);
+        setHistoryError(null);
+        setHistoryPreview(null);
+        setHistoryRevisions([]);
+        try {
+            const revisions = await sync.getGistRevisionHistory();
+            setHistoryRevisions(revisions);
+        } catch (err) {
+            setHistoryError(err instanceof Error ? err.message : t('common.unknownError'));
+        } finally {
+            setHistoryLoading(false);
+        }
+    };
+
+    const handlePreviewRevision = async (sha: string) => {
+        setHistoryPreviewLoading(true);
+        setHistoryError(null);
+        try {
+            const result = await sync.downloadGistRevision(sha);
+            if (result) {
+                setHistoryPreview({
+                    sha,
+                    payload: result.payload,
+                    preview: result.preview,
+                    deviceName: result.meta.deviceName,
+                    version: result.meta.version,
+                });
+            } else {
+                setHistoryError(t('cloudSync.revisionHistory.revisionNotFound'));
+            }
+        } catch {
+            // Decrypt failures can manifest as various error types:
+            // "Decryption failed", OperationError, "unable to authenticate
+            // data", AES-GCM tag mismatch, etc. Show the friendly message
+            // for any error originating from the decrypt step; network
+            // errors would have been caught by the fetch layer already.
+            setHistoryError(t('cloudSync.revisionHistory.decryptFailed'));
+        } finally {
+            setHistoryPreviewLoading(false);
+        }
+    };
+
+    const handleRestoreRevision = async () => {
+        if (!historyPreview) return;
+        // Gist revision restore is a destructive "replace local with cloud
+        // snapshot" op — same shape as a local backup restore, same
+        // cross-window race to block.
+        await withRestoreBarrier(async () => {
+            await Promise.resolve(onApplyPayload(historyPreview.payload));
+        });
+        toast.success(t('cloudSync.revisionHistory.restored'));
+        setShowHistoryModal(false);
+        setHistoryPreview(null);
+    };
+
     return (
         <div className="space-y-6">
             {/* Header with status */}
@@ -1091,6 +1575,14 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
                         onConnect={handleConnectGitHub}
                         onDisconnect={() => sync.disconnectProvider('github')}
                         onSync={() => handleSync('github')}
+                        extraActions={
+                            isProviderReadyForSync(sync.providers.github) ? (
+                                <Button size="sm" variant="ghost" onClick={handleOpenHistory} className="gap-1">
+                                    <History size={14} />
+                                    {t('cloudSync.revisionHistory.viewButton')}
+                                </Button>
+                            ) : undefined
+                        }
                     />
 
                     <ProviderCard
@@ -1247,6 +1739,10 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
                         </div>
                     )}
 
+                    <LocalBackupsPanel
+                        onApplyPayload={onApplyPayload}
+                    />
+
                     {/* Clear Local Data */}
                     <div className="p-4 rounded-lg border border-destructive/30 bg-destructive/5">
                         <div className="flex items-center justify-between">
@@ -1291,6 +1787,113 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
                 onClose={() => setShowConflictModal(false)}
             />
 
+            {/* Gist Revision History Modal (#679) */}
+            <Dialog open={showHistoryModal} onOpenChange={setShowHistoryModal}>
+                <DialogContent className="sm:max-w-[520px] max-h-[80vh] overflow-hidden flex flex-col z-[70]">
+                    <DialogHeader>
+                        <DialogTitle className="flex items-center gap-2">
+                            <History size={18} />
+                            {t('cloudSync.revisionHistory.title')}
+                        </DialogTitle>
+                        <DialogDescription>{t('cloudSync.revisionHistory.description')}</DialogDescription>
+                    </DialogHeader>
+
+                    {historyError && (
+                        <div className="rounded-lg bg-red-500/10 border border-red-500/20 p-3 text-sm text-red-500">
+                            {historyError}
+                        </div>
+                    )}
+
+                    {historyLoading ? (
+                        <div className="flex items-center justify-center py-8">
+                            <Loader2 size={24} className="animate-spin text-muted-foreground" />
+                        </div>
+                    ) : historyPreview ? (
+                        // Preview of a selected revision
+                        <div className="space-y-4 overflow-y-auto flex-1 min-h-0">
+                            <div className="rounded-lg border p-4 space-y-2">
+                                <div className="text-sm font-medium">{t('cloudSync.revisionHistory.revisionPreview')}</div>
+                                {historyPreview.deviceName && (
+                                    <div className="text-xs text-muted-foreground">
+                                        {t('cloudSync.revisionHistory.device')}: {historyPreview.deviceName}
+                                        {historyPreview.version != null && ` · v${historyPreview.version}`}
+                                    </div>
+                                )}
+                                <div className="grid grid-cols-2 gap-2 text-sm">
+                                    <div className="flex justify-between px-2 py-1 bg-muted/30 rounded">
+                                        <span className="text-muted-foreground">{t('cloudSync.revisionHistory.hosts')}</span>
+                                        <span className="font-medium">{historyPreview.preview.hostCount}</span>
+                                    </div>
+                                    <div className="flex justify-between px-2 py-1 bg-muted/30 rounded">
+                                        <span className="text-muted-foreground">{t('cloudSync.revisionHistory.keys')}</span>
+                                        <span className="font-medium">{historyPreview.preview.keyCount}</span>
+                                    </div>
+                                    <div className="flex justify-between px-2 py-1 bg-muted/30 rounded">
+                                        <span className="text-muted-foreground">{t('cloudSync.revisionHistory.snippets')}</span>
+                                        <span className="font-medium">{historyPreview.preview.snippetCount}</span>
+                                    </div>
+                                    <div className="flex justify-between px-2 py-1 bg-muted/30 rounded">
+                                        <span className="text-muted-foreground">{t('cloudSync.revisionHistory.identities')}</span>
+                                        <span className="font-medium">{historyPreview.preview.identityCount}</span>
+                                    </div>
+                                </div>
+                            </div>
+                            <DialogFooter className="gap-2">
+                                <Button variant="outline" onClick={() => setHistoryPreview(null)}>
+                                    {t('common.back')}
+                                </Button>
+                                <Button onClick={handleRestoreRevision} className="gap-1">
+                                    <Download size={14} />
+                                    {t('cloudSync.revisionHistory.restoreButton')}
+                                </Button>
+                            </DialogFooter>
+                        </div>
+                    ) : (
+                        // Revision list
+                        <div className="overflow-y-auto flex-1 min-h-0 -mx-1">
+                            {historyRevisions.length === 0 ? (
+                                <div className="text-sm text-muted-foreground text-center py-8">
+                                    {t('cloudSync.revisionHistory.empty')}
+                                </div>
+                            ) : (
+                                <div className="space-y-1 px-1">
+                                    {historyRevisions.map((rev, index) => (
+                                        <button
+                                            key={rev.version}
+                                            onClick={() => handlePreviewRevision(rev.version)}
+                                            disabled={historyPreviewLoading}
+                                            className={cn(
+                                                "w-full flex items-center justify-between p-2.5 rounded-lg text-left text-sm transition-colors",
+                                                "hover:bg-accent border border-transparent hover:border-border",
+                                                index === 0 && "bg-primary/5 border-primary/20",
+                                            )}
+                                        >
+                                            <div>
+                                                <div className="font-medium">
+                                                    {index === 0 ? t('cloudSync.revisionHistory.current') : `${t('cloudSync.revisionHistory.revision')} #${historyRevisions.length - index}`}
+                                                </div>
+                                                <div className="text-xs text-muted-foreground">
+                                                    {rev.date.toLocaleString()}
+                                                </div>
+                                            </div>
+                                            <div className="text-xs text-muted-foreground font-mono">
+                                                {rev.version.slice(0, 7)}
+                                            </div>
+                                        </button>
+                                    ))}
+                                </div>
+                            )}
+                        </div>
+                    )}
+
+                    {historyPreviewLoading && (
+                        <div className="absolute inset-0 bg-background/50 flex items-center justify-center rounded-lg">
+                            <Loader2 size={24} className="animate-spin" />
+                        </div>
+                    )}
+                </DialogContent>
+            </Dialog>
+
             <Dialog open={showWebdavDialog} onOpenChange={setShowWebdavDialog}>
                 <DialogContent className="sm:max-w-[460px] max-h-[80vh] overflow-y-auto z-[70]">
                     <DialogHeader>
@@ -1768,7 +2371,7 @@ const SyncDashboard: React.FC<SyncDashboardProps> = ({
 
 interface CloudSyncSettingsProps {
     onBuildPayload: () => SyncPayload;
-    onApplyPayload: (payload: SyncPayload) => void;
+    onApplyPayload: (payload: SyncPayload) => void | Promise<void>;
     onClearLocalData?: () => void;
 }
 
@@ -1778,7 +2381,19 @@ export const CloudSyncSettings: React.FC<CloudSyncSettingsProps> = (props) => {
     // Simplified UX: once a master key is configured, we auto-unlock via safeStorage
     // so users don't have to manage a separate LOCKED screen.
     if (securityState === 'NO_KEY') {
-        return <GatekeeperScreen onSetupComplete={() => { }} />;
+        return (
+            <div className="space-y-6">
+                <GatekeeperScreen onSetupComplete={() => { }} />
+                {/* The master key is not configured yet. Expose the backup
+                    history for diagnostic purposes but refuse restores: the
+                    vault encryption layer can't re-protect the restored
+                    credentials until the user finishes master-key setup (I3). */}
+                <LocalBackupsPanel
+                    onApplyPayload={props.onApplyPayload}
+                    restoreDisabledReason="no-master-key"
+                />
+            </div>
+        );
     }
 
     return <SyncDashboard {...props} />;

components/CreateWorkspaceDialog.tsx

@@ -67,27 +67,27 @@ export const CreateWorkspaceDialog: React.FC<CreateWorkspaceDialogProps> = ({
     <Dialog open={isOpen} onOpenChange={(open) => !open && onClose()}>
       <DialogContent className="max-w-md flex flex-col max-h-[80vh]">
         <DialogHeader>
-          <DialogTitle>{t('dialog.createWorkspace.title', 'Create Workspace')}</DialogTitle>
+          <DialogTitle>{t('dialog.createWorkspace.title', { defaultValue: 'Create Workspace' })}</DialogTitle>
         </DialogHeader>
 
         <div className="space-y-4 py-2 flex-1 flex flex-col min-h-0">
           <div className="space-y-2">
-            <Label htmlFor="workspace-name">{t('field.name', 'Name')}</Label>
+            <Label htmlFor="workspace-name">{t('field.name', { defaultValue: 'Name' })}</Label>
             <Input
               id="workspace-name"
               value={name}
               onChange={(e) => setName(e.target.value)}
-              placeholder={t('placeholder.workspaceName', 'Workspace Name')}
+              placeholder={t('placeholder.workspaceName', { defaultValue: 'Workspace Name' })}
               autoFocus
             />
           </div>
 
           <div className="space-y-2 flex-1 flex flex-col min-h-0">
-            <Label>{t('field.selectHosts', 'Select Hosts')}</Label>
+            <Label>{t('field.selectHosts', { defaultValue: 'Select Hosts' })}</Label>
             <div className="relative">
                 <Search className="absolute left-2 top-2.5 h-4 w-4 text-muted-foreground" />
                 <Input
-                placeholder={t('placeholder.searchHosts', 'Search hosts...')}
+                placeholder={t('placeholder.searchHosts', { defaultValue: 'Search hosts...' })}
                 value={search}
                 onChange={(e) => setSearch(e.target.value)}
                 className="pl-8"
@@ -99,7 +99,7 @@ export const CreateWorkspaceDialog: React.FC<CreateWorkspaceDialogProps> = ({
                     <div className="p-2 space-y-1">
                         {filteredHosts.length === 0 ? (
                             <div className="text-center py-4 text-sm text-muted-foreground">
-                                {t('common.noResults', 'No hosts found')}
+                                {t('common.noResults', { defaultValue: 'No hosts found' })}
                             </div>
                         ) : (
                             filteredHosts.map(host => {
@@ -126,15 +126,15 @@ export const CreateWorkspaceDialog: React.FC<CreateWorkspaceDialogProps> = ({
                 </ScrollArea>
             </div>
             <div className="text-xs text-muted-foreground text-right">
-                {selectedHostIds.size} {t('common.selected', 'selected')}
+                {selectedHostIds.size} {t('common.selected', { defaultValue: 'selected' })}
             </div>
           </div>
         </div>
 
         <DialogFooter>
-          <Button variant="ghost" onClick={onClose}>{t('common.cancel', 'Cancel')}</Button>
+          <Button variant="ghost" onClick={onClose}>{t('common.cancel', { defaultValue: 'Cancel' })}</Button>
           <Button onClick={handleCreate} disabled={!name.trim() || selectedHostIds.size === 0}>
-            {t('common.create', 'Create')}
+            {t('common.create', { defaultValue: 'Create' })}
           </Button>
         </DialogFooter>
       </DialogContent>

components/DistroAvatar.tsx

@@ -22,6 +22,16 @@ export const DISTRO_LOGOS: Record<string, string> = {
   macos: "/distro/macos.svg",
   windows: "/distro/windows.svg",
   linux: "/distro/linux.svg",
+  // Network device vendors — auto-detected from the SSH server
+  // identification string (see domain/host.ts `detectVendorFromSshVersion`).
+  cisco: "/distro/cisco.svg",
+  juniper: "/distro/juniper.svg",
+  huawei: "/distro/huawei.svg",
+  hpe: "/distro/hpe.svg",
+  mikrotik: "/distro/mikrotik.svg",
+  fortinet: "/distro/fortinet.svg",
+  paloalto: "/distro/paloalto.svg",
+  zyxel: "/distro/zyxel.svg",
 };
 
 export const DISTRO_COLORS: Record<string, string> = {
@@ -42,6 +52,15 @@ export const DISTRO_COLORS: Record<string, string> = {
   macos: "bg-[#333333]",
   windows: "bg-[#0078D4]",
   linux: "bg-[#333333]",
+  // Network device vendor brand colors
+  cisco: "bg-[#1BA0D7]",
+  juniper: "bg-[#0A6EB4]",
+  huawei: "bg-[#CF0A2C]",
+  hpe: "bg-[#01A982]",
+  mikrotik: "bg-[#293239]",
+  fortinet: "bg-[#EE3124]",
+  paloalto: "bg-[#FA582D]",
+  zyxel: "bg-[#00497A]",
   default: "bg-slate-600",
 };
 

components/GroupDetailsPanel.tsx

@@ -21,6 +21,7 @@ import {
 import React, { useCallback, useMemo, useState } from "react";
 import { useI18n } from "../application/i18n/I18nProvider";
 import { customThemeStore } from "../application/state/customThemeStore";
+import { resolveGroupDefaults, resolveGroupTerminalThemeId } from "../domain/groupConfig";
 import { cn } from "../lib/utils";
 import {
   EnvVar,
@@ -39,6 +40,7 @@ import {
 import {
   AsidePanel,
   AsidePanelContent,
+  type AsidePanelLayout,
 } from "./ui/aside-panel";
 import { Badge } from "./ui/badge";
 import { Button } from "./ui/button";
@@ -60,9 +62,11 @@ interface GroupDetailsPanelProps {
   allHosts: Host[];
   groups: string[];
   terminalThemeId: string;
+  groupConfigs?: GroupConfig[];
   terminalFontSize: number;
   onSave: (config: GroupConfig, newName?: string, newParent?: string | null) => void;
   onCancel: () => void;
+  layout?: AsidePanelLayout;
 }
 
 const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
@@ -73,9 +77,11 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
   allHosts,
   groups,
   terminalThemeId,
+  groupConfigs = [],
   terminalFontSize,
   onSave,
   onCancel,
+  layout = "overlay",
 }) => {
   const { t } = useI18n();
   const availableFonts = useAvailableFonts();
@@ -274,7 +280,14 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
   }, [groups, groupPath, t]);
 
   // Effective theme
-  const effectiveThemeId = form.theme || terminalThemeId;
+  const inheritedThemeId = useMemo(() => {
+    if (!parentGroup || groupConfigs.length === 0) return terminalThemeId;
+    return resolveGroupTerminalThemeId(resolveGroupDefaults(parentGroup, groupConfigs), terminalThemeId);
+  }, [groupConfigs, parentGroup, terminalThemeId]);
+  const effectiveThemeId = form.themeOverride === false
+    ? inheritedThemeId
+    : (form.theme || inheritedThemeId);
+  const hasActiveThemeOverride = form.themeOverride === true || (form.theme != null && form.themeOverride !== false);
 
   // Save handler
   const handleSubmit = () => {
@@ -322,7 +335,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
       }),
       // Shared fields (always saved)
       ...(form.charset !== undefined && { charset: form.charset }),
-      ...(form.theme !== undefined && { theme: form.theme }),
+      ...((form.themeOverride !== false && form.theme !== undefined) && { theme: form.theme }),
       ...(form.themeOverride !== undefined && { themeOverride: form.themeOverride }),
       ...(form.fontFamily !== undefined && { fontFamily: form.fontFamily }),
       ...(form.fontFamilyOverride !== undefined && { fontFamilyOverride: form.fontFamilyOverride }),
@@ -351,6 +364,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         onClearProxy={clearProxyConfig}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -368,6 +382,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         onClearChain={clearHostChain}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -395,6 +410,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         }}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -405,12 +421,17 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
         open={true}
         selectedThemeId={effectiveThemeId}
         onSelect={(themeId) => {
+          if (themeId === effectiveThemeId && !hasActiveThemeOverride) {
+            setActiveSubPanel("none");
+            return;
+          }
           setForm((prev) => ({ ...prev, theme: themeId, themeOverride: true }));
           setActiveSubPanel("none");
         }}
         onClose={onCancel}
         onBack={() => setActiveSubPanel("none")}
         showBackButton={true}
+        layout={layout}
       />
     );
   }
@@ -426,7 +447,9 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
       open={true}
       onClose={onCancel}
       width="w-[380px]"
+      dataSection="group-details-panel"
       title={t("vault.groups.details")}
+      layout={layout}
       actions={
         <Button
           variant="ghost"
@@ -1018,7 +1041,7 @@ const GroupDetailsPanel: React.FC<GroupDetailsPanelProps> = ({
               {customThemeStore.getThemeById(effectiveThemeId)?.name || "Flexoki Dark"}
             </span>
           </button>
-          {form.themeOverride && (
+          {hasActiveThemeOverride && (
             <Button
               variant="ghost"
               size="sm"

components/HostDetailsPanel.tsx

@@ -31,7 +31,12 @@ import {
 import React, { useEffect, useMemo, useState, useCallback } from "react";
 import { useI18n } from "../application/i18n/I18nProvider";
 import { useApplicationBackend } from "../application/state/useApplicationBackend";
-import { getEffectiveHostDistro, LINUX_DISTRO_OPTIONS } from "../domain/host";
+import { resolveGroupDefaults, resolveGroupTerminalThemeId } from "../domain/groupConfig";
+import {
+  getEffectiveHostDistro,
+  LINUX_DISTRO_OPTIONS,
+  NETWORK_DEVICE_OPTIONS,
+} from "../domain/host";
 import { customThemeStore } from "../application/state/customThemeStore";
 import {
   clearHostFontSizeOverride,
@@ -43,7 +48,7 @@ import {
 } from "../domain/terminalAppearance";
 import { MIN_FONT_SIZE, MAX_FONT_SIZE } from "../infrastructure/config/fonts";
 import { cn } from "../lib/utils";
-import { EnvVar, Host, Identity, ManagedSource, ProxyConfig, SSHKey } from "../types";
+import { EnvVar, GroupConfig, Host, Identity, ManagedSource, ProxyConfig, SSHKey } from "../types";
 import { DISTRO_COLORS, DISTRO_LOGOS } from "./DistroAvatar";
 import { DistroAvatar } from "./DistroAvatar";
 import ThemeSelectPanel from "./ThemeSelectPanel";
@@ -51,6 +56,7 @@ import {
   AsidePanel,
   AsidePanelContent,
   AsidePanelFooter,
+  type AsidePanelLayout,
 } from "./ui/aside-panel";
 import { Badge } from "./ui/badge";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./ui/tooltip";
@@ -82,7 +88,10 @@ type SubPanel =
   | "theme-select"
   | "telnet-theme-select";
 
-const LINUX_DISTRO_OPTION_IDS = [...LINUX_DISTRO_OPTIONS];
+const LINUX_DISTRO_OPTION_IDS = [
+  ...LINUX_DISTRO_OPTIONS,
+  ...NETWORK_DEVICE_OPTIONS,
+];
 
 interface HostDetailsPanelProps {
   initialData?: Host | null;
@@ -100,6 +109,8 @@ interface HostDetailsPanelProps {
   onCreateGroup?: (groupPath: string) => void; // Callback to create a new group
   onCreateTag?: (tag: string) => void; // Callback to create a new tag
   groupDefaults?: Partial<import('../domain/models').GroupConfig>;
+  groupConfigs?: GroupConfig[];
+  layout?: AsidePanelLayout;
 }
 
 const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
@@ -118,6 +129,8 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
   onCreateGroup,
   onCreateTag,
   groupDefaults,
+  groupConfigs = [],
+  layout = "overlay",
 }) => {
   const { t } = useI18n();
   const { checkSshAgent } = useApplicationBackend();
@@ -201,9 +214,17 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
     setForm((prev) => ({ ...prev, [key]: value }));
   };
 
+  const effectiveGroupDefaults = useMemo(() => {
+    const currentGroupPath = form.group || defaultGroup;
+    if (currentGroupPath && groupConfigs.length > 0) {
+      return resolveGroupDefaults(currentGroupPath, groupConfigs);
+    }
+    return groupDefaults;
+  }, [defaultGroup, form.group, groupConfigs, groupDefaults]);
+
   const effectiveThemeId = useMemo(
-    () => resolveHostTerminalThemeId(form, terminalThemeId),
-    [form, terminalThemeId],
+    () => resolveHostTerminalThemeId(form, resolveGroupTerminalThemeId(effectiveGroupDefaults, terminalThemeId)),
+    [effectiveGroupDefaults, form, terminalThemeId],
   );
   const effectiveFontSize = useMemo(
     () => resolveHostTerminalFontSize(form, terminalFontSize),
@@ -502,6 +523,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onSave={handleCreateGroup}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -514,6 +536,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClearProxy={clearProxyConfig}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -531,6 +554,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClearChain={clearHostChain}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -559,6 +583,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         }}
         onBack={() => setActiveSubPanel("none")}
         onCancel={onCancel}
+        layout={layout}
       />
     );
   }
@@ -570,12 +595,17 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         open={true}
         selectedThemeId={effectiveThemeId}
         onSelect={(themeId) => {
+          if (themeId === effectiveThemeId && !hasEffectiveThemeOverride) {
+            setActiveSubPanel("none");
+            return;
+          }
           setForm((prev) => ({ ...prev, theme: themeId, themeOverride: true }));
           setActiveSubPanel("none");
         }}
         onClose={onCancel}
         onBack={() => setActiveSubPanel("none")}
         showBackButton={true}
+        layout={layout}
       />
     );
   }
@@ -614,6 +644,7 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
         onClose={onCancel}
         onBack={() => setActiveSubPanel("none")}
         showBackButton={true}
+        layout={layout}
       />
     );
   }
@@ -624,6 +655,8 @@ const HostDetailsPanel: React.FC<HostDetailsPanelProps> = ({
       open={true}
       onClose={onCancel}
       width="w-[420px]"
+      layout={layout}
+      dataSection="host-details-panel"
       title={
         initialData ? t("hostDetails.title.details") : t("hostDetails.title.new")
       }

components/HostTreeView.tsx

@@ -36,6 +36,8 @@ interface HostTreeViewProps {
   isMultiSelectMode?: boolean;
   selectedHostIds?: Set<string>;
   toggleHostSelection?: (hostId: string) => void;
+  getDropTargetClasses?: (target: string) => string;
+  setDragOverDropTarget?: (target: string | null) => void;
 }
 
 interface TreeNodeProps {
@@ -61,6 +63,8 @@ interface TreeNodeProps {
   isMultiSelectMode?: boolean;
   selectedHostIds?: Set<string>;
   toggleHostSelection?: (hostId: string) => void;
+  getDropTargetClasses?: (target: string) => string;
+  setDragOverDropTarget?: (target: string | null) => void;
 }
 
 
@@ -87,6 +91,8 @@ const TreeNode: React.FC<TreeNodeProps> = ({
   isMultiSelectMode,
   selectedHostIds,
   toggleHostSelection,
+  getDropTargetClasses,
+  setDragOverDropTarget,
 }) => {
   const { t } = useI18n();
   const isExpanded = expandedPaths.has(node.path);
@@ -140,6 +146,7 @@ const TreeNode: React.FC<TreeNodeProps> = ({
               <div
                 className={cn(
                   "flex items-center py-2 pr-3 text-sm font-medium cursor-pointer transition-colors select-none group hover:bg-secondary/60 rounded-lg",
+                  getDropTargetClasses?.(node.path),
                 )}
                 style={{ paddingLeft }}
                 draggable
@@ -147,10 +154,19 @@ const TreeNode: React.FC<TreeNodeProps> = ({
                 onDragOver={(e) => {
                   e.preventDefault();
                   e.stopPropagation();
+                  setDragOverDropTarget?.(node.path);
+                }}
+                onDragLeave={(e) => {
+                  const nextTarget = e.relatedTarget;
+                  if (nextTarget instanceof Node && e.currentTarget.contains(nextTarget)) {
+                    return;
+                  }
+                  setDragOverDropTarget?.(null);
                 }}
                 onDrop={(e) => {
                   e.preventDefault();
                   e.stopPropagation();
+                  setDragOverDropTarget?.(null);
                   const hostId = e.dataTransfer.getData("host-id");
                   const groupPath = e.dataTransfer.getData("group-path");
                   if (hostId) moveHostToGroup(hostId, node.path);
@@ -242,6 +258,8 @@ const TreeNode: React.FC<TreeNodeProps> = ({
               isMultiSelectMode={isMultiSelectMode}
               selectedHostIds={selectedHostIds}
               toggleHostSelection={toggleHostSelection}
+              getDropTargetClasses={getDropTargetClasses}
+              setDragOverDropTarget={setDragOverDropTarget}
             />
           ))}
 
@@ -425,9 +443,11 @@ export const HostTreeView: React.FC<HostTreeViewProps> = ({
   isMultiSelectMode,
   selectedHostIds,
   toggleHostSelection,
+  getDropTargetClasses,
+  setDragOverDropTarget,
 }) => {
   const { t } = useI18n();
-  
+
   // Use external state if provided, otherwise use local persistent state
   const localTreeState = useTreeExpandedState(STORAGE_KEY_VAULT_HOSTS_TREE_EXPANDED);
   
@@ -548,6 +568,8 @@ export const HostTreeView: React.FC<HostTreeViewProps> = ({
           isMultiSelectMode={isMultiSelectMode}
           selectedHostIds={selectedHostIds}
           toggleHostSelection={toggleHostSelection}
+          getDropTargetClasses={getDropTargetClasses}
+          setDragOverDropTarget={setDragOverDropTarget}
         />
       ))}
 
@@ -578,4 +600,4 @@ export const HostTreeView: React.FC<HostTreeViewProps> = ({
       )}
     </div>
   );
-};
+};

components/KeyboardInteractiveModal.tsx

@@ -4,7 +4,7 @@
  * This modal displays prompts from the SSH server and collects user responses.
  */
 import { Eye, EyeOff, KeyRound, Loader2 } from "lucide-react";
-import React, { useCallback, useEffect, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { useI18n } from "../application/i18n/I18nProvider";
 import { Button } from "./ui/button";
 import {
@@ -24,6 +24,7 @@ export interface KeyboardInteractivePrompt {
 
 export interface KeyboardInteractiveRequest {
   requestId: string;
+  sessionId?: string;
   name: string;
   instructions: string;
   prompts: KeyboardInteractivePrompt[];
@@ -31,9 +32,18 @@ export interface KeyboardInteractiveRequest {
   savedPassword?: string | null;
 }
 
+const isAPasswordPrompt = (prompt: KeyboardInteractivePrompt) => {
+  if (prompt.echo) return false;
+  const lower = prompt.prompt.toLowerCase();
+  if (!lower.includes("password")) return false;
+  // Exclude OTP / one-time password / verification code prompts
+  if (lower.includes("one-time") || lower.includes("otp") || lower.includes("verification") || lower.includes("token") || lower.includes("code")) return false;
+  return true;
+};
+
 interface KeyboardInteractiveModalProps {
   request: KeyboardInteractiveRequest | null;
-  onSubmit: (requestId: string, responses: string[]) => void;
+  onSubmit: (requestId: string, responses: string[], savePassword?: string) => void;
   onCancel: (requestId: string) => void;
 }
 
@@ -46,15 +56,28 @@ export const KeyboardInteractiveModal: React.FC<KeyboardInteractiveModalProps> =
   const [responses, setResponses] = useState<string[]>([]);
   const [showPasswords, setShowPasswords] = useState<boolean[]>([]);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  const [savePassword, setSavePassword] = useState(false);
+
+  // Index of the first password prompt (if any)
+  const passwordPromptIndex = useMemo(() => {
+    if (!request) return -1;
+    return request.prompts.findIndex(p => isAPasswordPrompt(p));
+  }, [request]);
 
   // Reset state when request changes
   useEffect(() => {
     if (request) {
-      setResponses(request.prompts.map(() => ""));
+      const initial = request.prompts.map(() => "");
+      // Auto-fill saved password into the password prompt
+      if (request.savedPassword && passwordPromptIndex >= 0) {
+        initial[passwordPromptIndex] = request.savedPassword;
+      }
+      setResponses(initial);
       setShowPasswords(request.prompts.map(() => false));
       setIsSubmitting(false);
+      setSavePassword(false);
     }
-  }, [request]);
+  }, [request, passwordPromptIndex]);
 
   const handleResponseChange = useCallback((index: number, value: string) => {
     setResponses((prev) => {
@@ -75,8 +98,11 @@ export const KeyboardInteractiveModal: React.FC<KeyboardInteractiveModalProps> =
   const handleSubmit = useCallback(() => {
     if (!request || isSubmitting) return;
     setIsSubmitting(true);
-    onSubmit(request.requestId, responses);
-  }, [request, responses, onSubmit, isSubmitting]);
+    const passwordToSave = savePassword && passwordPromptIndex >= 0
+      ? responses[passwordPromptIndex]
+      : undefined;
+    onSubmit(request.requestId, responses, passwordToSave);
+  }, [request, responses, onSubmit, isSubmitting, savePassword, passwordPromptIndex]);
 
   const handleCancel = useCallback(() => {
     if (!request) return;
@@ -154,19 +180,20 @@ export const KeyboardInteractiveModal: React.FC<KeyboardInteractiveModalProps> =
                     </button>
                   )}
                 </div>
-                {/* Use saved password button - shown below input, right-aligned */}
-                {isPassword && request.savedPassword && !responses[index] && (
-                  <div className="flex justify-end">
-                    <button
-                      type="button"
-                      className="flex items-center gap-1 text-xs text-primary hover:text-primary/80 disabled:opacity-50"
-                      onClick={() => handleResponseChange(index, request.savedPassword!)}
+                {/* Save password checkbox - shown only for the first password prompt */}
+                {index === passwordPromptIndex && (
+                  <label className="flex items-center gap-2 cursor-pointer select-none">
+                    <input
+                      type="checkbox"
+                      checked={savePassword}
+                      onChange={(e) => setSavePassword(e.target.checked)}
                       disabled={isSubmitting}
-                    >
-                      <KeyRound size={12} />
-                      <span>{t("keyboard.interactive.useSavedPassword")}</span>
-                    </button>
-                  </div>
+                      className="accent-primary"
+                    />
+                    <span className="text-xs text-muted-foreground">
+                      {t("keyboard.interactive.savePassword")}
+                    </span>
+                  </label>
                 )}
               </div>
             );

components/KeychainManager.tsx

@@ -515,12 +515,12 @@ echo $3 >> "$FILE"`);
       {/* Main Content */}
       <div
         className={cn(
-          "flex-1 overflow-y-auto transition-all duration-200",
+          "flex-1 flex flex-col min-h-0 transition-all duration-200",
           panel.type !== "closed" && "mr-[380px]",
         )}
       >
         {/* Toolbar */}
-        <div className="flex flex-wrap items-center gap-3 bg-secondary/60 border-b border-border/70 px-3 py-1.5">
+        <div className="flex flex-wrap items-center gap-3 bg-secondary/60 border-b border-border/70 px-3 py-1.5 shrink-0">
           {/* Filter Tabs */}
           <div className="flex items-center gap-1">
             {/* KEY button with split interaction: left=switch view, right=dropdown */}
@@ -684,8 +684,10 @@ echo $3 >> "$FILE"`);
           </div>
         </div>
 
-        {/* Keys Section */}
-        <div className="space-y-3 p-3">
+        {/* Scrollable Content */}
+        <div className="flex-1 overflow-y-auto">
+          {/* Keys Section */}
+          <div className="space-y-3 p-3">
           <div className="flex items-center justify-between">
             <h2 className="text-base font-semibold text-muted-foreground">
               {t("keychain.section.keys")}
@@ -817,6 +819,7 @@ echo $3 >> "$FILE"`);
             </div>
           </div>
         )}
+        </div>
       </div>
 
       {/* Slide-out Panel */}

components/LogView.tsx

@@ -36,19 +36,35 @@ const LogViewComponent: React.FC<LogViewProps> = ({
     const [isReady, setIsReady] = useState(false);
     const [themeModalOpen, setThemeModalOpen] = useState(false);
     const [isExporting, setIsExporting] = useState(false);
+    const [previewTheme, setPreviewTheme] = useState<TerminalTheme | null>(null);
 
     // Subscribe to custom theme changes so editing triggers re-render
     const customThemes = useCustomThemes();
+    const explicitThemeId = useMemo(() => {
+        if (!log.themeId) return undefined;
+        const exists = TERMINAL_THEMES.some((theme) => theme.id === log.themeId)
+            || customThemes.some((theme) => theme.id === log.themeId);
+        return exists ? log.themeId : undefined;
+    }, [customThemes, log.themeId]);
+
+    useEffect(() => {
+        if (log.themeId && !explicitThemeId) {
+            onUpdateLog(log.id, { themeId: undefined });
+        }
+    }, [explicitThemeId, log.id, log.themeId, onUpdateLog]);
 
     // Use log's saved theme/fontSize or fall back to defaults
     const currentTheme = useMemo(() => {
-        if (log.themeId) {
-            return TERMINAL_THEMES.find(t => t.id === log.themeId)
-                || customThemes.find(t => t.id === log.themeId)
+        if (previewTheme) {
+            return previewTheme;
+        }
+        if (explicitThemeId) {
+            return TERMINAL_THEMES.find(t => t.id === explicitThemeId)
+                || customThemes.find(t => t.id === explicitThemeId)
                 || defaultTerminalTheme;
         }
         return defaultTerminalTheme;
-    }, [log.themeId, defaultTerminalTheme, customThemes]);
+    }, [customThemes, defaultTerminalTheme, explicitThemeId, previewTheme]);
 
     const currentFontSize = log.fontSize ?? defaultFontSize;
 
@@ -69,6 +85,12 @@ const LogViewComponent: React.FC<LogViewProps> = ({
         onUpdateLog(log.id, { themeId });
     }, [log.id, onUpdateLog]);
 
+    useEffect(() => {
+        if (!themeModalOpen) {
+            setPreviewTheme(null);
+        }
+    }, [themeModalOpen]);
+
     // Handle font size change
     const handleFontSizeChange = useCallback((fontSize: number) => {
         onUpdateLog(log.id, { fontSize });
@@ -295,10 +317,13 @@ const LogViewComponent: React.FC<LogViewProps> = ({
             <ThemeCustomizeModal
                 open={themeModalOpen}
                 onClose={() => setThemeModalOpen(false)}
-                currentThemeId={currentTheme.id}
+                currentThemeId={explicitThemeId}
+                displayThemeId={currentTheme.id}
                 currentFontSize={currentFontSize}
                 onThemeChange={handleThemeChange}
+                onThemeReset={() => onUpdateLog(log.id, { themeId: undefined })}
                 onFontSizeChange={handleFontSizeChange}
+                onPreviewThemeChange={setPreviewTheme}
             />
         </div>
     );

components/QuickAddSnippetDialog.tsx

@@ -0,0 +1,185 @@
+/**
+ * QuickAddSnippetDialog — lightweight "new snippet" modal mounted at the
+ * App root and triggered by the `netcatty:snippets:add` window event.
+ *
+ * Intentionally minimal: label + command + package only. Advanced fields
+ * (target hosts, shortkey, tags) can be set later via the full Snippets
+ * manager. This keeps the user in their terminal context instead of
+ * navigating to the Vault view just to add a command.
+ */
+
+import { Package } from 'lucide-react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useI18n } from '../application/i18n/I18nProvider';
+import type { Snippet } from '../domain/models';
+import { Button } from './ui/button';
+import { Combobox } from './ui/combobox';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from './ui/dialog';
+import { Input } from './ui/input';
+import { Label } from './ui/label';
+import { Textarea } from './ui/textarea';
+
+export interface QuickAddSnippetDialogProps {
+  snippets: Snippet[];
+  packages: string[];
+  onCreateSnippet: (snippet: Snippet) => void;
+  onCreatePackage?: (packagePath: string) => void;
+}
+
+export const QuickAddSnippetDialog: React.FC<QuickAddSnippetDialogProps> = ({
+  snippets,
+  packages,
+  onCreateSnippet,
+  onCreatePackage,
+}) => {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(false);
+  const [label, setLabel] = useState('');
+  const [command, setCommand] = useState('');
+  const [packagePath, setPackagePath] = useState('');
+  const labelInputRef = useRef<HTMLInputElement>(null);
+
+  // Listen for the global "add snippet" request dispatched by the
+  // terminal-side ScriptsSidePanel + button. We reset form state on
+  // every open so stale input from a previous cancel does not leak.
+  useEffect(() => {
+    const handler = () => {
+      setLabel('');
+      setCommand('');
+      setPackagePath('');
+      setOpen(true);
+    };
+    window.addEventListener('netcatty:snippets:add', handler);
+    return () => window.removeEventListener('netcatty:snippets:add', handler);
+  }, []);
+
+  // Auto-focus the label input once the dialog renders, so the user can
+  // start typing immediately after clicking the + button.
+  useEffect(() => {
+    if (!open) return;
+    const id = window.setTimeout(() => labelInputRef.current?.focus(), 50);
+    return () => window.clearTimeout(id);
+  }, [open]);
+
+  // Derive combobox options from the union of existing packages (from
+  // props) and any package path referenced by an existing snippet, so
+  // the user can reuse anything they see in the main snippets view.
+  const packageOptions = useMemo(() => {
+    const set = new Set<string>();
+    for (const p of packages) {
+      if (p) set.add(p);
+    }
+    for (const s of snippets) {
+      if (s.package) set.add(s.package);
+    }
+    return Array.from(set).sort().map((value) => ({ value, label: value }));
+  }, [packages, snippets]);
+
+  const canSave = label.trim().length > 0 && command.trim().length > 0;
+
+  const handleSave = useCallback(() => {
+    if (!canSave) return;
+    const trimmedPackage = packagePath.trim();
+    // If the user typed a brand new package name, surface it to the parent
+    // so it can be added to the user's package list alongside the snippet.
+    if (trimmedPackage && !packages.includes(trimmedPackage)) {
+      onCreatePackage?.(trimmedPackage);
+    }
+    onCreateSnippet({
+      id: crypto.randomUUID(),
+      label: label.trim(),
+      command, // preserve whitespace in multi-line commands
+      tags: [],
+      package: trimmedPackage || '',
+      targets: [],
+    });
+    setOpen(false);
+  }, [canSave, packagePath, packages, onCreatePackage, onCreateSnippet, label, command]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      // Cmd/Ctrl+Enter from anywhere in the dialog saves the snippet.
+      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter' && canSave) {
+        e.preventDefault();
+        handleSave();
+      }
+    },
+    [canSave, handleSave],
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent className="max-w-md" onKeyDown={handleKeyDown}>
+        <DialogHeader>
+          <DialogTitle>{t('snippets.panel.newTitle')}</DialogTitle>
+          <DialogDescription>
+            {t('snippets.empty.desc')}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3">
+          <div className="space-y-1.5">
+            <Label htmlFor="quick-add-snippet-label" className="text-xs">
+              {t('snippets.field.description')}
+            </Label>
+            <Input
+              id="quick-add-snippet-label"
+              ref={labelInputRef}
+              value={label}
+              onChange={(e) => setLabel(e.target.value)}
+              placeholder={t('snippets.field.descriptionPlaceholder')}
+              className="h-9"
+            />
+          </div>
+
+          <div className="space-y-1.5">
+            <Label htmlFor="quick-add-snippet-command" className="text-xs">
+              {t('snippets.field.scriptRequired')}
+            </Label>
+            <Textarea
+              id="quick-add-snippet-command"
+              value={command}
+              onChange={(e) => setCommand(e.target.value)}
+              placeholder="echo hello"
+              className="min-h-[120px] font-mono text-xs"
+              spellCheck={false}
+            />
+          </div>
+
+          <div className="space-y-1.5">
+            <Label className="text-xs flex items-center gap-1.5">
+              <Package size={12} /> {t('snippets.field.package')}
+            </Label>
+            <Combobox
+              value={packagePath}
+              onValueChange={setPackagePath}
+              options={packageOptions}
+              placeholder={t('snippets.field.packagePlaceholder')}
+              allowCreate
+              onCreateNew={setPackagePath}
+              createText={t('snippets.field.createPackage')}
+            />
+          </div>
+        </div>
+
+        <DialogFooter>
+          <Button variant="outline" onClick={() => setOpen(false)}>
+            {t('common.cancel')}
+          </Button>
+          <Button onClick={handleSave} disabled={!canSave}>
+            {t('common.save')}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+export default QuickAddSnippetDialog;

components/QuickSwitcher.tsx

@@ -70,6 +70,7 @@ interface QuickSwitcherProps {
   onCreateLocalTerminal?: (shell?: { command: string; args?: string[]; name?: string; icon?: string }) => void;
   // onCreateWorkspace removed - feature not currently used
   keyBindings?: KeyBinding[];
+  showSftpTab: boolean;
 }
 
 const QuickSwitcherInner: React.FC<QuickSwitcherProps> = ({
@@ -84,16 +85,19 @@ const QuickSwitcherInner: React.FC<QuickSwitcherProps> = ({
   onClose,
   onCreateLocalTerminal,
   keyBindings,
+  showSftpTab,
 }) => {
   const { t } = useI18n();
   const discoveredShells = useDiscoveredShells();
 
   const filteredShells = useMemo(() => {
-    if (!query.trim()) return discoveredShells;
-    const q = query.toLowerCase();
-    return discoveredShells.filter(
-      (s) => s.name.toLowerCase().includes(q) || s.id.toLowerCase().includes(q)
-    );
+    const list = !query.trim()
+      ? discoveredShells
+      : discoveredShells.filter(
+          (s) => s.name.toLowerCase().includes(query.toLowerCase()) || s.id.toLowerCase().includes(query.toLowerCase())
+        );
+    // Default shell first
+    return [...list].sort((a, b) => (a.isDefault === b.isDefault ? 0 : a.isDefault ? -1 : 1));
   }, [discoveredShells, query]);
 
   // Get hotkey display strings
@@ -159,7 +163,7 @@ const QuickSwitcherInner: React.FC<QuickSwitcherProps> = ({
       );
       // Tabs (built-in + sessions + workspaces)
       items.push({ type: "tab", id: "vault" });
-      items.push({ type: "tab", id: "sftp" });
+      if (showSftpTab) items.push({ type: "tab", id: "sftp" });
       orphanSessions.forEach((s) =>
         items.push({ type: "tab", id: s.id, data: s }),
       );
@@ -192,7 +196,7 @@ const QuickSwitcherInner: React.FC<QuickSwitcherProps> = ({
     });
 
     return { flatItems: items, itemIndexMap: indexMap };
-  }, [showCategorized, results, orphanSessions, workspaces, filteredShells]);
+  }, [showCategorized, results, orphanSessions, workspaces, filteredShells, showSftpTab]);
 
   // O(1) index lookup
   const getItemIndex = useCallback((type: string, id: string) => {
@@ -315,7 +319,7 @@ const QuickSwitcherInner: React.FC<QuickSwitcherProps> = ({
               </div>
 
               {/* Built-in tabs */}
-              {["vault", "sftp"].map((tabId) => {
+              {(showSftpTab ? ["vault", "sftp"] : ["vault"]).map((tabId) => {
                 const idx = getItemIndex("tab", tabId);
                 const isSelected = idx === selectedIndex;
                 const icon =

components/ScriptsSidePanel.tsx

@@ -5,7 +5,7 @@
  * Clicking a snippet executes it in the focused terminal session.
  */
 
-import { ChevronRight, Package, Search, Zap } from 'lucide-react';
+import { ChevronRight, Package, Plus, Search, Zap } from 'lucide-react';
 import React, { memo, useCallback, useMemo, useState } from 'react';
 import { useI18n } from '../application/i18n/I18nProvider';
 import { cn } from '../lib/utils';
@@ -119,15 +119,25 @@ const ScriptsSidePanelInner: React.FC<ScriptsSidePanelProps> = ({
     onSnippetClick(command, noAutoRun);
   }, [onSnippetClick]);
 
+  const handleAddSnippet = useCallback(() => {
+    // Let the App shell listen and navigate to the Snippets section with
+    // the "add" panel pre-opened, so the user does not have to leave the
+    // terminal to jump back and click "New Snippet".
+    window.dispatchEvent(new CustomEvent('netcatty:snippets:add'));
+  }, []);
+
   if (!isVisible) return null;
 
   const hasAnyContent = snippets.length > 0 || packages.length > 0;
 
   return (
-    <div className="h-full flex flex-col bg-background overflow-hidden">
-      {/* Search */}
-      <div className="shrink-0 px-2 py-1.5 border-b border-border/50">
-        <div className="relative">
+    <div
+      className="h-full flex flex-col bg-background overflow-hidden"
+      data-section="snippets-panel"
+    >
+      {/* Search + Add */}
+      <div className="shrink-0 px-2 py-1.5 border-b border-border/50 flex items-center gap-1.5">
+        <div className="relative flex-1 min-w-0">
           <Search size={12} className="absolute left-2 top-1/2 -translate-y-1/2 text-muted-foreground" />
           <Input
             value={search}
@@ -136,6 +146,15 @@ const ScriptsSidePanelInner: React.FC<ScriptsSidePanelProps> = ({
             className="h-7 pl-7 text-xs bg-muted/30 border-none"
           />
         </div>
+        <button
+          type="button"
+          onClick={handleAddSnippet}
+          title={t('snippets.action.newSnippet')}
+          aria-label={t('snippets.action.newSnippet')}
+          className="shrink-0 h-7 w-7 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/60 transition-colors"
+        >
+          <Plus size={14} />
+        </button>
       </div>
 
       {/* Breadcrumb */}

components/SelectHostPanel.tsx

@@ -1,11 +1,9 @@
 import {
-  ArrowLeft,
   Check,
   ChevronRight,
   LayoutGrid,
   Plus,
   Search,
-  X,
 } from "lucide-react";
 import React, { useMemo, useState } from "react";
 import { cn } from "../lib/utils";
@@ -14,6 +12,7 @@ import { Host, SSHKey } from "../types";
 import { ManagedSource } from "../domain/models";
 import { DistroAvatar } from "./DistroAvatar";
 import HostDetailsPanel from "./HostDetailsPanel";
+import { AsidePanel, type AsidePanelLayout } from "./ui/aside-panel";
 import { Button } from "./ui/button";
 import { Input } from "./ui/input";
 import { ScrollArea } from "./ui/scroll-area";
@@ -44,6 +43,7 @@ interface SelectHostPanelProps {
   title?: string;
   subtitle?: string;
   className?: string;
+  layout?: AsidePanelLayout;
 }
 
 const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
@@ -63,6 +63,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
   title,
   subtitle,
   className,
+  layout = "overlay",
 }) => {
   const { t } = useI18n();
   const panelTitle = title ?? t("selectHost.title");
@@ -205,35 +206,20 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
 
   return (
     <TooltipProvider delayDuration={300}>
-    <div
+    <AsidePanel
+      open={true}
+      onClose={onBack}
+      title={panelTitle}
+      subtitle={subtitle}
+      showBackButton={true}
+      onBack={onBack}
       className={cn(
-        "absolute right-0 top-0 bottom-0 w-[380px] border-l border-border/60 bg-background z-40 flex flex-col app-no-drag",
+        layout === "overlay" && "z-40",
+        showNewHostPanel && "overflow-visible",
         className,
       )}
+      layout={layout}
     >
-      {/* Header */}
-      <div className="px-4 py-3 border-b border-border/60 flex items-center justify-between gap-3 shrink-0">
-        <div className="flex items-center gap-3 min-w-0">
-          <button
-            onClick={onBack}
-            className="p-1 hover:bg-muted rounded-md transition-colors cursor-pointer shrink-0"
-          >
-            <ArrowLeft size={18} />
-          </button>
-          <div className="min-w-0">
-            <h3 className="text-sm font-semibold">{panelTitle}</h3>
-            {subtitle && (
-              <p className="text-xs text-muted-foreground">{subtitle}</p>
-            )}
-          </div>
-        </div>
-        <button
-          onClick={onBack}
-          className="p-1.5 hover:bg-muted rounded-md transition-colors cursor-pointer shrink-0"
-        >
-          <X size={18} />
-        </button>
-      </div>
 
       {/* Toolbar */}
       <div className="px-4 py-3 flex items-center gap-2 border-b border-border/60 shrink-0">
@@ -277,7 +263,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
       </div>
 
       {/* Content */}
-      <ScrollArea className="flex-1">
+      <ScrollArea className="flex-1 min-w-0">
         <div className="p-3 space-y-3">
           {/* Breadcrumbs */}
           {currentPath && (
@@ -398,7 +384,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
       </ScrollArea>
 
       {/* Footer */}
-      <div className="px-4 py-3 border-t border-border/60">
+      <div className="px-4 py-3 border-t border-border/60 shrink-0">
         <Button
           className="w-full"
           disabled={selectedHostIds.length === 0}
@@ -436,7 +422,7 @@ const SelectHostPanel: React.FC<SelectHostPanelProps> = ({
           onCreateGroup={onCreateGroup}
         />
       )}
-    </div>
+    </AsidePanel>
     </TooltipProvider>
   );
 };

components/SerialHostDetailsPanel.tsx

@@ -17,6 +17,7 @@ import {
   AsidePanel,
   AsidePanelContent,
   AsidePanelFooter,
+  type AsidePanelLayout,
 } from './ui/aside-panel';
 
 interface SerialPort {
@@ -35,6 +36,7 @@ interface SerialHostDetailsPanelProps {
   groups?: string[];
   onSave: (host: Host) => void;
   onCancel: () => void;
+  layout?: AsidePanelLayout;
 }
 
 const BAUD_RATES = [300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600];
@@ -49,6 +51,7 @@ export const SerialHostDetailsPanel: React.FC<SerialHostDetailsPanelProps> = ({
   groups = [],
   onSave,
   onCancel,
+  layout = 'overlay',
 }) => {
   const { t } = useI18n();
   const terminalBackend = useTerminalBackend();
@@ -164,6 +167,8 @@ export const SerialHostDetailsPanel: React.FC<SerialHostDetailsPanelProps> = ({
       title={t('serial.edit.title')}
       subtitle={initialData.label}
       className="z-40"
+      layout={layout}
+      dataSection="serial-host-details-panel"
     >
       <AsidePanelContent>
         {/* Label */}

components/SettingsApplicationTab.tsx

@@ -96,6 +96,18 @@ export default function SettingsApplicationTab({ updateState, checkNow, openRele
     };
   }, [getApplicationInfo]);
 
+  const handleOpenExternal = async (url: string) => {
+    try {
+      await openExternal(url);
+    } catch (err) {
+      console.warn("[SettingsApplicationTab] openExternal failed:", err);
+      toast.error(
+        t("settings.application.openExternal.failedBody"),
+        t("settings.application.openExternal.failedTitle"),
+      );
+    }
+  };
+
   const handleCheckForUpdates = async () => {
     // In demo mode, allow checking even for dev builds
     if (!isUpdateDemoMode && (!appInfo.version || appInfo.version === '0.0.0')) {
@@ -198,25 +210,25 @@ export default function SettingsApplicationTab({ updateState, checkNow, openRele
               icon={<Bug size={18} />}
               title={t("settings.application.reportProblem")}
               subtitle={t("settings.application.reportProblem.subtitle")}
-              onClick={() => void openExternal(issueUrl)}
+              onClick={() => void handleOpenExternal(issueUrl)}
             />
             <ActionRow
               icon={<MessageCircle size={18} />}
               title={t("settings.application.community")}
               subtitle={t("settings.application.community.subtitle")}
-              onClick={() => void openExternal(discussionsUrl)}
+              onClick={() => void handleOpenExternal(discussionsUrl)}
             />
             <ActionRow
               icon={<Github size={18} />}
               title="GitHub"
               subtitle={t("settings.application.github.subtitle")}
-              onClick={() => void openExternal(REPO_URL)}
+              onClick={() => void handleOpenExternal(REPO_URL)}
             />
             <ActionRow
               icon={<Newspaper size={18} />}
               title={t("settings.application.whatsNew")}
               subtitle={t("settings.application.whatsNew.subtitle")}
-              onClick={() => void openExternal(releasesUrl)}
+              onClick={() => void handleOpenExternal(releasesUrl)}
             />
           </div>
         </div>

components/SettingsPage.tsx

@@ -41,7 +41,7 @@ class AITabErrorBoundary extends React.Component<
         </div>
       );
     }
-    return this.props.children;
+    return (this.props as { children: React.ReactNode }).children;
   }
 }
 
@@ -56,6 +56,8 @@ const SettingsTerminalTabContainer: React.FC<{ settings: SettingsState }> = ({ s
         <SettingsTerminalTab
             terminalThemeId={settings.terminalThemeId}
             setTerminalThemeId={settings.setTerminalThemeId}
+            followAppTerminalTheme={settings.followAppTerminalTheme}
+            setFollowAppTerminalTheme={settings.setFollowAppTerminalTheme}
             terminalFontFamilyId={settings.terminalFontFamilyId}
             setTerminalFontFamilyId={settings.setTerminalFontFamilyId}
             terminalFontSize={settings.terminalFontSize}
@@ -86,6 +88,8 @@ const SettingsAITabContainer: React.FC = () => {
                     setActiveModelId={aiState.setActiveModelId}
                     globalPermissionMode={aiState.globalPermissionMode}
                     setGlobalPermissionMode={aiState.setGlobalPermissionMode}
+                    toolIntegrationMode={aiState.toolIntegrationMode}
+                    setToolIntegrationMode={aiState.setToolIntegrationMode}
                     externalAgents={aiState.externalAgents}
                     setExternalAgents={aiState.setExternalAgents}
                     defaultAgentId={aiState.defaultAgentId}
@@ -282,6 +286,12 @@ const SettingsPageContent: React.FC<{ settings: SettingsState }> = ({ settings }
                             setUiLanguage={settings.setUiLanguage}
                             customCSS={settings.customCSS}
                             setCustomCSS={settings.setCustomCSS}
+                            showRecentHosts={settings.showRecentHosts}
+                            setShowRecentHosts={settings.setShowRecentHosts}
+                            showOnlyUngroupedHostsInRoot={settings.showOnlyUngroupedHostsInRoot}
+                            setShowOnlyUngroupedHostsInRoot={settings.setShowOnlyUngroupedHostsInRoot}
+                            showSftpTab={settings.showSftpTab}
+                            setShowSftpTab={settings.setShowSftpTab}
                         />
                     )}
 

components/SnippetsManager.tsx

@@ -8,7 +8,7 @@ import { Host, ShellHistoryEntry, Snippet, SSHKey } from '../types';
 import { HotkeyScheme, KeyBinding, keyEventToString, ManagedSource, matchesKeyBinding, parseKeyCombo } from '../domain/models';
 import { DistroAvatar } from './DistroAvatar';
 import SelectHostPanel from './SelectHostPanel';
-import { AsidePanel, AsidePanelContent } from './ui/aside-panel';
+import { AsidePanel, AsidePanelContent, AsidePanelFooter } from './ui/aside-panel';
 import { Button } from './ui/button';
 import { Card } from './ui/card';
 import { Combobox, ComboboxOption } from './ui/combobox';
@@ -18,6 +18,7 @@ import { Input } from './ui/input';
 import { Label } from './ui/label';
 import { SortDropdown, SortMode } from './ui/sort-dropdown';
 import { Textarea } from './ui/textarea';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './ui/tooltip';
 
 interface SnippetsManagerProps {
   snippets: Snippet[];
@@ -720,6 +721,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           onSaveHost={onSaveHost}
           onCreateGroup={onCreateGroup}
           title={t('snippets.targets.add')}
+          layout="inline"
         />
       );
     }
@@ -730,6 +732,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           open={true}
           onClose={handleClosePanel}
           title={editingSnippet.id ? t('snippets.panel.editTitle') : t('snippets.panel.newTitle')}
+          layout="inline"
           actions={
             <Button
               variant="ghost"
@@ -883,7 +886,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           </AsidePanelContent>
 
           {/* Footer */}
-          <div className="px-4 py-3 border-t border-border/60 shrink-0">
+          <AsidePanelFooter>
             <Button
               className="w-full"
               onClick={handleSubmit}
@@ -891,7 +894,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
             >
               {editingSnippet.targets?.length ? t('action.run') : t('common.save')}
             </Button>
-          </div>
+          </AsidePanelFooter>
         </AsidePanel>
       );
     }
@@ -905,6 +908,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
           subtitle={t('snippets.history.subtitle', { count: shellHistory.length })}
           showBackButton={true}
           onBack={handleClosePanel}
+          layout="inline"
         >
           {/* History List */}
           <div
@@ -951,8 +955,9 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
   };
 
   return (
-    <div className="h-full flex gap-3 relative">
-      <div className="flex-1 flex flex-col min-h-0">
+    <TooltipProvider delayDuration={300}>
+    <div className="h-full min-h-0 flex relative">
+      <div className="flex-1 flex flex-col min-h-0 min-w-0 overflow-hidden">
         <header className="border-b border-border/50 bg-secondary/80 backdrop-blur">
           <div className="h-14 px-4 py-2 flex items-center gap-2">
             {/* Search box */}
@@ -1059,7 +1064,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
                     <ContextMenuTrigger>
                       <div
                         className={cn(
-                          "group cursor-pointer",
+                          "group cursor-pointer overflow-hidden",
                           viewMode === 'grid'
                             ? "soft-card elevate rounded-xl h-[68px] px-3 py-2"
                             : "h-14 px-3 py-2 hover:bg-secondary/60 rounded-lg transition-colors"
@@ -1079,11 +1084,11 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
                         }}
                         onClick={() => setSelectedPackage(pkg.path)}
                       >
-                        <div className="flex items-center gap-3 h-full">
+                        <div className="flex items-center gap-3 h-full min-w-0">
                           <div className="h-11 w-11 rounded-xl bg-primary/15 text-primary flex items-center justify-center flex-shrink-0">
                             <Package size={18} />
                           </div>
-                          <div className="min-w-0 flex-1">
+                          <div className="w-0 flex-1">
                             <div className="text-sm font-semibold truncate">{pkg.name}</div>
                             <div className="text-[11px] text-muted-foreground">{t('snippets.package.count', { count: pkg.count })}</div>
                           </div>
@@ -1114,7 +1119,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
                     <ContextMenuTrigger>
                       <div
                         className={cn(
-                          "group cursor-pointer",
+                          "group cursor-pointer overflow-hidden",
                           viewMode === 'grid'
                             ? "soft-card elevate rounded-xl h-[68px] px-3 py-2"
                             : "h-14 px-3 py-2 hover:bg-secondary/60 rounded-lg transition-colors"
@@ -1126,15 +1131,22 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
                         }}
                         onClick={() => handleEdit(snippet)}
                       >
-                        <div className="flex items-center gap-3 h-full">
+                        <div className="flex items-center gap-3 h-full min-w-0">
                           <div className="h-11 w-11 rounded-xl bg-primary/15 text-primary flex items-center justify-center flex-shrink-0">
                             <FileCode size={18} />
                           </div>
-                          <div className="min-w-0 flex-1">
+                          <div className="w-0 flex-1">
                             <div className="text-sm font-semibold truncate">{snippet.label}</div>
-                            <div className="text-[11px] text-muted-foreground font-mono leading-4 truncate">
-                              {snippet.command.replace(/\s+/g, ' ') || t('snippets.commandFallback')}
-                            </div>
+                            <Tooltip>
+                              <TooltipTrigger asChild>
+                                <div className="text-[11px] text-muted-foreground font-mono leading-4 truncate">
+                                  {snippet.command.replace(/\s+/g, ' ') || t('snippets.commandFallback')}
+                                </div>
+                              </TooltipTrigger>
+                              <TooltipContent side="bottom" className="max-w-sm break-all font-mono text-xs">
+                                {snippet.command}
+                              </TooltipContent>
+                            </Tooltip>
                           </div>
                           {snippet.shortkey && (
                             <div className="shrink-0 px-2 py-1 text-[10px] font-mono rounded border border-border bg-muted/50 text-muted-foreground">
@@ -1254,6 +1266,7 @@ const SnippetsManager: React.FC<SnippetsManagerProps> = ({
       {/* Right Panel */}
       {renderRightPanel()}
     </div>
+    </TooltipProvider>
   );
 };
 

components/Terminal.tsx

@@ -28,6 +28,7 @@ import {
 import {
   resolveHostTerminalThemeId,
 } from "../domain/terminalAppearance";
+import { classifyDistroId } from "../domain/host";
 import { resolveHostAuth } from "../domain/sshAuth";
 import { useTerminalBackend } from "../application/state/useTerminalBackend";
 import KnownHostConfirmDialog, { HostKeyInfo } from "./KnownHostConfirmDialog";
@@ -47,7 +48,8 @@ import { TerminalSearchBar } from "./terminal/TerminalSearchBar";
 import { ZmodemProgressIndicator } from "./terminal/ZmodemProgressIndicator";
 import { useZmodemTransfer } from "./terminal/hooks/useZmodemTransfer";
 import { createTerminalSessionStarters, type PendingAuth } from "./terminal/runtime/createTerminalSessionStarters";
-import { createXTermRuntime, type XTermRuntime } from "./terminal/runtime/createXTermRuntime";
+import { createXTermRuntime, primaryFontFamily, type XTermRuntime } from "./terminal/runtime/createXTermRuntime";
+import { preserveTerminalViewportInScrollback } from "./terminal/clearTerminalViewport";
 import { XTERM_PERFORMANCE_CONFIG } from "../infrastructure/config/xtermPerformance";
 import { useTerminalSearch } from "./terminal/hooks/useTerminalSearch";
 import { useTerminalContextActions } from "./terminal/hooks/useTerminalContextActions";
@@ -122,6 +124,7 @@ interface TerminalProps {
   fontFamilyId: string;
   fontSize: number;
   terminalTheme: TerminalTheme;
+  followAppTerminalTheme?: boolean;
   terminalSettings?: TerminalSettings;
   sessionId: string;
   startupCommand?: string;
@@ -196,6 +199,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   fontFamilyId,
   fontSize,
   terminalTheme,
+  followAppTerminalTheme = false,
   terminalSettings,
   sessionId,
   startupCommand,
@@ -242,6 +246,11 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   const sessionRef = useRef<string | null>(null);
   const hasConnectedRef = useRef(false);
   const hasRunStartupCommandRef = useRef(false);
+  // Token for an in-flight retry chain. handleRetry sets this to a fresh
+  // symbol; any cancel/close/teardown/subsequent-retry invalidates it. The
+  // chained xterm.write callbacks verify the token before proceeding so a
+  // cancelled retry can't fire a startNewSession after the fact.
+  const retryTokenRef = useRef<symbol | null>(null);
   const terminalDataCapturedRef = useRef(false);
   const onTerminalDataCaptureRef = useRef(onTerminalDataCapture);
   const commandBufferRef = useRef<string>("");
@@ -256,6 +265,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   isVisibleRef.current = isVisible;
   const pendingOutputScrollRef = useRef(false);
   const lastFittedSizeRef = useRef<{ width: number; height: number } | null>(null);
+  const fontWeightFixupDoneRef = useRef(false);
 
   useEffect(() => {
     if (xtermRuntimeRef.current) {
@@ -329,6 +339,23 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   const statusRef = useRef<TerminalSession["status"]>(status);
   statusRef.current = status;
 
+  // Work around xterm.js WebGL renderer bug: glyphs rendered via the constructor
+  // look different from dynamically-set ones. After text appears on screen (status
+  // becomes "connected"), do a fontWeight round-trip to normalize the rendering.
+  useEffect(() => {
+    if (status !== 'connected' || fontWeightFixupDoneRef.current || !termRef.current) return;
+    fontWeightFixupDoneRef.current = true;
+    const timer = setTimeout(() => {
+      if (!termRef.current) return;
+      // Re-read the current weight at fire time to avoid stale closures
+      const w = termRef.current.options.fontWeight;
+      if (w === 'normal' || w === 400) return;
+      termRef.current.options.fontWeight = 'normal';
+      termRef.current.options.fontWeight = w;
+    }, 200);
+    return () => clearTimeout(timer);
+  }, [status]);
+
   const [chainProgress, setChainProgress] = useState<{
     currentHop: number;
     totalHops: number;
@@ -492,12 +519,33 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   const isLocalConnection = host.protocol === "local";
   const isSerialConnection = host.protocol === "serial";
 
-  // Server stats (CPU, Memory, Disk) — only for Linux/macOS
+  // Server stats (CPU, Memory, Disk) — only for Linux/macOS, and never
+  // for hosts classified as network devices (either via explicit
+  // deviceType='network' or via SSH banner detection that populated
+  // host.distro with a network-vendor ID). See #674: polling the stats
+  // command on Cisco / Huawei / Juniper etc. generates one AAA session
+  // log entry per poll because each exec channel is counted as a new
+  // session on those devices.
+  //
+  // IMPORTANT: this gating must NOT go through getEffectiveHostDistro()
+  // because that honors the manual distro override (`distroMode: 'manual'`
+  // + `manualDistro`) which is purely a cosmetic icon choice. A user who
+  // pinned an "ubuntu" icon on what is actually a Cisco host would
+  // otherwise silently re-enable the polling loop and re-introduce the
+  // AAA log flood this patch is meant to eliminate. The display icon can
+  // still be overridden (see DistroAvatar) — gating uses the raw detected
+  // `host.distro` and the explicit `host.deviceType` only.
+  const detectedDeviceClass = classifyDistroId(host.distro);
+  const isNetworkDevice =
+    host.deviceType === 'network' || detectedDeviceClass === 'network-device';
+  const isSupportedOs =
+    !isNetworkDevice &&
+    (host.os === 'linux' || host.os === 'macos' || detectedDeviceClass === 'linux-like');
   const { stats: serverStats } = useServerStats({
     sessionId,
     enabled: terminalSettings?.showServerStats ?? true,
     refreshInterval: terminalSettings?.serverStatsRefreshInterval ?? 5,
-    isSupportedOs: host.os === 'linux' || host.os === 'macos',
+    isSupportedOs,
     isConnected: status === 'connected',
     isVisible,
   });
@@ -594,6 +642,10 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   }, [availableFonts, fontFamilyId, hasFontFamilyOverride, host.fontFamily]);
 
   const effectiveTheme = useMemo(() => {
+    // When "Follow Application Theme" is on and there's no active
+    // preview, skip per-host overrides — all terminals should use the
+    // UI-matched theme passed via terminalTheme prop.
+    if (followAppTerminalTheme && !themePreviewId) return terminalTheme;
     const themeId = themePreviewId ?? resolveHostTerminalThemeId(
       { theme: host.theme, themeOverride: host.themeOverride } as Pick<Host, 'theme' | 'themeOverride'>,
       terminalTheme.id,
@@ -604,7 +656,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
       if (hostTheme) return hostTheme;
     }
     return terminalTheme;
-  }, [customThemes, host.theme, host.themeOverride, terminalTheme, themePreviewId]);
+  }, [customThemes, followAppTerminalTheme, host.theme, host.themeOverride, terminalTheme, themePreviewId]);
 
   const resolvedChainHosts =
     chainHosts;
@@ -638,6 +690,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   };
 
   const teardown = () => {
+    retryTokenRef.current = null;
     cleanupSession();
     xtermRuntimeRef.current?.dispose();
     xtermRuntimeRef.current = null;
@@ -943,7 +996,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
       if (terminalSettings) {
         termRef.current.options.cursorStyle = terminalSettings.cursorShape;
         termRef.current.options.cursorBlink = terminalSettings.cursorBlink;
-        termRef.current.options.scrollback = terminalSettings.scrollback;
+        termRef.current.options.scrollback = terminalSettings.scrollback === 0 ? 999999 : terminalSettings.scrollback;
         termRef.current.options.fontWeight = effectiveFontWeight as
           | 100
           | 200
@@ -959,7 +1012,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
           if (typeof document === "undefined" || !document.fonts?.check) {
             return terminalSettings.fontWeightBold;
           }
-          const weightSpec = `${terminalSettings.fontWeightBold} ${effectiveFontSize}px ${fontFamily}`;
+          const weightSpec = `${terminalSettings.fontWeightBold} ${effectiveFontSize}px ${primaryFontFamily(fontFamily)}`;
           return document.fonts.check(weightSpec)
             ? terminalSettings.fontWeightBold
             : effectiveFontWeight;
@@ -1046,7 +1099,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
         if (terminalSettings && termRef.current) {
           const fontFamily = termRef.current.options?.fontFamily || "";
           if (typeof document !== "undefined" && document.fonts?.check) {
-            const weightSpec = `${terminalSettings.fontWeightBold} ${effectiveFontSize}px ${fontFamily}`;
+            const weightSpec = `${terminalSettings.fontWeightBold} ${effectiveFontSize}px ${primaryFontFamily(fontFamily)}`;
             const resolvedBold = document.fonts.check(weightSpec)
               ? terminalSettings.fontWeightBold
               : effectiveFontWeight;
@@ -1117,10 +1170,16 @@ const TerminalComponent: React.FC<TerminalProps> = ({
 
   useEffect(() => {
     if (!isVisible || !fitAddonRef.current) return;
-    const timer = setTimeout(() => {
+    // Fit twice: once after initial layout (100ms) and again after layout settles
+    // (350ms) to handle race conditions during split operations where the container
+    // dimensions may not be final on the first pass.
+    const timer1 = setTimeout(() => {
       safeFit({ requireVisible: true });
     }, 100);
-    return () => clearTimeout(timer);
+    const timer2 = setTimeout(() => {
+      safeFit({ force: true, requireVisible: true });
+    }, 350);
+    return () => { clearTimeout(timer1); clearTimeout(timer2); };
   }, [inWorkspace, isVisible]);
 
   // When search bar opens/closes, re-fit terminal and maintain scroll position
@@ -1346,6 +1405,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   };
 
   const handleCancelConnect = () => {
+    retryTokenRef.current = null;
     setIsCancelling(true);
     auth.setNeedsAuth(false);
     auth.setAuthRetryMessage(null);
@@ -1365,6 +1425,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   };
 
   const handleCloseDisconnectedSession = () => {
+    retryTokenRef.current = null;
     onCloseSession?.(sessionId);
   };
 
@@ -1406,6 +1467,15 @@ const TerminalComponent: React.FC<TerminalProps> = ({
   const handleRetry = () => {
     if (!termRef.current) return;
     cleanupSession();
+    const term = termRef.current;
+    // Claim a fresh retry token. If the user cancels / closes / unmounts /
+    // kicks off another retry while the chained writes below are still
+    // queued, the token will be invalidated and our callbacks will abort
+    // before opening a ghost backend session with no owning UI.
+    const retryToken = Symbol("retry");
+    retryTokenRef.current = retryToken;
+    const retryStillActive = () => retryTokenRef.current === retryToken && termRef.current === term;
+
     auth.resetForRetry();
     terminalDataCapturedRef.current = false;
     hasRunStartupCommandRef.current = false;
@@ -1414,17 +1484,51 @@ const TerminalComponent: React.FC<TerminalProps> = ({
     setError(null);
     setProgressLogs(["Retrying secure channel..."]);
     setShowLogs(true);
-    if (host.protocol === "serial") {
-      sessionStarters.startSerial(termRef.current);
-    } else if (host.protocol === "local" || host.hostname === "localhost") {
-      sessionStarters.startLocal(termRef.current);
-    } else if (host.protocol === "telnet") {
-      sessionStarters.startTelnet(termRef.current);
-    } else if (host.moshEnabled) {
-      sessionStarters.startMosh(termRef.current);
-    } else {
-      sessionStarters.startSSH(termRef.current);
-    }
+
+    const startNewSession = () => {
+      if (!retryStillActive()) return;
+      if (host.protocol === "serial") {
+        sessionStarters.startSerial(term);
+      } else if (host.protocol === "local" || host.hostname === "localhost") {
+        sessionStarters.startLocal(term);
+      } else if (host.protocol === "telnet") {
+        sessionStarters.startTelnet(term);
+      } else if (host.moshEnabled) {
+        sessionStarters.startMosh(term);
+      } else {
+        sessionStarters.startSSH(term);
+      }
+    };
+
+    // Chain the whole preparation through xterm.write callbacks so everything
+    // lands in strict order — see #695. xterm.write is async, so without
+    // chaining, a fast reconnect path (local/serial especially) can interleave
+    // the new session's first bytes with our reset sequence, corrupting the
+    // first screen.
+    //
+    // 1. Exit the alternate screen first. preserveTerminalViewportInScrollback
+    //    is a no-op on the alt buffer (disconnect while in vim/less/top), so
+    //    we must be on the normal buffer before preserving.
+    term.write('\x1b[?1049l', () => {
+      if (!retryStillActive()) return;
+      // 2. Push the previous session's viewport into scrollback so the user
+      //    can still read it after reconnect.
+      preserveTerminalViewportInScrollback(term);
+      // 3. Soft terminal reset (DECSTR, \x1b[!p) resets VT220-era modes that
+      //    full-screen apps may have left on — DECCKM (otherwise arrow keys
+      //    emit SS3 and break readline history), keypad mode, SGR,
+      //    insert/replace, origin, cursor visibility — without clearing the
+      //    buffer. DECSTR does not cover xterm-specific extensions, so also
+      //    explicitly disable mouse tracking (1000/1002/1003/1006) and
+      //    bracketed paste (2004). Finally home the cursor.
+      term.write(
+        '\x1b[!p\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?2004l\x1b[H',
+        // 4. Only now — after every prep byte has been applied to the
+        //    terminal — start the new session, so its first output can't
+        //    interleave with the reset sequence.
+        startNewSession,
+      );
+    });
   };
 
   const shouldShowConnectionDialog = status !== "connected"
@@ -1559,6 +1663,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
       isAlternateScreen={hasMouseTracking}
       onCopy={terminalContextActions.onCopy}
       onPaste={terminalContextActions.onPaste}
+      onPasteSelection={terminalContextActions.onPasteSelection}
       onSelectAll={terminalContextActions.onSelectAll}
       onClear={terminalContextActions.onClear}
       onSelectWord={terminalContextActions.onSelectWord}
@@ -1988,7 +2093,7 @@ const TerminalComponent: React.FC<TerminalProps> = ({
         >
           <div
             ref={containerRef}
-            className="absolute inset-x-0 bottom-0"
+            className="xterm-container absolute inset-x-0 bottom-0"
             style={{
               top: isSearchOpen ? "64px" : "30px",
               paddingLeft: 6,

components/TerminalLayer.tsx

@@ -33,6 +33,7 @@ import { STORAGE_KEY_SIDE_PANEL_WIDTH } from '../infrastructure/config/storageKe
 import { buildCacheKey } from '../application/state/sftp/sharedRemoteHostCache';
 import type { DropEntry } from '../lib/sftpFileUtils';
 import { GroupConfig, Host, Identity, KnownHost, SSHKey, Snippet, TerminalSession, TerminalTheme, Workspace, WorkspaceNode } from '../types';
+import type { ExecutorContext } from '../infrastructure/ai/cattyAgent/executor';
 import { resolveGroupDefaults, applyGroupDefaults } from '../domain/groupConfig';
 import { DistroAvatar } from './DistroAvatar';
 import Terminal from './Terminal';
@@ -40,7 +41,7 @@ import { SftpSidePanel } from './SftpSidePanel';
 import { ScriptsSidePanel } from './ScriptsSidePanel';
 import { ThemeSidePanel } from './terminal/ThemeSidePanel';
 import { AIChatSidePanel } from './AIChatSidePanel';
-import { cleanupOrphanedAISessions, useAIState } from '../application/state/useAIState';
+import { useAIState } from '../application/state/useAIState';
 import { TerminalComposeBar } from './terminal/TerminalComposeBar';
 import { TERMINAL_THEMES } from '../infrastructure/config/terminalThemes';
 import { useCustomThemes } from '../application/state/customThemeStore';
@@ -259,6 +260,10 @@ interface AIChatPanelsHostProps {
   }) => ExecutorContext;
 }
 
+interface AIStateMaintenanceHostProps {
+  validAIScopeTargetIds: Set<string>;
+}
+
 const AIStateProviderInner: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const aiState = useAIState();
   return (
@@ -271,6 +276,27 @@ const AIStateProviderInner: React.FC<{ children: React.ReactNode }> = ({ childre
 const AIStateProvider = memo(AIStateProviderInner);
 AIStateProvider.displayName = 'AIStateProvider';
 
+const AIStateMaintenanceHostInner: React.FC<AIStateMaintenanceHostProps> = ({
+  validAIScopeTargetIds,
+}) => {
+  const aiState = useContext(AIStateContext);
+
+  if (!aiState) {
+    throw new Error('AIStateMaintenanceHost must be rendered inside AIStateProvider');
+  }
+
+  const { cleanupOrphanedSessions } = aiState;
+
+  useEffect(() => {
+    cleanupOrphanedSessions(validAIScopeTargetIds);
+  }, [cleanupOrphanedSessions, validAIScopeTargetIds]);
+
+  return null;
+};
+
+const AIStateMaintenanceHost = memo(AIStateMaintenanceHostInner);
+AIStateMaintenanceHost.displayName = 'AIStateMaintenanceHost';
+
 const AIChatPanelsHostInner: React.FC<AIChatPanelsHostProps> = ({
   mountedTabIds,
   activeTabId,
@@ -300,12 +326,20 @@ const AIChatPanelsHostInner: React.FC<AIChatPanelsHostProps> = ({
             <AIChatSidePanel
               sessions={aiState.sessions}
               activeSessionIdMap={aiState.activeSessionIdMap}
+              draftsByScope={aiState.draftsByScope}
+              panelViewByScope={aiState.panelViewByScope}
               setActiveSessionId={aiState.setActiveSessionId}
+              ensureDraftForScope={aiState.ensureDraftForScope}
+              updateDraft={aiState.updateDraft}
+              showDraftView={aiState.showDraftView}
+              showSessionView={aiState.showSessionView}
+              clearDraftForScope={aiState.clearDraftForScope}
+              addDraftFiles={aiState.addDraftFiles}
+              removeDraftFile={aiState.removeDraftFile}
               createSession={aiState.createSession}
               deleteSession={aiState.deleteSession}
               updateSessionTitle={aiState.updateSessionTitle}
               updateSessionExternalSessionId={aiState.updateSessionExternalSessionId}
-              retargetSessionScope={aiState.retargetSessionScope}
               addMessageToSession={aiState.addMessageToSession}
               updateLastMessage={aiState.updateLastMessage}
               updateMessageById={aiState.updateMessageById}
@@ -313,6 +347,7 @@ const AIChatPanelsHostInner: React.FC<AIChatPanelsHostProps> = ({
               activeProviderId={aiState.activeProviderId}
               activeModelId={aiState.activeModelId}
               defaultAgentId={aiState.defaultAgentId}
+              toolIntegrationMode={aiState.toolIntegrationMode}
               externalAgents={aiState.externalAgents}
               setExternalAgents={aiState.setExternalAgents}
               agentModelMap={aiState.agentModelMap}
@@ -352,6 +387,7 @@ interface TerminalLayerProps {
   knownHosts?: KnownHost[];
   draggingSessionId: string | null;
   terminalTheme: TerminalTheme;
+  followAppTerminalTheme?: boolean;
   terminalSettings?: TerminalSettings;
   terminalFontFamilyId: string;
   fontSize?: number;
@@ -407,6 +443,7 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
   knownHosts = [],
   draggingSessionId,
   terminalTheme,
+  followAppTerminalTheme = false,
   terminalSettings,
   terminalFontFamilyId,
   fontSize = 14,
@@ -849,7 +886,7 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     return map;
   }, [sessions, sessionHostsMap, hostMap, groupConfigs]);
 
-  const validTerminalTabIds = useMemo(() => {
+  const validAIScopeTargetIds = useMemo(() => {
     const ids = new Set<string>();
     for (const session of sessions) ids.add(session.id);
     for (const workspace of workspaces) ids.add(workspace.id);
@@ -937,16 +974,12 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
   }, [workspaces]);
 
   useEffect(() => {
-    setSidePanelOpenTabs(prev => filterTabsMap(prev, validTerminalTabIds));
-    setSftpHostForTab(prev => filterTabsMap(prev, validTerminalTabIds));
-    setSftpInitialLocationForTab(prev => filterTabsMap(prev, validTerminalTabIds));
-    setSftpPendingUploadsForTab(prev => filterTabsMap(prev, validTerminalTabIds));
+    setSidePanelOpenTabs(prev => filterTabsMap(prev, validAIScopeTargetIds));
+    setSftpHostForTab(prev => filterTabsMap(prev, validAIScopeTargetIds));
+    setSftpInitialLocationForTab(prev => filterTabsMap(prev, validAIScopeTargetIds));
+    setSftpPendingUploadsForTab(prev => filterTabsMap(prev, validAIScopeTargetIds));
     sessionActivityStore.prune(validSessionActivityIds);
-  }, [validSessionActivityIds, validTerminalTabIds]);
-
-  useEffect(() => {
-    cleanupOrphanedAISessions(validTerminalTabIds);
-  }, [validTerminalTabIds]);
+  }, [validSessionActivityIds, validAIScopeTargetIds]);
 
   const computeWorkspaceRects = useCallback((workspace?: Workspace, size?: { width: number; height: number }): Record<string, WorkspaceRect> => {
     if (!workspace) return {} as Record<string, WorkspaceRect>;
@@ -1379,6 +1412,17 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
   const isFocusedHostLocal = useMemo(() => {
     return focusedHost?.protocol === 'local' || !!focusedHost?.id?.startsWith('local-');
   }, [focusedHost]);
+  // Hosts not in the persisted hostMap (e.g. quick-connect) are ephemeral —
+  // sidebar appearance changes should update global settings, not per-host overrides.
+  const isFocusedHostEphemeral = useMemo(() => {
+    if (isFocusedHostLocal) return true;
+    if (!focusedHost) return true;
+    return !hostMap.has(focusedHost.id);
+  }, [focusedHost, isFocusedHostLocal, hostMap]);
+  const rawFocusedHost = useMemo(() => {
+    if (!focusedHost) return null;
+    return hostMap.get(focusedHost.id) ?? null;
+  }, [focusedHost, hostMap]);
   const previewTargetSessionId = activeWorkspace?.focusedSessionId ?? activeSession?.id ?? null;
   const activeThemePreviewId = themePreview.targetSessionId === previewTargetSessionId
     ? themePreview.themeId
@@ -1393,9 +1437,11 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
   const focusedFontSizeOverridden = hasHostFontSizeOverride(focusedHost);
   const focusedFontWeight = resolveHostTerminalFontWeight(focusedHost, terminalSettings?.fontWeight ?? 400);
   const focusedFontWeightOverridden = hasHostFontWeightOverride(focusedHost);
+  const visibleFocusedThemeId = followAppTerminalTheme ? terminalTheme.id : focusedThemeId;
+  const previewedOrVisibleThemeId = activeThemePreviewId ?? visibleFocusedThemeId;
   const activeTopTabsThemeId = activeSidePanelTab === 'theme' && previewTargetSessionId
-    ? (activeThemePreviewId ?? focusedThemeId)
-    : (isVisible ? focusedThemeId : null);
+    ? previewedOrVisibleThemeId
+    : (isVisible ? visibleFocusedThemeId : null);
   const appliedPreviewSessionRef = useRef<string | null>(null);
   const customThemes = useCustomThemes();
   const applyTerminalPreviewVars = useCallback((sessionId: string | null, themeId: string | null) => {
@@ -1486,10 +1532,28 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     clearTopTabsPreviewVars();
   }, [activeTopTabsThemeId, applyTopTabsPreviewVars]);
 
+  useEffect(() => {
+    if (!followAppTerminalTheme) return;
+    if (themeCommitTimerRef.current) {
+      clearTimeout(themeCommitTimerRef.current);
+      themeCommitTimerRef.current = null;
+    }
+    const appliedSessionId = appliedPreviewSessionRef.current;
+    if (appliedSessionId) {
+      clearTerminalPreviewVars(appliedSessionId);
+      appliedPreviewSessionRef.current = null;
+    }
+    clearTopTabsPreviewVars();
+    if (themePreview.targetSessionId || themePreview.themeId) {
+      setThemePreview({ targetSessionId: null, themeId: null });
+    }
+  }, [followAppTerminalTheme, themePreview.targetSessionId, themePreview.themeId]);
+
   useEffect(() => {
     const panelOpen = activeSidePanelTab === 'theme' && !!previewTargetSessionId;
     const shouldKeepPreview =
       panelOpen &&
+      themePreview.targetSessionId === previewTargetSessionId &&
       !!themePreview.targetSessionId &&
       !!themePreview.themeId;
 
@@ -1509,14 +1573,14 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     if (
       themePreview.targetSessionId === previewTargetSessionId &&
       themePreview.themeId &&
-      themePreview.themeId === focusedThemeId
+      themePreview.themeId === visibleFocusedThemeId
     ) {
       setThemePreview({ targetSessionId: null, themeId: null });
     }
-  }, [focusedThemeId, previewTargetSessionId, themePreview]);
+  }, [previewTargetSessionId, themePreview, visibleFocusedThemeId]);
 
   const handleThemeChangeForFocusedSession = useCallback((themeId: string) => {
-    if (!focusedHost || themeId === focusedThemeId) return;
+    if (!focusedHost || themeId === previewedOrVisibleThemeId) return;
     applyTerminalPreviewVars(previewTargetSessionId, themeId);
     applyTopTabsPreviewVars(themeId);
     setThemePreview({ targetSessionId: previewTargetSessionId, themeId });
@@ -1525,14 +1589,16 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     }
     themeCommitTimerRef.current = setTimeout(() => {
       startTransition(() => {
-        if (isFocusedHostLocal) {
+        if (isFocusedHostEphemeral) {
           onUpdateTerminalThemeId?.(themeId);
           return;
         }
-        onUpdateHost({ ...focusedHost, theme: themeId, themeOverride: true });
+        if (rawFocusedHost) {
+          onUpdateHost({ ...rawFocusedHost, theme: themeId, themeOverride: true });
+        }
       });
     }, 160);
-  }, [applyTerminalPreviewVars, applyTopTabsPreviewVars, focusedHost, focusedThemeId, isFocusedHostLocal, onUpdateTerminalThemeId, onUpdateHost, previewTargetSessionId]);
+  }, [applyTerminalPreviewVars, applyTopTabsPreviewVars, focusedHost, isFocusedHostEphemeral, onUpdateTerminalThemeId, onUpdateHost, previewTargetSessionId, previewedOrVisibleThemeId, rawFocusedHost]);
 
   const handleThemeResetForFocusedSession = useCallback(() => {
     if (themeCommitTimerRef.current) {
@@ -1540,64 +1606,64 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     }
     clearTerminalPreviewVars(previewTargetSessionId);
     setThemePreview({ targetSessionId: null, themeId: null });
-    if (!focusedHost || isFocusedHostLocal) return;
-    onUpdateHost(clearHostThemeOverride(focusedHost));
-  }, [focusedHost, isFocusedHostLocal, onUpdateHost, previewTargetSessionId]);
+    if (!focusedHost || isFocusedHostEphemeral || !rawFocusedHost) return;
+    onUpdateHost(clearHostThemeOverride(rawFocusedHost));
+  }, [focusedHost, isFocusedHostEphemeral, onUpdateHost, previewTargetSessionId, rawFocusedHost]);
 
   const handleFontFamilyChangeForFocusedSession = useCallback((fontFamilyId: string) => {
     if (!focusedHost || fontFamilyId === focusedFontFamilyId) return;
     startTransition(() => {
-      if (isFocusedHostLocal) {
+      if (isFocusedHostEphemeral) {
         onUpdateTerminalFontFamilyId?.(fontFamilyId);
         return;
       }
       onUpdateHost({ ...focusedHost, fontFamily: fontFamilyId, fontFamilyOverride: true });
     });
-  }, [focusedHost, focusedFontFamilyId, isFocusedHostLocal, onUpdateTerminalFontFamilyId, onUpdateHost]);
+  }, [focusedHost, focusedFontFamilyId, isFocusedHostEphemeral, onUpdateTerminalFontFamilyId, onUpdateHost]);
 
   const handleFontFamilyResetForFocusedSession = useCallback(() => {
-    if (!focusedHost || isFocusedHostLocal) return;
+    if (!focusedHost || isFocusedHostEphemeral) return;
     onUpdateHost(clearHostFontFamilyOverride(focusedHost));
-  }, [focusedHost, isFocusedHostLocal, onUpdateHost]);
+  }, [focusedHost, isFocusedHostEphemeral, onUpdateHost]);
 
   const handleFontSizeChangeForFocusedSession = useCallback((newFontSize: number) => {
     if (!focusedHost || newFontSize === focusedFontSize) return;
     startTransition(() => {
-      if (isFocusedHostLocal) {
+      if (isFocusedHostEphemeral) {
         onUpdateTerminalFontSize?.(newFontSize);
         return;
       }
       onUpdateHost({ ...focusedHost, fontSize: newFontSize, fontSizeOverride: true });
     });
-  }, [focusedHost, focusedFontSize, isFocusedHostLocal, onUpdateTerminalFontSize, onUpdateHost]);
+  }, [focusedHost, focusedFontSize, isFocusedHostEphemeral, onUpdateTerminalFontSize, onUpdateHost]);
 
   const handleFontSizeResetForFocusedSession = useCallback(() => {
-    if (!focusedHost || isFocusedHostLocal) return;
+    if (!focusedHost || isFocusedHostEphemeral) return;
     onUpdateHost(clearHostFontSizeOverride(focusedHost));
-  }, [focusedHost, isFocusedHostLocal, onUpdateHost]);
+  }, [focusedHost, isFocusedHostEphemeral, onUpdateHost]);
 
   const handleFontWeightChangeForFocusedSession = useCallback((newFontWeight: number) => {
     if (!focusedHost || newFontWeight === focusedFontWeight) return;
     startTransition(() => {
-      if (isFocusedHostLocal) {
+      if (isFocusedHostEphemeral) {
         onUpdateTerminalFontWeight?.(newFontWeight);
         return;
       }
-      // Patch only fontWeight fields on the raw (un-merged) host to avoid flattening group defaults
+      // Prefer raw (un-merged) host to avoid flattening group defaults
       const rawHost = hostMap.get(focusedHost.id);
       if (rawHost) {
         onUpdateHost({ ...rawHost, fontWeight: newFontWeight, fontWeightOverride: true });
       }
     });
-  }, [focusedHost, focusedFontWeight, isFocusedHostLocal, onUpdateTerminalFontWeight, onUpdateHost, hostMap]);
+  }, [focusedHost, focusedFontWeight, isFocusedHostEphemeral, onUpdateTerminalFontWeight, onUpdateHost, hostMap]);
 
   const handleFontWeightResetForFocusedSession = useCallback(() => {
-    if (!focusedHost || isFocusedHostLocal) return;
+    if (!focusedHost || isFocusedHostEphemeral) return;
     const rawHost = hostMap.get(focusedHost.id);
     if (rawHost) {
       onUpdateHost(clearHostFontWeightOverride(rawHost));
     }
-  }, [focusedHost, isFocusedHostLocal, onUpdateHost, hostMap]);
+  }, [focusedHost, isFocusedHostEphemeral, onUpdateHost, hostMap]);
 
   // Keep MCP/ACP approval IPC listener alive for the entire terminal lifecycle.
   // Must live here (TerminalLayer), not inside the AI panel subtree, so closing
@@ -1610,8 +1676,8 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
   // recomputing scope resolution from scratch on every tab switch.
   const aiContextsByTabId = useMemo(() => {
     const localOs = detectLocalOs(navigator.userAgent || navigator.platform);
-    const sessionById = new Map(sessions.map((session) => [session.id, session]));
-    const workspaceById = new Map(workspaces.map((workspace) => [workspace.id, workspace]));
+    const sessionById = new Map<string, TerminalSession>(sessions.map((session) => [session.id, session]));
+    const workspaceById = new Map<string, Workspace>(workspaces.map((workspace) => [workspace.id, workspace]));
     const tabIds = new Set<string>(mountedAiTabIds);
     if (activeTabId) tabIds.add(activeTabId);
 
@@ -1692,11 +1758,11 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
   }, []);
 
   const resolvedPreviewTheme = useMemo(() => {
-    const themeId = activeThemePreviewId ?? focusedThemeId;
+    const themeId = previewedOrVisibleThemeId;
     return TERMINAL_THEMES.find((theme) => theme.id === themeId)
       || customThemes.find((theme) => theme.id === themeId)
       || terminalTheme;
-  }, [activeThemePreviewId, customThemes, focusedThemeId, terminalTheme]);
+  }, [customThemes, previewedOrVisibleThemeId, terminalTheme]);
   const sessionLogConfig = useMemo(
     () =>
       sessionLogsEnabled && sessionLogsDir
@@ -1812,7 +1878,10 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
     if (!activeWorkspace || !isFocusMode) return null;
 
     return (
-      <div className="w-56 flex-shrink-0 bg-secondary/50 border-r border-border/50 flex flex-col">
+      <div
+        className="w-56 flex-shrink-0 bg-secondary/50 border-r border-border/50 flex flex-col"
+        data-section="terminal-workspace-sidebar"
+      >
         {/* Header with view toggle */}
         <div className="h-10 flex items-center justify-between px-3 border-b border-border/50">
           <span className="text-xs font-medium text-muted-foreground">
@@ -1880,9 +1949,11 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
 
   return (
     <AIStateProvider>
+      <AIStateMaintenanceHost validAIScopeTargetIds={validAIScopeTargetIds} />
       <div
         ref={workspaceOuterRef}
         className="absolute inset-0 bg-background flex flex-col"
+        data-section="terminal-workspace"
         style={{
           visibility: isTerminalLayerVisible ? 'visible' : 'hidden',
           pointerEvents: isTerminalLayerVisible ? 'auto' : 'none',
@@ -1933,7 +2004,10 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="h-7 w-7 rounded-md p-0 hover:bg-transparent"
+                      data-tab-id="sftp"
+                      data-tab-type="sidepanel"
+                      data-state={activeSidePanelTab === 'sftp' ? 'active' : 'inactive'}
+                      className="netcatty-tab h-7 w-7 rounded-md p-0 hover:bg-transparent"
                       style={{
                         color: activeSidePanelTab === 'sftp'
                           ? 'var(--terminal-sidepanel-fg)'
@@ -1947,7 +2021,10 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="h-7 w-7 rounded-md p-0 hover:bg-transparent"
+                      data-tab-id="scripts"
+                      data-tab-type="sidepanel"
+                      data-state={activeSidePanelTab === 'scripts' ? 'active' : 'inactive'}
+                      className="netcatty-tab h-7 w-7 rounded-md p-0 hover:bg-transparent"
                       style={{
                         color: activeSidePanelTab === 'scripts'
                           ? 'var(--terminal-sidepanel-fg)'
@@ -1961,7 +2038,10 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="h-7 w-7 rounded-md p-0 hover:bg-transparent"
+                      data-tab-id="theme"
+                      data-tab-type="sidepanel"
+                      data-state={activeSidePanelTab === 'theme' ? 'active' : 'inactive'}
+                      className="netcatty-tab h-7 w-7 rounded-md p-0 hover:bg-transparent"
                       style={{
                         color: activeSidePanelTab === 'theme'
                           ? 'var(--terminal-sidepanel-fg)'
@@ -1975,7 +2055,10 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="h-7 w-7 rounded-md p-0 hover:bg-transparent"
+                      data-tab-id="ai"
+                      data-tab-type="sidepanel"
+                      data-state={activeSidePanelTab === 'ai' ? 'active' : 'inactive'}
+                      className="netcatty-tab h-7 w-7 rounded-md p-0 hover:bg-transparent"
                       style={{
                         color: activeSidePanelTab === 'ai'
                           ? 'var(--terminal-sidepanel-fg)'
@@ -2064,7 +2147,8 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
                   {activeSidePanelTab === 'theme' && (
                     <div className="absolute inset-0 z-10">
                       <ThemeSidePanel
-                        currentThemeId={activeThemePreviewId ?? focusedThemeId}
+                        followAppTerminalTheme={followAppTerminalTheme}
+                        currentThemeId={previewedOrVisibleThemeId}
                         globalThemeId={terminalTheme.id}
                         currentFontFamilyId={focusedFontFamilyId}
                         globalFontFamilyId={terminalFontFamilyId}
@@ -2223,6 +2307,7 @@ const TerminalLayerInner: React.FC<TerminalLayerProps> = ({
                   fontFamilyId={terminalFontFamilyId}
                   fontSize={fontSize}
                   terminalTheme={terminalTheme}
+                  followAppTerminalTheme={followAppTerminalTheme}
                   terminalSettings={terminalSettings}
                   sessionId={session.id}
                   startupCommand={session.startupCommand}

components/TextEditorModal.tsx

@@ -125,12 +125,38 @@ const hslToHex = (hslString: string): string => {
   return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
 };
 
-// Get background color from CSS variable
-const getBackgroundColor = (): string => {
-  const bgValue = getComputedStyle(document.documentElement)
-    .getPropertyValue('--background')
+// Read a CSS custom-property and convert from HSL to hex
+const getCssColor = (varName: string, fallback: string): string => {
+  const value = getComputedStyle(document.documentElement)
+    .getPropertyValue(varName)
     .trim();
-  return bgValue ? hslToHex(bgValue) : '#1e1e1e';
+  return value ? hslToHex(value) : fallback;
+};
+
+interface EditorColors {
+  bg: string;
+  fg: string;
+  primary: string;
+  card: string;
+  mutedFg: string;
+  border: string;
+}
+
+/** Read all UI CSS variables that matter for the Monaco theme. */
+const getEditorColors = (isDark: boolean): EditorColors => ({
+  bg: getCssColor('--background', isDark ? '#1e1e1e' : '#ffffff'),
+  fg: getCssColor('--foreground', isDark ? '#d4d4d4' : '#1e1e1e'),
+  primary: getCssColor('--primary', isDark ? '#569cd6' : '#0078d4'),
+  card: getCssColor('--card', isDark ? '#252526' : '#f3f3f3'),
+  mutedFg: getCssColor('--muted-foreground', isDark ? '#858585' : '#858585'),
+  border: getCssColor('--border', isDark ? '#3c3c3c' : '#d4d4d4'),
+});
+
+/** Build a fingerprint string so we can detect immersive-mode color changes cheaply. */
+const getThemeSignal = (): string => {
+  const root = document.documentElement;
+  return root.dataset.immersiveTheme
+    ?? getComputedStyle(root).getPropertyValue('--background').trim();
 };
 
 export const TextEditorModal: React.FC<TextEditorModalProps> = ({
@@ -163,49 +189,64 @@ export const TextEditorModal: React.FC<TextEditorModalProps> = ({
     document.documentElement.classList.contains('dark')
   );
 
-  // Track background color for custom theme
-  const [bgColor, setBgColor] = useState(() => getBackgroundColor());
+  // Track a signal that changes whenever immersive-mode or base theme colors change
+  const [themeSignal, setThemeSignal] = useState(() => getThemeSignal());
 
   // Custom theme name
   const customThemeName = isDarkTheme ? 'netcatty-dark' : 'netcatty-light';
 
-  // Define and update custom Monaco themes based on UI background color
+  // Define and update custom Monaco themes — syncs with immersive-mode / base UI colors
   useEffect(() => {
     if (!monaco) return;
 
-    // Define dark theme with custom background
+    const colors = getEditorColors(isDarkTheme);
+
+    const themeColors: Record<string, string> = {
+      'editor.background': colors.bg,
+      'editor.foreground': colors.fg,
+      'editorCursor.foreground': colors.primary,
+      'editor.selectionBackground': colors.primary + '40',
+      'editor.inactiveSelectionBackground': colors.primary + '25',
+      'editorLineNumber.foreground': colors.mutedFg,
+      'editorLineNumber.activeForeground': colors.fg,
+      'editor.lineHighlightBackground': colors.fg + '08',
+      'editorWidget.background': colors.card,
+      'editorWidget.foreground': colors.fg,
+      'editorWidget.border': colors.border,
+      'input.background': colors.card,
+      'input.foreground': colors.fg,
+      'input.border': colors.border,
+    };
+
     monaco.editor.defineTheme('netcatty-dark', {
       base: 'vs-dark',
       inherit: true,
       rules: [],
-      colors: {
-        'editor.background': bgColor,
-      },
+      colors: themeColors,
     });
 
-    // Define light theme with custom background
     monaco.editor.defineTheme('netcatty-light', {
       base: 'vs',
       inherit: true,
       rules: [],
-      colors: {
-        'editor.background': bgColor,
-      },
+      colors: themeColors,
     });
 
-    // Apply the current theme
     monaco.editor.setTheme(customThemeName);
-  }, [monaco, isDarkTheme, bgColor, customThemeName]);
+  }, [monaco, isDarkTheme, themeSignal, customThemeName]);
 
-  // Listen for theme changes via MutationObserver on <html> class and style
+  // Listen for theme changes via MutationObserver on <html> class, style, and immersive data attr
   useEffect(() => {
     const root = document.documentElement;
     const updateTheme = () => {
       setIsDarkTheme(root.classList.contains('dark'));
-      setBgColor(getBackgroundColor());
+      setThemeSignal(getThemeSignal());
     };
     const observer = new MutationObserver(updateTheme);
-    observer.observe(root, { attributes: true, attributeFilter: ['class', 'style'] });
+    observer.observe(root, {
+      attributes: true,
+      attributeFilter: ['class', 'style', 'data-immersive-theme'],
+    });
     return () => observer.disconnect();
   }, []);
 

components/ThemeList.tsx

@@ -4,7 +4,7 @@
 import React, { memo, useMemo } from 'react';
 import { Check } from 'lucide-react';
 import { useI18n } from '../application/i18n/I18nProvider';
-import { TERMINAL_THEMES } from '../infrastructure/config/terminalThemes';
+import { TERMINAL_THEMES, USER_VISIBLE_TERMINAL_THEMES, isUiMatchTerminalThemeId } from '../infrastructure/config/terminalThemes';
 import { useCustomThemes } from '../application/state/customThemeStore';
 import { cn } from '../lib/utils';
 import { TerminalTheme } from '../types';
@@ -58,15 +58,52 @@ interface ThemeListProps {
 export const ThemeList: React.FC<ThemeListProps> = ({ selectedThemeId, onSelect }) => {
     const { t } = useI18n();
     const customThemes = useCustomThemes();
+    const deletedSelectedTheme = useMemo(
+        () => (selectedThemeId
+            && !isUiMatchTerminalThemeId(selectedThemeId)
+            && !TERMINAL_THEMES.some((theme) => theme.id === selectedThemeId)
+            && !customThemes.some((theme) => theme.id === selectedThemeId)
+            ? selectedThemeId
+            : null),
+        [customThemes, selectedThemeId],
+    );
+    const hiddenSelectedTheme = useMemo(
+        () => (isUiMatchTerminalThemeId(selectedThemeId)
+            ? TERMINAL_THEMES.find(theme => theme.id === selectedThemeId) || null
+            : null),
+        [selectedThemeId],
+    );
 
     const { darkThemes, lightThemes } = useMemo(() => {
-        const dark = TERMINAL_THEMES.filter(t => t.type === 'dark');
-        const light = TERMINAL_THEMES.filter(t => t.type === 'light');
+        const dark = USER_VISIBLE_TERMINAL_THEMES.filter(t => t.type === 'dark');
+        const light = USER_VISIBLE_TERMINAL_THEMES.filter(t => t.type === 'light');
         return { darkThemes: dark, lightThemes: light };
     }, []);
 
     return (
         <>
+            {hiddenSelectedTheme && (
+                <div className="mb-4 rounded-lg border border-border/60 bg-muted/30 px-3 py-2.5">
+                    <div className="text-[10px] uppercase tracking-wider text-muted-foreground mb-1 font-semibold">
+                        {t('terminal.hiddenTheme.title')}
+                    </div>
+                    <div className="text-sm font-medium text-foreground">{hiddenSelectedTheme.name}</div>
+                    <div className="text-[11px] text-muted-foreground mt-1">
+                        {t('terminal.hiddenTheme.desc')}
+                    </div>
+                </div>
+            )}
+            {deletedSelectedTheme && (
+                <div className="mb-4 rounded-lg border border-border/60 bg-muted/30 px-3 py-2.5">
+                    <div className="text-[10px] uppercase tracking-wider text-muted-foreground mb-1 font-semibold">
+                        Missing Theme
+                    </div>
+                    <div className="text-sm font-medium text-foreground">{deletedSelectedTheme}</div>
+                    <div className="text-[11px] text-muted-foreground mt-1">
+                        This custom theme is no longer available. Pick another theme to replace it.
+                    </div>
+                </div>
+            )}
             {/* Dark Themes Section */}
             <div className="mb-4">
                 <div className="text-[10px] uppercase tracking-wider text-muted-foreground mb-2 font-semibold px-3">

components/ThemeSelectPanel.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import {
     AsidePanel,
     AsidePanelContent,
+    type AsidePanelLayout,
 } from './ui/aside-panel';
 import { ScrollArea } from './ui/scroll-area';
 import { ThemeList } from './ThemeList';
@@ -13,6 +14,7 @@ interface ThemeSelectPanelProps {
     onClose: () => void;
     onBack?: () => void;
     showBackButton?: boolean;
+    layout?: AsidePanelLayout;
 }
 
 const ThemeSelectPanel: React.FC<ThemeSelectPanelProps> = ({
@@ -22,6 +24,7 @@ const ThemeSelectPanel: React.FC<ThemeSelectPanelProps> = ({
     onClose,
     onBack,
     showBackButton = true,
+    layout = 'overlay',
 }) => {
     return (
         <AsidePanel
@@ -30,6 +33,7 @@ const ThemeSelectPanel: React.FC<ThemeSelectPanelProps> = ({
             title="Select Color Theme"
             showBackButton={showBackButton}
             onBack={onBack}
+            layout={layout}
         >
             <AsidePanelContent className="p-0">
                 <ScrollArea className="h-full">

components/TopTabs.tsx

@@ -21,6 +21,7 @@ const dragRegionNoSelect = { WebkitAppRegion: 'drag', userSelect: 'none' } as Re
 
 interface TopTabsProps {
   theme: 'dark' | 'light';
+  followAppTerminalTheme?: boolean;
   hosts: Host[];
   sessions: TerminalSession[];
   orphanSessions: TerminalSession[];
@@ -43,6 +44,7 @@ interface TopTabsProps {
   onStartSessionDrag: (sessionId: string) => void;
   onEndSessionDrag: () => void;
   onReorderTabs: (draggedId: string, targetId: string, position: 'before' | 'after') => void;
+  showSftpTab: boolean;
 }
 
 // Detect local OS for local terminal tab icons
@@ -227,6 +229,7 @@ WindowControls.displayName = 'WindowControls';
 
 const TopTabsInner: React.FC<TopTabsProps> = ({
   theme,
+  followAppTerminalTheme = false,
   hosts,
   sessions,
   orphanSessions,
@@ -249,6 +252,7 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
   onStartSessionDrag,
   onEndSessionDrag,
   onReorderTabs,
+  showSftpTab,
 }) => {
   const { t } = useI18n();
   // Subscribe to activeTabId from external store
@@ -496,6 +500,8 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
             <ContextMenuTrigger asChild>
               <div
                 data-tab-id={session.id}
+                data-tab-type="session"
+                data-state={activeTabId === session.id ? 'active' : 'inactive'}
                 onClick={() => onSelectTab(session.id)}
                 draggable
                 onDragStart={(e) => handleTabDragStart(e, session.id)}
@@ -504,7 +510,7 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
                 onDragLeave={handleTabDragLeave}
                 onDrop={(e) => handleTabDrop(e, session.id)}
                 className={cn(
-                  "relative h-7 pl-3 pr-2 min-w-[140px] max-w-[240px] rounded-none text-xs font-semibold cursor-pointer flex items-center justify-between gap-2 app-no-drag flex-shrink-0",
+                  "netcatty-tab relative h-7 pl-3 pr-2 min-w-[140px] max-w-[240px] rounded-none text-xs font-semibold cursor-pointer flex items-center justify-between gap-2 app-no-drag flex-shrink-0",
                   "transition-transform duration-150",
                   isBeingDragged && isDraggingForReorder ? "opacity-40 scale-95" : ""
                 )}
@@ -595,6 +601,8 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
             <ContextMenuTrigger asChild>
               <div
                 data-tab-id={workspace.id}
+                data-tab-type="workspace"
+                data-state={isActive ? 'active' : 'inactive'}
                 onClick={() => onSelectTab(workspace.id)}
                 draggable
                 onDragStart={(e) => handleTabDragStart(e, workspace.id)}
@@ -603,7 +611,7 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
                 onDragLeave={handleTabDragLeave}
                 onDrop={(e) => handleTabDrop(e, workspace.id)}
                 className={cn(
-                  "relative h-7 pl-3 pr-2 min-w-[150px] max-w-[260px] rounded-none text-xs font-semibold cursor-pointer flex items-center justify-between gap-2 app-no-drag flex-shrink-0",
+                  "netcatty-tab relative h-7 pl-3 pr-2 min-w-[150px] max-w-[260px] rounded-none text-xs font-semibold cursor-pointer flex items-center justify-between gap-2 app-no-drag flex-shrink-0",
                   "transition-transform duration-150",
                   isBeingDragged && isDraggingForReorder ? "opacity-40 scale-95" : ""
                 )}
@@ -693,9 +701,11 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
           <div
             key={logView.id}
             data-tab-id={logView.id}
+            data-tab-type="logView"
+            data-state={isActive ? 'active' : 'inactive'}
             onClick={() => onSelectTab(logView.id)}
             className={cn(
-              "relative h-7 pl-3 pr-2 min-w-[140px] max-w-[240px] rounded-none text-xs font-semibold cursor-pointer flex items-center justify-between gap-2 app-no-drag flex-shrink-0",
+              "netcatty-tab relative h-7 pl-3 pr-2 min-w-[140px] max-w-[240px] rounded-none text-xs font-semibold cursor-pointer flex items-center justify-between gap-2 app-no-drag flex-shrink-0",
             )}
             style={{
               backgroundColor: isActive
@@ -765,6 +775,7 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
   return (
     <div
       data-top-tabs-root
+      data-section="top-tabs"
       className="relative w-full bg-secondary app-drag"
       style={{
         ...dragRegionNoSelect,
@@ -782,9 +793,12 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
         {/* Fixed left tabs: Vaults and SFTP */}
         <div className="flex items-end gap-0 flex-shrink-0 app-drag">
           <div
+            data-tab-id="vault"
+            data-tab-type="root"
+            data-state={isVaultActive ? 'active' : 'inactive'}
             onClick={() => onSelectTab('vault')}
             className={cn(
-              "relative h-7 px-3 rounded text-xs font-semibold cursor-pointer flex items-center gap-2 app-no-drag",
+              "netcatty-tab relative h-7 px-3 rounded text-xs font-semibold cursor-pointer flex items-center gap-2 app-no-drag",
             )}
             style={{
               backgroundColor: isVaultActive
@@ -809,40 +823,45 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
           >
             <FolderLock size={14} /> Vaults
           </div>
-          <div
-            onClick={() => onSelectTab('sftp')}
-            className={cn(
-              "relative h-7 px-3 rounded-none text-xs font-semibold cursor-pointer flex items-center gap-2 app-no-drag",
-            )}
-            style={{
-              backgroundColor: isSftpActive
-                ? 'var(--top-tabs-active-bg, hsl(var(--background)))'
-                : 'transparent',
-              color: isSftpActive
-                ? 'var(--top-tabs-fg, hsl(var(--foreground)))'
-                : 'var(--top-tabs-muted, hsl(var(--muted-foreground)))',
-            }}
-            onMouseEnter={(e) => {
-              if (!isSftpActive) {
-                e.currentTarget.style.backgroundColor = 'color-mix(in srgb, var(--top-tabs-active-bg, hsl(var(--background))) 40%, transparent)';
-                e.currentTarget.style.color = 'var(--top-tabs-fg, hsl(var(--foreground)))';
-              }
-            }}
-            onMouseLeave={(e) => {
-              if (!isSftpActive) {
-                e.currentTarget.style.backgroundColor = 'transparent';
-                e.currentTarget.style.color = 'var(--top-tabs-muted, hsl(var(--muted-foreground)))';
-              }
-            }}
-          >
-            {isSftpActive && (
-              <div
-                className="absolute top-0 left-0 right-0 h-[2px]"
-                style={{ backgroundColor: 'var(--top-tabs-accent, hsl(var(--accent)))' }}
-              />
-            )}
-            <Folder size={14} /> SFTP
-          </div>
+          {showSftpTab && (
+            <div
+              data-tab-id="sftp"
+              data-tab-type="root"
+              data-state={isSftpActive ? 'active' : 'inactive'}
+              onClick={() => onSelectTab('sftp')}
+              className={cn(
+                "netcatty-tab relative h-7 px-3 rounded-none text-xs font-semibold cursor-pointer flex items-center gap-2 app-no-drag",
+              )}
+              style={{
+                backgroundColor: isSftpActive
+                  ? 'var(--top-tabs-active-bg, hsl(var(--background)))'
+                  : 'transparent',
+                color: isSftpActive
+                  ? 'var(--top-tabs-fg, hsl(var(--foreground)))'
+                  : 'var(--top-tabs-muted, hsl(var(--muted-foreground)))',
+              }}
+              onMouseEnter={(e) => {
+                if (!isSftpActive) {
+                  e.currentTarget.style.backgroundColor = 'color-mix(in srgb, var(--top-tabs-active-bg, hsl(var(--background))) 40%, transparent)';
+                  e.currentTarget.style.color = 'var(--top-tabs-fg, hsl(var(--foreground)))';
+                }
+              }}
+              onMouseLeave={(e) => {
+                if (!isSftpActive) {
+                  e.currentTarget.style.backgroundColor = 'transparent';
+                  e.currentTarget.style.color = 'var(--top-tabs-muted, hsl(var(--muted-foreground)))';
+                }
+              }}
+            >
+              {isSftpActive && (
+                <div
+                  className="absolute top-0 left-0 right-0 h-[2px]"
+                  style={{ backgroundColor: 'var(--top-tabs-accent, hsl(var(--accent)))' }}
+                />
+              )}
+              <Folder size={14} /> SFTP
+            </div>
+          )}
         </div>
 
         {/* Scrollable tabs container with fade masks */}
@@ -935,7 +954,7 @@ const TopTabsInner: React.FC<TopTabsProps> = ({
             className="h-6 w-6 app-no-drag"
             style={{ color: 'var(--top-tabs-muted, hsl(var(--muted-foreground)))' }}
             onClick={onToggleTheme}
-            disabled={isImmersiveActive}
+            disabled={isImmersiveActive && !followAppTerminalTheme}
             title="Toggle theme"
           >
             {theme === 'dark' ? <Sun size={16} /> : <Moon size={16} />}
@@ -964,7 +983,10 @@ const topTabsAreEqual = (prev: TopTabsProps, next: TopTabsProps): boolean => {
     prev.isMacClient === next.isMacClient &&
     prev.onOpenSettings === next.onOpenSettings &&
     prev.onSyncNow === next.onSyncNow &&
-    prev.isImmersiveActive === next.isImmersiveActive
+    prev.onToggleTheme === next.onToggleTheme &&
+    prev.followAppTerminalTheme === next.followAppTerminalTheme &&
+    prev.isImmersiveActive === next.isImmersiveActive &&
+    prev.showSftpTab === next.showSftpTab
   );
 };
 

components/VaultView.tsx

@@ -39,7 +39,11 @@ import { resolveGroupDefaults, applyGroupDefaults } from "../domain/groupConfig"
 import { getEffectiveHostDistro, sanitizeHost } from "../domain/host";
 import { importVaultHostsFromText, exportHostsToCsvWithStats } from "../domain/vaultImport";
 import type { VaultImportFormat } from "../domain/vaultImport";
-import { STORAGE_KEY_VAULT_HOSTS_VIEW_MODE, STORAGE_KEY_VAULT_HOSTS_TREE_EXPANDED, STORAGE_KEY_VAULT_SIDEBAR_COLLAPSED, STORAGE_KEY_SHOW_RECENT_HOSTS } from "../infrastructure/config/storageKeys";
+import {
+  STORAGE_KEY_VAULT_HOSTS_TREE_EXPANDED,
+  STORAGE_KEY_VAULT_HOSTS_VIEW_MODE,
+  STORAGE_KEY_VAULT_SIDEBAR_COLLAPSED,
+} from "../infrastructure/config/storageKeys";
 import { cn } from "../lib/utils";
 import { useInstantThemeSwitch } from "../lib/useInstantThemeSwitch";
 import {
@@ -101,6 +105,10 @@ const LazyConnectionLogsManager = lazy(() => import("./ConnectionLogsManager"));
 
 export type VaultSection = "hosts" | "keys" | "snippets" | "port" | "knownhosts" | "logs";
 
+type DropTarget =
+  | { kind: "root" }
+  | { kind: "group"; path: string };
+
 // Props without isActive - it's now subscribed internally
 interface VaultViewProps {
   hosts: Host[];
@@ -143,6 +151,8 @@ interface VaultViewProps {
   onRunSnippet?: (snippet: Snippet, targetHosts: Host[]) => void;
   groupConfigs: GroupConfig[];
   onUpdateGroupConfigs: (configs: GroupConfig[]) => void;
+  showRecentHosts: boolean;
+  showOnlyUngroupedHostsInRoot: boolean;
   // Optional: navigate to a specific section on mount or when changed
   navigateToSection?: VaultSection | null;
   onNavigateToSectionHandled?: () => void;
@@ -189,6 +199,8 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
   onRunSnippet,
   groupConfigs,
   onUpdateGroupConfigs,
+  showRecentHosts,
+  showOnlyUngroupedHostsInRoot,
   navigateToSection,
   onNavigateToSectionHandled,
 }) => {
@@ -222,12 +234,9 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
     false,
   );
 
-  const [isBreadcrumbDragOver, setIsBreadcrumbDragOver] = useState(false);
-
-  const [showRecentHosts, _setShowRecentHosts] = useStoredBoolean(
-    STORAGE_KEY_SHOW_RECENT_HOSTS,
-    true,
-  );
+  const [dragOverDropTarget, setDragOverDropTarget] = useState<DropTarget | null>(null);
+  const [confirmedDropTarget, setConfirmedDropTarget] = useState<DropTarget | null>(null);
+  const dropTargetPulseTimeoutRef = useRef<number | null>(null);
 
   // Handle external navigation requests
   useEffect(() => {
@@ -237,6 +246,14 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
     }
   }, [navigateToSection, onNavigateToSectionHandled]);
 
+  useEffect(() => {
+    return () => {
+      if (dropTargetPulseTimeoutRef.current !== null) {
+        window.clearTimeout(dropTargetPulseTimeoutRef.current);
+      }
+    };
+  }, []);
+
   // View mode, sorting, and tag filter state
   const [viewMode, setViewMode] = useStoredViewMode(
     STORAGE_KEY_VAULT_HOSTS_VIEW_MODE,
@@ -253,6 +270,21 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
   const [editingHost, setEditingHost] = useState<Host | null>(null);
   const [newHostGroupPath, setNewHostGroupPath] = useState<string | null>(null);
 
+  // Close host panel if the host being edited was deleted.
+  // Track previous host IDs so we only close for actual deletions, not for
+  // unsaved new/duplicated hosts whose IDs were never in the hosts array.
+  const knownHostIdsRef = useRef(new Set(hosts.map(h => h.id)));
+  useEffect(() => {
+    const currentIds = new Set(hosts.map(h => h.id));
+    // Check against previous IDs before updating the ref
+    if (editingHost && knownHostIdsRef.current.has(editingHost.id) && !currentIds.has(editingHost.id)) {
+      setIsHostPanelOpen(false);
+      setEditingHost(null);
+      setNewHostGroupPath(null);
+    }
+    knownHostIdsRef.current = currentIds;
+  }, [hosts, editingHost]);
+
   // Group panel state
   const [isGroupPanelOpen, setIsGroupPanelOpen] = useState(false);
   const [editingGroupPath, setEditingGroupPath] = useState<string | null>(null);
@@ -263,7 +295,6 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
     if (!group) return undefined;
     return resolveGroupDefaults(group, groupConfigs);
   }, [editingHost, newHostGroupPath, selectedGroupPath, groupConfigs]);
-
   // Quick connect state
   const [quickConnectTarget, setQuickConnectTarget] = useState<{
     hostname: string;
@@ -846,6 +877,11 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
         }
         return hostGroup === selectedGroupPath;
       });
+    } else if (showOnlyUngroupedHostsInRoot) {
+      filtered = filtered.filter((h) => {
+        const hostGroup = (h.group || "").trim();
+        return hostGroup === "";
+      });
     }
     if (search.trim()) {
       const s = search.toLowerCase();
@@ -883,7 +919,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
       }
     });
     return filtered;
-  }, [hosts, selectedGroupPath, search, selectedTags, sortMode]);
+  }, [hosts, selectedGroupPath, showOnlyUngroupedHostsInRoot, search, selectedTags, sortMode]);
 
   // Pinned hosts for root-level display (not inside a subgroup)
   // Respects active search and tag filters
@@ -928,19 +964,16 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
     }
     return filtered
       .sort((a, b) => (b.lastConnectedAt || 0) - (a.lastConnectedAt || 0))
-      .slice(0, 20);
+      .slice(0, 6);
   }, [hosts, selectedGroupPath, search, selectedTags]);
 
-  // IDs of hosts already shown in Pinned/Recent sections at root level,
-  // so the main host list can exclude them to avoid duplicates.
-  const pinnedRecentIds = useMemo(() => {
-    const ids = new Set<string>();
-    for (const h of pinnedHosts) ids.add(h.id);
-    if (showRecentHosts) {
-      for (const h of recentHosts) ids.add(h.id);
-    }
-    return ids;
-  }, [pinnedHosts, recentHosts, showRecentHosts]);
+  // No longer deduplicate pinned/recent hosts from the main list,
+  // so hosts always appear in their groups regardless of pinned/recent status.
+  const pinnedRecentIds = useMemo(() => new Set<string>(), []);
+  const visibleDisplayedHosts = useMemo(
+    () => displayedHosts.filter((h) => selectedGroupPath || !pinnedRecentIds.has(h.id)),
+    [displayedHosts, selectedGroupPath, pinnedRecentIds],
+  );
 
   // For tree view: apply search, tag filter, and sorting, but not group filtering
   const treeViewHosts = useMemo(() => {
@@ -1104,6 +1137,26 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- findGroupNode is derived from buildGroupTree
   }, [buildGroupTree, selectedGroupPath, customGroups]);
+  const shouldHideEmptyRootHostsSection = useMemo(() => {
+    if (selectedGroupPath || viewMode === "tree") return false;
+    if (search.trim() || selectedTags.length > 0) return false;
+    if (visibleDisplayedHosts.length > 0) return false;
+    return (
+      displayedGroups.length > 0 ||
+      pinnedHosts.length > 0 ||
+      (showRecentHosts && recentHosts.length > 0)
+    );
+  }, [
+    selectedGroupPath,
+    viewMode,
+    search,
+    selectedTags.length,
+    visibleDisplayedHosts.length,
+    displayedGroups.length,
+    pinnedHosts.length,
+    showRecentHosts,
+    recentHosts.length,
+  ]);
 
   // Known Hosts callbacks - use refs to keep stable references
   // Store latest values in refs so callbacks don't need to depend on them
@@ -1421,9 +1474,46 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
   }, [managedSources]);
 
   const isHostsSectionActive = currentSection === "hosts";
+  const hasHostsSidePanel =
+    isHostsSectionActive &&
+    ((isGroupPanelOpen && !!editingGroupPath) || isHostPanelOpen);
+  const splitViewGridStyle = hasHostsSidePanel
+    ? {
+      gridTemplateColumns: "repeat(auto-fill, minmax(min(100%, 220px), 280px))",
+      justifyContent: "start" as const,
+    }
+    : undefined;
 
-  const moveHostToGroup = (hostId: string, groupPath: string | null) => {
+  const isSameDropTarget = useCallback((a: DropTarget | null, b: DropTarget | null) => {
+    if (!a || !b) return a === b;
+    if (a.kind !== b.kind) return false;
+    if (a.kind === "root") return true;
+    return a.path === b.path;
+  }, []);
+
+  const pulseDropTarget = useCallback((target: DropTarget) => {
+    setConfirmedDropTarget(target);
+    if (dropTargetPulseTimeoutRef.current !== null) {
+      window.clearTimeout(dropTargetPulseTimeoutRef.current);
+    }
+    dropTargetPulseTimeoutRef.current = window.setTimeout(() => {
+      setConfirmedDropTarget((current) => (isSameDropTarget(current, target) ? null : current));
+      dropTargetPulseTimeoutRef.current = null;
+    }, 900);
+  }, [isSameDropTarget]);
+
+  const setGroupDragOverDropTarget = useCallback((path: string | null) => {
+    setDragOverDropTarget(path ? { kind: "group", path } : null);
+  }, []);
+
+  const moveHostToGroup = useCallback((hostId: string, groupPath: string | null) => {
     const targetGroup = groupPath || "";
+    const hostToMove = hosts.find((h) => h.id === hostId);
+    if (!hostToMove || (hostToMove.group || "") === targetGroup) {
+      setDragOverDropTarget(null);
+      return;
+    }
+
     // Find the most specific (deepest) managed source that matches the target group
     const targetManagedSource = managedSources
       .filter(s => targetGroup === s.groupName || targetGroup.startsWith(s.groupName + "/"))
@@ -1450,7 +1540,23 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
         };
       }),
     );
-  };
+    setDragOverDropTarget(null);
+    pulseDropTarget(groupPath ? { kind: "group", path: groupPath } : { kind: "root" });
+    toast.success(
+      t("vault.hosts.moveToGroup.success", {
+        host: hostToMove.label,
+        group: groupPath || t("vault.hosts.allHosts"),
+      }),
+    );
+  }, [hosts, managedSources, onUpdateHosts, pulseDropTarget, t]);
+
+  const getDropTargetClasses = (target: DropTarget) =>
+    cn(
+      isSameDropTarget(dragOverDropTarget, target) &&
+        "!bg-[#e7ebf0] dark:!bg-white/[0.10]",
+      isSameDropTarget(confirmedDropTarget, target) &&
+        "!bg-[#dde3ea] dark:!bg-white/[0.14]",
+    );
 
   const handleUnmanageGroup = useCallback((groupPath: string) => {
     const source = managedSources.find(s => s.groupName === groupPath);
@@ -1479,13 +1585,16 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
 
   // Component no longer handles visibility - that's done by VaultViewWrapper
   return (
-    <div ref={rootRef} className="absolute inset-0 min-h-0 flex">
+    <div ref={rootRef} className="absolute inset-0 min-h-0 flex" data-section="vault-view">
       {/* Sidebar */}
       <TooltipProvider delayDuration={100}>
-        <div className={cn(
-          "bg-secondary/80 border-r border-border/60 flex flex-col transition-all duration-200",
-          sidebarCollapsed ? "w-14" : "w-52"
-        )}>
+        <div
+          className={cn(
+            "bg-secondary/80 border-r border-border/60 flex flex-col transition-all duration-200",
+            sidebarCollapsed ? "w-14" : "w-52"
+          )}
+          data-section="vault-sidebar"
+        >
           <div className={cn(
             "py-4 flex items-center",
             sidebarCollapsed ? "px-2 justify-center" : "px-4"
@@ -1648,12 +1757,16 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
       </TooltipProvider>
 
       {/* Main Area */}
-      <div className="flex-1 flex flex-col min-h-0 relative">
+      <div
+        className="flex-1 min-w-0 flex flex-col min-h-0 relative"
+        data-section="vault-main"
+      >
         <header
           className={cn(
             "border-b border-border/50 bg-secondary/80 backdrop-blur app-drag",
             !isHostsSectionActive && "hidden",
           )}
+          data-section="vault-hosts-header"
         >
           <div className="h-14 px-4 py-2 flex items-center gap-3">
             <div className="relative flex-1 app-no-drag">
@@ -1757,14 +1870,25 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                 <CheckSquare size={16} />
               </Button>
             </div>
-            {/* New Host split button */}
-            <div className="flex items-center app-no-drag">
+            {/* New Host split button — collapses with an animation when the
+                host details / new-host aside panel is open, since the button
+                would be a no-op in that state. */}
+            <div
+              className={cn(
+                "flex items-center app-no-drag overflow-hidden transition-[max-width,opacity,margin] duration-200 ease-in-out",
+                isHostPanelOpen
+                  ? "max-w-0 opacity-0 -ml-2 pointer-events-none"
+                  : "max-w-[260px] opacity-100",
+              )}
+              aria-hidden={isHostPanelOpen}
+            >
               <Dropdown>
                 <div className="flex items-center rounded-md bg-primary text-primary-foreground">
                   <Button
                     size="sm"
                     className="h-10 px-3 rounded-r-none bg-transparent hover:bg-white/10 shadow-none app-no-drag"
                     onClick={handleNewHost}
+                    tabIndex={isHostPanelOpen ? -1 : 0}
                   >
                     <Plus size={14} className="mr-2" /> {t("vault.hosts.newHost")}
                   </Button>
@@ -1772,6 +1896,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                     <Button
                       size="sm"
                       className="h-10 px-2 rounded-l-none bg-transparent hover:bg-white/10 border-l border-primary-foreground/20 shadow-none app-no-drag"
+                      tabIndex={isHostPanelOpen ? -1 : 0}
                     >
                       <ChevronDown size={14} />
                     </Button>
@@ -1808,22 +1933,37 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                 </DropdownContent>
               </Dropdown>
             </div>
-            <Button
-              size="sm"
-              variant="secondary"
-              className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
-              onClick={onCreateLocalTerminal}
+            {/* Terminal + Serial — collapse together with an animation when
+                the host details / new-host aside panel is open, freeing
+                horizontal space for the panel. */}
+            <div
+              className={cn(
+                "flex items-center gap-3 overflow-hidden transition-[max-width,opacity,margin] duration-200 ease-in-out",
+                isHostPanelOpen
+                  ? "max-w-0 opacity-0 -ml-3 pointer-events-none"
+                  : "max-w-[320px] opacity-100",
+              )}
+              aria-hidden={isHostPanelOpen}
             >
-              <TerminalSquare size={14} className="mr-2" /> {t("common.terminal")}
-            </Button>
-            <Button
-              size="sm"
-              variant="secondary"
-              className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
-              onClick={() => setIsSerialModalOpen(true)}
-            >
-              <Usb size={14} className="mr-2" /> {t("serial.button")}
-            </Button>
+              <Button
+                size="sm"
+                variant="secondary"
+                className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
+                onClick={onCreateLocalTerminal}
+                tabIndex={isHostPanelOpen ? -1 : 0}
+              >
+                <TerminalSquare size={14} className="mr-2" /> {t("common.terminal")}
+              </Button>
+              <Button
+                size="sm"
+                variant="secondary"
+                className="h-10 px-3 app-no-drag bg-foreground/5 text-foreground hover:bg-foreground/10 border-border/40"
+                onClick={() => setIsSerialModalOpen(true)}
+                tabIndex={isHostPanelOpen ? -1 : 0}
+              >
+                <Usb size={14} className="mr-2" /> {t("serial.button")}
+              </Button>
+            </div>
           </div>
         </header>
 
@@ -1833,24 +1973,34 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
             "flex-1 overflow-auto px-4 py-4 space-y-6",
             !isHostsSectionActive && "hidden",
           )}
+          data-section="vault-host-list"
+          onDragEndCapture={() => setDragOverDropTarget(null)}
         >
                 <section className="space-y-2">
                   {viewMode !== "tree" && (
                     <div className="flex items-center gap-2 text-sm font-semibold">
                       <button
                         className={cn(
-                          "text-primary hover:underline transition-all rounded px-1 -mx-1",
-                          isBreadcrumbDragOver && "ring-2 ring-primary bg-primary/10",
+                          "text-primary hover:underline transition-colors duration-150 rounded px-1 -mx-1",
+                          getDropTargetClasses({ kind: "root" }),
                         )}
                         onClick={() => setSelectedGroupPath(null)}
                         onDragOver={(e) => {
                           e.preventDefault();
-                          setIsBreadcrumbDragOver(true);
+                          setDragOverDropTarget({ kind: "root" });
+                        }}
+                        onDragLeave={(e) => {
+                          const nextTarget = e.relatedTarget;
+                          if (nextTarget instanceof Node && e.currentTarget.contains(nextTarget)) {
+                            return;
+                          }
+                          setDragOverDropTarget((current) =>
+                            current?.kind === "root" ? null : current,
+                          );
                         }}
-                        onDragLeave={() => setIsBreadcrumbDragOver(false)}
                         onDrop={(e) => {
                           e.preventDefault();
-                          setIsBreadcrumbDragOver(false);
+                          setDragOverDropTarget(null);
                           const groupPath = e.dataTransfer.getData("group-path");
                           const hostId = e.dataTransfer.getData("host-id");
                           if (groupPath) moveGroup(groupPath, null);
@@ -1898,9 +2048,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       </h3>
                       <div className={cn(
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
-                      )}>
+                      )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}>
                         {pinnedHosts.map((host) => {
                           const safeHost = sanitizeHost(host);
                           const effectiveDistro = getEffectiveHostDistro(safeHost);
@@ -1998,9 +2152,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       </h3>
                       <div className={cn(
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
-                      )}>
+                      )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}>
                         {recentHosts.map((host) => {
                           const safeHost = sanitizeHost(host);
                           const effectiveDistro = getEffectiveHostDistro(safeHost);
@@ -2099,9 +2257,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       className={cn(
                         displayedGroups.length === 0 ? "hidden" : "",
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
                       )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}
                       onDragOver={(e) => {
                         e.preventDefault();
                       }}
@@ -2120,10 +2282,11 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                           <ContextMenuTrigger asChild>
                             <div
                               className={cn(
-                                "group cursor-pointer",
+                                "group cursor-pointer transition-colors duration-150",
                                 viewMode === "grid"
                                   ? "soft-card elevate rounded-xl h-[68px] px-3 py-2"
                                   : "h-14 px-3 py-2 hover:bg-secondary/60 rounded-lg transition-colors",
+                                getDropTargetClasses({ kind: "group", path: node.path }),
                               )}
                               draggable
                               onDragStart={(e) =>
@@ -2136,10 +2299,21 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                               onDragOver={(e) => {
                                 e.preventDefault();
                                 e.stopPropagation();
+                                setDragOverDropTarget({ kind: "group", path: node.path });
+                              }}
+                              onDragLeave={(e) => {
+                                const nextTarget = e.relatedTarget;
+                                if (nextTarget instanceof Node && e.currentTarget.contains(nextTarget)) {
+                                  return;
+                                }
+                                setDragOverDropTarget((current) =>
+                                  current?.kind === "group" && current.path === node.path ? null : current,
+                                );
                               }}
                               onDrop={(e) => {
                                 e.preventDefault();
                                 e.stopPropagation();
+                                setDragOverDropTarget(null);
                                 const hostId =
                                   e.dataTransfer.getData("host-id");
                                 const groupPath =
@@ -2211,6 +2385,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                   )}
                 </section>
 
+                {!shouldHideEmptyRootHostsSection && (
                 <section className="space-y-2">
                   <div className="flex items-center justify-between">
                     <h3 className="text-sm font-semibold text-muted-foreground">
@@ -2218,7 +2393,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                     </h3>
                     <div className="flex items-center gap-2 text-xs text-muted-foreground">
                       <span>
-                        {t("vault.hosts.header.entries", { count: viewMode === "tree" ? treeViewHosts.length : displayedHosts.length })}
+                        {t("vault.hosts.header.entries", { count: viewMode === "tree" ? treeViewHosts.length : visibleDisplayedHosts.length })}
                       </span>
                       <div className="bg-secondary/80 border border-border/70 rounded-md px-2 py-1 text-[11px]">
                         {t("vault.hosts.header.live", { count: sessions.length })}
@@ -2306,6 +2481,10 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                       isMultiSelectMode={isMultiSelectMode}
                       selectedHostIds={selectedHostIds}
                       toggleHostSelection={toggleHostSelection}
+                      getDropTargetClasses={(path) =>
+                        getDropTargetClasses({ kind: "group", path })
+                      }
+                      setDragOverDropTarget={setGroupDragOverDropTarget}
                     />
                   ) : sortMode === "group" && groupedDisplayHosts ? (
                     <div className="space-y-6">
@@ -2323,9 +2502,13 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                             <div
                               className={cn(
                                 viewMode === "grid"
-                                  ? "grid gap-3 grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                                  ? cn(
+                                    "grid gap-3",
+                                    !hasHostsSidePanel && "grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                                  )
                                   : "flex flex-col gap-0",
                               )}
+                              style={viewMode === "grid" ? splitViewGridStyle : undefined}
                             >
                               {group.hosts.filter((h) => selectedGroupPath || !pinnedRecentIds.has(h.id)).map((host) => {
                                 const safeHost = sanitizeHost(host);
@@ -2464,11 +2647,15 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                     <div
                       className={cn(
                         viewMode === "grid"
-                          ? "grid gap-3 grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                          ? cn(
+                            "grid gap-3",
+                            !hasHostsSidePanel && "grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+                          )
                           : "flex flex-col gap-0",
                       )}
+                      style={viewMode === "grid" ? splitViewGridStyle : undefined}
                     >
-                      {displayedHosts.filter((h) => selectedGroupPath || !pinnedRecentIds.has(h.id)).map((host) => {
+                      {visibleDisplayedHosts.map((host) => {
                           const safeHost = sanitizeHost(host);
                           const effectiveDistro = getEffectiveHostDistro(safeHost);
                           const distroBadge = {
@@ -2600,6 +2787,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
                     </div>
                   )}
                 </section>
+                )}
         </div>
 
         {currentSection === "snippets" && (
@@ -2726,12 +2914,14 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
           allHosts={hosts}
           groups={allGroupPaths}
           terminalThemeId={terminalThemeId}
+          groupConfigs={groupConfigs}
           terminalFontSize={terminalFontSize}
           onSave={handleSaveGroupConfig}
           onCancel={() => {
             setIsGroupPanelOpen(false);
             setEditingGroupPath(null);
           }}
+          layout="inline"
         />
       )}
 
@@ -2749,6 +2939,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
           terminalThemeId={terminalThemeId}
           terminalFontSize={terminalFontSize}
           groupDefaults={editingHostGroupDefaults}
+          groupConfigs={groupConfigs}
           onSave={(host) => {
             // Check if host already exists in the list (for updates vs. new/duplicate)
             const hostExists = hosts.some((h) => h.id === host.id);
@@ -2771,6 +2962,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
               Array.from(new Set([...customGroups, groupPath])),
             );
           }}
+          layout="inline"
         />
       )}
 
@@ -2791,6 +2983,7 @@ const VaultViewInner: React.FC<VaultViewProps> = ({
             setIsHostPanelOpen(false);
             setEditingHost(null);
           }}
+          layout="inline"
         />
       )}
 

components/ai-elements/conversation.tsx

@@ -8,7 +8,7 @@ export type ConversationProps = ComponentProps<typeof StickToBottom>;
 
 export const Conversation = ({ className, ...props }: ConversationProps) => (
   <StickToBottom
-    className={cn('relative flex-1 overflow-y-hidden', className)}
+    className={cn('relative flex-1 overflow-x-hidden overflow-y-hidden', className)}
     initial="instant"
     resize="smooth"
     role="log"
@@ -20,7 +20,7 @@ export type ConversationContentProps = ComponentProps<typeof StickToBottom.Conte
 
 export const ConversationContent = ({ className, ...props }: ConversationContentProps) => (
   <StickToBottom.Content
-    className={cn('flex flex-col gap-4 p-4', className)}
+    className={cn('flex min-w-0 max-w-full flex-col gap-4 overflow-x-hidden p-4', className)}
     {...props}
   />
 );

components/ai-elements/message.tsx

@@ -62,7 +62,7 @@ export const MessageResponse = memo(
         // Style the rendered markdown
         // Code: base styles (code-block overrides are in index.css)
         '[&_code]:text-[12px] [&_code]:font-mono',
-        '[&_p_code]:px-[0.4em] [&_p_code]:py-[0.15em] [&_p_code]:rounded [&_p_code]:bg-foreground/[0.06] [&_p_code]:text-[85%]',
+        '[&_p_code]:px-[0.4em] [&_p_code]:py-[0.15em] [&_p_code]:rounded [&_p_code]:bg-foreground/[0.06] [&_p_code]:text-[85%] [&_p_code]:whitespace-normal [&_p_code]:[overflow-wrap:anywhere]',
         '[&_p]:my-1.5',
         '[&_ul]:my-1.5 [&_ul]:pl-4 [&_ul]:list-disc',
         '[&_ol]:my-1.5 [&_ol]:pl-4 [&_ol]:list-decimal',

components/ai-elements/tool-call.tsx

@@ -1,6 +1,7 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import type { HTMLAttributes } from 'react';
 import { cn } from '../../lib/utils';
 import { Check, ChevronDown, ChevronRight, CheckCircle2, Loader2, ShieldAlert, X, XCircle, Slash } from 'lucide-react';
-import React, { useCallback, useEffect, useRef, useState, type HTMLAttributes } from 'react';
 import { Button } from '../ui/button';
 import { Badge } from '../ui/badge';
 import { useI18n } from '../../application/i18n/I18nProvider';
@@ -40,6 +41,7 @@ function formatToolResult(result: unknown): string {
 
 export interface ToolCallProps extends HTMLAttributes<HTMLDivElement> {
   name: string;
+  className?: string;
   args?: Record<string, unknown>;
   result?: unknown;
   isError?: boolean;

components/ai/ChatInput.tsx

@@ -6,12 +6,11 @@
  * and a bottom toolbar with muted controls + subtle send button.
  */
 
-import { AtSign, Check, ChevronDown, ChevronRight, Cpu, Expand, Eye, FileText, ImageIcon, Plus, ShieldCheck, X, Zap } from 'lucide-react';
-import React, { useCallback, useRef, useState } from 'react';
+import { AtSign, Check, ChevronDown, ChevronRight, Cpu, Expand, Eye, FileText, ImageIcon, Package, Plus, ShieldCheck, X, Zap } from 'lucide-react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { createPortal } from 'react-dom';
 import type { FormEvent } from 'react';
-import type { UploadedFile } from '../../application/state/useFileUpload';
 import {
   PromptInput,
   PromptInputFooter,
@@ -21,7 +20,11 @@ import {
 } from '../ai-elements/prompt-input';
 import type { PromptInputStatus } from '../ai-elements/prompt-input';
 import { formatThinkingLabel } from '../../infrastructure/ai/types';
-import type { AgentModelPreset, AIPermissionMode } from '../../infrastructure/ai/types';
+import type { AgentModelPreset, AIPermissionMode, UploadedFile } from '../../infrastructure/ai/types';
+import { ScrollArea } from '../ui/scroll-area';
+
+// Keep in sync with the popover's Tailwind max-width below.
+const MODEL_PICKER_MAX_WIDTH = 360;
 
 interface ChatInputProps {
   value: string;
@@ -48,6 +51,14 @@ interface ChatInputProps {
   onRemoveFile?: (id: string) => void;
   /** Available hosts for @ mention */
   hosts?: Array<{ sessionId: string; hostname: string; label: string; connected: boolean }>;
+  /** User skills currently selected for the next send */
+  selectedUserSkills?: Array<{ id: string; slug: string; name: string; description: string }>;
+  /** Available user skills for /skill-slug insertion */
+  userSkills?: Array<{ id: string; slug: string; name: string; description: string }>;
+  /** Callback to add a selected user skill */
+  onAddUserSkill?: (slug: string) => void;
+  /** Callback to remove a selected user skill */
+  onRemoveUserSkill?: (slug: string) => void;
   /** Permission mode (only shown for Catty Agent) */
   permissionMode?: AIPermissionMode;
   /** Callback when user changes permission mode */
@@ -72,38 +83,76 @@ const ChatInput: React.FC<ChatInputProps> = ({
   onAddFiles,
   onRemoveFile,
   hosts = [],
+  selectedUserSkills = [],
+  userSkills = [],
+  onAddUserSkill,
+  onRemoveUserSkill,
   permissionMode,
   onPermissionModeChange,
 }) => {
   const { t } = useI18n();
   const [expanded, setExpanded] = useState(false);
   // Consolidate menu state into a single discriminated union to prevent multiple menus open simultaneously
-  type ActiveMenu = 'model' | 'attach' | 'atMention' | 'perm' | null;
+  type ActiveMenu = 'model' | 'attach' | 'atMention' | 'slashSkill' | 'perm' | null;
   const [activeMenu, setActiveMenu] = useState<ActiveMenu>(null);
   const [menuPos, setMenuPos] = useState<{ left: number; bottom: number } | null>(null);
+  const [inputPanelPos, setInputPanelPos] = useState<{ left: number; bottom: number; width: number } | null>(null);
   const [hoveredModelId, setHoveredModelId] = useState<string | null>(null);
-  const [showHostSubmenu, setShowHostSubmenu] = useState(false);
+  const [slashQuery, setSlashQuery] = useState('');
+  const [slashRange, setSlashRange] = useState<{ start: number; end: number } | null>(null);
+  // Active highlight index for @ mention / slash skill keyboard navigation
+  const [activeMenuIndex, setActiveMenuIndex] = useState(0);
 
   // Derived booleans for readability
   const showModelPicker = activeMenu === 'model';
   const showAttachMenu = activeMenu === 'attach';
   const showAtMention = activeMenu === 'atMention';
+  const showSlashSkillPicker = activeMenu === 'slashSkill';
   const showPermPicker = activeMenu === 'perm';
 
   const closeAllMenus = useCallback(() => {
     setActiveMenu(null);
     setMenuPos(null);
+    setInputPanelPos(null);
     setHoveredModelId(null);
-    setShowHostSubmenu(false);
+    setSlashQuery('');
+    setSlashRange(null);
   }, []);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const inputShellRef = useRef<HTMLDivElement>(null);
   const modelBtnRef = useRef<HTMLButtonElement>(null);
   const permBtnRef = useRef<HTMLButtonElement>(null);
   const attachBtnRef = useRef<HTMLButtonElement>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
 
+  const findSlashTrigger = useCallback((text: string, caretPosition: number) => {
+    const beforeCaret = text.slice(0, caretPosition);
+    const match = /(^|\s)\/([a-z0-9-]*)$/i.exec(beforeCaret);
+    if (!match) return null;
+    const start = beforeCaret.length - match[0].length + match[1].length;
+    return {
+      start,
+      end: beforeCaret.length,
+      query: String(match[2] || '').toLowerCase(),
+    };
+  }, []);
+
+  const getInputPanelMenuPos = useCallback(() => {
+    const rect = inputShellRef.current?.getBoundingClientRect();
+    if (!rect) return null;
+    const horizontalMargin = 12;
+    const safeRight = window.innerWidth - horizontalMargin;
+    const width = Math.min(rect.width, safeRight - rect.left);
+    return {
+      left: rect.left,
+      bottom: window.innerHeight - rect.top + 8,
+      width,
+    };
+  }, []);
+
   const handleInputChange = useCallback((newValue: string) => {
     onChange(newValue);
+    const caretPosition = textareaRef.current?.selectionStart ?? newValue.length;
     // Detect if user just typed @
     if (
       hosts.length > 0 &&
@@ -111,16 +160,28 @@ const ChatInput: React.FC<ChatInputProps> = ({
       newValue.endsWith('@')
     ) {
       // Position the popover near the textarea
-      const el = textareaRef.current;
-      if (el) {
-        const rect = el.getBoundingClientRect();
-        setMenuPos({ left: rect.left + 12, bottom: window.innerHeight - rect.top + 4 });
-      }
+      const pos = getInputPanelMenuPos();
+      if (pos) setInputPanelPos(pos);
       setActiveMenu('atMention');
-    } else if (showAtMention && !newValue.includes('@')) {
-      setActiveMenu(null);
+      return;
     }
-  }, [onChange, value, hosts.length, showAtMention]);
+
+    const slashTrigger = findSlashTrigger(newValue, caretPosition);
+    if (userSkills.length > 0 && slashTrigger) {
+      const pos = getInputPanelMenuPos();
+      if (pos) setInputPanelPos(pos);
+      setSlashQuery(slashTrigger.query);
+      setSlashRange({ start: slashTrigger.start, end: slashTrigger.end });
+      setActiveMenu('slashSkill');
+      return;
+    }
+
+    if (showAtMention && !newValue.includes('@')) {
+      setActiveMenu(null);
+    } else if (showSlashSkillPicker) {
+      closeAllMenus();
+    }
+  }, [onChange, value, hosts.length, showAtMention, findSlashTrigger, userSkills.length, showSlashSkillPicker, closeAllMenus, getInputPanelMenuPos]);
 
   const handleSelectAtMention = useCallback((host: { label: string; hostname: string }) => {
     // Replace the trailing @ with @hostname
@@ -133,10 +194,117 @@ const ChatInput: React.FC<ChatInputProps> = ({
     closeAllMenus();
   }, [value, onChange, closeAllMenus]);
 
+  const openInputPanelMenu = useCallback((menu: 'atMention' | 'slashSkill') => {
+    const pos = getInputPanelMenuPos();
+    if (!pos) return;
+    setInputPanelPos(pos);
+    if (menu === 'slashSkill') {
+      setSlashQuery('');
+      setSlashRange(null);
+    }
+    setActiveMenu(menu);
+  }, [getInputPanelMenuPos]);
+
+  const filteredUserSkills = useMemo(() => userSkills.filter((skill) => {
+    if (!slashQuery) return true;
+    const lowerQuery = slashQuery.toLowerCase();
+    return skill.slug.toLowerCase().startsWith(lowerQuery) || skill.name.toLowerCase().includes(lowerQuery);
+  }), [userSkills, slashQuery]);
+
+  const removeSlashQueryFromInput = useCallback(() => {
+    if (!slashRange) return value;
+    const before = value.slice(0, slashRange.start);
+    const after = value.slice(slashRange.end);
+    if (/\s$/.test(before) && /^\s/.test(after)) {
+      return `${before}${after.slice(1)}`;
+    }
+    return `${before}${after}`;
+  }, [slashRange, value]);
+
+  const insertUserSkillToken = useCallback((skill: { slug: string }) => {
+    onAddUserSkill?.(skill.slug);
+    if (slashRange) {
+      onChange(removeSlashQueryFromInput());
+    }
+    closeAllMenus();
+  }, [closeAllMenus, onAddUserSkill, onChange, removeSlashQueryFromInput, slashRange]);
+
+  // Reset active highlight when a menu opens or when the *identity* of the
+  // visible items changes. Watching only `.length` misses cases where the
+  // filter produces a different set with the same count (e.g. user types
+  // another character into the slash query) — Enter would then commit an
+  // unexpected item. Derive a stable key from the visible ids instead.
+  const atMentionKey = useMemo(
+    () => hosts.map((h) => h.sessionId).join('|'),
+    [hosts],
+  );
+  const slashSkillKey = useMemo(
+    () => filteredUserSkills.map((s) => s.id).join('|'),
+    [filteredUserSkills],
+  );
+  useEffect(() => {
+    if (showAtMention) setActiveMenuIndex(0);
+  }, [showAtMention, atMentionKey]);
+  useEffect(() => {
+    if (showSlashSkillPicker) setActiveMenuIndex(0);
+  }, [showSlashSkillPicker, slashSkillKey]);
+
+  const handleTextareaKeyDown = useCallback((e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.nativeEvent.isComposing) return;
+    // @ mention popover keyboard navigation
+    if (showAtMention && hosts.length > 0) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setActiveMenuIndex((i) => (i + 1) % hosts.length);
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setActiveMenuIndex((i) => (i - 1 + hosts.length) % hosts.length);
+        return;
+      }
+      if (e.key === 'Enter' && !e.shiftKey) {
+        e.preventDefault();
+        const host = hosts[Math.min(activeMenuIndex, hosts.length - 1)];
+        if (host) handleSelectAtMention(host);
+        return;
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        closeAllMenus();
+        return;
+      }
+    }
+    // / skill popover keyboard navigation
+    if (showSlashSkillPicker && filteredUserSkills.length > 0) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setActiveMenuIndex((i) => (i + 1) % filteredUserSkills.length);
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setActiveMenuIndex((i) => (i - 1 + filteredUserSkills.length) % filteredUserSkills.length);
+        return;
+      }
+      if (e.key === 'Enter' && !e.shiftKey) {
+        e.preventDefault();
+        const skill = filteredUserSkills[Math.min(activeMenuIndex, filteredUserSkills.length - 1)];
+        if (skill) insertUserSkillToken(skill);
+        return;
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        closeAllMenus();
+        return;
+      }
+    }
+  }, [showAtMention, hosts, showSlashSkillPicker, filteredUserSkills, activeMenuIndex, handleSelectAtMention, insertUserSkillToken, closeAllMenus]);
+
   const handlePaste = useCallback((e: React.ClipboardEvent) => {
     const pastedFiles = Array.from(e.clipboardData.items)
-      .map((item) => item.getAsFile())
-      .filter(Boolean) as File[];
+      .map((item: DataTransferItem) => item.getAsFile())
+      .filter((f): f is File => !!f);
     if (pastedFiles.length > 0) {
       e.preventDefault();
       onAddFiles?.(pastedFiles);
@@ -166,21 +334,40 @@ const ChatInput: React.FC<ChatInputProps> = ({
 
   // Permission mode chip removed — agents run in autonomous mode
 
-  // selectedModelId may be "model/thinking" for codex
-  const selectedBaseModelId = selectedModelId?.split('/')[0];
-  const selectedThinking = selectedModelId?.includes('/') ? selectedModelId.split('/')[1] : undefined;
-  const selectedPreset = modelPresets.find(m => m.id === selectedBaseModelId);
+  // selectedModelId may be "<modelId>/<thinkingLevel>" for codex ChatGPT models
+  // (e.g. "gpt-5.4/high"). Note: custom config.toml / OpenRouter model ids
+  // themselves can contain '/' (e.g. "qwen/qwen3.6-plus"), so don't just
+  // split on the first '/'. Match against the full id first; only treat the
+  // trailing segment as a thinking level when we find a preset whose
+  // declared thinkingLevels make the combined form equal to selectedModelId.
+  const { selectedPreset, selectedThinking } = (() => {
+    if (!selectedModelId) return { selectedPreset: undefined, selectedThinking: undefined };
+    const direct = modelPresets.find(m => m.id === selectedModelId);
+    if (direct) return { selectedPreset: direct, selectedThinking: undefined };
+    const viaThinking = modelPresets.find(
+      m => m.thinkingLevels?.some(level => `${m.id}/${level}` === selectedModelId),
+    );
+    if (viaThinking) {
+      const thinking = selectedModelId.slice(viaThinking.id.length + 1);
+      return { selectedPreset: viaThinking, selectedThinking: thinking };
+    }
+    return { selectedPreset: undefined, selectedThinking: undefined };
+  })();
+  const selectedBaseModelId = selectedPreset?.id;
   const modelLabel = selectedPreset
     ? selectedPreset.name + (selectedThinking ? ` / ${formatThinkingLabel(selectedThinking)}` : '')
     : modelName || providerName || t('ai.chat.noModel');
   const hasModelPicker = modelPresets.length > 0 && onModelSelect;
   const chipClassName =
     'inline-flex h-6 items-center gap-1 rounded-full px-1.5 text-[10.5px] text-foreground/72';
+  const selectedSkillChipClassName =
+    'inline-flex h-7 items-center gap-1.5 rounded-full border border-primary/18 bg-primary/8 pl-2.5 pr-1.5 text-[11px] font-medium text-foreground/86 shadow-[inset_0_1px_0_rgba(255,255,255,0.06)]';
   const iconButtonClassName =
     'h-6 w-6 rounded-full bg-transparent text-foreground/62 hover:bg-muted/24 hover:text-foreground';
 
   return (
     <div className="shrink-0 px-4 pb-4">
+      <div ref={inputShellRef} className="relative">
       <PromptInput onSubmit={handleSubmit}>
         {/* File attachment chips */}
         {files.length > 0 && (
@@ -224,13 +411,44 @@ const ChatInput: React.FC<ChatInputProps> = ({
 
         {/* Textarea with expand toggle */}
         <div className="relative" onPaste={handlePaste} onDrop={handleDrop} onDragOver={(e) => e.preventDefault()}>
+          {selectedUserSkills.length > 0 && (
+            <div className="px-3 pt-3 pb-1.5">
+              <div className="flex flex-wrap gap-2">
+                {selectedUserSkills.map((skill) => (
+                  <div
+                    key={skill.id}
+                    className={selectedSkillChipClassName}
+                    title={skill.description || skill.name || skill.slug}
+                  >
+                    <Package size={11} className="text-primary/72 shrink-0" />
+                    <span className="truncate max-w-[180px]">
+                      {skill.name && skill.name !== skill.slug ? skill.name : `/${skill.slug}`}
+                    </span>
+                    <button
+                      type="button"
+                      onClick={() => onRemoveUserSkill?.(skill.slug)}
+                      className="inline-flex h-4.5 w-4.5 items-center justify-center rounded-full text-foreground/42 hover:bg-primary/10 hover:text-foreground/72 transition-colors cursor-pointer"
+                      aria-label={`Remove skill ${skill.name || skill.slug}`}
+                    >
+                      <X size={9} />
+                    </button>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
           <PromptInputTextarea
             ref={textareaRef}
             value={value}
             onChange={(e) => handleInputChange(e.target.value)}
+            onKeyDown={handleTextareaKeyDown}
             placeholder={placeholder || defaultPlaceholder}
             disabled={disabled}
-            className={expanded ? 'max-h-[220px]' : undefined}
+            className={[
+              selectedUserSkills.length > 0 ? 'pt-1.5' : undefined,
+              expanded ? 'max-h-[220px]' : undefined,
+            ].filter(Boolean).join(' ')}
+            maxLength={100000}
           />
           <button
             type="button"
@@ -243,31 +461,93 @@ const ChatInput: React.FC<ChatInputProps> = ({
         </div>
 
         {/* @ mention popover */}
-        {showAtMention && hosts.length > 0 && menuPos && createPortal(
+        {showAtMention && hosts.length > 0 && inputPanelPos && createPortal(
           <>
             <div className="fixed inset-0 z-[999]" onClick={closeAllMenus} />
             <div
               role="listbox"
               aria-label="Mention host"
-              className="fixed z-[1000] min-w-[160px] rounded-lg border border-border/50 bg-popover shadow-lg py-1"
-              style={{ left: menuPos.left, bottom: menuPos.bottom }}
+              aria-activedescendant={hosts[activeMenuIndex] ? `at-mention-${hosts[activeMenuIndex].sessionId}` : undefined}
+              className="fixed z-[1000] overflow-hidden rounded-lg border border-border/50 bg-popover shadow-lg"
+              style={{ left: inputPanelPos.left, bottom: inputPanelPos.bottom, width: 'auto', minWidth: Math.min(200, inputPanelPos.width), maxWidth: inputPanelPos.width }}
             >
-              <div className="px-3 py-1 text-[10px] text-muted-foreground/40 tracking-wide">{t('ai.chat.menuHosts')}</div>
-              {hosts.map(host => (
-                <button
-                  key={host.sessionId}
-                  type="button"
-                  role="option"
-                  onClick={() => handleSelectAtMention(host)}
-                  className="w-full flex items-center gap-2 px-3 py-1.5 text-left text-[12px] hover:bg-muted/30 transition-colors cursor-pointer whitespace-nowrap"
-                >
-                  <span className={`h-1.5 w-1.5 rounded-full shrink-0 ${host.connected ? 'bg-green-500' : 'bg-muted-foreground/30'}`} />
-                  <span className="text-foreground/85 truncate">{host.label || host.hostname}</span>
-                  {host.label && host.hostname !== host.label && (
-                    <span className="text-[10px] text-muted-foreground/40">{host.hostname}</span>
-                  )}
-                </button>
-              ))}
+              <ScrollArea className="max-h-[280px]">
+                <div className="p-1">
+                  {hosts.map((host, idx) => {
+                    const isActive = idx === activeMenuIndex;
+                    const showHostnameLine = host.label
+                      && host.hostname !== host.label
+                      && !host.label.includes(host.hostname);
+                    return (
+                      <button
+                        id={`at-mention-${host.sessionId}`}
+                        key={host.sessionId}
+                        type="button"
+                        role="option"
+                        aria-selected={isActive}
+                        onMouseEnter={() => setActiveMenuIndex(idx)}
+                        onClick={() => handleSelectAtMention(host)}
+                        className={`w-full rounded-md px-2 py-1 text-left transition-colors cursor-pointer ${isActive ? 'bg-muted/40' : 'hover:bg-muted/30'}`}
+                      >
+                        <div className="flex items-center gap-2 text-[12px] text-foreground/90">
+                          <span className={`h-1.5 w-1.5 rounded-full shrink-0 ${host.connected ? 'bg-green-500' : 'bg-muted-foreground/30'}`} />
+                          <span className="truncate">{host.label || host.hostname}</span>
+                        </div>
+                        {showHostnameLine ? (
+                          <div className="pl-3.5 text-[10px] text-muted-foreground/60 truncate">
+                            {host.hostname}
+                          </div>
+                        ) : null}
+                      </button>
+                    );
+                  })}
+                </div>
+              </ScrollArea>
+            </div>
+          </>,
+          document.body,
+        )}
+
+        {/* / skill popover */}
+        {showSlashSkillPicker && filteredUserSkills.length > 0 && inputPanelPos && createPortal(
+          <>
+            <div className="fixed inset-0 z-[999]" onClick={closeAllMenus} />
+            <div
+              role="listbox"
+              aria-label="Insert user skill"
+              aria-activedescendant={filteredUserSkills[activeMenuIndex] ? `slash-skill-${filteredUserSkills[activeMenuIndex].id}` : undefined}
+              className="fixed z-[1000] overflow-hidden rounded-lg border border-border/50 bg-popover shadow-lg"
+              style={{ left: inputPanelPos.left, bottom: inputPanelPos.bottom, width: 'auto', minWidth: Math.min(200, inputPanelPos.width), maxWidth: inputPanelPos.width }}
+            >
+              <ScrollArea className="max-h-[280px]">
+                <div className="p-1">
+                  {filteredUserSkills.map((skill, idx) => {
+                    const isActive = idx === activeMenuIndex;
+                    return (
+                      <button
+                        id={`slash-skill-${skill.id}`}
+                        key={skill.id}
+                        type="button"
+                        role="option"
+                        aria-selected={isActive}
+                        onMouseEnter={() => setActiveMenuIndex(idx)}
+                        onClick={() => insertUserSkillToken(skill)}
+                        className={`w-full rounded-md px-2 py-1 text-left transition-colors cursor-pointer ${isActive ? 'bg-muted/40' : 'hover:bg-muted/30'}`}
+                      >
+                        <div className="flex items-center gap-2 text-[12px]">
+                          <Package size={12} className="text-muted-foreground/55 shrink-0" />
+                          <span className="text-foreground/90">/{skill.slug}</span>
+                        </div>
+                        {skill.description ? (
+                          <div className="pl-5 text-[10px] leading-4.5 text-muted-foreground/62 line-clamp-2">
+                            {skill.description}
+                          </div>
+                        ) : null}
+                      </button>
+                    );
+                  })}
+                </div>
+              </ScrollArea>
             </div>
           </>,
           document.body,
@@ -322,48 +602,30 @@ const ChatInput: React.FC<ChatInputProps> = ({
                     <ImageIcon size={13} className="text-muted-foreground/60" />
                     <span className="text-foreground/85">{t('ai.chat.menuImage')}</span>
                   </button>
-                  <div
-                    className="relative"
-                    onMouseEnter={() => setShowHostSubmenu(true)}
-                    onMouseLeave={() => setShowHostSubmenu(false)}
-                    onFocus={() => setShowHostSubmenu(true)}
-                    onBlur={(e) => { if (!e.currentTarget.contains(e.relatedTarget)) setShowHostSubmenu(false); }}
+                  <button
+                    type="button"
+                    role="menuitem"
+                    aria-label="Mention host"
+                    onClick={() => openInputPanelMenu('atMention')}
+                    className="w-full flex items-center gap-2.5 px-3 py-1.5 text-left text-[12px] hover:bg-muted/30 transition-colors cursor-pointer whitespace-nowrap"
                   >
+                    <AtSign size={13} className="text-muted-foreground/60" />
+                    <span className="flex-1 text-foreground/85">{t('ai.chat.menuMentionHost')}</span>
+                    {hosts.length > 0 && <ChevronRight size={10} className="text-muted-foreground/50" />}
+                  </button>
+                  {userSkills.length > 0 && (
                     <button
                       type="button"
                       role="menuitem"
-                      aria-label="Mention host"
-                      aria-expanded={showHostSubmenu && hosts.length > 0}
+                      aria-label="Insert user skill"
+                      onClick={() => openInputPanelMenu('slashSkill')}
                       className="w-full flex items-center gap-2.5 px-3 py-1.5 text-left text-[12px] hover:bg-muted/30 transition-colors cursor-pointer whitespace-nowrap"
                     >
-                      <AtSign size={13} className="text-muted-foreground/60" />
-                      <span className="flex-1 text-foreground/85">{t('ai.chat.menuMentionHost')}</span>
-                      {hosts.length > 0 && <ChevronRight size={10} className="text-muted-foreground/50" />}
+                      <Package size={13} className="text-muted-foreground/60" />
+                      <span className="flex-1 text-foreground/85">{t('ai.chat.menuUserSkills')}</span>
+                      <ChevronRight size={10} className="text-muted-foreground/50" />
                     </button>
-                    {showHostSubmenu && hosts.length > 0 && (
-                      <div role="menu" className="absolute left-full top-0 ml-1 min-w-[160px] rounded-lg border border-border/50 bg-popover shadow-lg py-1 z-[1001]">
-                        {hosts.map(host => (
-                          <button
-                            key={host.sessionId}
-                            type="button"
-                            role="menuitem"
-                            onClick={() => {
-                              const mention = `@${host.label || host.hostname} `;
-                              onChange(value + mention);
-                              closeAllMenus();
-                            }}
-                            className="w-full flex items-center gap-2 px-3 py-1.5 text-left text-[12px] hover:bg-muted/30 transition-colors cursor-pointer whitespace-nowrap"
-                          >
-                            <span className={`h-1.5 w-1.5 rounded-full shrink-0 ${host.connected ? 'bg-green-500' : 'bg-muted-foreground/30'}`} />
-                            <span className="text-foreground/85 truncate">{host.label || host.hostname}</span>
-                            {host.label && host.hostname !== host.label && (
-                              <span className="text-[10px] text-muted-foreground/40">{host.hostname}</span>
-                            )}
-                          </button>
-                        ))}
-                      </div>
-                    )}
-                  </div>
+                  )}
                 </div>
               </>,
               document.body,
@@ -375,7 +637,13 @@ const ChatInput: React.FC<ChatInputProps> = ({
                 if (!hasModelPicker) return;
                 if (!showModelPicker) {
                   const rect = modelBtnRef.current?.getBoundingClientRect();
-                  if (rect) setMenuPos({ left: rect.left, bottom: window.innerHeight - rect.top + 6 });
+                  if (rect) {
+                    // Clamp so the popover stays inside the viewport when
+                    // the chip is near the right edge of a narrow AI side
+                    // panel.
+                    const left = Math.max(8, Math.min(rect.left, window.innerWidth - MODEL_PICKER_MAX_WIDTH - 8));
+                    setMenuPos({ left, bottom: window.innerHeight - rect.top + 6 });
+                  }
                   setActiveMenu('model');
                 } else {
                   closeAllMenus();
@@ -395,8 +663,8 @@ const ChatInput: React.FC<ChatInputProps> = ({
                 <div
                   role="listbox"
                   aria-label="Select model"
-                  className="fixed z-[1000] min-w-[160px] rounded-lg border border-border/50 bg-popover shadow-lg py-1"
-                  style={{ left: menuPos.left, bottom: menuPos.bottom }}
+                  className="fixed z-[1000] w-max min-w-[160px] rounded-lg border border-border/50 bg-popover shadow-lg py-1"
+                  style={{ left: menuPos.left, bottom: menuPos.bottom, maxWidth: MODEL_PICKER_MAX_WIDTH }}
                   onMouseLeave={() => setHoveredModelId(null)}
                 >
                   {modelPresets.map(preset => {
@@ -420,12 +688,11 @@ const ChatInput: React.FC<ChatInputProps> = ({
                               closeAllMenus();
                             }
                           }}
-                          className="w-full flex items-center gap-1.5 px-3 py-1.5 text-left text-[12px] hover:bg-muted/30 transition-colors cursor-pointer whitespace-nowrap"
+                          className="w-full min-w-0 flex items-center gap-1.5 px-3 py-1.5 text-left text-[12px] hover:bg-muted/30 transition-colors cursor-pointer"
                         >
                           {isSelected ? <Check size={11} className="text-primary shrink-0" /> : <span className="w-[11px] shrink-0" />}
-                          <span className="flex-1 text-foreground/85">{preset.name}</span>
-                          {preset.description && <span className="text-[10px] text-muted-foreground/50 mr-1">{preset.description}</span>}
-                          {hasThinking && <ChevronRight size={10} className="text-muted-foreground/50" />}
+                          <span className="flex-1 min-w-0 truncate text-foreground/85">{preset.name}</span>
+                          {hasThinking && <ChevronRight size={10} className="text-muted-foreground/50 shrink-0" />}
                         </button>
                         {/* Thinking level sub-menu */}
                         {hasThinking && hoveredModelId === preset.id && (
@@ -555,6 +822,7 @@ const ChatInput: React.FC<ChatInputProps> = ({
           </div>
         </PromptInputFooter>
       </PromptInput>
+      </div>
     </div>
   );
 };

components/ai/ChatMessageList.tsx

@@ -177,13 +177,14 @@ const ChatMessageList: React.FC<ChatMessageListProps> = ({ messages, isStreaming
             return (
               <React.Fragment key={message.id}>
                 {message.toolResults?.map((tr) => (
-                  <ToolCall
-                    key={tr.toolCallId}
-                    name={toolCallNames.get(tr.toolCallId) || tr.toolCallId}
-                    args={toolCallArgs.get(tr.toolCallId)}
-                    result={tr.content}
-                    isError={tr.isError}
-                  />
+                  <div key={tr.toolCallId}>
+                    <ToolCall
+                      name={toolCallNames.get(tr.toolCallId) || tr.toolCallId}
+                      args={toolCallArgs.get(tr.toolCallId)}
+                      result={tr.content}
+                      isError={tr.isError}
+                    />
+                  </div>
                 ))}
               </React.Fragment>
             );
@@ -255,15 +256,16 @@ const ChatMessageList: React.FC<ChatMessageListProps> = ({ messages, isStreaming
                         ? 'denied' as const
                         : undefined;
                   return (
-                    <ToolCall
-                      key={tc.id}
-                      name={tc.name}
-                      args={tc.arguments}
-                      isInterrupted={!isPending}
-                      approvalStatus={approvalStatus}
-                      onApprove={() => handleApprove(tc.id)}
-                      onReject={() => handleReject(tc.id)}
-                    />
+                    <div key={tc.id}>
+                      <ToolCall
+                        name={tc.name}
+                        args={tc.arguments}
+                        isInterrupted={!isPending}
+                        approvalStatus={approvalStatus}
+                        onApprove={() => handleApprove(tc.id)}
+                        onReject={() => handleReject(tc.id)}
+                      />
+                    </div>
                   );
                 })}
 
@@ -308,34 +310,35 @@ const ChatMessageList: React.FC<ChatMessageListProps> = ({ messages, isStreaming
                 ? 'denied' as const
                 : undefined;
           return (
-            <ToolCall
-              key={tc.id}
-              name={tc.name}
-              args={tc.arguments}
-              isLoading={isStreaming && lastAssistantMessage.executionStatus === 'running' && !isPending}
-              approvalStatus={approvalStatus}
-              onApprove={() => handleApprove(tc.id)}
-              onReject={() => handleReject(tc.id)}
-            />
+            <div key={tc.id}>
+              <ToolCall
+                name={tc.name}
+                args={tc.arguments}
+                isLoading={isStreaming && lastAssistantMessage.executionStatus === 'running' && !isPending}
+                approvalStatus={approvalStatus}
+                onApprove={() => handleApprove(tc.id)}
+                onReject={() => handleReject(tc.id)}
+              />
+            </div>
           );
         })}
 
         {/* Standalone MCP/ACP approval requests (not tied to SDK tool calls) */}
         {Array.from(pendingApprovals.entries())
-          .filter((entry) => entry[0].startsWith('mcp_approval_') && (!activeSessionId || entry[1].chatSessionId === activeSessionId))
-          .map((entry) => {
-            const [id, req] = entry;
+          .filter(([id, req]) => id.startsWith('mcp_approval_') && (!activeSessionId || req.chatSessionId === activeSessionId))
+          .map(([id, req]) => {
             return (
-              <ToolCall
-                key={id}
-                name={req.toolName}
-                args={req.args}
-                isLoading={false}
-                isInterrupted={false}
-                approvalStatus={'pending'}
-                onApprove={() => handleApprove(id)}
-                onReject={() => handleReject(id)}
-              />
+              <div key={id}>
+                <ToolCall
+                  name={req.toolName}
+                  args={req.args}
+                  isLoading={false}
+                  isInterrupted={false}
+                  approvalStatus={'pending'}
+                  onApprove={() => handleApprove(id)}
+                  onReject={() => handleReject(id)}
+                />
+              </div>
             );
           })}
         {/* Streaming indicator — only when no content and no thinking yet */}

components/ai/aiPanelViewState.test.ts

@@ -0,0 +1,177 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type {
+  AIPanelView,
+  AISession,
+} from "../../infrastructure/ai/types.ts";
+import {
+  applyDraftEntrySelection,
+  applyHistorySessionSelection,
+  normalizePanelView,
+  resolveDisplayedPanelView,
+  resolveDisplayedSession,
+} from "./aiPanelViewState.ts";
+
+function createSession(id: string): AISession {
+  return {
+    id,
+    title: `Session ${id}`,
+    messages: [],
+    createdAt: 1,
+    updatedAt: 1,
+    agentId: "catty",
+    scope: {
+      type: "terminal",
+      targetId: "terminal-1",
+    },
+  };
+}
+
+test("draft view never falls back to most recent history", () => {
+  const panelView: AIPanelView = { mode: "draft" };
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.equal(resolveDisplayedSession(panelView, sessions), null);
+});
+
+test("session view returns the selected session", () => {
+  const selectedSession = createSession("session-2");
+  const panelView: AIPanelView = { mode: "session", sessionId: selectedSession.id };
+  const sessions = [createSession("session-1"), selectedSession];
+
+  assert.equal(resolveDisplayedSession(panelView, sessions), selectedSession);
+});
+
+test("missing session target resolves to null instead of history fallback", () => {
+  const panelView: AIPanelView = { mode: "session", sessionId: "missing-session" };
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.equal(resolveDisplayedSession(panelView, sessions), null);
+});
+
+test("missing session target normalizes back to draft view", () => {
+  const panelView: AIPanelView = { mode: "session", sessionId: "missing-session" };
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(normalizePanelView(panelView, sessions), { mode: "draft" });
+});
+
+test("missing explicit panel view resumes the most recent matching history when no draft exists", () => {
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, false, sessions, undefined, "workspace"),
+    { mode: "session", sessionId: "session-2" },
+  );
+});
+
+test("missing explicit panel view restores the persisted active session instead of the newest", () => {
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, false, sessions, "session-1", "workspace"),
+    { mode: "session", sessionId: "session-1" },
+  );
+});
+
+test("persisted session id that no longer exists in history falls back to newest", () => {
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, false, sessions, "deleted-session", "workspace"),
+    { mode: "session", sessionId: "session-2" },
+  );
+});
+
+test("null persisted session id falls back to newest history entry", () => {
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, false, sessions, null, "workspace"),
+    { mode: "session", sessionId: "session-2" },
+  );
+});
+
+test("terminal scope without explicit view always starts from draft even when history exists", () => {
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, false, sessions, "session-1", "terminal"),
+    { mode: "draft" },
+  );
+});
+
+test("missing explicit panel view prefers the draft when unsent input exists", () => {
+  const sessions = [createSession("session-2"), createSession("session-1")];
+
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, true, sessions),
+    { mode: "draft" },
+  );
+});
+
+test("draft state is used when there is no implicit history to resume", () => {
+  assert.deepEqual(
+    resolveDisplayedPanelView(undefined, true, []),
+    { mode: "draft" },
+  );
+});
+
+test("history selection switches to the chosen session without touching draft state", () => {
+  const calls: string[] = [];
+
+  applyHistorySessionSelection("session-2", {
+    showSessionView: (sessionId) => {
+      calls.push(`view:${sessionId}`);
+    },
+    setActiveSessionId: (sessionId) => {
+      calls.push(`active:${sessionId}`);
+    },
+    closeHistory: () => {
+      calls.push("close-history");
+    },
+  });
+
+  assert.deepEqual(calls, [
+    "view:session-2",
+    "active:session-2",
+    "close-history",
+  ]);
+});
+
+test("draft entry ensures a draft exists before switching the panel to draft mode", () => {
+  const calls: string[] = [];
+
+  applyDraftEntrySelection({
+    ensureDraft: () => {
+      calls.push("ensure-draft");
+    },
+    showDraftView: () => {
+      calls.push("show-draft");
+    },
+  });
+
+  assert.deepEqual(calls, [
+    "ensure-draft",
+    "show-draft",
+  ]);
+});
+
+test("draft entry can preserve the current session view while ensuring draft state", () => {
+  const calls: string[] = [];
+
+  applyDraftEntrySelection({
+    ensureDraft: () => {
+      calls.push("ensure-draft");
+    },
+    showDraftView: () => {
+      calls.push("show-draft");
+    },
+    preserveSessionView: true,
+  });
+
+  assert.deepEqual(calls, [
+    "ensure-draft",
+  ]);
+});

components/ai/aiPanelViewState.ts

@@ -0,0 +1,94 @@
+import type {
+  AIPanelView,
+  AISession,
+} from "../../infrastructure/ai/types.ts";
+
+const DEFAULT_PANEL_VIEW: AIPanelView = { mode: "draft" };
+
+interface HistorySessionSelectionActions {
+  showSessionView: (sessionId: string) => void;
+  setActiveSessionId: (sessionId: string) => void;
+  closeHistory?: () => void;
+}
+
+interface DraftEntrySelectionActions {
+  ensureDraft: () => void;
+  showDraftView: () => void;
+  preserveSessionView?: boolean;
+}
+
+export function resolveDisplayedPanelView(
+  panelView: AIPanelView | undefined,
+  hasDraft: boolean,
+  sessions: AISession[],
+  persistedSessionId?: string | null,
+  scopeType: "terminal" | "workspace" = "workspace",
+): AIPanelView {
+  if (panelView) {
+    return normalizePanelView(panelView, sessions);
+  }
+
+  if (hasDraft) {
+    return DEFAULT_PANEL_VIEW;
+  }
+
+  // New terminal sessions should always start from a blank draft. History is
+  // still available in the drawer, but never auto-resumed into a fresh SSH tab.
+  if (scopeType === "terminal") {
+    return DEFAULT_PANEL_VIEW;
+  }
+
+  // Honour the persisted active-session selection (survives cold mount)
+  // before falling back to the newest history entry.
+  if (persistedSessionId && sessions.some((s) => s.id === persistedSessionId)) {
+    return { mode: "session", sessionId: persistedSessionId };
+  }
+
+  if (sessions[0]) {
+    return { mode: "session", sessionId: sessions[0].id };
+  }
+
+  return DEFAULT_PANEL_VIEW;
+}
+
+export function normalizePanelView(
+  panelView: AIPanelView,
+  sessions: AISession[],
+): AIPanelView {
+  if (panelView.mode !== "session") {
+    return panelView;
+  }
+
+  return sessions.some((session) => session.id === panelView.sessionId)
+    ? panelView
+    : DEFAULT_PANEL_VIEW;
+}
+
+export function resolveDisplayedSession(
+  panelView: AIPanelView,
+  sessions: AISession[],
+): AISession | null {
+  if (panelView.mode !== "session") {
+    return null;
+  }
+
+  return sessions.find((session) => session.id === panelView.sessionId) ?? null;
+}
+
+export function applyHistorySessionSelection(
+  sessionId: string,
+  actions: HistorySessionSelectionActions,
+): void {
+  actions.showSessionView(sessionId);
+  actions.setActiveSessionId(sessionId);
+  actions.closeHistory?.();
+}
+
+export function applyDraftEntrySelection(
+  actions: DraftEntrySelectionActions,
+): void {
+  actions.ensureDraft();
+  if (!actions.preserveSessionView) {
+    actions.showDraftView();
+  }
+}

components/ai/draftSendGate.test.ts

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  endDraftSend,
+  tryBeginDraftSend,
+} from "./draftSendGate.ts";
+
+test("draft send gate allows only one in-flight draft send at a time", () => {
+  const gate = { current: false };
+
+  assert.equal(tryBeginDraftSend(gate), true);
+  assert.equal(tryBeginDraftSend(gate), false);
+
+  endDraftSend(gate);
+
+  assert.equal(tryBeginDraftSend(gate), true);
+});

components/ai/draftSendGate.ts

@@ -0,0 +1,12 @@
+export function tryBeginDraftSend(gate: { current: boolean }): boolean {
+  if (gate.current) {
+    return false;
+  }
+
+  gate.current = true;
+  return true;
+}
+
+export function endDraftSend(gate: { current: boolean }): void {
+  gate.current = false;
+}

components/ai/hooks/useAIChatStreaming.ts

@@ -14,6 +14,7 @@ import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { streamText, stepCountIs, type ModelMessage } from 'ai';
 import type {
   AIPermissionMode,
+  AIToolIntegrationMode,
   AISession,
   ChatMessage,
   ChatMessageAttachment,
@@ -120,6 +121,17 @@ export interface PanelBridge extends NetcattyBridge {
     chatSessionId?: string,
   ) => Promise<{ ok: boolean; models?: Array<{ id: string; name: string; description?: string }>; currentModelId?: string | null; error?: string }>;
   aiAcpCleanup?: (chatSessionId: string) => Promise<{ ok: boolean }>;
+  aiUserSkillsGetStatus?: () => Promise<{
+    ok: boolean;
+    skills?: Array<{
+      id: string;
+      slug: string;
+      name: string;
+      description: string;
+      status: 'ready' | 'warning';
+    }>;
+  }>;
+  aiUserSkillsBuildContext?: (prompt: string, selectedSkillSlugs?: string[]) => Promise<{ ok: boolean; context?: string; error?: string }>;
   [key: string]: ((...args: unknown[]) => unknown) | undefined;
 }
 
@@ -137,6 +149,10 @@ export interface TerminalSessionInfo {
   connected: boolean;
 }
 
+export interface DefaultTargetSessionHint extends TerminalSessionInfo {
+  source: 'scope-target' | 'only-connected-in-scope';
+}
+
 /** Typed accessor for the netcatty bridge on the window object. */
 export function getNetcattyBridge(): PanelBridge | undefined {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -150,6 +166,45 @@ function generateId(): string {
   return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
+const USER_SKILLS_CONTEXT_TIMEOUT_MS = 500;
+
+interface UserSkillsContextResult {
+  ok: boolean;
+  context?: string;
+  error?: string;
+}
+
+function buildExplicitUserSkillsFallback(selectedUserSkillSlugs?: string[]): string {
+  if (!selectedUserSkillSlugs?.length) return '';
+  return `The user explicitly selected these Netcatty user skills for this request: ${selectedUserSkillSlugs.map((slug) => `/${slug}`).join(', ')}. Honor those selections even if their expanded skill content is unavailable.`;
+}
+
+async function resolveUserSkillsContext(
+  bridge: PanelBridge | undefined,
+  prompt: string,
+  selectedUserSkillSlugs?: string[],
+): Promise<string> {
+  if (!bridge?.aiUserSkillsBuildContext) {
+    return buildExplicitUserSkillsFallback(selectedUserSkillSlugs);
+  }
+
+  const buildContextPromise: Promise<UserSkillsContextResult> = bridge
+    .aiUserSkillsBuildContext(prompt, selectedUserSkillSlugs)
+    .catch(() => ({ ok: false, context: '' }));
+
+  const hasExplicitSelections = (selectedUserSkillSlugs?.length ?? 0) > 0;
+  const result = hasExplicitSelections
+    ? await buildContextPromise
+    : await Promise.race([
+        buildContextPromise,
+        new Promise<UserSkillsContextResult>((resolve) =>
+          setTimeout(() => resolve({ ok: false, context: '' }), USER_SKILLS_CONTEXT_TIMEOUT_MS),
+        ),
+      ]);
+
+  return result.context || buildExplicitUserSkillsFallback(selectedUserSkillSlugs);
+}
+
 const sharedStreamingSessionIds = new Set<string>();
 const sharedAbortControllers = new Map<string, AbortController>();
 const streamingSubscribers = new Set<() => void>();
@@ -234,6 +289,7 @@ export interface SendToCattyContext {
   webSearchConfig?: WebSearchConfig | null;
   getExecutorContext?: () => ExecutorContext;
   autoTitleSession: (sessionId: string, text: string) => void;
+  selectedUserSkillSlugs?: string[];
 }
 
 /** Context values needed by sendToExternalAgent that change frequently. */
@@ -242,8 +298,11 @@ export interface SendToExternalContext {
   updateExternalSessionId?: (sessionId: string, externalSessionId: string | undefined) => void;
   historyMessages?: Array<{ role: 'user' | 'assistant'; content: string }>;
   terminalSessions: TerminalSessionInfo[];
+  defaultTargetSession?: DefaultTargetSessionHint;
   providers: ProviderConfig[];
   selectedAgentModel?: string;
+  toolIntegrationMode: AIToolIntegrationMode;
+  selectedUserSkillSlugs?: string[];
 }
 
 // -------------------------------------------------------------------
@@ -535,6 +594,11 @@ export function useAIChatStreaming({
     context: SendToExternalContext,
   ) => {
     const bridge = getNetcattyBridge();
+    const userSkillsContext = await resolveUserSkillsContext(
+      bridge,
+      trimmed,
+      context.selectedUserSkillSlugs,
+    );
 
     if (agentConfig.acpCommand && bridge) {
       const requestId = `acp_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
@@ -544,11 +608,6 @@ export function useAIChatStreaming({
         await bridge.aiMcpUpdateSessions(context.terminalSessions, sessionId);
       }
 
-      // Pass only the provider ID — the main process resolves and decrypts the API key itself,
-      // avoiding plaintext key transit across the IPC boundary.
-      const openaiProvider = context.providers.find(p => p.providerId === 'openai' && p.enabled && p.apiKey);
-      const agentProviderId = openaiProvider?.id;
-
       // Mutable flag: set after tool-result, cleared when new assistant msg is created
       let needsNewAssistantMsg = false;
       const maybeCreateAssistantMsg = () => {
@@ -630,17 +689,23 @@ export function useAIChatStreaming({
           onDone: () => {},
         },
         abortController.signal,
-        agentProviderId,
+        // Managed ACP agents (codex, claude) must resolve auth from their own
+        // CLI config/login state, so we deliberately pass no providerId here.
+        // See issue #705 for Codex; same reasoning for Claude.
+        undefined,
         context.selectedAgentModel,
         context.existingSessionId,
         context.historyMessages,
         attachedImages.length > 0 ? attachedImages : undefined,
+        context.toolIntegrationMode,
+        context.defaultTargetSession,
+        userSkillsContext,
       );
     } else {
       // Fallback: spawn as raw process
       await runExternalAgentTurn(
         agentConfig,
-        trimmed,
+        userSkillsContext ? `${userSkillsContext}\n\nUser request:\n${trimmed}` : trimmed,
         {
           onTextDelta: (text: string) => {
             updateLastMessage(sessionId, msg => ({ ...msg, content: msg.content + text }));
@@ -674,6 +739,11 @@ export function useAIChatStreaming({
     attachments?: ChatMessageAttachment[],
   ) => {
     const bridge = getNetcattyBridge();
+    const userSkillsContext = await resolveUserSkillsContext(
+      bridge,
+      trimmed,
+      context.selectedUserSkillSlugs,
+    );
     const getExecutorContext = context.getExecutorContext ?? (() => ({
       sessions: context.terminalSessions,
       workspaceId: context.scopeType === 'workspace' ? context.scopeTargetId : undefined,
@@ -701,6 +771,7 @@ export function useAIChatStreaming({
       })),
       permissionMode: context.globalPermissionMode,
       webSearchEnabled: isWebSearchReady(context.webSearchConfig),
+      userSkillsContext,
     });
 
     // Guard: activeProvider must exist for Catty agent path

components/ai/sessionHistoryLayout.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  SESSION_HISTORY_ROW_CLASSNAMES,
+} from "./sessionHistoryLayout.ts";
+
+test("session history row keeps metadata pinned to the end while title truncates", () => {
+  assert.match(SESSION_HISTORY_ROW_CLASSNAMES.row, /\bgrid\b/);
+  assert.ok(SESSION_HISTORY_ROW_CLASSNAMES.row.includes('grid-cols-[minmax(0,1fr)_auto]'));
+  assert.match(SESSION_HISTORY_ROW_CLASSNAMES.title, /\btruncate\b/);
+  assert.match(SESSION_HISTORY_ROW_CLASSNAMES.title, /\bmin-w-0\b/);
+  assert.match(SESSION_HISTORY_ROW_CLASSNAMES.meta, /\bjustify-self-end\b/);
+  assert.match(SESSION_HISTORY_ROW_CLASSNAMES.meta, /\bshrink-0\b/);
+});

components/ai/sessionHistoryLayout.ts

@@ -0,0 +1,7 @@
+export const SESSION_HISTORY_ROW_CLASSNAMES = {
+  row: 'w-full grid grid-cols-[minmax(0,1fr)_auto] items-center gap-3 py-2.5 border-b border-border/20 text-left transition-colors cursor-pointer group',
+  title: 'text-[13px] truncate min-w-0',
+  meta: 'flex items-center gap-2 justify-self-end shrink-0',
+  time: 'text-[12px] text-muted-foreground/50 whitespace-nowrap',
+  deleteButton: 'opacity-0 group-hover:opacity-100 p-0.5 hover:text-destructive transition-all cursor-pointer shrink-0',
+} as const;

components/ai/sessionScopeMatch.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { AISession } from "../../infrastructure/ai/types.ts";
+import { getSessionScopeMatchRank } from "./sessionScopeMatch.ts";
+
+function createSession(id: string, targetId: string, hostIds: string[]): AISession {
+  return {
+    id,
+    title: id,
+    messages: [],
+    createdAt: 1,
+    updatedAt: 1,
+    agentId: "catty",
+    scope: {
+      type: "terminal",
+      targetId,
+      hostIds,
+    },
+  };
+}
+
+test("host-matched terminal session is excluded when another active terminal already displays it", () => {
+  const session = createSession("session-1", "terminal-other", ["host-a"]);
+
+  assert.equal(
+    getSessionScopeMatchRank(
+      session,
+      "terminal",
+      "terminal-current",
+      ["host-a"],
+      new Set(["session-1"]),
+    ),
+    0,
+  );
+});
+
+test("host-matched terminal session remains resumable when no terminal is displaying it", () => {
+  const session = createSession("session-1", "terminal-closed", ["host-a"]);
+
+  assert.equal(
+    getSessionScopeMatchRank(
+      session,
+      "terminal",
+      "terminal-current",
+      ["host-a"],
+      new Set(["session-other"]),
+    ),
+    1,
+  );
+});
+
+test("ownership is tracked by session id, not scope.targetId", () => {
+  // Session was created in terminal-A but a different terminal (B) is now
+  // displaying it after the user resumed it from history. Opening a third
+  // terminal (C) should not see this session as owned, because the new
+  // ownership check is keyed on session id, not the stale targetId.
+  const session = createSession("session-1", "terminal-A", ["host-a"]);
+
+  assert.equal(
+    getSessionScopeMatchRank(
+      session,
+      "terminal",
+      "terminal-C",
+      ["host-a"],
+      // terminal-B is displaying session-1; pass session-1 as an
+      // active-id so C sees it as in-use
+      new Set(["session-1"]),
+    ),
+    0,
+  );
+});
+
+test("session targeting the current scope is an exact match (rank 2)", () => {
+  const session = createSession("session-1", "terminal-current", ["host-a"]);
+
+  assert.equal(
+    getSessionScopeMatchRank(
+      session,
+      "terminal",
+      "terminal-current",
+      ["host-a"],
+      new Set(),
+    ),
+    2,
+  );
+});
+
+test("scope type mismatch returns 0 regardless of target or hosts", () => {
+  const session = createSession("session-1", "terminal-current", ["host-a"]);
+
+  assert.equal(
+    getSessionScopeMatchRank(
+      session,
+      "workspace",
+      "terminal-current",
+      ["host-a"],
+    ),
+    0,
+  );
+});

components/ai/sessionScopeMatch.ts

@@ -0,0 +1,28 @@
+import type { AISession } from "../../infrastructure/ai/types";
+
+export function getSessionScopeMatchRank(
+  session: AISession,
+  scopeType: "terminal" | "workspace",
+  scopeTargetId?: string,
+  scopeHostIds?: string[],
+  /**
+   * Session ids currently displayed by other terminal scopes. Tracked by
+   * session id rather than `scope.targetId` so that a host-matched session
+   * resumed from a different terminal is still recognised as in-use and
+   * not offered (or cleaned) as if it were orphaned.
+   */
+  activeTerminalSessionIds?: Set<string>,
+): number {
+  if (session.scope.type !== scopeType) return 0;
+  if (session.scope.targetId === scopeTargetId) return 2;
+
+  if (scopeType !== "terminal" || !scopeHostIds?.length || !session.scope.hostIds?.length) {
+    return 0;
+  }
+
+  if (activeTerminalSessionIds?.has(session.id)) {
+    return 0;
+  }
+
+  return session.scope.hostIds.some((hostId) => scopeHostIds.includes(hostId)) ? 1 : 0;
+}

components/ai/userSkillsState.test.ts

@@ -0,0 +1,80 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  getNextSelectedUserSkillSlugsMap,
+  getReadyUserSkillOptions,
+  pruneSelectedUserSkillSlugsMap,
+} from "./userSkillsState.ts";
+
+test("getReadyUserSkillOptions returns only ready skills and clears invalid payloads", () => {
+  assert.deepEqual(getReadyUserSkillOptions(null), []);
+  assert.deepEqual(getReadyUserSkillOptions({ ok: false }), []);
+  assert.deepEqual(
+    getReadyUserSkillOptions({
+      ok: true,
+      skills: [
+        {
+          id: "alpha",
+          slug: "alpha",
+          name: "Alpha",
+          description: "Alpha helper",
+          status: "ready",
+        },
+        {
+          id: "beta",
+          slug: "beta",
+          name: "Beta",
+          description: "Beta helper",
+          status: "warning",
+        },
+      ],
+    }),
+    [
+      {
+        id: "alpha",
+        slug: "alpha",
+        name: "Alpha",
+        description: "Alpha helper",
+      },
+    ],
+  );
+});
+
+test("pruneSelectedUserSkillSlugsMap removes stale slugs and empty scopes", () => {
+  assert.deepEqual(
+    pruneSelectedUserSkillSlugsMap(
+      {
+        "terminal:1": ["alpha", "missing"],
+        "workspace:1": ["missing"],
+      },
+      [
+        {
+          id: "alpha",
+          slug: "alpha",
+          name: "Alpha",
+          description: "Alpha helper",
+        },
+      ],
+    ),
+    {
+      "terminal:1": ["alpha"],
+    },
+  );
+});
+
+test("getNextSelectedUserSkillSlugsMap preserves selections when refresh fails", () => {
+  const selected = {
+    "terminal:1": ["alpha", "missing"],
+    "workspace:1": ["beta"],
+  };
+
+  assert.equal(
+    getNextSelectedUserSkillSlugsMap(selected, null),
+    selected,
+  );
+  assert.equal(
+    getNextSelectedUserSkillSlugsMap(selected, { ok: false }),
+    selected,
+  );
+});

components/ai/userSkillsState.ts

@@ -0,0 +1,73 @@
+export interface UserSkillStatusItemLike {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  status: "ready" | "warning";
+}
+
+export interface UserSkillsStatusLike {
+  ok: boolean;
+  skills?: UserSkillStatusItemLike[];
+}
+
+export interface UserSkillOption {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+}
+
+export function getReadyUserSkillOptions(
+  status: UserSkillsStatusLike | null | undefined,
+): UserSkillOption[] {
+  if (!status?.ok || !Array.isArray(status.skills)) return [];
+
+  return status.skills
+    .filter((skill) => skill.status === "ready" && typeof skill.slug === "string" && skill.slug.length > 0)
+    .map((skill) => ({
+      id: skill.id,
+      slug: skill.slug,
+      name: skill.name,
+      description: skill.description,
+    }));
+}
+
+export function pruneSelectedUserSkillSlugsMap(
+  selectedByScope: Record<string, string[]>,
+  options: UserSkillOption[],
+): Record<string, string[]> {
+  const validSlugs = new Set(options.map((option) => option.slug));
+  let changed = false;
+  const nextEntries: Array<[string, string[]]> = [];
+
+  for (const [scopeKey, slugs] of Object.entries(selectedByScope)) {
+    const filteredSlugs = slugs.filter((slug) => validSlugs.has(slug));
+    if (filteredSlugs.length !== slugs.length) changed = true;
+    if (filteredSlugs.length > 0) {
+      nextEntries.push([scopeKey, filteredSlugs]);
+    } else if (slugs.length > 0) {
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    return selectedByScope;
+  }
+
+  return Object.fromEntries(nextEntries);
+}
+
+export function getNextSelectedUserSkillSlugsMap(
+  selectedByScope: Record<string, string[]>,
+  status: UserSkillsStatusLike | null | undefined,
+): Record<string, string[]> {
+  if (!status?.ok || !Array.isArray(status.skills)) {
+    return selectedByScope;
+  }
+
+  return pruneSelectedUserSkillSlugsMap(
+    selectedByScope,
+    getReadyUserSkillOptions(status),
+  );
+}

components/host-details/ChainPanel.tsx

@@ -7,7 +7,7 @@ import React, { useMemo, useState } from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { Host } from '../../types';
 import { DistroAvatar } from '../DistroAvatar';
-import { AsidePanel } from '../ui/aside-panel';
+import { AsidePanel, type AsidePanelLayout } from '../ui/aside-panel';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
 import { Input } from '../ui/input';
@@ -24,6 +24,7 @@ export interface ChainPanelProps {
     onClearChain: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const ChainPanel: React.FC<ChainPanelProps> = ({
@@ -37,6 +38,7 @@ export const ChainPanel: React.FC<ChainPanelProps> = ({
     onClearChain,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     const [searchQuery, setSearchQuery] = useState('');
@@ -54,6 +56,7 @@ export const ChainPanel: React.FC<ChainPanelProps> = ({
             title={t('hostDetails.chain.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onBack}>
                     {t('common.save')}

components/host-details/CreateGroupPanel.tsx

@@ -5,7 +5,7 @@
 import { FolderPlus,HelpCircle,Plus } from 'lucide-react';
 import React from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
-import { AsidePanel,AsidePanelContent } from '../ui/aside-panel';
+import { AsidePanel,AsidePanelContent,type AsidePanelLayout } from '../ui/aside-panel';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
 import { Input } from '../ui/input';
@@ -42,6 +42,7 @@ export interface CreateGroupPanelProps {
     onSave: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const CreateGroupPanel: React.FC<CreateGroupPanelProps> = ({
@@ -53,6 +54,7 @@ export const CreateGroupPanel: React.FC<CreateGroupPanelProps> = ({
     onSave,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     return (
@@ -62,6 +64,7 @@ export const CreateGroupPanel: React.FC<CreateGroupPanelProps> = ({
             title={t('hostDetails.group.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onSave} disabled={!newGroupName.trim()}>
                     {t('common.save')}

components/host-details/EnvVarsPanel.tsx

@@ -6,7 +6,7 @@ import { Plus,X } from 'lucide-react';
 import React from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { EnvVar } from '../../types';
-import { AsidePanel,AsidePanelContent } from '../ui/aside-panel';
+import { AsidePanel,AsidePanelContent,type AsidePanelLayout } from '../ui/aside-panel';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
 import { Input } from '../ui/input';
@@ -25,6 +25,7 @@ export interface EnvVarsPanelProps {
     onSave: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const EnvVarsPanel: React.FC<EnvVarsPanelProps> = ({
@@ -41,6 +42,7 @@ export const EnvVarsPanel: React.FC<EnvVarsPanelProps> = ({
     onSave,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     return (
@@ -50,6 +52,7 @@ export const EnvVarsPanel: React.FC<EnvVarsPanelProps> = ({
             title={t('hostDetails.envVars.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onSave}>
                     {t('common.save')}

components/host-details/ProxyPanel.tsx

@@ -7,7 +7,7 @@ import React from 'react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { cn } from '../../lib/utils';
 import { ProxyConfig } from '../../types';
-import { AsidePanel,AsidePanelContent } from '../ui/aside-panel';
+import { AsidePanel,AsidePanelContent,type AsidePanelLayout } from '../ui/aside-panel';
 import { Badge } from '../ui/badge';
 import { Button } from '../ui/button';
 import { Card } from '../ui/card';
@@ -19,6 +19,7 @@ export interface ProxyPanelProps {
     onClearProxy: () => void;
     onBack: () => void;
     onCancel: () => void;
+    layout?: AsidePanelLayout;
 }
 
 export const ProxyPanel: React.FC<ProxyPanelProps> = ({
@@ -27,6 +28,7 @@ export const ProxyPanel: React.FC<ProxyPanelProps> = ({
     onClearProxy,
     onBack,
     onCancel,
+    layout = 'overlay',
 }) => {
     const { t } = useI18n();
     return (
@@ -36,6 +38,7 @@ export const ProxyPanel: React.FC<ProxyPanelProps> = ({
             title={t('hostDetails.proxyPanel.title')}
             showBackButton={true}
             onBack={onBack}
+            layout={layout}
             actions={
                 <Button size="sm" onClick={onBack} disabled={!proxyConfig?.host}>
                     {t('common.save')}

components/settings/tabs/SettingsAITab.tsx

@@ -7,11 +7,12 @@
  *   - CodexConnectionCard, ClaudeCodeCard
  *   - SafetySettings
  */
-import { Bot, Globe } from "lucide-react";
+import { AlertTriangle, Bot, FolderOpen, Globe, Link, Package, RefreshCcw } from "lucide-react";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type {
   AIPermissionMode,
   AIProviderId,
+  AIToolIntegrationMode,
   ExternalAgentConfig,
   ProviderConfig,
   WebSearchConfig,
@@ -24,6 +25,7 @@ import {
 import { PROVIDER_PRESETS } from "../../../infrastructure/ai/types";
 import { useI18n } from "../../../application/i18n/I18nProvider";
 import { TabsContent } from "../../ui/tabs";
+import { Button } from "../../ui/button";
 import { Select, SettingRow } from "../settings-ui";
 import { AgentIconBadge } from "../../ai/AgentIconBadge";
 
@@ -31,6 +33,7 @@ import type {
   AgentPathInfo,
   CodexIntegrationStatus,
   CodexLoginSession,
+  UserSkillsStatusResult,
 } from "./ai/types";
 import {
   AGENT_DEFAULTS,
@@ -61,6 +64,8 @@ interface SettingsAITabProps {
   setActiveModelId: (id: string) => void;
   globalPermissionMode: AIPermissionMode;
   setGlobalPermissionMode: (mode: AIPermissionMode) => void;
+  toolIntegrationMode: AIToolIntegrationMode;
+  setToolIntegrationMode: (mode: AIToolIntegrationMode) => void;
   externalAgents: ExternalAgentConfig[];
   setExternalAgents: (value: ExternalAgentConfig[] | ((prev: ExternalAgentConfig[]) => ExternalAgentConfig[])) => void;
   defaultAgentId: string;
@@ -138,6 +143,8 @@ const SettingsAITab: React.FC<SettingsAITabProps> = ({
   setActiveModelId,
   globalPermissionMode,
   setGlobalPermissionMode,
+  toolIntegrationMode,
+  setToolIntegrationMode,
   externalAgents,
   setExternalAgents,
   defaultAgentId,
@@ -182,6 +189,8 @@ const SettingsAITab: React.FC<SettingsAITabProps> = ({
   const [copilotPathInfo, setCopilotPathInfo] = useState<AgentPathInfo | null>(null);
   const [copilotCustomPath, setCopilotCustomPath] = useState("");
   const [isResolvingCopilot, setIsResolvingCopilot] = useState(false);
+  const [userSkillsStatus, setUserSkillsStatus] = useState<UserSkillsStatusResult | null>(null);
+  const [isLoadingUserSkills, setIsLoadingUserSkills] = useState(false);
 
   // Ref to read current defaultAgentId without adding it as a dependency.
   const defaultAgentIdRef = useRef(defaultAgentId);
@@ -299,18 +308,14 @@ const SettingsAITab: React.FC<SettingsAITabProps> = ({
       .map((a) => ({ value: a.id, label: a.name, icon: <AgentIconBadge agent={a} size="xs" variant="plain" /> })),
   ], [externalAgents, t]);
 
-  const hasOpenAiProviderKey = providers.some(
-    (provider) => provider.providerId === "openai" && provider.enabled && !!provider.apiKey,
-  );
-
-  const refreshCodexIntegration = useCallback(async () => {
+  const refreshCodexIntegration = useCallback(async (opts?: { refreshShellEnv?: boolean }) => {
     const bridge = getBridge();
     if (!bridge?.aiCodexGetIntegration) return;
 
     setIsCodexLoading(true);
     setCodexError(null);
     try {
-      const integration = await bridge.aiCodexGetIntegration();
+      const integration = await bridge.aiCodexGetIntegration(opts);
       setCodexIntegration(integration);
     } catch (err) {
       setCodexError(normalizeCodexBridgeError(err));
@@ -420,6 +425,54 @@ const SettingsAITab: React.FC<SettingsAITabProps> = ({
     }
   }, [refreshCodexIntegration]);
 
+  const refreshUserSkillsStatus = useCallback(async () => {
+    const bridge = getBridge();
+    if (!bridge?.aiUserSkillsGetStatus) {
+      setUserSkillsStatus({
+        ok: false,
+        error: t('ai.userSkills.unavailable'),
+      });
+      return;
+    }
+
+    setIsLoadingUserSkills(true);
+    try {
+      const result = await bridge.aiUserSkillsGetStatus();
+      setUserSkillsStatus(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setUserSkillsStatus({ ok: false, error: message });
+    } finally {
+      setIsLoadingUserSkills(false);
+    }
+  }, [t]);
+
+  useEffect(() => {
+    let cancelled = false;
+    void refreshUserSkillsStatus().then(() => {
+      if (cancelled) return;
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [refreshUserSkillsStatus]);
+
+  const handleOpenUserSkillsFolder = useCallback(async () => {
+    const bridge = getBridge();
+    if (!bridge?.aiUserSkillsOpenFolder) return;
+
+    setIsLoadingUserSkills(true);
+    try {
+      const result = await bridge.aiUserSkillsOpenFolder();
+      setUserSkillsStatus(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setUserSkillsStatus({ ok: false, error: message });
+    } finally {
+      setIsLoadingUserSkills(false);
+    }
+  }, []);
+
   return (
     <TabsContent
       value="ai"
@@ -519,9 +572,8 @@ const SettingsAITab: React.FC<SettingsAITabProps> = ({
               integration={codexIntegration}
               loginSession={codexLoginSession}
               isLoading={isCodexLoading}
-              hasOpenAiProviderKey={hasOpenAiProviderKey}
               error={codexError}
-              onRefresh={() => void refreshCodexIntegration()}
+              onRefresh={() => void refreshCodexIntegration({ refreshShellEnv: true })}
               onConnect={() => void handleStartCodexLogin()}
               onCancel={() => void handleCancelCodexLogin()}
               onOpenUrl={handleOpenCodexLoginUrl}
@@ -585,6 +637,130 @@ const SettingsAITab: React.FC<SettingsAITabProps> = ({
             </div>
           )}
 
+          <div className="space-y-4">
+            <div className="flex items-center gap-2">
+              <Link size={18} className="text-muted-foreground" />
+              <h3 className="text-base font-medium">{t('ai.toolAccess.title')}</h3>
+            </div>
+
+            <div className="bg-muted/30 rounded-lg p-4">
+              <SettingRow
+                label={t('ai.toolAccess.mode')}
+                description={t('ai.toolAccess.description')}
+              >
+                <Select
+                  value={toolIntegrationMode}
+                  options={[
+                    { value: 'mcp', label: t('ai.toolAccess.mode.mcp') },
+                    { value: 'skills', label: t('ai.toolAccess.mode.skills') },
+                  ]}
+                  onChange={(value) => setToolIntegrationMode(value as AIToolIntegrationMode)}
+                  className="w-48"
+                />
+              </SettingRow>
+            </div>
+          </div>
+
+          <div className="space-y-4">
+            <div className="flex items-center justify-between gap-4">
+              <div className="flex items-center gap-2">
+                <Package size={18} className="text-muted-foreground" />
+                <h3 className="text-base font-medium">{t('ai.userSkills.title')}</h3>
+              </div>
+              <div className="flex items-center gap-2">
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => void refreshUserSkillsStatus()}
+                  disabled={isLoadingUserSkills}
+                >
+                  <RefreshCcw size={14} className="mr-2" />
+                  {t('ai.userSkills.reload')}
+                </Button>
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => void handleOpenUserSkillsFolder()}
+                  disabled={isLoadingUserSkills}
+                >
+                  <FolderOpen size={14} className="mr-2" />
+                  {t('ai.userSkills.openFolder')}
+                </Button>
+              </div>
+            </div>
+
+            <div className="rounded-lg bg-muted/30 p-4 space-y-4">
+              <div className="space-y-1">
+                <p className="text-sm text-muted-foreground">
+                  {t('ai.userSkills.description')}
+                </p>
+                {userSkillsStatus?.directoryPath ? (
+                  <p className="text-xs text-muted-foreground">
+                    {t('ai.userSkills.location')}:{" "}
+                    <span className="font-mono">{userSkillsStatus.directoryPath}</span>
+                  </p>
+                ) : null}
+              </div>
+
+              <div className="text-sm text-muted-foreground">
+                {isLoadingUserSkills
+                  ? t('ai.userSkills.loading')
+                  : userSkillsStatus?.ok
+                    ? t('ai.userSkills.summary', {
+                        ready: String(userSkillsStatus.readyCount ?? 0),
+                        warnings: String(userSkillsStatus.warningCount ?? 0),
+                      })
+                    : userSkillsStatus?.error || t('ai.userSkills.unavailable')}
+              </div>
+
+              {userSkillsStatus?.ok && userSkillsStatus.skills && userSkillsStatus.skills.length > 0 ? (
+                <div className="space-y-3">
+                  {userSkillsStatus.skills.map((skill) => (
+                    <div
+                      key={skill.id}
+                      className="rounded-md border border-border/60 bg-background/70 p-3"
+                    >
+                      <div className="flex items-start justify-between gap-3">
+                        <div className="min-w-0 space-y-1">
+                          <div className="font-medium">{skill.name}</div>
+                          <div className="text-sm text-muted-foreground">{skill.description}</div>
+                          <div className="text-xs text-muted-foreground font-mono break-all">
+                            {skill.directoryName}
+                          </div>
+                        </div>
+                        <span
+                          className={
+                            skill.status === "ready"
+                              ? "rounded-full bg-emerald-500/10 px-2 py-1 text-xs font-medium text-emerald-600"
+                              : "rounded-full bg-amber-500/10 px-2 py-1 text-xs font-medium text-amber-600"
+                          }
+                        >
+                          {skill.status === "ready"
+                            ? t('ai.userSkills.status.ready')
+                            : t('ai.userSkills.status.warning')}
+                        </span>
+                      </div>
+                      {skill.warnings.length > 0 ? (
+                        <div className="mt-3 space-y-1 text-sm text-amber-700">
+                          {skill.warnings.map((warning, index) => (
+                            <div key={`${skill.id}-${index}`} className="flex items-start gap-2">
+                              <AlertTriangle size={14} className="mt-0.5 shrink-0" />
+                              <span>{warning}</span>
+                            </div>
+                          ))}
+                        </div>
+                      ) : null}
+                    </div>
+                  ))}
+                </div>
+              ) : userSkillsStatus?.ok ? (
+                <div className="text-sm text-muted-foreground">
+                  {t('ai.userSkills.empty')}
+                </div>
+              ) : null}
+            </div>
+          </div>
+
           {/* -- Web Search Section -- */}
           <WebSearchSettings
             webSearchConfig={webSearchConfig}

components/settings/tabs/SettingsAppearanceTab.tsx

@@ -7,8 +7,6 @@ import { SUPPORTED_UI_LOCALES } from "../../../infrastructure/config/i18n";
 import { cn } from "../../../lib/utils";
 import { SectionHeader, SettingsTabContent, SettingRow, Toggle, Select } from "../settings-ui";
 import { FontSelect } from "../FontSelect";
-import { STORAGE_KEY_SHOW_RECENT_HOSTS } from "../../../infrastructure/config/storageKeys";
-import { useStoredBoolean } from "../../../application/state/useStoredBoolean";
 
 export default function SettingsAppearanceTab(props: {
   theme: "dark" | "light" | "system";
@@ -27,6 +25,12 @@ export default function SettingsAppearanceTab(props: {
   setUiLanguage: (language: string) => void;
   customCSS: string;
   setCustomCSS: (css: string) => void;
+  showRecentHosts: boolean;
+  setShowRecentHosts: (enabled: boolean) => void;
+  showOnlyUngroupedHostsInRoot: boolean;
+  setShowOnlyUngroupedHostsInRoot: (enabled: boolean) => void;
+  showSftpTab: boolean;
+  setShowSftpTab: (enabled: boolean) => void;
 }) {
   const { t } = useI18n();
   const availableUIFonts = useAvailableUIFonts();
@@ -47,13 +51,14 @@ export default function SettingsAppearanceTab(props: {
     setUiLanguage,
     customCSS,
     setCustomCSS,
+    showRecentHosts,
+    setShowRecentHosts,
+    showOnlyUngroupedHostsInRoot,
+    setShowOnlyUngroupedHostsInRoot,
+    showSftpTab,
+    setShowSftpTab,
   } = props;
 
-  const [showRecentHosts, setShowRecentHosts] = useStoredBoolean(
-    STORAGE_KEY_SHOW_RECENT_HOSTS,
-    true,
-  );
-
   const getHslStyle = useCallback((hsl: string) => ({ backgroundColor: `hsl(${hsl})` }), []);
 
   const hexToHsl = useCallback((hex: string) => {
@@ -269,6 +274,21 @@ export default function SettingsAppearanceTab(props: {
         >
           <Toggle checked={showRecentHosts} onChange={setShowRecentHosts} />
         </SettingRow>
+        <SettingRow
+          label={t('settings.vault.showOnlyUngroupedHostsInRoot')}
+          description={t('settings.vault.showOnlyUngroupedHostsInRootDesc')}
+        >
+          <Toggle
+            checked={showOnlyUngroupedHostsInRoot}
+            onChange={setShowOnlyUngroupedHostsInRoot}
+          />
+        </SettingRow>
+        <SettingRow
+          label={t('settings.vault.showSftpTab')}
+          description={t('settings.vault.showSftpTabDesc')}
+        >
+          <Toggle checked={showSftpTab} onChange={setShowSftpTab} />
+        </SettingRow>
       </div>
 
       <SectionHeader title={t("settings.appearance.customCss")} />

components/settings/tabs/SettingsSyncTab.tsx

@@ -2,7 +2,9 @@ import React, { useCallback } from "react";
 import type { PortForwardingRule } from "../../../domain/models";
 import type { SyncPayload } from "../../../domain/sync";
 import { buildSyncPayload, applySyncPayload } from "../../../application/syncPayload";
+import { applyProtectedSyncPayload } from "../../../application/localVaultBackups";
 import type { SyncableVaultData } from "../../../application/syncPayload";
+import { useI18n } from "../../../application/i18n/I18nProvider";
 import { STORAGE_KEY_PORT_FORWARDING } from "../../../infrastructure/config/storageKeys";
 import { localStorageAdapter } from "../../../infrastructure/persistence/localStorageAdapter";
 import { getEffectiveKnownHosts } from "../../../infrastructure/syncHelpers";
@@ -25,6 +27,7 @@ export default function SettingsSyncTab(props: {
     clearVaultData,
     onSettingsApplied,
   } = props;
+  const { t } = useI18n();
 
   const onBuildPayload = useCallback((): SyncPayload => {
     // If hook state is empty but localStorage has data, the async store
@@ -54,14 +57,19 @@ export default function SettingsSyncTab(props: {
   }, [vault, portForwardingRules]);
 
   const onApplyPayload = useCallback(
-    (payload: SyncPayload) => {
-      applySyncPayload(payload, {
-        importVaultData: importDataFromString,
-        importPortForwardingRules,
-        onSettingsApplied,
-      });
-    },
-    [importDataFromString, importPortForwardingRules, onSettingsApplied],
+    (payload: SyncPayload) =>
+      applyProtectedSyncPayload({
+        buildPreApplyPayload: onBuildPayload,
+        applyPayload: () =>
+          applySyncPayload(payload, {
+            importVaultData: importDataFromString,
+            importPortForwardingRules,
+            onSettingsApplied,
+          }),
+        translateProtectiveBackupFailure: (message) =>
+          t("cloudSync.localBackups.protectiveBackupFailed", { message }),
+      }),
+    [importDataFromString, importPortForwardingRules, onBuildPayload, onSettingsApplied, t],
   );
 
   const clearAllLocalData = useCallback(() => {

components/settings/tabs/SettingsTerminalTab.tsx

@@ -263,6 +263,8 @@ const ThemePreviewButton: React.FC<{
 export default function SettingsTerminalTab(props: {
   terminalThemeId: string;
   setTerminalThemeId: (id: string) => void;
+  followAppTerminalTheme: boolean;
+  setFollowAppTerminalTheme: (value: boolean) => void;
   terminalFontFamilyId: string;
   setTerminalFontFamilyId: (id: string) => void;
   terminalFontSize: number;
@@ -279,6 +281,8 @@ export default function SettingsTerminalTab(props: {
   const {
     terminalThemeId,
     setTerminalThemeId,
+    followAppTerminalTheme,
+    setFollowAppTerminalTheme,
     terminalFontFamilyId,
     setTerminalFontFamilyId,
     terminalFontSize,
@@ -491,11 +495,24 @@ export default function SettingsTerminalTab(props: {
   return (
     <SettingsTabContent value="terminal">
       <SectionHeader title={t("settings.terminal.section.theme")} />
-      <ThemePreviewButton
-        theme={currentTheme}
-        onClick={() => setThemeModalOpen(true)}
-        buttonLabel={t("settings.terminal.theme.selectButton")}
-      />
+      <div className="rounded-lg border bg-card px-4">
+        <SettingRow
+          label={t("settings.terminal.theme.followApp")}
+          description={t("settings.terminal.theme.followApp.desc")}
+        >
+          <Toggle
+            checked={followAppTerminalTheme}
+            onChange={setFollowAppTerminalTheme}
+          />
+        </SettingRow>
+      </div>
+      {!followAppTerminalTheme && (
+        <ThemePreviewButton
+          theme={currentTheme}
+          onClick={() => setThemeModalOpen(true)}
+          buttonLabel={t("settings.terminal.theme.selectButton")}
+        />
+      )}
 
       <ThemeSelectModal
         open={themeModalOpen}

components/settings/tabs/ai/CodexConnectionCard.tsx

@@ -15,7 +15,6 @@ export const CodexConnectionCard: React.FC<{
   integration: CodexIntegrationStatus | null;
   loginSession: CodexLoginSession | null;
   isLoading: boolean;
-  hasOpenAiProviderKey: boolean;
   error: string | null;
   onRefresh: () => void;
   onConnect: () => void;
@@ -31,7 +30,6 @@ export const CodexConnectionCard: React.FC<{
   integration,
   loginSession,
   isLoading,
-  hasOpenAiProviderKey,
   error,
   onRefresh,
   onConnect,
@@ -42,6 +40,14 @@ export const CodexConnectionCard: React.FC<{
   const { t } = useI18n();
   const found = pathInfo?.available;
 
+  const customConfigIncomplete = Boolean(
+    integration?.state === "connected_custom_config"
+    && integration.customConfig
+    && integration.customConfig.envKey
+    && !integration.customConfig.envKeyPresent
+    && !integration.customConfig.hasHardcodedApiKey,
+  );
+
   const status = isResolvingPath
     ? t('ai.codex.detecting')
     : !found
@@ -52,9 +58,13 @@ export const CodexConnectionCard: React.FC<{
           ? t('ai.codex.connectedChatGPT')
           : integration?.state === "connected_api_key"
             ? t('ai.codex.connectedApiKey')
-            : integration?.state === "not_logged_in"
-              ? t('ai.codex.notConnected')
-              : t('ai.codex.statusUnknown');
+            : integration?.state === "connected_custom_config"
+              ? customConfigIncomplete
+                ? t('ai.codex.customConfigIncomplete')
+                : t('ai.codex.connectedCustomConfig')
+              : integration?.state === "not_logged_in"
+                ? t('ai.codex.notConnected')
+                : t('ai.codex.statusUnknown');
 
   const statusClassName = isResolvingPath
     ? "text-muted-foreground"
@@ -62,9 +72,11 @@ export const CodexConnectionCard: React.FC<{
       ? "text-amber-500"
       : loginSession?.state === "running"
         ? "text-amber-500"
-        : integration?.isConnected
-          ? "text-emerald-500"
-          : "text-muted-foreground";
+        : customConfigIncomplete
+          ? "text-amber-500"
+          : integration?.isConnected
+            ? "text-emerald-500"
+            : "text-muted-foreground";
 
   const outputText = loginSession?.error
     ? loginSession.error
@@ -139,6 +151,9 @@ export const CodexConnectionCard: React.FC<{
                   {t('common.cancel')}
                 </Button>
               </>
+            ) : integration?.state === "connected_custom_config" ? (
+              // Nothing to log out of; config.toml is user-owned state.
+              null
             ) : integration?.isConnected ? (
               <Button variant="outline" size="sm" onClick={onLogout}>
                 <LogOut size={14} className="mr-1.5" />
@@ -157,10 +172,23 @@ export const CodexConnectionCard: React.FC<{
             </Button>
           </div>
 
-          {hasOpenAiProviderKey && (
-            <p className="text-xs text-emerald-500">
-              {t('ai.codex.apiKeyHint')}
-            </p>
+          {integration?.state === "connected_custom_config" && integration.customConfig && (
+            <>
+              <p className="text-xs text-emerald-500">
+                {t('ai.codex.customConfigHint').replace(
+                  '{provider}',
+                  integration.customConfig.displayName || integration.customConfig.providerName,
+                )}
+              </p>
+              {integration.customConfig.envKey && !integration.customConfig.envKeyPresent && !integration.customConfig.hasHardcodedApiKey && (
+                <p className="text-xs text-amber-500">
+                  {t('ai.codex.customConfigMissingEnvKey').replace(
+                    '{envKey}',
+                    integration.customConfig.envKey,
+                  )}
+                </p>
+              )}
+            </>
           )}
         </>
       )}

components/settings/tabs/ai/types.ts

@@ -10,14 +10,27 @@ import type {
 export type CodexIntegrationState =
   | "connected_chatgpt"
   | "connected_api_key"
+  | "connected_custom_config"
   | "not_logged_in"
   | "unknown";
 
+export interface CodexCustomProviderConfig {
+  providerName: string;
+  displayName: string;
+  baseUrl: string | null;
+  envKey: string | null;
+  envKeyPresent: boolean;
+  hasHardcodedApiKey: boolean;
+  model: string | null;
+  authHash: string | null;
+}
+
 export interface CodexIntegrationStatus {
   state: CodexIntegrationState;
   isConnected: boolean;
   rawOutput: string;
   exitCode: number | null;
+  customConfig?: CodexCustomProviderConfig | null;
 }
 
 export type CodexLoginState = "running" | "success" | "error" | "cancelled";
@@ -37,6 +50,28 @@ export interface AgentPathInfo {
   available: boolean;
 }
 
+export interface UserSkillStatusItem {
+  id: string;
+  slug: string;
+  directoryName: string;
+  directoryPath: string;
+  skillPath: string;
+  name: string;
+  description: string;
+  status: "ready" | "warning";
+  warnings: string[];
+}
+
+export interface UserSkillsStatusResult {
+  ok: boolean;
+  directoryPath?: string;
+  readyCount?: number;
+  warningCount?: number;
+  skills?: UserSkillStatusItem[];
+  warnings?: string[];
+  error?: string;
+}
+
 export interface ProviderFormState {
   name: string;
   apiKey: string;
@@ -57,12 +92,14 @@ export interface FetchBridge {
 }
 
 export interface NetcattyAiBridge {
-  aiCodexGetIntegration?: () => Promise<CodexIntegrationStatus>;
+  aiCodexGetIntegration?: (options?: { refreshShellEnv?: boolean }) => Promise<CodexIntegrationStatus>;
   aiCodexStartLogin?: () => Promise<{ ok: boolean; session?: CodexLoginSession; error?: string }>;
   aiCodexGetLoginSession?: (sessionId: string) => Promise<{ ok: boolean; session?: CodexLoginSession; error?: string }>;
   aiCodexCancelLogin?: (sessionId: string) => Promise<{ ok: boolean; found?: boolean; session?: CodexLoginSession; error?: string }>;
   aiCodexLogout?: () => Promise<{ ok: boolean; state?: CodexIntegrationState; isConnected?: boolean; rawOutput?: string; logoutOutput?: string; error?: string }>;
   aiResolveCli?: (params: { command: string; customPath?: string }) => Promise<AgentPathInfo>;
+  aiUserSkillsGetStatus?: () => Promise<UserSkillsStatusResult>;
+  aiUserSkillsOpenFolder?: () => Promise<UserSkillsStatusResult>;
   openExternal?: (url: string) => Promise<void>;
 }
 

components/sftp/SftpTabBar.tsx

@@ -318,6 +318,8 @@ const SftpTabBarInner: React.FC<SftpTabBarProps> = ({
               <div
                 key={tab.id}
                 data-tab-id={tab.id}
+                data-tab-type="sftp"
+                data-state={isActive ? 'active' : 'inactive'}
                 onClick={(e) => handleSelectTabClick(e, tab.id)}
                 draggable
                 onDragStart={(e) => handleTabDragStart(e, tab.id)}
@@ -325,7 +327,7 @@ const SftpTabBarInner: React.FC<SftpTabBarProps> = ({
                 onDragOver={(e) => handleTabDragOver(e, tab.id)}
                 onDrop={(e) => handleTabDrop(e, tab.id)}
                 className={cn(
-                  "relative px-3 min-w-[100px] max-w-[180px] text-xs font-medium cursor-pointer flex items-center justify-between gap-2 flex-shrink-0 border-r border-border/40",
+                  "netcatty-tab relative px-3 min-w-[100px] max-w-[180px] text-xs font-medium cursor-pointer flex items-center justify-between gap-2 flex-shrink-0 border-r border-border/40",
                   "transition-[color,opacity,transform] duration-100 ease-out",
                   isActive
                     ? "text-foreground border-b-2"

components/sftp/hooks/useSftpViewPaneCallbacks.ts

@@ -46,6 +46,8 @@ interface UseSftpViewPaneCallbacksParams {
   ) => Promise<{ transferId: string; totalBytes?: number; error?: string }>;
   getSftpIdForConnection?: (connectionId: string) => string | undefined;
   listLocalFiles: (path: string) => Promise<RemoteFile[]>;
+  mkdirLocal?: (path: string) => Promise<void>;
+  deleteLocalFile?: (path: string) => Promise<void>;
 }
 
 export const useSftpViewPaneCallbacks = ({

components/terminal/TerminalContextMenu.tsx

@@ -31,6 +31,7 @@ export interface TerminalContextMenuProps {
   isAlternateScreen?: boolean;
   onCopy?: () => void;
   onPaste?: () => void;
+  onPasteSelection?: () => void;
   onSelectAll?: () => void;
   onClear?: () => void;
   onSplitHorizontal?: () => void;
@@ -48,6 +49,7 @@ export const TerminalContextMenu: React.FC<TerminalContextMenuProps> = ({
   isAlternateScreen = false,
   onCopy,
   onPaste,
+  onPasteSelection,
   onSelectAll,
   onClear,
   onSplitHorizontal,
@@ -70,26 +72,32 @@ export const TerminalContextMenu: React.FC<TerminalContextMenuProps> = ({
 
   const copyShortcut = getShortcut('copy');
   const pasteShortcut = getShortcut('paste');
+  const pasteSelectionShortcut = getShortcut('paste-selection');
   const selectAllShortcut = getShortcut('select-all');
   const splitHShortcut = getShortcut('split-horizontal');
   const splitVShortcut = getShortcut('split-vertical');
   const clearShortcut = getShortcut('clear-buffer');
 
-  const showContextMenu = rightClickBehavior === 'context-menu' && !isAlternateScreen;
-
+  // Handle right-click: intercept for paste/select-word unless Shift is held
+  // or rightClickBehavior is 'context-menu'. The ContextMenuTrigger stays always
+  // enabled so Shift+Right-Click opens the menu on the first click.
   const handleRightClick = useCallback(
     (e: React.MouseEvent) => {
       // In alternate screen (tmux, vim, etc.), let the terminal application
       // handle right-click natively to avoid conflicting menus
-      if (isAlternateScreen) return;
-
-      if (rightClickBehavior === 'paste') {
+      if (isAlternateScreen) {
         e.preventDefault();
-        e.stopPropagation();
+        return;
+      }
+
+      // Shift+Right-Click or context-menu mode: let Radix open the menu
+      if (e.shiftKey || rightClickBehavior === 'context-menu') return;
+
+      // Paste / select-word: intercept and prevent the context menu
+      e.preventDefault();
+      if (rightClickBehavior === 'paste') {
         onPaste?.();
       } else if (rightClickBehavior === 'select-word') {
-        e.preventDefault();
-        e.stopPropagation();
         onSelectWord?.();
       }
     },
@@ -102,12 +110,11 @@ export const TerminalContextMenu: React.FC<TerminalContextMenuProps> = ({
     <ContextMenu>
       <ContextMenuTrigger
         asChild
-        disabled={!showContextMenu}
-        onContextMenu={!showContextMenu ? handleRightClick : undefined}
+        onContextMenu={handleRightClick}
       >
         {children}
       </ContextMenuTrigger>
-      {showContextMenu && (
+      {!isAlternateScreen && (
         <ContextMenuContent className="w-56">
           <ContextMenuItem onClick={onCopy} disabled={!hasSelection}>
             <Copy size={14} className="mr-2" />
@@ -119,6 +126,13 @@ export const TerminalContextMenu: React.FC<TerminalContextMenuProps> = ({
             {t('terminal.menu.paste')}
             <ContextMenuShortcut>{pasteShortcut}</ContextMenuShortcut>
           </ContextMenuItem>
+          {onPasteSelection && (
+            <ContextMenuItem onClick={onPasteSelection} disabled={!hasSelection}>
+              <ClipboardPaste size={14} className="mr-2" />
+              {t('terminal.menu.pasteSelection')}
+              <ContextMenuShortcut>{pasteSelectionShortcut}</ContextMenuShortcut>
+            </ContextMenuItem>
+          )}
           <ContextMenuItem onClick={onSelectAll}>
             <TerminalIcon size={14} className="mr-2" />
             {t('terminal.menu.selectAll')}

components/terminal/ThemeCustomizeModal.tsx

@@ -15,7 +15,7 @@ import { createPortal } from 'react-dom';
 import { Check, Download, Minus, Palette, Pencil, Plus, Sparkles, Type, X } from 'lucide-react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { useAvailableFonts } from '../../application/state/fontStore';
-import { TERMINAL_THEMES, TerminalThemeConfig } from '../../infrastructure/config/terminalThemes';
+import { TERMINAL_THEMES, TerminalThemeConfig, USER_VISIBLE_TERMINAL_THEMES, isUiMatchTerminalThemeId } from '../../infrastructure/config/terminalThemes';
 import { DEFAULT_FONT_SIZE, MIN_FONT_SIZE, MAX_FONT_SIZE, TerminalFont } from '../../infrastructure/config/fonts';
 import { useCustomThemes, useCustomThemeActions } from '../../application/state/customThemeStore';
 import { parseItermcolors } from '../../infrastructure/parsers/itermcolorsParser';
@@ -125,16 +125,21 @@ interface ThemeCustomizeModalProps {
     open: boolean;
     onClose: () => void;
     currentThemeId?: string;
+    displayThemeId?: string;
     currentFontFamilyId?: string;
     currentFontSize?: number;
     /** Called immediately when user selects a theme (for real-time preview) */
     onThemeChange?: (themeId: string) => void;
+    /** Called when the theme should return to inherited/default state */
+    onThemeReset?: () => void;
     /** Called immediately when user selects a font (for real-time preview) */
     onFontFamilyChange?: (fontFamilyId: string) => void;
     /** Called immediately when user changes font size (for real-time preview) */
     onFontSizeChange?: (fontSize: number) => void;
     /** Called when user clicks Save to persist settings */
     onSave?: () => void;
+    /** Optional live preview callback for consumers that render outside this modal */
+    onPreviewThemeChange?: (theme: TerminalTheme | null) => void;
 }
 
 // Memoized preview component to avoid re-rendering on every state change
@@ -261,26 +266,39 @@ const TerminalPreview = memo(({
 ));
 TerminalPreview.displayName = 'TerminalPreview';
 
+const cloneTheme = (theme: TerminalTheme): TerminalTheme => ({
+    ...theme,
+    colors: { ...theme.colors },
+    isCustom: true,
+});
+
+const serializeTheme = (theme: TerminalTheme): string => JSON.stringify(theme);
+
 export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
     open,
     onClose,
-    currentThemeId = 'termius-dark',
+    currentThemeId,
+    displayThemeId,
     currentFontFamilyId = 'menlo',
     currentFontSize = DEFAULT_FONT_SIZE,
     onThemeChange,
+    onThemeReset,
     onFontFamilyChange,
     onFontSizeChange,
     onSave,
+    onPreviewThemeChange,
 }) => {
     const { t } = useI18n();
     const availableFonts = useAvailableFonts();
     const customThemes = useCustomThemes();
     const { addTheme, updateTheme, deleteTheme } = useCustomThemeActions();
 
+    const resolvedThemeId = currentThemeId ?? displayThemeId ?? TERMINAL_THEMES[0].id;
     const [activeTab, setActiveTab] = useState<TabType>('theme');
-    const [selectedTheme, setSelectedTheme] = useState(currentThemeId);
+    const [selectedTheme, setSelectedTheme] = useState(resolvedThemeId);
     const [selectedFont, setSelectedFont] = useState(currentFontFamilyId);
     const [fontSize, setFontSize] = useState(currentFontSize);
+    const [draftCustomThemes, setDraftCustomThemes] = useState<TerminalTheme[]>(() => customThemes.map(cloneTheme));
 
     // Custom theme editor state
     const [editingTheme, setEditingTheme] = useState<TerminalTheme | null>(null);
@@ -293,30 +311,37 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
         font: currentFontFamilyId,
         fontSize: currentFontSize,
     });
+    const originalCustomThemesRef = useRef<TerminalTheme[]>([]);
+    const wasOpenRef = useRef(false);
 
     // Combine built-in + custom themes
     const allThemes = useMemo(
-        () => [...TERMINAL_THEMES, ...customThemes],
-        [customThemes]
+        () => [...TERMINAL_THEMES, ...draftCustomThemes],
+        [draftCustomThemes]
     );
 
     // Sync state when modal opens
     useEffect(() => {
-        if (open) {
+        if (open && !wasOpenRef.current) {
             // Store original values for potential cancel
             originalValuesRef.current = {
                 theme: currentThemeId,
                 font: currentFontFamilyId,
                 fontSize: currentFontSize,
             };
+            originalCustomThemesRef.current = customThemes.map((theme) => ({
+                ...cloneTheme(theme),
+            }));
             // Initialize selected values
-            setSelectedTheme(currentThemeId);
+            setSelectedTheme(resolvedThemeId);
             setSelectedFont(currentFontFamilyId);
             setFontSize(currentFontSize);
+            setDraftCustomThemes(customThemes.map(cloneTheme));
             setEditingTheme(null);
             setIsNewTheme(false);
         }
-    }, [open, currentThemeId, currentFontFamilyId, currentFontSize]);
+        wasOpenRef.current = open;
+    }, [open, currentThemeId, resolvedThemeId, currentFontFamilyId, currentFontSize, customThemes]);
 
     const currentFont = useMemo(
         (): TerminalFont => availableFonts.find(f => f.id === selectedFont) || availableFonts[0],
@@ -326,6 +351,16 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
         () => editingTheme || allThemes.find(t => t.id === selectedTheme) || TERMINAL_THEMES[0],
         [selectedTheme, allThemes, editingTheme]
     );
+    const hiddenSelectedTheme = useMemo(
+        () => (isUiMatchTerminalThemeId(selectedTheme)
+            ? TERMINAL_THEMES.find((theme) => theme.id === selectedTheme) || null
+            : null),
+        [selectedTheme]
+    );
+
+    useEffect(() => {
+        onPreviewThemeChange?.(open ? currentTheme : null);
+    }, [currentTheme, onPreviewThemeChange, open]);
 
     // Handle theme selection - apply immediately for real-time preview
     const handleThemeSelect = useCallback((themeId: string) => {
@@ -379,7 +414,7 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
             const xml = reader.result as string;
             const parsed = parseItermcolors(xml, name);
             if (parsed) {
-                addTheme(parsed);
+                setDraftCustomThemes((prev) => [...prev, cloneTheme(parsed)]);
                 setSelectedTheme(parsed.id);
                 onThemeChange?.(parsed.id);
                 setActiveTab('theme');
@@ -394,16 +429,16 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
         reader.readAsText(file);
         // Reset file input so the same file can be re-imported
         e.target.value = '';
-    }, [addTheme, onThemeChange, t]);
+    }, [onThemeChange, t]);
 
     const handleEditTheme = useCallback((themeId: string) => {
-        const theme = customThemes.find(t => t.id === themeId);
+        const theme = draftCustomThemes.find(t => t.id === themeId);
         if (theme) {
             setEditingTheme({ ...theme, colors: { ...theme.colors } });
             setIsNewTheme(false);
             setActiveTab('custom');
         }
-    }, [customThemes]);
+    }, [draftCustomThemes]);
 
 
     const handleEditorBack = useCallback(() => {
@@ -412,40 +447,63 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
     }, []);
 
     const handleEditorDelete = useCallback((themeId: string) => {
-        deleteTheme(themeId);
+        setDraftCustomThemes((prev) => prev.filter((theme) => theme.id !== themeId));
         if (selectedTheme === themeId) {
-            setSelectedTheme(TERMINAL_THEMES[0].id);
-            onThemeChange?.(TERMINAL_THEMES[0].id);
+            const originalThemeId = originalValuesRef.current.theme;
+            const fallbackThemeId = originalThemeId && originalThemeId !== themeId
+                ? originalThemeId
+                : (displayThemeId && displayThemeId !== themeId ? displayThemeId : USER_VISIBLE_TERMINAL_THEMES[0].id);
+            setSelectedTheme(fallbackThemeId);
+            if (originalThemeId == null && displayThemeId && displayThemeId !== themeId) {
+                onThemeReset?.();
+            } else {
+                onThemeChange?.(fallbackThemeId);
+            }
         }
         setEditingTheme(null);
         setIsNewTheme(false);
-    }, [deleteTheme, selectedTheme, onThemeChange]);
+    }, [displayThemeId, onThemeChange, onThemeReset, selectedTheme]);
 
     // Save: just close (changes are already applied)
     const handleSave = useCallback(() => {
-        // If editing a custom theme, save it first
-        if (editingTheme) {
-            if (isNewTheme) {
-                addTheme(editingTheme);
-                setSelectedTheme(editingTheme.id);
-                onThemeChange?.(editingTheme.id);
-            } else {
-                updateTheme(editingTheme.id, editingTheme);
+        const originalThemes = originalCustomThemesRef.current;
+        const originalMap = new Map(originalThemes.map((theme) => [theme.id, theme]));
+        const draftMap = new Map(draftCustomThemes.map((theme) => [theme.id, theme]));
+
+        for (const [id, originalTheme] of originalMap) {
+            if (!draftMap.has(id)) {
+                deleteTheme(id);
+                continue;
+            }
+            const nextTheme = draftMap.get(id)!;
+            if (serializeTheme(originalTheme) !== serializeTheme(nextTheme)) {
+                updateTheme(id, nextTheme);
             }
         }
+
+        for (const [id, draftTheme] of draftMap) {
+            if (!originalMap.has(id)) {
+                addTheme(draftTheme);
+            }
+        }
+
         onSave?.();
         onClose();
-    }, [editingTheme, isNewTheme, addTheme, updateTheme, onSave, onClose, onThemeChange]);
+    }, [addTheme, deleteTheme, draftCustomThemes, onClose, onSave, updateTheme]);
 
     // Cancel: revert to original values
     const handleCancel = useCallback(() => {
         const original = originalValuesRef.current;
         // Revert all changes
-        onThemeChange?.(original.theme);
+        if (original.theme) {
+            onThemeChange?.(original.theme);
+        } else {
+            onThemeReset?.();
+        }
         onFontFamilyChange?.(original.font);
         onFontSizeChange?.(original.fontSize);
         onClose();
-    }, [onThemeChange, onFontFamilyChange, onFontSizeChange, onClose]);
+    }, [onThemeChange, onThemeReset, onFontFamilyChange, onFontSizeChange, onClose]);
 
     // Handle ESC key - same as cancel, but skip when child editor is open
     useEffect(() => {
@@ -465,7 +523,7 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
     if (!open) return null;
 
     // Separate built-in and custom themes for display in the theme list
-    const builtinThemes = TERMINAL_THEMES;
+    const builtinThemes = USER_VISIBLE_TERMINAL_THEMES;
 
     const modalContent = (
         <div
@@ -541,6 +599,17 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
                             <div className="flex-1 min-h-0 overflow-y-auto p-2">
                                 {activeTab === 'theme' && (
                                     <div className="space-y-1">
+                                        {hiddenSelectedTheme && (
+                                            <div className="rounded-lg border border-border/60 bg-muted/30 px-3 py-2.5 mb-2">
+                                                <div className="text-[10px] uppercase tracking-wider text-muted-foreground mb-1 font-semibold">
+                                                    {t('terminal.hiddenTheme.title')}
+                                                </div>
+                                                <div className="text-xs font-medium text-foreground">{hiddenSelectedTheme.name}</div>
+                                                <div className="text-[10px] text-muted-foreground mt-1">
+                                                    {t('terminal.hiddenTheme.desc')}
+                                                </div>
+                                            </div>
+                                        )}
                                         {/* Built-in themes */}
                                         {builtinThemes.map(theme => (
                                             <ThemeItem
@@ -551,12 +620,12 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
                                             />
                                         ))}
                                         {/* Custom themes section */}
-                                        {customThemes.length > 0 && (
+                                        {draftCustomThemes.length > 0 && (
                                             <>
                                                 <div className="text-[9px] uppercase tracking-wider text-muted-foreground mt-3 mb-1.5 px-1 font-semibold">
                                                     {t('terminal.customTheme.section')}
                                                 </div>
-                                                {customThemes.map(theme => (
+                                                {draftCustomThemes.map(theme => (
                                                     <ThemeItem
                                                         key={theme.id}
                                                         theme={theme}
@@ -617,12 +686,12 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
                                         />
 
                                         {/* Custom themes list */}
-                                        {customThemes.length > 0 && (
+                                        {draftCustomThemes.length > 0 && (
                                             <>
                                                 <div className="text-[9px] uppercase tracking-wider text-muted-foreground mt-3 mb-1 px-1 font-semibold">
                                                     {t('terminal.customTheme.yourThemes')}
                                                 </div>
-                                                {customThemes.map(theme => (
+                                                {draftCustomThemes.map(theme => (
                                                     <ThemeItem
                                                         key={theme.id}
                                                         theme={theme}
@@ -717,12 +786,16 @@ export const ThemeCustomizeModal: React.FC<ThemeCustomizeModalProps> = ({
                     theme={editingTheme}
                     isNew={isNewTheme}
                     onSave={(theme) => {
+                        setDraftCustomThemes((prev) => {
+                            if (isNewTheme) {
+                                return [...prev, cloneTheme(theme)];
+                            }
+                            return prev.map((entry) => entry.id === theme.id ? cloneTheme(theme) : entry);
+                        });
                         if (isNewTheme) {
-                            addTheme(theme);
                             setSelectedTheme(theme.id);
                             onThemeChange?.(theme.id);
                         } else {
-                            updateTheme(theme.id, theme);
                             if (selectedTheme === theme.id) {
                                 onThemeChange?.(theme.id);
                             }

components/terminal/ThemeSidePanel.tsx

@@ -6,11 +6,11 @@
  * Changes apply in real-time.
  */
 
-import React, { memo, useCallback, useMemo, useRef, useState } from 'react';
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Check, Download, Minus, Palette, Pencil, Plus, Sparkles, Type } from 'lucide-react';
 import { useI18n } from '../../application/i18n/I18nProvider';
 import { useAvailableFonts } from '../../application/state/fontStore';
-import { TERMINAL_THEMES, TerminalThemeConfig } from '../../infrastructure/config/terminalThemes';
+import { TERMINAL_THEMES, TerminalThemeConfig, USER_VISIBLE_TERMINAL_THEMES, isUiMatchTerminalThemeId } from '../../infrastructure/config/terminalThemes';
 import { MIN_FONT_SIZE, MAX_FONT_SIZE, TerminalFont } from '../../infrastructure/config/fonts';
 import { useCustomThemes, useCustomThemeActions } from '../../application/state/customThemeStore';
 import { parseItermcolors } from '../../infrastructure/parsers/itermcolorsParser';
@@ -126,6 +126,7 @@ const FontItem = memo(({
 FontItem.displayName = 'FontItem';
 
 interface ThemeSidePanelProps {
+  followAppTerminalTheme?: boolean;
   currentThemeId: string;
   globalThemeId: string;
   currentFontFamilyId: string;
@@ -152,6 +153,7 @@ interface ThemeSidePanelProps {
 }
 
 const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
+  followAppTerminalTheme = false,
   currentThemeId,
   globalThemeId,
   currentFontFamilyId,
@@ -178,7 +180,7 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
   const customThemes = useCustomThemes();
   const { addTheme, updateTheme, deleteTheme } = useCustomThemeActions();
 
-  const [activeTab, setActiveTab] = useState<TabType>('theme');
+  const [activeTab, setActiveTab] = useState<TabType>(followAppTerminalTheme ? 'font' : 'theme');
   const [editingTheme, setEditingTheme] = useState<TerminalTheme | null>(null);
   const [isNewTheme, setIsNewTheme] = useState(false);
   const fileInputRef = useRef<HTMLInputElement>(null);
@@ -191,6 +193,12 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
     () => allThemes.find((theme) => theme.id === globalThemeId) || TERMINAL_THEMES[0],
     [allThemes, globalThemeId],
   );
+  const hiddenSelectedTheme = useMemo(
+    () => (isUiMatchTerminalThemeId(currentThemeId)
+      ? TERMINAL_THEMES.find((theme) => theme.id === currentThemeId) || null
+      : null),
+    [currentThemeId],
+  );
   const globalFont = useMemo(
     () => availableFonts.find((font) => font.id === globalFontFamilyId) || availableFonts[0],
     [availableFonts, globalFontFamilyId],
@@ -264,9 +272,27 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
     setIsNewTheme(false);
   }, [deleteTheme, currentThemeId, onThemeChange]);
 
+  const themeEditingLocked = followAppTerminalTheme;
+
+  useEffect(() => {
+    if (themeEditingLocked && activeTab !== 'font') {
+      setActiveTab('font');
+    }
+  }, [activeTab, themeEditingLocked]);
+
+  useEffect(() => {
+    if (!themeEditingLocked || !editingTheme) return;
+    setEditingTheme(null);
+    setIsNewTheme(false);
+  }, [editingTheme, themeEditingLocked]);
+
   if (!isVisible) return null;
 
-  const builtinThemes = TERMINAL_THEMES;
+  const builtinThemes = USER_VISIBLE_TERMINAL_THEMES;
+
+  const footerLabel = themeEditingLocked
+    ? `${availableFonts.find(f => f.id === currentFontFamilyId)?.name ?? currentFontFamilyId} • ${currentFontSize}px • ${currentFontWeight}`
+    : `${allThemes.find(t => t.id === currentThemeId)?.name ?? currentThemeId} • ${availableFonts.find(f => f.id === currentFontFamilyId)?.name ?? currentFontFamilyId} • ${currentFontSize}px • ${currentFontWeight}`;
   const panelVars = {
     ['--terminal-panel-bg' as never]: previewColors?.background ?? 'var(--background)',
     ['--terminal-panel-fg' as never]: previewColors?.foreground ?? 'var(--foreground)',
@@ -289,17 +315,19 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
       >
         {/* Tab Bar */}
         <div className="flex p-1.5 gap-0.5 shrink-0 border-b" style={{ borderColor: 'var(--terminal-panel-border)' }}>
-          <button
-            onClick={() => { setActiveTab('theme'); setEditingTheme(null); }}
-            className="flex-1 flex items-center justify-center gap-1 px-1.5 py-1.5 rounded-md text-[11px] font-medium transition-all"
-            style={{
-              backgroundColor: activeTab === 'theme' ? 'var(--terminal-panel-active)' : 'transparent',
-              color: activeTab === 'theme' ? 'var(--terminal-panel-fg)' : 'var(--terminal-panel-muted)',
-            }}
-          >
-            <Palette size={12} />
-            {t('terminal.themeModal.tab.theme')}
-          </button>
+          {!themeEditingLocked && (
+            <button
+              onClick={() => { setActiveTab('theme'); setEditingTheme(null); }}
+              className="flex-1 flex items-center justify-center gap-1 px-1.5 py-1.5 rounded-md text-[11px] font-medium transition-all"
+              style={{
+                backgroundColor: activeTab === 'theme' ? 'var(--terminal-panel-active)' : 'transparent',
+                color: activeTab === 'theme' ? 'var(--terminal-panel-fg)' : 'var(--terminal-panel-muted)',
+              }}
+            >
+              <Palette size={12} />
+              {t('terminal.themeModal.tab.theme')}
+            </button>
+          )}
           <button
             onClick={() => setActiveTab('font')}
             className="flex-1 flex items-center justify-center gap-1 px-1.5 py-1.5 rounded-md text-[11px] font-medium transition-all"
@@ -311,24 +339,37 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
             <Type size={12} />
             {t('terminal.themeModal.tab.font')}
           </button>
-          <button
-            onClick={() => setActiveTab('custom')}
-            className="flex-1 flex items-center justify-center gap-1 px-1.5 py-1.5 rounded-md text-[11px] font-medium transition-all"
-            style={{
-              backgroundColor: activeTab === 'custom' ? 'var(--terminal-panel-active)' : 'transparent',
-              color: activeTab === 'custom' ? 'var(--terminal-panel-fg)' : 'var(--terminal-panel-muted)',
-            }}
-          >
-            <Sparkles size={12} />
-            {t('terminal.themeModal.tab.custom')}
-          </button>
+          {!themeEditingLocked && (
+            <button
+              onClick={() => setActiveTab('custom')}
+              className="flex-1 flex items-center justify-center gap-1 px-1.5 py-1.5 rounded-md text-[11px] font-medium transition-all"
+              style={{
+                backgroundColor: activeTab === 'custom' ? 'var(--terminal-panel-active)' : 'transparent',
+                color: activeTab === 'custom' ? 'var(--terminal-panel-fg)' : 'var(--terminal-panel-muted)',
+              }}
+            >
+              <Sparkles size={12} />
+              {t('terminal.themeModal.tab.custom')}
+            </button>
+          )}
         </div>
 
         {/* List Content */}
         <ScrollArea className="flex-1 min-h-0">
           <div className="py-1">
-            {activeTab === 'theme' && (
+            {!themeEditingLocked && activeTab === 'theme' && (
               <div>
+                {hiddenSelectedTheme && (
+                  <div className="mx-2 mb-2 rounded-lg border px-3 py-2.5" style={{ borderColor: 'var(--terminal-panel-border)', backgroundColor: 'var(--terminal-panel-hover)' }}>
+                    <div className="text-[10px] uppercase tracking-wider mb-1 font-semibold" style={{ color: 'var(--terminal-panel-muted)' }}>
+                      {t('terminal.hiddenTheme.title')}
+                    </div>
+                    <div className="text-xs font-medium">{hiddenSelectedTheme.name}</div>
+                    <div className="text-[10px] mt-1" style={{ color: 'var(--terminal-panel-muted)' }}>
+                      {t('terminal.hiddenTheme.desc')}
+                    </div>
+                  </div>
+                )}
                 {builtinThemes.map(theme => (
                   <ThemeItem
                     key={theme.id}
@@ -391,7 +432,7 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
                 )}
               </div>
             )}
-            {activeTab === 'custom' && !editingTheme && (
+            {!themeEditingLocked && activeTab === 'custom' && !editingTheme && (
               <div>
                 <button
                   onClick={handleNewTheme}
@@ -505,6 +546,23 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
           </div>
         )}
 
+        {themeEditingLocked && canResetTheme && (
+          <div className="p-2.5 border-t shrink-0" style={{ borderColor: 'var(--terminal-panel-border)' }}>
+            <div className="flex items-center justify-between gap-2">
+              <div className="text-[9px] uppercase tracking-wider font-semibold" style={{ color: 'var(--terminal-panel-muted)' }}>
+                {t('terminal.themeModal.globalTheme')}
+              </div>
+              <button
+                onClick={onThemeReset}
+                className="text-[10px] font-medium hover:opacity-80 transition-opacity"
+                style={{ color: 'var(--terminal-panel-fg)' }}
+              >
+                {t('common.useGlobal')}
+              </button>
+            </div>
+          </div>
+        )}
+
         {/* Font Weight Control (only in font tab) */}
         {activeTab === 'font' && (
           <div className="p-2.5 border-t shrink-0" style={{ borderColor: 'var(--terminal-panel-border)' }}>
@@ -550,7 +608,7 @@ const ThemeSidePanelInner: React.FC<ThemeSidePanelProps> = ({
         {/* Current selection info */}
         <div className="px-2.5 py-1.5 border-t shrink-0" style={{ borderColor: 'var(--terminal-panel-border)' }}>
           <div className="text-[9px] truncate" style={{ color: 'var(--terminal-panel-muted)' }}>
-            {allThemes.find(t => t.id === currentThemeId)?.name ?? currentThemeId} • {availableFonts.find(f => f.id === currentFontFamilyId)?.name ?? currentFontFamilyId} • {currentFontSize}px • {currentFontWeight}
+            {footerLabel}
           </div>
         </div>
       </div>

components/terminal/clearTerminalViewport.ts

@@ -0,0 +1,85 @@
+import type { Terminal as XTerm } from "@xterm/xterm";
+
+type CsiParam = number | number[];
+type InternalTerminal = XTerm & {
+  _core?: {
+    scroll?: (eraseAttr: unknown, isWrapped?: boolean) => void;
+    _inputHandler?: {
+      _eraseAttrData?: () => unknown;
+    };
+  };
+};
+
+const getVisibleContentRowCount = (term: XTerm): number => {
+  const buffer = term.buffer.active;
+  if (buffer.type !== "normal") {
+    return 0;
+  }
+
+  const baseY = buffer.baseY;
+  for (let row = term.rows - 1; row >= 0; row--) {
+    const line = buffer.getLine(baseY + row);
+    if (!line) {
+      continue;
+    }
+    if (line.translateToString(true).length > 0) {
+      return row + 1;
+    }
+  }
+
+  return 0;
+};
+
+export const preserveTerminalViewportInScrollback = (term: XTerm): void => {
+  const rowsToPreserve = getVisibleContentRowCount(term);
+  if (rowsToPreserve <= 0) {
+    return;
+  }
+
+  const internal = term as InternalTerminal;
+  const scroll = internal._core?.scroll;
+  const eraseAttr = internal._core?._inputHandler?._eraseAttrData?.();
+
+  if (typeof scroll !== "function" || eraseAttr === undefined) {
+    return;
+  }
+
+  for (let row = 0; row < rowsToPreserve; row++) {
+    scroll.call(internal._core, eraseAttr, false);
+  }
+};
+
+export const clearTerminalViewport = (term: XTerm): void => {
+  const buffer = term.buffer.active;
+  if (buffer.type !== "normal") return;
+
+  const cursorY = buffer.cursorY;
+  const cursorX = buffer.cursorX;
+
+  if (cursorY === 0 && buffer.baseY === 0) return;
+
+  const internal = term as InternalTerminal;
+  const scroll = internal._core?.scroll;
+  const eraseAttr = internal._core?._inputHandler?._eraseAttrData?.();
+
+  if (typeof scroll !== "function" || eraseAttr === undefined) return;
+
+  // Push lines above cursor into scrollback so they are preserved.
+  // After cursorY scrolls the prompt line shifts to active-screen row 0.
+  for (let i = 0; i < cursorY; i++) {
+    scroll.call(internal._core, eraseAttr, false);
+  }
+
+  // Clear everything below the prompt and reposition the cursor on it.
+  // CSI coordinates are 1-indexed.
+  const col = cursorX + 1;
+  term.write(`\x1b[2;1H\x1b[J\x1b[1;${col}H`, () => {
+    term.scrollToBottom();
+  });
+};
+
+export const isEraseScrollbackSequence = (params: CsiParam[]): boolean =>
+  params.length > 0 && params[0] === 3;
+
+export const isEraseViewportSequence = (params: CsiParam[]): boolean =>
+  params.length > 0 && params[0] === 2;

components/terminal/hooks/useServerStats.ts

@@ -89,11 +89,23 @@ export function useServerStats({
   const hasFetchedRef = useRef(false);
   const connectedAtRef = useRef(0);
   const fetchGenerationRef = useRef(0);
+  // Auto-disable polling after a few consecutive failures. This covers
+  // hosts the banner classifier could not identify (e.g. Juniper JUNOS,
+  // Arista EOS, Cisco NX-OS — all of which advertise themselves as
+  // OpenSSH but do not support the POSIX stats shell command). Without
+  // this, the hook would keep retrying forever and generate an AAA
+  // session log every refresh interval.
+  const CONSECUTIVE_FAILURE_LIMIT = 3;
+  const consecutiveFailuresRef = useRef(0);
+  const givenUpRef = useRef(false);
 
   const fetchStats = useCallback(async () => {
     if (!enabled || !isSupportedOs || !isConnected || !isVisible || !sessionId) {
       return;
     }
+    if (givenUpRef.current) {
+      return;
+    }
 
     const bridge = netcattyBridge.get();
     if (!bridge?.getServerStats) {
@@ -104,6 +116,21 @@ export function useServerStats({
     setIsLoading(true);
     setError(null);
 
+    const markFailure = (message: string) => {
+      consecutiveFailuresRef.current += 1;
+      setError(message);
+      if (consecutiveFailuresRef.current >= CONSECUTIVE_FAILURE_LIMIT) {
+        // Stop polling this session. The caller's useEffect sees the
+        // givenUp flag via the next render cycle and we also clear the
+        // interval locally so no further ticks fire.
+        givenUpRef.current = true;
+        if (intervalRef.current) {
+          clearInterval(intervalRef.current);
+          intervalRef.current = null;
+        }
+      }
+    };
+
     try {
       const result = await bridge.getServerStats(sessionId);
 
@@ -112,6 +139,7 @@ export function useServerStats({
 
       if (result.success && result.stats) {
         hasFetchedRef.current = true;
+        consecutiveFailuresRef.current = 0;
         setStats({
           cpu: result.stats.cpu,
           cpuCores: result.stats.cpuCores,
@@ -134,11 +162,17 @@ export function useServerStats({
           lastUpdated: Date.now(),
         });
       } else if (result.error) {
-        setError(result.error);
+        markFailure(result.error);
+      } else {
+        // Response was not marked as success but has no error — treat as
+        // a soft failure. This happens e.g. when the stats shell pipeline
+        // returns a parse failure on a host that isn't a typical Linux
+        // distro (JUNOS, NX-OS, EOS).
+        markFailure('No stats returned');
       }
     } catch (err) {
       if (isMountedRef.current && generation === fetchGenerationRef.current) {
-        setError(err instanceof Error ? err.message : 'Unknown error');
+        markFailure(err instanceof Error ? err.message : 'Unknown error');
       }
     } finally {
       if (isMountedRef.current && generation === fetchGenerationRef.current) {
@@ -147,6 +181,15 @@ export function useServerStats({
     }
   }, [sessionId, enabled, isSupportedOs, isConnected, isVisible]);
 
+  // When the session changes (e.g., same tab reconnects to a different host
+  // while staying connected), reset the failure counter. Without this, a
+  // JUNOS session that tripped the counter would permanently suppress
+  // polling even after the tab reconnects to a Linux host.
+  useEffect(() => {
+    consecutiveFailuresRef.current = 0;
+    givenUpRef.current = false;
+  }, [sessionId]);
+
   // Initial fetch and periodic refresh
   useEffect(() => {
     isMountedRef.current = true;
@@ -158,9 +201,13 @@ export function useServerStats({
     }
 
     if (!enabled || !isSupportedOs || !isConnected) {
-      // Reset stats and fetch state when disabled or not connected
+      // Reset stats and fetch state when disabled or not connected.
+      // Also reset the give-up flag so that a reconnect (possibly to a
+      // different host at the same sessionId slot) gets a fresh chance.
       hasFetchedRef.current = false;
       connectedAtRef.current = 0;
+      consecutiveFailuresRef.current = 0;
+      givenUpRef.current = false;
 
       setStats({
         cpu: null,
@@ -222,15 +269,23 @@ export function useServerStats({
     // (e.g., tab was hidden while connected and is now becoming visible).
     const connectionAge = Date.now() - connectedAtRef.current;
     const needsWarmup = !hasFetchedRef.current && connectionAge < 2000;
-    const initialTimer = setTimeout(fetchStats, needsWarmup ? 2000 : 0);
+    // If we already gave up on this session (exceeded the consecutive
+    // failure limit), don't even schedule new timers on effect reruns
+    // such as visibility/tab-focus/settings changes. The cleanup at
+    // disconnect/sessionId change clears the flag for a fresh attempt.
+    const initialTimer = givenUpRef.current
+      ? null
+      : setTimeout(fetchStats, needsWarmup ? 2000 : 0);
 
     // Set up periodic refresh
     const intervalMs = Math.max(5, refreshInterval) * 1000; // Minimum 5 seconds
-    intervalRef.current = setInterval(fetchStats, intervalMs);
+    if (!givenUpRef.current) {
+      intervalRef.current = setInterval(fetchStats, intervalMs);
+    }
 
     return () => {
       isMountedRef.current = false;
-      clearTimeout(initialTimer);
+      if (initialTimer) clearTimeout(initialTimer);
       if (intervalRef.current) {
         clearInterval(intervalRef.current);
         intervalRef.current = null;

components/terminal/hooks/useTerminalContextActions.ts

@@ -3,6 +3,7 @@ import { useCallback } from "react";
 import type { RefObject } from "react";
 import { logger } from "../../../lib/logger";
 import { normalizeLineEndings, wrapBracketedPaste } from "../../../lib/utils";
+import { clearTerminalViewport } from "../clearTerminalViewport";
 
 type TerminalBackendWriteApi = {
   writeToSession: (sessionId: string, data: string) => void;
@@ -55,6 +56,24 @@ export const useTerminalContextActions = ({
     }
   }, [sessionRef, termRef, terminalBackend, disableBracketedPasteRef, scrollOnPasteRef]);
 
+  const onPasteSelection = useCallback(() => {
+    const term = termRef.current;
+    if (!term) return;
+    const selection = term.getSelection();
+    if (!selection || !sessionRef.current) return;
+    let data = normalizeLineEndings(selection);
+    if (term.modes.bracketedPasteMode && !disableBracketedPasteRef?.current) data = wrapBracketedPaste(data);
+    terminalBackend.writeToSession(sessionRef.current, data);
+    if (scrollOnPasteRef?.current) {
+      term.scrollToBottom();
+      if (typeof requestAnimationFrame === "function") {
+        requestAnimationFrame(() => {
+          term.scrollToBottom();
+        });
+      }
+    }
+  }, [sessionRef, termRef, terminalBackend, disableBracketedPasteRef, scrollOnPasteRef]);
+
   const onSelectAll = useCallback(() => {
     const term = termRef.current;
     if (!term) return;
@@ -65,7 +84,7 @@ export const useTerminalContextActions = ({
   const onClear = useCallback(() => {
     const term = termRef.current;
     if (!term) return;
-    term.clear();
+    clearTerminalViewport(term);
   }, [termRef]);
 
   const onSelectWord = useCallback(() => {
@@ -75,5 +94,5 @@ export const useTerminalContextActions = ({
     onHasSelectionChange?.(true);
   }, [onHasSelectionChange, termRef]);
 
-  return { onCopy, onPaste, onSelectAll, onClear, onSelectWord };
+  return { onCopy, onPaste, onPasteSelection, onSelectAll, onClear, onSelectWord };
 };

components/terminal/runtime/createTerminalSessionStarters.ts

@@ -10,9 +10,23 @@ import {
   sanitizeCredentialValue,
 } from "../../../domain/credentials";
 import { resolveHostAuth } from "../../../domain/sshAuth";
+import { detectVendorFromSshVersion } from "../../../domain/host";
 
-/** Timeout of distro detection task */
-const DISTRO_DETECT_TIMEOUT = 8000; // ms
+/**
+ * Per-connection token for stale-timer detection. The renderer reuses the
+ * same sessionId across reconnects within a tab, so comparing sessionIds
+ * cannot distinguish "the current attempt" from "a previous attempt on
+ * the same slot". We assign each startSSH call a fresh token object and
+ * store it in this module-local map, keyed by sessionId. A timer that
+ * was scheduled under an older token will see a different value here and
+ * bail out. The map entry for a sessionId is overwritten on each new
+ * connect and stays around until the app exits — since there is only one
+ * entry per active session, the memory cost is negligible.
+ */
+const connectionTokensBySessionId = new Map<string, object>();
+
+const isConnectionTokenCurrent = (sessionId: string, token: object): boolean =>
+  connectionTokensBySessionId.get(sessionId) === token;
 
 type TerminalBackendApi = {
   backendAvailable: () => boolean;
@@ -38,6 +52,17 @@ type TerminalBackendApi = {
     stdout?: string;
     stderr?: string;
   }>;
+  getSessionRemoteInfo?: (sessionId: string) => Promise<{
+    success: boolean;
+    remoteSshVersion?: string;
+    error?: string;
+  }>;
+  getSessionDistroInfo?: (sessionId: string) => Promise<{
+    success: boolean;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+  }>;
   onSessionData: (sessionId: string, cb: (data: string) => void) => () => void;
   onSessionExit: (
     sessionId: string,
@@ -223,32 +248,73 @@ const attachSessionToTerminal = (
       }
     }
 
+    // Clean up the connection token for this sessionId so stale timers
+    // that haven't fired yet will fail the isConnectionTokenCurrent check
+    // (previously they would see the old token still in the map and pass).
+    connectionTokensBySessionId.delete(ctx.sessionId);
+
     ctx.onSessionExit?.(ctx.sessionId, evt);
   });
 };
 
 const runDistroDetection = async (
   ctx: TerminalSessionStartersContext,
-  auth: { username: string; password?: string; key?: SSHKey; passphrase?: string },
+  sessionId: string,
+  connectionToken: object,
 ) => {
-  if (!ctx.terminalBackend.execAvailable()) return;
+  // Stale-session guard: the renderer reuses ctx.sessionId across
+  // reconnects in the same tab, so comparing sessionIds is not enough.
+  // We compare against a per-connection token instead; if a newer
+  // connect attempt has run, it will have replaced the token in the
+  // module-level map and this check will fail. Repeated after every
+  // await because the session can change during an async call.
+  const isStillCurrent = () => isConnectionTokenCurrent(sessionId, connectionToken);
+
+  if (!isStillCurrent()) return;
+
+  // Step 1: try to classify from the SSH server identification string
+  // captured at handshake time. This is free (no extra channel) and
+  // reliably identifies most network-device vendors (Cisco IOS, Huawei
+  // VRP, HPE Comware, MikroTik, Fortinet, etc.) so we can skip the
+  // POSIX-shell probe entirely for those hosts — which otherwise fails
+  // and, on devices like Cisco / Juniper with AAA logging, generates an
+  // extra session log entry per connect.
   try {
-    const res = await ctx.terminalBackend.execCommand({
-      hostname: ctx.host.hostname,
-      username: auth.username || "root",
-      port: ctx.host.port || 22,
-      password: auth.password,
-      privateKey: auth.key?.privateKey,
-      passphrase: auth.passphrase ?? auth.key?.passphrase,
-      command: "cat /etc/os-release 2>/dev/null || uname -a",
-      timeout: DISTRO_DETECT_TIMEOUT,
-    });
-    const data = `${res.stdout || ""}\n${res.stderr || ""}`;
-    const idMatch = data.match(/^ID="?([\w-]+)"?$/im);
-    const distro = idMatch
-      ? idMatch[1]
-      : (data.split(/\s+/)[0] || "").toLowerCase();
-    if (distro) ctx.onOsDetected?.(ctx.host.id, distro);
+    if (ctx.terminalBackend.getSessionRemoteInfo && sessionId) {
+      const info = await ctx.terminalBackend.getSessionRemoteInfo(sessionId);
+      if (!isStillCurrent()) return;
+      const vendor = detectVendorFromSshVersion(info?.remoteSshVersion);
+      if (vendor) {
+        ctx.onOsDetected?.(ctx.host.id, vendor);
+        return;
+      }
+    }
+  } catch (err) {
+    logger.warn("SSH banner vendor detection failed", err);
+  }
+
+  if (!isStillCurrent()) return;
+
+  // Step 2: unknown or generic OpenSSH/Dropbear — fall back to the
+  // /etc/os-release probe to pick a distro-specific icon. We deliberately
+  // use `getSessionDistroInfo` which runs the probe on the *existing*
+  // SSH connection's exec channel instead of spinning up a brand new
+  // SSH client the way `execCommand` would. That saves a full handshake
+  // round-trip on every connect, and on OpenSSH-fronted network devices
+  // that we couldn't identify from the banner (JUNOS, NX-OS, EOS) it
+  // avoids one extra AAA session log entry per connect.
+  try {
+    if (ctx.terminalBackend.getSessionDistroInfo && sessionId) {
+      const res = await ctx.terminalBackend.getSessionDistroInfo(sessionId);
+      if (!isStillCurrent()) return;
+      if (!res?.success) return;
+      const data = `${res.stdout || ""}\n${res.stderr || ""}`;
+      const idMatch = data.match(/^ID="?([\w-]+)"?$/im);
+      const distro = idMatch
+        ? idMatch[1]
+        : (data.split(/\s+/)[0] || "").toLowerCase();
+      if (distro) ctx.onOsDetected?.(ctx.host.id, distro);
+    }
   } catch (err) {
     logger.warn("OS probe failed", err);
   }
@@ -262,12 +328,6 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
   };
 
   const startSSH = async (term: XTerm) => {
-    try {
-      term.clear?.();
-    } catch (err) {
-      logger.warn("Failed to clear terminal before connect", err);
-    }
-
     if (!ctx.terminalBackend.backendAvailable()) {
       ctx.setError("Native SSH bridge unavailable. Launch via Electron app.");
       term.writeln(
@@ -299,8 +359,6 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
     const effectivePassphrase = sanitizeCredentialValue(resolvedAuth.passphrase);
     const hasEncryptedPrimaryPassword = isEncryptedCredentialPlaceholder(resolvedAuth.password);
     const hasEncryptedPrimaryKey = isEncryptedCredentialPlaceholder(key?.privateKey);
-    let usedKey: SSHKey | undefined;
-    let usedPassword: string | undefined;
 
     const isAuthError = (err: unknown): boolean => {
       if (!(err instanceof Error)) return false;
@@ -572,7 +630,6 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
       if (hasKeyMaterial) {
         try {
           id = await startAttempt({ key });
-          usedKey = key;
         } catch (err) {
           if (isAuthError(err) && hasPassword) {
             ctx.setProgressLogs((prev) => [
@@ -580,14 +637,12 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
               "Key auth failed. Trying password...",
             ]);
             id = await startAttempt({ password: effectivePassword });
-            usedPassword = effectivePassword;
           } else {
             throw err;
           }
         }
       } else {
         id = await startAttempt({ password: effectivePassword });
-        usedPassword = effectivePassword;
       }
 
       if (unsubscribeChainProgress) unsubscribeChainProgress();
@@ -614,17 +669,20 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
         }, 600);
       }
 
-      // Run OS detection only after successful connection
-      setTimeout(
-        () =>
-          void runDistroDetection(ctx, {
-            username: effectiveUsername,
-            password: usedPassword,
-            key: usedKey,
-            passphrase: effectivePassphrase,
-          }),
-        600,
-      );
+      // Run OS detection only after successful connection. Mint a fresh
+      // token for this specific connection attempt and register it as
+      // the current one for this sessionId slot; any previous timer
+      // scheduled against an earlier token will see the replacement
+      // and bail out. The detection function re-checks the token after
+      // every async await so a reconnect mid-probe is also caught.
+      {
+        const connectionToken = {};
+        connectionTokensBySessionId.set(id, connectionToken);
+        setTimeout(() => {
+          if (!isConnectionTokenCurrent(id, connectionToken)) return;
+          void runDistroDetection(ctx, id, connectionToken);
+        }, 600);
+      }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       const authError = isAuthError(err);
@@ -653,12 +711,6 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
   };
 
   const startTelnet = async (term: XTerm) => {
-    try {
-      term.clear?.();
-    } catch (err) {
-      logger.warn("Failed to clear terminal before connect", err);
-    }
-
     if (!ctx.terminalBackend.telnetAvailable()) {
       ctx.setError("Telnet bridge unavailable. Please run the desktop build.");
       term.writeln("\r\n[Telnet bridge unavailable. Please run the desktop build.]");
@@ -692,12 +744,6 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
   };
 
   const startMosh = async (term: XTerm) => {
-    try {
-      term.clear?.();
-    } catch (err) {
-      logger.warn("Failed to clear terminal before connect", err);
-    }
-
     if (!ctx.terminalBackend.moshAvailable()) {
       ctx.setError("Mosh bridge unavailable. Please run the desktop build.");
       term.writeln("\r\n[Mosh bridge unavailable. Please run the desktop build.]");
@@ -748,12 +794,6 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex
   };
 
   const startLocal = async (term: XTerm) => {
-    try {
-      term.clear?.();
-    } catch (err) {
-      logger.warn("Failed to clear terminal before connect", err);
-    }
-
     if (!ctx.terminalBackend.localAvailable()) {
       ctx.setError("Local shell bridge unavailable. Please run the desktop build.");
       term.writeln(

components/terminal/runtime/createXTermRuntime.ts

@@ -31,6 +31,12 @@ import {
 import { logger } from "../../../lib/logger";
 import { isMacPlatform, normalizeLineEndings, wrapBracketedPaste } from "../../../lib/utils";
 import { netcattyBridge } from "../../../infrastructure/services/netcattyBridge";
+import {
+  clearTerminalViewport,
+  isEraseViewportSequence,
+  isEraseScrollbackSequence,
+  preserveTerminalViewportInScrollback,
+} from "../clearTerminalViewport";
 import type {
   Host,
   KeyBinding,
@@ -129,6 +135,21 @@ const detectPlatform = (): XTermPlatform => {
   return "darwin";
 };
 
+/**
+ * Extract the primary font family from a CSS font-family string that may
+ * include fallback fonts.  `document.fonts.check` returns `false` when *any*
+ * listed font is still loading, so passing the entire CJK fallback stack
+ * causes false negatives during early terminal creation – which in turn makes
+ * `fontWeightBold` fall back to the normal weight and renders bold text too
+ * thin.
+ */
+export const primaryFontFamily = (fontFamily: string): string => {
+  // Split on commas that are NOT inside quotes to handle font names like "Foo, Bar"
+  const match = fontFamily.match(/^(?:"[^"]*"|'[^']*'|[^,])+/);
+  const first = match?.[0]?.trim();
+  return first || fontFamily;
+};
+
 export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime => {
   const platform = detectPlatform();
   const deviceMemoryGb =
@@ -161,7 +182,11 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
 
   const cursorStyle = settings?.cursorShape ?? "block";
   const cursorBlink = settings?.cursorBlink ?? true;
-  const scrollback = settings?.scrollback ?? 10000;
+  // xterm.js treats scrollback=0 as "no scrollback buffer", which breaks mouse
+  // wheel scrolling (events become arrow-key sequences).  The UI uses 0 to mean
+  // "no limit", so map it to a large value instead.
+  const rawScrollback = settings?.scrollback ?? 10000;
+  const scrollback = rawScrollback === 0 ? 999999 : rawScrollback;
   const drawBoldTextInBrightColors = settings?.drawBoldInBrightColors ?? true;
   const fontWeight = resolveHostTerminalFontWeight(ctx.host, settings?.fontWeight ?? 400);
   const fontWeightBold = settings?.fontWeightBold ?? 700;
@@ -180,7 +205,7 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
     if (typeof document === "undefined" || !document.fonts?.check) {
       return fontWeightBold;
     }
-    const weightSpec = `${fontWeightBold} ${effectiveFontSize}px ${fontFamily}`;
+    const weightSpec = `${fontWeightBold} ${effectiveFontSize}px ${primaryFontFamily(fontFamily)}`;
     return document.fonts.check(weightSpec) ? fontWeightBold : fontWeight;
   })();
 
@@ -400,12 +425,6 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
       if (!consumed) return false; // Event was consumed by autocomplete
     }
 
-    if ((e.ctrlKey || e.metaKey) && e.key === "f" && e.type === "keydown") {
-      e.preventDefault();
-      ctx.setIsSearchOpen(true);
-      return false;
-    }
-
     const currentScheme = ctx.hotkeySchemeRef.current;
     // Use shared utility for platform detection when hotkey scheme is disabled
     const isMac = currentScheme === "mac" || (currentScheme === "disabled" && isMacPlatform());
@@ -478,12 +497,23 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
           });
           break;
         }
+        case "pasteSelection": {
+          const selection = term.getSelection();
+          const id = ctx.sessionRef.current;
+          if (selection && id) {
+            let data = normalizeLineEndings(selection);
+            if (term.modes.bracketedPasteMode && !ctx.terminalSettingsRef.current?.disableBracketedPaste) data = wrapBracketedPaste(data);
+            ctx.terminalBackend.writeToSession(id, data);
+            scrollToBottomAfterPaste();
+          }
+          break;
+        }
         case "selectAll": {
           term.selectAll();
           break;
         }
         case "clearBuffer": {
-          term.clear();
+          clearTerminalViewport(term);
           break;
         }
         case "searchTerminal": {
@@ -626,6 +656,17 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
   // OSC 7 format: \x1b]7;file://hostname/path\x07 or \x1b]7;file://hostname/path\x1b\\
   let currentCwd: string | undefined = undefined;
 
+  const eraseScrollbackDisposable = term.parser.registerCsiHandler({ final: "J" }, (params) => {
+    if (isEraseViewportSequence(params)) {
+      preserveTerminalViewportInScrollback(term);
+      return false;
+    }
+    if (!isEraseScrollbackSequence(params)) {
+      return false;
+    }
+    return true;
+  });
+
   // Register OSC 7 handler using xterm.js parser
   // OSC 7 is the standard way for shells to report the current working directory
   const osc7Disposable = term.parser.registerOscHandler(7, (data) => {
@@ -748,6 +789,7 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime
     dispose: () => {
       cleanupMiddleClick?.();
       keywordHighlighter.dispose();
+      eraseScrollbackDisposable.dispose();
       osc7Disposable.dispose();
       osc52Disposable.dispose();
       try {

components/ui/aside-panel.tsx

@@ -1,5 +1,5 @@
 import { ArrowLeft, MoreVertical, X } from 'lucide-react';
-import React, { createContext, ReactNode, useCallback, useContext, useState } from 'react';
+import React, { createContext, ReactNode, useCallback, useContext, useMemo, useState } from 'react';
 import { cn } from '../../lib/utils';
 import { Popover, PopoverContent, PopoverTrigger } from './popover';
 import { ScrollArea } from './scroll-area';
@@ -44,6 +44,12 @@ interface AsidePanelProps {
     children: ReactNode;
     className?: string;
     width?: string;
+    layout?: AsidePanelLayout;
+    /**
+     * Optional stable identifier emitted as `data-section` on the panel
+     * root. Used as a targeting hook for Custom CSS (Settings → Appearance).
+     */
+    dataSection?: string;
 }
 
 interface AsidePanelHeaderProps {
@@ -171,14 +177,40 @@ interface AsidePanelStackProps {
     initialItem: AsideContentItem;
     className?: string;
     width?: string;
+    layout?: AsidePanelLayout;
+    /**
+     * Optional stable identifier emitted as `data-section` on the panel
+     * root. Used as a targeting hook for Custom CSS.
+     */
+    dataSection?: string;
 }
 
+export type AsidePanelLayout = 'overlay' | 'inline';
+
+const resolveInlineWidth = (width: string) => {
+    const arbitraryWidthMatch = width.match(/w-\[(.+)\]/);
+    if (arbitraryWidthMatch) {
+        return arbitraryWidthMatch[1];
+    }
+
+    switch (width) {
+        case 'w-full':
+            return '100%';
+        case 'w-screen':
+            return '100vw';
+        default:
+            return '380px';
+    }
+};
+
 export const AsidePanelStack: React.FC<AsidePanelStackProps> = ({
     open,
     onClose,
     initialItem,
     className,
     width = 'w-[380px]',
+    layout = 'overlay',
+    dataSection,
 }) => {
     const [stack, setStack] = useState<AsideContentItem[]>([initialItem]);
 
@@ -205,6 +237,13 @@ export const AsidePanelStack: React.FC<AsidePanelStackProps> = ({
 
     const currentItem = stack[stack.length - 1];
     const canGoBack = stack.length > 1;
+    const inlineWidth = useMemo(() => resolveInlineWidth(width), [width]);
+    const inlineStyle = layout === 'inline'
+        ? ({
+            width: inlineWidth,
+            ['--aside-inline-width' as string]: inlineWidth,
+        } as React.CSSProperties)
+        : undefined;
 
     // Reset stack when panel closes/opens
     React.useEffect(() => {
@@ -218,10 +257,14 @@ export const AsidePanelStack: React.FC<AsidePanelStackProps> = ({
     return (
         <AsidePanelContext.Provider value={{ push, pop, replace, clear, canGoBack, currentItem }}>
             <div className={cn(
-                "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
-                width,
+                layout === 'inline'
+                    ? "relative split-panel-enter shrink-0 h-full min-h-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden shadow-[-16px_0_32px_hsl(var(--foreground)/0.08)]"
+                    : "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
+                layout === 'overlay' && width,
                 className
-            )}>
+            )}
+            style={inlineStyle}
+            data-section={dataSection}>
                 <AsidePanelHeader
                     title={currentItem.title}
                     subtitle={currentItem.subtitle}
@@ -248,15 +291,29 @@ export const AsidePanel: React.FC<AsidePanelProps> = ({
     children,
     className,
     width = 'w-[380px]',
+    layout = 'overlay',
+    dataSection,
 }) => {
     if (!open) return null;
 
+    const inlineWidth = resolveInlineWidth(width);
+    const inlineStyle = layout === 'inline'
+        ? ({
+            width: inlineWidth,
+            ['--aside-inline-width' as string]: inlineWidth,
+        } as React.CSSProperties)
+        : undefined;
+
     return (
         <div className={cn(
-            "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
-            width,
+            layout === 'inline'
+                ? "relative split-panel-enter shrink-0 h-full min-h-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden shadow-[-16px_0_32px_hsl(var(--foreground)/0.08)]"
+                : "absolute right-0 top-0 bottom-0 max-w-full border-l border-border/60 bg-background z-30 flex flex-col app-no-drag overflow-hidden",
+            layout === 'overlay' && width,
             className
-        )}>
+        )}
+        style={inlineStyle}
+        data-section={dataSection}>
             {title && (
                 <AsidePanelHeader
                     title={title}

domain/groupConfig.ts

@@ -17,10 +17,30 @@ export function resolveGroupDefaults(
     const config = configMap.get(ancestorPath);
     if (config) {
       for (const [key, value] of Object.entries(config)) {
+        if (
+          (key === 'theme' && config.themeOverride === false) ||
+          (key === 'fontFamily' && config.fontFamilyOverride === false) ||
+          (key === 'fontSize' && config.fontSizeOverride === false) ||
+          (key === 'fontWeight' && config.fontWeightOverride === false)
+        ) {
+          continue;
+        }
         if (key !== 'path' && value !== undefined) {
           merged[key] = value;
         }
       }
+      if (config.themeOverride === false) {
+        delete merged.themeOverride;
+      }
+      if (config.fontFamilyOverride === false) {
+        delete merged.fontFamilyOverride;
+      }
+      if (config.fontSizeOverride === false) {
+        delete merged.fontSizeOverride;
+      }
+      if (config.fontWeightOverride === false) {
+        delete merged.fontWeightOverride;
+      }
     }
   }
   return merged as Partial<GroupConfig>;
@@ -50,3 +70,11 @@ export function applyGroupDefaults(host: Host, groupDefaults: Partial<GroupConfi
   }
   return effective;
 }
+
+export function resolveGroupTerminalThemeId(
+  groupDefaults: Partial<GroupConfig> | undefined,
+  fallbackThemeId: string,
+): string {
+  if (!groupDefaults) return fallbackThemeId;
+  return groupDefaults.theme || fallbackThemeId;
+}

domain/host.ts

@@ -17,6 +17,26 @@ export const LINUX_DISTRO_OPTIONS = [
   'kali',
 ] as const;
 
+/**
+ * Known network-device vendor IDs that Netcatty can detect from the SSH
+ * server identification string. When a host is classified as one of these,
+ * features that assume a POSIX shell (e.g. the periodic server stats poll)
+ * are disabled, because the stats command would either be rejected outright
+ * or generate one AAA session log per poll on the remote device.
+ */
+export const NETWORK_DEVICE_OPTIONS = [
+  'cisco',
+  'juniper',
+  'huawei',
+  'hpe',
+  'mikrotik',
+  'fortinet',
+  'paloalto',
+  'zyxel',
+] as const;
+
+export type NetworkDeviceVendor = typeof NETWORK_DEVICE_OPTIONS[number];
+
 export const normalizeDistroId = (value?: string) => {
   const v = (value || '').toLowerCase().trim();
   if (!v) return '';
@@ -33,10 +53,87 @@ export const normalizeDistroId = (value?: string) => {
   if (v.includes('almalinux')) return 'almalinux';
   if (v.includes('oracle')) return 'oracle';
   if (v.includes('kali')) return 'kali';
+  // Network device vendor IDs may arrive here after detection — preserve them.
+  if ((NETWORK_DEVICE_OPTIONS as readonly string[]).includes(v)) return v;
   if (v === 'linux' || v.includes('linux')) return 'linux';
   return '';
 };
 
+/**
+ * Parse the SSH server identification string (the `software` portion of
+ * `SSH-<protocol>-<software>\r\n`, exposed by ssh2 as `conn._remoteVer`)
+ * and return a normalized network-device vendor ID, or '' if the ident
+ * does not match a known vendor.
+ *
+ * Matching patterns are sourced from the Nmap nmap-service-probes
+ * database (match lines beginning with `match ssh m|^SSH-`), cross-
+ * referenced with the ssh-audit project's software.py and vendor docs.
+ * Only rules whose pattern can be reproduced from those sources are
+ * included here.
+ *
+ * Empty string means "use the fallback linux/macos detection path" —
+ * that is what happens for OpenSSH, Dropbear, JUNOS, Cisco NX-OS, and
+ * Arista EOS, all of which either are POSIX systems or present as
+ * plain `OpenSSH_*` with no distinct vendor marker.
+ */
+export const detectVendorFromSshVersion = (softwareVersion?: string): '' | NetworkDeviceVendor => {
+  const s = (softwareVersion || '').trim();
+  if (!s) return '';
+
+  // Cisco family — IOS, IOS XA, Wireless LAN Controller
+  if (/^Cisco[-_]/i.test(s)) return 'cisco';
+  if (/^CiscoIOS_/i.test(s)) return 'cisco';
+  if (/^CISCO_WLC\b/.test(s)) return 'cisco';
+  // Note: `IPSSH-*` is used by both Cisco and 3Com devices (per Nmap
+  // `match ssh m|^SSH-([\d.]+)-IPSSH-([\d.]+)\|`), so we cannot map it
+  // to a specific vendor icon from the banner alone. Users who want a
+  // custom icon for such devices can set one via the Host Details
+  // manual distro override. The stats-polling gate is still handled
+  // correctly via `host.deviceType === 'network'`.
+
+  // Juniper NetScreen firewall (JUNOS itself uses OpenSSH and is caught
+  // by the fallback failure-counter path in useServerStats).
+  if (/^NetScreen\b/.test(s)) return 'juniper';
+
+  // Huawei VRP and related products
+  if (/^HUAWEI[-_]/i.test(s)) return 'huawei';
+  if (/^VRP-/i.test(s)) return 'huawei';
+
+  // HPE / H3C — Comware switches, Integrated Lights-Out (iLO), legacy 3Com
+  if (/^Comware-/i.test(s)) return 'hpe';
+  if (/^3Com\s*OS/i.test(s)) return 'hpe';
+  if (/^mpSSH_/i.test(s)) return 'hpe';
+
+  // MikroTik RouterOS
+  if (/^ROSSSH\b/.test(s)) return 'mikrotik';
+
+  // Fortinet FortiOS / FortiGate
+  if (/^FortiSSH_/i.test(s)) return 'fortinet';
+
+  // Palo Alto Networks PAN-OS
+  if (/^PaloAltoNetworks[_-]/i.test(s)) return 'paloalto';
+
+  // ZyXEL ZyWALL
+  if (/^Zyxel\s*SSH/i.test(s)) return 'zyxel';
+
+  return '';
+};
+
+/**
+ * Classify a distro/vendor ID into a high-level device class. Features that
+ * assume a POSIX shell (periodic stats polling, /etc/os-release probing, etc.)
+ * should only run when this returns `linux-like`.
+ */
+export type DeviceClass = 'linux-like' | 'network-device' | 'other';
+
+export const classifyDistroId = (distroId?: string): DeviceClass => {
+  const v = (distroId || '').toLowerCase().trim();
+  if (!v) return 'other';
+  if ((NETWORK_DEVICE_OPTIONS as readonly string[]).includes(v)) return 'network-device';
+  if ((LINUX_DISTRO_OPTIONS as readonly string[]).includes(v)) return 'linux-like';
+  return 'other';
+};
+
 export const getEffectiveHostDistro = (
   host?: Pick<Host, 'distro' | 'manualDistro' | 'distroMode'> | null,
 ) => {

domain/models.ts

@@ -394,9 +394,10 @@ export const DEFAULT_KEY_BINDINGS: KeyBinding[] = [
   // Terminal Operations
   { id: 'copy', action: 'copy', label: 'Copy from Terminal', mac: '⌘ + C', pc: 'Ctrl + Shift + C', category: 'terminal' },
   { id: 'paste', action: 'paste', label: 'Paste to Terminal', mac: '⌘ + V', pc: 'Ctrl + Shift + V', category: 'terminal' },
+  { id: 'paste-selection', action: 'pasteSelection', label: 'Paste Selection to Terminal', mac: '⌘ + Shift + X', pc: 'Ctrl + Shift + X', category: 'terminal' },
   { id: 'select-all', action: 'selectAll', label: 'Select All in Terminal', mac: '⌘ + A', pc: 'Ctrl + Shift + A', category: 'terminal' },
   { id: 'clear-buffer', action: 'clearBuffer', label: 'Clear Terminal Buffer', mac: '⌘ + ⌃ + K', pc: 'Ctrl + Shift + K', category: 'terminal' },
-  { id: 'search-terminal', action: 'searchTerminal', label: 'Open Terminal Search', mac: '⌘ + F', pc: 'Ctrl + Shift + F', category: 'terminal' },
+  { id: 'search-terminal', action: 'searchTerminal', label: 'Open Terminal Search', mac: '⌘ + F', pc: 'Ctrl + F', category: 'terminal' },
 
   // Navigation / Split View
   { id: 'move-focus', action: 'moveFocus', label: 'Move focus between Split View panes', mac: '⌘ + ⌥ + arrows', pc: 'Ctrl + Alt + arrows', category: 'navigation' },

domain/sync.ts

@@ -206,6 +206,10 @@ export interface SyncPayload {
     immersiveMode?: boolean;
     // Vault: show recently connected hosts
     showRecentHosts?: boolean;
+    // Vault: root list shows only ungrouped hosts
+    showOnlyUngroupedHostsInRoot?: boolean;
+    // Top tabs: show standalone SFTP view tab
+    showSftpTab?: boolean;
   };
 
   // Sync metadata

domain/terminalAppearance.ts

@@ -41,6 +41,34 @@ export const clearHostFontSizeOverride = (host: Host): Host => ({
 export const resolveHostTerminalThemeId = (host: Host | null | undefined, defaultThemeId: string): string =>
   hasHostThemeOverride(host) && host?.theme ? host.theme : defaultThemeId;
 
+/**
+ * Map a UI theme preset ID to the terminal theme whose background matches
+ * it exactly. Used when "Follow Application Theme" is enabled so the
+ * terminal blends seamlessly with the app chrome. Returns undefined if no
+ * match exists (caller should fall back to the global terminal theme).
+ */
+const UI_TO_TERMINAL_THEME: Record<string, string> = {
+  // Light
+  'snow': 'ui-snow',
+  'pure-white': 'ui-pure-white',
+  'ivory': 'ui-ivory',
+  'mist': 'ui-mist',
+  'mint': 'ui-mint',
+  'sand': 'ui-sand',
+  'lavender': 'ui-lavender',
+  // Dark
+  'pure-black': 'ui-pure-black',
+  'midnight': 'ui-midnight',
+  'deep-blue': 'ui-deep-blue',
+  'vscode': 'ui-vscode',
+  'graphite': 'ui-graphite',
+  'obsidian': 'ui-obsidian',
+  'forest': 'ui-forest',
+};
+
+export const getTerminalThemeForUiTheme = (uiThemeId: string): string | undefined =>
+  UI_TO_TERMINAL_THEME[uiThemeId];
+
 export const resolveHostTerminalFontFamilyId = (host: Host | null | undefined, defaultFontFamilyId: string): string =>
   hasHostFontFamilyOverride(host) && host?.fontFamily ? host.fontFamily : defaultFontFamilyId;
 

domain/vaultImport.ts

@@ -155,6 +155,7 @@ const createHost = (input: {
   label?: string;
   hostname: string;
   username?: string;
+  password?: string;
   port?: number;
   protocol?: Exclude<HostProtocol, "mosh">;
   group?: string;
@@ -167,6 +168,7 @@ const createHost = (input: {
     hostname: input.hostname.trim(),
     port: input.port ?? DEFAULT_SSH_PORT,
     username: input.username?.trim() ?? "",
+    password: input.password || undefined,
     group: normalizeGroupPath(input.group),
     tags: (input.tags ?? []).filter(Boolean),
     os: "linux",
@@ -189,6 +191,7 @@ const dedupeHosts = (hosts: Host[]): { hosts: Host[]; duplicates: number } => {
     duplicates++;
     const mergedTags = Array.from(new Set([...(existing.tags ?? []), ...(host.tags ?? [])]));
     existing.tags = mergedTags;
+    if (!existing.password && host.password) existing.password = host.password;
     if (existing.group == null && host.group != null) existing.group = host.group;
     if (existing.label === existing.hostname && host.label && host.label !== host.hostname) {
       existing.label = host.label;
@@ -333,6 +336,7 @@ const importFromCsv = (text: string): VaultImportResult => {
   const protocolIdx = findHeaderIndex(header, ["protocol", "proto", "scheme"]);
   const portIdx = findHeaderIndex(header, ["port"]);
   const usernameIdx = findHeaderIndex(header, ["username", "user", "login"]);
+  const passwordIdx = findHeaderIndex(header, ["password", "pass", "passwd"]);
 
   if (hostnameIdx === -1) {
     return {
@@ -378,12 +382,14 @@ const importFromCsv = (text: string): VaultImportResult => {
       "ssh";
     const port = parsePort(portIdx >= 0 ? row[portIdx] : undefined) ?? target.port;
     const username = (usernameIdx >= 0 ? row[usernameIdx] : undefined)?.trim() || target.username;
+    const password = (passwordIdx >= 0 ? row[passwordIdx] : undefined) || undefined;
 
     parsedHosts.push(
       createHost({
         label,
         hostname: target.hostname,
         username,
+        password,
         port,
         protocol,
         group,
@@ -993,12 +999,12 @@ export const getVaultCsvTemplate = (
   opts: VaultCsvTemplateOptions = {},
 ): string => {
   const includeExampleRows = opts.includeExampleRows !== false;
-  const header = ["Groups", "Label", "Tags", "Hostname/IP", "Protocol", "Port", "Username"];
+  const header = ["Groups", "Label", "Tags", "Hostname/IP", "Protocol", "Port", "Username", "Password"];
   const rows: string[][] = [header];
   if (includeExampleRows) {
-    rows.push(["Project/Dev", "Web Server (dev)", "dev,web", "192.168.1.10", "ssh", "22", "root"]);
-    rows.push(["Project/Prod", "Web Server (prod)", "prod,web", "server-a.example.com", "ssh", "22", "ubuntu"]);
-    rows.push(["Database", "DB", "db,mysql", "db.example.com", "ssh", "4567", "admin"]);
+    rows.push(["Project/Dev", "Web Server (dev)", "dev,web", "192.168.1.10", "ssh", "22", "root", ""]);
+    rows.push(["Project/Prod", "Web Server (prod)", "prod,web", "server-a.example.com", "ssh", "22", "ubuntu", ""]);
+    rows.push(["Database", "DB", "db,mysql", "db.example.com", "ssh", "4567", "admin", ""]);
   }
 
   const escapeCsv = (value: string) => {
@@ -1011,13 +1017,14 @@ export const getVaultCsvTemplate = (
 };
 
 const exportHostsToCsv = (hosts: Host[]): string => {
-  const header = ["Groups", "Label", "Tags", "Hostname/IP", "Protocol", "Port", "Username"];
+  const header = ["Groups", "Label", "Tags", "Hostname/IP", "Protocol", "Port", "Username", "Password"];
   const rows: string[][] = [header];
 
-  const escapeCsv = (value: string) => {
+  const escapeCsv = (value: string, skipFormulaGuard = false) => {
     // Prevent CSV formula injection by prefixing dangerous characters with a single quote
     // These characters can be interpreted as formulas by spreadsheet applications
-    if (/^[=+\-@\t\r]/.test(value)) {
+    // Skip for password fields to preserve credentials verbatim for round-trip
+    if (!skipFormulaGuard && /^[=+\-@\t\r]/.test(value)) {
       value = "'" + value;
     }
     if (value.includes('"')) value = value.replace(/"/g, '""');
@@ -1059,10 +1066,12 @@ const exportHostsToCsv = (hosts: Host[]): string => {
       host.protocol ?? "ssh",
       String(effectivePort),
       effectiveUsername,
+      host.password ?? "",
     ]);
   }
 
-  return rows.map((r) => r.map((c) => escapeCsv(c)).join(",")).join("\r\n") + "\r\n";
+  const passwordColIdx = header.indexOf("Password");
+  return rows.map((r, rowIdx) => r.map((c, i) => escapeCsv(c, rowIdx > 0 && i === passwordColIdx)).join(",")).join("\r\n") + "\r\n";
 };
 
 interface ExportHostsResult {

electron-builder.config.cjs

@@ -21,6 +21,7 @@ module.exports = {
         'electron/**/*',
         'lib/**/*.cjs',
         '!electron/.dev-config.json',
+        'skills/**/*',
         'public/**/*',
         'node_modules/**/*'
     ],
@@ -41,7 +42,10 @@ module.exports = {
         'node_modules/fast-deep-equal/**/*',
         'node_modules/fast-uri/**/*',
         'node_modules/json-schema-traverse/**/*',
+        'electron/cli/**/*',
         'electron/mcp/**/*'
+        ,
+        'skills/**/*'
     ],
     mac: {
         target: [
@@ -83,9 +87,16 @@ module.exports = {
             {
                 target: 'nsis',
                 arch: ['x64', 'arm64']
+            },
+            {
+                target: 'portable',
+                arch: ['x64', 'arm64']
             }
         ]
     },
+    portable: {
+        artifactName: '${productName}-${version}-portable-${os}-${arch}.${ext}',
+    },
     nsis: {
         oneClick: false,
         perMachine: false,

electron/bridges/ai/codexHelpers.cjs

@@ -8,7 +8,8 @@
 
 const { execFileSync } = require("node:child_process");
 const { createHash } = require("node:crypto");
-const { existsSync } = require("node:fs");
+const { existsSync, readFileSync } = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 
 const { stripAnsi, extractFirstNonLocalhostUrl, toUnpackedAsarPath } = require("./shellUtils.cjs");
@@ -82,13 +83,13 @@ function resolveCodexAcpBinaryPath(shellEnv, electronModule) {
   // Packaged build (or dev fallback): use npm-bundled binary
   try {
     const pkgName = getCodexPackageName();
-    if (!pkgName) return binaryName;
+    if (!pkgName) return null;
 
     const pkgRoot = path.dirname(require.resolve("@zed-industries/codex-acp/package.json"));
     const resolved = require.resolve(`${pkgName}/bin/${binaryName}`, { paths: [pkgRoot] });
     return toUnpackedAsarPath(resolved);
   } catch {
-    return binaryName;
+    return null;
   }
 }
 
@@ -124,6 +125,212 @@ function getActiveCodexLoginSession() {
   return null;
 }
 
+// ── Codex config.toml probing ──
+//
+// Users who hand-configure `~/.codex/config.toml` with a custom
+// `model_provider` + matching `[model_providers.<name>]` entry are fully
+// functional from the Codex CLI, but `codex login status` doesn't see them
+// because it only reports on `~/.codex/auth.json` (populated by `codex login`).
+// We read and minimally parse the config file so we can surface this as a
+// valid "ready" state and skip the ChatGPT login prompt in the UI.
+
+/** Find `#` outside quoted regions. Tracks escape state via a flag rather
+ *  than peeking at the previous character, so even runs of backslashes like
+ *  `"C:\\path\\"` close the string correctly. Literal (single-quoted) TOML
+ *  strings don't recognize `\` as an escape, so only honor escapes inside
+ *  basic (double-quoted) strings. */
+function findUnquotedHash(value) {
+  let inStr = false;
+  let quote = "";
+  let escaped = false;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (inStr) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (quote === '"' && ch === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (ch === quote) {
+        inStr = false;
+        quote = "";
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inStr = true;
+      quote = ch;
+      continue;
+    }
+    if (ch === "#") return i;
+  }
+  return -1;
+}
+
+/**
+ * Parse the narrow subset of TOML we need from Codex's config.toml:
+ *   - top-level string keys (e.g. `model_provider = "my_provider"`)
+ *   - `[model_providers.<name>]` tables with string-valued keys
+ * Unsupported TOML features (arrays, inline tables, multi-line strings, etc.)
+ * are ignored — Codex's config.toml doesn't use them for provider definitions.
+ */
+function parseCodexConfigToml(text) {
+  const result = { model_providers: {} };
+  let currentProvider = null;
+  let atTopLevel = true;
+
+  // Strip UTF-8 BOM so the first key still matches the regex on Windows-edited files.
+  const normalized = String(text || "").replace(/^\uFEFF/, "");
+  const lines = normalized.split(/\r?\n/);
+  for (const rawLine of lines) {
+    let line = rawLine;
+    const hashIdx = findUnquotedHash(line);
+    if (hashIdx >= 0) line = line.slice(0, hashIdx);
+    line = line.trim();
+    if (!line) continue;
+
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      const section = sectionMatch[1].trim();
+      if (section.startsWith("model_providers.")) {
+        currentProvider = section.slice("model_providers.".length);
+        if (!result.model_providers[currentProvider]) {
+          result.model_providers[currentProvider] = {};
+        }
+        atTopLevel = false;
+      } else {
+        currentProvider = null;
+        atTopLevel = false;
+      }
+      continue;
+    }
+
+    const kvMatch = line.match(/^([A-Za-z_][\w.-]*)\s*=\s*(.+)$/);
+    if (!kvMatch) continue;
+    const key = kvMatch[1];
+    let raw = kvMatch[2].trim();
+    let value;
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+      value = raw.slice(1, -1);
+    } else {
+      value = raw;
+    }
+
+    if (atTopLevel) {
+      result[key] = value;
+    } else if (currentProvider) {
+      result.model_providers[currentProvider][key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Inspect `~/.codex/config.toml` to determine whether the user has
+ * configured a custom `model_provider` that isn't the built-in OpenAI/ChatGPT
+ * path.
+ *
+ * Returns null when:
+ *   - the config file doesn't exist or can't be read
+ *   - no `model_provider` is set, or it points to the default `openai` preset
+ *   - the referenced provider entry is missing (config is malformed)
+ *
+ * Returns a summary object otherwise — even if the env_key isn't currently
+ * exported in the shell environment. That case is surfaced via
+ * `envKeyPresent: false` so the UI can warn the user; we don't want the
+ * absence of an env var to silently fall back to the ChatGPT login flow,
+ * because the config.toml is a strong signal the user doesn't want that.
+ */
+function readCodexCustomProviderConfig(shellEnv) {
+  const home = shellEnv?.HOME || shellEnv?.USERPROFILE || os.homedir();
+  if (!home) return null;
+  const configPath = path.join(home, ".codex", "config.toml");
+  if (!existsSync(configPath)) return null;
+
+  let text;
+  try {
+    text = readFileSync(configPath, "utf8");
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = parseCodexConfigToml(text);
+  } catch {
+    return null;
+  }
+
+  const activeName = typeof parsed.model_provider === "string"
+    ? parsed.model_provider.trim()
+    : "";
+  if (!activeName) return null;
+  // The built-in "openai" provider still goes through ChatGPT/API-key auth
+  // managed by `codex login`, so treating it as "custom" would be wrong.
+  if (activeName === "openai") return null;
+
+  const providerEntry = parsed.model_providers?.[activeName];
+  if (!providerEntry) return null;
+
+  const envKeyName = typeof providerEntry.env_key === "string" ? providerEntry.env_key.trim() : "";
+  const envKeyValue = envKeyName && shellEnv ? String(shellEnv[envKeyName] || "").trim() : "";
+  const hardcodedApiKey = typeof providerEntry.api_key === "string" ? providerEntry.api_key.trim() : "";
+  const activeModel = typeof parsed.model === "string" ? parsed.model.trim() : "";
+
+  // Hash the actual auth material (either the hardcoded api_key or the
+  // resolved env_key value) so the ACP provider fingerprint changes when
+  // the user rotates their key — without ever returning the raw value
+  // across the IPC boundary.
+  const authMaterial = hardcodedApiKey || envKeyValue;
+  const authHash = authMaterial
+    ? createHash("sha256").update(authMaterial).digest("hex")
+    : null;
+
+  return {
+    providerName: activeName,
+    displayName: providerEntry.name || activeName,
+    baseUrl: providerEntry.base_url || null,
+    envKey: envKeyName || null,
+    envKeyPresent: Boolean(envKeyValue),
+    hasHardcodedApiKey: Boolean(hardcodedApiKey),
+    model: activeModel || null,
+    authHash,
+  };
+}
+
+/**
+ * Returns a user-facing error message when a Codex config.toml custom
+ * provider references an env_key that isn't exported in the shell env and
+ * doesn't have a hardcoded api_key either — otherwise returns null. Shared
+ * by every spawn path (stream handler, list-models handler) so users get
+ * the same actionable message regardless of which one hits first.
+ */
+function getCodexCustomConfigPreflightError(customConfig) {
+  if (!customConfig) return null;
+  if (!customConfig.envKey) return null;
+  if (customConfig.envKeyPresent || customConfig.hasHardcodedApiKey) return null;
+  return `Codex is configured to use the "${customConfig.displayName}" provider from ~/.codex/config.toml, but the environment variable ${customConfig.envKey} is not set. Export it in your shell (e.g. add to ~/.zshrc) and click "Refresh Status" in Settings.`;
+}
+
+/**
+ * Compute the ACP auth override object for Codex spawn sites.
+ *   - netcatty-managed API key present → "codex-api-key"
+ *   - user's own ~/.codex/config.toml custom provider detected → no override
+ *     (so codex-acp resolves auth from the shell env / config itself)
+ *   - otherwise → "chatgpt" (triggers the browser OAuth login flow)
+ *
+ * Returned as an object designed to be spread into createACPProvider options.
+ */
+function getCodexAuthOverride(apiKey, shellEnv) {
+  if (apiKey) return { authMethodId: "codex-api-key" };
+  if (readCodexCustomProviderConfig(shellEnv)) return {};
+  return { authMethodId: "chatgpt" };
+}
+
 // ── Integration state ──
 
 function normalizeCodexIntegrationState(rawOutput) {
@@ -199,6 +406,9 @@ module.exports = {
   toCodexLoginSessionResponse,
   getActiveCodexLoginSession,
   normalizeCodexIntegrationState,
+  readCodexCustomProviderConfig,
+  getCodexAuthOverride,
+  getCodexCustomConfigPreflightError,
   extractCodexError,
   isCodexAuthError,
   getCodexAuthFingerprint,

electron/bridges/ai/ptyExec.cjs

@@ -88,7 +88,7 @@ function buildWrappedCommand(command, shellKind, marker) {
         `set ${marker} 0; function __ncmcp_int --on-signal INT; printf '%s\\n' '${marker}_E:130'; functions -e __ncmcp_int; end; ` +
         `set -l ${marker}_cmd '${escapeFishSingleQuoted(command)}'; ` +
         `begin; set -gx PAGER cat; set -gx SYSTEMD_PAGER ''; set -gx GIT_PAGER cat; set -gx LESS ''; ` +
-        `printf '%s\\n' '${marker}_S'; eval -- \$${marker}_cmd; set __NCMCP_rc $status; ` +
+        `printf '%s\\n' '${marker}_S'; eval \$${marker}_cmd; set __NCMCP_rc $status; ` +
         `functions -e __ncmcp_int; printf '%s\\n' '${marker}_E:'\$__NCMCP_rc; end\n`
       );
 
@@ -145,6 +145,668 @@ function findEndMarker(outputText, marker) {
   return null;
 }
 
+function normalizePtyOutput(stdout, {
+  stripMarkers = false,
+  expectedPrompt = "",
+  trimOutput = true,
+  stripPrompt = true,
+  markerToStrip = null,
+} = {}) {
+  let cleaned = stripAnsi(stdout || "").replace(/\r/g, "");
+  if (stripMarkers) {
+    // Prefer the job-specific marker so user output that contains "__NCMCP_"
+    // (e.g. printf '__NCMCP_demo\n') is preserved.
+    const pattern = markerToStrip
+      ? new RegExp(`^[^\r\n]*${markerToStrip}[^\r\n]*[\r\n]*`, "gm")
+      : /^[^\r\n]*__NCMCP_[^\r\n]*[\r\n]*/gm;
+    cleaned = cleaned.replace(pattern, "");
+  }
+  const normalizedPrompt = stripAnsi(String(expectedPrompt || "")).replace(/\r/g, "");
+  if (stripPrompt && normalizedPrompt && cleaned.endsWith(normalizedPrompt)) {
+    cleaned = cleaned.slice(0, cleaned.length - normalizedPrompt.length);
+  }
+  return trimOutput ? cleaned.trim() : cleaned;
+}
+
+function appendBoundedOutput(current, chunk, maxBufferedChars) {
+  const combined = `${current || ""}${chunk || ""}`;
+  const limit = Number.isFinite(maxBufferedChars) ? Math.max(0, Math.floor(maxBufferedChars)) : 0;
+  if (limit <= 0 || combined.length <= limit) {
+    return { text: combined, dropped: 0 };
+  }
+  const dropped = combined.length - limit;
+  return {
+    text: combined.slice(dropped),
+    dropped,
+  };
+}
+
+function consumeVisibleText(carry, chunk) {
+  const input = `${carry || ""}${chunk || ""}`;
+  if (!input) {
+    return { visibleText: "", carry: "" };
+  }
+
+  let visibleText = "";
+  let index = 0;
+
+  while (index < input.length) {
+    const ch = input[index];
+
+    if (ch === "\r") {
+      // Preserve \r so consumers / serializers can collapse progress-bar
+      // redraws to the latest frame. \r\n becomes a single \n.
+      if (input[index + 1] === "\n") {
+        visibleText += "\n";
+        index += 2;
+        continue;
+      }
+      visibleText += "\r";
+      index += 1;
+      continue;
+    }
+
+    if (ch !== "\u001b") {
+      visibleText += ch;
+      index += 1;
+      continue;
+    }
+
+    if (index + 1 >= input.length) {
+      break;
+    }
+
+    const next = input[index + 1];
+
+    if (next === "[") {
+      let cursor = index + 2;
+      let complete = false;
+      while (cursor < input.length) {
+        const code = input.charCodeAt(cursor);
+        if (code >= 0x40 && code <= 0x7e) {
+          index = cursor + 1;
+          complete = true;
+          break;
+        }
+        cursor += 1;
+      }
+      if (!complete) break;
+      continue;
+    }
+
+    if (next === "]") {
+      let cursor = index + 2;
+      let complete = false;
+      while (cursor < input.length) {
+        const oscChar = input[cursor];
+        if (oscChar === "\u0007") {
+          index = cursor + 1;
+          complete = true;
+          break;
+        }
+        if (oscChar === "\u001b") {
+          if (cursor + 1 >= input.length) break;
+          if (input[cursor + 1] === "\\") {
+            index = cursor + 2;
+            complete = true;
+            break;
+          }
+        }
+        cursor += 1;
+      }
+      if (!complete) break;
+      continue;
+    }
+
+    visibleText += ch;
+    index += 1;
+  }
+
+  return {
+    visibleText,
+    carry: input.slice(index),
+  };
+}
+
+function startPtyJob(ptyStream, command, options) {
+  const {
+    stripMarkers = false,
+    trackForCancellation = null,
+    timeoutMs = 60000,
+    shellKind,
+    chatSessionId,
+    abortSignal,
+    expectedPrompt,
+    typedInput = false,
+    echoCommand,
+    maxBufferedChars = 0,
+    normalizeFinalOutput = true,
+    enforceWallTimeout = false,
+  } = options || {};
+
+  const marker = `__NCMCP_${Date.now().toString(36)}_${crypto.randomBytes(16).toString('hex')}__`;
+  const resolvedShellKind = shellKind || "posix";
+  const CANCEL_RETRY_MS = 5000;
+  const CANCEL_WALL_TIMEOUT_MS = 30000;
+
+  let output = "";
+  let foundStart = false;
+  let preStartOutput = "";
+  let visibleOutput = "";
+  let visibleOutputOffset = 0;
+  // Monotonic high-water mark for the visible byte stream. Increases on every
+  // append; never decreases when CR redraws collapse visibleOutput. Used as
+  // the polling nextOffset so callers' offsets stay monotonic.
+  let visibleHighWatermark = 0;
+  let visibleCarry = "";
+  let timeoutId = null;
+  let wallTimeoutId = null;
+  let startupTimeoutId = null;
+  let promptFallbackTimer = null;
+  let cancelRetryTimerId = null;
+  // Track one-shot timers scheduled inside requestCancel so finish() can
+  // clear them when the job exits early; otherwise they keep the Node
+  // event loop alive after the resultPromise has already resolved.
+  const cancelOneShotTimers = [];
+  let cancelRequested = false;
+  let finished = false;
+  let unsubscribe = null;
+  const cleanupFns = [];
+  let pendingStart = "";
+  let resolveResult;
+  const resultPromise = new Promise((resolve) => {
+    resolveResult = resolve;
+  });
+
+  function clearPromptFallback() {
+    if (promptFallbackTimer) {
+      clearTimeout(promptFallbackTimer);
+      promptFallbackTimer = null;
+    }
+  }
+
+  function clearCancelRetryTimer() {
+    if (cancelRetryTimerId) {
+      clearTimeout(cancelRetryTimerId);
+      cancelRetryTimerId = null;
+    }
+  }
+
+  function armOutputTimeout() {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      sendInterrupt();
+      if (cancelRequested) {
+        armOutputTimeout();
+        return;
+      }
+      const timeoutSec = Math.round(timeoutMs / 1000);
+      finish(foundStart ? output : preStartOutput, -1, `Command timed out after ${timeoutSec}s without output`);
+    }, timeoutMs);
+  }
+
+  // Hard wall-clock deadline: opt-in via enforceWallTimeout. Used by callers
+  // that have a strict tool-call budget (e.g. MCP terminal_execute, where the
+  // model can fall back to terminal_start). Default is off so existing
+  // foreground execution paths (Catty Agent) keep their inactivity-based
+  // timeout for long-running streaming commands.
+  function armWallTimeout() {
+    if (!enforceWallTimeout || maxBufferedChars > 0) return;
+    wallTimeoutId = setTimeout(() => {
+      if (finished) return;
+      sendInterrupt();
+      const timeoutSec = Math.round(timeoutMs / 1000);
+      finish(foundStart ? output : preStartOutput, -1, `Command timed out (${timeoutSec}s)`);
+    }, timeoutMs);
+  }
+
+  // Bounded startup deadline: we always need a hard limit on how long we
+  // wait for the wrapped command's start marker. Otherwise an already-chatty
+  // PTY (e.g. a tab running tail -f) would let onData re-arm the inactivity
+  // timer forever before _S arrives, hanging the call and the session lock.
+  // Foreground execs use the configured timeoutMs as the deadline (matching
+  // the pre-PR behavior); background jobs use a fixed 30s since their main
+  // timeout is much longer (1 hour) and meant for the actual command.
+  const BG_STARTUP_TIMEOUT_MS = 30000;
+  function armStartupTimeout() {
+    const startupMs = maxBufferedChars > 0 ? BG_STARTUP_TIMEOUT_MS : timeoutMs;
+    startupTimeoutId = setTimeout(() => {
+      if (finished || foundStart) return;
+      sendInterrupt();
+      const label = maxBufferedChars > 0 ? "Background job startup" : "Command startup";
+      finish(preStartOutput, -1, `${label} timed out — start marker never arrived`);
+    }, startupMs);
+  }
+  function clearStartupTimeout() {
+    if (startupTimeoutId) {
+      clearTimeout(startupTimeoutId);
+      startupTimeoutId = null;
+    }
+  }
+
+  function sendInterrupt() {
+    try {
+      if (typeof ptyStream.signal === "function") {
+        ptyStream.signal("INT");
+      }
+    } catch {
+      // Ignore signal failures and fall back to ETX.
+    }
+    try {
+      if (typeof ptyStream.write === "function") {
+        ptyStream.write("\x03");
+      }
+    } catch {
+      // Ignore PTY write failures during cancellation.
+    }
+  }
+
+  function requestCancel() {
+    if (finished || cancelRequested) return;
+    cancelRequested = true;
+    clearPromptFallback();
+    clearCancelRetryTimer();
+    // Cancel the startup timer too — otherwise a pre-start cancel resolves
+    // as "Background job startup timed out" instead of "Cancelled".
+    clearStartupTimeout();
+    // For pre-start cancellation on sessions without a known idle prompt,
+    // schedule a short fallback to finish the job after Ctrl+C has had time
+    // to take effect. Without this, the cancel waits the full forced-cancel
+    // window even though the shell may have returned to idle quickly.
+    if (!foundStart && !expectedPrompt) {
+      const t = setTimeout(() => {
+        if (finished || foundStart) return;
+        finish(preStartOutput, 130, "Cancelled");
+      }, 2000);
+      cancelOneShotTimers.push(t);
+    }
+    sendInterrupt();
+    cancelRetryTimerId = setTimeout(function retryCancel() {
+      if (finished || !cancelRequested) return;
+      sendInterrupt();
+      cancelRetryTimerId = setTimeout(retryCancel, CANCEL_RETRY_MS);
+    }, CANCEL_RETRY_MS);
+    armOutputTimeout();
+    const t150 = setTimeout(() => {
+      if (!finished) sendInterrupt();
+    }, 150);
+    cancelOneShotTimers.push(t150);
+    // Hard wall-clock deadline for cancellation: if the process ignores
+    // Ctrl+C and never redraws the prompt, force-finish after a bounded
+    // period so the session is not stuck in "stopping" forever.
+    // Mark as "forced" so callers can tell the shell may still be busy.
+    const tWall = setTimeout(() => {
+      if (!finished) {
+        finish(foundStart ? output : preStartOutput, 130, "Cancelled (forced — process may still be running)");
+      }
+    }, CANCEL_WALL_TIMEOUT_MS);
+    cancelOneShotTimers.push(tWall);
+  }
+
+  function schedulePromptFallback() {
+    clearPromptFallback();
+    if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
+    // Background jobs use a much longer delay (30s) so commands that open
+    // child shells / REPLs with the same prompt have time to print past
+    // their initial prompt and avoid being misdetected as completed.
+    // Foreground execs use 250ms to match the pre-PR behavior.
+    const delayMs = maxBufferedChars > 0 ? 30000 : 250;
+    promptFallbackTimer = setTimeout(() => {
+      if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
+      finish(output, null, null);
+    }, delayMs);
+  }
+
+  function checkEnd() {
+    const found = findEndMarker(output, marker);
+    if (!found) return;
+    const stdout = output.slice(0, found.endIdx);
+    finish(stdout, found.exitCode);
+  }
+
+  // Carry buffer for incomplete marker lines split across chunks.
+  let visibleMarkerCarry = "";
+
+  // Note: we intentionally do NOT collapse CR redraws in visibleOutput.
+  // Doing so makes polling offsets non-monotonic and can drop finalized
+  // lines after a CR rewrite. Instead, the buffer stores raw bytes
+  // (including \r) and the bounded-buffer cap (256KB) keeps progress-bar
+  // accumulation under control. Consumers that want a "collapsed" view
+  // can apply CR processing themselves.
+
+  function appendToVisible(text) {
+    if (!text) return;
+    const normalized = consumeVisibleText(visibleCarry, text);
+    visibleCarry = normalized.carry;
+    if (!normalized.visibleText) return;
+
+    let cleanVisible = normalized.visibleText;
+    if (maxBufferedChars > 0) {
+      // Rejoin with any incomplete line from the previous chunk so marker
+      // lines split across PTY data boundaries are matched as a whole.
+      cleanVisible = visibleMarkerCarry + cleanVisible;
+      visibleMarkerCarry = "";
+      // We must withhold any trailing line that *might* be the start of an
+      // internal marker line, even if the random marker token isn't fully
+      // present yet (the chunk boundary may split the marker mid-token).
+      // Detect this by looking for the constant prefix "__NCMCP_" — only
+      // user output that *contains an unrelated __NCMCP_ string and ends
+      // with a newline* will be preserved through the next strip step.
+      const NCMCP_PREFIX = "__NCMCP_";
+      const lastNl = cleanVisible.lastIndexOf("\n");
+      if (lastNl === -1) {
+        if (cleanVisible.includes(NCMCP_PREFIX)) {
+          visibleMarkerCarry = cleanVisible;
+          return;
+        }
+      } else if (lastNl < cleanVisible.length - 1) {
+        const trailing = cleanVisible.slice(lastNl + 1);
+        if (trailing.includes(NCMCP_PREFIX)) {
+          visibleMarkerCarry = trailing;
+          cleanVisible = cleanVisible.slice(0, lastNl + 1);
+        }
+      }
+      // Strip only this job's specific marker lines so user output that
+      // happens to contain "__NCMCP_" (e.g. printf '__NCMCP_demo\n') is
+      // preserved.
+      cleanVisible = cleanVisible.replace(new RegExp(`^[^\r\n]*${marker}[^\r\n]*[\r\n]*`, "gm"), "");
+      if (!cleanVisible) return;
+    }
+    visibleHighWatermark += cleanVisible.length;
+    const next = appendBoundedOutput(visibleOutput, cleanVisible, maxBufferedChars);
+    visibleOutput = next.text;
+    visibleOutputOffset += next.dropped;
+  }
+
+  function appendToOutput(text) {
+    if (!text) return;
+    const next = appendBoundedOutput(output, text, maxBufferedChars);
+    output = next.text;
+    appendToVisible(text);
+  }
+
+  function finish(stdout, exitCode, error) {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timeoutId);
+    clearTimeout(wallTimeoutId);
+    clearStartupTimeout();
+    clearPromptFallback();
+    clearCancelRetryTimer();
+    // Clear any pending one-shot cancel timers so they do not keep the
+    // Node event loop alive after the job has resolved.
+    while (cancelOneShotTimers.length) {
+      clearTimeout(cancelOneShotTimers.pop());
+    }
+    unsubscribe?.();
+    for (const fn of cleanupFns) {
+      try {
+        fn();
+      } catch {
+        // Ignore cleanup failures
+      }
+    }
+    if (trackForCancellation) {
+      trackForCancellation.delete(marker);
+    }
+
+    // Flush any incomplete marker carry — if it wasn't this job's marker, append it.
+    if (visibleMarkerCarry) {
+      const leftover = visibleMarkerCarry.replace(new RegExp(`^[^\r\n]*${marker}[^\r\n]*[\r\n]*`, "gm"), "");
+      visibleMarkerCarry = "";
+      if (leftover) {
+        const next = appendBoundedOutput(visibleOutput, leftover, maxBufferedChars);
+        visibleOutput = next.text;
+        visibleOutputOffset += next.dropped;
+      }
+    }
+
+    // For background jobs (maxBufferedChars > 0), use the already-stripped
+    // visibleOutput so completion offsets are consistent with polling offsets.
+    // Re-normalizing from the raw buffer would produce a shorter result because
+    // ANSI codes inflate the raw buffer, causing it to truncate earlier.
+    let cleaned;
+    let outputBaseOffset;
+    let totalOutputChars;
+    if (maxBufferedChars > 0 && foundStart) {
+      // Always strip this job's markers from the visible buffer — it accumulates
+      // raw PTY data including the end-marker line that must not leak to callers.
+      const strippedVisible = normalizePtyOutput(visibleOutput, {
+        stripMarkers: true,
+        markerToStrip: marker,
+        expectedPrompt,
+        trimOutput: normalizeFinalOutput,
+        stripPrompt: true,
+      });
+      cleaned = strippedVisible;
+      outputBaseOffset = visibleOutputOffset;
+      totalOutputChars = outputBaseOffset + visibleOutput.length;
+    } else {
+      const visibleStdout = normalizePtyOutput(stdout, {
+        stripMarkers,
+        markerToStrip: marker,
+        expectedPrompt,
+        trimOutput: false,
+        stripPrompt: true,
+      });
+      cleaned = normalizeFinalOutput
+        ? normalizePtyOutput(stdout, {
+          stripMarkers,
+          markerToStrip: marker,
+          expectedPrompt,
+          trimOutput: true,
+          stripPrompt: true,
+        })
+        : visibleStdout;
+      outputBaseOffset = foundStart ? visibleOutputOffset : 0;
+      totalOutputChars = outputBaseOffset + visibleStdout.length;
+    }
+    const finalError = (!error && cancelRequested) ? "Cancelled" : error;
+    const finalExitCode = finalError === "Cancelled" ? (exitCode ?? 130) : exitCode;
+    if (finalError) {
+      resolveResult({
+        ok: false,
+        stdout: cleaned,
+        stderr: "",
+        exitCode: finalExitCode ?? -1,
+        error: finalError,
+        outputBaseOffset,
+        totalOutputChars,
+        outputTruncated: outputBaseOffset > 0,
+      });
+    } else {
+      resolveResult({
+        ok: exitCode === 0 || exitCode === null,
+        stdout: cleaned,
+        stderr: "",
+        exitCode: finalExitCode ?? 0,
+        outputBaseOffset,
+        totalOutputChars,
+        outputTruncated: outputBaseOffset > 0,
+      });
+    }
+  }
+
+  function onData(data) {
+    const text = data.toString();
+    armOutputTimeout();
+
+    if (!foundStart) {
+      preStartOutput += text;
+      // Cap preStartOutput for background jobs so a noisy idle PTY can't
+      // accumulate megabytes before the start marker arrives. We only need
+      // enough tail to find the marker boundary.
+      if (maxBufferedChars > 0 && preStartOutput.length > maxBufferedChars) {
+        preStartOutput = preStartOutput.slice(preStartOutput.length - maxBufferedChars);
+      }
+      const combined = pendingStart + text;
+      pendingStart = "";
+      const startMarker = marker + "_S";
+      let matched = false;
+
+      const lines = combined.split(/\r?\n/);
+      const trailingPartial = /[\r\n]$/.test(combined) ? "" : lines.pop() || "";
+      for (const line of lines) {
+        if (stripAnsi(line).trim() === startMarker) {
+          foundStart = true;
+          matched = true;
+          break;
+        }
+      }
+      pendingStart = trailingPartial;
+
+      if (foundStart) {
+        clearStartupTimeout();
+        // Use the *last* occurrence of the start marker to skip the echoed
+        // wrapper command and capture only output after the real printf line.
+        const markerPattern = new RegExp(`${marker}_S[^\n\r]*(?:\r?\n|$)`, "g");
+        let boundary = -1;
+        let m;
+        while ((m = markerPattern.exec(preStartOutput)) !== null) {
+          boundary = m.index;
+        }
+        if (boundary !== -1) {
+          const afterBoundary = preStartOutput.slice(boundary);
+          const firstNl = afterBoundary.search(/\r?\n/);
+          const initialOutput = firstNl === -1 ? "" : afterBoundary.slice(firstNl).replace(/^\r?\n/, "");
+          output = "";
+          visibleOutput = "";
+          visibleOutputOffset = 0;
+          visibleCarry = "";
+          appendToOutput(initialOutput);
+        }
+        preStartOutput = "";
+        schedulePromptFallback();
+        checkEnd();
+        return;
+      }
+
+      if (!matched) {
+        const fallbackEnd = findEndMarker(preStartOutput, marker);
+        if (fallbackEnd) {
+          let stdout = preStartOutput.slice(0, fallbackEnd.endIdx);
+          const lastStartIdx = stdout.lastIndexOf(startMarker);
+          if (lastStartIdx !== -1) {
+            const nlAfterStart = stdout.indexOf("\n", lastStartIdx);
+            if (nlAfterStart !== -1) {
+              stdout = stdout.slice(nlAfterStart + 1);
+            }
+          }
+          finish(stdout, fallbackEnd.exitCode);
+          return;
+        }
+      }
+      // If we're cancelling a still-queued command and the shell has returned
+      // to its idle prompt, finish immediately as Cancelled instead of waiting
+      // for the cancel wall-clock timer.
+      if (cancelRequested && hasExpectedPromptSuffix(preStartOutput, expectedPrompt)) {
+        finish(preStartOutput, 130, "Cancelled");
+        return;
+      }
+      return;
+    }
+
+    appendToOutput(text);
+    if (!cancelRequested) {
+      schedulePromptFallback();
+    } else if (hasExpectedPromptSuffix(output, expectedPrompt)) {
+      finish(output, 130, "Cancelled");
+      return;
+    }
+    checkEnd();
+  }
+
+  if (abortSignal?.aborted) {
+    finish("", -1, "Cancelled");
+    return {
+      marker,
+      cancel: () => {},
+      getSnapshot: () => ({ stdout: "", status: "cancelled", foundStart: false }),
+      resultPromise,
+    };
+  }
+
+  armOutputTimeout();
+  armWallTimeout();
+  armStartupTimeout();
+
+  unsubscribe = subscribeToPtyData(ptyStream, onData);
+
+  const cancel = () => {
+    requestCancel();
+  };
+
+  if (trackForCancellation) {
+    trackForCancellation.set(marker, {
+      ptyStream,
+      chatSessionId: chatSessionId || null,
+      cancel,
+      cleanup: () => {
+        clearTimeout(timeoutId);
+        unsubscribe?.();
+      },
+    });
+  }
+
+  if (typeof ptyStream.on === "function") {
+    const onClose = () => finish(foundStart ? output : preStartOutput, null, cancelRequested ? "Cancelled" : "Stream closed unexpectedly");
+    const onError = (err) => finish(foundStart ? output : preStartOutput, -1, cancelRequested ? "Cancelled" : `Stream error: ${err?.message || err}`);
+    ptyStream.on("close", onClose);
+    ptyStream.on("end", onClose);
+    ptyStream.on("error", onError);
+    cleanupFns.push(() => {
+      try { ptyStream.removeListener("close", onClose); } catch {}
+      try { ptyStream.removeListener("end", onClose); } catch {}
+      try { ptyStream.removeListener("error", onError); } catch {}
+    });
+  }
+  if (typeof ptyStream.onExit === "function") {
+    const disposable = ptyStream.onExit(() => finish(foundStart ? output : preStartOutput, null, cancelRequested ? "Cancelled" : "Process exited"));
+    cleanupFns.push(() => {
+      try {
+        disposable?.dispose?.();
+      } catch {
+        // Ignore cleanup failures
+      }
+    });
+  }
+
+  if (abortSignal) {
+    const onAbort = () => {
+      requestCancel();
+    };
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    cleanupFns.push(() => abortSignal.removeEventListener("abort", onAbort));
+  }
+
+  if (typedInput && typeof echoCommand === "function") {
+    try {
+      echoCommand(command);
+    } catch {
+      // Ignore synthetic echo failures.
+    }
+  }
+
+  ptyStream.write(buildWrappedCommand(command, resolvedShellKind, marker));
+
+  return {
+    marker,
+    cancel,
+    // Until the start marker arrives, return empty stdout/zero offsets so
+    // an early poll cannot advance nextOffset past pre-start PTY noise that
+    // gets discarded once the real command begins.
+    getSnapshot: () => ({
+      stdout: foundStart ? visibleOutput : "",
+      outputBaseOffset: foundStart ? visibleOutputOffset : 0,
+      totalOutputChars: foundStart ? visibleOutputOffset + visibleOutput.length : 0,
+      outputTruncated: foundStart ? visibleOutputOffset > 0 : false,
+      status: finished ? "finished" : (cancelRequested ? "stopping" : "running"),
+      foundStart,
+    }),
+    resultPromise,
+  };
+}
+
 /**
  * Execute command through a terminal PTY stream.
  * The user sees the command typed and output in their terminal.
@@ -163,228 +825,7 @@ function findEndMarker(outputText, marker) {
  * @param {(command: string) => void} [options.echoCommand] - Callback used to display synthetic command echo
  */
 function execViaPty(ptyStream, command, options) {
-  const {
-    stripMarkers = false,
-    trackForCancellation = null,
-    timeoutMs = 60000,
-    shellKind,
-    chatSessionId,
-    abortSignal,
-    expectedPrompt,
-    typedInput = false,
-    echoCommand,
-  } = options || {};
-
-  const marker = `__NCMCP_${Date.now().toString(36)}_${crypto.randomBytes(16).toString('hex')}__`;
-  const resolvedShellKind = shellKind || "posix";
-
-  // Fast-path: already aborted before we even start
-  if (abortSignal?.aborted) {
-    return Promise.resolve({ ok: false, stdout: "", stderr: "", exitCode: -1, error: "Cancelled" });
-  }
-
-  return new Promise((resolve) => {
-    let output = "";
-    let foundStart = false;
-    let preStartOutput = "";
-    let timeoutId = null;
-    let promptFallbackTimer = null;
-    let finished = false;
-    let unsubscribe = null;
-    const cleanupFns = [];
-
-    // Buffer for incomplete line data when searching for start marker.
-    // SSH channels can split data at arbitrary byte boundaries, so the
-    // start marker may arrive across two chunks.  We keep the content
-    // after the last \n (i.e. the current incomplete line) and prepend
-    // it to the next chunk so indexOf can match the full marker.
-    let pendingStart = "";
-
-    const onData = (data) => {
-      const text = data.toString();
-
-      if (!foundStart) {
-        preStartOutput += text;
-        const combined = pendingStart + text;
-        pendingStart = "";
-        const startMarker = marker + "_S";
-        let matched = false;
-        let pos = 0;
-        while (pos < combined.length) {
-          const idx = combined.indexOf(startMarker, pos);
-          if (idx === -1) break;
-          if (idx === 0 || combined[idx - 1] === '\n' || combined[idx - 1] === '\r') {
-            foundStart = true;
-            matched = true;
-            const afterMarker = combined.slice(idx);
-            const nlIdx = afterMarker.indexOf("\n");
-            if (nlIdx !== -1) {
-              output += afterMarker.slice(nlIdx + 1);
-            }
-            break;
-          }
-          pos = idx + 1;
-        }
-        if (!matched) {
-          // Keep the last incomplete line for cross-chunk matching
-          const lastNl = combined.lastIndexOf("\n");
-          pendingStart = lastNl === -1 ? combined : combined.slice(lastNl + 1);
-        }
-        if (foundStart) {
-          preStartOutput = "";
-          schedulePromptFallback();
-          checkEnd();
-          return;
-        }
-
-        // Fallback: if strict start-marker detection missed (e.g. due shell
-        // control sequence prefixes), still complete as soon as we observe a
-        // valid end marker with exit code.
-        const fallbackEnd = findEndMarker(preStartOutput, marker);
-        if (fallbackEnd) {
-          let stdout = preStartOutput.slice(0, fallbackEnd.endIdx);
-          const lastStartIdx = stdout.lastIndexOf(startMarker);
-          if (lastStartIdx !== -1) {
-            const nlAfterStart = stdout.indexOf("\n", lastStartIdx);
-            if (nlAfterStart !== -1) {
-              stdout = stdout.slice(nlAfterStart + 1);
-            }
-          }
-          finish(stdout, fallbackEnd.exitCode);
-        }
-        return;
-      }
-
-      output += text;
-      schedulePromptFallback();
-      checkEnd();
-    };
-
-    function clearPromptFallback() {
-      if (promptFallbackTimer) {
-        clearTimeout(promptFallbackTimer);
-        promptFallbackTimer = null;
-      }
-    }
-
-    function schedulePromptFallback() {
-      clearPromptFallback();
-      if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
-
-      // Fallback for shells that visibly return to the same idle prompt but
-      // never emit the wrapped end marker line.
-      promptFallbackTimer = setTimeout(() => {
-        if (!hasExpectedPromptSuffix(output, expectedPrompt)) return;
-        finish(output, null, null);
-      }, 250);
-    }
-
-    function checkEnd() {
-      // Look for the end marker at a line boundary (actual printf output),
-      // not inside the echo of the printf command argument.
-      const found = findEndMarker(output, marker);
-      if (!found) return;
-      const stdout = output.slice(0, found.endIdx);
-      finish(stdout, found.exitCode);
-    }
-
-    function finish(stdout, exitCode, error) {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timeoutId);
-      clearPromptFallback();
-      unsubscribe?.();
-      for (const fn of cleanupFns) { try { fn(); } catch { /* ignore */ } }
-      if (trackForCancellation) {
-        trackForCancellation.delete(marker);
-      }
-
-      let cleaned = stripAnsi(stdout || "").replace(/\r/g, "");
-      if (stripMarkers) {
-        cleaned = cleaned.replace(/^[^\r\n]*__NCMCP_[^\r\n]*[\r\n]*/gm, "");
-      }
-      const normalizedPrompt = stripAnsi(String(expectedPrompt || "")).replace(/\r/g, "");
-      if (normalizedPrompt && cleaned.endsWith(normalizedPrompt)) {
-        cleaned = cleaned.slice(0, cleaned.length - normalizedPrompt.length);
-      }
-      cleaned = cleaned.trim();
-      if (error) {
-        resolve({ ok: false, stdout: cleaned, stderr: "", exitCode: exitCode ?? -1, error });
-      } else {
-        resolve({
-          ok: exitCode === 0 || exitCode === null,
-          stdout: cleaned,
-          stderr: "",
-          exitCode: exitCode ?? 0,
-        });
-      }
-    }
-
-    timeoutId = setTimeout(() => {
-      // Send Ctrl+C to kill the timed-out command
-      if (typeof ptyStream.write === "function") ptyStream.write("\x03");
-      const timeoutSec = Math.round(timeoutMs / 1000);
-      finish(output, -1, `Command timed out (${timeoutSec}s)`);
-    }, timeoutMs);
-
-    unsubscribe = subscribeToPtyData(ptyStream, onData);
-
-    // Register for cancellation if tracking map provided
-    if (trackForCancellation) {
-      trackForCancellation.set(marker, {
-        ptyStream,
-        chatSessionId: chatSessionId || null,
-        cancel: () => {
-          if (typeof ptyStream.write === "function") ptyStream.write("\x03");
-          finish(output, -1, "Cancelled");
-        },
-        cleanup: () => {
-          clearTimeout(timeoutId);
-          unsubscribe?.();
-        },
-      });
-    }
-
-    // Stream close/error detection — resolve immediately instead of waiting for timeout
-    if (typeof ptyStream.on === "function") {
-      const onClose = () => finish(output, null, "Stream closed unexpectedly");
-      const onError = (err) => finish(output, -1, `Stream error: ${err?.message || err}`);
-      ptyStream.on("close", onClose);
-      ptyStream.on("end", onClose);
-      ptyStream.on("error", onError);
-      cleanupFns.push(() => {
-        try { ptyStream.removeListener("close", onClose); } catch { /* */ }
-        try { ptyStream.removeListener("end", onClose); } catch { /* */ }
-        try { ptyStream.removeListener("error", onError); } catch { /* */ }
-      });
-    }
-    // node-pty uses onExit instead of close/end
-    if (typeof ptyStream.onExit === "function") {
-      const disposable = ptyStream.onExit(() => finish(output, null, "Process exited"));
-      cleanupFns.push(() => { try { disposable?.dispose?.(); } catch { /* */ } });
-    }
-
-    // AbortSignal handling — send Ctrl+C and resolve when aborted
-    if (abortSignal) {
-      const onAbort = () => {
-        if (typeof ptyStream.write === "function") ptyStream.write("\x03");
-        finish(output, -1, "Cancelled");
-      };
-      abortSignal.addEventListener("abort", onAbort, { once: true });
-      cleanupFns.push(() => abortSignal.removeEventListener("abort", onAbort));
-    }
-
-    if (typedInput && typeof echoCommand === "function") {
-      try {
-        echoCommand(command);
-      } catch {
-        // Ignore synthetic echo failures.
-      }
-    }
-
-    // Markers are filtered from terminal display by preload.cjs.
-    ptyStream.write(buildWrappedCommand(command, resolvedShellKind, marker));
-  });
+  return startPtyJob(ptyStream, command, options).resultPromise;
 }
 
 /**
@@ -659,6 +1100,7 @@ execViaRawPty._seq = 0;
 
 module.exports = {
   execViaPty,
+  startPtyJob,
   execViaChannel,
   execViaRawPty,
   detectShellKind,

electron/bridges/ai/shellUtils.cjs

@@ -211,6 +211,15 @@ async function getShellEnv() {
   return _cachedShellEnv;
 }
 
+/**
+ * Drop the shell-env cache so the next getShellEnv() call re-spawns the
+ * login shell. Useful when the user has just exported a new variable in
+ * their rc file and clicks "Refresh Status" without restarting the app.
+ */
+function invalidateShellEnvCache() {
+  _cachedShellEnv = null;
+}
+
 // ── Claude Code ACP binary resolution ──
 
 /**
@@ -316,5 +325,6 @@ module.exports = {
   resolveClaudeAcpBinaryPath,
   toUnpackedAsarPath,
   getShellEnv,
+  invalidateShellEnvCache,
   serializeStreamChunk,
 };

electron/bridges/ai/userSkills.cjs

@@ -0,0 +1,511 @@
+const fsPromises = require("node:fs/promises");
+const path = require("node:path");
+
+const USER_SKILLS_DIR_NAME = "Skills";
+const USER_SKILLS_README_NAME = "README.txt";
+const MAX_SKILL_BYTES = 24 * 1024;
+const MAX_DESCRIPTION_LENGTH = 280;
+const MAX_INDEX_SKILLS = 8;
+const MAX_EXPLICIT_SKILLS = 4;
+const MAX_MATCHED_SKILLS = 2;
+const MAX_MATCHED_SKILL_CHARS = 6000;
+const MAX_TOTAL_INJECTED_SKILL_CHARS = 12000;
+const USER_SKILLS_README_CONTENT = [
+  "Netcatty user skills",
+  "",
+  "Add one folder per skill inside this directory.",
+  "Each skill folder must contain a SKILL.md file.",
+  "",
+  "Example layout:",
+  "  Skills/",
+  "    My Skill/",
+  "      SKILL.md",
+  "",
+  "Minimal SKILL.md:",
+  "  ---",
+  "  name: My Skill",
+  "  description: Short summary of what this skill helps with.",
+  "  ---",
+  "",
+  "  Write the skill instructions here.",
+  "",
+  "After adding or editing a skill, reopen the AI settings page or start a new chat to refresh the list.",
+  "",
+].join("\n");
+
+const STOPWORDS = new Set([
+  "the", "and", "for", "with", "that", "this", "from", "into", "when", "then",
+  "only", "your", "will", "should", "have", "has", "had", "using", "use",
+  "agent", "skill", "skills", "task", "file", "files", "user", "into", "about",
+]);
+
+function stripQuotes(value) {
+  const trimmed = String(value || "").trim();
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function slugifySkill(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function tokenize(value) {
+  return String(value || "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 3 && !STOPWORDS.has(token));
+}
+
+function escapeRegExp(value) {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function formatSkillReadWarning(error) {
+  const code = typeof error?.code === "string" ? error.code : null;
+  const message = typeof error?.message === "string" ? error.message : String(error || "Unknown error");
+  return code
+    ? `Failed to read SKILL.md (${code}: ${message}).`
+    : `Failed to read SKILL.md (${message}).`;
+}
+
+function containsPlaintextPhrase(prompt, phrase) {
+  const trimmedPhrase = String(phrase || "").trim();
+  if (!trimmedPhrase) return false;
+  const pattern = new RegExp(`(^|\\s)${escapeRegExp(trimmedPhrase)}(?=$|\\s|[.,!?;:])`, "i");
+  return pattern.test(String(prompt || ""));
+}
+
+function parseFrontmatter(content) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(content);
+  if (!match) {
+    return { attributes: {}, body: content, hasFrontmatter: false };
+  }
+
+  const attributes = {};
+  for (const rawLine of match[1].split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const colonIndex = line.indexOf(":");
+    if (colonIndex <= 0) continue;
+    const key = line.slice(0, colonIndex).trim();
+    const value = stripQuotes(line.slice(colonIndex + 1).trim());
+    if (key) attributes[key] = value;
+  }
+
+  return {
+    attributes,
+    body: content.slice(match[0].length),
+    hasFrontmatter: true,
+  };
+}
+
+function summarizeSkillSlugs(skillsOrSlugs, maxItems = 4) {
+  const values = (Array.isArray(skillsOrSlugs) ? skillsOrSlugs : [])
+    .map((entry) => {
+      if (typeof entry === "string") return entry;
+      const slug = typeof entry?.slug === "string" ? entry.slug : "";
+      return slug;
+    })
+    .filter(Boolean)
+    .map((slug) => `/${slug}`);
+  if (values.length <= maxItems) {
+    return values.join(", ");
+  }
+  return `${values.slice(0, maxItems).join(", ")}, and ${values.length - maxItems} more`;
+}
+
+function getUserSkillsDir(electronApp) {
+  const userDataDir = electronApp?.getPath?.("userData");
+  if (!userDataDir) {
+    throw new Error("Electron app userData path is unavailable.");
+  }
+  return path.join(userDataDir, USER_SKILLS_DIR_NAME);
+}
+
+async function ensureUserSkillsDir(electronApp) {
+  const skillsDir = getUserSkillsDir(electronApp);
+  await fsPromises.mkdir(skillsDir, { recursive: true });
+  return skillsDir;
+}
+
+async function ensureUserSkillsReadme(electronApp) {
+  const skillsDir = await ensureUserSkillsDir(electronApp);
+  const dirEntries = await fsPromises.readdir(skillsDir);
+  if (dirEntries.length === 0) {
+    await fsPromises.writeFile(
+      path.join(skillsDir, USER_SKILLS_README_NAME),
+      USER_SKILLS_README_CONTENT,
+      "utf8",
+    );
+  }
+  return skillsDir;
+}
+
+async function scanUserSkills(electronApp) {
+  const skillsDir = await ensureUserSkillsReadme(electronApp);
+  const dirEntries = await fsPromises.readdir(skillsDir, { withFileTypes: true });
+  const skills = [];
+  const warnings = [];
+
+  for (const entry of dirEntries) {
+    // Only process actual directories, skipping symlinks for security
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+
+    const dirName = entry.name;
+    // Basic path traversal protection: skip any directory name containing path separators
+    if (dirName.includes("/") || dirName.includes("\\") || dirName === ".." || dirName === ".") {
+      continue;
+    }
+
+    const skillDir = path.join(skillsDir, dirName);
+    const skillPath = path.join(skillDir, "SKILL.md");
+    const baseItem = {
+      id: dirName,
+      slug: slugifySkill(dirName),
+      directoryName: dirName,
+      directoryPath: skillDir,
+      skillPath,
+      name: dirName,
+      description: "",
+      status: "warning",
+      warnings: [],
+    };
+
+    try {
+      await fsPromises.access(skillPath);
+    } catch {
+      baseItem.warnings.push("Missing SKILL.md");
+      warnings.push(`${dirName}: Missing SKILL.md`);
+      skills.push(baseItem);
+      continue;
+    }
+
+    try {
+      const stat = await fsPromises.lstat(skillPath);
+      if (stat.isSymbolicLink()) {
+        baseItem.warnings.push("SKILL.md must not be a symbolic link.");
+        warnings.push(`${dirName}: SKILL.md must not be a symbolic link.`);
+        skills.push(baseItem);
+        continue;
+      }
+
+      if (!stat.isFile()) {
+        baseItem.warnings.push("SKILL.md must be a regular file.");
+        warnings.push(`${dirName}: SKILL.md must be a regular file.`);
+        skills.push(baseItem);
+        continue;
+      }
+
+      if (stat.size > MAX_SKILL_BYTES) {
+        baseItem.warnings.push(`SKILL.md is too large (${stat.size} bytes > ${MAX_SKILL_BYTES} bytes).`);
+        warnings.push(`${dirName}: SKILL.md is too large.`);
+        skills.push(baseItem);
+        continue;
+      }
+
+      const content = await fsPromises.readFile(skillPath, "utf8");
+      const { attributes, body, hasFrontmatter } = parseFrontmatter(content);
+      const name = stripQuotes(attributes.name || "").trim();
+      const description = stripQuotes(attributes.description || "").trim();
+      const usableSlug = slugifySkill(name || dirName);
+
+      if (!hasFrontmatter) {
+        baseItem.warnings.push("Missing YAML frontmatter.");
+      }
+      if (!name) {
+        baseItem.warnings.push("Missing frontmatter field: name.");
+      }
+      if (!description) {
+        baseItem.warnings.push("Missing frontmatter field: description.");
+      } else if (description.length > MAX_DESCRIPTION_LENGTH) {
+        baseItem.warnings.push(`Description is too long (${description.length} chars > ${MAX_DESCRIPTION_LENGTH}).`);
+      }
+      if (!usableSlug) {
+        baseItem.warnings.push("Skill name must include ASCII letters or digits to generate a usable slug.");
+      }
+
+      if (baseItem.warnings.length > 0) {
+        warnings.push(...baseItem.warnings.map((warning) => `${dirName}: ${warning}`));
+        skills.push({
+          ...baseItem,
+          slug: usableSlug,
+          name: name || dirName,
+          description,
+        });
+        continue;
+      }
+
+      skills.push({
+        ...baseItem,
+        slug: usableSlug,
+        name,
+        description,
+        status: "ready",
+        warnings: [],
+        body,
+        mtimeMs: stat.mtimeMs,
+      });
+    } catch (error) {
+      const warning = formatSkillReadWarning(error);
+      baseItem.warnings.push(warning);
+      warnings.push(`${dirName}: ${warning}`);
+      skills.push(baseItem);
+    }
+  }
+
+  const readySkillsBySlug = new Map();
+  for (const skill of skills) {
+    if (skill.status !== "ready" || !skill.slug) continue;
+    const matches = readySkillsBySlug.get(skill.slug);
+    if (matches) {
+      matches.push(skill);
+    } else {
+      readySkillsBySlug.set(skill.slug, [skill]);
+    }
+  }
+
+  for (const [slug, duplicateSkills] of readySkillsBySlug.entries()) {
+    if (duplicateSkills.length < 2) continue;
+    const duplicateWarning = `Duplicate skill slug "${slug}". Rename the skill or change its frontmatter name.`;
+    for (const skill of duplicateSkills) {
+      skill.status = "warning";
+      skill.warnings = [...skill.warnings, duplicateWarning];
+      warnings.push(`${skill.directoryName}: ${duplicateWarning}`);
+    }
+  }
+
+  const readyCount = skills.filter((skill) => skill.status === "ready").length;
+  const warningCount = skills.filter((skill) => skill.status === "warning").length;
+
+  return {
+    directoryPath: skillsDir,
+    readyCount,
+    warningCount,
+    skills: skills.map((skill) => ({
+      id: skill.id,
+      slug: skill.slug,
+      directoryName: skill.directoryName,
+      directoryPath: skill.directoryPath,
+      skillPath: skill.skillPath,
+      name: skill.name,
+      description: skill.description,
+      status: skill.status,
+      warnings: skill.warnings,
+    })),
+    warnings,
+    _readySkills: skills.filter((skill) => skill.status === "ready"),
+  };
+}
+
+/**
+ * Scores how well a skill matches a user prompt.
+ *
+ * Scored based on:
+ * - 50 points: Plain-text name/directory mention (e.g. prompt contains "my skill")
+ * - 1 point per keyword overlap (after tokenization/stopword filtering)
+ *
+ * @param {string} prompt - The user prompt
+ * @param {object} skill - The skill object from scanUserSkills
+ * @returns {number} The score (higher is better)
+ */
+function scoreSkillMatch(prompt, skill) {
+  const name = String(skill.name || "").trim();
+  const directoryName = String(skill.directoryName || "").trim();
+
+  // High weight for an exact plain-text mention of the skill name.
+  if (
+    (name && containsPlaintextPhrase(prompt, name)) ||
+    (directoryName && containsPlaintextPhrase(prompt, directoryName))
+  ) {
+    return 50;
+  }
+
+  // Fallback to token keyword overlap
+  const promptTokens = new Set(tokenize(prompt));
+  const skillTokens = tokenize(`${skill.name} ${skill.description}`);
+  let overlap = 0;
+  for (const token of skillTokens) {
+    if (promptTokens.has(token)) overlap += 1;
+  }
+  return overlap;
+}
+
+/**
+ * Builds the contextual prompt part from matched user skills.
+ *
+ * @param {object} electronApp - The Electron app instance
+ * @param {string} prompt - The user's input prompt
+ * @param {string[]} selectedSkillSlugs - Explicitly requested skill slugs
+ * @returns {Promise<{context: string, status: object}>} The built prompt part and scan status
+ */
+async function buildUserSkillsContext(electronApp, prompt, selectedSkillSlugs = []) {
+  const status = await scanUserSkills(electronApp);
+  const readySkills = status._readySkills || [];
+  const trimmedPrompt = String(prompt || "").trim();
+  if (readySkills.length === 0) {
+    return { context: "", status };
+  }
+
+  const indexSkills = readySkills.slice(0, MAX_INDEX_SKILLS);
+  const remainingCount = Math.max(readySkills.length - indexSkills.length, 0);
+
+  const indexLine = indexSkills
+    .map((skill) => `${skill.name}: ${skill.description}`)
+    .join("; ");
+
+  const orderedExplicitSlugs = [];
+  const seenExplicitSlugs = new Set();
+  for (const rawSlug of Array.isArray(selectedSkillSlugs) ? selectedSkillSlugs : []) {
+    const slug = slugifySkill(rawSlug);
+    if (!slug || seenExplicitSlugs.has(slug)) continue;
+    seenExplicitSlugs.add(slug);
+    orderedExplicitSlugs.push(slug);
+  }
+
+  const additionalExplicitCount = Math.max(orderedExplicitSlugs.length - MAX_EXPLICIT_SKILLS, 0);
+  const cappedExplicitSlugs = orderedExplicitSlugs.slice(0, MAX_EXPLICIT_SKILLS);
+  const explicitSlugSet = new Set(cappedExplicitSlugs);
+  const readySkillsBySlug = new Map(readySkills.map((skill) => [skill.slug, skill]));
+  const explicitSkills = [];
+  const unavailableExplicitSlugs = [];
+  for (const slug of cappedExplicitSlugs) {
+    const skill = readySkillsBySlug.get(slug);
+    if (skill) {
+      explicitSkills.push(skill);
+    } else {
+      unavailableExplicitSlugs.push(slug);
+    }
+  }
+
+  const matchedSkills = readySkills
+    .filter((skill) => !explicitSlugSet.has(skill.slug))
+    .map((skill) => ({ skill, score: scoreSkillMatch(trimmedPrompt, skill) }))
+    .filter((entry) => entry.score >= 2)
+    .sort((left, right) => right.score - left.score)
+    .slice(0, MAX_MATCHED_SKILLS)
+    .map((entry) => entry.skill);
+
+  const finalSkills = [...explicitSkills, ...matchedSkills];
+
+  const parts = [
+    "User-managed skills are installed in Netcatty.",
+    `Available user skills: ${indexLine}${remainingCount > 0 ? `; and ${remainingCount} more.` : "."}`,
+    "Use a user-managed skill only when it clearly matches the current request.",
+  ];
+
+  if (additionalExplicitCount > 0) {
+    parts.push(
+      `The user selected ${additionalExplicitCount} additional Netcatty user skills that were omitted to stay within the prompt budget.`,
+    );
+  }
+
+  if (unavailableExplicitSlugs.length > 0) {
+    parts.push(
+      `The user explicitly selected these Netcatty user skills for this request, but their content is currently unavailable: ${summarizeSkillSlugs(unavailableExplicitSlugs)}.`,
+    );
+  }
+
+  if (finalSkills.length > 0) {
+    const includedSkillSections = [];
+    const omittedSkills = [];
+    const truncatedSkills = [];
+    let remainingSkillChars = MAX_TOTAL_INJECTED_SKILL_CHARS;
+    let budgetStopIndex = finalSkills.length;
+
+    for (let index = 0; index < finalSkills.length; index += 1) {
+      const skill = finalSkills[index];
+      const heading = `### ${skill.name}\n`;
+      const maxBodyChars = Math.min(
+        MAX_MATCHED_SKILL_CHARS,
+        Math.max(remainingSkillChars - heading.length, 0),
+      );
+      if (maxBodyChars <= 0) {
+        omittedSkills.push(skill);
+        continue;
+      }
+
+      const rawBody = String(skill.body || "").trim();
+      if (!rawBody) {
+        omittedSkills.push(skill);
+        continue;
+      }
+
+      if (rawBody.length > maxBodyChars && includedSkillSections.length > 0) {
+        omittedSkills.push(skill);
+        budgetStopIndex = index;
+        continue;
+      }
+
+      const body = rawBody.slice(0, maxBodyChars);
+      if (!body) {
+        omittedSkills.push(skill);
+        continue;
+      }
+
+      includedSkillSections.push(`${heading}${body}`);
+      remainingSkillChars -= heading.length + body.length;
+
+      if (body.length < rawBody.length) {
+        truncatedSkills.push(skill);
+        budgetStopIndex = index + 1;
+        break;
+      }
+    }
+
+    parts.push("Matched user-managed skills for this request:");
+
+    if (includedSkillSections.length > 0) {
+      parts.push(...includedSkillSections);
+    }
+
+    const omittedAfterIncluded = finalSkills.slice(budgetStopIndex);
+    for (const skill of omittedAfterIncluded) {
+      if (!omittedSkills.includes(skill) && !truncatedSkills.includes(skill)) {
+        omittedSkills.push(skill);
+      }
+    }
+
+    if (truncatedSkills.length > 0) {
+      parts.push(
+        `Some matched user-managed skill content was truncated to stay within the prompt budget: ${summarizeSkillSlugs(truncatedSkills)}.`,
+      );
+    }
+
+    if (omittedSkills.length > 0) {
+      parts.push(
+        `Additional matched user-managed skills were omitted to stay within the prompt budget: ${summarizeSkillSlugs(omittedSkills)}.`,
+      );
+    }
+  }
+
+  return {
+    context: parts.join("\n\n"),
+    status,
+  };
+}
+
+function toPublicUserSkillsStatus(status) {
+  if (!status || typeof status !== "object") {
+    return status;
+  }
+  const publicStatus = { ...status };
+  delete publicStatus._readySkills;
+  return publicStatus;
+}
+
+module.exports = {
+  USER_SKILLS_DIR_NAME,
+  getUserSkillsDir,
+  ensureUserSkillsDir,
+  ensureUserSkillsReadme,
+  scanUserSkills,
+  buildUserSkillsContext,
+  toPublicUserSkillsStatus,
+};

electron/bridges/ai/userSkills.test.cjs

@@ -0,0 +1,336 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+
+const { buildUserSkillsContext, scanUserSkills } = require("./userSkills.cjs");
+
+async function withUserSkills(skillDefinitions, run) {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "netcatty-user-skills-"));
+  const userDataDir = path.join(rootDir, "userData");
+  const skillsDir = path.join(userDataDir, "Skills");
+  await fs.mkdir(skillsDir, { recursive: true });
+
+  for (const skill of skillDefinitions) {
+    const skillDir = path.join(skillsDir, skill.directoryName);
+    await fs.mkdir(skillDir, { recursive: true });
+    const content = [
+      "---",
+      `name: ${skill.name}`,
+      `description: ${skill.description}`,
+      "---",
+      "",
+      skill.body,
+      "",
+    ].join("\n");
+    await fs.writeFile(path.join(skillDir, "SKILL.md"), content, "utf8");
+  }
+
+  const electronApp = {
+    getPath(key) {
+      return key === "userData" ? userDataDir : "";
+    },
+  };
+
+  try {
+    await run(electronApp);
+  } finally {
+    await fs.rm(rootDir, { recursive: true, force: true });
+  }
+}
+
+test("does not auto-match a user skill from an absolute path segment", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Tmp Helper",
+        name: "tmp",
+        description: "Helper for scratch space workflows.",
+        body: "Body for tmp",
+      },
+    ],
+    async (electronApp) => {
+      const result = await buildUserSkillsContext(
+        electronApp,
+        "please inspect /tmp/netcatty.log",
+        [],
+      );
+
+      assert.equal(result.context.includes("Matched user-managed skills for this request:"), false);
+      assert.equal(result.context.includes("Body for tmp"), false);
+    },
+  );
+});
+
+test("keeps every explicitly selected skill in the built context", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Alpha One",
+        name: "Alpha One",
+        description: "Alpha helper.",
+        body: "Body for Alpha One",
+      },
+      {
+        directoryName: "Beta Two",
+        name: "Beta Two",
+        description: "Beta helper.",
+        body: "Body for Beta Two",
+      },
+      {
+        directoryName: "Gamma Three",
+        name: "Gamma Three",
+        description: "Gamma helper.",
+        body: "Body for Gamma Three",
+      },
+    ],
+    async (electronApp) => {
+      const result = await buildUserSkillsContext(
+        electronApp,
+        "plain prompt",
+        ["alpha-one", "beta-two", "gamma-three"],
+      );
+
+      assert.equal(result.context.includes("Body for Alpha One"), true);
+      assert.equal(result.context.includes("Body for Beta Two"), true);
+      assert.equal(result.context.includes("Body for Gamma Three"), true);
+    },
+  );
+});
+
+test("preserves an unavailable explicit selection in the built context", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Beta",
+        name: "Beta",
+        description: "Beta helper.",
+        body: "Body for Beta",
+      },
+    ],
+    async (electronApp) => {
+      const result = await buildUserSkillsContext(
+        electronApp,
+        "plain prompt",
+        ["missing-skill"],
+      );
+
+      assert.equal(result.context.includes("Available user skills: Beta: Beta helper."), true);
+      assert.equal(result.context.includes("/missing-skill"), true);
+      assert.match(result.context, /explicitly selected/i);
+      assert.match(result.context, /unavailable/i);
+    },
+  );
+});
+
+test("initializing an empty skills directory creates only an instructions file", async () => {
+  await withUserSkills([], async (electronApp) => {
+    const status = await scanUserSkills(electronApp);
+    const entries = await fs.readdir(status.directoryPath);
+
+    assert.deepEqual(status.skills, []);
+    assert.equal(status.readyCount, 0);
+    assert.equal(status.warningCount, 0);
+    assert.deepEqual(entries.sort(), ["README.txt"]);
+  });
+});
+
+test("unreadable SKILL.md becomes a warning instead of aborting the entire scan", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Working Skill",
+        name: "Working Skill",
+        description: "A valid skill.",
+        body: "Working body",
+      },
+      {
+        directoryName: "Broken Skill",
+        name: "Broken Skill",
+        description: "This file will be unreadable.",
+        body: "Broken body",
+      },
+    ],
+    async (electronApp) => {
+      const unreadablePath = path.join(
+        electronApp.getPath("userData"),
+        "Skills",
+        "Broken Skill",
+        "SKILL.md",
+      );
+
+      await fs.chmod(unreadablePath, 0o000);
+
+      try {
+        const status = await scanUserSkills(electronApp);
+        const workingSkill = status.skills.find((skill) => skill.name === "Working Skill");
+        const brokenSkill = status.skills.find((skill) => skill.directoryName === "Broken Skill");
+
+        assert.equal(status.readyCount, 1);
+        assert.equal(status.warningCount, 1);
+        assert.equal(workingSkill?.status, "ready");
+        assert.equal(brokenSkill?.status, "warning");
+        assert.match(brokenSkill?.warnings?.[0] || "", /Failed to read SKILL\.md/i);
+      } finally {
+        await fs.chmod(unreadablePath, 0o644);
+      }
+    },
+  );
+});
+
+test("symlinked SKILL.md is downgraded to a warning and never injected", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Working Skill",
+        name: "Working Skill",
+        description: "A valid skill.",
+        body: "Working body",
+      },
+    ],
+    async (electronApp) => {
+      const skillsDir = path.join(electronApp.getPath("userData"), "Skills");
+      const linkedDir = path.join(skillsDir, "Linked Skill");
+      const externalTarget = path.join(skillsDir, "..", "outside-secret.md");
+      await fs.mkdir(linkedDir, { recursive: true });
+      await fs.writeFile(
+        externalTarget,
+        [
+          "---",
+          "name: Linked Skill",
+          "description: Linked helper.",
+          "---",
+          "",
+          "TOPSECRET",
+          "",
+        ].join("\n"),
+        "utf8",
+      );
+      await fs.symlink(externalTarget, path.join(linkedDir, "SKILL.md"));
+
+      const status = await scanUserSkills(electronApp);
+      const result = await buildUserSkillsContext(electronApp, "plain prompt", ["linked-skill"]);
+      const linkedSkill = status.skills.find((skill) => skill.directoryName === "Linked Skill");
+
+      assert.equal(status.readyCount, 1);
+      assert.equal(status.warningCount, 1);
+      assert.equal(linkedSkill?.status, "warning");
+      assert.match(linkedSkill?.warnings?.[0] || "", /symbolic link/i);
+      assert.equal(result.context.includes("TOPSECRET"), false);
+      assert.match(result.context, /linked-skill/i);
+      assert.match(result.context, /unavailable/i);
+    },
+  );
+});
+
+test("duplicate normalized slugs are downgraded to warnings and not injected explicitly", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Foo Bar",
+        name: "Foo Bar",
+        description: "First skill.",
+        body: "Body for Foo Bar",
+      },
+      {
+        directoryName: "foo-bar",
+        name: "foo-bar",
+        description: "Second skill.",
+        body: "Body for foo-bar",
+      },
+    ],
+    async (electronApp) => {
+      const status = await scanUserSkills(electronApp);
+      const result = await buildUserSkillsContext(electronApp, "plain prompt", ["foo-bar"]);
+
+      assert.equal(status.readyCount, 0);
+      assert.equal(status.warningCount, 2);
+      assert.equal(status.skills.every((skill) => skill.status === "warning"), true);
+      assert.equal(
+        status.skills.every((skill) =>
+          skill.warnings.some((warning) => warning.includes('Duplicate skill slug "foo-bar"')),
+        ),
+        true,
+      );
+      assert.equal(result.context.includes("Body for Foo Bar"), false);
+      assert.equal(result.context.includes("Body for foo-bar"), false);
+    },
+  );
+});
+
+test("skills without a usable ASCII slug are downgraded to warnings", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "部署助手",
+        name: "部署助手",
+        description: "Deployment helper.",
+        body: "Body for 部署助手",
+      },
+    ],
+    async (electronApp) => {
+      const status = await scanUserSkills(electronApp);
+
+      assert.equal(status.readyCount, 0);
+      assert.equal(status.warningCount, 1);
+      assert.equal(status.skills[0]?.status, "warning");
+      assert.equal(status.skills[0]?.slug, "");
+      assert.match(
+        status.skills[0]?.warnings?.[0] || "",
+        /usable slug/i,
+      );
+    },
+  );
+});
+
+test("explicit selections are capped to stay within the prompt budget", async () => {
+  await withUserSkills(
+    [
+      {
+        directoryName: "Skill One",
+        name: "Skill One",
+        description: "Helper one.",
+        body: "BODY_ONE_" + "a".repeat(3500),
+      },
+      {
+        directoryName: "Skill Two",
+        name: "Skill Two",
+        description: "Helper two.",
+        body: "BODY_TWO_" + "b".repeat(3500),
+      },
+      {
+        directoryName: "Skill Three",
+        name: "Skill Three",
+        description: "Helper three.",
+        body: "BODY_THREE_" + "c".repeat(3500),
+      },
+      {
+        directoryName: "Skill Four",
+        name: "Skill Four",
+        description: "Helper four.",
+        body: "BODY_FOUR_" + "d".repeat(3500),
+      },
+      {
+        directoryName: "Skill Five",
+        name: "Skill Five",
+        description: "Helper five.",
+        body: "BODY_FIVE_" + "e".repeat(3500),
+      },
+    ],
+    async (electronApp) => {
+      const result = await buildUserSkillsContext(
+        electronApp,
+        "plain prompt",
+        ["skill-one", "skill-two", "skill-three", "skill-four", "skill-five"],
+      );
+
+      assert.equal(result.context.includes("BODY_ONE_"), true);
+      assert.equal(result.context.includes("BODY_TWO_"), true);
+      assert.equal(result.context.includes("BODY_THREE_"), true);
+      assert.equal(result.context.includes("BODY_FOUR_"), false);
+      assert.equal(result.context.includes("BODY_FIVE_"), false);
+      assert.match(result.context, /prompt budget|additional selected/i);
+    },
+  );
+});

electron/bridges/aiBridge.cjs

@@ -14,6 +14,12 @@ const fs = require("node:fs");
 const { existsSync } = fs;
 
 const mcpServerBridge = require("./mcpServerBridge.cjs");
+const { getCliLauncherPath, TOOL_CLI_DISCOVERY_ENV_VAR } = require("../cli/discoveryPath.cjs");
+const {
+  scanUserSkills,
+  buildUserSkillsContext,
+  toPublicUserSkillsStatus,
+} = require("./ai/userSkills.cjs");
 
 // ── Extracted modules ──
 const {
@@ -23,7 +29,9 @@ const {
   resolveCliFromPath,
   resolveClaudeAcpBinaryPath,
   getShellEnv,
+  invalidateShellEnvCache,
   serializeStreamChunk,
+  toUnpackedAsarPath,
 } = require("./ai/shellUtils.cjs");
 
 const {
@@ -33,6 +41,9 @@ const {
   toCodexLoginSessionResponse,
   getActiveCodexLoginSession,
   normalizeCodexIntegrationState,
+  readCodexCustomProviderConfig,
+  getCodexAuthOverride,
+  getCodexCustomConfigPreflightError,
   extractCodexError,
   isCodexAuthError,
   getCodexAuthFingerprint,
@@ -42,6 +53,136 @@ const {
   setCodexValidationCache,
 } = require("./ai/codexHelpers.cjs");
 
+const DEBUG_MCP = process.env.NETCATTY_MCP_DEBUG === "1";
+const NETCATTY_TOOL_SKILL_PATH = toUnpackedAsarPath(
+  path.resolve(__dirname, "../../skills/netcatty-tool-cli/SKILL.md"),
+);
+const NETCATTY_TOOL_LAUNCHER_PATH = getCliLauncherPath();
+const NETCATTY_TOOL_CLI_PATH = toUnpackedAsarPath(
+  path.resolve(__dirname, "../cli/netcatty-tool-cli.cjs"),
+);
+
+function debugMcpLog(...args) {
+  if (!DEBUG_MCP) return;
+  console.error("[AI Bridge:debug]", ...args);
+}
+
+function normalizeToolIntegrationMode(mode) {
+  return mode === "skills" ? "skills" : "mcp";
+}
+
+function setToolIntegrationMode(mode) {
+  // Tool access mode is selected per ACP request. The TCP bridge host is shared
+  // by both MCP and Skills + CLI, so changing the setting must not tear down
+  // unrelated in-flight sessions, approvals, or background jobs.
+  return normalizeToolIntegrationMode(mode);
+}
+
+async function ensureSkillsCliHost() {
+  return mcpServerBridge.getOrCreateHost();
+}
+
+function getSkillsCliInvocation() {
+  if (existsSync(NETCATTY_TOOL_LAUNCHER_PATH)) {
+    return {
+      commandPrefix: `"${NETCATTY_TOOL_LAUNCHER_PATH}"`,
+      launcherPath: NETCATTY_TOOL_LAUNCHER_PATH,
+      usesLauncher: true,
+    };
+  }
+  if (existsSync(NETCATTY_TOOL_CLI_PATH)) {
+    return {
+      commandPrefix: `node "${NETCATTY_TOOL_CLI_PATH}"`,
+      launcherPath: null,
+      usesLauncher: false,
+    };
+  }
+  return {
+    commandPrefix: "netcatty-tool-cli",
+    launcherPath: null,
+    usesLauncher: false,
+  };
+}
+
+function buildExternalAgentContextualPrompt({ mode, prompt, chatSessionId, defaultTargetSession, userSkillsContext }) {
+  const userSkillsPreamble = userSkillsContext ? `${userSkillsContext}\n\n` : "";
+  if (mode === "skills") {
+    const { commandPrefix: cliCommandPrefix, launcherPath, usesLauncher } = getSkillsCliInvocation();
+    const skillHint = existsSync(NETCATTY_TOOL_SKILL_PATH)
+      ? `The local Netcatty skill file is "${NETCATTY_TOOL_SKILL_PATH}". You do not need to read it for routine read-only requests if the host instructions here are sufficient. Only open it when the task is unusual, multi-step, or you are unsure about the workflow. `
+      : "";
+    const cliHint = usesLauncher
+      ? (
+        `For this chat session, the Netcatty CLI launcher is at \`${launcherPath}\`. ` +
+        `Invoke that launcher directly for every Netcatty CLI call, and do not prepend \`node\`. ` +
+        (process.platform === "win32"
+          ? `If your execution surface supports argv-style execution, use that launcher path as the executable and pass subcommands/flags as separate arguments. If you need a literal shell command line, invoke it as \`${cliCommandPrefix}\`. `
+          : `The literal shell command prefix is \`${cliCommandPrefix}\`. `)
+      )
+      : existsSync(NETCATTY_TOOL_CLI_PATH)
+        ? `For this chat session, the exact Netcatty CLI command prefix is \`${cliCommandPrefix}\`.`
+        : "Use the exact Netcatty CLI command prefix provided by the host application for this chat session. ";
+    const scopeHint = chatSessionId
+      ? `Always include \`--chat-session ${chatSessionId}\` on every Netcatty CLI call so you stay inside the current scoped session set. `
+      : "";
+    const defaultTargetHint = defaultTargetSession
+      ? (
+        `The host has already identified the default target session for this AI panel: ` +
+        `sessionId="${defaultTargetSession.sessionId}", ` +
+        `label="${defaultTargetSession.label || ""}", ` +
+        `hostname="${defaultTargetSession.hostname || ""}", ` +
+        `protocol="${defaultTargetSession.protocol || ""}", ` +
+        `connected=${defaultTargetSession.connected !== false}. ` +
+        (defaultTargetSession.connected !== false
+          ? `For routine requests that do not mention another session or host, use this default target directly and prefer \`${cliCommandPrefix} session --session ${defaultTargetSession.sessionId} --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` as the first call instead of starting with \`env\` discovery. Only run \`env\` when the user explicitly points to another session (for example with @), when the task is ambiguous, or when that direct session lookup fails. `
+          : `This default target is currently not connected, so do not execute against it directly. Fall back to \`env\` / \`session\` lookup if the user may want another available session. `)
+      )
+      : "";
+    const discoveryHint = defaultTargetSession?.connected !== false
+      ? `If you do need discovery because the task is ambiguous or points to another session, start with \`${cliCommandPrefix} env --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` to discover available sessions and their IDs. `
+      : `Start with \`${cliCommandPrefix} env --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` to discover available sessions and their IDs. `;
+
+    return (
+      `${userSkillsPreamble}` +
+      `[Context: You are inside Netcatty, a multi-session terminal manager. ` +
+      `${skillHint}` +
+      `${cliHint}` +
+      `${scopeHint}` +
+      `${defaultTargetHint}` +
+      `Use Skills + CLI instead of the "netcatty-remote-hosts" MCP server for Netcatty session access. ` +
+      `First classify the task: remote command execution tasks go through \`exec\`, while remote file or directory tasks go through \`sftp\`. If the user explicitly says to avoid shell or \`exec\`, do not use \`exec\`. Treat \`exec\` as the short-command path only: use it only for commands expected to finish within about 60 seconds. For builds, scans, watch mode, tail-following, ping, or anything likely to exceed that budget or stream output for an extended period, do not use plain \`exec\`; use the long-running job commands instead. ` +
+      `${discoveryHint}` +
+      `After choosing a target session ID, call \`${cliCommandPrefix} session --session <id> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` before executing anything. Do not infer protocol, shell type, device type, or connection readiness from the \`env\` result alone when you are about to run a command. ` +
+      `For remote file operations, use the Netcatty SFTP CLI surface instead of trying to reconstruct SSH credentials or open your own SSH/SFTP connection, but only when the chosen session is SSH-backed and connected. After the required \`session --session <id>\` confirmation step, inspect the reported protocol, shell type, device type, and connected state before picking a file-operation path. For SSH-backed sessions, prefer one-off commands such as \`${cliCommandPrefix} sftp list --session <id> --remote-path <remote-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, \`${cliCommandPrefix} sftp read --session <id> --remote-path <remote-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, \`${cliCommandPrefix} sftp write --session <id> --remote-path <remote-path> --content <text> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, \`${cliCommandPrefix} sftp download --session <id> --remote-path <remote-path> --local-path <local-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`, or \`${cliCommandPrefix} sftp upload --session <id> --local-path <local-path> --remote-path <remote-path> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\`. For local sessions, use normal local filesystem tools instead of Netcatty SFTP. For Mosh, Telnet, serial/raw, or network-device sessions, do not call SFTP; use a real SSH session, vendor CLI commands, or tell the user that the requested file transfer is unsupported on that transport. ` +
+      `Keep local and remote path semantics strict: \`--remote-path\` always refers to the remote host, while \`--local-path\` always refers to the local machine running Netcatty. If the user asks to download a file to a local destination such as \`/tmp\`, \`~/Downloads\`, or a desktop path, use \`sftp download\`, not \`sftp read\` or \`sftp write\`. If the user asks to create or modify a file on the remote host, use \`sftp write\` or another remote SFTP operation, not \`sftp download\`. ` +
+      `If you need to create or update a small text file with known content on the remote host, prefer \`${cliCommandPrefix} sftp write ...\` directly. Use \`sftp upload\` only when a real local file already exists and must be transferred to the remote host. Do not create temporary local files just to upload text that could be sent with \`sftp write\`. ` +
+      `Keep SFTP usage one-off and explicit: every \`sftp\` command should include both \`--session <id>\` and \`--chat-session ${chatSessionId || "<chat-session-id>"}\`. Do not open reusable SFTP handles or use \`--sftp <id>\`. ` +
+      `Run Netcatty CLI calls strictly one at a time. Do not issue concurrent or background Netcatty CLI commands for the same chat session, and always wait for each call to finish before starting the next one. ` +
+      `For simple read-only requests such as hostname, IP address, CPU info, memory info, disk usage, pwd, whoami, uname, or process checks, use the shortest possible path: one \`env\`, one \`session\`, then one \`exec\`. Prefer a single straightforward command over creating helper scripts or multi-step shell orchestration. ` +
+      `For long-running command tasks, start them with \`${cliCommandPrefix} job-start --session <id> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""} -- <command>\`, then use \`${cliCommandPrefix} job-poll --job <job-id> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` to fetch incremental output, and \`${cliCommandPrefix} job-stop --job <job-id> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""}\` if the user asks to stop them. Do not poll aggressively; wait roughly 30 seconds between polls unless the output clearly justifies checking sooner. ` +
+      `For those simple read-only requests, do not spend time reading extra files, designing scripts, or narrating a plan unless the first direct command fails or the session metadata shows a special device type. ` +
+      `Do not create temporary scripts, JSON post-processing scripts, or extra wrapper commands unless the task genuinely requires logic that cannot fit cleanly in one direct command. ` +
+      `Avoid shell command substitution such as \`$()\` and backticks, because Netcatty safety policy may block them. Prefer straightforward command chains such as \`hostname && hostname -I && lscpu\`. ` +
+      `Avoid wrapping simple commands in \`sh -c\`, \`bash -c\`, or similar shell launcher patterns unless the task genuinely requires shell parsing that cannot be expressed as a direct command. ` +
+      `Do not spend time narrating intent before every CLI call for routine read-only checks. Execute the minimal command sequence and then report the result. ` +
+      `Only after that confirmation step should you call \`${cliCommandPrefix} exec --session <id> --json${chatSessionId ? ` --chat-session ${chatSessionId}` : ""} -- <command>\` for command execution. ` +
+      `If the user stops the run or asks to abort outstanding Netcatty work, use \`${cliCommandPrefix} cancel --chat-session ${chatSessionId || "<chat-session-id>"} --json\`, and use \`resume\` to re-enable execs for that scope if needed. ` +
+      `For serial/raw sessions and network device sessions (deviceType: network), commands are sent as-is without shell wrapping and exit codes are unavailable. Use vendor CLI commands directly.]\n\n${prompt}`
+    );
+  }
+
+  return (
+    `${userSkillsPreamble}` +
+    `[Context: You are inside Netcatty, a multi-session terminal manager. ` +
+    `Use the "netcatty-remote-hosts" MCP tools to operate only on the terminal sessions exposed by Netcatty. ` +
+    `Those sessions may be remote hosts, a local terminal, or Mosh-backed shells. ` +
+    `Call get_environment first to discover available sessions and their IDs. ` +
+    `Use terminal_execute only for commands likely to finish within about 60 seconds. ` +
+    `For long-running commands such as builds, scans, follow/log streaming, watch commands, or anything likely to exceed 60 seconds on PTY-backed shell sessions, use terminal_start, then terminal_poll until completed is true. Reuse the returned nextOffset for the next poll. If terminal_poll reports outputTruncated=true, only the retained tail starting at outputBaseOffset is still available. Do not poll aggressively: wait at least about 30 seconds between polls, and increase the interval further when there is no new output, to avoid wasting tokens. As soon as completed is true, stop polling and analyze the result immediately. ` +
+    `Use terminal_stop if you need to interrupt a started long-running command. Note: terminal_start requires a PTY-backed session; for sessions that only support exec-channel execution (no writable PTY), use terminal_execute instead. ` +
+    `For serial/raw sessions and network device sessions (deviceType: network), commands are sent as-is without shell wrapping and exit codes are unavailable. Use vendor CLI commands directly.]\n\n${prompt}`
+  );
+}
 
 const { execViaPty } = require("./ai/ptyExec.cjs");
 
@@ -49,6 +190,7 @@ let sessions = null;
 let sftpClients = null;
 let electronModule = null;
 let mainWebContentsId = null;
+let cliDiscoveryFilePath = null;
 
 // Active streaming requests (for cancellation)
 const activeStreams = new Map();
@@ -104,6 +246,34 @@ function resolveProviderApiKey(providerId) {
   };
 }
 
+function getAcpProviderAuthFingerprint(apiKey, provider, customConfig) {
+  const parts = [
+    typeof apiKey === "string" ? apiKey.trim() : "",
+    typeof provider?.id === "string" ? provider.id.trim() : "",
+    typeof provider?.providerId === "string" ? provider.providerId.trim() : "",
+    typeof provider?.baseURL === "string" ? provider.baseURL.trim() : "",
+    customConfig
+      ? [
+          "custom",
+          customConfig.providerName || "",
+          customConfig.baseUrl || "",
+          customConfig.envKey || "",
+          customConfig.envKeyPresent ? "1" : "0",
+          // authHash changes when the user rotates their hardcoded api_key
+          // or the env_key's resolved value; without it a cached ACP
+          // provider would keep serving the stale key.
+          customConfig.authHash || "",
+        ].join(":")
+      : "",
+  ].filter(Boolean);
+
+  if (parts.length === 0) {
+    return null;
+  }
+
+  return getCodexAuthFingerprint(parts.join("\n"));
+}
+
 /** Check if TLS verification should be skipped for a given provider. */
 function shouldSkipTLSVerify(providerId) {
   if (!providerId) return false;
@@ -249,7 +419,8 @@ function init(deps) {
   sessions = deps.sessions;
   sftpClients = deps.sftpClients;
   electronModule = deps.electronModule;
-  mcpServerBridge.init({ sessions, sftpClients, electronModule });
+  cliDiscoveryFilePath = deps.cliDiscoveryFilePath || null;
+  mcpServerBridge.init({ sessions, sftpClients, electronModule, cliDiscoveryFilePath });
 
   // Wire up main window getter for MCP approval IPC
   mcpServerBridge.setMainWindowGetter(() => {
@@ -272,6 +443,15 @@ function init(deps) {
   } catch {
     // windowManager may not be available yet; will be set lazily
   }
+
+}
+
+function withCliDiscoveryEnv(env) {
+  if (!cliDiscoveryFilePath) return env;
+  return {
+    ...env,
+    [TOOL_CLI_DISCOVERY_ENV_VAR]: cliDiscoveryFilePath,
+  };
 }
 
 /**
@@ -594,6 +774,41 @@ function streamRequest(url, options, event, requestId, skipTLS) {
 }
 
 function registerHandlers(ipcMain) {
+  ipcMain.handle("netcatty:ai:user-skills:status", async (event) => {
+    if (!validateSenderOrSettings(event)) return { ok: false, error: "Unauthorized IPC sender" };
+    try {
+      const status = await scanUserSkills(electronModule?.app);
+      return { ok: true, ...toPublicUserSkillsStatus(status) };
+    } catch (err) {
+      return { ok: false, error: err?.message || String(err) };
+    }
+  });
+
+  ipcMain.handle("netcatty:ai:user-skills:open", async (event) => {
+    if (!validateSenderOrSettings(event)) return { ok: false, error: "Unauthorized IPC sender" };
+    try {
+      const status = await scanUserSkills(electronModule?.app);
+      const openResult = await electronModule?.shell?.openPath?.(status.directoryPath);
+      return {
+        ok: !openResult,
+        error: openResult || undefined,
+        ...toPublicUserSkillsStatus(status),
+      };
+    } catch (err) {
+      return { ok: false, error: err?.message || String(err) };
+    }
+  });
+
+  ipcMain.handle("netcatty:ai:user-skills:build-context", async (event, { prompt, selectedSkillSlugs }) => {
+    if (!validateSender(event)) return { ok: false, error: "Unauthorized IPC sender" };
+    try {
+      const { context, status } = await buildUserSkillsContext(electronModule?.app, prompt, selectedSkillSlugs);
+      return { ok: true, context, status: toPublicUserSkillsStatus(status) };
+    } catch (err) {
+      return { ok: false, error: err?.message || String(err) };
+    }
+  });
+
   // ── Provider config sync (renderer → main, keys stay encrypted) ──
   ipcMain.handle("netcatty:ai:sync-providers", async (event, { providers }) => {
     if (!validateSenderOrSettings(event)) return { ok: false };
@@ -1029,6 +1244,19 @@ function registerHandlers(ipcMain) {
       return { ok: false, error: "Session not found" };
     }
 
+    // Honor the per-session execution lock so this IPC path does not race with
+    // long-running background jobs started via terminal_start.
+    const busyErr = mcpServerBridge.getSessionBusyError?.(sessionId);
+    if (busyErr) return busyErr;
+    const reservation = mcpServerBridge.reserveSessionExecution?.(sessionId, "exec");
+    if (reservation && !reservation.ok) return reservation;
+    const sessionToken = reservation?.token;
+    const releaseLock = () => {
+      if (sessionToken) {
+        try { mcpServerBridge.releaseSessionExecution?.(sessionId, sessionToken); } catch {}
+      }
+    };
+
     // Look up device type from metadata (set by renderer from Host.deviceType).
     // Mosh sessions use a shell-backed PTY, so network device mode only applies to SSH/serial.
     // Prefer session.protocol (runtime truth) over meta.protocol (renderer hint)
@@ -1043,12 +1271,26 @@ function registerHandlers(ipcMain) {
     if (!isNetworkDevice) {
       const safety = mcpServerBridge.checkCommandSafety(command);
       if (safety.blocked) {
+        releaseLock();
         return { ok: false, error: `Command blocked by safety policy. Pattern: ${safety.matchedPattern}` };
       }
     }
 
+    // Helper: ensure the session lock is released once the promise settles
+    // (or immediately on a synchronous error/early return).
+    const withLockRelease = (factory) => {
+      try {
+        const result = factory();
+        return Promise.resolve(result).finally(releaseLock);
+      } catch (err) {
+        releaseLock();
+        return { ok: false, error: err?.message || String(err) };
+      }
+    };
+
     try {
       if ((session.protocol === "local" || session.type === "local") && session.shellKind === "unknown") {
+        releaseLock();
         return {
           ok: false,
           error: "AI execution is not supported for this local shell executable. Configure the local terminal to use bash/zsh/sh, fish, PowerShell/pwsh, or cmd.exe.",
@@ -1062,18 +1304,18 @@ function registerHandlers(ipcMain) {
       if (isNetworkDevice && ptyStream && typeof ptyStream.write === "function") {
         const { execViaRawPty } = require("./ai/ptyExec.cjs");
         const timeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaRawPty(ptyStream, command, {
+        return withLockRelease(() => execViaRawPty(ptyStream, command, {
           timeoutMs,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           chatSessionId,
           encoding: "utf8", // SSH PTY streams use UTF-8, not latin1
-        });
+        }));
       }
 
       // Prefer PTY stream (visible in terminal)
       if (ptyStream && typeof ptyStream.write === "function") {
         const timeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaPty(ptyStream, command, {
+        return withLockRelease(() => execViaPty(ptyStream, command, {
           stripMarkers: true,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           timeoutMs,
@@ -1089,11 +1331,16 @@ function registerHandlers(ipcMain) {
               syntheticEcho: true,
             });
           },
-        });
+          // Catty Agent has no terminal_start fallback for long-running
+          // commands, so do NOT enforce a hard wall-clock timeout here.
+          // The inactivity timeout still applies, so genuinely hung
+          // processes are still terminated.
+        }));
       }
 
       // Network devices require an interactive PTY for raw command execution.
       if (isNetworkDevice) {
+        releaseLock();
         return { ok: false, error: "Network device session has no writable PTY stream for command execution" };
       }
 
@@ -1102,27 +1349,29 @@ function registerHandlers(ipcMain) {
       if (sshClient && typeof sshClient.exec === "function") {
         const { execViaChannel } = require("./ai/ptyExec.cjs");
         const channelTimeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaChannel(sshClient, command, {
+        return withLockRelease(() => execViaChannel(sshClient, command, {
           timeoutMs: channelTimeoutMs,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           chatSessionId,
-        });
+        }));
       }
 
       // Serial port: raw command execution (no shell wrapping)
       if (session.protocol === "serial" && session.serialPort && typeof session.serialPort.write === "function") {
         const { execViaRawPty } = require("./ai/ptyExec.cjs");
         const serialTimeoutMs = mcpServerBridge.getCommandTimeoutMs ? mcpServerBridge.getCommandTimeoutMs() : 60000;
-        return execViaRawPty(session.serialPort, command, {
+        return withLockRelease(() => execViaRawPty(session.serialPort, command, {
           timeoutMs: serialTimeoutMs,
           trackForCancellation: mcpServerBridge.activePtyExecs,
           chatSessionId,
           encoding: session.serialEncoding || "utf8",
-        });
+        }));
       }
 
+      releaseLock();
       return { ok: false, error: "No terminal stream or SSH client available for this session" };
     } catch (err) {
+      releaseLock();
       return { ok: false, error: err?.message || String(err) };
     }
   });
@@ -1133,6 +1382,7 @@ function registerHandlers(ipcMain) {
       return { ok: false, error: "Unauthorized IPC sender" };
     }
     mcpServerBridge.cancelPtyExecsForSession(chatSessionId);
+    void mcpServerBridge.cancelSftpOpsForSession?.(chatSessionId);
     return { ok: true };
   });
 
@@ -1208,8 +1458,14 @@ function registerHandlers(ipcMain) {
 
     const { createACPProvider } = require("@mcpc-tech/acp-ai-provider");
     const shellEnv = await getShellEnv();
+    const resolvedCommand = resolveCodexAcpBinaryPath(shellEnv, electronModule);
+    if (!resolvedCommand) {
+      const result = { ok: false, checkedAt: now, error: "codex-acp binary not found", code: "ENOENT" };
+      setCodexValidationCache(result);
+      return result;
+    }
     const provider = createACPProvider({
-      command: resolveCodexAcpBinaryPath(shellEnv, electronModule),
+      command: resolvedCommand,
       env: shellEnv,
       session: {
         cwd: process.cwd(),
@@ -1508,8 +1764,14 @@ function registerHandlers(ipcMain) {
     return { path: resolvedPath, version, available: true };
   });
 
-  ipcMain.handle("netcatty:ai:codex:get-integration", async (event) => {
+  ipcMain.handle("netcatty:ai:codex:get-integration", async (event, options) => {
     if (!validateSenderOrSettings(event)) return { ok: false, error: "Unauthorized IPC sender" };
+    // When the user clicks "Refresh Status" in Settings we also want to
+    // rescan the shell env — otherwise a newly-exported variable in
+    // .zshrc stays invisible until they restart netcatty entirely.
+    if (options && options.refreshShellEnv) {
+      invalidateShellEnvCache();
+    }
     try {
       const result = await runCodexCli(["login", "status"]);
       const rawOutput = [result.stdout, result.stderr]
@@ -1543,11 +1805,33 @@ function registerHandlers(ipcMain) {
         }
       }
 
+      // `codex login status` only reflects ~/.codex/auth.json. A user who
+      // configured a custom provider directly in ~/.codex/config.toml is
+      // functional from the CLI but would look "not_logged_in" here. Probe
+      // config.toml so we can surface that as a valid ready state instead of
+      // pushing the user into the ChatGPT login flow.
+      let customConfig = null;
+      if (state !== "connected_chatgpt" && state !== "connected_api_key") {
+        try {
+          const shellEnv = await getShellEnv();
+          customConfig = readCodexCustomProviderConfig(shellEnv);
+          if (customConfig) {
+            state = "connected_custom_config";
+          }
+        } catch {
+          customConfig = null;
+        }
+      }
+
       return {
         state,
-        isConnected: state === "connected_chatgpt" || state === "connected_api_key",
+        isConnected:
+          state === "connected_chatgpt" ||
+          state === "connected_api_key" ||
+          state === "connected_custom_config",
         rawOutput: effectiveRawOutput,
         exitCode: result.exitCode,
+        customConfig,
       };
     } catch (err) {
       return {
@@ -1555,6 +1839,7 @@ function registerHandlers(ipcMain) {
         isConnected: false,
         rawOutput: err?.message || String(err),
         exitCode: null,
+        customConfig: null,
       };
     }
   });
@@ -1666,7 +1951,10 @@ function registerHandlers(ipcMain) {
       return {
         ok: true,
         state,
-        isConnected: state === "connected_chatgpt" || state === "connected_api_key",
+        isConnected:
+          state === "connected_chatgpt" ||
+          state === "connected_api_key" ||
+          state === "connected_custom_config",
         rawOutput,
         logoutOutput: [logoutResult.stdout, logoutResult.stderr]
           .filter((chunk) => chunk.trim().length > 0)
@@ -1883,6 +2171,16 @@ function registerHandlers(ipcMain) {
     return { ok: true };
   });
 
+  ipcMain.handle("netcatty:ai:mcp:set-tool-integration-mode", async (event, { mode }) => {
+    if (!validateSenderOrSettings(event)) return { ok: false, error: "Unauthorized IPC sender" };
+    const validModes = ["mcp", "skills"];
+    if (!validModes.includes(mode)) {
+      return { ok: false, error: `mode must be one of: ${validModes.join(", ")}` };
+    }
+    setToolIntegrationMode(mode);
+    return { ok: true };
+  });
+
   // ── MCP Approval response (renderer → main) ──
   ipcMain.handle("netcatty:ai:mcp:approval-response", async (event, { approvalId, approved }) => {
     if (!validateSender(event)) return { ok: false, error: "Unauthorized IPC sender" };
@@ -1911,10 +2209,29 @@ function registerHandlers(ipcMain) {
       const resolvedProvider = providerId ? resolveProviderApiKey(providerId) : null;
       const apiKey = resolvedProvider?.apiKey || undefined;
 
-      const agentEnv = { ...shellEnv };
-      if (apiKey) {
+      // Mirror the stream handler's pre-flight: if Codex is pointed at a
+      // config.toml custom provider whose env_key is not exported, surface
+      // a targeted error instead of spawning codex-acp and letting it fail
+      // mid-init with an opaque message.
+      if (isCodexAgent && !apiKey) {
+        const preflight = getCodexCustomConfigPreflightError(
+          readCodexCustomProviderConfig(shellEnv),
+        );
+        if (preflight) {
+          return { ok: false, models: [], error: preflight };
+        }
+      }
+
+      const agentEnv = withCliDiscoveryEnv({ ...shellEnv });
+      if (isCodexAgent && apiKey) {
         agentEnv.CODEX_API_KEY = apiKey;
       }
+      if (isCodexAgent && resolvedProvider?.provider?.baseURL) {
+        agentEnv.OPENAI_BASE_URL = resolvedProvider.provider.baseURL;
+      }
+      // Claude agent auth is owned entirely by its CLI config/login state
+      // (`claude auth login`, ~/.claude settings, or ANTHROPIC_* in the user's
+      // shell env). netcatty's provider list must not override it.
 
       if (isCopilotAgent) {
         copilotConfigInfo = prepareCopilotHome(shellEnv, [], chatSessionId || `models_${Date.now()}`);
@@ -1927,6 +2244,9 @@ function registerHandlers(ipcMain) {
         : claudeAcp
           ? claudeAcp.command
           : acpCommand;
+      if (!resolvedCommand) {
+        return { ok: false, models: [], error: `${agentLabel} binary not found` };
+      }
       const resolvedArgs = claudeAcp
         ? [...claudeAcp.prependArgs, ...(acpArgs || [])]
         : acpArgs || [];
@@ -1940,7 +2260,7 @@ function registerHandlers(ipcMain) {
           mcpServers: [],
         },
         ...(isCodexAgent
-          ? { authMethodId: apiKey ? "codex-api-key" : "chatgpt" }
+          ? getCodexAuthOverride(apiKey, shellEnv)
           : isCopilotAgent
             ? { authMethodId: "copilot-login" }
             : {}),
@@ -1988,7 +2308,7 @@ function registerHandlers(ipcMain) {
     }
   });
 
-  ipcMain.handle("netcatty:ai:acp:stream", async (event, { requestId, chatSessionId, acpCommand, acpArgs, prompt, cwd, providerId, model, existingSessionId, historyMessages, images }) => {
+  ipcMain.handle("netcatty:ai:acp:stream", async (event, { requestId, chatSessionId, acpCommand, acpArgs, prompt, cwd, providerId, model, existingSessionId, historyMessages, images, toolIntegrationMode, defaultTargetSession, userSkillsContext }) => {
     // Validate IPC sender (Issue #17)
     if (!validateSender(event)) {
       return { ok: false, error: "Unauthorized IPC sender" };
@@ -2033,12 +2353,46 @@ function registerHandlers(ipcMain) {
       const isClaudeAgent = matchesAgentCommand(acpCommand, "claude-agent-acp");
       const isCopilotAgent = matchesAgentCommand(acpCommand, "copilot");
       const agentLabel = isCodexAgent ? "codex" : isClaudeAgent ? "claude" : isCopilotAgent ? "copilot" : acpCommand;
+      const effectiveToolIntegrationMode = normalizeToolIntegrationMode(toolIntegrationMode);
+      debugMcpLog("ACP request start", {
+        requestId,
+        chatSessionId,
+        acpCommand,
+        acpArgs,
+        model,
+        providerId,
+        sessionCwd,
+        isCodexAgent,
+        isClaudeAgent,
+        toolIntegrationMode: effectiveToolIntegrationMode,
+      });
 
       // Resolve API key from providerId (decrypted in main process only)
       const resolvedProvider = providerId ? resolveProviderApiKey(providerId) : null;
       const apiKey = resolvedProvider?.apiKey || undefined;
 
-      if (isCodexAgent && !apiKey) {
+      // Probe ~/.codex/config.toml first so we can tell a ChatGPT user
+      // (needs login validation) from a custom-provider user (must NOT be
+      // forced through ChatGPT validation, since their auth lives in
+      // config.toml / shell env, not auth.json).
+      const codexCustomConfig = isCodexAgent && !apiKey
+        ? readCodexCustomProviderConfig(shellEnv)
+        : null;
+
+      // Fail loud: custom-provider config is set but has no usable auth
+      // material yet (env_key is named but not exported in the shell env,
+      // and no api_key is hardcoded). Don't spawn — codex-acp would fail
+      // mid-request with an opaque "Missing environment variable" error.
+      const preflightError = getCodexCustomConfigPreflightError(codexCustomConfig);
+      if (preflightError) {
+        safeSend(event.sender, "netcatty:ai:acp:error", {
+          requestId,
+          error: preflightError,
+        });
+        return { ok: false, error: `Missing env var ${codexCustomConfig.envKey}` };
+      }
+
+      if (isCodexAgent && !apiKey && !codexCustomConfig) {
         const validation = await validateCodexChatGptAuth({ maxAgeMs: 10000 });
         if (shouldAbortStartup()) return { ok: true };
         if (!validation.ok) {
@@ -2059,27 +2413,53 @@ function registerHandlers(ipcMain) {
         }
       }
 
-      const authFingerprint = isCodexAgent ? getCodexAuthFingerprint(apiKey) : null;
+      const authFingerprint = isCodexAgent
+        ? getAcpProviderAuthFingerprint(apiKey, resolvedProvider?.provider, codexCustomConfig)
+        : null;
       const mcpSnapshot = isCodexAgent
         ? await resolveCodexMcpSnapshot(sessionCwd)
         : { mcpServers: [], fingerprint: getCodexMcpFingerprint([]) };
       if (shouldAbortStartup()) return { ok: true };
 
-      // Inject Netcatty MCP server for scoped terminal-session access
-      try {
-        const mcpPort = await mcpServerBridge.getOrCreateHost();
-        const scopedIds = mcpServerBridge.getScopedSessionIds(chatSessionId);
-        const netcattyMcpConfig = mcpServerBridge.buildMcpServerConfig(mcpPort, scopedIds, chatSessionId);
-        mcpSnapshot.mcpServers.push(netcattyMcpConfig);
-        if (isCopilotAgent) {
-          logAcpDebug(agentLabel, "Injected Netcatty MCP server into session", {
-            chatSessionId,
-            scopedIds,
-            injectedServer: summarizeMcpServersForDebug([netcattyMcpConfig])[0],
+      setToolIntegrationMode(effectiveToolIntegrationMode);
+      if (effectiveToolIntegrationMode === "skills") {
+        try {
+          await ensureSkillsCliHost();
+        } catch (err) {
+          const message = err?.message || String(err);
+          safeSend(event.sender, "netcatty:ai:acp:error", {
+            requestId,
+            error: `Failed to initialize Netcatty Skills + CLI bridge.\n\nDetails: ${message}`,
           });
+          return { ok: false, error: message };
+        }
+      }
+
+      // Inject Netcatty MCP server for scoped terminal-session access only when
+      // the user selected MCP mode. Skills mode uses the Netcatty CLI instead.
+      if (effectiveToolIntegrationMode === "mcp") {
+        try {
+          const mcpPort = await mcpServerBridge.getOrCreateHost();
+          const scopedIds = mcpServerBridge.getScopedSessionIds(chatSessionId);
+          const netcattyMcpConfig = mcpServerBridge.buildMcpServerConfig(mcpPort, scopedIds, chatSessionId);
+          mcpSnapshot.mcpServers.push(netcattyMcpConfig);
+          debugMcpLog("Injected Netcatty MCP server", {
+            requestId,
+            chatSessionId,
+            mcpPort,
+            scopedIds,
+            mcpServerNames: mcpSnapshot.mcpServers.map(server => server.name),
+          });
+          if (isCopilotAgent) {
+            logAcpDebug(agentLabel, "Injected Netcatty MCP server into session", {
+              chatSessionId,
+              scopedIds,
+              injectedServer: summarizeMcpServersForDebug([netcattyMcpConfig])[0],
+            });
+          }
+        } catch (err) {
+          console.error("[ACP] Failed to inject Netcatty MCP server:", err?.message || err);
         }
-      } catch (err) {
-        console.error("[ACP] Failed to inject Netcatty MCP server:", err?.message || err);
       }
       if (shouldAbortStartup()) return { ok: true };
 
@@ -2101,10 +2481,14 @@ function registerHandlers(ipcMain) {
         const resumeSessionId = providerEntry?.provider?.getSessionId?.() || existingSessionId || undefined;
         cleanupAcpProvider(chatSessionId);
 
-        const agentEnv = { ...shellEnv };
-        if (apiKey) {
+        const agentEnv = withCliDiscoveryEnv({ ...shellEnv });
+        if (isCodexAgent && apiKey) {
           agentEnv.CODEX_API_KEY = apiKey;
         }
+        if (isCodexAgent && resolvedProvider?.provider?.baseURL) {
+          agentEnv.OPENAI_BASE_URL = resolvedProvider.provider.baseURL;
+        }
+        // See comment above: Claude auth is CLI-owned, not provider-driven.
         let copilotConfigInfo = null;
         if (isCopilotAgent) {
           copilotConfigInfo = prepareCopilotHome(shellEnv, mcpSnapshot.mcpServers, chatSessionId);
@@ -2117,6 +2501,9 @@ function registerHandlers(ipcMain) {
           : claudeAcp
             ? claudeAcp.command
             : acpCommand;
+        if (!resolvedCommand) {
+          throw new Error(`${agentLabel} binary not found`);
+        }
         const resolvedArgs = claudeAcp
           ? [...claudeAcp.prependArgs, ...(acpArgs || [])]
           : acpArgs || [];
@@ -2132,12 +2519,20 @@ function registerHandlers(ipcMain) {
           },
           ...(resumeSessionId ? { existingSessionId: resumeSessionId } : {}),
           ...(isCodexAgent
-            ? { authMethodId: apiKey ? "codex-api-key" : "chatgpt" }
+            ? getCodexAuthOverride(apiKey, shellEnv)
             : isCopilotAgent
               ? { authMethodId: "copilot-login" }
             : {}),
           persistSession: true,
         });
+        debugMcpLog("Created ACP provider", {
+          requestId,
+          chatSessionId,
+          resolvedCommand,
+          resolvedArgs,
+          mcpServerNames: mcpSnapshot.mcpServers.map(server => server.name),
+          authMethodId: isCodexAgent ? (getCodexAuthOverride(apiKey, shellEnv).authMethodId || null) : null,
+        });
 
         if (isCopilotAgent) {
           logAcpDebug(agentLabel, "Creating ACP provider", {
@@ -2167,6 +2562,11 @@ function registerHandlers(ipcMain) {
       let modelInstance = providerEntry.provider.languageModel(model || undefined);
       try {
         await providerEntry.provider.initSession(providerEntry.provider.tools);
+        debugMcpLog("provider.initSession ok", {
+          requestId,
+          chatSessionId,
+          providerSessionId: providerEntry.provider.getSessionId?.() || null,
+        });
         if (isCopilotAgent) {
           logAcpDebug(agentLabel, "ACP session initialized", {
             requestId,
@@ -2177,6 +2577,11 @@ function registerHandlers(ipcMain) {
         }
         if (shouldAbortStartup()) return { ok: true };
       } catch (err) {
+        debugMcpLog("provider.initSession error", {
+          requestId,
+          chatSessionId,
+          message: err?.message || String(err),
+        });
         const attemptedResumeSessionId = providerEntry.provider?.getSessionId?.() || existingSessionId;
         if (!attemptedResumeSessionId || !shouldRetryFreshSession(err)) {
           throw err;
@@ -2185,17 +2590,27 @@ function registerHandlers(ipcMain) {
         cleanupAcpProvider(chatSessionId);
 
         const fallbackClaudeAcp = isClaudeAgent ? resolveClaudeAcpBinaryPath(shellEnv, electronModule) : null;
+        const fallbackCommand = isCodexAgent
+          ? resolveCodexAcpBinaryPath(shellEnv, electronModule)
+          : fallbackClaudeAcp
+            ? fallbackClaudeAcp.command
+            : acpCommand;
+        if (!fallbackCommand) {
+          throw new Error(`${agentLabel} binary not found`);
+        }
         const fallbackProvider = createACPProvider({
-          command: isCodexAgent
-            ? resolveCodexAcpBinaryPath(shellEnv, electronModule)
-            : fallbackClaudeAcp
-              ? fallbackClaudeAcp.command
-              : acpCommand,
+          command: fallbackCommand,
           args: fallbackClaudeAcp
             ? [...fallbackClaudeAcp.prependArgs, ...(acpArgs || [])]
             : acpArgs || [],
           env: (() => {
-            const fallbackEnv = apiKey ? { ...shellEnv, CODEX_API_KEY: apiKey } : { ...shellEnv };
+            const fallbackEnv = withCliDiscoveryEnv(
+              isCodexAgent && apiKey ? { ...shellEnv, CODEX_API_KEY: apiKey } : { ...shellEnv },
+            );
+            if (isCodexAgent && resolvedProvider?.provider?.baseURL) {
+              fallbackEnv.OPENAI_BASE_URL = resolvedProvider.provider.baseURL;
+            }
+            // See comment above: Claude auth is CLI-owned, not provider-driven.
             if (isCopilotAgent) {
               const fallbackCopilotConfig = prepareCopilotHome(shellEnv, mcpSnapshot.mcpServers, chatSessionId);
               fallbackEnv.COPILOT_HOME = fallbackCopilotConfig.copilotHome;
@@ -2207,7 +2622,7 @@ function registerHandlers(ipcMain) {
             mcpServers: isCopilotAgent ? [] : mcpSnapshot.mcpServers,
           },
           ...(isCodexAgent
-            ? { authMethodId: apiKey ? "codex-api-key" : "chatgpt" }
+            ? getCodexAuthOverride(apiKey, shellEnv)
             : isCopilotAgent
               ? { authMethodId: "copilot-login" }
             : {}),
@@ -2226,6 +2641,11 @@ function registerHandlers(ipcMain) {
         acpProviders.set(chatSessionId, providerEntry);
         modelInstance = providerEntry.provider.languageModel(model || undefined);
         await providerEntry.provider.initSession(providerEntry.provider.tools);
+        debugMcpLog("fallback provider.initSession ok", {
+          requestId,
+          chatSessionId,
+          providerSessionId: providerEntry.provider.getSessionId?.() || null,
+        });
         if (isCopilotAgent) {
           logAcpDebug(agentLabel, "ACP session initialized after fallback", {
             requestId,
@@ -2244,14 +2664,14 @@ function registerHandlers(ipcMain) {
         });
       }
 
-      // Prepend context hint so the agent uses Netcatty MCP tools for the scoped sessions
-      const contextualPrompt =
-        `[Context: You are inside Netcatty, a multi-session terminal manager. ` +
-        `Use the "netcatty-remote-hosts" MCP tools to operate only on the terminal sessions exposed by Netcatty. ` +
-        `Those sessions may be remote hosts, a local terminal, or Mosh-backed shells. ` +
-        `Call get_environment first to discover available sessions and their IDs. ` +
-        `For normal shell commands, use terminal_execute so you receive command output. ` +
-        `For serial/raw sessions and network device sessions (deviceType: network), commands are sent as-is without shell wrapping and exit codes are unavailable. Use vendor CLI commands directly.]\n\n${prompt}`;
+      // Prepend context hint so the agent uses the configured Netcatty access mode.
+      const contextualPrompt = buildExternalAgentContextualPrompt({
+        mode: effectiveToolIntegrationMode,
+        prompt,
+        chatSessionId,
+        defaultTargetSession,
+        userSkillsContext,
+      });
 
       // Build message content: text + optional attachments
       // ACP provider only supports image/* and audio/* inline via `type: "file"`.
@@ -2349,12 +2769,18 @@ function registerHandlers(ipcMain) {
             const serialized = serializeStreamChunk(chunk);
             if (!serialized || !serialized.type) continue;
 
-            if (serialized.type === "text-delta" || serialized.type === "reasoning-delta" || serialized.type === "tool-call") {
+            if (serialized.type === "text-delta" || serialized.type === "reasoning-delta" || serialized.type === "tool-call" || serialized.type === "tool-result") {
               hasContent = true;
             }
             if (isCopilotAgent && (serialized.type === "tool-call" || serialized.type === "tool-result" || serialized.type === "error" || serialized.type === "status")) {
               logAcpDebug(agentLabel, `Stream event: ${serialized.type}`, serialized);
             }
+            debugMcpLog("ACP stream event", {
+              requestId,
+              chatSessionId,
+              type: serialized.type,
+              toolName: serialized.toolName || null,
+            });
             safeSend(event.sender, "netcatty:ai:acp:event", {
               requestId,
               event: serialized,
@@ -2370,6 +2796,12 @@ function registerHandlers(ipcMain) {
 
       // If stream completed with zero content, likely an auth or connection issue
       if (!hasContent && !abortController.signal.aborted) {
+        debugMcpLog("ACP empty response", {
+          requestId,
+          chatSessionId,
+          isCodexAgent,
+          providerSessionId: providerEntry.provider.getSessionId?.() || null,
+        });
         if (isCopilotAgent) {
           logAcpDebug(agentLabel, "Stream completed with no content", {
             requestId,
@@ -2387,6 +2819,7 @@ function registerHandlers(ipcMain) {
             : "Agent returned an empty response.",
         });
       } else {
+        debugMcpLog("ACP stream done", { requestId, chatSessionId, hasContent });
         if (!isActiveAcpRun(chatSessionId, requestId)) {
           return { ok: true };
         }
@@ -2427,9 +2860,13 @@ function registerHandlers(ipcMain) {
     const effectiveChatSessionId = chatSessionId || acpRequestSessions.get(requestId);
     const activeRun = effectiveChatSessionId ? acpChatRuns.get(effectiveChatSessionId) : null;
     const effectiveRequestId = requestId || activeRun?.requestId || "";
-    // Cancel PTY executions scoped to this chat session (send Ctrl+C)
-    mcpServerBridge.cancelPtyExecsForSession(effectiveChatSessionId);
+    // Cancel synchronous PTY executions scoped to this chat session (send Ctrl+C).
+    // Do NOT cancel terminal_start background jobs here — they were intentionally
+    // launched as long-running and should keep running when the user only wants
+    // to stop the model's polling/output. Background jobs are still cleaned up
+    // when the chat session itself is deleted (see cleanupScopedMetadata).
     mcpServerBridge.setChatSessionCancelled?.(effectiveChatSessionId, true);
+    mcpServerBridge.cancelPtyExecsForSession(effectiveChatSessionId);
     mcpServerBridge.clearPendingApprovals(effectiveChatSessionId);
     if (activeRun && activeRun.requestId === effectiveRequestId) {
       activeRun.cancelRequested = true;
@@ -2449,6 +2886,7 @@ function registerHandlers(ipcMain) {
     // cleanup is handled by netcatty:ai:acp:cleanup when the chat is deleted.
     if (effectiveChatSessionId) cancelled = true;
     if (effectiveRequestId) acpRequestSessions.delete(effectiveRequestId);
+    void mcpServerBridge.cancelSftpOpsForSession?.(effectiveChatSessionId);
     return cancelled ? { ok: true } : { ok: false, error: "Stream not found" };
   });
 
@@ -2456,8 +2894,9 @@ function registerHandlers(ipcMain) {
   ipcMain.handle("netcatty:ai:acp:cleanup", async (event, { chatSessionId }) => {
     if (!validateSender(event)) return { ok: false, error: "Unauthorized IPC sender" };
     mcpServerBridge.setChatSessionCancelled?.(chatSessionId, true);
+    mcpServerBridge.cancelPtyExecsForSession(chatSessionId);
     cleanupAcpProvider(chatSessionId);
-    mcpServerBridge.cleanupScopedMetadata(chatSessionId);
+    await mcpServerBridge.cleanupScopedMetadata(chatSessionId);
     return { ok: true };
   });
 
@@ -2527,6 +2966,7 @@ function cleanup() {
   }
   codexLoginSessions.clear();
   invalidateCodexValidationCache();
+  mcpServerBridge.cleanup();
 }
 
 module.exports = { init, registerHandlers, cleanup };