From 116961f3a82957167419e826e599aba7de2bd892 Mon Sep 17 00:00:00 2001
From: JD <jd@jds.haus>
Date: Wed, 21 Oct 2026 18:23:45 -0400
Subject: [PATCH 1/2] fix(mobile): swipe through sessions in the order the
 strip draws them

nextSession/prevSession walk the canonical sessionOrder, but the case and state tab layouts, a sorted rail and named groups reorder the strip, so with any of them a swipe jumped to tabs that were not next to the current one on screen. The swipe now asks for the drawn order, read with the same walk the strip's arrow keys already use (factored out as _visibleTabRows); Alt+[ / Alt+], Ctrl+Tab and Alt+1..9 keep the canonical order. An active session the list does not draw steps in at the first or last row, and an empty drawn list goes nowhere instead of falling back to a hidden session.
---
 docs/wiki/Mobile-Guide.md            |  5 +-
 src/web/CLAUDE.md                    |  4 +-
 src/web/public/app.js                | 95 ++++++++++++++++++---------
 src/web/public/mobile-handlers.js    |  6 +-
 test/mobile/tabs.test.ts             |  8 +--
 test/session-select-ack-gate.test.ts |  3 +-
 test/session-swipe-gesture.test.ts   | 96 ++++++++++++++++++++++++++++
 7 files changed, 176 insertions(+), 41 deletions(-)

diff --git a/docs/wiki/Mobile-Guide.md b/docs/wiki/Mobile-Guide.md
index a8f47aaf..a6171460 100644
--- a/docs/wiki/Mobile-Guide.md
+++ b/docs/wiki/Mobile-Guide.md
@@ -37,8 +37,9 @@ a bottom sheet rather than a dropdown. On a folding phone (iPhone Duo) dialogs s
 the hinge, and opening or closing the device is treated as the device changing shape, never
 as the keyboard appearing.
 
-**Swipe left and right** on the terminal to switch sessions. A visible text selection pauses
-the swipe, and a terminal wider than the screen pans sideways instead.
+**Swipe left and right** on the terminal to switch sessions, in the order the tabs are shown
+(a grouped or sorted tab layout included). A visible text selection pauses the swipe, and a
+terminal wider than the screen pans sideways instead.
 
 ## The home screen
 
diff --git a/src/web/CLAUDE.md b/src/web/CLAUDE.md
index f2cca22b..1fac309a 100644
--- a/src/web/CLAUDE.md
+++ b/src/web/CLAUDE.md
@@ -36,9 +36,9 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Mobile tab strip scrolling** (issue #257): under 768px the tab strip scrolls horizontally, so the active tab must be kept reachable. `_updateActiveTabImmediate()` reveals it via `computeTabScrollLeft()` (constants.js, rect math on the strip's own `scrollLeft`, never `scrollIntoView()`, which scrolls the document under the fixed header); `_fullRenderSessionTabs()` must restore `scrollLeft` across rebuilds and re-reveal only when the active tab changed (`_lastRenderedActiveTabId`) or, grouped by state, the ACTIVE tab moved to another state band (`_noteActiveTabBand()`, both render paths, scrolling row only; another tab's move never scrolls). ⚠️ The phone-block `min-width` on `.session-tab.active .tab-name` keeps the tab's centre off the gear/close icons, sized for numberless tabs 10+ (floor 40px); do not shrink it. ⚠️ Never reintroduce hoisting the active session to the front of the strip. Tests: `test/mobile-tab-tap-zones.test.ts`, `test/tab-triage.test.ts`. → [architecture-invariants#mobile-tab-strip-scrolling](../../docs/architecture-invariants.md#mobile-tab-strip-scrolling)
 
-**Session list layout: header strip or left sidebar** (`sessionListLayout`, default `header`; per-device via `displayKeys`, also in `SettingsUpdateSchema`): the list can move into a collapsible `<aside>` (Alt+B, `toggleSessionSidebar`) or, via `tabOrientation`, a resizable vertical `#tabRail` (desktop/tablet only). ⚠️ There is ONE `#sessionTabs`, MOVED between hosts, never a second list: `applySessionListLayout()` runs first, then `applyTabOrientation()`, both BEFORE `applyTabWrapSettings()`, and both arm/disarm `_startSidebarRichClock()`. ⚠️ Axis decisions use `_isVerticalTabList()`, never `isSessionSidebarActive()` alone. ⚠️ Rich rows share one gate, `isRichTabRows()`; rich CSS pairs sidebar+rail with comma-grouped selectors, never `:is()`, and card rules stay rail-scoped. ⚠️ Rail sort (`tabRailSort`, default `activity`) is the flex `order` property only, never a DOM reorder; the arrow-key walk alone follows computed `order`. ⚠️ Leaving sidebar mode clears `_sidebarFilter`; the handheld overlay drawer is `inert` when closed, the docked rail never. ⚠️ The rail's **Search sessions** box (`setTabRailSearch`, in memory only) and the sidebar filter share ONE row filter, `_applyTabListFilter()` over the pure `CodemanTabSearch` (constants.js): classes only, never a reorder or layout write; the rail matches the name, the sidebar name + folder. ⚠️ A session row with a tab alert (`tabAlerts`, red or yellow) is never hidden by either box: it goes in as `keep: true`, counts toward its group (which stays on screen) but not toward `matchCount`. ⚠️ Escape in the rail box is claimed by the global capture-phase Escape branch (the box's own `onkeydown` runs after it, too late to stop `closeAllPanels()`), and a filter change that shows or hides anything redraws the connector lines, since a keystroke re-renders nothing; a floating window finds its parent tab only through `_paintedSessionTab()` (a hidden row's rect is all zero but truthy, which drew connectors from the viewport's corner). While it runs `_projectTabGroups()` projects every group open (a collapsed group's rows are not in the DOM) and `toggleTabGroupCollapsed()` refuses, leaving the stored collapse untouched; drag stays on during a search (owner decision), a drop landing between the visible neighbours; `applyTabOrientation()` clears it off the rail. Tests: `test/tab-rail-search.test.ts`, `test/tab-rail-search.browser.test.ts`. → [architecture-invariants#session-list-layout-header-strip-vs-left-sidebar](../../docs/architecture-invariants.md#session-list-layout-header-strip-vs-left-sidebar)
+**Session list layout: header strip or left sidebar** (`sessionListLayout`, default `header`; per-device via `displayKeys`, also in `SettingsUpdateSchema`): the list can move into a collapsible `<aside>` (Alt+B, `toggleSessionSidebar`) or, via `tabOrientation`, a resizable vertical `#tabRail` (desktop/tablet only). ⚠️ There is ONE `#sessionTabs`, MOVED between hosts, never a second list: `applySessionListLayout()` runs first, then `applyTabOrientation()`, both BEFORE `applyTabWrapSettings()`, and both arm/disarm `_startSidebarRichClock()`. ⚠️ Axis decisions use `_isVerticalTabList()`, never `isSessionSidebarActive()` alone. ⚠️ Rich rows share one gate, `isRichTabRows()`; rich CSS pairs sidebar+rail with comma-grouped selectors, never `:is()`, and card rules stay rail-scoped. ⚠️ Rail sort (`tabRailSort`, default `activity`) is the flex `order` property only, never a DOM reorder; the arrow-key walk and the phone swipe follow computed `order`. ⚠️ Leaving sidebar mode clears `_sidebarFilter`; the handheld overlay drawer is `inert` when closed, the docked rail never. ⚠️ The rail's **Search sessions** box (`setTabRailSearch`, in memory only) and the sidebar filter share ONE row filter, `_applyTabListFilter()` over the pure `CodemanTabSearch` (constants.js): classes only, never a reorder or layout write; the rail matches the name, the sidebar name + folder. ⚠️ A session row with a tab alert (`tabAlerts`, red or yellow) is never hidden by either box: it goes in as `keep: true`, counts toward its group (which stays on screen) but not toward `matchCount`. ⚠️ Escape in the rail box is claimed by the global capture-phase Escape branch (the box's own `onkeydown` runs after it, too late to stop `closeAllPanels()`), and a filter change that shows or hides anything redraws the connector lines, since a keystroke re-renders nothing; a floating window finds its parent tab only through `_paintedSessionTab()` (a hidden row's rect is all zero but truthy, which drew connectors from the viewport's corner). While it runs `_projectTabGroups()` projects every group open (a collapsed group's rows are not in the DOM) and `toggleTabGroupCollapsed()` refuses, leaving the stored collapse untouched; drag stays on during a search (owner decision), a drop landing between the visible neighbours; `applyTabOrientation()` clears it off the rail. Tests: `test/tab-rail-search.test.ts`, `test/tab-rail-search.browser.test.ts`. → [architecture-invariants#session-list-layout-header-strip-vs-left-sidebar](../../docs/architecture-invariants.md#session-list-layout-header-strip-vs-left-sidebar)
 
-**Tab layouts** (`tabArrangement`, per-device, default `classic`; `state`/`case`/`ledger` are opt-in; Discussion #426): `state` (option C) splits the list into needs you / waiting / working / idle (idle is `quiet`: its heading stays as the row's anchor but draws no label; `tabStateOrder: 'urgent-last'` flips the order, needs you at the bottom): rows in the desktop header strip with left-aligned labels in a measured column (the brand sits over the strip's corner, so the rows after the first start under "Codeman"), sections in the flat rail and the sidebar, inline dividers on the tablet strip, group order with no headings on phones. `case` (option A) wraps each case's tabs in one `.tab-cluster` box and hides the `-<case>` of a generated name (`.tab-name-case`). `ledger` (option B) is a CSS-only grid on the desktop header strip. `classic` is the old strip. Pure cores: `CodemanTabTriage` and `CodemanTabClusters` (constants.js). ⚠️ `state` is the flex `order` property plus `aria-hidden` heading/break elements reconciled in place by `_syncTabTriageChrome()` after BOTH render paths, never a DOM reorder (a state change is an incremental pass). ⚠️ `case` boxes ARE a DOM grouping, so the incremental path rebuilds whenever `_tabClusterLayout().key` changes; membership follows `_mobileOverviewCaseFor()` like the home screens. ⚠️ Drag only reorders within a group or box (`_isTabDropAcrossGroups()`). ⚠️ Named groups in the vertical rail win over both groupings. ⚠️ `classic` must leave no trace (no headings, no inline order, no boxes, no name split), and the ledger must not change the markup. Tests: `test/tab-triage.test.ts`, `test/tab-clusters.test.ts`. → [architecture-invariants#tab-layouts-by-state-by-case-ledger](../../docs/architecture-invariants.md#tab-layouts-by-state-by-case-ledger)
+**Tab layouts** (`tabArrangement`, per-device, default `classic`; `state`/`case`/`ledger` are opt-in; Discussion #426): `state` (option C) splits the list into needs you / waiting / working / idle (idle is `quiet`: its heading stays as the row's anchor but draws no label; `tabStateOrder: 'urgent-last'` flips the order, needs you at the bottom): rows in the desktop header strip with left-aligned labels in a measured column (the brand sits over the strip's corner, so the rows after the first start under "Codeman"), sections in the flat rail and the sidebar, inline dividers on the tablet strip, group order with no headings on phones. `case` (option A) wraps each case's tabs in one `.tab-cluster` box and hides the `-<case>` of a generated name (`.tab-name-case`). `ledger` (option B) is a CSS-only grid on the desktop header strip. `classic` is the old strip. Pure cores: `CodemanTabTriage` and `CodemanTabClusters` (constants.js). ⚠️ `state` is the flex `order` property plus `aria-hidden` heading/break elements reconciled in place by `_syncTabTriageChrome()` after BOTH render paths, never a DOM reorder (a state change is an incremental pass). ⚠️ `case` boxes ARE a DOM grouping, so the incremental path rebuilds whenever `_tabClusterLayout().key` changes; membership follows `_mobileOverviewCaseFor()` like the home screens. ⚠️ Drag only reorders within a group or box (`_isTabDropAcrossGroups()`). ⚠️ Named groups in the vertical rail win over both groupings. ⚠️ `classic` must leave no trace (no headings, no inline order, no boxes, no name split), and the ledger must not change the markup. ⚠️ Grouping is a render layer: `sessionOrder`, Alt+[ / Alt+], Ctrl+Tab and Alt+1..9 keep the canonical order, and only the phone swipe walks the drawn order (`nextSession({ visual: true })` through `_stripSessionOrder()`, the same `_visibleTabRows()` walk the strip's arrow keys use); an active session the list does not draw steps in at the first or last row, and an empty drawn list goes nowhere rather than falling back to a hidden session (`test/session-swipe-gesture.test.ts`). Tests: `test/tab-triage.test.ts`, `test/tab-clusters.test.ts`. → [architecture-invariants#tab-layouts-by-state-by-case-ledger](../../docs/architecture-invariants.md#tab-layouts-by-state-by-case-ledger)
 
 **Header stats styles** (`headerStatsStyle`, per-device, desktop only, default `compact`; Discussion #426 option G): `tiles` / `compact` (two pills, a ring beside every value) / `classic` (as before), keyed on `data-header-stats` (pre-paint + `applyHeaderStatsStyle()`), forced to `classic` below 768px and in a solo window. ⚠️ The clustered styles MOVE `#connectionIndicator` into `#headerSystemStats` and `#planUsageChip` right after it; `classic` moves them back to comment anchors. ⚠️ WS joins the pill only while System Stats is shown. ⚠️ The extra parts (stat rings, tile words, plan rings, meters) are always rendered and hidden by default in CSS, which is what keeps `classic` unchanged; tile words are derived beside the connection descriptor, never added to it (`test/connection-indicator.test.ts` pins its shape). ⚠️ A tile is a three-row grid (label, value, bar) with pixel line-heights and the bundled JetBrains Mono; never lay the bar over a fixed-height tile (a taller system mono put the value on top of it). The WS tile's grid lives on the inner `.connection-tile`, because JS writes the indicator's `display` inline. Tests: `test/header-stats-style.test.ts`. → [architecture-invariants#header-stats-styles](../../docs/architecture-invariants.md#header-stats-styles)
 
diff --git a/src/web/public/app.js b/src/web/public/app.js
index 03383854..c5703cd1 100644
--- a/src/web/public/app.js
+++ b/src/web/public/app.js
@@ -7245,24 +7245,7 @@ class CodemanApp {
       // the axis a user reaches for there.
       if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'Enter', ' '].includes(e.key)) return;
 
-      // Rows hidden by the sidebar filter must not be steppable.
-      const tabs = [...container.querySelectorAll('.session-tab:not(.tab-filtered-out)')];
-      // ⚠️ A sorted rail paints its rows with the flex `order` property while the
-      // DOM stays in `sessionOrder` (that is what keeps the Alt+N badge and the
-      // drag model honest), so a DOM-order walk steps around the screen instead of
-      // down it: ArrowDown from the top card lands wherever that session happens to
-      // sit in the tab order. Walk what the eye sees. Read the COMPUTED order, not
-      // the inline one, or web tabs (pinned past the cards by a CSS `order: 9999`
-      // rather than an inline style) read as 0 and the walk starts on them. Array
-      // sort is stable, so equal orders keep DOM order, which is the unsorted case.
-      if (this.isTabRailSorted() || container.classList.contains('tabs-triage')) {
-        const orderOf = (el) => Number(getComputedStyle(el).order) || 0;
-        // Case clusters are boxes in DOM order and a sorted rail orders rows
-        // INSIDE each one, so the box goes first in the key.
-        const boxes = [...container.querySelectorAll(':scope > .tab-cluster')];
-        const boxOf = (el) => boxes.indexOf(el.closest('.tab-cluster'));
-        tabs.sort((a, b) => boxOf(a) - boxOf(b) || orderOf(a) - orderOf(b));
-      }
+      const tabs = this._visibleTabRows(container);
       const currentIndex = tabs.indexOf(document.activeElement);
 
       // Enter or Space activates the tab
@@ -7312,6 +7295,52 @@ class CodemanApp {
     }
   }
 
+  /**
+   * The strip's rows (session and web tabs) in the order the eye reads them,
+   * for any layout except the grouped tree (see _tabTreeItems).
+   */
+  _visibleTabRows(container) {
+    // Rows hidden by the sidebar filter must not be steppable.
+    const tabs = [...container.querySelectorAll('.session-tab:not(.tab-filtered-out)')];
+    // ⚠️ A sorted rail paints its rows with the flex `order` property while the
+    // DOM stays in `sessionOrder` (that is what keeps the Alt+N badge and the
+    // drag model honest), so a DOM-order walk steps around the screen instead of
+    // down it: ArrowDown from the top card lands wherever that session happens to
+    // sit in the tab order. Walk what the eye sees. Read the COMPUTED order, not
+    // the inline one, or web tabs (pinned past the cards by a CSS `order: 9999`
+    // rather than an inline style) read as 0 and the walk starts on them. Array
+    // sort is stable, so equal orders keep DOM order, which is the unsorted case.
+    if (this.isTabRailSorted() || container.classList.contains('tabs-triage')) {
+      const orderOf = (el) => Number(getComputedStyle(el).order) || 0;
+      // Case clusters are boxes in DOM order and a sorted rail orders rows
+      // INSIDE each one, so the box goes first in the key.
+      const boxes = [...container.querySelectorAll(':scope > .tab-cluster')];
+      const boxOf = (el) => boxes.indexOf(el.closest('.tab-cluster'));
+      tabs.sort((a, b) => boxOf(a) - boxOf(b) || orderOf(a) - orderOf(b));
+    }
+    return tabs;
+  }
+
+  /**
+   * Session ids in the order the session list DRAWS them: case boxes, state
+   * groups, a sorted rail and named groups all reorder the screen while
+   * `sessionOrder` stays canonical. Only the phone swipe walks this order
+   * (`nextSession({ visual: true })`); Alt+[ / Alt+], Ctrl+Tab and Alt+1..9 keep
+   * the canonical one, since grouping is a render layer. Web tabs are skipped.
+   */
+  _stripSessionOrder() {
+    const container = document.getElementById('sessionTabs');
+    if (!container) return this.sessionOrder;
+    const rows =
+      container.getAttribute('role') === 'tree'
+        ? this._tabTreeItems(container).filter((el) => el.classList.contains('session-tab'))
+        : this._visibleTabRows(container);
+    // An empty list is a real answer (every row filtered out, a tree collapsed
+    // to nothing): the swipe then goes nowhere, like the strip. Only a missing
+    // strip falls back to the canonical order.
+    return rows.map((row) => row.dataset.id).filter((id) => id && this.sessions.has(id));
+  }
+
   /** Select a session row or open a web-tab row (Enter/Space, either layout). */
   _activateTabRow(row) {
     if (row?.dataset.webviewId) return this.openWebview(row.dataset.webviewId);
@@ -10612,23 +10641,29 @@ class CodemanApp {
     }
   }
 
-  nextSession() {
+  /** `{ visual: true }` walks the order the strip draws (the phone swipe), see _stripSessionOrder. */
+  nextSession(options = {}) {
     // With the tile grid open, Ctrl+Tab and Alt+[ / Alt+] cycle through the tiles.
     if (this._cycleTileFocus?.(1)) return;
-    if (this.sessionOrder.length <= 1) return;
-
-    const currentIndex = this.sessionOrder.indexOf(this.activeSessionId);
-    const nextIndex = (currentIndex + 1) % this.sessionOrder.length;
-    this.selectSession(this.sessionOrder[nextIndex]);
+    const order = options.visual ? this._stripSessionOrder() : this.sessionOrder;
+    // An active session the list does not show (filtered out, or none active on
+    // the home screen) steps in at the first row; a lone row that is not the
+    // active one is still a destination.
+    const currentIndex = order.indexOf(this.activeSessionId);
+    const nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % order.length;
+    if (!order[nextIndex] || order[nextIndex] === this.activeSessionId) return;
+    this.selectSession(order[nextIndex]);
   }
 
-  prevSession() {
+  prevSession(options = {}) {
     if (this._cycleTileFocus?.(-1)) return;
-    if (this.sessionOrder.length <= 1) return;
-
-    const currentIndex = this.sessionOrder.indexOf(this.activeSessionId);
-    const prevIndex = (currentIndex - 1 + this.sessionOrder.length) % this.sessionOrder.length;
-    this.selectSession(this.sessionOrder[prevIndex]);
+    const order = options.visual ? this._stripSessionOrder() : this.sessionOrder;
+    // As above, from the other end: a hidden or absent active session steps in
+    // at the last row (the old arithmetic landed on the second to last).
+    const currentIndex = order.indexOf(this.activeSessionId);
+    const prevIndex = currentIndex < 0 ? order.length - 1 : (currentIndex - 1 + order.length) % order.length;
+    if (!order[prevIndex] || order[prevIndex] === this.activeSessionId) return;
+    this.selectSession(order[prevIndex]);
   }
 
   // ═══════════════════════════════════════════════════════════════
diff --git a/src/web/public/mobile-handlers.js b/src/web/public/mobile-handlers.js
index 3c3ba549..f63b848c 100644
--- a/src/web/public/mobile-handlers.js
+++ b/src/web/public/mobile-handlers.js
@@ -862,7 +862,9 @@ const SwipeHandler = {
     if (Math.abs(deltaX) < this.minSwipeDistance) return; // Too short
 
     // Valid swipe detected. Swipe right -> previous session, left -> next.
-    if (deltaX > 0) app.prevSession();
-    else app.nextSession();
+    // In the order the strip draws, which a grouped layout ('case', 'state', a
+    // sorted rail) makes differ from the canonical session order.
+    if (deltaX > 0) app.prevSession({ visual: true });
+    else app.nextSession({ visual: true });
   },
 };
diff --git a/test/mobile/tabs.test.ts b/test/mobile/tabs.test.ts
index d9335f2b..a751509b 100644
--- a/test/mobile/tabs.test.ts
+++ b/test/mobile/tabs.test.ts
@@ -373,11 +373,11 @@ describe('Tab Navigation', () => {
           var origPrev = app.prevSession;
           app.nextSession = function() {
             window.__swipeLog.push('next');
-            if (origNext) origNext.call(app);
+            if (origNext) origNext.apply(app, arguments);
           };
           app.prevSession = function() {
             window.__swipeLog.push('prev');
-            if (origPrev) origPrev.call(app);
+            if (origPrev) origPrev.apply(app, arguments);
           };
         }
       `);
@@ -482,7 +482,7 @@ describe('Tab Navigation', () => {
             var origNext = app.nextSession;
             app.nextSession = function() {
               window.__swipeLog.push('next');
-              if (origNext) origNext.call(app);
+              if (origNext) origNext.apply(app, arguments);
             };
           }
         `);
@@ -520,7 +520,7 @@ describe('Tab Navigation', () => {
             var origPrev = app.prevSession;
             app.prevSession = function() {
               window.__swipeLog.push('prev');
-              if (origPrev) origPrev.call(app);
+              if (origPrev) origPrev.apply(app, arguments);
             };
           }
         `);
diff --git a/test/session-select-ack-gate.test.ts b/test/session-select-ack-gate.test.ts
index cc3a73af..67163ea9 100644
--- a/test/session-select-ack-gate.test.ts
+++ b/test/session-select-ack-gate.test.ts
@@ -182,7 +182,8 @@ describe('selectSession acknowledgement gate', () => {
       // Alt+1..9 and Alt+[/] are a human asking for that tab, so they keep
       // acknowledging; only app-chosen selections are tagged.
       expect(APP_SOURCE).toContain('this.selectSession(live[idx]);');
-      expect(APP_SOURCE).toContain('this.selectSession(this.sessionOrder[nextIndex]);');
+      // Swipes walk the drawn order (`order` is sessionOrder or the strip's), same call.
+      expect(APP_SOURCE).toContain('this.selectSession(order[nextIndex]);');
     });
   });
 });
diff --git a/test/session-swipe-gesture.test.ts b/test/session-swipe-gesture.test.ts
index 91d9757a..3e7086e9 100644
--- a/test/session-swipe-gesture.test.ts
+++ b/test/session-swipe-gesture.test.ts
@@ -165,3 +165,99 @@ describe('terminal touch handler hands sideways drags to the swipe', () => {
     expect(load().swipe.maxVerticalDrift).toBe(50);
   });
 });
+
+describe('the swipe walks the order the strip draws', () => {
+  type Proto = Record<string, (this: Record<string, unknown>, ...args: unknown[]) => unknown>;
+  function loadAppProto() {
+    const document = {
+      addEventListener: vi.fn(),
+      documentElement: { dataset: {} },
+      getElementById: (_id: string): unknown => null,
+    };
+    const context = vm.createContext({
+      console,
+      setInterval: vi.fn(),
+      clearInterval: vi.fn(),
+      setTimeout,
+      clearTimeout,
+      requestAnimationFrame: vi.fn(),
+      HTMLCanvasElement: class HTMLCanvasElement {},
+      WebSocket: { OPEN: 1 },
+      fetch: vi.fn(),
+      URLSearchParams,
+      document,
+      localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() },
+      window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+      MobileDetection: { isTouchDevice: () => true, isHandheldDevice: () => true, getDeviceType: () => 'mobile' },
+    });
+    const read = (f: string) => readFileSync(resolve(import.meta.dirname, '../src/web/public', f), 'utf8');
+    vm.runInContext(`${read('constants.js')}\n${read('app.js')}\nglobalThis.__App = CodemanApp;`, context);
+    return { proto: (context as unknown as { __App: { prototype: Proto } }).__App.prototype, document };
+  }
+
+  /** The real next/prev over a strip drawn as `rows` (ids; 'web' is a web tab) with `active` selected. */
+  function walk(rows: string[], active: string | null) {
+    const { proto, document } = loadAppProto();
+    const row = (id: string) =>
+      id === 'web' ? { dataset: { webviewId: 'web' } } : { dataset: { id }, classList: { contains: () => false } };
+    const strip = {
+      getAttribute: () => 'tablist',
+      classList: { contains: () => false },
+      querySelectorAll: () => rows.map(row),
+    };
+    const selected: string[] = [];
+    const app: Record<string, unknown> = {
+      sessionOrder: ['w1', 'w2', 'homelab', 'w3'],
+      sessions: new Map(['w1', 'w2', 'homelab', 'w3'].map((id) => [id, {}])),
+      activeSessionId: active,
+      isTabRailSorted: () => false,
+      selectSession: (id: string) => selected.push(id),
+    };
+    for (const name of ['_visibleTabRows', '_stripSessionOrder', 'nextSession', 'prevSession']) app[name] = proto[name];
+    document.getElementById = () => strip;
+    const next = (o?: unknown) => (app.nextSession as (o?: unknown) => void).call(app, o);
+    const prev = (o?: unknown) => (app.prevSession as (o?: unknown) => void).call(app, o);
+    return { selected, next, prev };
+  }
+
+  it('follows the case boxes, not the creation order', () => {
+    // Created w1, w2, homelab, w3; the 'case' layout boxes md-viewer's tabs together.
+    const { selected, next, prev } = walk(['w1', 'w2', 'w3', 'web', 'homelab'], 'w3');
+    next({ visual: true });
+    prev({ visual: true });
+    next();
+    // Visual: w3 -> homelab (next), w3 -> w2 (prev). Canonical (no option) keeps sessionOrder: w3 -> w1.
+    expect(selected).toEqual(['homelab', 'w2', 'w1']);
+  });
+
+  it('steps in at the first or last drawn row when the active session is not drawn', () => {
+    // A filter hid the active tab (or nothing is active on the home screen).
+    const { selected, next, prev } = walk(['w1', 'w2', 'homelab'], 'w3');
+    next({ visual: true });
+    prev({ visual: true });
+    expect(selected).toEqual(['w1', 'homelab']);
+  });
+
+  it('reaches a lone drawn row that is not the active one, and goes nowhere from a lone active one', () => {
+    const lone = walk(['w2'], 'w3');
+    lone.next({ visual: true });
+    expect(lone.selected).toEqual(['w2']);
+    const self = walk(['w3'], 'w3');
+    self.next({ visual: true });
+    self.prev({ visual: true });
+    expect(self.selected).toEqual([]);
+  });
+
+  it('goes nowhere when every row is filtered out, instead of falling back to a hidden session', () => {
+    const { selected, next, prev } = walk([], 'w3');
+    next({ visual: true });
+    prev({ visual: true });
+    expect(selected).toEqual([]);
+  });
+
+  it('the swipe asks for the visual order', () => {
+    const { app, gesture } = load();
+    gesture({ clientX: 300, clientY: 400 }, { clientX: 150, clientY: 400 });
+    expect(app.nextSession).toHaveBeenCalledWith({ visual: true });
+  });
+});

From 4da6aee660434fc7a1fa54804ce3ebd3e341587d Mon Sep 17 00:00:00 2001
From: Codeman maintainer <noreply@anthropic.com>
Date: Sat, 24 Oct 2026 14:05:05 +0200
Subject: [PATCH 2/2] fix: apply the review items for #682 at merge

docs: architecture-invariants (arrow-key walk section) names the phone swipe beside the arrow keys as following the drawn order
docs: root CLAUDE.md (Owner tab layouts) carves the phone swipe out of "every other order consumer reads sessionOrder"
test: pin the grouped-tree branch of _stripSessionOrder() (sorted rail, header and web tab skipped, groups not interleaved)
test: the step-in case uses a drawn order (homelab, w1, w2) that master's canonical walk and the old arithmetic cannot satisfy

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                          |  2 +-
 docs/architecture-invariants.md    |  2 +-
 test/session-swipe-gesture.test.ts | 73 +++++++++++++++++++++++++-----
 3 files changed, 63 insertions(+), 14 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 02704d0f..ac38722e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -193,7 +193,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history and transcript files into one deduped list (pure core `src/services/unified-session-service.ts`), backing the Cmd+K Session Manager, pinning and cross-device tab order (`PUT /api/session-order`, `src/session-order.ts`). ⚠️ Transcript history is THREE stores (`~/.claude/projects`, `~/.omp/agent/sessions`, `~/.codex/sessions`), folded via the `claudeSessionId → Codeman id` alias map (not Claude-only despite the name). ⚠️ `resumeId` is set by a SCANNER row only, never a live session; every surface that re-projects these rows (phone overview included) must carry it through, or a tap silently starts a second conversation. → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
 
-**Owner tab layouts** (`tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat strip, scoped per owner (`@single` when multi-user is off), persisted as `tabLayouts` in state.json. The frontend reads AND edits it (`tab-layout-browser.js` + the grouped-rail block in app.js): the vertical rail draws the owner's groups as collapsible sections (collapse is per-device localStorage), and with no groups or a failed read the rail is the flat list. Groups are created, renamed, reordered and deleted, and rows moved between them, from the row/group menus (Shift+F10 on a header too) and by pointer drag in the grouped rail. A ref may carry `focus: true` ("Add to Focus" in the row/web-tab menu, the named `setFocus` operation): the rail then draws a SHORTCUT to it in a pinned, collapsible Focus section (`_renderTabFocus()`), its own element in `#tabRail` ABOVE `#sessionTabs`, so it shows on the flat rail too and is never a row, tree item, Alt+N slot, lineage anchor or drag target. ⚠️ Every copy of a ref (`copyRef` in tab-layout-browser.js, `parseRef`/`mapRef` in tab-layout.ts) must carry `focus` like `placement`: the browser PUTs whole layouts, so a dropped field is erased on the next save by whoever saves. ⚠️ Grouping is a render layer only: `sessionOrder`, Alt+N and every other order consumer still read the server-projected session order, and a grouped row's markup is the flat row's markup. ⚠️ Only the GROUPED rail is an ARIA tree (`role=tree`, headers owning `role=group`s, one roving `tabindex=0`); the strip, sidebar and flat rail stay `tablist`/`tab`. ⚠️ Every browser write is a named operation through ONE serialized `PUT /api/tab-layout` at a time (`createEditCoordinator`): a 409 replays the operations onto the server's layout and retries (bounded), and an SSE reload is deferred while a write is in flight. Never PUT the layout from anywhere else in the frontend (the `pagehide` keepalive in `_persistPendingTabLayoutEdits` is the one deliberate exception). ⚠️ Placing a NEW session in a group rides its create request (`tabGroupId` on `POST /api/sessions` / `/api/quick-start`) into `TabLayoutService.sessionCreated()`, which registers the session inside the owner lock and places it in the same write; never place a created session with a follow-up PUT. A spawned child lands after its parent; whether it keeps FOLLOWING it until moved by hand is the synced `spawnedTabsFollowParent` setting (default OFF: pinned `manual` in the creating write), read fresh in `sessionCreated()`. A case's **default session group** (Case settings; `caseDefaultGroups` in state.json, per owner and case) is the fallback placement in that same write, below `tabGroupId` and the parent, from the create request's `caseName` (quick-start, Ralph start, or inferred lexically from a `POST /api/sessions` `workingDir`); it is read and written ONLY through `TabLayoutService`. ⚠️ A legacy order PUT marks a child `manual` ONLY when the requested order splits it from its parent's block (`applyLegacySessionRank`), and the browser never echoes create/delete through `PUT /api/session-order`: the server already re-projected and broadcast it. Web-tab OPENNESS stays per device. ⚠️ `TabLayoutService` is the single mutation boundary (one completed server action = at most one versioned write); never write layout state from a route or manager directly. ⚠️ The layout PROJECTS onto `PUT /api/session-order` via `tab-layout-legacy-order.ts`; change both sides together. ⚠️ Reconciliation is gated on a SUCCESSFUL restore (`markRestorationComplete`/`assertDeletionReady()`): a failed restore must leave the layout untouched or live tabs get pruned. → [architecture-invariants#owner-tab-layouts](docs/architecture-invariants.md#owner-tab-layouts)
+**Owner tab layouts** (`tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat strip, scoped per owner (`@single` when multi-user is off), persisted as `tabLayouts` in state.json. The frontend reads AND edits it (`tab-layout-browser.js` + the grouped-rail block in app.js): the vertical rail draws the owner's groups as collapsible sections (collapse is per-device localStorage), and with no groups or a failed read the rail is the flat list. Groups are created, renamed, reordered and deleted, and rows moved between them, from the row/group menus (Shift+F10 on a header too) and by pointer drag in the grouped rail. A ref may carry `focus: true` ("Add to Focus" in the row/web-tab menu, the named `setFocus` operation): the rail then draws a SHORTCUT to it in a pinned, collapsible Focus section (`_renderTabFocus()`), its own element in `#tabRail` ABOVE `#sessionTabs`, so it shows on the flat rail too and is never a row, tree item, Alt+N slot, lineage anchor or drag target. ⚠️ Every copy of a ref (`copyRef` in tab-layout-browser.js, `parseRef`/`mapRef` in tab-layout.ts) must carry `focus` like `placement`: the browser PUTs whole layouts, so a dropped field is erased on the next save by whoever saves. ⚠️ Grouping is a render layer only: `sessionOrder`, Alt+N and every other order consumer still read the server-projected session order (Alt+[ / Alt+] and Ctrl+Tab included), except the phone swipe, which walks the drawn order like the strip's arrow keys (`nextSession({ visual: true })` through `_stripSessionOrder()`), and a grouped row's markup is the flat row's markup. ⚠️ Only the GROUPED rail is an ARIA tree (`role=tree`, headers owning `role=group`s, one roving `tabindex=0`); the strip, sidebar and flat rail stay `tablist`/`tab`. ⚠️ Every browser write is a named operation through ONE serialized `PUT /api/tab-layout` at a time (`createEditCoordinator`): a 409 replays the operations onto the server's layout and retries (bounded), and an SSE reload is deferred while a write is in flight. Never PUT the layout from anywhere else in the frontend (the `pagehide` keepalive in `_persistPendingTabLayoutEdits` is the one deliberate exception). ⚠️ Placing a NEW session in a group rides its create request (`tabGroupId` on `POST /api/sessions` / `/api/quick-start`) into `TabLayoutService.sessionCreated()`, which registers the session inside the owner lock and places it in the same write; never place a created session with a follow-up PUT. A spawned child lands after its parent; whether it keeps FOLLOWING it until moved by hand is the synced `spawnedTabsFollowParent` setting (default OFF: pinned `manual` in the creating write), read fresh in `sessionCreated()`. A case's **default session group** (Case settings; `caseDefaultGroups` in state.json, per owner and case) is the fallback placement in that same write, below `tabGroupId` and the parent, from the create request's `caseName` (quick-start, Ralph start, or inferred lexically from a `POST /api/sessions` `workingDir`); it is read and written ONLY through `TabLayoutService`. ⚠️ A legacy order PUT marks a child `manual` ONLY when the requested order splits it from its parent's block (`applyLegacySessionRank`), and the browser never echoes create/delete through `PUT /api/session-order`: the server already re-projected and broadcast it. Web-tab OPENNESS stays per device. ⚠️ `TabLayoutService` is the single mutation boundary (one completed server action = at most one versioned write); never write layout state from a route or manager directly. ⚠️ The layout PROJECTS onto `PUT /api/session-order` via `tab-layout-legacy-order.ts`; change both sides together. ⚠️ Reconciliation is gated on a SUCCESSFUL restore (`markRestorationComplete`/`assertDeletionReady()`): a failed restore must leave the layout untouched or live tabs get pruned. → [architecture-invariants#owner-tab-layouts](docs/architecture-invariants.md#owner-tab-layouts)
 
 **Hook events**: Claude Code hooks trigger via `/api/hook-event` (`permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`, `prompt_submitted`); see `src/hooks-config.ts` and `docs/claude-code-hooks-reference.md`. ⚠️ Every claude session installs the hooks block into its workspace (add-only merge) from every create path and from `restoreMuxSessions()`, gated by `workspaceHooksEnabled` (SYNCED, default ON). ⚠️ Route that decision through `applyWorkspaceHooks`, never call `ensureCodemanHooks` at a new site, or the setting silently stops applying. ⚠️ An AskUserQuestion / plan-selection dialog arrives as `permission_prompt` (RED alert), not `elicitation_dialog` (MCP elicitation). → [architecture-invariants#hook-events-and-workspace-hook-installation](docs/architecture-invariants.md#hook-events-and-workspace-hook-installation)
 
diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md
index f446f4a1..1f60d4d5 100644
--- a/docs/architecture-invariants.md
+++ b/docs/architecture-invariants.md
@@ -895,7 +895,7 @@ Tests: `test/tab-rail-search.test.ts` (gate) and `test/tab-rail-search.browser.t
 
 ⚠️ **Row ORDER is a third rail attribute** (`tabRailSort: 'activity'|'manual'`, `data-tab-rail-sort`, default **activity**): a sorted rail answers the home screens' question with the home screens' answer, `CodemanSessionOrder` over rows classified by `_mobileOverviewState` (`_tabRailSortOrder` in app.js). ⚠️ **It is applied as the flex `order` property, never by reordering the DOM**: `#sessionTabs` stays in `sessionOrder`, so the Alt+N badge (`_tabIdx`, which therefore does NOT run 1,2,3 down a sorted rail — it names a shortcut, not a position), drag-and-drop, the arrow-key walk, the sidebar filter and `_scrollActiveTabIntoView()` all keep reading the list they always read, and a session changing state moves ONE inline style instead of forcing the full rebuild that would restart every card's animation on every SSE tick. The incremental render path therefore has to re-apply it (a state flip adds no tab, so the full rebuild is never reached) and an empty string is what clears it when sorting stops. ⚠️ Web tabs are pinned past the cards by a CSS `order: 9999` rather than an inline one, since `renderWebviewTabs()` emits the same markup for every layout; the flex default of 0 would interleave them among the sorted sessions. ⚠️ `setupTabDragHandlers()` sets `draggable="false"` and returns while sorting is on: the drop rewrites `sessionOrder` correctly and the sort then puts the card straight back, so the affordance would be a lie — `'manual'` is the way back to drag-reordering.
 
-⚠️ **The arrow-key walk is the one place that must follow the SORT rather than the DOM**: `_tabKeydownHandler` steps `querySelectorAll` order, which is `sessionOrder`, so on a sorted rail ArrowDown from the top card landed wherever that session sat in the tab order instead of on the card below it. It now sorts its node list by the COMPUTED `order` first (computed, not inline: web tabs get their `order: 9999` from CSS and would otherwise read as 0 and lead the walk). This is the exception that proves the DOM-stays-in-sessionOrder rule: the badge, drag model and Alt+N index all deliberately keep reading the DOM, and only the thing the user steps with their eyes follows the paint.
+⚠️ **The arrow-key walk and the phone swipe are the two places that must follow the SORT rather than the DOM**: `_tabKeydownHandler` steps `querySelectorAll` order, which is `sessionOrder`, so on a sorted rail ArrowDown from the top card landed wherever that session sat in the tab order instead of on the card below it. It now sorts its node list by the COMPUTED `order` first (computed, not inline: web tabs get their `order: 9999` from CSS and would otherwise read as 0 and lead the walk). That walk is `_visibleTabRows()`, and the phone swipe shares it: `SwipeHandler` calls `nextSession({ visual: true })` / `prevSession({ visual: true })`, which step through `_stripSessionOrder()` (the grouped tree's session rows via `_tabTreeItems()`, otherwise `_visibleTabRows()`, web tabs skipped), so a swipe lands on the tab drawn next to the current one in the case and state layouts, a sorted rail and named groups; Alt+[ / Alt+], Ctrl+Tab and Alt+1..9 keep `sessionOrder`. An active session the list does not draw steps in at the first row (next) or the last (previous), and an empty drawn list goes nowhere rather than falling back to a hidden session (`test/session-swipe-gesture.test.ts`). This is the exception that proves the DOM-stays-in-sessionOrder rule: the badge, drag model and Alt+N index all deliberately keep reading the DOM, and only the things the user steps with their eyes (the arrow keys and the swipe) follow the paint.
 
 ### Split-pane sessions
 
diff --git a/test/session-swipe-gesture.test.ts b/test/session-swipe-gesture.test.ts
index 3e7086e9..2d4036cc 100644
--- a/test/session-swipe-gesture.test.ts
+++ b/test/session-swipe-gesture.test.ts
@@ -181,6 +181,8 @@ describe('the swipe walks the order the strip draws', () => {
       setTimeout,
       clearTimeout,
       requestAnimationFrame: vi.fn(),
+      // A row stub's `cssOrder` stands in for the flex `order` a sorted rail paints.
+      getComputedStyle: (el: { cssOrder?: number }) => ({ order: String(el.cssOrder ?? 0) }),
       HTMLCanvasElement: class HTMLCanvasElement {},
       WebSocket: { OPEN: 1 },
       fetch: vi.fn(),
@@ -197,23 +199,32 @@ describe('the swipe walks the order the strip draws', () => {
 
   /** The real next/prev over a strip drawn as `rows` (ids; 'web' is a web tab) with `active` selected. */
   function walk(rows: string[], active: string | null) {
-    const { proto, document } = loadAppProto();
     const row = (id: string) =>
       id === 'web' ? { dataset: { webviewId: 'web' } } : { dataset: { id }, classList: { contains: () => false } };
-    const strip = {
-      getAttribute: () => 'tablist',
-      classList: { contains: () => false },
-      querySelectorAll: () => rows.map(row),
-    };
+    return drive(
+      {
+        getAttribute: () => 'tablist',
+        classList: { contains: () => false },
+        querySelectorAll: () => rows.map(row),
+      },
+      active
+    );
+  }
+
+  /** The real next/prev over `strip` (a stub of #sessionTabs) with `active` selected. */
+  function drive(strip: unknown, active: string | null, sorted = false) {
+    const { proto, document } = loadAppProto();
     const selected: string[] = [];
     const app: Record<string, unknown> = {
       sessionOrder: ['w1', 'w2', 'homelab', 'w3'],
       sessions: new Map(['w1', 'w2', 'homelab', 'w3'].map((id) => [id, {}])),
       activeSessionId: active,
-      isTabRailSorted: () => false,
+      isTabRailSorted: () => sorted,
       selectSession: (id: string) => selected.push(id),
     };
-    for (const name of ['_visibleTabRows', '_stripSessionOrder', 'nextSession', 'prevSession']) app[name] = proto[name];
+    for (const name of ['_visibleTabRows', '_tabTreeItems', '_stripSessionOrder', 'nextSession', 'prevSession']) {
+      app[name] = proto[name];
+    }
     document.getElementById = () => strip;
     const next = (o?: unknown) => (app.nextSession as (o?: unknown) => void).call(app, o);
     const prev = (o?: unknown) => (app.prevSession as (o?: unknown) => void).call(app, o);
@@ -230,12 +241,50 @@ describe('the swipe walks the order the strip draws', () => {
     expect(selected).toEqual(['homelab', 'w2', 'w1']);
   });
 
-  it('steps in at the first or last drawn row when the active session is not drawn', () => {
-    // A filter hid the active tab (or nothing is active on the home screen).
-    const { selected, next, prev } = walk(['w1', 'w2', 'homelab'], 'w3');
+  it('walks the grouped tree: group by group, sorted inside each, headers and web tabs skipped', () => {
+    // A rail sorted by activity with a named group "ops" (homelab, a web tab, w3) above
+    // Ungrouped (w1, w2); the DOM keeps sessionOrder inside each group. The tree sorts
+    // INSIDE each group, so it draws w3, homelab, web | w1, w2, where one sort over the
+    // whole list (the flat walk) would interleave the groups as w3, w1, homelab, w2.
+    const tab = (id: string, cssOrder: number) => ({
+      dataset: id === 'web' ? { webviewId: 'web' } : { id },
+      cssOrder,
+      classList: { contains: (c: string) => c === 'session-tab' },
+      closest: () => null,
+    });
+    const header = { dataset: { tabGroupHeader: 'ops' }, classList: { contains: () => false } };
+    const section = (head: unknown, rows: unknown[]) => ({
+      classList: { contains: () => false },
+      querySelector: () => head,
+      querySelectorAll: () => rows,
+    });
+    const ops = [tab('homelab', 2), tab('web', 9999), tab('w3', 0)];
+    // The Ungrouped heading is aria-hidden, not a treeitem, so the section has none.
+    const ungrouped = [tab('w1', 1), tab('w2', 3)];
+    const sections = [section(header, ops), section(null, ungrouped)];
+    const strip = {
+      getAttribute: (name: string) => (name === 'role' ? 'tree' : null),
+      classList: { contains: () => false },
+      querySelectorAll: (sel: string) =>
+        sel === '.tab-layout-group' ? sections : sel.includes('.tab-cluster') ? [] : [...ops, ...ungrouped],
+    };
+    const { selected, next, prev } = drive(strip, 'homelab', true);
     next({ visual: true });
     prev({ visual: true });
-    expect(selected).toEqual(['w1', 'homelab']);
+    // Tree: homelab -> w1 (past the web tab, into the next group), homelab -> w3.
+    // The flat walk would give w2 / w1, the canonical order w3 / w2.
+    expect(selected).toEqual(['w1', 'w3']);
+  });
+
+  it('steps in at the first or last drawn row when the active session is not drawn', () => {
+    // A filter hid the active tab (or nothing is active on the home screen). The drawn
+    // order differs from sessionOrder's ends (w1 ... w3), so the canonical walk from w3
+    // (w1 / homelab) cannot pass for this, and nor can the old arithmetic on the drawn
+    // order, which put previous on the second to last row (w1).
+    const { selected, next, prev } = walk(['homelab', 'w1', 'w2'], 'w3');
+    next({ visual: true });
+    prev({ visual: true });
+    expect(selected).toEqual(['homelab', 'w2']);
   });
 
   it('reaches a lone drawn row that is not the active one, and goes nowhere from a lone active one', () => {