From caccf28641ba0546d393bebf3679f8a9eace37e6 Mon Sep 17 00:00:00 2001
From: lior <liory7@gmail.com>
Date: Wed, 29 Jul 2026 04:20:51 +0300
Subject: [PATCH] feat(mobile): add opt-in terminal controls

Unify keyboard-open and keyboard-hidden terminal navigation behind one opt-in setting. Add swipe, simultaneous Up+Down Enter, exposed volume-key mapping, modal suppression, and optional haptic or sound feedback while preserving upstream path-picker actions.
---
 src/web/public/app.js                |  12 +-
 src/web/public/i18n.js               |  14 +-
 src/web/public/index.html            |  42 +-
 src/web/public/keyboard-accessory.js | 680 +++++++++++++++++++++++----
 src/web/public/mobile-handlers.js    |  84 +++-
 src/web/public/mobile.css            | 163 ++++++-
 src/web/public/settings-ui.js        |  38 +-
 src/web/public/styles.css            |  74 ++-
 src/web/public/terminal-ui.js        |  10 +
 test/mobile-navigation-pad.test.ts   | 379 +++++++++++++++
 test/mobile/helpers/constants.ts     |   3 +
 test/mobile/keyboard.test.ts         | 185 +++++++-
 test/mobile/navigation-pad.test.ts   | 533 +++++++++++++++++++++
 test/mobile/settings.test.ts         |  61 ++-
 14 files changed, 2074 insertions(+), 204 deletions(-)
 create mode 100644 test/mobile-navigation-pad.test.ts
 create mode 100644 test/mobile/navigation-pad.test.ts

diff --git a/src/web/public/app.js b/src/web/public/app.js
index 6f953be8..a8624749 100644
--- a/src/web/public/app.js
+++ b/src/web/public/app.js
@@ -41,7 +41,7 @@
  * @dependency mobile-handlers.js (MobileDetection, KeyboardHandler, SwipeHandler)
  * @dependency voice-input.js (VoiceInput, DeepgramProvider)
  * @dependency notification-manager.js (NotificationManager class)
- * @dependency keyboard-accessory.js (KeyboardAccessoryBar, FocusTrap)
+ * @dependency keyboard-accessory.js (MobileTerminalControls, FocusTrap)
  * @dependency vendor/xterm.js, vendor/xterm-addon-fit.js, vendor/xterm-addon-webgl.js
  * @dependency vendor/xterm-zerolag-input.iife.js (LocalEchoOverlay)
  * @loadorder 6 of 15 — loaded after keyboard-accessory.js, before terminal-ui.js
@@ -790,10 +790,14 @@ class CodemanApp {
     KeyboardHandler.init();
     SwipeHandler.init();
     VoiceInput.init();
-    KeyboardAccessoryBar.init();
-    // Apply keyboard bar mode from settings
+    // One setting controls both mobile terminal-control surfaces: the
+    // keyboard-hidden menu pad and the keyboard-open accessory bar.
     const _kbSettings = this.loadAppSettingsFromStorage();
-    if (_kbSettings.extendedKeyboardBar) KeyboardAccessoryBar.setMode('extended');
+    const _kbDefaults = this.getDefaultSettings();
+    MobileTerminalControls.configureFeedback(_kbSettings, _kbDefaults);
+    MobileTerminalControls.init(
+      MobileTerminalControls.resolveEnabled(_kbSettings, _kbDefaults)
+    );
     this.applyHeaderVisibilitySettings();
     this.restorePlanUsageChip();
     this.applySkin();
diff --git a/src/web/public/i18n.js b/src/web/public/i18n.js
index 4ea11c50..0b35ef8e 100644
--- a/src/web/public/i18n.js
+++ b/src/web/public/i18n.js
@@ -281,12 +281,16 @@
     Input: '输入',
     'Local Echo': '本地回显',
     'CJK Input': '中日韩输入',
-    'Extended Keyboard Bar': '扩展键盘栏',
+    'Mobile Terminal Controls': '移动终端控制',
+    'Control Haptics': '控制振动',
+    'Control Sounds': '控制音效',
     'Gesture Control (beta)': '手势控制（测试版）',
     'Wheel Scrolls Local History': '滚轮滚动本地历史',
     'Instant typing feedback with local echo': '通过本地回显即时显示输入',
     'Dedicated IME input field for CJK languages': '为中日韩语言提供专用输入法文本框',
-    'Extra keys: Tab, Esc, arrows, Ctrl+O': '附加按键：Tab、Esc、方向键、Ctrl+O',
+    'Esc, menu navigation, Tab, and keyboard-open shortcuts': 'Esc、菜单导航、Tab 和键盘打开时的快捷键',
+    'Brief vibration on terminal controls': '操作终端控件时短暂振动',
+    'Quiet tone on terminal controls': '操作终端控件时播放轻提示音',
 
     // CLI / model settings
     'Startup Mode': '启动模式',
@@ -665,8 +669,10 @@
       '通过覆盖层即时显示输入，同时在后台把按键转发到服务器。支持 Tab 补全、切换标签时保留输入并防止会话崩溃丢字；推荐移动端和高延迟连接使用。',
     "Show a dedicated input field below the terminal for CJK (Chinese/Japanese/Korean) IME composition. Recommended for mobile devices with Chinese input methods where xterm's native input handling may drop characters.":
       '在终端下方显示中日韩输入法专用文本框。推荐在可能因 xterm 原生输入而丢字的移动端中文输入法中使用。',
-    'Show additional buttons (Tab, Shift+Tab, Ctrl+O, Esc, Alt+Enter, left/right arrows) in the mobile keyboard accessory bar.':
-      '在移动端键盘工具栏显示附加按键（Tab、Shift+Tab、Ctrl+O、Esc、Alt+Enter、左右方向键）。',
+    'Show Esc, Up, Enter, Down, and Tab controls while the mobile keyboard is hidden, plus the full terminal key bar while it is open. Hardware volume keys are used when the browser exposes them; press both directions together for Enter.':
+      '移动键盘隐藏时显示 Esc、上、Enter、下和 Tab 控件，键盘打开时显示完整终端按键栏。浏览器支持时可使用硬件音量键；同时按下两个方向键可发送 Enter。',
+    'Vibrate briefly after a mobile terminal control is accepted.': '移动终端控件生效后短暂振动。',
+    'Play a short, quiet tone after a mobile terminal control is accepted.': '移动终端控件生效后播放短促轻柔的提示音。',
     'Scroll local history (when mouse passthrough is active)': '滚动本地历史（鼠标直通启用时）',
     'Plain wheel/trackpad pages the terminal scrollback': '使用普通滚轮/触控板翻阅终端历史',
     'Camera hand-tracking overlay (applied on reload)': '摄像头手势跟踪覆盖层（重新加载后生效）',
diff --git a/src/web/public/index.html b/src/web/public/index.html
index 224280db..49372290 100644
--- a/src/web/public/index.html
+++ b/src/web/public/index.html
@@ -6,7 +6,7 @@
        served at /session/:id (detached single-session window) without 404ing
        on relative <script>/<link> URLs. Must precede the first resource tag. -->
   <base href="/">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover, interactive-widget=resizes-content">
   <meta name="description" content="Claude Code session manager with web interface">
   <meta name="theme-color" content="#11151c">
   <meta name="google" content="notranslate">
@@ -1285,6 +1285,36 @@ <h3>App Settings</h3>
               </div>
               <!-- Input Section -->
               <div class="settings-section-header">Input</div>
+              <div class="settings-item settings-item-multiline" id="appSettingsMobileTerminalControlsItem" title="Show Esc, Up, Enter, Down, and Tab controls while the mobile keyboard is hidden, plus the full terminal key bar while it is open. Hardware volume keys are used when the browser exposes them; press both directions together for Enter.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">Mobile Terminal Controls</span>
+                  <span class="settings-item-desc">Esc, menu navigation, Tab, and keyboard-open shortcuts</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsMobileTerminalControls" checked>
+                  <span class="slider"></span>
+                </label>
+              </div>
+              <div class="settings-item settings-item-multiline" id="appSettingsMobileControlHapticsItem" title="Vibrate briefly after a mobile terminal control is accepted.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">Control Haptics</span>
+                  <span class="settings-item-desc">Brief vibration on terminal controls</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsMobileControlHaptics" checked>
+                  <span class="slider"></span>
+                </label>
+              </div>
+              <div class="settings-item settings-item-multiline" id="appSettingsMobileControlSoundItem" title="Play a short, quiet tone after a mobile terminal control is accepted.">
+                <div class="settings-item-text">
+                  <span class="settings-item-label">Control Sounds</span>
+                  <span class="settings-item-desc">Quiet tone on terminal controls</span>
+                </div>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsMobileControlSound">
+                  <span class="slider"></span>
+                </label>
+              </div>
               <div class="settings-item settings-item-multiline" title="Scroll the terminal's own local scrollback with a plain mouse wheel / two-finger swipe, instead of forwarding the wheel to the CLI's transcript. Turn on if scrolling back through history doesn't work (e.g. macOS trackpad in Claude sessions). Shift+wheel always reaches local scrollback regardless.">
                 <div class="settings-item-text">
                   <span class="settings-item-label">Wheel Scrolls Local History</span>
@@ -1316,16 +1346,6 @@ <h3>App Settings</h3>
                 </label>
               </div>
 
-              <div class="settings-item settings-item-multiline" title="Show additional buttons (Tab, Shift+Tab, Ctrl+O, Esc, Alt+Enter, left/right arrows) in the mobile keyboard accessory bar.">
-                <div class="settings-item-text">
-                  <span class="settings-item-label">Extended Keyboard Bar</span>
-                  <span class="settings-item-desc">Extra keys: Tab, Esc, arrows, Ctrl+O</span>
-                </div>
-                <label class="switch switch-sm">
-                  <input type="checkbox" id="appSettingsExtendedKeyboardBar">
-                  <span class="slider"></span>
-                </label>
-              </div>
               <div class="settings-item settings-item-multiline" id="appSettingsGestureControlItem" title="Enable the camera hand-tracking gesture overlay (applied on reload). The instance must run with CODEMAN_GESTURE=1.">
                 <div class="settings-item-text">
                   <span class="settings-item-label">Gesture Control (beta)</span>
diff --git a/src/web/public/keyboard-accessory.js b/src/web/public/keyboard-accessory.js
index 68e08fd2..d9b5d374 100644
--- a/src/web/public/keyboard-accessory.js
+++ b/src/web/public/keyboard-accessory.js
@@ -1,10 +1,14 @@
 /**
- * @fileoverview Mobile keyboard accessory bar and modal focus trap.
+ * @fileoverview Mobile keyboard controls and modal focus trap.
  *
- * Defines three exports:
+ * Defines five exports:
+ *
+ * - MobileTerminalControls (singleton object) — Product-level facade that owns
+ *   initialization, enablement, modal visibility, and shared key mappings for
+ *   both responsive control surfaces.
  *
  * - KeyboardAccessoryBar (singleton object) — Quick action buttons shown above the virtual
- *   keyboard on mobile: arrow up/down, /init, /clear, /compact, paste, Esc, and dismiss.
+ *   keyboard on mobile: arrows, Tab, Esc, commands, paste, and dismiss.
  *   The paste button opens a dialog that handles both text paste and image attach
  *   (native picker + best-effort image paste, routed through app._uploadAndInsertImages).
  *   Destructive actions (/clear, /compact) require double-tap confirmation (2s amber state).
@@ -13,12 +17,18 @@
  * - PathPicker (singleton object) — Lazy server-side file/folder browser shared
  *   by Link Existing and the extended mobile keyboard bar.
  *
+ * - MobileNavigationPad (singleton object) — Keyboard-hidden Esc/Up/Enter/Down/Tab controls
+ *   for terminal menus. A simultaneous Up+Down press emits Enter, and vertical swipes on
+ *   the surrounding bar emit arrow keys without focusing xterm or opening the keyboard.
+ *
  * - FocusTrap (class) — Traps Tab/Shift+Tab keyboard focus within a modal element.
  *   Saves and restores previously focused element on deactivate. Used by Ralph wizard
  *   and other modal dialogs.
  *
  * @globals {object} KeyboardAccessoryBar
  * @globals {object} PathPicker
+ * @globals {object} MobileNavigationPad
+ * @globals {object} MobileTerminalControls
  * @globals {class} FocusTrap
  *
  * @dependency mobile-handlers.js (MobileDetection.isTouchDevice)
@@ -29,6 +39,31 @@
 // Codeman — Keyboard accessory bar and focus trap for modals
 // Loaded after mobile-handlers.js, before app.js
 
+const TERMINAL_CONTROL_SEQUENCES = Object.freeze({
+  up: '\x1b[A',
+  down: '\x1b[B',
+  left: '\x1b[D',
+  right: '\x1b[C',
+  enter: '\r',
+  esc: '\x1b',
+  tab: '\t',
+  shiftTab: '\x1b[Z',
+  ctrlO: '\x0f',
+  optionEnter: '\x1b\r',
+});
+
+const TERMINAL_ACCESSORY_KEY_ACTIONS = Object.freeze({
+  'scroll-up': 'up',
+  'scroll-down': 'down',
+  'arrow-left': 'left',
+  'arrow-right': 'right',
+  esc: 'esc',
+  'opt-enter': 'optionEnter',
+  tab: 'tab',
+  'shift-tab': 'shiftTab',
+  'ctrl-o': 'ctrlO',
+});
+
 // ═══════════════════════════════════════════════════════════════
 // Shared Filesystem Path Picker
 // ═══════════════════════════════════════════════════════════════
@@ -370,57 +405,34 @@ const PathPicker = {
  */
 const KeyboardAccessoryBar = {
   element: null,
-  _mode: 'simple', // 'simple' or 'extended'
+  enabled: false,
 
-  /** HTML for simple mode: arrows, commands, paste, Esc, dismiss */
-  _simpleButtons: `
-      <button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
-        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
-          <path d="M5 15l7-7 7 7"/>
-        </svg>
-      </button>
-      <button class="accessory-btn accessory-btn-arrow" data-action="scroll-down" title="Arrow down">
+  /** Full keyboard-open control set. */
+  _buttons: `
+      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
+      <button class="accessory-btn accessory-btn-arrow" data-action="arrow-left" title="Arrow left">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
-          <path d="M19 9l-7 7-7-7"/>
-        </svg>
-      </button>
-      <button class="accessory-btn" data-action="init" title="/init">/init</button>
-      <button class="accessory-btn" data-action="clear" title="/clear">/clear</button>
-      <button class="accessory-btn" data-action="paste" title="Paste from clipboard">
-        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-          <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>
-          <rect x="8" y="2" width="8" height="4" rx="1" ry="1"/>
+          <path d="M15 19l-7-7 7-7"/>
         </svg>
       </button>
-      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
-      <button class="accessory-btn accessory-btn-dismiss" data-action="dismiss" title="Dismiss keyboard">
-        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
-          <path d="M19 9l-7 7-7-7"/>
-        </svg>
-      </button>`,
-
-  /** HTML for extended mode: all keys including arrows, Tab, Esc, etc. */
-  _extendedButtons: `
       <button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
           <path d="M5 15l7-7 7 7"/>
         </svg>
       </button>
+      <button class="accessory-btn" data-action="opt-enter" title="Option+Enter (newline)">⌥Enter</button>
       <button class="accessory-btn accessory-btn-arrow" data-action="scroll-down" title="Arrow down">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
           <path d="M19 9l-7 7-7-7"/>
         </svg>
       </button>
-      <button class="accessory-btn accessory-btn-arrow" data-action="arrow-left" title="Arrow left">
-        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
-          <path d="M15 19l-7-7 7-7"/>
-        </svg>
-      </button>
       <button class="accessory-btn accessory-btn-arrow" data-action="arrow-right" title="Arrow right">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
           <path d="M9 5l7 7-7 7"/>
         </svg>
       </button>
+      <button class="accessory-btn" data-action="tab" title="Tab">Tab</button>
+      <button class="accessory-btn" data-action="shift-tab" title="Shift+Tab">⇧Tab</button>
       <button class="accessory-btn" data-action="paste" title="Paste from clipboard">
         <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
           <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>
@@ -429,12 +441,8 @@ const KeyboardAccessoryBar = {
       </button>
       <button class="accessory-btn" data-action="pick-path" title="Insert a file or folder path">&#x1F4C1; Path</button>
       <button class="accessory-btn" data-action="clear-input" title="Clear the current unsent input">&#x232B; All</button>
-      <button class="accessory-btn" data-action="tab" title="Tab">Tab</button>
-      <button class="accessory-btn" data-action="shift-tab" title="Shift+Tab">⇧Tab</button>
       <button class="accessory-btn" data-action="effort-max" title="/effort max">Max</button>
       <button class="accessory-btn" data-action="ctrl-o" title="Ctrl+O">⌃O</button>
-      <button class="accessory-btn" data-action="opt-enter" title="Option+Enter (newline)">⌥Enter</button>
-      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
       <button class="accessory-btn" data-action="init" title="/init">/init</button>
       <button class="accessory-btn" data-action="clear" title="/clear">/clear</button>
       <button class="accessory-btn" data-action="compact" title="/compact">/compact</button>
@@ -447,12 +455,12 @@ const KeyboardAccessoryBar = {
   /** Create and inject the accessory bar */
   init() {
     // Only on mobile
-    if (!MobileDetection.isTouchDevice()) return;
+    if (!MobileDetection.isTouchDevice() || this.element) return;
 
     // Create accessory bar element
     this.element = document.createElement('div');
     this.element.className = 'keyboard-accessory-bar';
-    this.element.innerHTML = this._simpleButtons;
+    this.element.innerHTML = this._buttons;
 
     // Add click handlers — preventDefault stops event from reaching terminal
     this.element.addEventListener('click', (e) => {
@@ -481,12 +489,24 @@ const KeyboardAccessoryBar = {
     }
   },
 
-  /** Switch between 'simple' and 'extended' button layouts */
-  setMode(mode) {
-    if (mode === this._mode || !this.element) return;
-    this._mode = mode;
-    this.clearConfirm();
-    this.element.innerHTML = mode === 'extended' ? this._extendedButtons : this._simpleButtons;
+  /** Enable or disable the keyboard-open surface of mobile terminal controls. */
+  setEnabled(enabled) {
+    this.enabled = enabled === true;
+    this.syncVisibility();
+  },
+
+  /** Match the accessory surface to keyboard and modal state. */
+  syncVisibility() {
+    if (!this.element) return;
+    const keyboardVisible =
+      (typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible) ||
+      document.body.classList.contains('keyboard-visible');
+    const hasSession = typeof app !== 'undefined' && Boolean(app.activeSessionId);
+    const hasOpenDialog = MobileTerminalControls.hasOpenDialog();
+    const visible = this.enabled && hasSession && keyboardVisible && !hasOpenDialog;
+    this.element.classList.toggle('visible', visible);
+    document.body.classList.toggle('keyboard-accessory-visible', visible);
+    if (!visible) this.clearConfirm();
   },
 
   _confirmTimer: null,
@@ -495,35 +515,13 @@ const KeyboardAccessoryBar = {
   /** Handle accessory button actions */
   handleAction(action, btn) {
     if (typeof app === 'undefined' || !app.activeSessionId) return;
+    const terminalKey = TERMINAL_ACCESSORY_KEY_ACTIONS[action];
+    if (terminalKey) {
+      MobileTerminalControls.sendKey(terminalKey);
+      return;
+    }
 
     switch (action) {
-      case 'scroll-up':
-        this.sendKey('\x1b[A');
-        break;
-      case 'scroll-down':
-        this.sendKey('\x1b[B');
-        break;
-      case 'arrow-left':
-        this.sendKey('\x1b[D');
-        break;
-      case 'arrow-right':
-        this.sendKey('\x1b[C');
-        break;
-      case 'esc':
-        this.sendKey('\x1b');
-        break;
-      case 'opt-enter':
-        this.sendKey('\x1b\r');
-        break;
-      case 'tab':
-        this.sendKey('\t');
-        break;
-      case 'shift-tab':
-        this.sendKey('\x1b[Z');
-        break;
-      case 'ctrl-o':
-        this.sendKey('\x0f');
-        break;
       case 'effort-max':
         this.sendCommand('/effort max');
         break;
@@ -554,7 +552,10 @@ const KeyboardAccessoryBar = {
         // Blur active element to dismiss keyboard
         document.activeElement?.blur();
         break;
+      default:
+        return;
     }
+    MobileTerminalControls.feedback(action);
   },
 
   /** Enter confirm state: button turns amber for 2s waiting for second tap */
@@ -596,18 +597,6 @@ const KeyboardAccessoryBar = {
     setTimeout(() => app.sendInput('\r'), 120);
   },
 
-  /** Send a special key (arrow, escape, etc.) directly to the PTY.
-   *  Bypasses tmux send-keys -l (literal mode) since escape sequences
-   *  must be written raw to be interpreted as key presses by Ink. */
-  sendKey(escapeSequence) {
-    if (!app.activeSessionId) return;
-    fetch(`/api/sessions/${app.activeSessionId}/input`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ input: escapeSequence })
-    }).catch(() => {});
-  },
-
   /** Browse the active session's workspace and insert a selected path without Enter. */
   pickPath() {
     if (!app.activeSessionId) return;
@@ -706,19 +695,520 @@ const KeyboardAccessoryBar = {
     textarea.focus();
   },
 
-  /** Show the accessory bar */
-  show() {
-    if (this.element) {
-      this.element.classList.add('visible');
+};
+
+// ═══════════════════════════════════════════════════════════════
+// Keyboard-hidden terminal navigation
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * MobileNavigationPad - Persistent terminal-menu controls for phone layouts.
+ *
+ * Arrow actions are emitted on pointer release so a second simultaneous pointer
+ * can turn an Up+Down pair into Enter without leaking the first arrow.
+ */
+const MobileNavigationPad = {
+  element: null,
+  enabled: false,
+  _pointers: new Map(),
+  _consumedPointers: new Set(),
+  _chordActive: false,
+  _volumeKeys: new Map(),
+  _volumeChordActive: false,
+  _swipeDistance: 36,
+  _swipeTime: 600,
+
+  _buttons: `
+    <button type="button" class="mobile-terminal-nav-btn mobile-terminal-nav-key"
+            data-nav-key="esc" aria-label="Escape" title="Escape">Esc</button>
+    <button type="button" class="mobile-terminal-nav-btn" data-nav-key="up"
+            aria-label="Terminal menu up" title="Terminal menu up">
+      <svg viewBox="0 0 24 24" aria-hidden="true">
+        <path d="m6 15 6-6 6 6"/>
+      </svg>
+    </button>
+    <button type="button" class="mobile-terminal-nav-btn mobile-terminal-nav-enter"
+            data-nav-key="enter" aria-label="Terminal menu enter" title="Enter">
+      <svg viewBox="0 0 24 24" aria-hidden="true">
+        <path d="M9 10 4 15l5 5"/>
+        <path d="M20 4v7a4 4 0 0 1-4 4H4"/>
+      </svg>
+    </button>
+    <button type="button" class="mobile-terminal-nav-btn" data-nav-key="down"
+            aria-label="Terminal menu down" title="Terminal menu down">
+      <svg viewBox="0 0 24 24" aria-hidden="true">
+        <path d="m6 9 6 6 6-6"/>
+      </svg>
+    </button>
+    <button type="button" class="mobile-terminal-nav-btn mobile-terminal-nav-key"
+            data-nav-key="tab" aria-label="Tab" title="Tab">Tab</button>`,
+
+  init(enabled = false) {
+    if (!MobileDetection.isTouchDevice() || this.element) return;
+
+    this.element = document.createElement('div');
+    this.element.className = 'mobile-terminal-nav';
+    this.element.setAttribute('role', 'group');
+    this.element.setAttribute('aria-label', 'Terminal menu navigation');
+    this.element.setAttribute('aria-hidden', 'true');
+    this.element.innerHTML = this._buttons;
+
+    this._pointerDownHandler = (e) => this.onPointerDown(e);
+    this._pointerUpHandler = (e) => this.onPointerUp(e);
+    this._pointerCancelHandler = (e) => this.onPointerCancel(e);
+    this._clickHandler = (e) => this.onClick(e);
+    this._volumeKeyDownHandler = (e) => this.onVolumeKeyDown(e);
+    this._volumeKeyUpHandler = (e) => this.onVolumeKeyUp(e);
+
+    this.element.addEventListener('pointerdown', this._pointerDownHandler);
+    this.element.addEventListener('pointerup', this._pointerUpHandler);
+    this.element.addEventListener('pointercancel', this._pointerCancelHandler);
+    this.element.addEventListener('lostpointercapture', this._pointerCancelHandler);
+    this.element.addEventListener('click', this._clickHandler);
+    document.addEventListener('keydown', this._volumeKeyDownHandler, true);
+    document.addEventListener('keyup', this._volumeKeyUpHandler, true);
+    document.body.appendChild(this.element);
+
+    this.setEnabled(enabled);
+  },
+
+  setEnabled(enabled) {
+    this.enabled = enabled === true;
+    this.syncVisibility();
+  },
+
+  syncVisibility() {
+    if (!this.element) return;
+
+    const keyboardVisible =
+      (typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible) ||
+      document.body.classList.contains('keyboard-visible');
+    const isPhoneLayout =
+      typeof MobileDetection !== 'undefined' &&
+      MobileDetection.isTouchDevice() &&
+      MobileDetection.getDeviceType() !== 'desktop';
+    const hasSession = typeof app !== 'undefined' && Boolean(app.activeSessionId);
+    const hasOpenDialog = MobileTerminalControls.hasOpenDialog();
+    const visible =
+      this.enabled && isPhoneLayout && hasSession && !keyboardVisible && !hasOpenDialog;
+
+    this.element.classList.toggle('visible', visible);
+    this.element.setAttribute('aria-hidden', visible ? 'false' : 'true');
+    for (const button of this.element.querySelectorAll('button')) {
+      button.disabled = !visible;
+    }
+    document.body.classList.toggle('mobile-nav-visible', visible);
+
+    if (!visible) {
+      this.resetPointers();
+      this.resetVolumeKeys();
     }
   },
 
-  /** Hide the accessory bar */
-  hide() {
-    if (this.element) {
-      this.element.classList.remove('visible');
+  blurTerminalInput() {
+    const active = document.activeElement;
+    const terminalTextarea =
+      typeof app !== 'undefined' && app.terminal ? app.terminal.textarea : null;
+    const isTerminalInput =
+      active === terminalTextarea ||
+      active?.classList?.contains('xterm-helper-textarea') ||
+      active?.id === 'cjkInput';
+    if (isTerminalInput) active.blur();
+  },
+
+  onPointerDown(e) {
+    if (!this.element?.classList.contains('visible')) return;
+
+    const button = e.target.closest?.('[data-nav-key]');
+    const key = button?.dataset.navKey || 'swipe';
+    // Android can leave xterm's hidden textarea focused after the user dismisses
+    // the keyboard. Release it inside the trusted touch gesture before sending
+    // terminal input, otherwise the same gesture may reopen the keyboard.
+    this.blurTerminalInput();
+    e.preventDefault();
+    e.stopPropagation();
+
+    this._pointers.set(e.pointerId, {
+      key,
+      button: button || null,
+      startY: e.clientY,
+      startedAt: Date.now(),
+    });
+    button?.classList.add('pressed');
+
+    try {
+      (button || this.element).setPointerCapture?.(e.pointerId);
+    } catch {
+      // Synthetic test events are not registered as active OS pointers.
     }
-  }
+
+    if ((key === 'up' || key === 'down') && !this._chordActive) {
+      const opposite = key === 'up' ? 'down' : 'up';
+      const oppositeEntry = [...this._pointers.entries()].find(
+        ([pointerId, state]) => pointerId !== e.pointerId && state.key === opposite
+      );
+      if (oppositeEntry) {
+        this._consumedPointers.add(e.pointerId);
+        this._consumedPointers.add(oppositeEntry[0]);
+        this._chordActive = true;
+        this.element.classList.add('chord-active');
+        this.sendKey('enter');
+      }
+    }
+  },
+
+  onPointerUp(e) {
+    const state = this._pointers.get(e.pointerId);
+    if (!state) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    const consumed = this._consumedPointers.has(e.pointerId);
+
+    if (!consumed) {
+      if (state.key === 'swipe') {
+        const elapsed = Date.now() - state.startedAt;
+        const deltaY = e.clientY - state.startY;
+        if (elapsed <= this._swipeTime && Math.abs(deltaY) >= this._swipeDistance) {
+          this.sendKey(deltaY < 0 ? 'up' : 'down');
+        }
+      } else {
+        this.sendKey(state.key);
+      }
+    }
+
+    this.releasePointer(e.pointerId, state);
+  },
+
+  onPointerCancel(e) {
+    const state = this._pointers.get(e.pointerId);
+    if (!state) return;
+    this.releasePointer(e.pointerId, state);
+  },
+
+  releasePointer(pointerId, state) {
+    this._pointers.delete(pointerId);
+    this._consumedPointers.delete(pointerId);
+
+    if (
+      state.button &&
+      ![...this._pointers.values()].some((pointer) => pointer.button === state.button)
+    ) {
+      state.button.classList.remove('pressed');
+    }
+
+    const pointerDirectionHeld = [...this._pointers.values()].some(
+      (pointer) => pointer.key === 'up' || pointer.key === 'down'
+    );
+    if (!pointerDirectionHeld) {
+      this._chordActive = false;
+      this.syncChordVisual();
+    }
+  },
+
+  onClick(e) {
+    const button = e.target.closest?.('[data-nav-key]');
+    if (!button) return;
+
+    this.blurTerminalInput();
+    e.preventDefault();
+    e.stopPropagation();
+    // Pointer input is handled above. detail=0 preserves keyboard/switch-control activation.
+    if (e.detail === 0 && this.element?.classList.contains('visible')) {
+      this.sendKey(button.dataset.navKey);
+    }
+  },
+
+  volumeDirection(e) {
+    const values = [e.key, e.code];
+    if (values.includes('AudioVolumeUp') || values.includes('VolumeUp')) return 'up';
+    if (values.includes('AudioVolumeDown') || values.includes('VolumeDown')) return 'down';
+    return null;
+  },
+
+  onVolumeKeyDown(e) {
+    const direction = this.volumeDirection(e);
+    if (!direction || !this.element?.classList.contains('visible')) return;
+
+    this.blurTerminalInput();
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.repeat) return;
+
+    // Recover from a missing keyup before recording a fresh physical press.
+    if (this._volumeKeys.has(direction)) {
+      this.releaseVolumeKey(direction);
+    }
+
+    const state = { consumed: false };
+    this._volumeKeys.set(direction, state);
+    this.syncDirectionPressed(direction);
+
+    const opposite = direction === 'up' ? 'down' : 'up';
+    const oppositeState = this._volumeKeys.get(opposite);
+    if (oppositeState && !this._volumeChordActive) {
+      state.consumed = true;
+      oppositeState.consumed = true;
+      this._volumeChordActive = true;
+      this.syncChordVisual();
+      this.sendKey('enter');
+    }
+  },
+
+  onVolumeKeyUp(e) {
+    const direction = this.volumeDirection(e);
+    const state = direction && this._volumeKeys.get(direction);
+    if (!state) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    if (!state.consumed && this.element?.classList.contains('visible')) {
+      this.sendKey(direction);
+    }
+    this.releaseVolumeKey(direction);
+  },
+
+  releaseVolumeKey(direction) {
+    this._volumeKeys.delete(direction);
+    this.syncDirectionPressed(direction);
+
+    if (this._volumeKeys.size === 0) {
+      this._volumeChordActive = false;
+      this.syncChordVisual();
+    }
+  },
+
+  syncDirectionPressed(direction) {
+    const button = this.element?.querySelector(`[data-nav-key="${direction}"]`);
+    if (!button) return;
+
+    const pointerHeld = [...this._pointers.values()].some(
+      (pointer) => pointer.key === direction
+    );
+    button.classList.toggle('pressed', pointerHeld || this._volumeKeys.has(direction));
+  },
+
+  syncChordVisual() {
+    this.element?.classList.toggle(
+      'chord-active',
+      this._chordActive || this._volumeChordActive
+    );
+  },
+
+  sendKey(key) {
+    MobileTerminalControls.sendKey(key);
+  },
+
+  resetPointers() {
+    this._pointers.clear();
+    this._consumedPointers.clear();
+    this._chordActive = false;
+    this.element?.classList.remove('chord-active');
+    for (const button of this.element?.querySelectorAll('.pressed') || []) {
+      button.classList.remove('pressed');
+    }
+  },
+
+  resetVolumeKeys() {
+    this._volumeKeys.clear();
+    this._volumeChordActive = false;
+    this.syncChordVisual();
+    for (const direction of ['up', 'down']) {
+      this.syncDirectionPressed(direction);
+    }
+  },
+
+  cleanup() {
+    if (!this.element) return;
+    this.resetPointers();
+    this.resetVolumeKeys();
+    this.element.removeEventListener('pointerdown', this._pointerDownHandler);
+    this.element.removeEventListener('pointerup', this._pointerUpHandler);
+    this.element.removeEventListener('pointercancel', this._pointerCancelHandler);
+    this.element.removeEventListener('lostpointercapture', this._pointerCancelHandler);
+    this.element.removeEventListener('click', this._clickHandler);
+    document.removeEventListener('keydown', this._volumeKeyDownHandler, true);
+    document.removeEventListener('keyup', this._volumeKeyUpHandler, true);
+    this.element.remove();
+    this.element = null;
+    document.body.classList.remove('mobile-nav-visible');
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════
+// Unified mobile terminal controls
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * MobileTerminalControls - Product-level owner for the two responsive surfaces.
+ */
+const MobileTerminalControls = {
+  enabled: false,
+  hapticsEnabled: true,
+  soundEnabled: false,
+  _audioContext: null,
+  _modalObserver: null,
+
+  /**
+   * Resolve the canonical per-device setting while preserving both shipped
+   * legacy formats. The old extendedKeyboardBar=false selected a smaller bar;
+   * it never disabled mobile controls. Only explicit canonical or legacy
+   * enablement turns the consolidated controls on.
+   */
+  resolveEnabled(settings = {}, defaults = {}, isTouchDevice = null) {
+    if (typeof settings?.mobileTerminalControlsEnabled === 'boolean') {
+      return settings.mobileTerminalControlsEnabled;
+    }
+    if (typeof settings?.mobileNavigationPadEnabled === 'boolean') {
+      return settings.mobileNavigationPadEnabled;
+    }
+    if (typeof defaults?.mobileTerminalControlsEnabled === 'boolean') {
+      return defaults.mobileTerminalControlsEnabled;
+    }
+    if (settings?.extendedKeyboardBar === true || defaults?.extendedKeyboardBar === true) {
+      return true;
+    }
+    return false;
+  },
+
+  init(enabled = false) {
+    KeyboardAccessoryBar.init();
+    MobileNavigationPad.init(false);
+    this._installModalObserver();
+    this.setEnabled(enabled);
+  },
+
+  configureFeedback(settings = {}, defaults = {}) {
+    this.hapticsEnabled =
+      settings.mobileControlHaptics ?? defaults.mobileControlHaptics ?? true;
+    this.soundEnabled =
+      settings.mobileControlSound ?? defaults.mobileControlSound ?? false;
+  },
+
+  setEnabled(enabled) {
+    this.enabled = enabled === true;
+    KeyboardAccessoryBar.setEnabled(this.enabled);
+    MobileNavigationPad.setEnabled(this.enabled);
+  },
+
+  syncVisibility() {
+    KeyboardAccessoryBar.syncVisibility();
+    MobileNavigationPad.syncVisibility();
+  },
+
+  sendKey(action) {
+    const sequence = TERMINAL_CONTROL_SEQUENCES[action];
+    if (!sequence || typeof app === 'undefined' || !app.activeSessionId) return;
+    app.sendTerminalKey(sequence);
+    this.feedback(action);
+  },
+
+  feedback(action) {
+    if (this.hapticsEnabled && navigator.vibrate) {
+      try {
+        navigator.vibrate(action === 'enter' ? 18 : 10);
+      } catch {
+        // Vibration is optional and may be blocked by browser policy.
+      }
+    }
+    if (!this.soundEnabled) return;
+
+    const AudioContext = window.AudioContext || window.webkitAudioContext;
+    if (!AudioContext) return;
+    try {
+      const context = this._audioContext || new AudioContext();
+      this._audioContext = context;
+      const play = () => {
+        const oscillator = context.createOscillator();
+        const gain = context.createGain();
+        const now = context.currentTime;
+        const frequencies = { up: 620, down: 440, enter: 760, esc: 320, tab: 540 };
+        oscillator.type = 'sine';
+        oscillator.frequency.setValueAtTime(frequencies[action] || 500, now);
+        gain.gain.setValueAtTime(0.025, now);
+        gain.gain.exponentialRampToValueAtTime(0.0001, now + 0.035);
+        oscillator.connect(gain);
+        gain.connect(context.destination);
+        oscillator.start(now);
+        oscillator.stop(now + 0.04);
+      };
+      if (context.state === 'suspended') {
+        context.resume().then(play).catch(() => {});
+      } else {
+        play();
+      }
+    } catch {
+      // Audio feedback is best-effort on browsers without a usable Web Audio context.
+    }
+  },
+
+  /** True when a pointer target will perform its own semantic key claim. */
+  isKeyControlTarget(target) {
+    if (!target?.closest) return false;
+    if (target.closest('.mobile-terminal-nav')) return true;
+    const accessoryButton = target.closest('.keyboard-accessory-bar [data-action]');
+    return Boolean(TERMINAL_ACCESSORY_KEY_ACTIONS[accessoryButton?.dataset.action]);
+  },
+
+  /** Match every modal convention currently used by Codeman's UI modules. */
+  hasOpenDialog() {
+    return [...document.querySelectorAll('.modal')].some((modal) => {
+      if (
+        modal.classList.contains('active') ||
+        modal.classList.contains('show') ||
+        modal.hasAttribute('open')
+      ) {
+        return true;
+      }
+      return Boolean(modal.style.display && modal.style.display !== 'none');
+    });
+  },
+
+  _installModalObserver() {
+    if (
+      this._modalObserver ||
+      typeof MobileDetection === 'undefined' ||
+      !MobileDetection.isTouchDevice()
+    ) {
+      return;
+    }
+    this._modalObserver = new MutationObserver((mutations) => {
+      if (
+        mutations.some(
+          (mutation) =>
+            mutation.target.classList?.contains('modal') ||
+            (mutation.type === 'childList' &&
+              [...mutation.addedNodes, ...mutation.removedNodes].some(
+                (node) =>
+                  node.nodeType === Node.ELEMENT_NODE &&
+                  (node.matches?.('.modal') || node.querySelector?.('.modal'))
+              ))
+        )
+      ) {
+        this.syncVisibility();
+      }
+    });
+    this._modalObserver.observe(document.body, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ['class', 'style', 'open'],
+    });
+  },
+
+  cleanup() {
+    this._modalObserver?.disconnect();
+    this._modalObserver = null;
+    MobileNavigationPad.cleanup();
+    KeyboardAccessoryBar.clearConfirm();
+    KeyboardAccessoryBar.element?.remove();
+    KeyboardAccessoryBar.element = null;
+    KeyboardAccessoryBar.enabled = false;
+    document.body.classList.remove('keyboard-accessory-visible');
+    this._audioContext?.close?.().catch?.(() => {});
+    this._audioContext = null;
+    this.enabled = false;
+  },
 };
 
 // ═══════════════════════════════════════════════════════════════
diff --git a/src/web/public/mobile-handlers.js b/src/web/public/mobile-handlers.js
index 5b8b99a5..7608b729 100644
--- a/src/web/public/mobile-handlers.js
+++ b/src/web/public/mobile-handlers.js
@@ -18,7 +18,7 @@
  * @globals {object} KeyboardHandler
  * @globals {object} SwipeHandler
  *
- * @dependency keyboard-accessory.js (KeyboardAccessoryBar reference in KeyboardHandler.onKeyboardShow, soft — guarded with typeof check)
+ * @dependency keyboard-accessory.js (MobileTerminalControls references in KeyboardHandler, soft — guarded with typeof checks)
  * @loadorder 2 of 15 — loaded after constants.js, before voice-input.js
  */
 
@@ -115,6 +115,7 @@ const MobileDetection = {
       'device-tablet',
       'device-desktop',
       'touch-device',
+      'handheld-device',
       'ios-device',
       'safari-browser'
     );
@@ -127,6 +128,10 @@ const MobileDetection = {
       body.classList.add('touch-device');
     }
 
+    if (this.isHandheldDevice()) {
+      body.classList.add('handheld-device');
+    }
+
     // Add iOS-specific class for safe area handling
     if (this.isIOS()) {
       body.classList.add('ios-device');
@@ -171,6 +176,9 @@ const MobileDetection = {
         // Tab auto-wrap is width-driven, so it must re-evaluate on resize — the only
         // other trigger is a tab content render. No-op on mobile/tablet (method bails).
         if (typeof app !== 'undefined') app.updateTabOverflowMode?.();
+        if (typeof MobileTerminalControls !== 'undefined') {
+          MobileTerminalControls.syncVisibility();
+        }
       }, 100);
     };
     window.addEventListener('resize', this._resizeHandler);
@@ -212,6 +220,7 @@ const KeyboardHandler = {
   lastViewportHeight: 0,
   keyboardVisible: false,
   initialViewportHeight: 0,
+  initialViewportWidth: 0,
 
   /** Initialize keyboard handling */
   init() {
@@ -219,6 +228,7 @@ const KeyboardHandler = {
     if (!MobileDetection.isTouchDevice()) return;
 
     this.initialViewportHeight = window.visualViewport?.height || window.innerHeight;
+    this.initialViewportWidth = window.visualViewport?.width || window.innerWidth;
     this.lastViewportHeight = this.initialViewportHeight;
 
     // Simple focus handler - scroll input into view after keyboard appears
@@ -281,6 +291,16 @@ const KeyboardHandler = {
   /** Handle viewport resize (keyboard show/hide) */
   handleViewportResize() {
     const currentHeight = window.visualViewport?.height || window.innerHeight;
+    const currentWidth = window.visualViewport?.width || window.innerWidth;
+
+    // Keyboard animations often arrive as several sub-threshold resize steps.
+    // Keep the full-height baseline anchored instead of ratcheting it downward.
+    // A substantial width change indicates a rotation or posture change, where
+    // the previous orientation's height is no longer a useful baseline.
+    if (Math.abs(this.initialViewportWidth - currentWidth) > 80) {
+      this.initialViewportHeight = Math.max(currentHeight, window.innerHeight);
+      this.initialViewportWidth = currentWidth;
+    }
     const heightDiff = this.initialViewportHeight - currentHeight;
 
     // Keyboard appeared (viewport shrunk by more than 150px)
@@ -304,10 +324,11 @@ const KeyboardHandler = {
       MobileDetection.updateAppHeight();
     }
 
-    // Update baseline when keyboard is not visible — adapts to address bar
-    // state changes, orientation changes, and other viewport shifts
+    // Grow the baseline while the keyboard is hidden (for example when the
+    // browser address bar collapses), but never lower it during a keyboard
+    // opening animation.
     if (!this.keyboardVisible) {
-      this.initialViewportHeight = currentHeight;
+      this.initialViewportHeight = Math.max(this.initialViewportHeight, currentHeight);
     } else {
       document.documentElement.style.setProperty('--app-height', `${currentHeight}px`);
     }
@@ -326,15 +347,25 @@ const KeyboardHandler = {
     }
 
     const cjkInput = document.getElementById('cjkInput');
-    const isSmallMedium = MobileDetection.isSmallScreen() || MobileDetection.isMediumScreen();
+    const isPhoneLayout = MobileDetection.isHandheldDevice();
+    const isMediumScreen = !isPhoneLayout && window.innerWidth < 768;
 
     if (this.keyboardVisible) {
       const keyboardHeight = this.initialViewportHeight - (window.visualViewport.height || window.innerHeight);
       const accessoryBar = document.querySelector('.keyboard-accessory-bar');
 
-      if (isSmallMedium) {
-        // Phones/small tablets: toolbar and accessory bar are position:fixed
-        // via CSS. Use translateY to lift them above the keyboard.
+      if (isPhoneLayout) {
+        // The phone app is already constrained to the visual viewport. CSS
+        // reserves exactly one accessory row when mobile terminal controls are
+        // enabled; otherwise the terminal reaches the OS keyboard.
+        const toolbar = document.querySelector('.toolbar');
+        const main = document.querySelector('.main');
+        if (toolbar) toolbar.style.transform = '';
+        if (accessoryBar) accessoryBar.style.transform = '';
+        if (main) main.style.paddingBottom = '';
+      } else if (isMediumScreen) {
+        // Small tablets retain fixed controls and use the visual viewport
+        // offset to lift them above the keyboard.
         const toolbar = document.querySelector('.toolbar');
         const main = document.querySelector('.main');
 
@@ -349,8 +380,15 @@ const KeyboardHandler = {
           accessoryBar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
         }
         if (main && keyboardHeight > 0) {
-          const cjkInputHeight = cjkInput?.classList.contains('cjk-input-visible') ? 44 : 0;
-          main.style.paddingBottom = `${84 + cjkInputHeight}px`;
+          const toolbarHeight =
+            toolbar && getComputedStyle(toolbar).display !== 'none' ? toolbar.getBoundingClientRect().height : 0;
+          const accessoryHeight = accessoryBar?.classList.contains('visible')
+            ? accessoryBar.getBoundingClientRect().height
+            : 0;
+          const cjkInputHeight = cjkInput?.classList.contains('cjk-input-visible')
+            ? cjkInput.getBoundingClientRect().height
+            : 0;
+          main.style.paddingBottom = `${toolbarHeight + accessoryHeight + cjkInputHeight}px`;
         }
       } else if (keyboardHeight > 0) {
         // iPad: use direct bottom positioning (translateY unreliable —
@@ -362,16 +400,23 @@ const KeyboardHandler = {
 
       // CJK textarea positioning (always position:fixed on touch devices).
       if (cjkInput?.classList.contains('cjk-input-visible') && keyboardHeight > 0) {
-        if (isSmallMedium) {
-          // Phones: use translateY like toolbar/accessory bar.
+        if (isPhoneLayout) {
+          // Phone CSS keeps the CJK field in terminal-wrap's flex flow.
+          cjkInput.style.transform = '';
+          cjkInput.style.bottom = '';
+        } else if (isMediumScreen) {
+          // Small tablets use the same translation as the fixed controls.
           const layoutHeight = window.innerHeight;
           const visualBottom = window.visualViewport.offsetTop + window.visualViewport.height;
           const keyboardOffset = Math.max(0, layoutHeight - visualBottom);
           cjkInput.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
           cjkInput.style.bottom = '';
         } else {
-          // iPad: direct bottom = keyboard + accessory bar height.
-          cjkInput.style.bottom = `${keyboardHeight + 44}px`;
+          // iPad: direct bottom = keyboard + the currently visible accessory row.
+          const accessoryHeight = accessoryBar?.classList.contains('visible')
+            ? accessoryBar.getBoundingClientRect().height
+            : 0;
+          cjkInput.style.bottom = `${keyboardHeight + accessoryHeight}px`;
           cjkInput.style.transform = '';
         }
       }
@@ -405,10 +450,10 @@ const KeyboardHandler = {
 
   /** Called when keyboard appears */
   onKeyboardShow() {
-    // Show keyboard accessory bar
-    if (typeof KeyboardAccessoryBar !== 'undefined') {
-      KeyboardAccessoryBar.show();
+    if (typeof MobileTerminalControls !== 'undefined') {
+      MobileTerminalControls.syncVisibility();
     }
+    this.updateLayoutForKeyboard();
 
     // Reset any page scroll that occurred during keyboard open.
     // iOS Safari may scroll the document to reveal xterm's hidden textarea.
@@ -447,9 +492,8 @@ const KeyboardHandler = {
 
   /** Called when keyboard hides */
   onKeyboardHide() {
-    // Hide keyboard accessory bar
-    if (typeof KeyboardAccessoryBar !== 'undefined') {
-      KeyboardAccessoryBar.hide();
+    if (typeof MobileTerminalControls !== 'undefined') {
+      MobileTerminalControls.syncVisibility();
     }
 
     this.resetLayout();
diff --git a/src/web/public/mobile.css b/src/web/public/mobile.css
index 95c5064c..44d04fc1 100644
--- a/src/web/public/mobile.css
+++ b/src/web/public/mobile.css
@@ -439,14 +439,17 @@ html.mobile-init .file-browser-panel {
   }
 
   .main {
-    padding-bottom: calc(40px + var(--safe-area-bottom));
+    padding-bottom: calc(var(--mobile-toolbar-height) + var(--safe-area-bottom));
   }
 
   /* iOS Safari: toolbar is pushed up by (100vh - --app-height) to clear the
      browser's bottom bar. Match that offset in main's padding so the terminal
      doesn't extend behind the toolbar. */
   .ios-device.safari-browser .main {
-    padding-bottom: calc(40px + var(--safe-area-bottom) + (100vh - var(--app-height, 100vh)));
+    padding-bottom: calc(
+      var(--mobile-toolbar-height) + var(--safe-area-bottom) +
+        (100vh - var(--app-height, 100vh))
+    );
   }
 
   .header-right {
@@ -568,19 +571,6 @@ html.mobile-init .file-browser-panel {
     position: relative;
   }
 
-  /* When keyboard is visible, pin the app container to the viewport.
-     iOS Safari scrolls the page to bring the focused input (xterm's hidden
-     textarea) into view, even with overflow:hidden. position:fixed prevents
-     the browser from scrolling the document under the app. */
-  .keyboard-visible .app {
-    position: fixed;
-    top: 0;
-    left: 0;
-    right: 0;
-    bottom: auto;
-    height: var(--app-height, 100dvh);
-  }
-
   /* Ultra-compact session tabs — .tabs-two-rows override needed to match
      specificity of .session-tabs.tabs-two-rows in styles.css (0,2,0) */
   .session-tabs,
@@ -695,7 +685,7 @@ html.mobile-init .file-browser-panel {
     bottom: var(--safe-area-bottom);
   }
   .keyboard-visible.ios-device.safari-browser .keyboard-accessory-bar {
-    bottom: calc(var(--safe-area-bottom) + 40px);
+    bottom: 0;
   }
 
   /* Show case selector in center */
@@ -923,7 +913,7 @@ html.mobile-init .file-browser-panel {
   /* Simplified toolbar layout — Run, Enter, and Case */
   .toolbar-left .toolbar-group:first-child {
     width: 100%;
-    gap: 8px;
+    gap: 4px;
   }
 
   /* Mobile case button - visible on mobile */
@@ -1022,13 +1012,13 @@ html.mobile-init .file-browser-panel {
   .keyboard-accessory-bar {
     display: none;
     position: fixed;
-    bottom: calc(var(--safe-area-bottom) + 40px); /* Above toolbar */
+    bottom: calc(var(--safe-area-bottom) + var(--mobile-toolbar-height)); /* Above toolbar */
     left: 0;
     right: 0;
-    height: 44px;
+    height: var(--mobile-terminal-accessory-height);
     background: #1a1a1a;
     border-top: 1px solid rgba(255, 255, 255, 0.1);
-    padding: 6px 8px;
+    padding: 0 8px;
     padding-left: calc(8px + var(--safe-area-left));
     padding-right: calc(8px + var(--safe-area-right));
     gap: 8px;
@@ -1052,11 +1042,13 @@ html.mobile-init .file-browser-panel {
 
   .accessory-btn {
     display: inline-flex;
+    min-width: 40px;
+    height: 100%;
     align-items: center;
     justify-content: center;
     flex-shrink: 0;
     gap: 4px;
-    padding: 6px 12px;
+    padding: 0 8px;
     background: #2a2a2a;
     border: 1px solid rgba(255, 255, 255, 0.15);
     border-radius: 6px;
@@ -1084,12 +1076,17 @@ html.mobile-init .file-browser-panel {
   }
 
   .accessory-btn-arrow {
-    padding: 6px 10px;
+    padding: 0 6px;
     background: #2563eb;
     border-color: rgba(59, 130, 246, 0.5);
     color: #fff;
   }
 
+  .keyboard-accessory-bar [data-action='opt-enter'] {
+    min-width: 58px;
+    padding: 0 6px;
+  }
+
   .accessory-btn-arrow:active {
     background: #1d4ed8;
   }
@@ -1098,7 +1095,7 @@ html.mobile-init .file-browser-panel {
     margin-left: auto;
     flex: 1 1 0;
     max-width: 100px;
-    padding: 10px 8px;
+    padding: 0 8px;
     background: #2563eb;
     border-color: rgba(59, 130, 246, 0.5);
     color: #fff;
@@ -2303,6 +2300,126 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
    (always loaded — covers iPad landscape where mobile.css doesn't load).
    Phone-specific overrides remain in @media (max-width: 430px) above. */
 
+/* ============================================================================
+   Keyboard-hidden terminal menu navigation
+   A dedicated band keeps vertical terminal gestures available for scrollback.
+   The empty space around the buttons is also a vertical swipe surface.
+   ============================================================================ */
+@media (max-width: 768px) {
+  .mobile-terminal-nav {
+    display: none;
+    position: fixed;
+    right: 0;
+    bottom: calc(var(--safe-area-bottom) + var(--mobile-toolbar-height));
+    left: 0;
+    box-sizing: border-box;
+    height: var(--mobile-terminal-nav-height);
+    padding: 0 calc(8px + var(--safe-area-right)) 0
+      calc(8px + var(--safe-area-left));
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    background: var(--term-bg, #161b23);
+    border-top: 0;
+    z-index: 51;
+    touch-action: none;
+    user-select: none;
+    -webkit-user-select: none;
+    -webkit-touch-callout: none;
+  }
+
+  .touch-device .mobile-terminal-nav.visible {
+    display: flex;
+  }
+
+  .keyboard-visible .mobile-terminal-nav {
+    display: none !important;
+  }
+
+  .mobile-terminal-nav-btn {
+    display: inline-flex;
+    width: var(--mobile-terminal-nav-height);
+    min-width: var(--mobile-terminal-nav-height);
+    height: var(--mobile-terminal-nav-height);
+    min-height: var(--mobile-terminal-nav-height);
+    padding: 0;
+    align-items: center;
+    justify-content: center;
+    color: #fff;
+    background: #2563eb;
+    border: 1px solid rgba(147, 197, 253, 0.55);
+    border-radius: 6px;
+    touch-action: none;
+  }
+
+  .mobile-terminal-nav [data-nav-key="esc"] {
+    margin-right: auto;
+  }
+
+  .mobile-terminal-nav [data-nav-key="tab"] {
+    margin-left: auto;
+  }
+
+  .mobile-terminal-nav-btn svg {
+    width: 22px;
+    height: 22px;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 2.25;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+    pointer-events: none;
+  }
+
+  .mobile-terminal-nav-enter {
+    color: #e5e7eb;
+    background: #2f333b;
+    border-color: rgba(255, 255, 255, 0.2);
+  }
+
+  .mobile-terminal-nav-key {
+    color: #e5e7eb;
+    background: #2f333b;
+    border-color: rgba(255, 255, 255, 0.2);
+    font: 600 0.75rem/1 var(--ui-font);
+  }
+
+  .mobile-terminal-nav-btn.pressed {
+    background: #1d4ed8;
+    transform: translateY(1px);
+  }
+
+  .mobile-terminal-nav.chord-active .mobile-terminal-nav-enter {
+    color: #fff;
+    background: #15803d;
+    border-color: #4ade80;
+  }
+
+  .mobile-terminal-nav-btn:focus-visible {
+    outline: 2px solid #f8fafc;
+    outline-offset: -3px;
+  }
+
+  .mobile-terminal-nav-btn:disabled {
+    opacity: 0.45;
+  }
+
+  body.mobile-nav-visible:not(.keyboard-visible) .main {
+    padding-bottom: calc(
+      var(--mobile-toolbar-height) + var(--mobile-terminal-nav-height) +
+        var(--safe-area-bottom)
+    );
+    background: var(--term-bg, #161b23);
+  }
+
+  body.mobile-nav-visible:not(.keyboard-visible).ios-device.safari-browser .main {
+    padding-bottom: calc(
+      var(--mobile-toolbar-height) + var(--mobile-terminal-nav-height) +
+        var(--safe-area-bottom) + (100vh - var(--app-height, 100vh))
+    );
+  }
+}
+
 /* ============================================================================
    iOS Safari Specific Fixes
    ============================================================================ */
diff --git a/src/web/public/settings-ui.js b/src/web/public/settings-ui.js
index 9e0c0d0c..a9e3cefd 100644
--- a/src/web/public/settings-ui.js
+++ b/src/web/public/settings-ui.js
@@ -347,7 +347,21 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsTerminalWheelLocal').checked =
       settings.terminalWheelLocalScrollback ?? defaults.terminalWheelLocalScrollback ?? false;
     document.getElementById('appSettingsCjkInput').checked = settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false;
-    document.getElementById('appSettingsExtendedKeyboardBar').checked = settings.extendedKeyboardBar ?? false;
+    const mobileControlsItem = document.getElementById('appSettingsMobileTerminalControlsItem');
+    const mobileControlItems = [
+      mobileControlsItem,
+      document.getElementById('appSettingsMobileControlHapticsItem'),
+      document.getElementById('appSettingsMobileControlSoundItem'),
+    ];
+    for (const item of mobileControlItems) {
+      if (item) item.style.display = MobileDetection.isTouchDevice() ? '' : 'none';
+    }
+    document.getElementById('appSettingsMobileTerminalControls').checked =
+      MobileTerminalControls.resolveEnabled(settings, defaults);
+    document.getElementById('appSettingsMobileControlHaptics').checked =
+      settings.mobileControlHaptics ?? defaults.mobileControlHaptics ?? true;
+    document.getElementById('appSettingsMobileControlSound').checked =
+      settings.mobileControlSound ?? defaults.mobileControlSound ?? false;
     document.getElementById('appSettingsTabTwoRows').checked = settings.tabTwoRows ?? defaults.tabTwoRows ?? false;
     // Claude CLI settings
     const claudeModeSelect = document.getElementById('appSettingsClaudeMode');
@@ -1458,8 +1472,10 @@ Object.assign(CodemanApp.prototype, {
       localEchoEnabled: document.getElementById('appSettingsLocalEcho').checked,
       terminalWheelLocalScrollback: document.getElementById('appSettingsTerminalWheelLocal').checked,
       cjkInputEnabled: document.getElementById('appSettingsCjkInput').checked,
+      mobileTerminalControlsEnabled: document.getElementById('appSettingsMobileTerminalControls').checked,
+      mobileControlHaptics: document.getElementById('appSettingsMobileControlHaptics').checked,
+      mobileControlSound: document.getElementById('appSettingsMobileControlSound').checked,
       webglRendererEnabled: document.getElementById('appSettingsWebglRenderer').checked,
-      extendedKeyboardBar: document.getElementById('appSettingsExtendedKeyboardBar').checked,
       tabTwoRows: document.getElementById('appSettingsTabTwoRows').checked,
       skin: document.getElementById('appSettingsSkin').value,
       // Claude CLI settings
@@ -1610,12 +1626,13 @@ Object.assign(CodemanApp.prototype, {
     // Apply CJK input visibility immediately
     this._updateCjkInputState();
 
-    // Apply keyboard bar mode
-    KeyboardAccessoryBar.setMode(settings.extendedKeyboardBar ? 'extended' : 'simple');
+    // Apply both responsive surfaces of the unified mobile terminal controls.
+    MobileTerminalControls.configureFeedback(settings, this.getDefaultSettings());
+    MobileTerminalControls.setEnabled(settings.mobileTerminalControlsEnabled);
 
     // Save to server (includes notification prefs for cross-browser persistence).
     // Strip device-specific DISPLAY keys so they never sync across devices —
-    // localEcho/cjk/extendedKeyboard/skin are per-platform, and showPlanUsageLimits
+    // localEcho/cjk/mobile terminal controls/skin are per-platform, and showPlanUsageLimits
     // is per-device too (desktop can show the usage chip while mobile stays hidden).
     // webglRendererEnabled is per-device as well (renderer choice is GPU-specific,
     // and syncing would leak mobile's hidden-checkbox false onto desktop); it's
@@ -1627,7 +1644,9 @@ Object.assign(CodemanApp.prototype, {
     const {
       localEchoEnabled: _leo,
       cjkInputEnabled: _cjk,
-      extendedKeyboardBar: _ekb,
+      mobileTerminalControlsEnabled: _mtc,
+      mobileControlHaptics: _mch,
+      mobileControlSound: _mcs,
       skin: _skin,
       language: _language,
       showPlanUsageLimits: _pul,
@@ -1809,6 +1828,9 @@ Object.assign(CodemanApp.prototype, {
         remoteAutoReconnect: true,
         // Input
         gestureControlEnabled: false,
+        mobileTerminalControlsEnabled: false,
+        mobileControlHaptics: false,
+        mobileControlSound: false,
         // Feature toggles - keep tracking on even on mobile
         subagentTrackingEnabled: true,
         subagentActiveTabOnly: true, // Only show subagents for active tab
@@ -2241,7 +2263,9 @@ Object.assign(CodemanApp.prototype, {
           'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
           'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
           'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
-          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
+          'subagentActiveTabOnly', 'tabTwoRows', 'localEchoEnabled', 'cjkInputEnabled',
+          'mobileTerminalControlsEnabled', 'mobileNavigationPadEnabled', 'extendedKeyboardBar',
+          'mobileControlHaptics', 'mobileControlSound',
           'skin', 'showPlanUsageLimits', 'showAttachmentsButton', 'showFileViewerButton', 'webglRendererEnabled',
           'language',
           'terminalWheelLocalScrollback',
diff --git a/src/web/public/styles.css b/src/web/public/styles.css
index 67e2a847..49e03cbb 100644
--- a/src/web/public/styles.css
+++ b/src/web/public/styles.css
@@ -81,6 +81,9 @@
 
   /* Touch target minimum (iOS Human Interface Guidelines) */
   --touch-target-min: 44px;
+  --mobile-toolbar-height: 40px;
+  --mobile-terminal-accessory-height: 44px;
+  --mobile-terminal-nav-height: 48px;
 
   /* UI font + accent/gradient/hover tokens referenced by the v1.0 override block.
      These :root values equal the daylight-blue palette so the no-attribute fallback
@@ -947,7 +950,7 @@ body {
   color: var(--text);
   display: flex;
   align-items: center;
-  gap: 8px;
+  gap: 4px;
 }
 
 .tunnel-panel-status {
@@ -10853,7 +10856,7 @@ kbd {
   position: fixed;
   left: var(--safe-area-left);
   right: var(--safe-area-right);
-  bottom: calc(var(--safe-area-bottom) + 40px);
+  bottom: calc(var(--safe-area-bottom) + var(--mobile-toolbar-height));
   z-index: 52;
   display: block;
   min-height: 34px;
@@ -10870,11 +10873,17 @@ kbd {
 }
 
 .touch-device.keyboard-visible #cjkInput.cjk-input-visible {
-  bottom: calc(var(--safe-area-bottom) + 84px);
+  bottom: calc(
+    var(--safe-area-bottom) + var(--mobile-toolbar-height) +
+      var(--mobile-terminal-accessory-height)
+  );
 }
 
 body.touch-device.cjk-input-visible .main {
-  padding-bottom: calc(84px + var(--safe-area-bottom));
+  padding-bottom: calc(
+    var(--mobile-toolbar-height) + var(--mobile-terminal-accessory-height) +
+      var(--safe-area-bottom)
+  );
 }
 
 /* ═══════════════════════════════════════════════════════════════
@@ -10886,10 +10895,10 @@ body.touch-device.cjk-input-visible .main {
 
 .keyboard-accessory-bar {
   display: none;
-  height: 44px;
+  height: var(--mobile-terminal-accessory-height);
   background: var(--floating-bg);
   border-top: 1px solid var(--control-border);
-  padding: 6px 8px;
+  padding: 0 8px;
   gap: 8px;
   align-items: center;
   overflow-x: auto;
@@ -10917,13 +10926,55 @@ body.touch-device.cjk-input-visible .main {
   will-change: transform;
 }
 
+/* Android scaling, phone landscape, and foldables can expose a desktop-width
+   viewport. These rules live in the always-loaded stylesheet so keyboard
+   geometry follows stable handheld identity at every posture. */
+body.handheld-device.keyboard-visible .app {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: auto;
+  left: 0;
+  height: var(--app-height, 100dvh);
+}
+
+body.handheld-device.keyboard-visible .main {
+  padding-bottom: 0 !important;
+}
+
+body.handheld-device.keyboard-visible.keyboard-accessory-visible .main {
+  padding-bottom: var(--mobile-terminal-accessory-height) !important;
+}
+
+body.handheld-device.keyboard-visible .toolbar {
+  display: none !important;
+}
+
+body.handheld-device.keyboard-visible .keyboard-accessory-bar {
+  position: absolute;
+  bottom: 0 !important;
+  transform: none !important;
+}
+
+body.handheld-device.keyboard-visible .keyboard-accessory-bar.visible {
+  display: flex !important;
+}
+
+body.touch-device.handheld-device.keyboard-visible #cjkInput.cjk-input-visible {
+  position: static;
+  flex-shrink: 0;
+  transform: none !important;
+}
+
 .accessory-btn {
   display: inline-flex;
+  min-width: 40px;
+  height: 100%;
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
   gap: 4px;
-  padding: 6px 12px;
+  padding: 0 8px;
   background: var(--control-bg);
   border: 1px solid var(--control-border);
   border-radius: 6px;
@@ -10950,12 +11001,17 @@ body.touch-device.cjk-input-visible .main {
 }
 
 .accessory-btn-arrow {
-  padding: 6px 10px;
+  padding: 0 6px;
   background: var(--accent);
   border-color: var(--accent);
   color: var(--accent-ink);
 }
 
+.keyboard-accessory-bar [data-action='opt-enter'] {
+  min-width: 58px;
+  padding: 0 6px;
+}
+
 .accessory-btn-arrow:active {
   background: var(--accent-hover);
 }
@@ -10964,7 +11020,7 @@ body.touch-device.cjk-input-visible .main {
   margin-left: auto;
   flex: 1 1 0;
   max-width: 100px;
-  padding: 10px 8px;
+  padding: 0 8px;
   background: var(--accent);
   border-color: var(--accent);
   color: var(--accent-ink);
diff --git a/src/web/public/terminal-ui.js b/src/web/public/terminal-ui.js
index 3a9de819..64cf9d26 100644
--- a/src/web/public/terminal-ui.js
+++ b/src/web/public/terminal-ui.js
@@ -2815,6 +2815,16 @@ Object.assign(CodemanApp.prototype, {
     this._sendSyntheticSgrTap(ev.clientX, ev.clientY);
   },
 
+  /**
+   * Send one terminal control key without focusing xterm.
+   * The existing durable input queue preserves ordering and reconnect safety.
+   */
+  sendTerminalKey(input) {
+    const sessionId = this.activeSessionId;
+    if (!sessionId || !input) return;
+    this._sendInputAsync(sessionId, input);
+  },
+
   _installMobileTapMouseGuard() {
     const el = this.terminal?.element;
     if (!el || el._codemanTapMouseGuardInstalled) return;
diff --git a/test/mobile-navigation-pad.test.ts b/test/mobile-navigation-pad.test.ts
new file mode 100644
index 00000000..2ee4d065
--- /dev/null
+++ b/test/mobile-navigation-pad.test.ts
@@ -0,0 +1,379 @@
+import { readFileSync } from 'node:fs';
+import { JSDOM } from 'jsdom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const SOURCE = readFileSync(new URL('../src/web/public/keyboard-accessory.js', import.meta.url), 'utf8');
+
+type NavigationPad = {
+  element: HTMLElement | null;
+  init: (enabled: boolean) => void;
+  syncVisibility: () => void;
+};
+
+type MobileControls = {
+  init: (enabled: boolean) => void;
+  configureFeedback: (settings?: Record<string, unknown>, defaults?: Record<string, unknown>) => void;
+  feedback: (action: string) => void;
+  resolveEnabled: (
+    settings?: Record<string, unknown>,
+    defaults?: Record<string, unknown>,
+    isTouchDevice?: boolean
+  ) => boolean;
+};
+
+function dispatchPointer(win: JSDOM['window'], target: Element, type: string, pointerId: number, clientY = 0): void {
+  const event = new win.MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    clientY,
+    detail: 1,
+  });
+  Object.defineProperty(event, 'pointerId', { value: pointerId });
+  target.dispatchEvent(event);
+}
+
+function dispatchVolumeKey(win: JSDOM['window'], type: 'keydown' | 'keyup', key: string): KeyboardEvent {
+  const event = new win.KeyboardEvent(type, {
+    key,
+    code: key,
+    bubbles: true,
+    cancelable: true,
+  });
+  win.document.body.dispatchEvent(event);
+  return event;
+}
+
+function loadHarness() {
+  const dom = new JSDOM('<!doctype html><body></body>', {
+    url: 'http://localhost/',
+    runScripts: 'outside-only',
+  });
+  const win = dom.window as unknown as Window &
+    typeof globalThis & {
+      MobileDetection: {
+        isTouchDevice: () => boolean;
+        getDeviceType: () => string;
+      };
+      KeyboardHandler: { keyboardVisible: boolean };
+      app: {
+        activeSessionId: string | null;
+        terminal: { focus: ReturnType<typeof vi.fn> };
+        sendTerminalKey: ReturnType<typeof vi.fn>;
+      };
+    };
+
+  win.MobileDetection = {
+    isTouchDevice: () => true,
+    getDeviceType: () => 'mobile',
+  };
+  win.KeyboardHandler = { keyboardVisible: false };
+  const vibrate = vi.fn();
+  Object.defineProperty(win.navigator, 'vibrate', {
+    configurable: true,
+    value: vibrate,
+  });
+  win.app = {
+    activeSessionId: 'session-1',
+    terminal: { focus: vi.fn() },
+    sendTerminalKey: vi.fn(),
+  };
+  win.fetch = vi.fn(async () => ({ ok: true, status: 200 })) as unknown as typeof fetch;
+  win.eval(`
+    ${SOURCE}
+    window.__testMobileNavigationPad = MobileNavigationPad;
+    window.__testMobileTerminalControls = MobileTerminalControls;
+  `);
+
+  const pad = (win as unknown as { __testMobileNavigationPad: NavigationPad }).__testMobileNavigationPad;
+  const controls = (win as unknown as { __testMobileTerminalControls: MobileControls }).__testMobileTerminalControls;
+  controls.init(true);
+
+  return {
+    dom,
+    win,
+    pad,
+    controls,
+    sendKey: win.app.sendTerminalKey,
+    vibrate,
+  };
+}
+
+describe('MobileTerminalControls settings migration', () => {
+  let harness: ReturnType<typeof loadHarness>;
+
+  beforeEach(() => {
+    harness = loadHarness();
+  });
+
+  afterEach(() => {
+    harness?.dom.window.close();
+  });
+
+  it.each([
+    [{ mobileTerminalControlsEnabled: true }, {}, true, true],
+    [{ mobileTerminalControlsEnabled: false }, {}, true, false],
+    [{ mobileNavigationPadEnabled: true }, {}, true, true],
+    [{ mobileNavigationPadEnabled: false }, { mobileTerminalControlsEnabled: true }, true, false],
+    [{ extendedKeyboardBar: true }, {}, false, true],
+    [{ extendedKeyboardBar: false }, {}, true, false],
+    [{ extendedKeyboardBar: false }, {}, false, false],
+    [{}, { mobileTerminalControlsEnabled: true }, false, true],
+  ])(
+    'resolves canonical and legacy settings without changing old false semantics',
+    (settings, defaults, touchDevice, expected) => {
+      expect(harness.controls.resolveEnabled(settings, defaults, touchDevice)).toBe(expected);
+    }
+  );
+});
+
+describe('MobileNavigationPad', () => {
+  let harness: ReturnType<typeof loadHarness>;
+
+  beforeEach(() => {
+    harness = loadHarness();
+  });
+
+  afterEach(() => {
+    harness?.dom.window.close();
+  });
+
+  it('shows only for an active phone session while the keyboard is hidden', () => {
+    const { pad, win } = harness;
+    expect(pad.element?.classList.contains('visible')).toBe(true);
+    expect(win.document.body.classList.contains('mobile-nav-visible')).toBe(true);
+    expect(pad.element?.getAttribute('aria-hidden')).toBe('false');
+
+    win.KeyboardHandler.keyboardVisible = true;
+    pad.syncVisibility();
+    expect(pad.element?.classList.contains('visible')).toBe(false);
+
+    win.KeyboardHandler.keyboardVisible = false;
+    win.app.activeSessionId = null;
+    pad.syncVisibility();
+    expect(pad.element?.classList.contains('visible')).toBe(false);
+  });
+
+  it('hides behind active dialogs and restores itself when they close', async () => {
+    const { pad, win } = harness;
+    const modal = win.document.createElement('div');
+    modal.className = 'modal';
+    win.document.body.appendChild(modal);
+
+    modal.classList.add('active');
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(false);
+    expect(pad.element?.getAttribute('aria-hidden')).toBe('true');
+    expect(win.document.body.classList.contains('mobile-nav-visible')).toBe(false);
+
+    modal.classList.remove('active');
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(true);
+    expect(pad.element?.getAttribute('aria-hidden')).toBe('false');
+  });
+
+  it('tracks dynamically inserted and inline-display dialogs', async () => {
+    const { pad, win } = harness;
+    const dynamicModal = win.document.createElement('div');
+    dynamicModal.className = 'modal active';
+    win.document.body.appendChild(dynamicModal);
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(false);
+
+    dynamicModal.remove();
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(true);
+
+    const inlineModal = win.document.createElement('div');
+    inlineModal.className = 'modal';
+    inlineModal.style.display = 'flex';
+    win.document.body.appendChild(inlineModal);
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(false);
+
+    inlineModal.style.display = 'none';
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(true);
+  });
+
+  it('sends one arrow on release without focusing the terminal', () => {
+    const { pad, sendKey, win } = harness;
+    const up = pad.element!.querySelector('[data-nav-key="up"]')!;
+
+    dispatchPointer(win, up, 'pointerdown', 1);
+    expect(sendKey).not.toHaveBeenCalled();
+    dispatchPointer(win, up, 'pointerup', 1);
+
+    expect(sendKey).toHaveBeenCalledTimes(1);
+    expect(sendKey).toHaveBeenCalledWith('\x1b[A');
+    expect(win.app.terminal.focus).not.toHaveBeenCalled();
+  });
+
+  it('provides configurable haptic feedback for accepted controls', () => {
+    const { controls, pad, vibrate, win } = harness;
+    const up = pad.element!.querySelector('[data-nav-key="up"]')!;
+
+    controls.configureFeedback({
+      mobileControlHaptics: true,
+      mobileControlSound: false,
+    });
+    dispatchPointer(win, up, 'pointerdown', 1);
+    dispatchPointer(win, up, 'pointerup', 1);
+    expect(vibrate).toHaveBeenCalledWith(10);
+
+    controls.configureFeedback({
+      mobileControlHaptics: false,
+      mobileControlSound: false,
+    });
+    dispatchPointer(win, up, 'pointerdown', 2);
+    dispatchPointer(win, up, 'pointerup', 2);
+    expect(vibrate).toHaveBeenCalledTimes(1);
+  });
+
+  it('plays an optional short Web Audio tone', () => {
+    const { controls, win } = harness;
+    const start = vi.fn();
+    const stop = vi.fn();
+    const setFrequency = vi.fn();
+    const setGain = vi.fn();
+    const rampGain = vi.fn();
+    class FakeAudioContext {
+      currentTime = 1;
+      state = 'running';
+      destination = {};
+      createOscillator() {
+        return {
+          type: 'sine',
+          frequency: { setValueAtTime: setFrequency },
+          connect: vi.fn(),
+          start,
+          stop,
+        };
+      }
+      createGain() {
+        return {
+          gain: {
+            setValueAtTime: setGain,
+            exponentialRampToValueAtTime: rampGain,
+          },
+          connect: vi.fn(),
+        };
+      }
+    }
+    Object.defineProperty(win, 'AudioContext', {
+      configurable: true,
+      value: FakeAudioContext,
+    });
+
+    controls.configureFeedback({
+      mobileControlHaptics: false,
+      mobileControlSound: true,
+    });
+    controls.feedback('enter');
+
+    expect(setFrequency).toHaveBeenCalledWith(760, 1);
+    expect(setGain).toHaveBeenCalledWith(0.025, 1);
+    expect(rampGain).toHaveBeenCalledWith(0.0001, 1.035);
+    expect(start).toHaveBeenCalledWith(1);
+    expect(stop).toHaveBeenCalledWith(1.04);
+  });
+
+  it('turns a simultaneous Up+Down press into Enter without leaking arrows', () => {
+    const { pad, sendKey, win } = harness;
+    const up = pad.element!.querySelector('[data-nav-key="up"]')!;
+    const down = pad.element!.querySelector('[data-nav-key="down"]')!;
+
+    dispatchPointer(win, up, 'pointerdown', 1);
+    dispatchPointer(win, down, 'pointerdown', 2);
+    expect(sendKey).toHaveBeenCalledTimes(1);
+    expect(sendKey).toHaveBeenCalledWith('\r');
+    expect(pad.element?.classList.contains('chord-active')).toBe(true);
+
+    dispatchPointer(win, up, 'pointerup', 1);
+    dispatchPointer(win, down, 'pointerup', 2);
+    expect(sendKey).toHaveBeenCalledTimes(1);
+    expect(pad.element?.classList.contains('chord-active')).toBe(false);
+  });
+
+  it('uses exposed hardware volume keys without focusing the terminal', () => {
+    const { sendKey, win } = harness;
+
+    const down = dispatchVolumeKey(win, 'keydown', 'AudioVolumeUp');
+    expect(down.defaultPrevented).toBe(true);
+    expect(sendKey).not.toHaveBeenCalled();
+
+    const up = dispatchVolumeKey(win, 'keyup', 'AudioVolumeUp');
+    expect(up.defaultPrevented).toBe(true);
+    expect(sendKey).toHaveBeenCalledOnce();
+    expect(sendKey).toHaveBeenCalledWith('\x1b[A');
+    expect(win.app.terminal.focus).not.toHaveBeenCalled();
+  });
+
+  it('turns simultaneous volume directions into one Enter without leaking arrows', () => {
+    const { pad, sendKey, win } = harness;
+
+    dispatchVolumeKey(win, 'keydown', 'AudioVolumeUp');
+    dispatchVolumeKey(win, 'keydown', 'AudioVolumeDown');
+    expect(sendKey).toHaveBeenCalledOnce();
+    expect(sendKey).toHaveBeenCalledWith('\r');
+    expect(pad.element?.classList.contains('chord-active')).toBe(true);
+
+    dispatchVolumeKey(win, 'keyup', 'AudioVolumeUp');
+    dispatchVolumeKey(win, 'keyup', 'AudioVolumeDown');
+    expect(sendKey).toHaveBeenCalledOnce();
+    expect(pad.element?.classList.contains('chord-active')).toBe(false);
+  });
+
+  it('leaves volume keys alone while the mobile controls are unavailable', async () => {
+    const { pad, sendKey, win } = harness;
+    const modal = win.document.createElement('div');
+    modal.className = 'modal';
+    win.document.body.appendChild(modal);
+    modal.classList.add('active');
+    await Promise.resolve();
+    expect(pad.element?.classList.contains('visible')).toBe(false);
+
+    const down = dispatchVolumeKey(win, 'keydown', 'AudioVolumeDown');
+    const up = dispatchVolumeKey(win, 'keyup', 'AudioVolumeDown');
+
+    expect(down.defaultPrevented).toBe(false);
+    expect(up.defaultPrevented).toBe(false);
+    expect(sendKey).not.toHaveBeenCalled();
+  });
+
+  it('keeps an explicit Enter button available for one-finger and switch input', () => {
+    const { pad, sendKey } = harness;
+    const enter = pad.element!.querySelector('[data-nav-key="enter"]') as HTMLButtonElement;
+
+    enter.click();
+
+    expect(sendKey).toHaveBeenCalledTimes(1);
+    expect(sendKey).toHaveBeenCalledWith('\r');
+  });
+
+  it('maps vertical swipes on the bar to arrows and ignores short movement', () => {
+    const { pad, sendKey, win } = harness;
+    const bar = pad.element!;
+
+    dispatchPointer(win, bar, 'pointerdown', 10, 100);
+    dispatchPointer(win, bar, 'pointerup', 10, 50);
+    dispatchPointer(win, bar, 'pointerdown', 11, 50);
+    dispatchPointer(win, bar, 'pointerup', 11, 100);
+    dispatchPointer(win, bar, 'pointerdown', 12, 50);
+    dispatchPointer(win, bar, 'pointerup', 12, 70);
+
+    expect(sendKey).toHaveBeenNthCalledWith(1, '\x1b[A');
+    expect(sendKey).toHaveBeenNthCalledWith(2, '\x1b[B');
+    expect(sendKey).toHaveBeenCalledTimes(2);
+  });
+
+  it('drops canceled pointers without sending or leaving a pressed state', () => {
+    const { pad, sendKey, win } = harness;
+    const down = pad.element!.querySelector('[data-nav-key="down"]')!;
+
+    dispatchPointer(win, down, 'pointerdown', 5);
+    dispatchPointer(win, down, 'pointercancel', 5);
+
+    expect(sendKey).not.toHaveBeenCalled();
+    expect(down.classList.contains('pressed')).toBe(false);
+  });
+});
diff --git a/test/mobile/helpers/constants.ts b/test/mobile/helpers/constants.ts
index b2dda4d0..9bc71636 100644
--- a/test/mobile/helpers/constants.ts
+++ b/test/mobile/helpers/constants.ts
@@ -9,6 +9,7 @@ export const PORTS = {
   VISUAL_REGRESSION: 3206,
   ACCESSIBILITY: 3207,
   HEADER_BUTTONS: 3208,
+  NAVIGATION_PAD: 3209,
 } as const;
 
 // CSS Selectors
@@ -36,6 +37,7 @@ export const SELECTORS = {
   // Keyboard
   KEYBOARD_ACCESSORY: '.keyboard-accessory-bar',
   KEYBOARD_ACCESSORY_VISIBLE: '.keyboard-accessory-bar.visible',
+  MOBILE_NAVIGATION: '.mobile-terminal-nav',
 
   // Terminal
   TERMINAL_CONTAINER: '.terminal-container',
@@ -68,6 +70,7 @@ export const KEYBOARD = {
   SHOW_THRESHOLD: 150, // heightDiff > 150px triggers show
   HIDE_THRESHOLD: 100, // heightDiff < 100px triggers hide
   TYPICAL_IOS_HEIGHT: 336,
+  TYPICAL_ANDROID_HEIGHT: 300,
   FOCUSIN_DELAY: 400,
   ANIMATION_DELAY: 150,
   RESIZE_DELAY_SHOW: 150,
diff --git a/test/mobile/keyboard.test.ts b/test/mobile/keyboard.test.ts
index 5032f653..872ebac7 100644
--- a/test/mobile/keyboard.test.ts
+++ b/test/mobile/keyboard.test.ts
@@ -23,7 +23,7 @@ import {
   assertHidden,
   getCSSProperty,
 } from './helpers/assertions.js';
-import { REPRESENTATIVE_DEVICES } from './devices.js';
+import { DEVICE_REGISTRY, REPRESENTATIVE_DEVICES } from './devices.js';
 import type { WebServer } from '../src/web/server.js';
 
 const PORT = PORTS.KEYBOARD;
@@ -127,6 +127,40 @@ describe('Virtual Keyboard', () => {
       expect(visible).toBe(false);
     });
 
+    it('accumulates incremental keyboard-animation shrink without lowering its baseline', async () => {
+      const initial = await getKeyboardState(page);
+      const baseline = initial.initialViewportHeight;
+
+      for (const shrink of [70, 140]) {
+        await page.evaluate(`(function(height, fullHeight) {
+          var vv = window.visualViewport;
+          Object.defineProperty(vv, 'height', {
+            get: function() { return height; },
+            configurable: true,
+          });
+          Object.defineProperty(window, 'innerHeight', {
+            get: function() { return fullHeight; },
+            configurable: true,
+          });
+          KeyboardHandler.handleViewportResize();
+        })(${baseline - shrink}, ${baseline})`);
+        expect(await getKeyboardVisible(page)).toBe(false);
+        expect((await getKeyboardState(page)).initialViewportHeight).toBe(baseline);
+      }
+
+      await page.evaluate(`(function(height) {
+        var vv = window.visualViewport;
+        Object.defineProperty(vv, 'height', {
+          get: function() { return height; },
+          configurable: true,
+        });
+        KeyboardHandler.handleViewportResize();
+      })(${baseline - 210})`);
+
+      expect(await getKeyboardVisible(page)).toBe(true);
+      await assertHasClass(page, 'body', BODY_CLASSES.KEYBOARD_VISIBLE);
+    });
+
     it('dismissing keyboard restores original state', async () => {
       // Show
       await showKeyboardViaCDP(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
@@ -222,43 +256,58 @@ describe('Virtual Keyboard', () => {
       await context.close();
     });
 
-    it('toolbar remains below terminal when keyboard show shrinks the app viewport', async () => {
+    it('hides Codeman control rows so the terminal reaches the phone keyboard edge', async () => {
       await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
       await page.waitForTimeout(WAIT.KEYBOARD_ANIMATION);
 
       const layout = await page.evaluate(() => {
         const toolbar = document.querySelector('.toolbar') as HTMLElement | null;
         const accessory = document.querySelector('.keyboard-accessory-bar') as HTMLElement | null;
-        const terminalWrap = document.querySelector('.terminal-wrap') as HTMLElement | null;
+        const terminal = document.getElementById('terminalContainer');
+        const appEl = document.querySelector('.app') as HTMLElement | null;
+        const main = document.querySelector('.main') as HTMLElement | null;
         const toolbarRect = toolbar?.getBoundingClientRect();
         const accessoryRect = accessory?.getBoundingClientRect();
-        const terminalRect = terminalWrap?.getBoundingClientRect();
+        const terminalRect = terminal?.getBoundingClientRect();
+        const appRect = appEl?.getBoundingClientRect();
         return {
+          toolbarDisplay: toolbar ? getComputedStyle(toolbar).display : '',
+          accessoryDisplay: accessory ? getComputedStyle(accessory).display : '',
           toolbarTransform: toolbar?.style.transform ?? '',
           accessoryTransform: (accessory as HTMLElement | null)?.style.transform ?? '',
-          toolbarTop: toolbarRect?.top ?? 0,
-          accessoryTop: accessoryRect?.top ?? 0,
+          toolbarHeight: toolbarRect?.height ?? 0,
+          accessoryHeight: accessoryRect?.height ?? 0,
           terminalBottom: terminalRect?.bottom ?? 0,
+          appBottom: appRect?.bottom ?? 0,
+          mainPadding: main ? parseFloat(getComputedStyle(main).paddingBottom) : -1,
         };
       });
+      expect(layout.toolbarDisplay).toBe('none');
+      expect(layout.accessoryDisplay).toBe('none');
       expect(layout.toolbarTransform).toBe('');
       expect(layout.accessoryTransform).toBe('');
-      expect(layout.accessoryTop).toBeGreaterThanOrEqual(layout.terminalBottom - 4);
-      expect(layout.toolbarTop).toBeGreaterThan(layout.accessoryTop);
+      expect(layout.toolbarHeight).toBe(0);
+      expect(layout.accessoryHeight).toBe(0);
+      expect(layout.mainPadding).toBe(0);
+      expect(Math.abs(layout.terminalBottom - layout.appBottom)).toBeLessThanOrEqual(1);
     });
 
-    it('accessory bar gets .visible class', async () => {
+    it('keeps the accessory bar hidden on phones while the keyboard is open', async () => {
       await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
       await page.waitForTimeout(WAIT.KEYBOARD_ANIMATION);
 
-      const hasVisible = await page.evaluate(() => {
+      const accessoryState = await page.evaluate(() => {
         const bar = document.querySelector('.keyboard-accessory-bar');
-        return bar?.classList.contains('visible') ?? false;
+        return {
+          hasVisibleClass: bar?.classList.contains('visible') ?? false,
+          display: bar ? getComputedStyle(bar).display : '',
+        };
       });
-      expect(hasVisible).toBe(true);
+      expect(accessoryState.hasVisibleClass).toBe(false);
+      expect(accessoryState.display).toBe('none');
     });
 
-    it('main padding increases on keyboard show', async () => {
+    it('clears main padding when the phone keyboard opens', async () => {
       const initialPadding = await page.evaluate(() => {
         const main = document.querySelector('.main') as HTMLElement | null;
         return main ? getComputedStyle(main).paddingBottom : '0px';
@@ -273,7 +322,8 @@ describe('Virtual Keyboard', () => {
         return main ? main.style.paddingBottom : '';
       });
       const newPx = parseFloat(newPadding) || 0;
-      expect(newPx).toBeGreaterThan(initialPx);
+      expect(initialPx).toBeGreaterThan(0);
+      expect(newPx).toBe(0);
     });
 
     it('does not reserve the keyboard height as visible terminal dead space', async () => {
@@ -284,12 +334,15 @@ describe('Virtual Keyboard', () => {
         const main = document.querySelector('.main') as HTMLElement | null;
         const appEl = document.querySelector('.app') as HTMLElement | null;
         const terminalWrap = document.querySelector('.terminal-wrap') as HTMLElement | null;
+        const terminal = document.getElementById('terminalContainer');
         const toolbar = document.querySelector('.toolbar') as HTMLElement | null;
         const accessory = document.querySelector('.keyboard-accessory-bar') as HTMLElement | null;
         return {
           appHeight: appEl?.getBoundingClientRect().height ?? 0,
+          appBottom: appEl?.getBoundingClientRect().bottom ?? 0,
           mainPaddingBottom: main ? parseFloat(main.style.paddingBottom || '0') : 0,
           terminalHeight: terminalWrap?.getBoundingClientRect().height ?? 0,
+          terminalBottom: terminal?.getBoundingClientRect().bottom ?? 0,
           toolbarHeight: toolbar?.getBoundingClientRect().height ?? 0,
           accessoryHeight: accessory?.getBoundingClientRect().height ?? 0,
           visualViewportHeight: window.visualViewport?.height ?? window.innerHeight,
@@ -297,8 +350,9 @@ describe('Virtual Keyboard', () => {
       });
 
       expect(layout.appHeight).toBeLessThanOrEqual(layout.visualViewportHeight + 2);
-      expect(layout.mainPaddingBottom).toBeLessThan(KEYBOARD.TYPICAL_IOS_HEIGHT);
-      expect(layout.mainPaddingBottom).toBeGreaterThanOrEqual(layout.toolbarHeight + layout.accessoryHeight - 4);
+      expect(layout.mainPaddingBottom).toBe(0);
+      expect(layout.toolbarHeight + layout.accessoryHeight).toBe(0);
+      expect(Math.abs(layout.terminalBottom - layout.appBottom)).toBeLessThanOrEqual(1);
       expect(layout.terminalHeight).toBeGreaterThan(160);
     });
 
@@ -323,13 +377,31 @@ describe('Virtual Keyboard', () => {
       expect(mainPadding).toBe('');
     });
 
-    it('accessory bar has the simple-mode action buttons', async () => {
+    it('accessory bar has the unified terminal-control action set', async () => {
       const actions = await page.evaluate(() => {
         return Array.from(document.querySelectorAll('.keyboard-accessory-bar [data-action]')).map(
           (button) => (button as HTMLElement).dataset.action
         );
       });
-      expect(actions).toEqual(['scroll-up', 'scroll-down', 'init', 'clear', 'paste', 'dismiss']);
+      expect(actions).toEqual([
+        'esc',
+        'arrow-left',
+        'scroll-up',
+        'opt-enter',
+        'scroll-down',
+        'arrow-right',
+        'tab',
+        'shift-tab',
+        'paste',
+        'pick-path',
+        'clear-input',
+        'effort-max',
+        'ctrl-o',
+        'init',
+        'clear',
+        'compact',
+        'dismiss',
+      ]);
     });
 
     it('double-tap confirm on /clear button', async () => {
@@ -475,7 +547,7 @@ describe('Virtual Keyboard', () => {
       expect(Number(styles?.zIndex)).toBeGreaterThanOrEqual(0);
     });
 
-    it('routes CJK textarea typing through local echo on Enter', async () => {
+    it('routes CJK textarea typing directly to session input', async () => {
       await page.evaluate(() => {
         window.__sentInputs = [];
         const sessionId = 'mobile-cjk-local-echo-test';
@@ -514,18 +586,18 @@ describe('Virtual Keyboard', () => {
         pendingText: app._localEchoOverlay.pendingText,
         sentInputs: window.__sentInputs,
       }));
-      expect(beforeEnter.visibleText).toBe('hello');
+      expect(beforeEnter.visibleText).toBe('');
       expect(beforeEnter.pendingText).toBe('');
-      expect(beforeEnter.sentInputs).toEqual([]);
+      expect(beforeEnter.sentInputs.join('')).toBe('hello');
 
       await page.keyboard.press('Enter');
-      await page.waitForFunction(() => window.__sentInputs?.length === 2);
+      await page.waitForFunction(() => window.__sentInputs?.join('') === 'hello\r');
       const afterEnter = await page.evaluate(() => ({
         pendingText: app._localEchoOverlay.pendingText,
         sentInputs: window.__sentInputs,
       }));
       expect(afterEnter.pendingText).toBe('');
-      expect(afterEnter.sentInputs).toEqual(['hello', '\r']);
+      expect(afterEnter.sentInputs.join('')).toBe('hello\r');
     });
 
     it('shows the CJK textarea on mobile for server override only inside an active session', async () => {
@@ -796,6 +868,73 @@ describe('Virtual Keyboard', () => {
       }
     });
 
+    it('scaled Android phone keeps unified controls flush with the keyboard edge', async () => {
+      const device = DEVICE_REGISTRY.find((entry) => entry.name === 'Galaxy S23 Ultra')!;
+      const { context, page } = await createDevicePage(device, BASE_URL, 'chromium');
+      try {
+        expect(await page.evaluate(() => window.innerWidth)).toBeGreaterThan(430);
+        expect(await page.evaluate(`MobileDetection.isHandheldDevice()`)).toBe(true);
+
+        await page.evaluate(`
+          app.activeSessionId = 'scaled-android-controls-test';
+          app.hideWelcome();
+          MobileTerminalControls.setEnabled(true);
+          MobileTerminalControls.syncVisibility();
+        `);
+
+        const viewport = page.viewportSize()!;
+        const keyboardViewportHeight = viewport.height - KEYBOARD.TYPICAL_ANDROID_HEIGHT;
+        const cdp = await getCDP(page);
+        await setVisualViewportHeight(cdp, viewport.width, keyboardViewportHeight, device.deviceScaleFactor);
+        await page.waitForTimeout(100);
+        await page.evaluate(`KeyboardHandler.handleViewportResize()`);
+        await page.waitForTimeout(WAIT.KEYBOARD_ANIMATION);
+        expect(await getKeyboardVisible(page)).toBe(true);
+
+        const layout = await page.evaluate(() => {
+          const appEl = document.querySelector('.app') as HTMLElement | null;
+          const main = document.querySelector('.main') as HTMLElement | null;
+          const terminal = document.getElementById('terminalContainer');
+          const toolbar = document.querySelector('.toolbar') as HTMLElement | null;
+          const accessory = document.querySelector('.keyboard-accessory-bar') as HTMLElement | null;
+          const accessoryRect = accessory?.getBoundingClientRect();
+          const buttonRects = [...(accessory?.querySelectorAll('button') ?? [])].map((button) =>
+            button.getBoundingClientRect()
+          );
+          return {
+            viewportMeta: document.querySelector<HTMLMetaElement>('meta[name="viewport"]')?.content ?? '',
+            hasHandheldClass: document.body.classList.contains('handheld-device'),
+            toolbarDisplay: toolbar ? getComputedStyle(toolbar).display : '',
+            accessoryDisplay: accessory ? getComputedStyle(accessory).display : '',
+            mainPadding: main ? parseFloat(getComputedStyle(main).paddingBottom) : -1,
+            terminalBottom: terminal?.getBoundingClientRect().bottom ?? 0,
+            accessoryTop: accessoryRect?.top ?? 0,
+            accessoryBottom: accessoryRect?.bottom ?? 0,
+            accessoryButtonsContained: buttonRects.every(
+              (rect) => rect.top >= (accessoryRect?.top ?? 0) - 1 && rect.bottom <= (accessoryRect?.bottom ?? 0) + 1
+            ),
+            appBottom: appEl?.getBoundingClientRect().bottom ?? 0,
+            layoutViewportHeight: window.innerHeight,
+            visualViewportHeight: window.visualViewport?.height ?? 0,
+          };
+        });
+
+        expect(layout.viewportMeta).toContain('interactive-widget=resizes-content');
+        expect(layout.hasHandheldClass).toBe(true);
+        expect(layout.toolbarDisplay).toBe('none');
+        expect(layout.accessoryDisplay).toBe('flex');
+        expect(layout.mainPadding).toBeGreaterThan(0);
+        expect(layout.accessoryButtonsContained).toBe(true);
+        expect(layout.layoutViewportHeight).toBe(keyboardViewportHeight);
+        expect(layout.visualViewportHeight).toBe(keyboardViewportHeight);
+        expect(Math.abs(layout.appBottom - keyboardViewportHeight)).toBeLessThanOrEqual(1);
+        expect(Math.abs(layout.terminalBottom - layout.accessoryTop)).toBeLessThanOrEqual(1);
+        expect(Math.abs(layout.accessoryBottom - layout.appBottom)).toBeLessThanOrEqual(1);
+      } finally {
+        await context.close();
+      }
+    });
+
     it('tablet: keyboard handling active', async () => {
       const device = REPRESENTATIVE_DEVICES['standard-tablet']; // iPad Mini
       const { context, page } = await createDevicePage(device, BASE_URL, 'chromium');
diff --git a/test/mobile/navigation-pad.test.ts b/test/mobile/navigation-pad.test.ts
new file mode 100644
index 00000000..e1284b62
--- /dev/null
+++ b/test/mobile/navigation-pad.test.ts
@@ -0,0 +1,533 @@
+// Port 3209 - Keyboard-hidden terminal navigation tests
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { BrowserContext, Page } from 'playwright';
+import type { WebServer } from '../../src/web/server.js';
+import { TmuxManager } from '../../src/tmux-manager.js';
+import { DEVICE_REGISTRY } from './devices.js';
+import { createDevicePage, closeAllBrowsers } from './helpers/browser.js';
+import { KEYBOARD, PORTS, SELECTORS } from './helpers/constants.js';
+import { getCDP, dispatchTouchEvent } from './helpers/cdp.js';
+import { createTestServer, stopTestServer } from './helpers/server.js';
+
+const PORT = PORTS.NAVIGATION_PAD;
+const BASE_URL = `http://localhost:${PORT}`;
+const SESSION_ID = 'mobile-navigation-test';
+const PIXEL_8 = DEVICE_REGISTRY.find((device) => device.name === 'Pixel 8')!;
+const tmuxAvailableSpy = vi.spyOn(TmuxManager, 'isTmuxAvailable').mockReturnValue(true);
+
+describe('Mobile Navigation Pad', () => {
+  let server: WebServer;
+  let context: BrowserContext;
+  let page: Page;
+  let inputLog: string[];
+  let resizeLog: Array<Record<string, unknown>>;
+  let dataDir: string;
+  let previousDataDir: string | undefined;
+
+  beforeAll(async () => {
+    previousDataDir = process.env.CODEMAN_DATA_DIR;
+    dataDir = await mkdtemp(join(tmpdir(), 'codeman-mobile-navigation-'));
+    process.env.CODEMAN_DATA_DIR = dataDir;
+    server = await createTestServer(PORT);
+    ({ context, page } = await createDevicePage(PIXEL_8, BASE_URL, 'chromium'));
+    inputLog = [];
+    resizeLog = [];
+    await page.exposeFunction('__recordMobileNavigationInput', (input: string) => {
+      inputLog.push(input);
+    });
+    await page.exposeFunction('__recordMobileNavigationResize', (options: Record<string, unknown>) => {
+      resizeLog.push(options);
+    });
+  });
+
+  beforeEach(async () => {
+    inputLog.length = 0;
+    resizeLog.length = 0;
+    await page.evaluate(`
+      document.getElementById('appSettingsModal')?.classList.remove('active');
+      document.body.classList.remove('keyboard-visible');
+      KeyboardHandler.keyboardVisible = false;
+      app.sendResize = function(_sessionId, options = {}) {
+        window.__recordMobileNavigationResize(options);
+        return Promise.resolve(true);
+      };
+      app._sendInputAsync = function(_sessionId, input) {
+        window.__recordMobileNavigationInput(input);
+      };
+      let helper = document.querySelector('.xterm-helper-textarea');
+      if (!helper) {
+        helper = document.createElement('textarea');
+        helper.className = 'xterm-helper-textarea';
+        helper.setAttribute('aria-label', 'Terminal input test adapter');
+        document.body.appendChild(helper);
+      }
+      if (!app.terminal) {
+        app.terminal = {
+          focus: () => helper.focus(),
+          write: () => {},
+          options: {},
+          rows: 24,
+          refresh: () => {},
+        };
+      }
+      app.activeSessionId = ${JSON.stringify(SESSION_ID)};
+      app.hideWelcome();
+      MobileTerminalControls.setEnabled(true);
+    `);
+  });
+
+  afterAll(async () => {
+    await context?.close();
+    await closeAllBrowsers();
+    if (server) await stopTestServer(server);
+    if (previousDataDir === undefined) delete process.env.CODEMAN_DATA_DIR;
+    else process.env.CODEMAN_DATA_DIR = previousDataDir;
+    if (dataDir) await rm(dataDir, { recursive: true, force: true });
+    tmuxAvailableSpy.mockRestore();
+  });
+
+  it('fits above the toolbar with accessible touch targets', async () => {
+    const navigation = page.locator(SELECTORS.MOBILE_NAVIGATION);
+    expect(await navigation.isVisible()).toBe(true);
+    expect(await navigation.getAttribute('aria-hidden')).toBe('false');
+
+    const navBox = await navigation.boundingBox();
+    const toolbarBox = await page.locator(SELECTORS.TOOLBAR).boundingBox();
+    const terminalBox = await page.locator(SELECTORS.TERMINAL_CONTAINER).boundingBox();
+    expect(navBox).not.toBeNull();
+    expect(toolbarBox).not.toBeNull();
+    expect(terminalBox).not.toBeNull();
+    expect((terminalBox?.y ?? 0) + (terminalBox?.height ?? 0)).toBeLessThanOrEqual((navBox?.y ?? 0) + 1);
+    expect((navBox?.y ?? 0) + (navBox?.height ?? 0)).toBeLessThanOrEqual((toolbarBox?.y ?? 0) + 1);
+    expect(navBox?.height).toBe(48);
+
+    const buttons = navigation.locator('button');
+    expect(await buttons.count()).toBe(5);
+    const buttonBoxes = [];
+    for (let index = 0; index < 5; index++) {
+      const box = await buttons.nth(index).boundingBox();
+      buttonBoxes.push(box);
+      expect(box?.width ?? 0).toBeGreaterThanOrEqual(48);
+      expect(box?.height).toBe(48);
+      expect(Math.abs((box?.y ?? 0) - (navBox?.y ?? 0))).toBeLessThanOrEqual(1);
+    }
+
+    const [escapeBox, upBox, , downBox, tabBox] = buttonBoxes;
+    expect((escapeBox?.x ?? 0) - (navBox?.x ?? 0)).toBeLessThanOrEqual(12);
+    expect((navBox?.x ?? 0) + (navBox?.width ?? 0) - ((tabBox?.x ?? 0) + (tabBox?.width ?? 0))).toBeLessThanOrEqual(12);
+    expect((upBox?.x ?? 0) - ((escapeBox?.x ?? 0) + (escapeBox?.width ?? 0))).toBeGreaterThanOrEqual(24);
+    expect((tabBox?.x ?? 0) - ((downBox?.x ?? 0) + (downBox?.width ?? 0))).toBeGreaterThanOrEqual(24);
+    const navigationCenter = (navBox?.x ?? 0) + (navBox?.width ?? 0) / 2;
+    const directionalCenter = (upBox?.x ?? 0) + ((downBox?.x ?? 0) + (downBox?.width ?? 0) - (upBox?.x ?? 0)) / 2;
+    expect(Math.abs(navigationCenter - directionalCenter)).toBeLessThanOrEqual(1);
+
+    const layerStyles = await page.evaluate(() => {
+      const main = document.querySelector('.main') as HTMLElement;
+      const terminal = document.getElementById('terminalContainer') as HTMLElement;
+      const navigation = document.querySelector('.mobile-terminal-nav') as HTMLElement;
+      return {
+        mainPadding: parseFloat(getComputedStyle(main).paddingBottom),
+        mainBackground: getComputedStyle(main).backgroundColor,
+        terminalBackground: getComputedStyle(terminal).backgroundColor,
+        navigationBackground: getComputedStyle(navigation).backgroundColor,
+      };
+    });
+    expect(layerStyles.mainPadding).toBe(88);
+    expect(layerStyles.mainBackground).toBe(layerStyles.terminalBackground);
+    expect(layerStyles.navigationBackground).toBe(layerStyles.terminalBackground);
+
+    if (process.env.CODEMAN_NAV_SCREENSHOT) {
+      await page.evaluate(`
+        app.terminal?.write(
+          '\\x1b[2J\\x1b[H' +
+          'Select a dispatched agent\\r\\n\\r\\n' +
+          '  Agent 1 - research\\r\\n' +
+          '  Agent 2 - implementation\\r\\n' +
+          '> Agent 3 - review\\r\\n\\r\\n' +
+          'Use arrow keys and Enter'
+        );
+      `);
+      await page.waitForTimeout(100);
+      await page.screenshot({ path: process.env.CODEMAN_NAV_SCREENSHOT });
+    }
+  });
+
+  it('sends raw Up without focusing xterm or showing the keyboard', async () => {
+    await page.evaluate(`
+      app.terminal.focus();
+      KeyboardHandler.keyboardVisible = false;
+      document.body.classList.remove('keyboard-visible');
+      MobileNavigationPad.syncVisibility();
+    `);
+    const focusedBefore = await page.evaluate(
+      () => document.activeElement?.classList.contains('xterm-helper-textarea') ?? false
+    );
+    expect(focusedBefore).toBe(true);
+
+    const viewportHeight = await page.evaluate(() => window.visualViewport?.height);
+    const up = page.locator('[data-nav-key="up"]');
+    const box = await up.boundingBox();
+    expect(box).not.toBeNull();
+
+    const cdp = await getCDP(page);
+    await dispatchTouchEvent(cdp, 'touchStart', [
+      { x: (box?.x ?? 0) + (box?.width ?? 0) / 2, y: (box?.y ?? 0) + (box?.height ?? 0) / 2 },
+    ]);
+    await dispatchTouchEvent(cdp, 'touchEnd', []);
+    await vi.waitFor(() => {
+      expect(inputLog).toEqual(['\x1b[A']);
+    });
+    const state = await page.evaluate(`
+      ({
+        keyboardVisible: KeyboardHandler.keyboardVisible,
+        viewportHeight: window.visualViewport?.height,
+        activeTag: document.activeElement?.tagName,
+        activeClass: document.activeElement?.className || ''
+      })
+    `);
+    expect(state.keyboardVisible).toBe(false);
+    expect(state.viewportHeight).toBe(viewportHeight);
+    expect(state.activeTag).not.toBe('TEXTAREA');
+    expect(state.activeClass).not.toContain('xterm-helper-textarea');
+  });
+
+  it('sends raw Escape and Tab without opening the keyboard', async () => {
+    const viewportHeight = await page.evaluate(() => window.visualViewport?.height);
+
+    await page.locator('[data-nav-key="esc"]').click();
+    await page.locator('[data-nav-key="tab"]').click();
+    await vi.waitFor(() => {
+      expect(inputLog).toEqual(['\x1b', '\t']);
+    });
+
+    const state = await page.evaluate(`({
+      keyboardVisible: KeyboardHandler.keyboardVisible,
+      viewportHeight: window.visualViewport?.height,
+      terminalFocused: document.activeElement?.classList.contains('xterm-helper-textarea') || false
+    })`);
+    expect(state.keyboardVisible).toBe(false);
+    expect(state.viewportHeight).toBe(viewportHeight);
+    expect(state.terminalFocused).toBe(false);
+  });
+
+  it('maps Up+Down to one Enter and supports swipes on the surrounding band', async () => {
+    await page.evaluate(`
+      (function() {
+        const nav = document.querySelector(${JSON.stringify(SELECTORS.MOBILE_NAVIGATION)});
+        const up = nav.querySelector('[data-nav-key="up"]');
+        const down = nav.querySelector('[data-nav-key="down"]');
+        const emit = (target, type, pointerId, clientY = 0) => {
+          target.dispatchEvent(new PointerEvent(type, {
+            bubbles: true,
+            cancelable: true,
+            pointerId,
+            pointerType: 'touch',
+            isPrimary: pointerId === 1,
+            clientY
+          }));
+        };
+
+        emit(up, 'pointerdown', 1);
+        emit(down, 'pointerdown', 2);
+        emit(up, 'pointerup', 1);
+        emit(down, 'pointerup', 2);
+      })()
+    `);
+    await page.waitForTimeout(50);
+    expect(inputLog).toEqual(['\r']);
+
+    inputLog.length = 0;
+    await page.evaluate(`
+      (function() {
+        const nav = document.querySelector(${JSON.stringify(SELECTORS.MOBILE_NAVIGATION)});
+        const rect = nav.getBoundingClientRect();
+        const x = rect.left + 12;
+        nav.dispatchEvent(new PointerEvent('pointerdown', {
+          bubbles: true,
+          cancelable: true,
+          pointerId: 3,
+          pointerType: 'touch',
+          isPrimary: true,
+          clientX: x,
+          clientY: rect.bottom - 4
+        }));
+        nav.dispatchEvent(new PointerEvent('pointerup', {
+          bubbles: true,
+          cancelable: true,
+          pointerId: 3,
+          pointerType: 'touch',
+          isPrimary: true,
+          clientX: x,
+          clientY: rect.top + 4
+        }));
+      })()
+    `);
+    await page.waitForTimeout(50);
+    expect(inputLog).toEqual(['\x1b[A']);
+  });
+
+  it('uses volume-key DOM events when the browser exposes them', async () => {
+    await page.evaluate(`
+      document.body.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'AudioVolumeDown',
+        code: 'AudioVolumeDown',
+        bubbles: true,
+        cancelable: true
+      }));
+      document.body.dispatchEvent(new KeyboardEvent('keyup', {
+        key: 'AudioVolumeDown',
+        code: 'AudioVolumeDown',
+        bubbles: true,
+        cancelable: true
+      }));
+    `);
+    await page.waitForTimeout(50);
+    expect(inputLog).toEqual(['\x1b[B']);
+
+    inputLog.length = 0;
+    await page.evaluate(`
+      for (const [type, key] of [
+        ['keydown', 'AudioVolumeUp'],
+        ['keydown', 'AudioVolumeDown'],
+        ['keyup', 'AudioVolumeUp'],
+        ['keyup', 'AudioVolumeDown']
+      ]) {
+        document.body.dispatchEvent(new KeyboardEvent(type, {
+          key,
+          code: key,
+          bubbles: true,
+          cancelable: true
+        }));
+      }
+    `);
+    await page.waitForTimeout(50);
+    expect(inputLog).toEqual(['\r']);
+  });
+
+  it('is controlled from the mobile App Settings Input options', async () => {
+    await page.evaluate(`app.openAppSettings()`);
+    const settingRow = page.locator('#appSettingsMobileTerminalControlsItem');
+    const setting = page.locator('#appSettingsMobileTerminalControls');
+    const settingSlider = settingRow.locator('.slider');
+    const hapticsRow = page.locator('#appSettingsMobileControlHapticsItem');
+    const haptics = hapticsRow.locator('#appSettingsMobileControlHaptics');
+    const soundRow = page.locator('#appSettingsMobileControlSoundItem');
+    const sound = soundRow.locator('#appSettingsMobileControlSound');
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(false);
+    expect(await settingRow.isVisible()).toBe(true);
+    expect(await settingSlider.isVisible()).toBe(true);
+    expect(await setting.isChecked()).toBe(false);
+    expect(await hapticsRow.isVisible()).toBe(true);
+    expect(await hapticsRow.locator('.slider').isVisible()).toBe(true);
+    expect(await haptics.isChecked()).toBe(false);
+    expect(await soundRow.isVisible()).toBe(true);
+    expect(await soundRow.locator('.slider').isVisible()).toBe(true);
+    expect(await sound.isChecked()).toBe(false);
+    expect(await settingRow.locator('.settings-item-label').textContent()).toBe('Mobile Terminal Controls');
+    expect(await page.locator('#appSettingsExtendedKeyboardBar').count()).toBe(0);
+    if (process.env.CODEMAN_NAV_MODAL_SCREENSHOT) {
+      await page.screenshot({ path: process.env.CODEMAN_NAV_MODAL_SCREENSHOT });
+    }
+
+    await settingSlider.click();
+    expect(await setting.isChecked()).toBe(true);
+    await page.evaluate(`app.saveAppSettings()`);
+    await page.waitForFunction(() => {
+      const saved = JSON.parse(localStorage.getItem('codeman-app-settings-mobile') || '{}');
+      return saved.mobileTerminalControlsEnabled === true;
+    });
+    expect(
+      await page.evaluate(
+        `MobileTerminalControls.enabled === true &&
+          MobileNavigationPad.enabled === true &&
+          KeyboardAccessoryBar.enabled === true`
+      )
+    ).toBe(true);
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(true);
+
+    await page.evaluate(`app.openAppSettings()`);
+    expect(await setting.isChecked()).toBe(true);
+    await settingSlider.click();
+    expect(await setting.isChecked()).toBe(false);
+    await page.evaluate(`app.saveAppSettings()`);
+    await page.waitForFunction(() => {
+      const saved = JSON.parse(localStorage.getItem('codeman-app-settings-mobile') || '{}');
+      return saved.mobileTerminalControlsEnabled === false;
+    });
+    expect(
+      await page.evaluate(
+        `MobileTerminalControls.enabled === false &&
+          MobileNavigationPad.enabled === false &&
+          KeyboardAccessoryBar.enabled === false`
+      )
+    ).toBe(true);
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(false);
+  });
+
+  it('switches to the extended accessory bar while the phone keyboard is visible', async () => {
+    const viewportHeight = await page.evaluate(() => window.visualViewport?.height);
+    await page.evaluate(`
+      KeyboardHandler.keyboardVisible = true;
+      document.body.classList.add('keyboard-visible');
+      KeyboardHandler.onKeyboardShow();
+    `);
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(false);
+    expect(await page.locator(SELECTORS.KEYBOARD_ACCESSORY).isVisible()).toBe(true);
+    expect(await page.locator('.keyboard-accessory-bar [data-action="arrow-left"]').isVisible()).toBe(true);
+    expect(await page.locator('.toolbar').isVisible()).toBe(false);
+    const keyboardLayout = await page.evaluate(() => {
+      const appEl = document.querySelector('.app') as HTMLElement;
+      const main = document.querySelector('.main') as HTMLElement;
+      const terminal = document.getElementById('terminalContainer') as HTMLElement;
+      const accessory = document.querySelector('.keyboard-accessory-bar') as HTMLElement;
+      const appBox = appEl.getBoundingClientRect();
+      const terminalBox = terminal.getBoundingClientRect();
+      const accessoryBox = accessory.getBoundingClientRect();
+      return {
+        mainPadding: parseFloat(getComputedStyle(main).paddingBottom),
+        appBottom: appBox.bottom,
+        terminalBottom: terminalBox.bottom,
+        accessoryTop: accessoryBox.top,
+        accessoryBottom: accessoryBox.bottom,
+        accessoryScrollLeft: accessory.scrollLeft,
+        primaryButtonsContained: [
+          'esc',
+          'arrow-left',
+          'scroll-up',
+          'opt-enter',
+          'scroll-down',
+          'arrow-right',
+          'tab',
+        ].every((action) => {
+          const button = accessory.querySelector(`[data-action="${action}"]`);
+          if (!(button instanceof HTMLElement)) return false;
+          const box = button.getBoundingClientRect();
+          return box.left >= accessoryBox.left - 1 && box.right <= accessoryBox.right + 1;
+        }),
+      };
+    });
+    expect(keyboardLayout.mainPadding).toBeGreaterThan(0);
+    expect(keyboardLayout.terminalBottom).toBeLessThanOrEqual(keyboardLayout.accessoryTop + 1);
+    expect(Math.abs(keyboardLayout.accessoryBottom - keyboardLayout.appBottom)).toBeLessThanOrEqual(1);
+    expect(keyboardLayout.accessoryScrollLeft).toBe(0);
+    expect(keyboardLayout.primaryButtonsContained).toBe(true);
+
+    inputLog.length = 0;
+    await page.locator('.keyboard-accessory-bar [data-action="arrow-left"]').click();
+    await vi.waitFor(() => {
+      expect(inputLog).toEqual(['\x1b[D']);
+    });
+    const afterKey = await page.evaluate(`({
+      keyboardVisible: KeyboardHandler.keyboardVisible,
+      viewportHeight: window.visualViewport?.height,
+      terminalFocused: document.activeElement?.classList.contains('xterm-helper-textarea') || false
+    })`);
+    expect(afterKey.keyboardVisible).toBe(true);
+    expect(afterKey.viewportHeight).toBe(viewportHeight);
+    expect(afterKey.terminalFocused).toBe(true);
+
+    await page.evaluate(`
+      KeyboardHandler.keyboardVisible = false;
+      document.body.classList.remove('keyboard-visible');
+      KeyboardHandler.onKeyboardHide();
+    `);
+    await page.waitForTimeout(KEYBOARD.ANIMATION_DELAY);
+    expect(await page.locator(SELECTORS.KEYBOARD_ACCESSORY).isVisible()).toBe(false);
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(true);
+    expect(await page.locator('.toolbar').isVisible()).toBe(true);
+  });
+
+  it('removes the keyboard-open reservation when mobile controls are disabled', async () => {
+    await page.evaluate(`
+      MobileTerminalControls.setEnabled(false);
+      KeyboardHandler.keyboardVisible = true;
+      document.body.classList.add('keyboard-visible');
+      KeyboardHandler.onKeyboardShow();
+    `);
+
+    expect(await page.locator(SELECTORS.KEYBOARD_ACCESSORY).isVisible()).toBe(false);
+    const layout = await page.evaluate(() => {
+      const appBox = document.querySelector('.app')!.getBoundingClientRect();
+      const terminalBox = document.getElementById('terminalContainer')!.getBoundingClientRect();
+      return {
+        hasReservation: document.body.classList.contains('keyboard-accessory-visible'),
+        mainPadding: parseFloat(getComputedStyle(document.querySelector('.main')!).paddingBottom),
+        appBottom: appBox.bottom,
+        terminalBottom: terminalBox.bottom,
+      };
+    });
+    expect(layout.hasReservation).toBe(false);
+    expect(layout.mainPadding).toBe(0);
+    expect(Math.abs(layout.terminalBottom - layout.appBottom)).toBeLessThanOrEqual(1);
+  });
+
+  it('removes both keyboard control surfaces while a dialog is open', async () => {
+    await page.evaluate(`
+      KeyboardHandler.keyboardVisible = true;
+      document.body.classList.add('keyboard-visible');
+      KeyboardHandler.onKeyboardShow();
+    `);
+    expect(await page.locator(SELECTORS.KEYBOARD_ACCESSORY).isVisible()).toBe(true);
+
+    await page.evaluate(`app.openAppSettings()`);
+    await page.waitForFunction(() => !document.body.classList.contains('keyboard-accessory-visible'));
+    expect(await page.locator(SELECTORS.KEYBOARD_ACCESSORY).isVisible()).toBe(false);
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(false);
+    expect(
+      await page.evaluate(() => parseFloat(getComputedStyle(document.querySelector('.main')!).paddingBottom))
+    ).toBe(0);
+
+    await page.evaluate(`app.closeAppSettings()`);
+    await page.waitForFunction(() => document.body.classList.contains('keyboard-accessory-visible'));
+    expect(await page.locator(SELECTORS.KEYBOARD_ACCESSORY).isVisible()).toBe(true);
+  });
+
+  it('removes the navigation-band reservation during an incremental keyboard animation', async () => {
+    const state = await page.evaluate(`(function() {
+      var vv = window.visualViewport;
+      var baseline = KeyboardHandler.initialViewportHeight;
+      Object.defineProperty(window, 'innerHeight', {
+        get: function() { return baseline; },
+        configurable: true,
+      });
+
+      for (const shrink of [70, 140, 210]) {
+        Object.defineProperty(vv, 'height', {
+          get: function() { return baseline - shrink; },
+          configurable: true,
+        });
+        KeyboardHandler.handleViewportResize();
+      }
+
+      return {
+        keyboardVisible: KeyboardHandler.keyboardVisible,
+        keyboardClass: document.body.classList.contains('keyboard-visible'),
+        navigationClass: document.body.classList.contains('mobile-nav-visible'),
+        mainPadding: parseFloat(getComputedStyle(document.querySelector('.main')).paddingBottom),
+        toolbarDisplay: getComputedStyle(document.querySelector('.toolbar')).display,
+        accessoryDisplay: getComputedStyle(document.querySelector('.keyboard-accessory-bar')).display,
+        toolbarTransform: document.querySelector('.toolbar').style.transform,
+        accessoryTransform: document.querySelector('.keyboard-accessory-bar').style.transform,
+        appBottom: document.querySelector('.app').getBoundingClientRect().bottom,
+        terminalBottom: document.getElementById('terminalContainer').getBoundingClientRect().bottom,
+        accessoryTop: document.querySelector('.keyboard-accessory-bar').getBoundingClientRect().top,
+        accessoryBottom: document.querySelector('.keyboard-accessory-bar').getBoundingClientRect().bottom,
+      };
+    })()`);
+
+    expect(state.keyboardVisible).toBe(true);
+    expect(state.keyboardClass).toBe(true);
+    expect(state.navigationClass).toBe(false);
+    expect(state.mainPadding).toBeGreaterThan(0);
+    expect(state.toolbarDisplay).toBe('none');
+    expect(state.accessoryDisplay).toBe('flex');
+    expect(state.toolbarTransform).toBe('');
+    expect(state.accessoryTransform).toBe('');
+    expect(state.terminalBottom).toBeLessThanOrEqual(state.accessoryTop + 1);
+    expect(Math.abs(state.accessoryBottom - state.appBottom)).toBeLessThanOrEqual(1);
+    expect(await page.locator(SELECTORS.MOBILE_NAVIGATION).isVisible()).toBe(false);
+  });
+});
diff --git a/test/mobile/settings.test.ts b/test/mobile/settings.test.ts
index 5d6282b2..28df1f98 100644
--- a/test/mobile/settings.test.ts
+++ b/test/mobile/settings.test.ts
@@ -60,7 +60,7 @@ describe('Settings Modal', () => {
       }
     });
 
-    it('mobile defaults: all panels hidden, subagent tracking OFF, ralph OFF', async () => {
+    it('mobile defaults: panels hidden, subagent tracking ON, ralph OFF', async () => {
       const defaults = await page.evaluate(() => {
         const fn = (window as any).app?.getDefaultSettings;
         if (fn) return fn.call((window as any).app);
@@ -76,8 +76,11 @@ describe('Settings Modal', () => {
         expect(defaults.showProjectInsights).toBe(false);
         expect(defaults.showFileBrowser).toBe(false);
         expect(defaults.showSubagents).toBe(false);
-        expect(defaults.subagentTrackingEnabled).toBe(false);
+        expect(defaults.subagentTrackingEnabled).toBe(true);
         expect(defaults.ralphTrackerEnabled).toBe(false);
+        expect(defaults.mobileTerminalControlsEnabled).toBe(false);
+        expect(defaults.mobileControlHaptics).toBe(false);
+        expect(defaults.mobileControlSound).toBe(false);
       }
     });
 
@@ -305,7 +308,6 @@ describe('Settings Modal', () => {
             JSON.stringify({
               showFontControls: true,
               showMonitor: true,
-              subagentTrackingEnabled: true,
             })
           );
         }, STORAGE_KEYS.SETTINGS_MOBILE);
@@ -323,7 +325,6 @@ describe('Settings Modal', () => {
         expect(settings).not.toBeNull();
         expect(settings?.showFontControls).toBe(true);
         expect(settings?.showMonitor).toBe(true);
-        expect(settings?.subagentTrackingEnabled).toBe(true);
       } finally {
         await context.close();
       }
@@ -414,7 +415,7 @@ describe('Settings Modal', () => {
             key,
             JSON.stringify({
               showResponseViewer: true,
-              extendedKeyboardBar: true,
+              mobileTerminalControlsEnabled: true,
             })
           );
         }, STORAGE_KEYS.SETTINGS_MOBILE);
@@ -434,16 +435,60 @@ describe('Settings Modal', () => {
           responseViewerVisible: !document
             .querySelector('.btn-response-viewer-header')
             ?.classList.contains('btn-response-viewer-header--hidden'),
-          keyboardExtended: Boolean(document.querySelector('.keyboard-accessory-bar [data-action="arrow-left"]')),
         }));
 
         expect(state.deviceType).toBe('desktop');
         expect(state.handheld).toBe(true);
         expect(state.storageKey).toBe(STORAGE_KEYS.SETTINGS_MOBILE);
         expect(state.responseViewerVisible).toBe(true);
-        expect(state.keyboardExtended).toBe(true);
+        expect(await page.evaluate('MobileTerminalControls.enabled')).toBe(true);
 
-        await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT);
+        await page.evaluate(() => (window as any).app.openAppSettings());
+        await assertVisible(page, '#appSettingsMobileTerminalControlsItem');
+        expect(await page.locator('#appSettingsMobileTerminalControls').isChecked()).toBe(true);
+        await page.evaluate(() => (window as any).app.closeAppSettings());
+
+        await page.evaluate(`
+          app.activeSessionId = 'foldable-controls-test';
+          app.hideWelcome();
+          MobileTerminalControls.syncVisibility();
+        `);
+
+        await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT, { preferredLayer: 'dom' });
+        await assertVisible(page, '.keyboard-accessory-bar');
+        const alignment = await page.evaluate(() => {
+          const appBox = document.querySelector('.app')!.getBoundingClientRect();
+          const accessoryBox = document.querySelector('.keyboard-accessory-bar')!.getBoundingClientRect();
+          return Math.abs(accessoryBox.bottom - appBox.bottom);
+        });
+        expect(alignment).toBeLessThanOrEqual(1);
+      } finally {
+        await context.close();
+      }
+    });
+
+    it('keeps unified controls opt-in on touch tablets', async () => {
+      const device = REPRESENTATIVE_DEVICES['standard-tablet'];
+      const { page, context } = await createDevicePage(device, BASE_URL, 'chromium');
+
+      try {
+        expect(await page.evaluate('MobileTerminalControls.enabled')).toBe(false);
+
+        await page.evaluate(() => (window as any).app.openAppSettings());
+        await assertVisible(page, '#appSettingsMobileTerminalControlsItem');
+        expect(await page.locator('#appSettingsMobileTerminalControls').isChecked()).toBe(false);
+        await page.evaluate(() => (window as any).app.closeAppSettings());
+
+        await page.evaluate(`
+          const settings = app.loadAppSettingsFromStorage();
+          settings.mobileTerminalControlsEnabled = true;
+          app.saveAppSettingsToStorage(settings);
+          MobileTerminalControls.setEnabled(true);
+          app.activeSessionId = 'tablet-controls-test';
+          app.hideWelcome();
+          MobileTerminalControls.syncVisibility();
+        `);
+        await showKeyboard(page, KEYBOARD.TYPICAL_IOS_HEIGHT, { preferredLayer: 'dom' });
         await assertVisible(page, '.keyboard-accessory-bar');
       } finally {
         await context.close();