docs: CLI Logos on Tabs in the settings reference and the dashboard page

The Settings Reference gets the new row in the Appearance tab table, the
Dashboard's Session tabs section says what the logo is and where to turn
it off, and the CliEntry.shortBadge comment in docs/cli-registry.md no
longer implies every tab always shows a logo.

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

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "codeman",
       "source": "./plugins/codeman",
       "description": "Drive Codeman from inside a Claude Code session: spawn worker sessions, prompt them, wait for them, read their answers, clean up. Acts only inside a Codeman-managed session.",
-      "version": "1.34.0",
+      "version": "1.40.0",
       "author": {
         "name": "Ark0N",
         "url": "https://github.com/Ark0N"

.github/CONTRIBUTING.md

@@ -55,7 +55,9 @@ npm run test:all       # literally everything, environmental failures included
 
 Expect `test:browser`/`test:mobile`/`test:perf` to fail where the machine cannot provide what they need; read that as "not runnable here", not as a regression. `config/test-suites.ts` holds the globs, and both configs derive from it, so the exclusions and those runners cannot drift apart.
 
-If you add a test that binds a port, pick a unique one at 3150 or above (search the repo for `const PORT =` first). Never 3000.
+The browser suite also runs nightly (and on demand) in `.github/workflows/browser-suite.yml`; it is informational, not a gate.
+
+If you add a test that binds a port, bind port 0 (`new WebServer(0, …)` + `server.boundPort`, or `listen({ port: 0 })` + `address().port`), or use `app.inject()` when no socket is needed; `test/test-ports-guard.test.ts` fails a `WebServer` built on any other port. Mobile tests (`test/mobile/**`, via `createTestServer(PORT)`) keep the fixed-port convention in `test/mobile/README.md` for now, because that helper caches servers by port. Never 3000.
 
 Tests are tmux-safe by design: under vitest, the tmux layer becomes an in-memory mock, so tests cannot touch real sessions.
 

.github/workflows/browser-suite.yml

@@ -0,0 +1,50 @@
+name: Browser suite
+
+# The per-push CI gate deliberately skips the Playwright-driven suite (config/test-suites.ts),
+# so a browser-only regression can merge green. This job runs that suite on a schedule and on
+# demand, so such a regression (the Shift+Enter keypress bug was one) is caught within a day
+# instead of by a user. It is NOT a merge gate: a red run means "look", and it never blocks a
+# push or a PR.
+#
+# Needs: chromium (installed below), tmux, and the live server the tests start themselves.
+# Not run here: test:mobile (per-machine PNG baselines), test:perf (wall-clock), and
+# codex-predictive-echo (needs a real codex binary; it also skips itself without one).
+
+on:
+  schedule:
+    - cron: '29 3 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  browser:
+    name: Playwright browser suite
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install tmux
+        run: |
+          if ! command -v tmux >/dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y tmux
+          fi
+
+      - name: Install chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run the browser suite
+        run: npm run test:browser -- --exclude test/codex-predictive-echo.test.ts

.github/workflows/ci.yml

@@ -219,6 +219,8 @@ jobs:
         run: npx vitest run
         working-directory: packages/xterm-zerolag-input
 
+# The browser suite also runs nightly (and on demand) in .github/workflows/browser-suite.yml;
+# that job is informational and never gates a push or a PR.
 # Note: three suites are excluded from CI, each with its own local runner:
 #   npm run test:browser  Playwright + chromium (+ a live server, and a real
 #                         codex binary for codex-predictive-echo)

.prettierignore

@@ -24,7 +24,6 @@ src/web/public/settings-ui.js
 src/web/public/sw.js
 src/web/public/terminal-ui.js
 src/web/public/voice-input.js
-src/web/public/upload.html
 scripts/remotion/
 
 # Hand-maintained; Prettier escapes underscores in glob paths and corrupts paragraphs.

AGENTS.md

@@ -12,6 +12,6 @@ Quick pointers:
 
 - Type check: `tsc --noEmit` · Lint: `npm run lint` · Format: `npm run format:check`
 - Tests: `npm test` (the CI gate, safe to run bare) or `npm test -- test/<file>.test.ts` for one file
-- Route tests use `app.inject()`; new tests needing ports must pick a unique `const PORT =`
+- Route tests use `app.inject()`; new tests needing a socket bind port 0 (`new WebServer(0, …)` + `boundPort`), except mobile tests, which keep `createTestServer(PORT)` for now
 - Branch off `master` for all work; Conventional Commit-style messages (`fix(mobile): ...`)
 - Never commit secrets or local state from `~/.codeman/`

CHANGELOG.md

@@ -1,5 +1,78 @@
 # aicodeman
 
+## 1.40.0
+
+### Minor Changes
+
+- ### Thanks
+  - @opticon454 for four PRs in this release: the end of Android autocorrect duplicating a line (#541), a Run dropdown that fits and scrolls on any screen (#542), Git status that copes with big folders and slow shares (#543), and a nightly browser-suite workflow plus the three stale browser tests it needed (#540). Thanks also for confirming #550 on a live install.
+  - @JDProfresh, a first-time contributor, for four PRs: Respawn and Ralph back in Claude's Session Options (#550), removing the broken tunnel Upload URL page (#551), the wiki's Contributing page catching up with CONTRIBUTING.md (#552), and a remote-wake test that no longer pins its budget to the millisecond (#559).
+  - @Randalix for making opencode tabs selectable and scrollable again (#555), and for the server reporting the port it really bound, which let the test suite move off fixed ports (#556).
+  - @shenlvkang-collab for Default Codex model and reasoning effort settings (#546), and for the opt-in `window.CodemanHost` bridge that lets a native wrapper app pop a session or a file preview out into a window of its own (#432).
+  - @aakhter for `.xlsx` spreadsheets in the File Viewer (#502), parsed entirely in the browser behind admission limits that held up to round after round of review.
+
+  This is the biggest visual overhaul Codeman has had: a tile grid for driving several sessions at once, a new header, CLI logos everywhere an agent is named, lineage trees, a calmer welcome screen and optional new tab layouts. The defaults are chosen so an upgrade looks familiar: the tab strip stays Classic, the header gets the Compact stats, and the Tiles button is there to try.
+
+  **The tile grid: up to six live sessions side by side.** Click **Tiles** in the header (or press `Ctrl+Shift+G`) and the window splits into a grid of real terminals, each one a full session you can read and type in, with its own connection. Every tile has a small header naming the session, the agent (its logo) and the model it runs (`Claude on Opus 5.5`, `DeepSeek on qwen3.8-27b`, following an in-session `/model` switch), a status dot that turns red and pulses the tile's border when that session needs you, a session menu, zoom (`⤢` or `Alt+Shift+Enter`) and remove (`×`, the session keeps running). Right-click the button for a 2 / 4 / 6 count menu (remembered per device; a hover card explains both clicks). Add sessions by `Ctrl`/`Cmd`+clicking a tab, dragging a tab onto a tile or an empty cell, "Open group as tiles" in a tab group's menu, or just Run while the grid is open. Rearrange by dragging a tile by its header (onto another tile they swap, and an empty cell can sit anywhere), with `Ctrl+Shift+Arrows`, and resize with the column and row dividers; `Alt+Shift+Arrows`, `Ctrl+Tab` and `Alt+[` / `]` move the focus, and the focused tile is the session every panel follows (files, git status, respawn, subagent windows, voice, image paste). Picking a tab that is not tiled shows it on its own and one click brings the grid back; app-driven selections never collapse it. The grid survives a reload (per device, session ids only), opens and closes with a short animation (off under reduced motion), auto-zooms the focused tile when the window gets too small, shows an Attach overlay for a session that is not attached or whose agent exited, and is fully translated into 简体中文. It was built to stay fast with six busy agents: tiles paint first and load their terminals one per frame, a tile replays its history at xterm's own pace and never reads more scrollback than it keeps, the main terminal is parked (no SSE terminal stream) while tiles own the screen, and a window resize refits each tile exactly once. Desktop only (a window at least 1180px wide); the setting is App Settings → Header & Panels → Tiles, on by default on desktop and opt-in on touch tablets. The user guide is the new [Tile Grid](https://github.com/Ark0N/Codeman/wiki/Tile-Grid) wiki page.
+
+  **Split view, rebuilt on the same terminal (#560).** The split's second pane is now a `TerminalTile`, the same component every tile is: its input goes through the exactly-once queue, so a dropped link can no longer lose or double a keystroke; it reconnects on its own after a drop or a server restart; it and its PTY never disagree about size; file paths are clickable and `Ctrl+V` pastes images into it; and app shortcuts, voice and image paste follow the pane you are in. Both panes now name their agent and model above them.
+
+  **A new header.** The header stats come in three styles (App Settings → Header & Panels → Header Stats Style, per device): **Compact**, the new default, draws WS, CPU, MEM and the plan usage windows as two pills where every reading is a ring, a label and a value; **Tiles** gives each one its own box; **As before** keeps the old readout. The icon buttons beside them take the matching shape, and hover now moves the icon, never the button.
+
+  **CLI logos everywhere an agent is named (#532).** The Run menus (toolbar, phone overview picker, custom endpoints, model picker), every agent tab (header strip, rail, sidebar, phone chips, the desktop home rail, Claude's tabs included), the tile and split headers and the welcome screen now show each CLI's own logo instead of a colour dot or a two-letter pill. The marks are inline SVG, follow every skin, and a CLI you added through `clis.json` gets a plain dot.
+
+  **Lineage trees (#544).** The lines from a tab to the tabs it spawned are now one rounded tree per spawning tab, routed through the gaps between tab rows so they never cross a tab or reach the terminal. Every family is always drawn, the selected tab's family is drawn thicker and on top, and a dashed branch now means that child is working.
+
+  **Tab layouts (#538, optional).** App Settings → Appearance → Tabs → **Tab Layout** adds three opt-in arrangements next to the default **Classic** strip: **By state** (a row each for Needs you, Waiting, Working and the rest, most urgent first, flippable with State Order), **By case** (one labelled box per case) and **Ledger** (an aligned grid of equal cells). By state and By case also group the vertical rail and the sidebar. Per device; phones keep their scrolling chip row.
+
+  **A calmer welcome screen.** One primary launcher for the first agent in your catalog (Claude Code on a stock install, the next agent if it is disabled) with its real logo, every other CLI as a slim pill under it, and Cloudflare Tunnel as a quiet link above its QR. The toolbar's "+" and case gear moved into the case picker as "New or link a case…" and "Case settings…" rows, and the duplicate instance stepper is gone (#428).
+
+  **Every session knows its model.** Sessions publish the model they run (`displayModel` on the session state): a custom endpoint's model id, else what the running CLI itself reports (Claude's statusLine, codex's, pi's and opencode's footers, the dsh status line), else the model its config pins (a DeepSeek route) or the one it was launched with. It is persisted, follows `/model` switches, and is stripped of control characters and capped.
+
+  **Idle detection for every agent.** OpenCode, Gemini, Pi and OMP turns now end: their composer bars and spinners are read so a session goes idle when the agent is done instead of spinning "working" forever, codex 0.162's new footer row no longer hides its model or its background-terminal row, and a freshly started or re-attached agent pane now announces its idle to open pages (it used to stay `busy` until a reload). A pane prompted within its first seconds is never settled idle at launch, so send-and-wait cannot resolve before the turn starts.
+
+  **Spreadsheets in the File Viewer (#502).** `.xlsx` files open as a read-only grid with sheet tabs, number formats, merged cells and colours, from the Files panel, attachments or a path an agent prints. They are parsed entirely in your browser in a worker (up to 10 MB) behind admission limits on everything the parser would expand. `.xls` and `.ods` stay download-only, and `file-content` now reports `type: 'spreadsheet'` for `.xlsx`.
+
+  **Default Codex model and reasoning effort (#546).** App Settings has a Default Codex model and a Default Codex reasoning effort, applied to new local Codex sessions (Run menu, Resume and the HTTP API) unless the launch names its own; custom endpoints, Docker and remote sessions keep their own settings.
+
+  **Pop-out windows for native wrapper apps (#432).** A native wrapper (for example an Android app on a foldable) can pop a session, a file preview or a web tab out into a window of its own beside the dashboard through an opt-in, experimental `window.CodemanHost` bridge. Browsers behave exactly as before.
+
+  **Git status for big folders and slow shares (#543).** Two per-device settings under Settings → Bottom bar set how many repositories it lists (up to 50, default 12) and how long one git command may take (5 to 120 s, now 30 s by default), and a repository git cannot read is listed with the reason and counted as `? N` in the indicator instead of silently disappearing.
+
+  **Behaviour change: `Ctrl+W` no longer closes a session.** It is delete-word in every shell and agent CLI, and muscle memory used to kill a session (its pane and CLI, with no confirm) mid-sentence. Close Session has no default key now; bind one in App Settings → Shortcuts if you want it.
+
+  **Removed: the tunnel Upload URL page (#551).** Since the response envelope change it reported "Saved: undefined" and listed nothing. Use the in-app image paste instead. `POST /api/screenshots`, `GET /api/screenshots` and `GET /api/screenshots/:name` (and their `/api/v1` aliases) still work unchanged but log a one-time deprecation warning and will be removed in a future major release.
+
+  **Fixes.** Android keyboards that autocorrect as you type (SwiftKey, Gboard) no longer duplicate the line in the prompt: the corrected word reaches the session exactly once, including when Enter arrives in the same keyboard transaction (#541). opencode tabs: a drag selects text again (so copy-on-select works and `Ctrl+C` copies instead of closing opencode), and the wheel and touch swipes page through opencode's conversation (#555). The Run dropdown no longer runs off the top of the screen: with many CLIs, endpoints and saved URLs it fits between the header and the toolbar, follows the on-screen keyboard and the iPhone safe areas, and scrolls (#542). Claude sessions show the Respawn and Ralph / Todo tabs and the auto-resume toggle in Session Options again, hidden since 1.33.0 (#550, fixes #549). The terminal refits when only its box changes size (a header that grows with the state rows or the lineage gutter used to leave the bottom rows clipped behind the toolbar until a tab switch). A device with any shortcut override no longer gets every App Settings save rejected while the toast still said "Settings saved". Image paste and dictation land in the session they started in. App Settings search finds Split and Tiles by what they do. The Run button family, the Help modal, the shortcut overlay leftovers and the exited-agent tab badge are translated into Chinese.
+
+  **For contributors.** The server reports the port it actually bound (`boundPort`), the tests that shared fixed ports bind ephemeral ones, and a static guard keeps new fixed ports out, so two test runs on one machine no longer collide (#556). A nightly (and on-demand) Playwright browser-suite workflow runs the suites the CI gate cannot, informational and never a gate (#540). The wiki's Contributing page says `npm test` is the CI gate (#552).
+
+  **A final review before shipping.** A last adversarially verified review of the whole release fixed these in the tile view: an image dropped on a tile uploads to that tile's session instead of navigating the browser away; a Claude session started into the grid keeps its welcome banner and transcript; a tile refresh never blanks the screen while it waits; a remote close or a reconnect no longer moves your keyboard into another session's tile; dictation and the phone keyboard's Path and Clear keys reach the focused tile or split pane; each tile caps its live-output backlog and recovers dropped output with one bounded refresh; Redraw on a tile forces the resize it reports; popping out the last tile leaves no frozen view; and "Open group as tiles" no longer pulls an open split into the grid. Also from that review: the By case layout stays one scrolling row on 600 to 767px tablets, the needs-you pulse animates opacity only, a codex session on the ultra effort shows its model, codex's launch defaults are CLI registry data instead of an id check, `npm run build` checks its dependencies before it deletes anything, and the release's new strings (case picker rows, Git status settings, toasts, tile and spreadsheet texts, the Redraw toasts) have zh-CN translations.
+
+  **Fixes applied while landing.** Tiles and the split's Pane B got the same two fixes the main terminal got from contributors: opencode's wheel paging and click reports (#555), and the Android keyboard handling that stops autocorrect duplicating a line (#541). Android: a word composed right before Enter in the same keyboard transaction was sent twice; it now arrives once (#541). Codex: App Settings refuses a Default Codex model the server would reject instead of failing the whole save behind a "Settings saved" toast, and the two Codex rows stack under their labels on phones (#546). Run dropdown: its height follows the on-screen keyboard and both iPhone safe areas, a long custom-endpoint label no longer adds a horizontal scrollbar, and the open menu sits above the keyboard accessory bar (#542). Git status: a lone repository git cannot read is no longer shown as clean and empty, a repeated `timeout` query parameter no longer answers 500, and the timeout field accepts any whole number of seconds (#543). Spreadsheets: cells clipped to nothing at the edge of a very large sheet no longer grow its scroll area, and the preview's fixed texts have zh-CN translations (#502). Pop-out windows: the bridge refuses to pop out without a window channel (the tab could never re-dock), the tab menu follows the host-aware default, and Close window works inside a host window (#432). Every deprecated `/api/screenshots` route now logs its warning, pinned per route (#551). Across the new tab layouts and header styles: lineage lines run between the state labels and the tabs and never through a case box, an open Tiles or Split button stays highlighted in the boxed header styles, a phone keeps the active chip in view when it changes state band, and the Tab Layout and Header Stats Style settings are translated.
+
+## 1.35.0
+
+### Minor Changes
+
+- 6f88e40: ### Thanks
+  - @opticon454 for four PRs in one night: the Git status indicator with its panel of uncommitted and unpushed work and per-file diffs (#537), `codeman doctor` in Settings (#536), creating a case in a custom folder (#535) and the detailed-rail rename clamp fix (#534). Both review rounds came back within half an hour with every item addressed.
+  - @aakhter for making the grouped vertical rail editable end to end (#525), the inline rename write queue and the long-prefix editor layout (#526), and bounded path probes so an unreachable network mount can no longer freeze the server (#516). Every round came back with tests that replay the exact sequences from the review, and the review nits were already fixed before landing.
+
+  **Edit tab groups in the vertical rail (#525).** The grouped rail is now editable from the browser: create, rename, reorder and delete groups, and move tabs between groups or back to Ungrouped, from the row menu, a group menu (Shift+F10, ContextMenu, right-click, or the header glyph, which stays visible on touch screens; F2 renames inline) or a mouse/pen drag. A flat rail offers "Move to new group" to make the first one. Every edit is a named operation saved through the existing `PUT /api/tab-layout`, one write in flight at a time; a version conflict replays the pending operations onto the server's layout and retries, so a concurrent edit from another device survives, and unsaved edits survive a reload. A drag released outside the rail leaves nothing behind, and committing a group rename by clicking elsewhere leaves focus where you clicked. No server changes.
+
+  **Inline rename that keeps up (#526).** Inline renames go through a per-session queue: one PUT at a time in the order they were made, the confirmed name applied even if the editor was reopened or cancelled meanwhile, an editor reopened over a rename in flight starts from that name, and a failed rename always shows its toast. A long `w<n>-<case>` prefix no longer pushes the editor out of its row in the rail or the sidebar, and the detailed rail no longer keeps its 3-line clamp around the editor (#534 found and fixed the same clamp independently).
+
+  **Git status in the bottom bar (#537).** Turn on Settings → Header & Panels → Bottom bar → "Git status" (per-device, off by default) and a small indicator shows the active session's repository at a glance (`● 3` uncommitted files, `↑ 2` commits not pushed, `✓` when everything is committed and pushed). Click it for a draggable window listing the uncommitted files (staged, not staged, untracked, conflicts; click one for its diff; grouped under collapsible folders) and the unpushed commits. A folder holding several projects gets a section per repository found up to two levels down, and an unrelated repository above the workspace (a dotfiles repo in your home folder) is ignored. Read-only and offline: Codeman never fetches or changes the repository, and git never runs on a repository a Docker case can write to. Not shown for Docker or remote sessions. New `GET /api/sessions/:id/git-status` and `GET /api/sessions/:id/git-diff`.
+
+  **Diagnostics in Settings (#536).** Settings → System → Diagnostics runs `codeman doctor` on the server (`GET /api/doctor`) and lists which agent CLIs, tmux, Node and the optional office tools are installed, with versions, paths and install hints. The probe runs in a child process, so a slow `--version` cannot freeze the server, and both the panel and the terminal `codeman doctor` now also look in each CLI's usual install directories, so a CLI installed outside a service's minimal PATH is found. Admin only in multi-user mode.
+
+  **Create a case in a custom folder (#535).** Add Case → Create New has a "Create in a custom folder" option with a Browse button: the case folder is created inside the parent you pick, scaffolded like any other case and listed alongside the rest (deleting it unlinks, never removes files). `POST /api/cases` accepts an optional `path` for the same thing. The folder must not exist or must be empty, and system folders, the home folder, credential folders and the cases directory itself are refused. Nothing is left behind if creation fails part-way. Admin only in multi-user mode.
+
+  **An unreachable mount no longer freezes the server (#516).** A linked case can live on a network mount, and when that mount goes away a hard mount makes `stat()` wait indefinitely; the synchronous probes in the case routes, the workspace hook and statusLine helpers and session creation used to freeze the whole server with it. Those probes now go through one bounded, tri-state probe (present, absent, or unknown when nothing answers in time): a stalled path costs one threadpool worker, paths on the same mount answer "unknown" without a new stat, and unrelated paths keep working. "Unknown" is never treated as "absent": `GET /api/cases/:name` reports an unreachable linked case with `unreachable: true` instead of NOT_FOUND, Run creates a case only on a real NOT_FOUND, and session creation answers OPERATION_FAILED for a folder that did not answer and never scaffolds over it. Tunable with `CODEMAN_PATH_PROBE_TIMEOUT_MS` (default 1500) and `CODEMAN_PATH_PROBE_MAX_STALLED`.
+
+  **Fixes applied while landing.** Tab groups: an edit made while an earlier save was still in flight, and made inapplicable by that save's conflict (its group deleted on another device), is no longer dropped silently but reported like every other dropped edit, and the menus stop offering a new group once the 32-group limit is reached instead of failing with an untranslated error. Rail: a static CI check now pins that no rail or sidebar clamp out-ranks the rename unclamp (the browser test that caught it is outside the gate). Git status: a cached repository list is re-checked against the current Docker workspaces on every poll, a diff larger than 8 MB is cut short instead of failing, a diff click refreshes only that repository, a dotfiles repository above the workspace is identified with one `rev-parse` before any full status (a failing status there no longer hides the repositories below), and "Upstream is gone" now reads "Upstream not on remote", which is also true for a branch that was never pushed. Doctor: candidates are judged like the Run menu's own resolver (a wrong binary on the PATH no longer hides the right one in an install directory, a non-executable file or a relative directory reads as missing), probes are killed with SIGKILL on timeout, a missing optional tool shows ○ instead of ✗, and the contract test no longer runs the machine's installed CLIs. Custom-folder cases: the symlink-resolved target is judged against resolved roots too (home reached through a link, macOS `/private/etc`), a target inside the cases directory is refused, the success toast names the folder the server created, the new labels have zh-CN translations, and the route test can no longer delete a real `~/projects` or the live linked-cases registry when run outside `npm test`.
+
 ## 1.34.0
 
 ### Minor Changes

README.md

@@ -385,6 +385,14 @@ Beyond single-session respawn, the **Orchestrator** turns a high-level goal into
 
 Run **20 parallel sessions** with full visibility — real-time xterm.js terminals at 60fps, per-session token and cost tracking, tab-based navigation, and one-click management.
 
+### Tile Grid
+
+<p align="center">
+  <img src="docs/images/tile-grid-20261009.gif" alt="Tile grid: the Tiles button opens six live sessions side by side (DeepSeek Harness, Claude Code, Codex, a shell, OpenCode and Pi), and a second click returns to a single session" width="800">
+</p>
+
+Watch and drive up to **six sessions side by side** in one window. Click **Tiles** in the header (or press `Ctrl+Shift+G`) and your sessions open as a grid of live terminals: every tile takes your keystrokes and shows its agent's logo, model and state in its header. Right-click **Tiles** to choose 2, 4 or 6 tiles, and drag a tile by its header to move it. Click **Tiles** again to return to a single session; the grid is remembered for next time. Desktop only (a window about 1180px wide or more). Full guide: [Tile Grid](docs/wiki/Tile-Grid.md).
+
 ### Persistent Sessions
 
 Every session runs inside **tmux** — sessions survive server restarts, network drops, and machine sleep. Auto-recovery on startup with dual redundancy. Ghost session discovery finds orphaned tmux sessions. Managed sessions are environment-tagged so the agent won't kill its own session.
@@ -444,8 +452,11 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 ## More Features
 
 - **Background daemon & service install** — `codeman web -d` runs the server detached with a pidfile, `~/.codeman/web.log`, and verified startup (it polls the server until it answers, so a port clash never reads as success); `codeman service install` writes a systemd user unit (Linux) or LaunchAgent (macOS) with your shell's PATH baked in, so an nvm or Homebrew `node`, `tmux` and `claude` are actually found. Secrets are never written into unit files
+- **Diagnostics in Settings** — **App Settings → System → Diagnostics → Run checks** runs `codeman doctor` on the server and lists Node, tmux, every agent CLI and the optional office tools with versions, paths and install hints. Besides the `PATH`, it also looks in each CLI's usual install directories (`~/.local/bin`, `~/.npm-global/bin` and the like), so most installs are found under a service with a minimal `PATH`. Admin only in multi-user mode.
 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → System → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
+- **Git status in the bottom bar** — off by default (**App Settings → Header & Panels → Bottom bar → Git status**, per device). A small indicator at the right of the bottom bar shows the active session's repository at a glance: `● 3` uncommitted files, `↑ 2` commits not pushed, `⚠` merge conflicts, `✓` all committed and pushed. Click it for a draggable window listing the staged, not-staged, untracked and conflicted files (grouped under collapsed folders, or as a flat list if you turn that setting off) and the unpushed commits; **click a file to see its diff** (new files as all additions, deleted files as all removals), with **Open file** to jump to the viewer. A folder that holds several projects gets one collapsible section per repository found up to two levels down, all collapsed until you open them. Read-only and offline (Codeman never fetches or changes the repo); not shown for Docker or remote sessions.
 - **Clone a GitHub repo as a case** — paste a repository URL into **Add Case → Clone Repo** and Codeman clones it into `~/codeman-cases/<name>` and registers it as a normal case, ready to run an agent in. It preflights the URL while you type (tells you whether it can be cloned anonymously and offers the repo's real branches and tags for the optional branch/tag field), fills the case name in from the URL, and lets you pick which CLI the Run button should use. Public repositories over `https://`; Codeman never collects or stores credentials
+- **Create a case in a custom folder** — tick **Create in a custom folder** in **Add Case → Create New**, pick a parent folder (Browse included) and a name, and Codeman scaffolds the new case there instead of `~/codeman-cases`. The target must be a new or empty folder; system directories, your home folder itself, credential trees such as `~/.ssh`, and Codeman's own data folder are refused. Admin only in multi-user mode.
 - **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, **Gemini**, **Pi**, **Grok**, **DeepSeek Harness**, or **OMP** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*` vs `GROK_*`/`XAI_*` vs `DSH_*`/`DEEPSEEK_*` vs `OMP_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md), [`docs/pi-integration.md`](docs/pi-integration.md), [`docs/grok-integration.md`](docs/grok-integration.md), [`docs/deepseek-integration.md`](docs/deepseek-integration.md) and [`docs/omp-integration.md`](docs/omp-integration.md)
 - **Custom model endpoints** _(new in 1.29.0, HTTP API for now)_ — point a session's CLI at any OpenAI-compatible endpoint instead of its native backend: a local llama.cpp, llama-swap, Ollama or vLLM box, or a cloud gateway such as Azure AI Foundry or OpenRouter. Save an endpoint once (`POST /api/model-endpoints`; its models are discovered from `/v1/models`), apply it to a session (`POST /api/sessions/:id/custom-model`), and the CLI restarts in place on that endpoint. Verified live for Claude, OpenCode, Pi, Grok and OMP; Codex, Gemini and DeepSeek have documented gaps, Antigravity has no mechanism. A toolbar picker is the follow-up. See [`docs/custom-model-endpoints.md`](docs/custom-model-endpoints.md)
 - **Web tabs** — open Grafana, Uptime Kuma, a Vite dev server or any dashboard URL as a tab beside your sessions (Run dropdown → **Web / URL** → **Add URL**). Dashboards are proxied through Codeman's own origin, so an `http://` target works from a phone over HTTPS and through the tunnel, single-page apps route on their own paths, and a frame that reloads recovers itself. A `localhost` link an agent prints opens as a web tab automatically. See [`docs/web-tabs.md`](docs/web-tabs.md)

README.zh-CN.md

@@ -386,6 +386,14 @@ WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE →
 
 运行 **20 个并行会话**且全程可见 —— 60fps 的实时 xterm.js 终端、按会话的 token 与成本跟踪、基于标签的导航，以及一键管理。
 
+### 平铺网格
+
+<p align="center">
+  <img src="docs/images/tile-grid-20261009.gif" alt="平铺网格：点击平铺按钮，六个实时会话并排打开（DeepSeek Harness、Claude Code、Codex、一个 shell、OpenCode 和 Pi），再点击一次即回到单个会话" width="800">
+</p>
+
+在一个窗口里并排查看和操作最多**六个会话**。点击顶栏的**平铺**按钮（或按 `Ctrl+Shift+G`），会话会以实时终端网格的形式打开：每个窗格都能直接接收键盘输入，并在窗格标题栏中显示智能体的图标、模型和状态。右键单击**平铺**可选择 2、4 或 6 个窗格，按住窗格标题栏拖动即可移动窗格。再次点击**平铺**即回到单个会话，网格会被记住，下次直接恢复。仅限桌面端（窗口宽度约 1180px 以上）。完整说明：[Tile Grid](docs/wiki/Tile-Grid.md)（英文）。
+
 ### 持久化会话
 
 每个会话都运行在 **tmux** 内 —— 会话可在服务器重启、网络中断与机器休眠后存续。启动时自动恢复，具备双重冗余。幽灵会话发现机制能找到孤立的 tmux 会话。受管会话带有环境标签，因此智能体不会杀掉自己的会话。

config/test-suites.ts

@@ -21,6 +21,7 @@
 export const BROWSER_TEST_GLOBS = [
   'test/tab-rail-resize.browser.test.ts',
   'test/tab-activation.browser.test.ts',
+  'test/tab-layout-editing.browser.test.ts',
   'test/session-sidebar-ux.browser.test.ts',
   'test/session-options-responsive.browser.test.ts',
   'test/inline-rename.test.ts',
@@ -32,12 +33,18 @@ export const BROWSER_TEST_GLOBS = [
   'test/capture-geometry-retry.browser.test.ts',
   'test/codex-predictive-echo.test.ts', // also needs a real codex binary
   'test/split-pane-terminal.browser.test.ts',
+  'test/terminal-tile-scroll.browser.test.ts',
   'test/shift-enter-keypress.browser.test.ts',
   'test/key-tester.browser.test.ts',
   'test/webhook-settings.browser.test.ts',
+  'test/case-custom-path.browser.test.ts',
+  'test/doctor-settings.browser.test.ts',
+  'test/git-status.browser.test.ts',
   'test/split-pane-orchestration.browser.test.ts',
   'test/split-pane-auto-collapse.browser.test.ts',
+  'test/spreadsheet-preview.browser.test.ts',
   'test/mobile-ime-preview.browser.test.ts',
+  'test/run-mode-menu-scroll.browser.test.ts',
 ];
 
 /**

docs/api-reference.md

@@ -45,6 +45,13 @@ payload return `{ "success": true, "data": {} }`.
 > `GET /api/sessions/:id/tail-file` (SSE), `GET /api/download`,
 > `GET /api/screenshots/:name`, `GET /q/:code` (QR redirect), and the
 > `GET /ws/sessions/:id/terminal` WebSocket upgrade.
+>
+> **Deprecated:** `POST /api/screenshots`, `GET /api/screenshots` and
+> `GET /api/screenshots/:name` keep working but log a one-time warning on first
+> use. They are removed in a later MAJOR, after at least one MINOR release that
+> carries this warning (see `docs/versioning-policy.md`). To hand
+> a file to an agent, use `POST /api/sessions/:id/paste-image`, which saves it into
+> that session's workspace.
 
 > The [agent wait endpoints](#long-polling-agent-wait) use the normal envelope but
 > are the only JSON endpoints that deliberately **hold the connection open**, for up
@@ -445,6 +452,20 @@ count against the same 16, not 16 of each. An abandoned request no longer holds
 slot, because the routes release the waiter when the client disconnects, but a
 client that opens many concurrent waits against one session will still hit the cap.
 
+## Terminal capture (`GET /api/v1/sessions/:id/terminal`)
+
+What a session's terminal shows, for a client to replay: `data.terminalBuffer`,
+with `source` (`mux-visible`, `mux-full-history` or `history`), `truncated`,
+`truncationReason`, `fullSize`, and `captureCols`/`captureRows` when the pane's
+geometry was read. The capture runs synchronous tmux calls on the server; the
+`Server-Timing` header reports `capture`, `prepare` and `total`.
+
+| Query | Meaning |
+|---|---|
+| `full=1` | tmux's scrollback, not only the visible frame (`source: 'mux-full-history'`), ending with a relative cursor move back to the pane's caret. |
+| `tail=<bytes>` | Keep the newest `<bytes>` of the result (`truncationReason: 'tail'` when it cut). |
+| `lines=<n>` | With `full=1` only: read at most `<n>` lines of tmux history above the visible frame. An integer of at least 1, clamped to the configured history limit; absent or malformed, the whole limit (100,000 lines by default), as before. `truncated` and `truncationReason` describe byte cuts only, not this bound. Without it a full capture reads all of that history before `tail` cuts it, so a client that keeps a fixed number of lines (the tile grid sends its xterm's scrollback plus its rows) should send it. |
+
 ## Session lineage (`parentSessionId`)
 
 A create request may name the session that spawned it, which the web UI draws as a
@@ -470,6 +491,32 @@ also pure decoration: it confers no permission, and a child is unaffected by its
 parent exiting. It appears on session state as `parentSessionId` (absent when
 unresolved) and survives a server restart.
 
+## Session model (`displayModel`)
+
+Session state (`GET /api/v1/sessions`, the `session:updated` event) carries the model a
+session runs as far as the server knows it, for the web UI's session headers:
+
+```json
+"displayModel": { "model": "qwen3.8-27b", "source": "screen" }
+```
+
+`source` is where it came from, strongest first:
+
+| `source`          | Meaning                                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------- |
+| `custom-endpoint` | The session is pointed at a Custom Model Endpoint Profile; its `modelId` answers, whatever the CLI prints. |
+| `statusline`      | Claude's statusLine exporter reported it (`model.display_name`); follows an in-session `/model`.          |
+| `screen`          | Read off the CLI's own footer (`capabilities.modelDetect`, today dsh and codex); follows a switch.      |
+| `config`          | What the CLI's own config pins for the session (`capabilities.modelDetect.configResolver`, today dsh-TUI's route), while its screen names none. |
+| `launch`          | What the session was launched with (`--model`, the app-wide default, `<cli>Config.model`); nothing has reported since. |
+
+Between `statusline` and `screen` the newest report wins. The field is absent when no
+model is known (a shell, a CLI that reports none and was launched without one). `model`
+is display text from a pane or a CLI report: control characters are stripped and it is at
+most 64 characters, but treat it as untrusted text. A `statusline` or `screen` value is
+persisted and restored after a server restart until the next report replaces it; a
+`config` value is read again at every pane start, attach and relaunch instead.
+
 ## Approvals Inbox
 
 Cross-session queue of prompts waiting on a human (permission dialogs,
@@ -700,6 +747,46 @@ normal `caseName`/`mode`/etc. body)
   jarring than a full relaunch, and folding it into the one-shot path is
   separate work — see `docs/custom-model-endpoints-plan.md`).
 
+## Creating a case in a custom folder
+
+`POST /api/cases` takes `{ name, description?, path? }`. Without `path` it creates `<cases dir>/<name>` as always. With `path` (absolute, or starting with `~`) the case folder is created at that exact path instead, scaffolded the same way (`CLAUDE.md`, `src/`, `.claude/settings.local.json`), and registered in the linked-cases registry, so it lists, resolves and deletes like a linked case (deleting unlinks; it never removes files). Response: `{ case: { name, path } }`, where `path` is the symlink-resolved folder.
+
+The target is judged before anything is written:
+
+- It must be absolute with no `..` and none of the shell metacharacters a session working directory is rejected for (spaces are fine). `400 INVALID_INPUT` otherwise.
+- It must not be a system directory (`/etc`, `/usr`, `/proc`, ...), the home folder itself, Codeman's own data folder, or a credential/config tree (`~/.ssh`, `~/.aws`, `~/.claude`, ...). Judged on the path as typed and on its symlink-resolved form, against both the given and the symlink-resolved roots. `400`.
+- It must not be, or be inside, the cases directory (the caller's own and the shared one): a case there is a plain create without `path`. `400`.
+- Its parent must already exist (one folder is created, never a chain): `404 NOT_FOUND`. A parent that does not answer (an unreachable network mount) or cannot be read is `422 OPERATION_FAILED`, checked through the bounded path probe before anything else touches it.
+- The folder must not exist, or must be an **empty** directory; a folder with contents is Link Existing's job: `409 ALREADY_EXISTS`. A symlink or a plain file at the target is `400`.
+- `409 ALREADY_EXISTS` also for a case name already in use (in the cases dir or the registry) and for a folder that is already a case.
+
+Admin only in multi-user mode (`403`), like `POST /api/cases/link`: it writes outside the cases directory and into the shared, ownerless registry. If anything fails after the first write, what this call created is removed (the whole folder if it created it, otherwise only the scaffold inside the empty folder you picked) and the response is `500`.
+
+## Git status
+
+`GET /api/sessions/:id/git-status` is what the bottom-bar Git indicator and its panel read (Settings → Header & Panels → Bottom bar, per-device, default off). It reports what the session's workspace has not committed or pushed. **Read-only and offline:** it never fetches, pulls, commits or writes (it runs `git status` with `--no-optional-locks`, so it does not even refresh the index), which is why `behind` is as of the last `git fetch`. The session is resolved like every session route (ownership via `findSessionOrFail`; another user's session is `404`). A repository whose root is, or is inside, a Docker case workspace is dropped (from the walk-up, the scan below a folder, and the diff route): a container can write there, and a repository's own clean filter or signature program would run on the host. When a branch's upstream does not exist on the remote (deleted and pruned, or never pushed, as after cloning an empty repository and committing), `upstreamGone` is `true` and the unpushed list falls back to commits on no remote-tracking ref at all.
+
+`GET /api/sessions/:id/git-diff?repo=<repoRoot>&path=<path>&kind=staged|unstaged|untracked|conflicted` returns the unified diff of one file the panel lists (`{ diff, truncated, binary }`; staged is index vs HEAD, unstaged is working tree vs index, untracked is the whole file as additions). It is what opens when you click a file in the Git panel. `repo` and `path` are matched against the current status rather than trusted, so anything the status does not list is `404`. Read-only: it passes `--no-ext-diff --no-textconv` (no external diff or textconv driver runs), but a repository's clean filters still run, as they do for any `git diff`, which is why a repository a container can write to is never inspected (below). Capped at 400 KB, and refused (`400`) for remote and Docker sessions; a repository at or inside a Docker case workspace is not in the status, so it is `404` here.
+
+**Which repositories.** git finds a repository by walking *up* from the session's working directory, so:
+
+- Inside a repository (or at its root): that one repository, whole (a subfolder reports its enclosing repo, `path` says where it is, e.g. `../..`). A nested repo below it is just an untracked folder to the outer one and is not scanned; start the session inside it to see it.
+- **Not** inside one (a folder that holds several projects): every repository found up to **two levels down**, nearest and alphabetical first, at most `maxRepos` of them (default 12, 1 to 50; `reposTruncated` says when there were more and `repoLimit` is the limit that was applied). Dot-folders, `node_modules`, `dist`, `build`, `target`, `vendor`, `venv` and `__pycache__` are skipped, symlinks are never followed, and a repository's own contents are not searched. The list of repositories is re-scanned at most every 30 s; each repository's status is cached for 4 s.
+- A repository that merely sits **above** the workspace and is the home folder or higher (a dotfiles repo in `$HOME`, or `/`) is ignored: its dirty files are not this session's work. A workspace that *is* that repository's root is not ignored.
+- A worktree (whose `.git` is a file) counts as a repository. A submodule's own uncommitted files are not reported, only a changed submodule pointer.
+
+Both routes accept two optional query parameters, which the UI sends from its per-device settings and the server clamps again: `maxRepos` (1 to 50, default 12) and `timeout` (seconds one git command may run, 5 to 120, default 30). An empty or non-numeric value means the default. A repository whose `git status` fails (typically a timeout on a slow network share) is **kept in `repos[]`** with `status.state: 'error'` and the reason in `status.error`, not dropped, so it is visible that something is not being reported.
+
+`data` is `{ state, repos, reposTruncated, repoLimit, checkedAt }` (`repoLimit` in the folder-of-projects case only):
+
+- `state: 'ok'`: `repos[]`, each `{ name, path, status }` where `name` is the repository folder's name, `path` its root relative to the working directory, and `status` is:
+  `branch` (null when `detached`), `upstream`, `ahead`, `behind`, `hasRemote`, `counts` (`staged`, `unstaged`, `untracked`, `conflicted`, `uncommitted` = distinct paths, `stashes`), `files[]` (`path` relative to `repoRoot`, `origPath` for a rename, `index` and `worktree` status letters, `kind`: `staged` \| `unstaged` \| `untracked` \| `conflicted`; a file that is staged *and* modified again appears once per kind), `filesTruncated`, `unpushedCount` (exact) and `unpushed[]` (newest first: `hash`, `author`, `time` in epoch seconds, `subject`), `repoRoot`, `checkedAt`.
+- `state: 'not-a-repo'`: no repository here, above (that counts) or within two levels below.
+- `state: 'unsupported'` with `reason: 'remote' | 'docker'`: those sessions are never inspected (a Docker workspace is writable from inside its sandbox, and git here would run on the host).
+- `state: 'error'` with a short `error` (git missing, timed out, or git's first stderr line with any `user:token@` credentials redacted).
+
+Lists are capped (300 files and 50 commits per repository) while the counts stay exact. A branch with no upstream reports the commits no remote has (`HEAD --not --remotes`); a repository with no remote reports `unpushedCount: 0`, since there is nothing to push to. Concurrent polls of one folder share a single git invocation; `?fresh=1` (what the panel's Refresh button and opening the panel send) skips the short-lived caches, though it still joins a computation already running.
+
 ## CLI management
 
 Read and write the CLI registry (`docs/cli-registry.md`). Every **write** route answers `403 FORBIDDEN` while `cliManagementEnabled` is off (the default), and for a non-admin in multi-user mode. A write that would overwrite a `clis.json` which does not parse, or which has group/world permission bits, is refused with `409 CONFLICT` and a message naming the fix; the file is left untouched.
@@ -748,6 +835,10 @@ Posts the Web Push events to ntfy, Slack, Discord or a generic JSON URL (Setting
 
 Delivery goes through the same egress guard as web tabs (refused on the resolved address too), does not follow redirects, times out after 5 s, sends the same event for the same session at most once per 3 s, and has at most 5 requests in flight. Error text never contains the URL.
 
+## Diagnostics
+
+`GET /api/doctor[?category=core|office|other]` returns the `codeman doctor --json` report (`platform`, `summary`, `tools[]` with `status` `ok` \| `missing` \| `outdated` \| `skipped` \| `error`, `version`, `path`, `installHint`). The probe engine is synchronous, so it runs in a child process of the same entry script, never on the server's event loop (30 s timeout). It names install paths and versions, so it is admin only in multi-user mode (`403`). `400` for an unknown category, `500` if the child produces no report.
+
 ## Voice dictation
 
 Browser dictation transcribed through this server's Claude Code login, i.e. the

docs/browser-testing-guide.md

@@ -71,17 +71,21 @@ We tested three browser automation frameworks against the Codeman web UI:
 
 ## Test File Structure
 
-### Port Allocation
+### Ports
 
-| Port Range | Test File |
-|------------|-----------|
-| 3150-3153 | browser-e2e.test.ts (existing) |
-| 3154 | file-link-click.test.ts |
-| 3155 | browser-playwright.test.ts |
-| 3156 | browser-puppeteer.test.ts |
-| 3157 | browser-agent.test.ts |
-| 3158-3160 | browser-comparison.test.ts |
-| 3180-3182 | scripts/browser-comparison.mjs |
+A test that starts a server binds an ephemeral port, never a fixed one:
+
+- `WebServer`: `new WebServer(0, false, true)`, then read the port the OS handed out from
+  `server.boundPort` after `await server.start()`. `test/test-ports-guard.test.ts` fails
+  any `WebServer` built under `test/` on a non-zero port (a shrink-only legacy list
+  excepted).
+- A raw Fastify or `ws` server: `listen({ port: 0 })`, then `address().port`.
+- The mobile suite (`test/mobile/**`, via `createTestServer(PORT)`) keeps the fixed-port
+  convention in `test/mobile/README.md` for now.
+- Never port 3000: that is the live instance.
+
+`scripts/browser-comparison.mjs` is a standalone script outside the guard and still uses
+fixed ports 3180-3182.
 
 ### File Purposes
 
@@ -106,7 +110,7 @@ const browser = await chromium.launch({
 });
 
 const page = await browser.newPage();
-await page.goto('http://localhost:3000');
+await page.goto(BASE_URL);
 
 // Auto-waiting selectors
 await page.click('.btn-claude');
@@ -140,7 +144,7 @@ const browser = await puppeteer.launch({
 });
 
 const page = await browser.newPage();
-await page.goto('http://localhost:3000');
+await page.goto(BASE_URL);
 
 // Manual waiting often needed
 await page.click('.btn-claude');
@@ -186,7 +190,7 @@ function agentBrowserJson<T>(cmd: string): T {
 }
 
 // Usage
-agentBrowser('open http://localhost:3000');
+agentBrowser(`open ${BASE_URL}`);
 agentBrowser('click ".btn-claude"');
 const title = agentBrowserJson<{title: string}>('get title');
 
@@ -246,11 +250,14 @@ npx playwright install chromium
 ### 4. Wait for Server Startup
 
 ```typescript
-const server = new WebServer(PORT);
+const server = new WebServer(0, false, true); // port 0 (the OS picks one), no TLS, testMode
 await server.start();
-await new Promise(r => setTimeout(r, 1000)); // Allow server to stabilize
+const BASE_URL = `http://localhost:${server.boundPort}`;
 ```
 
+`boundPort` holds the real port only once `start()` has resolved. The `BASE_URL` used by the
+other snippets on this page is this one.
+
 ### 5. Clean Up Sessions
 
 Track created sessions for cleanup:

docs/cli-registry.md

@@ -36,7 +36,7 @@ These are the only writes to `clis.json`. They are serialized, and a file that d
 interface CliEntry {
   id: CliId; // 'codex'
   label: string; // 'Codex' — shown in menus
-  shortBadge: string; // tab badge, e.g. 'CX'
+  shortBadge: string; // short label ("Run CX", the Settings CLI list), e.g. 'CX'; tabs show the run-mode-dot logo instead (no mark at all with CLI Logos on Tabs off)
   accent: string; // single hex colour
   enabled: boolean;
   stock: boolean; // set by the loader; a custom entry can never claim it
@@ -49,6 +49,11 @@ interface CliEntry {
   //   .workDetect?: { promptGlyph, workingLine, watchingLine?, watchingLines?, awaitingLine? }
   //   — how this CLI's pane shows work, work it started in the background, and a turn
   //   that ended waiting for workers it will resume from
+  //   .modelDetect?: { screenLine, screenLines? }
+  //   (where this CLI's own chrome names the model it runs: SessionState.displayModel)
+  //   .launchDefaults?: { [launchParam]: settingsKey }
+  //   (synced App Settings that seed a LOCAL launch's params the caller left unset;
+  //   codex's model and reasoning effort, via src/web/launch-defaults.ts)
   overlays: CliOverlays; // remote-SSH / Docker pane commands, credential store
 }
 ```
@@ -57,10 +62,14 @@ interface CliEntry {
 
 ### Regexes that come from config
 
-Four capability fields carry a regular expression an override file can set: `discovery.version.regex`, `capabilities.workDetect.workingLine`, `capabilities.workDetect.watchingLine` and `capabilities.workDetect.awaitingLine`. All four go through `compileVersionRegex()`, which caps the source at 200 characters, refuses the nested-quantifier shapes that cause catastrophic backtracking, and returns `null` rather than throwing so every caller degrades instead of crashing.
+Five capability fields carry a regular expression an override file can set: `discovery.version.regex`, `capabilities.workDetect.workingLine`, `capabilities.workDetect.watchingLine`, `capabilities.workDetect.awaitingLine` and `capabilities.modelDetect.screenLine`. All five go through `compileVersionRegex()`, which caps the source at 200 characters, refuses the nested-quantifier shapes that cause catastrophic backtracking, and returns `null` rather than throwing so every caller degrades instead of crashing.
 
 `workingLine` is the one that matters most, because it is compiled once per session and then run against every accumulated PTY chunk and every pane capture. A nested quantifier there is a ReDoS against the event loop for the whole server, not just that session. The guard therefore runs in two places, and neither is redundant: `schema.ts` rejects the entry at LOAD time so a bad pattern never reaches a session, and `_workingLinePattern()` in `session.ts` compiles through the same helper so the runtime cannot end up with a pattern the schema would have refused.
 
+`modelDetect.screenLine` names the model a session runs, for the tile grid's and the split pane's headers (`SessionState.displayModel`). It must have exactly ONE capture group, the model, which `schema.ts` checks at LOAD time, and it runs over the last `screenLines` (1 to 8, default 1) non-blank rows of the capture the idle/working probe already takes, joined with newlines so a pattern can anchor on the row above. Like `watchingLine`, the rows are pane text the agent writes most of, so a pattern must anchor on chrome only that CLI draws. The two stock ones, measured on live panes: dsh-TUI's status line on the row under its composer's rounded border (`╰─+╯\n ?(<model>)`, three rows), codex's `  <model> <effort> · ` footer (its last row, or the row above codex 0.162's indented hint row, so a two-row window), and opencode's composer agent row (`┃  Build  <model> <provider>`, directly above the box's `╹` edge, eight rows because its home screen puts up to five rows of its own chrome below it). opencode's field is the model AND the provider, since only colour separates them on that row; the pattern takes the LAST such row in the window, so a composer-shaped row the agent prints higher up cannot stand in for it. A screen that does not match keeps the last model the session reported; a CLI without the field shows its launch model, if any. Claude needs none: its statusLine exporter reports `model.display_name` on every render. ⚠️ dsh-TUI's first field is the model only while its status bar's model field is on; switched off, it is the next field: the reasoning effort (` medium · <cwd>`), the session mode, or the folder name. So a captured field is not taken when it is one of the CLI's declared `modelDetect.rejectWords` (single tokens, compared ignoring case; dsh lists every effort id its adapters offer and the shipped mode ids) or the session's own working-directory basename (the shared reader's rule, for every CLI). Anything else the pattern captures is the model, so the official `deepseek-chat` / `deepseek-reasoner` ids are read.
+
+`modelDetect.configResolver` names a READER in `src/model-config-resolvers.ts` (a name, never code in config, like a launcher profile) that resolves the model the CLI's own config pins for one session, for while its screen names none (the `config` source of `displayModel`, ranked below any report from the running CLI). It runs at every pane start, attach and relaunch, with the session's own launch config and env, and must be read-only, bounded (probe before read, no synchronous filesystem call) and return the model id alone. The one stock reader, `deepseek-route` (`src/deepseek-route-config.ts`), resolves dsh-TUI's route the way dsh composes it for the session's profile under the session's `DSH_HOME`: the last of `profiles/<profile>/cordis.patch.yml` and `$DSH_HOME/cordis.patch.yml` carrying `config` for the `dsh-tui` row counts, and only when it names both `provider` and `model`. Anything in doubt answers nothing: a half-pinned route, a profile without dsh-TUI, an unreadable, oversized or symlinked-out layer, a file beyond its narrow YAML subset.
+
 `watchingLine` reads a different row of the same screen. A CLI draws it while work the agent
 itself started is still running — Claude prints `⏵⏵ bypass permissions on · 1 monitor · ← for
 agents` while a monitor, a backgrounded shell or a cloud session is live. Codeman turns that
@@ -75,10 +84,11 @@ Two CLIs declare such a row today, and they put it in different places. Claude w
 chip on the last row of the screen, so it keeps the default one-row window and anchors on
 the `·` its footer joins items with. Codex pins
 `1 background terminal running · /ps to view · /stop to close` ABOVE its composer, which
-puts the row third from the bottom once the status line and the composer are counted, so its
-entry declares `watchingLines: 3` and matches that row end to end. Both were measured
-against live panes rather than read out of a binary, which is the standard for adding a
-third.
+puts the row third from the bottom once the status line and the composer are counted, and
+fourth on codex 0.162+ at rest, where a `← for agents · ? for shortcuts` hint row sits under
+the status line (it disappears while a prompt is typed). So its entry declares
+`watchingLines: 4` and matches that row end to end. Both were measured against live panes
+rather than read out of a binary, which is the standard for adding a third.
 
 `awaitingLine` covers the quiet pane that is neither idle nor watching: a turn that ENDED
 to wait for workers the CLI will resume from by itself. When background agents or an

docs/deepseek-integration.md

@@ -201,6 +201,18 @@ not try to set one. Configure it where the harness does: `~/.dsh/settings.yaml`
 plus a home-level `~/.dsh/cordis.patch.yml`, or a `--patch` overlay on the
 profile. That is also how you point dsh at a local or third-party provider.
 
+Codeman does READ the route, for display only: a session header names the model
+the TUI's status line draws, and while it draws none (the status bar's model
+field switched off, or not painted yet) the model the session's route config
+pins (`src/deepseek-route-config.ts`). That is dsh-TUI's own rule: the last of
+`profiles/<profile>/cordis.patch.yml` and `$DSH_HOME/cordis.patch.yml` carrying
+`config` for the `dsh-tui` row, and only when it names BOTH `provider` and
+`model`; a half-pinned route is dropped whole by the TUI and shows nothing here.
+`settings.yaml`'s `agent-default-model` is the headless default and is not read.
+The reader never writes, follows no symlink out of the dsh home, and returns the
+model id alone. The TUI can still reject a pinned route against its provider's
+model catalog at startup; the status line, when on, then shows what it chose.
+
 **Environment.** `DSH_*` and `DEEPSEEK_*` are allowlisted for `envOverrides`
 (so `DSH_HOME`, `DSH_PERMISSION_MODE`, `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`
 all flow through). Provider keys with *other* names are deliberately not: a dsh

docs/multi-user-plan.md

@@ -158,7 +158,7 @@ Codeman now ships a global **Startup Mode** picker (App Settings, Claude CLI tab
 | `GET /api/away-digest`                                                     | Aggregate only owned sessions/events                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `GET /api/subagents`, workflow runs                                        | Filter by owning session (`claudeSessionId -> session -> owner`); agents not attributable to any session: admin-only                                                                                                                                                                                                                                                                                                                                      |
 | Push (`push-routes.ts`)                                                    | Subscription records currently carry NO identity (keyed by endpoint only): `subscribe` stamps `username`. All 8 `PUSH_EVENT_MAP` events are session-scoped, so routing = resolve owner from `data.sessionId`, deliver to that owner's (plus admins') subscriptions. Legacy identity-less subscriptions: admin-only delivery                                                                                                                               |
-| Screenshots `/api/screenshots`                                             | Per-user subdir `~/.codeman/screenshots/<username>/` in multi-user mode. Note: `GET /:name` deliberately rejects `/` in names as traversal, so derive the subdir server-side from `req.authUser` and keep client-visible names flat                                                                                                                                                                                                                       |
+| Screenshots `/api/screenshots` (deprecated)                                | Deprecated: removed in a later MAJOR, so no per-user subdir is planned; the replacement `POST /api/sessions/:id/paste-image` is already session-scoped. Former plan: per-user subdir `~/.codeman/screenshots/<username>/` in multi-user mode. Note: `GET /:name` deliberately rejects `/` in names as traversal, so derive the subdir server-side from `req.authUser` and keep client-visible names flat                                                  |
 | Attachments                                                                | Already session-scoped; inherits the session owner check. `attachmentConfineToWorkspace` is a global, default-OFF setting today: in multi-user mode it is FORCED ON for non-admins regardless of the setting (their attachments must resolve inside their own space); the setting keeps meaning what it means for admins                                                                                                                                  |
 | File routes (browse/preview)                                               | Path allowlist adds: non-admin paths must resolve (realpath) inside their own space or their own sessions' workingDirs                                                                                                                                                                                                                                                                                                                                    |
 | Settings (`settings.json`)                                                 | Global, admin-only writes in multi-user mode; reads allowed (per-device display keys stay in localStorage as today). Per-user server settings: out of scope v1                                                                                                                                                                                                                                                                                            |
@@ -228,7 +228,7 @@ These operate directly on `users.json` via `user-store.ts` (no server needed), h
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Default (no flag)  | No behavior change. No new file reads on the hot path. All new fields optional in state                                                                                                                     |
 | State round-trip   | `SessionState.owner`, `MuxSession.owner`, `CronJob.owner`, registry `owner` fields are optional; old state loads clean; new state loaded by an old build ignores unknown fields (existing tolerant parsing) |
-| Instance isolation | `users.json`, audit log, screenshots subdirs all via `dataPath()`; user spaces dir is shared across instances like `~/codeman-cases` is today (documented)                                                  |
+| Instance isolation | `users.json` and the audit log via `dataPath()`; user spaces dir is shared across instances like `~/codeman-cases` is today (documented)                                                                    |
 | API versioning     | HTTP API is internal per `docs/versioning-policy.md`; still, all changes are additive. Ship as a **minor** version                                                                                          |
 | Hooks              | Unchanged (instance-level hook secret; owner resolved from the session)                                                                                                                                     |
 

docs/omp-integration.md

@@ -163,9 +163,13 @@ remote user's home, so resolving locally would pin a stranger's id. See
 
 ## Known gaps
 
-- **No idle/completion hook.** Idle detection falls back to output-stabilization
-  like every other external CLI. If omp ever ships a hooks system, a Codeman hook
-  POSTing to `/api/hook-event` would be the highest-value follow-up.
+- **No idle/completion hook.** Idle detection reads the screen instead: the
+  registry entry's `workDetect` names omp's `╰─` input row as the glyph that arms
+  the idle check, and the status bar's spinner plus elapsed time (` ⠼ 14s > ⬢ …`)
+  or the `⎋ Working…` row as the working line, measured on omp 18.8.6 and 18.0.11.
+  Without it an omp session that had started a turn never left `busy`. If omp ever
+  ships a hooks system, a Codeman hook POSTing to `/api/hook-event` would still be
+  the highest-value follow-up.
 - **Killing a pane mid-turn loses the conversation for real.** `tmux kill-session`
   before an in-TUI `/exit` beats omp's own session-file flush — confirmed by direct
   testing (kill after a clean `/exit` resumes correctly; kill without `/exit` first

docs/opencode-integration.md

@@ -920,6 +920,8 @@ const mode = cmd.includes('opencode') ? 'opencode' : 'claude';
 
 > **DEFERRED**: This entire phase (except `waitForOpenCodeReady()`) is out of MVP scope. Idle detection, ANSI content filter, working/busy state tracking, and token parsing are all deferred until we have real PTY output data from stable OpenCode sessions. Only the basic TUI ready detection from `waitForOpenCodeReady()` is needed for the MVP and is included in Phase 3.
 
+> **Update 2026-10-09 (working/idle shipped, from measured data):** the registry entry now declares `capabilities.workDetect` for opencode, measured on a live opencode 1.3.0 pane (pane captures every 250-300 ms through real turns at 40, 60, 120 and 200 columns, plus the raw PTY stream). Every composer row starts with a `┃` bar, which arms the shared screen-probed idle check; a running turn puts an 8-cell knight-rider spinner (`⬝■■■■■■⬝  esc interrupt`) at the head of the footer row, redrawn about every 40 ms, and `[⬝■]{8}` is the working line. The label is not the anchor: tmux ships `esc` and `interrupt` as separate words joined by cursor moves, and below about 45 columns the footer wraps it. At rest the TUI is silent (no cursor or timer redraws), and a pending permission prompt replaces the composer and stops the spinner, so it reads as idle. Before this, a turn that ran a tool latched the session `busy` for good (the tool row's braille spinner tripped the generic spinner detector, and nothing ever armed the idle check). Token parsing and the ANSI content filter remain deferred.
+
 ### Goal
 Detect OpenCode's state from terminal output (idle, working, ready).
 

docs/pi-integration.md

@@ -223,9 +223,13 @@ command override instead.
 ## Known gaps
 
 - **No idle/completion hook.** Pi has no hook system Codeman can install into, so
-  idle detection falls back to output-stabilization like the other external CLIs.
-  Pi 0.84.0 shipped an `agent_settled` extension event that is a genuine idle
-  signal; a Codeman pi extension using it is the highest-value follow-up.
+  idle detection reads the screen: the registry entry's `workDetect` names pi's
+  composer rule (`─`) as the glyph that arms the idle check and the spinner pi embeds
+  in that rule while a turn runs (`── ⠏ Working ───`) as the working line, measured
+  on pi 1.1.0. Without it a pi session that had started a turn never left `busy`,
+  since pi never draws Claude's `❯`. Pi 0.84.0 shipped an `agent_settled` extension
+  event that is a genuine idle signal; a Codeman pi extension using it is still the
+  highest-value follow-up.
 - **No response viewer.** Pi writes JSONL v3 session files under
   `~/.pi/agent/sessions/`; nothing reads them yet.
 - **Cron jobs mis-detect readiness.** The cron readiness poll looks for `❯` or a

docs/scrollback-fix-plan.md

@@ -278,8 +278,8 @@ Touch is always-local by design, and Claude sessions keep content in the normal
 - The `terminalWheelLocalScrollback` opt-out setting keeps working (pins plain wheel to local).
 - The viewport-at-bottom gate stays: once the user scrolled up locally, wheel stays local until they return to bottom.
 - 40ms SGR coalescing: never send per-event writes to the server.
-- Strip parity triangle: `session.ts` live strip ↔ `session-routes.ts` replay strip ↔ `_sessionUsesServerMouseStrip()` in the frontend. If you touch mode lists, update all three.
-- Don't add `opencode`/`antigravity` to any strip/forward list; their TUI wheel behavior is unverified (documented at `_shouldForwardWheelToApp`).
+- Strip parity: `session.ts` live strip ↔ `stripReplayBuffer()` in `session-routes.ts`, both driven by the registry's `altScreen` value and pinned together for every stock CLI in `test/claude-scrollback-strip.test.ts`. The frontend keeps no mode list: `_shouldReportMouseToCli()` reads only the server-published `cliMouseTracking`.
+- Don't add `opencode`/`antigravity` to the wheel-FORWARD list; their TUI wheel behavior is unverified (documented at `_shouldForwardWheelToApp`). ⚠️ 2026-09-16: opencode's half is now MEASURED — 1.18.31 ignores SGR wheel reports but pages its transcript on PageUp/PageDown — so it belongs in the **paging** list (`_localScrollbackIsHollow`). ⚠️ It also joined a STRIP list that same day, for a different reason: `isMuxMouseStripMode` removes its mouse DECSETs so a drag selects text again (see `docs/architecture-invariants.md` §Three strip flavors). antigravity/grok/deepseek/omp remain unverified.
 - The chunk-boundary sequence carry in `_handleTerminalOutput` must not be weakened.
 
 ## Testing (per repo rules)

docs/security-architecture.md

@@ -354,8 +354,9 @@ is by id (`GET /api/sessions/:id/attachments/:attachmentId/raw`, same download c
 the `/root` and `/etc` trees, extendable via `attachmentBlockedPaths` /
 `CODEMAN_ATTACHMENT_BLOCKED_PATHS`) on every request. Unlike the workspace file
 routes, attachments are intentionally **cross‑workspace** — so the effective gate
-is the blocklist + a 6‑extension allowlist (`png/pdf/docx/pptx/md/txt`), not
-realpath containment.
+is the blocklist + an extension allowlist (`SUPPORTED_ATTACHMENT_EXTENSIONS` in
+`src/attachment-registry.ts`: images, pdf/docx/pptx/xlsx, audio/video, md/txt and
+other text), not realpath containment.
 
 Two registration paths, with **different trust**:
 

docs/split-pane-sessions-plan.md

@@ -4,6 +4,14 @@
 **Author**: Claude (session with Tim), 2026-09-15
 **Scope**: v1 only. v2 items are named and explicitly deferred, not designed.
 
+> **Update (tile grid, PR 1):** Pane B is now a `TerminalTile`
+> (`terminal-tile.js`) and is no longer as plain as this spec describes: it
+> reconnects after a drop, delivers input exactly once, has clickable paths
+> and image paste, sizes its PTY without a floor and adopts `zc` columns, and
+> the app-level terminal shortcuts follow the focused pane. Ctrl+W no longer
+> closes anything (Close Session has no default key).
+> See `docs/tile-grid-plan.md` and `architecture-invariants#split-pane-sessions`.
+
 ## Problem
 
 Codeman's terminal area shows exactly one active session (pane) at a time —
@@ -84,7 +92,15 @@ view needs a wide viewport). So:
   keyboard accessory bar. On a desktop, typing directly into an xterm
   instance with no overlay is exactly how Codeman behaved before the local-
   echo overlay existed for touch devices — normal, not degraded, for a
-  keyboard-and-mouse user.
+  keyboard-and-mouse user. (Since moved to `TerminalTile`, terminal-tile.js,
+  which has gained three pieces of the primary pane: hollow-buffer wheel
+  paging (#555) and the desktop click report for a CLI with
+  `cliMouseTracking` on, both through the primary pane's gates aimed at the
+  tile, and its own keyCode-229 soft-keyboard controller
+  (terminal-keycode229-recovery.js: the #441 next-keydown drain and #541's
+  edit-based diff, so an Android autocorrect is not sent twice). The 1180px
+  width gate is all that keeps a phone out, and a wide Android tablet clears
+  it. See that file's fileoverview.)
 
 If this asymmetry actually bothers you in daily use, promoting Pane B to full
 parity is a scoped v2 (extract the shared logic already once you have two

docs/terminal-copy-shortcut-plan.md

@@ -82,6 +82,7 @@ This is exactly how `command-palette` already behaves: it is a full registry ent
 
 - The server strips mouse-tracking DECSETs for `claude`, `codex`, and `gemini` (`isAltScreenStripMode`, `src/session.ts:179`), which is why plain drag-select works in those tabs even though the TUI has mouse tracking on.
 - `shell`, `opencode`, and `antigravity` keep mouse reporting, so xterm requires `Shift`+drag to force a selection there. Worth one line in the docs, it is not a code change.
+  ⚠️ **Corrected 2026-09-16:** `opencode` no longer keeps mouse reporting in the browser. Its TUI enables tracking DECSETs, tmux `mouse off` passes them through to the tmux client, and xterm then reported DRAGS to the TUI instead of selecting — so `Shift`+drag was the only way to select, and a plain drag silently copied nothing (measured 62 `none` / 18 `any` over 16s; 5/5 dead drags while `any`). The server now strips those DECSETs (`isMuxMouseStripMode`), so a plain drag selects in opencode. `shell` and `antigravity` are unchanged.
 - Touch devices deliberately disable selection entirely (`body.touch-device .terminal-container .xterm{user-select:none !important}`, `styles.css:3196`), and phones have no Ctrl key. This feature is desktop and hardware-keyboard only, with no mobile regression surface.
 
 ### 2.6 Helpers that already exist and should be reused
@@ -245,7 +246,7 @@ The shortcut overlay (`Ctrl+?`) and App Settings -> Shortcuts are registry-drive
 | Whitespace-only or empty selection | `getSelection()` empty string is treated as "no selection", so Ctrl+C still interrupts |
 | macOS Cmd+C | registry treats ctrl/meta as interchangeable, so with a selection it takes our path (same visible result as today's native copy), without one it falls through |
 | Chrome/Firefox `Ctrl+Shift+C` is the devtools inspect chord | browser-level and may still toggle devtools, our copy runs regardless. Document as a caveat, `Ctrl+C` is the primary path |
-| Selection in a tab whose TUI owns the mouse (`shell`/`opencode`/`antigravity`) | unchanged, `Shift`+drag selects, then Ctrl+C copies |
+| Selection in a tab whose TUI owns the mouse (`shell`/`antigravity`; `opencode` left this list on 2026-09-16 — its DECSETs are stripped now) | unchanged, `Shift`+drag selects, then Ctrl+C copies |
 | Web tab (iframe dashboard) focused | xterm handler never runs, browser-native copy inside the iframe |
 | Teammate/subagent terminals (`panels-ui.js:2268`, `onData` wired) | same limitation exists there, out of scope for this PR (section 8) |
 
@@ -281,7 +282,7 @@ Against a throwaway session on the live instance (`curl -sk https://localhost:30
 3. Type a few characters with local echo on (phone or `localEchoEnabled` forced), press Ctrl+C with no selection, confirm buffered text plus interrupt behave as before.
 4. Uncheck the shortcut in App Settings -> Shortcuts, confirm Ctrl+C always interrupts even with a selection.
 5. Rebind it, confirm the new chord copies and Ctrl+C reverts to pure interrupt.
-6. Repeat 1 and 2 in an `opencode` or `shell` tab using Shift+drag to select.
+6. Repeat 1 and 2 in a `shell` or `antigravity` tab using Shift+drag to select (`opencode` selects with a plain drag since 2026-09-16).
 7. Load over plain HTTP (`--host` LAN or `http://127.0.0.1:<port>`) and confirm the `execCommand` fallback copies and focus returns to the terminal.
 8. Mobile smoke: confirm nothing changed (selection is CSS-disabled, no Ctrl key).
 

docs/versioning-policy.md

@@ -57,8 +57,10 @@ These may change in a **MINOR** (or even PATCH) release without a MAJOR bump:
    programmatically is not supported (there is no stable library entry point).
 3. **Experimental / opt-in features**, regardless of the app's version:
    Gesture Control (beta), Agent Teams
-   (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), and anything labeled experimental
-   in the UI or docs. These may change or be removed at any time.
+   (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), the native-wrapper window bridge
+   (`window.CodemanHost.openWindow` / `closeWindow` / `focusWindow`), and
+   anything labeled experimental in the UI or docs. These may change or be
+   removed at any time.
 
 ## Deprecation policy
 

docs/wiki/Agent-CLIs.md

@@ -69,7 +69,7 @@ output. The other CLIs expose no equivalent.
 | Respawn cycling and unattended runs               | Yes    | Yes                                                  |
 | Cron jobs                                         | Yes    | Yes                                                  |
 | Docker cases, remote SSH cases                    | Yes    | Yes                                                  |
-| Precise idle detection                            | Yes    | Codex: same screen check, via its own prompt and working line. DeepSeek: reports its state itself. Others: output stabilization, coarser |
+| Precise idle detection                            | Yes    | Codex, Pi, OpenCode, OMP and Gemini: same screen check, via their own prompt and working line. DeepSeek: reports its state itself. Others: output stabilization, coarser |
 | Auto-resume when a usage limit resets             | Yes    | No                                                   |
 | Plan usage chip                                   | Yes    | No                                                   |
 | Approvals Inbox                                   | Yes    | DeepSeek yes; others no                              |
@@ -121,10 +121,24 @@ Renders its own TUI, so Codeman treats readiness as output stabilization rather
 watching for a prompt marker. Requires tmux, with no direct-PTY fallback, because its
 environment is injected through socket-scoped `tmux setenv` rather than the command line.
 
+Working and idle come from the screen: while a turn runs, OpenCode draws a small spinner at
+the start of its footer (`⬝■■■■■■⬝  esc interrupt`), and Codeman reads that to tell a working
+session from an idle one. A pending permission prompt shows as idle, since it is waiting on
+you. Before 1.40.0 an OpenCode session that had run a tool showed as working for good.
+
 Integration detail: [`docs/opencode-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/opencode-integration.md).
 
 ### Codex
 
+App Settings has synced **Default Codex model** and **Default Codex reasoning effort**
+controls. Enter a model ID supported by your Codex provider; available reasoning levels
+depend on the model and CLI version. Empty defaults use Codex's own configuration.
+The defaults apply to local Codex sessions started from the Run menu, from Resume, and through
+`POST /api/sessions` or `/api/quick-start`; scheduled (cron) jobs do not use them.
+Explicit `codexConfig.model` / `codexConfig.reasoningEffort` values take precedence.
+Custom model endpoints, Docker containers and remote host command overrides keep their own settings.
+Changing a default affects new sessions and does not edit Codex configuration files.
+
 Two behaviours that are deliberate and worth knowing:
 
 - **Predictive echo instead of buffered echo.** Codex's composer reacts to every keystroke,
@@ -148,6 +162,11 @@ needs `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS`, and
 `GOOGLE_GENAI_USE_VERTEXAI`. That is the loosest allowlist entry in Codeman and it affects
 only the CLI you spawned yourself.
 
+Working and idle come from the screen: while a turn runs, Gemini CLI draws a spinner line
+(`⠦ Thinking... (esc to cancel, 6s)`) above its composer, and Codeman reads that. A tool
+confirmation that waits for you shows as idle. Before 1.40.0 a Gemini session showed as
+working for good after its first turn.
+
 ### Antigravity
 
 Google's successor to the consumer Gemini CLI, invoked as `agy`. It keeps all of its state
@@ -169,6 +188,10 @@ Pi needs the opposite instincts from every other CLI here.
   `HF_TOKEN`, and so on) share no common prefix, and the environment allowlist is global
   rather than per mode, so admitting them for Pi would widen the allowlist for every mode at
   once. They stay out.
+- **Work detection reads Pi's composer rule.** Pi has no prompt glyph; while a turn runs it
+  puts a spinner into the rule above the composer (`── ⠏ Working ───`), and Codeman reads
+  that to tell working from idle. Before 1.40.0 a Pi session that had started a turn showed
+  as working for good.
 
 Guide: [`docs/pi-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/pi-integration.md).
 
@@ -222,7 +245,9 @@ documented default approval mode is `yolo`, so an OMP pane auto-approves tool us
 flag from Codeman; change that in OMP's own config, not here.
 
 OMP conversations appear in Past Sessions and can be resumed, and a respawn continues the
-same conversation with `--continue`.
+same conversation with `--continue`. Codeman tells working from idle by reading OMP's status
+bar, where a spinner and the elapsed time replace the `π` while a turn runs. Before 1.40.0
+an OMP session that had started a turn showed as working for good.
 
 Guide: [`docs/omp-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/omp-integration.md).
 

docs/wiki/Contributing.md

@@ -43,8 +43,8 @@ npm run lint
 npm run format:check
 npm run check:frontend-syntax
 npm run check:browser-excludes
-npm test -- test/<file>.test.ts   # one file, the normal way
-npm run test:ci                    # the full CI sweep
+npm test                          # the gate, exactly what CI runs
+npm test -- test/<file>.test.ts   # one file
 ```
 
 `npm install` installs a `pre-push` git hook that runs the static checks above (about 10-40s,
@@ -53,13 +53,19 @@ something other than the checked-out HEAD, or when the tree has uncommitted chan
 checks would read. Skip it once with `CODEMAN_SKIP_PREPUSH=1 git push`; a
 `pre-push` hook of your own is never overwritten.
 
-**Never run bare `npm test`.** The default configuration includes browser-driven Playwright
-suites that need a live server, Chromium, and environment-specific baselines; they hang or
-fail on a normal machine. `test:ci` is the honest "run everything".
+`npm test` runs the same suite CI runs, so a green run locally means a green run there. It
+leaves out three suites that cannot pass on an arbitrary machine, each with its own command:
+`npm run test:browser` (Playwright, Chromium and a live server), `npm run test:mobile` (the
+same plus environment-specific screenshot baselines) and `npm run test:perf` (wall-clock
+benchmarks for an otherwise idle machine). Expect those to fail where the machine cannot
+provide what they need; that means "not runnable here", not a regression.
 
 Tests are tmux-safe by design: under vitest the tmux layer becomes an in-memory mock, so
-tests cannot touch real sessions. If you add a test that binds a port, pick a unique one at
-3150 or above, and never 3000.
+tests cannot touch real sessions. If you add a test that binds a port, bind port 0
+(`new WebServer(0, …)` + `server.boundPort`, or `listen({ port: 0 })` + `address().port`),
+or use `app.inject()` when no socket is needed. Never 3000. Mobile tests (`test/mobile/**`,
+via `createTestServer(PORT)`) keep the fixed ports in `test/mobile/README.md` for now,
+because that helper caches servers by port.
 
 ## Finding your way around
 

docs/wiki/Core-Concepts.md

@@ -15,11 +15,12 @@ Codeman-side configuration:
 - Per-case toggles (Agent Teams, 1M Opus context).
 - Where it runs, if it is not the local filesystem: see [Location overlays](#location-overlays).
 
-Three ways to get one, all under **+** next to the case picker:
+Three ways to get one, all under **New or link a case…** at the bottom of the case picker
+(the case dropdown in the bottom toolbar; on a phone, the case sheet's **Create New Case**):
 
 | How               | Result                                                                                                 |
 | ----------------- | ------------------------------------------------------------------------------------------------------ |
-| **Create New**    | A fresh `~/codeman-cases/<name>` with a scaffolded `CLAUDE.md`.                                          |
+| **Create New**    | A fresh `~/codeman-cases/<name>` with a scaffolded `CLAUDE.md`, or with **Create in a custom folder**, a new folder inside a parent you choose, scaffolded the same way and registered in place like a linked case. |
 | **Clone Repo**    | A repo cloned into `~/codeman-cases/<name>` and registered as a case. Private repos need this machine's own git credentials (see below). |
 | **Link Existing** | An existing folder anywhere on disk, registered in place. Nothing is copied or moved.                    |
 

docs/wiki/Driving-Codeman-From-An-Agent.md

@@ -189,7 +189,7 @@ followed by a wait races, and reports the previous turn's state.
 ## Lineage
 
 A create request can name the session that spawned it, through a body field or a header, and
-the dashboard then draws a lineage arc from parent to child. The skill sets it automatically.
+the dashboard then draws a lineage line from parent to child. The skill sets it automatically.
 
 It is resolved rather than trusted: an unresolvable parent is dropped silently rather than
 failing the spawn, because a cosmetic field must never break a worker.

docs/wiki/Home.md

@@ -62,7 +62,9 @@ codeman web    # then open http://localhost:3000
 | Page                                       | What it answers                                            |
 | ------------------------------------------ | ---------------------------------------------------------- |
 | [The Dashboard](The-Dashboard)             | What is the UI telling me?                                 |
+| [Tile Grid](Tile-Grid)                     | How do I watch and drive several sessions side by side?    |
 | [Agent CLIs](Agent-CLIs)                   | Which agent should this session run, and how do I set it up? |
+| [Custom Model Endpoints](Custom-Model-Endpoints) | How do I point a session at my own OpenAI-compatible endpoint? |
 | [Working With Files](Working-With-Files)   | How do I read, edit, and attach files?                     |
 | [Input And Voice](Input-And-Voice)         | How do I talk to an agent, including by voice?             |
 | [Mobile Guide](Mobile-Guide)               | How well does this work on a phone?                        |

docs/wiki/Keyboard-Shortcuts.md

@@ -9,13 +9,16 @@ Press `Ctrl+?` in the app for the same list in a floating overlay.
 | Shortcut                        | Action                                                          |
 | ------------------------------- | --------------------------------------------------------------- |
 | `Ctrl+K` (also `Cmd+K`, `Alt+K`)| Find an open session or start a new one.                         |
-| `Ctrl+W`                        | Kill the active session.                                         |
 | `Ctrl+Tab`                      | Next session.                                                    |
 | `Alt+[` / `Alt+]`               | Previous / next tab.                                             |
 | `Alt+1` to `Alt+9`              | Switch to tab N. Physical keys, so macOS Option layouts work.    |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move the active tab left / right.                                |
 | `Alt+B`                         | Collapse / expand the session sidebar, when that layout is on.    |
 
+`Ctrl+W` is not a Codeman shortcut: it goes to the terminal, where shells and agent CLIs
+use it to delete the previous word. **Close Session** has no key by default; close a session
+from its tab, or bind a key to it in App Settings → Shortcuts.
+
 ## Terminal
 
 | Shortcut                | Action                                                          |
@@ -36,6 +39,22 @@ Press `Ctrl+?` in the app for the same list in a floating overlay.
 
 Anything you copy is cleaned on the way to the clipboard: each line loses the padding spaces a full-screen program paints across the rest of the row. Leading indentation is left exactly as it is, so indented code, a `git log` message body and `git diff` context lines paste back the way they looked on screen. An `Alt+drag` rectangular selection is copied exactly as it looks, so its columns stay lined up.
 
+## Tile grid
+
+| Shortcut                    | Action                                                       |
+| --------------------------- | ------------------------------------------------------------ |
+| `Ctrl+Shift+G`              | Open or close the tile grid (needs the Tiles setting on).     |
+| `Alt+Shift+Arrows`          | Focus the tile to the left, right, above or below.            |
+| `Ctrl+Shift+Arrows`         | Move the focused tile one place: into an empty slot, or swap. |
+| Drag a tile's header        | Move the tile: onto another tile they swap, onto an empty slot it moves there. |
+| `Alt+Shift+Enter`           | Zoom the focused tile, or restore the grid.                   |
+| `Ctrl`+click / `Cmd`+click a tab | Add that session to the grid.                            |
+| Right-click the Tiles button | Choose how many tiles: 2, 4 or 6 (remembered).           |
+
+While the grid is open, `Ctrl+Tab` and `Alt+[` / `Alt+]` cycle through the tiles, and the
+terminal shortcuts above act on the focused tile. **Remove Focused Tile** has no key by
+default. See [Tile Grid](Tile-Grid).
+
 ## Everything else
 
 | Shortcut       | Action                          |

docs/wiki/Mobile-Guide.md

@@ -158,7 +158,7 @@ enough to fix a typo an agent introduced while you are away from your desk.
   enforces it.
 - The Approvals bell. Phones get the NEEDS YOU strips on the home screen instead.
 - The desktop home tab rail, which needs a wide window.
-- Lineage arcs, which are a desktop overlay.
+- Lineage lines, which are a desktop overlay.
 
 ## Gotchas
 

docs/wiki/Quick-Start.md

@@ -42,7 +42,7 @@ To make a new one, click **+** next to the picker. The Add Case dialog has three
 
 | Tab               | Use it when                                                                                                        |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
-| **Create New**    | Starting a fresh project. Creates `~/codeman-cases/<name>` and scaffolds a `CLAUDE.md` into it.                     |
+| **Create New**    | Starting a fresh project. Creates `~/codeman-cases/<name>` and scaffolds a `CLAUDE.md` into it. Tick **Create in a custom folder** to put it somewhere else instead. |
 | **Clone Repo**    | Working on an existing repo: public, or private once this machine's git can authenticate (the Docker image can include `gh`/`az` helpers for this). Paste the URL; Codeman preflights it as you type, offers the repo's real branches and tags, and fills in the case name. |
 | **Link Existing** | The code is already on disk. Point at the folder, with **Browse** if you would rather click than type.               |
 
@@ -131,7 +131,7 @@ the tmux server or rebooting the machine.
 | To do this                | Do that                                                             |
 | ------------------------- | ------------------------------------------------------------------- |
 | Interrupt the current turn | `Ctrl+C` with nothing selected, or the **Stop** button.            |
-| Close one session          | `Ctrl+W`, or the tab's close control.                              |
+| Close one session          | The tab's close control (`Ctrl+W` is delete-word in the terminal). |
 | Stop the server, keep agents | `codeman web --stop`. The tmux sessions stay alive.              |
 | Stop everything            | `tmux -L codeman kill-server`.                                     |
 

docs/wiki/Settings-Reference.md

@@ -57,14 +57,30 @@ supervised by systemd or launchd; npm installs report as non-updatable. See
 Chips for every optional header control, with a live preview of the resulting header:
 
 Run, Font Size, System Stats, Redraw Terminal, Response Viewer, Away Digest, Session
-Manager, Attachments, File Viewer, Multi-monitor, Split, Plan Usage, Lifecycle Log, Monitor,
+Manager, Attachments, File Viewer, Multi-monitor, Split, Tiles, Plan Usage, Lifecycle Log, Monitor,
 Project Insights, File Browser, Subagents, Approvals Inbox, Read My Mind, Ultracode Agents,
 Ultracode Windows, Cron.
 
-Most default to off. The stock desktop header is system stats, File Viewer, and the gear.
+**Bottom bar** (below the chips): **Git status** shows a small indicator at the right of the
+bottom bar, off by default and per device. It reads `● N` uncommitted files, `↑ N` commits not
+pushed, `⚠ N` merge conflicts, `? N` repositories git could not read, or `✓` when everything is
+committed and pushed. Click it for the Git window; see
+[Working With Files](Working-With-Files#git-changes). **Git status: group files
+by folder** (per device, on by default) shows changed files under collapsed folders in that
+window; off lists every file by its full path. **Git status: max repositories** (per device,
+1 to 50, default 12) is how many repositories the window lists when a session's folder holds
+several projects. **Git status: git timeout** (per device, 5 to 120 seconds, default 30) is how
+long one git command may run before that repository is reported as unreadable; raise it for
+repositories on a slow network share.
+
+Most default to off. The stock desktop header is system stats, File Viewer, Tiles, and the gear.
+**Header Stats Style** picks how the system stats and plan usage are drawn: *Compact*
+(default; two pills with a ring beside every value), *Tiles* (label over value with a bar underneath) or *As before* (the bars and the `5H · 7D` chip). Desktop only, per device.
 New header controls never appear on phones. Split is desktop-only regardless of this
 setting — the button and the feature both stay off below a ~1180px viewport, where two
-resizable panes plus their divider have nowhere to go.
+resizable panes plus their divider have nowhere to go. **Tiles** is desktop-only the same
+way; it also enables the `Ctrl+Shift+G` grid toggle on this device. See
+[Tile Grid](Tile-Grid).
 
 This section also holds background-agent tracking, including whether to track agents for
 every session or only the active tab.
@@ -79,10 +95,13 @@ every session or only the active tab.
 | Interface Language     | English or Simplified Chinese. Per device.                                                 |
 | Session List Layout    | Header tab strip (default), a collapsible left sidebar, or the sidebar with detailed rows. See [The Dashboard](The-Dashboard#session-list-layout). |
 | Tab Orientation        | Keeps the header list but turns the strip vertical beside the terminal, resizable, with detailed rows by default. Desktop and tablet only. |
-| Vertical Rail Order    | *By activity* (default) sorts the rail the way the home screens are sorted; *Manual* keeps your tab order and drag-reordering. |
+| Tab Layout             | *Classic* (default): the single list as before. *By state*: a row each for needs you, waiting, working and idle, sections in the rail and sidebar. *By case*: one box per case. *Ledger*: an aligned column grid. See [The Dashboard](The-Dashboard#tab-layouts). |
+| State Order            | For *By state*: needs you on top (default) or at the bottom, right above the terminal. |
+| Vertical Rail Order    | *By activity* (default) sorts the rail the way the home screens are sorted; *Manual* keeps your tab order and drag-reordering. With *By state* or *By case* it orders the rows inside each section. |
 | Tall Tabs              | Taller tab strip.                                                                          |
+| CLI Logos on Tabs      | Each agent tab, and its row on the desktop home rail, shows the CLI's logo before the name. Off hides those logos on this device; the status dot and the shell's SH badge stay, and tiles, split headers and the Run menus keep their logos. On by default. |
 | Pop-out Button on Tabs | Adds the detach control to tabs, with a per-tab override.                                  |
-| Spawn Lineage Lines    | Arcs from a parent tab to sessions it spawned. Desktop only, on by default.                |
+| Spawn Lineage Lines    | Lines from each tab to the sessions it spawned; the selected tab's family is drawn thicker. Desktop only, on by default. |
 | Auto-name Sessions     | Titles a new tab after its first prompt, keeping the case prefix (`w3-myapp: fix the login redirect`). Synced, off by default. See [The Dashboard](The-Dashboard#automatic-session-names). |
 | Overview Home Screen   | The phone home screen. On by default.                                                      |
 
@@ -120,7 +139,9 @@ instead of its native cloud backend. See [Custom Model Endpoints](Custom-Model-E
 | Codeman Agent Skill              | Injects the agent skill into new Claude sessions per case. Off by default. See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent). |
 | Remote auto-reconnect            | Reattaches dropped remote SSH sessions. On by default.                                         |
 | Nice priority / value            | Runs agent processes at a lower CPU priority.                                                  |
-| Bypass approvals and sandbox     | Pi's project trust. Read [Agent CLIs](Agent-CLIs) before enabling.                             |
+| Default Codex model              | Model for new local Codex sessions; empty uses Codex's own config. Letters, digits, `.` `_` `-` `/` only. |
+| Default Codex reasoning effort   | Reasoning level for new local Codex sessions; empty uses Codex's own config.                   |
+| Bypass approvals and sandbox     | Starts new Codex sessions with `--dangerously-bypass-approvals-and-sandbox`. Read [Agent CLIs](Agent-CLIs) before enabling. |
 | Animated status effects          | Cosmetic.                                                                                      |
 | MCP server sync                  | Copies the MCP servers each installed, enabled CLI (Claude, Codex, Gemini, OpenCode, Antigravity) has into the others' own config files. Synced, off by default, admin only in multi-user mode. Turn it on and save, then **Preview** shows what would change and **Sync now** applies it. It only adds missing servers, keeps the previous file as `.codeman-bak`, and leaves a file that receives env values or headers readable by you only. A config dir moved by `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME` or `GEMINI_CLI_HOME` in Codeman's own environment is followed. |
 
@@ -145,8 +166,10 @@ Rebinding for the shortcut registry. See [Keyboard Shortcuts](Keyboard-Shortcuts
 ### System
 
 `CLAUDE.md` template for new cases, default working directory, the image watcher, and
-Cloudflare tunnel controls including the tunnel and upload URLs. In multi-user mode, the
-**Users** administration entry is injected here.
+Cloudflare tunnel controls including the tunnel URL. The **Diagnostics** group runs
+`codeman doctor` on the server and lists the agent CLIs, tmux, Node and the optional office
+tools with their versions and install hints (admin only in multi-user mode). In multi-user
+mode, the **Users** administration entry is injected here.
 
 ## Session Options
 
@@ -181,6 +204,8 @@ Some things are configured before the server starts, not in the UI:
 | `CODEMAN_BASE_URL`                  | Mounts Codeman under a sub-path behind a reverse proxy that forwards the prefix unchanged. See [Remote Access](Remote-Access). |
 | `CODEMAN_MAX_DOWNLOAD_BYTES`        | Cap on raw file bodies and downloads. 2 GB by default, `0` for none.    |
 | `CODEMAN_MAX_REMOTE_FILE_SSH`       | Concurrent ssh reads for files in remote cases. 4 by default.           |
+| `CODEMAN_PATH_PROBE_TIMEOUT_MS`     | How long a linked case's folder may take to answer before it is shown as unreachable. 1500 ms by default; raise it for a slow but healthy mount. |
+| `CODEMAN_PATH_PROBE_MAX_STALLED`    | Unanswered folder checks allowed to pile up before new ones are refused. 2 by default: one below the threadpool size minus one, so it follows `UV_THREADPOOL_SIZE` (4 unless set), and it is never allowed above that ceiling. A check you start by opening one case or session may use the one slot left above it. |
 
 ## Gotchas
 

docs/wiki/The-Dashboard.md

@@ -15,7 +15,7 @@ page says so and names the setting.
 | **Header, left**   | The "C" logo (goes home) and the session list, unless you moved it to the sidebar.       |
 | **Header, right**  | Status chips and panel buttons, most of them off by default.                            |
 | **Center**         | The terminal for the active session, or the home screen when nothing is selected.        |
-| **Bottom toolbar** | Run, Stop, Run Shell, the case picker, and the instance counters.                        |
+| **Bottom toolbar** | Run, Stop, Run Shell, the case picker, and the instance counter.                         |
 | **Overlays**       | Panels and modals: Respawn, Cron, Subagents, File Viewer, Settings.                      |
 
 ## Session list layout
@@ -27,18 +27,56 @@ Session List Layout** can move it into a vertical sidebar on the left instead, a
 
 | Layout               | Behaviour                                                                       |
 | -------------------- | --------------------------------------------------------------------------------- |
-| **Header tab strip** | The default. Wraps to a second row on desktop, scrolls sideways on a phone.        |
+| **Header tab strip** | The default. One list in tab order unless you pick another [Tab layout](#tab-layouts); it scrolls sideways on a phone. |
 | **Left sidebar**     | A vertical list with a filter box and a live session count. `Alt+B` collapses it to a narrow rail that keeps the status dots and task badges visible. On a phone it is an off-canvas drawer rather than a docked rail. A detailed variant adds the home screen's per-session line (`created 3d ago · working 12m`) and a status pill. |
-| **Vertical rail**    | The strip turned vertical beside the terminal, resizable, with detailed rows by default. **Vertical Rail Order** sorts it by activity (blocked on you first, then longest running, then most recently quiet), the same order as the home screens; pick *Manual* to get your own order and drag-reordering back. Desktop and tablet only. |
+| **Vertical rail**    | The strip turned vertical beside the terminal, resizable, with detailed rows by default. **Vertical Rail Order** sorts it by activity (blocked on you first, then longest running, then most recently quiet), the same order as the home screens; pick *Manual* to get your own order and drag-reordering back. **Tab groups:** pick *Move to new group* from a row's ⋯ menu (or Shift+F10 on it) to make the first one; a group header's menu (right-click, Shift+F10 or its ⋯ glyph) renames it (also F2), reorders or deletes it, rows move between groups from their own menu or by dragging with a mouse or pen, and a collapsed group stays collapsed on that device. Desktop and tablet only. |
 
 It is the same list either way, just re-hosted: tab order, drag-to-reorder, the `Alt+1`
 to `Alt+9` numbers and every status colour below behave identically in both. The setting is
 per device, so a sidebar on your desktop does not force one onto your phone.
 
+## Tab layouts
+
+**App Settings → Appearance → Tabs → Tab Layout** picks how the tabs are arranged. Per device.
+
+| Layout                 | What it does                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| **By state**           | Groups the tabs by what each session needs from you (below).                         |
+| **By case**            | One box per case, labelled with the case and its tab count. Inside a box, `w75-api-gateway` reads just `w75`. A case with one tab gets a box with a colour swatch. |
+| **Ledger**             | The same list on an aligned column grid: equal cells, monospace names, a coloured bar on the left of each cell instead of the dot (yellow waiting, red needs you). Desktop header only. |
+| **Classic** (default)  | The single list in tab order, as before.                                             |
+
+**By state** groups the tabs like this, most urgent on top:
+
+| Group         | Who is in it                                                                        |
+| ------------- | ----------------------------------------------------------------------------------- |
+| **Needs you** | Red: a question or permission prompt is blocking the agent. A failed session too.   |
+| **Waiting**   | Yellow: the agent finished its turn and is waiting for your next prompt.            |
+| **Working**   | A turn is running.                                                                  |
+| **Idle**      | Everything quiet, including ended sessions, agents that exited inside their pane, and web tabs. |
+
+In the header each group is a row with its name and count on the left (Idle, the quiet
+default, carries no label); a group with more tabs than fit on one line continues on the
+next line. **State Order → Needs you at the
+bottom** turns the rows the other way up, so the needs-you row sits right above the
+terminal. Empty groups are not shown. These are the same states the phone overview and the
+desktop home rail use, and tabs move between groups on their own as their state changes.
+
+Both groupings also apply to the vertical rail and the left sidebar, as labelled sections.
+Inside a group or a box tabs keep your tab order (on a rail sorted *By activity*, the
+activity order), and the `Alt+1` to `Alt+9` numbers never change. Dragging reorders tabs
+within a group or box. On a phone the strip stays a single scrolling row in group order,
+without labels or boxes. If you have named tab groups in the vertical rail, those take
+precedence there.
+
 ## Session tabs
 
 One tab per session, in your order, and that order syncs across your devices.
 
+An agent tab shows its CLI's logo before the name, and a shell tab an `SH` badge. **CLI Logos
+on Tabs** (App Settings → Appearance → Tabs) hides the logos on that device; the tile and split
+headers and the Run menus keep theirs.
+
 **Status is carried by the dot and the tab's own styling:**
 
 | Look                          | Meaning                                                                 |
@@ -64,7 +102,7 @@ reloading while a permission prompt is blocking does not lose the red tab.
 | Jump to tab N                   | `Alt+1` to `Alt+9` (the number on the tab)              |
 | Next / previous                 | `Ctrl+Tab`, `Alt+[`, `Alt+]`                            |
 | Move the active tab             | `Ctrl+Shift+{`, `Ctrl+Shift+}`                          |
-| Close                           | `Ctrl+W`                                                |
+| Close                           | The tab's close control (no key by default)            |
 | Find any session, open or past  | `Ctrl+K` (also `Cmd+K` and `Alt+K`)                     |
 
 Tabs can also be dragged to reorder.
@@ -84,13 +122,18 @@ title is derived locally from the prompt's first sentence; no text leaves the ma
 On phones the strip scrolls horizontally instead of wrapping, and the active tab is always
 scrolled into view. It is not reordered to the front, so the `Alt+N` numbering stays stable.
 
-### Lineage arcs
+### Lineage lines
 
 When one session spawns another (an agent starting a worker through the API), Codeman draws
-a coloured arc under the strip connecting parent to child, with one colour per child. It is
-how a fan-out of eight workers stays readable.
+lines from the parent to each child, in the parent's colour, routed through the gaps between
+tab rows so they never cover a tab or the terminal. Every family is always shown; selecting
+a tab draws its own family thicker and brighter. A dashed branch means that child is
+working. It is how a fan-out of eight workers stays readable.
 
-Desktop only, and on by default. Turn it off in **App Settings → Appearance**. Arcs are
+While any tab has spawned another, the strip keeps a little extra room between rows for the
+lines, so switching tabs never changes the header height.
+
+Desktop only, and on by default. Turn it off in **App Settings → Appearance**. Lines are
 skipped for tabs scrolled out of the strip.
 
 ## Header controls
@@ -102,7 +145,7 @@ The right side of the header. Almost all of these are off until you enable them
 | ---------------------- | ------------------ | ------------------------------------------------------------------------------- |
 | Connection dot         | Always on          | SSE connection health. Green is connected.                                       |
 | Font size `-` / `+`    | Always on          | `Ctrl +` / `Ctrl -` do the same.                                                 |
-| CPU / MEM bars         | On                 | Server resource use.                                                             |
+| CPU / MEM              | On                 | Server resource use. Drawn as a compact pill by default; see Header Stats Style below. |
 | File Viewer            | On                 | Toggles the file browser panel.                                                  |
 | Settings gear          | Always on          | App Settings.                                                                    |
 | Plan usage chip        | On, desktop only   | Live Claude subscription usage. Claude-only, and needs its telemetry exporter, which the same setting installs. |
@@ -118,12 +161,33 @@ The right side of the header. Almost all of these are off until you enable them
 | Cron ⏰                | Off                | Scheduled jobs.                                                                   |
 | Multi-monitor          | Off, macOS         | Opens a window spanning every display.                                            |
 | Split                  | Off, desktop only  | View a second session beside the active one, with a draggable divider.           |
+| Tiles                  | On, desktop only   | Up to six live sessions side by side. See [Tile Grid](Tile-Grid).                |
 | Tunnel indicator       | When a tunnel runs | Cloudflare tunnel status.                                                        |
 | Admin panel            | Multi-user only    | User administration.                                                              |
 
+### Header Stats Style
+
+The connection readout, CPU, MEM and the plan usage windows can be drawn three ways
+(**App Settings → Header & Panels → Header Stats Style**, per device, desktop only):
+
+| Style          | Look                                                                                   |
+| -------------- | -------------------------------------------------------------------------------------- |
+| **Tiles**      | One small tile each (`WS live`, `CPU 22%`, `MEM 14.4G`, `5H 28%`, `7D 35%`): label over value, a thin bar underneath, no icons. |
+| **Compact**    | The default. Two slim pills, `WS · CPU · MEM` and the plan windows, with a small ring beside every value. Hands the tabs back the most room. |
+| **As before**  | The bars and the `5H · 7D` chip, exactly as they were.                                 |
+
+Hiding System Stats or Plan Usage still hides them in every style.
+
 New header controls never appear on phones. Phone layout is deliberately minimal and is
 covered in [Mobile Guide](Mobile-Guide).
 
+## Bottom bar
+
+**Git status** sits at the right of the bottom bar and shows the active session's uncommitted
+and unpushed work. It is off by default and per device: turn it on in **App Settings → Header &
+Panels → Bottom bar**. Click it for the Git window. See
+[Working With Files](Working-With-Files#git-changes).
+
 ## Connection state
 
 The dot in the header is the quick read. Two louder surfaces exist because a cached page
@@ -158,7 +222,9 @@ Worth knowing:
   Claude runs fullscreen (`CLAUDE_CODE_NO_FLICKER=1`, or `"tui": "fullscreen"` in
   `~/.claude/settings.json`), so the wheel scrolls the conversation rather than the terminal.
   Claude's default inline view keeps its history in the terminal and scrolls locally. `Shift+Wheel` is
-  always local scrollback. Other CLIs scroll locally.
+  always local scrollback. OpenCode's wheel and swipes page its own conversation
+  (PageUp/PageDown); in a grid tile or the split view's second pane the wheel does
+  too. Other CLIs scroll locally.
 - **Selection copy.** `Ctrl+C` copies when text is selected and interrupts when it is not.
   `Ctrl+Shift+C` always copies.
 - **Selecting where the CLI owns the mouse.** `Shift+drag` starts a selection even in a pane

docs/wiki/Tile-Grid.md

@@ -0,0 +1,137 @@
+# Tile Grid
+
+Watch and drive up to six sessions at once, side by side in one window. Each tile is a
+full live terminal: it reads, it takes your keystrokes, and it shows at a glance whether
+its agent is working, idle, or waiting on you.
+
+The grid is a desktop feature. It needs a window at least about 1180px wide, and it is
+never offered in a popped-out session window.
+
+## Turning it on
+
+**App Settings → Header & Panels → Tiles.** This is a per-device setting, on by default
+on desktops and laptops and off on phones and tablets, and the button only appears in a
+window at least 1180px wide.
+It shows a **Tiles** button in the header, beside Split, and enables `Ctrl+Shift+G`.
+
+## Opening a grid
+
+- **Tiles button**: one click shows the tiles straight away, as many as you last chose
+  (six until you choose; fewer if the window is too small or you have fewer sessions open).
+  You get the grid you last had, its tiles where they were, topped up with your open
+  sessions in tab order; if there is none, an open split's two first; otherwise your open
+  sessions in tab order, with the session you are on focused. With the grid open, the same
+  button closes it.
+- **Rest the pointer on the Tiles button** (or tab to it) for a short card that shows the
+  count it opens and what a click and a right-click do.
+- **Right-click the Tiles button** (or press `Shift+F10` on it) to choose how many tiles:
+  **2**, **4** or **6**, each drawn as its layout. Your choice is remembered on this device
+  and is what the next click opens. With the grid open, picking a count re-forms it: the
+  tile you are in always stays, extra tiles leave from the end, new ones join from your tab
+  order. A count the window is too small for is greyed out, with the reason.
+- **`Ctrl+Shift+G`**: exactly what a click on the Tiles button does.
+- **`Ctrl`+click (or `Cmd`+click) a tab**: adds that session to the grid and focuses it. With
+  the grid closed it opens what the Tiles button would show, with that session among them
+  (still the count you chose in total). On macOS use
+  `Cmd`: `Ctrl`+click there opens the tab's rename instead.
+- **Drag a tab onto a tile** to replace that tile with it (the replaced session keeps
+  running), or onto an empty slot to add it. Dragging a session that is already tiled onto
+  another tile swaps the two.
+- **"Open group as tiles"** in a tab group's menu, in the vertical tab rail with groups.
+- **Run**: a session you start from this browser tab's Run button while the grid is open
+  joins it. Sessions started elsewhere (an agent, another device, a cron job) do not.
+
+The layout follows the tile count: 1x1, 2x1, three side by side on a wide screen (else a
+2x2 with one empty slot), 2x2, 3x2. The grid holds at most six tiles, fewer when the
+window is too small for six; the count menu says which limit applies.
+
+Opening, the tiles fade in one after another and each terminal appears once its history
+has loaded, rather than scrolling through it. Closing with the button, the tiles stay
+on screen, dimmed, until the single session behind them has loaded, then fade away. With
+reduced motion turned on in your system settings, the grid opens and closes at once.
+
+## A tile
+
+Each tile has a small header: `● [logo] name · model ......... ⋯ ⤢ ×`
+
+| Part   | What it does                                                                                     |
+| ------ | ------------------------------------------------------------------------------------------------ |
+| `●`    | The session's state: working, idle, waiting on you, needs you (red, and the tile's border pulses), error, ended. Hover the header for how long. |
+| logo   | Which agent runs in the tile (Claude Code, Codex, DeepSeek, Shell, ...). Hover it for the agent and the model by name. |
+| name   | Double-click to rename the session.                                                              |
+| model  | The model the session runs, when Codeman knows it: what the agent itself reports (it follows a `/model` switch), else the model its own config pins (DeepSeek's route, shown "from config"), else the model it was started with. Nothing when unknown. OpenCode shows the model and its provider together (`Big Pickle OpenCode Zen`), exactly as its own composer does. |
+| `⋯`    | The session menu: options, open in a new window, close the session.                              |
+| `⤢`    | Zoom: the tile fills the grid; press it again (or `Alt+Shift+Enter`) to get the grid back.        |
+| `×`    | Remove the tile. The session keeps running; close it from `⋯` if you want it gone.                |
+
+Click a tile to focus it. The focused tile has the accent border, takes your keyboard, and
+is the session every panel follows: files, git status, respawn and Ralph, subagent windows,
+voice and image paste. Tabs of tiled sessions carry a small underline.
+
+Drag the thin lines between tiles to resize columns and rows. A tile never gets smaller than
+about 60 columns; when the window is too small for all the tiles, the grid shows the focused
+one on its own until the window is big enough again.
+
+A tile whose session is not running shows **Not attached** with an **Attach** button. A tile
+whose agent exited inside its pane says so instead; close that session from `⋯`.
+
+## Moving tiles
+
+Drag a tile by its header (anywhere but its buttons) onto another tile and the two trade
+places. Drop it on an empty slot and it moves there, leaving its old place empty; nothing else
+moves, so the empty slot can be anywhere in the grid. The dropped tile takes the focus. Press
+`Escape` or let go anywhere else and nothing changes, not even which tile has the focus: a
+header focuses its tile when you click it, not when you press it.
+
+With the keyboard, `Ctrl+Shift+Arrows` moves the focused tile one place left, right, up or
+down: into the empty slot if that is the place, else trading places with the tile there. It
+keeps the focus.
+
+A moved tile takes the size of the place it lands in: column widths and row heights stay
+where you dragged the dividers. Tiles do not move while one is zoomed. Where everything is,
+the empty slot included, is saved with the grid and comes back on reload.
+
+Closing a tile leaves its place empty when the grid keeps its shape (six tiles to five), and a
+new tile takes the first empty place. When the number of tiles changes the grid's shape (four
+tiles to five is two columns to three), the tiles keep their places if they still fit, or line
+up again from the top left. `Alt+Shift+Arrows` and `Ctrl+Tab` never stop on an empty slot.
+
+## Keys
+
+| Shortcut                 | Action                                                     |
+| ------------------------ | ---------------------------------------------------------- |
+| `Ctrl+Shift+G`           | Open or close the grid.                                     |
+| `Alt+Shift+Arrows`       | Focus the tile to the left, right, above or below.          |
+| `Ctrl+Shift+Arrows`      | Move the focused tile left, right, up or down.              |
+| `Alt+Shift+Enter`        | Zoom the focused tile, or restore the grid.                 |
+| `Ctrl+Tab`, `Alt+[` `]`  | Cycle through the tiles.                                    |
+| `Ctrl+L`                 | Clear the focused tile.                                     |
+| `Ctrl` `+` / `Ctrl` `-`  | Tile font size (tiles have their own, smaller font).        |
+
+All of them can be rebound in App Settings → Shortcuts, where **Remove Focused Tile** can
+also get a key. Outside the grid, `Alt+Shift+Arrows`, `Ctrl+Shift+Arrows` and
+`Alt+Shift+Enter` go to the terminal as usual. While it is open, `Alt+Shift+Arrows` and
+`Ctrl+Shift+Arrows` in a text field (renaming a tile, the file editor) still select text there;
+inside a tile they focus and move tiles, so a terminal editor there (nano, micro, emacs) does
+not get them. With the Tiles setting off, `Ctrl+Shift+G` does nothing.
+
+## Leaving the grid
+
+Clicking the tab of a session that is not tiled (or picking it with `Alt+1-9` or the
+session finder) shows that session on its own, the normal single view. The grid is
+remembered: the Tiles button or `Ctrl+Shift+G` brings it straight back. Going Home does the
+same. Narrowing the window below the desktop width also returns to the single view.
+
+The grid is saved on this device and comes back when you reload the page, with its focus,
+zoom and column widths. A session that was closed in the meantime is simply left out.
+
+Split shows the same logo, name and model above both of its panes.
+
+The grid and Split are never open together: opening the grid turns an open split into two
+tiles, and Split is unavailable while the grid is open.
+
+## Read next
+
+- [The Dashboard](The-Dashboard) - the single view, tabs and the header.
+- [Keyboard Shortcuts](Keyboard-Shortcuts) - every binding.
+- [Settings Reference](Settings-Reference) - where the Tiles setting lives.

docs/wiki/Watching-Agents-Work.md

@@ -22,13 +22,18 @@ transcript: what it was asked to do, what it is doing, and what it returned.
 This is the feature that makes a fan-out legible. Without it, a lead session that spawned
 eight workers looks like a stalled terminal for several minutes.
 
-## Session lineage arcs
+## Session lineage lines
 
-The tab strip draws a coloured arc from a parent tab to any tab it spawned, one colour per
-child. That covers the other direction of fan-out: not subagents inside one session, but
-whole sessions started by an agent through the API.
+The tab strip draws lines from every tab to the tabs it spawned. That covers the other
+direction of fan-out: not subagents inside one session, but whole sessions started by an
+agent through the API.
 
-Desktop only, on by default, and toggled in **App Settings → Appearance**. Arcs are skipped
+The lines form one tree per spawning tab, in that tab's colour, and run only through the
+gaps between tab rows, so they never cover a tab name or the terminal. Select a tab and its
+family (the tabs it spawned, or its parent and siblings) is drawn thicker and brighter. A
+dashed branch means that child is working.
+
+Desktop only, on by default, and toggled in **App Settings → Appearance**. Lines are skipped
 for tabs scrolled out of view.
 
 See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) for the spawning side.
@@ -42,7 +47,8 @@ in the CLI's own environment:
 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
 ```
 
-and turn the per-case **Agent Teams** toggle on in the case settings gear.
+and turn the per-case **Agent Teams** toggle on under **Case settings…** at the bottom of the case
+picker (the gear beside the case button on a phone).
 
 Codeman watches the team directory and matches teammates to the session leading them.
 Teammates are in-process threads rather than separate CLI processes, so they show up as

docs/wiki/Working-With-Files.md

@@ -17,6 +17,7 @@ It renders what it can:
 | Markdown                 | Rendered by default: headings, tables, code blocks with copy buttons, images and links relative to the file (root-relative ones resolve from the workspace root, as on GitHub). Opened from an attachment card, where the file's folder is unknown, relative images show their alt text and relative links show as plain text. The MD pill in the header flips to source. |
 | Images                   | Inline.                                                                    |
 | Audio and video          | Inline with a working scrub bar, because range requests are supported.     |
+| Spreadsheets (`.xlsx`)   | Read-only grid, parsed in your browser (never on the server), up to 10 MB. `.xls` and `.ods` are download only. |
 | PDF and Office documents | Converted for preview when a converter is available.                       |
 | Anything else            | Download.                                                                  |
 
@@ -163,6 +164,44 @@ HEIC images from an iPhone are converted to JPEG on the way in.
 When an agent produces a file the UI can show (a chart, a diagram, a document), it can
 surface as an artifact attachment rather than a path you have to go and find.
 
+## Git changes
+
+Agents often leave work uncommitted or unpushed. Turn on **App Settings → Header & Panels →
+Bottom bar → Git status** (per device, off by default) and the right of the bottom bar shows
+the active session's repository: `● 3` uncommitted files, `↑ 2` commits not pushed, `⚠` merge
+conflicts, `? 1` a repository git could not read, `✓` when everything is committed and pushed.
+
+Click it for a draggable window, in the style of the File Viewer:
+
+- **Uncommitted changes**, grouped as staged, not staged, untracked and conflicted, each with a
+  status letter (`M` modified, `A` added, `D` deleted, `R` renamed, `?` new, `U` conflict).
+- **Not pushed**: the commits no remote has. A branch with no upstream says so, and so does one whose
+  upstream does not exist on the remote, because it was never pushed or was deleted there ("Upstream
+  not on remote"), which counts every commit on no remote rather than showing a green tick.
+- Files are grouped under their folders, collapsed until you click a folder (a chain of single-child
+  folders is one row, and the folders you opened stay open when the list refreshes). Turn off
+  **App Settings → Header & Panels → Bottom bar → Git status: group files by folder** for a flat
+  list of full paths instead.
+- **Click a file** to see what changed in it, as a unified diff with added and removed lines
+  coloured. Staged files show index versus last commit, not-staged files show working tree
+  versus index, untracked files show as all additions and deleted files as all removals.
+  **Open file** jumps to the File Viewer; **Back** returns to the list. A binary file shows a
+  note instead, and a diff over 400 KB is cut short.
+- A session folder that holds several projects gets one collapsible section per repository
+  found up to two levels down (up to **Git status: max repositories**, 12 by default; the window says
+  when there are more). A repository git could not read, typically a timeout on a slow network
+  share, is listed with the reason and counted as `? N` in the bottom-bar indicator, never silently
+  left out; the **git timeout** setting raises how long it waits. They all start collapsed (each summary line shows its branch and
+  what is outstanding), and the ones you open stay open when the window refreshes; an unrelated repository above the workspace (a dotfiles repo
+  in your home folder) is ignored.
+
+It is read-only and offline: Codeman never fetches, commits or changes the repository, so
+"behind" is as of your last fetch. It is not shown for Docker or remote (SSH) sessions, and a repository at or inside a Docker case
+workspace is skipped even from a local session (a container can write there, and git would run
+that repository's own configuration on the host). The
+data comes from `GET /api/sessions/:id/git-status` and `GET /api/sessions/:id/git-diff`
+(see the [API reference](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md)).
+
 ## Gotchas
 
 - **The viewer follows the active session's workspace.** Switching tabs changes what you are

docs/wiki/_Sidebar.md

@@ -11,6 +11,7 @@
 **Using it**
 
 - [The Dashboard](The-Dashboard)
+- [Tile Grid](Tile-Grid)
 - [Agent CLIs](Agent-CLIs)
 - [Custom Model Endpoints](Custom-Model-Endpoints)
 - [Working With Files](Working-With-Files)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.34.0",
+  "version": "1.40.0",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -129,6 +129,8 @@
     "agent-browser": "^0.6.0",
     "esbuild": "^0.27.3",
     "eslint": "^9.0.0",
+    "exceljs": "4.4.0",
+    "fflate": "0.8.3",
     "pixelmatch": "^6.0.0",
     "playwright": "^1.58.0",
     "pngjs": "^7.0.0",

plugins/codeman/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codeman",
   "description": "Drive Codeman, the self-hosted session manager for AI coding agents, from inside a Claude Code session: spawn worker sessions, prompt them, wait for them, read their answers, clean up. Acts only inside a Codeman-managed session.",
-  "version": "1.34.0",
+  "version": "1.40.0",
   "author": {
     "name": "Ark0N",
     "url": "https://github.com/Ark0N"

plugins/codeman/skills/codeman/reference/verbs.md

@@ -95,6 +95,9 @@ Differences from `quick-start` worth knowing before you debug one:
 - the id is at `.data.session.id`, not `.data.sessionId`;
 - `workingDir` must already exist (400 `INVALID_INPUT`, "workingDir does not exist"),
   and in multi-user mode must be inside the caller's own workspace (403 `FORBIDDEN`);
+  one that does not answer or cannot be read (an unreachable network mount, a
+  permission error) is 422 `OPERATION_FAILED`, never "does not exist", so do not
+  create a replacement for it;
 - hitting the session cap here is `OPERATION_FAILED`, where `quick-start` returns
   `SESSION_BUSY` for the identical condition.
 

scripts/build.mjs

@@ -4,6 +4,7 @@
  * Extracted from the package.json one-liner for readability and debuggability.
  *
  * Steps:
+ *   0. Preflight: the build-time packages resolve (nothing is touched before it)
  *   1. TypeScript compilation
  *   2. Copy static assets (web/public, templates)
  *   3. Build vendor xterm bundles
@@ -13,6 +14,7 @@
  */
 
 import { execSync } from 'child_process';
+import { createRequire } from 'module';
 import { appendFileSync, readFileSync, writeFileSync, renameSync } from 'fs';
 import { createHash } from 'crypto';
 import { fileURLToPath } from 'url';
@@ -25,6 +27,31 @@ function run(label, cmd) {
   execSync(cmd, { stdio: 'inherit', cwd: ROOT, shell: true });
 }
 
+// 0. Preflight: resolve the build-time packages the asset stage reads only AFTER it has
+// deleted dist/web/public (step 2), before anything is touched. A tree whose node_modules
+// predate them (a deploy that pulled but never ran `npm install`) used to fail mid-build
+// with dist/web/public already wiped, so the running server kept serving an index.html
+// whose hashed assets were gone. Keep the list in step with every require.resolve in
+// scripts/prepare-spreadsheet-assets.mjs (test/spreadsheet-assets.test.ts checks it).
+// Only specifiers that resolve without an exports map in the way: a subpath of a package
+// that has one (@xterm/*) can throw ERR_PACKAGE_PATH_NOT_EXPORTED while installed.
+// A hand-run of the asset stage alone (past a blocked tsc) skips this check.
+const BUILD_TIME_MODULES = ['exceljs/dist/exceljs.min.js', 'fflate'];
+const requireFromBuild = createRequire(import.meta.url);
+const missingModules = BUILD_TIME_MODULES.filter((specifier) => {
+  try {
+    requireFromBuild.resolve(specifier);
+    return false;
+  } catch {
+    return true;
+  }
+});
+if (missingModules.length > 0) {
+  console.error(`[build] missing build dependency: ${missingModules.join(', ')}`);
+  console.error('[build] run `npm install` first, then `npm run build` again. Nothing was built or deleted.');
+  process.exit(1);
+}
+
 // 1. TypeScript compilation
 run('tsc', 'tsc');
 run('chmod dist/index.js', 'chmod +x dist/index.js');
@@ -49,6 +76,9 @@ run('xterm-addon-serialize', 'npx esbuild node_modules/@xterm/addon-serialize/li
 run('xterm-addon-webgl', 'cp node_modules/@xterm/addon-webgl/lib/addon-webgl.js dist/web/public/vendor/xterm-addon-webgl.min.js');
 run('xterm-addon-unicode11', 'npx esbuild node_modules/@xterm/addon-unicode11/lib/addon-unicode11.js --minify --outfile=dist/web/public/vendor/xterm-addon-unicode11.min.js');
 run('xterm-zerolag-input', 'npx esbuild packages/xterm-zerolag-input/src/zerolag-input-addon.ts --bundle --minify --format=iife --global-name=XtermZerolagInput --outfile=dist/web/public/vendor/xterm-zerolag-input.js');
+// XLSX preview parser bundles: loaded only inside spreadsheet-preview-worker.js,
+// never by the page (see scripts/prepare-spreadsheet-assets.mjs).
+run('spreadsheet preview vendors', 'node scripts/prepare-spreadsheet-assets.mjs dist/web/public/vendor');
 
 // Append global aliases so app.js can use `new LocalEchoOverlay(terminal)`
 appendFileSync(
@@ -129,6 +159,7 @@ console.log('\n[build] content-hash cache busting');
     'api-client.js',
     'subagent-windows.js',
     'image-input.js',
+    'spreadsheet-preview.js',
     'vendor/xterm-zerolag-input.js',
     'vendor/xterm-predictive-echo.js',
   ];

scripts/check-public-assets.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { execFileSync } from 'node:child_process';
-import { readdirSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -9,6 +10,10 @@ const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const publicRoot = resolve(repoRoot, 'src/web/public');
 const prettierBin = resolve(repoRoot, 'node_modules/.bin/prettier');
 const checkedExtensions = new Set(['.js', '.css', '.html', '.json']);
+// Combined budget for the two XLSX-preview vendor bundles (exceljs + fflate).
+// They load only inside the spreadsheet worker, but a dependency bump that
+// balloons them should be a deliberate decision, not a silent one.
+const SPREADSHEET_VENDOR_MAX_BYTES = 1_100_000;
 
 function collectTextAssets(dir) {
   const files = [];
@@ -35,6 +40,39 @@ function findNullByte(buffer) {
 const files = collectTextAssets(publicRoot);
 const failures = [];
 
+// The spreadsheet worker is a stable (unhashed) URL, cache-busted by the
+// SPREADSHEET_ASSET_VERSION token in spreadsheet-preview.js. That token must be
+// the content hash of everything the worker loads, or a deploy can pair a new
+// worker with a stale cached core/vendor file (static assets are cached 1y).
+const spreadsheetWorker = join(publicRoot, 'spreadsheet-preview-worker.js');
+const spreadsheetCore = join(publicRoot, 'spreadsheet-xlsx-core.js');
+const spreadsheetEntry = join(publicRoot, 'spreadsheet-preview.js');
+const spreadsheetVendors = [join(publicRoot, 'vendor', 'exceljs.min.js'), join(publicRoot, 'vendor', 'fflate.min.js')];
+
+if ([spreadsheetWorker, spreadsheetCore, spreadsheetEntry, ...spreadsheetVendors].every(existsSync)) {
+  const vendorBytes = spreadsheetVendors.reduce((total, file) => total + readFileSync(file).length, 0);
+  if (vendorBytes > SPREADSHEET_VENDOR_MAX_BYTES) {
+    failures.push(`Spreadsheet vendor bundles exceed ${SPREADSHEET_VENDOR_MAX_BYTES} bytes (${vendorBytes} bytes)`);
+  }
+
+  const expectedVersion = createHash('sha256')
+    .update(readFileSync(spreadsheetWorker))
+    .update(readFileSync(spreadsheetCore))
+    .update(readFileSync(spreadsheetVendors[0]))
+    .update(readFileSync(spreadsheetVendors[1]))
+    .digest('hex')
+    .slice(0, 12);
+  const entrySource = readFileSync(spreadsheetEntry, 'utf8');
+  const actualVersion = entrySource.match(/const SPREADSHEET_ASSET_VERSION = '([a-f0-9]+)'/)?.[1];
+  if (actualVersion !== expectedVersion) {
+    failures.push(
+      `SPREADSHEET_ASSET_VERSION mismatch: expected ${expectedVersion}, found ${actualVersion || 'missing'}`
+    );
+  }
+} else {
+  failures.push('Spreadsheet preview assets are missing; run `node scripts/prepare-spreadsheet-assets.mjs`');
+}
+
 for (const file of files) {
   const rel = relative(repoRoot, file);
   const data = readFileSync(file);

scripts/postinstall.js

@@ -341,6 +341,22 @@ if (isGlobalInstall) {
     }
 }
 
+// ----------------------------------------------------------------------------
+// 4a. Copy the XLSX preview's browser bundles (exceljs, fflate) into
+//     src/web/public/vendor/ for dev mode. The build does the same into dist/.
+// ----------------------------------------------------------------------------
+
+if (!isGlobalInstall) {
+    try {
+        execSync(`node "${join(import.meta.dirname, 'prepare-spreadsheet-assets.mjs')}"`, { stdio: 'pipe' });
+        console.log(colors.green('✓ Spreadsheet preview vendor files prepared'));
+    } catch (err) {
+        hasWarnings = true;
+        console.log(colors.yellow('⚠ Failed to prepare spreadsheet preview vendor files'));
+        console.log(colors.dim(`  ${err.message}`));
+    }
+}
+
 // ----------------------------------------------------------------------------
 // 4b. Fetch gesture-overlay runtime assets (MediaPipe wasm + model) for dev mode
 //     (src/web/public/gesture/). Opt-in feature (CODEMAN_GESTURE=1); non-fatal.

scripts/prepare-spreadsheet-assets.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Copy the XLSX preview's browser bundles (exceljs, fflate) into a public vendor
+ * dir. Run by postinstall for dev (src/web/public/vendor, gitignored) and by
+ * build.mjs for prod (dist/web/public/vendor). Both packages are pinned exactly
+ * in package.json, and check-public-assets.mjs hashes the output into
+ * SPREADSHEET_ASSET_VERSION (the worker's cache-bust token), so a version bump
+ * that changes the bytes fails that check until the token is refreshed.
+ * Source-map comments are stripped: the maps are not shipped.
+ */
+
+import { createRequire } from 'node:module';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const outputDir = resolve(process.argv[2] || join(import.meta.dirname, '..', 'src', 'web', 'public', 'vendor'));
+const excelSource = require.resolve('exceljs/dist/exceljs.min.js');
+const fflateSource = join(dirname(require.resolve('fflate')), '..', 'umd', 'index.js');
+
+function copyBrowserBundle(source, outputName) {
+  const content = readFileSync(source, 'utf8').replace(/\n?\/\/# sourceMappingURL=.*(?:\n|$)/g, '\n');
+  if (/sourceMappingURL/.test(content)) {
+    throw new Error(`Failed to strip sourceMappingURL from ${outputName}`);
+  }
+  writeFileSync(join(outputDir, outputName), content, 'utf8');
+}
+
+mkdirSync(outputDir, { recursive: true });
+copyBrowserBundle(excelSource, 'exceljs.min.js');
+copyBrowserBundle(fflateSource, 'fflate.min.js');

skills/codeman/reference/verbs.md

@@ -95,6 +95,9 @@ Differences from `quick-start` worth knowing before you debug one:
 - the id is at `.data.session.id`, not `.data.sessionId`;
 - `workingDir` must already exist (400 `INVALID_INPUT`, "workingDir does not exist"),
   and in multi-user mode must be inside the caller's own workspace (403 `FORBIDDEN`);
+  one that does not answer or cannot be read (an unreachable network mount, a
+  permission error) is 422 `OPERATION_FAILED`, never "does not exist", so do not
+  create a replacement for it;
 - hitting the session cap here is `OPERATION_FAILED`, where `quick-start` returns
   `SESSION_BUSY` for the identical condition.
 

src/attachment-registry.ts

@@ -53,15 +53,20 @@ export const AUDIO_ATTACHMENT_EXTENSIONS: ReadonlySet<string> = new Set([
  */
 export const TEXT_ATTACHMENT_EXTENSIONS: ReadonlySet<string> = EDITABLE_EXTENSIONS;
 
+/**
+ * Document types an attachment card previews. Also the list `codeman attach`'s
+ * error text names, so the help cannot drift from what is accepted. `xlsx` is
+ * previewed client-side (spreadsheet-preview-worker.js) and served raw like the rest.
+ */
+export const DOCUMENT_ATTACHMENT_EXTENSIONS: readonly string[] = Object.freeze(['pdf', 'docx', 'pptx', 'xlsx']);
+
 const SUPPORTED_ATTACHMENT_EXTENSIONS = new Set([
   'png',
   'jpg',
   'jpeg',
   'gif',
   'webp',
-  'pdf',
-  'docx',
-  'pptx',
+  ...DOCUMENT_ATTACHMENT_EXTENSIONS,
   'md',
   'txt',
   ...VIDEO_ATTACHMENT_EXTENSIONS,
@@ -154,6 +159,7 @@ export function getAttachmentType(extension: string): AttachmentDetectedType {
   if (AUDIO_ATTACHMENT_EXTENSIONS.has(normalized)) return 'audio';
   if (normalized === 'pdf') return 'pdf';
   if (normalized === 'pptx') return 'presentation';
+  if (normalized === 'xlsx') return 'spreadsheet';
   if (normalized === 'md') return 'markdown';
   // Everything else in the text family reads as text, including code and
   // config: the card and the preview both treat it as a plain-text file.

src/cli.ts

@@ -23,7 +23,7 @@ import { getTaskQueue } from './task-queue.js';
 import { getRalphLoop } from './ralph-loop.js';
 import { getStore } from './state-store.js';
 import { getErrorMessage } from './types.js';
-import { isSupportedAttachmentExtension } from './attachment-registry.js';
+import { DOCUMENT_ATTACHMENT_EXTENSIONS, isSupportedAttachmentExtension } from './attachment-registry.js';
 import { daemonStatus, startDaemon, stopDaemon, type WebLaunchOptions } from './daemon-control.js';
 import { installService, serviceStatus, uninstallService } from './service-installer.js';
 import { isLoopbackBindHost, isUnauthenticatedNetworkAcknowledged } from './web/network-auth-policy.js';
@@ -111,7 +111,11 @@ program
   .action(async (filePath, options) => {
     const extension = String(filePath).split('.').pop()?.toLowerCase() || '';
     if (!isAbsolute(filePath) || !isSupportedAttachmentExtension(extension)) {
-      console.error(palette.err('✗ attach requires an absolute path to a png, pdf, docx, pptx, md, or txt file'));
+      console.error(
+        palette.err(
+          `✗ attach requires an absolute path to an image (png, jpg, gif, webp), document (${DOCUMENT_ATTACHMENT_EXTENSIONS.join(', ')}), audio, video, md, txt or other text file`
+        )
+      );
       process.exit(1);
     }
 

src/config/cli-registry/patterns.ts

@@ -119,3 +119,16 @@ export function compileVersionRegex(source: string): RegExp | null {
     return null;
   }
 }
+
+/**
+ * How many capture groups a regex source declares (named ones included), or -1 when it
+ * does not compile. Matching the empty string against `source|` always succeeds through
+ * the empty alternative, and the match array then has one slot per group.
+ */
+export function countCaptureGroups(source: string): number {
+  try {
+    return (new RegExp(`${source}|`).exec('') as RegExpExecArray).length - 1;
+  } catch {
+    return -1;
+  }
+}

src/config/cli-registry/schema.ts

@@ -13,9 +13,9 @@
  */
 
 import { z } from 'zod';
-import { compileVersionRegex, TOKEN_PATTERNS } from './patterns.js';
+import { compileVersionRegex, countCaptureGroups, TOKEN_PATTERNS } from './patterns.js';
 import { isKnownLauncherProfile, isKnownSetenvProfile } from './profiles.js';
-import type { McpConfigFormat } from './types.js';
+import type { LaunchDefaultSettingKey, McpConfigFormat, ModelConfigResolverName } from './types.js';
 
 /** A bare CLI id: lowercase, starts with a letter, at most 24 chars. Also used as a CSS/URL token. */
 const cliId = z
@@ -289,7 +289,7 @@ const capabilitiesSchema = z
     requiresMux: z.boolean(),
     hooks: z.enum(['none', 'always', 'supervised']),
     transcript: z.enum(['claude-jsonl', 'codex-rollout', 'deepseek-zstd', 'omp-jsonl', 'none']),
-    altScreen: z.enum(['strip-full', 'strip-mux-only', 'preserve']),
+    altScreen: z.enum(['strip-full', 'strip-mux-only', 'strip-mux-and-mouse', 'preserve']),
     echo: echoSchema,
     wheelForward: z
       .object({ mode: z.enum(['never', 'version-gated']), minVersion: z.string().max(20).optional() })
@@ -370,6 +370,56 @@ const capabilitiesSchema = z
     model: z
       .object({ source: z.enum(['flag', 'claude-settings-file', 'none']), param: z.string().optional() })
       .strict(),
+    // Same guard as the workDetect patterns: ~/.codeman/clis.json can set it, and it runs
+    // over the foot of a pane capture every time a session settles. Exactly one capture
+    // group (the model), checked here so a pattern without one fails at LOAD time instead
+    // of silently never naming a model.
+    modelDetect: z
+      .object({
+        screenLine: z
+          .string()
+          .min(1)
+          .refine(
+            (src) => compileVersionRegex(src) !== null && countCaptureGroups(src) === 1,
+            'screenLine must be a regex compileVersionRegex() accepts (at most 200 characters, no nested quantifiers) with exactly one capture group'
+          )
+          .optional(),
+        // Bounded hard, like watchingLines: every row it adds is one more row the agent
+        // itself may be able to write. 8 is the reader's own cap (readScreenModel); a
+        // window taller than the CLI's footer needs a pattern only that CLI's chrome can
+        // satisfy at its position, as opencode's does by taking the LAST composer row.
+        screenLines: z.number().int().min(1).max(8).optional(),
+        // Single tokens, bounded: each is compared against one captured field.
+        rejectWords: z.array(z.string().min(1).max(40).regex(/^\S+$/)).max(32).optional(),
+        // A NAMED reader (src/model-config-resolvers.ts), never code in config.
+        configResolver: z.enum(['deepseek-route'] as const satisfies readonly ModelConfigResolverName[]).optional(),
+      })
+      .strict()
+      // Typos rather than configurations, refused at LOAD time like watchingLines.
+      .refine(
+        (v) => v.screenLine !== undefined || v.configResolver !== undefined,
+        'modelDetect declares nothing to read'
+      )
+      .refine(
+        (v) => v.screenLines === undefined || v.screenLine !== undefined,
+        'screenLines has nothing to bound without a screenLine'
+      )
+      .refine(
+        (v) => v.rejectWords === undefined || v.screenLine !== undefined,
+        'rejectWords has nothing to filter without a screenLine'
+      )
+      .optional(),
+    // Launch param -> synced App Settings key. The values are a closed enum, like
+    // configResolver: a clis.json override names one of the settings this build knows
+    // how to validate, never an arbitrary key. Params are checked against the declared
+    // ones in the superRefine below.
+    launchDefaults: z
+      .record(
+        z.string(),
+        z.enum(['codexModel', 'codexReasoningEffort'] as const satisfies readonly LaunchDefaultSettingKey[])
+      )
+      .refine((v) => Object.keys(v).length >= 1 && Object.keys(v).length <= 8, 'launchDefaults takes 1 to 8 params')
+      .optional(),
     privilegedParams: z
       .array(
         z
@@ -588,6 +638,30 @@ export const CliEntrySchema = z
       }
     });
 
+    // Same silent-no-op class again: a launch default for a param the entry never declared
+    // would be filled into the config object and then read by nothing. And without a
+    // `legacyConfigField` the entry's params are read off the request body itself, where a
+    // filled `model` would be a different field (claude's per-session one), so refuse it.
+    const { launchDefaults } = entry.capabilities;
+    if (launchDefaults !== undefined) {
+      if (entry.launch.legacyConfigField === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'launchDefaults needs launch.legacyConfigField to fill',
+          path: ['capabilities', 'launchDefaults'],
+        });
+      }
+      for (const param of Object.keys(launchDefaults)) {
+        if (!declaredParams.has(param)) {
+          ctx.addIssue({
+            code: 'custom',
+            message: `launchDefaults param "${param}" is not a declared launch param`,
+            path: ['capabilities', 'launchDefaults', param],
+          });
+        }
+      }
+    }
+
     const { setenvProfile } = entry.env;
     if (setenvProfile !== undefined && !isKnownSetenvProfile(setenvProfile)) {
       ctx.addIssue({

src/config/cli-registry/stock.ts

@@ -491,8 +491,45 @@ const OPENCODE: CliEntry = {
   },
   capabilities: {
     ...agentDefaults(),
-    altScreen: 'strip-mux-only',
+    altScreen: 'strip-mux-and-mouse',
     echo: { policy: 'buffer', anchor: { kind: 'cursor' }, predictProfile: undefined },
+    // Measured on a live opencode 1.3.0 pane (capture-pane every 250-300 ms through real
+    // turns at 40, 60, 120 and 200 columns, plus the raw PTY stream, 2026-10-09). Every
+    // composer row starts with a `┃` bar, and the submitted prompt lands in the transcript
+    // with the same bar, so a turn's first repaint arms the idle confirmation and tmux's
+    // reattach repaint does the same for a restored pane. While a turn runs the footer row
+    // starts with an 8-cell knight-rider spinner, `⬝■■■■■■⬝  esc interrupt`, redrawn about
+    // every 40 ms (never a 2.5 s gap mid-turn, so silence cannot end one early); at rest the
+    // row holds only the key hints and nothing on screen draws a `⬝`/`■` run, the wide
+    // layout's sidebar included. The working line is the spinner run, not the label: tmux
+    // ships `esc` and `interrupt` as separate words joined by cursor moves, and below about
+    // 45 columns the footer wraps the label itself. A pending permission prompt replaces
+    // the composer and stops the spinner, so it reads as idle (waiting on the user).
+    // ⚠️ Without this entry an opencode session latched `busy` after any turn that ran a
+    // tool: the braille spinner on a running tool row trips SPINNER_PATTERN, and opencode
+    // never draws Claude's `❯`, the fallback that would have armed the idle check. The
+    // last `┃` row on screen is the composer's agent/model row (or the permission box's
+    // closing bar), never the prompt text, so the submit verifier stands down.
+    workDetect: {
+      promptGlyph: '┃',
+      workingLine: '[⬝■]{8}',
+    },
+    // The composer's agent row, measured on live opencode 1.3.0 panes (home screen and in
+    // session, at 40, 60, 120 and 200 columns, 2026-10-09): `┃  Build  Big Pickle OpenCode
+    // Zen`, directly above the box's bottom edge `╹▀▀▀`. opencode renders it as the agent,
+    // then the model's name, then the provider's name (then `· <variant>` when the model
+    // has one), and only colour tells model from provider, so the field is all of it: what
+    // opencode itself shows, owner's choice. A double space ends it, which is where the
+    // 200-column layout's sidebar shares the row. The lookahead takes the LAST such row in
+    // the window, so nothing the agent prints higher up can stand in for it; below the
+    // composer there is only opencode's own chrome (key hints, a tip, the cwd/version
+    // row), which is why the window can be 8 rows: the home screen puts up to 5 of those
+    // rows under it. A permission prompt or shell mode hides the row, and the last model
+    // is kept. `No provider ` is opencode's placeholder before a provider is connected.
+    modelDetect: {
+      screenLine: String.raw`┃ {2}[^\s·]+ {2}(?!No provider )([^ \n](?:[^ \n]| (?! ))*)(?: {2}.*)?\n *╹(?![\s\S]*\n *╹)`,
+      screenLines: 8,
+    },
     // opencode's global config dir is xdg-basedir's `$XDG_CONFIG_HOME/opencode`.
     mcpConfig: {
       path: '.config/opencode/opencode.json',
@@ -598,10 +635,15 @@ const CODEX: CliEntry = {
     // Measured against a live codex-cli 0.154.0 pane on 2026-09-22: the row appears when
     // the terminal starts, follows the composer down as the conversation grows, and is
     // gone after `/stop`.
+    // ⚠️ Codex 0.162.0 (measured 2026-10-09) draws a hint row under the status line at
+    // rest (`  ← for agents · ? for shortcuts`) and drops it while a prompt is typed, so
+    // the chip is FOURTH from the bottom at rest and third while typing. A three-row
+    // window never saw it at rest, which is exactly when the idle probe reads it, so a
+    // session waiting on its terminal read as plainly idle. Four rows cover both.
     // ⚠️ This entry CANNOT promise what Claude's does, and the difference is Codex's
-    // layout rather than its pattern. The third row from the bottom is the chip only
+    // layout rather than its pattern. The fourth row from the bottom is the chip only
     // while a terminal runs; with none running it is the last row of the transcript,
-    // which the agent writes. Matching the complete row raises the bar — an assistant
+    // which the agent writes (and while a prompt is typed, the last two). Matching the complete row raises the bar — an assistant
     // message has to end with this exact line, to the character — but nothing here makes
     // forging it impossible, so do not read the Claude comment above as applying here.
     // What contains it is that codex declares `hooks: 'none'`: no hook event from a codex
@@ -620,8 +662,37 @@ const CODEX: CliEntry = {
       promptGlyph: '›',
       workingLine: '[Ee]sc to interrupt',
       watchingLine: String.raw`^\s{0,4}(\d+ background terminals?) running · /ps to view · /stop to close$`,
-      watchingLines: 3,
+      watchingLines: 4,
     },
+    // The footer under the composer, measured on a live 0.147.0 pane:
+    // `  gpt-5.6-terra default · ~/codeman-cases/th-scratch` (model, reasoning effort,
+    // cwd). It sits below the composer, so the transcript never reaches it, and the
+    // effort word right after the model is codex's own format: an open slash-command
+    // popup or a bare line of prose does not have that shape. A footer without an effort
+    // word (a model with no reasoning setting) is not read, and the session keeps its
+    // last known or launch model.
+    // The effort words are built from CODEX_REASONING_EFFORTS, the same list the
+    // `reasoningEffort` launch param above admits, plus `default` (what codex prints when
+    // no effort is configured). A hand-kept copy once left out `ultra`, so a session at
+    // that level never named its model. Every word is plain letters, so the join adds no
+    // quantifier and only a few characters to the 200-character compileVersionRegex cap.
+    // ⚠️ It is not always the LAST row. 0.162.0 (measured 2026-10-09) adds a hint row
+    // under it at rest, `  ← for agents · ? for shortcuts` or `  ? for shortcuts`, and
+    // drops it again while a prompt is being typed. With a one-row window the footer was
+    // never seen and every codex tile showed no model. So the window is two rows and the
+    // footer is either the last one or followed by exactly one more two-space-indented
+    // row. The `$` (no `m` flag: the end of the window) is what keeps the guard the
+    // one-row rule had: with the footer hidden, the last two rows are a transcript line
+    // and the `›` composer, and a forged footer-shaped transcript line is not followed by
+    // an indented row, so it is not read.
+    modelDetect: {
+      screenLine: String.raw`(?:^|\n) {2}([A-Za-z0-9][\w.:/@+-]{0,79}) (?:${[...CODEX_REASONING_EFFORTS, 'default'].join('|')}) · [^\n]*(?:\n {2}[^\n]*)?$`,
+      screenLines: 2,
+    },
+    // App Settings → Codex model / reasoning effort (synced), filled into a LOCAL launch's
+    // codexConfig wherever the caller left the field unset. Launch-only: nothing writes
+    // codex's own config.toml. Read by applyLaunchDefaults() in src/web/launch-defaults.ts.
+    launchDefaults: { model: 'codexModel', reasoningEffort: 'codexReasoningEffort' },
     // Two columns, like claude's, measured on a live 0.154.0 answer: the `•`/`›`/`⚠`
     // markers sit in the gutter, prose continuations sit at 2, and a nested YAML block
     // the model wrote rendered at 2/4/6/8 for its own 0/2/4/6. Replayed at 100, 120,
@@ -744,6 +815,28 @@ const GEMINI: CliEntry = {
     ...agentDefaults(),
     altScreen: 'strip-full',
     echo: { policy: 'buffer', anchor: { kind: 'cursor' } },
+    // Measured on a live Gemini CLI 0.63.0 pane (capture-pane every 300 ms through real
+    // turns with a shell call at 40, 120 and 200 columns, YOLO and default approval mode,
+    // plus the raw PTY stream, 2026-10-09). The TUI repaints its whole bottom region on
+    // every frame, composer included, and the composer sits between a `▄` bar and a `▀`
+    // bar; the submitted prompt is echoed between the same bars. So the `▀` bar arms the
+    // idle confirmation (every repaint and tmux's reattach repaint carry it), and it is the
+    // glyph rather than the composer's prompt character, which follows the approval mode
+    // (`*` in YOLO) and whose `>` also starts the echoed prompt. While a turn runs a line
+    // `⠦ Thinking... (esc to cancel, 6s)` animates about every 80 ms (largest gap mid-turn:
+    // 214 ms); the label can be any loading phrase, so the working line is the
+    // `(esc to cancel, <n>` suffix, or a spinner frame opening a line where a long phrase
+    // pushed that suffix onto the next one. At rest nothing on screen matches either. A tool
+    // confirmation (default mode) replaces the composer and stops the spinner, and the pane
+    // goes silent, so it reads as idle (waiting on the user).
+    // ⚠️ Without this entry a gemini session latched `busy` after its first turn: the braille
+    // spinner trips SPINNER_PATTERN, and gemini never draws Claude's `❯`, the fallback that
+    // would have armed the idle check. A line starting with `▀` is a bar, never prompt text,
+    // so the submit verifier stands down.
+    workDetect: {
+      promptGlyph: '▀',
+      workingLine: String.raw`\(esc to cancel, \d|(?:^|\n) ?[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏] `,
+    },
     // gemini's builder defaults an ABSENT approvalMode to 'yolo', so the clamp must
     // MATERIALIZE a config (not just touch an already-sent one) or a non-granted owner who
     // sends no geminiConfig at all would still get yolo for free.
@@ -925,6 +1018,37 @@ const PI: CliEntry = {
     ...agentDefaults(),
     altScreen: 'preserve', // pi's TUI renders into the main screen with terminal-owned scrollback
     echo: { policy: 'buffer', anchor: { kind: 'cursor' } },
+    // Measured on a live pi 1.1.0 pane (capture-pane every 250 ms through a turn,
+    // 2026-10-09): pi has no composer glyph. Its composer sits between two `─` rules, and
+    // while a turn runs it embeds its status in the TOP rule as `── ⠏ Working ───…`, the
+    // braille frame animating every ~80 ms; at rest both rules are plain `─`. So the rule
+    // is the glyph that arms the idle confirmation, and a spinner frame inside it is the
+    // working line (the frame, not the word: an extension can replace "Working").
+    // ⚠️ Without this entry a pi session never left `busy` once marked working: the
+    // braille spinner trips SPINNER_PATTERN, and pi never draws Claude's `❯`, the
+    // fallback that would have armed the idle check. The rules carry no prompt text, so
+    // the submit verifier reading them stands down instead of re-pressing Enter.
+    workDetect: {
+      promptGlyph: '─',
+      workingLine: '── [⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏] ',
+    },
+    // pi's footer stats row, read from pi 1.1.0's footer code (0.84.4's is the same) and
+    // measured live as `0.8%/253k (auto)            qwen3.8-27b-pi • xhigh`: usage and
+    // context on the left, then at least two spaces and `[(provider) ]<model>` followed
+    // by ` • <thinking>` for a reasoning model and ` → <routed model>` when routed. Only
+    // the last two rows are read, which sit below the composer where the transcript never
+    // reaches (an extension's status row may sit under the stats row), and the context
+    // field (`12.3%/253k`, `?/128k`) picks the stats row out of them.
+    // ⚠️ A narrow pane truncates the right side with NO ellipsis, leaving exactly two
+    // spaces of padding. So a model with nothing after it is read only with 3+ spaces in
+    // front; with two, only when a following ` •`/` →` proves the name is whole (the
+    // bullet only ever follows a complete name, even when the cut lands right after it).
+    // A cut name is never shown. `no-model` is pi's placeholder when none is selected.
+    modelDetect: {
+      screenLine: String.raw`[%?]/[\d.]+[kKM]?(?: \(auto\))?(?: • xp)? {2}(?: +|(?=(?:\(\S{1,40}\) )?\S{1,80} [•→]))(?:\([\w.@-]{1,40}\) )?([A-Za-z0-9][\w.:/@+-]{0,79})(?= [•→]|\n|$)`,
+      screenLines: 2,
+      rejectWords: ['no-model'],
+    },
     // pi's absent-config default is an interactive trust PROMPT the session user could
     // just answer "yes" to, so omitting --approve is not itself a clamp — MATERIALIZE
     // approveProjectTrust:false so buildPiCommand emits --no-approve outright.
@@ -1042,8 +1166,9 @@ const GROK: CliEntry = {
   },
   capabilities: {
     ...agentDefaults(),
-    // Fullscreen alt-screen TUI with mouse support — same shape as opencode/antigravity:
-    // only the tmux-attach-time smcup strip, not Ink's full erase-scrollback+DECSET strip.
+    // Fullscreen alt-screen TUI with mouse support, same strip as antigravity until measured
+    // (opencode's mouse strip is #443): only the tmux-attach-time smcup strip, not Ink's full
+    // erase-scrollback+DECSET strip.
     altScreen: 'strip-mux-only',
     // Buffer-policy fallthrough default, unmeasured against an authenticated grok composer
     // (the existing hedge, preserved verbatim) — same as gemini/antigravity/pi.
@@ -1222,6 +1347,35 @@ const DEEPSEEK: CliEntry = {
     echo: { policy: 'buffer', anchor: { kind: 'cursor' } },
     // Model is NOT a session field for dsh — it is a profile composition entry.
     model: { source: 'none' },
+    // So the screen is where the model is known: dsh-TUI resolves the route itself
+    // (profile cordis.yml pin, else the persisted `/model` choice, else its default;
+    // lib/types/modelRoute.js) and its status line draws "the route requests actually
+    // take", model first (StatusLine.js; `statusBar.model` is on by default and forced
+    // on in minimal mode). Measured on dsh-TUI 0.10.0-beta.1: the composer's rounded box
+    // and, on the row right under its bottom border, ` qwen3.8-27b · medium · <cwd>`.
+    // The border anchors it: nothing the agent writes can sit below the composer, and a
+    // suggestion popup there starts with `/` or `+`, never a model id.
+    // ⚠ The first field is the model only while the status bar's model field is on (the
+    // default). Switched off, the first field is the next one (StatusLine.js): tokens per
+    // second (`12 t/s`) and the token count (`1.2k→3.4k`), which the pattern cannot match,
+    // then the reasoning effort (` medium · th-config`, measured live), then the session
+    // mode, then the cwd's basename. So `rejectWords` lists what those can be, from the
+    // dsh 0.1.1-rc.2 / dsh-TUI 0.10.0-beta.1 sources: every effort id (pi-ai's
+    // THINKING_LEVELS and the DeepSeek adapter's off/low/high/max), and the shipped mode
+    // ids. A mode's drawn label (`plan mode`, `full access`, CJK) never matches one token,
+    // and a field equal to the session's folder name is refused by the shared reader.
+    // Known gaps, all off by default: a custom mode id drawn raw, a git branch or a
+    // one-word session title as the first field; and the non-compact layout, whose
+    // left/right justification never ends a field with ` · `, so nothing is read there
+    // and the session shows its route config.
+    modelDetect: {
+      screenLine: String.raw`╰─+╯\n ?([A-Za-z0-9][\w.:/@+-]{0,79})(?= · |\n|$)`,
+      screenLines: 3,
+      rejectWords: ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'default', 'plan', 'full'],
+      // With the status bar's model field off (or before it paints), the route the
+      // session's profile pins, read the way dsh-TUI resolves it: src/deepseek-route-config.ts.
+      configResolver: 'deepseek-route',
+    },
     // Only-if-sent, like codex/antigravity/grok: an ABSENT permissionMode means the
     // launcher's own default, `workspace-write`, which already asks. Clamping to
     // `read-only` instead would break the workspace rather than protect it.
@@ -1347,13 +1501,27 @@ const OMP: CliEntry = {
   },
   capabilities: {
     ...agentDefaults(),
-    // Fullscreen alt-screen TUI, same shape as opencode/antigravity/grok: only the
+    // Fullscreen alt-screen TUI, same shape as antigravity/grok: only the
     // tmux-attach-time smcup strip, not Ink's full erase-scrollback+DECSET strip.
     altScreen: 'strip-mux-only',
     // Codeman reads omp's own `~/.omp/agent/sessions/**/*.jsonl` host-side, which is what
     // makes an omp conversation survive a full session kill.
     transcript: 'omp-jsonl',
     echo: { policy: 'buffer', anchor: { kind: 'cursor' } },
+    // Measured on live omp 18.8.6 and 18.0.11 panes (2026-10-09, a turn held open against
+    // an endpoint that never answers): the input row is `╰─ <text>`, redrawn when a turn
+    // ends, at launch and on reattach. While a turn runs the status bar's leading `π`
+    // becomes a braille spinner plus the elapsed time (` ⠼ 14s > ⬢ model > 📁 ~/dir ▶──`;
+    // 18.0.11 pads it with two spaces, past a minute it reads `1m`), and a `⎋ Working…`
+    // row appears above it. At rest the bar starts ` π > `.
+    // ⚠️ Without this entry an omp session never left `busy` once marked working, like pi:
+    // the spinner trips SPINNER_PATTERN and omp never draws Claude's `❯` after setup.
+    // The glyph also switches the submit verifier on for omp. A prompt sent mid-turn goes
+    // to omp's `Steering` queue and clears the input row, so the verifier stands down.
+    workDetect: {
+      promptGlyph: '╰─',
+      workingLine: '[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏] [0-9hms ]+> |⎋ Working',
+    },
     // No permission prompts and no bypass flag, so nothing config-shaped to clamp — the
     // whole privileged surface here is env-shaped.
     privilegedParams: [],

src/config/cli-registry/types.ts

@@ -93,6 +93,17 @@ export interface CliVariant {
 /** The newline chord a CLI's composer reads as "insert a line break" (see `CliCapabilities.newline`). */
 export type NewlineSequence = 'line-feed' | 'esc-enter';
 
+/** The config readers `capabilities.modelDetect.configResolver` may name (src/model-config-resolvers.ts). */
+export type ModelConfigResolverName = 'deepseek-route';
+
+/**
+ * The synced App Settings keys `capabilities.launchDefaults` may name (src/web/launch-defaults.ts).
+ * A closed list rather than any settings key, so a clis.json override cannot feed an
+ * arbitrary setting onto a command line; each name must also be a `SettingsUpdateSchema`
+ * key, which the resolver's typing enforces.
+ */
+export type LaunchDefaultSettingKey = 'codexModel' | 'codexReasoningEffort';
+
 /** The MCP config dialects `src/mcp-sync.ts` has an adapter for. */
 export type McpConfigFormat = 'claude-json' | 'gemini-json' | 'codex-toml' | 'opencode-json' | 'antigravity-json';
 
@@ -362,8 +373,8 @@ export interface CliCapabilities {
     /**
      * How many rows at the FOOT of the screen that row can appear in, counting non-blank
      * rows only. Claude writes its chip on the last row and keeps the default; Codex pins
-     * its own above the composer, which puts it third from the bottom, so it declares
-     * more. Keep each number as small as that CLI's layout allows: every extra row is
+     * its own above the composer, which puts it third or fourth from the bottom (its hint
+     * row comes and goes), so it declares more. Keep each number as small as that CLI's layout allows: every extra row is
      * another row an agent might be able to write, and the label is what silences an
      * alert. See `watchingLabel()` in `session-activity.ts`.
      */
@@ -436,11 +447,40 @@ export interface CliCapabilities {
    */
   transcript: 'claude-jsonl' | 'codex-rollout' | 'deepseek-zstd' | 'omp-jsonl' | 'none';
   /**
-   * 'strip-full'     — alt-screen + erase-scrollback + mouse DECSETs stripped (Ink TUIs).
-   * 'strip-mux-only' — only tmux's own attach-time smcup (the safe default).
-   * 'preserve'       — leave everything (a direct-PTY shell running vim/less/htop).
+   * What the server strips from this CLI's output stream before the browser sees it.
+   * The value encodes three independent choices (predicates in session.ts):
+   *
+   * | value                 | alt-screen toggles  | `3J` (erase scrollback) | mouse DECSETs       |
+   * |-----------------------|---------------------|-------------------------|---------------------|
+   * | `strip-full`          | stripped            | stripped                | stripped            |
+   * | `strip-mux-and-mouse` | stripped under tmux | kept                    | stripped under tmux |
+   * | `strip-mux-only`      | stripped under tmux | kept                    | kept                |
+   * | `preserve`            | stripped under tmux | kept                    | kept                |
+   *
+   * `strip-full` is `isAltScreenStripMode`; `strip-mux-and-mouse` is `isMuxMouseStripMode`;
+   * every other value takes `isMuxAltScreenOnlyStripMode`, so at runtime `preserve` and
+   * `strip-mux-only` are the same row — `preserve` only says what such a CLI's pane
+   * holds (terminal-owned scrollback: a shell, pi), not a different strip.
+   *
+   * - alt-screen: the tmux CLIENT emits `smcup` as its first bytes at attach, parking
+   *   xterm in the scrollback-less alternate buffer; a pane program's own toggles never
+   *   reach the client (tmux repaints instead). "Under tmux" means `useMux`: on a
+   *   direct-PTY fallback the `?1049h` is the program's own and must stay.
+   * - `3J`: a user's `clear` is a deliberate scrollback wipe; only an Ink TUI's
+   *   redraw-driven `3J` (strip-full) is noise.
+   * - mouse DECSETs: stripping them keeps a drag a local selection instead of a report
+   *   to the TUI. The browser then hand-encodes clicks (`_sendSyntheticSgrTap`), gated
+   *   on the `cliMouseTracking` the server records as it strips. Kept where a program's
+   *   own mouse support must work in the pane (htop/vim in a shell).
+   *
+   * Stock CLIs: `strip-full` = claude, codex, gemini (Ink TUIs); `strip-mux-and-mouse` =
+   * opencode (a full-screen TUI that enables tracking itself); `strip-mux-only` =
+   * antigravity, grok, deepseek, omp; `preserve` = shell, pi.
+   *
+   * A fourth combination is the point to split this into flags; three is still cheaper
+   * as an enum.
    */
-  altScreen: 'strip-full' | 'strip-mux-only' | 'preserve';
+  altScreen: 'strip-full' | 'strip-mux-only' | 'strip-mux-and-mouse' | 'preserve';
   echo: {
     policy: 'buffer' | 'predict' | 'off';
     /** How the local-echo overlay locates the composer row. */
@@ -462,6 +502,55 @@ export interface CliCapabilities {
   statusLineTelemetry: boolean;
   /** Where a model override is delivered. Claude uniquely writes settings.local.json. */
   model: { source: 'flag' | 'claude-settings-file' | 'none'; param?: string };
+  /**
+   * Where this CLI draws the model it is running, so a session header can name it
+   * (`SessionState.displayModel`, src/session-display-model.ts).
+   *
+   * `screenLine` is the source of a regex with exactly ONE capture group, the model. It
+   * runs over the last `screenLines` non-blank rows of the pane capture the idle/working
+   * probe already takes (rows joined with `\n`, so a pattern may span them), which costs no
+   * extra tmux call and re-reads the footer at every turn transition, so an in-session
+   * `/model` switch is followed.
+   *
+   * ⚠ The rows are pane text and the agent writes most of a pane, so a pattern must anchor
+   * on chrome only this CLI draws (the row under its own composer, an effort word in its
+   * own footer format), never on a shape the agent could print in its transcript. Measured
+   * on a live pane per CLI; absent means the CLI's screen is never read for a model and
+   * the session shows its launch model, if any.
+   *
+   * `configResolver` names a reader (src/model-config-resolvers.ts) that resolves the
+   * model the CLI's own config pins, the way that CLI resolves it for the session, for
+   * while the screen names none (its status line switched off, or not drawn yet). Read
+   * once per pane start, attach or relaunch, bounded and read-only; the screen still
+   * wins whenever it names a model. A NAMED reader, like a launcher profile, so the
+   * per-CLI behaviour stays data here and code in one module.
+   */
+  modelDetect?: {
+    screenLine?: string;
+    screenLines?: number;
+    /**
+     * Words the `screenLine` field can show when it is NOT the model (a footer whose model
+     * field is switched off shows the next field there), compared lower-cased. A field
+     * equal to the session's own working-directory basename is never the model either,
+     * for every CLI; that rule is the shared reader's, not data.
+     */
+    rejectWords?: string[];
+    configResolver?: ModelConfigResolverName;
+  };
+  /**
+   * Synced App Settings that seed this CLI's launch params when the caller left them unset,
+   * keyed by LAUNCH PARAM name (`{ model: 'codexModel' }`), never the legacy wire name; the
+   * resolver translates through `launch.legacyConfigAliases` like every other `param`.
+   *
+   * Filled into the entry's `launch.legacyConfigField` object at create time by
+   * `applyLaunchDefaults()` (src/web/launch-defaults.ts), which re-validates each value
+   * with `SettingsUpdateSchema` and never overwrites a value the caller sent. Which
+   * launches get it is the CALLER's decision (local ones only: never remote, Docker or a
+   * custom model endpoint). `schema.ts` refuses an undeclared param, and an entry without
+   * a `legacyConfigField`, whose params would otherwise be read off the request body itself.
+   * Absent = no launch defaults.
+   */
+  launchDefaults?: Record<string, LaunchDefaultSettingKey>;
   /**
    * Params a non-granted multi-user owner may not set freely, and what they are forced to.
    * Data-driven so a CUSTOM CLI's bypass flag is clampable exactly like codex's.

src/config/dependency-registry.ts

@@ -7,6 +7,8 @@
  * @module config/dependency-registry
  */
 
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { enabledClis } from './cli-registry/registry.js';
 import { compileVersionRegex } from './cli-registry/patterns.js';
 
@@ -30,6 +32,24 @@ export interface PathResolver {
    * there and a false "installed" contradicts the run mode's own resolver.
    */
   requireVersionMatch?: boolean;
+  /**
+   * Absolute directories to probe (`<dir>/<bin>`) when `which` misses. A service (systemd,
+   * launchd) runs with a minimal PATH, so a CLI installed under `~/.local/bin` or an npm/nvm
+   * prefix is invisible to `which` while the run mode, which falls back to the registry's
+   * `discovery.searchDirs`, still finds it. Carries those dirs so the doctor agrees.
+   */
+  searchDirs?: string[];
+}
+
+/**
+ * Expand a leading `~` (the only form registry `searchDirs` use). Twin of `expandHome()` in
+ * src/utils/cli-resolver.ts, copied rather than imported because importing it from config/
+ * would pull in the whole resolver chain; keep the two in step.
+ */
+function expandSearchDir(dir: string): string {
+  if (dir === '~') return homedir();
+  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2));
+  return dir;
 }
 
 /** Resolve a Windows-installed app reachable from win32 or WSL. */
@@ -131,6 +151,7 @@ function cliDependencyEntries(): ToolDependency[] {
             // (pi, grok, dsh): a bare `which` hit there is not evidence of the right
             // program, so a version mismatch means MISSING rather than unknown-version.
             requireVersionMatch: version?.requireVersionMatch,
+            searchDirs: cli.discovery.searchDirs.map(expandSearchDir),
           },
         },
       ],

src/config/path-probe.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Limits for the bounded path probe (`src/utils/bounded-path-probe.ts`).
+ *
+ * A linked case can live on a network mount, and a hard mount that went away makes
+ * `stat()` wait until the mount comes back. The probe gives up on such a path after
+ * `PATH_PROBE_TIMEOUT_MS` and answers "unknown", and it stops starting new probes
+ * once `MAX_STALLED_PATH_PROBES` timed-out stats are still holding libuv threadpool
+ * workers (the pool is shared by every `fs`, `dns.lookup` and `crypto` call in the
+ * process, and holds 4 workers unless `UV_THREADPOOL_SIZE` says otherwise).
+ *
+ * Both are env-overridable, in the same style as the other config modules. A slow
+ * but healthy mount (an sshfs that needs a couple of seconds on first touch) may want
+ * a longer timeout. The stall limits follow `UV_THREADPOOL_SIZE` on their own, so a
+ * server started with a larger pool gets a higher ceiling without further setup.
+ *
+ * @module config/path-probe
+ */
+
+function envInt(name: string, fallback: number, min: number, max: number): number {
+  const raw = parseInt(process.env[name] || '', 10);
+  if (!Number.isFinite(raw) || raw <= 0) return fallback;
+  return Math.max(min, Math.min(max, raw));
+}
+
+/** How long a caller waits for one path probe before the answer is "unknown". */
+export const PATH_PROBE_TIMEOUT_MS = envInt('CODEMAN_PATH_PROBE_TIMEOUT_MS', 1_500, 100, 60_000);
+
+/**
+ * Hard ceiling on timed-out probes left pending, for every caller, `pastCap` ones
+ * included: the threadpool size minus one, so a dead mount can never take the last
+ * worker. libuv sizes the pool from `UV_THREADPOOL_SIZE` (4 when unset). A pool of
+ * one cannot keep a worker free at all, so the ceiling never drops below one.
+ */
+export const PATH_PROBE_STALL_CEILING = Math.max(1, (Number(process.env.UV_THREADPOOL_SIZE) || 4) - 1);
+
+/**
+ * Timed-out probes allowed to stay pending before new BULK probes are refused
+ * (answered "unknown" without a stat). This is a backstop, not the main defence: a
+ * stalled path on a network or FUSE mount already takes the rest of that mount out
+ * of probing (a stall anywhere else takes out only the stalled path), so the cap
+ * only engages once that many UNRELATED places have stopped answering. It defaults
+ * to one below {@link PATH_PROBE_STALL_CEILING} (2 with the default pool), leaving a
+ * slot a `pastCap` probe may still use, and is never allowed above the ceiling.
+ */
+export const MAX_STALLED_PATH_PROBES = Math.min(
+  PATH_PROBE_STALL_CEILING,
+  envInt('CODEMAN_PATH_PROBE_MAX_STALLED', Math.max(1, PATH_PROBE_STALL_CEILING - 1), 1, 64)
+);

src/deepseek-route-config.ts

@@ -0,0 +1,464 @@
+/**
+ * @fileoverview The model a DeepSeek Harness (`dsh`) session's TUI is configured to
+ * use, read from its route config, for a session header whose screen names no model
+ * yet (the status bar's model field switched off, or not drawn yet). See
+ * `SessionState.displayModel` (src/session-display-model.ts): the screen still wins
+ * whenever it names a model, since it is what the running TUI actually uses.
+ *
+ * ## How dsh-TUI resolves its route (dsh 0.1.1-rc.2, dsh-TUI 0.10.0-beta.1)
+ *
+ * A profile is a stack of loader patch layers over an empty root, in this order
+ * (`@deepseek-ai/dsh` profile-boot): every bundle's patch layer, the profile's own
+ * `$DSH_HOME/profiles/<profile>/cordis.patch.yml`, the home-level
+ * `$DSH_HOME/cordis.patch.yml` (it outranks the profile layer), then `--patch`
+ * overlays (Codeman passes none). A patch targets a row by `id`; one whose `name`
+ * does not match the row's is skipped; every other key REPLACES the row's field
+ * whole (`applyEntryPatches`), so the last layer carrying `config` for the `dsh-tui`
+ * row defines all of it.
+ *
+ * dsh-TUI then takes its model route from that config only when it names BOTH
+ * `provider` and `model` (`lib/types/modelRoute.js`, issue #67). Anything less is
+ * dropped whole and the TUI falls back to the persisted `/model` choice, then to its
+ * own default: neither is in the config, so neither is answered here. The bundle's
+ * own row pins `provider: deepseek-official` alone, by design, so only the two user
+ * layers can pin a route; the bundle layers are not read (they resolve through the dsh
+ * installation, outside the dsh home). `settings.yaml`'s `agent-default-model` is the
+ * HEADLESS default, not the TUI's, and is never read.
+ *
+ * ## Answer nothing rather than a guess
+ *
+ * Every doubt answers null: a profile that does not compose dsh-TUI, a half-pinned
+ * route, a layer that cannot be read (unreadable, a symlink out of the dsh home, too
+ * big, a mount that does not answer), and a file this reader does not fully
+ * understand. The YAML reader below is deliberately narrow (the repo carries no YAML
+ * dependency): a top-level block sequence of patch items, plain keys, single-line
+ * plain or quoted string scalars for the values it needs, and null for anything else
+ * that could change the answer (an anchor, alias or tag such as `!!js` on such a value,
+ * a merge key, a multi-line scalar, flow or block-scalar config, duplicate keys, a
+ * scalar YAML would type as a number, boolean or null, a second document, a nested
+ * row redefining dsh-TUI).
+ *
+ * ## Never block, never write, never leak
+ *
+ * Every path is probed with the bounded `probePathKind()` before it is touched, read
+ * asynchronously with a size cap, and must resolve (realpath) inside the dsh home.
+ * Nothing is written. Only the model id leaves this module: never the provider, a
+ * base URL, a key or any other config value.
+ *
+ * Tests: `test/deepseek-route-config.test.ts`.
+ *
+ * @module deepseek-route-config
+ */
+
+import fs from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { probePathKind } from './utils/bounded-path-probe.js';
+import {
+  deepSeekProfileFromManifest,
+  isProfileDirName,
+  resolveDefaultDeepSeekProfile,
+  type DeepSeekProfile,
+} from './utils/deepseek-cli-resolver.js';
+
+/** The dsh-TUI bundle a profile must compose for its route to be read here. */
+export const DSH_TUI_PACKAGE = '@deepseek-harness-tui/dsh-tui';
+/** The loader row dsh-TUI's own config lives on. */
+export const DSH_TUI_ROW_ID = 'dsh-tui';
+/** Largest file read: a patch layer is a few dozen lines. */
+export const MAX_ROUTE_FILE_BYTES = 64 * 1024;
+/** A profile name as the launch accepts it (the `path-segment` token pattern). */
+const PROFILE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** How many profile directories the default-profile inventory looks at. */
+const MAX_PROFILES = 64;
+
+/** What one patch item does to the dsh-TUI row. */
+export interface DshTuiRowPatch {
+  /** `name` on the patch; a mismatch makes dsh skip it. */
+  name?: string;
+  /** `disabled` on the patch, when present. */
+  disabled?: boolean;
+  /**
+   * `config` on the patch, when present: the provider and model it names (absent when
+   * it does not name one), or `{}` for a config that is empty or not a mapping.
+   */
+  config?: { provider?: string; model?: string };
+}
+
+/** Thrown inside the parser for anything it does not fully understand. */
+class Ambiguous extends Error {}
+
+/** A nested line naming the dsh-TUI row: a group's config can re-define the row through it. */
+const ROW_ID_LINE = /^(?:-\s+)?id:\s*(['"]?)dsh-tui\1\s*$/;
+
+const KEY_LINE = /^([A-Za-z_][\w-]*):(?:\s+(.*))?$/;
+
+/**
+ * Strip a line's comment (`#` at line start or after whitespace, outside quotes) and
+ * trailing blanks. Throws on an unterminated quote: a multi-line flow scalar is
+ * beyond this reader.
+ */
+function stripComment(line: string): string {
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote === "'") {
+      if (c === "'") {
+        if (line[i + 1] === "'") i++;
+        else quote = null;
+      }
+    } else if (quote === '"') {
+      if (c === '\\') i++;
+      else if (c === '"') quote = null;
+    } else if (c === "'" || c === '"') {
+      // A quote opens a scalar only at its start; inside a plain scalar it is a character.
+      const prev = line.slice(0, i).trimEnd();
+      if (prev === '' || /[:\-[{,]$/.test(prev)) quote = c;
+    } else if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i).trimEnd();
+    }
+  }
+  if (quote) throw new Ambiguous('unterminated quote');
+  return line.trimEnd();
+}
+
+/** Indentation of a line; a tab in it is refused (YAML forbids tabs there). */
+function indentOf(line: string): number {
+  const m = /^[ \t]*/.exec(line)![0];
+  if (m.includes('\t')) throw new Ambiguous('tab indentation');
+  return m.length;
+}
+
+/**
+ * A single-line scalar as a string: plain, or single/double-quoted. Throws on anything
+ * that is not plainly a string (a tag, an anchor, an alias, a flow collection, a
+ * block scalar, or a plain scalar YAML would type as null, a boolean or a number).
+ */
+function stringScalar(raw: string): string {
+  const v = raw.trim();
+  if (v.startsWith("'")) {
+    const m = /^'((?:[^']|'')*)'$/.exec(v);
+    if (!m) throw new Ambiguous('quoted scalar');
+    return m[1].replace(/''/g, "'");
+  }
+  if (v.startsWith('"')) {
+    const m = /^"((?:[^"\\]|\\["\\/])*)"$/.exec(v);
+    if (!m) throw new Ambiguous('quoted scalar');
+    return m[1].replace(/\\(["\\/])/g, '$1');
+  }
+  if (v === '' || /^[!&*[\]{}|>%@`,?:-]/.test(v)) throw new Ambiguous('not a plain string');
+  if (/^(?:~|null|Null|NULL|true|True|TRUE|false|False|FALSE)$/.test(v)) throw new Ambiguous('typed scalar');
+  if (
+    /^[-+]?(?:\.\d+|\d[\d_]*(?:\.\d*)?)(?:[eE][-+]?\d+)?$|^0[xob][0-9a-fA-F_]+$|^[-+]?\.(?:inf|Inf|INF)$|^\.(?:nan|NaN|NAN)$/.test(
+      v
+    )
+  ) {
+    throw new Ambiguous('numeric scalar');
+  }
+  if (/\s#|:\s/.test(v)) throw new Ambiguous('plain scalar with an indicator');
+  return v;
+}
+
+/** `true`/`false` as YAML spells them, or a throw. */
+function boolScalar(raw: string): boolean {
+  const v = raw.trim();
+  if (/^(?:true|True|TRUE)$/.test(v)) return true;
+  if (/^(?:false|False|FALSE)$/.test(v)) return false;
+  throw new Ambiguous('not a boolean');
+}
+
+interface Line {
+  indent: number;
+  text: string;
+}
+
+/**
+ * The direct keys of a block mapping whose lines all sit at `indent` or deeper, each
+ * with its inline value and the lines nested under it. Throws on a line that is not a
+ * key at the mapping's indent, and on a duplicate key (js-yaml refuses those, so dsh
+ * would not boot).
+ */
+function mappingKeys(lines: Line[], indent: number): Map<string, { inline: string | undefined; nested: Line[] }> {
+  const keys = new Map<string, { inline: string | undefined; nested: Line[] }>();
+  let current: { inline: string | undefined; nested: Line[] } | null = null;
+  for (const line of lines) {
+    if (line.indent > indent) {
+      if (!current) throw new Ambiguous('nested line with no key');
+      current.nested.push(line);
+      continue;
+    }
+    if (line.indent < indent) throw new Ambiguous('dedent inside a mapping');
+    const m = KEY_LINE.exec(line.text);
+    if (!m) throw new Ambiguous(`not a key: ${line.text.slice(0, 20)}`);
+    if (keys.has(m[1])) throw new Ambiguous('duplicate key');
+    current = { inline: m[2] === undefined || m[2] === '' ? undefined : m[2], nested: [] };
+    keys.set(m[1], current);
+  }
+  return keys;
+}
+
+/**
+ * Whether an item this reader cannot follow is certainly about another row: a plain
+ * `id:` at the item's indent naming a row other than dsh-TUI, no `insert:` and no
+ * mention of the dsh-TUI row anywhere in it.
+ */
+function isUnrelatedItem(item: Line[]): boolean {
+  const indent = item[0].indent;
+  const top = item.filter((l) => l.indent === indent);
+  if (top.some((l) => /^insert\s*:/.test(l.text))) return false;
+  const ids = top.map((l) => KEY_LINE.exec(l.text)).filter((m) => m?.[1] === 'id');
+  if (ids.length !== 1 || ids[0]![2] === undefined) return false;
+  try {
+    return stringScalar(ids[0]![2]) !== DSH_TUI_ROW_ID;
+  } catch {
+    return false;
+  }
+}
+
+/** The `config` of a dsh-TUI patch: its provider and model, if it names them. */
+function configOf(entry: { inline: string | undefined; nested: Line[] }): { provider?: string; model?: string } {
+  if (entry.inline !== undefined) {
+    if (entry.nested.length) throw new Ambiguous('config with both an inline value and nested lines');
+    const v = entry.inline.trim();
+    // An empty flow mapping or a null names no route; anything else inline (a tag, a
+    // non-empty flow mapping, a block scalar) is beyond this reader.
+    if (v === '{}' || /^(?:~|null|Null|NULL)$/.test(v)) return {};
+    throw new Ambiguous('inline config');
+  }
+  if (!entry.nested.length) return {};
+  const keys = mappingKeys(entry.nested, entry.nested[0].indent);
+  const out: { provider?: string; model?: string } = {};
+  for (const field of ['provider', 'model'] as const) {
+    const value = keys.get(field);
+    if (!value) continue;
+    if (value.nested.length || value.inline === undefined) throw new Ambiguous(`${field} is not a single-line scalar`);
+    out[field] = stringScalar(value.inline);
+  }
+  return out;
+}
+
+/**
+ * What a cordis patch-list file (a top-level YAML array of loader patches) does to the
+ * dsh-TUI row, in order. An empty list when the file does not touch it. Null when the
+ * file is beyond this reader's subset, or when it could re-insert the row.
+ *
+ * @param text the file's content
+ */
+export function parseDshTuiPatches(text: string): DshTuiRowPatch[] | null {
+  try {
+    const lines: Line[] = [];
+    let sawContent = false;
+    for (const rawLine of text.replace(/^\uFEFF/, '').split(/\r?\n/)) {
+      const stripped = stripComment(rawLine);
+      if (stripped.trim() === '') continue;
+      const indent = indentOf(stripped);
+      const body = stripped.slice(indent);
+      if (indent === 0 && body === '---') {
+        if (sawContent) throw new Ambiguous('a second document');
+        continue;
+      }
+      sawContent = true;
+      lines.push({ indent, text: body });
+    }
+    if (lines.length === 0) return [];
+    if (lines.length === 1 && lines[0].indent === 0 && lines[0].text === '[]') return [];
+
+    // Split the top-level block sequence into items.
+    const items: Line[][] = [];
+    for (const line of lines) {
+      if (line.indent === 0) {
+        const m = /^-(?:(\s+)(.*))?$/.exec(line.text);
+        if (!m) throw new Ambiguous('not a top-level sequence');
+        const item: Line[] = [];
+        // `- key: value`: the key sits at its real column, which its siblings below share.
+        if (m[2] !== undefined && m[2] !== '') item.push({ indent: 1 + m[1].length, text: m[2] });
+        items.push(item);
+        continue;
+      }
+      if (items.length === 0) throw new Ambiguous('indented content before the first item');
+      items[items.length - 1].push(line);
+    }
+
+    const patches: DshTuiRowPatch[] = [];
+    for (const item of items) {
+      if (item.length === 0) throw new Ambiguous('empty item');
+      // The first key's column is the item's indent; every key shares it.
+      let keys: ReturnType<typeof mappingKeys>;
+      try {
+        keys = mappingKeys(item, item[0].indent);
+      } catch (err) {
+        // An item this reader cannot follow is harmless only when it provably is about
+        // another row: its own id names one, and no line in it names the dsh-TUI row.
+        if (!(err instanceof Ambiguous) || !isUnrelatedItem(item)) throw err;
+        if (item.slice(1).some((l) => ROW_ID_LINE.test(l.text))) throw new Ambiguous('a nested dsh-tui row');
+        continue;
+      }
+      const id = keys.get('id');
+      if (keys.has('insert')) {
+        // An insert that could bring a second dsh-TUI row is beyond this reader.
+        const body = item.map((l) => l.text).join('\n');
+        if (body.includes(DSH_TUI_ROW_ID)) throw new Ambiguous('insert mentioning the dsh-tui row');
+        continue;
+      }
+      if (!id) continue; // dsh warns and skips a non-insert patch without an id
+      if (id.nested.length || id.inline === undefined) throw new Ambiguous('id is not a scalar');
+      if (stringScalar(id.inline) !== DSH_TUI_ROW_ID) {
+        // Another row; but a group row's config is a list of rows, and one of them could
+        // be a second dsh-TUI row (dsh indexes nested group entries by id too).
+        if (item.slice(1).some((l) => ROW_ID_LINE.test(l.text))) throw new Ambiguous('a nested dsh-tui row');
+        continue;
+      }
+      const patch: DshTuiRowPatch = {};
+      const name = keys.get('name');
+      if (name) {
+        if (name.nested.length || name.inline === undefined) throw new Ambiguous('name is not a scalar');
+        patch.name = stringScalar(name.inline);
+      }
+      const disabled = keys.get('disabled');
+      if (disabled) {
+        if (disabled.nested.length || disabled.inline === undefined) throw new Ambiguous('disabled is not a scalar');
+        patch.disabled = boolScalar(disabled.inline);
+      }
+      const config = keys.get('config');
+      if (config) patch.config = configOf(config);
+      patches.push(patch);
+    }
+    return patches;
+  } catch (err) {
+    if (err instanceof Ambiguous) return null;
+    throw err;
+  }
+}
+
+/**
+ * The model dsh-TUI's route config pins, given what the user layers do to its row in
+ * application order (profile layer first, then the home layer). Null unless the last
+ * `config` that applies names both a provider and a model, and the row is not
+ * disabled. Pure.
+ *
+ * @param layers each layer's patches for the row, or null for a layer that could not be read
+ */
+export function resolveDshTuiRouteModel(layers: Array<DshTuiRowPatch[] | null>): string | null {
+  let config: { provider?: string; model?: string } | undefined;
+  let disabled = false;
+  for (const layer of layers) {
+    if (layer === null) return null;
+    for (const patch of layer) {
+      if (patch.name !== undefined && patch.name !== DSH_TUI_PACKAGE) continue;
+      if (patch.disabled !== undefined) disabled = patch.disabled;
+      if (patch.config !== undefined) config = patch.config;
+    }
+  }
+  if (disabled || !config?.provider || !config.model) return null;
+  return config.model;
+}
+
+/** A file under the dsh home, read only if it provably is one; see {@link readHomeFile}. */
+type FileRead = { state: 'absent' } | { state: 'read'; text: string } | { state: 'refused' };
+
+/**
+ * Read `path`, which must resolve inside `realHome`, bounded: probed first (a mount
+ * that does not answer is refused, never waited on), its real path checked against
+ * the dsh home (a symlink out of it is refused), size-capped.
+ */
+async function readHomeFile(path: string, realHome: string): Promise<FileRead> {
+  const kind = await probePathKind(path);
+  if (kind === 'absent') return { state: 'absent' };
+  if (kind !== 'file') return { state: 'refused' };
+  try {
+    const real = await fs.realpath(path);
+    if (!real.startsWith(realHome + sep)) return { state: 'refused' };
+    const stat = await fs.stat(real);
+    if (!stat.isFile() || stat.size > MAX_ROUTE_FILE_BYTES) return { state: 'refused' };
+    return { state: 'read', text: await fs.readFile(real, 'utf8') };
+  } catch {
+    return { state: 'refused' };
+  }
+}
+
+/**
+ * The dsh home a session runs against: its own `DSH_HOME` (already clamped for a
+ * non-granted owner), else the server's, else `~/.dsh`, as the `dsh` wrapper's
+ * `${DSH_HOME:-...}` resolves it. Null for a relative value, which names no place.
+ */
+export function effectiveDshHome(env: (key: string) => string | undefined): string | null {
+  const value = env('DSH_HOME')?.trim();
+  if (!value) return join(homedir(), '.dsh');
+  return isAbsolute(value) ? resolve(value) : null;
+}
+
+/**
+ * The profiles under a dsh home, read with the same bounded rules as the route files.
+ * Used to name the profile a session boots when it named none, the way the launch's
+ * `launcherDefaultTarget` does (resolveDefaultDeepSeekProfile).
+ */
+async function listProfilesBounded(home: string): Promise<DeepSeekProfile[] | null> {
+  const profilesDir = join(home, 'profiles');
+  if ((await probePathKind(home)) !== 'directory' || (await probePathKind(profilesDir)) !== 'directory') return null;
+  let realHome: string;
+  let names: string[];
+  try {
+    realHome = await fs.realpath(home);
+    names = (await fs.readdir(profilesDir, { withFileTypes: true }))
+      .filter((e) => e.isDirectory() && isProfileDirName(e.name) && PROFILE_NAME.test(e.name))
+      .map((e) => e.name)
+      .sort((a, b) => a.localeCompare(b))
+      .slice(0, MAX_PROFILES);
+  } catch {
+    return null;
+  }
+  const profiles: DeepSeekProfile[] = [];
+  for (const name of names) {
+    const manifest = await readHomeFile(join(profilesDir, name, 'package.json'), realHome);
+    if (manifest.state !== 'read') continue;
+    const profile = deepSeekProfileFromManifest(name, manifest.text);
+    if (profile) profiles.push(profile);
+  }
+  return profiles;
+}
+
+/** What the reader needs to know about one session. */
+export interface DeepSeekRouteContext {
+  /** The session's `deepSeekConfig.profile`, if any. */
+  profile?: unknown;
+  /** The session's dsh home (see {@link effectiveDshHome}). */
+  home: string | null;
+  /** The server's own dsh home, which names the default profile (as the launch does). */
+  serverHome: string | null;
+}
+
+/**
+ * The model the session's dsh-TUI route config pins, or null when it pins none or the
+ * answer is in any doubt. Read-only and bounded; see the module comment.
+ */
+export async function readDeepSeekRouteModel(ctx: DeepSeekRouteContext): Promise<string | null> {
+  const { home } = ctx;
+  if (!home) return null;
+  // An invalid name reads as unset at launch, so the default applies there too.
+  let profile = typeof ctx.profile === 'string' && PROFILE_NAME.test(ctx.profile) ? ctx.profile : null;
+  if (!profile) {
+    if (!ctx.serverHome) return null;
+    const listed = await listProfilesBounded(ctx.serverHome);
+    profile = listed ? resolveDefaultDeepSeekProfile(listed) : null;
+    if (!profile) return null;
+  }
+  if ((await probePathKind(home)) !== 'directory') return null;
+  let realHome: string;
+  try {
+    realHome = await fs.realpath(home);
+  } catch {
+    return null;
+  }
+  const profileDir = join(home, 'profiles', profile);
+  const manifest = await readHomeFile(join(profileDir, 'package.json'), realHome);
+  if (manifest.state !== 'read') return null;
+  if (!deepSeekProfileFromManifest(profile, manifest.text)?.bundles.includes(DSH_TUI_PACKAGE)) return null;
+
+  const layers: Array<DshTuiRowPatch[] | null> = [];
+  for (const file of [join(profileDir, 'cordis.patch.yml'), join(home, 'cordis.patch.yml')]) {
+    const read = await readHomeFile(file, realHome);
+    if (read.state === 'refused') return null;
+    layers.push(read.state === 'absent' ? [] : parseDshTuiPatches(read.text));
+  }
+  return resolveDshTuiRouteModel(layers);
+}

src/git-workspace-status.ts

@@ -0,0 +1,801 @@
+/**
+ * @fileoverview "What has this session's workspace not committed or pushed?": a read-only git
+ * snapshot of a session's working directory, for the bottom-bar Git indicator and its panel
+ * (`GET /api/sessions/:id/git-status`). Agents leave work uncommitted and unpushed; this makes that
+ * visible without leaving Codeman.
+ *
+ * Split so the parts that matter test without a repo:
+ *   - pure: `parsePorcelainV2` (status output → branch, upstream, ahead/behind, per-file entries),
+ *     `parseCommitLog`
+ *   - IO: `getGitWorkspaceStatus` (a handful of async, bounded, read-only `git` calls), with a short
+ *     single-flight cache so several tabs polling one repo cost one set of git processes
+ *
+ * WHICH repositories. `getGitWorkspaceOverview` answers for the session's working directory:
+ *   - inside a repository (or at its root): that one repository. git finds it by walking UP, so a
+ *     subfolder reports its whole enclosing repo; a nested repo below it is just an untracked folder
+ *     to the outer one, and is not scanned;
+ *   - NOT inside one (a folder that holds several projects): every repository found up to two levels
+ *     DOWN (the caller's `maxRepos` of them, `MAX_REPOS` by default, skipping dot-folders, `node_modules`
+ *     and the like, never following symlinks), each reported separately;
+ *   - a repository that merely sits ABOVE the workspace and is the home folder or higher (a dotfiles
+ *     repo in `$HOME`, or `/`) is ignored: its dirty files are not this session's work.
+ *
+ * Rules the code keeps and the tests pin:
+ *   - READ-ONLY and OFFLINE. It never fetches, pulls, commits or writes. "Behind" therefore reflects
+ *     the last fetch (the UI says so); "ahead" and the unpushed list are exact against the
+ *     remote-tracking refs already on disk. `--no-optional-locks` keeps `git status` from even
+ *     refreshing the index, so polling cannot contend with the agent's own git commands.
+ *   - Every call is async (`execFile`), bounded by a timeout, and never interpolates a path into a
+ *     shell: the working directory is the process `cwd`, and the only operand-like input is a fixed
+ *     revision range.
+ *   - Output is capped: the counts are exact, the lists are not (`filesTruncated`).
+ *   - git can run helpers a repository configures: a clean filter (`filter.<name>.clean`) still runs
+ *     during `git status` and `git diff`, as it does for any `git status`. A LOCAL session already
+ *     runs as this same OS user, so polling adds no privilege there. What is turned off: the
+ *     filesystem monitor (`core.fsmonitor`), external diff and textconv drivers, and the signature
+ *     program (`log.showSignature`). A repository a container can write to is NOT inspected: a
+ *     Docker session answers `unsupported`, and any repository whose root is, or is inside, a Docker
+ *     case workspace is dropped from the walk-up, the scan below a folder, and the diff route, because
+ *     the container could have planted that config and git here would run it on the host.
+ *   - Remote URLs and git's stderr can embed `user:token@host`; anything that reaches a client goes
+ *     through `redactGitCredentials`.
+ *
+ * @module git-workspace-status
+ */
+
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, relative, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { gitNonInteractiveEnv, redactGitCredentials } from './git-clone.js';
+
+const execFileAsync = promisify(execFile);
+
+/** How long one git command may run, unless the caller passes `timeoutMs` (a slow network share needs more). */
+export const DEFAULT_GIT_TIMEOUT_MS = 30_000;
+export const MIN_GIT_TIMEOUT_MS = 5_000;
+export const MAX_GIT_TIMEOUT_MS = 120_000;
+/** `git status` on a huge tree can print a lot; a bound on what we will hold. */
+const MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+/** Max file rows returned. The counts stay exact. */
+export const MAX_FILES = 300;
+/** Max unpushed commits listed. The count stays exact. */
+export const MAX_COMMITS = 50;
+/** A fresh-enough result is reused, so N tabs on one repo cost one set of git calls. */
+const CACHE_TTL_MS = 4000;
+const CACHE_MAX_ENTRIES = 64;
+
+export type GitFileKind = 'staged' | 'unstaged' | 'untracked' | 'conflicted';
+
+export interface GitFileEntry {
+  /** Path relative to the repository root, as git reports it. */
+  path: string;
+  /** Rename/copy source, when the entry is one. */
+  origPath?: string;
+  /** Status letter in the index (`M`, `A`, `D`, `R`, `C`, `T`, `.`). */
+  index: string;
+  /** Status letter in the working tree (`M`, `D`, `T`, `.`, ...). `?` for untracked. */
+  worktree: string;
+  kind: GitFileKind;
+}
+
+export interface GitCommitEntry {
+  hash: string;
+  author: string;
+  /** Seconds since the epoch. */
+  time: number;
+  subject: string;
+}
+
+export interface GitWorkspaceStatus {
+  /**
+   * `ok`: a repository, the rest of the fields are meaningful. `not-a-repo`: nothing to show.
+   * `unsupported`: a remote or Docker session (never inspected). `error`: git failed; see `error`.
+   */
+  state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
+  reason?: 'remote' | 'docker';
+  error?: string;
+  repoRoot?: string;
+  /** Null when HEAD is detached. */
+  branch: string | null;
+  detached: boolean;
+  upstream: string | null;
+  /**
+   * The configured upstream does not exist on the remote (deleted and pruned, or never pushed, as after
+   * cloning an empty repository and committing): nothing is tracked.
+   */
+  upstreamGone: boolean;
+  ahead: number;
+  /** Behind the remote-tracking ref as of the LAST FETCH; this module never fetches. */
+  behind: number;
+  /** Whether the repository has any remote at all. */
+  hasRemote: boolean;
+  counts: {
+    staged: number;
+    unstaged: number;
+    untracked: number;
+    conflicted: number;
+    /** Distinct paths that are not committed. */
+    uncommitted: number;
+    stashes: number;
+  };
+  files: GitFileEntry[];
+  filesTruncated: boolean;
+  /** Commits on this branch that no remote has: exact. */
+  unpushedCount: number;
+  unpushed: GitCommitEntry[];
+  checkedAt: number;
+}
+
+const EMPTY: Omit<GitWorkspaceStatus, 'state' | 'checkedAt'> = {
+  branch: null,
+  detached: false,
+  upstream: null,
+  upstreamGone: false,
+  ahead: 0,
+  behind: 0,
+  hasRemote: false,
+  counts: { staged: 0, unstaged: 0, untracked: 0, conflicted: 0, uncommitted: 0, stashes: 0 },
+  files: [],
+  filesTruncated: false,
+  unpushedCount: 0,
+  unpushed: [],
+};
+
+export const emptyStatus = (
+  state: GitWorkspaceStatus['state'],
+  extra: Partial<GitWorkspaceStatus> = {}
+): GitWorkspaceStatus => ({ ...EMPTY, counts: { ...EMPTY.counts }, state, checkedAt: Date.now(), ...extra });
+
+// ---------------------------------------------------------------------------
+// Pure parsing
+// ---------------------------------------------------------------------------
+
+export interface ParsedStatus {
+  branch: string | null;
+  detached: boolean;
+  upstream: string | null;
+  /** `# branch.upstream` was printed but `# branch.ab` was not: no such remote branch (deleted and pruned, or never pushed). */
+  upstreamGone: boolean;
+  ahead: number;
+  behind: number;
+  files: GitFileEntry[];
+}
+
+/**
+ * Parse `git status --porcelain=v2 --branch -z`. Entries are NUL-separated and paths are NOT quoted,
+ * so a name with spaces, quotes or a newline arrives intact. A rename/copy (`2 ...`) is followed by
+ * one more NUL-terminated token holding the original path.
+ */
+export function parsePorcelainV2(text: string): ParsedStatus {
+  const out: ParsedStatus = {
+    branch: null,
+    detached: false,
+    upstream: null,
+    upstreamGone: false,
+    ahead: 0,
+    behind: 0,
+    files: [],
+  };
+  let sawAb = false;
+  const tokens = text.split('\0');
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (!t) continue;
+    if (t.startsWith('# ')) {
+      const [key, ...rest] = t.slice(2).split(' ');
+      const value = rest.join(' ');
+      if (key === 'branch.head') {
+        out.detached = value === '(detached)';
+        out.branch = out.detached ? null : value;
+      } else if (key === 'branch.upstream') {
+        out.upstream = value;
+      } else if (key === 'branch.ab') {
+        sawAb = true;
+        const m = /^\+(\d+) -(\d+)$/.exec(value);
+        if (m) {
+          out.ahead = Number(m[1]);
+          out.behind = Number(m[2]);
+        }
+      }
+      continue;
+    }
+    const type = t[0];
+    if (type === '1') {
+      // 1 XY sub mH mI mW hH hI path
+      const f = t.split(' ');
+      const xy = f[1] ?? '..';
+      out.files.push(...entriesFor(xy, f.slice(8).join(' ')));
+    } else if (type === '2') {
+      // 2 XY sub mH mI mW hH hI Xscore path  <NUL> origPath
+      const f = t.split(' ');
+      const xy = f[1] ?? '..';
+      const path = f.slice(9).join(' ');
+      const origPath = tokens[++i] ?? '';
+      out.files.push(...entriesFor(xy, path, origPath));
+    } else if (type === 'u') {
+      // u XY sub m1 m2 m3 mW h1 h2 h3 path
+      const f = t.split(' ');
+      out.files.push({
+        path: f.slice(10).join(' '),
+        index: f[1]?.[0] ?? 'U',
+        worktree: f[1]?.[1] ?? 'U',
+        kind: 'conflicted',
+      });
+    } else if (type === '?') {
+      out.files.push({ path: t.slice(2), index: '?', worktree: '?', kind: 'untracked' });
+    }
+    // '!' (ignored) is not requested; anything unknown is skipped rather than guessed at.
+  }
+  out.upstreamGone = out.upstream !== null && !sawAb;
+  return out;
+}
+
+/** One porcelain entry can be both staged AND modified in the tree: that is two rows, one per kind. */
+function entriesFor(xy: string, path: string, origPath?: string): GitFileEntry[] {
+  const index = xy[0] ?? '.';
+  const worktree = xy[1] ?? '.';
+  const rows: GitFileEntry[] = [];
+  const base = origPath ? { path, origPath } : { path };
+  if (index !== '.') rows.push({ ...base, index, worktree, kind: 'staged' });
+  if (worktree !== '.') rows.push({ ...base, index, worktree, kind: 'unstaged' });
+  return rows;
+}
+
+/** Parse `git log --format=%h%x1f%an%x1f%ct%x1f%s%x1e`. */
+export function parseCommitLog(text: string): GitCommitEntry[] {
+  const out: GitCommitEntry[] = [];
+  for (const record of text.split('\x1e')) {
+    const r = record.replace(/^\n+/, '');
+    if (!r) continue;
+    const [hash, author, time, ...subject] = r.split('\x1f');
+    if (!hash) continue;
+    out.push({ hash, author: author ?? '', time: Number(time) || 0, subject: subject.join('\x1f') });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// IO
+// ---------------------------------------------------------------------------
+
+/** Runs `git <args>` in `cwd` and returns stdout. Injected so the cache and error paths test without git. */
+export type GitRunner = (cwd: string, args: string[], opts?: { timeoutMs?: number }) => Promise<string>;
+
+export const runGit: GitRunner = async (cwd, args, opts) => {
+  const { stdout } = await execFileAsync(
+    'git',
+    // --no-optional-locks: never touch the index just to look. core.fsmonitor=false: do not start or
+    // consult a filesystem monitor on behalf of a poll. log.showSignature=false: `git log` must not run
+    // a configured gpg.program to verify signatures.
+    ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'log.showSignature=false', ...args],
+    {
+      cwd,
+      timeout: opts?.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
+      maxBuffer: MAX_OUTPUT_BYTES,
+      env: { ...gitNonInteractiveEnv(), LC_ALL: 'C', LANG: 'C', GIT_OPTIONAL_LOCKS: '0' },
+    }
+  );
+  return stdout;
+};
+
+function describeFailure(err: unknown): { notARepo: boolean; message: string } {
+  const e = err as { code?: unknown; stderr?: unknown; message?: string };
+  const stderr = typeof e.stderr === 'string' ? e.stderr : '';
+  if (/not a git repository/i.test(stderr)) return { notARepo: true, message: '' };
+  if (e.code === 'ENOENT') return { notARepo: false, message: 'git is not installed (or the folder no longer exists)' };
+  if (e.code === 'ETIMEDOUT' || (err as { killed?: boolean }).killed)
+    return { notARepo: false, message: 'git timed out' };
+  const text = (stderr || e.message || 'git failed').trim().split('\n')[0];
+  return { notARepo: false, message: redactGitCredentials(text).slice(0, 300) };
+}
+
+async function collect(cwd: string, git: GitRunner, timeoutMs?: number): Promise<GitWorkspaceStatus> {
+  let statusText: string;
+  try {
+    statusText = await git(
+      cwd,
+      ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=normal', '--ignore-submodules=dirty'],
+      { timeoutMs }
+    );
+  } catch (err) {
+    const f = describeFailure(err);
+    return f.notARepo ? emptyStatus('not-a-repo') : emptyStatus('error', { error: f.message });
+  }
+  const parsed = parsePorcelainV2(statusText);
+
+  const safe = async (args: string[]): Promise<string> => {
+    try {
+      return await git(cwd, args, { timeoutMs });
+    } catch {
+      return '';
+    }
+  };
+
+  // A configured upstream whose remote branch is gone has no `branch.ab`, and `@{upstream}` no longer
+  // resolves: treat it as no usable upstream rather than letting the failed rev-list read as 0.
+  const hasUpstream = parsed.upstream !== null && !parsed.upstreamGone;
+  // With an upstream: what is ahead of it. Without one (a branch never pushed, a detached HEAD, or an
+  // upstream that is gone): what is on HEAD but on no remote-tracking ref at all.
+  const range = hasUpstream ? ['@{upstream}..HEAD'] : ['HEAD', '--not', '--remotes'];
+  const [root, remotes, stash, countText, logText] = await Promise.all([
+    safe(['rev-parse', '--show-toplevel']),
+    safe(['remote']),
+    safe(['stash', 'list', '--format=%gd']),
+    safe(['rev-list', '--count', ...range]),
+    safe(['log', `--max-count=${MAX_COMMITS}`, '--format=%h%x1f%an%x1f%ct%x1f%s%x1e', ...range]),
+  ]);
+
+  const hasRemote = remotes.trim().length > 0;
+  // A repository with no remote has nothing to push to, so "unpushed" would be every commit it has.
+  const unpushedCount = hasUpstream || hasRemote ? Number(countText.trim()) || 0 : 0;
+  const unpushed = unpushedCount > 0 ? parseCommitLog(logText) : [];
+
+  const counts = { staged: 0, unstaged: 0, untracked: 0, conflicted: 0, uncommitted: 0, stashes: 0 };
+  const distinct = new Set<string>();
+  for (const f of parsed.files) {
+    counts[f.kind]++;
+    distinct.add(f.path);
+  }
+  counts.uncommitted = distinct.size;
+  counts.stashes = stash.split('\n').filter(Boolean).length;
+
+  return {
+    state: 'ok',
+    repoRoot: root.trim() || undefined,
+    branch: parsed.branch,
+    detached: parsed.detached,
+    upstream: parsed.upstream,
+    upstreamGone: parsed.upstreamGone,
+    ahead: parsed.ahead,
+    behind: parsed.behind,
+    hasRemote,
+    counts,
+    files: parsed.files.slice(0, MAX_FILES),
+    filesTruncated: parsed.files.length > MAX_FILES,
+    unpushedCount,
+    unpushed,
+    checkedAt: Date.now(),
+  };
+}
+
+interface CacheEntry<T> {
+  at: number;
+  value?: T;
+  inflight?: Promise<T>;
+}
+const cache = new Map<string, CacheEntry<GitWorkspaceStatus>>();
+
+/** For tests. */
+export function clearGitStatusCache(): void {
+  cache.clear();
+  toplevelCache.clear();
+  discoveryCache.clear();
+}
+
+/**
+ * `compute()` for `key`, single-flight and briefly cached: concurrent callers share the computation in
+ * flight, and a result younger than `CACHE_TTL_MS` is reused. `fresh` skips the reuse (a person pressed
+ * Refresh and expects the truth) but still joins a computation that is already running, which is as
+ * current as a new one would be.
+ */
+async function singleFlight<T>(
+  map: Map<string, CacheEntry<T>>,
+  key: string,
+  opts: { now: () => number; fresh?: boolean },
+  compute: () => Promise<T>
+): Promise<T> {
+  const hit = map.get(key);
+  if (hit?.inflight) return hit.inflight;
+  if (!opts.fresh && hit?.value !== undefined && opts.now() - hit.at < CACHE_TTL_MS) return hit.value;
+
+  const inflight = compute();
+  map.set(key, { at: opts.now(), inflight });
+  try {
+    const value = await inflight;
+    map.set(key, { at: opts.now(), value });
+    if (map.size > CACHE_MAX_ENTRIES) {
+      for (const [k, v] of map) {
+        if (map.size <= CACHE_MAX_ENTRIES) break;
+        if (k !== key && !v.inflight) map.delete(k);
+      }
+    }
+    return value;
+  } catch (err) {
+    map.delete(key);
+    throw err;
+  }
+}
+
+/**
+ * The git snapshot of `cwd`. Concurrent callers share one in-flight computation, and a result younger
+ * than a few seconds is reused, so several tabs polling one repo cost one set of git processes.
+ * `fresh` skips the reuse but still joins a computation already running (see `singleFlight`).
+ */
+export async function getGitWorkspaceStatus(
+  cwd: string,
+  opts: { git?: GitRunner; now?: () => number; fresh?: boolean; timeoutMs?: number } = {}
+): Promise<GitWorkspaceStatus> {
+  const git = opts.git ?? runGit;
+  return singleFlight(cache, cwd, { now: opts.now ?? Date.now, fresh: opts.fresh }, () =>
+    collect(cwd, git, opts.timeoutMs)
+  );
+}
+
+type RepoToplevel = { state: 'ok'; root: string } | { state: 'not-a-repo' } | { state: 'error'; error: string };
+const toplevelCache = new Map<string, CacheEntry<RepoToplevel>>();
+
+/** The root of the repository enclosing `cwd` (git walks up), from one cheap `rev-parse`. Cached like the status. */
+function enclosingRepoRoot(
+  cwd: string,
+  opts: { git?: GitRunner; now?: () => number; fresh?: boolean; timeoutMs?: number }
+): Promise<RepoToplevel> {
+  const git = opts.git ?? runGit;
+  return singleFlight(toplevelCache, cwd, { now: opts.now ?? Date.now, fresh: opts.fresh }, async () => {
+    try {
+      const root = (await git(cwd, ['rev-parse', '--show-toplevel'], { timeoutMs: opts.timeoutMs })).trim();
+      return root ? { state: 'ok', root } : { state: 'not-a-repo' };
+    } catch (err) {
+      const f = describeFailure(err);
+      return f.notARepo ? { state: 'not-a-repo' } : { state: 'error', error: f.message };
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Which repositories: the overview
+// ---------------------------------------------------------------------------
+
+/** How far below the working directory to look for repositories (`cwd/a/b` is found, `cwd/a/b/c` is not). */
+const DISCOVERY_MAX_DEPTH = 2;
+/** Directory entries inspected per folder (after sorting), so a folder with thousands of children stays cheap. */
+const DISCOVERY_MAX_ENTRIES = 300;
+/** Repositories reported for one workspace. */
+export const MAX_REPOS = 12;
+/** The most repositories a caller may ask for: each one costs several git processes per poll. */
+export const MAX_REPOS_LIMIT = 50;
+
+/** `value` as a whole number within [min, max], else `fallback`. For options that arrive as untrusted query strings. */
+export function clampInt(value: unknown, min: number, max: number, fallback: number): number {
+  // An empty string is "not given", not 0 (Number('') is 0, which would clamp to the minimum).
+  const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
+/** The list of repositories under a folder changes rarely, so it is re-scanned far less often than status. */
+const DISCOVERY_TTL_MS = 30_000;
+/** Folders that are never worth descending into when looking for projects. */
+const DISCOVERY_SKIP = new Set(['node_modules', 'dist', 'build', 'target', '__pycache__', 'venv', 'vendor']);
+/** Status calls in flight at once for one overview: each is several git processes. */
+const STATUS_CONCURRENCY = 4;
+
+export interface GitRepoEntry {
+  /** Folder name of the repository (its root's basename). */
+  name: string;
+  /** The repository root relative to the working directory: `.`, `..`, `api`, `apps/web`. */
+  path: string;
+  status: GitWorkspaceStatus;
+}
+
+export interface GitWorkspaceOverview {
+  /** `ok` when at least one repository was found; the other states are as in `GitWorkspaceStatus`. */
+  state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
+  reason?: 'remote' | 'docker';
+  error?: string;
+  repos: GitRepoEntry[];
+  /** More than `repoLimit` repositories were found; only the first are reported. */
+  reposTruncated: boolean;
+  /** The most repositories this overview would list (the caller's setting, or `MAX_REPOS`). */
+  repoLimit?: number;
+  checkedAt: number;
+}
+
+export const emptyOverview = (
+  state: GitWorkspaceOverview['state'],
+  extra: Partial<GitWorkspaceOverview> = {}
+): GitWorkspaceOverview => ({ state, repos: [], reposTruncated: false, checkedAt: Date.now(), ...extra });
+
+const realOr = async (p: string): Promise<string> => {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return p;
+  }
+};
+
+/** Real paths of `dirs` (a Docker case workspace may be reached through a symlink). */
+const realAll = (dirs: string[]): Promise<string[]> => Promise.all(dirs.map(realOr));
+
+const isWithin = (child: string, root: string): boolean => child === root || child.startsWith(root + sep);
+
+/**
+ * True when `path` is, or is inside, any of the (already real) `roots`. Used for Docker case
+ * workspaces: a container can write there, so git must not run on its behalf on the host.
+ */
+export async function isInsideAny(path: string, realRoots: string[]): Promise<boolean> {
+  if (!realRoots.length) return false;
+  const real = await realOr(path);
+  return realRoots.some((r) => isWithin(real, r));
+}
+
+/**
+ * True when `repoRoot` is a repository that merely contains the workspace and is the home folder or
+ * above it (`$HOME` managed as a dotfiles repo, `/`, `/home`): its changes are not the session's work.
+ * A workspace that IS the repository root is never "unrelated", even when that root is the home folder.
+ */
+export async function isUnrelatedAncestor(repoRoot: string, cwd: string, home: string): Promise<boolean> {
+  const [root, here, h] = await Promise.all([realOr(repoRoot), realOr(cwd), realOr(home)]);
+  if (root === here) return false;
+  return root === sep || h === root || h.startsWith(root + sep);
+}
+
+async function hasDotGit(dir: string): Promise<boolean> {
+  try {
+    await fs.lstat(join(dir, '.git')); // a directory, or a file (worktrees and submodules)
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Most directory entries READ from one folder before sorting and slicing, so the scan of a huge folder is bounded. */
+const DISCOVERY_MAX_SCAN = 5000;
+
+/** Up to `DISCOVERY_MAX_SCAN` entries of `dir` (null when unreadable). */
+async function readDirBounded(dir: string): Promise<import('node:fs').Dirent[] | null> {
+  let handle;
+  try {
+    handle = await fs.opendir(dir);
+  } catch {
+    return null;
+  }
+  const out: import('node:fs').Dirent[] = [];
+  try {
+    for await (const e of handle) {
+      out.push(e);
+      if (out.length >= DISCOVERY_MAX_SCAN) break;
+    }
+  } catch {
+    /* a folder that fails mid-read: use what was read */
+  } finally {
+    await handle.close().catch(() => {});
+  }
+  return out;
+}
+
+/** Repositories up to `DISCOVERY_MAX_DEPTH` levels below `cwd`, nearest and alphabetical first. Never follows symlinks. */
+export async function discoverChildRepos(
+  cwd: string,
+  excludeRealRoots: string[] = [],
+  maxRepos: number = MAX_REPOS
+): Promise<{ dirs: string[]; truncated: boolean }> {
+  const found: string[] = [];
+  let level = [cwd];
+  for (let depth = 1; depth <= DISCOVERY_MAX_DEPTH && level.length > 0; depth++) {
+    const next: string[] = [];
+    for (const dir of level) {
+      const entries = await readDirBounded(dir);
+      if (!entries) continue;
+      entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+      entries.length = Math.min(entries.length, DISCOVERY_MAX_ENTRIES);
+      for (const e of entries) {
+        // isDirectory() is false for a symlink, which is how a link to elsewhere is never followed.
+        if (!e.isDirectory() || e.name.startsWith('.') || DISCOVERY_SKIP.has(e.name)) continue;
+        const child = join(dir, e.name);
+        // A Docker case workspace (or anything inside one) is never inspected, nor descended into.
+        if (await isInsideAny(child, excludeRealRoots)) continue;
+        if (await hasDotGit(child)) found.push(child);
+        else next.push(child);
+      }
+    }
+    level = next;
+  }
+  return { dirs: found.slice(0, maxRepos), truncated: found.length > maxRepos };
+}
+
+const discoveryCache = new Map<string, { at: number; value: { dirs: string[]; truncated: boolean } }>();
+
+/** Run `fn` over `items` with at most `limit` in flight, keeping the input order. */
+async function mapLimited<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return out;
+}
+
+export interface GitOverviewOptions {
+  git?: GitRunner;
+  now?: () => number;
+  fresh?: boolean;
+  home?: string;
+  /** Docker case workspaces (host paths): repositories at or inside these are never inspected. */
+  dockerWorkspaces?: string[];
+  /** How many repositories to report below a folder that is not itself a repository (1 to `MAX_REPOS_LIMIT`, default `MAX_REPOS`). */
+  maxRepos?: number;
+  /** How long one git command may run, in ms (`MIN_GIT_TIMEOUT_MS` to `MAX_GIT_TIMEOUT_MS`, default `DEFAULT_GIT_TIMEOUT_MS`). */
+  timeoutMs?: number;
+}
+
+/** The repository limit and git timeout an overview was computed with, from untrusted options. */
+export function resolveOverviewLimits(opts: { maxRepos?: unknown; timeoutMs?: unknown }): {
+  maxRepos: number;
+  timeoutMs: number;
+} {
+  return {
+    maxRepos: clampInt(opts.maxRepos, 1, MAX_REPOS_LIMIT, MAX_REPOS),
+    timeoutMs: clampInt(opts.timeoutMs, MIN_GIT_TIMEOUT_MS, MAX_GIT_TIMEOUT_MS, DEFAULT_GIT_TIMEOUT_MS),
+  };
+}
+
+type WorkspaceRepos =
+  | { kind: 'docker' }
+  | { kind: 'error'; error: string }
+  | { kind: 'enclosing'; root: string }
+  | { kind: 'children'; dirs: string[]; truncated: boolean; limit: number };
+
+/**
+ * WHICH repositories belong to the workspace (the module header has the rules), without a full
+ * status of any of them: one cached `rev-parse` for the enclosing repository, else the cached scan
+ * below the folder. The overview and the diff route both go through here, so they cannot disagree.
+ */
+async function resolveWorkspaceRepos(cwd: string, opts: GitOverviewOptions): Promise<WorkspaceRepos> {
+  const now = opts.now ?? Date.now;
+  const { maxRepos, timeoutMs } = resolveOverviewLimits(opts);
+  const dockerRoots = await realAll(opts.dockerWorkspaces ?? []);
+  // Checked BEFORE any git runs: git walks up from cwd, and a repository the container can write to
+  // could carry config (a clean filter) that runs on the host.
+  if (await isInsideAny(cwd, dockerRoots)) return { kind: 'docker' };
+  // The enclosing repository is identified before its full status runs, so an unrelated one above the
+  // workspace (a dotfiles repo in $HOME) costs one rev-parse, and its status failing cannot hide the
+  // repositories below.
+  const top = await enclosingRepoRoot(cwd, { ...opts, timeoutMs });
+  if (top.state === 'error') return { kind: 'error', error: top.error };
+  if (top.state === 'ok') {
+    if (await isInsideAny(top.root, dockerRoots)) return { kind: 'docker' };
+    if (!(await isUnrelatedAncestor(top.root, cwd, opts.home ?? homedir())))
+      return { kind: 'enclosing', root: top.root };
+  }
+
+  // Not inside a repository of this workspace: look below for projects.
+  // Keyed by the limit too: a list cut at 12 must not answer a request for 30.
+  const discoveryKey = `${cwd}\0${maxRepos}`;
+  const hit = discoveryCache.get(discoveryKey);
+  let found: { dirs: string[]; truncated: boolean };
+  if (!opts.fresh && hit && now() - hit.at < DISCOVERY_TTL_MS) found = hit.value;
+  else {
+    found = await discoverChildRepos(cwd, dockerRoots, maxRepos);
+    discoveryCache.set(discoveryKey, { at: now(), value: found });
+    if (discoveryCache.size > CACHE_MAX_ENTRIES) discoveryCache.delete(discoveryCache.keys().next().value as string);
+  }
+  // The cached list can predate a Docker case linked since: filter it against the roots as they are NOW.
+  const dirs: string[] = [];
+  for (const dir of found.dirs) if (!(await isInsideAny(dir, dockerRoots))) dirs.push(dir);
+  return { kind: 'children', dirs, truncated: found.truncated, limit: maxRepos };
+}
+
+/**
+ * Everything git knows about the session's workspace: the enclosing repository when there is one,
+ * otherwise each repository found below the working directory. See the module header for the rules.
+ */
+export async function getGitWorkspaceOverview(
+  cwd: string,
+  opts: GitOverviewOptions = {}
+): Promise<GitWorkspaceOverview> {
+  const where = await resolveWorkspaceRepos(cwd, opts);
+  if (where.kind === 'docker') return emptyOverview('unsupported', { reason: 'docker' });
+  if (where.kind === 'error') return emptyOverview('error', { error: where.error });
+  if (where.kind === 'enclosing') {
+    const primary = await getGitWorkspaceStatus(cwd, { ...opts, timeoutMs: resolveOverviewLimits(opts).timeoutMs });
+    if (primary.state === 'error') return emptyOverview('error', { error: primary.error });
+    if (primary.state !== 'ok') return emptyOverview('not-a-repo');
+    const root = primary.repoRoot ?? where.root;
+    return {
+      state: 'ok',
+      repos: [{ name: basename(root), path: relative(cwd, root) || '.', status: primary }],
+      reposTruncated: false,
+      checkedAt: primary.checkedAt,
+    };
+  }
+
+  const timeoutMs = resolveOverviewLimits(opts).timeoutMs;
+  const statuses = await mapLimited(where.dirs, STATUS_CONCURRENCY, (dir) =>
+    getGitWorkspaceStatus(dir, { ...opts, timeoutMs })
+  );
+  const repos: GitRepoEntry[] = [];
+  where.dirs.forEach((dir, i) => {
+    const status = statuses[i];
+    // A repository git could not read (a timeout on a slow share, a broken worktree) stays in the
+    // list with its error, so it is visible that something is not being reported; only a folder
+    // that turned out not to be a repository after all is left out.
+    if (status.state === 'ok' || status.state === 'error')
+      repos.push({ name: basename(dir), path: relative(cwd, dir), status });
+  });
+  if (!repos.length) return emptyOverview('not-a-repo');
+  return { state: 'ok', repos, reposTruncated: where.truncated, repoLimit: where.limit, checkedAt: Date.now() };
+}
+
+/**
+ * `repo` when it is the root of one of the repositories the overview reports for `cwd` (the same rules
+ * and caches, and the Docker roots as they are now), else null. The diff route checks a requested
+ * repository with this rather than recomputing every repository's status.
+ */
+export async function findWorkspaceRepo(
+  cwd: string,
+  repo: string,
+  opts: GitOverviewOptions = {}
+): Promise<string | null> {
+  const where = await resolveWorkspaceRepos(cwd, opts);
+  const roots = where.kind === 'enclosing' ? [where.root] : where.kind === 'children' ? where.dirs : [];
+  // git reports a repository root with symlinks resolved; a discovered folder may be reached through one.
+  for (const root of roots) if (root === repo || (await realOr(root)) === repo) return repo;
+  return null;
+}
+
+// ── Per-file diff ──────────────────────────────────────────────────────────
+
+/** Longest diff handed to the browser; beyond this it is cut at a line boundary and flagged. */
+export const MAX_DIFF_BYTES = 400 * 1024;
+
+export interface GitFileDiff {
+  /** Unified diff text (empty when git reports no textual change, e.g. a mode-only edit shows its header). */
+  diff: string;
+  truncated: boolean;
+  binary: boolean;
+}
+
+/** A repo-relative path git reported, minus anything that could escape the repo. (A leading `-` is fine: every operand follows `--`.) */
+export function isSafeRepoRelativePath(p: string): boolean {
+  if (!p || p.length > 4096 || p.includes('\0') || p.startsWith('/')) return false;
+  return !p.split('/').includes('..');
+}
+
+/**
+ * The diff of one changed file, as the panel's rows describe it: `staged` is index vs HEAD,
+ * `unstaged`/`conflicted` is working tree vs index (a conflict shows git's combined diff), and
+ * `untracked` is the whole file as additions. Read-only. `--no-ext-diff --no-textconv` stop the external
+ * diff and textconv drivers a repository configures; a clean filter still runs, as it does for any
+ * `git diff`, which is why a container-writable repository never reaches this function.
+ */
+export async function getGitFileDiff(
+  repoRoot: string,
+  file: { path: string; origPath?: string; kind: GitFileKind },
+  opts: { git?: GitRunner; timeoutMs?: number } = {}
+): Promise<GitFileDiff> {
+  if (!isSafeRepoRelativePath(file.path) || (file.origPath && !isSafeRepoRelativePath(file.origPath))) {
+    throw new Error('Invalid path');
+  }
+  const git = opts.git ?? runGit;
+  const base = ['diff', '--no-color', '--no-ext-diff', '--no-textconv', '-U3'];
+  let args: string[];
+  if (file.kind === 'untracked') args = [...base, '--no-index', '--', '/dev/null', file.path];
+  else {
+    const paths = file.origPath ? [file.origPath, file.path] : [file.path];
+    args = file.kind === 'staged' ? [...base, '--cached', '-M', '--', ...paths] : [...base, '--', ...paths];
+  }
+  let out: string;
+  let cutShort = false;
+  try {
+    out = await git(repoRoot, args, { timeoutMs: opts.timeoutMs });
+  } catch (err) {
+    const e = err as { code?: unknown; stdout?: unknown };
+    // `--no-index` exits 1 when the files differ, which is the normal case for it.
+    if (file.kind === 'untracked' && e.code === 1 && typeof e.stdout === 'string') out = e.stdout;
+    // A diff past runGit's output bound: git was stopped, and what it printed so far is cut below like
+    // any oversized diff.
+    else if (e.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' && typeof e.stdout === 'string') {
+      out = e.stdout;
+      cutShort = true;
+    } else throw err;
+  }
+  const binary = /^Binary files .* differ$/m.test(out) || /^GIT binary patch$/m.test(out);
+  if (out.length <= MAX_DIFF_BYTES) return { diff: out, truncated: cutShort, binary };
+  const cut = out.lastIndexOf('\n', MAX_DIFF_BYTES);
+  return { diff: out.slice(0, cut > 0 ? cut : MAX_DIFF_BYTES), truncated: true, binary };
+}

src/hooks-config.ts

@@ -30,7 +30,6 @@
  */
 
 import { randomBytes } from 'node:crypto';
-import { existsSync } from 'node:fs';
 import { readFile, writeFile, mkdir, lstat, readdir, realpath, rename, unlink, rmdir, chmod } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -40,6 +39,52 @@ import type { HookEventType } from './types.js';
 import { HOOK_TIMEOUT_SECONDS } from './config/auth-config.js';
 import { dataPath } from './config/instance.js';
 import { readJsonConfig, SETTINGS_PATH } from './web/route-helpers.js';
+import { isNearStalledPath, probePath } from './utils/index.js';
+
+/**
+ * Existence check for a WRITER. Unlike the bounded read-side probe (`probePath`),
+ * which gives up after a timeout and answers "unknown", this waits for the real
+ * answer: only ENOENT reads as absent, anything else throws, so a
+ * stalled or unreadable workspace can never be mistaken for an empty one and
+ * have its settings recreated over the top. It is async, so a dead mount ties
+ * up a threadpool worker rather than the event loop.
+ */
+async function pathExistsForWrite(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+/**
+ * Probe a path a per-spawn helper is about to touch. An "unknown" that is NOT near a
+ * stalled probe (the bulk cap refused it, or the stat failed with something other
+ * than ENOENT) gets ONE more bounded probe past the bulk cap, so a healthy path still
+ * answers while unrelated mounts are dead. Whatever is still "unknown" after that
+ * must be skipped by the caller, never touched with an unbounded `lstat`/`readFile`:
+ * on a dead mount those never settle, and each would hold a threadpool worker the
+ * probe's ceiling does not count.
+ */
+async function probeBeforeTouching(path: string) {
+  const state = await probePath(path);
+  if (state !== 'unknown' || isNearStalledPath(path)) return state;
+  return probePath(path, { pastCap: true });
+}
+
+/**
+ * Whether a READ-side helper should leave `path` alone: it is definitely absent, or
+ * it did not answer (a mount that is not responding, a refused probe, an unreadable
+ * path). See `probeBeforeTouching` for why "unknown" is a skip.
+ */
+async function absentOrUnreachable(path: string): Promise<'absent' | 'unreachable' | false> {
+  const state = await probeBeforeTouching(path);
+  if (state === 'absent') return 'absent';
+  if (state === 'unknown') return 'unreachable';
+  return false;
+}
 
 /**
  * Serializes read-modify-write access to a `settings.local.json` path. Every
@@ -558,7 +603,7 @@ export async function stripCaseEnvKeys(casePath: string, keysToRemove: readonly
   if (keysToRemove.length === 0) return;
 
   await withSafeSettingsWrite(casePath, 'env-key removal', async (_claudeDir, settingsPath) => {
-    if (!existsSync(settingsPath)) return;
+    if (!(await pathExistsForWrite(settingsPath))) return;
 
     let existing: Record<string, unknown>;
     try {
@@ -590,7 +635,7 @@ export async function stripCaseEnvKeys(casePath: string, keysToRemove: readonly
  */
 export async function updateCaseEnvVars(casePath: string, envVars: Record<string, string>): Promise<void> {
   await withSafeSettingsWrite(casePath, 'env vars', async (claudeDir, settingsPath) => {
-    if (!existsSync(claudeDir)) {
+    if (!(await pathExistsForWrite(claudeDir))) {
       await mkdir(claudeDir, { recursive: true });
     }
 
@@ -621,7 +666,7 @@ export async function updateCaseEnvVars(casePath: string, envVars: Record<string
  */
 export async function updateCaseModel(casePath: string, model: string | null): Promise<void> {
   await withSafeSettingsWrite(casePath, 'model', async (claudeDir, settingsPath) => {
-    if (!existsSync(claudeDir)) {
+    if (!(await pathExistsForWrite(claudeDir))) {
       await mkdir(claudeDir, { recursive: true });
     }
 
@@ -650,7 +695,7 @@ export async function updateCaseModel(casePath: string, model: string | null): P
  */
 export async function writeHooksConfig(casePath: string): Promise<void> {
   await withSafeSettingsWrite(casePath, 'hooks', async (claudeDir, settingsPath) => {
-    if (!existsSync(claudeDir)) {
+    if (!(await pathExistsForWrite(claudeDir))) {
       await mkdir(claudeDir, { recursive: true });
     }
 
@@ -698,7 +743,7 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
  */
 export async function ensureCodemanHooks(casePath: string): Promise<void> {
   await withSafeSettingsWrite(casePath, 'hooks (ensure)', async (claudeDir, settingsPath) => {
-    if (!existsSync(claudeDir)) {
+    if (!(await pathExistsForWrite(claudeDir))) {
       await mkdir(claudeDir, { recursive: true });
     }
 
@@ -738,7 +783,7 @@ export async function ensureCodemanHooks(casePath: string): Promise<void> {
  * when the hooks aren't ours, so it is cheap enough to call on every Claude spawn.
  */
 export async function refreshStaleCodemanHooks(casePath: string): Promise<void> {
-  if (!existsSync(join(casePath, '.claude', 'settings.local.json'))) return;
+  if (await absentOrUnreachable(join(casePath, '.claude', 'settings.local.json'))) return;
   await withSafeSettingsWrite(casePath, 'hooks (refresh)', async (_claudeDir, settingsPath) => {
     let existing: Record<string, unknown>;
     try {
@@ -820,7 +865,17 @@ export async function refreshStaleCodemanHooks(casePath: string): Promise<void>
  */
 export async function applyWorkspaceHooks(workspace: string, install?: boolean): Promise<void> {
   try {
-    if (!existsSync(workspace)) return;
+    // "absent" stays absent: the install below would mkdir -p a deleted repo back
+    // into being. "unknown" is skipped too, never asked again with an unbounded
+    // lstat (see probeBeforeTouching).
+    const state = await probeBeforeTouching(workspace);
+    if (state === 'absent') return;
+    if (state === 'unknown') {
+      console.warn(
+        `[hooks] ${workspace} is not responding or not readable (unreachable mount?); Codeman hooks not checked or installed`
+      );
+      return;
+    }
     const shouldInstall = install ?? (await readWorkspaceHooksEnabled());
     await (shouldInstall ? ensureCodemanHooks(workspace) : refreshStaleCodemanHooks(workspace));
   } catch {
@@ -883,7 +938,7 @@ export function generateStatusLineCommand(): string {
 export async function applyStatusLineConfig(casePath: string, enabled: boolean): Promise<void> {
   await withSafeSettingsWrite(casePath, 'statusLine', async (claudeDir, settingsPath) => {
     let existing: Record<string, unknown> = {};
-    if (existsSync(settingsPath)) {
+    if (await pathExistsForWrite(settingsPath)) {
       try {
         existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
       } catch {
@@ -898,7 +953,7 @@ export async function applyStatusLineConfig(casePath: string, enabled: boolean):
       const desired = generateStatusLineCommand();
       if (isOurs && current?.command === desired) return; // already current — skip rewrite
       if (current && !isOurs) return; // user has their OWN statusLine — never clobber it
-      if (!existsSync(claudeDir)) await mkdir(claudeDir, { recursive: true });
+      if (!(await pathExistsForWrite(claudeDir))) await mkdir(claudeDir, { recursive: true });
       existing.statusLine = { type: 'command', command: desired }; // add, or update an out-of-date ours
     } else {
       if (!isOurs) return; // nothing of ours to remove (leave a user's own statusLine alone)
@@ -957,7 +1012,7 @@ function statusLineExporterScriptContent(): string {
 }
 
 async function readStatusLineCommandFromFile(settingsPath: string): Promise<string | undefined> {
-  if (!existsSync(settingsPath)) return undefined;
+  if (await absentOrUnreachable(settingsPath)) return undefined;
   try {
     const parsed = JSON.parse(await readFile(settingsPath, 'utf-8'));
     const current = parsed.statusLine as { command?: unknown } | undefined;
@@ -1103,9 +1158,21 @@ export async function resolveStatusLineCliCommand(
 ): Promise<string | undefined> {
   const settingsPath = join(casePath, '.claude', 'settings.local.json');
   let userHasOwnStatusLine = false;
-  if (existsSync(settingsPath)) {
+  const skip = await absentOrUnreachable(settingsPath);
+  // Unreachable: whether the user configured their own statusLine there cannot be
+  // told, and this must never override a real one, so inject nothing.
+  if (skip === 'unreachable') return undefined;
+  if (!skip) {
+    let raw: string;
     try {
-      const existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+      raw = await readFile(settingsPath, 'utf-8');
+    } catch (err) {
+      // Gone since the probe: nothing to respect. Unreadable: same reason as above.
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return undefined;
+      raw = '';
+    }
+    try {
+      const existing = raw ? JSON.parse(raw) : {};
       const current = existing.statusLine as { command?: unknown } | undefined;
       if (current && typeof current.command === 'string') {
         if (current.command.includes(STATUSLINE_MARKER)) {

src/model-config-resolvers.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview The config readers a CLI's registry entry may name for the model its
+ * session runs (`capabilities.modelDetect.configResolver`): the per-CLI behaviour lives
+ * here, keyed by name, so no code branches on a CLI id (like the launcher profiles in
+ * config/cli-registry/profiles.ts).
+ *
+ * A reader answers the model the CLI's own config pins for one session, or null when
+ * it pins none or the answer is in any doubt. It must be read-only, bounded (no
+ * synchronous filesystem call, nothing that can wait on a dead mount) and must return
+ * the model id alone, never another config value.
+ *
+ * @module model-config-resolvers
+ */
+
+import type { ModelConfigResolverName } from './config/cli-registry/types.js';
+import { effectiveDshHome, readDeepSeekRouteModel } from './deepseek-route-config.js';
+
+/** What a reader gets to know about the session. */
+export interface ModelConfigContext {
+  /** The session's own launch config for its CLI (its `<Mode>Config`), if any. */
+  config: Record<string, unknown> | undefined;
+  /** The environment the session's CLI runs with (its own overrides, then the server's). */
+  env: (key: string) => string | undefined;
+}
+
+const RESOLVERS: Record<ModelConfigResolverName, (ctx: ModelConfigContext) => Promise<string | null>> = {
+  // dsh-TUI's route: the session's profile (else the one the launch boots, which the
+  // launch names from the server's own dsh home) read under the session's dsh home.
+  'deepseek-route': (ctx) =>
+    readDeepSeekRouteModel({
+      profile: ctx.config?.profile,
+      home: effectiveDshHome(ctx.env),
+      serverHome: effectiveDshHome((key) => process.env[key]),
+    }),
+};
+
+/**
+ * The model the named reader resolves for a session, or null.
+ *
+ * @param name a `configResolver` from the registry (schema-checked at load)
+ * @param ctx what the reader may know about the session
+ */
+export async function resolveConfigModel(
+  name: ModelConfigResolverName,
+  ctx: ModelConfigContext
+): Promise<string | null> {
+  const resolver = RESOLVERS[name];
+  return resolver ? resolver(ctx) : null;
+}

src/session-display-model.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview Which model a session is running, as far as the server can know it
+ * (`SessionState.displayModel`, shown in the tile grid's and split pane's headers).
+ *
+ * Pure: the session feeds it what it has and publishes the answer through `toState()`.
+ *
+ * ## Sources, strongest first
+ *
+ * 1. **custom-endpoint**: a session pointed at a Custom Model Endpoint Profile is answered
+ *    by that endpoint's `modelId`, whatever alias the CLI itself prints.
+ * 2. **statusline / screen**: what the running CLI REPORTS, newest report wins. Claude's
+ *    statusLine exporter posts `model.display_name` on every render (it follows an
+ *    in-session `/model`); a CLI whose registry entry declares
+ *    `capabilities.modelDetect` has its footer read off the pane capture the idle/working
+ *    probe already takes.
+ * 3. **config**: the model the CLI's own config pins for this session, read by the
+ *    reader its registry entry names (`capabilities.modelDetect.configResolver`, e.g. the
+ *    dsh-TUI route: src/deepseek-route-config.ts), for while the screen names none. Not
+ *    a report from the running CLI, so any report outranks it.
+ * 4. **launch**: the model the session was launched with (claude's `--model` or the
+ *    app-wide default it was created with; another CLI's `<cli>Config.model`). What was
+ *    asked for, not what was reported, so it only shows when nothing reported.
+ *
+ * Nothing known means no field at all: the header shows the harness logo alone, never a
+ * placeholder or a guess.
+ *
+ * ## Untrusted text
+ *
+ * A screen-read model is pane text, and a statusline payload is a POST body: both are
+ * stripped of escape sequences and control characters, whitespace-collapsed and capped
+ * here, and the browser renders the result with `textContent`.
+ *
+ * Tests: `test/session-display-model.test.ts`.
+ *
+ * @module session-display-model
+ */
+
+import type { DisplayModel, DisplayModelSource } from './types/session.js';
+import { stripAnsi } from './utils/index.js';
+import { getCli } from './config/cli-registry/index.js';
+import { legacyConfigForMode } from './session-cli-registry-bridge.js';
+
+/** Longest model name published (the header truncates long before this). */
+export const MAX_DISPLAY_MODEL_CHARS = 64;
+
+/** A report from the running CLI itself: the sources a restart may restore. */
+export type ReportedModelSource = Extract<DisplayModelSource, 'statusline' | 'screen'>;
+
+export interface ReportedModel {
+  model: string;
+  source: ReportedModelSource;
+}
+
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/g;
+
+/**
+ * A model name fit to publish, or undefined when nothing printable is left.
+ *
+ * @param raw anything; only a string can yield a name
+ */
+export function sanitizeModelName(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined;
+  const clean = stripAnsi(raw).replace(CONTROL_CHARS, ' ').replace(/\s+/g, ' ').trim();
+  if (!clean) return undefined;
+  return clean.slice(0, MAX_DISPLAY_MODEL_CHARS).trimEnd();
+}
+
+/** What a footer field can show that is never the model. */
+export interface ScreenModelRejects {
+  /** The CLI's declared non-model words (`capabilities.modelDetect.rejectWords`), lower-cased compare. */
+  rejectWords?: readonly string[];
+  /** The session's working-directory basename: a footer field equal to it is the folder, exact compare. */
+  cwdBasename?: string;
+}
+
+/**
+ * The model a pane's own chrome shows, read with the CLI's `modelDetect` pattern.
+ *
+ * Only the last `tailRows` non-blank rows are searched (joined with `\n`, so a pattern
+ * can anchor on the row above), which keeps the search below the transcript: the
+ * pattern itself must still anchor on chrome only that CLI draws.
+ *
+ * A footer whose model field is switched off shows its NEXT field where the model
+ * was, so the captured field is not taken when it is one of the CLI's declared
+ * non-model words (an effort level, a mode) or the session's own folder name, which a
+ * footer field equal to is the folder, never the model, whatever the CLI. Anything
+ * else the pattern captures is read as the model.
+ *
+ * @param paneText a plain `capture-pane -p` frame, or null when it could not be read
+ * @param pattern compiled through `compileVersionRegex()`, capture group 1 = the model
+ * @param tailRows how many non-blank rows from the bottom the pattern sees
+ * @param rejects fields that are never the model (see {@link ScreenModelRejects})
+ * @returns the model, or undefined when the frame shows none
+ */
+export function readScreenModel(
+  paneText: string | null | undefined,
+  pattern: RegExp,
+  tailRows: number = 1,
+  rejects: ScreenModelRejects = {}
+): string | undefined {
+  if (!paneText) return undefined;
+  const rows = stripAnsi(paneText)
+    .split('\n')
+    .map((row) => row.trimEnd())
+    .filter((row) => row !== '');
+  const window = rows.slice(-Math.max(1, Math.min(tailRows, 8))).join('\n');
+  // compileVersionRegex() never sets `g`, but a pattern from elsewhere might, and a
+  // stale lastIndex would make the same frame match every other call.
+  pattern.lastIndex = 0;
+  const match = pattern.exec(window);
+  if (!match) return undefined;
+  const field = match[1] ?? '';
+  if (rejects.cwdBasename && field === rejects.cwdBasename) return undefined;
+  if (rejects.rejectWords?.some((word) => word.toLowerCase() === field.toLowerCase())) return undefined;
+  return sanitizeModelName(field);
+}
+
+/**
+ * The model a session was launched with, read the way its spawn reads it: where the
+ * model param lives is registry data (`capabilities.model` names the param, the entry's
+ * `legacyConfigField` the `<Mode>Config` object holding it, or the option bag itself for
+ * claude), never a branch on the CLI id. A CLI whose model is not a launch param (shell,
+ * dsh) has none.
+ *
+ * @param mode the session's CLI id
+ * @param bag the session's launch option bag (`model`, `codexConfig`, ...)
+ */
+export function launchModelFor(mode: string, bag: Record<string, unknown>): string | undefined {
+  const entry = getCli(mode);
+  const model = entry?.capabilities.model;
+  if (!entry || !model || model.source === 'none') return undefined;
+  const param = model.param ?? 'model';
+  const key = entry.launch.legacyConfigAliases?.[param] ?? param;
+  const value = legacyConfigForMode(mode, bag)?.[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * The persisted `displayModel` of a previous run, when it was a report from the CLI
+ * itself: a restart shows it until the next report replaces it. A custom-endpoint or
+ * launch answer is not restored, since the session derives those again by itself.
+ */
+export function restoredReportedModel(saved: unknown): ReportedModel | undefined {
+  if (!saved || typeof saved !== 'object') return undefined;
+  const { model, source } = saved as { model?: unknown; source?: unknown };
+  if (source !== 'statusline' && source !== 'screen') return undefined;
+  const name = sanitizeModelName(model);
+  return name ? { model: name, source } : undefined;
+}
+
+/**
+ * The model a session header shows, and where it came from.
+ *
+ * @param input.customModelId the custom endpoint's model, when the session is pointed at one
+ * @param input.reported the newest report from the CLI itself
+ * @param input.configModel the model the CLI's config pins for the session
+ * @param input.launchModel the model the session was launched with
+ */
+export function resolveDisplayModel(input: {
+  customModelId?: string;
+  reported?: ReportedModel | null;
+  configModel?: string | null;
+  launchModel?: string;
+}): DisplayModel | undefined {
+  const custom = sanitizeModelName(input.customModelId);
+  if (custom) return { model: custom, source: 'custom-endpoint' };
+  const reported = input.reported ? sanitizeModelName(input.reported.model) : undefined;
+  if (reported && input.reported) return { model: reported, source: input.reported.source };
+  const config = sanitizeModelName(input.configModel);
+  if (config) return { model: config, source: 'config' };
+  const launch = sanitizeModelName(input.launchModel);
+  if (launch) return { model: launch, source: 'launch' };
+  return undefined;
+}

src/session.ts

@@ -29,6 +29,7 @@
  */
 
 import { EventEmitter } from 'node:events';
+import { basename } from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 import { v4 as uuidv4 } from 'uuid';
 import * as pty from 'node-pty';
@@ -137,7 +138,18 @@ import {
   sanitizeAttachmentHistory,
   upsertAttachmentHistory as upsertAttachmentHistoryList,
 } from './session-attachment-history.js';
-import type { SessionAttachmentHistoryItem } from './types/session.js';
+import type { SessionAttachmentHistoryItem, DisplayModel } from './types/session.js';
+import { resolveConfigModel } from './model-config-resolvers.js';
+import { legacyConfigForMode } from './session-cli-registry-bridge.js';
+import {
+  launchModelFor,
+  readScreenModel,
+  resolveDisplayModel,
+  restoredReportedModel,
+  sanitizeModelName,
+  type ReportedModel,
+  type ReportedModelSource,
+} from './session-display-model.js';
 
 export type { BackgroundTask } from './task-tracker.js';
 export type { RalphTrackerState, RalphTodoItem, ActiveBashTool } from './types.js';
@@ -265,10 +277,11 @@ function cliExportsTruecolor(mode: SessionMode): boolean {
  * Codex, Claude Code, and Gemini are known, controlled (Ink/React) TUIs that
  * repaint via cursor positioning, so dropping the alt-screen switch is safe —
  * content stays in the normal buffer. Excluded: `shell` (arbitrary programs like
- * vim/less/htop legitimately need the alt screen), `opencode` (renders its own
- * TUI that may rely on it), `pi` (below) and `grok` (a fullscreen alt-screen TUI
- * with mouse support, i.e. the opencode case, not the Ink case). Keep parity
- * with the replay-side strip in session-routes.ts.
+ * vim/less/htop legitimately need the alt screen), `opencode` (its own MIDDLE strip,
+ * isMuxMouseStripMode), `pi` (below) and `grok` (a fullscreen alt-screen TUI with
+ * mouse support). Keep parity with the replay-side strip (`stripReplayBuffer` in
+ * session-routes.ts); the table in `CliCapabilities.altScreen` is pinned for every
+ * stock CLI in test/claude-scrollback-strip.test.ts.
  *
  * ⚠️ Being excluded here does NOT preserve the alt screen. Every excluded mode
  * falls through to isMuxAltScreenOnlyStripMode(), which strips the alt-screen
@@ -288,8 +301,10 @@ export function isAltScreenStripMode(mode: SessionMode): boolean {
 
 /**
  * Modes that need the NARROW strip: alt-screen toggles only, leaving `\x1b[3J`
- * and the mouse-tracking DECSETs alone. Applies to every mode `isAltScreenStripMode`
- * excludes, but ONLY when the session is tmux-backed (`useMux`).
+ * and the mouse-tracking DECSETs alone. Applies to every mode that is neither
+ * `strip-full` (isAltScreenStripMode) nor `strip-mux-and-mouse` (isMuxMouseStripMode),
+ * so `strip-mux-only` and `preserve` alike, but ONLY when the session is tmux-backed
+ * (`useMux`).
  *
  * The bug (issue #205): the tmux CLIENT emits `smcup` (`\x1b[?1049h`) as its first
  * bytes on attach, before any program has run. Unstripped, xterm.js parks in the
@@ -314,7 +329,31 @@ export function isAltScreenStripMode(mode: SessionMode): boolean {
  * `\x1b[3J` from a user's own `clear` is a deliberate "wipe my scrollback".
  */
 export function isMuxAltScreenOnlyStripMode(mode: SessionMode, useMux: boolean): boolean {
-  return useMux && !isAltScreenStripMode(mode);
+  if (!useMux) return false;
+  const altScreen = getCli(mode)?.capabilities.altScreen;
+  return altScreen !== 'strip-full' && altScreen !== 'strip-mux-and-mouse';
+}
+
+/**
+ * Modes whose mouse-tracking DECSETs must be stripped, leaving `3J` alone:
+ * `altScreen: 'strip-mux-and-mouse'`, i.e. a mouse-capable full-screen TUI.
+ *
+ * Why this exists (opencode, measured 2026-09-16): the TUI enables tracking
+ * DECSETs, tmux runs with `mouse off` and therefore passes the PANE's DECSETs
+ * straight through to the tmux client, and the browser's xterm obeyed them —
+ * `mouseTrackingMode` flipped to `'any'` and xterm then reported DRAGS to the TUI
+ * instead of selecting locally. "Mark text, copy on select" silently did nothing
+ * (measured 62 `none` / 18 `any` over 16s, and 5/5 dead drags while `any`), and
+ * the obvious fallback — Ctrl+C — is opencode's `app_exit`, so the failure also
+ * ended sessions. Stripping at the source keeps xterm in selection mode; clicks
+ * still reach the CLI through the browser's hand-encoded tap, which this strip
+ * publishes as `cliMouseTracking` (`_recordStrippedMouseMode`).
+ *
+ * Gated on `useMux` for the same reason as the narrow strip: on the direct-PTY
+ * fallback the program's own DECSETs really do reach xterm and must be honoured.
+ */
+export function isMuxMouseStripMode(mode: SessionMode, useMux: boolean): boolean {
+  return useMux && getCli(mode)?.capabilities.altScreen === 'strip-mux-and-mouse';
 }
 
 // Note: Claude CLI PATH resolution moved to session-cli-builder.ts (buildClaudeEnv)
@@ -550,6 +589,27 @@ export class Session extends EventEmitter {
   private _watchingWindow = WATCHING_TAIL_LINES;
   /** Lazily compiled `capabilities.workDetect.awaitingLine`. See _awaitingLinePattern(). */
   private _awaitingLineRe: RegExp | null | undefined = undefined;
+  /**
+   * The newest model the running CLI reported for itself (its statusline, or its own
+   * footer read off the probe's capture), or null when none has. Feeds `displayModel`
+   * (src/session-display-model.ts). Persisted through `toState()` and restored after a
+   * restart, so an idle session keeps naming its model until the next report.
+   */
+  private _reportedModel: ReportedModel | null = null;
+  /**
+   * The model the CLI's own config pins for this session (`modelDetect.configResolver`),
+   * read at each pane start, attach or relaunch; null when it pins none. Below any
+   * report from the running CLI in `displayModel`. Not persisted: the next start reads it.
+   */
+  private _configModel: string | null = null;
+  /** Bumped per config read, so a read that lands after a newer one is dropped. */
+  private _configModelGen = 0;
+  /** Lazily compiled `capabilities.modelDetect.screenLine`. See _modelLinePattern(). */
+  private _modelLineRe: RegExp | null | undefined = undefined;
+  /** Resolved with the pattern above: how many rows at the foot of the screen it sees. */
+  private _modelLineRows = 1;
+  /** Resolved with the pattern above: the fields it shows that are never the model. */
+  private _modelRejectWords: readonly string[] = [];
   private _trustDialogAccepted: boolean = false; // Stops the trust-dialog scan (answered, or given up)
   private _trustDialogAttempts = 0; // Keystrokes sent at the trust dialog
   private _lastTrustDialogScanAt = 0; // Throttle for the trust-dialog screen read
@@ -807,6 +867,8 @@ export class Session extends EventEmitter {
       claudeSessionChain?: string[];
       /** Restored agent-exit observation for this session's pane (see `paneExit`). */
       paneExit?: PaneExit;
+      /** The previous run's `displayModel`; a CLI-reported one is restored (see `displayModel`). */
+      displayModel?: DisplayModel;
       /** This session was rebuilt from the tmux socket, so its metadata is a guess. */
       discoveredMuxSession?: boolean;
       /** Restored wall-clock ms of the pane's last output (recovery only; see `_wireActivityAt`). */
@@ -974,6 +1036,7 @@ export class Session extends EventEmitter {
     // replaces it with a first-hand reading. NOT the stats collector, which a
     // browser panel arms and disarms — see `startPaneExitWatcher`.
     this.setPaneExit(config.paneExit);
+    this._reportedModel = restoredReportedModel(config.displayModel) ?? null;
     // Never self-parent: a session pointing at itself would draw a zero-length
     // lineage arc under its own tab. Only reachable via the recovery path, where
     // both the id and the saved parent come from disk.
@@ -1267,6 +1330,9 @@ export class Session extends EventEmitter {
     } finally {
       this._paneLifecycleOps--;
       this._paneStartedAt = Date.now();
+      // A start, attach or relaunch is when the CLI read its config, so it is when
+      // the model that config pins is read here too.
+      this._refreshConfigModel();
     }
   }
 
@@ -1316,7 +1382,7 @@ export class Session extends EventEmitter {
   /**
    * True when this session's PTY is a tmux client rather than the program itself.
    * Read by the replay-side alt-screen strip, which must apply the same
-   * `useMux` gate as the live strip (isMuxAltScreenOnlyStripMode).
+   * `useMux` gate as the live strip (isMuxAltScreenOnlyStripMode, isMuxMouseStripMode).
    */
   get usesMux(): boolean {
     return this._useMux;
@@ -1858,6 +1924,7 @@ export class Session extends EventEmitter {
       model: cliTakesSessionModel(this.mode) ? this._model : undefined,
       advisorModel: this._advisorModel,
       customModel: this.customModel,
+      displayModel: this.displayModel,
       // COD-118: runtime-only — surfaced so the frontend can require explicit user
       // intent before restarting a crash-looped session. Deliberately NOT restored
       // by the constructor: a Codeman restart starts with a fresh breaker so boot
@@ -2489,14 +2556,21 @@ export class Session extends EventEmitter {
     // redraws overwrite only the cells they target, so non-erased rows keep
     // their content. Gated to Codex/Claude/Gemini (isAltScreenStripMode).
     //
-    // Every OTHER mode (shell/opencode/antigravity) gets the NARROW strip when it
-    // is tmux-backed: alt-screen toggles only, because the sequence that breaks
+    // Every OTHER mode (shell/antigravity/pi/grok/deepseek/omp) gets the NARROW strip
+    // when it is tmux-backed: alt-screen toggles only, because the sequence that breaks
     // scrollback there is tmux's own client-side smcup at attach, not anything the
     // program in the pane emitted (issue #205, see isMuxAltScreenOnlyStripMode).
     // 3J and the mouse DECSETs stay, so `clear` and mouse-aware TUIs keep working.
+    //
+    // The MIDDLE case (isMuxMouseStripMode) is a mouse-capable full-screen TUI:
+    // it needs smcup AND the mouse DECSETs gone — otherwise the pane's tracking
+    // reaches xterm and every drag becomes a mouse report instead of a text
+    // selection, which is what killed mark-and-copy in opencode — while 3J stays,
+    // because a TUI is not a `clear` consumer.
     const fullStrip = isAltScreenStripMode(this.mode);
-    const altOnlyStrip = !fullStrip && isMuxAltScreenOnlyStripMode(this.mode, this._useMux);
-    if (fullStrip || altOnlyStrip) {
+    const mouseStrip = isMuxMouseStripMode(this.mode, this._useMux);
+    const altOnlyStrip = !fullStrip && !mouseStrip && isMuxAltScreenOnlyStripMode(this.mode, this._useMux);
+    if (fullStrip || mouseStrip || altOnlyStrip) {
       // Reassemble sequences split across PTY chunk boundaries first: a chunk
       // ending mid-sequence ('\x1b[?104' now, '9h' next) would slip past the
       // strip below and leave xterm stuck in the scrollback-less alt buffer
@@ -2515,14 +2589,18 @@ export class Session extends EventEmitter {
       // eslint-disable-next-line no-control-regex
       data = data.replace(/\x1b\[\?(?:47|1047|1049)[hl]/g, '');
       if (fullStrip) {
-        data = data
         // eslint-disable-next-line no-control-regex
-          .replace(/\x1b\[3J/g, '')
+        data = data.replace(/\x1b\[3J/g, '');
+      }
+      if (fullStrip || mouseStrip) {
+        data = data.replace(
           // eslint-disable-next-line no-control-regex
-          .replace(/\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g, (seq) => {
+          /\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g,
+          (seq) => {
             this._recordStrippedMouseMode(seq);
             return '';
-          });
+          }
+        );
       }
     }
 
@@ -2743,19 +2821,14 @@ export class Session extends EventEmitter {
           this.id;
 
         // For NEW mux sessions: wait for readiness then clean buffer
-        // For RESTORED mux sessions: don't do anything - client will fetch buffer on tab switch
+        // For RESTORED mux sessions: leave the buffer alone - client will fetch it on tab switch
         if (!isRestored) {
           if (isExternalCliMode(this.mode)) {
             // External CLIs use custom TUIs — no ❯ prompt to detect.
             // Wait for TUI to stabilize (output stops changing), then mark ready.
             // Don't clear the buffer — the TUI's initial render IS the useful content.
             // Emit needsRefresh so the client fetches the full buffer once the TUI has rendered.
-            this._promptCheckTimeout = setTimeout(() => {
-              this._promptCheckTimeout = null;
-              if (this._isStopped) return;
-              this._status = 'idle';
-              this.emit('needsRefresh');
-            }, 3000);
+            this._armPaneSettle(false);
           } else {
             // Claude mode: wait for ❯ prompt
             this._promptCheckInterval = setInterval(() => {
@@ -2787,6 +2860,8 @@ export class Session extends EventEmitter {
               this._promptCheckTimeout = null;
             }, 5000);
           }
+        } else {
+          this._armPaneSettle(true);
         }
       } catch (err) {
         console.error('[Session] Failed to create mux session, falling back to direct PTY:', err);
@@ -3134,9 +3209,130 @@ export class Session extends EventEmitter {
     this._lastPaneProbeWorking =
       text === null ? null : this._workingLinePattern().test(text) || this._paneAwaitsWorkers(text);
     this._readWatching(text);
+    this._readScreenModel(text);
     return this._lastPaneProbeWorking;
   }
 
+  /**
+   * Read the model the CLI's own footer names off the same capture, for a CLI whose
+   * registry entry declares `capabilities.modelDetect`.
+   *
+   * Unlike `_readWatching`, a capture that could not be read, or a footer the pattern
+   * does not find (a popup covering it, a footer turned off), KEEPS the last model. The
+   * two are not symmetric: background work ends and its badge must go, while a model does
+   * not stop running because something was drawn over the row that names it.
+   */
+  private _readScreenModel(paneText: string | null): void {
+    if (paneText === null) return;
+    const pattern = this._modelLinePattern();
+    if (!pattern) return;
+    const model = readScreenModel(paneText, pattern, this._modelLineRows, {
+      rejectWords: this._modelRejectWords,
+      // A footer field equal to the folder this session runs in is the folder, never the
+      // model: the generic half of the rule, for every CLI.
+      cwdBasename: basename(this.workingDir),
+    });
+    if (model) this.noteReportedModel('screen', model);
+  }
+
+  /**
+   * The regex reading this CLI's model off its footer, or null for a CLI that declares
+   * none. Compiled once per session through `compileVersionRegex()` (null, never a throw,
+   * for a pattern it refuses), like the working- and watching-line patterns.
+   */
+  private _modelLinePattern(): RegExp | null {
+    if (this._modelLineRe === undefined) {
+      const detect = getCli(this.mode)?.capabilities.modelDetect;
+      this._modelLineRe = detect?.screenLine ? compileVersionRegex(detect.screenLine) : null;
+      this._modelLineRows = detect?.screenLines ?? 1;
+      this._modelRejectWords = detect?.rejectWords ?? [];
+    }
+    return this._modelLineRe;
+  }
+
+  /**
+   * Record a model the running CLI reported for itself: its statusline (claude's
+   * exporter, via `POST /api/status-telemetry`) or its own footer. The newest report
+   * wins whatever its source. An empty or unprintable report changes nothing.
+   *
+   * @returns true when the reported model changed (and `displayModelChanged` was emitted)
+   */
+  noteReportedModel(source: ReportedModelSource, raw: unknown): boolean {
+    const model = sanitizeModelName(raw);
+    if (!model) return false;
+    if (this._reportedModel?.model === model && this._reportedModel.source === source) return false;
+    this._reportedModel = { model, source };
+    // The status does not change with it, so it needs a broadcast (and a persist) of its own.
+    this.emit('displayModelChanged');
+    return true;
+  }
+
+  /**
+   * The model this session runs as far as the server knows, and where that came from:
+   * the custom endpoint's model, else the newest report from the CLI, else the launch
+   * model (src/session-display-model.ts). Undefined when none is known.
+   */
+  get displayModel(): DisplayModel | undefined {
+    return resolveDisplayModel({
+      customModelId: this._customModel?.modelId,
+      reported: this._reportedModel,
+      configModel: this._configModel,
+      launchModel: launchModelFor(this.mode, this._launchOptionBag()),
+    });
+  }
+
+  /**
+   * The same option bag the spawn reads its launch params from: `model` at the top for
+   * claude (the `--model` or app-wide default it was created with; inert for every other
+   * CLI, which is why it is not handed over for them), each other CLI's own
+   * `<Mode>Config`. Where a param lives is registry data (`legacyConfigForMode`).
+   */
+  private _launchOptionBag(): Record<string, unknown> {
+    return {
+      model: cliTakesSessionModel(this.mode) ? this._model : undefined,
+      openCodeConfig: this._openCodeConfig,
+      codexConfig: this._codexConfig,
+      geminiConfig: this._geminiConfig,
+      antigravityConfig: this._antigravityConfig,
+      piConfig: this._piConfig,
+      grokConfig: this._grokConfig,
+      deepSeekConfig: this._deepSeekConfig,
+      ompConfig: this._ompConfig,
+    };
+  }
+
+  /**
+   * Read the model this session's CLI config pins, with the reader its registry entry
+   * names (`capabilities.modelDetect.configResolver`), and announce a change. Async and
+   * bounded (the reader probes before it reads); a read that lands after a newer one,
+   * or after the session stopped, is dropped. A remote or docker session's CLI reads its
+   * config on another machine or in its container, so nothing local is read for it.
+   */
+  private _refreshConfigModel(): void {
+    const name = getCli(this.mode)?.capabilities.modelDetect?.configResolver;
+    if (!name || this._remote || this._docker) return;
+    const gen = ++this._configModelGen;
+    const overrides = this._envOverrides;
+    resolveConfigModel(name, {
+      config: legacyConfigForMode(this.mode, this._launchOptionBag()),
+      // The session's own env first (already clamped for a non-granted owner), then the
+      // server's: what the pane's CLI inherits.
+      env: (key) => overrides?.[key] ?? process.env[key],
+    }).then(
+      (model) => {
+        if (gen !== this._configModelGen || this._isStopped) return;
+        // Sanitized where it is published (resolveDisplayModel), like every source.
+        const next = model || null;
+        if (next === this._configModel) return;
+        this._configModel = next;
+        this.emit('displayModelChanged');
+      },
+      () => {
+        /* A reader answers null on doubt and never throws; a throw changes nothing. */
+      }
+    );
+  }
+
   /**
    * Read the background-work chip off the same capture the working probe just took.
    *
@@ -3272,14 +3468,74 @@ export class Session extends EventEmitter {
     // 1. Claude was working and is now at prompt (normal case)
     // 2. Session just started and is ready (status is 'busy' but _isWorking is false)
     const wasWorking = this._isWorking;
-    const isInitialReady = this._status === 'busy' && !this._isWorking;
-    if (wasWorking || isInitialReady) {
+    if (wasWorking || this._status === 'busy') this._concludeIdle(wasWorking);
+  }
+
+  /**
+   * The one place a pane is concluded idle: status, working flag and prompt stamp
+   * change together, and the change is ANNOUNCED. The `idle` event is what the web
+   * server turns into `session:idle` plus a state broadcast, so a path that flips
+   * `_status` without it leaves every browser on the `busy` it was last sent. A fresh
+   * codex pane used to stay "working" in the UI for its whole life that way.
+   *
+   * @param turnEnded a real turn just finished (not a pane becoming ready at launch)
+   */
+  private _concludeIdle(turnEnded: boolean): void {
     this._isWorking = false;
     this._status = 'idle';
     this._lastPromptTime = Date.now();
-      if (wasWorking) this._maybeCaptureOmpSessionId();
+    // Only a finished turn proves omp has written its session file; a pane that is
+    // merely ready has nothing to resolve yet and could claim a neighbour's file.
+    if (turnEnded) this._maybeCaptureOmpSessionId();
     this.emit('idle');
   }
+
+  /**
+   * Arm the launch settle (`_settlePaneStartup`) for a pane `startInteractive()` just
+   * started or re-attached, when one applies:
+   * - a NEW pane of an external CLI, whose TUI has no ❯ for the Claude wait to find;
+   * - a RESTORED pane (Codeman restart, auto-reattach, tile Attach) of a CLI that
+   *   declares no `capabilities.workDetect`. It is `busy` from `_resetBuffers()` like a
+   *   new pane, and with no composer glyph to arm `_confirmIdle()` nothing else would
+   *   ever settle it. A restored claude or codex pane is left to its glyph, which
+   *   reads the screen first, so a restart in mid-turn is never called idle.
+   */
+  private _armPaneSettle(isRestored: boolean): void {
+    const applies = isRestored ? !getCli(this.mode)?.capabilities.workDetect : isExternalCliMode(this.mode);
+    if (!applies) return;
+    const armedAt = Date.now();
+    this._promptCheckTimeout = setTimeout(() => this._settlePaneStartup(!isRestored, armedAt), 3000);
+  }
+
+  /**
+   * The launch settle: 3 s after a NEW external-CLI pane spawned, or after ANY pane of a
+   * CLI without work detection was re-attached, its TUI is taken to have rendered. A pane
+   * still in its spawn-time `busy` is concluded idle (announced, see `_concludeIdle`),
+   * then, for a new pane, the browser is told to refetch the rendered screen.
+   *
+   * ⚠️ This used to set `_status = 'idle'` without an event. When the launch paint
+   * never tripped `_markWorking()`, the later `_confirmIdle()` found the status
+   * already idle and emitted nothing, so no browser ever learned the pane was ready.
+   *
+   * A pane is left to `_confirmIdle()` only when its CLI declares
+   * `capabilities.workDetect` (its composer glyph arms that confirmation, which reads
+   * the screen first) AND it is already working, or a prompt was submitted since the
+   * timer was armed: a turn started 2.9 s in is not marked working before the deferred
+   * parsers run, and an idle edge here would end a send-and-wait registered for it.
+   * For every other CLI this timer is the only thing that ever settles a fresh pane,
+   * so it settles it even if a stray spinner glyph in the launch paint latched
+   * `_isWorking`.
+   *
+   * @param refreshScreen emit `needsRefresh` (a new pane; an attach refetches by itself)
+   * @param armedAt when the timer was armed (a submit at or after it means a prompt)
+   */
+  private _settlePaneStartup(refreshScreen: boolean, armedAt: number): void {
+    this._promptCheckTimeout = null;
+    if (this._isStopped) return;
+    const busyWithTurn = this._isWorking || this.lastSubmitAt >= armedAt;
+    const leaveToConfirm = busyWithTurn && !!getCli(this.mode)?.capabilities.workDetect;
+    if (this._status === 'busy' && !leaveToConfirm) this._concludeIdle(false);
+    if (refreshScreen) this.emit('needsRefresh');
   }
 
   /**
@@ -4267,7 +4523,7 @@ export class Session extends EventEmitter {
           : this._mux.capturePaneText?.(this._muxSession.muxName),
       sendEnter: () => this._mux?.sendInput(this.id, '\r'),
       // ⚠ NO fallback glyph here, unlike the screen-reading probe elsewhere in this file.
-      // Only claude and codex declare a promptGlyph; the other eight modes would fall back
+      // Only claude, codex, pi, opencode, omp and gemini declare a promptGlyph; the other modes would fall back
       // to claude's `❯`, which is ALSO starship's default shell prompt (and pure's, and
       // spaceship's, and p10k lean's). On a shell session the line `❯ npm run build` sits
       // on screen for as long as the command runs, promptStillInComposer() reads that as

src/types/api.ts

@@ -157,6 +157,13 @@ export interface CaseInfo {
   location?: 'local' | 'linked-local' | 'remote' | 'docker';
   /** Whether this is a linked local folder */
   linked?: boolean;
+  /**
+   * The case folder did not answer (an unreachable network mount, or an error other
+   * than "no such file"), or its probe was refused because folders on other unreachable
+   * mounts are still not answering, so whether it still exists is unknown. A refused
+   * probe can set this on a healthy linked case. Absent = it answered.
+   */
+  unreachable?: boolean;
   /**
    * Present when Codeman scaffolded this case directory for an AGENT-spawned session
    * (the packaged skill's workers, or any spawn naming a parent session), read back

src/types/session.ts

@@ -641,6 +641,24 @@ export interface CustomModelSelection {
   label?: string;
 }
 
+/**
+ * Where a session's {@link DisplayModel} came from (src/session-display-model.ts):
+ * - `custom-endpoint`: the Custom Model Endpoint Profile's model, which wins.
+ * - `statusline`: the CLI reported it (claude's statusLine exporter), follows a switch.
+ * - `screen`: read off the CLI's own footer (`capabilities.modelDetect`), follows a switch.
+ * - `config`: what the CLI's own config pins for this session
+ *   (`capabilities.modelDetect.configResolver`), while its screen names none.
+ * - `launch`: what the session was launched with; nothing has reported since.
+ */
+export type DisplayModelSource = 'custom-endpoint' | 'statusline' | 'screen' | 'config' | 'launch';
+
+/** The model a session runs as far as the server knows, for a session header. */
+export interface DisplayModel {
+  /** Display text: sanitized (no control characters) and at most 64 characters. */
+  model: string;
+  source: DisplayModelSource;
+}
+
 /**
  * The full custom-model selection a session keeps: the public selection plus the
  * bookkeeping `Session.setCustomModel()` needs to UNDO it later without guessing what
@@ -794,7 +812,8 @@ export interface SessionState {
   /**
    * True while the CLI in the pane has a mouse-tracking DECSET on, as observed
    * by the server on its way out of the stream (those sequences are stripped for
-   * claude/codex/gemini, so the browser can never see them itself). The browser
+   * the strip-full and strip-mux-and-mouse modes, claude/codex/gemini and opencode
+   * under tmux, so the browser can never see them itself). The browser
    * hand-encodes a click report ONLY when this is true; without it, every click
    * sent mouse reports to a CLI that never asked for them.
    */
@@ -847,6 +866,16 @@ export interface SessionState {
    * written) is {@link CustomModelBookkeeping}, persisted disk-only like `__envOverrides`.
    */
   customModel?: CustomModelSelection;
+  /**
+   * The model this session runs, as far as the server knows it, and where that came from
+   * (src/session-display-model.ts): the custom endpoint's model, else the newest report
+   * from the CLI itself (statusline or its own footer), else the model its config pins,
+   * else the launch model. Absent when
+   * none is known; a session header then shows the harness alone. Untrusted display text
+   * (pane-derived for `screen`): render it as text. Persisted, and a `statusline`/`screen`
+   * value is restored after a restart until the next report replaces it.
+   */
+  displayModel?: DisplayModel;
   /** Sanitized per-session attachment history. */
   attachmentHistory?: SessionAttachmentHistoryItem[];
   /**

src/types/tools.ts

@@ -70,6 +70,7 @@ export type AttachmentDetectedType =
   | 'pdf'
   | 'document'
   | 'presentation'
+  | 'spreadsheet'
   | 'markdown'
   | 'text';
 

src/utils/bounded-path-probe.ts

@@ -0,0 +1,247 @@
+/**
+ * @fileoverview Bounded existence probe for user-chosen paths.
+ *
+ * A linked case can live on a network mount (NFS, SMB, sshfs). When that mount
+ * goes unreachable, a hard mount makes `stat()` wait forever. A synchronous
+ * probe (`existsSync`) on such a path blocks the event loop and freezes the
+ * whole web server; even an async `stat()` never settles and permanently holds
+ * one of libuv's few threadpool workers, which every other `fs`, `dns.lookup`
+ * and `crypto` call in the process shares.
+ *
+ * The probe therefore answers one of THREE things, never two:
+ * - `'present'` / `'absent'`: the filesystem answered (ENOENT and ENOTDIR are
+ *   the only errors that mean absent);
+ * - `'unknown'`: it did not answer in `PATH_PROBE_TIMEOUT_MS`, it answered with
+ *   some other error (EIO from a soft mount that gave up, EACCES), or the probe
+ *   was refused (below). "Unknown" is NOT "absent": a caller that would create,
+ *   scaffold or 404 on absence must not do so on unknown.
+ *
+ * And it keeps a dead mount from draining the threadpool:
+ * - one in-flight probe per path, shared by concurrent callers;
+ * - a path whose probe timed out is "stalled" until that stat finally settles.
+ *   Paths NEAR a stalled one are answered "unknown" without a new stat, so one
+ *   dead mount costs one worker, not one per case and file on it. "Near" means on
+ *   the same mount when that mount is a network or FUSE filesystem (NFS, SMB,
+ *   sshfs and the like): under the deepest mount point holding the stalled path,
+ *   with its type, read from `/proc/self/mounts` (procfs, which never waits on the
+ *   dead filesystem). Otherwise it narrows to the stalled path and everything under
+ *   it: when the deepest mount is local (a path typed under a local `/home` can
+ *   reach a NAS through a symlink, and must not take the rest of `/home` with it),
+ *   is `/`, or the table is unavailable (not Linux). Unrelated paths are probed
+ *   normally;
+ * - once `MAX_STALLED_PATH_PROBES` stalled stats are pending, new probes are
+ *   refused process-wide (answered "unknown"), since each would risk another
+ *   worker. Probes merely in flight do not count, so concurrent healthy probes
+ *   never get refused. A caller acting on ONE path at a user's explicit request
+ *   (opening a case, starting a session in it) may pass `{ pastCap: true }`: its
+ *   probe is still bounded and still recorded as stalled if it hangs (so a dead
+ *   path costs at most one worker however often it is retried), but it is not
+ *   refused just because unrelated mounts are dead. Bulk scans (the case list)
+ *   keep the cap; the per-spawn hook and statusLine helpers retry one refused
+ *   probe past it and then skip a path that still answers "unknown", rather than
+ *   touch it with an unbounded call. `pastCap` still stops at
+ *   `PATH_PROBE_STALL_CEILING` (the threadpool size minus one), so explicit
+ *   requests against several dead paths can never take the last worker.
+ *
+ * Both events are logged once (`console.warn`): a path's first stall, and the
+ * cap engaging, so "my case vanished" and "hooks stopped firing" leave a trace.
+ *
+ * Writers should not use this at all: a writer that must tell "missing" apart
+ * from "unreachable" wants an ENOENT-aware async `lstat` (see
+ * `pathExistsForWrite` in hooks-config.ts).
+ *
+ * @module utils/bounded-path-probe
+ */
+
+import { readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { MAX_STALLED_PATH_PROBES, PATH_PROBE_STALL_CEILING, PATH_PROBE_TIMEOUT_MS } from '../config/path-probe.js';
+
+/** What a probe could establish about a path. */
+export type PathProbeState = 'present' | 'absent' | 'unknown';
+/** Like {@link PathProbeState}, with "present" split by whether it is a directory. */
+export type PathProbeKind = 'directory' | 'file' | 'absent' | 'unknown';
+
+const inFlight = new Map<string, Promise<PathProbeKind>>();
+/** Stalled path -> the directory whose subtree is answered "unknown" while it stays stalled. */
+const stalled = new Map<string, string>();
+let capWarned = false;
+
+async function statKind(path: string): Promise<PathProbeKind> {
+  try {
+    return (await fs.stat(path)).isDirectory() ? 'directory' : 'file';
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR' ? 'absent' : 'unknown';
+  }
+}
+
+function isWithin(path: string, root: string): boolean {
+  if (path === root) return true;
+  return path.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+/** Filesystem types whose stall means the whole mount is gone (network and FUSE). */
+const REMOTE_FS_TYPES = new Set([
+  'nfs',
+  'nfs4',
+  'cifs',
+  'smb3',
+  'smbfs',
+  '9p',
+  'ceph',
+  'glusterfs',
+  'afs',
+  'lustre',
+  'davfs',
+]);
+
+function isRemoteFsType(fsType: string): boolean {
+  return REMOTE_FS_TYPES.has(fsType) || fsType.startsWith('fuse.');
+}
+
+/** Deepest mount holding `abs`, from the kernel's mount table; undefined when unreadable. */
+function mountOf(abs: string): { mountPoint: string; fsType: string } | undefined {
+  let table: string;
+  try {
+    table = readFileSync('/proc/self/mounts', 'utf-8');
+  } catch {
+    return undefined;
+  }
+  let best: { mountPoint: string; fsType: string } | undefined;
+  for (const line of table.split('\n')) {
+    const [, field, fsType] = line.split(' ');
+    if (!field || !fsType) continue;
+    // The table octal-escapes space, tab, newline and backslash in mount points.
+    const mountPoint = field.replace(/\\([0-7]{3})/g, (_m, oct: string) => String.fromCharCode(parseInt(oct, 8)));
+    if (isWithin(abs, mountPoint) && (!best || mountPoint.length > best.mountPoint.length)) {
+      best = { mountPoint, fsType };
+    }
+  }
+  return best;
+}
+
+/**
+ * The subtree a stalled path takes down with it (see the module comment): its
+ * mount when that is a network or FUSE filesystem, else just the path itself.
+ */
+function stallScope(abs: string): string {
+  const mount = mountOf(abs);
+  return mount && mount.mountPoint !== '/' && isRemoteFsType(mount.fsType) ? mount.mountPoint : abs;
+}
+
+/**
+ * Whether `path` is near a path whose probe is still stalled (see the module
+ * comment), i.e. whether the probe would answer "unknown" for it without a stat.
+ * Lets a caller tell "this workspace sits on the dead mount" apart from "the
+ * probe was refused for capacity".
+ */
+export function isNearStalledPath(path: string): boolean {
+  const abs = resolve(path);
+  for (const scope of stalled.values()) {
+    if (isWithin(abs, scope)) return true;
+  }
+  return false;
+}
+
+/** Options for {@link probePathKind} / {@link probePath}. */
+export interface PathProbeOptions {
+  /** Probe even while the stall cap is engaged (see the module comment). */
+  pastCap?: boolean;
+}
+
+/**
+ * Probe `path` without letting an unresponsive filesystem block the caller for
+ * longer than `PATH_PROBE_TIMEOUT_MS`. Follows symlinks, like `stat()`.
+ */
+export async function probePathKind(path: string, options: PathProbeOptions = {}): Promise<PathProbeKind> {
+  const abs = resolve(path);
+  if (isNearStalledPath(abs)) return 'unknown';
+
+  let probe = inFlight.get(abs);
+  if (!probe) {
+    // pastCap lifts the bulk cap, never the ceiling that keeps one worker free.
+    if (stalled.size >= (options.pastCap ? PATH_PROBE_STALL_CEILING : MAX_STALLED_PATH_PROBES)) {
+      if (!capWarned) {
+        capWarned = true;
+        console.warn(
+          `[path-probe] ${stalled.size} path probes are stalled on unresponsive filesystems; ` +
+            'not starting new ones until one answers (paths read as unknown meanwhile)'
+        );
+      }
+      return 'unknown';
+    }
+    probe = statKind(abs);
+    const started = probe;
+    inFlight.set(abs, started);
+    void started.finally(() => {
+      inFlight.delete(abs);
+      stalled.delete(abs);
+      if (stalled.size < MAX_STALLED_PATH_PROBES) capWarned = false;
+    });
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      probe,
+      new Promise<PathProbeKind>((resolveTimeout) => {
+        timer = setTimeout(() => {
+          if (inFlight.get(abs) === probe && !stalled.has(abs)) {
+            stalled.set(abs, stallScope(abs));
+            console.warn(
+              `[path-probe] ${abs} did not answer within ${PATH_PROBE_TIMEOUT_MS} ms ` +
+                '(unreachable mount?); treating it and its neighbours as unknown until it does'
+            );
+          }
+          resolveTimeout('unknown');
+        }, PATH_PROBE_TIMEOUT_MS);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Why a probe of `path` answers "unknown" right now: its mount is not answering
+ * (`'stalled'`, it is near a stalled probe), new probes are refused because enough
+ * UNRELATED paths are stalled (`'refused'`; `pastCap` picks which limit applies), or
+ * neither, so the filesystem answered with an error such as EACCES or EIO
+ * (`'unreadable'`). For messages only: it reads the state now, not at probe time.
+ */
+export function unknownPathReason(path: string, options: PathProbeOptions = {}): 'stalled' | 'refused' | 'unreadable' {
+  if (isNearStalledPath(path)) return 'stalled';
+  if (stalled.size >= (options.pastCap ? PATH_PROBE_STALL_CEILING : MAX_STALLED_PATH_PROBES)) return 'refused';
+  return 'unreadable';
+}
+
+/**
+ * User-facing sentence for an "unknown" probe of `path` (`label` names it, e.g.
+ * "workingDir"). A refused probe says so, rather than blaming a folder that was never
+ * checked: at the ceiling every new folder reads "unknown" until a dead mount answers.
+ */
+export function describeUnknownPath(label: string, path: string, options: PathProbeOptions = {}): string {
+  return unknownPathReason(path, options) === 'refused'
+    ? `${label} was not checked: folders on other unreachable mounts are still not answering, ` +
+        `so Codeman is not checking new folders until one does (see the server log): ${path}`
+    : `${label} is not responding or not readable: ${path}`;
+}
+
+/** Tri-state probe of `path`; see the module comment for what "unknown" means. */
+export async function probePath(path: string, options: PathProbeOptions = {}): Promise<PathProbeState> {
+  const kind = await probePathKind(path, options);
+  return kind === 'directory' || kind === 'file' ? 'present' : kind;
+}
+
+/**
+ * `true` only when `path` is known to exist. For DISPLAY decisions only (does a
+ * case have a CLAUDE.md): it folds "unknown" into `false`, so never use it to
+ * decide that something is absent and may be created, scaffolded or reported
+ * missing; use {@link probePath} for that.
+ */
+export async function boundedPathExists(path: string): Promise<boolean> {
+  return (await probePath(path)) === 'present';
+}

src/utils/cli-executable-resolver.ts

@@ -122,7 +122,8 @@ export interface ProductionCliResolverHostOptions {
   allowRealIoUnderVitest?: boolean;
 }
 
-function isExecutableRegularFile(path: string): boolean {
+/** An executable regular file. Exported for `codeman doctor`, which must judge a candidate the same way. */
+export function isExecutableRegularFile(path: string): boolean {
   try {
     if (!statSync(path).isFile()) return false;
     accessSync(path, constants.X_OK);

src/utils/deepseek-cli-resolver.ts

@@ -156,6 +156,11 @@ const STOCK_NON_INTERACTIVE_PROFILES = new Map<string, DeepSeekProfileKind>([
 /** Profile directory names that are not profiles. */
 const NON_PROFILE_DIRS = new Set(['node_modules', '.bin', '.pnpm']);
 
+/** Whether a directory under `$DSH_HOME/profiles` can be a profile at all (not `node_modules`, not hidden). */
+export function isProfileDirName(name: string): boolean {
+  return !NON_PROFILE_DIRS.has(name) && !name.startsWith('.');
+}
+
 function classifyProfile(name: string, bundles: string[]): DeepSeekProfileKind {
   const haystack = [name, ...bundles].join(' ');
   // Order matters: a profile that composes BOTH a web app and a tui bundle is a
@@ -174,7 +179,19 @@ function classifyProfile(name: string, bundles: string[]): DeepSeekProfileKind {
  */
 function readProfile(profilesDir: string, name: string): DeepSeekProfile | null {
   try {
-    const raw = readFileSync(join(profilesDir, name, 'package.json'), 'utf-8');
+    return deepSeekProfileFromManifest(name, readFileSync(join(profilesDir, name, 'package.json'), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A profile from its directory name and the text of its `package.json`, or null when
+ * that text is not JSON. Pure, so a caller with its own (bounded, async) reads gets the
+ * same classification as the inventory below.
+ */
+export function deepSeekProfileFromManifest(name: string, raw: string): DeepSeekProfile | null {
+  try {
     const parsed = JSON.parse(raw) as { dsh?: { profile?: { bundles?: unknown } } };
     const rawBundles = parsed?.dsh?.profile?.bundles;
     const bundles = Array.isArray(rawBundles) ? rawBundles.filter((b): b is string => typeof b === 'string') : [];
@@ -198,7 +215,7 @@ export function listDeepSeekProfiles(): DeepSeekProfile[] {
   let entries: string[];
   try {
     entries = readdirSync(profilesDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && !NON_PROFILE_DIRS.has(e.name) && !e.name.startsWith('.'))
+      .filter((e) => e.isDirectory() && isProfileDirName(e.name))
       .map((e) => e.name);
   } catch {
     return [];

src/utils/dependency-checker.ts

@@ -8,7 +8,9 @@
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { isExecutableRegularFile } from './cli-executable-resolver.js';
 import type { ProbeEnvironment, ToolCategory, ToolDependency } from '../config/dependency-registry.js';
 
 export interface EnvDetectionInputs {
@@ -62,6 +64,8 @@ export interface ProbeHost {
   environment: ProbeEnvironment;
   which(bin: string): string | null;
   fileExists(path: string): boolean;
+  /** An executable regular file, the run mode's own test for a `searchDirs` candidate. */
+  isExecutableFile(path: string): boolean;
   runVersion(bin: string, args: string[]): string | null;
   windowsProgramRoots(): string[];
   windowsFileVersion(winPath: string): string | null;
@@ -94,18 +98,33 @@ export function checkTool(tool: ToolDependency, host: ProbeHost): ToolResult {
   if (!spec) return { ...base, status: 'skipped', reason: `not applicable on ${host.environment}` };
 
   if (spec.resolver.kind === 'path') {
-    const { bins, versionArg, versionRegex, requireVersionMatch } = spec.resolver;
+    const { bins, versionArg, versionRegex, requireVersionMatch, searchDirs } = spec.resolver;
     for (const bin of bins) {
-      const resolved = host.which(bin);
-      if (resolved) {
-        const out = host.runVersion(bin, [versionArg ?? '--version']);
+      // The same candidate order and the same per-candidate test as the run mode's resolver
+      // (createCliExecutableResolver): the `which` hit (the PATH), then each search dir. Under
+      // a service the PATH is minimal and the run mode finds the CLI through those dirs, so
+      // the doctor must too. A search-dir candidate counts only as an absolute path to an
+      // executable regular file, so a relative dir from a custom clis.json or a file without
+      // the x bit reads as missing here exactly as it does in the Run menu.
+      const candidates: string[] = [];
+      const onPath = host.which(bin);
+      if (onPath && isAbsolute(onPath)) candidates.push(onPath);
+      for (const dir of searchDirs ?? []) {
+        const candidate = join(dir, bin);
+        if (candidates.includes(candidate)) continue; // a search dir that is also on the PATH
+        if (isAbsolute(candidate) && host.isExecutableFile(candidate)) candidates.push(candidate);
+      }
+      for (const candidate of candidates) {
+        // Run the RESOLVED path: a bare name would miss the same binary `which` just missed.
+        const out = host.runVersion(candidate, [versionArg ?? '--version']);
         const version = out ? extractVersion(out, versionRegex) : undefined;
         // A generic binary name that prints the wrong thing is some OTHER program (see
-        // PathResolver.requireVersionMatch). Keep looking, then report MISSING; the
-        // alternative is claiming a tool is installed that the feature's own resolver
-        // rejects, which reads as "the mode is broken" rather than "install it".
+        // PathResolver.requireVersionMatch). Try the next candidate, then report MISSING;
+        // the alternative is claiming a tool is installed that the feature's own resolver
+        // rejects, or missing one it accepts (an npm squatter on the PATH in front of the
+        // real grok in ~/.grok/bin), which reads as "the mode is broken".
         if (requireVersionMatch && !version) continue;
-        return finalize(base, tool, resolved, version);
+        return finalize(base, tool, candidate, version);
       }
     }
     return { ...base, status: 'missing', installHint };
@@ -132,11 +151,16 @@ export function checkAll(registry: ToolDependency[], host: ProbeHost): ToolResul
   return registry.map((tool) => checkTool(tool, host));
 }
 
+// SIGKILL on every probe below: execFileSync's `timeout` only SENDS the kill signal and then
+// keeps waiting for the child, so a `--version` that ignores the default SIGTERM would hold
+// the doctor (now a Settings button) until GET /api/doctor's own timeout, then be orphaned.
+// Same reasoning as the resolver host in cli-executable-resolver.ts.
 function safeWhich(bin: string): string | null {
   try {
     const out = execFileSync(process.platform === 'win32' ? 'where' : 'which', [bin], {
       encoding: 'utf-8',
       timeout: EXEC_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
     }).trim();
     const first = out.split(/\r?\n/)[0]?.trim();
     return first && existsSync(first) ? first : null;
@@ -151,6 +175,7 @@ function safeRunVersion(bin: string, args: string[]): string | null {
       encoding: 'utf-8',
       timeout: EXEC_TIMEOUT_MS,
       stdio: ['ignore', 'pipe', 'ignore'],
+      killSignal: 'SIGKILL',
     });
   } catch (err: unknown) {
     // Some tools (e.g. ffmpeg) exit non-zero on -version but still print to stdout
@@ -187,11 +212,12 @@ function readWindowsFileVersion(winPath: string): string | null {
     const windowsPath = execFileSync('wslpath', ['-w', winPath], {
       encoding: 'utf-8',
       timeout: EXEC_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
     }).trim();
     const out = execFileSync(
       'powershell.exe',
       ['-NoProfile', '-Command', `(Get-Item '${windowsPath.replace(/'/g, "''")}').VersionInfo.ProductVersion`],
-      { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }
+      { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS, killSignal: 'SIGKILL' }
     ).trim();
     return out || null;
   } catch {
@@ -209,6 +235,7 @@ export function createRealHost(): ProbeHost {
     environment,
     which: safeWhich,
     fileExists: existsSync,
+    isExecutableFile: isExecutableRegularFile,
     runVersion: safeRunVersion,
     windowsProgramRoots: listWindowsProgramRoots,
     windowsFileVersion: readWindowsFileVersion,

src/utils/index.ts

@@ -68,3 +68,12 @@ export type { DeepSeekProfile, DeepSeekProfileKind } from './deepseek-cli-resolv
 export { compileFileQuery, matchFileQuery } from './file-query.js';
 export type { FileQueryMatcher } from './file-query.js';
 export { resolveOmpDir, isOmpAvailable, getOmpNotFoundMessage, getOmpCliVersion } from './omp-cli-resolver.js';
+export {
+  boundedPathExists,
+  describeUnknownPath,
+  probePath,
+  probePathKind,
+  isNearStalledPath,
+  unknownPathReason,
+} from './bounded-path-probe.js';
+export type { PathProbeState, PathProbeKind, PathProbeOptions } from './bounded-path-probe.js';

src/web/case-path.ts

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Validation for "create a new case in a custom folder" (`POST /api/cases` with a
+ * `path`). Creating a case writes a scaffold (`CLAUDE.md`, `src/`, `.claude/settings.local.json`)
+ * and registers the folder in the shared, ownerless linked-cases registry, so the target has to be
+ * judged before anything is created:
+ *
+ *   - it must be an absolute path (a leading `~` is expanded) with no traversal and none of the shell
+ *     metacharacters a session's working directory is later rejected for (`isValidWorkingDir`), so
+ *     a case this accepts is one a session can actually start in;
+ *   - it must not be a system directory, the home directory itself, Codeman's own data directory, or
+ *     a credential/config tree (`~/.ssh`, `~/.aws`, `~/.claude`, ...). Judged on the path as typed AND on
+ *     its symlink-resolved form, against both the given and the symlink-resolved roots (a home reached
+ *     through a link, macOS's `/etc` -> `/private/etc`), so a link into a blocked tree is not a way
+ *     around it;
+ *   - it must not be, or be inside, a cases directory: a case there is a plain Create New, and the same
+ *     folder listed both as a local case and as a linked one would make deleting it remove files;
+ *   - its parent must already exist (one folder is created, never a whole chain), and the folder
+ *     itself must not exist or must be an EMPTY directory (a folder with contents is Link Existing's
+ *     job, and silently scaffolding into someone's project is the one thing this must never do);
+ *   - it must not be a symlink.
+ *
+ * Pure except for the filesystem reads in `prepareNewCasePath`; the policy lives in `blockedReason`
+ * so it can be tested without a disk.
+ *
+ * @module web/case-path
+ */
+
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { isValidWorkingDir } from './schemas.js';
+import { describeUnknownPath, probePath } from '../utils/index.js';
+
+/** System trees nobody creates a project in; creating one here is a mistake or an attack. */
+const BLOCKED_SYSTEM_ROOTS = [
+  '/bin',
+  '/boot',
+  '/dev',
+  '/etc',
+  '/lib',
+  '/lib32',
+  '/lib64',
+  '/proc',
+  '/run',
+  '/sbin',
+  '/sys',
+  '/usr',
+];
+
+/** Home-relative trees that hold credentials or other tools' own configuration. */
+const BLOCKED_HOME_DIRS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker', '.claude', '.codex', '.gemini'];
+
+export interface NewCasePathContext {
+  home: string;
+  /** Codeman's own state directory (`getDataDir()`), which must never become a case. */
+  dataDir: string;
+  /**
+   * The cases directories (the caller's own and the shared one). A folder in one of them is already
+   * listed as a local case, so it must not be registered as a linked one too.
+   */
+  casesDirs?: readonly string[];
+}
+
+export type NewCasePathResult =
+  | { ok: true; path: string; existedEmpty: boolean }
+  | { ok: false; code: 'INVALID' | 'BLOCKED' | 'NOT_FOUND' | 'EXISTS' | 'UNREACHABLE'; reason: string };
+
+const isWithin = (child: string, root: string): boolean =>
+  child === root || child.startsWith(root.endsWith(sep) ? root : root + sep);
+
+/** `~` and `~/x` to the home directory; anything else is returned unchanged. */
+export function expandHome(raw: string, home: string): string {
+  if (raw === '~') return home;
+  if (raw.startsWith('~/')) return join(home, raw.slice(2));
+  return raw;
+}
+
+/**
+ * Why a case may not live at this (already absolute and normalised) path, or null. `systemRoots`
+ * defaults to the system trees as spelled; pass their symlink-resolved forms to judge a resolved path.
+ */
+export function blockedReason(
+  absPath: string,
+  ctx: NewCasePathContext,
+  systemRoots: readonly string[] = BLOCKED_SYSTEM_ROOTS
+): string | null {
+  if (absPath === sep) return 'The filesystem root cannot be a case';
+  for (const root of systemRoots) {
+    if (isWithin(absPath, root)) return `${root} is a system directory`;
+  }
+  if (absPath === ctx.home) return 'The home folder itself cannot be a case; pick a folder inside it';
+  for (const dir of BLOCKED_HOME_DIRS) {
+    if (isWithin(absPath, join(ctx.home, dir))) return `~/${dir} holds credentials or another tool's configuration`;
+  }
+  if (isWithin(absPath, ctx.dataDir)) return "Codeman's own data folder cannot be a case";
+  // Any Codeman instance's data dir under the home folder (~/.codeman, ~/.codeman-beta, ...), not only
+  // the one this process uses.
+  if (absPath.startsWith(ctx.home + sep)) {
+    const firstSegment = absPath.slice(ctx.home.length + 1).split(sep)[0];
+    if (/^\.codeman/.test(firstSegment)) return "Codeman's own data folder cannot be a case";
+  }
+  for (const dir of ctx.casesDirs ?? []) {
+    if (isWithin(absPath, dir)) {
+      return 'That folder is inside the cases folder; create a case there with plain Create New (no custom folder)';
+    }
+  }
+  return null;
+}
+
+/** `p` with its symlinks resolved, or `p` itself when it does not exist (or cannot be read). */
+async function realpathOr(p: string): Promise<string> {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return p;
+  }
+}
+
+/** The context and system roots with their symlinks resolved, for judging a resolved path. */
+async function resolvedPolicy(ctx: NewCasePathContext): Promise<[NewCasePathContext, string[]]> {
+  const [home, dataDir, casesDirs, systemRoots] = await Promise.all([
+    realpathOr(ctx.home),
+    realpathOr(ctx.dataDir),
+    Promise.all((ctx.casesDirs ?? []).map(realpathOr)),
+    Promise.all(BLOCKED_SYSTEM_ROOTS.map(realpathOr)),
+  ]);
+  return [{ home, dataDir, casesDirs }, systemRoots];
+}
+
+/**
+ * Judge `raw` as the folder for a new case and, if it is acceptable, say what to create.
+ * Never creates anything.
+ */
+export async function prepareNewCasePath(raw: string, ctx: NewCasePathContext): Promise<NewCasePathResult> {
+  const typed = raw.trim();
+  if (!typed) return { ok: false, code: 'INVALID', reason: 'Enter a folder path' };
+  const expanded = expandHome(typed, ctx.home);
+  if (!isValidWorkingDir(expanded)) {
+    return {
+      ok: false,
+      code: 'INVALID',
+      reason: 'Use an absolute path with letters, numbers, spaces, - _ . only (no .., no shell characters)',
+    };
+  }
+
+  const target = resolve(expanded);
+  const typedBlock = blockedReason(target, ctx);
+  if (typedBlock) return { ok: false, code: 'BLOCKED', reason: typedBlock };
+
+  // Bounded first: the parent can sit on a network mount that stopped answering, where the
+  // realpath/stat/lstat/readdir below would each hold a threadpool worker until it returns.
+  // It is one folder the user named, so the probe may pass the bulk cap (never the ceiling).
+  const parentState = await probePath(dirname(target), { pastCap: true });
+  if (parentState === 'absent') {
+    return { ok: false, code: 'NOT_FOUND', reason: `The parent folder ${dirname(target)} does not exist` };
+  }
+  if (parentState === 'unknown') {
+    return {
+      ok: false,
+      code: 'UNREACHABLE',
+      reason: describeUnknownPath('The parent folder', dirname(target), { pastCap: true }),
+    };
+  }
+
+  // Resolve the parent's symlinks, then judge again: a link into a blocked tree must not pass.
+  let realParent: string;
+  try {
+    realParent = await fs.realpath(dirname(target));
+    if (!(await fs.stat(realParent)).isDirectory()) {
+      return { ok: false, code: 'INVALID', reason: `${dirname(target)} is not a folder` };
+    }
+  } catch {
+    return { ok: false, code: 'NOT_FOUND', reason: `The parent folder ${dirname(target)} does not exist` };
+  }
+  const real = join(realParent, basename(target));
+  // The resolved path against the roots as given AND as resolved: with home reached through a link, a
+  // link to <real home>/.ssh is only caught by the resolved home; on macOS /etc is /private/etc.
+  const [resolvedCtx, resolvedSystemRoots] = await resolvedPolicy(ctx);
+  const realBlock = blockedReason(real, ctx) ?? blockedReason(real, resolvedCtx, resolvedSystemRoots);
+  if (realBlock) return { ok: false, code: 'BLOCKED', reason: realBlock };
+
+  try {
+    const st = await fs.lstat(real);
+    if (st.isSymbolicLink()) return { ok: false, code: 'INVALID', reason: `${target} is a symbolic link` };
+    if (!st.isDirectory()) return { ok: false, code: 'INVALID', reason: `${target} exists and is not a folder` };
+    if ((await fs.readdir(real)).length > 0) {
+      return {
+        ok: false,
+        code: 'EXISTS',
+        reason: `${target} already has files in it. Use "Link Existing" for a project that already exists`,
+      };
+    }
+    return { ok: true, path: real, existedEmpty: true };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { ok: true, path: real, existedEmpty: false };
+    return { ok: false, code: 'INVALID', reason: `Cannot read ${target}: ${(err as Error).message}` };
+  }
+}

src/web/launch-defaults.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Launch-time defaults from synced App Settings, driven by registry data.
+ *
+ * A CLI entry declares `capabilities.launchDefaults` (launch param -> settings key; today
+ * only codex, `{ model: 'codexModel', reasoningEffort: 'codexReasoningEffort' }`), and
+ * `applyLaunchDefaults()` fills those settings into the entry's `launch.legacyConfigField`
+ * object, setting ONLY the fields the caller left unset. Persisted values are re-validated
+ * with `SettingsUpdateSchema`, so a hand-edited settings.json can never smuggle an
+ * unchecked value onto the command line.
+ *
+ * Scope is the caller's decision: the create and quick-start routes apply it to local
+ * launches only, never to remote, Docker or custom-endpoint launches. Nothing here writes
+ * a CLI's own config files.
+ */
+
+import { getCli } from '../config/cli-registry/registry.js';
+import { SettingsUpdateSchema } from './schemas.js';
+import { readJsonConfig, SETTINGS_PATH } from './route-helpers.js';
+
+/**
+ * Return `configs` with the launch defaults of `mode`'s registry entry filled into its
+ * legacy config object (e.g. `codexConfig`). Every other field of `configs` is passed
+ * through untouched, and `configs` itself comes back unchanged (same object) when the entry
+ * declares no defaults, `customEndpoint` is set, or no setting names a value.
+ */
+export async function applyLaunchDefaults<T extends object>(
+  mode: string,
+  configs: T,
+  customEndpoint = false
+): Promise<T> {
+  const entry = getCli(mode);
+  const declared = entry?.capabilities.launchDefaults;
+  const field = entry?.launch.legacyConfigField;
+  if (customEndpoint || !declared || field === undefined) return configs;
+
+  const settings = await readJsonConfig<Record<string, unknown>>(SETTINGS_PATH, 'CLI launch defaults', {});
+  const aliases = entry.launch.legacyConfigAliases ?? {};
+  const current = (configs as Record<string, unknown>)[field] as Record<string, unknown> | undefined;
+  const defaults: Record<string, unknown> = {};
+  for (const [param, settingKey] of Object.entries(declared)) {
+    const parsed = SettingsUpdateSchema.shape[settingKey].safeParse(settings[settingKey]);
+    // '' is the settings' "leave it to the CLI" value, the same as unset.
+    const value = parsed.success ? parsed.data || undefined : undefined;
+    const wireKey = aliases[param] ?? param;
+    if (value !== undefined && (current?.[wireKey] ?? undefined) === undefined) defaults[wireKey] = value;
+  }
+  if (Object.keys(defaults).length === 0) return configs;
+  return { ...configs, [field]: { ...current, ...defaults } };
+}

src/web/public/entrance-animations.js

@@ -692,6 +692,7 @@ Object.assign(CodemanApp.prototype, {
         <span class="tab-number">${base + i + 1}</span>
         <span class="tab-status idle" aria-hidden="true"></span>
         <span class="tab-info"><span class="tab-name-row">
+          <span class="tab-harness run-mode-dot claude" aria-hidden="true"></span>
           <span class="tab-name">w${base + i + 1}-demo</span>
         </span></span>`;
       container.appendChild(tab);

src/web/public/git-status-ui.js

@@ -0,0 +1,719 @@
+/**
+ * @fileoverview Git status indicator in the bottom bar, and the panel it opens.
+ *
+ * Agents leave work uncommitted and unpushed. This puts a small indicator at the right of the bottom
+ * toolbar for the ACTIVE session's repository, or repositories when the session's folder holds several (`●3` uncommitted files, `↑2` commits not pushed,
+ * `✓` when everything is committed and pushed) and, on click, a draggable panel in the style of the
+ * Files window listing exactly which files are uncommitted and which commits are not pushed.
+ *
+ * OPTIONAL and per-device: `showGitStatus` (App Settings → Header & Panels → Bottom bar), default
+ * OFF. While it is off nothing polls and the button never shows. While it is on, the page asks
+ * `GET /api/sessions/:id/git-status` for the active session on a slow poll (and at once when the
+ * session changes or the window regains focus). The route is read-only and offline: it never fetches
+ * or changes the repository, so the "behind" number reflects the last `git fetch`, which the panel
+ * footer says. Remote (SSH) and Docker sessions answer `unsupported` and show no indicator.
+ *
+ * Everything that comes from git (file names, commit subjects, author names) is untrusted text: it is
+ * only ever written with `textContent`, never `innerHTML`.
+ *
+ * The bottom toolbar's right group is hidden on phones (mobile.css), so this surface is desktop and
+ * tablet only by construction.
+ *
+ * @mixin Extends CodemanApp.prototype via Object.assign
+ * @dependency app.js (this.activeSessionId, this.loadAppSettingsFromStorage, this.getDefaultSettings, this.$)
+ * @dependency panels-ui.js (openFilePreview)
+ * @loadorder 12.57 of 16, after home-sessions.js, before entrance-animations.js
+ */
+
+/** How often the active session's repository is re-read while the indicator is on. */
+const GIT_STATUS_POLL_MS = 15000;
+/** The timer only decides whether a poll is due; it is cheap and runs while the indicator is on. */
+const GIT_STATUS_TICK_MS = 2000;
+/** A focus or visibility change refreshes at once unless the last read is younger than this. */
+const GIT_STATUS_MIN_REFRESH_MS = 3000;
+
+const GIT_STATUS_BADGE_TITLE = {
+  M: 'Modified',
+  A: 'Added',
+  D: 'Deleted',
+  R: 'Renamed',
+  C: 'Copied',
+  T: 'Type changed',
+  U: 'Unmerged',
+  '?': 'Untracked',
+};
+
+Object.assign(CodemanApp.prototype, {
+  /** Per-device setting, default OFF. */
+  isGitStatusEnabled() {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    return (settings.showGitStatus ?? defaults.showGitStatus ?? false) === true;
+  },
+
+  /**
+   * Starts or stops the poll to match the setting. Called from applyHeaderVisibilitySettings(), which
+   * runs on boot and after every settings save, so a live toggle needs no reload.
+   */
+  applyGitStatusVisibility() {
+    const on = this.isGitStatusEnabled();
+    if (on && !this._gitStatusTimer) {
+      this._gitStatusTimer = setInterval(() => this._gitStatusTick(), GIT_STATUS_TICK_MS);
+      this._gitStatusOnVisible = () => {
+        if (!document.hidden) this.refreshGitStatus({ minAgeMs: GIT_STATUS_MIN_REFRESH_MS });
+      };
+      document.addEventListener('visibilitychange', this._gitStatusOnVisible);
+      window.addEventListener('focus', this._gitStatusOnVisible);
+      this.refreshGitStatus();
+    } else if (!on && this._gitStatusTimer) {
+      clearInterval(this._gitStatusTimer);
+      this._gitStatusTimer = null;
+      document.removeEventListener('visibilitychange', this._gitStatusOnVisible);
+      window.removeEventListener('focus', this._gitStatusOnVisible);
+      this._gitStatusOnVisible = null;
+    }
+    if (!on) {
+      this._gitStatus = null;
+      this._gitStatusEpoch = (this._gitStatusEpoch || 0) + 1; // an in-flight read must not repaint
+      // That read's `finally` no longer owns the flag (its epoch is stale), so release it here: left set,
+      // turning the setting back on would skip every refresh for this session until a reload.
+      this._gitStatusInFlight = false;
+      this.closeGitStatusPanel();
+    }
+    this._renderGitStatusButton();
+  },
+
+  _gitStatusTick() {
+    if (document.hidden) return;
+    const sid = this.activeSessionId || null;
+    if (sid !== this._gitStatusSessionId) {
+      // The active session changed (or the first one opened): show nothing stale, read now.
+      this._gitStatus = null;
+      this._renderGitStatusButton();
+      if (this._isGitStatusPanelOpen()) this._renderGitStatusPanel(); // not the previous repo's files
+      this.refreshGitStatus();
+      return;
+    }
+    if (sid && Date.now() - (this._gitStatusFetchedAt || 0) >= GIT_STATUS_POLL_MS) this.refreshGitStatus();
+  },
+
+  /** Reads the active session's git status and repaints. Stale answers (another session, setting off) are dropped. */
+  async refreshGitStatus({ minAgeMs = 0, fresh = false } = {}) {
+    if (!this.isGitStatusEnabled()) return;
+    const sid = this.activeSessionId || null;
+    this._gitStatusSessionId = sid;
+    if (!sid) {
+      this._gitStatus = null;
+      this._renderGitStatusButton();
+      if (this._isGitStatusPanelOpen()) this._renderGitStatusPanel();
+      return;
+    }
+    if (minAgeMs && Date.now() - (this._gitStatusFetchedAt || 0) < minAgeMs) return;
+    // A read for THIS session is already running: let it finish. One for another session is not worth
+    // waiting for (its answer is dropped below), so a session switch is never left blank.
+    if (this._gitStatusInFlight && this._gitStatusInFlightSid === sid) return;
+    this._gitStatusInFlight = true;
+    this._gitStatusInFlightSid = sid;
+    const epoch = (this._gitStatusEpoch = (this._gitStatusEpoch || 0) + 1);
+    this._gitStatusFetchedAt = Date.now();
+    try {
+      const query = new URLSearchParams(this.gitStatusLimits());
+      if (fresh) query.set('fresh', '1');
+      const data = await this._apiJson(`/api/sessions/${encodeURIComponent(sid)}/git-status?${query}`);
+      if (epoch !== this._gitStatusEpoch || sid !== this.activeSessionId || !this.isGitStatusEnabled()) return;
+      this._gitStatus = data ? { sessionId: sid, data } : null;
+    } catch {
+      if (epoch === this._gitStatusEpoch) this._gitStatus = null;
+    } finally {
+      // Only the newest request owns the flag: an older one finishing late must not clear it.
+      if (epoch === this._gitStatusEpoch) this._gitStatusInFlight = false;
+    }
+    if (epoch !== this._gitStatusEpoch) return;
+    this._renderGitStatusButton();
+    if (this._isGitStatusPanelOpen()) this._renderGitStatusPanel();
+  },
+
+  /**
+   * How many repositories to list below a folder that is not itself a repository, and how long one
+   * git command may run, in seconds (Settings → Bottom bar, per device). The server clamps both again.
+   */
+  gitStatusLimits() {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    const num = (v, min, max, fallback) => {
+      const n = Math.trunc(Number(v));
+      return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+    };
+    return {
+      maxRepos: num(settings.gitStatusMaxRepos ?? defaults.gitStatusMaxRepos, 1, 50, 12),
+      timeout: num(settings.gitStatusTimeoutSeconds ?? defaults.gitStatusTimeoutSeconds, 5, 120, 30),
+    };
+  },
+
+  /** Whether the Git window groups changed files under collapsible folders (default on). */
+  isGitStatusTree() {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    return (settings.gitStatusTree ?? defaults.gitStatusTree ?? true) === true;
+  },
+
+  /** The data for the session on screen, or null (not enabled, no session, not a repo, remote/docker, error). */
+  _currentGitStatus() {
+    const s = this._gitStatus;
+    return s && s.sessionId === this.activeSessionId && s.data ? s.data : null;
+  },
+
+  /** `{ uncommitted, unpushed, conflicted, repos, tone }` summed over every repository, or null when there is nothing to show. */
+  _gitStatusSummary(overview) {
+    if (!overview || overview.state !== 'ok' || !overview.repos?.length) return null;
+    let uncommitted = 0;
+    let unpushed = 0;
+    let conflicted = 0;
+    let unreadable = 0;
+    for (const r of overview.repos) {
+      if (r.status.state === 'error') unreadable += 1;
+      uncommitted += r.status.counts.uncommitted;
+      unpushed += r.status.unpushedCount;
+      conflicted += r.status.counts.conflicted;
+    }
+    // A repository that could not be read is not "clean": it must not let the indicator say ✓.
+    const tone = conflicted > 0 ? 'conflict' : uncommitted > 0 || unpushed > 0 || unreadable > 0 ? 'dirty' : 'clean';
+    return { uncommitted, unpushed, conflicted, unreadable, repos: overview.repos.length, tone };
+  },
+
+  /** One sentence for the tooltip and the screen-reader label. */
+  _gitStatusSentence(overview) {
+    const sum = this._gitStatusSummary(overview);
+    if (!sum) return '';
+    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    const bits = [];
+    if (sum.conflicted) bits.push(plural(sum.conflicted, 'file with a merge conflict', 'files with merge conflicts'));
+    if (sum.uncommitted) bits.push(plural(sum.uncommitted, 'uncommitted file', 'uncommitted files'));
+    if (sum.unpushed) bits.push(plural(sum.unpushed, 'commit not pushed', 'commits not pushed'));
+    if (sum.unreadable)
+      bits.push(plural(sum.unreadable, 'repository could not be read', 'repositories could not be read'));
+    if (!bits.length) bits.push('everything is committed and pushed');
+    let where;
+    if (sum.repos > 1) where = `${sum.repos} repositories`;
+    else {
+      const d = overview.repos[0].status;
+      where = d.state === 'error' ? overview.repos[0].name : d.detached ? 'detached HEAD' : d.branch || 'no branch';
+    }
+    return `Git (${where}): ${bits.join(', ')}. Click for details.`;
+  },
+
+  _renderGitStatusButton() {
+    const btn = this.$('gitStatusBtn');
+    if (!btn) return;
+    const data = this.isGitStatusEnabled() ? this._currentGitStatus() : null;
+    const sum = this._gitStatusSummary(data);
+    btn.hidden = !sum;
+    btn.classList.toggle('git-status--clean', sum?.tone === 'clean');
+    btn.classList.toggle('git-status--dirty', sum?.tone === 'dirty');
+    btn.classList.toggle('git-status--conflict', sum?.tone === 'conflict');
+    const label = btn.querySelector('.git-status-label');
+    if (!sum) {
+      if (label) label.textContent = '';
+      return;
+    }
+    const parts = [];
+    if (sum.conflicted) parts.push(`⚠ ${sum.conflicted}`);
+    if (sum.uncommitted) parts.push(`● ${sum.uncommitted}`);
+    if (sum.unpushed) parts.push(`↑ ${sum.unpushed}`);
+    if (sum.unreadable) parts.push(`? ${sum.unreadable}`);
+    if (!parts.length) parts.push('✓');
+    if (label) label.textContent = parts.join('  ');
+    const sentence = this._gitStatusSentence(data);
+    btn.title = sentence;
+    btn.setAttribute('aria-label', sentence);
+  },
+
+  // ── Panel ───────────────────────────────────────────────────────────────
+
+  _isGitStatusPanelOpen() {
+    return !!this.$('gitStatusPanel')?.classList.contains('visible');
+  },
+
+  toggleGitStatusPanel() {
+    if (this._isGitStatusPanelOpen()) {
+      this.closeGitStatusPanel();
+      return;
+    }
+    const panel = this.$('gitStatusPanel');
+    if (!panel) return;
+    panel.classList.add('visible');
+    this.$('gitStatusBtn')?.setAttribute('aria-expanded', 'true');
+    this._ensureGitStatusPanelDrag();
+    this._renderGitStatusPanel();
+    this.refreshGitStatus({ fresh: true }); // the click should show what is true now, not what was true 14s ago
+  },
+
+  closeGitStatusPanel() {
+    this._gitDiffView = null;
+    const panel = this.$('gitStatusPanel');
+    if (panel) {
+      panel.classList.remove('visible');
+      // Reset a dragged position so it reopens at the default spot.
+      panel.style.left = panel.style.top = panel.style.right = panel.style.bottom = '';
+    }
+    this.$('gitStatusBtn')?.setAttribute('aria-expanded', 'false');
+  },
+
+  refreshGitStatusNow() {
+    this._gitStatusFetchedAt = 0;
+    this._gitStatusInFlight = false;
+    return this.refreshGitStatus({ fresh: true });
+  },
+
+  /** Drag by the header. Pointer events cover mouse, pen and touch; one set of listeners lives as long as the page. */
+  _ensureGitStatusPanelDrag() {
+    const panel = this.$('gitStatusPanel');
+    const handle = panel?.querySelector('.git-status-header');
+    if (!panel || !handle || handle._dragReady) return;
+    handle._dragReady = true;
+    let drag = null;
+    handle.addEventListener('pointerdown', (e) => {
+      if (e.target.closest('button')) return;
+      const rect = panel.getBoundingClientRect();
+      drag = { dx: e.clientX - rect.left, dy: e.clientY - rect.top };
+      // Switch from right/bottom anchoring to explicit left/top so the drag has one coordinate system.
+      panel.style.left = `${rect.left}px`;
+      panel.style.top = `${rect.top}px`;
+      panel.style.right = 'auto';
+      panel.style.bottom = 'auto';
+      handle.setPointerCapture?.(e.pointerId);
+      e.preventDefault();
+    });
+    handle.addEventListener('pointermove', (e) => {
+      if (!drag) return;
+      const maxX = window.innerWidth - panel.offsetWidth - 4;
+      const maxY = window.innerHeight - panel.offsetHeight - 4;
+      panel.style.left = `${Math.max(4, Math.min(e.clientX - drag.dx, maxX))}px`;
+      panel.style.top = `${Math.max(4, Math.min(e.clientY - drag.dy, maxY))}px`;
+    });
+    const end = (e) => {
+      drag = null;
+      handle.releasePointerCapture?.(e.pointerId);
+    };
+    handle.addEventListener('pointerup', end);
+    handle.addEventListener('pointercancel', end);
+  },
+
+  _gitEl(tag, className, text) {
+    const el = document.createElement(tag);
+    if (className) el.className = className;
+    if (text !== undefined) el.textContent = text;
+    return el;
+  },
+
+  _renderGitStatusPanel() {
+    const body = this.$('gitStatusBody');
+    const head = this.$('gitStatusBranch');
+    const foot = this.$('gitStatusFooter');
+    if (!body) return;
+    const overview = this._currentGitStatus();
+    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
+    // The 15 s poll replaces every row: put keyboard focus back on the same file afterwards.
+    const focusKey = body.contains(document.activeElement)
+      ? document.activeElement.closest?.('[data-git-key]')?.dataset.gitKey
+      : null;
+    const view = this._gitDiffView;
+    if (view && view.sessionId === this.activeSessionId) {
+      // A file's diff is on screen: the 15 s poll re-renders the panel, and must not throw it away.
+      this._renderGitDiffView(body, view);
+      if (head) head.textContent = '';
+      if (foot) foot.textContent = '';
+      return;
+    }
+    this._gitDiffView = null;
+    body.replaceChildren();
+    const clearChrome = () => {
+      if (head) head.textContent = '';
+      if (foot) foot.textContent = '';
+    };
+
+    if (!this.activeSessionId) {
+      body.append(el('div', 'git-status-empty', 'Open a session to see its repository.'));
+      clearChrome();
+      return;
+    }
+    if (!overview) {
+      body.append(
+        el('div', 'git-status-empty', this._gitStatus === null ? 'Reading the repository…' : 'No status available.')
+      );
+      return;
+    }
+    if (overview.state !== 'ok') {
+      const why =
+        overview.state === 'not-a-repo'
+          ? 'No git repository here: this session’s folder is not one, and none was found inside it (up to two levels down).'
+          : overview.state === 'unsupported'
+            ? overview.reason === 'docker'
+              ? 'Git status is not available for Docker sessions, or for folders inside a Docker case workspace.'
+              : 'Git status is not available for remote (SSH) sessions.'
+            : `Could not read the repository: ${overview.error || 'git failed'}`;
+      body.append(el('div', 'git-status-empty', why));
+      clearChrome();
+      return;
+    }
+
+    const repos = overview.repos;
+    if (repos.length === 1 && repos[0].status.state !== 'error' && !overview.reposTruncated) {
+      // One repository: the panel is that repository, as it always was. One that git could not read,
+      // or the only one shown of several (the limit is 1), takes the list view below instead, so its
+      // error row or the "Showing the first" notice is not lost.
+      const d = repos[0].status;
+      if (head) head.textContent = d.detached ? 'detached HEAD' : d.branch || '';
+      this._renderGitRepoInto(body, d);
+    } else {
+      if (head) head.textContent = repos.length === 1 ? '1 repository' : `${repos.length} repositories`;
+      for (const r of repos) body.append(this._gitRepoSection(r));
+      if (overview.reposTruncated) {
+        body.append(
+          el(
+            'div',
+            'git-status-more',
+            `Showing the first ${overview.repoLimit || repos.length} of more than ${overview.repoLimit || repos.length} repositories under this folder. Raise “Git status: max repositories” in Settings → Bottom bar to see more.`
+          )
+        );
+      }
+    }
+
+    if (foot) {
+      foot.textContent = `Checked ${new Date(overview.checkedAt).toLocaleTimeString()}. Read-only: Codeman never fetches or changes the repository, so “behind” is as of your last fetch.`;
+    }
+    if (focusKey) {
+      const again = [...body.querySelectorAll('[data-git-key]')].find((n) => n.dataset.gitKey === focusKey);
+      again?.focus({ preventScroll: true });
+    }
+  },
+
+  /**
+   * One repository of several: a collapsible section, collapsed by default (the summary line already
+   * shows what is outstanding). Which ones the user opened stay open across the 15 s re-render.
+   */
+  _gitRepoSection(r) {
+    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
+    const d = r.status;
+    if (d.state === 'error') {
+      // Kept in the list with the reason, rather than silently left out.
+      const row = el('div', 'git-status-repo git-status-repo--error');
+      row.append(el('span', 'git-status-repo-name', r.name));
+      if (r.path !== r.name) row.append(el('span', 'git-status-repo-path', r.path));
+      const why = el('span', 'git-status-repo-unreadable', `⚠ could not read: ${d.error || 'git failed'}`);
+      why.title = 'If this is a timeout, raise “Git status: git timeout” in Settings → Bottom bar.';
+      row.append(why);
+      return row;
+    }
+    const section = el('details', 'git-status-repo');
+    const outstanding = d.counts.uncommitted > 0 || d.unpushedCount > 0;
+    const openRepos = (this._gitTreeOpen = this._gitTreeOpen || new Set());
+    const repoKey = `repo|${d.repoRoot || r.path}`;
+    section.open = openRepos.has(repoKey);
+    section.addEventListener('toggle', () => (section.open ? openRepos.add(repoKey) : openRepos.delete(repoKey)));
+    const summary = el('summary', 'git-status-repo-summary');
+    summary.append(el('span', 'git-status-repo-name', r.name));
+    if (r.path !== r.name) summary.append(el('span', 'git-status-repo-path', r.path));
+    summary.append(el('span', 'git-status-repo-branch', d.detached ? 'detached HEAD' : d.branch || ''));
+    const bits = [];
+    if (d.counts.conflicted) bits.push(`⚠ ${d.counts.conflicted}`);
+    if (d.counts.uncommitted) bits.push(`● ${d.counts.uncommitted}`);
+    if (d.unpushedCount) bits.push(`↑ ${d.unpushedCount}`);
+    const state = el(
+      'span',
+      `git-status-repo-state${outstanding ? ' git-status-repo-state--dirty' : ''}`,
+      bits.join('  ') || '✓'
+    );
+    summary.append(state);
+    section.append(summary);
+    const inner = el('div', 'git-status-repo-body');
+    this._renderGitRepoInto(inner, d);
+    section.append(inner);
+    return section;
+  },
+
+  /** The branch line, uncommitted files and unpushed commits of ONE repository into `body`. */
+  _renderGitRepoInto(body, data) {
+    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
+
+    // Branch / upstream line.
+    const line = el('div', 'git-status-branchline');
+    if (data.upstream && data.upstreamGone) {
+      line.append(el('span', 'git-status-chip', `${data.branch || 'HEAD'} → ${data.upstream}`));
+      const gone = el('span', 'git-status-chip git-status-chip--warn', 'Upstream not on remote');
+      gone.title =
+        'The upstream branch does not exist on the remote (never pushed, or deleted and pruned), so the commits below are on no remote.';
+      line.append(gone);
+    } else if (data.upstream) {
+      line.append(el('span', 'git-status-chip', `${data.branch || 'HEAD'} → ${data.upstream}`));
+      if (data.ahead) line.append(el('span', 'git-status-chip git-status-chip--warn', `↑ ${data.ahead} ahead`));
+      if (data.behind) {
+        const behind = el('span', 'git-status-chip', `↓ ${data.behind} behind`);
+        behind.title = 'As of the last git fetch: Codeman never fetches.';
+        line.append(behind);
+      }
+    } else if (data.hasRemote) {
+      line.append(el('span', 'git-status-chip git-status-chip--warn', 'No upstream branch'));
+    } else {
+      line.append(el('span', 'git-status-chip', 'No remote configured'));
+    }
+    if (data.counts.stashes) {
+      line.append(
+        el('span', 'git-status-chip', `${data.counts.stashes} stash${data.counts.stashes === 1 ? '' : 'es'}`)
+      );
+    }
+    body.append(line);
+
+    // Uncommitted changes.
+    const filesSection = el('section', 'git-status-section');
+    filesSection.append(el('h4', 'git-status-section-title', `Uncommitted changes (${data.counts.uncommitted})`));
+    if (!data.files.length) {
+      filesSection.append(el('div', 'git-status-ok', 'Nothing uncommitted.'));
+    } else {
+      const groups = [
+        ['conflicted', 'Merge conflicts'],
+        ['staged', 'Staged'],
+        ['unstaged', 'Not staged'],
+        ['untracked', 'Untracked'],
+      ];
+      for (const [kind, label] of groups) {
+        const rows = data.files.filter((f) => f.kind === kind);
+        if (!rows.length) continue;
+        const group = el('div', `git-status-group git-status-group--${kind}`);
+        group.append(el('div', 'git-status-group-title', `${label} (${data.counts[kind]})`));
+        if (this.isGitStatusTree()) group.append(...this._gitFileTree(rows, data, kind));
+        else for (const f of rows) group.append(this._gitFileRow(f, data));
+        filesSection.append(group);
+      }
+      if (data.filesTruncated) {
+        filesSection.append(
+          el(
+            'div',
+            'git-status-more',
+            `Showing the first ${data.files.length} entries; the counts above include every file.`
+          )
+        );
+      }
+    }
+    body.append(filesSection);
+
+    // Commits not pushed.
+    const pushSection = el('section', 'git-status-section');
+    pushSection.append(el('h4', 'git-status-section-title', `Not pushed (${data.unpushedCount})`));
+    if (!data.unpushedCount) {
+      pushSection.append(
+        el(
+          'div',
+          'git-status-ok',
+          data.hasRemote ? 'Every commit on this branch is on a remote.' : 'There is no remote to push to.'
+        )
+      );
+    } else {
+      if (!data.upstream || data.upstreamGone) {
+        pushSection.append(
+          el(
+            'div',
+            'git-status-note',
+            data.upstreamGone
+              ? 'The upstream branch does not exist on the remote (never pushed, or deleted), so these commits are on no remote.'
+              : 'This branch has no upstream, so these commits are on no remote yet.'
+          )
+        );
+      }
+      for (const c of data.unpushed) pushSection.append(this._gitCommitRow(c));
+      if (data.unpushedCount > data.unpushed.length) {
+        pushSection.append(
+          el('div', 'git-status-more', `…and ${data.unpushedCount - data.unpushed.length} older commits.`)
+        );
+      }
+    }
+    body.append(pushSection);
+  },
+
+  /**
+   * `rows` as folders (collapsed until clicked) holding their files. A folder with one child folder and
+   * nothing else is merged into it (`src/web/public` as one row) so a deep path is one click, not five.
+   * Which folders are open survives the 15 s re-render (`_gitTreeOpen`, keyed by repo, group and folder).
+   */
+  _gitFileTree(rows, data, kind) {
+    const root = { dirs: new Map(), files: [] };
+    for (const f of rows) {
+      const trailing = f.path.endsWith('/');
+      const parts = f.path.replace(/\/$/, '').split('/');
+      const leaf = parts.pop() + (trailing ? '/' : '');
+      let node = root;
+      for (const part of parts) {
+        if (!node.dirs.has(part)) node.dirs.set(part, { dirs: new Map(), files: [] });
+        node = node.dirs.get(part);
+      }
+      node.files.push({ f, leaf });
+    }
+    const open = (this._gitTreeOpen = this._gitTreeOpen || new Set());
+    const count = (n) => n.files.length + [...n.dirs.values()].reduce((sum, d) => sum + count(d), 0);
+    const build = (node, prefix) => {
+      const out = [];
+      for (const [name0, child0] of [...node.dirs].sort((a, b) => a[0].localeCompare(b[0]))) {
+        let name = name0;
+        let child = child0;
+        while (child.files.length === 0 && child.dirs.size === 1) {
+          const [n, c] = [...child.dirs][0];
+          name += `/${n}`;
+          child = c;
+        }
+        const key = `${data.repoRoot}|${kind}|${prefix}${name}`;
+        const dir = this._gitEl('details', 'git-tree-dir');
+        dir.open = open.has(key);
+        dir.addEventListener('toggle', () => (dir.open ? open.add(key) : open.delete(key)));
+        const summary = this._gitEl('summary', 'git-tree-summary');
+        summary.append(this._gitEl('span', 'git-tree-name', `${name}/`));
+        summary.append(this._gitEl('span', 'git-tree-count', String(count(child))));
+        dir.append(summary);
+        const inner = this._gitEl('div', 'git-tree-children');
+        inner.append(...build(child, `${prefix}${name}/`));
+        dir.append(inner);
+        out.push(dir);
+      }
+      for (const { f, leaf } of node.files.sort((a, b) => a.leaf.localeCompare(b.leaf))) {
+        out.push(this._gitFileRow(f, data, leaf));
+      }
+      return out;
+    };
+    return build(root, '');
+  },
+
+  _gitFileRow(f, data, displayName) {
+    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
+    const row = el('div', 'git-status-file');
+    // Untracked entries have `?`; staged ones show the index letter, the rest the working-tree letter.
+    const letter =
+      f.kind === 'untracked' ? '?' : f.kind === 'conflicted' ? 'U' : f.kind === 'staged' ? f.index : f.worktree;
+    const badge = el('span', `git-status-badge git-status-badge--${letter === '?' ? 'new' : letter}`, letter);
+    badge.title = GIT_STATUS_BADGE_TITLE[letter] || letter;
+    row.dataset.gitKey = `${f.kind}|${f.path}`;
+    row.append(badge);
+    const name = el('span', 'git-status-path', displayName ?? f.path);
+    if (displayName) name.title = f.path;
+    row.append(name);
+    if (f.origPath) row.append(el('span', 'git-status-orig', `← ${f.origPath}`));
+
+    // An untracked folder has no single diff; every other row opens its changes.
+    if (!f.path.endsWith('/') && data.repoRoot) {
+      row.classList.add('git-status-file--clickable');
+      row.tabIndex = 0;
+      row.setAttribute('role', 'button');
+      row.title = 'Show what changed';
+      const open = () => this.openGitDiff(data.repoRoot, f, letter);
+      row.addEventListener('click', open);
+      row.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          open();
+        }
+      });
+    }
+    return row;
+  },
+
+  // ── Diff view ───────────────────────────────────────────────────────────
+
+  /** Show `file`'s changes in the panel (a Back button returns to the list). */
+  async openGitDiff(repoRoot, file, letter) {
+    const sessionId = this.activeSessionId;
+    if (!sessionId) return;
+    const view = { sessionId, repoRoot, file, letter, state: 'loading' };
+    this._gitDiffView = view;
+    this._renderGitStatusPanel();
+    const qs = new URLSearchParams({
+      repo: repoRoot,
+      path: file.path,
+      kind: file.kind,
+      ...this.gitStatusLimits(),
+    });
+    const res = await this._api(`/api/sessions/${encodeURIComponent(sessionId)}/git-diff?${qs}`);
+    // Back, another file or another session while this was in flight: drop the answer.
+    if (this._gitDiffView !== view) return;
+    let body = null;
+    try {
+      body = res ? await res.json() : null;
+    } catch {
+      /* fall through */
+    }
+    if (this._gitDiffView !== view) return;
+    if (res && res.ok && body?.success) {
+      view.state = 'ok';
+      view.result = body.data;
+    } else {
+      view.state = 'error';
+      view.error = body?.error || 'Could not read the diff.';
+    }
+    this._renderGitStatusPanel();
+  },
+
+  closeGitDiff() {
+    this._gitDiffView = null;
+    this._renderGitStatusPanel();
+  },
+
+  _renderGitDiffView(body, view) {
+    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
+    body.replaceChildren();
+    const bar = el('div', 'git-diff-bar');
+    const back = el('button', 'btn-toolbar btn-sm', '← Back');
+    back.type = 'button';
+    back.addEventListener('click', () => this.closeGitDiff());
+    bar.append(back);
+    bar.append(el('span', 'git-diff-path', view.file.path));
+    const kindLabel = { staged: 'staged', unstaged: 'not staged', untracked: 'new file', conflicted: 'conflict' };
+    bar.append(el('span', 'git-diff-kind', kindLabel[view.file.kind] || ''));
+    if (view.letter !== 'D') {
+      const open = el('button', 'btn-toolbar btn-sm', 'Open file');
+      open.type = 'button';
+      open.addEventListener('click', () =>
+        this.openFilePreview?.(`${view.repoRoot}/${view.file.path}`, this.activeSessionId)
+      );
+      bar.append(open);
+    }
+    body.append(bar);
+
+    if (view.state === 'loading') {
+      body.append(el('div', 'git-status-empty', 'Reading the diff…'));
+      return;
+    }
+    if (view.state === 'error') {
+      body.append(el('div', 'git-status-empty', view.error));
+      return;
+    }
+    const { diff, truncated, binary } = view.result;
+    if (binary) body.append(el('div', 'git-status-note', 'This is a binary file; there is no text diff to show.'));
+    if (!diff.trim()) {
+      if (!binary) body.append(el('div', 'git-status-empty', 'No textual changes (the file may differ only in mode).'));
+      return;
+    }
+    const pre = el('pre', 'git-diff');
+    const frag = document.createDocumentFragment();
+    for (const line of diff.split('\n')) {
+      let cls = 'git-diff-line';
+      if (line.startsWith('@@')) cls += ' git-diff-line--hunk';
+      else if (
+        /^(diff --git|index |--- |\+\+\+ |new file|deleted file|similarity|rename |old mode|new mode)/.test(line)
+      )
+        cls += ' git-diff-line--meta';
+      else if (line.startsWith('+')) cls += ' git-diff-line--add';
+      else if (line.startsWith('-')) cls += ' git-diff-line--del';
+      frag.append(el('span', cls, line + '\n'));
+    }
+    pre.append(frag);
+    body.append(pre);
+    if (truncated) body.append(el('div', 'git-status-more', 'Diff cut short: it is larger than the viewer shows.'));
+  },
+
+  _gitCommitRow(c) {
+    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
+    const row = el('div', 'git-status-commit');
+    row.append(el('span', 'git-status-hash', c.hash));
+    row.append(el('span', 'git-status-subject', c.subject));
+    const meta = c.time ? `${c.author} · ${this.formatRelativeTime?.(c.time * 1000) ?? ''}` : c.author;
+    row.append(el('span', 'git-status-commit-meta', meta));
+    return row;
+  },
+});

src/web/public/home-sessions.js

@@ -70,17 +70,13 @@ const HOME_SESSIONS_PILL_LABEL = {
   done: 'done',
 };
 
-/** Short backend badge, mirroring `.tab-mode` in the tab strip. */
+/**
+ * Text badge per backend, mirroring the tab strip: only the shell has one. Every
+ * agent CLI (claude included) shows its logo instead, through the same
+ * `run-mode-dot <id>` slot the strip uses (see _buildHomeSessionRow).
+ */
 const HOME_SESSIONS_MODE_BADGE = {
   shell: 'sh',
-  opencode: 'oc',
-  codex: 'cx',
-  gemini: 'gm',
-  antigravity: 'ag',
-  pi: 'pi',
-  grok: 'gk',
-  deepseek: 'ds',
-  omp: 'om',
 };
 
 Object.assign(CodemanApp.prototype, {
@@ -430,6 +426,14 @@ Object.assign(CodemanApp.prototype, {
       badge.setAttribute('data-i18n-skip', '');
       badge.textContent = row.modeBadge;
       line1.appendChild(badge);
+    } else {
+      // The agent's logo: PR #532's slot, the mode id as data (an id with no
+      // logo rule gets the slot's plain dot). CLI Logos on Tabs hides it in CSS
+      // (html[data-tab-logos='off']), exactly as it does on the tab strip.
+      const logo = document.createElement('span');
+      logo.className = `home-sessions-harness run-mode-dot ${row.mode}`;
+      logo.setAttribute('aria-hidden', 'true');
+      line1.appendChild(logo);
     }
     const name = document.createElement('span');
     // .session-name is in the i18n skip list: a session name is user content.

src/web/public/i18n.js

@@ -45,6 +45,15 @@
   // Exact English-source translations. Technical names, command examples, model
   // names, keyboard chords, and user-authored content intentionally stay unchanged.
   const ZH_CN = Object.freeze({
+    'Default Codex model': 'Codex 默认模型',
+    'Default Codex reasoning effort': 'Codex 默认思考强度',
+    'Use Codex configuration': '使用 Codex 配置',
+    'Model ID for new local Codex sessions, including WSL. Leave empty to use Codex configuration.':
+      '新本地 Codex 会话（包括 WSL）使用的模型 ID。留空时使用 Codex 配置。',
+    'Applies to new local sessions; supported levels depend on the model and Codex version. Custom endpoints, Docker and remote sessions keep their own settings.':
+      '应用于新本地会话；可用强度取决于模型和 Codex 版本。自定义端点、Docker 和远程会话保留自己的设置。',
+    'Default Codex model may only contain letters, digits, ".", "_", "-" and "/"':
+      'Codex 默认模型只能包含字母、数字、"."、"_"、"-" 和 "/"',
     'Skip to terminal': '跳转到终端',
     'Go to main page': '返回主页',
     'Session tabs': '会话标签页',
@@ -68,6 +77,24 @@
     'Session Manager': '会话管理器',
     'Session actions': '会话操作',
     Ungrouped: '未分组',
+    'Group actions': '分组操作',
+    'Group name': '分组名称',
+    'Web tab actions': '网页标签操作',
+    'Web tab settings': '网页标签设置',
+    'New group': '新建分组',
+    'Rename group': '重命名分组',
+    'Move group up': '上移分组',
+    'Move group down': '下移分组',
+    'Delete group': '删除分组',
+    'Move up': '上移',
+    'Move down': '下移',
+    'Move to Ungrouped': '移到未分组',
+    'Move to new group': '移到新分组',
+    'Could not save tab groups.': '无法保存标签分组。',
+    'Tab groups changed elsewhere; part of your edit no longer applies.':
+      '标签分组已在别处更改；你的部分编辑已不再适用。',
+    'Tab groups kept changing elsewhere; your edit was not saved.': '标签分组在别处持续更改；你的编辑未保存。',
+    'Your tab group edit was not saved.': '你的标签分组编辑未保存。',
     'Open session manager': '打开会话管理器',
     Attachments: '附件',
     'Open attachment history': '打开附件历史',
@@ -78,6 +105,88 @@
     'Split: close the second session': '分屏：关闭第二个会话',
     'Close split': '关闭分屏',
     'No other sessions to split with': '没有其他可用于分屏的会话',
+    // Tile grid (tile-grid.js, docs/tile-grid-plan.md). 平铺 is the feature (the
+    // button, the setting, the grid), 窗格 one tile in it. Key names stay as
+    // they are; Click / Right-click are mouse actions, Arrows the arrow keys.
+    // Counts, exit codes and durations are patterns in translateDynamic.
+    Tiles: '平铺',
+    Split: '分屏',
+    'Tiled sessions': '平铺的会话',
+    'Tiles: show several sessions side by side (right-click for how many)':
+      '平铺：并排显示多个会话（右键单击可选择窗格数量）',
+    'Tiles: back to a single session (right-click for how many tiles)': '平铺：返回单个会话（右键单击可选择窗格数量）',
+    'How many tiles': '窗格数量',
+    // The Tiles button's hover card (the count and the fits note are patterns).
+    'Click: open the grid': '单击：打开平铺网格',
+    'Click: close the grid': '单击：关闭平铺网格',
+    'Right-click: choose 2, 4 or 6 tiles': '右键单击：选择 2、4 或 6 个窗格',
+    'Shift+F10: the same menu from the keyboard': 'Shift+F10：用键盘打开同一菜单',
+    'Split: unavailable while tiles are open': '分屏：平铺打开时不可用',
+    'Toggle Tile Grid': '切换平铺网格',
+    'Focus Tile Left': '聚焦左侧窗格',
+    'Focus Tile Right': '聚焦右侧窗格',
+    'Focus Tile Up': '聚焦上方窗格',
+    'Focus Tile Down': '聚焦下方窗格',
+    'Focus Tile Left / Right / Up / Down': '聚焦左侧 / 右侧 / 上方 / 下方窗格',
+    'Move Tile Left': '向左移动窗格',
+    'Move Tile Right': '向右移动窗格',
+    'Move Tile Up': '向上移动窗格',
+    'Move Tile Down': '向下移动窗格',
+    'Move Tile Left / Right / Up / Down': '向左 / 右 / 上 / 下移动窗格',
+    Drag: '拖动',
+    "a tile's header": '窗格的标题栏',
+    'Move the Tile (onto Another: Swap)': '移动窗格（拖到另一个窗格上：互换位置）',
+    'Zoom Focused Tile': '放大聚焦的窗格',
+    'Remove Focused Tile': '移除聚焦的窗格',
+    'Add the Session to the Tile Grid': '将该会话加入平铺网格',
+    'Choose How Many Tiles (2, 4 or 6)': '选择窗格数量（2、4 或 6）',
+    'a tab': '标签页',
+    'the Tiles button': '平铺按钮',
+    Click: '单击',
+    'Right-click': '右键单击',
+    Arrows: '方向键',
+    'not bound': '未绑定',
+    'Open group as tiles': '以平铺方式打开分组',
+    'No sessions to show as tiles': '没有可平铺显示的会话',
+    'This group has no session to show as tiles': '此分组没有可平铺显示的会话',
+    'Zoom this tile': '放大此窗格',
+    'Restore the grid': '恢复平铺网格',
+    'Remove tile (the session keeps running)': '移除窗格（会话继续运行）',
+    'Drop a tab or a tile here': '将标签页或窗格拖放到此处',
+    // A file dropped on a tile (tile-grid.js) or the single view (image-input.js).
+    'Only image files are supported': '仅支持图像文件',
+    // Redraw (Ctrl+Shift+R, terminal-ui.js restoreTerminalSize) on the main pane, a tile or Pane B.
+    'No active session': '没有活动会话',
+    'This session is sized by its own window': '此会话的尺寸由它自己的窗口决定',
+    'Terminal not connected: its size is sent when it reconnects': '终端未连接：重新连接后会发送其尺寸',
+    'Could not determine terminal size': '无法确定终端尺寸',
+    'Failed to restore terminal size': '恢复终端尺寸失败',
+    // A tile header's tooltip while tiles can move (with the state above it: a pattern below).
+    'Drag to move the tile': '拖动可移动窗格',
+    'Resize tile columns': '调整窗格列宽',
+    'Resize tile rows': '调整窗格行高',
+    Attach: '附加',
+    'Attaching…': '正在附加…',
+    'Not attached': '未附加',
+    'The session ended': '会话已结束',
+    'The agent exited': '智能体已退出',
+    'It cannot be restarted in place: close it from ⋯ (Close session).': '无法原地重启：请通过 ⋯（关闭会话）关闭它。',
+    'Could not attach the session': '无法附加会话',
+    // The tab's exited-agent badge (app.js applyPaneExitBadge, Ark0N/Codeman#446);
+    // its exit-code forms and the tab's accessible name are patterns.
+    exited: '已退出',
+    // The Run button family (session-ui.js _applyRunMode; "Run CC", "Run SH" ...
+    // are a pattern; mode codes and product names stay), and the toolbar beside it.
+    'Terminal / Shell': '终端 / Shell',
+    'Send Enter': '发送回车',
+    // The Help modal and the shortcut overlay. Key names stay; Wheel is a mouse
+    // input like Click (单击).
+    Tabs: '标签页',
+    'Toggle Session Sidebar': '切换会话侧边栏',
+    'Copy Selection': '复制选中内容',
+    'Copy Selection (interrupts when nothing is selected)': '复制选中内容（无选中内容时中断）',
+    'Focus Tabs': '聚焦标签页',
+    Wheel: '滚轮',
     'Ultracode / Workflow agents': 'Ultracode / Workflow 智能体',
     'Open ultracode workflow agents': '打开 Ultracode 工作流智能体',
     Notifications: '通知',
@@ -122,10 +231,16 @@
     'Run DeepSeek': '运行 DeepSeek',
     'Run OMP': '运行 OMP',
     'Run Shell': '运行 Shell',
+    'More tools': '更多工具',
     'Select AI backend': '选择 AI 后端',
     'Create New Case': '新建案例',
     'Create new case': '新建案例',
     'Link Existing': '关联现有目录',
+    // The toolbar case picker's action rows (session-ui.js CASE_PICKER_ACTIONS),
+    // which replaced the "+" and gear buttons, and its empty state.
+    'New or link a case…': '新建或关联案例…',
+    'Case settings…': '案例设置…',
+    'No cases match': '没有匹配的案例',
     'Add Case': '添加案例',
     'Open sessions': '打开会话',
     'Recent Sessions': '最近会话',
@@ -203,6 +318,7 @@
     Running: '运行中',
     Idle: '空闲',
     Working: '工作中',
+    Waiting: '等待中',
     Today: '今天',
     Home: '主页',
     Local: '本地',
@@ -253,6 +369,56 @@
       '会话列表显示为顶栏横向标签条，或左侧可折叠侧边栏（Alt+B）。完整侧边栏为每个会话显示与主界面相同的详细信息。',
     'Tall Tabs (Name + Folder)': '双行标签（名称 + 文件夹）',
     'Pop-out Button on Tabs': '标签页弹出窗口按钮',
+    'CLI Logos on Tabs': '标签页上的 CLI 图标',
+    "Show each agent's CLI logo before the session name on tabs and the home screen's tab list. Off leaves the status dot and the shell's SH badge. Tiles, split headers and the Run menus keep their logos.":
+      '在标签页和主界面的标签列表中，于会话名称前显示每个智能体的 CLI 图标。关闭后仍保留状态圆点和 Shell 的 SH 标记。平铺、分屏标题栏和运行菜单中的图标不受影响。',
+    // Tab Layout and Header Stats Style (Discussion #426). The header style's
+    // "Tiles" is 磁贴, never 平铺: that is the tile grid's word (the Tiles
+    // button), and "Tiles (label over value)" must not read as the grid.
+    'Tab Layout': '标签页布局',
+    'By state: a row each for needs you, waiting, working and idle. By case: one box per case. Ledger: an aligned column grid. Classic: the single list, as before. By state and By case group the side rail and sidebar too. Alt+1..9 keeps the tab order.':
+      '按状态：需要你、等待中、工作中和空闲各占一行。按案例：每个案例一个框。台账：对齐的列网格。经典：与以前相同的单一列表。按状态和按案例也会为侧边标签栏和侧边栏分组。Alt+1..9 仍按标签页顺序切换。',
+    'By state (rows per state)': '按状态（每种状态一行）',
+    'By case (clusters)': '按案例（分组框）',
+    'Ledger (aligned columns)': '台账（对齐的列）',
+    'Classic (default)': '经典（默认）',
+    'State Order': '状态顺序',
+    'For Tab Layout by state. At the bottom flips the rows, so needs you sits right above the terminal.':
+      '用于按状态的标签页布局。选择在底部会倒转各行，让“需要你”紧挨在终端上方。',
+    'Needs you on top (default)': '“需要你”在顶部（默认）',
+    'Needs you at the bottom': '“需要你”在底部',
+    'Header Stats Style': '顶部栏状态样式',
+    'How WS, CPU, MEM and the plan-usage windows are drawn. Compact puts a ring beside each value in two pills; Tiles put each label over its value with a bar underneath.':
+      'WS、CPU、MEM 和套餐用量窗口的显示方式。紧凑：在两个胶囊中每个数值旁显示一个圆环；磁贴：每个标签位于数值上方，下方带一条进度条。',
+    'As before (bars)': '与以前相同（进度条）',
+    'Compact (default)': '紧凑（默认）',
+    'Tiles (label over value)': '磁贴（标签在数值上方）',
+    // The connection tile's value word in that style (app.js
+    // _connectionTileValueText). Scoped keys on purpose: the bare words also
+    // name other things ("retry" is the orchestrator's Retry button, "LIVE" a
+    // badge in the resume list), and a bare key would translate those too.
+    'Connection tile: live': '已连接',
+    'Connection tile: fallback': '回退',
+    'Connection tile: offline': '离线',
+    'Connection tile: queued': '已排队',
+    'Connection tile: retry': '重连中',
+    // App Settings → Bottom bar, translated as one group (the Git status rows,
+    // #543's two included). Keys are the trimmed label text, without the scope tag.
+    'Bottom bar': '底部栏',
+    'Git status': 'Git 状态',
+    "Shows, at the right of the bottom bar, when the active session's repository (or each repository inside its folder, up to two levels down) has uncommitted files or commits that are not pushed. Click it for the list. Read-only: Codeman never fetches or changes the repository. Not shown for Docker or remote sessions. Off by default.":
+      '在底部栏右侧显示当前会话的仓库（或其文件夹内向下两层以内的每个仓库）是否有未提交的文件或未推送的提交。点击可查看列表。只读：{name} 从不拉取或更改仓库。Docker 和远程会话不显示。默认关闭。',
+    'Git status: group files by folder': 'Git 状态：按文件夹分组显示文件',
+    'In the Git window, show changed files under their folders, collapsed until you click a folder. Off lists every file by its full path. On by default.':
+      '在 Git 窗口中，将更改的文件显示在各自的文件夹下，点击文件夹前保持折叠。关闭时按完整路径列出每个文件。默认开启。',
+    'Git status: max repositories': 'Git 状态：最多仓库数',
+    "When the session's folder holds several projects instead of being one, the Git window lists up to this many (1 to 50, default 12). Each one costs a few git commands per refresh.":
+      '当会话的文件夹包含多个项目（而不是本身就是一个项目）时，Git 窗口最多列出这么多个（1 到 50，默认 12）。每个仓库每次刷新都要运行几条 git 命令。',
+    'Git status: git timeout': 'Git 状态：git 超时',
+    'Seconds one git command may run before that repository is reported as unreadable (5 to 120, default 30). Raise it for repositories on a slow network share.':
+      '单条 git 命令可运行的秒数，超时后该仓库会被报告为无法读取（5 到 120，默认 30）。仓库位于较慢的网络共享上时请调高此值。',
+    'Refresh git status': '刷新 Git 状态',
+    'Close git status': '关闭 Git 状态',
     Panels: '面板',
     Monitor: '监视器',
     'Project Insights': '项目洞察',
@@ -333,7 +499,6 @@
     'Remote Access': '远程访问',
     'Cloudflare Tunnel': 'Cloudflare 隧道',
     'Tunnel URL': '隧道地址',
-    'Upload URL': '上传地址',
     Updates: '更新',
     'Current Version': '当前版本',
     'Check for Updates': '检查更新',
@@ -574,6 +739,13 @@
     'Nothing to copy': '没有可复制的内容',
     // A `#session=<id>` link whose session never appeared (app.js _armUrlSessionWait).
     'Session not found': '未找到会话',
+    // A native host that would not open a window (app.js openInHostWindow); the
+    // "dashboard" is a web tab.
+    'Could not open a new window for this session': '无法在新窗口中打开此会话',
+    'Could not open a new window for this preview': '无法在新窗口中打开此预览',
+    'Could not open a new window for this dashboard': '无法在新窗口中打开此网页标签',
+    // Dictation whose session closed before the text was sent (voice-input.js).
+    'That session has closed; dictation not sent': '该会话已关闭，语音输入未发送',
     // Terminal touch-selection bar (long-press to select). The bar is a sibling of
     // `.xterm`, not a descendant, so SKIP_SELECTOR does not cover it and these apply.
     Copy: '复制',
@@ -735,6 +907,40 @@
     'Wrap lines': '自动换行',
     'Unsaved changes': '未保存的更改',
     Saved: '已保存',
+    'Loading spreadsheet…': '正在加载电子表格…',
+    'This workbook is too large to preview (10 MB limit).': '此工作簿太大，无法预览（上限 10 MB）。',
+    'This workbook has no visible worksheets.': '此工作簿没有可见的工作表。',
+    'This worksheet is empty.': '此工作表为空。',
+    'Some workbook features are not shown': '部分工作簿功能未显示',
+    'Spreadsheet preview timed out.': '电子表格预览超时。',
+    'Spreadsheet preview failed': '电子表格预览失败',
+    'Spreadsheet parser failed.': '电子表格解析器出错。',
+    'Spreadsheet parser failed to start': '电子表格解析器启动失败',
+    'Spreadsheet parser message failed.': '电子表格解析器消息出错。',
+    'Spreadsheet parser message failed': '电子表格解析器消息出错',
+    'Spreadsheet preview is unavailable.': '电子表格预览不可用。',
+    'Spreadsheet preview must use a same-origin URL': '电子表格预览必须使用同源 URL',
+    // Worker refusals, one sentence per error code (spreadsheet-preview.js
+    // WORKER_ERROR_TEXT), and the notice bar's items (renderWarnings). The
+    // counted ones are patterns in translateDynamic below.
+    'This workbook is password-protected or in the old .xls format, so it cannot be previewed.':
+      '此工作簿受密码保护或为旧版 .xls 格式，无法预览。',
+    'This workbook uses ZIP64, which the preview does not support.': '此工作簿使用 ZIP64 格式，预览不支持该格式。',
+    'This workbook is too large or complex to preview.': '此工作簿过大或过于复杂，无法预览。',
+    'This workbook could not be read. The file may be damaged or not a valid .xlsx file.':
+      '无法读取此工作簿。文件可能已损坏，或不是有效的 .xlsx 文件。',
+    // The features the preview leaves out (spreadsheet-preview.js warningText).
+    // Scoped keys on purpose: a bare 'charts' or 'macros' key would also
+    // translate a folder or case of that name (a Helm chart's charts/, a dbt
+    // project's macros/) in the Files panel and the case picker.
+    'Spreadsheet feature: charts': '图表',
+    'Spreadsheet feature: drawings': '绘图',
+    'Spreadsheet feature: pivot tables': '数据透视表',
+    'Spreadsheet feature: external links': '外部链接',
+    'Spreadsheet feature: macros': '宏',
+    'Formula has no cached result': '公式没有缓存的计算结果',
+    'Unsupported cell value': '不支持的单元格值',
+    'Unsupported number format': '不支持的数字格式',
     'Export as JSON': '导出为 JSON',
     'Export as Markdown': '导出为 Markdown',
     'Mark all read': '全部标为已读',
@@ -770,6 +976,22 @@
       '现有项目文件夹的绝对路径，例如 /home/you/my-project',
     'Letters, numbers, hyphens, underscores only. Created in ~/codeman-cases/':
       '仅允许字母、数字、连字符和下划线；将在 ~/codeman-cases/ 中创建。',
+    'Letters, numbers, hyphens, underscores only. Created inside the parent folder below.':
+      '仅允许字母、数字、连字符和下划线；将在下方的父文件夹中创建。',
+    'A fresh workspace under ~/codeman-cases, scaffolded with its own CLAUDE.md.':
+      '在 ~/codeman-cases 下新建工作区，并生成独立的 CLAUDE.md。',
+    'A fresh workspace in a folder you choose, scaffolded with its own CLAUDE.md.':
+      '在你选择的文件夹中新建工作区，并生成独立的 CLAUDE.md。',
+    'Create in a custom folder': '在自定义文件夹中创建',
+    '📁 Create in a custom folder': '📁 在自定义文件夹中创建',
+    'By default a new case is created under ~/codeman-cases. Choose another folder and the case is created there instead; it is listed like any other case.':
+      '新案例默认创建在 ~/codeman-cases 下。选择其他文件夹后，案例会改为创建在那里，并像其他案例一样列出。',
+    'Parent Folder': '父文件夹',
+    'Pick the folder the new case folder should be created inside.': '选择要在其中创建新案例文件夹的文件夹。',
+    'Choose the folder to create the case in': '选择要在其中创建案例的文件夹',
+    'Not available for a Docker case': 'Docker 案例不可用',
+    'Not available with a custom folder': '使用自定义文件夹时不可用',
+    'Browse…': '浏览…',
     'Docker exports': 'Docker 导出',
     'No exports yet. Export a docker case from its tab.': '暂无导出；请从 Docker 案例标签页导出。',
     'Runs inside an isolated container. Multiple sessions can share the same container.':
@@ -917,6 +1139,17 @@
     return value.replace(/\{([a-zA-Z][\w]*)\}/g, (_match, key) => String(variables[key] ?? ''));
   }
 
+  // The six-state words of a tile header's tooltip (tile-grid.js _paintTileHandle).
+  const TILE_STATE_ZH = {
+    'needs you': '需要你',
+    error: '错误',
+    waiting: '等待中',
+    working: '工作中',
+    idle: '空闲',
+    done: '已完成',
+    exited: '已退出',
+  };
+
   function translateDynamic(source) {
     const patterns = [
       [/^(\d+) tokens?$/, (_m, count) => `${count} 个 Token`],
@@ -934,6 +1167,83 @@
       [/^Update available: v(.+)$/, (_m, version) => `有可用更新：v${version}`],
       [/^Selected: (.+)$/, (_m, value) => `已选择：${value}`],
       [/^Failed to (.+)$/, (_m, action) => `操作失败：${action}`],
+      [/^Will create: (.+)$/, (_m, path) => `将创建：${path}`],
+      // The spreadsheet preview: an HTTP status, and the notice bar's counts.
+      [/^Spreadsheet preview failed \((\d+)\)$/, (_m, status) => `电子表格预览失败（${status}）`],
+      [/^Terminal restored to (\d+)x(\d+)$/, (_m, cols, rows) => `终端已恢复为 ${cols}x${rows}`],
+      [/^View truncated to the first (\d+) cells$/, (_m, n) => `视图仅显示前 ${n} 个单元格`],
+      [/^(\d+) unsupported number formats$/, (_m, n) => `${n} 种不支持的数字格式`],
+      // Group names are user text: they pass through untranslated.
+      [/^Move to "(.+)"$/, (_m, group) => `移到“${group}”`],
+      [
+        /^Delete group "(.+)"\? Its tabs move to Ungrouped\.$/,
+        (_m, group) => `删除分组“${group}”？其中的标签将移到未分组。`,
+      ],
+      // Tile grid: counts, exit codes and durations pass through.
+      [/^(\d+) tiles$/, (_m, n) => `${n} 个窗格`],
+      [/^Tiles \u00B7 (\d+)$/, (_m, n) => `平铺 · ${n}`],
+      [
+        /^This window fits (\d+) tiles?: a click opens (\d+)$/,
+        (_m, n, m) => `此窗口可容纳 ${n} 个窗格：单击将打开 ${m} 个`,
+      ],
+      [/^This window fits (\d+) tiles?$/, (_m, n) => `此窗口可容纳 ${n} 个窗格`],
+      [/^The grid holds at most (\d+) tiles$/, (_m, n) => `平铺网格最多容纳 ${n} 个窗格`],
+      [
+        /^The grid already holds what this window fits \((\d+)\)$/,
+        (_m, n) => `平铺网格已达到此窗口可容纳的数量（${n}）`,
+      ],
+      [
+        /^The grid holds at most (\d+) tiles: the new session opens on its own$/,
+        (_m, n) => `平铺网格最多容纳 ${n} 个窗格：新会话将单独打开`,
+      ],
+      [
+        /^The grid already holds what this window fits \((\d+)\): the new session opens on its own$/,
+        (_m, n) => `平铺网格已达到此窗口可容纳的数量（${n}）：新会话将单独打开`,
+      ],
+      [
+        /^The window is too small for (\d+) tiles: showing the focused one$/,
+        (_m, n) => `窗口太小，容纳不下 ${n} 个窗格：只显示聚焦的窗格`,
+      ],
+      [/^The agent exited \((-?\d+)\)$/, (_m, code) => `智能体已退出（${code}）`],
+      [/^The agent exited \(signal (\d+)\)$/, (_m, signal) => `智能体已退出（信号 ${signal}）`],
+      // A session header's harness logo (tile grid, split pane): "<harness> · <model>",
+      // and where the model came from when the CLI did not report it. The harness
+      // and model names pass through untranslated.
+      [/^(.+) \(set at launch\)$/, (_m, names) => `${names}（启动时设定）`],
+      [/^(.+) \(custom endpoint\)$/, (_m, names) => `${names}（自定义端点）`],
+      [/^(.+) \(from config\)$/, (_m, names) => `${names}（来自配置）`],
+      // The Run button's mode codes ("Run CC", "Run SH", "Run OC" ...; a registry
+      // CLI's shortBadge too). Exact entries win first ("Run Shell", "Run OMP").
+      [/^Run ([A-Z][A-Z0-9]{1,5})$/, (_m, code) => `运行 ${code}`],
+      // The tab's exited-agent badge, and the tab's accessible name carrying it.
+      // The session name is user text: it passes through untranslated.
+      [/^exited \((-?\d+)\)$/, (_m, code) => `已退出（${code}）`],
+      [/^exited \(signal (\d+)\)$/, (_m, signal) => `已退出（信号 ${signal}）`],
+      [
+        /^(.+) session, agent exited \(signal (\d+)\)$/,
+        (_m, name, signal) => `${name} 会话，智能体已退出（信号 ${signal}）`,
+      ],
+      [/^(.+) session, agent exited \((-?\d+)\)$/, (_m, name, code) => `${name} 会话，智能体已退出（${code}）`],
+      [/^(.+) session, agent exited$/, (_m, name) => `${name} 会话，智能体已退出`],
+      // A session name is user text: it passes through untranslated.
+      [
+        /^(.+) was stopped after crashing repeatedly\. Restart it\?$/,
+        (_m, name) => `${name} 因反复崩溃已被停止。要重启吗？`,
+      ],
+      // A tile header's tooltip: a state and how long ("idle 3m"). The duration
+      // is required: bare state words stay out of the table, they collide with
+      // state strings on other surfaces (see mobile-overview.js).
+      [
+        /^(needs you|error|waiting|working|idle|done|exited) (<1m|\d+[dhm](?: \d+[hm])?)$/,
+        (_m, state, duration) => `${TILE_STATE_ZH[state]} ${duration}`,
+      ],
+      // The same while tiles can move, with the drag hint on a second line.
+      // Anchored on the hint, so a bare state word is safe here.
+      [
+        /^(needs you|error|waiting|working|idle|done|exited)(?: (<1m|\d+[dhm](?: \d+[hm])?))?\nDrag to move the tile$/,
+        (_m, state, duration) =>
+          `${TILE_STATE_ZH[state]}${duration ? ` ${duration}` : ''}\n${ZH_CN['Drag to move the tile']}`,
+      ],
     ];
     for (const [pattern, replacement] of patterns) {
       const match = source.match(pattern);
@@ -992,6 +1302,23 @@
     return !element || Boolean(element.closest(SKIP_SELECTOR));
   }
 
+  // xterm's DOM renderer rewrites its rows (`.xterm-rows > div`) on every frame
+  // a pane changes: thousands of mutation records a second with a grid of tiles,
+  // each paying a closest() over the whole skip list. All rows of one terminal
+  // share that parent, so its own shouldSkip() verdict is kept once it says
+  // skip; a skip verdict cannot lapse, since xterm keeps `.xterm-rows` inside
+  // its `.xterm`. A rows container that is not skipped is never kept: its rows
+  // go through the full check below like any other node.
+  const skippedRows = new WeakSet();
+  function isSkippedRow(node) {
+    const rows = node.parentNode;
+    if (!rows?.classList?.contains('xterm-rows')) return false;
+    if (skippedRows.has(rows)) return true;
+    if (!shouldSkip(rows)) return false;
+    skippedRows.add(rows);
+    return true;
+  }
+
   function shouldSkipText(node) {
     const element = node.nodeType === Node.ELEMENT_NODE ? node : node.parentElement;
     return shouldSkip(node) || Boolean(element?.closest(USER_TEXT_SELECTOR));
@@ -1087,6 +1414,13 @@
     observer = new MutationObserver((mutations) => {
       if (applying) return;
       for (const mutation of mutations) {
+        // A change inside a skipped surface cannot need translating: every
+        // node it adds or edits sits under the same skip ancestor, so both
+        // translators would return on their own closest() check anyway. One
+        // check per record instead of one per text node and attribute matters
+        // for xterm's DOM renderer, which replaces rows every frame (the split
+        // pane, every tile of the grid).
+        if (isSkippedRow(mutation.target) || shouldSkip(mutation.target)) continue;
         if (mutation.type === 'characterData') translateNode(mutation.target);
         if (mutation.type === 'attributes') translateAttributes(mutation.target);
         for (const added of mutation.addedNodes) translateNode(added);

src/web/public/image-input.js

@@ -50,8 +50,13 @@ Object.assign(CodemanApp.prototype, {
   // Called from customKeyEventHandler in terminal-ui.js on Ctrl+V keydown.
   // Creates a hidden paste trap, lets the browser paste into it, then inspects
   // the result for images. Works on plain HTTP (no Clipboard API needed).
-  _handleImagePaste() {
+  // `target` names the terminal the Ctrl+V came from and its session; both
+  // default to the primary pane. A second terminal (the split pane) passes its
+  // own, so text pastes into THAT xterm and images upload to THAT session.
+  _handleImagePaste(target = {}) {
     const self = this;
+    const terminal = target.terminal || this.terminal;
+    const sessionId = target.sessionId || this.activeSessionId;
 
     // Create a hidden contenteditable div to receive the paste
     const trap = document.createElement('div');
@@ -93,11 +98,11 @@ Object.assign(CodemanApp.prototype, {
       setTimeout(function() {
         if (trap.parentNode) trap.parentNode.removeChild(trap);
         // Refocus the terminal
-        if (self.terminal) self.terminal.focus();
+        if (terminal) terminal.focus();
       }, 0);
 
       if (imageFiles.length > 0) {
-        self._uploadAndInsertImages(imageFiles);
+        self._uploadAndInsertImages(imageFiles, { sessionId: sessionId });
       } else {
         // No image -- route text through xterm's paste() so bracketed-paste
         // markers (CSI 200~ ... CSI 201~) survive when the inner application
@@ -106,7 +111,7 @@ Object.assign(CodemanApp.prototype, {
         // indistinguishable from typed input, weakening the CLI's
         // prompt-injection defenses.
         var text = e.clipboardData ? e.clipboardData.getData('text/plain') : '';
-        if (text && self.terminal) self.terminal.paste(text);
+        if (text && terminal) terminal.paste(text);
       }
     });
 
@@ -126,9 +131,10 @@ Object.assign(CodemanApp.prototype, {
 
   /** Upload a batch and normally insert its paths into the active terminal.
    *  The prompt composer passes `{ insert: false }` so it can put those paths
-   *  into its textarea instead. Returns successful paths in selection order. */
+   *  into its textarea instead. `options.sessionId` names the session to upload
+   *  to (default: the active one). Returns successful paths in selection order. */
   async _uploadAndInsertImages(fileList, options = {}) {
-    const sessionId = this.activeSessionId;
+    const sessionId = options.sessionId || this.activeSessionId;
     if (!sessionId) return [];
 
     let files = Array.from(fileList || []);
@@ -179,8 +185,12 @@ Object.assign(CodemanApp.prototype, {
 
     const paths = results.filter(Boolean);
     if (paths.length > 0 && options.insert !== false) {
-      // Insert all paths in one shot, space-separated, in selection order.
-      await this.sendInput(paths.join(' '));
+      // Insert all paths in one shot, space-separated, in selection order, into
+      // the session the batch was uploaded TO. Not sendInput(): it re-reads
+      // activeSessionId, and after the awaits above that is whatever tab the
+      // user switched to mid-upload, so the paths landed in the wrong session.
+      // Same delivery sendInput() uses (durable queue, useMux for the POST path).
+      this._sendInputAsync(sessionId, paths.join(' '), { useMux: true });
     }
 
     // Final status: successes, plus any failures / cap so nothing is silent.

src/web/public/index.html

@@ -65,7 +65,7 @@
        app.js, NOT the handheld storage-key test `m`. Use a different predicate
        here and boot will contradict this value, animating the drawer open by
        itself on every load between 768 and 1023px. -->
-  <script>try{var m=window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024);var k=m?'codeman-app-settings-mobile':'codeman-app-settings';var A=JSON.parse(localStorage.getItem(k)||'{}');var L=A.sessionListLayout;var F=Number(A.sessionSidebarFontSize);var solo=/^\/session\//.test(location.pathname);var C=localStorage.getItem('codeman-sidebar-collapsed');var S=(L==='sidebar'||L==='sidebar-rich')&&!solo;document.documentElement.dataset.sessionList=S?'sidebar':'header';document.documentElement.dataset.sidebarDetail=(S&&L==='sidebar-rich')?'rich':'simple';document.documentElement.dataset.sidebar=(C===null?window.innerWidth<1024:C==='1')?'collapsed':'expanded';var V=A.tabOrientation==='vertical'&&!S&&!solo&&window.innerWidth>=768;document.documentElement.dataset.tabOrientation=V?'vertical':'horizontal';document.documentElement.dataset.tabRailDetail=(A.tabRailDetail==='simple')?'simple':'rich';document.documentElement.dataset.tabRailSort=(A.tabRailSort==='manual')?'manual':'activity';var W=Number(A.tabRailWidth);if(V){if(Number.isInteger(W)&&W>=208&&W<=360)document.documentElement.style.setProperty('--tab-rail-width',W+'px');else if(document.documentElement.dataset.tabRailDetail!=='simple')document.documentElement.style.setProperty('--tab-rail-width','320px');}if(Number.isInteger(F)&&F>=11&&F<=18)document.documentElement.style.setProperty('--session-sidebar-name-font-size',F+'px');}catch(e){document.documentElement.dataset.sessionList='header';document.documentElement.dataset.sidebarDetail='simple';document.documentElement.dataset.sidebar='expanded';document.documentElement.dataset.tabOrientation='horizontal';document.documentElement.dataset.tabRailDetail='rich';document.documentElement.dataset.tabRailSort='activity';}</script>
+  <script>try{var m=window.innerWidth<768||(('ontouchstart' in window||navigator.maxTouchPoints>0)&&window.innerWidth<1024);var k=m?'codeman-app-settings-mobile':'codeman-app-settings';var A=JSON.parse(localStorage.getItem(k)||'{}');var L=A.sessionListLayout;var F=Number(A.sessionSidebarFontSize);var solo=/^\/session\//.test(location.pathname);var C=localStorage.getItem('codeman-sidebar-collapsed');var S=(L==='sidebar'||L==='sidebar-rich')&&!solo;document.documentElement.dataset.sessionList=S?'sidebar':'header';document.documentElement.dataset.sidebarDetail=(S&&L==='sidebar-rich')?'rich':'simple';document.documentElement.dataset.sidebar=(C===null?window.innerWidth<1024:C==='1')?'collapsed':'expanded';var V=A.tabOrientation==='vertical'&&!S&&!solo&&window.innerWidth>=768;document.documentElement.dataset.tabOrientation=V?'vertical':'horizontal';document.documentElement.dataset.tabRailDetail=(A.tabRailDetail==='simple')?'simple':'rich';document.documentElement.dataset.tabRailSort=(A.tabRailSort==='manual')?'manual':'activity';var T=A.tabArrangement;document.documentElement.dataset.tabArrangement=(T==='state'||T==='case'||T==='ledger')?T:'classic';document.documentElement.dataset.tabStateOrder=(A.tabStateOrder==='urgent-last')?'urgent-last':'urgent-first';document.documentElement.dataset.tabLogos=(A.showTabCliLogos===false)?'off':'on';var H=A.headerStatsStyle;document.documentElement.dataset.headerStats=(window.innerWidth<768||solo)?'classic':(H==='classic'||H==='tiles')?H:'compact';var W=Number(A.tabRailWidth);if(V){if(Number.isInteger(W)&&W>=208&&W<=360)document.documentElement.style.setProperty('--tab-rail-width',W+'px');else if(document.documentElement.dataset.tabRailDetail!=='simple')document.documentElement.style.setProperty('--tab-rail-width','320px');}if(Number.isInteger(F)&&F>=11&&F<=18)document.documentElement.style.setProperty('--session-sidebar-name-font-size',F+'px');}catch(e){document.documentElement.dataset.sessionList='header';document.documentElement.dataset.sidebarDetail='simple';document.documentElement.dataset.sidebar='expanded';document.documentElement.dataset.tabOrientation='horizontal';document.documentElement.dataset.tabRailDetail='rich';document.documentElement.dataset.tabRailSort='activity';document.documentElement.dataset.tabArrangement='classic';document.documentElement.dataset.tabStateOrder='urgent-first';document.documentElement.dataset.headerStats='classic';document.documentElement.dataset.tabLogos='on';}</script>
   <!-- Inline critical CSS for instant skeleton paint (before styles.css loads) -->
   <style>
     .loading-skeleton{display:flex;flex-direction:column;height:100vh;height:100dvh;background:var(--bg-dark,#11151c)}
@@ -147,13 +147,14 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
           <span>Admin Panel</span>
         </button>
-        <button class="btn-icon-header btn-solo-redock" id="soloRedockBtn" style="display: none;" onclick="window.close()" title="Re-dock to dashboard (close window)" aria-label="Re-dock session to dashboard">&#x229E;</button>
+        <button class="btn-icon-header btn-solo-redock" id="soloRedockBtn" style="display: none;" onclick="app._closeSoloWindow()" title="Re-dock to dashboard (close window)" aria-label="Re-dock session to dashboard">&#x229E;</button>
         <button class="tunnel-indicator" id="tunnelIndicator" style="display: none;" onclick="app.toggleTunnelPanel()" title="Cloudflare Tunnel" aria-label="Tunnel status">
           <span class="tunnel-dot"></span>
         </button>
         <div class="connection-indicator" id="connectionIndicator" style="display: none;">
           <span class="connection-dot" id="connectionDot"></span>
           <span class="connection-text" id="connectionText"></span>
+          <span class="connection-tile"><span class="connection-tile-label" id="connectionTileLabel"></span><span class="connection-tile-value" id="connectionTileValue" data-i18n-skip></span></span>
         </div>
         <div class="header-font-controls">
           <button class="btn-icon-header btn-sm" onclick="app.decreaseFontSize()" title="Decrease font (Ctrl+-)" aria-label="Decrease font size">A-</button>
@@ -162,6 +163,7 @@
         </div>
         <div class="header-system-stats" id="headerSystemStats" title="System resource usage">
           <div class="stat-item">
+            <span class="stat-ring" id="statCpuRing" aria-hidden="true"></span>
             <span class="stat-label">CPU</span>
             <div class="stat-bar">
               <div class="stat-bar-fill stat-bar-cpu" id="statCpuBar"></div>
@@ -169,6 +171,7 @@
             <span class="stat-value" id="statCpu">--%</span>
           </div>
           <div class="stat-item">
+            <span class="stat-ring" id="statMemRing" aria-hidden="true"></span>
             <span class="stat-label">MEM</span>
             <div class="stat-bar">
               <div class="stat-bar-fill stat-bar-mem" id="statMemBar"></div>
@@ -189,9 +192,10 @@
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
           <span class="attachment-history-badge" id="attachmentHistoryBadge" style="display:none;">0</span>
         </button>
-        <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
+        <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path class="icon-folder-closed" d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><g class="icon-folder-open"><path d="M3 17V7a2 2 0 0 1 2-2h4l2 2h6a2 2 0 0 1 2 2v1.5"/><path d="M3 17l2.3-5.4A2 2 0 0 1 7.2 10.5H20a1.5 1.5 0 0 1 1.4 2l-1.9 5.2A2 2 0 0 1 17.6 19H5a2 2 0 0 1-2-2z"/></g></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
         <button class="btn-icon-header btn-split btn-split--hidden" onclick="app.openSplitPicker(event)" title="Split: open a second session beside this one" aria-label="Split: open a second session beside this one" aria-pressed="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg></button>
+        <button class="btn-icon-header btn-tile-grid btn-tile-grid--hidden" onclick="app.toggleTileGrid()" oncontextmenu="app.openTileCountMenu(event)" aria-describedby="tileGridHint" aria-label="Tiles: show several sessions side by side (right-click for how many)" aria-pressed="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="8" height="8" rx="1"/><rect x="13" y="3" width="8" height="8" rx="1"/><rect x="3" y="13" width="8" height="8" rx="1"/><rect x="13" y="13" width="8" height="8" rx="1"/></svg></button>
         <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
         <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude and Codex plan usage limits">—</div>
         <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
@@ -435,6 +439,12 @@
           autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
       </div>
 
+      <!-- Tile grid (tile-grid.js): 1 to 6 sessions side by side, each a
+           TerminalTile. A SIBLING of .terminal-wrap, never a parent: while
+           .main.tiles-active is set the main terminal is parked (hidden) and
+           this section takes its place. -->
+      <section class="tile-grid" id="tileGrid" aria-label="Tiled sessions"></section>
+
       <!-- Web tab layer: one iframe per open dashboard, shown in place of the
            terminal while a web tab is active. Frames stay mounted while hidden so
            switching tabs does not reload (and re-authenticate) a dashboard. -->
@@ -450,9 +460,14 @@
         <div class="welcome-content">
           <h1 class="welcome-title">Codeman</h1>
           <p class="welcome-desc">Manage AI Coding tools in persistent tmux sessions.</p>
+          <!-- Launchers (settings-ui.js renderWelcomeCliActions): one primary
+               button for the first agent in the registry catalog, then a chip
+               row for every other enabled CLI. The tunnel is not a launcher, so
+               it sits under them as a quiet link; settings-ui.js rewrites its
+               contents on every state change and owns its inline display. -->
           <div class="welcome-actions">
             <div class="welcome-cli-actions" id="welcomeCliActions"></div>
-            <button class="welcome-btn welcome-btn-tunnel" id="welcomeTunnelBtn" style="display: none;" onclick="app.toggleTunnelFromWelcome()">
+            <button type="button" class="welcome-tunnel-link" id="welcomeTunnelBtn" style="display: none;" onclick="app.toggleTunnelFromWelcome()">
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>
               Cloudflare Tunnel
             </button>
@@ -567,6 +582,19 @@
       <div class="file-browser-status" id="fileBrowserStatus"></div>
     </div>
 
+    <!-- Git status panel (git-status-ui.js): what the active session's repo has not committed or pushed. -->
+    <div class="git-status-panel" id="gitStatusPanel" role="dialog" aria-label="Git status">
+      <div class="git-status-header">
+        <span class="git-status-title">Git <span class="git-status-branch" id="gitStatusBranch" data-i18n-skip></span></span>
+        <div class="git-status-actions">
+          <button class="btn-icon-sm" onclick="app.refreshGitStatusNow()" title="Refresh" aria-label="Refresh git status">&#x21BB;</button>
+          <button class="btn-icon-sm" onclick="app.closeGitStatusPanel()" title="Close" aria-label="Close git status">&times;</button>
+        </div>
+      </div>
+      <div class="git-status-body" id="gitStatusBody" data-i18n-skip></div>
+      <div class="git-status-footer" id="gitStatusFooter" data-i18n-skip></div>
+    </div>
+
     <!-- File Preview Overlay -->
     <div class="file-preview-overlay" id="filePreviewOverlay">
       <div class="file-preview-window">
@@ -677,11 +705,9 @@
           <button class="btn-toolbar btn-enter" onclick="app.sendEnterKey()" title="Send Enter">
             Enter
           </button>
-          <div class="tab-count-group" title="Instance count">
-            <button class="tab-count-btn" onclick="app.decrementShellCount()">−</button>
-            <input type="number" id="shellCount" class="tab-count-input" value="1" min="1" max="20" readonly>
-            <button class="tab-count-btn" onclick="app.incrementShellCount()">+</button>
-          </div>
+          <!-- Run Shell had a second, identical instance-count stepper here. The
+               toolbar carried two of them side by side, so it is gone and Run
+               Shell reads the one above (#tabCount) like the Run button does. -->
           <div class="case-select-group">
             <div class="case-combobox" id="quickStartCasePicker">
               <input
@@ -701,8 +727,9 @@
             <select id="quickStartCase" class="toolbar-select case-native-select" title="Select case" aria-hidden="true" tabindex="-1">
               <option value="testcase">testcase</option>
             </select>
-            <button class="btn-case-add" onclick="app.showCreateCaseModal()" title="Create new case">+</button>
-            <button class="btn-case-settings" onclick="app.toggleCaseSettings()" title="Case settings">&#x2699;</button>
+            <!-- "New or link a case…" and "Case settings…" are the last two rows of
+                 the case picker's own list (CASE_PICKER_ACTIONS, session-ui.js); the
+                 "+" and gear buttons that sat here were removed (owner, 1.36.0). -->
             <div class="case-settings-popover hidden" id="caseSettingsPopover">
               <label class="checkbox-inline">
                 <input type="checkbox" id="caseAgentTeams" onchange="app.onCaseSettingChanged()">
@@ -771,6 +798,13 @@
         <!-- Orchestrator button hidden until feature is ready -->
         <!-- <button class="btn-toolbar btn-sm" onclick="app.toggleOrchestratorPanel()" title="Orchestrator Loop">&#x2699; Orchestrator</button> -->
         <button class="btn-toolbar btn-sm btn-cron btn-cron--hidden" onclick="app.openCron()" title="Cron Jobs">&#x23F0; Cron</button>
+        <!-- Git status of the active session's repository (git-status-ui.js). Optional and per-device
+             (App Settings → Header & Panels → Bottom bar, default OFF), so it is hidden until that
+             setting is on AND the session is a local git repository. -->
+        <button type="button" class="btn-toolbar btn-sm btn-git-status" id="gitStatusBtn" hidden aria-expanded="false" aria-controls="gitStatusPanel" onclick="app.toggleGitStatusPanel()">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="8" r="2.5"/><path d="M6 8.5v7"/><path d="M18 10.5c0 4-6 3-11 6"/></svg>
+          <span class="git-status-label" data-i18n-skip></span>
+        </button>
         <span class="version-display" id="versionDisplay" title="Codeman version">v0.0.0</span>
       </div>
     </footer>
@@ -787,7 +821,6 @@
           <section class="shortcut-section">
             <h4>Session</h4>
             <div class="shortcuts-grid">
-              <div><kbd>Ctrl</kbd>+<kbd>W</kbd></div><div>Close Session</div>
               <div><kbd>Ctrl/Cmd/Option</kbd>+<kbd>K</kbd></div><div>Find Open Session</div>
               <div><kbd>Ctrl</kbd>+<kbd>Tab</kbd></div><div>Next Session</div>
               <div><kbd>Alt/Option</kbd>+<kbd>[</kbd> / <kbd>Alt/Option</kbd>+<kbd>]</kbd></div><div>Previous / Next Session</div>
@@ -802,11 +835,23 @@
               <div><kbd>Ctrl</kbd>+<kbd>}</kbd></div><div>Move Active Tab Right</div>
               <div><kbd>ArrowLeft</kbd> / <kbd>ArrowUp</kbd></div><div>Focus Previous Tab</div>
               <div><kbd>ArrowRight</kbd> / <kbd>ArrowDown</kbd></div><div>Focus Next Tab</div>
-              <div><kbd>Home</kbd></div><div>Focus First Tab</div>
+              <div><kbd data-i18n-skip>Home</kbd></div><div>Focus First Tab</div>
               <div><kbd>End</kbd></div><div>Focus Last Tab</div>
               <div><kbd>Enter</kbd> / <kbd>Space</kbd></div><div>Activate Focused Tab</div>
             </div>
           </section>
+          <section class="shortcut-section">
+            <h4>Tiles</h4>
+            <div class="shortcuts-grid">
+              <div><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd></div><div>Toggle Tile Grid</div>
+              <div><kbd>Alt/Option</kbd>+<kbd>Shift</kbd>+<kbd>Arrows</kbd></div><div>Focus Tile Left / Right / Up / Down</div>
+              <div><kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Arrows</kbd></div><div>Move Tile Left / Right / Up / Down</div>
+              <div><kbd>Drag</kbd> a tile's header</div><div>Move the Tile (onto Another: Swap)</div>
+              <div><kbd>Alt/Option</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd></div><div>Zoom Focused Tile</div>
+              <div><kbd>Ctrl/Cmd</kbd>+<kbd>Click</kbd> a tab</div><div>Add the Session to the Tile Grid</div>
+              <div><kbd>Right-click</kbd> the Tiles button</div><div>Choose How Many Tiles (2, 4 or 6)</div>
+            </div>
+          </section>
           <section class="shortcut-section">
             <h4>Terminal</h4>
             <div class="shortcuts-grid">
@@ -1884,7 +1929,7 @@
                 <div class="set-group-head"><h4>Header buttons</h4><span class="set-scope">device</span></div>
                 <p class="set-group-hint">Tap to show a control in the header. Multi-monitor is the one entry here that syncs across devices.</p>
                 <div class="set-group-body">
-                  <div class="set-chips" data-search="header buttons plan usage font stats lifecycle response file viewer attachments monitor session away cron redraw">
+                  <div class="set-chips" data-search="header buttons plan usage font stats lifecycle response file viewer attachments monitor session away cron redraw split tiles">
                     <label class="set-chip" data-preview="header" data-preview-order="1" data-preview-text="A+"><input type="checkbox" id="appSettingsShowFontControls"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 20 10 5l6 15"/><path d="M6.5 15h7"/><path d="M18 12h4M20 10v4"/></svg><span>Font Size</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="2" data-preview-text="CPU 12%"><input type="checkbox" id="appSettingsShowSystemStats" checked><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 12h4l2.5-7 4 14L16 12h5"/></svg><span>System Stats</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="3"><input type="checkbox" id="appSettingsShowRedrawButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="1 4 1 10 7 10"/><polyline points="23 20 23 14 17 14"/><path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15"/></svg><span>Redraw Terminal</span></label>
@@ -1894,10 +1939,22 @@
                     <label class="set-chip" data-preview="header" data-preview-order="9"><input type="checkbox" id="appSettingsShowAttachmentsButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg><span>Attachments</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="10"><input type="checkbox" id="appSettingsShowFileViewerButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg><span>File Viewer</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="11"><input type="checkbox" id="appSettingsShowMultiMonitorButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg><span>Multi-monitor</span></label>
-                    <label class="set-chip" data-preview="header" data-preview-order="11.5"><input type="checkbox" id="appSettingsShowSplitButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg><span>Split</span></label>
+                    <label class="set-chip" data-search="split pane side by side two sessions" data-preview="header" data-preview-order="11.5"><input type="checkbox" id="appSettingsShowSplitButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg><span>Split</span></label>
+                    <label class="set-chip" data-search="tiles tile grid side by side several sessions" data-preview="header" data-preview-order="11.6"><input type="checkbox" id="appSettingsShowTileGridButton"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="8" height="8" rx="1"/><rect x="13" y="3" width="8" height="8" rx="1"/><rect x="3" y="13" width="8" height="8" rx="1"/><rect x="13" y="13" width="8" height="8" rx="1"/></svg><span>Tiles</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="13" data-preview-text="42%"><input type="checkbox" id="appSettingsShowPlanUsageLimits"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 18a8 8 0 1 1 16 0"/><path d="M12 18l4.5-5"/></svg><span>Plan Usage</span></label>
                     <label class="set-chip" data-preview="header" data-preview-order="14"><input type="checkbox" id="appSettingsShowLifecycleLog"><svg class="set-chip-ico" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/></svg><span>Lifecycle Log</span></label>
                   </div>
+                  <div class="set-row has-field" data-search="header stats style system cpu mem ws plan usage tiles compact rings">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Header Stats Style <span class="set-tag">desktop</span></span>
+                      <span class="set-row-desc">How WS, CPU, MEM and the plan-usage windows are drawn. Compact puts a ring beside each value in two pills; Tiles put each label over its value with a bar underneath.</span>
+                    </div>
+                    <select id="appSettingsHeaderStatsStyle" class="set-select">
+                      <option value="classic">As before (bars)</option>
+                      <option value="compact">Compact (default)</option>
+                      <option value="tiles">Tiles (label over value)</option>
+                    </select>
+                  </div>
                 </div>
               </div>
 
@@ -1935,6 +1992,40 @@
                 </div>
               </div>
 
+              <div class="set-group">
+                <div class="set-group-head"><h4>Bottom bar</h4></div>
+                <div class="set-group-body">
+                  <div class="set-row" data-search="git status uncommitted unpushed commit push indicator bottom bar toolbar">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Git status <span class="set-scope">device</span></span>
+                      <span class="set-row-desc">Shows, at the right of the bottom bar, when the active session's repository (or each repository inside its folder, up to two levels down) has uncommitted files or commits that are not pushed. Click it for the list. Read-only: Codeman never fetches or changes the repository. Not shown for Docker or remote sessions. Off by default.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsShowGitStatus"><span class="slider"></span></label>
+                  </div>
+                  <div class="set-row" data-search="git status folders tree flat list collapsed expand files">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Git status: group files by folder <span class="set-scope">device</span></span>
+                      <span class="set-row-desc">In the Git window, show changed files under their folders, collapsed until you click a folder. Off lists every file by its full path. On by default.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsGitStatusTree" checked><span class="slider"></span></label>
+                  </div>
+                  <div class="set-row" data-search="git status maximum repositories folder many repos limit">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Git status: max repositories <span class="set-scope">device</span></span>
+                      <span class="set-row-desc">When the session's folder holds several projects instead of being one, the Git window lists up to this many (1 to 50, default 12). Each one costs a few git commands per refresh.</span>
+                    </div>
+                    <input type="number" id="appSettingsGitStatusMaxRepos" class="set-num" value="12" min="1" max="50" step="1">
+                  </div>
+                  <div class="set-row" data-search="git status timeout seconds slow share network">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Git status: git timeout <span class="set-scope">device</span></span>
+                      <span class="set-row-desc">Seconds one git command may run before that repository is reported as unreadable (5 to 120, default 30). Raise it for repositories on a slow network share.</span>
+                    </div>
+                    <input type="number" id="appSettingsGitStatusTimeout" class="set-num" value="30" min="5" max="120" step="1">
+                  </div>
+                </div>
+              </div>
+
               <div class="set-group">
                 <div class="set-group-head"><h4>Subagent windows</h4></div>
                 <div class="set-group-body">
@@ -2030,6 +2121,28 @@
               <div class="set-group">
                 <div class="set-group-head"><h4>Tabs</h4><span class="set-scope">device</span></div>
                 <div class="set-group-body">
+                  <div class="set-row has-field" data-search="tab layout grouping group by state triage needs you waiting working idle case clusters ledger columns classic old new">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Tab Layout</span>
+                      <span class="set-row-desc">By state: a row each for needs you, waiting, working and idle. By case: one box per case. Ledger: an aligned column grid. Classic: the single list, as before. By state and By case group the side rail and sidebar too. Alt+1..9 keeps the tab order.</span>
+                    </div>
+                    <select id="appSettingsTabArrangement" class="set-select">
+                      <option value="state">By state (rows per state)</option>
+                      <option value="case">By case (clusters)</option>
+                      <option value="ledger">Ledger (aligned columns)</option>
+                      <option value="classic">Classic (default)</option>
+                    </select>
+                  </div>
+                  <div class="set-row has-field" data-search="state order reverse needs you bottom top rows sections">
+                    <div class="set-row-text">
+                      <span class="set-row-label">State Order</span>
+                      <span class="set-row-desc">For Tab Layout by state. At the bottom flips the rows, so needs you sits right above the terminal.</span>
+                    </div>
+                    <select id="appSettingsTabStateOrder" class="set-select">
+                      <option value="urgent-first">Needs you on top (default)</option>
+                      <option value="urgent-last">Needs you at the bottom</option>
+                    </select>
+                  </div>
                   <div class="set-row has-field" data-search="tab orientation horizontal vertical side rail">
                     <div class="set-row-text">
                       <span class="set-row-label">Tab Orientation</span>
@@ -2053,7 +2166,7 @@
                   <div class="set-row has-field" data-search="tab rail sort order activity manual drag reorder">
                     <div class="set-row-text">
                       <span class="set-row-label">Vertical Rail Order</span>
-                      <span class="set-row-desc">By activity uses the home screen's order: blocked on you first, then whatever has been running longest, then the most recently quiet. Manual keeps your tab order and is the only mode you can drag rows in. Alt+1..9 always follows the tab order either way.</span>
+                      <span class="set-row-desc">By activity uses the home screen's order: blocked on you first, then whatever has been running longest, then the most recently quiet. Manual keeps your tab order and is the only mode you can drag rows in. With Tab Layout by state or by case it orders the rows inside each section. Alt+1..9 always follows the tab order either way.</span>
                     </div>
                     <select id="appSettingsTabRailSort" class="set-select">
                       <option value="activity">By activity (home screen order)</option>
@@ -2103,6 +2216,13 @@
                     </div>
                     <label class="switch switch-sm"><input type="checkbox" id="appSettingsTabTwoRows"><span class="slider"></span></label>
                   </div>
+                  <div class="set-row" data-search="cli logos on tabs logo icon harness agent cli tab hide">
+                    <div class="set-row-text">
+                      <span class="set-row-label">CLI Logos on Tabs</span>
+                      <span class="set-row-desc">Show each agent's CLI logo before the session name on tabs and the home screen's tab list. Off leaves the status dot and the shell's SH badge. Tiles, split headers and the Run menus keep their logos.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsShowTabCliLogos" checked><span class="slider"></span></label>
+                  </div>
                   <div class="set-row" data-search="pop out detach tab window">
                     <div class="set-row-text">
                       <span class="set-row-label">Pop-out Button on Tabs</span>
@@ -2113,7 +2233,7 @@
                   <div class="set-row" id="appSettingsLineageLinesItem" data-search="lineage lines spawned worker parent connection">
                     <div class="set-row-text">
                       <span class="set-row-label">Spawn Lineage Lines <span class="set-tag">desktop</span></span>
-                      <span class="set-row-desc">Draw a line under the tab strip from a session to the sessions it spawned.</span>
+                      <span class="set-row-desc">Draw lines from each session to the sessions it spawned. The selected tab's family is drawn thicker.</span>
                     </div>
                     <label class="switch switch-sm"><input type="checkbox" id="appSettingsLineageLines" checked><span class="slider"></span></label>
                   </div>
@@ -2487,6 +2607,30 @@
               <div class="set-group" id="appSettingsCodexGroup">
                 <div class="set-group-head"><h4>Codex</h4><span class="set-scope">synced</span></div>
                 <div class="set-group-body">
+                  <div class="set-row has-field" data-search="codex default model">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Default Codex model</span>
+                      <span class="set-row-desc">Model ID for new local Codex sessions, including WSL. Leave empty to use Codex configuration.</span>
+                    </div>
+                    <input id="appSettingsCodexModel" class="set-input" type="text" maxlength="100" aria-label="Default Codex model" placeholder="Use Codex configuration" autocomplete="off" spellcheck="false">
+                  </div>
+                  <div class="set-row has-field" data-search="codex default reasoning effort thinking">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Default Codex reasoning effort</span>
+                      <span class="set-row-desc">Applies to new local sessions; supported levels depend on the model and Codex version. Custom endpoints, Docker and remote sessions keep their own settings.</span>
+                    </div>
+                    <select id="appSettingsCodexReasoningEffort" class="set-select" aria-label="Default Codex reasoning effort">
+                      <option value="">Use Codex configuration</option>
+                      <option value="none">none</option>
+                      <option value="minimal">minimal</option>
+                      <option value="low">low</option>
+                      <option value="medium">medium</option>
+                      <option value="high">high</option>
+                      <option value="xhigh">xhigh</option>
+                      <option value="max">max</option>
+                      <option value="ultra">ultra</option>
+                    </select>
+                  </div>
                   <div class="set-row" data-search="codex bypass approvals sandbox">
                     <div class="set-row-text">
                       <span class="set-row-label">Bypass approvals and sandbox</span>
@@ -2829,6 +2973,20 @@
               </div>
               <p class="set-section-blurb">Paths, automation and remote access. Set once, rarely touched.</p>
 
+              <div class="set-group" id="doctorGroup">
+                <div class="set-group-head"><h4>Diagnostics</h4><span class="set-scope">server</span></div>
+                <div class="set-group-body">
+                  <div class="set-row" data-search="diagnostics doctor dependencies tmux node claude codex check install">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Check this machine</span>
+                      <span class="set-row-desc">Runs <code>codeman doctor</code> on the server: which agent CLIs, tmux, Node and the optional office tools are installed, their versions, and how to install what is missing.</span>
+                    </div>
+                    <button class="btn-toolbar btn-sm" id="doctorRunBtn" onclick="app.runDoctor()">Run checks</button>
+                  </div>
+                  <div id="doctorResult" class="set-note" style="display:none" data-i18n-skip></div>
+                </div>
+              </div>
+
               <div class="set-group">
                 <div class="set-group-head"><h4>Paths</h4><span class="set-scope">synced</span></div>
                 <div class="set-group-body">
@@ -2879,10 +3037,6 @@
                       <button class="btn-icon-sm" id="tunnelQrBtn" onclick="app.showTunnelQR()" title="Show QR code">&#x229E;</button>
                     </div>
                   </div>
-                  <div class="set-row" id="tunnelUploadUrlRow" style="display:none">
-                    <div class="set-row-text"><span class="set-row-label">Upload URL</span></div>
-                    <span id="tunnelUploadUrlDisplay" class="set-copy" title="Click to copy"></span>
-                  </div>
                 </div>
               </div>
             </section>
@@ -2969,18 +3123,30 @@
               <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M12 8v8M8 12h8"/></svg>
               <h2>Create New</h2>
             </div>
-            <p class="set-section-blurb">A fresh workspace under ~/codeman-cases, scaffolded with its own CLAUDE.md.</p>
+            <p class="set-section-blurb" id="newCaseBlurb">A fresh workspace under ~/codeman-cases, scaffolded with its own CLAUDE.md.</p>
             <div class="form-row">
               <label>Case Name</label>
-              <input type="text" id="newCaseName" placeholder="my-project" pattern="[a-zA-Z0-9_-]+" autocomplete="off" autocapitalize="off" spellcheck="false">
-              <span class="form-hint">Letters, numbers, hyphens, underscores only. Created in ~/codeman-cases/</span>
+              <input type="text" id="newCaseName" placeholder="my-project" pattern="[a-zA-Z0-9_-]+" autocomplete="off" autocapitalize="off" spellcheck="false" oninput="app.updateNewCasePathPreview()">
+              <span class="form-hint" id="newCaseNameHint">Letters, numbers, hyphens, underscores only. Created in ~/codeman-cases/</span>
             </div>
             <div class="form-row">
               <label>Description (optional)</label>
               <input type="text" id="newCaseDescription" placeholder="A brief description..." autocomplete="off">
             </div>
+            <div class="form-row" id="newCaseCustomPathToggleRow">
+              <label class="checkbox-row"><input type="checkbox" id="newCaseCustomPathToggle" onchange="app.toggleNewCaseCustomPath()"> 📁 Create in a custom folder</label>
+              <span class="form-hint">By default a new case is created under ~/codeman-cases. Choose another folder and the case is created there instead; it is listed like any other case.</span>
+            </div>
+            <div class="form-row" id="newCaseCustomPathRow" style="display:none">
+              <label>Parent Folder</label>
+              <div class="path-input-group">
+                <input type="text" id="newCasePath" placeholder="~/projects" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false" oninput="app.updateNewCasePathPreview()">
+                <button type="button" class="btn path-input-browse" onclick="app.openNewCasePathPicker()">Browse&hellip;</button>
+              </div>
+              <span class="form-hint" id="newCasePathPreview">Pick the folder the new case folder should be created inside.</span>
+            </div>
             <div class="form-row docker-quick-row">
-              <label class="checkbox-row"><input type="checkbox" id="newCaseDocker"> 🐳 Run in an isolated Docker container</label>
+              <label class="checkbox-row"><input type="checkbox" id="newCaseDocker" onchange="app.toggleNewCaseCustomPath()"> 🐳 Run in an isolated Docker container</label>
               <span class="form-hint">Runs this case in a hardened, isolated container. The base image is built automatically on first use. Docker/Podman must be installed.</span>
               <span class="form-hint">Already have a container running? <button type="button" class="btn-inline-check" id="dockerAdoptJumpBtn">Attach to it instead</button> Codeman only runs docker exec into it and never touches its lifecycle.</span>
             </div>
@@ -3853,7 +4019,9 @@
   <script defer src="app.js"></script>
   <script defer src="tab-rail-resize.js"></script>
   <script defer src="terminal-ui.js"></script>
+  <script defer src="terminal-tile.js"></script>
   <script defer src="terminal-split.js"></script>
+  <script defer src="tile-grid.js"></script>
   <script defer src="respawn-ui.js"></script>
   <script defer src="ralph-panel.js"></script>
   <script defer src="orchestrator-panel.js"></script>
@@ -3870,6 +4038,7 @@
   <script defer src="webview-tabs.js"></script>
   <script defer src="mobile-overview.js"></script>
   <script defer src="home-sessions.js"></script>
+  <script defer src="git-status-ui.js"></script>
   <script defer src="entrance-animations.js"></script>
   <script defer src="ralph-wizard.js"></script>
   <script defer src="api-client.js"></script>
@@ -3877,5 +4046,6 @@
   <script defer src="ultracode-windows.js"></script>
   <script defer src="session-lineage.js"></script>
   <script defer src="image-input.js"></script>
+  <script defer src="spreadsheet-preview.js"></script>
 </body>
 </html>

src/web/public/mobile-handlers.js

@@ -410,6 +410,12 @@ const KeyboardHandler = {
       const keyboardHeight = this.initialViewportHeight - (window.visualViewport.height || window.innerHeight);
       const accessoryBar = document.querySelector('.keyboard-accessory-bar');
 
+      // The mobile case picker is a third position:fixed bottom-anchored
+      // surface, and since it gained a search field the keyboard can open over
+      // it. iOS does not shrink the layout viewport, so an unlifted sheet sits
+      // BEHIND the keyboard with its own search box out of sight.
+      const caseSheet = document.querySelector('.mobile-case-picker.active .mobile-case-picker-sheet');
+
       if (isSmallMedium) {
         // Phones/small tablets: toolbar and accessory bar are position:fixed
         // via CSS. Use translateY to lift them above the keyboard.
@@ -426,6 +432,9 @@ const KeyboardHandler = {
         if (accessoryBar) {
           accessoryBar.style.transform = keyboardOffset > 0 ? `translateY(${-keyboardOffset}px)` : '';
         }
+        if (caseSheet) {
+          caseSheet.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`;
@@ -436,6 +445,9 @@ const KeyboardHandler = {
         if (accessoryBar) {
           accessoryBar.style.bottom = `${keyboardHeight}px`;
         }
+        if (caseSheet) {
+          caseSheet.style.bottom = `${keyboardHeight}px`;
+        }
       }
 
       // CJK textarea positioning (always position:fixed on touch devices).
@@ -464,6 +476,10 @@ const KeyboardHandler = {
     const accessoryBar = document.querySelector('.keyboard-accessory-bar');
     const cjkInput = document.getElementById('cjkInput');
     const main = document.querySelector('.main');
+    // Not scoped to `.active`, unlike the lift above: a sheet closed while the
+    // keyboard was still up must still have its inline offset cleared, or the
+    // next open slides in already displaced.
+    const caseSheet = document.querySelector('.mobile-case-picker-sheet');
 
     if (toolbar) {
       toolbar.style.transform = '';
@@ -476,6 +492,10 @@ const KeyboardHandler = {
       cjkInput.style.transform = '';
       cjkInput.style.bottom = '';
     }
+    if (caseSheet) {
+      caseSheet.style.transform = '';
+      caseSheet.style.bottom = '';
+    }
     if (main) {
       main.style.paddingBottom = '';
     }

src/web/public/mobile.css

@@ -39,8 +39,10 @@ html.mobile-init .file-browser-panel {
 
   /* No "open in new window" (detach) on phones/tablets — popped-out browser
      windows aren't usable there. !important beats the hover/detached reveal
-     rules in styles.css */
-  .session-tab .tab-detach {
+     rules in styles.css. A native wrapper that opens windows of its own (side
+     by side on a foldable) keeps it at tablet widths: app.js sets
+     html.host-windows. Phone widths hide it again in the 599px block. */
+  html:not(.host-windows) .session-tab .tab-detach {
     display: none !important;
   }
 }
@@ -332,6 +334,34 @@ html.mobile-init .file-browser-panel {
   }
 }
 
+/* Tab Layout "By case" at tablet widths, getDeviceType()'s 'tablet' (600 to
+   767px). The strip is the tablet block's one scrolling row and
+   updateTabOverflowMode() never wraps it here, so the boxes, which may shrink
+   below 768px, squeezed and wrapped their tabs inside themselves instead of
+   overflowing: the strip never scrolled, and every tab past a box's first
+   line was clipped under the fixed header. The boxes dissolve into the chip
+   row as on phones (the 599px block), which keeps the tablet's own 40px chip
+   geometry; a 44px box would hang below the 48px header. Ends at 767px, not
+   at the tablet block's 768: from 768 getDeviceType() says 'desktop', and the
+   desktop rule in styles.css (flex-shrink: 0, wrapping box by box) owns the
+   strip. With the boxes, their labels and their case-colour borders gone, the
+   `-<case>` part of a generated name (.tab-name-case, which styles.css hides
+   in the clustered strip) is the only cue left to which case a chip is in: the
+   w<n> counter is per case, so w1-alpha and w1-beta would both read "w1". */
+@media (min-width: 600px) and (max-width: 767px) {
+  :where(.header) .session-tabs-host > .session-tabs.tabs-clusters > .tab-cluster {
+    display: contents;
+  }
+
+  :where(.header) .tab-cluster-label {
+    display: none;
+  }
+
+  :where(.header) .session-tabs-host > .session-tabs.tabs-clusters .tab-name-case {
+    display: inline;
+  }
+}
+
 /* Edge fade for the phone's header tab strip (used in the block below).
    Registered so the keyframes can interpolate them as lengths; @property is
    only valid at the top level, hence out here. */
@@ -755,6 +785,31 @@ html.mobile-init .file-browser-panel {
     font-weight: 500;
   }
 
+  /* Grouped by state (tabArrangement 'state'), the phone strip keeps its one scrolling
+     row: the tabs still come in state order, most urgent first, but the
+     headings would cost chips and the dots already say which state is which.
+     The phone overview is where the labelled sections live. */
+  :where(.header) .tab-triage-head {
+    display: none;
+  }
+
+  /* Clustered by case, the same holds: the boxes dissolve into the one chip
+     row (in cluster order) and the labels go, since every chip still names
+     its session. It does so in full: the `-<case>` part of a generated name,
+     which styles.css hides in the clustered strip, shows again, or w1-alpha
+     and w1-beta (the w<n> counter is per case) would both read "w1". */
+  :where(.header) .session-tabs-host > .session-tabs.tabs-clusters > .tab-cluster {
+    display: contents;
+  }
+
+  :where(.header) .tab-cluster-label {
+    display: none;
+  }
+
+  :where(.header) .session-tabs-host > .session-tabs.tabs-clusters .tab-name-case {
+    display: inline;
+  }
+
   /* Only the active tab shows its action icons on a phone (see below), so on
      every other tab the container is empty but still a flex item, and its gap
      made the chip visibly wider on the right than on the left. */
@@ -852,6 +907,13 @@ html.mobile-init .file-browser-panel {
     display: none;
   }
 
+  /* The tap-zone reserve counts gear + close only (test/mobile-tab-tap-zones),
+     so the pop-out icon stays off phone tabs even under a window-opening host,
+     which offers the pop-out from its own chrome (app.detachSession). */
+  .session-tab .tab-detach {
+    display: none !important;
+  }
+
   /* Gear icon on active tab - tiny, subtle */
   .session-tab.active .tab-gear {
     display: inline-flex;
@@ -1449,15 +1511,6 @@ html.mobile-init .file-browser-panel {
     padding: 6px 14px;
   }
 
-  /* Add case button - compact (keeping for when shown via menu) */
-  .btn-case-add {
-    display: none !important;
-  }
-
-  .btn-case-settings {
-    display: none !important;
-  }
-
   /* When keyboard is visible, also move accessory bar up */
   .keyboard-visible .keyboard-accessory-bar.visible {
     /* Position is handled by JS transform along with toolbar */
@@ -1471,33 +1524,6 @@ html.mobile-init .file-browser-panel {
     display: none !important;
   }
 
-  /* Keep btn-case-add styling for tablet/future use */
-  .toolbar .btn-case-add {
-    min-width: 26px !important;
-    max-width: 26px !important;
-    width: 26px !important;
-    min-height: 26px !important;
-    max-height: 26px !important;
-    height: 26px !important;
-    padding: 0 !important;
-    font-size: 0.9rem;
-    font-weight: bold;
-    display: inline-flex !important;
-    align-items: center;
-    justify-content: center;
-    line-height: 1;
-    border-radius: 4px;
-    background: transparent;
-    border: 1px solid rgba(255, 255, 255, 0.15);
-    color: #9ca3af;
-  }
-
-  .btn-case-add:hover,
-  .btn-case-add:active {
-    background: rgba(255, 255, 255, 0.1);
-    color: #fff;
-  }
-
   /* Panels on mobile - full width, positioned above toolbar, visibility controlled by JS */
   .monitor-panel,
   .subagents-panel {
@@ -1722,17 +1748,24 @@ html.mobile-init .file-browser-panel {
   }
 
   .welcome-actions {
-    flex-direction: column;
-    gap: 0.5rem;
     margin-top: 1rem;
   }
 
-  .welcome-btn {
+  /* Only reached with the phone overview switched off. The primary spans the
+     column; the chips keep wrapping at the finger size styles.css gives touch
+     screens (40px, its pointer: coarse rule). This rule loads later at equal
+     specificity, so a lower value here made a phone's chips shorter than a
+     tablet's; restating 40px also covers a narrow window with a mouse. */
+  .welcome-primary {
     width: 100%;
     justify-content: center;
     min-height: 44px;
-    padding: 0.75rem 1rem;
-    font-size: 0.85rem;
+    font-size: 0.9rem;
+  }
+
+  .welcome-chip {
+    height: 40px;
+    border-radius: 20px;
   }
 
   .history-show-more {
@@ -2289,6 +2322,18 @@ html.mobile-init .file-browser-panel {
     font-size: 1.5rem;
   }
 
+  /* With the keyboard up the sheet is lifted above it (mobile-handlers.js), so
+     what is left to fit is much shorter than 80dvh of the layout viewport. Cap
+     the list rather than the sheet, so the search row and the Create button
+     stay on screen and only the rows scroll. */
+  .keyboard-visible .mobile-case-picker-sheet {
+    max-height: 45vh;
+  }
+
+  .keyboard-visible .mobile-case-picker-body {
+    max-height: 28vh;
+  }
+
   .mobile-case-picker-footer {
     padding-bottom: calc(12px + var(--safe-area-bottom));
   }
@@ -3200,13 +3245,13 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
    both stylesheets and repainted the armed modifier back to a resting button on
    all four light skins. Excluding the state here fixes phone and tablet at once;
    adding a class to the armed rules would only have moved the tie. */
-html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile, .btn-settings-mobile, .btn-toolbar.btn-shell, .toolbar .btn-case-add, .accessory-btn:not(.armed)) {
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile, .btn-settings-mobile, .btn-toolbar.btn-shell, .accessory-btn:not(.armed)) {
   background: var(--control-bg);
   border-color: var(--control-border);
   color: var(--text-dim);
 }
 
-html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile:active, .btn-settings-mobile:active, .btn-toolbar.btn-shell:hover, .btn-toolbar.btn-shell:active, .btn-case-add:hover, .btn-case-add:active, .accessory-btn:active) {
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile:active, .btn-settings-mobile:active, .btn-toolbar.btn-shell:hover, .btn-toolbar.btn-shell:active, .accessory-btn:active) {
   background: var(--control-bg-hover);
   border-color: var(--control-border-hover);
   color: var(--text);
@@ -4038,3 +4083,24 @@ html[data-session-list="sidebar"] .session-sidebar .session-tab .tab-close {
     max-height: min(88vh, env(viewport-segment-height 0 1, 88vh));
   }
 }
+
+/* XLSX preview (spreadsheet-preview.js): larger sheet tabs and a taller,
+   touch-scrollable grid on phones. */
+@media (max-width: 700px) {
+  .spreadsheet-sheet-tabs {
+    padding-inline: 4px;
+    scroll-snap-type: x proximity;
+  }
+
+  .spreadsheet-sheet-tab {
+    min-width: 96px;
+    min-height: 40px;
+    scroll-snap-align: start;
+  }
+
+  .spreadsheet-grid {
+    min-height: 55vh;
+    -webkit-overflow-scrolling: touch;
+    touch-action: pan-x pan-y;
+  }
+}

src/web/public/panels-ui.js

@@ -4178,6 +4178,8 @@ Object.assign(CodemanApp.prototype, {
         bodyEl.innerHTML = `<iframe src="${escapeHtml(`${base}/raw`)}" title="${escapeHtml(filePath)}"></iframe>`;
       } else if (ext === 'docx' || ext === 'pptx') {
         bodyEl.innerHTML = `<iframe src="${escapeHtml(`${base}/preview`)}" title="${escapeHtml(filePath)}"></iframe>`;
+      } else if (ext === 'xlsx') {
+        this._openSpreadsheetPreview(bodyEl, `${base}/raw`, externalSize);
       } else {
         try {
           // Bounded like the workspace text preview: a Range for the first
@@ -4274,6 +4276,9 @@ Object.assign(CodemanApp.prototype, {
       } else if (data.type === 'audio') {
         bodyEl.innerHTML = `<audio src="${escapeHtml(CodemanBase.url(data.url))}" controls autoplay preload="metadata"></audio>`;
         footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`;
+      } else if (data.type === 'spreadsheet') {
+        this._openSpreadsheetPreview(bodyEl, CodemanBase.url(data.url), data.size);
+        footerEl.textContent = `${this.formatFileSize(data.size)} \u2022 ${data.extension}`;
       } else if (data.type === 'binary') {
         const downloadHref = CodemanBase.url(`/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}&download=true`);
         bodyEl.innerHTML = `<div class="binary-message">Binary file (${this.formatFileSize(data.size)})<br>Cannot preview<br><a href="${escapeHtml(downloadHref)}" download>Download</a></div>`;
@@ -4329,6 +4334,12 @@ Object.assign(CodemanApp.prototype, {
    */
   detachFilePreview() {
     if (!this.filePreviewDetachUrl) return;
+    const hosted = this.openInHostWindow?.(this.filePreviewDetachUrl) ?? null;
+    if (hosted !== null) {
+      if (hosted) this.closeFilePreview();
+      else this.showToast('Could not open a new window for this preview', 'error');
+      return;
+    }
     const win = window.open(this.filePreviewDetachUrl, '_blank');
     if (!win) {
       this.showToast('Pop-up blocked: allow pop-ups for this site to detach previews', 'error');
@@ -4347,6 +4358,9 @@ Object.assign(CodemanApp.prototype, {
    * the in-flight network fetch and puts the element back in NETWORK_EMPTY.
    */
   _stopFilePreviewMedia() {
+    // A spreadsheet preview owns a fetch and a Web Worker; emptying the body
+    // leaves both running, so tear them down with the rest of the media.
+    this._disposeSpreadsheetPreview();
     const bodyEl = this.$('filePreviewBody');
     if (!bodyEl) return;
     for (const media of bodyEl.querySelectorAll('video, audio')) {
@@ -4361,6 +4375,42 @@ Object.assign(CodemanApp.prototype, {
     bodyEl.innerHTML = '';
   },
 
+  /**
+   * Render an XLSX into the preview body via spreadsheet-preview.js, which
+   * parses it in a Web Worker (the ExcelJS bundle loads there, on demand, and
+   * never on page load). `url` is a raw route; the renderer adds `?preview=true`
+   * so the server applies its preview size cap. Superseded by the next
+   * _stopFilePreviewMedia(), which runs on every open and on close.
+   */
+  _openSpreadsheetPreview(bodyEl, url, size) {
+    this._disposeSpreadsheetPreview();
+    const renderer = window.CodemanSpreadsheetPreview;
+    if (!renderer?.open) {
+      bodyEl.innerHTML = '<div class="binary-message">Spreadsheet preview is unavailable.</div>';
+      return;
+    }
+    bodyEl.textContent = '';
+    const token = {};
+    this._spreadsheetPreviewToken = token;
+    this._spreadsheetPreview = renderer.open({
+      container: bodyEl,
+      url,
+      size,
+      isCurrent: () => this._spreadsheetPreviewToken === token,
+    });
+  },
+
+  _disposeSpreadsheetPreview() {
+    const handle = this._spreadsheetPreview;
+    this._spreadsheetPreview = null;
+    this._spreadsheetPreviewToken = null;
+    try {
+      handle?.dispose();
+    } catch (err) {
+      console.warn('Failed to dispose spreadsheet preview:', err);
+    }
+  },
+
   // ═══════════════════════════════════════════════════════════════
   // File Viewer text view: rendered markdown, line numbers, wrap
   // ═══════════════════════════════════════════════════════════════
@@ -5056,7 +5106,7 @@ Object.assign(CodemanApp.prototype, {
           <div class="attachment-history-empty-title">No attachments yet</div>
           <div>Show a file here by running:</div>
           <code>codeman attach /absolute/path/to/file.pptx</code>
-          <div>Supports .pptx, .docx, .pdf, .png, .md, and .txt.</div>
+          <div>Supports .pptx, .docx, .xlsx, .pdf, .png, .md, and .txt.</div>
         </div>
       `;
       return;
@@ -6028,6 +6078,11 @@ Object.assign(CodemanApp.prototype, {
       }
     }
 
+    // Rings for the Compact header style, kept current in every style (two
+    // style writes a poll) so switching styles never shows an empty ring.
+    this._setStatRing('statCpuRing', stats.cpu);
+    this._setStatRing('statMemRing', stats.memory?.percent);
+
     if (memEl && memBar) {
       const memGB = (stats.memory.usedMB / 1024).toFixed(1);
       memEl.textContent = `${memGB}G`;
@@ -6045,6 +6100,20 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * Fill one stat ring (Compact header style) to `percent`, clamped to 0-100,
+   * and flag it `high` above 80%, the same threshold at which the value next
+   * to it turns red.
+   */
+  _setStatRing(id, percent) {
+    const ring = this.$(id);
+    if (!ring) return;
+    const value = Number(percent);
+    const fill = Number.isFinite(value) ? Math.round(Math.min(100, Math.max(0, value))) : 0;
+    ring.style.setProperty('--pu', String(fill));
+    ring.classList.toggle('high', fill > 80);
+  },
+
   // ─── Clipboard ──────────────────────────────────────────────────────────────
 
   async _onClipboardWrite(data) {

src/web/public/session-lineage.js

@@ -1,29 +1,41 @@
 /**
- * @fileoverview Session lineage lines — the arcs joining a tab to the tabs it spawned.
+ * @fileoverview Session lineage lines: the tree joining a tab to the tabs it spawned.
  *
  * A session that starts another session (the `codeman` agent skill spawning a worker,
  * which passes its own `$CODEMAN_SESSION_ID`) gets `parentSessionId` stamped on its
- * state server-side. This module turns that field into the same kind of glowing
- * connection line the subagent windows use, but tab → tab, so the strip shows at a
- * glance which tab spawned which.
+ * state server-side. This module turns that field into a quiet orthogonal tree, one per
+ * spawning tab, routed through the gaps between tab rows so it never crosses a label or
+ * the terminal (geometry: `CodemanLineage.computeTree` in constants.js).
+ *
+ * EVERY FAMILY IS ALWAYS DRAWN, AND THE SELECTED TAB'S IS EMPHASIZED: the family the
+ * active tab spawned, and the family it belongs to as a child, get the
+ * `lineage-family--focus` group (thicker, full opacity, drawn last so nothing covers
+ * it). Drawing ONLY the selected family was tried first and rejected by the owner
+ * (2026-10-07: "I wanna see all the connections always"). Selection still has to
+ * redraw to move the emphasis, which `_updateActiveTabImmediate()` does whenever any
+ * lineage exists (`_lineageTotalEdges`).
  *
  * It is an ADDITIONAL LAYER on the existing SVG pass, not a second pass: the core
  * `_updateConnectionLinesImmediate()` (subagent-windows.js) calls
  * `_appendLineageConnectionLines(svg, rects)` at its tail, exactly like ultracode does,
  * so every layer shares ONE batched read → write reflow and one tab-rect cache.
  *
- * Two constraints that are not obvious from the code:
- * - DESKTOP ONLY. The overlay is `z-index: 999`; the desktop header is 100 (arcs paint
+ * Constraints that are not obvious from the code:
+ * - DESKTOP ONLY. The overlay is `z-index: 999`; the desktop header is 100 (lines paint
  *   over it, which is what lets them touch tab bottoms), but under 1024px mobile.css
  *   makes the header `position: fixed; z-index: 1200` and would bury them. The phone
  *   strip is also a scroller where both endpoints are rarely on screen at once.
+ * - The routing room is RESERVED in CSS (`.session-tabs.lineage-tree`), toggled by
+ *   `_syncLineageGutter()` from `updateTabOverflowMode()`. It keys on whether ANY
+ *   family exists, never on the selection, so switching tabs never resizes the header
+ *   (and with it the terminal and the PTY).
  * - Paths carry `data-agent-id="lineage:<childId>"` because that is the attribute
  *   `_applyLineEntrances()` queries, so the draw-in animation and its
  *   negative-`animation-delay` resume across `svg.innerHTML = ''` come for free.
  *
  * @mixin Extends CodemanApp.prototype via Object.assign
  * @dependency subagent-windows.js (_updateConnectionLinesImmediate, #connectionLines)
- * @dependency constants.js (window.CodemanLineage.computePath + .COLORS)
+ * @dependency constants.js (window.CodemanLineage.computeTree + .COLORS)
  * @dependency settings-ui.js (loadAppSettingsFromStorage, getDefaultSettings)
  * @loadorder 15.6 (after ultracode-windows.js — appended to the same SVG pass)
  */
@@ -62,49 +74,99 @@ Object.assign(CodemanApp.prototype, {
   applyLineageLineSettings() {
     const prev = this._lineageLinesOn;
     const next = this._syncLineageLinesEnabled();
-    if (prev !== next) this.updateConnectionLines();
+    if (prev !== next) {
+      // The reserved routing room follows the setting; updateTabOverflowMode()
+      // re-syncs it and re-measures the wrap with the new padding.
+      this.updateTabOverflowMode?.();
+      this.updateConnectionLines();
+    }
   },
 
   /**
-   * Every parent → child pair worth drawing, with the child's index among its siblings
-   * (that index is what nests sibling arcs instead of overprinting them).
+   * Reserve (or release) the strip's routing room: `.lineage-tree` on #sessionTabs
+   * widens the row gap, pads the bottom for the last row's gap, and opens the spine
+   * channel on the left of a wrapped strip (styles.css). Called at the top of
+   * `updateTabOverflowMode()`, so it runs on every tab render, BEFORE the wrap is
+   * measured.
    *
-   * Walks `sessionOrder` rather than the sessions Map so sibling depth follows the
-   * strip's own left-to-right order, which is what the user sees.
+   * Keyed on whether any family exists at all, never on which one is selected: a
+   * class that followed the selection would grow and shrink the header on every tab
+   * switch, and the header's height is the terminal's height.
+   *
+   * Only the header strip routes through reserved gaps. The vertical rail keeps its
+   * own `--lineage-vertical-gutter`, and the sidebar draws no lineage.
+   */
+  _syncLineageGutter() {
+    const edges = this._lineageLinesEnabled() ? this._collectLineageEdges() : [];
+    this._lineageTotalEdges = edges.length;
+    const strip = document.getElementById('sessionTabs');
+    if (!strip) return;
+    const want = edges.length > 0 && !this._isVerticalTabList?.();
+    if (strip.classList.contains('lineage-tree') !== want) strip.classList.toggle('lineage-tree', want);
+  },
+
+  /**
+   * Every parent → child pair, in strip order. Walks `sessionOrder` rather than the
+   * sessions Map so sibling order follows the strip's own left-to-right order, which
+   * is what the user sees.
    */
   _collectLineageEdges() {
     const edges = [];
     if (!this.sessions || this.sessions.size < 2) return edges;
     const order = this.sessionOrder && this.sessionOrder.length ? this.sessionOrder : [...this.sessions.keys()];
-    const seenPerParent = new Map();
     for (const id of order) {
       const session = this.sessions.get(id);
       const parentId = session && session.parentSessionId;
       // A parent that is gone (closed, or never came back after a restart) draws
       // nothing: the field is decoration, so a dangling one is simply not rendered.
       if (!parentId || parentId === id || !this.sessions.has(parentId)) continue;
-      const depth = seenPerParent.get(parentId) || 0;
-      seenPerParent.set(parentId, depth + 1);
-      edges.push({ parentId, childId: id, depth, status: session.status || 'idle' });
+      edges.push({ parentId, childId: id, status: session.status || 'idle' });
     }
     return edges;
   },
 
+  /** Every family as `{ parentId, edges }`, in strip order of first appearance. */
+  _lineageFamilies(edges) {
+    const families = new Map();
+    for (const edge of edges) {
+      if (!families.has(edge.parentId)) families.set(edge.parentId, []);
+      families.get(edge.parentId).push(edge);
+    }
+    return [...families].map(([parentId, familyEdges]) => ({ parentId, edges: familyEdges }));
+  },
+
   /**
-   * Colour for one arc, from CodemanLineage.COLORS, keyed on the SPAWNING tab.
+   * Parent ids of the families the selection emphasizes: the family the selected tab
+   * spawned, and the family it was spawned into (its parent plus its siblings). Empty
+   * when a web tab holds the stage, or the selected tab has no lineage at all.
+   */
+  _lineageFocusParents(edges) {
+    const parents = new Set();
+    const focus = this.activeWebviewId ? null : this.activeSessionId;
+    if (!focus) return parents;
+    for (const edge of edges) {
+      if (edge.parentId === focus || edge.childId === focus) parents.add(edge.parentId);
+    }
+    return parents;
+  },
+
+  /**
+   * Colour for one family, from CodemanLineage.COLORS, keyed on the SPAWNING tab.
    *
-   * ⚠️ Per PARENT, not per child: every arc leaving one tab is the same colour, no
+   * ⚠ Per PARENT, not per child: every line leaving one tab is the same colour, no
    * matter how many workers it spawns, so the strip reads as "these five came from
    * w1, those two came from w2". Keying it per child instead gave one tab's own
    * children a different colour each, which is the thing the colours exist to tell
    * apart. A child that goes on to spawn its own workers is a parent in its turn and
-   * gets its own colour for the arcs BELOW it, so a chain changes colour at each
+   * gets its own colour for the lines BELOW it, so a chain changes colour at each
    * generation while each generation's fan-out stays uniform.
    *
    * Assigned in FIRST-SEEN order and remembered per parent id. First-seen rather than
    * draw-index keeps a colour stable across re-renders, tab reorders and sibling
    * closes (the SVG is wiped and rebuilt constantly, so an index-based colour would
-   * flicker). An empty string means "no override": the CSS falls back to
+   * flicker). The draw pass claims a colour for EVERY family in strip order before it
+   * draws anything, so neither the draw order (the selected family goes last) nor
+   * which family was selected first ever decides who gets which colour. An empty string means "no override": the CSS falls back to
    * --session-blue, so the first spawning tab keeps the skin-aware blue.
    */
   _lineageColorFor(parentId) {
@@ -140,19 +202,20 @@ Object.assign(CodemanApp.prototype, {
   _appendLineageConnectionLines(svg, rects) {
     this._lineageEdgeCount = 0;
     if (!svg || !this._lineageLinesEnabled()) return;
-    // Sidebar layout: computeLineagePath()'s whole geometry — the U-bridge hung
-    // from the STRIP's bottom edge, the 64px dip corridor — assumes a horizontal
-    // tab row. Against a vertical list the "strip bottom" is the bottom of the
-    // sidebar, so every arc would draw a giant loop to the foot of the list.
-    // Parent/child adjacency reads fine in a vertical list without arcs; a
-    // sideways lineage shape is a follow-up with its own visual tuning, not a
-    // by-product of a layout port.
+    // Sidebar layout: the tree is routed for a horizontal strip or the vertical
+    // rail. The sidebar is a vertical list with its own scroller and no reserved
+    // channel; parent/child adjacency reads fine there without lines.
     if (this.isSessionSidebarActive?.()) return;
-    const compute = window.CodemanLineage && window.CodemanLineage.computePath;
-    if (!compute) return;
+    const computeTree = window.CodemanLineage && window.CodemanLineage.computeTree;
+    if (!computeTree) return;
 
     const edges = this._collectLineageEdges();
+    this._lineageTotalEdges = edges.length;
     if (edges.length === 0) return;
+    // Claim colours in strip order for every family before drawing (_lineageColorFor).
+    for (const edge of edges) this._lineageColorFor(edge.parentId);
+    const families = this._lineageFamilies(edges);
+    const focusParents = this._lineageFocusParents(edges);
     if (!rects) rects = new Map();
 
     // PHASE 1 — reads.
@@ -162,9 +225,9 @@ Object.assign(CodemanApp.prototype, {
     const orientation =
       document.documentElement.getAttribute('data-tab-orientation') === 'vertical' ? 'vertical' : 'horizontal';
     // A session hidden inside a collapsed group of the grouped rail has no row
-    // to anchor to, so its end of the arc moves to that group's header (a
-    // "proxied" endpoint, drawn quieter). Two endpoints proxied to the SAME
-    // header would be an arc from a row to itself: skipped.
+    // to anchor to, so its end of the line moves to that group's header (a
+    // "proxied" endpoint, drawn quieter). A child proxied to the same header as
+    // its parent would be a line from a row to itself: skipped.
     const resolveEndpoint = (id) => {
       const tab = strip.querySelector(`.session-tab[data-id="${CSS.escape(id)}"]`);
       if (tab) return { key: 'tab:' + id, element: tab, proxied: false };
@@ -173,71 +236,138 @@ Object.assign(CodemanApp.prototype, {
       const header = strip.querySelector(`[data-tab-group-header="${CSS.escape(groupId)}"]`);
       return { key: 'group:' + groupId, element: header, proxied: !!header };
     };
-    const resolvedEdges = [];
-    for (const edge of edges) {
-      const parentEndpoint = resolveEndpoint(edge.parentId);
-      const childEndpoint = resolveEndpoint(edge.childId);
-      if (parentEndpoint.key === childEndpoint.key) continue;
-      resolvedEdges.push({ edge, parentEndpoint, childEndpoint });
-      for (const endpoint of [parentEndpoint, childEndpoint]) {
-        if (rects.has(endpoint.key)) continue;
+    const measure = (endpoint) => {
+      if (!rects.has(endpoint.key)) {
         rects.set(endpoint.key, endpoint.element ? endpoint.element.getBoundingClientRect() : null);
       }
+      return rects.get(endpoint.key);
+    };
+    const resolvedFamilies = [];
+    for (const family of families) {
+      const parentEndpoint = resolveEndpoint(family.parentId);
+      const parentRect = measure(parentEndpoint);
+      if (!parentRect) continue;
+      const children = [];
+      for (const edge of family.edges) {
+        const childEndpoint = resolveEndpoint(edge.childId);
+        if (childEndpoint.key === parentEndpoint.key) continue;
+        const rect = measure(childEndpoint);
+        if (rect) children.push({ edge, endpoint: childEndpoint, rect });
+      }
+      if (children.length > 0) resolvedFamilies.push({ family, parentEndpoint, parentRect, children });
+    }
+    if (resolvedFamilies.length === 0) return;
+    // The header strip's rows come from EVERY tab in it (computeTree hangs a row's
+    // gap under its tallest tab), web tabs included. The rail needs none.
+    const tabRects = [];
+    let spineLeft;
+    if (orientation === 'horizontal') {
+      // Where the spine channel is: the reserved --lineage-spine-channel just left
+      // of the strip's content edge. Usually that is the strip's own left edge,
+      // but grouped by state the label column comes first (styles.css), and a
+      // spine at the edge ran through every label. Read back from the padding
+      // the CSS laid out, so geometry and stylesheet cannot disagree.
+      const style = typeof getComputedStyle === 'function' ? getComputedStyle(strip) : null;
+      const channel = style ? parseFloat(style.getPropertyValue('--lineage-spine-channel')) : NaN;
+      if (Number.isFinite(channel)) {
+        const inset = (parseFloat(style.borderLeftWidth) || 0) + (parseFloat(style.paddingLeft) || 0);
+        spineLeft = stripRect.left + inset - channel;
+      }
+      for (const tab of strip.querySelectorAll('.session-tab')) {
+        const id = tab.getAttribute('data-id');
+        const key = id ? 'tab:' + id : null;
+        if (key && rects.has(key)) tabRects.push(rects.get(key));
+        else {
+          const rect = tab.getBoundingClientRect();
+          if (key) rects.set(key, rect);
+          tabRects.push(rect);
+        }
+      }
     }
-    this._lineageEdgeCount = resolvedEdges.length;
 
     // PHASE 2 — writes, from the cache only.
-    for (const { edge, parentEndpoint, childEndpoint } of resolvedEdges) {
-      const parentRect = rects.get(parentEndpoint.key);
-      const childRect = rects.get(childEndpoint.key);
-      if (!parentRect || !childRect) continue;
-
-      const geom = compute({
+    // Lanes follow STRIP order, so a family keeps its lane when the selection moves;
+    // only the DRAW order changes (the emphasized families last, on top). A row gap
+    // fits a few lanes, so they cycle: families that share one are told apart by colour.
+    const laneLimit = Math.max(1, (window.CodemanLineage && window.CodemanLineage.MAX_LANES) || 3);
+    const laneCount = Math.min(laneLimit, resolvedFamilies.length);
+    const drawOrder = resolvedFamilies
+      .map((resolved, index) => ({
+        ...resolved,
+        lane: index % laneCount,
+        focus: focusParents.has(resolved.family.parentId),
+      }))
+      .sort((a, b) => a.focus - b.focus);
+    for (const { family, parentEndpoint, parentRect, children, lane, focus } of drawOrder) {
+      const geom = computeTree({
         parent: parentRect,
-        child: childRect,
+        children: children.map((c) => ({ id: c.edge.childId, rect: c.rect })),
         strip: stripRect,
-        depth: edge.depth,
+        tabs: tabRects,
+        spineLeft,
         orientation,
+        lane,
+        laneCount,
       });
-      if (!geom) continue; // scrolled out of the strip, or a degenerate rect
-
+      if (!geom || geom.routes.length === 0) continue;
+      const byId = new Map(children.map((c) => [c.edge.childId, c]));
+      const color = this._lineageColorFor(family.parentId);
+      // One group per family: it carries the translucency, so the stretches its
+      // routes share (the trunk) do not stack into a brighter line than the branches,
+      // and the emphasis for the selected tab's families (styles.css).
+      const group = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+      group.setAttribute('class', 'lineage-family' + (focus ? ' lineage-family--focus' : ''));
+      group.setAttribute('data-parent-tab', family.parentId);
+      // Working routes go in FIRST, so an idle sibling's solid stroke covers the
+      // shared trunk and only the working child's own branch shows its dashes.
+      const routes = geom.routes
+        .map((route) => ({ route, child: byId.get(route.id) }))
+        .filter((r) => r.child)
+        .sort((a, b) => (b.child.edge.status === 'working') - (a.child.edge.status === 'working'));
+      for (const { route, child } of routes) {
         const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-      line.setAttribute('d', geom.d);
-      // The working class marches the dashes, so an active worker is visible along
-      // the line itself. `status` is the CHILD's, which is the interesting end.
-      const working = edge.status === 'working' ? ' lineage-line--working' : '';
-      const proxied = parentEndpoint.proxied || childEndpoint.proxied;
-      line.setAttribute('class', 'connection-line lineage-line' + working + (proxied ? ' lineage-line--proxied' : ''));
-      // The PARENT's colour rides a CSS custom property so the stylesheet keeps owning
-      // opacity, glow and dash; an empty colour leaves the --session-blue fallback.
-      // Every arc out of one tab shares it — see _lineageColorFor().
-      const color = this._lineageColorFor(edge.parentId);
+        line.setAttribute('d', route.d);
+        // `status` is the CHILD's, which is the interesting end: a working child's
+        // route is dashed (and marches, motion permitting).
+        const working = child.edge.status === 'working' ? ' lineage-line--working' : '';
+        const proxied = parentEndpoint.proxied || child.endpoint.proxied;
+        line.setAttribute(
+          'class',
+          'connection-line lineage-line' + working + (proxied ? ' lineage-line--proxied' : '')
+        );
+        // The PARENT's colour rides a CSS custom property so the stylesheet keeps
+        // owning weight and dash; an empty colour leaves the --session-blue fallback.
         if (color) line.style.setProperty('--lineage-color', color);
         // `data-agent-id` is what _applyLineEntrances() queries — see the file header.
-      line.setAttribute('data-agent-id', 'lineage:' + edge.childId);
-      line.setAttribute('data-parent-tab', edge.parentId);
-      line.setAttribute('data-child-tab', edge.childId);
-      svg.appendChild(line);
-
-      // Direction marker at the CHILD end. A circle rather than an SVG <marker>:
-      // markers need a <defs> block and fight the dash pattern.
+        line.setAttribute('data-agent-id', 'lineage:' + child.edge.childId);
+        line.setAttribute('data-parent-tab', family.parentId);
+        line.setAttribute('data-child-tab', child.edge.childId);
+        group.appendChild(line);
+      }
+      // Direction marker at each CHILD end, after every path so no stroke covers it.
+      for (const { route, child } of routes) {
+        const working = child.edge.status === 'working' ? ' lineage-line--working' : '';
+        const proxied = parentEndpoint.proxied || child.endpoint.proxied;
         const dot = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
-      dot.setAttribute('cx', String(geom.endX));
-      dot.setAttribute('cy', String(geom.endY));
-      // Resting radius; `lineage-dot-pulse` breathes it 3.5 → 4.5 while the child
-      // works, so the two have to be changed together.
-      dot.setAttribute('r', '3.5');
+        dot.setAttribute('cx', String(route.endX));
+        dot.setAttribute('cy', String(route.endY));
+        // Fallback radius only: styles.css sizes the dot through `--lineage-dot-r`
+        // (larger in an emphasized family), and `lineage-dot-pulse` breathes from it.
+        dot.setAttribute('r', '2.5');
         dot.setAttribute('class', 'lineage-line-dot' + working + (proxied ? ' lineage-line-dot--proxied' : ''));
-      dot.setAttribute('data-child-tab', edge.childId);
+        dot.setAttribute('data-child-tab', child.edge.childId);
         if (color) dot.style.setProperty('--lineage-color', color);
-      svg.appendChild(dot);
+        group.appendChild(dot);
+      }
+      svg.appendChild(group);
+      this._lineageEdgeCount += routes.length;
     }
   },
 
   /**
    * The strip scrolls (desktop `overflow-x: auto` and every wrapped layout), and a
-   * scroll moves both endpoints without firing any render, so the arcs would slide off
-   * their tabs. Passive listener, and the redraw is the normal coalesced one.
+   * scroll moves both endpoints without firing any render, so the lines would slide
+   * off their tabs. Passive listener, and the redraw is the normal coalesced one.
    *
    * Installed once; the guard also keeps a re-init from stacking listeners.
    */
@@ -248,11 +378,24 @@ Object.assign(CodemanApp.prototype, {
     this._lineageScrollHandler = () => {
       // Sidebar layout and the vertical rail scroll the SAME element
       // vertically, and there the subagent/ultracode connectors anchor to tab
-      // rects too (the sidebar skips lineage arcs entirely, and the rail can
-      // show connectors with zero lineage edges, so _lineageEdgeCount alone
-      // would never redraw them).
+      // rects too (the sidebar skips lineage entirely, and the rail can show
+      // connectors with zero lineage edges, so _lineageEdgeCount alone would
+      // never redraw them).
       if (this._lineageEdgeCount > 0 || this._isVerticalTabList?.()) this.updateConnectionLines();
     };
     strip.addEventListener('scroll', this._lineageScrollHandler, { passive: true });
+
+    // ⚠ A SELECTION RESIZES TABS AFTER THE REDRAW. The active tab reveals its gear
+    // and close icons by transitioning their padding (styles.css), so it keeps
+    // widening for ~150ms after `_updateActiveTabImmediate()` has already redrawn,
+    // and the tab it was selected from shrinks. That can move tabs or re-wrap a row,
+    // which left a family's trunk hanging under the tab's OLD position. Redraw once
+    // a size transition inside the strip ends (coalesced, like every other redraw).
+    this._lineageTransitionHandler = (event) => {
+      const prop = event.propertyName || '';
+      if (!(prop === 'width' || prop === 'max-width' || prop.startsWith('padding'))) return;
+      if (this._lineageTotalEdges > 0) this.updateConnectionLines();
+    };
+    strip.addEventListener('transitionend', this._lineageTransitionHandler);
   },
 });

src/web/public/session-ui.js

@@ -125,6 +125,17 @@ const RUN_MODE_LAUNCH = {
 /** How often the OPEN case picker re-reads /api/cases (it also refreshes once on open). */
 const CASE_PICKER_REFRESH_MS = 5000;
 
+/**
+ * Action rows at the bottom of the toolbar case picker. They replaced the "+"
+ * and gear buttons that sat beside the picker (owner, 1.36.0 beta): the same two
+ * actions, one click away, without two extra controls in the toolbar. The arrow
+ * keys reach them after the last case; Enter or a click runs `run`.
+ */
+const CASE_PICKER_ACTIONS = [
+  { id: 'add', icon: '+', label: 'New or link a case…', run: (app) => app.showCreateCaseModal() },
+  { id: 'settings', icon: '\u2699', label: 'Case settings…', run: (app) => app.toggleCaseSettings() },
+];
+
 const EXTERNAL_CLI_MODES = new Set(Object.keys(RUN_MODE_LAUNCH));
 const BUILT_IN_RUN_MODES = new Set(['claude', 'shell', ...Object.keys(RUN_MODE_LAUNCH)]);
 
@@ -140,6 +151,13 @@ function isExternalCliRunMode(mode) {
   return EXTERNAL_CLI_MODES.has(mode) || registryCliById(mode)?.kind === 'agent';
 }
 
+// Does this session lack the Claude-only features (Respawn, Ralph)? The registry's
+// `capabilities.external`, the flag the server's isExternalCliMode() reads. Not
+// isExternalCliRunMode(): that picks a launch path, and claude is `kind: 'agent'` too.
+function isExternalCliSession(mode) {
+  return registryCliById(mode)?.external ?? isExternalCliRunMode(mode);
+}
+
 Object.assign(CodemanApp.prototype, {
   /**
    * Build envOverrides payload from case + global settings.
@@ -343,13 +361,32 @@ Object.assign(CodemanApp.prototype, {
 
     const options = this.filterCasePickerOptions(this.getCasePickerOptions(), this._casePickerFilter || '');
     const selectedName = select.value || 'testcase';
-    const maxIndex = Math.max(0, options.length - 1);
+    // The arrow keys walk the cases, then the action rows under them.
+    const maxIndex = options.length + CASE_PICKER_ACTIONS.length - 1;
     this._casePickerActiveIndex = Math.min(Math.max(this._casePickerActiveIndex || 0, 0), maxIndex);
 
+    const actionRows = CASE_PICKER_ACTIONS.map((action, i) => {
+      const index = options.length + i;
+      const active = index === this._casePickerActiveIndex;
+      return `
+          <button
+            type="button"
+            id="quickStartCaseOption-${index}"
+            class="case-combobox-action ${active ? 'active' : ''}"
+            role="option"
+            aria-selected="false"
+            data-case-action="${action.id}">
+            <span class="case-combobox-action-icon" aria-hidden="true">${action.icon}</span>
+            <span class="case-combobox-option-label">${escapeHtml(action.label)}</span>
+          </button>
+        `;
+    }).join('');
+    const actionsBlock = `<div class="case-combobox-actions" role="presentation">${actionRows}</div>`;
+
     if (options.length === 0) {
-      list.innerHTML = '<div class="case-combobox-empty">No cases match</div>';
+      list.innerHTML = '<div class="case-combobox-empty">No cases match</div>' + actionsBlock;
       list.classList.remove('hidden');
-      input.removeAttribute('aria-activedescendant');
+      input.setAttribute('aria-activedescendant', `quickStartCaseOption-${this._casePickerActiveIndex}`);
       return;
     }
 
@@ -372,11 +409,22 @@ Object.assign(CodemanApp.prototype, {
           </button>
         `;
       })
-      .join('');
+      .join('') + actionsBlock;
     list.classList.remove('hidden');
     input.setAttribute('aria-activedescendant', `quickStartCaseOption-${this._casePickerActiveIndex}`);
   },
 
+  /** Run a case picker action row (`CASE_PICKER_ACTIONS`): close the list first, then act. */
+  runCasePickerAction(id) {
+    const action = CASE_PICKER_ACTIONS.find((a) => a.id === id);
+    if (!action) return;
+    const select = document.getElementById('quickStartCase');
+    if (select) this.updateCasePickerInput(select.value);
+    this.closeCasePicker();
+    document.getElementById('quickStartCaseSearch')?.blur?.();
+    action.run(this);
+  },
+
   selectQuickStartCase(caseName, { save = true } = {}) {
     const select = document.getElementById('quickStartCase');
     if (!select) return;
@@ -419,18 +467,26 @@ Object.assign(CodemanApp.prototype, {
       const options = this.filterCasePickerOptions(this.getCasePickerOptions(), this._casePickerFilter || input.value);
       if (event.key === 'ArrowDown') {
         event.preventDefault();
-        this._casePickerActiveIndex = Math.min((this._casePickerActiveIndex || 0) + 1, Math.max(0, options.length - 1));
+        this._casePickerActiveIndex = Math.min(
+          (this._casePickerActiveIndex || 0) + 1,
+          options.length + CASE_PICKER_ACTIONS.length - 1
+        );
         this._casePickerOpen ? this.renderCasePickerList() : this.openCasePicker(input.value);
       } else if (event.key === 'ArrowUp') {
         event.preventDefault();
         this._casePickerActiveIndex = Math.max((this._casePickerActiveIndex || 0) - 1, 0);
         this._casePickerOpen ? this.renderCasePickerList() : this.openCasePicker(input.value);
       } else if (event.key === 'Enter') {
-        const option = options[this._casePickerActiveIndex || 0];
+        const index = this._casePickerActiveIndex || 0;
+        const option = options[index];
+        const action = this._casePickerOpen ? CASE_PICKER_ACTIONS[index - options.length] : undefined;
         if (option) {
           event.preventDefault();
           this.selectQuickStartCase(option.name);
           this.run?.();
+        } else if (action) {
+          event.preventDefault();
+          this.runCasePickerAction(action.id);
         }
       } else if (event.key === 'Escape') {
         event.preventDefault();
@@ -443,6 +499,11 @@ Object.assign(CodemanApp.prototype, {
     });
     list.addEventListener('mousedown', event => event.preventDefault());
     list.addEventListener('click', event => {
+      const action = event.target.closest?.('.case-combobox-action');
+      if (action?.dataset?.caseAction) {
+        this.runCasePickerAction(action.dataset.caseAction);
+        return;
+      }
       const option = event.target.closest?.('.case-combobox-option');
       if (option?.dataset?.case) {
         this.selectQuickStartCase(option.dataset.case);
@@ -573,6 +634,10 @@ Object.assign(CodemanApp.prototype, {
     }
 
     if (session?.id) this._onSessionCreated(session);
+    // A session this tab's Run created joins an open tile grid (tile-grid.js),
+    // so Run's selectSession() below focuses its tile instead of leaving the
+    // grid. Only here: sessions created elsewhere arrive by session:created.
+    this._joinTileGridFromRun?.(sessionId);
     // session:created normally uses the debounced renderer. The direct POST path
     // needs the tab in the DOM before selectSession() marks it active.
     this._renderSessionTabsImmediate?.();
@@ -1799,19 +1864,6 @@ Object.assign(CodemanApp.prototype, {
     input.value = Math.max(1, current - 1);
   },
 
-  // Shell count stepper functions
-  incrementShellCount() {
-    const input = document.getElementById('shellCount');
-    const current = parseInt(input.value) || 1;
-    input.value = Math.min(20, current + 1);
-  },
-
-  decrementShellCount() {
-    const input = document.getElementById('shellCount');
-    const current = parseInt(input.value) || 1;
-    input.value = Math.max(1, current - 1);
-  },
-
   // Next free <prefix><n> index for a case's session tabs (e.g. w1-<case>,
   // w2-<case> for agents, s1-<case> for shells), shared by the local and
   // remote/docker launch paths so all tabs follow the same naming convention.
@@ -1874,10 +1926,14 @@ Object.assign(CodemanApp.prototype, {
     try {
       // Get case path first
       const caseRes = await fetch(`/api/cases/${caseName}`);
-      let caseData = (await caseRes.json())?.data ?? {};
+      const caseLookup = await caseRes.json();
+      let caseData = caseLookup?.data ?? {};
 
-      // Create the case if it doesn't exist
+      // Create the case only when the server says it does not exist. Any other
+      // failure (a linked folder on a mount that is not answering) must not
+      // scaffold a same-name local case that would then shadow the real one.
       if (!caseData.path) {
+        if (caseLookup?.errorCode !== 'NOT_FOUND') throw new Error(caseLookup?.error || 'Case lookup failed');
         const createCaseRes = await fetch('/api/cases', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
@@ -2074,7 +2130,9 @@ Object.assign(CodemanApp.prototype, {
 
   async runShell() {
     const caseName = document.getElementById('quickStartCase').value || 'testcase';
-    const shellCount = Math.min(20, Math.max(1, parseInt(document.getElementById('shellCount').value) || 1));
+    // Run Shell reads the toolbar's one instance stepper, like every other run*();
+    // its own second `− 1 +` group (#shellCount) was removed (#428).
+    const shellCount = this._readTabCount();
 
     const ownsLaunchTerminal = this._beginSessionLaunchStatus(
       `Starting ${shellCount} Shell session(s) in ${caseName}...`,
@@ -2084,10 +2142,14 @@ Object.assign(CodemanApp.prototype, {
     try {
       // Get the case path
       const caseRes = await fetch(`/api/cases/${caseName}`);
-      let caseData = (await caseRes.json())?.data ?? {};
+      const caseLookup = await caseRes.json();
+      let caseData = caseLookup?.data ?? {};
 
-      // Create the case if it doesn't exist
+      // Create the case only when the server says it does not exist. Any other
+      // failure (a linked folder on a mount that is not answering) must not
+      // scaffold a same-name local case that would then shadow the real one.
       if (!caseData.path) {
+        if (caseLookup?.errorCode !== 'NOT_FOUND') throw new Error(caseLookup?.error || 'Case lookup failed');
         const createCaseRes = await fetch('/api/cases', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
@@ -2422,7 +2484,7 @@ Object.assign(CodemanApp.prototype, {
     if (detachToggle) detachToggle.checked = this.hasTabDetachOverride(sessionId);
 
     // Reset to an appropriate tab — Summary for external CLIs (Respawn/Ralph are Claude-only)
-    const isAltMode = isExternalCliRunMode(session.mode);
+    const isAltMode = isExternalCliSession(session.mode);
     this.switchOptionsTab(isAltMode ? 'summary' : 'respawn');
 
     // Update respawn status display and buttons
@@ -2589,6 +2651,62 @@ Object.assign(CodemanApp.prototype, {
     return typeof confirmed === 'string' ? confirmed : name;
   },
 
+  /**
+   * Write an inline rename, one PUT per session at a time, in the order the
+   * user made them. The editor can be reopened (or cancelled, or replaced by a
+   * group rename) while a PUT is in flight, so the write lives here rather than
+   * in the editor: a confirmed name is applied locally even after its editor is
+   * gone, and the "already that name" check runs only once the earlier writes
+   * have landed, so confirming the name still on screen is a real write.
+   * Resolves { status: 'confirmed' | 'failed' | 'deleted' }; never rejects,
+   * and reports a failed write itself, since its editor may be gone by then.
+   * `_inlineRenamePending` holds the newest queued name per session, so an
+   * editor reopened over a write in flight starts from that name rather than
+   * the one the server has not replaced yet.
+   */
+  _queueInlineSessionName(sessionId, desiredName) {
+    this._inlineRenameWrites ??= new Map();
+    this._inlineRenamePending ??= new Map();
+    const writes = this._inlineRenameWrites;
+    const pending = this._inlineRenamePending;
+    pending.set(sessionId, desiredName);
+    // Chained from a settled promise, so one rejected write cannot stop the
+    // writes queued behind it.
+    const prev = (writes.get(sessionId) || Promise.resolve()).catch(() => {});
+    const task = prev.then(async () => {
+      const session = this.sessions.get(sessionId);
+      if (!session) return { status: 'deleted' };
+      if (session.name === desiredName) return { status: 'confirmed' };
+      let confirmed = null;
+      try {
+        confirmed = await this._putSessionName(sessionId, desiredName);
+      } catch {
+        // A failure is a value, so a later write in the chain still runs.
+      }
+      if (!this.sessions.has(sessionId)) return { status: 'deleted' };
+      if (confirmed === null) {
+        this.showToast('Failed to rename', 'error');
+        return { status: 'failed' };
+      }
+      try {
+        this._applyLocalSessionName(sessionId, confirmed);
+        this.renderSessionTabs();
+      } catch (err) {
+        // The server holds the name; a local repaint failing is not a failed write.
+        console.error('[rename] applying the confirmed name failed', err);
+      }
+      return { status: 'confirmed' };
+    });
+    writes.set(sessionId, task);
+    const cleanup = () => {
+      if (writes.get(sessionId) !== task) return;
+      writes.delete(sessionId);
+      pending.delete(sessionId);
+    };
+    task.then(cleanup, cleanup);
+    return task;
+  },
+
   async saveSessionName() {
     if (!this.editingSessionId) return;
     // Captured: the modal can be closed (or switched to another session) while
@@ -2877,7 +2995,11 @@ Object.assign(CodemanApp.prototype, {
     tabName.classList.add('tab-name-renaming');
 
     const currentName = this.getSessionName(session);
-    const parsed = parseSessionPrefix(session.name);
+    // A rename still in flight is the user's last word, not the name the
+    // server has yet to replace: start from it, and compare against it below.
+    const shownName = this._inlineRenamePending?.get(sessionId) ?? session.name;
+    const renameInFlight = shownName !== session.name;
+    const parsed = parseSessionPrefix(shownName);
     const originalContent = tabName.textContent;
     const originalChildren = [...tabName.childNodes].map((node) => node.cloneNode(true));
     const restoreOriginalChildren = () => {
@@ -2898,13 +3020,17 @@ Object.assign(CodemanApp.prototype, {
 
     const input = document.createElement('input');
     input.type = 'text';
-    input.value = parsed ? parsed.suffix : (session.name || '');
+    input.value = parsed ? parsed.suffix : (shownName || '');
     input.placeholder = parsed ? 'Add description...' : currentName;
     input.className = 'tab-rename-input';
     // 80px is tuned for the narrow header tab; a full-width sidebar row can and
-    // should give the whole line to the input.
-    const renameWidth = tabName.closest('.tab-rail') ? 'auto' : this.isSessionSidebarActive?.() ? '100%' : '80px';
-    input.style.cssText = `width: ${renameWidth}; min-width: 0; font-size: 0.75rem; padding: 2px 4px; background: var(--bg-input); border: 1px solid var(--accent); border-radius: 3px; color: var(--text); outline: none;`;
+    // should give the whole line to the input. The header editor may shrink to
+    // nothing, while a rail or sidebar row always keeps room to type.
+    const inRail = !!tabName.closest('.tab-rail');
+    const inSidebar = !inRail && !!this.isSessionSidebarActive?.();
+    const renameWidth = inRail ? 'auto' : inSidebar ? '100%' : '80px';
+    const renameMinWidth = inRail || inSidebar ? '4rem' : '0';
+    input.style.cssText = `width: ${renameWidth}; min-width: ${renameMinWidth}; font-size: 0.75rem; padding: 2px 4px; background: var(--bg-input); border: 1px solid var(--accent); border-radius: 3px; color: var(--text); outline: none;`;
 
     tabName.appendChild(input);
     input.focus();
@@ -2954,22 +3080,20 @@ Object.assign(CodemanApp.prototype, {
 
       const suffix = input.value.trim();
       const fullName = parsed ? parsed.prefix + (suffix ? ': ' + suffix : '') : suffix;
-      if (fullName === session.name) restoreOriginalChildren();
+      // An unchanged confirm puts the old label back, unless the editor opened
+      // over a rename in flight: that label was repainted from the server's
+      // older name, so show the in-flight name rather than make it look lost.
+      if (fullName === shownName && !renameInFlight) restoreOriginalChildren();
       else tabName.textContent = fullName || originalContent;
 
-      // Skip the API call if the session vanished between focus and blur.
-      const stillExists = this.sessions.has(sessionId);
-      if (stillExists && fullName !== session.name) {
-        const confirmed = await this._putSessionName(sessionId, fullName);
+      // Skip the API call if the session vanished between focus and blur. The
+      // queue applies the confirmed name to this.sessions before the re-render
+      // below repaints from it (see _applyLocalSessionName()).
+      if (this.sessions.has(sessionId)) {
+        const result = await this._queueInlineSessionName(sessionId, fullName);
         if (invalidated || this._activeRename !== renameHandle || !this.sessions.has(sessionId)) return;
-        if (confirmed === null) {
-          restoreOriginalChildren();
-          this.showToast('Failed to rename', 'error');
-        } else {
-          // The re-render below repaints from this.sessions, so the new name has
-          // to be in the map before it runs (see _applyLocalSessionName()).
-          this._applyLocalSessionName(sessionId, confirmed);
-        }
+        // The queue reports a failure itself; the editor only puts its label back.
+        if (result.status === 'failed') restoreOriginalChildren();
       }
       // Re-render tabs to restore full tab structure
       completeCurrentRename();
@@ -3020,7 +3144,7 @@ Object.assign(CodemanApp.prototype, {
 
       // Close on outside click (one-shot listener)
       const closeHandler = (e) => {
-        if (!popover.contains(e.target) && !e.target.classList.contains('btn-case-settings')) {
+        if (!popover.contains(e.target) && !e.target.closest?.('.case-combobox-action')) {
           popover.classList.add('hidden');
           document.removeEventListener('click', closeHandler);
         }
@@ -3098,6 +3222,16 @@ Object.assign(CodemanApp.prototype, {
   showCreateCaseModal() {
     document.getElementById('newCaseName').value = '';
     document.getElementById('newCaseDescription').value = '';
+    // Custom folder starts off each time, and is not offered to a non-admin in multi-user mode: the
+    // server refuses it (it writes outside the cases directory and into the shared registry).
+    const customToggle = document.getElementById('newCaseCustomPathToggle');
+    if (customToggle) customToggle.checked = false;
+    const customPath = document.getElementById('newCasePath');
+    if (customPath) customPath.value = '';
+    const me = window.__codemanUser || {};
+    const customRow = document.getElementById('newCaseCustomPathToggleRow');
+    if (customRow) customRow.style.display = me.multiUser && me.role !== 'admin' ? 'none' : '';
+    this.toggleNewCaseCustomPath();
     document.getElementById('linkCaseName').value = '';
     document.getElementById('linkCasePath').value = '';
     const remoteFields = [
@@ -3265,6 +3399,71 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * Custom-folder row for Create New: shows or hides the parent-folder field, and keeps it and the
+   * Docker option mutually exclusive (a Docker case has its own workspace flow, and the quick-create
+   * route has no `path`).
+   */
+  toggleNewCaseCustomPath() {
+    const custom = document.getElementById('newCaseCustomPathToggle');
+    const docker = document.getElementById('newCaseDocker');
+    const row = document.getElementById('newCaseCustomPathRow');
+    if (!custom || !row) return;
+    row.style.display = custom.checked ? '' : 'none';
+    // The "under ~/codeman-cases" wording is wrong while a custom folder is picked.
+    const blurb = document.getElementById('newCaseBlurb');
+    if (blurb) {
+      blurb.textContent = custom.checked
+        ? 'A fresh workspace in a folder you choose, scaffolded with its own CLAUDE.md.'
+        : 'A fresh workspace under ~/codeman-cases, scaffolded with its own CLAUDE.md.';
+    }
+    const nameHint = document.getElementById('newCaseNameHint');
+    if (nameHint) {
+      nameHint.textContent = custom.checked
+        ? 'Letters, numbers, hyphens, underscores only. Created inside the parent folder below.'
+        : 'Letters, numbers, hyphens, underscores only. Created in ~/codeman-cases/';
+    }
+    custom.disabled = !!docker?.checked;
+    custom.title = docker?.checked ? 'Not available for a Docker case' : '';
+    if (docker) {
+      docker.disabled = custom.checked;
+      docker.title = custom.checked ? 'Not available with a custom folder' : '';
+    }
+    this.updateNewCasePathPreview();
+  },
+
+  /** The folder the case would be created in: the parent field plus the case name. */
+  _newCaseTargetPath() {
+    const rawParent = (document.getElementById('newCasePath')?.value || '').trim();
+    const name = (document.getElementById('newCaseName')?.value || '').trim();
+    if (!rawParent || !name) return '';
+    // Trailing slashes off, but `/` stays the root rather than becoming an empty path.
+    const parent = rawParent.replace(/\/+$/, '');
+    return `${parent}/${name}`;
+  },
+
+  updateNewCasePathPreview() {
+    const hint = document.getElementById('newCasePathPreview');
+    if (!hint) return;
+    const target = this._newCaseTargetPath();
+    hint.textContent = target ? `Will create: ${target}` : 'Pick the folder the new case folder should be created inside.';
+  },
+
+  openNewCasePathPicker() {
+    const input = document.getElementById('newCasePath');
+    PathPicker.open({
+      title: 'Choose the folder to create the case in',
+      initialPath: input.value.trim(),
+      directoriesOnly: true,
+      onSelect: (path) => {
+        input.value = path;
+        this.updateNewCasePathPreview();
+        input.focus();
+        input.setSelectionRange(path.length, path.length);
+      },
+    });
+  },
+
   async createCase() {
     const name = document.getElementById('newCaseName').value.trim();
     const description = document.getElementById('newCaseDescription').value.trim();
@@ -3282,9 +3481,16 @@ Object.assign(CodemanApp.prototype, {
     // One-click "Run in Docker": create the case folder AND a container, then start
     // a session inside it. Optional expandable settings override the defaults.
     const inDocker = document.getElementById('newCaseDocker')?.checked;
+    const customFolder = !inDocker && document.getElementById('newCaseCustomPathToggle')?.checked;
+    if (customFolder && !(document.getElementById('newCasePath')?.value || '').trim()) {
+      this.showToast('Choose the folder to create the case in', 'error');
+      return;
+    }
     const endpoint = inDocker ? '/api/cases/docker-quickcreate' : '/api/cases';
     const payload = inDocker
       ? { name, description, ...this._collectDockerQuickSettings() }
+      : customFolder
+        ? { name, description, path: this._newCaseTargetPath() }
         : { name, description };
 
     try {
@@ -3307,7 +3513,9 @@ Object.assign(CodemanApp.prototype, {
           // Start a session INSIDE the container (routes through quick-start).
           await this.runClaude();
         } else {
-          this.showToast(`Case "${name}" created`, 'success');
+          // The server's path is the folder actually created (~ expanded, symlinks resolved).
+          const createdIn = data.data?.case?.path || payload.path;
+          this.showToast(customFolder ? `Case "${name}" created in ${createdIn}` : `Case "${name}" created`, 'success');
         }
       } else {
         this.showToast(data.error || 'Failed to create case', 'error');

src/web/public/settings-ui.js

@@ -382,6 +382,7 @@ Object.assign(CodemanApp.prototype, {
     // Header visibility settings
     document.getElementById('appSettingsShowFontControls').checked = settings.showFontControls ?? defaults.showFontControls ?? false;
     document.getElementById('appSettingsShowSystemStats').checked = settings.showSystemStats ?? defaults.showSystemStats ?? true;
+    document.getElementById('appSettingsHeaderStatsStyle').value = this.resolveHeaderStatsStyle(settings);
     document.getElementById('appSettingsShowLifecycleLog').checked = settings.showLifecycleLog ?? defaults.showLifecycleLog ?? false;
     document.getElementById('appSettingsShowResponseViewer').checked = settings.showResponseViewer ?? defaults.showResponseViewer ?? false;
     document.getElementById('appSettingsShowFileViewerButton').checked = settings.showFileViewerButton ?? defaults.showFileViewerButton ?? true;
@@ -422,6 +423,7 @@ Object.assign(CodemanApp.prototype, {
     this._mcpSyncSavedOn = settings.mcpSyncEnabled === true;
     document.getElementById('appSettingsMcpSync').checked = this._mcpSyncSavedOn;
     this.applyMcpSyncVisibility();
+    this._applyDoctorAdminGate();
     this.loadWebhook();
     // Read My Mind: synced, default OFF (opt-in; capture + prediction cost real tokens).
     document.getElementById('appSettingsReadMyMind').checked = settings.readMyMindEnabled === true;
@@ -429,6 +431,7 @@ Object.assign(CodemanApp.prototype, {
       settings.ultracodeFloatingWindows ?? defaults.ultracodeFloatingWindows ?? false;
     document.getElementById('appSettingsShowMultiMonitorButton').checked = settings.showMultiMonitorButton ?? defaults.showMultiMonitorButton ?? false;
     document.getElementById('appSettingsShowSplitButton').checked = settings.showSplitButton ?? defaults.showSplitButton ?? false;
+    document.getElementById('appSettingsShowTileGridButton').checked = settings.showTileGridButton ?? defaults.showTileGridButton ?? true;
     document.getElementById('appSettingsShowPlanUsageLimits').checked = this.planUsageChipEnabled(settings);
     document.getElementById('appSettingsShowRedrawButton').checked = settings.showRedrawButton ?? defaults.showRedrawButton ?? false;
     // Phone overview home screen: only meaningful under 600px, so the row is
@@ -450,6 +453,10 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsShowSessionButton').checked = settings.showSessionButton ?? defaults.showSessionButton ?? false;
     document.getElementById('appSettingsShowAwayDigestButton').checked = settings.showAwayDigestButton ?? defaults.showAwayDigestButton ?? false;
     document.getElementById('appSettingsShowCronButton').checked = settings.showCronButton ?? defaults.showCronButton ?? false;
+    document.getElementById('appSettingsShowGitStatus').checked = settings.showGitStatus ?? defaults.showGitStatus ?? false;
+    document.getElementById('appSettingsGitStatusTree').checked = settings.gitStatusTree ?? defaults.gitStatusTree ?? true;
+    document.getElementById('appSettingsGitStatusMaxRepos').value = settings.gitStatusMaxRepos ?? defaults.gitStatusMaxRepos ?? 12;
+    document.getElementById('appSettingsGitStatusTimeout').value = settings.gitStatusTimeoutSeconds ?? defaults.gitStatusTimeoutSeconds ?? 30;
     // Gesture control lives in the Input section (alongside Local Echo / CJK Input)
     // but is only available when the instance runs with CODEMAN_GESTURE=1 (server sets
     // window.__codemanGestureAvailable). Hide just this item otherwise so the toggle
@@ -480,6 +487,7 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsCjkInput').checked = settings.cjkInputEnabled ?? defaults.cjkInputEnabled ?? false;
     document.getElementById('appSettingsExtendedKeyboardBar').checked = settings.extendedKeyboardBar ?? false;
     document.getElementById('appSettingsTabTwoRows').checked = settings.tabTwoRows ?? defaults.tabTwoRows ?? false;
+    document.getElementById('appSettingsShowTabCliLogos').checked = this.tabCliLogosEnabled(settings);
     document.getElementById('appSettingsTabOrientation').value =
       settings.tabOrientation ?? defaults.tabOrientation ?? 'horizontal';
     const tabRailWidth = window.CodemanTabRail?.resolveWidth({
@@ -497,7 +505,11 @@ Object.assign(CodemanApp.prototype, {
       settings.tabRailDetail ?? defaults.tabRailDetail ?? 'rich';
     document.getElementById('appSettingsTabRailSort').value =
       settings.tabRailSort ?? defaults.tabRailSort ?? 'activity';
-    document.getElementById('appSettingsShowTabDetachButton').checked = settings.showTabDetachButton ?? defaults.showTabDetachButton ?? false;
+    document.getElementById('appSettingsTabArrangement').value = this.resolveTabArrangement(settings);
+    document.getElementById('appSettingsTabStateOrder').value = this.resolveTabStateOrder(settings);
+    document.getElementById('appSettingsShowTabDetachButton').checked =
+      this.tabDetachButtonEnabled?.(settings, defaults)
+      ?? (settings.showTabDetachButton ?? defaults.showTabDetachButton ?? false);
     document.getElementById('appSettingsSessionListLayout').value =
       settings.sessionListLayout ?? defaults.sessionListLayout ?? 'header';
     const sessionSidebarFontSize = this.resolveSessionSidebarFontSize(
@@ -523,6 +535,8 @@ Object.assign(CodemanApp.prototype, {
       settings.codexDangerouslyBypassApprovals ?? false;
     document.getElementById('appSettingsCodexAnimations').checked =
       settings.codexAnimationsEnabled ?? false;
+    document.getElementById('appSettingsCodexModel').value = settings.codexModel ?? '';
+    document.getElementById('appSettingsCodexReasoningEffort').value = settings.codexReasoningEffort ?? '';
     this._applyCodexSettingsVisibility();
     // Claude Permissions settings
     document.getElementById('appSettingsAgentTeams').checked = settings.agentTeamsEnabled ?? false;
@@ -1192,6 +1206,18 @@ Object.assign(CodemanApp.prototype, {
     group.style.display = me.multiUser && me.role !== 'admin' ? 'none' : '';
   },
 
+  /**
+   * GET /api/doctor is admin-only in multi-user mode (it names install paths on the host), so a
+   * non-admin gets no Diagnostics group instead of a button that can only answer 403. Also
+   * wired to `codeman:me` for the same late-resolving role as the groups above.
+   */
+  _applyDoctorAdminGate() {
+    const group = document.getElementById('doctorGroup');
+    if (!group) return;
+    const me = window.__codemanUser || {};
+    group.style.display = me.multiUser && me.role !== 'admin' ? 'none' : '';
+  },
+
   /** Preview (apply=false) or run (apply=true) the MCP server sync across enabled CLIs. */
   async mcpSync(apply) {
     const out = this.$('mcpSyncResult');
@@ -1364,6 +1390,69 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * Settings → System → Diagnostics: run `codeman doctor` on the server (GET /api/doctor) and list
+   * each tool. Built with DOM nodes and textContent: paths and versions come from the host.
+   */
+  async runDoctor() {
+    const out = document.getElementById('doctorResult');
+    const btn = document.getElementById('doctorRunBtn');
+    if (!out) return;
+    const say = (text) => {
+      out.replaceChildren(document.createTextNode(text));
+      out.style.display = 'block';
+    };
+    if (btn) btn.disabled = true;
+    say('Checking…');
+    try {
+      const res = await this._api('/api/doctor');
+      let body = null;
+      try { body = res ? await res.json() : null; } catch { /* fall through */ }
+      if (!res || !res.ok || !body || body.success === false) {
+        say(body?.error || 'The check failed.');
+        return;
+      }
+      const { tools, summary, platform } = body.data;
+      const glyph = { ok: '✓', missing: '✗', outdated: '!', error: '!', skipped: '–' };
+      const list = document.createElement('ul');
+      list.style.margin = '0';
+      list.style.paddingLeft = '1.2em';
+      for (const t of tools) {
+        const li = document.createElement('li');
+        const strong = document.createElement('b');
+        // As the terminal doctor marks it: a missing OPTIONAL tool is ○, only a required one ✗.
+        const mark = t.status === 'missing' && !t.required ? '○' : glyph[t.status] || '?';
+        strong.textContent = `${mark} ${t.label}`;
+        li.append(strong);
+        const bits = [t.status];
+        if (t.version) bits.push(t.version);
+        if (t.status !== 'ok' && t.status !== 'skipped') bits.push(t.required ? 'required' : 'optional');
+        if (t.reason) bits.push(t.reason);
+        li.append(document.createTextNode(` ${bits.join(' · ')}`));
+        if (t.path) {
+          const p = document.createElement('div');
+          p.className = 'mono';
+          p.textContent = t.path;
+          li.append(p);
+        }
+        if (t.status === 'missing' && t.installHint) {
+          const h = document.createElement('div');
+          h.textContent = `Install: ${t.installHint}`;
+          li.append(h);
+        }
+        list.append(li);
+      }
+      const head = document.createElement('p');
+      head.textContent =
+        `${summary.ok} ok · ${summary.requiredMissing} required missing · ${summary.optionalMissing} optional missing` +
+        ` (${platform.environment})`;
+      out.replaceChildren(head, list);
+      out.style.display = 'block';
+    } finally {
+      if (btn) btn.disabled = false;
+    }
+  },
+
   _setUpdateResult(html) {
     const el = this.$('updateResult');
     if (el) { el.style.display = 'block'; el.innerHTML = html; }
@@ -1563,40 +1652,88 @@ Object.assign(CodemanApp.prototype, {
     return flags[tool] !== false;
   },
 
-  /** Render the registry's enabled, available CLIs as welcome-screen actions. */
+  /**
+   * Render the registry's enabled, available CLIs as welcome-screen actions:
+   * ONE primary button, then every other entry as a slim chip in a row under it.
+   *
+   * The primary is the first AGENT in catalog order (the first entry whose kind
+   * is not 'shell'), so on a stock install it is Claude Code, and with Claude
+   * disabled or missing it is simply the next agent; only a catalog with no agent
+   * at all promotes the shell. Chosen from the catalog's order and kind, never by
+   * an id: the registry decides what comes first. Everything else keeps catalog
+   * order inside the chip row, so the DOM order across both is the catalog's.
+   *
+   * The CLI id travels only as DATA: `data-mode` for the click, and the
+   * `run-mode-dot <id>` logo slot every Run menu shares (styles.css draws the
+   * brand mark, or a plain dot for an id it has no logo for). No per-id class on
+   * the buttons themselves, so no rule anywhere can give one CLI its own look.
+   */
   renderWelcomeCliActions() {
     const container = document.getElementById('welcomeCliActions');
     if (!container) return;
     const catalog = Array.isArray(window.__codemanCliCatalog) ? window.__codemanCliCatalog : [];
-    container.replaceChildren();
-    for (const cli of catalog) {
-      if (!cli.enabled || !this.isCliAvailable(cli.id)) continue;
-      const btn = document.createElement('button');
-      btn.type = 'button';
-      btn.className = `welcome-btn welcome-btn-cli welcome-btn-${cli.id}`;
-      btn.dataset.mode = cli.id;
-      const icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
-      icon.setAttribute('width', '20');
-      icon.setAttribute('height', '20');
-      icon.setAttribute('viewBox', '0 0 24 24');
-      icon.setAttribute('fill', 'none');
-      icon.setAttribute('stroke', 'currentColor');
-      icon.setAttribute('stroke-width', '2');
-      icon.setAttribute('aria-hidden', 'true');
-      const play = document.createElementNS('http://www.w3.org/2000/svg', 'polygon');
-      play.setAttribute('points', '5 3 19 12 5 21 5 3');
-      icon.appendChild(play);
-      btn.appendChild(icon);
-      // Same "Run <label>" text the static buttons had ("Run Claude Code", "Run Shell"),
-      // left translatable on purpose: i18n.js carries these strings, and a custom CLI's
-      // label simply has no dictionary entry, so it renders as typed.
-      btn.append(`Run ${cli.kind === 'shell' ? 'Shell' : cli.label}`);
-      btn.onclick = () => {
+    const offered = catalog.filter((cli) => cli.enabled && this.isCliAvailable(cli.id));
+    const primary = offered.find((cli) => cli.kind !== 'shell') || offered[0];
+    // "Run <label>", the strings i18n.js translates ("Run Claude Code", "Run Shell");
+    // a custom CLI's label simply has no dictionary entry, so it renders as typed.
+    const runLabel = (cli) => `Run ${cli.kind === 'shell' ? 'Shell' : cli.label}`;
+    const logo = (cli) => {
+      const dot = document.createElement('span');
+      dot.className = `run-mode-dot ${cli.id}`;
+      dot.setAttribute('aria-hidden', 'true');
+      return dot;
+    };
+    const launch = (cli) => () => {
       this.setRunMode(cli.id);
       void this.run();
     };
-      container.appendChild(btn);
+    container.replaceChildren();
+    if (!primary) return;
+
+    const main = document.createElement('button');
+    main.type = 'button';
+    main.className = 'welcome-primary';
+    main.dataset.mode = primary.id;
+    // The mark sits on a small light disc: brand marks (Claude's is orange) turn
+    // muddy straight on the accent fill, and the disc reads on every skin.
+    const disc = document.createElement('span');
+    disc.className = 'welcome-primary-logo';
+    disc.appendChild(logo(primary));
+    main.appendChild(disc);
+    // One raw string, kept whole: i18n.js matches the exact text node. The span
+    // only lets a long custom label ellipsize (styles.css .welcome-label).
+    const mainLabel = document.createElement('span');
+    mainLabel.className = 'welcome-label';
+    mainLabel.textContent = runLabel(primary);
+    main.appendChild(mainLabel);
+    main.onclick = launch(primary);
+    container.appendChild(main);
+
+    const rest = offered.filter((cli) => cli !== primary);
+    if (!rest.length) return;
+    const chips = document.createElement('div');
+    chips.className = 'welcome-chips';
+    chips.setAttribute('role', 'group');
+    chips.setAttribute('aria-label', 'More tools');
+    for (const cli of rest) {
+      const chip = document.createElement('button');
+      chip.type = 'button';
+      chip.className = 'welcome-chip';
+      chip.dataset.mode = cli.id;
+      // The chip shows the bare name (the row under "Run …" already says what it
+      // does); the full "Run <label>" is its accessible name and tooltip, both of
+      // which i18n.js translates.
+      chip.title = runLabel(cli);
+      chip.setAttribute('aria-label', runLabel(cli));
+      chip.appendChild(logo(cli));
+      const chipLabel = document.createElement('span');
+      chipLabel.className = 'welcome-label';
+      chipLabel.textContent = cli.kind === 'shell' ? 'Shell' : cli.label;
+      chip.appendChild(chipLabel);
+      chip.onclick = launch(cli);
+      chips.appendChild(chip);
     }
+    container.appendChild(chips);
   },
 
   /**
@@ -1630,17 +1767,16 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
-  _updateTunnelUrlRow(rowId, displayId, url, suffix = '') {
-    const row = document.getElementById(rowId);
-    const display = document.getElementById(displayId);
+  _updateTunnelUrlDisplay(url) {
+    const row = document.getElementById('tunnelUrlRow');
+    const display = document.getElementById('tunnelUrlDisplay');
     if (!row || !display) return;
     if (url) {
-      const fullUrl = url + suffix;
       row.style.display = '';
-      display.textContent = fullUrl;
+      display.textContent = url;
       display.onclick = () => {
-        navigator.clipboard.writeText(fullUrl).then(() => {
-          this.showToast(`${suffix ? 'Upload' : 'Tunnel'} URL copied`, 'success');
+        navigator.clipboard.writeText(url).then(() => {
+          this.showToast('Tunnel URL copied', 'success');
         });
       };
     } else {
@@ -1650,11 +1786,6 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
-  _updateTunnelUrlDisplay(url) {
-    this._updateTunnelUrlRow('tunnelUrlRow', 'tunnelUrlDisplay', url);
-    this._updateTunnelUrlRow('tunnelUploadUrlRow', 'tunnelUploadUrlDisplay', url, '/upload.html');
-  },
-
   showTunnelQR() {
     // Close existing popup if open
     this.closeTunnelQR();
@@ -2397,6 +2528,7 @@ Object.assign(CodemanApp.prototype, {
       // Header visibility settings
       showFontControls: document.getElementById('appSettingsShowFontControls').checked,
       showSystemStats: document.getElementById('appSettingsShowSystemStats').checked,
+      headerStatsStyle: document.getElementById('appSettingsHeaderStatsStyle').value,
       showLifecycleLog: document.getElementById('appSettingsShowLifecycleLog').checked,
       showResponseViewer: document.getElementById('appSettingsShowResponseViewer').checked,
       showFileViewerButton: document.getElementById('appSettingsShowFileViewerButton').checked,
@@ -2414,6 +2546,7 @@ Object.assign(CodemanApp.prototype, {
       ultracodeFloatingWindows: document.getElementById('appSettingsUltracodeFloatingWindows').checked,
       showMultiMonitorButton: document.getElementById('appSettingsShowMultiMonitorButton').checked,
       showSplitButton: document.getElementById('appSettingsShowSplitButton').checked,
+      showTileGridButton: document.getElementById('appSettingsShowTileGridButton').checked,
       showPlanUsageLimits: document.getElementById('appSettingsShowPlanUsageLimits').checked,
       showRedrawButton: document.getElementById('appSettingsShowRedrawButton').checked,
       mobileOverviewEnabled: document.getElementById('appSettingsMobileOverview').checked,
@@ -2422,6 +2555,11 @@ Object.assign(CodemanApp.prototype, {
       showSessionButton: document.getElementById('appSettingsShowSessionButton').checked,
       showAwayDigestButton: document.getElementById('appSettingsShowAwayDigestButton').checked,
       showCronButton: document.getElementById('appSettingsShowCronButton').checked,
+      showGitStatus: document.getElementById('appSettingsShowGitStatus').checked,
+      gitStatusTree: document.getElementById('appSettingsGitStatusTree').checked,
+      // Clamped here and again on the server; an empty or odd value falls back to the default.
+      gitStatusMaxRepos: Math.min(50, Math.max(1, parseInt(document.getElementById('appSettingsGitStatusMaxRepos').value, 10) || 12)),
+      gitStatusTimeoutSeconds: Math.min(120, Math.max(5, parseInt(document.getElementById('appSettingsGitStatusTimeout').value, 10) || 30)),
       gestureControlEnabled: document.getElementById('appSettingsGestureControl').checked,
       subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
       subagentActiveTabOnly: document.getElementById('appSettingsSubagentActiveTabOnly').checked,
@@ -2440,10 +2578,13 @@ Object.assign(CodemanApp.prototype, {
       webglRendererEnabled: document.getElementById('appSettingsWebglRenderer').checked,
       extendedKeyboardBar: document.getElementById('appSettingsExtendedKeyboardBar').checked,
       tabTwoRows: document.getElementById('appSettingsTabTwoRows').checked,
+      showTabCliLogos: document.getElementById('appSettingsShowTabCliLogos').checked,
       tabOrientation: document.getElementById('appSettingsTabOrientation').value,
       tabRailWidth: this.readTabRailWidthSetting?.() ?? 256,
       tabRailDetail: document.getElementById('appSettingsTabRailDetail').value,
       tabRailSort: document.getElementById('appSettingsTabRailSort').value,
+      tabArrangement: document.getElementById('appSettingsTabArrangement').value,
+      tabStateOrder: document.getElementById('appSettingsTabStateOrder').value,
       showTabDetachButton: document.getElementById('appSettingsShowTabDetachButton').checked,
       sessionListLayout: document.getElementById('appSettingsSessionListLayout').value,
       sessionSidebarFontSize: this.resolveSessionSidebarFontSize(
@@ -2454,6 +2595,8 @@ Object.assign(CodemanApp.prototype, {
       claudeMode: document.getElementById('appSettingsClaudeMode').value,
       allowedTools: document.getElementById('appSettingsAllowedTools').value.trim(),
       // Codex CLI settings
+      codexModel: document.getElementById('appSettingsCodexModel').value.trim(),
+      codexReasoningEffort: document.getElementById('appSettingsCodexReasoningEffort').value,
       codexDangerouslyBypassApprovals: document.getElementById('appSettingsCodexDangerouslyBypassApprovals').checked,
       codexAnimationsEnabled: document.getElementById('appSettingsCodexAnimations').checked,
       // Claude Permissions settings
@@ -2473,6 +2616,15 @@ Object.assign(CodemanApp.prototype, {
       },
     };
 
+    // SettingsUpdateSchema is .strict() and checks codexModel with this same
+    // pattern, so one bad character 400s the WHOLE settings PUT while the toast
+    // still says "Settings saved". Refuse it here, before anything is persisted.
+    if (!/^[A-Za-z0-9._\/-]*$/.test(settings.codexModel)) {
+      this.showToast('Default Codex model may only contain letters, digits, ".", "_", "-" and "/"', 'error');
+      document.getElementById('appSettingsCodexModel')?.focus();
+      return;
+    }
+
     // The "Token Count" / "Show Cost ($)" header toggles were removed from the
     // UI, but their features still read settings.showTokenCount / settings.showCost
     // (applyHeaderVisibilitySettings, the header cost render). saveAppSettings
@@ -2650,6 +2802,9 @@ Object.assign(CodemanApp.prototype, {
       // SettingsUpdateSchema (.strict()) — sending it 400s the whole PUT
       // (moving it into displayKeys alone is not the strip; this is).
       showSplitButton: _ssp,
+      // Same as Split: a per-device header button (and the Tiles chord), absent
+      // from SettingsUpdateSchema (.strict()), so sending it 400s the whole PUT.
+      showTileGridButton: _stg,
       webglRendererEnabled: _wgl,
       terminalWheelLocalScrollback: _twls,
       // Copy-on-select. Per-device (clipboard access differs by device and by
@@ -2674,6 +2829,11 @@ Object.assign(CodemanApp.prototype, {
       showSessionButton: _ssb,
       showAwayDigestButton: _adb,
       showCronButton: _crb,
+      // Per-device bottom-bar indicator, absent from SettingsUpdateSchema (.strict()): it must not reach the PUT.
+      showGitStatus: _sgs,
+      gitStatusTree: _gst,
+      gitStatusMaxRepos: _gsm,
+      gitStatusTimeoutSeconds: _gst2,
       showTabDetachButton: _tdb,
       // Phone-only home surface, and absent from SettingsUpdateSchema (.strict()).
       mobileOverviewEnabled: _mov,
@@ -2681,6 +2841,13 @@ Object.assign(CodemanApp.prototype, {
       // .strict() schema — syncing it would push a desktop-shaped choice onto
       // devices that cannot render it at all.
       sessionLineageLines: _sll,
+      // Keyboard shortcut overrides are per-device (bindings follow the keyboard
+      // and the OS: Cmd on macOS, Ctrl elsewhere) and absent from the .strict()
+      // SettingsUpdateSchema. They used to ride along here, so the first
+      // Shortcuts change on a device (even a Reset, which leaves an empty {})
+      // made EVERY later App Settings save a 400, and every synced key stopped
+      // reaching the server while the toast still said "Settings saved".
+      shortcutOverrides: _sco,
       ...serverSettings
     } = settings;
     let webhookError = '';
@@ -3077,12 +3244,18 @@ Object.assign(CodemanApp.prototype, {
   /** Keep the launch surfaces in sync with Settings mutations without a reload. */
   _syncCliLaunchCatalog() {
     if (!Array.isArray(this._cliList) || this._cliList.length === 0) return;
+    // /api/clis rows carry no capabilities, so keep the served catalog's `external`
+    // (isExternalCliSession() reads it). A new custom CLI has none and falls back to `kind`.
+    const previous = new Map(
+      (Array.isArray(window.__codemanCliCatalog) ? window.__codemanCliCatalog : []).map((cli) => [cli.id, cli])
+    );
     window.__codemanCliCatalog = this._cliList.map((cli) => ({
       id: cli.id,
       label: cli.label,
       shortBadge: cli.shortBadge,
       order: cli.order,
       kind: cli.kind,
+      external: previous.get(cli.id)?.external,
       enabled: cli.enabled,
       available: cli.kind === 'shell' || (cli.enabled && cli.installed),
     }));
@@ -3337,6 +3510,7 @@ Object.assign(CodemanApp.prototype, {
         ultracodeFloatingWindows: false,
         showMultiMonitorButton: false,
         showSplitButton: false,
+        showTileGridButton: false,
         // Desktop defaults this ON (see planUsageChipEnabled); handhelds keep it
         // OFF so the phone header stays minimal and the mobile-header-buttons
         // policy guard keeps passing.
@@ -3361,10 +3535,13 @@ Object.assign(CodemanApp.prototype, {
         imageWatcherEnabled: false,
         ralphTrackerEnabled: false,
         tabTwoRows: false,
+        showTabCliLogos: true,
         tabOrientation: 'horizontal',
         tabRailWidth: 256,
         tabRailDetail: 'rich',
         tabRailSort: 'activity',
+        tabArrangement: 'classic',
+        tabStateOrder: 'urgent-first',
         sessionListLayout: 'header',
         sessionSidebarFontSize: 12,
         cjkInputEnabled: false,
@@ -3375,7 +3552,14 @@ Object.assign(CodemanApp.prototype, {
     }
     // Desktop defaults - rely on ?? operators in apply functions
     // This allows desktop to have different defaults without duplication
-    return {};
+    // A touch-primary tablet (iPad, an Android tablet: not a handheld, so it
+    // lands here) keeps the Tiles button opt-in, as Split is: a tile has none of
+    // the main terminal's touch, IME and soft-keyboard handling. The PRIMARY
+    // pointer decides, never MobileDetection.isTouchDevice(), which is true on a
+    // touchscreen laptop too (fine primary pointer: the desktop default stays).
+    const coarsePrimaryPointer =
+      typeof window !== 'undefined' && window.matchMedia?.('(pointer: coarse)')?.matches === true;
+    return coarsePrimaryPointer ? { showTileGridButton: false } : {};
   },
 
   loadAppSettingsFromStorage() {
@@ -3392,8 +3576,15 @@ Object.assign(CodemanApp.prototype, {
     } catch (err) {
       console.error('Failed to load app settings:', err);
     }
-    // Return device-specific defaults
-    this._cachedAppSettings = this.getDefaultSettings();
+    // Return device-specific defaults, without showTileGridButton: its default
+    // on a non-handheld follows the LIVE primary pointer (getDefaultSettings),
+    // and this object is what a fresh device caches and the server-settings
+    // merge then persists, which would freeze a 2-in-1's first-load posture
+    // into a stored value. Every reader resolves the absent key through a
+    // fresh getDefaultSettings() (?? defaults.showTileGridButton ?? true).
+    const defaults = { ...this.getDefaultSettings() };
+    delete defaults.showTileGridButton;
+    this._cachedAppSettings = defaults;
     return this._cachedAppSettings;
   },
 
@@ -3439,6 +3630,10 @@ Object.assign(CodemanApp.prototype, {
     if (result && this.notificationManager) {
       this.notificationManager.originalTitle = document.title;
     }
+    // The connection tile's value word (Header Stats Style Tiles) is written
+    // already translated into a data-i18n-skip span, so the translator above
+    // cannot revert it; its own language compare makes this one call repaint it.
+    this._updateConnectionIndicator?.();
   },
 
   // Resolved per-device state of the plan-usage chip. Desktop defaults ON,
@@ -3466,6 +3661,91 @@ Object.assign(CodemanApp.prototype, {
     return now === before ? undefined : now;
   },
 
+  /**
+   * The stored tab layout, or the default. Anything but the four known values
+   * (an absent key, a value from a newer build) reads as 'classic', the default:
+   * the single strip as before, the owner's pick on the 1.36.0 beta. 'state'
+   * (Discussion #426, option C), 'case' and 'ledger' are opt-in.
+   */
+  resolveTabArrangement(settings) {
+    const value = settings?.tabArrangement ?? this.getDefaultSettings().tabArrangement;
+    return value === 'state' || value === 'case' || value === 'ledger' ? value : 'classic';
+  },
+
+  /**
+   * CLI Logos on Tabs (`showTabCliLogos`, per-device, default ON on every
+   * device). Anything but an explicit false reads as on, the same test the
+   * pre-paint script in index.html applies, so a reload and a Save never
+   * disagree about an odd stored value.
+   */
+  tabCliLogosEnabled(settings) {
+    return (settings?.showTabCliLogos ?? this.getDefaultSettings().showTabCliLogos) !== false;
+  },
+
+  /** The stored state-group order: 'urgent-last' only when chosen, else 'urgent-first'. */
+  resolveTabStateOrder(settings) {
+    const value = settings?.tabStateOrder ?? this.getDefaultSettings().tabStateOrder;
+    return value === 'urgent-last' ? 'urgent-last' : 'urgent-first';
+  },
+
+  /**
+   * The stored header-stats style, or the default. Anything but the three
+   * known values (an absent key, a value from a newer build) reads as
+   * 'compact', the default (the two-pill ring variant of Discussion #426's
+   * option G, picked by the owner on the 1.36.0 beta over 'tiles').
+   */
+  resolveHeaderStatsStyle(settings) {
+    const value = settings?.headerStatsStyle ?? this.getDefaultSettings().headerStatsStyle;
+    return value === 'classic' || value === 'tiles' ? value : 'compact';
+  },
+
+  /**
+   * Apply a header-stats style: the `data-header-stats` attribute every rule in
+   * the "Header stats styles" block of styles.css keys on, plus the two DOM
+   * moves the clustered styles need.
+   *
+   * The template keeps the classic order, where the connection indicator sits
+   * before the font controls and the plan-usage chip near the end of the header.
+   * Compact and Tiles draw them as ONE cluster (WS · CPU · MEM, then the plan
+   * windows), so the indicator moves into #headerSystemStats as its first child
+   * and the chip moves right after it. Comment anchors left at the template
+   * positions are what 'classic' moves them back to, so switching back restores
+   * the header exactly.
+   *
+   * ⚠️ The indicator only joins the pill while System Stats is shown: the pill
+   * is hidden with `display: none`, and the WS readout must not disappear with
+   * it. Both elements keep their ids, so every writer (setConnectionStatus,
+   * updatePlanUsageChip) finds them wherever they sit.
+   *
+   * @param {{style: 'classic'|'compact'|'tiles', showSystemStats: boolean}} opts
+   */
+  applyHeaderStatsStyle({ style, showSystemStats }) {
+    document.documentElement.dataset.headerStats = style;
+    const stats = document.getElementById('headerSystemStats');
+    const conn = document.getElementById('connectionIndicator');
+    const plan = document.getElementById('planUsageChip');
+    if (!stats || !conn || !plan) return;
+    if (!this._headerStatsAnchors) {
+      const connAnchor = document.createComment(' connection indicator (classic position) ');
+      const planAnchor = document.createComment(' plan usage chip (classic position) ');
+      conn.before(connAnchor);
+      plan.before(planAnchor);
+      this._headerStatsAnchors = { conn: connAnchor, plan: planAnchor };
+    }
+    const anchors = this._headerStatsAnchors;
+    const clustered = style !== 'classic';
+    if (clustered && showSystemStats) {
+      if (stats.firstElementChild !== conn) stats.prepend(conn);
+    } else if (anchors.conn.nextSibling !== conn) {
+      anchors.conn.after(conn);
+    }
+    if (clustered) {
+      if (stats.nextElementSibling !== plan) stats.after(plan);
+    } else if (anchors.plan.nextSibling !== plan) {
+      anchors.plan.after(plan);
+    }
+  },
+
   applyHeaderVisibilitySettings() {
     const settings = this.loadAppSettingsFromStorage();
     const defaults = this.getDefaultSettings();
@@ -3474,7 +3754,11 @@ Object.assign(CodemanApp.prototype, {
     // default OFF, per-device). Mirrored as a class on <html>: styles.css hides
     // .tab-detach without it (a tab that is already detached keeps its icon as
     // the re-focus affordance for the popped-out window).
-    const showTabDetach = settings.showTabDetachButton ?? defaults.showTabDetachButton ?? false;
+    // Under a host that opens windows (see hasHostWindows) popping out is the
+    // way to get two panes side by side, so the button defaults on there.
+    const showTabDetach =
+      this.tabDetachButtonEnabled?.(settings, defaults)
+      ?? (settings.showTabDetachButton ?? defaults.showTabDetachButton ?? false);
     document.documentElement.classList.toggle('tabs-show-detach', showTabDetach);
     const compactHeader = MobileDetection.getDeviceType() !== 'desktop';
     const showFontControls = compactHeader ? false : (settings.showFontControls ?? defaults.showFontControls ?? false);
@@ -3496,6 +3780,12 @@ Object.assign(CodemanApp.prototype, {
     if (tokenCountEl) {
       tokenCountEl.style.display = showTokenCount ? '' : 'none';
     }
+    // After the System Stats visibility above: whether WS joins the stats pill
+    // depends on the pill being shown.
+    this.applyHeaderStatsStyle({
+      style: compactHeader || this.isSoloWindow ? 'classic' : this.resolveHeaderStatsStyle(settings),
+      showSystemStats,
+    });
 
     // Hide lifecycle log button when setting is disabled
     // Default OFF: the lifecycle-log document icon is opt-in; the default header
@@ -3549,6 +3839,10 @@ Object.assign(CodemanApp.prototype, {
     const showSplitButton = settings.showSplitButton ?? defaults.showSplitButton ?? false;
     this._applySplitButtonVisibility?.(showSplitButton);
 
+    // Tiles button: same gate and backstop as Split (tile-grid.js).
+    const showTileGridButton = settings.showTileGridButton ?? defaults.showTileGridButton ?? true;
+    this._applyTileGridButtonVisibility?.(showTileGridButton);
+
     // Ultracode/Workflow agents launcher — hidden by default; reveal when enabled.
     // Marker class only (base is display:inline-flex !important) so it's auto-excluded
     // from the mobile-header-buttons-policy guard.
@@ -3613,6 +3907,10 @@ Object.assign(CodemanApp.prototype, {
       cronBtn.classList.toggle('btn-cron--hidden', !showCronButton);
     }
 
+    // Bottom-bar Git indicator (git-status-ui.js): opt-in, per-device. Starts or stops its poll to
+    // match the setting, so a live toggle needs no reload.
+    this.applyGitStatusVisibility?.();
+
     // Notification bell is retired (notifications live in Settings → Notifications
     // + the drawer); keep it hidden regardless of the notification-enabled state.
     const notifBtn = document.querySelector('.btn-notifications');
@@ -3659,6 +3957,27 @@ Object.assign(CodemanApp.prototype, {
     const sort = (settings.tabRailSort ?? defaults.tabRailSort ?? 'activity') === 'manual' ? 'manual' : 'activity';
     root.dataset.tabRailSort = sort;
 
+    // The tab layout rides on a fourth attribute, for the same reason: it is
+    // applied by the render paths (inline `order` plus headings, or cluster
+    // boxes), so a flip has to re-render, and the gates in app.js
+    // (`isTabTriage()`, `isTabClusters()`, `isTabLedger()`) read one attribute
+    // per pass instead of re-parsing localStorage.
+    const previousArrangement = root.dataset.tabArrangement || 'state';
+    const arrangement = this.resolveTabArrangement(settings);
+    root.dataset.tabArrangement = arrangement;
+    // Which end the state groups start from; read by _tabTriageLayout().
+    const previousStateOrder = root.dataset.tabStateOrder || 'urgent-first';
+    const stateOrder = this.resolveTabStateOrder(settings);
+    root.dataset.tabStateOrder = stateOrder;
+    // CLI Logos on Tabs. Unlike the attributes above this one is pure CSS
+    // (styles.css hides `.tab-harness` and `.home-sessions-harness` under
+    // html[data-tab-logos='off']), so a flip re-renders nothing and stays out
+    // of `changed` below: the logo spans are always in the markup. It still
+    // resizes every agent tab, which the tail of this function settles.
+    const previousLogos = root.dataset.tabLogos;
+    const logos = this.tabCliLogosEnabled(settings) ? 'on' : 'off';
+    root.dataset.tabLogos = logos;
+
     const tabsEl = document.getElementById('sessionTabs');
     const rail = document.getElementById('tabRail');
     const headerHost = document.getElementById('sessionTabsHost');
@@ -3682,7 +4001,7 @@ Object.assign(CodemanApp.prototype, {
     // the row template, not toggled by CSS — same reasoning as the sidebar's
     // detail half in applySessionListLayout(). Taller rows also move every
     // connector anchored to a tab rect.
-    const changed = orientationChanged || previousDetail !== detail || previousSort !== sort;
+    const changed = orientationChanged || previousDetail !== detail || previousSort !== sort || previousArrangement !== arrangement || previousStateOrder !== stateOrder;
     if (orientationChanged) {
       this.updateTabOverflowMode?.();
       if (!settleRailWidth) this.syncTerminalGeometry?.();
@@ -3707,6 +4026,14 @@ Object.assign(CodemanApp.prototype, {
       if (!wrapRendered) this._fullRenderSessionTabs?.();
       this._updateConnectionLinesImmediate?.();
       this._refreshHomeSessionsIfVisible?.();
+    } else if (previousLogos !== logos) {
+      // A logo flip narrows or widens every agent tab with no render behind
+      // it, so re-take what a render would have: the strip's one-row wrap
+      // decision and the lines anchored to tab rects (lineage, subagent
+      // connectors). A header that gains or loses a row resizes the terminal
+      // container, whose ResizeObserver (terminal-ui.js) owns the PTY geometry.
+      this.updateTabOverflowMode?.();
+      this._updateConnectionLinesImmediate?.();
     }
     // Only detailed rows carry stamps that go stale with no event behind them.
     // _fullRenderSessionTabs() settles this too, but applyTabOrientation() runs
@@ -3952,20 +4279,21 @@ Object.assign(CodemanApp.prototype, {
         // NOTE: Feature toggles (subagentTrackingEnabled, imageWatcherEnabled, ralphTrackerEnabled)
         // are NOT display keys — they control server-side behavior and must sync from server.
         const displayKeys = new Set([
-          'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
+          'showFontControls', 'showSystemStats', 'headerStatsStyle', 'showTokenCount', 'showCost',
           'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
           'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
-          'subagentActiveTabOnly', 'tabTwoRows', 'tabOrientation', 'tabRailWidth', 'tabRailDetail', 'tabRailSort', 'sessionListLayout', 'sessionSidebarFontSize', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
+          'subagentActiveTabOnly', 'tabTwoRows', 'showTabCliLogos', 'tabOrientation', 'tabRailWidth', 'tabRailDetail', 'tabRailSort', 'tabArrangement', 'tabStateOrder', 'sessionListLayout', 'sessionSidebarFontSize', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
           'skin', 'showPlanUsageLimits', 'showAttachmentsButton', 'showFileViewerButton', 'webglRendererEnabled',
           'terminalFontFamily', 'terminalFontWeight', 'terminalFontWeightBold',
           'language',
           'terminalWheelLocalScrollback',
           'autoCopySelection', 'copyStripMargin',
-          'showSessionButton', 'showAwayDigestButton', 'showCronButton',
+          'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds',
           'showTabDetachButton',
           'mobileOverviewEnabled',
           'sessionLineageLines',
           'showSplitButton',
+          'showTileGridButton',
         ]);
         // The plan-usage chip is a PER-DEVICE display setting (desktop default ON,
         // handheld default OFF): desktop can show it while mobile stays hidden. Drop
@@ -4373,4 +4701,5 @@ document.addEventListener?.('codeman:me', () => {
   window.app?._applyCustomModelAdminGate?.();
   window.app?._applyCliManagementAdminGate?.();
   window.app?._applyMcpSyncAdminGate?.();
+  window.app?._applyDoctorAdminGate?.();
 });

src/web/public/spreadsheet-preview-worker.js

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Same-origin XLSX parsing worker for the file-preview overlay.
+ *
+ * Runs off the main thread and is the ONLY place the spreadsheet vendor bundles
+ * load: fflate + the pure core at worker start, ExcelJS only after the ZIP has
+ * passed `admitXlsx()` (entry/inflate/ratio/cell/style caps). ExcelJS is then
+ * given a STORE-only archive rebuilt from the entries admission inflated, never
+ * the fetched bytes, so it can only parse what admission counted. The page never
+ * loads either vendor file. Cell values are sent back as plain strings; the
+ * renderer writes them with `textContent`. Formulas are never evaluated (the
+ * cached result is shown, else the formula text), and nothing here fetches:
+ * external links, images and drawings are reported as unsupported features.
+ *
+ * Script URLs are RELATIVE so they resolve against this worker's own URL, which
+ * keeps a reverse-proxy `--base-url` mount working.
+ */
+
+'use strict';
+
+const spreadsheetAssetVersion = new URL(self.location.href).searchParams.get('v') || 'dev';
+const spreadsheetAssetQuery = `?v=${encodeURIComponent(spreadsheetAssetVersion)}`;
+importScripts(`vendor/fflate.min.js${spreadsheetAssetQuery}`, `spreadsheet-xlsx-core.js${spreadsheetAssetQuery}`);
+
+const core = self.CodemanSpreadsheetXlsxCore;
+let workbook = null;
+let sheetsById = new Map();
+// Per sheet: its populated rows in order, each with its populated cells in
+// column order, built once at load from the keys that exist (`populatedRowIndex`).
+let populatedRowsById = new Map();
+// Merges read once at load: `sheet.model` rebuilds every row and cell model,
+// which is far too much to pay on every tile.
+let mergesById = new Map();
+let normalizedStyles = [];
+let styleIds = new Map();
+let themePalette = core.DEFAULT_THEME_PALETTE;
+
+function postError(error) {
+  self.postMessage({
+    type: 'error',
+    code: error?.code || 'parse-failed',
+    message: error?.message || 'Spreadsheet preview failed',
+  });
+}
+
+// Maximum cells in one tile reply; the renderer draws at most this many too.
+const MAX_TILE_CELLS = 2500;
+
+// ExcelJS keeps the workbook's raw theme XML on `_themes.theme1`; the admitted
+// entry is the fallback and the default Office palette is the last resort.
+function readThemeXml(loadedWorkbook, admittedEntries) {
+  const stashed = loadedWorkbook?._themes?.theme1;
+  if (typeof stashed === 'string' && stashed.length > 0) return stashed;
+  const theme = admittedEntries?.['xl/theme/theme1.xml'];
+  return theme ? new TextDecoder().decode(theme) : '';
+}
+
+function normalizeStyle(cell) {
+  // Colours are resolved and contrast-checked as a PAIR. Emitting a
+  // font colour without its background lets workbook text land on the skin's
+  // `var(--bg-primary)` and disappear.
+  const colors = core.resolveCellColors(cell.fill?.fgColor, cell.font?.color, themePalette);
+  const style = {
+    font: {
+      bold: Boolean(cell.font?.bold),
+      italic: Boolean(cell.font?.italic),
+      color: colors.foreground,
+    },
+    fill: colors.background,
+    alignment: ['left', 'center', 'right'].includes(cell.alignment?.horizontal) ? cell.alignment.horizontal : undefined,
+    wrapText: Boolean(cell.alignment?.wrapText),
+  };
+  const key = JSON.stringify(style);
+  if (styleIds.has(key)) return styleIds.get(key);
+  if (normalizedStyles.length >= core.LIMITS.maxStyles) {
+    throw new core.XlsxPreviewError('style-limit', 'Workbook exceeds the normalized styles limit');
+  }
+  const id = normalizedStyles.length;
+  normalizedStyles.push(style);
+  styleIds.set(key, id);
+  return id;
+}
+
+// Ascending numeric own keys of a sparse array. ExcelJS keeps rows at
+// `_rows[r - 1]` and a row's cells at `_cells[col - 1]`, and one far index puts
+// the array in dictionary mode, where its own `eachRow`, `eachCell` and
+// `hasValues` (forEach/some) visit every index up to the largest: a single XFD
+// cell per row costs 16,384 steps a row. Walking the keys that exist does not.
+function presentIndices(sparse) {
+  const indices = [];
+  for (const key of Object.keys(sparse || [])) {
+    const index = Number(key);
+    if (Number.isInteger(index) && index >= 0) indices.push(index);
+  }
+  return indices.sort((a, b) => a - b);
+}
+
+// The rows and cells `sheet.eachRow({ includeEmpty: false })` and
+// `row.eachCell({ includeEmpty: false })` would visit, in the same order: a
+// cell counts when it exists and its type is not `ValueType.Null`, and a row
+// counts when it holds at least one such cell (ExcelJS's `row.hasValues`).
+function populatedRowIndex(sheet) {
+  const nullType = self.ExcelJS.ValueType.Null;
+  const rows = [];
+  for (const rowIndex of presentIndices(sheet._rows)) {
+    const row = sheet._rows[rowIndex];
+    if (!row) continue;
+    const cells = [];
+    for (const cellIndex of presentIndices(row._cells)) {
+      const cell = row._cells[cellIndex];
+      if (cell && cell.type !== nullType) cells.push(cell);
+    }
+    if (cells.length > 0) rows.push({ number: row.number, row, cells });
+  }
+  return rows;
+}
+
+function worksheetMetadata(sheet) {
+  const cellRefs = [];
+  const rowOverrides = [];
+  const populatedRows = populatedRowIndex(sheet);
+  for (const { number, row, cells } of populatedRows) {
+    for (const cell of cells) {
+      cellRefs.push(cell.address);
+      normalizeStyle(cell);
+    }
+    if (row.hidden) rowOverrides.push([number, 0]);
+    else if (row.height) rowOverrides.push([number, Math.min(546, Math.max(0, row.height * (4 / 3)))]);
+  }
+  // `sheet.model` rebuilds every row and cell model, so merges come straight
+  // from ExcelJS's own merge map, in the order the model getter would list them.
+  const merges = Object.values(sheet._merges || {}).map((merge) => merge.range);
+  const extent = core.deriveExtent(cellRefs, merges);
+  const columnOverrides = [];
+  for (let col = 1; col <= extent.cols; col += 1) {
+    const column = sheet.getColumn(col);
+    if (column.hidden) columnOverrides.push([col, 0]);
+    else if (column.width) columnOverrides.push([col, Math.min(1785, Math.max(0, column.width * 7))]);
+  }
+  return {
+    populatedRows,
+    merges,
+    metadata: {
+      id: String(sheet.id),
+      name: sheet.name,
+      rows: extent.rows,
+      cols: extent.cols,
+      defaultRowHeight: Math.min(546, Math.max(1, (sheet.properties?.defaultRowHeight || 15) * (4 / 3))),
+      defaultColumnWidth: Math.min(1785, Math.max(1, (sheet.properties?.defaultColWidth || 9.14) * 7)),
+      rowOverrides,
+      columnOverrides,
+      merges,
+    },
+  };
+}
+
+function cellDisplay(cell, date1904, warnings) {
+  const formatted = core.formatCellValue(cell.value, cell.numFmt || 'General', date1904);
+  if (formatted.warning) warnings.add(formatted.warning);
+  return formatted.text;
+}
+
+async function loadWorkbook(bytes) {
+  const admission = core.admitXlsx(new Uint8Array(bytes), self.fflate);
+  const admitted = core.buildAdmittedArchive(admission, self.fflate);
+  if (!self.ExcelJS) importScripts(`vendor/exceljs.min.js${spreadsheetAssetQuery}`);
+  const nextWorkbook = new self.ExcelJS.Workbook();
+  // ExcelJS's DefinedNames model setter expands every range into one object per
+  // cell (a whole-sheet name exhausts the heap), and admission reads only the
+  // `<sheet>` ids in xl/workbook.xml, never defined names. The preview never shows defined names, so they are not
+  // stored at all; print areas and titles are split off before this setter runs.
+  // defineProperty throws if a future ExcelJS renames `_definedNames`, rather
+  // than silently expanding again.
+  Object.defineProperty(nextWorkbook._definedNames, 'model', { configurable: true, get: () => [], set: () => {} });
+  // ExcelJS expands every address of a `<dataValidation sqref>` into its own
+  // object (a whole-column dropdown is a million), and the preview never shows
+  // validations, so they are not parsed at all. `maxRows` is a per-sheet
+  // backstop behind admission's row count, which also caps the workbook total.
+  await nextWorkbook.xlsx.load(admitted, {
+    ignoreNodes: ['dataValidations'],
+    maxRows: core.LIMITS.maxRowsPerSheet,
+  });
+  const nextSheets = new Map();
+  const nextRows = new Map();
+  const nextMerges = new Map();
+  normalizedStyles = [];
+  styleIds = new Map();
+  themePalette = core.parseThemePalette(readThemeXml(nextWorkbook, admission.entries));
+  const sheets = [];
+  for (const sheet of nextWorkbook.worksheets) {
+    if (sheet.state === 'hidden' || sheet.state === 'veryHidden') continue;
+    const sheetResult = worksheetMetadata(sheet);
+    const metadata = sheetResult.metadata;
+    nextSheets.set(metadata.id, sheet);
+    nextRows.set(metadata.id, sheetResult.populatedRows);
+    nextMerges.set(metadata.id, sheetResult.merges);
+    sheets.push(metadata);
+  }
+  workbook = nextWorkbook;
+  sheetsById = nextSheets;
+  populatedRowsById = nextRows;
+  mergesById = nextMerges;
+  self.postMessage({
+    type: 'metadata',
+    sheets,
+    styles: normalizedStyles,
+    date1904: Boolean(workbook.properties?.date1904),
+    empty: sheets.length === 0,
+    warnings: admission.features,
+  });
+}
+
+function sendTile(message) {
+  if (!workbook) throw new Error('Workbook is not loaded');
+  const sheet = sheetsById.get(String(message.sheetId));
+  if (!sheet) throw new Error('Worksheet is unavailable');
+  const range = message.range;
+  const warnings = new Set();
+  const cells = [];
+  const seenCells = new Set();
+  let truncated = false;
+  // Hidden rows and columns are 0 px, so a viewport can span thousands of them
+  // (a filtered sheet); they are never drawn, so never sent.
+  const hiddenColumns = new Map();
+  const columnHidden = (col) => {
+    if (!hiddenColumns.has(col)) hiddenColumns.set(col, Boolean(sheet.getColumn(col).hidden));
+    return hiddenColumns.get(col);
+  };
+  const addCell = (cell) => {
+    const key = `${cell.row}:${cell.col}`;
+    if (seenCells.has(key) || (cell.isMerged && cell.master !== cell)) return;
+    if (sheet.getRow(cell.row).hidden || columnHidden(cell.col)) return;
+    if (cells.length >= MAX_TILE_CELLS) {
+      truncated = true;
+      return;
+    }
+    seenCells.add(key);
+    cells.push({
+      row: cell.row,
+      col: cell.col,
+      text: cellDisplay(cell, Boolean(workbook.properties?.date1904), warnings),
+      styleId: normalizeStyle(cell),
+    });
+  };
+  const populatedRows = populatedRowsById.get(String(message.sheetId)) || [];
+  for (const populated of populatedRows) {
+    if (truncated) break;
+    if (populated.number < range.r1) continue;
+    if (populated.number > range.r2) break;
+    if (populated.row.hidden) continue;
+    for (const cell of populated.cells) {
+      if (cell.col < range.c1) continue;
+      if (cell.col > range.c2) break;
+      addCell(cell);
+    }
+  }
+  const merges = core.intersectingMerges(mergesById.get(String(message.sheetId)) || [], range);
+  for (const merge of merges) {
+    const anchor = core.parseRange(merge);
+    if (anchor) addCell(sheet.getCell(anchor.r1, anchor.c1));
+  }
+  if (truncated) warnings.add(`View truncated to the first ${MAX_TILE_CELLS} cells`);
+  self.postMessage({
+    type: 'tile',
+    requestId: message.requestId,
+    sheetId: String(message.sheetId),
+    cells,
+    merges,
+    // One counted entry for many unsupported number formats keeps the notice bar short.
+    warnings: core.foldWarnings(Array.from(warnings)),
+  });
+}
+
+self.onmessage = async (event) => {
+  try {
+    const message = event.data || {};
+    if (message.type === 'load') await loadWorkbook(message.bytes);
+    else if (message.type === 'tile') sendTile(message);
+    else if (message.type === 'dispose') {
+      workbook = null;
+      sheetsById = new Map();
+      populatedRowsById = new Map();
+      mergesById = new Map();
+      themePalette = core.DEFAULT_THEME_PALETTE;
+    }
+  } catch (error) {
+    postError(error);
+  }
+};
+
+self.postMessage({ type: 'ready' });

src/web/public/spreadsheet-preview.js

@@ -0,0 +1,555 @@
+/**
+ * @fileoverview Read-only, virtualized XLSX preview for the file-preview overlay.
+ *
+ * `CodemanSpreadsheetPreview.open({ container, url, size })` fetches the workbook
+ * bytes (same-origin only, `?preview=true` so the server applies its 10 MB
+ * preview cap), hands them to spreadsheet-preview-worker.js, and renders only
+ * the visible tile of cells. Parsing happens entirely in the browser worker; the
+ * server just streams the file through its existing confined raw routes.
+ *
+ * Every workbook string (cell text, sheet names) is written with `textContent`,
+ * never markup. The per-style `<style>` block only emits validated `#rrggbb`
+ * colours and a fixed set of keywords. `dispose()` aborts the fetch and
+ * terminates the worker; panels-ui.js calls it whenever the overlay is reused
+ * or closed.
+ *
+ * @dependency constants.js (CodemanBase.url for the worker URL under --base-url)
+ * @loadorder 16.5 (after image-input.js; only defines a global, used on demand)
+ */
+
+(function initSpreadsheetPreview(global) {
+  'use strict';
+
+  const SPREADSHEET_ASSET_VERSION = '911680fac09d';
+  const MAX_PREVIEW_BYTES = 10 * 1024 * 1024;
+  const DEFAULT_TIMEOUT_MS = 20000;
+  const MAX_SCROLL_PX = 8000000;
+  const ROW_HEADING_WIDTH = 36;
+  const COLUMN_HEADING_HEIGHT = 20;
+  const assets = Object.freeze({
+    version: SPREADSHEET_ASSET_VERSION,
+    workerUrl: `/spreadsheet-preview-worker.js?v=${SPREADSHEET_ASSET_VERSION}`,
+  });
+
+  // What a refusal from the worker says on screen. The core's own messages
+  // (spreadsheet-xlsx-core.js) are developer detail, so each error code maps to
+  // one sentence with a zh-CN entry in i18n.js, and the raw message goes to the
+  // console. Any other code (parse-failed carries ExcelJS's own exception text)
+  // shows the generic failure.
+  const TOO_LARGE_OR_COMPLEX = 'This workbook is too large or complex to preview.';
+  const UNREADABLE = 'This workbook could not be read. The file may be damaged or not a valid .xlsx file.';
+  const WORKER_ERROR_TEXT = Object.freeze({
+    encrypted: 'This workbook is password-protected or in the old .xls format, so it cannot be previewed.',
+    zip64: 'This workbook uses ZIP64, which the preview does not support.',
+    malformed: UNREADABLE,
+    'number-format': UNREADABLE,
+    'entry-limit': TOO_LARGE_OR_COMPLEX,
+    'entry-size': TOO_LARGE_OR_COMPLEX,
+    'inflated-size': TOO_LARGE_OR_COMPLEX,
+    'compression-ratio': TOO_LARGE_OR_COMPLEX,
+    'worksheet-limit': TOO_LARGE_OR_COMPLEX,
+    'element-limit': TOO_LARGE_OR_COMPLEX,
+    'row-limit': TOO_LARGE_OR_COMPLEX,
+    'cell-limit': TOO_LARGE_OR_COMPLEX,
+    'merge-limit': TOO_LARGE_OR_COMPLEX,
+    'style-limit': TOO_LARGE_OR_COMPLEX,
+  });
+
+  // The workbook features the preview leaves out, as the core names them
+  // (featureForName), in words for the notice bar.
+  const FEATURE_LABELS = Object.freeze({
+    charts: 'charts',
+    drawings: 'drawings',
+    pivotTables: 'pivot tables',
+    externalLinks: 'external links',
+    macros: 'macros',
+  });
+  const UNSUPPORTED_FORMAT_PREFIX = 'Unsupported number format: ';
+
+  function translate(text) {
+    return global.codemanT?.(text) || text;
+  }
+
+  function own(map, key) {
+    return Object.prototype.hasOwnProperty.call(map, key);
+  }
+
+  function workerErrorText(payload) {
+    const code = String(payload?.code || '');
+    if (payload?.message) console.warn(`Spreadsheet preview: ${code || 'error'}: ${payload.message}`);
+    return own(WORKER_ERROR_TEXT, code) ? WORKER_ERROR_TEXT[code] : 'Spreadsheet preview failed';
+  }
+
+  // One notice bar item, translated on its own (the bar is one text node, which
+  // the i18n layer could only match whole; the bar itself carries
+  // data-i18n-skip). A number format's code is workbook text: it is appended
+  // as is, never passed through the translator, which would read a `{…}` in it
+  // as a placeholder. A feature word goes through its scoped
+  // 'Spreadsheet feature: <word>' key and reads as the plain word when that key
+  // has no translation: a bare 'charts' key would also rename a charts/ folder.
+  function warningText(warning) {
+    const text = String(warning);
+    if (text.startsWith(UNSUPPORTED_FORMAT_PREFIX)) {
+      return `${translate('Unsupported number format')}: ${text.slice(UNSUPPORTED_FORMAT_PREFIX.length)}`;
+    }
+    if (own(FEATURE_LABELS, text)) {
+      const label = FEATURE_LABELS[text];
+      const key = `Spreadsheet feature: ${label}`;
+      const translated = translate(key);
+      return translated !== key ? translated : label;
+    }
+    return translate(text);
+  }
+
+  function message(container, text, kind) {
+    container.textContent = '';
+    const state = document.createElement('div');
+    state.className = `spreadsheet-preview-message ${kind || ''}`.trim();
+    state.textContent = text;
+    container.appendChild(state);
+  }
+
+  function safePreviewUrl(candidate) {
+    const url = new URL(candidate, global.location.href);
+    if (url.origin !== global.location.origin) throw new Error('Spreadsheet preview must use a same-origin URL');
+    url.searchParams.set('preview', 'true');
+    return `${url.pathname}${url.search}${url.hash}`;
+  }
+
+  function open(options) {
+    const container = options.container;
+    const isCurrent = typeof options.isCurrent === 'function' ? options.isCurrent : () => true;
+    let disposed = false;
+    let worker = null;
+    let controller = null;
+    let timer = null;
+    let metadata = null;
+    let activeSheetId = null;
+    let latestRequestId = 0;
+    let grid = null;
+    let spacer = null;
+    let cellsLayer = null;
+    let headingsLayer = null;
+    let emptySheetState = null;
+    let resizeObserver = null;
+    let latestRange = null;
+    let latestAxes = null;
+    let scrollFrame = null;
+
+    const current = () => !disposed && isCurrent();
+    const clearTimer = () => {
+      if (timer !== null) global.clearTimeout(timer);
+      timer = null;
+    };
+    const fail = (text) => {
+      if (!current()) return;
+      clearTimer();
+      message(container, text || 'Spreadsheet preview failed', 'error');
+    };
+
+    function sheetMetadata() {
+      return metadata?.sheets.find((sheet) => String(sheet.id) === String(activeSheetId));
+    }
+
+    // Prefix sums per override list, built once per sheet's axis: renderTile
+    // asks for several offsets per cell, so a linear walk over every override
+    // (one per row on a sheet with explicit heights) made each tile O(n) per cell.
+    const axisDeltas = new WeakMap();
+
+    function overrideDeltas(overrides, defaultSize) {
+      let entry = axisDeltas.get(overrides);
+      if (!entry || entry.defaultSize !== defaultSize) {
+        const deltas = [];
+        let delta = 0;
+        for (const [, size] of overrides) {
+          delta += size - defaultSize;
+          deltas.push(delta);
+        }
+        entry = { defaultSize, deltas };
+        axisDeltas.set(overrides, entry);
+      }
+      return entry.deltas;
+    }
+
+    function axisOffset(count, defaultSize, overrides, index) {
+      const bounded = Math.max(1, Math.min(count + 1, index));
+      const list = overrides || [];
+      let low = 0;
+      let high = list.length;
+      while (low < high) {
+        const mid = (low + high) >> 1;
+        if (list[mid][0] < bounded) low = mid + 1;
+        else high = mid;
+      }
+      return (bounded - 1) * defaultSize + (low ? overrideDeltas(list, defaultSize)[low - 1] : 0);
+    }
+
+    function axisIndex(count, defaultSize, overrides, offset) {
+      let low = 1;
+      let high = Math.max(1, count);
+      while (low < high) {
+        const mid = Math.floor((low + high + 1) / 2);
+        if (axisOffset(count, defaultSize, overrides, mid) <= offset) low = mid;
+        else high = mid - 1;
+      }
+      return low;
+    }
+
+    // Past MAX_SCROLL_PX the spacer is shorter than the sheet, so only the
+    // scroll POSITION is scaled (the scroll range maps onto the sheet's whole
+    // range, so the last row stays reachable) and the tile is laid out at real
+    // sizes from there. `shift` is the logical offset minus the scroll offset,
+    // 0 when the sheet fits; `end` is the bottom (or right) of the spacer.
+    function scrollAxis(logical, scroll, viewport, heading) {
+      const shown = Math.min(MAX_SCROLL_PX, logical);
+      const scrollRange = Math.max(0, heading + shown - viewport);
+      const logicalRange = Math.max(0, heading + logical - viewport);
+      const virtual =
+        logical > shown && scrollRange > 0 ? Math.min(logicalRange, (scroll / scrollRange) * logicalRange) : scroll;
+      return { virtual, shift: virtual - scroll, end: heading + shown };
+    }
+
+    function requestTile() {
+      if (!current() || !worker || !grid) return;
+      const sheet = sheetMetadata();
+      if (!sheet || sheet.rows === 0 || sheet.cols === 0) return;
+      const viewHeight = grid.clientHeight || 500;
+      const viewWidth = grid.clientWidth || 800;
+      const y = scrollAxis(
+        axisOffset(sheet.rows, sheet.defaultRowHeight, sheet.rowOverrides, sheet.rows + 1),
+        grid.scrollTop,
+        viewHeight,
+        COLUMN_HEADING_HEIGHT
+      );
+      const x = scrollAxis(
+        axisOffset(sheet.cols, sheet.defaultColumnWidth, sheet.columnOverrides, sheet.cols + 1),
+        grid.scrollLeft,
+        viewWidth,
+        ROW_HEADING_WIDTH
+      );
+      const r1 = Math.max(
+        1,
+        axisIndex(
+          sheet.rows,
+          sheet.defaultRowHeight,
+          sheet.rowOverrides,
+          Math.max(0, y.virtual - COLUMN_HEADING_HEIGHT)
+        ) - 2
+      );
+      const c1 = Math.max(
+        1,
+        axisIndex(
+          sheet.cols,
+          sheet.defaultColumnWidth,
+          sheet.columnOverrides,
+          Math.max(0, x.virtual - ROW_HEADING_WIDTH)
+        ) - 2
+      );
+      const r2 = Math.min(
+        sheet.rows,
+        axisIndex(
+          sheet.rows,
+          sheet.defaultRowHeight,
+          sheet.rowOverrides,
+          Math.max(0, y.virtual - COLUMN_HEADING_HEIGHT + viewHeight)
+        ) + 2
+      );
+      const c2 = Math.min(
+        sheet.cols,
+        axisIndex(
+          sheet.cols,
+          sheet.defaultColumnWidth,
+          sheet.columnOverrides,
+          Math.max(0, x.virtual - ROW_HEADING_WIDTH + viewWidth)
+        ) + 2
+      );
+      latestRequestId += 1;
+      latestRange = { r1, c1, r2, c2 };
+      latestAxes = { y, x };
+      worker.postMessage({
+        type: 'tile',
+        requestId: latestRequestId,
+        sheetId: String(activeSheetId),
+        range: { r1, c1, r2, c2 },
+      });
+    }
+
+    function renderWarnings(tileWarnings) {
+      const notice = container.querySelector('.spreadsheet-preview-notice');
+      if (!notice) return;
+      const warnings = [...(metadata?.warnings || []), ...(tileWarnings || [])];
+      notice.hidden = warnings.length === 0;
+      const warningLabel = translate('Some workbook features are not shown');
+      notice.textContent = warnings.length ? `${warningLabel}: ${warnings.map(warningText).join(', ')}` : '';
+    }
+
+    function pinHeadings() {
+      if (!grid || !headingsLayer) return;
+      headingsLayer.querySelectorAll('.spreadsheet-row-heading').forEach((heading) => {
+        heading.style.left = `${grid.scrollLeft}px`;
+      });
+      headingsLayer.querySelectorAll('.spreadsheet-column-heading').forEach((heading) => {
+        heading.style.top = `${grid.scrollTop}px`;
+      });
+    }
+
+    function renderTile(tile) {
+      if (!current() || tile.requestId !== latestRequestId || String(tile.sheetId) !== String(activeSheetId)) return;
+      const sheet = sheetMetadata();
+      if (!sheet || !cellsLayer || !headingsLayer || !latestRange || !latestAxes) return;
+      const { y, x } = latestAxes;
+      // Sizes are real; a span (a tall merge) is clipped at the spacer's edge so
+      // it never grows the scroll area.
+      const rowTop = (row) =>
+        COLUMN_HEADING_HEIGHT + axisOffset(sheet.rows, sheet.defaultRowHeight, sheet.rowOverrides, row) - y.shift;
+      const colLeft = (col) =>
+        ROW_HEADING_WIDTH + axisOffset(sheet.cols, sheet.defaultColumnWidth, sheet.columnOverrides, col) - x.shift;
+      const rowSpan = (from, to) => Math.max(0, Math.min(rowTop(to + 1), y.end) - rowTop(from));
+      const colSpan = (from, to) => Math.max(0, Math.min(colLeft(to + 1), x.end) - colLeft(from));
+      cellsLayer.textContent = '';
+      headingsLayer.textContent = '';
+      const mergeByAnchor = new Map();
+      for (const merge of tile.merges || []) {
+        const match = /^([A-Z]+)(\d+):([A-Z]+)(\d+)$/i.exec(merge);
+        if (!match) continue;
+        const column = (letters) =>
+          [...letters.toUpperCase()].reduce((value, char) => value * 26 + char.charCodeAt(0) - 64, 0);
+        mergeByAnchor.set(`${Number(match[2])}:${column(match[1])}`, {
+          r2: Number(match[4]),
+          c2: column(match[3]),
+        });
+      }
+      for (const cell of tile.cells.slice(0, 2500)) {
+        const merge = mergeByAnchor.get(`${cell.row}:${cell.col}`);
+        const height = rowSpan(cell.row, merge?.r2 || cell.row);
+        const width = colSpan(cell.col, merge?.c2 || cell.col);
+        // A cell clipped to nothing at the spacer's edge (or sized 0 px) is
+        // skipped like its heading: padding and border would still draw it as a
+        // small box below the spacer and grow the scroll area.
+        if (height <= 0 || width <= 0) continue;
+        const element = document.createElement('div');
+        element.className = `spreadsheet-cell spreadsheet-style-${Number(cell.styleId) || 0}`;
+        element.dataset.row = String(cell.row);
+        element.dataset.col = String(cell.col);
+        element.textContent = String(cell.text ?? '');
+        element.style.top = `${rowTop(cell.row)}px`;
+        element.style.left = `${colLeft(cell.col)}px`;
+        element.style.height = `${height}px`;
+        element.style.width = `${width}px`;
+        cellsLayer.appendChild(element);
+      }
+      // Headings take their size from the same axis math as the cells, so custom
+      // widths/heights line up; hidden (0 px) rows and columns get no heading and
+      // do not count against the heading caps.
+      let rowHeadings = 0;
+      for (let row = latestRange.r1; row <= latestRange.r2 && rowHeadings < 200; row += 1) {
+        const height = rowSpan(row, row);
+        if (height <= 0) continue;
+        rowHeadings += 1;
+        const heading = document.createElement('div');
+        heading.className = 'spreadsheet-row-heading';
+        heading.textContent = String(row);
+        heading.style.top = `${rowTop(row)}px`;
+        heading.style.height = `${height}px`;
+        heading.style.left = `${grid.scrollLeft}px`;
+        headingsLayer.appendChild(heading);
+      }
+      let columnHeadings = 0;
+      for (let col = latestRange.c1; col <= latestRange.c2 && columnHeadings < 100; col += 1) {
+        const width = colSpan(col, col);
+        if (width <= 0) continue;
+        columnHeadings += 1;
+        const heading = document.createElement('div');
+        heading.className = 'spreadsheet-column-heading';
+        let label = '';
+        for (let value = col; value > 0; value = Math.floor((value - 1) / 26))
+          label = String.fromCharCode(65 + ((value - 1) % 26)) + label;
+        heading.textContent = label;
+        heading.style.left = `${colLeft(col)}px`;
+        heading.style.width = `${width}px`;
+        heading.style.top = `${grid.scrollTop}px`;
+        headingsLayer.appendChild(heading);
+      }
+      renderWarnings(tile.warnings);
+    }
+
+    function selectSheet(sheetId) {
+      if (!current() || !metadata?.sheets.some((sheet) => String(sheet.id) === String(sheetId))) return;
+      activeSheetId = String(sheetId);
+      latestRequestId += 1;
+      latestRange = null;
+      latestAxes = null;
+      if (cellsLayer) cellsLayer.textContent = '';
+      if (headingsLayer) headingsLayer.textContent = '';
+      container.querySelectorAll('[role="tab"]').forEach((tab) => {
+        const selected = tab.dataset.sheetId === activeSheetId;
+        tab.setAttribute('aria-selected', String(selected));
+        tab.tabIndex = selected ? 0 : -1;
+      });
+      if (grid) {
+        grid.scrollTop = 0;
+        grid.scrollLeft = 0;
+      }
+      const sheet = sheetMetadata();
+      if (sheet && spacer) {
+        const logicalHeight = axisOffset(sheet.rows, sheet.defaultRowHeight, sheet.rowOverrides, sheet.rows + 1);
+        const logicalWidth = axisOffset(sheet.cols, sheet.defaultColumnWidth, sheet.columnOverrides, sheet.cols + 1);
+        spacer.style.height = `${COLUMN_HEADING_HEIGHT + Math.min(MAX_SCROLL_PX, logicalHeight)}px`;
+        spacer.style.width = `${ROW_HEADING_WIDTH + Math.min(MAX_SCROLL_PX, logicalWidth)}px`;
+      }
+      if (emptySheetState) emptySheetState.hidden = Boolean(sheet?.rows && sheet?.cols);
+      renderWarnings([]);
+      requestTile();
+    }
+
+    function renderMetadata(nextMetadata) {
+      if (!current()) return;
+      metadata = nextMetadata;
+      container.textContent = '';
+      if (!metadata.sheets?.length) {
+        message(container, 'This workbook has no visible worksheets.', 'empty');
+        return;
+      }
+      const shell = document.createElement('div');
+      shell.className = 'spreadsheet-preview-shell';
+      const styleSheet = document.createElement('style');
+      styleSheet.textContent = (metadata.styles || [])
+        .map((style, id) => {
+          const declarations = [];
+          if (style.font?.bold) declarations.push('font-weight:700');
+          if (style.font?.italic) declarations.push('font-style:italic');
+          // Colour and background are emitted together or not at all.
+          // The worker already contrast-checked them as a pair; contributing
+          // one half would drop the cell back onto the skin's own background.
+          if (/^#[a-f0-9]{6}$/i.test(style.font?.color || '') && /^#[a-f0-9]{6}$/i.test(style.fill || '')) {
+            declarations.push(`color:${style.font.color}`, `background-color:${style.fill}`);
+          }
+          if (['left', 'center', 'right'].includes(style.alignment)) declarations.push(`text-align:${style.alignment}`);
+          if (style.wrapText) declarations.push('white-space:normal');
+          return `.spreadsheet-style-${id}{${declarations.join(';')}}`;
+        })
+        .join('');
+      const tabs = document.createElement('div');
+      tabs.className = 'spreadsheet-sheet-tabs';
+      tabs.setAttribute('role', 'tablist');
+      tabs.setAttribute('data-i18n-skip', '');
+      for (const sheet of metadata.sheets) {
+        const tab = document.createElement('button');
+        tab.type = 'button';
+        tab.className = 'spreadsheet-sheet-tab';
+        tab.setAttribute('role', 'tab');
+        tab.dataset.sheetId = String(sheet.id);
+        tab.textContent = sheet.name;
+        tab.addEventListener('click', () => selectSheet(sheet.id));
+        tabs.appendChild(tab);
+      }
+      const notice = document.createElement('div');
+      notice.className = 'spreadsheet-preview-notice';
+      // Written already translated, item by item (renderWarnings), and it ends
+      // with workbook text (a number format's code): the observer's t() over
+      // the whole line would rewrite a `{name}` or a "Codeman" in that code.
+      notice.setAttribute('data-i18n-skip', '');
+      notice.hidden = true;
+      emptySheetState = document.createElement('div');
+      emptySheetState.className = 'spreadsheet-empty-sheet';
+      emptySheetState.textContent = 'This worksheet is empty.';
+      emptySheetState.hidden = true;
+      grid = document.createElement('div');
+      grid.className = 'spreadsheet-grid';
+      grid.setAttribute('data-i18n-skip', '');
+      spacer = document.createElement('div');
+      spacer.className = 'spreadsheet-grid-spacer';
+      cellsLayer = document.createElement('div');
+      cellsLayer.className = 'spreadsheet-cells';
+      headingsLayer = document.createElement('div');
+      headingsLayer.className = 'spreadsheet-headings';
+      grid.append(spacer, cellsLayer, headingsLayer);
+      grid.addEventListener(
+        'scroll',
+        () => {
+          pinHeadings();
+          if (scrollFrame !== null) return;
+          scrollFrame = global.requestAnimationFrame(() => {
+            scrollFrame = null;
+            requestTile();
+          });
+        },
+        { passive: true }
+      );
+      shell.append(styleSheet, tabs, notice, emptySheetState, grid);
+      container.appendChild(shell);
+      resizeObserver = typeof ResizeObserver === 'function' ? new ResizeObserver(requestTile) : null;
+      resizeObserver?.observe(grid);
+      selectSheet(metadata.sheets[0].id);
+    }
+
+    function dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearTimer();
+      if (scrollFrame !== null) global.cancelAnimationFrame(scrollFrame);
+      controller?.abort();
+      resizeObserver?.disconnect();
+      try {
+        worker?.postMessage({ type: 'dispose' });
+        worker?.terminate();
+      } catch {
+        // A worker that failed during startup may already be unavailable.
+      }
+      worker = null;
+    }
+
+    async function start() {
+      if (Number(options.size) > MAX_PREVIEW_BYTES) {
+        fail('This workbook is too large to preview (10 MB limit).');
+        return;
+      }
+      message(container, 'Loading spreadsheet…', 'loading');
+      let previewUrl;
+      try {
+        previewUrl = safePreviewUrl(options.url);
+        controller = new AbortController();
+        // Root-absolute paths ignore <base href>; route through the mount prefix.
+        worker = new Worker(global.CodemanBase?.url ? global.CodemanBase.url(assets.workerUrl) : assets.workerUrl);
+        const ready = new Promise((resolve, reject) => {
+          worker.onerror = () => reject(new Error('Spreadsheet parser failed to start'));
+          worker.onmessageerror = () => reject(new Error('Spreadsheet parser message failed'));
+          worker.onmessage = (event) => {
+            if (event.data?.type === 'ready') resolve();
+          };
+        });
+        const responsePromise = fetch(previewUrl, { signal: controller.signal });
+        const [response] = await Promise.all([responsePromise, ready]);
+        if (!current()) return;
+        if (response.status === 413) throw new Error('This workbook is too large to preview (10 MB limit).');
+        if (!response.ok) throw new Error(`Spreadsheet preview failed (${response.status})`);
+        const bytes = await response.arrayBuffer();
+        if (!current()) return;
+        worker.onmessage = (event) => {
+          if (!current()) return;
+          const payload = event.data || {};
+          if (payload.type === 'metadata') {
+            clearTimer();
+            renderMetadata(payload);
+          } else if (payload.type === 'tile') renderTile(payload);
+          else if (payload.type === 'error') fail(workerErrorText(payload));
+        };
+        worker.onerror = () => fail('Spreadsheet parser failed.');
+        worker.onmessageerror = () => fail('Spreadsheet parser message failed.');
+        timer = global.setTimeout(() => {
+          worker?.terminate();
+          fail('Spreadsheet preview timed out.');
+        }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        worker.postMessage({ type: 'load', bytes }, [bytes]);
+      } catch (error) {
+        if (!disposed && error?.name !== 'AbortError') fail(error?.message);
+      }
+    }
+
+    void start();
+    return Object.freeze({ dispose, selectSheet, resize: requestTile });
+  }
+
+  global.CodemanSpreadsheetPreviewAssets = assets;
+  global.CodemanSpreadsheetPreview = Object.freeze({ open, MAX_PREVIEW_BYTES });
+})(window);

src/web/public/tab-layout-browser.js

@@ -1,9 +1,9 @@
 /**
- * @fileoverview Read-only browser projection of the owner tab layout.
+ * @fileoverview Browser projection and editing of the owner tab layout.
  *
  * `GET /api/tab-layout` returns the owner's named tab GROUPS (`src/tab-layout.ts`
  * is the server model). Browser assets cannot import that TypeScript, so this
- * module is a small, dependency-free mirror that owns three things:
+ * module is a small, dependency-free mirror that owns four things:
  *
  *  1. Projection: which live sessions and open web tabs land in which group,
  *     and which rows a collapsed group hides.
@@ -12,6 +12,10 @@
  *     byte-identical to the flat rail's row.
  *  3. Load sequencing: concurrent layout reads settle newest-wins, and a failed
  *     read degrades to the flat rail with a capped, backed-off retry.
+ *  4. Editing: named operations (create/rename/delete/reorder a group, move a
+ *     row) applied optimistically and saved through ONE serialized
+ *     `PUT /api/tab-layout` at a time, rebased onto the server's layout on a
+ *     version conflict.
  *
  * The server stays the only authority for layout content. Collapse is a
  * per-device view preference and lives in localStorage only.
@@ -34,8 +38,16 @@
     !!ref && (ref.kind === 'session' || ref.kind === 'webview') && typeof ref.id === 'string' && ref.id.length > 0;
   const asIds = (value) => (Array.isArray(value) ? value.filter((id) => typeof id === 'string' && id) : []);
   const stableIds = (value) => [...new Set(asIds(value))];
-  const copyRefs = (value) =>
-    Array.isArray(value) ? value.filter(validRef).map((r) => ({ kind: r.kind, id: r.id })) : [];
+  // `placement: 'manual'` must survive the round trip: the browser writes whole
+  // layouts back, and dropping it would re-attach a hand-placed child session to
+  // its parent's subtree on the next save.
+  const copyRef = (r) =>
+    r.placement === 'manual' ? { kind: r.kind, id: r.id, placement: 'manual' } : { kind: r.kind, id: r.id };
+  const copyRefs = (value) => (Array.isArray(value) ? value.filter(validRef).map(copyRef) : []);
+
+  /** Server limits (src/tab-layout.ts), mirrored so a bad edit fails before the PUT. */
+  const MAX_GROUPS = 32;
+  const MAX_NAME_LENGTH = 60;
 
   /**
    * Defensive copy of a server layout. Unknown fields are dropped, so a newer
@@ -46,6 +58,7 @@
     const groups = Array.isArray(value.groups) ? value.groups : [];
     return {
       version: Number.isSafeInteger(value.version) && value.version >= 0 ? value.version : 0,
+      updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : '',
       groups: groups
         .filter((group) => group && typeof group.id === 'string' && group.id.length > 0)
         .map((group) => ({
@@ -276,10 +289,17 @@
         const expandedAttr = leaf ? '' : ` aria-expanded="${expanded ? 'true' : 'false'}"`;
         return (
           `<section class="tab-layout-group${section.collapsed ? ' tab-layout-group--collapsed' : ''}" role="presentation" data-tab-group-id="${id}">` +
-          `<div class="tab-layout-group-header tab-layout-group-toggle" role="treeitem" tabindex="-1" data-tab-group-header="${id}"${expandedAttr}${expanded ? ` aria-owns="${refsId}"` : ''} onclick="app.toggleTabGroupCollapsed(this.dataset.tabGroupHeader)">` +
+          `<div class="tab-layout-group-header tab-layout-group-toggle" role="treeitem" tabindex="-1" data-tab-group-header="${id}"${expandedAttr}${expanded ? ` aria-owns="${refsId}"` : ''} onclick="app.toggleTabGroupCollapsed(this.dataset.tabGroupHeader)" oncontextmenu="event.preventDefault(); app.openTabGroupMenu(event, this.dataset.tabGroupHeader)">` +
           '<span class="tab-layout-group-chevron" aria-hidden="true"></span>' +
           `<span class="tab-layout-group-name" id="${nameId}" data-i18n-skip>${escapeHtml(section.name)}</span>` +
-          `<span class="tab-layout-group-count">${section.count}</span></div>` +
+          `<span class="tab-layout-group-count">${section.count}</span>` +
+          // Pointer path to the group menu (right-click on the header works too).
+          // Deliberately NOT a button and not focusable: a treeitem holds no
+          // interactive children, and the keyboard path is Shift+F10 /
+          // ContextMenu on the header itself. aria-hidden keeps the glyph out of
+          // the header's accessible name.
+          '<span class="tab-layout-group-menu" aria-hidden="true" title="Group actions" ' +
+          'onclick="event.stopPropagation(); app.openTabGroupMenu(event, this.closest(\'[data-tab-group-header]\').dataset.tabGroupHeader)">&#x22EF;</span></div>' +
           `<div class="tab-layout-group-refs" id="${refsId}" ${expanded ? `role="group" aria-labelledby="${nameId}"` : 'role="presentation"'}>${rows}</div></section>`
         );
       })
@@ -340,6 +360,375 @@
     };
   }
 
+  // ─── Editing ────────────────────────────────────────────────────────────
+  //
+  // The browser edits through NAMED operations, not by diffing arrays: a write
+  // that loses a version race (409) is rebased by replaying the same operations
+  // on the layout the server returned, so a concurrent edit elsewhere survives.
+  // The server stays the authority: it re-validates and normalizes every PUT.
+
+  function editError(message) {
+    throw new Error(`Tab layout edit failed: ${message}`);
+  }
+
+  const clampIndex = (value, length) => (Number.isInteger(value) ? Math.max(0, Math.min(value, length)) : length);
+
+  function groupName(value) {
+    const name = typeof value === 'string' ? value.trim() : '';
+    if (!name || name.length > MAX_NAME_LENGTH) editError(`group name must be 1-${MAX_NAME_LENGTH} characters`);
+    return name;
+  }
+
+  function refLocations(layout) {
+    return [
+      ...layout.groups.flatMap((group) => group.refs.map((ref) => ({ groupId: group.id, ref }))),
+      ...layout.ungrouped.map((ref) => ({ groupId: null, ref })),
+    ];
+  }
+
+  function containerRefs(layout, groupId) {
+    if (groupId === null) return layout.ungrouped;
+    const group = layout.groups.find((candidate) => candidate.id === groupId);
+    if (!group) editError('unknown group');
+    return group.refs;
+  }
+
+  /**
+   * The rows that move together with `ref`: the session plus every descendant
+   * that still follows its parent (non-manual, parent stored). Mirrors the
+   * server's moveRef block so the optimistic rail matches what it will store.
+   * `parents` maps a session id to its parent session id.
+   */
+  function lineageBlock(layout, ref, parents) {
+    const stored = new Map(refLocations(layout).map((item) => [refKey(item.ref), item.ref]));
+    const children = new Map();
+    for (const [childId, parentId] of Object.entries(parents || {})) {
+      const child = stored.get(`session:${childId}`);
+      if (!child || child.placement === 'manual' || !stored.has(`session:${parentId}`)) continue;
+      if (!children.has(parentId)) children.set(parentId, []);
+      children.get(parentId).push(childId);
+    }
+    const keys = new Set();
+    const visit = (key) => {
+      if (keys.has(key)) return;
+      keys.add(key);
+      if (key.startsWith('session:')) for (const id of children.get(key.slice(8)) || []) visit(`session:${id}`);
+    };
+    visit(refKey(ref));
+    return keys;
+  }
+
+  /**
+   * Where a moved row lands, as the server's `index` (counted AFTER the moved
+   * block is taken out): before or after `anchor` in that container, or at its
+   * end when there is no anchor.
+   */
+  function moveDestination(layoutInput, ref, groupId, anchor, placement, parents) {
+    const layout = normalizeLayout(layoutInput);
+    const block = lineageBlock(layout, ref, parents);
+    const remaining = containerRefs(layout, groupId).filter((candidate) => !block.has(refKey(candidate)));
+    // No anchor means "at the end", and an operation with no index keeps
+    // meaning that when it is replayed onto a layout that has changed since.
+    if (!anchor) return { groupId };
+    const at = remaining.findIndex((candidate) => refKey(candidate) === refKey(anchor));
+    if (at < 0) return { groupId };
+    return { groupId, index: placement === 'after' ? at + 1 : at };
+  }
+
+  /**
+   * Map a finished drag to ONE operation (or null for a drop that changes
+   * nothing). Pure, so the drop -> PUT mapping is testable without a pointer.
+   *
+   * source: { type: 'ref', ref } | { type: 'group', groupId }
+   * target: { type: 'ref', ref, groupId, placement: 'before' | 'after' }
+   *       | { type: 'group', groupId }   (a named group's header or empty body)
+   *       | { type: 'ungrouped' }
+   *
+   * A group dropped on another group (or any row in it) takes that group's slot;
+   * dropped on the Ungrouped section it goes last. A row dropped on a row lands
+   * before/after it, on a header it is appended to that group.
+   */
+  function dropOperation(layoutInput, source, target, parents) {
+    const layout = normalizeLayout(layoutInput);
+    if (!source || !target) return null;
+    if (source.type === 'group') {
+      const from = layout.groups.findIndex((group) => group.id === source.groupId);
+      if (from < 0) return null;
+      const targetId = target.type === 'ungrouped' ? null : (target.groupId ?? null);
+      const to = targetId === null ? layout.groups.length - 1 : layout.groups.findIndex((g) => g.id === targetId);
+      if (to < 0 || to === from) return null;
+      return { type: 'reorderGroup', groupId: source.groupId, index: to };
+    }
+    if (source.type !== 'ref' || !validRef(source.ref)) return null;
+    const location = refLocations(layout).find((item) => refKey(item.ref) === refKey(source.ref));
+    if (!location) return null;
+    let groupId;
+    let anchor = null;
+    let placement = 'before';
+    if (target.type === 'ref' && validRef(target.ref)) {
+      // Onto itself or onto a row that moves with it: nowhere to go.
+      if (lineageBlock(layout, source.ref, parents).has(refKey(target.ref))) return null;
+      groupId = target.groupId ?? null;
+      anchor = target.ref;
+      placement = target.placement === 'after' ? 'after' : 'before';
+    } else if (target.type === 'group') {
+      groupId = target.groupId ?? null;
+      if (groupId === location.groupId) return null;
+    } else if (target.type === 'ungrouped') {
+      groupId = null;
+      if (location.groupId === null) return null;
+    } else return null;
+    if (groupId !== null && !layout.groups.some((group) => group.id === groupId)) return null;
+    const destination = moveDestination(layout, source.ref, groupId, anchor, placement, parents);
+    const operation = {
+      type: 'moveRef',
+      ref: { kind: source.ref.kind, id: source.ref.id },
+      groupId: destination.groupId,
+      ...(destination.index === undefined ? {} : { index: destination.index }),
+      parents: parents || {},
+    };
+    return contentKey(applyOperation(layout, operation)) === contentKey(layout) ? null : operation;
+  }
+
+  /**
+   * Apply one operation to a copy of the layout. Throws when the operation no
+   * longer makes sense (an unknown group or row); a rebase drops that one
+   * operation and keeps the rest. Replays are idempotent where it matters for
+   * recovery: creating a group that already exists is a no-op.
+   */
+  function applyOperation(layoutInput, operation) {
+    const layout = normalizeLayout(layoutInput);
+    const op = operation || {};
+    const groupIndex = layout.groups.findIndex((group) => group.id === op.groupId);
+    switch (op.type) {
+      case 'createGroup': {
+        if (typeof op.id !== 'string' || !op.id) editError('invalid group id');
+        const name = groupName(op.name);
+        if (layout.groups.some((group) => group.id === op.id)) return layout;
+        if (layout.groups.length >= MAX_GROUPS) editError('group limit reached');
+        layout.groups.splice(clampIndex(op.index, layout.groups.length), 0, { id: op.id, name, refs: [] });
+        return layout;
+      }
+      case 'renameGroup':
+        if (groupIndex < 0) editError('unknown group');
+        layout.groups[groupIndex].name = groupName(op.name);
+        return layout;
+      case 'deleteGroup': {
+        // Already gone (deleted elsewhere): nothing left to do.
+        if (groupIndex < 0) return layout;
+        const [removed] = layout.groups.splice(groupIndex, 1);
+        layout.ungrouped.push(...removed.refs);
+        return layout;
+      }
+      case 'reorderGroup': {
+        if (groupIndex < 0) editError('unknown group');
+        const [moved] = layout.groups.splice(groupIndex, 1);
+        layout.groups.splice(clampIndex(op.index, layout.groups.length), 0, moved);
+        return layout;
+      }
+      case 'moveRef': {
+        if (!validRef(op.ref)) editError('invalid row');
+        const targetKey = refKey(op.ref);
+        if (!refLocations(layout).some((item) => refKey(item.ref) === targetKey)) editError('unknown row');
+        const destinationId = op.groupId ?? null;
+        containerRefs(layout, destinationId);
+        const keys = lineageBlock(layout, op.ref, op.parents);
+        const block = refLocations(layout)
+          .filter((item) => keys.has(refKey(item.ref)))
+          .map((item) => copyRef(item.ref));
+        // A hand-moved child stops following its parent (server moveRef does the same).
+        const head = block.find((item) => refKey(item) === targetKey);
+        if (op.ref.kind === 'session' && op.parents?.[op.ref.id]) head.placement = 'manual';
+        block.sort((a, b) => (a === head ? -1 : b === head ? 1 : 0));
+        for (const group of layout.groups) group.refs = group.refs.filter((ref) => !keys.has(refKey(ref)));
+        layout.ungrouped = layout.ungrouped.filter((ref) => !keys.has(refKey(ref)));
+        const destination = containerRefs(layout, destinationId);
+        destination.splice(clampIndex(op.index, destination.length), 0, ...block);
+        return layout;
+      }
+      default:
+        return editError(`unknown operation ${op.type}`);
+    }
+  }
+
+  /** Layout content without version metadata: equal keys mean "nothing to save". */
+  function contentKey(layoutInput) {
+    const layout = normalizeLayout(layoutInput);
+    return JSON.stringify([layout.groups, layout.ungrouped]);
+  }
+
+  /** Replay operations, dropping (and counting) the ones that no longer apply. */
+  function replayOperations(base, operations) {
+    let layout = normalizeLayout(base);
+    const kept = [];
+    let dropped = 0;
+    for (const operation of operations) {
+      try {
+        layout = applyOperation(layout, operation);
+        kept.push(operation);
+      } catch (_error) {
+        dropped++;
+      }
+    }
+    return { layout, kept, dropped };
+  }
+
+  /**
+   * Serialized, optimistic writer for `PUT /api/tab-layout`.
+   *
+   *  - enqueue() applies an operation at once (the rail repaints optimistically)
+   *    and schedules a flush; operations enqueued in the same turn share a PUT.
+   *  - Exactly ONE write is in flight. Operations enqueued meanwhile wait and are
+   *    sent on top of the version that write returns.
+   *  - A 409 carries the server's current layout: the in-flight operations are
+   *    replayed onto it and re-sent with its version (bounded attempts). A 400
+   *    (a row vanished between read and write) re-reads and rebases the same way.
+   *  - Anything else, or attempts exhausted, drops the batch and reports it; the
+   *    caller re-reads so the rail shows the server's truth.
+   *
+   * options: { initialLayout, put({ baseVersion, layout }) -> { ok, status,
+   *   layout }, fetchLayout?(), applyLayout(layout, meta), reportError?(message),
+   *   onSettled?(), onFailure?(), schedule?(fn), cancel?(handle), maxAttempts? }
+   */
+  function createEditCoordinator(options) {
+    let authoritative = normalizeLayout(options.initialLayout);
+    let optimistic = authoritative;
+    let pending = [];
+    let inFlight = [];
+    let writing = false;
+    let timer = null;
+    let disposed = false;
+    const schedule = options.schedule || ((fn) => setTimeout(fn, 0));
+    const cancel = options.cancel || ((handle) => clearTimeout(handle));
+    const maxAttempts = options.maxAttempts || 3;
+    const report = (message) => options.reportError?.(message);
+    const publish = (meta) => options.applyLayout(normalizeLayout(optimistic), meta);
+    const queue = () => {
+      if (timer === null) timer = schedule(flush);
+    };
+
+    async function flush() {
+      timer = null;
+      if (disposed || writing || pending.length === 0) return;
+      writing = true;
+      inFlight = pending;
+      pending = [];
+      let failed = false;
+      let reportedDrop = false;
+      let rereadFor400 = false;
+      try {
+        for (let attempt = 0; attempt < maxAttempts && inFlight.length; attempt++) {
+          const desired = replayOperations(authoritative, inFlight);
+          inFlight = desired.kept;
+          if (desired.dropped && !reportedDrop) {
+            reportedDrop = true;
+            report('Tab groups changed elsewhere; part of your edit no longer applies.');
+          }
+          // Nothing left to change (dropped, or already true on the server).
+          if (!inFlight.length || contentKey(desired.layout) === contentKey(authoritative)) {
+            inFlight = [];
+            break;
+          }
+          const response = await options.put({ baseVersion: authoritative.version, layout: desired.layout });
+          if (disposed) return;
+          if (response?.ok && response.layout) {
+            authoritative = normalizeLayout(response.layout);
+            inFlight = [];
+          } else if (response?.status === 409 && response.layout) {
+            authoritative = normalizeLayout(response.layout);
+          } else if (response?.status === 400 && options.fetchLayout && !rereadFor400) {
+            // Maybe our base was stale in a way the server reports as invalid:
+            // re-read once. A 400 that survives that is a refusal, not a race.
+            rereadFor400 = true;
+            authoritative = normalizeLayout(await options.fetchLayout());
+            if (disposed) return;
+          } else {
+            throw new Error('Tab layout save failed');
+          }
+        }
+        if (inFlight.length) {
+          failed = true;
+          report('Tab groups kept changing elsewhere; your edit was not saved.');
+        }
+      } catch (_error) {
+        failed = true;
+        report('Could not save tab groups.');
+      } finally {
+        inFlight = [];
+        writing = false;
+        if (!disposed) {
+          const rebased = replayOperations(authoritative, pending);
+          // Edits made while the write was in flight are rebased here, so one the
+          // conflict made inapplicable is dropped here too, and says so (once).
+          if (rebased.dropped && !failed && !reportedDrop) {
+            report('Tab groups changed elsewhere; part of your edit no longer applies.');
+          }
+          pending = rebased.kept;
+          optimistic = rebased.layout;
+          publish({ authoritative: true });
+          if (failed) options.onFailure?.();
+          if (pending.length) queue();
+          else options.onSettled?.();
+        }
+      }
+    }
+
+    return {
+      /** Apply now, save soon. Throws (and changes nothing) for an invalid edit. */
+      enqueue(operation) {
+        optimistic = applyOperation(optimistic, operation);
+        pending.push(operation);
+        publish({ optimistic: true });
+        queue();
+        return normalizeLayout(optimistic);
+      },
+      /**
+       * Re-apply operations recovered after a reload. Returns false (and queues
+       * nothing) when the layout already reflects them, e.g. the keepalive save
+       * landed before the page went away.
+       */
+      restore(operations) {
+        const replayed = replayOperations(optimistic, Array.isArray(operations) ? operations : []);
+        if (!replayed.kept.length || contentKey(replayed.layout) === contentKey(optimistic)) return false;
+        optimistic = replayed.layout;
+        pending.push(...replayed.kept);
+        publish({ optimistic: true });
+        queue();
+        return true;
+      },
+      /**
+       * Adopt a layout read from the server (SSE reload). Pending operations are
+       * rebased onto it. Refused while a write is in flight (its result decides)
+       * and for a layout older than the one already held.
+       */
+      adoptExternal(layout) {
+        if (disposed || writing) return false;
+        const next = normalizeLayout(layout);
+        if (next.version < authoritative.version) return false;
+        authoritative = next;
+        const rebased = replayOperations(next, pending);
+        if (rebased.dropped) report('Tab groups changed elsewhere; part of your edit no longer applies.');
+        pending = rebased.kept;
+        optimistic = rebased.layout;
+        publish({ authoritative: true, external: true });
+        return true;
+      },
+      flush,
+      isWriting: () => writing,
+      hasPending: () => writing || pending.length > 0,
+      /** Every operation not yet confirmed by the server, oldest first. */
+      pendingOperations: () => JSON.parse(JSON.stringify([...inFlight, ...pending])),
+      baseVersion: () => authoritative.version,
+      getLayout: () => normalizeLayout(optimistic),
+      dispose() {
+        disposed = true;
+        if (timer !== null) cancel(timer);
+        timer = null;
+        pending = [];
+      },
+    };
+  }
+
   global.CodemanTabLayout = {
     normalizeLayout,
     hasGroups,
@@ -347,8 +736,15 @@
     hiddenGroupAlerts,
     structureKey,
     renderProjection,
+    applyOperation,
+    moveDestination,
+    movingRefKeys: (layout, ref, parents) => [...lineageBlock(normalizeLayout(layout), ref, parents)],
+    dropOperation,
+    contentKey,
+    createEditCoordinator,
     createLoadCoordinator,
     loadCollapsedGroupIds,
     saveCollapsedGroupIds,
+    MAX_GROUPS,
   };
 })(typeof window !== 'undefined' ? window : globalThis);

src/web/public/tab-rail-resize.js

@@ -298,7 +298,9 @@ Object.assign(CodemanApp.prototype, {
   },
 
   closeTabRailActionMenu(options = {}) {
-    const menu = document.querySelector('.tab-rail-action-menu');
+    // The group menu borrows this class for its look but has its own owner
+    // (closeTabGroupMenu); removing its DOM here would strand its listeners.
+    const menu = document.querySelector('.tab-rail-action-menu:not(.tab-layout-group-action-menu)');
     const trigger = this._tabRailActionMenuTrigger;
     menu?.remove();
     if (this._tabRailActionMenuOutside) {
@@ -325,7 +327,10 @@ Object.assign(CodemanApp.prototype, {
     const settings = this.loadAppSettingsFromStorage();
     const actions = [
       { label: 'Session options', run: () => this.openSessionOptions(sessionId) },
-      ...(settings.showTabDetachButton || this.detachedSessions?.has(sessionId)
+      // Group placement (vertical rail with a tab layout only; [] elsewhere).
+      ...(this._tabRefMoveActions?.({ kind: 'session', id: sessionId }) || []),
+      ...((this.tabDetachButtonEnabled?.(settings) ?? settings.showTabDetachButton) ||
+      this.detachedSessions?.has(sessionId)
         ? [{ label: 'Open in a new window', run: () => this.detachSession(sessionId) }]
         : []),
       { label: 'Close session', className: 'danger', run: () => this.requestCloseSession(sessionId) },

src/web/public/terminal-keycode229-recovery.js

@@ -18,6 +18,15 @@
  * the case this module exists for, and the case its browser test asserts by
  * checking WHO delivered the byte rather than merely that one arrived.
  *
+ * A SECOND failure lives in that same self-rescue: xterm diffs `newValue.replace(oldValue, '')`,
+ * which only works when the keyboard APPENDED. A soft keyboard that autocorrects on space
+ * (SwiftKey, Gboard) rewrites the tail instead: it deletes the word and inserts the corrected
+ * one, and xterm answers by sending the WHOLE new textarea value (the old value is not a
+ * substring of it), then sends the inserted text AGAIN from the second keydown's timer. One
+ * autocorrect turned `testing the peompt` + <space> into
+ * `testing the peompttesting the prompt rompt `. A multi-character delete is also sent as ONE
+ * DEL. `installEditSync` below replaces that diff with an edit-based one.
+ *
  * The recovery never guesses the character: the `input` event already carries
  * the real committed text in `ev.data`, which is exactly what xterm itself
  * would have forwarded. We only decide WHETHER to forward it, by asking
@@ -33,12 +42,28 @@
  * also be a CAPTURE listener; see the measured table at the addEventListener
  * call below.
  *
- * @dependency none (standalone IIFE; consumed by terminal-ui.js)
- * @loadorder 5.55 (before app.js/terminal-ui.js, which create the controller)
+ * @dependency none (standalone IIFE; consumed by terminal-ui.js for the primary pane and by
+ *   terminal-tile.js for every grid tile and the split's Pane B, one controller per xterm)
+ * @loadorder 5.55 (before app.js/terminal-ui.js/terminal-tile.js, which create controllers)
  */
 (function (global) {
   'use strict';
 
+  /**
+   * What turns `previous` into `next`, as a terminal sees it: how many characters to delete from
+   * the END of the line, then what to type. Everything after the common prefix is treated as
+   * replaced, because a terminal can only edit at its cursor. Counts are code points, so an
+   * emoji is one DEL, as it is one backspace.
+   */
+  function editBetween(previous, next) {
+    const a = Array.from(previous);
+    const b = Array.from(next);
+    let prefix = 0;
+    const max = Math.min(a.length, b.length);
+    while (prefix < max && a[prefix] === b[prefix]) prefix += 1;
+    return { deleted: a.length - prefix, inserted: b.slice(prefix).join('') };
+  }
+
   function create(options) {
     const textarea = options?.textarea;
     const emitRecovered = options?.emitRecovered;
@@ -65,6 +90,9 @@
     let keydownSnapshot = 0;
     let composing = false;
     const pending = [];
+    // Applies any edit-sync diff still waiting on its timer. Assigned by installEditSync() below; a
+    // no-op when xterm's internals are not available.
+    let settleEdit = () => {};
 
     /**
      * Resolve every candidate still pending, right now, instead of waiting for
@@ -147,6 +175,13 @@
       // reach the PTY — see flushPending(). This runs from xterm's custom key
       // handler, i.e. before xterm processes the key, so a recovered character
       // is always ordered ahead of the bytes this keydown produces.
+      // ORDER MATTERS. Settle the edit-sync diff first: it bumps `canonicalCount` for the
+      // keystroke it belongs to, so flushPending() then stands that keystroke's orphan candidate
+      // down. Swapped, the candidate would resolve first and the character would be sent twice.
+      // It also has to happen BEFORE xterm handles THIS key: for Enter, xterm clears the textarea
+      // in its own keydown, and a timer left pending would then diff the whole line against ''
+      // and send one DEL per character ahead of the submitted line.
+      settleEdit(event);
       flushPending();
       keydownSnapshot = canonicalCount;
     }
@@ -176,6 +211,92 @@
       }
     }
 
+    /**
+     * Replace xterm's `_handleAnyTextareaChanges` (see the header) with an edit-based diff against
+     * the value the PTY side has already been told about. `synced` is that value; it is shared by
+     * every keydown's timer, so two timers that both see the final textarea value cannot both
+     * send it. Returns an uninstall function, or null when xterm's internals are not as expected
+     * (then xterm's own, flawed, behaviour is left in place).
+     */
+    function installEditSync() {
+      let helper;
+      try {
+        helper = options.getCompositionHelper?.();
+      } catch {
+        return null;
+      }
+      const original = helper?._handleAnyTextareaChanges;
+      const coreService = helper?._coreService;
+      if (typeof original !== 'function' || typeof coreService?.triggerDataEvent !== 'function') return null;
+
+      let synced = textarea.value;
+      const waiting = new Set();
+
+      /** Send what changed since `synced`, once, and remember it. */
+      function applyEdit() {
+        if (destroyed || helper._isComposing) return; // xterm's composition path owns this one
+        const current = textarea.value;
+        if (current === synced) return;
+        const { deleted, inserted } = editBetween(synced, current);
+        synced = current;
+        try {
+          // One DEL per character, like repeated backspace presses: the local-echo composer and
+          // the PTY both treat each as a single edit.
+          for (let i = 0; i < deleted; i += 1) coreService.triggerDataEvent('\x7f', true);
+          if (inserted) {
+            helper._dataAlreadySent = inserted;
+            coreService.triggerDataEvent(inserted, true);
+          }
+        } catch {
+          // Delivery is best effort; never throw into the browser's timer queue.
+        }
+      }
+
+      helper._handleAnyTextareaChanges = function handleAnyTextareaChanges() {
+        if (destroyed) return original.call(this);
+        // No edit in flight and the value is not what we last sent: something outside the IME
+        // changed it (xterm clears it after Enter, a composition committed). Nothing to send;
+        // resynchronise.
+        if (waiting.size === 0 && synced !== textarea.value) synced = textarea.value;
+        const entry = { id: null };
+        waiting.add(entry);
+        entry.id = setTimer(() => {
+          waiting.delete(entry);
+          applyEdit();
+        }, 0);
+      };
+
+      // Apply the pending edit NOW instead of on its timer (see handleKeyEvent).
+      settleEdit = (event) => {
+        if (waiting.size === 0) return;
+        for (const entry of waiting) {
+          try {
+            clearTimer(entry.id);
+          } catch {
+            // A broken timer host must not break input handling.
+          }
+        }
+        // Cleared BEFORE the return below, on purpose: left pending, the timer would fire after
+        // Enter clears the textarea and send one DEL per character ahead of the submitted line.
+        waiting.clear();
+        // A composition just ended and this key makes xterm finalize it SYNCHRONOUSLY, through
+        // `_finalizeComposition(false)`, which ignores `_dataAlreadySent`: that text is xterm's, and
+        // sending the edit too would deliver it twice. On 229, CapsLock and the modifiers xterm keeps
+        // the composition on its async path, which honours `_dataAlreadySent`, so the edit still
+        // applies there. Only this settle path is guarded: on the timer path xterm always finalizes
+        // asynchronously, and skipping the edit there would drop a byte master delivers.
+        if (helper._isSendingComposition && ![229, 20, 16, 17, 18].includes(event?.keyCode)) return;
+        applyEdit();
+      };
+
+      return () => {
+        settleEdit = () => {};
+        if (helper._handleAnyTextareaChanges !== original) helper._handleAnyTextareaChanges = original;
+      };
+    }
+
+    const uninstallEditSync = installEditSync();
+
     function onCompositionStart() {
       if (destroyed) return;
       composing = true;
@@ -191,6 +312,11 @@
       if (destroyed) return;
       destroyed = true;
       cancelPending();
+      try {
+        uninstallEditSync?.();
+      } catch {
+        // Best effort.
+      }
       try {
         textarea.removeEventListener('input', onInput, true);
         textarea.removeEventListener('compositionstart', onCompositionStart, true);
@@ -228,5 +354,5 @@
     return Object.freeze({ handleKeyEvent, notifyCanonicalData, destroy });
   }
 
-  global.CodemanKeyCode229Recovery = Object.freeze({ create });
+  global.CodemanKeyCode229Recovery = Object.freeze({ create, editBetween });
 })(typeof window !== 'undefined' ? window : globalThis);

src/web/public/terminal-split.js

@@ -1,640 +1,16 @@
 // src/web/public/terminal-split.js
 
 /**
- * @fileoverview SplitTerminalPane — a second, independent live terminal pane
- * ("Pane B") for split-view sessions. Deliberately plainer than the primary
- * pane (this.terminal/this._ws in terminal-ui.js): no local-echo overlay, no
- * CJK IME, no touch/mobile handlers, no keyboard accessory bar. Desktop-only
- * feature by nature — see docs/split-pane-sessions-plan.md.
+ * @fileoverview Split-pane orchestration: opens a second live session
+ * ("Pane B") beside the active one, in a TerminalTile (terminal-tile.js), with
+ * a draggable divider, a session picker, and auto-collapse when either
+ * session ends. Desktop-only; see docs/split-pane-sessions-plan.md.
  *
- * @dependency vendor/xterm.js, vendor/xterm-addon-fit.js
- * @dependency constants.js (window.CodemanTerminalFont, DEFAULT_SCROLLBACK, TERMINAL_TAIL_SIZE, TERMINAL_CHUNK_SIZE)
- * @dependency terminal-ui.js (codemanCurrentXtermTheme, codemanCurrentSkinIsLight)
- * @loadorder 7.5 of 16 — loaded after terminal-ui.js, before respawn-ui.js
+ * @dependency terminal-tile.js (window.TerminalTile)
+ * @dependency constants.js (window.CodemanSplitPane, SPLIT_PANE_MIN_WIDTH)
+ * @loadorder 7.5 of 16, loaded after terminal-tile.js and before tile-grid.js
  */
 
-(function (global) {
-  // How long a scroll-to-top history pull may hold Pane B's live output.
-  const HISTORY_PULL_TIMEOUT_MS = 10000;
-
-  /**
-   * Minimal chunked write for Pane B's own xterm instance — write() in
-   * TERMINAL_CHUNK_SIZE slices, yielding a frame between each, instead of one
-   * giant synchronous write that blocks the main thread while parsing a long
-   * scrollback. Deliberately NOT the primary pane's chunkedTerminalWrite
-   * (terminal-ui.js): that one is wired into session-switch generation
-   * counters and the live-output gate this simpler, independently
-   * created/destroyed pane has no equivalent of.
-   */
-  function writeChunked(terminal, buffer, isDestroyed) {
-    if (!buffer) return Promise.resolve();
-    if (buffer.length <= TERMINAL_CHUNK_SIZE) {
-      terminal.write(buffer);
-      return Promise.resolve();
-    }
-    // Resolves once the LAST chunk is written (or the pane was destroyed
-    // mid-replay), so _loadBuffer() below can hold its single-flight flag
-    // across the whole replay rather than just the fetch that precedes it.
-    return new Promise((resolve) => {
-      let offset = 0;
-      const writeNext = () => {
-        if (isDestroyed() || !terminal) {
-          resolve();
-          return;
-        }
-        const chunk = buffer.slice(offset, offset + TERMINAL_CHUNK_SIZE);
-        offset += chunk.length;
-        terminal.write(chunk);
-        if (offset < buffer.length) {
-          if (typeof requestAnimationFrame === 'function') requestAnimationFrame(writeNext);
-          else setTimeout(writeNext, 16);
-        } else {
-          resolve();
-        }
-      };
-      writeNext();
-    });
-  }
-
-  class SplitTerminalPane {
-    constructor(sessionId, mountEl, opts = {}) {
-      this.sessionId = sessionId;
-      this.mountEl = mountEl;
-      this.sessionMode = opts.mode;
-      this.fontSettings = opts.fontSettings || {};
-      // Live reference (not a snapshot) to the app's detachedSessions Set —
-      // detaching this session AFTER the split is already open must still be
-      // seen by _sendResize() below, or it re-creates the exact PTY-size
-      // fight the split picker already refuses to open at pick time.
-      this.detachedSessions = opts.detachedSessions;
-      this.terminal = null;
-      this.fitAddon = null;
-      this.ws = null;
-      this._wsReady = false;
-      this._wsClosed = false;
-      this._destroyed = false;
-      // Single-flight state for _loadBuffer()/_refreshBuffer() below.
-      this._bufferLoading = false;
-      this._bufferRefreshPending = false;
-      // Scroll-to-top history pull (shell panes only), see _maybeLoadMoreHistory().
-      // `_liveQueue` is non-null from the pull's response until its finally
-      // block: live frames are held there with their arrival time instead of
-      // written under the replay. `_markerOwed` is the "disconnected" marker a
-      // load still has to write (see _onSocketClosed()/_stampMarkerIfOwed()).
-      this._historyPullAt = 0;
-      this._historyPullUseless = false;
-      this._liveQueue = null;
-      this._markerOwed = false;
-      this._onWheel = null;
-    }
-
-    async connect() {
-      const savedFontSize = parseInt(localStorage.getItem('codeman-font-size'), 10);
-      this.terminal = new Terminal({
-        theme: { ...global.codemanCurrentXtermTheme() },
-        fontFamily: global.CodemanTerminalFont.resolve(this.fontSettings.terminalFontFamily),
-        ...global.CodemanTerminalFont.resolveWeights(this.fontSettings),
-        fontSize: Number.isFinite(savedFontSize) ? savedFontSize : 14,
-        lineHeight: 1.2,
-        cursorBlink: false,
-        cursorStyle: 'block',
-        minimumContrastRatio: global.codemanCurrentSkinIsLight() ? 4.5 : 1,
-        scrollback: DEFAULT_SCROLLBACK,
-        allowTransparency: true,
-        allowProposedApi: true,
-      });
-
-      this.fitAddon = new FitAddon.FitAddon();
-      this.terminal.loadAddon(this.fitAddon);
-      this.terminal.open(this.mountEl);
-      this.fitAddon.fit();
-
-      this._installWheelListener();
-
-      this.terminal.onData((data) => {
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-          this.ws.send(JSON.stringify({ t: 'i', d: data }));
-        }
-      });
-
-      // Pane B has no gates of its own by default, so every app-level chord
-      // that the document capture-phase handler (app.js) only preventDefault()s
-      // — never stopPropagation()s — reaches xterm here too and writes its raw
-      // byte/escape sequence into THIS session's PTY on top of whatever the app
-      // action already did to Pane A (COD-153; mirrors the primary pane's own
-      // gates at terminal-ui.js's attachCustomKeyEventHandler: command palette,
-      // Alt+1-9/[/] tab nav, Alt+B sidebar toggle, Ctrl+Z suspend, Shift/Ctrl+Enter
-      // newline, and smart-copy Ctrl+C/Ctrl+Shift+C). Routed through the same
-      // registry-aware predicates so a rebind or a disable restores plain
-      // terminal behavior here too. Ctrl+V is deliberately left on xterm's own
-      // default (plain-text paste): Pane B has no image-paste trap to route it
-      // to, so intercepting it here would only break paste.
-      this.terminal.attachCustomKeyEventHandler((ev) => {
-        if (ev.isComposing || ev.key === 'Process' || ev.keyCode === 229) return true;
-        if (
-          ev.altKey &&
-          !ev.ctrlKey &&
-          !ev.shiftKey &&
-          /^(Digit[1-9]|BracketLeft|BracketRight|KeyK)$/.test(ev.code || '')
-        ) {
-          return false;
-        }
-        if (ev.type === 'keydown' && global.app?.shouldOpenCommandPaletteFromShortcut?.(ev)) {
-          return false;
-        }
-        if (ev.type === 'keydown' && global.app?.shouldToggleSessionSidebarFromShortcut?.(ev)) {
-          return false;
-        }
-        // Ctrl+Z (SIGTSTP/job-control suspend): mirrors terminal-ui.js's own
-        // swallow — in a plain shell session this is the user's own
-        // job-control tool and must reach the PTY, but in every other mode
-        // (claude/omp/pi/codex/...) it silently stops an unattended agent
-        // loop dead. Pane B has its own PTY/session and must not send a
-        // suspend into a non-shell one just because the primary pane's own
-        // gate lives elsewhere.
-        if (
-          ev.type === 'keydown' &&
-          ev.key.toLowerCase() === 'z' &&
-          ev.ctrlKey &&
-          !ev.altKey &&
-          !ev.metaKey &&
-          !ev.shiftKey &&
-          this.sessionMode !== 'shell'
-        ) {
-          return false;
-        }
-        // Shift+Enter / Ctrl+Enter: insert a newline instead of submitting.
-        // Mirrors terminal-ui.js's own handling — xterm sends plain \r for
-        // every Enter variant, so an Ink app (Claude Code) can't tell a
-        // newline from a submit. Without this gate, Pane B's onData would
-        // send that bare \r straight over the WS and submit an incomplete
-        // prompt instead of adding a line to it. Targets THIS pane's own
-        // session (this.sessionId), never the primary pane's
-        // activeSessionId, and has no local-echo overlay of its own to flush
-        // first (Pane B is deliberately plainer — see the fileoverview).
-        // Swallow keypress/keyup too (xterm would send \r for a Shift-only keypress); only keydown sends.
-        if (ev.key === 'Enter' && (ev.shiftKey || ev.ctrlKey)) {
-          if (ev.type === 'keydown') {
-            fetch(`/api/sessions/${this.sessionId}/send-key`, {
-              method: 'POST',
-              headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({ key: ev.ctrlKey ? 'C-Enter' : 'S-Enter' }),
-            }).catch(() => {
-              /* Best-effort, matching this pane's tolerance elsewhere. */
-            });
-          }
-          return false;
-        }
-        // Smart copy (mirrors terminal-ui.js's Ctrl+C gate, #211): with a
-        // selection, Ctrl+C copies THIS pane's own selection instead of
-        // sending ^C; with none, plain Ctrl+C must fall through unchanged or
-        // the interrupt key is lost. Ctrl+Shift+C is different: it is the
-        // explicit, never-falls-through copy chord, and the predicate above
-        // does not distinguish it from plain Ctrl+C — ev.shiftKey does, below.
-        // xterm's own evaluateKeyboardEvent routes a shifted ctrl-letter into
-        // a branch that assigns c.key only for a couple of special cases
-        // ("_"->US, "@"->NUL), neither of which is "c", so it emits NOTHING
-        // for Ctrl+Shift+C either way — this is not about an accidental
-        // interrupt byte reaching the PTY (verified live: it does not).
-        // Gating this whole block on hasSelection() (an earlier draft) meant
-        // that with no selection Ctrl+Shift+C skipped straight to `return
-        // true`, silently ceding the keystroke to the BROWSER's own handling
-        // (e.g. Chrome's Inspect-Element binding) with no feedback and no
-        // attempt to copy, unlike Pane A, which always intercepts it.
-        // Re-implemented against this.terminal rather than reusing
-        // app.copyTerminalSelection(), which reads app.terminal — Pane A's —
-        // and would copy the wrong pane's selection.
-        if (ev.type === 'keydown' && global.app?.shouldCopyTerminalSelectionFromShortcut?.(ev)) {
-          const raw = this.terminal?.getSelection?.() || '';
-          const isColumnSelection = this.terminal?._core?._selectionService?._activeSelectionMode === 3;
-          // Both clean options are read for THIS pane, never the primary one:
-          // the gutter width comes from this.sessionId's own run mode, and the
-          // partial-first-line flag from this terminal's own selection range.
-          // Passing neither left Pane B keeping a margin Pane A dropped, on the
-          // same split and the same keystroke.
-          const range = global.app?._normalisedSelectionRange?.(this.terminal);
-          const selection = isColumnSelection
-            ? raw
-            : (global.CodemanCopySelection?.clean?.(raw, {
-                margin: global.app?._cliGutterColumns?.(this.sessionId) ?? 0,
-                firstLinePartial: !!range && range.start.x > 0,
-              }) ?? raw);
-          if (selection.trim()) {
-            ev.preventDefault();
-            void global.app._copyText?.(selection).then((ok) => {
-              this.terminal?.clearSelection?.();
-              global.app.showToast?.(ok ? 'Copied to clipboard' : 'Failed to copy', ok ? 'success' : 'error');
-            });
-            return false;
-          }
-          // Nothing worth copying — clear for feedback (a padding-only
-          // selection cleans to '' and this press still falls through to the
-          // PTY as 0x03, matching the primary pane's own rule).
-          if (this.terminal?.hasSelection?.()) {
-            this.terminal.clearSelection?.();
-            global.app.showToast?.('Nothing to copy', 'warning');
-          }
-          // Ctrl+Shift+C never falls through, even with nothing to copy —
-          // matches terminal-ui.js's own ev.shiftKey branch.
-          if (ev.shiftKey) {
-            ev.preventDefault();
-            return false;
-          }
-        }
-        return true;
-      });
-
-      // Load existing scrollback before going live. The WS below is
-      // subscribe-only (ws-routes.ts sends nothing on connect, only future
-      // 'terminal' events), so without this Pane B stays blank until the
-      // target session happens to produce new output. It LOOKED
-      // intermittent rather than always-broken because _sendResize() below
-      // often nudges the shared session's real tmux window to a new size,
-      // and tmux repaints its current screen on resize — that repaint was
-      // getting captured and streamed here, incidentally populating the
-      // pane. When Pane B's computed dimensions happened to already match
-      // the session's last-known size, Session.resize() (session.ts) skips
-      // the resize as a no-op, no repaint fires, and the pane stayed blank.
-      // The await covers the whole chunked replay, not just the fetch, so a
-      // live frame from the socket below can never land in the middle of it.
-      await this._loadBuffer();
-      if (this._destroyed) return;
-
-      const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
-      const url = `${proto}//${location.host}${window.CodemanBase.base}/ws/sessions/${this.sessionId}/terminal`;
-      this.ws = new WebSocket(url);
-
-      this.ws.onopen = () => {
-        this._wsReady = true;
-        this._sendResize();
-      };
-
-      this.ws.onmessage = (event) => {
-        try {
-          const msg = JSON.parse(event.data);
-          if (msg.t === 'o') {
-            this._onLiveOutput(msg.d);
-          } else if (msg.t === 'c') {
-            this._onLiveClear();
-          } else if (msg.t === 'r') {
-            // Server-triggered refresh (SSE backpressure cleared, terminal
-            // data was dropped). The primary pane routes this to
-            // _onSessionNeedsRefresh (app.js:2990) — Pane B has its own
-            // buffer loader for the same reason connect() does.
-            this._refreshBuffer();
-          }
-        } catch {
-          /* Malformed frame — ignore, matches primary pane's tolerance. */
-        }
-      };
-
-      // Mirror app.js's onclose/onerror pattern (app.js:2905-2964): _wsReady
-      // must go false on a drop or fit()/_sendResize() silently no-ops on a
-      // closed socket per the WebSocket spec (no exception, no log). No
-      // reconnect logic here — Pane B is deliberately plainer than the
-      // primary pane (see the fileoverview above); a drop just stops
-      // resizing until the parent recreates the pane. But onData already
-      // silently drops keystrokes while _wsReady is false (below), so
-      // without a visible marker a dropped socket left Pane B looking
-      // normal while it quietly ate everything typed into it. v1 scope is
-      // "say so", not reconnect — collapsing the split would lose the
-      // user's place in Pane B's scrollback for a transient blip.
-      this.ws.onclose = () => this._onSocketClosed();
-
-      this.ws.onerror = () => {
-        // onclose fires after onerror — cleanup happens there.
-      };
-    }
-
-    // The socket's close, split out of connect() so the tests can drive it.
-    // While any load runs (a history pull or a `{t:'r'}` refresh) the marker is
-    // only owed, and that load's finally block settles it (_stampMarkerIfOwed()):
-    // written now, it would sit above the output a pull is still holding (flushed
-    // after it on a skip, a downgrade or a failed fetch), above a refresh's
-    // replay, or in the middle of a chunked replay. A pull still waiting for its
-    // response holds the marker too, for as long as the request takes (up to its
-    // budget, see _pullHistory()).
-    _onSocketClosed() {
-      this._wsReady = false;
-      this._wsClosed = true;
-      if (this._bufferLoading) this._markerOwed = true;
-      else this._writeDisconnectedMarker();
-    }
-
-    // Settles a marker the pane owes: set when a close lands during a load (the
-    // replay would otherwise sit below it) or when a load wipes the terminal on
-    // a closed socket. Called from each load's own finally, just before
-    // _endBufferLoad() starts any trailing refresh.
-    _stampMarkerIfOwed() {
-      // A trailing refresh is about to clear() synchronously, while xterm parses
-      // a write() on a later tick: a marker written here would land in the
-      // freshly cleared buffer ABOVE that refresh's replay, a second, stale copy.
-      // The refresh re-owes the marker on a closed socket and stamps it itself.
-      if (this._bufferRefreshPending && !this._destroyed) return;
-      const owed = this._markerOwed;
-      this._markerOwed = false;
-      if (owed && this._wsClosed && !this._destroyed) this._writeDisconnectedMarker();
-    }
-
-    // Extracted so both _onSocketClosed() and a load that ends owing it on a
-    // closed socket can write it (see _stampMarkerIfOwed()).
-    _writeDisconnectedMarker() {
-      this.terminal?.write('\r\n\x1b[2m[Pane B disconnected — close and reopen the split to reconnect]\x1b[0m\r\n');
-    }
-
-    // Fetches and writes the session's current scrollback. Used both by
-    // connect() (initial load) and by the `{t:'r'}` server-refresh frame
-    // (below) — the primary pane's own _onSessionNeedsRefresh (app.js) is
-    // scoped to `this.activeSessionId` and clears/rewrites the primary
-    // terminal, neither of which applies to this independent pane, so this is
-    // a standalone equivalent rather than a call into it.
-    //
-    // Mirrors the primary pane's own mode check (app.js's selectSession /
-    // _onSessionNeedsRefresh): a shell session can retain hundreds of
-    // thousands of plain scrollback lines, so pulling `?full=1` there parses
-    // an unbounded, server-capped (up to terminalBufferMaxBytes, 32MB) body
-    // into a 50000-line xterm on every load. Non-shell (TUI) sessions still
-    // get one full replay. `fetch` here goes through the global wrapper
-    // (constants.js), which already prefixes CodemanBase — unlike the raw
-    // WebSocket URL above, which does not.
-    //
-    // Single-flight: the flag is held across the fetch AND the chunked write
-    // (writeChunked resolves after its last chunk), so two replays can never
-    // interleave their chunks into one terminal. A second call while one is
-    // in flight is dropped here; _refreshBuffer() is the caller that queues
-    // a trailing re-run instead.
-    async _loadBuffer() {
-      if (this._bufferLoading) return;
-      this._bufferLoading = true;
-      try {
-        const query = this.sessionMode === 'shell' ? `tail=${TERMINAL_TAIL_SIZE}` : 'full=1';
-        const res = await fetch(`/api/sessions/${this.sessionId}/terminal?${query}`);
-        const payload = (await res.json())?.data ?? {};
-        if (payload.terminalBuffer && this.terminal) {
-          await writeChunked(this.terminal, payload.terminalBuffer, () => this._destroyed);
-        }
-      } catch {
-        /* Best-effort — live output still arrives once the socket connects. */
-      } finally {
-        this._stampMarkerIfOwed();
-        this._endBufferLoad();
-      }
-    }
-
-    // Ends a single-flight load (initial, refresh or history pull): clears the
-    // flag, then runs the ONE trailing refresh that arrived while it was busy.
-    _endBufferLoad() {
-      this._bufferLoading = false;
-      if (this._bufferRefreshPending && !this._destroyed) {
-        this._bufferRefreshPending = false;
-        this._refreshBuffer();
-      }
-    }
-
-    // Live terminal output. Written straight through, except while a history
-    // pull is replaying: a capture is current only up to the instant tmux took
-    // it, so a frame arriving mid-replay is held with its arrival time and
-    // replayed behind the snapshot by _pullHistory() (the primary pane's
-    // _finishBufferLoad `since` rule), never written underneath it.
-    _onLiveOutput(data) {
-      if (this._liveQueue) this._liveQueue.push({ at: performance.now(), data });
-      else this.terminal?.write(data);
-    }
-
-    // The server's `{t:'c'}` clear frame takes the same route as output, for the
-    // same reason: clearing straight away, mid-replay, would wipe the half-written
-    // snapshot and leave _pullHistory() measuring a buffer that is no longer the
-    // one it is restoring. Queued, it lands in order with the frames around it.
-    _onLiveClear() {
-      if (this._liveQueue) this._liveQueue.push({ at: performance.now(), clear: true });
-      else this.terminal?.clear();
-    }
-
-    // Capture phase, because xterm's own wheel handler stopPropagation()s every
-    // event it consumes, so a bubbling listener here would never see the wheel
-    // while the pane still has scrollback to scroll. Passive: this only observes,
-    // xterm keeps doing the scrolling.
-    _installWheelListener() {
-      this._onWheel = (ev) => {
-        if (ev.deltaY < 0) this._maybeLoadMoreHistory();
-      };
-      this.mountEl.addEventListener('wheel', this._onWheel, { capture: true, passive: true });
-    }
-
-    // Wheel-up at the top of a SHELL pane's scrollback. tmux repaints a burst of
-    // output (`cat` of a file longer than the screen) instead of scrolling it,
-    // so this pane's xterm ends up with about one screen of scrollback while
-    // tmux holds every line — and nothing here ever went back to ask, so the
-    // history was unreachable. The primary pane has the same pull
-    // (app.js _maybeRefetchFullHistory); Pane B is a separate xterm and needs its
-    // own. Shell only: a non-shell CLI's history is out of scope for this pull
-    // (its load already takes `full=1`; codex and Claude's inline renderer do
-    // grow tmux history, this just isn't how they recover it). The alternate-
-    // screen skip (nano, vim, less) only matters for a direct-PTY shell — under
-    // tmux the browser xterm never enters the alternate buffer.
-    _maybeLoadMoreHistory() {
-      if (this.sessionMode !== 'shell' || this._destroyed || !this.terminal) return;
-      if (this._bufferLoading) return;
-      // Mirrors app.js _maybeRefetchFullHistory and this pane's own
-      // _sendResize(): a detached session's own window already owns its PTY
-      // size and scrollback, so Pane B has nothing of its own to reconcile.
-      if (this.detachedSessions?.has(this.sessionId)) return;
-      const active = this.terminal.buffer.active;
-      if (active.type !== 'normal' || active.viewportY !== 0) return;
-      // Momentum scrolling fires this dozens of times per flick, so cooldown
-      // rather than latch; a pull that could only have downgraded the pane
-      // waits far longer.
-      const cooldown = this._historyPullUseless ? 60000 : 4000;
-      const now = Date.now();
-      if (now - this._historyPullAt < cooldown) return;
-      this._historyPullAt = now;
-      void this._pullHistory();
-    }
-
-    // Pulls a BOUNDED window of tmux's full history (the same TERMINAL_TAIL_SIZE
-    // a tab switch loads, so a multi-megabyte capture never lands on xterm's
-    // main thread) and replays it under the reader's current place. Holds the
-    // single-flight flag across the fetch AND the replay, like _loadBuffer().
-    async _pullHistory() {
-      this._bufferLoading = true;
-      let replayed = false;
-      let capturedAt = 0;
-      // Two budgets on one signal. The request itself gets the primary pane's
-      // (CodemanFetchDeadline, constants.js): live output is not held while it
-      // runs, but the single-flight flag is, so a coalesced `{t:'r'}` refresh and
-      // the marker owed by a close (_onSocketClosed()) both wait for it, at worst
-      // for that whole budget. Once the headers land live output IS held, so the
-      // body read gets the short one instead: a body that hangs would otherwise
-      // freeze the pane for the long budget. Aborting lands in the catch below,
-      // which releases the flag and the queue. AbortSignal.timeout() alone cannot
-      // be re-armed, hence the controller; without AbortController the pull
-      // simply has no deadline.
-      const controller = global.AbortController ? new global.AbortController() : null;
-      let abortTimer = null;
-      const armDeadline = (ms) => {
-        if (!controller) return;
-        clearTimeout(abortTimer);
-        abortTimer = setTimeout(() => controller.abort(), ms);
-      };
-      try {
-        armDeadline(global.CodemanFetchDeadline?.terminalFetchDeadlineMs?.({ full: true }) ?? HISTORY_PULL_TIMEOUT_MS);
-        const res = await fetch(`/api/sessions/${this.sessionId}/terminal?full=1&tail=${TERMINAL_TAIL_SIZE}`, {
-          signal: controller?.signal,
-        });
-        armDeadline(HISTORY_PULL_TIMEOUT_MS);
-        // The cutoff below is the response's arrival, the same `since` rule the
-        // primary pane uses (_finishBufferLoad). It is a client clock standing in
-        // for the instant tmux took the capture, which lies somewhere in the
-        // round trip, so a frame in that window can be lost or doubled. Bounded
-        // by one round trip and not closable without a server-side capture time.
-        capturedAt = performance.now();
-        // Opened only now: a frame from before the response is either replaced by
-        // the capture or written unchanged, so holding it for the round trip
-        // bought nothing and froze the pane for as long as the fetch took.
-        this._liveQueue = [];
-        const payload = (await res.json())?.data;
-        clearTimeout(abortTimer);
-        const buffer = payload?.terminalBuffer;
-        const term = this.terminal;
-        if (!buffer || !term || this._destroyed) return;
-        const rowsBefore = term.buffer.active.length;
-        const rowsIncoming = global.app?._estimateReplayRows?.(buffer, term.cols) ?? buffer.split('\n').length;
-        // xterm keeps at most `scrollback + rows` rows while tmux keeps far more
-        // lines, so a window of short lines can carry more rows than this pane
-        // can ever hold, and `rowsIncoming <= rowsBefore` would never come true.
-        const scrollbackCap = term.options?.scrollback || 0;
-        const paneFull = scrollbackCap > 0 && rowsBefore >= scrollbackCap + term.rows;
-        // Nothing to gain (this also covers a downgrade, which would delete
-        // history mid-scroll), and a reset+rewrite would jump the viewport. An
-        // untruncated window IS all of tmux's history and the next burst can add
-        // more, so keep the 4 s cooldown. A truncated window can never reach past
-        // what the pane shows, and every ask costs the server a capture-pane of
-        // the whole history (`tail` is cut after it): back off to 60 s, as the
-        // primary pane does (app.js _maybeRefetchFullHistory). A full pane backs
-        // off too, since no window can ever fit in it.
-        if (rowsIncoming <= rowsBefore || paneFull) {
-          if (payload.truncated || paneFull) this._historyPullUseless = true;
-          return;
-        }
-        this._historyPullUseless = false;
-        term.write('\x1bc');
-        replayed = true;
-        if (this._wsClosed) this._markerOwed = true;
-        await writeChunked(term, buffer, () => this._destroyed);
-        if (this._destroyed || !this.terminal) return;
-        // xterm parses asynchronously: an empty write's callback fires only
-        // after everything before it, so the row count below is the settled one.
-        await new Promise((resolve) => this.terminal.write('', resolve));
-        if (this._destroyed || !this.terminal) return;
-        // The replay grew the buffer UPWARD, so what was row 0 is now `delta`
-        // rows down; land there and the recovered history sits above it.
-        const delta = this.terminal.buffer.active.length - rowsBefore;
-        if (delta > 0) this.terminal.scrollToLine(delta);
-        else this.terminal.scrollToTop();
-      } catch {
-        /* Best-effort — live output keeps arriving whatever happens here. */
-      } finally {
-        clearTimeout(abortTimer);
-        const queued = this._liveQueue ?? [];
-        this._liveQueue = null;
-        // After a replay, only frames that arrived after the capture are news;
-        // earlier ones are already in it. With no replay, every held frame is.
-        const cutoff = replayed ? capturedAt : 0;
-        for (const entry of queued) {
-          if (entry.at < cutoff) continue;
-          if (entry.clear) this.terminal?.clear();
-          else this.terminal?.write(entry.data);
-        }
-        // Settled after the queue flush so the marker is the last thing on
-        // screen: a close during the pull wrote nothing (_onSocketClosed() defers
-        // it while a load runs), and a replay's own `\x1bc` (flagged above) wipes
-        // one written before it, which would paint a fresh, current-looking
-        // history while onData keeps silently dropping every keystroke on the
-        // dead socket. With a trailing refresh pending (_endBufferLoad) the marker
-        // is left to that refresh, which writes it below its own replay.
-        this._stampMarkerIfOwed();
-        this._endBufferLoad();
-      }
-    }
-
-    // The `{t:'r'}` server-refresh path: clear, then replay. Two refresh
-    // frames in a row used to start two concurrent replays, each clearing
-    // the terminal under the other's chunked write. A refresh that arrives
-    // mid-replay is COALESCED into one trailing re-run rather than ignored:
-    // the in-flight fetch may predate the drop the new frame is reporting,
-    // and no further frame is coming to correct stale content.
-    _refreshBuffer() {
-      if (this._bufferLoading) {
-        this._bufferRefreshPending = true;
-        return;
-      }
-      this.terminal?.clear();
-      // The clear wipes a "disconnected" marker (a `{t:'r'}` frame can queue a
-      // trailing refresh behind a pull that the socket's close then interrupts),
-      // so a refresh on a closed socket owes it back once its replay is written.
-      if (this._wsClosed) this._markerOwed = true;
-      void this._loadBuffer();
-    }
-
-    // Local reflow only — no PTY resize frame. Split out so a divider drag
-    // can reflow both panes at the browser's paint rate (rAF) while sending
-    // the actual `{t:'z'}` resize once, at drag end, matching the primary
-    // pane's own convention (throttledResize in terminal-ui.js).
-    localFit() {
-      if (!this.fitAddon) return;
-      this.fitAddon.fit();
-    }
-
-    fit() {
-      this.localFit();
-      this._sendResize();
-    }
-
-    _sendResize() {
-      if (!this._wsReady || !this.fitAddon) return;
-      // One PTY cannot hold two sizes (mirrors sendResize's own
-      // detachedElsewhere yield in terminal-ui.js): the session got detached
-      // to its own window AFTER this split was opened, so its own window now
-      // owns the PTY's size and Pane B must stand aside.
-      if (this.detachedSessions?.has(this.sessionId)) return;
-      const dims = this.fitAddon.proposeDimensions();
-      if (!dims) return;
-      // Send the real proposed dimensions unclamped, matching the primary
-      // pane's convention (terminal-ui.js's getTerminalDimensions()) — the
-      // server enforces its own valid range ([1,500]/[1,200] in ws-routes.ts).
-      // A 40/10 floor here misreported Pane B's real width to the PTY at the
-      // divider's own reachable 20% floor position, causing real
-      // output-wrapping bugs.
-      this.ws.send(JSON.stringify({ t: 'z', c: dims.cols, r: dims.rows, v: 'desktop' }));
-    }
-
-    destroy() {
-      this._destroyed = true;
-      if (this._onWheel) {
-        this.mountEl?.removeEventListener('wheel', this._onWheel, { capture: true });
-        this._onWheel = null;
-      }
-      if (this.ws) {
-        this.ws.onopen = null;
-        this.ws.onmessage = null;
-        // onclose fires asynchronously AFTER close(); without this it ran
-        // its "disconnected" write against a pane already torn down.
-        this.ws.onclose = null;
-        this.ws.onerror = null;
-        this.ws.close();
-        this.ws = null;
-      }
-      if (this.terminal) {
-        this.terminal.dispose();
-        this.terminal = null;
-      }
-      this.fitAddon = null;
-    }
-  }
-
-  global.SplitTerminalPane = SplitTerminalPane;
-})(window);
-
 Object.assign(CodemanApp.prototype, {
   /**
    * Desktop-only gate, same shape as home-sessions.js's shouldShowHomeSessions
@@ -670,6 +46,9 @@ Object.assign(CodemanApp.prototype, {
     // the old exact-node check below) bubbled straight through to
     // `document` and self-closed the menu it just opened.
     event?.stopPropagation();
+    // The tile grid and the split are never open together (tile-grid.js); the
+    // Split button shows as unavailable meanwhile.
+    if (this._tilesOwnTerminal?.()) return;
     if (this._splitPane) {
       this.closeSplitPane();
       return;
@@ -763,6 +142,8 @@ Object.assign(CodemanApp.prototype, {
     // see _applySplitButtonVisibility's comment for why both a JS check and
     // a CSS backstop exist.
     if (window.innerWidth < SPLIT_PANE_MIN_WIDTH) return;
+    // Never beside the tile grid: the main terminal is parked while it is open.
+    if (this._tilesOwnTerminal?.()) return;
     // No active session means there is no `.terminal-wrap` to split against
     // (the welcome overlay is showing) — without this, a split opened from
     // the home screen still created the container and connected Pane B, just
@@ -777,7 +158,7 @@ Object.assign(CodemanApp.prototype, {
     // B's own session tab while split can otherwise land here with
     // sessionId === activeSessionId: two live WebSockets to the same
     // session, each independently claiming PTY dimensions via its own `{t:'z',...}`
-    // resize frame. Refuse before creating any DOM or SplitTerminalPane.
+    // resize frame. Refuse before creating any DOM or TerminalTile.
     if (sessionId === this.activeSessionId) return;
     // The picker's own exclusions (buildSplitPickerSessions in constants.js),
     // re-applied here: the menu can sit open while a listed session's CLI
@@ -803,22 +184,38 @@ Object.assign(CodemanApp.prototype, {
 
     const paneB = document.createElement('div');
     paneB.className = 'terminal-pane-b';
-    paneB.innerHTML = `
-      <div class="terminal-pane-b-header">
-        <span class="session-name">${escapeHtml(session?.name || 'Session')}</span>
-        <button type="button" class="terminal-pane-b-close" onclick="app.closeSplitPane()" aria-label="Close split">&times;</button>
-      </div>
-      <div class="terminal-pane-b-container"></div>
-    `;
+    // Pane B's header: the harness logo, the name and the model, as on a grid
+    // tile, and the close button at a tile button's size.
+    const headerB = this._buildSplitPaneHeader();
+    const close = document.createElement('button');
+    close.type = 'button';
+    close.className = 'tile-btn tile-remove terminal-pane-b-close';
+    close.title = 'Close split';
+    close.setAttribute('aria-label', 'Close split');
+    close.textContent = '\u00D7';
+    close.addEventListener('click', () => this.closeSplitPane());
+    headerB.el.appendChild(close);
+    const bodyB = document.createElement('div');
+    bodyB.className = 'terminal-pane-b-container';
+    paneB.append(headerB.el, bodyB);
+    // Pane A is the main terminal, which has no header of its own: while the
+    // split is open it gets the same strip, so each session in the split view
+    // names its harness and model. It takes height from the main terminal,
+    // which the opening resize below fits through syncTerminalGeometry (#464);
+    // closeSplitPane gives it back.
+    const headerA = this._buildSplitPaneHeader();
+    headerA.el.classList.add('terminal-pane-a-header');
+    this._splitHeaders = { a: headerA, b: headerB };
 
     parent.insertBefore(container, wrap);
+    wrap.insertBefore(headerA.el, wrap.firstChild);
     container.appendChild(wrap);
     wrap.style.flexBasis = '50%';
     container.appendChild(divider);
     container.appendChild(paneB);
     paneB.style.flexBasis = '50%';
 
-    this._splitPane = new window.SplitTerminalPane(sessionId, paneB.querySelector('.terminal-pane-b-container'), {
+    this._splitPane = new window.TerminalTile(sessionId, bodyB, {
       mode: session?.mode,
       fontSettings: this.loadAppSettingsFromStorage?.() || {},
       detachedSessions: this.detachedSessions,
@@ -828,6 +225,7 @@ Object.assign(CodemanApp.prototype, {
          initial load — live output still arrives once/if the socket connects. */
     });
     this._splitSessionId = sessionId;
+    this._renderSplitChrome();
 
     // Pane A just went from full width to 50%, but nothing has told its
     // session's PTY/tmux window about it yet — the passive ResizeObserver in
@@ -855,6 +253,9 @@ Object.assign(CodemanApp.prototype, {
     this._splitPane.destroy();
     this._splitPane = null;
     this._splitSessionId = null;
+    // Before the refit below, so the main terminal gets its full height back.
+    this._splitHeaders?.a.el.remove();
+    this._splitHeaders = null;
     this._updateSplitButtonState(false);
 
     const container = document.querySelector('.terminal-split-container');
@@ -865,14 +266,16 @@ Object.assign(CodemanApp.prototype, {
     parent.insertBefore(wrap, container);
     container.remove();
 
-    if (this.fitAddon) this.fitAddon.fit();
+    // Pane A takes the whole width back and, with its header strip gone, its
+    // whole height: through syncTerminalGeometry (#464), never a bare
+    // fitAddon.fit(). sendResize fits that way as its first step.
     // The Pane-A-ends branch of the _onSessionDeleted wrapper below collapses the split
     // while activeSessionId is still the id the server just removed, so a
     // resize from here would be aimed at a session that no longer exists;
-    // the promoted session gets its own resize from selectSession().
-    if (!options.skipPrimaryResize) {
-      this.sendResize?.(this.activeSessionId, { force: true })?.catch?.(() => {});
-    }
+    // the promoted session gets its own resize from selectSession(), and the
+    // terminal is only refitted here.
+    if (options.skipPrimaryResize) this.syncTerminalGeometry?.();
+    else this.sendResize?.(this.activeSessionId, { force: true })?.catch?.(() => {});
   },
 
   // A click on .btn-split does one of two things — open the picker, or
@@ -880,6 +283,92 @@ Object.assign(CodemanApp.prototype, {
   // nothing on the button said which. `.split-open` + aria-pressed give it
   // the same active-state language as the codebase's other toggle buttons
   // (keyboard-accessory's Ctrl key, the voice-input mic).
+  /**
+   * A split pane's header strip: the harness logo, the session name and the
+   * model, the three a grid tile's header shows. Built from nodes (the name
+   * and the model are untrusted text) and painted by _renderSplitChrome.
+   */
+  _buildSplitPaneHeader() {
+    const el = document.createElement('div');
+    el.className = 'terminal-pane-b-header';
+    const harness = document.createElement('span');
+    harness.className = 'split-harness run-mode-dot';
+    harness.setAttribute('role', 'img');
+    const title = document.createElement('span');
+    title.className = 'split-title';
+    const name = document.createElement('span');
+    // `.session-name` is one of the translator's skipped surfaces (user text).
+    name.className = 'session-name';
+    // As on a tile: the name inside is never translated, the tooltip may be,
+    // and screen readers hear the model once, in the logo's accessible name.
+    const model = document.createElement('span');
+    model.className = 'split-model';
+    model.setAttribute('aria-hidden', 'true');
+    model.hidden = true;
+    const modelName = document.createElement('span');
+    modelName.setAttribute('data-i18n-skip', '');
+    model.appendChild(modelName);
+    title.append(name, model);
+    el.append(harness, title);
+    return { el, harness, name, model, modelName };
+  },
+
+  /**
+   * Both split headers from their sessions: Pane A shows the active session,
+   * Pane B its own. Runs after every tab render, so a rename or a model
+   * change reaches them; unchanged values write nothing.
+   */
+  _renderSplitChrome() {
+    const headers = this._splitHeaders;
+    if (!headers || !this._splitPane) return;
+    for (const [parts, id] of [
+      [headers.a, this.activeSessionId],
+      [headers.b, this._splitSessionId],
+    ]) {
+      const session = id ? this.sessions.get(id) : null;
+      if (!session) continue;
+      const name = this.getSessionName?.(session) || session.name || 'Session';
+      if (parts.nameValue !== name) {
+        parts.nameValue = name;
+        parts.name.textContent = name;
+      }
+      this._paintSessionHarness(parts, session, 'split-harness');
+    }
+  },
+
+  /**
+   * Paints a session header's harness logo and model: a grid tile's, and the
+   * split panes'. The logo is PR #532's `run-mode-dot <cliId>` slot (the id is
+   * data, never a branch), the model is text (describeSessionHarness,
+   * constants.js). Diffs against the values it last wrote, kept on `parts`,
+   * never against the DOM, which the translator may have rewritten: an
+   * unchanged session writes nothing, and this runs on every tab render.
+   *
+   * @param {{harness: HTMLElement, model: HTMLElement, modelName: HTMLElement}} parts - the
+   *   header's nodes (the model's box and the name inside it); the memo lives here too
+   * @param {object} session - the session the header shows
+   * @param {string} logoClass - the header's own class for its logo
+   */
+  _paintSessionHarness(parts, session, logoClass) {
+    const harness = window.CodemanSessionHarness.describeSessionHarness(session, window.__codemanCliCatalog);
+    const cls = `${logoClass} run-mode-dot${harness.id ? ` ${harness.id}` : ''}`;
+    if (parts.harnessClass !== cls) {
+      parts.harnessClass = cls;
+      parts.harness.className = cls;
+    }
+    if (parts.harnessTitle !== harness.title) {
+      parts.harnessTitle = harness.title;
+      parts.harness.title = harness.title;
+      parts.harness.setAttribute('aria-label', harness.title);
+      parts.model.title = harness.title;
+    }
+    if (parts.modelValue !== harness.model) {
+      parts.modelValue = harness.model;
+      parts.modelName.textContent = harness.model;
+      parts.model.hidden = !harness.model;
+    }
+  },
+
   _updateSplitButtonState(open) {
     const btn = document.querySelector('.btn-split');
     if (!btn) return;
@@ -900,10 +389,9 @@ Object.assign(CodemanApp.prototype, {
     // frame). Coalesced to one call per animation frame below — a raw
     // mousemove stream fires far faster than the browser repaints, and
     // without the rAF gate each event did a full xterm reflow on BOTH
-    // panes AND sent Pane B a `{t:'z'}` resize frame (SplitTerminalPane has
-    // no client-side "dims unchanged" skip), which fanned out into a
-    // `tmux resize-window` child plus a SIGWINCH per frame — roughly fifty
-    // of each dragging across half a wide viewport.
+    // panes AND sent Pane B a `{t:'z'}` resize frame, which fanned out
+    // into a `tmux resize-window` child plus a SIGWINCH per frame, roughly
+    // fifty of each dragging across half a wide viewport.
     const applyDragPercent = (clientX) => {
       const container = divider.parentElement;
       // The split can auto-collapse mid-drag (the other pane's session
@@ -1039,6 +527,15 @@ CodemanApp.prototype._onSessionDeleted = function (data) {
 // this, Pane A rebinds to a session that Pane B's independent WebSocket is
 // still attached to — two live WebSockets to one session, each claiming PTY
 // dimensions via its own `{t:'z',...}` resize frame.
+// Every tab render (any session change: a rename, a model switch) refreshes
+// the split headers too, the way tile-grid.js refreshes the tile headers.
+const _splitOriginalRenderSessionTabsImmediate = CodemanApp.prototype._renderSessionTabsImmediate;
+CodemanApp.prototype._renderSessionTabsImmediate = function (...args) {
+  const result = _splitOriginalRenderSessionTabsImmediate.apply(this, args);
+  this._renderSplitChrome?.();
+  return result;
+};
+
 const _originalSelectSession = CodemanApp.prototype.selectSession;
 CodemanApp.prototype.selectSession = function (sessionId, ...args) {
   if (this._splitPane && this._splitSessionId === sessionId) {

src/web/public/terminal-ui.js

@@ -92,6 +92,36 @@
   // Bound on page keys emitted from one gesture batch, mirroring the SGR tick
   // cap: a fling must not build a backlog that keeps paging after it stops.
   const PAGE_KEY_MAX_PER_BATCH = 3;
+
+  // Wheel delta → scroll lines (fractional), for a terminal `rows` tall. The
+  // body of the primary pane's _wheelScrollLinesFloat (see its comment for the
+  // Shift-axis trap and the deltaMode units), pure so a TerminalTile pages with
+  // the same math against its own row count.
+  function wheelDeltaLines(ev, rows) {
+    const delta = ev.shiftKey && Math.abs(ev.deltaX) > Math.abs(ev.deltaY) ? ev.deltaX : ev.deltaY;
+    if (!delta) return 0;
+    return ev.deltaMode === 1 // DOM_DELTA_LINE (Firefox mouse wheel)
+      ? delta
+      : ev.deltaMode === 2 // DOM_DELTA_PAGE
+        ? delta * (rows || 24)
+        : delta / 25; // DOM_DELTA_PIXEL (Chrome/WebKit, and every trackpad)
+  }
+
+  // Gesture travel → PageUp/PageDown keys for a terminal `rows` tall: adds
+  // `lines` to the sub-page travel already `pending`, and returns the travel
+  // left over plus the keys to send ('' below one page). The arithmetic of the
+  // primary pane's _maybePageCliTranscript, pure so a TerminalTile (which keeps
+  // its own pending travel) pages identically.
+  function pageKeysForTravel(pending, lines, rows) {
+    const perPage = Math.max(2, Math.round((rows || 24) * PAGE_KEY_SCREEN_FRACTION));
+    const total = (pending || 0) + lines;
+    const pages = Math.trunc(total / perPage);
+    const keys = pages
+      ? (pages < 0 ? KEY_PAGE_UP : KEY_PAGE_DOWN).repeat(Math.min(Math.abs(pages), PAGE_KEY_MAX_PER_BATCH))
+      : '';
+    return { pending: total - pages * perPage, keys };
+  }
+
   const TUI_PROMPT_DEFAULT_ROWS_FROM_BOTTOM = 4;
   // Composer navigation keys as xterm.js encodes user keystrokes: plain and
   // modified arrows (CSI A-D, CSI 1;mA-D, SS3 A-D), Home/End (CSI H/F, SS3
@@ -229,6 +259,8 @@
     KEY_PAGE_DOWN,
     PAGE_KEY_SCREEN_FRACTION,
     PAGE_KEY_MAX_PER_BATCH,
+    wheelDeltaLines,
+    pageKeysForTravel,
     TUI_PROMPT_DEFAULT_ROWS_FROM_BOTTOM,
     MOBILE_KEYBOARD_DISMISS_EXEMPT_SELECTOR,
     MOBILE_KEYBOARD_DISMISS_TAP_SLOP,
@@ -544,6 +576,9 @@ Object.assign(CodemanApp.prototype, {
     this._installMobileTapMouseGuard();
     this._installShiftDragSelection();
     this._installTouchSelectionFocusGuard();
+    // Focus coming back to the primary terminal ends a second pane's claim on
+    // the keyboard (see _focusedPane).
+    this.terminal.textarea?.addEventListener('focus', () => this._noteFocusedTile(null));
 
     // Let xterm's CompositionHelper own IME key events. In particular, a
     // non-composing keyCode 229 is how an active IME commits numbers and
@@ -587,6 +622,11 @@ Object.assign(CodemanApp.prototype, {
         return false;
       }
 
+      // Tile grid chords (Ctrl+Shift+G, Alt+Shift+Arrows): the capture handler
+      // has already acted on one that applies, and its preventDefault() does not
+      // stop xterm. Every event type, and BEFORE the Shift+Enter branch below.
+      if (this.tileShortcutFor?.(ev)) return false;
+
       // Smart copy (#211): with a selection, Ctrl+C copies it instead of sending
       // ^C. With NO selection the branch must fall through (return true, and no
       // preventDefault) or the interrupt key is lost, which is the whole reason
@@ -1265,7 +1305,8 @@ Object.assign(CodemanApp.prototype, {
     // A real mouse click normally reaches the PTY through xterm's own mouse
     // encoder, but that encoder only runs while mouseTrackingMode is ON — and
     // the server strips the enabling DECSETs from claude/codex/gemini output
-    // (isAltScreenStripMode, session.ts) so the wheel keeps scrolling
+    // (isAltScreenStripMode, session.ts) and from opencode's (isMuxMouseStripMode,
+    // so a drag selects text) so the wheel keeps scrolling
     // scrollback. Desktop clicks therefore stopped reporting entirely (the
     // same breakage the mobile touchend tap branch above works around).
     // Hand-encode the SGR report for plain left-clicks on those sessions.
@@ -1325,6 +1366,9 @@ Object.assign(CodemanApp.prototype, {
         // Same yield as sendResize: never resize a PTY whose session is showing
         // in its own window. Dragging the dashboard's border must not reshape it.
         const detachedElsewhere = !this.isSoloWindow && this.detachedSessions?.has(this.activeSessionId);
+        // The tile grid parks the main terminal: its session is sized by its
+        // tile, which this same timer refits below (_forEachTile).
+        const tilesOwnTerminal = this._tilesOwnTerminal?.();
         // ⚠️ Whether to fit is the SAME question as whether to send (issue #464).
         // This block used to fit unconditionally and skip only the SIGWINCH,
         // which is the one combination that cannot be right: it moves xterm to
@@ -1332,7 +1376,9 @@ Object.assign(CodemanApp.prototype, {
         // repaints from the shape it was told. Withhold both, or neither —
         // a reflow nothing is rendering for buys nothing and costs correctness.
         const dims =
-          this.activeSessionId && !keyboardUp && !detachedElsewhere ? this._geometryForResizeRequest() : null;
+          this.activeSessionId && !keyboardUp && !detachedElsewhere && !tilesOwnTerminal
+            ? this._geometryForResizeRequest()
+            : null;
         // ⚠️ A null measurement is NOT a reason to report the floor. It used to
         // fall back to a bare 40x10, which tells the PTY a shape nothing measured
         // and xterm does not hold — the write-only guess this whole change exists
@@ -1415,8 +1461,11 @@ Object.assign(CodemanApp.prototype, {
         // frame — this observer only ever measured Pane A's container, so
         // without this call Pane B never learned about a window resize, an
         // Alt+B sidebar toggle, or a tab-rail drag, and its PTY silently
-        // stayed at whatever size it was last dragged to.
-        this._splitPane?.fit();
+        // stayed at whatever size it was last dragged to. Grid tiles are left
+        // out: the grid's own observer (tile-grid.js _scheduleTileGridRefit)
+        // refits every one of them on the same resize, and a second fit here
+        // only re-measured six panes to send nothing.
+        this._forEachTile?.((tile) => tile.fit(), { grid: false });
       }, 300); // Trailing-edge: only fire after 300ms of no resize events
     };
 
@@ -1789,10 +1838,14 @@ Object.assign(CodemanApp.prototype, {
     // registers its own listener with `capture: true`; on bubble xterm's
     // `cancel()` (stopPropagation) would swallow exactly the handled events —
     // see the measured table in terminal-keycode229-recovery.js.
+    // Twin: TerminalTile (terminal-tile.js _createKeyCode229Recovery and its
+    // connect() key handler and onData) wires its own controller the same way
+    // for every grid tile and the split's Pane B; keep the two in step.
     try {
       this._keyCode229Recovery = window.CodemanKeyCode229Recovery?.create?.({
         textarea: this.terminal.textarea,
         emitRecovered: (data) => handleTerminalData(data),
+        getCompositionHelper: () => this.terminal?._core?._compositionHelper,
         isScreenReaderMode: () => this.terminal?.options?.screenReaderMode === true,
       });
     } catch {
@@ -1827,9 +1880,24 @@ Object.assign(CodemanApp.prototype, {
    * Register a custom link provider for xterm.js that detects file paths
    * in terminal output and makes them clickable.
    * When clicked, opens a floating log viewer window with live streaming.
+   *
+   * `target` defaults to the primary terminal and the active session. A second
+   * terminal (the split pane) passes its own `{ terminal, getSessionId,
+   * setHovered }`, so a path printed there opens against THAT pane's session and
+   * hovering it never flips the primary pane's `_linkHovered`. Only the primary
+   * registration is kept on `_terminalLinkProvider`, which the touch path reads.
+   * Returns the provider.
    */
-  registerFilePathLinkProvider() {
+  registerFilePathLinkProvider(target = {}) {
     const self = this;
+    const terminal = target.terminal || this.terminal;
+    const getSessionId = target.getSessionId || (() => this.activeSessionId);
+    const setHovered =
+      target.setHovered ||
+      ((hovered) => {
+        this._linkHovered = hovered;
+      });
+    const isPrimary = terminal === this.terminal;
 
     // Debug: Track if provider is being invoked
     let lastInvokedLine = -1;
@@ -1842,7 +1910,7 @@ Object.assign(CodemanApp.prototype, {
           console.debug('[LinkProvider] Checking line:', bufferLineNumber);
         }
 
-        const buffer = self.terminal.buffer.active;
+        const buffer = terminal.buffer.active;
         // provideLinks passes 1-based line number, getLine expects 0-based
         const line = buffer.getLine(bufferLineNumber - 1);
 
@@ -1866,7 +1934,7 @@ Object.assign(CodemanApp.prototype, {
         const logical = window.CodemanTerminalLines?.terminalLogicalLine(
           buffer,
           bufferLineNumber - 1,
-          self.terminal.cols,
+          terminal.cols,
           MAX_STITCHED_ROWS
         );
         if (!logical) {
@@ -1919,10 +1987,10 @@ Object.assign(CodemanApp.prototype, {
               window.open(text, '_blank', 'noopener,noreferrer');
             },
             hover() {
-              self._linkHovered = true;
+              setHovered(true);
             },
             leave() {
-              self._linkHovered = false;
+              setHovered(false);
             },
           });
         };
@@ -1978,17 +2046,18 @@ Object.assign(CodemanApp.prototype, {
               // path clicked in the response viewer previewed fine. The preview
               // reads those through the guarded attachment routes, so external
               // paths route there and the two surfaces agree.
-              if (previewsInFileViewer(text) || self._isExternalPreviewPath(text, self.activeSessionId)) {
-                self.openFilePreview(text, self.activeSessionId);
+              const sessionId = getSessionId();
+              if (previewsInFileViewer(text) || self._isExternalPreviewPath(text, sessionId)) {
+                self.openFilePreview(text, sessionId);
                 return;
               }
-              self.openLogViewerWindow(text, self.activeSessionId);
+              self.openLogViewerWindow(text, sessionId);
             },
             hover() {
-              self._linkHovered = true;
+              setHovered(true);
             },
             leave() {
-              self._linkHovered = false;
+              setHovered(false);
             },
           });
         };
@@ -2031,10 +2100,11 @@ Object.assign(CodemanApp.prototype, {
     // produce), so the tap path asks this SAME provider what is under the finger
     // rather than growing a second, driftable copy of the patterns.
     // See _terminalLinkAtPoint.
-    this._terminalLinkProvider = provider;
-    this.terminal.registerLinkProvider(provider);
+    if (isPrimary) this._terminalLinkProvider = provider;
+    terminal.registerLinkProvider(provider);
 
     console.log('[LinkProvider] File path link provider registered');
+    return provider;
   },
 
   /**
@@ -4480,13 +4550,70 @@ Object.assign(CodemanApp.prototype, {
   // Terminal Controls
   // ═══════════════════════════════════════════════════════════════
 
+  /**
+   * The terminal the keyboard is in, as `{ terminal, sessionId, isPrimary, tile }`.
+   *
+   * The ONE place a shortcut, voice or paste should ask "which pane?", rather
+   * than reading `this.terminal` / `this.activeSessionId`, which always mean the
+   * primary pane. It answers with the pane whose terminal was focused LAST, not
+   * with `document.activeElement`: clicking the mic or a header button moves
+   * DOM focus to that button, and the dictation it starts still belongs to the
+   * pane the user was typing in. A second pane (the split pane's Pane B) claims
+   * it from its own terminal's focus; the primary terminal's focus gives it back.
+   */
+  _focusedPane() {
+    let tile = this._focusedTile;
+    // With the tile grid open the main terminal is parked, so the pane is the
+    // focused tile even when DOM focus sits on a button or a panel.
+    if ((!tile || tile._destroyed || !tile.terminal) && this._tilesOwnTerminal?.()) {
+      tile = this._tileFor(this.activeSessionId);
+    }
+    if (tile && !tile._destroyed && tile.terminal) {
+      return { terminal: tile.terminal, sessionId: tile.sessionId, isPrimary: false, tile };
+    }
+    return { terminal: this.terminal, sessionId: this.activeSessionId, isPrimary: true, tile: null };
+  },
+
+  /** Record which second pane holds the keyboard (null: the primary terminal). */
+  _noteFocusedTile(tile) {
+    this._focusedTile = tile || null;
+  },
+
+  /**
+   * Run `fn(tile)` for every secondary terminal pane on screen: the split
+   * pane's second terminal and every tile of the tile grid (never both: the two
+   * modes are not open together). Font, weight, family and skin changes go
+   * through here so they reach every pane without a special case per pane kind.
+   * `{ grid: false }` skips grid tiles (they keep their own font size).
+   * Agent Teams terminals size themselves and are not tiles.
+   */
+  _forEachTile(fn, { grid = true } = {}) {
+    if (this._splitPane?.terminal) fn(this._splitPane);
+    if (!grid || !this._tileGrid?.open) return;
+    for (const { tile } of this._tileGrid.tiles.values()) {
+      if (tile.terminal) fn(tile);
+    }
+  },
+
+  // Clears the pane the keyboard is in. The chord itself also reaches that
+  // pane's xterm (the capture handler only preventDefault()s), so the ^L lands
+  // in the same pane whose display is cleared, never a different one.
   clearTerminal() {
-    this.terminal.clear();
+    this._focusedPane().terminal?.clear();
   },
 
   /** Insert editable text at the active prompt without pressing Enter. */
   insertTerminalText(text) {
     if (!this.activeSessionId || !text) return;
+    // A tile or the split's Pane B holds the keyboard: the text belongs to that
+    // pane's session. Those panes have no local-echo overlay, and the main
+    // overlay is parked behind the grid, so send it straight to the pane.
+    const pane = this._focusedPane?.();
+    if (pane && !pane.isPrimary) {
+      this._sendInputAsync(pane.sessionId, text);
+      pane.terminal?.focus();
+      return;
+    }
     // Under predict the text goes out via sendInput (bypasses onData), so the
     // hook never sees it: clear outstanding predictions here instead.
     if (this._localEchoPolicy === 'predict') this._predictiveEcho?.clearPredictions();
@@ -4510,6 +4637,16 @@ Object.assign(CodemanApp.prototype, {
     if (!this.activeSessionId) return;
 
     if (typeof CjkInput !== 'undefined') CjkInput.clear();
+    // A tile or Pane B holds the keyboard: its TUI owns the editable buffer
+    // (no local-echo overlay there), so kill the line in that pane's session,
+    // never in the parked main pane's.
+    const pane = this._focusedPane?.();
+    if (pane && !pane.isPrimary) {
+      this._sendInputAsync(pane.sessionId, '\x15');
+      this.showToast?.('Input cleared', 'success');
+      pane.terminal?.focus();
+      return;
+    }
     if (this._inputFlushTimeout) {
       clearTimeout(this._inputFlushTimeout);
       this._inputFlushTimeout = null;
@@ -4545,10 +4682,34 @@ Object.assign(CodemanApp.prototype, {
    * Ctrl+L is NOT sent here (Claude Code 2.x treats it as "clear conversation").
    */
   async restoreTerminalSize() {
+    // A second pane owns its own geometry: refit it and force its PTY to the
+    // size it renders at (TerminalTile.fit sends the same forced `f` resize
+    // sendResize sends below), whatever another device set. fit() says whether
+    // the resize went out; when it did not, say why rather than report a size
+    // that was never sent, as the primary branch does below.
+    const pane = this._focusedPane();
+    if (!pane.isPrimary) {
+      const sent = pane.tile.fit({ force: true });
+      if (sent !== false) {
+        this.showToast(`Terminal restored to ${pane.terminal.cols}x${pane.terminal.rows}`, 'success');
+      } else if (this.detachedSessions?.has(pane.sessionId)) {
+        // Its own window owns the PTY's size (TerminalTile._sendResize yields).
+        this.showToast('This session is sized by its own window', 'warning');
+      } else if (!pane.tile._wsReady) {
+        // The tile announces its size again as soon as its socket reopens.
+        this.showToast('Terminal not connected: its size is sent when it reconnects', 'warning');
+      } else {
+        this.showToast('Could not determine terminal size', 'error');
+      }
+      return;
+    }
     if (!this.activeSessionId) {
       this.showToast('No active session', 'warning');
       return;
     }
+    // Backstop: _focusedPane() answers with the focused tile while the grid is
+    // open, so this is reached only if that tile is gone mid-call.
+    if (this._tilesOwnTerminal?.()) return;
 
     // The pane belongs to the popup showing it, so this window has nothing to
     // restore. Say so rather than reporting a size that was never sent — the
@@ -4639,15 +4800,18 @@ Object.assign(CodemanApp.prototype, {
    * terminal._core for cell dimensions, and falls back to cleaning normally if
    * a future xterm renames it. SelectionMode.COLUMN is 3.
    */
-  cleanedTerminalSelection(text) {
-    const raw = text ?? (this.terminal?.hasSelection?.() ? this.terminal.getSelection() : '');
+  cleanedTerminalSelection(text, target = {}) {
+    // `target` names a second terminal (the split pane) and its session; both
+    // default to the primary pane, whose `this.terminal` this file otherwise reads.
+    const terminal = target.terminal || this.terminal;
+    const raw = text ?? (terminal?.hasSelection?.() ? terminal.getSelection() : '');
     if (!raw) return '';
-    if (this.terminal?._core?._selectionService?._activeSelectionMode === 3) return raw;
+    if (terminal?._core?._selectionService?._activeSelectionMode === 3) return raw;
     const clean = window.CodemanCopySelection?.clean;
     if (!clean) return raw;
-    const range = this._normalisedSelectionRange();
+    const range = this._normalisedSelectionRange(terminal);
     return clean(raw, {
-      margin: this._cliGutterColumns(),
+      margin: this._cliGutterColumns(target.sessionId),
       firstLinePartial: !!range && range.start.x > 0,
     });
   },
@@ -4717,8 +4881,11 @@ Object.assign(CodemanApp.prototype, {
   // Copy the current terminal selection. Goes through _copyText (Clipboard API,
   // then a hidden-textarea + execCommand fallback) because install.sh's LAN
   // option serves plain HTTP, where navigator.clipboard is undefined.
-  async copyTerminalSelection(text) {
-    const selection = this.cleanedTerminalSelection(text);
+  async copyTerminalSelection(text, target = {}) {
+    // Every terminal touched below is the TARGET one: clearing or refocusing the
+    // primary after copying from the split pane would hit the wrong pane.
+    const terminal = target.terminal || this.terminal;
+    const selection = this.cleanedTerminalSelection(text, target);
     // trim(), not emptiness: a multi-row drag across padding cleans to newlines
     // alone, which are truthy, and a bare newline pasted into a chat composer
     // or a shell submits the line. decideAutoCopy applies the same rule.
@@ -4727,7 +4894,7 @@ Object.assign(CodemanApp.prototype, {
       // selection, so a padding-only selection left set can no longer swallow a
       // later interrupt; it cleans to '' and the press reaches the PTY. What the
       // clear avoids is a highlight that sits there having copied nothing.
-      this.terminal?.clearSelection?.();
+      terminal?.clearSelection?.();
       this.showToast('Nothing to copy', 'warning');
       return false;
     }
@@ -4735,14 +4902,14 @@ Object.assign(CodemanApp.prototype, {
     if (ok) {
       // Clearing is what makes a second Ctrl+C an interrupt (and xterm already
       // drops the selection on any keypress, so this matches existing feel).
-      this.terminal.clearSelection?.();
+      terminal.clearSelection?.();
       this.showToast('Copied to clipboard', 'success');
     } else {
       this.showToast('Failed to copy', 'error');
     }
     // The execCommand fallback focuses a temp textarea, so hand focus back. This
     // is the CJK-aware focus router, not xterm's raw focus().
-    this.terminal.focus();
+    terminal.focus();
     return ok;
   },
 
@@ -4755,8 +4922,9 @@ Object.assign(CodemanApp.prototype, {
    * settings save can forget to call, and the toggle takes effect on the next
    * selection instead of the next reload. ⚠️ The test is `!== false`, not
    * `=== true`: this one defaults ON, and the desktop branch of
-   * getDefaultSettings returns {} and leans on the read sites for defaults, so
-   * a device that has never opened App Settings has no stored value at all.
+   * getDefaultSettings sets no copyStripMargin and leans on the read sites for
+   * defaults, so a device that has never opened App Settings has no stored
+   * value at all.
    */
   _copyStripMarginEnabled() {
     try {
@@ -5205,9 +5373,10 @@ Object.assign(CodemanApp.prototype, {
       // follows the same path as a desktop click.
       this._dispatchSyntheticTerminalClick(touch.clientX, touch.clientY);
     } else if (shouldActivate && this._shouldReportMouseToCli()) {
-      // Claude/Codex/Gemini DECSETs are stripped from the browser stream, so
-      // report directly to the PTY while retaining local touch scrollback. Only
-      // while the CLI actually has tracking on (see _shouldReportMouseToCli).
+      // This session's mouse DECSETs are stripped from the browser stream
+      // (strip-full or strip-mux-and-mouse), so report directly to the PTY
+      // while retaining local touch scrollback, and only while the CLI
+      // actually has tracking on (see _shouldReportMouseToCli).
       this._sendSyntheticSgrTap(touch.clientX, touch.clientY);
     }
 
@@ -5271,69 +5440,81 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
-  // Mirror of the server's isAltScreenStripMode (session.ts): session modes whose
-  // output stream has mouse-tracking DECSET sequences stripped before reaching the
-  // browser. For these, xterm's live mouseTrackingMode is useless as a gate — the
-  // PTY-side TUI keeps tracking enabled, we just never see the enable sequence.
   /**
-   * True when the browser has to hand-encode a click report for the CLI.
+   * True when the browser has to hand-encode a click report for the CLI: the
+   * server stripped this session's mouse-tracking DECSETs out of the stream (so
+   * xterm's own encoder is permanently idle here and something has to stand in
+   * for it) AND the CLI has a tracking mode on right now.
    *
-   * Two conditions, and dropping either one is a bug that has already happened:
+   * One flag answers both. The server sets `cliMouseTracking` only as it strips a
+   * tracking DECSET (`_recordStrippedMouseMode` in session.ts, called from the
+   * mouse-strip branch of `_handleTerminalOutput` and nowhere else), so it can
+   * only ever be true for a mode whose DECSETs are stripped: whichever modes the
+   * registry decides to strip, the browser follows, with no mode list here to
+   * keep in step. For a `preserve` / `strip-mux-only` mode the flag stays false
+   * and xterm keeps encoding its own reports. That invariant is pinned server-side
+   * in test/claude-scrollback-strip.test.ts.
    *
-   * 1. The session's mode is one whose mouse DECSETs the server STRIPS out of
-   *    the stream (claude/codex/gemini, `isAltScreenStripMode`), which is why
-   *    xterm's own encoder is permanently idle here and something has to stand
-   *    in for it.
-   * 2. The CLI actually has a mouse-tracking mode on right now. The server
-   *    records that as it strips (`_recordStrippedMouseMode` in session.ts) and
-   *    publishes it as `cliMouseTracking`. Without this half the browser
-   *    reported EVERY click, so a CLI sitting at its composer with no dialog
-   *    open, or a pane that has fallen back to a shell prompt, received mouse
-   *    reports it never asked for. A shell prints those as literal text
-   *    (`[<0;88;20M`) and they garble the next line typed.
+   * Without the flag the browser reported EVERY click, so a CLI sitting at its
+   * composer with no dialog open, or a pane that has fallen back to a shell
+   * prompt, received mouse reports it never asked for. A shell prints those as
+   * literal text (`[<0;88;20M`) and they garble the next line typed.
    *
    * Fails toward silence: an unknown or stale flag reports nothing rather than
    * injecting bytes. After a server restart the flag is false until the CLI
    * re-emits its DECSET, which closing and reopening a dialog does.
+   *
+   * `sessionId` defaults to the primary pane's session; a TerminalTile passes
+   * its own (through _handleDesktopTerminalClick's target), never the active one.
    */
-  _shouldReportMouseToCli() {
-    const session = this.sessions?.get(this.activeSessionId);
-    const mode = session?.mode || 'claude';
-    if (mode !== 'claude' && mode !== 'codex' && mode !== 'gemini') return false;
-    return session?.cliMouseTracking === true;
+  _shouldReportMouseToCli(sessionId = this.activeSessionId) {
+    return this.sessions?.get(sessionId)?.cliMouseTracking === true;
   },
 
   // True when xterm's viewport shows the live PTY screen (not scrolled up into
   // local scrollback). SGR coordinates are only meaningful then: the TUI's
   // screen is the bottom `rows` of the buffer, so a report computed from a
   // scrolled-up viewport would hit-test a completely different row.
-  _terminalViewportAtBottom() {
-    const buf = this.terminal?.buffer?.active;
+  // `terminal` defaults to the primary pane's (a TerminalTile passes its own).
+  _terminalViewportAtBottom(terminal = this.terminal) {
+    const buf = terminal?.buffer?.active;
     return !buf || buf.viewportY >= buf.baseY;
   },
 
   // Map a viewport point to a 1-based terminal cell the same way xterm maps a
   // click: offset inside .xterm-screen divided by the rendered cell size,
   // clamped to the grid. Returns null when the terminal isn't measurable yet.
-  _clientPointToCell(clientX, clientY) {
-    if (!this.terminal || !Number.isFinite(clientX) || !Number.isFinite(clientY)) return null;
-    const screen = this.terminal.element?.querySelector('.xterm-screen');
-    const cell = this.terminal._core?._renderService?.dimensions?.css?.cell;
+  // `terminal` defaults to the primary pane's (a TerminalTile passes its own).
+  _clientPointToCell(clientX, clientY, terminal = this.terminal) {
+    if (!terminal || !Number.isFinite(clientX) || !Number.isFinite(clientY)) return null;
+    const screen = terminal.element?.querySelector('.xterm-screen');
+    const cell = terminal._core?._renderService?.dimensions?.css?.cell;
     if (!screen || !cell?.width || !cell?.height) return null;
     const rect = screen.getBoundingClientRect();
-    const col = Math.max(1, Math.min(this.terminal.cols, Math.floor((clientX - rect.left) / cell.width) + 1));
-    const row = Math.max(1, Math.min(this.terminal.rows, Math.floor((clientY - rect.top) / cell.height) + 1));
+    const col = Math.max(1, Math.min(terminal.cols, Math.floor((clientX - rect.left) / cell.width) + 1));
+    const row = Math.max(1, Math.min(terminal.rows, Math.floor((clientY - rect.top) / cell.height) + 1));
     return { col, row };
   },
 
   // Encode a tap as an SGR mouse report (press + release at button 0) and send it
-  // to the PTY directly, bypassing xterm's mouse encoder.
-  _sendSyntheticSgrTap(clientX, clientY) {
-    if (!this.activeSessionId) return;
-    if (!this._terminalViewportAtBottom()) return; // scrollback click → misfire, do nothing
-    const pos = this._clientPointToCell(clientX, clientY);
+  // to the PTY directly, bypassing xterm's mouse encoder. `target` ({ terminal,
+  // sessionId, ephemeral }) aims it at a TerminalTile instead of the primary
+  // pane; either of the first two left out means the primary pane's.
+  // `ephemeral: true` sends it through _sendInputEphemeral instead of the
+  // persisted exactly-once queue: a TerminalTile's mouse reports never enter
+  // that queue (CLAUDE.md, Split-pane sessions), or a reload would replay one
+  // onto a later screen. Left out, the report stays on _sendInputAsync, as the
+  // primary pane always sent it.
+  _sendSyntheticSgrTap(clientX, clientY, target = {}) {
+    const sessionId = target.sessionId || this.activeSessionId;
+    const terminal = target.terminal || this.terminal;
+    if (!sessionId) return;
+    if (!this._terminalViewportAtBottom(terminal)) return; // scrollback click → misfire, do nothing
+    const pos = this._clientPointToCell(clientX, clientY, terminal);
     if (!pos) return;
-    this._sendInputAsync(this.activeSessionId, `\x1b[<0;${pos.col};${pos.row}M\x1b[<0;${pos.col};${pos.row}m`);
+    const report = `\x1b[<0;${pos.col};${pos.row}M\x1b[<0;${pos.col};${pos.row}m`;
+    if (target.ephemeral) this._sendInputEphemeral(sessionId, report);
+    else this._sendInputAsync(sessionId, report);
   },
 
   // True when a parsed CLI version string ('2.1.187' — banner-parsed on the
@@ -5389,18 +5570,17 @@ Object.assign(CodemanApp.prototype, {
 
   /** Unrounded variant for the smooth local-scroll path, which accumulates
    *  sub-line fractions across events instead of forcing every tiny trackpad
-   *  delta to a whole ±1 line. Same unit handling and Shift-axis trap. */
+   *  delta to a whole ±1 line. Same unit handling and Shift-axis trap. The
+   *  math is the pure CodemanTerminalInput.wheelDeltaLines (top of this file),
+   *  which a TerminalTile calls with its own row count. */
   _wheelScrollLinesFloat(ev) {
-    const delta = ev.shiftKey && Math.abs(ev.deltaX) > Math.abs(ev.deltaY) ? ev.deltaX : ev.deltaY;
-    if (!delta) return 0;
-    return ev.deltaMode === 1 // DOM_DELTA_LINE (Firefox mouse wheel)
-      ? delta
-      : ev.deltaMode === 2 // DOM_DELTA_PAGE
-        ? delta * (this.terminal?.rows || 24)
-        : delta / 25; // DOM_DELTA_PIXEL (Chrome/WebKit, and every trackpad)
+    return window.CodemanTerminalInput.wheelDeltaLines(ev, this.terminal?.rows);
   },
 
-  _shouldForwardWheelToApp(ev) {
+  // `target` ({ terminal, sessionId }) asks the question for a TerminalTile:
+  // its own terminal's tracking mode and its own session, never the active one.
+  // Either field left out means the primary pane's.
+  _shouldForwardWheelToApp(ev, target = {}) {
     if (ev.shiftKey) return false;
     // Opt-out (App Settings → Input → "Wheel scrolls local history"): pin the
     // plain wheel to xterm's own scrollback like pre-#144, for users who prefer
@@ -5417,9 +5597,9 @@ Object.assign(CodemanApp.prototype, {
     // falls through to _maybePageCliTranscript, so the gesture still pages the
     // CLI's transcript and the setting keeps meaning exactly what it says.
     if (this.loadAppSettingsFromStorage?.()?.terminalWheelLocalScrollback) return false;
-    const mode = this.terminal?.modes?.mouseTrackingMode;
+    const mode = (target.terminal || this.terminal)?.modes?.mouseTrackingMode;
     if (mode && mode !== 'none') return false;
-    const session = this.sessions?.get(this.activeSessionId);
+    const session = this.sessions?.get(target.sessionId || this.activeSessionId);
     const sessionMode = session?.mode || 'claude';
     if (sessionMode !== 'claude') return false;
     if (!this._cliVersionAtLeast(session?.cliVersion, '2.1.187')) return false;
@@ -5474,6 +5654,10 @@ Object.assign(CodemanApp.prototype, {
    * tmux send-keys server-side, so per-event writes would spawn a process storm
    * on a single flick; the queue is bounded so a wild scroll can't build a
    * backlog that keeps scrolling after the finger stops.
+   *
+   * A TerminalTile keeps its own narrow twin (TerminalTile._queueScrollBytes,
+   * terminal-tile.js: same 40ms window, same 512-byte bound) because this queue
+   * flushes to the active session only; keep the two in step.
    */
   _queueScrollBytes(data) {
     if (!data || !this.activeSessionId) return;
@@ -5485,18 +5669,39 @@ Object.assign(CodemanApp.prototype, {
   },
 
   /**
-   * True when this session's LOCAL scrollback is structurally empty: a Claude
-   * pane in repaint mode, where tmux reports `history_size≈0` and every frame
-   * overwrites the last, so xterm's normal buffer never grows past one screen
+   * True when this session's LOCAL scrollback is structurally empty: a pane whose
+   * TUI repaints one full screen in place, so tmux keeps no history for it
+   * (`history_size≈0`) and xterm's normal buffer never grows past one screen
    * (`baseY === 0`). Scrolling that buffer is a no-op no matter how the gesture
    * is routed — the "wheel does nothing at all" half of the #205 retest.
+   *
+   * Two shapes, measured separately:
+   *  - `claude` in repaint mode (the original, #205 round 2), and
+   *  - `opencode`, whose TUI runs on the ALTERNATE SCREEN (opencode 1.18.31: tmux
+   *    `alternate_on=1`, `history_size=0`) and so pushes nothing into the
+   *    terminal's scrollback at all. It pages its own transcript with the same
+   *    PageUp/PageDown keys (`messages_page_up/down`) but IGNORES SGR wheel
+   *    reports — six `\x1b[<64;…M` reports against an idle pane left the capture
+   *    byte-identical — so paging is the only gesture that reaches it. Without
+   *    this the wheel was silently dead in every opencode tab.
+   *
+   * Every other mode is deliberately absent: shell/pi own real terminal
+   * scrollback, and codex/gemini/antigravity/grok/deepseek/omp page-key behaviour
+   * is unverified (docs/scrollback-fix-plan.md).
+   *
+   * `target` ({ terminal, sessionId, localRows }) asks for a TerminalTile, which
+   * calls this with its own session and terminal, so the mode list above stays
+   * here alone. `localRows` replaces `baseY` as the history row count: a tile
+   * discounts the stale rows its own load order leaves above the screen
+   * (TerminalTile._localRows). Every field left out means the primary pane's.
    */
-  _localScrollbackIsHollow() {
-    const mode = this.sessions?.get(this.activeSessionId)?.mode || 'claude';
-    if (mode !== 'claude') return false;
-    const buf = this.terminal?.buffer?.active;
+  _localScrollbackIsHollow(target = {}) {
+    const mode = this.sessions?.get(target.sessionId || this.activeSessionId)?.mode || 'claude';
+    if (mode !== 'claude' && mode !== 'opencode') return false;
+    const buf = (target.terminal || this.terminal)?.buffer?.active;
     if (!buf || buf.type === 'alternate') return false;
-    return (buf.baseY || 0) === 0;
+    const rows = Number.isFinite(target.localRows) ? target.localRows : buf.baseY;
+    return (rows || 0) === 0;
   },
 
   /**
@@ -5504,21 +5709,28 @@ Object.assign(CodemanApp.prototype, {
    * coalesced PageUp/PageDown key sends so the CLI pages its OWN transcript.
    *
    * The rescue path for every way `_shouldForwardWheelToApp` can come back false
-   * on a Claude session that has no local history to fall back on: the CLI
-   * version probe failed or is genuinely older than 2.1.187, the CLI's mouse
-   * tracking flag is unset (the inline renderer, or fullscreen right after a
-   * server restart), or the user turned on "Wheel scrolls local history" (which
-   * pins the wheel to a buffer that, for a repaint-mode CLI, is empty: the
-   * setting's footgun). Before this, all of those produced a completely dead
-   * gesture; the #205 reporter proved the keyboard route works by paging back
-   * through intact text with Fn+Up.
+   * on a session that has no local history to fall back on: the CLI version probe
+   * failed or is genuinely older than 2.1.187, the CLI's mouse tracking flag is
+   * unset (the inline renderer, or fullscreen right after a server restart), the
+   * user turned on "Wheel scrolls local history" (which pins the wheel to a buffer
+   * that, for a repaint-mode CLI, is empty: the setting's footgun), or the CLI is
+   * opencode, which never fills the buffer and never accepts the wheel. Before
+   * this, all of those produced a completely dead gesture; the #205 reporter
+   * proved the keyboard route works by paging back through intact text with Fn+Up.
    *
-   * Triple-guarded (claude mode + gate false + `baseY === 0`), so a session with
-   * real local scrollback is never touched. Shift is excluded on purpose: it is
-   * the explicit "give me local scrollback" gesture and must keep that meaning.
+   * Guarded by `_localScrollbackIsHollow()` plus a false forwarding gate, so a
+   * session with real local scrollback is never touched. Shift is excluded on
+   * purpose: it is the explicit "give me local scrollback" gesture and must keep
+   * that meaning.
    *
    * @returns true when the gesture was consumed here (the caller must not also
    *          scroll locally).
+   *
+   * Twin: TerminalTile._maybePageCliTranscript (terminal-tile.js) pages a tile
+   * through the same gates and the same pageKeysForTravel arithmetic; keep the
+   * two in step. The tile adds one gate this pane cannot need, viewport at the
+   * bottom: hollow here means baseY 0, so this viewport is always there, while a
+   * tile is hollow with its own discounted rows still above the screen.
    */
   _maybePageCliTranscript(ev, lines) {
     if (!lines || ev?.shiftKey || !this.activeSessionId) return false;
@@ -5528,15 +5740,9 @@ Object.assign(CodemanApp.prototype, {
       this._pageKeySession = this.activeSessionId;
       this._pageKeyPending = 0;
     }
-    const tuning = window.CodemanTerminalInput;
-    const perPage = Math.max(2, Math.round((this.terminal?.rows || 24) * tuning.PAGE_KEY_SCREEN_FRACTION));
-    const pending = (this._pageKeyPending || 0) + lines;
-    const pages = Math.trunc(pending / perPage);
-    this._pageKeyPending = pending - pages * perPage;
-    if (pages) {
-      const key = pages < 0 ? tuning.KEY_PAGE_UP : tuning.KEY_PAGE_DOWN;
-      this._queueScrollBytes(key.repeat(Math.min(Math.abs(pages), tuning.PAGE_KEY_MAX_PER_BATCH)));
-    }
+    const step = window.CodemanTerminalInput.pageKeysForTravel(this._pageKeyPending, lines, this.terminal?.rows);
+    this._pageKeyPending = step.pending;
+    if (step.keys) this._queueScrollBytes(step.keys);
     this._logScrollRouting('page-keys');
     return true;
   },
@@ -5591,18 +5797,26 @@ Object.assign(CodemanApp.prototype, {
   // synthetic SGR press could e.g. dismiss a claude permission dialog),
   // clicks outside the cell grid, and sessions where xterm's own encoder is
   // live (it reported the click itself — a second report would double-move).
-  _handleDesktopTerminalClick(ev) {
-    if (!this.terminal || !ev?.isTrusted) return;
+  //
+  // `target` ({ terminal, sessionId, linkHovered, ephemeral }) runs the same
+  // skips for a TerminalTile's click: its own terminal, its own session's
+  // tracking flag and its own link hover (the primary pane's _linkHovered
+  // belongs to its terminal alone). `ephemeral` reaches _sendSyntheticSgrTap,
+  // so a TerminalTile's mouse report never enters the persisted input queue.
+  // Every field left out means the primary pane's.
+  _handleDesktopTerminalClick(ev, target = {}) {
+    const terminal = target.terminal || this.terminal;
+    if (!terminal || !ev?.isTrusted) return;
     if (ev.button !== 0 || ev.detail !== 1) return;
     if (ev.shiftKey || ev.altKey || ev.ctrlKey || ev.metaKey) return;
-    const mode = this.terminal.modes?.mouseTrackingMode;
+    const mode = terminal.modes?.mouseTrackingMode;
     if (mode && mode !== 'none') return;
-    if (!this._shouldReportMouseToCli()) return;
-    if (this.terminal.hasSelection?.()) return;
-    if (this._linkHovered) return; // link provider hover/leave callbacks (registerFilePathLinkProvider)
+    if (!this._shouldReportMouseToCli(target.sessionId)) return;
+    if (terminal.hasSelection?.()) return;
+    if (target.linkHovered ?? this._linkHovered) return; // link provider hover/leave callbacks (registerFilePathLinkProvider)
     if (performance.now() <= (this._trustedTapMouseSuppressUntil || 0)) return;
     if (!ev.target?.closest?.('.xterm-screen')) return;
-    this._sendSyntheticSgrTap(ev.clientX, ev.clientY);
+    this._sendSyntheticSgrTap(ev.clientX, ev.clientY, target);
   },
 
   /**
@@ -5616,7 +5830,8 @@ Object.assign(CodemanApp.prototype, {
    * The reason is that the habit and xterm's Shift mean different things once
    * the DECSETs are stripped. xterm reads Shift as "force selection" ONLY while
    * the app actually has mouse tracking on; the server strips those DECSETs for
-   * claude/codex/gemini (isAltScreenStripMode), so xterm's mouseTrackingMode is
+   * claude/codex/gemini (isAltScreenStripMode) and opencode (isMuxMouseStripMode),
+   * so xterm's mouseTrackingMode is
    * permanently `none`, that branch is unreachable, and Shift instead falls into
    * `_onIncrementalClick` — EXTEND an existing selection. Extending is a no-op
    * when `selectionStart` is null, so the drag never anchors and no selection is
@@ -5671,11 +5886,20 @@ Object.assign(CodemanApp.prototype, {
   },
 
   increaseFontSize() {
+    // With the tile grid open, Ctrl +/- sizes the tiles (their own font size).
+    if (this._tilesOwnTerminal?.()) {
+      this.setTileFontSize(Math.min(this._tileGridFontSize() + 2, 24));
+      return;
+    }
     const current = this.terminal.options.fontSize || 14;
     this.setFontSize(Math.min(current + 2, 24));
   },
 
   decreaseFontSize() {
+    if (this._tilesOwnTerminal?.()) {
+      this.setTileFontSize(Math.max(this._tileGridFontSize() - 2, 10));
+      return;
+    }
     const current = this.terminal.options.fontSize || 14;
     this.setFontSize(Math.max(current - 2, 10));
   },
@@ -5688,10 +5912,13 @@ Object.assign(CodemanApp.prototype, {
     // Update overlay font cache and re-render at new cell dimensions
     this._localEchoOverlay?.refreshFont();
     this._predictiveEcho?.refreshFont();
-    if (this._splitPane?.terminal) {
-      this._splitPane.terminal.options.fontSize = size;
-      this._splitPane.fitAddon?.fit();
-    }
+    this._forEachTile?.(
+      (tile) => {
+        tile.terminal.options.fontSize = size;
+        tile.fit(); // a font change is a size change: tell its PTY too (#464)
+      },
+      { grid: false }
+    );
   },
 
   /**
@@ -5717,10 +5944,10 @@ Object.assign(CodemanApp.prototype, {
     this._refitAfterCellSizeChange();
     this._localEchoOverlay?.refreshFont();
     this._predictiveEcho?.refreshFont();
-    if (this._splitPane?.terminal) {
-      this._splitPane.terminal.options.fontFamily = resolved;
-      this._splitPane.fitAddon?.fit();
-    }
+    this._forEachTile?.((tile) => {
+      tile.terminal.options.fontFamily = resolved;
+      tile.fit(); // a font change is a size change: tell its PTY too (#464)
+    });
   },
 
   /**
@@ -5772,11 +5999,11 @@ Object.assign(CodemanApp.prototype, {
         /* pane not laid out yet — its own resize observer refits it */
       }
     }
-    if (this._splitPane?.terminal) {
-      this._splitPane.terminal.options.fontWeight = fontWeight;
-      this._splitPane.terminal.options.fontWeightBold = fontWeightBold;
-      this._splitPane.fitAddon?.fit();
-    }
+    this._forEachTile?.((tile) => {
+      tile.terminal.options.fontWeight = fontWeight;
+      tile.terminal.options.fontWeightBold = fontWeightBold;
+      tile.fit(); // a font change is a size change: tell its PTY too (#464)
+    });
   },
 
   loadFontSize() {
@@ -5995,6 +6222,9 @@ Object.assign(CodemanApp.prototype, {
     // settle-time refit through this call and has no fallback, which is correct:
     // a pane it does not own is not its to refit either.
     if (!this.isSoloWindow && this.detachedSessions?.has(sessionId)) return false;
+    // Backstop: while the tile grid owns the terminal, a tile sizes this PTY and
+    // the parked main terminal measures nothing worth sending.
+    if (this._tilesOwnTerminal?.()) return false;
     // Fit, floor, and apply in one step so the numbers below are the numbers
     // xterm is actually holding (or, while another device holds the width,
     // the numbers this container would hold if the PTY followed).
@@ -6245,13 +6475,13 @@ Object.assign(CodemanApp.prototype, {
         }
       }
     }
-    if (this._splitPane?.terminal) {
-      this._splitPane.terminal.options.minimumContrastRatio = minimumContrastRatio;
-      this._splitPane.terminal.options.theme = { ...theme };
+    this._forEachTile?.((tile) => {
+      tile.terminal.options.minimumContrastRatio = minimumContrastRatio;
+      tile.terminal.options.theme = { ...theme };
       try {
-        this._splitPane.terminal.refresh(0, this._splitPane.terminal.rows - 1);
+        tile.terminal.refresh(0, tile.terminal.rows - 1);
       } catch {}
-    }
+    });
   },
 });
 

src/web/public/upload.html

@@ -1,155 +0,0 @@
-<!DOCTYPE html>
-<html lang="en"><head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
-<title>Upload Screenshot - Codeman</title>
-<style>
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
-    background: #0d1117; color: #c9d1d9;
-    min-height: 100vh; min-height: 100dvh;
-    display: flex; align-items: center; justify-content: center;
-    padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
-    -webkit-text-size-adjust: 100%;
-  }
-  .container { max-width: 480px; width: 100%; padding: 24px; }
-  h1 { font-size: 1.4em; margin-bottom: 16px; color: #58a6ff; }
-  .drop-zone {
-    border: 2px dashed #30363d; border-radius: 12px;
-    padding: 48px 20px; text-align: center;
-    -webkit-tap-highlight-color: transparent;
-    transition: border-color 0.2s, background 0.2s;
-  }
-  .drop-zone.active { border-color: #58a6ff; background: #161b22; }
-  .drop-zone p { margin-bottom: 12px; font-size: 1.1em; }
-  .drop-zone small { color: #8b949e; }
-  input[type=file] { display: none; }
-  .preview { margin-top: 16px; text-align: center; display: none; }
-  .preview img { max-width: 100%; max-height: 300px; border-radius: 8px; border: 1px solid #30363d; }
-  .preview .name { margin-top: 6px; font-size: 0.85em; color: #8b949e; word-break: break-all; }
-  button {
-    width: 100%; padding: 14px; margin-top: 16px;
-    background: #238636; color: #fff; border: none;
-    border-radius: 8px; font-size: 1.05em;
-    font-weight: 600; -webkit-appearance: none;
-    opacity: 0.4; pointer-events: none;
-  }
-  button.ready { opacity: 1; pointer-events: auto; }
-  button:active { background: #2ea043; }
-  .status { margin-top: 12px; padding: 10px; border-radius: 6px; text-align: center; display: none; }
-  .status.ok { display: block; background: #1a3a2a; color: #3fb950; }
-  .status.err { display: block; background: #3a1a1a; color: #f85149; }
-  .files { margin-top: 24px; }
-  .files h2 { font-size: 0.95em; color: #8b949e; margin-bottom: 8px; }
-  .files a { display: block; color: #58a6ff; text-decoration: none; padding: 6px 0; font-size: 0.9em; word-break: break-all; }
-  .files a:active { color: #79c0ff; }
-  .back { display: inline-block; margin-bottom: 12px; color: #8b949e; text-decoration: none; font-size: 0.9em; }
-  .back:active { color: #c9d1d9; }
-</style>
-</head><body>
-<div class="container">
-  <a class="back" href="/">&larr; Back to Codeman</a>
-  <h1>Upload Screenshot</h1>
-  <div class="drop-zone" id="drop">
-    <p>Tap to select image</p>
-    <small>PNG, JPG, WebP &mdash; up to 10 MB</small>
-  </div>
-  <input type="file" id="file" accept="image/*">
-  <div class="preview" id="preview">
-    <img id="previewImg" alt="Preview">
-    <div class="name" id="previewName"></div>
-  </div>
-  <button id="btn">Upload</button>
-  <div class="status" id="status"></div>
-  <div class="files" id="files"></div>
-</div>
-<script>
-(function() {
-  var drop = document.getElementById('drop');
-  var fileInput = document.getElementById('file');
-  var preview = document.getElementById('preview');
-  var previewImg = document.getElementById('previewImg');
-  var previewName = document.getElementById('previewName');
-  var btn = document.getElementById('btn');
-  var status = document.getElementById('status');
-  var filesDiv = document.getElementById('files');
-  var selectedFile = null;
-
-  drop.addEventListener('click', function() { fileInput.click(); });
-
-  fileInput.addEventListener('change', function() {
-    if (fileInput.files && fileInput.files[0]) pick(fileInput.files[0]);
-  });
-
-  // Drag-and-drop (desktop fallback)
-  drop.addEventListener('dragover', function(e) { e.preventDefault(); drop.classList.add('active'); });
-  drop.addEventListener('dragleave', function() { drop.classList.remove('active'); });
-  drop.addEventListener('drop', function(e) {
-    e.preventDefault(); drop.classList.remove('active');
-    if (e.dataTransfer && e.dataTransfer.files[0]) pick(e.dataTransfer.files[0]);
-  });
-
-  function pick(f) {
-    selectedFile = f;
-    previewImg.src = URL.createObjectURL(f);
-    previewName.textContent = f.name + ' (' + (f.size / 1024).toFixed(0) + ' KB)';
-    preview.style.display = 'block';
-    btn.classList.add('ready');
-    status.className = 'status';
-    status.style.display = 'none';
-  }
-
-  btn.addEventListener('click', function() {
-    if (!selectedFile) return;
-    btn.classList.remove('ready');
-    btn.textContent = 'Uploading\u2026';
-    var form = new FormData();
-    form.append('file', selectedFile);
-    fetch('/api/screenshots', { method: 'POST', body: form })
-      .then(function(r) { return r.json(); })
-      .then(function(j) {
-        if (j.success) {
-          status.className = 'status ok';
-          status.textContent = 'Saved: ' + j.filename;
-          status.style.display = 'block';
-          selectedFile = null;
-          preview.style.display = 'none';
-          btn.textContent = 'Upload';
-          loadFiles();
-        } else {
-          status.className = 'status err';
-          status.textContent = j.error || 'Upload failed';
-          status.style.display = 'block';
-          btn.classList.add('ready');
-          btn.textContent = 'Upload';
-        }
-      })
-      .catch(function(e) {
-        status.className = 'status err';
-        status.textContent = e.message;
-        status.style.display = 'block';
-        btn.classList.add('ready');
-        btn.textContent = 'Upload';
-      });
-  });
-
-  function loadFiles() {
-    fetch('/api/screenshots')
-      .then(function(r) { return r.json(); })
-      .then(function(j) {
-        if (j.files && j.files.length) {
-          var html = '<h2>Recent uploads</h2>';
-          j.files.forEach(function(f) {
-            html += '<a href="/api/screenshots/' + encodeURIComponent(f.name) + '" target="_blank">' + f.name + '</a>';
-          });
-          filesDiv.innerHTML = html;
-        }
-      })
-      .catch(function() {});
-  }
-
-  loadFiles();
-})();
-</script>
-</body></html>