Mobile: the way back rides in the pane header

On a phone the session window carried a bar of its own above it, holding a back
arrow and the session's name. The name was already in the pane header directly
below it, so the bar's only unique job was the arrow — and it charged a row of
the one dimension a terminal has too little of.

The arrow moves into the pane header, immediately left of the agent's logo, as
the operator suggested. The bar goes with it: at 390px the terminal grows from
544px to 582px, and the header it moved into is not one pixel taller, because
the button stretches into the header's existing padding rather than adding any.

The bar survives wherever nothing else can hold the arrow, which is the part
worth reviewing:

- a group, whose bar is also the chip pager between its agents
- the Overview, which has no pane header at all
- the files and trace panes, whose flat headers have no identity block — and
whose leftmost spot is, for files, already a back button to the file list, so
a second arrow there would be two backs meaning two different things

That rule is `paneOwnsBack` in lib/mobileBack.ts, tested rather than inlined,
because it decides whether a surface has any way back at all.

Also: the terminal/reader switch takes the left edge on a phone. It sat adrift
mid-bar because the spacer that pushes the zoom keys right on a wide window was
pushing it too; ordering it ahead of the spacer gives it the left and leaves
zoom on the right.

Verified with playwright at 320/390/768/1280, before and after. Desktop is
untouched: every measured number identical, and a chrome-only pixel diff differs
by 0-17px against a 7-39px noise floor measured by running the same build twice.
No page scrolls sideways at any width (#71 holds). 13 browser checks on the
behaviour, 13 unit checks on the rule, web and server suites green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

web/package.json

@@ -13,7 +13,7 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "typecheck": "tsc --noEmit",
-    "test": "node test/exchanges.test.mjs && node test/sessionTitle.test.mjs && node test/overviewSort.test.mjs && node test/drafts.test.mjs && node test/traceWindows.test.mjs",
+    "test": "node test/mobileBack.test.mjs && node test/exchanges.test.mjs && node test/sessionTitle.test.mjs && node test/overviewSort.test.mjs && node test/drafts.test.mjs && node test/traceWindows.test.mjs",
     "preview": "vite preview"
   },
   "dependencies": {

web/src/App.tsx

@@ -19,6 +19,7 @@ import type { Cli, GridSpec, MoveTarget, OverviewChip, OverviewSort, Session, Tr
 import { onPaneMode, readPaneMode, writePaneMode } from './lib/paneMode';
 import { hiddenSessionIds } from './lib/overviewHidden';
 import { useReaderBatch } from './lib/readerBatch';
+import { paneOwnsBack } from './lib/mobileBack';
 import { isPassive, isRemote } from './types';
 import { EyeGlyph, EyeOffGlyph, GridGlyph, ListGlyph, SortGlyph } from './components/icons';
 import { uploadPendingAttachments } from './lib/attachments';
@@ -516,6 +517,13 @@ export default function App() {
     [activeGroup, sessById],
   );
 
+  // A staged agent carries its own way back, in its header left of the logo, and
+  // the bar above it goes away with the row it cost. See mobileBack.ts for which
+  // surfaces still need the bar and why.
+  const ownsBack = paneOwnsBack({
+    isMobile, staged: mobileStage, inGroup: !!activeGroup, cli: activeSingle?.cli,
+  });
+
   // Tile grid for the active group: the chosen layout, or auto (fit the count).
   // On mobile it's always a single pane — the chip strip switches between them.
   const grid: GridSpec = activeGroup && !isMobile ? (activeGroup.layout ?? autoGrid(groupSessions.length)) : { cols: 1, rows: 1 };
@@ -903,6 +911,7 @@ export default function App() {
                 active={shown && deckVisible && s.id === focusedId}
                 dragId={shown && canDrag ? `p:${s.id}` : undefined}
                 isMobile={isMobile}
+                onBack={ownsBack ? () => setMobileStage(false) : undefined}
                 onDragActive={setPaneDrag}
                 onFocus={() => setFocusedId(s.id)}
                 onRename={(name) => renameSession(s.id, name)}
@@ -935,6 +944,7 @@ export default function App() {
                 groupName={groupNameOf[s.id]}
                 focused={visibleSessions.length > 1 && s.id === focusedId}
                 dragId={canDrag ? `p:${s.id}` : undefined}
+                onBack={ownsBack ? () => setMobileStage(false) : undefined}
                 onDragActive={setPaneDrag}
                 onFocus={() => setFocusedId(s.id)}
                 onRename={(name) => renameSession(s.id, name)}
@@ -1063,7 +1073,7 @@ export default function App() {
       />
 
       <div className="main">
-        {isMobile && mobileStage && (
+        {isMobile && mobileStage && !ownsBack && (
           <div className="mbar">
             <button className="icon-btn mback" onClick={() => setMobileStage(false)} title="Back to list">‹</button>
             {activeGroup ? (

web/src/components/RemotePane.tsx

@@ -5,7 +5,7 @@ import * as api from '../api';
 import Logo from './Logo';
 import { renderMarkdown } from '../lib/markdown';
 import { groupLabel, sessionTitle } from '../lib/sessionTitle';
-import { CloseGlyph, StopGlyph, PlayGlyph, ShareGlyph, AckGlyph } from './icons';
+import { BackGlyph, CloseGlyph, StopGlyph, PlayGlyph, ShareGlyph, AckGlyph } from './icons';
 
 // Looks like the terminal, is not one: no PTY, no xterm.js, no WebSocket. The
 // agent's real TUI is running on its own machine — what crosses the wire is
@@ -25,13 +25,14 @@ const fmtAgo = (ts?: number | null) => {
 };
 
 export default function RemotePane({
-  session, focused, zoom = 100, dragId, groupName, onDragActive, onFocus, onClose, onRename,
+  session, focused, zoom = 100, dragId, groupName, onBack, onDragActive, onFocus, onClose, onRename,
 }: {
   session: Session;
   groupName?: string | null; // the group this pane belongs to, if any
   focused?: boolean;
   zoom?: number;
   dragId?: string;
+  onBack?: () => void;       // mobile: leave the pane for the list (see .ph-back)
   onDragActive?: (dragging: boolean) => void;
   onFocus?: () => void;
   onClose: () => void;
@@ -207,6 +208,20 @@ export default function RemotePane({
         onDragEnd={dragId ? () => onDragActive?.(false) : undefined}
       >
         <div className="ph-left">
+          {onBack && (
+            // See TerminalPane: on a phone the way back rides in the header
+            // rather than costing the pane a bar of its own.
+            <button
+              className="mini-btn ph-back"
+              title="Back to list"
+              aria-label="Back to list"
+              draggable={false}
+              onMouseDown={(e) => e.stopPropagation()}
+              onClick={(e) => { e.stopPropagation(); onBack(); }}
+            >
+              <BackGlyph />
+            </button>
+          )}
           <Logo cli="remote" size={16} tint="#5ec2e0" />
           <span className={`status ${state}`} title={stateLabel} />
         </div>

web/src/components/TerminalPane.tsx

@@ -12,7 +12,7 @@ import ConversationView from './conversation/ConversationView';
 import { isPassive } from '../types';
 import type { PaneMode } from '../lib/paneMode';
 import { groupLabel, sessionTitle } from '../lib/sessionTitle';
-import { CloseGlyph, RefreshGlyph } from './icons';
+import { BackGlyph, CloseGlyph, RefreshGlyph } from './icons';
 import * as api from '../api';
 import type { Attachment } from '../api';
 import {
@@ -189,7 +189,7 @@ if (typeof window !== 'undefined') {
 
 export default function TerminalPane({
   session, cli, theme, focused, visible, active, zoom = 100, mode = 'terminal', readerEnabled,
-  readerReadyKey, onReaderReady, dragId, isMobile, groupName, onDragActive, onFocus, onRename, onClose,
+  readerReadyKey, onReaderReady, dragId, isMobile, groupName, onBack, onDragActive, onFocus, onRename, onClose,
 }: {
   session: Session;
   cli?: Cli;
@@ -205,6 +205,7 @@ export default function TerminalPane({
   onReaderReady?: () => void;
   dragId?: string;          // set when the pane can be rearranged (group view)
   isMobile?: boolean;       // show the on-screen control-key bar
+  onBack?: () => void;      // mobile: leave the pane for the list (see .ph-back)
   onDragActive?: (dragging: boolean) => void;
   onFocus?: () => void;
   onRename?: (name: string) => void;
@@ -1021,6 +1022,20 @@ export default function TerminalPane({
         onMouseDown={(e) => { if (!dragId) e.preventDefault(); onFocus?.(); focusTerm(); }}
       >
         <div className="ph-left">
+          {onBack && (
+            // Sits in the header rather than in a bar of its own above it: a
+            // phone pays for that bar in the one dimension the terminal needs.
+            <button
+              className="mini-btn ph-back"
+              title="Back to list"
+              aria-label="Back to list"
+              draggable={false}
+              onMouseDown={(e) => e.stopPropagation()}
+              onClick={(e) => { e.stopPropagation(); onBack(); }}
+            >
+              <BackGlyph />
+            </button>
+          )}
           <Logo cli={session.cli} size={16} tint={tint} />
           <span className={`status ${session.state}`} title={`${STATE_LABEL[session.state]} · ${conn}`} />
         </div>

web/src/lib/mobileBack.ts

@@ -0,0 +1,29 @@
+import { isPassive } from '../types';
+
+/**
+ * Does the staged pane carry its own way back, in its header?
+ *
+ * On a phone the app is two full-screen views — the list, or one staged pane —
+ * so a staged pane needs a way back to the list. It used to be a bar above the
+ * pane holding an arrow and the session's name, and that bar cost a row of the
+ * one dimension a terminal actually needs. An agent's pane header already has
+ * an identity block (logo and status) on its left and already shows the name,
+ * so the arrow goes there and the bar goes away.
+ *
+ * The bar survives wherever nothing else can hold the arrow:
+ *  - a group, whose bar is also the chip pager between its agents;
+ *  - the Overview, which has no pane header at all;
+ *  - the files and trace panes, whose flat headers have no identity block —
+ *    and whose leftmost spot is, for files, already a back button to the file
+ *    list, so a second arrow there would be two backs meaning two things.
+ *
+ * Desktop never stages and never asks: the sidebar is always on screen.
+ */
+export const paneOwnsBack = (
+  { isMobile, staged, inGroup, cli }: {
+    isMobile: boolean;
+    staged: boolean;
+    inGroup: boolean;
+    cli?: string | null;
+  },
+): boolean => isMobile && staged && !inGroup && !!cli && !isPassive(cli);

web/src/styles.css

@@ -652,7 +652,11 @@ body {
    already reachable with a long enough agent name; putting the group in front
    of the name made it reachable at ordinary ones. With the floor the title is
    capped at what is actually free and ellipsises instead. */
-.pane-head { container-type: inline-size; display: grid; grid-template-columns: minmax(min-content, 1fr) minmax(0, auto) minmax(min-content, 1fr); align-items: center; gap: 9px; padding: 7px 11px; background: var(--panel); border-bottom: 1px solid var(--border); font-size: 12px; flex: none; }
+/* The vertical padding is a variable because .ph-back cancels it to reach the
+   header's full height without adding any (below). A bleed that restated the
+   number would drift the first time this padding changed — the same way a
+   hardcoded 14px against an 8px gutter gave the phone a sideways scroll. */
+.pane-head { --ph-pad-y: 7px; container-type: inline-size; display: grid; grid-template-columns: minmax(min-content, 1fr) minmax(0, auto) minmax(min-content, 1fr); align-items: center; gap: 9px; padding: var(--ph-pad-y) 11px; background: var(--panel); border-bottom: 1px solid var(--border); font-size: 12px; flex: none; }
 .pane-head .ph-left { grid-column: 1; justify-self: start; display: inline-flex; align-items: center; gap: 7px; }
 .pane-head .ph-title { grid-column: 2; min-width: 0; max-width: 100%; display: inline-flex; align-items: center; justify-content: center; gap: 5px; font-family: var(--font-mono); font-weight: 600; white-space: nowrap; overflow: hidden; cursor: text; }
 /* `[Group] name` is one title in two parts, and the group is the only part that
@@ -671,6 +675,12 @@ body {
 .pane-head .ph-path { min-width: 0; max-width: min(24vw, 220px); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--muted); font-family: var(--font-mono); font-size: 10.5px; font-weight: 500; }
 .pane-head .ph-title-input { width: 100%; text-align: center; font: inherit; font-family: var(--font-mono); font-weight: 600; padding: 1px 6px; border: 1px solid var(--accent); border-radius: var(--r-sm); background: var(--panel-2); color: var(--text); min-width: 0; }
 .pane-head .ph-close { justify-self: end; }
+/* The way back on a phone, left of the agent's logo. It stretches to the
+   header's own height — cancelling that height's padding rather than adding any
+   — because a taller header would hand straight back the row that dropping the
+   bar above it won (see .mbar). */
+.pane-head .ph-back { align-self: stretch; margin: calc(-1 * var(--ph-pad-y)) 1px calc(-1 * var(--ph-pad-y)) -5px; padding: 0 8px; }
+.pane-head .ph-back svg { width: 15px; height: 15px; }
 @container (max-width: 520px) {
   .pane-head .ph-path { display: none; }
 }
@@ -1240,6 +1250,11 @@ a.btn-ghost { text-decoration: none; }
     width: 1px !important;
     height: 1px !important;
   }
+  /* Reading mode is the switch you reach for most on a phone, and it sat adrift
+     in the middle of the bar: the spacer that pushes the zoom keys right on a
+     wide window was pushing this too. Order it ahead of the spacer instead, so
+     it takes the left edge and zoom keeps the right. */
+  .zoombar .modebar { order: -1; }
   .app.m-home .main { display: none; }
   .app.m-home .sidebar { width: 100%; border-right: none; }
   .app.m-stage .sidebar { display: none; }

web/test/mobileBack.test.mjs

@@ -0,0 +1,62 @@
+// Which mobile surface carries its own way back, and which still needs the bar
+// above it. The rule decides whether a phone spends a row of vertical space on
+// chrome, and the cases that matter are the ones where dropping the bar would
+// leave no way back at all.
+//
+// Same shape as sessionTitle.test.mjs, bundled because the rule shares the
+// passive-CLI list with types.ts rather than restating it. Run with:
+//   node test/mobileBack.test.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const out = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'mback-')), 'mobileBack.mjs');
+await build({
+  entryPoints: [path.join(HERE, '../src/lib/mobileBack.ts')],
+  outfile: out, format: 'esm', bundle: true, logLevel: 'error',
+});
+const { paneOwnsBack } = await import(pathToFileURL(out).href);
+
+let failed = 0;
+const check = (what, fn) => {
+  try { fn(); console.log(`  ok  ${what}`); } catch (e) {
+    failed++;
+    console.log(`  FAIL ${what}\n       ${e.message.split('\n')[0]}`);
+  }
+};
+// A staged agent on a phone, unless a case below says otherwise.
+const staged = { isMobile: true, staged: true, inGroup: false, cli: 'claude' };
+
+console.log('an agent pane carries its own way back');
+check('a staged agent', () => assert.equal(paneOwnsBack(staged), true));
+check('whichever agent it is', () => assert.equal(paneOwnsBack({ ...staged, cli: 'codex' }), true));
+check('a remote agent too — same header, same identity block',
+  () => assert.equal(paneOwnsBack({ ...staged, cli: 'remote' }), true));
+check('a shell', () => assert.equal(paneOwnsBack({ ...staged, cli: 'shell' }), true));
+
+console.log('\nand the bar stays wherever nothing else can hold the arrow');
+check('a group — its bar is also the pager between its agents',
+  () => assert.equal(paneOwnsBack({ ...staged, inGroup: true }), false));
+check('the files pane — its own leftmost button already means "back to the files"',
+  () => assert.equal(paneOwnsBack({ ...staged, cli: 'files' }), false));
+check('the trace pane — a flat header with no identity block',
+  () => assert.equal(paneOwnsBack({ ...staged, cli: 'trace' }), false));
+check('the overview — no pane header at all, so no cli either',
+  () => assert.equal(paneOwnsBack({ ...staged, cli: null }), false));
+check('…and undefined reads the same as null',
+  () => assert.equal(paneOwnsBack({ ...staged, cli: undefined }), false));
+
+console.log('\nand nowhere it would be meaningless');
+check('not on the list itself, where there is nothing to go back from',
+  () => assert.equal(paneOwnsBack({ ...staged, staged: false }), false));
+check('not on desktop, where the sidebar never leaves',
+  () => assert.equal(paneOwnsBack({ ...staged, isMobile: false }), false));
+check('not on a desktop group either',
+  () => assert.equal(paneOwnsBack({ ...staged, isMobile: false, inGroup: true }), false));
+
+console.log(failed ? `\n${failed} failed` : '\nall checks passed');
+process.exit(failed ? 1 : 0);