From 7aad2f2bcfdfb2f79558005f2dea358ec9cfded5 Mon Sep 17 00:00:00 2001
From: jacob314 <jacob314@gmail.com>
Date: Fri, 20 Feb 2026 10:38:43 -0800
Subject: [PATCH] fix(cli): update JetBrains terminal warning messaging and
 only show in alternate buffer mode

---
 .../scripts/fetch-pr-info.js                  |  3 ++-
 packages/cli/src/utils/userStartupWarnings.ts |  6 ++++-
 packages/core/src/utils/compatibility.test.ts | 16 ++++++++++---
 packages/core/src/utils/compatibility.ts      | 23 +++++++++++++++----
 4 files changed, 39 insertions(+), 9 deletions(-)

diff --git a/.gemini/skills/pr-address-comments/scripts/fetch-pr-info.js b/.gemini/skills/pr-address-comments/scripts/fetch-pr-info.js
index 772f8d18a4..de99def0ce 100755
--- a/.gemini/skills/pr-address-comments/scripts/fetch-pr-info.js
+++ b/.gemini/skills/pr-address-comments/scripts/fetch-pr-info.js
@@ -20,7 +20,8 @@ async function run(cmd) {
       stdio: ['pipe', 'pipe', 'ignore'],
     });
     return stdout.trim();
-  } catch (_e) { // eslint-disable-line @typescript-eslint/no-unused-vars
+  } catch (_e) {
+    // eslint-disable-line @typescript-eslint/no-unused-vars
     return null;
   }
 }
diff --git a/packages/cli/src/utils/userStartupWarnings.ts b/packages/cli/src/utils/userStartupWarnings.ts
index da9623acb6..3116fafdac 100644
--- a/packages/cli/src/utils/userStartupWarnings.ts
+++ b/packages/cli/src/utils/userStartupWarnings.ts
@@ -105,7 +105,11 @@ export async function getUserStartupWarnings(
   const warnings = results.filter((w): w is StartupWarning => w !== null);
 
   if (settings.ui?.showCompatibilityWarnings !== false) {
-    warnings.push(...getCompatibilityWarnings());
+    warnings.push(
+      ...getCompatibilityWarnings({
+        useAlternateBuffer: settings.ui?.useAlternateBuffer !== false,
+      }),
+    );
   }
 
   return warnings;
diff --git a/packages/core/src/utils/compatibility.test.ts b/packages/core/src/utils/compatibility.test.ts
index c7819578f1..1f6191b1d5 100644
--- a/packages/core/src/utils/compatibility.test.ts
+++ b/packages/core/src/utils/compatibility.test.ts
@@ -131,11 +131,11 @@ describe('compatibility', () => {
       );
     });
 
-    it('should return JetBrains warning when detected', () => {
+    it('should return JetBrains warning when detected and useAlternateBuffer is true', () => {
       vi.mocked(os.platform).mockReturnValue('darwin');
       vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
 
-      const warnings = getCompatibilityWarnings();
+      const warnings = getCompatibilityWarnings({ useAlternateBuffer: true });
       expect(warnings).toContainEqual(
         expect.objectContaining({
           id: 'jetbrains-terminal',
@@ -144,6 +144,16 @@ describe('compatibility', () => {
       );
     });
 
+    it('should NOT return JetBrains warning when detected but useAlternateBuffer is false', () => {
+      vi.mocked(os.platform).mockReturnValue('darwin');
+      vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
+
+      const warnings = getCompatibilityWarnings({ useAlternateBuffer: false });
+      expect(
+        warnings.find((w) => w.id === 'jetbrains-terminal'),
+      ).toBeUndefined();
+    });
+
     it('should return 256-color warning when 256 colors are not supported', () => {
       vi.mocked(os.platform).mockReturnValue('linux');
       vi.stubEnv('TERMINAL_EMULATOR', '');
@@ -201,7 +211,7 @@ describe('compatibility', () => {
       vi.stubEnv('TERM_PROGRAM', 'xterm');
       process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
 
-      const warnings = getCompatibilityWarnings();
+      const warnings = getCompatibilityWarnings({ useAlternateBuffer: true });
       expect(warnings).toHaveLength(3);
       expect(warnings[0].message).toContain('Windows 10 detected');
       expect(warnings[1].message).toContain('JetBrains terminal detected');
diff --git a/packages/core/src/utils/compatibility.ts b/packages/core/src/utils/compatibility.ts
index 8099351ad0..27847109ac 100644
--- a/packages/core/src/utils/compatibility.ts
+++ b/packages/core/src/utils/compatibility.ts
@@ -89,7 +89,13 @@ export interface StartupWarning {
   priority: WarningPriority;
 }
 
-export function getCompatibilityWarnings(): StartupWarning[] {
+export interface CompatibilityOptions {
+  useAlternateBuffer?: boolean;
+}
+
+export function getCompatibilityWarnings(
+  options: CompatibilityOptions = {},
+): StartupWarning[] {
   const warnings: StartupWarning[] = [];
 
   if (isWindows10()) {
@@ -101,11 +107,20 @@ export function getCompatibilityWarnings(): StartupWarning[] {
     });
   }
 
-  if (isJetBrainsTerminal()) {
+  if (isJetBrainsTerminal() && options.useAlternateBuffer) {
+    let suggestedTerminals = '';
+    const platform = os.platform();
+    if (platform === 'win32') {
+      suggestedTerminals = 'Windows Terminal';
+    } else if (platform === 'darwin') {
+      suggestedTerminals = 'iTerm2, Ghostty';
+    } else {
+      suggestedTerminals = 'Ghostty';
+    }
+
     warnings.push({
       id: 'jetbrains-terminal',
-      message:
-        'Warning: JetBrains terminal detected. You may experience rendering or scrolling issues. Using an external terminal (e.g., Windows Terminal, iTerm2) is recommended.',
+      message: `Warning: JetBrains terminal detected. Jetbrains mouse scrolling physics has strange bouncing behavior. Using an external terminal (e.g., ${suggestedTerminals}) is recommended.`,
       priority: WarningPriority.High,
     });
   }