fix(tui): termux-gate scrollback preservation, touch-friendly defaults

Adds a Termux runtime detection helper and gates three TUI defaults on it:

- Skip the startup scrollback clear on Termux so users can review/copy
  earlier output after reopening the app. Desktop keeps the existing
  \x1b[2J\x1b[H\x1b[3J slate (AlternateScreen takes over there anyway).
- Default INLINE_MODE on under Termux: primary-buffer rendering makes
  long-thread review and copy/paste much less fragile when users
  background/foreground the app. Override with HERMES_TUI_INLINE=0/1.
- Default mouse tracking off under Termux so touch selection isn't
  intercepted by terminal mouse protocols. Explicit override via
  HERMES_TUI_MOUSE_TRACKING=0/1; legacy HERMES_TUI_DISABLE_MOUSE still
  works on desktop.

Detection is purely env-based (TERMUX_VERSION or PREFIX path) with an
explicit opt-out HERMES_TUI_TERMUX_MODE=0 for debugging. Non-Termux
platforms keep every existing default.

Co-authored-by: adybag14-cyber <252811164+adybag14-cyber@users.noreply.github.com>

ui-tui/src/__tests__/termux.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+
+import { isTermuxEnv, isTermuxTuiMode } from '../lib/termux.js'
+
+describe('isTermuxEnv', () => {
+  it('detects TERMUX_VERSION marker', () => {
+    expect(isTermuxEnv({ TERMUX_VERSION: '0.118.0' } as NodeJS.ProcessEnv)).toBe(true)
+  })
+
+  it('detects Termux PREFIX path marker', () => {
+    expect(
+      isTermuxEnv({ PREFIX: '/data/data/com.termux/files/usr' } as NodeJS.ProcessEnv)
+    ).toBe(true)
+  })
+
+  it('returns false for generic Linux envs', () => {
+    expect(isTermuxEnv({ PREFIX: '/usr' } as NodeJS.ProcessEnv)).toBe(false)
+  })
+})
+
+describe('isTermuxTuiMode', () => {
+  it('defaults to true inside Termux', () => {
+    expect(isTermuxTuiMode({ TERMUX_VERSION: '0.118.0' } as NodeJS.ProcessEnv)).toBe(true)
+  })
+
+  it('allows explicit opt-out override', () => {
+    expect(
+      isTermuxTuiMode({ TERMUX_VERSION: '0.118.0', HERMES_TUI_TERMUX_MODE: '0' } as NodeJS.ProcessEnv)
+    ).toBe(false)
+  })
+
+  it('stays false outside Termux even if override is set', () => {
+    expect(isTermuxTuiMode({ HERMES_TUI_TERMUX_MODE: '1', PREFIX: '/usr' } as NodeJS.ProcessEnv)).toBe(false)
+  })
+})

ui-tui/src/config/env.ts

@@ -1,16 +1,51 @@
+import { isTermuxTuiMode } from '../lib/termux.js'
+
 const truthy = (v?: string) => /^(?:1|true|yes|on)$/i.test((v ?? '').trim())
+const falsy = (v?: string) => /^(?:0|false|no|off)$/i.test((v ?? '').trim())
+
+const parseToggle = (v?: string): boolean | null => {
+  const raw = (v ?? '').trim()
+
+  if (!raw) {
+    return null
+  }
+
+  if (truthy(raw)) {
+    return true
+  }
+
+  if (falsy(raw)) {
+    return false
+  }
+
+  return null
+}
+
+export const TERMUX_TUI_MODE = isTermuxTuiMode()
 
 export const STARTUP_RESUME_ID = (process.env.HERMES_TUI_RESUME ?? '').trim()
 export const STARTUP_QUERY = (process.env.HERMES_TUI_QUERY ?? '').trim()
 export const STARTUP_IMAGE = (process.env.HERMES_TUI_IMAGE ?? '').trim()
-export const MOUSE_TRACKING = !truthy(process.env.HERMES_TUI_DISABLE_MOUSE)
+
+const mouseTrackingOverride = parseToggle(process.env.HERMES_TUI_MOUSE_TRACKING)
+const mouseTrackingDisabledLegacy = truthy(process.env.HERMES_TUI_DISABLE_MOUSE)
+// Mobile selection UX: on Termux default mouse tracking OFF so touch selection
+// is less likely to be intercepted by terminal mouse protocols. Desktop keeps
+// prior behavior unless explicitly overridden.
+export const MOUSE_TRACKING =
+  mouseTrackingOverride ?? (TERMUX_TUI_MODE ? false : !mouseTrackingDisabledLegacy)
+
 export const NO_CONFIRM_DESTRUCTIVE = truthy(process.env.HERMES_TUI_NO_CONFIRM)
 
+const inlineOverride = parseToggle(process.env.HERMES_TUI_INLINE)
+
 // Skip AlternateScreen — TUI renders into the primary buffer so the host
 // terminal's native scrollback captures whatever scrolls off the top.
-// Experiment gate: lets us measure native scroll vs our virtualization on
-// the same pipeline.
-export const INLINE_MODE = truthy(process.env.HERMES_TUI_INLINE)
+//
+// On Termux we default this on: users often background/foreground the app,
+// and primary-buffer rendering makes long-thread review and copy/paste much
+// less fragile. Override explicitly with HERMES_TUI_INLINE=0/1.
+export const INLINE_MODE = inlineOverride ?? TERMUX_TUI_MODE
 
 // Live FPS counter overlay, fed by ink's onFrame (real render rate, not a
 // synthetic timer).

ui-tui/src/entry.tsx

@@ -5,6 +5,7 @@ import './lib/forceTruecolor.js'
 
 import type { FrameEvent } from '@hermes/ink'
 
+import { TERMUX_TUI_MODE } from './config/env.js'
 import { GatewayClient } from './gatewayClient.js'
 import { setupGracefulExit } from './lib/gracefulExit.js'
 import { formatBytes, type HeapDumpResult, performHeapDump } from './lib/memory.js'
@@ -21,11 +22,14 @@ if (!process.stdin.isTTY) {
 // terminal tab can still have mouse/focus/paste modes enabled.
 resetTerminalModes()
 
-// Clear visible screen + scrollback buffer. Without this, tmux may retain
-// stale TUI output in its scrollback buffer from the previous session,
-// which is visible when the user scrolls up or briefly before AlternateScreen
-// takes over on restart. See entry.tsx → AlternateScreen flow.
-process.stdout.write('\x1b[2J\x1b[H\x1b[3J')
+// Desktop terminals benefit from a clean startup slate because the TUI usually
+// runs in AlternateScreen. On Termux we keep prior output intact so users can
+// review/copy earlier assistant replies after reopening the app.
+if (TERMUX_TUI_MODE) {
+  process.stdout.write('\n')
+} else {
+  process.stdout.write('\x1b[2J\x1b[H\x1b[3J')
+}
 
 const gw = new GatewayClient()
 

ui-tui/src/lib/termux.ts

@@ -0,0 +1,29 @@
+const TERMUX_PREFIX = '/data/data/com.termux/files/usr'
+
+const truthy = (value?: string) => /^(?:1|true|yes|on)$/i.test(String(value ?? '').trim())
+
+export const isTermuxEnv = (env: NodeJS.ProcessEnv = process.env): boolean => {
+  const prefix = String(env.PREFIX ?? '')
+
+  return Boolean(env.TERMUX_VERSION) || prefix.includes(TERMUX_PREFIX)
+}
+
+/**
+ * Return true when Hermes should enable Termux-focused TUI defaults.
+ *
+ * Defaults to on in Termux, with an explicit opt-out for debugging:
+ *   HERMES_TUI_TERMUX_MODE=0
+ */
+export const isTermuxTuiMode = (env: NodeJS.ProcessEnv = process.env): boolean => {
+  if (!isTermuxEnv(env)) {
+    return false
+  }
+
+  const override = String(env.HERMES_TUI_TERMUX_MODE ?? '').trim().toLowerCase()
+
+  if (override) {
+    return truthy(override)
+  }
+
+  return true
+}