feat(mobile): shell keyboard bar with a one-shot Ctrl modifier (#262)

The mobile accessory bar was built around coding-agent commands, so a shell
session had no way to send Ctrl chords at all.

A shell-mode session now gets its own bar automatically: Ctrl, Esc, Tab,
four arrows, paste, dismiss. Agent sessions (claude, codex, opencode,
gemini, antigravity) keep the existing bar unchanged.

Ctrl is a one-shot modifier: tap it and it lights up, the next character
typed on the system keyboard is sent as its control byte, and Ctrl disarms.
Tapping it again cancels. That puts Ctrl+C/D/Z/R/L/A/E/W/U/K on a
nine-button bar without a button per chord.

Implementation notes:

* The interception lives in terminal.onData, not a keydown handler: a
  virtual keyboard reports no usable key events, so the character only
  exists as onData text. It sits after shouldSuppressTerminalQueryResponse
  (xterm answers DA/CPR queries through onData too, and letting one of those
  spend the modifier would silently eat the user's Ctrl) and before every
  send path, so the control byte follows the normal control-char route.
* ctrlByteFor() maps `code & 0x1f` over @A-Z[\]^_ and a-z, plus
  Ctrl+Space = NUL and Ctrl+? = DEL. Characters with no control equivalent
  pass through unchanged, like a hardware keyboard.
* The bar now separates the base layout (the extendedKeyboardBar setting)
  from the effective one, resolved per session by refreshForActiveSession().
  A settings save during a shell session cannot yank the bar away, and
  switching back to an agent tab restores the user's choice.
* Ctrl disarms on use, a second tap, any other accessory key, a session
  switch, keyboard dismissal and a layout swap.
* Ctrl joins the refocus set, so tapping it keeps the terminal focused and
  the keyboard open.
* The armed style needs three classes to outrank mobile.css's light-skin
  .accessory-btn rule at (0,2,1).

Verified end to end against a real shell session on an isolated instance:
tapping Ctrl then typing c interrupted a running `sleep 300` (^C in the
pane), the modifier disarmed, plain typing stayed literal, Ctrl+L cleared,
and a cancelled Ctrl typed a literal c.

Tests: test/mobile-shell-keyboard.test.ts (new, runs in CI) covers the
mapping table, layout selection per session mode, base-mode memory and every
disarm path; test/mobile/keyboard.test.ts adds nine browser regressions that
drive the real xterm with page.keyboard.type() and assert on the bytes that
would go out.

Closes #262

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

src/web/public/app.js

@@ -848,9 +848,11 @@ class CodemanApp {
     SwipeHandler.init();
     VoiceInput.init();
     KeyboardAccessoryBar.init();
-    // Apply keyboard bar mode from settings
+    // Apply keyboard bar mode from settings. Always set it (not only when the
+    // extended bar is on) so the bar's remembered agent-session layout matches
+    // the setting before the first shell session swaps in the terminal bar.
     const _kbSettings = this.loadAppSettingsFromStorage();
-    if (_kbSettings.extendedKeyboardBar) KeyboardAccessoryBar.setMode('extended');
+    KeyboardAccessoryBar.setMode(_kbSettings.extendedKeyboardBar ? 'extended' : 'simple');
     this.applyHeaderVisibilitySettings();
     this.restorePlanUsageChip();
     this.applySkin();
@@ -4457,6 +4459,10 @@ class CodemanApp {
       this.loadAttachmentHistory?.(sessionId);
     }
     this._updateLocalEchoState();
+    // Shell sessions get the terminal keyboard bar, agent sessions the command
+    // bar (issue #262). Also disarms a one-shot Ctrl left over from the tab we
+    // just left, so it can never fire against the session we just opened.
+    if (typeof KeyboardAccessoryBar !== 'undefined') KeyboardAccessoryBar.refreshForActiveSession();
 
     // Restore flushed offset AND text IMMEDIATELY so backspace/typing work during
     // the async buffer load.  Without this, the offset is 0 during the

src/web/public/keyboard-accessory.js

@@ -12,6 +12,13 @@
  *   Destructive actions (/clear, /compact, extended bar only) require double-tap confirmation (2s amber state).
  *   Commands are sent as text + Enter separately for Ink compatibility.
  *   Only initializes on touch devices (MobileDetection.isTouchDevice guard).
+ *   SHELL sessions get their own layout automatically (issue #262): Ctrl, Esc, Tab,
+ *   four arrows, paste, dismiss. Ctrl is a ONE-SHOT modifier: arm it, type a
+ *   character on the system keyboard, and terminal-ui.js's onData hook swaps the
+ *   character for its control byte (ctrlByteFor) and disarms. That is what makes
+ *   Ctrl+C/D/Z/R/L/A/E/W/U/K reachable without a button per chord. It resets on
+ *   use, on a second tap, on any other accessory key, on a session switch
+ *   (refreshForActiveSession) and when the keyboard is dismissed (hide).
  * - PathPicker (singleton object) — Lazy server-side file/folder browser shared
  *   by Link Existing and the extended mobile keyboard bar.
  *
@@ -414,12 +421,58 @@ const PathPicker = {
 // Mobile Keyboard Accessory Bar
 // ═══════════════════════════════════════════════════════════════
 
+/**
+ * Control byte a terminal sends for Ctrl+<char> (issue #262).
+ *
+ * Returns null for characters with no control equivalent (digits, most
+ * punctuation): the caller then sends the character unchanged, matching a
+ * hardware keyboard where Ctrl+7 just types "7".
+ *
+ * `code & 0x1f` covers both ranges a terminal maps: @A-Z[\]^_ (64-95 → 0-31)
+ * and a-z (97-122 → 1-26). Space and ? are the two conventional extras
+ * (Ctrl+Space = NUL, Ctrl+? = DEL) and can't come from the mask.
+ */
+function ctrlByteFor(char) {
+  if (typeof char !== 'string' || char.length !== 1) return null;
+  const code = char.charCodeAt(0);
+  if (code === 32) return '\x00';
+  if (code === 63) return '\x7f';
+  if ((code >= 64 && code <= 95) || (code >= 97 && code <= 122)) {
+    return String.fromCharCode(code & 0x1f);
+  }
+  return null;
+}
+
+/**
+ * Apply an armed one-shot Ctrl to one chunk of terminal input.
+ * Returns `{ data, consumed }`, where `consumed` tells the bar to disarm.
+ *
+ * Multi-character chunks (pastes, escape sequences, IME commits) have no
+ * single key to modify, but they still spend the modifier: leaving it armed
+ * would silently turn the NEXT innocent keystroke into a control byte.
+ */
+function applyOneShotCtrl(data) {
+  if (typeof data !== 'string' || data.length === 0) return { data, consumed: false };
+  if (data.length === 1) {
+    const byte = ctrlByteFor(data);
+    return { data: byte === null ? data : byte, consumed: true };
+  }
+  return { data, consumed: true };
+}
+
 /**
  * KeyboardAccessoryBar - Quick action buttons shown above keyboard when typing.
  */
 const KeyboardAccessoryBar = {
   element: null,
-  _mode: 'simple', // 'simple' or 'extended'
+  // Layout currently in the DOM: 'simple' | 'extended' | 'shell'.
+  _mode: 'simple',
+  // Layout the user picked for AGENT sessions ('simple' | 'extended', the
+  // extendedKeyboardBar setting). Shell sessions override it with the shell
+  // bar; this is what we come back to when they switch to an agent tab.
+  _baseMode: 'simple',
+  // One-shot Ctrl modifier (shell bar only). See handleAction('ctrl').
+  _ctrlArmed: false,
 
   /** HTML for simple mode: arrows, commands, paste, Esc, dismiss */
   _simpleButtons: `
@@ -448,6 +501,45 @@ const KeyboardAccessoryBar = {
         </svg>
       </button>`,
 
+  /** HTML for shell mode (issue #262): terminal controls instead of agent
+   *  commands. Ctrl is a one-shot modifier rather than one button per chord,
+   *  which is what puts Ctrl+C/D/Z/R/L/A/E/W/U/K on a 9-button bar. */
+  _shellButtons: `
+      <button class="accessory-btn accessory-btn-ctrl" data-action="ctrl" title="Ctrl, then tap a key" aria-pressed="false">Ctrl</button>
+      <button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
+      <button class="accessory-btn" data-action="tab" title="Tab">Tab</button>
+      <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">
+        <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="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"/>
+        </svg>
+      </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">
@@ -514,7 +606,7 @@ const KeyboardAccessoryBar = {
       this.handleAction(action, btn);
 
       // Refocus terminal so keyboard stays open (tap blurs terminal → keyboard dismisses → toolbar shifts)
-      const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc', 'effort-max', 'clear-input']);
+      const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl', 'ctrl-o', 'opt-enter', 'esc', 'effort-max', 'clear-input']);
       if (refocusActions.has(action) ||
           ((action === 'clear' || action === 'compact') && this._confirmAction)) {
         if (typeof app !== 'undefined' && app.terminal) {
@@ -530,14 +622,91 @@ const KeyboardAccessoryBar = {
     }
   },
 
-  /** Switch between 'simple' and 'extended' button layouts */
+  /** Pick the layout the user wants for AGENT sessions ('simple' | 'extended',
+   *  the extendedKeyboardBar setting). A shell session keeps the shell bar;
+   *  the preference is remembered and applied on the next agent tab. */
   setMode(mode) {
-    if (mode === this._mode || !this.element) return;
+    this._baseMode = mode === 'extended' ? 'extended' : 'simple';
+    this._applyLayout(this._resolveMode());
+  },
+
+  /** Re-resolve the layout after the active session changed (issue #262):
+   *  shell sessions get the terminal bar, everything else the agent bar. Also
+   *  disarms Ctrl, because a modifier armed on one session must never fire on
+   *  the next one. */
+  refreshForActiveSession() {
+    this.clearCtrl();
+    this._applyLayout(this._resolveMode());
+  },
+
+  /** Which layout the current state calls for. */
+  _resolveMode() {
+    return this._isShellSession() ? 'shell' : this._baseMode;
+  },
+
+  _isShellSession() {
+    if (typeof app === 'undefined' || !app.activeSessionId) return false;
+    return app.sessions?.get(app.activeSessionId)?.mode === 'shell';
+  },
+
+  /** Swap the button set in the DOM. */
+  _applyLayout(mode) {
+    if (!this.element || mode === this._mode) return;
     this._mode = mode;
     this.clearConfirm();
-    this.element.innerHTML = mode === 'extended' ? this._extendedButtons : this._simpleButtons;
+    // Reset before the rewrite: _setCtrl() styles the button it can find, and
+    // the one holding the armed class is about to be replaced.
+    this.clearCtrl();
+    this.element.innerHTML =
+      mode === 'shell' ? this._shellButtons : mode === 'extended' ? this._extendedButtons : this._simpleButtons;
   },
 
+  // ── One-shot Ctrl modifier (shell bar) ──────────────────────────────────
+  // Tap Ctrl, then type a character on the system keyboard: the character is
+  // replaced by its control byte and Ctrl disarms. Tapping Ctrl again cancels.
+  // The interception lives in the terminal onData handler (terminal-ui.js),
+  // which is where system-keyboard input arrives on a phone. A keydown hook
+  // would miss it, since virtual keyboards report no usable key events.
+
+  /** Is the one-shot Ctrl waiting for a key? */
+  isCtrlArmed() {
+    return this._ctrlArmed === true;
+  },
+
+  /** Arm/cancel the one-shot Ctrl (the Ctrl button toggles). */
+  toggleCtrl() {
+    this._setCtrl(!this._ctrlArmed);
+  },
+
+  /** Disarm: used by session switch, keyboard dismissal and every other key. */
+  clearCtrl() {
+    if (this._ctrlArmed) this._setCtrl(false);
+  },
+
+  _setCtrl(on) {
+    this._ctrlArmed = !!on;
+    const btn = this.element?.querySelector('[data-action="ctrl"]');
+    if (btn) {
+      btn.classList.toggle('armed', this._ctrlArmed);
+      btn.setAttribute('aria-pressed', this._ctrlArmed ? 'true' : 'false');
+    }
+  },
+
+  /**
+   * Apply an armed Ctrl to a chunk of typed input and disarm.
+   * Returns the data unchanged (and leaves the modifier alone) when Ctrl is
+   * not armed, so the caller can pipe every keystroke through it.
+   */
+  consumeCtrl(data) {
+    if (!this._ctrlArmed) return data;
+    const result = applyOneShotCtrl(data);
+    if (result.consumed) this.clearCtrl();
+    return result.data;
+  },
+
+  /** Exposed for tests: pure char to control byte mapping. */
+  ctrlByteFor,
+
   _confirmTimer: null,
   _confirmAction: null,
 
@@ -545,7 +714,15 @@ const KeyboardAccessoryBar = {
   handleAction(action, btn) {
     if (typeof app === 'undefined' || !app.activeSessionId) return;
 
+    // Any key other than Ctrl itself spends the modifier. It is a one-shot for
+    // the next TYPED character, so an accessory key tapped in between (Esc, an
+    // arrow, paste) must not leave it armed to bite the keystroke after that.
+    if (action !== 'ctrl') this.clearCtrl();
+
     switch (action) {
+      case 'ctrl':
+        this.toggleCtrl();
+        break;
       case 'scroll-up':
         this.sendKey('\x1b[A');
         break;
@@ -784,6 +961,10 @@ const KeyboardAccessoryBar = {
 
   /** Hide the accessory bar */
   hide() {
+    // The bar goes away with the keyboard, so an armed Ctrl has nothing left
+    // to modify, and a modifier the user can no longer see must not survive
+    // to the next time they open the keyboard.
+    this.clearCtrl();
     if (this.element) {
       this.element.classList.remove('visible');
     }

src/web/public/mobile.css

@@ -1162,6 +1162,17 @@ html.mobile-init .file-browser-panel {
     color: #ffd54f;
   }
 
+  /* Armed one-shot Ctrl (shell bar, issue #262). Phone palette is hardcoded in
+     this block, so the state needs its own entry here; three classes to outrank
+     the light-skin .accessory-btn rule at the bottom of this file. */
+  .accessory-btn.accessory-btn-ctrl.armed {
+    background: #2563eb;
+    border-color: rgba(59, 130, 246, 0.9);
+    color: #fff;
+    font-weight: 700;
+    box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.45);
+  }
+
   .accessory-btn:active {
     background: #3a3a3a;
   }

src/web/public/styles.css

@@ -12081,6 +12081,18 @@ body.touch-device.cjk-input-visible .main {
   color: var(--yellow);
 }
 
+/* Armed one-shot Ctrl (shell bar, issue #262). Three classes on purpose: the
+   light-skin compatibility rule in mobile.css repaints every .accessory-btn at
+   specificity (0,2,1), so a two-class rule here would lose and the modifier
+   would look unarmed on the light skins. */
+.accessory-btn.accessory-btn-ctrl.armed {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--accent-ink);
+  font-weight: 700;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 40%, transparent);
+}
+
 .accessory-btn:active {
   background: var(--control-bg-hover);
 }

src/web/public/terminal-ui.js

@@ -930,6 +930,18 @@ Object.assign(CodemanApp.prototype, {
         ) {
           return;
         }
+
+        // ── One-shot Ctrl (mobile shell bar, issue #262) ──
+        // A virtual keyboard reports no usable key events, so a keydown hook
+        // would never see the character the modifier applies to: it arrives
+        // here as onData text. Sits AFTER the query-response filter so xterm's
+        // own DA/CPR replies can never spend the modifier, and BEFORE every
+        // send path so the control byte follows the normal control-char route
+        // (immediate flush, local-echo state cleared).
+        if (typeof KeyboardAccessoryBar !== 'undefined' && KeyboardAccessoryBar.isCtrlArmed?.()) {
+          data = KeyboardAccessoryBar.consumeCtrl(data);
+        }
+
         this._lastTerminalData = { data, time: performance.now() };
 
         // ── Local Echo Pass-through ──