chore: version packages (1.41.0)

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.35.0",
+      "version": "1.41.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; mobile tests call `createTestServer()` and read `server.boundPort`. `test/test-ports-guard.test.ts` fails a `WebServer` built on any other port and a raw `listen` on a fixed one. 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)

.gitignore

@@ -107,7 +107,9 @@ todo.md
 @fix_plan.md
 readme-preview.mjs
 
-# Uploaded images land here under each session working dir (runtime artifact)
+# Prompt uploads land here under each session working dir (runtime artifact);
+# .claude-images/ is where they landed before the move.
+.codeman-uploads/
 .claude-images/
 
 # Local-LLM harness smoke-test config (real IPs/keys) — see the .example.json

.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`); mobile tests use `createTestServer()` and read `server.boundPort`
 - 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,102 @@
 # aicodeman
 
+## 1.41.0
+
+### Minor Changes
+
+- 87f1c9c: ### Thanks
+  - @Randalix for `codeman agent` (#557), the session verbs (`ls`, `spawn`, `send`, `wait`, `read`, `interrupt`, `rm`) for agents in every CLI mode, and for moving every test server onto an ephemeral port (#570), which finishes #440. Thanks also for reporting and fixing git's clone errors on non-English hosts (#568, shipped as #572 with your commit).
+  - @opticon454 for five PRs: MCP server sync for GitHub Copilot CLI (#581), an Apply button that saves Settings without closing them (#565), configurable toast and browser-notification display times (#564), in-document links in rendered markdown that scroll to their heading (#563), and npm-based CLI installs that work when the system npm prefix is root-owned (#562).
+  - @JDProfresh for three PRs: pasted and uploaded files moving into a hidden, self-ignoring `.codeman-uploads/` folder (#574, after your #553 proposal), local echo that keeps painting on phones when the view sits above the bottom (#576), and upload failures that say why they failed (#578).
+  - @aakhter for session search on the vertical tab rail (#580), built on the sidebar's existing filter instead of a second one, and for keeping alerted tabs visible during a search.
+
+  ![Codeman tile grid: six live agents powering on and off with the CRT tile animation](https://raw.githubusercontent.com/Ark0N/Codeman/08694b5862534b2b1224e9e272ad9858c787ebef/release-1.41/tiles-crt-stats-800.gif)
+
+  **Tile Animations (#571).** The tile grid from 1.40.0 can now open with a show. App Settings has a new **Animations** section (right after Appearance) that holds every animation setting: the Entrance Theme (moved out of Appearance), the new **Tile Animations** row, and a button that opens the animation lab. Tile styles: **CRT** (each tile switches on as a hot line in a diagonal wave, and switches off to a line and a dot), **Fly from tab** (each tile grows out of its session tab and flies back into it), **Deal** (dealt out of the Tiles button like cards), **Beam down**, **Cascade**, **Pop**, **Soft** and **None**. A styled tile plays in two beats: the frame enters in the tile style, then its screen powers on in the terminal style of your Entrance Theme. Picking a theme presets a matching tile style, and a new **Launch** theme flies the tiles out of their tabs. Off by default (the grid keeps its quick fade), per device, nothing moves under reduced motion, and the animations never cost an extra PTY resize. The terminal pane's Boot entrance style is gone; a saved Boot falls back to off.
+
+  **Tiles open the sessions you care about, and keep your layout.** With no grid arranged yet, the Tiles button (or `Ctrl+Shift+G`) now fills the grid with the sessions that are working first (most recently started first), then the ones waiting on you (a permission prompt or a finished turn you have not seen), then the most recently used, instead of the tabs in strip order, which opened the oldest ones. The session you are on is still always included. Once you arrange a grid (which session sits where, empty cells, the tile count, divider sizes, the focused and zoomed tile), that layout is remembered in this browser and the Tiles button brings it back exactly, however the grid was closed, and so does a reload while it was open. A session that has gone since frees its place, which the same ranking fills. A grid larger than the window opens in full with the focused tile zoomed, instead of being trimmed (and losing the rest of your layout).
+
+  **The wheel scrolls Claude inside a tile (#577).** In a tile or the split's second pane, a Claude session on its fullscreen renderer now scrolls its own conversation with the mouse wheel, exactly like the main terminal: the wheel goes to Claude as mouse reports, aimed at that tile's session and computed from the tile's own screen. Before, the wheel did nothing or scrolled the stale frames left over from loading the tile. Shift+wheel (scroll local history) works in every tile on Windows and Linux too; it was dead there.
+
+  **`codeman agent`: session verbs for every CLI (#557).** Agents in any mode (Codex, OpenCode, Gemini, Pi and the rest, not just Claude) can now drive other Codeman sessions from the command line: `codeman agent ls | spawn | send | wait | read | interrupt | rm`. It is a thin client over the existing session API: every call names the session that made it, `wait` blocks on a signal (`--until stop,exit`) or a literal output marker (`--match`), and exit codes say what happened (`0` ok, `1` error, `2` timeout, `3` exited, `4` refused). Ids shorter than 8 characters are refused, so a stray `rm 9` can never pick a session at random, and `rm` never deletes the session it runs in. See the README section "`codeman agent`" and the wiki page Driving Codeman From An Agent. This is phase 1 of #445.
+
+  **Settings: Apply (#565).** Next to Save, an Apply button saves the same way but keeps Settings open. Switching on MCP server sync makes its Preview and Sync usable straight away, and CLI management's add, enable and disable work without closing and reopening Settings.
+
+  **MCP server sync reaches GitHub Copilot CLI (#581).** With MCP server sync on (App Settings, off by default), Copilot CLI's `~/.copilot/mcp-config.json` now takes part like the agent CLIs' own files: its servers are copied to the others and theirs to it, additively, with the previous file kept as `.codeman-bak`. Copilot joins only when it is installed or already has that file, a server switched off in Copilot is never copied, and `COPILOT_HOME` is followed. Copilot is a sync target only, not a new run mode.
+
+  **Notifications stay up longer if you want (#564).** Settings → Notifications has a Toast display time and a Browser notification display time (1 second to 5 minutes, per device; the defaults stay 3 s and 8 s).
+
+  **CLI logos on tabs can be switched off (#569).** App Settings → Appearance → Tabs → **CLI Logos on Tabs** hides the agent logo on every tab surface (header strip, rails, sidebar, phone chips, the desktop home list) on this device. On by default. Tile headers, split pane headers and the Run menus keep their logos.
+
+  **Search sessions on the vertical rail (#580).** The vertical tab rail has a **Search sessions** box at the top: type part of a name and the rail narrows to the tabs that match (a web tab by its title), across every group, collapsed ones included, without touching your groups, their collapse or the tab order. A tab with an alert stays visible even when its name does not match, so a prompt waiting on you is never filtered away. Escape or × clears it, you can still drag a found tab into a group, and nothing is saved. The sidebar's filter box shares the same filter: a tab with an alert stays visible there too, and in the by-case tab layout a case with no match now hides.
+
+  **Closing a tab is instant.** Closing a session used to take half a second or more before the tab went away. The tab, tile or split pane now goes (and the next session is selected) the moment you click, while the server shuts the session down in the background, and the server side is faster too (about 450 ms down to 200-260 ms for a Claude session): it no longer sleeps fixed intervals, no longer freezes for about 70 ms per close on a synchronous tmux call, and scans for a session's subagents once instead of once per subagent. If the server refuses the close, the tab comes back where it was with the error. This also fixes a bug where a failed close still said "Session closed" while the session kept running.
+
+  **Fixes.**
+  - **Clone errors on non-English hosts (#572, from #568).** Cloning a repository as a case now classifies a failed clone correctly whatever the host's language: a missing branch or tag is "does not exist on the remote" (400) and a missing repository is a 404, instead of a generic 422 with git's German (or any other) error text. Git runs with `LC_ALL=C` for clones and repo status, so the repo status card's error text is English on every host as well.
+  - **Links within a markdown file (#563).** A link to another heading of the same document (`[Install](#installation)`) in the File Viewer or Response Viewer scrolls to that heading instead of doing nothing. Headings get GitHub-style slugs, repeated titles are numbered, and non-ASCII headings work.
+  - **npm CLI installs on a root-owned prefix (#562).** Installing an npm-based CLI from Settings (DeepSeek's `dsh`, pi, ...) no longer fails with EACCES when the system node keeps its global prefix under `/usr`: the install goes to `~/.local`, where Codeman already looks for CLIs. A prefix you set yourself, or one you can write to, is left alone, including when Codeman runs under `npm run`.
+  - **Uploads go to a hidden `.codeman-uploads/` folder (#574).** Images you paste or upload into a prompt are saved in `<workspace>/.codeman-uploads/` instead of `.claude-images/`. The folder ignores itself in git (it carries a `.gitignore` of `*`), stays hidden in the Files panel, and is cleaned up as before: files older than 7 days in an hourly sweep, and the folder when the last session in that workspace closes. The old `.claude-images/` folder gets nothing new and is still swept and removed during 1.41.x. An upload to a remote (SSH) session is now refused with a clear message, since the file would land on the Codeman host where the remote agent cannot read it.
+  - **Typing on a phone after a tab switch (#576, fixes #575).** With local echo on (the default on touch devices), text typed while the terminal sat above the bottom was buffered but never painted, so the keyboard looked dead. The view sits there after every tab switch and after the keyboard closes. The overlay now paints whenever the prompt row is on screen, and hides only when you scroll the prompt out of view.
+  - **Upload failures say why (#578).** When a prompt image upload fails, the toast shows the server's reason (for example a rate limit) instead of only "1 failed".
+  - **The npm page shows the English README.** npmjs.com had been rendering the Chinese README, because npm picks the package's readme from an unsorted file match at publish time. The publish now moves `README.zh-CN.md` aside while it runs (the file and every link to it stay as they are), and the package description and homepage say what Codeman is and point at getcodeman.com.
+  - **New cases ask for clickable file paths.** The CLAUDE.md generated into a new case asks the agent to report every file it created as a full absolute path, which Codeman turns into a link that opens the File Viewer, and mentions the codeman skill for starting and managing worker sessions.
+
+  **For contributors (#570).** Every in-process test server binds an ephemeral port, the mobile suite included, and the port guard now also refuses raw listeners on a fixed port, so two test runs on one machine never collide.
+
+  **Fixes applied while landing.** zh-CN translations for the two new notification display-time settings and for the new Animations section. A session whose name matches an interface word ("Lab", "New session") is no longer translated in the tab strip when the interface is in Chinese. Plus test and doc cleanups left over from review.
+
+## 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

README.md

@@ -19,16 +19,12 @@
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
-<p align="center">
-  ⭐ <strong>Like Codeman? <a href="https://github.com/Ark0N/Codeman">Give it a star on GitHub!</a></strong> It takes one click and helps more people find the project. ⭐
-</p>
-
 <p align="center">
   <strong>English</strong> &bull; <a href="README.zh-CN.md">简体中文</a>
 </p>
 
 <p align="center">
-  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — parallel subagent visualization" width="900">
+  <img src="docs/images/tiles-crt-stats-20261010.gif" alt="Codeman tile grid: six live agents (DeepSeek Harness, Claude Code, Pi, Codex, OpenCode and a shell) powering on and off with the CRT animation, with the live header strip showing CPU, memory and Claude plan usage" width="800">
 </p>
 
 **Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, DeepSeek Harness, or OMP inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
@@ -54,7 +50,7 @@ The installer asks before every system change, and re-running the same line upda
 - **Self-hosted and private** - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine
 
 <p align="center">
-  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman dashboard tour: session tabs per case, one-click Run for new agents, live plan usage in the header" width="900">
+  <img src="docs/images/codeman-tour-20261010.png" alt="Codeman dashboard tour: session tabs per case, one-click Run for new agents, live plan usage in the header" width="900">
 </p>
 
 ---
@@ -385,6 +381,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.
@@ -418,7 +422,7 @@ The title is templated into the served HTML on first byte, so it's correct from
 ### Tab Alerts
 
 <p align="center">
-  <img src="docs/images/tab-alerts-glow-20260815.gif" alt="Session tabs: a regular active tab beside a yellow waiting-for-input tab and a red needs-decision tab, both with a breathing glow" width="900">
+  <a href="docs/images/codeman-tab-states-20261010.png"><img src="docs/images/codeman-tab-states-20261010.gif" alt="Tab states, annotated: a working tab with a spinning green ring, a red tab blocked on the agent's question shown below it, and a yellow tab whose turn is done, both alert tabs breathing" width="900"></a>
 </p>
 
 Every tab tells you its state at a glance. A running session keeps its green status dot. When a session stops and waits for input, its tab turns **yellow**: steady ring, tinted background, yellow dot, with a slow breathing glow on top. When a permission prompt or question is **blocking** the agent, the tab turns **red** with a faster pulse. The base tint never blinks off, so even a split-second glance (or a screenshot) reads the true state; the ring stays visible while the tab is selected, and a page reload re-arms pending alerts from the server, so a blocked session can never hide behind a fresh-looking tab.
@@ -731,6 +735,10 @@ For AI agents and automation that control Codeman without a browser: an agent th
 
 Everything in this section also ships as a **Claude Code skill** in [`skills/codeman`](skills/codeman/SKILL.md). Install it once and you never paste API docs into a prompt again. You ask for what you want in plain English, and the agent already sitting inside a Codeman session loads the recipes and drives the API itself.
 
+<p align="center">
+  <a href="docs/images/codeman-skill-20261010.png"><img src="docs/images/codeman-skill-20261010.gif" alt="A real codeman skill run: one plain-English request to a lead session, three Claude Code workers opening as new tabs, and lineage lines from the lead to every worker" width="900"></a>
+</p>
+
 #### Step 1: install it
 
 | How            | Command                                                    | Scope                                                                                      |
@@ -936,6 +944,24 @@ codeman tui --list                       #      numbered session list (plain tex
 codeman tui 3                            #      attach to session 3 of that list
 ```
 
+### `codeman agent` — session-to-session verbs in every CLI mode
+
+The skill above is claude-shaped (Codeman seeds its preamble for claude sessions only). An `opencode`, `codex`, `pi` or `gemini` agent has the same environment (`CODEMAN_MUX=1`, `CODEMAN_SESSION_ID`, `CODEMAN_API_URL` are exported into every pane) but nothing that teaches it the verbs — so `codeman agent` packages them as commands. It is a thin client over the endpoints listed under [API](#api): no new route, no new transport, auth and ownership unchanged. One line in a case's `AGENTS.md` is enough: *"other sessions: `codeman agent --help`"*.
+
+```bash
+codeman agent ls                                          # sessions; * marks this one
+SID=$(codeman agent spawn scratch-1 --mode claude)        # quick-start + wait for the composer where the mode has a ready mark
+codeman agent send "$SID" 'review src/, then say DONE' --until stop,exit --timeout 300000   # --wait = default signal set
+codeman agent read "$SID"                                 # last answer (as the server reads it for that mode)
+codeman agent read "$SID" --tail 3000                     # terminal tail, ANSI stripped (every mode)
+codeman agent send "$SID" 'run the tests, then print WORKDONE followed by _4711'   # hook-less modes (opencode, pi, …): ask for the marker in halves …
+codeman agent wait "$SID" --match WORKDONE_4711           # … and wait on the joined form, which the prompt's echo never contains
+codeman agent interrupt "$SID"                            # a bare ESC, conversation intact
+codeman agent rm "$SID"                                   # any session except this one
+```
+
+Rules the commands enforce rather than document: they refuse outside a Codeman session and never guess a URL; `send` transmits printable text plus Enter only (a control byte such as `Ctrl+C` is `app_exit` in opencode — ESC exists solely as `interrupt`, which never appends Enter); `rm` refuses an empty id, an unprovable self id and a prefix match in either direction. Ids may be the 8-character prefixes `ls` prints (resolved through the list; an ambiguous prefix refuses, anything shorter than 8 characters refuses on every verb). A prompt that starts with `-` goes after `--` (`send "$SID" -- "- fix the bug"`). The echo of the prompt you sent is output too: a `--match` marker that appears verbatim in the prompt matches at once, before the worker has done anything, so the prompt asks for it in halves. A remote session whose host is asleep answers a fire-and-forget `send` with `buffered` (Codeman wakes the host and types the prompt once the pane is back) or `dropped` (over the wake buffer's cap, nothing will be typed: exit `1`). Exit codes: `0` delivered/matched/signal, `1` error, `2` timeout, `3` the worker exited or the wait ended without an answer (`delivered:false`, `ended:true`), `4` refused. `spawn` prints the id alone on stdout (prose goes to stderr), so `SID=$(…)` captures exactly the id. `--json` prints the envelope's `data` for every verb. `--until stop` on a mode without hook signals is the server's 400, passed through — the marker path (`--match`) is the answer there, exactly as for the skill.
+
 ### Hooks (events flowing _back_ to Codeman)
 
 Codeman registers Claude Code hooks that `POST /api/hook-event` (`permission_prompt`, `idle_prompt`, `stop`, `task_completed`, …) so the dashboard reacts in real time. This endpoint is auth-exempt on loopback but, under a managed tunnel, requires the `X-Codeman-Hook-Secret` header (read it from `$CODEMAN_HOOK_SECRET_FILE`). You normally don't call this by hand — Codeman wires it up — but it's how the autonomy layers "see" what the agent is doing.

README.zh-CN.md

@@ -24,11 +24,7 @@
 </p>
 
 <p align="center">
-  ⭐ <strong>喜欢 Codeman？<a href="https://github.com/Ark0N/Codeman">在 GitHub 上给它点个 Star 吧！</a></strong>只需轻点一下，就能帮助更多人发现这个项目。⭐
-</p>
-
-<p align="center">
-  <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — 并行子智能体可视化" width="900">
+  <img src="docs/images/tiles-crt-stats-20261010.gif" alt="Codeman 平铺视图：六个实时智能体（DeepSeek Harness、Claude Code、Pi、Codex、OpenCode 和一个 shell）以 CRT 动画开启与关闭，顶部实时显示 CPU、内存和 Claude 套餐用量" width="800">
 </p>
 
 > 本文档由英文版 [`README.md`](README.md) 翻译而来。如有出入，以英文版为准。
@@ -386,6 +382,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

@@ -22,6 +22,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/tab-rail-search.browser.test.ts',
   'test/session-sidebar-ux.browser.test.ts',
   'test/session-options-responsive.browser.test.ts',
   'test/inline-rename.test.ts',
@@ -33,6 +34,7 @@ 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',
@@ -41,7 +43,10 @@ export const BROWSER_TEST_GLOBS = [
   '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',
+  'test/markdown-anchor-links.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
@@ -459,6 +466,27 @@ geometry was read. The capture runs synchronous tmux calls on the server; the
 | `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. |
 
+## The `codeman agent` CLI (client over these endpoints)
+
+`codeman agent ls|spawn|send|wait|read|interrupt|rm` (`src/cli-agent.ts`) is the command-line client for the endpoints above, for agents in modes that never receive the claude-only skill preamble. It adds no route: `spawn` is `POST /api/v1/quick-start` (+ `wait-output` on the mode's `capabilities.composerReadyMark` from the CLI registry, where it declares one), `send` is `POST …/input` with `clientId`+`seq` (and `wait`/`waitTimeout` for `--wait` / `--until <signals>`; `delivered:false` without `duplicate` and `wait.ended` both exit 3 — the CLI never reports a dead worker as done), `wait` is `GET …/wait` (`--until`) or `GET …/wait-output` (`--match`, `from=buffer` by default), `read` is `GET …/last-response` or `GET …/terminal?tail=`, `interrupt` is `POST …/input` with a bare `\u001b`, `rm` is `DELETE …/sessions/:id`. A fire-and-forget `send` to a sleeping wake-on-LAN host reads the route's `buffered` (own line, exit 0) and `dropped` (exit 1: the chunk is gone). An id may be the 8-character form `ls` prints, resolved through `GET /api/v1/sessions`; anything shorter refuses before any request, the same floor as `PARENT_SESSION_ID_MIN_PREFIX`. Every call carries `X-Codeman-Parent-Session`; only `spawn`'s quick-start carries `X-Codeman-Agent-Origin: codeman-agent-cli` (the agent-scratch label must never reach a request that cannot create the case directory). Basic auth comes from `CODEMAN_PASSWORD` or the data dir's `.env`. Server-side error codes are shown verbatim (`INVALID_INPUT: until=stop …` on a hook-less mode is not hidden); exit codes are `0` ok, `1` error, `2` timeout, `3` the session exited, `4` refused by a client-side guard. See the README section "`codeman agent`" for the guards and `test/cli-agent.test.ts` for the pinned behaviour.
+
+## Prompt uploads (`POST /api/v1/sessions/:id/paste-image`)
+
+A `multipart/form-data` body with one `image` part. The file is written into the
+session's workspace as `<workingDir>/.codeman-uploads/paste-<ms>-<hex>.<ext>`, and
+`data` carries `path` and `filename` for the client to type the path into the
+prompt. The folder is Codeman's own: hidden, created on first use with a
+`.gitignore` containing `*` (written once, never over a file already there), and
+cleaned up the way pasted images always were: `paste-*` files older than 7 days
+go in an hourly sweep, and the folder goes when the last session of that
+workspace is killed. Uploads made before this release sit in `.claude-images/`;
+that folder receives nothing new, and is swept and removed the same way for one
+release. A remote (SSH) session answers 400, since the file would land on the
+Codeman host under a path the remote agent cannot read. A Docker session of an
+owned case is fine, its workspace is bind-mounted at the same absolute path; an
+adopted container (`owned: false`) mounts nothing, so its agent can open the file
+only if the container itself exposes that host path.
+
 ## Session lineage (`parentSessionId`)
 
 A create request may name the session that spawned it, which the web UI draws as a
@@ -764,11 +792,13 @@ Admin only in multi-user mode (`403`), like `POST /api/cases/link`: it writes ou
 **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 12 (`reposTruncated` says when there were more). 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.
+- **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.
 
-`data` is `{ state, repos, reposTruncated, checkedAt }`:
+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`.
@@ -803,10 +833,10 @@ Copies MCP servers between the agent CLIs' own user-level config files (`docs/cl
 Result (`data`):
 
 - `applied` — `false` for the dry run.
-- `targets[]` — one per enabled CLI that declares an MCP config: `id`, `label`, `file`, `status`, `error?`, `servers` (names it already has), `added` (names added, or that would be), `skipped` (names its dialect cannot express, e.g. SSE for Codex and Antigravity).
+- `targets[]` — one per enabled CLI that declares an MCP config, plus GitHub Copilot CLI (`id: "copilot"`, a sync-only target that is not a run mode): `id`, `label`, `file`, `status`, `error?`, `servers` (names it already has), `added` (names added, or that would be), `skipped` (names its dialect cannot express, e.g. SSE for Codex and Antigravity).
   - `status`: `ok`; `absent` (not installed and no config file, so not read or created); `skipped` (the CLI's relocation env var, e.g. `CODEX_HOME`, is set to a relative path in the server's environment, so its file cannot be located safely and is neither read nor written); `unreadable` (the file exists but cannot be parsed safely, so it is not written); `failed` (a read or write error, the file may be unchanged).
   - `error` says why a target is not `ok`. A parse failure is reported by position only (`not valid TOML (line 3, column 21)`, `not valid JSON`), never with text from the file.
-  - `file` honours each CLI's own relocation env var as the server process sees it (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME`, `GEMINI_CLI_HOME`); see `docs/cli-registry.md`.
+  - `file` honours each CLI's own relocation env var as the server process sees it (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME`, `GEMINI_CLI_HOME`, and `COPILOT_HOME` for the sync-only Copilot CLI); see `docs/cli-registry.md`.
 - `conflicts[]` — names defined differently by different CLIs. Existing definitions are kept; the first CLI's is copied where the name is missing.
 - `disabled[]` — names left out because every definition is switched off in its own CLI (codex `enabled = false`, opencode `enabled: false`, antigravity `disabled: true`).
 - `unsupported[]` — labels of enabled agent CLIs with no known MCP config file (nothing is guessed).

docs/browser-testing-guide.md

@@ -71,17 +71,23 @@ 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 raw `http`, `net`, Fastify or `ws` server: `listen({ port: 0 })`, then
+  `address().port`. The guard also fails a raw listen on a number or a `…PORT` constant.
+- The mobile suite (`test/mobile/**`) gets its server from `createTestServer()`, which
+  binds an ephemeral port too; read it from `server.boundPort`.
+- The one exception is `test/codex-predictive-echo.test.ts`, which starts a separate lab
+  server process on port 3222 that the guard cannot see.
+- 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 +112,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 +146,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 +192,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 +252,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

@@ -25,7 +25,7 @@ Every run mode Codeman can launch — Claude Code, Terminal/Shell, OpenCode, Cod
 App Settings → Agents & CLIs → **CLI management** (`cliManagementEnabled`, default OFF; admin-only in multi-user mode) lists every entry with an installed/not-installed badge and:
 
 - toggles any entry on or off. A `kind: 'shell'` entry cannot be disabled, and the row shows no switch for it. A disabled CLI disappears from the Run menu, the welcome screen and the phone overview, and new session requests for it are rejected.
-- installs a missing **stock** CLI by running its shipped install command, after a confirm that names the exact command. Only one install per CLI runs at a time, and the command runs without any `CODEMAN_*` variable in its environment. A custom entry's install command is never executed.
+- installs a missing **stock** CLI by running its shipped install command, after a confirm that names the exact command. Only one install per CLI runs at a time, and the command runs without any `CODEMAN_*` variable in its environment. An `npm install -g` command is pointed at `~/.local` (which every resolver searches) when the npm global prefix is not writable by the server user, for example a system node under `/usr`; a writable prefix, a prefix that does not exist yet but could be created, and an explicit `NPM_CONFIG_PREFIX` are left alone. A custom entry's install command is never executed.
 - adds, edits and deletes **custom** entries (id, label, badge, binaries, launch argv). The server re-validates the whole assembled entry through `CliEntrySchema`, so the form cannot bypass the load-time rules.
 
 These are the only writes to `clis.json`. They are serialized, and a file that does not parse or has unsafe permissions is refused rather than overwritten; fix it (or `chmod 600` it) and retry. The HTTP routes are listed in `docs/api-reference.md` under *CLI management*.
@@ -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
@@ -51,6 +51,9 @@ interface CliEntry {
   //   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
 }
 ```
@@ -63,7 +66,7 @@ Five capability fields carry a regular expression an override file can set: `dis
 
 `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 4, 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), and codex's `  <model> <effort> · ` footer on its last row. 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.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.
 
@@ -81,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
@@ -261,9 +265,11 @@ A module-level const freezes at first import, and the failure is asymmetric: a C
 
 ## MCP server sync
 
-`capabilities.mcpConfig` (`{ path, format, relocation? }`, `path` relative to the home directory) names the file a CLI keeps its user-level MCP server list in and the dialect it is written in. `src/mcp-sync.ts` reads that list from every ENABLED CLI that declares one, and that is installed or already has the file (a CLI that is neither is reported `absent`, never created), and adds any server a CLI is missing from the others. It writes other tools' own config, so it is **opt-in**: `mcpSyncEnabled` (synced, default OFF) gates `GET`/`POST /api/mcp-sync` (403 while off) and the Settings → Agents & CLIs → MCP servers controls. Declared today for claude, gemini, codex, opencode and antigravity; every format was checked against what the CLI's own `mcp add` writes, except opencode's (documented, not installed to check). A CLI with no entry (pi, grok, omp, deepseek) is not guessed at: it is listed as `unsupported` in the result when enabled. Adding one is a registry entry plus a small adapter in `mcp-sync.ts`, and a verified fixture in `test/mcp-sync.test.ts`.
+`capabilities.mcpConfig` (`{ path, format, relocation? }`, `path` relative to the home directory) names the file a CLI keeps its user-level MCP server list in and the dialect it is written in. `src/mcp-sync.ts` reads that list from every ENABLED CLI that declares one, and that is installed or already has the file (a CLI that is neither is reported `absent`, never created), and adds any server a CLI is missing from the others. It writes other tools' own config, so it is **opt-in**: `mcpSyncEnabled` (synced, default OFF) gates `GET`/`POST /api/mcp-sync` (403 while off) and the Settings → Agents & CLIs → MCP servers controls. Declared today for claude, gemini, codex, opencode and antigravity (plus GitHub Copilot CLI as a sync-only target, below); every format was checked against what the CLI's own `mcp add` writes, except opencode's (documented, not installed to check). A CLI with no entry (pi, grok, omp, deepseek) is not guessed at: it is listed as `unsupported` in the result when enabled. Adding one is a registry entry plus a small adapter in `mcp-sync.ts`, and a verified fixture in `test/mcp-sync.test.ts`.
 
-`relocation` (`{ envVar, path }`) names the env var the CLI itself reads to move that file: claude `CLAUDE_CONFIG_DIR` (`.claude.json` under it), codex `CODEX_HOME` (`config.toml`), opencode `XDG_CONFIG_HOME` (`opencode/opencode.json`) and gemini `GEMINI_CLI_HOME` (`.gemini/settings.json`); antigravity follows `$HOME` only, so it declares none. The var is read from the SERVER process env at call time, which is the env the CLIs Codeman spawns inherit. An absolute value moves the file to `<value>/<relocation.path>`, an empty one counts as unset (as it does for each CLI), and anything else reports the target `skipped` with the reason instead of writing a file the CLI never reads. A per-session relocation (a session's own `CLAUDE_CONFIG_DIR` in `envOverrides`) is not followed: the sync only knows the server's environment.
+**Tools that are not run modes.** GitHub Copilot CLI keeps an MCP list worth syncing but Codeman does not launch it, so it has no registry entry. `src/mcp-sync-targets.ts` declares such tools as plain data (`MCP_SYNC_ONLY_TOOLS`: id, label, config path, dialect, relocation var, the binary whose presence means "installed"). They join the registry CLIs as sync targets (listed after them, so a registry CLI's definition wins a same-name difference), under the same rules: installed or already configured, otherwise `absent`. Copilot's dialect is `copilot-json` (`~/.copilot/mcp-config.json`, relocated by `COPILOT_HOME`; checked against `copilot mcp add` 1.0.94): `mcpServers`, each entry with `tools` (`["*"]` = all), `type` `local` | `http` | `sse`, `command`/`args`/`env` or `url`/`headers`. `copilot mcp disable` does not mark the entry: it lists the name under `disabledMcpServers` in `settings.json` beside the config. Sync reads that list (never writes it) so a disabled server is not copied, and reports the target `unreadable` if `settings.json` is not valid JSON rather than guessing.
+
+`relocation` (`{ envVar, path }`) names the env var the CLI itself reads to move that file: claude `CLAUDE_CONFIG_DIR` (`.claude.json` under it), codex `CODEX_HOME` (`config.toml`), opencode `XDG_CONFIG_HOME` (`opencode/opencode.json`), gemini `GEMINI_CLI_HOME` (`.gemini/settings.json`) and, for the sync-only Copilot CLI, `COPILOT_HOME` (`mcp-config.json`); antigravity follows `$HOME` only, so it declares none. The var is read from the SERVER process env at call time, which is the env the CLIs Codeman spawns inherit. An absolute value moves the file to `<value>/<relocation.path>`, an empty one counts as unset (as it does for each CLI), and anything else reports the target `skipped` with the reason instead of writing a file the CLI never reads. A per-session relocation (a session's own `CLAUDE_CONFIG_DIR` in `envOverrides`) is not followed: the sync only knows the server's environment.
 
 The rules the module keeps and the tests pin: it only ADDS (a name already defined, in any shape, is never edited or removed; a same-name difference is reported as a conflict); a server switched off in its own CLI is not copied; it never writes a file it could not parse (opencode JSONC with comments, a TOML file with a duplicate table) and re-parses the new text before writing; codex TOML is read with a real parser (`smol-toml`), so CRLF files and inline tables are handled; names such as `__proto__` are ignored and every table keyed by an untrusted name has no prototype; a symlinked config is written through, not replaced; a file that receives `env`/`headers` is left `0600`; only one apply runs at a time; and its result carries server names only, never env values or headers, and never file text: a parse failure is reported by line and column, not by the parser's message (smol-toml prints a code frame of the offending lines and V8's JSON errors quote source, either of which can hold a secret). The schema restricts `path` and `relocation.path` to a relative path without `..`, since sync writes to it.
 

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

@@ -92,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/tile-grid-plan.md

@@ -1,8 +1,8 @@
 # Tile Grid: Design Spec
 
-**Status**: PR 1 (tile foundation) implemented on `feat/terminal-tile`; PR 2 (the grid) implemented on `feat/tile-grid`, both local only. Builds on `docs/split-pane-sessions-plan.md`; the split pane stays.
+**Status**: Merged for the 1.40.0 release as #560 (the TerminalTile foundation) and #561 (the grid). Where the "As built" section below differs from this spec, As built is authoritative. Builds on `docs/split-pane-sessions-plan.md`; the split pane stays.
 **Author**: Claude (planning session with the maintainer), 2026-10-06
-**Branches**: PR 1 `feat/terminal-tile`, PR 2 `feat/tile-grid` stacked on it (worktrees `claudeman-tiles`, `claudeman-tilegrid`)
+**Branches**: developed as PR 1 `feat/terminal-tile` and PR 2 `feat/tile-grid` stacked on it, both merged
 **Scope**: v1 is fully designed here; follow-ups are named at the end and explicitly deferred.
 
 ## As built: where PR 2 differs from this spec
@@ -20,14 +20,22 @@ or settled a question the spec left open. The invariants as built are in
 - **`Ctrl+Shift+G` follows `showTileGridButton`** (decided by the owner, decision 6): with
   the setting off the toggle chord is inert. A grid opened another
   way (Ctrl/Cmd+click, a dropped tab, "Open group as tiles") keeps all its chords.
+- **The Tiles button ships ON** (owner, 1.36.0 beta): `showTileGridButton` defaults to on
+  everywhere but handhelds (their defaults object keeps it off) and, since the 1.40.0 final
+  checkup, devices whose primary pointer is coarse (touch tablets, opt-in there), so the
+  chord is live by default too. An absent key resolves through the device defaults in both the button
+  (settings-ui.js) and the chord (`tileShortcutFor`), so they cannot disagree.
 - **Dividers are grid tracks.** Each gap between columns and rows is its own 6px track (the
   grid gap is 0) and every tile and every empty slot is placed explicitly in its cell
   (`grid.cells`, see "Tiles move"). Fractions reset when the column or row count changes.
 - **Zoom follows tmux.** Moving focus to another tile restores the grid; an automatic zoom
   (window too small for the minimum tile) follows focus instead.
 - **Tile loads are bounded** (`boundedLoad`), carry a fetch deadline covering the body (Pane
-  B too), and a refresh clears the screen at its turn in the queue, so a waiting tile keeps
-  its last frame.
+  B too), and a refresh fetches at its turn in the queue: the tile keeps its last frame
+  through its wait and its own round trip, and is reset with the queued in-stream `\x1bc`
+  only once the capture is in hand, right before the replay (never xterm's `clear()` before
+  the fetch). A failed, aborted or empty fetch writes nothing and resets nothing: the tile
+  keeps its last frame and every held live frame.
 - **4009 lands on the Attach overlay**, and 4003/4004/4010 remove the tile.
 - **Tile header buttons are 26px targets with 16 to 19px glyphs** (owner feedback: the
   first build's 12px glyphs read as tiny next to the name), the size of the app header's own
@@ -37,20 +45,28 @@ or settled a question the spec left open. The invariants as built are in
   `Right-click`) and `Arrows` translated. Every string has its own entry or pattern; refreshes
   compare with the last English value, not the translated DOM.
 - **The Tiles button opens the grid at once** (owner decision 8, with the count of
-  decision 10): a click (and `Ctrl+Shift+G`, the same `toggleTileGrid`) opens the remembered
-  count of tiles (default 6, at most what the window fits). `tileGridOpenSet`
-  (constants.js) picks the grid this tab last had, else an open split's two sessions, else
-  the open sessions in tab order, the active one always included and focused, and
-  `tileGridSetForCount` trims it (from the end, the session to focus kept) or fills it
-  (from tab order) to the count. A remembered grid comes back with its tiles first, in
-  their cells, then sessions in tab order, to the count in total: the count is a shape
-  change under the cell model's rule (`reformTileCells`: the tiles keep their row and
-  column when all fit, else they pack in reading order) and the added tiles fill the empty
-  cells first. This supersedes decision 8's "exactly the stored set" (owner answer). A
-  remembered grid still wins over an open split: the split closes and its sessions are not
-  seeded first. A page-load restore brings back exactly the stored grid, whatever the
-  count. Ctrl/Cmd+click on a tab with the grid closed opens the count in total, that
-  session among them and focused (owner answer: N, not N+1).
+  decision 10 and the layout memory of decision 11): a click (and `Ctrl+Shift+G`, the same
+  `toggleTileGrid`) brings back the grid this browser last had EXACTLY as the user left
+  it: which session sits in which cell, holes included, its tile count, divider sizes,
+  focus and a zoom the user chose (`restoreTileGridCells`, constants.js). It is never
+  filled to the remembered count and never trimmed to the window (a window too small
+  for it shows the focused tile alone until it fits, the arrangement kept). A session
+  that no longer exists frees its cell, which the ranking fills. Only with nothing
+  stored, or none of its sessions left, does `tileGridOpenSet` (constants.js) take an
+  open split's two sessions, else the open sessions as `rankTileSessions` orders them
+  (owner request: "prefer to load in tiles that are working and then the most recent,
+  so the oldest don't get opened"): WORKING first (the most recently started turn
+  first, keyed off `lastSubmitAt` only), then the ones NEEDING INPUT (the red and yellow
+  tab alerts), then the rest by most recent activity, tab order breaking ties; the
+  active one always included and focused, and `tileGridSetForCount` trims it (from the
+  end, the session to focus kept) or fills it (from the ranking) to the remembered count
+  (default 6, at most what the window fits). The states and stamps are the home
+  screens' own (`_mobileOverviewState`, `sessionActivityAnchor`). A remembered grid still
+  wins over an open split: the split closes and its sessions are not seeded first. A
+  page-load restore brings back the same grid as the toggle. Ctrl/Cmd+click on a tab
+  with the grid closed opens what the toggle would with that session among the tiles and
+  focused, never past the count (owner answer: N, not N+1): it joins the first empty cell
+  while the grid holds fewer than the count, else it takes the last tile's place.
 - **A hover card on the Tiles button says it** (owner feedback: "give me the hover info
   to right click over the tile button to adjust it"). It replaces the button's native title:
   "Tiles · N" (the remembered count, live), what a click does (open or close the grid),
@@ -72,9 +88,10 @@ or settled a question the spec left open. The invariants as built are in
   back on the Tiles button, Tab, a click elsewhere and the keyboard leaving it for another
   element close it (the single view a close starts focuses its terminal when its replay
   lands; a menu left open behind that would send its keys there). A pick is remembered per
-  device in `codeman:tile-count` (`codeman:tile-grid` stays ids only) and opens that many
-  tiles; with the grid open it re-forms it (`_reformTileGrid`): the focused tile always
-  stays, the others leave from the end or join from tab order, filling empty cells first,
+  device in `codeman:tile-count` and opens that many tiles (a stored grid re-formed to
+  it, its tiles first in their cells); with the grid open it re-forms it
+  (`_reformTileGrid`): the focused tile always stays, the others leave from the end or
+  join from the ranking, filling empty cells first,
   every joining tile mounted and laid out before any connects (one fit, one PTY resize
   each), and a zoom the user chose ends. The other ways in (Ctrl/Cmd+click, a dragged tab,
   "Open group as tiles", Run) still add up to the cap of 6.
@@ -89,7 +106,10 @@ or settled a question the spec left open. The invariants as built are in
   `test/header-icon-hover.test.ts`.
 - **The grid opens and closes with a short animation, on by default** (owner request:
   "when clicking on the tile button first make this animation nicer"). It is the grid's
-  own, not an `entrance-animations.js` theme (those are off by default). Opening, each tile
+  own `settle` style, the default of App Settings → Animations → Tile Animations, which
+  switches on other styles (`fly` out of the tabs, `deal` from the Tiles button, `crt`,
+  `beam`, ...; docs/architecture-invariants.md#entrance-animations).
+  Opening, each tile
   fades and settles in (opacity, translateY 6px and scale .97), 180 ms, 24 ms apart in
   reading order (`--tile-enter-index`): the last of six is done at 300 ms; a tile added
   later enters the same way. Its terminal stays transparent (`.tile--revealing`) until the
@@ -211,8 +231,10 @@ no `+`, owner decision 9).
 
 ## Non-goals (v1)
 
-- Phones and tablets. The grid is desktop-only, gated at 1180 px like the
-  split (`SPLIT_PANE_MIN_WIDTH`) and the home rail (`HOME_SESSIONS_MIN_WIDTH`).
+- Phones. The grid is gated on width alone at 1180 px like the split
+  (`SPLIT_PANE_MIN_WIDTH`) and the home rail (`HOME_SESSIONS_MIN_WIDTH`); a
+  wide tablet, or a large foldable unfolded in landscape, can reach it (see the
+  keyboard exception below).
 - More than 9 tiles.
 - WebGL rendering inside tiles (see "Rendering" below).
 - Full parity with the main terminal's touch and IME features: local-echo
@@ -220,7 +242,11 @@ no `+`, owner decision 9).
   mouse-wheel forwarding to Claude's fullscreen renderer, the "Load full
   history" banner. These exist for touch devices or rare cases; a desktop
   keyboard user types straight into xterm, which is how Codeman behaved before
-  those features existed.
+  those features existed. (One exception, since the 1180 px gate is width
+  only and a wide Android tablet clears it: every tile wires the main
+  terminal's keyCode-229 soft-keyboard controller, terminal-keycode229-recovery.js,
+  so an Android autocorrect is sent as an edit rather than a duplicated line,
+  #541, and a character committed with Enter is not lost, #441.)
 - Server-side persistence of grids (named presets per owner).
 - Pop-out windows (`/session/:id`, solo mode) showing a grid.
 
@@ -375,16 +401,34 @@ the harness/model request; see "As built")
 
 ### Persistence
 
-Decided: per device, restored on reload. Stored in localStorage key
-`codeman:tile-grid`:
+Decided: per device (per browser), restored on reload when it was open, and by
+the Tiles toggle however it was closed (decision 11). Stored in localStorage key `codeman:tile-grid`, never on the
+server:
 
 ```json
-{ "v": 1, "open": true, "ids": ["…", "…"], "focused": "…", "zoomed": null,
-  "colFr": [1, 1, 1], "rowFr": [1, 1] }
+{ "v": 1, "open": true, "ids": ["…", null, "…"], "count": 3, "focused": "…",
+  "zoomed": null, "colFr": [1, 1, 1], "rowFr": [1, 1] }
 ```
 
-Ids only, never content. A pure sanitizer drops unknown, deleted, detached and
-duplicate ids on load. Never restored in a solo window.
+Session ids and the layout, never content. `ids` are the CELLS in reading order,
+`null` for an empty one. `count` is how many tiles the user's own last change
+left (open, add, remove by hand, a count picked): a session that goes away by
+itself (deleted, popped out, its socket refused) does not lower it, so the next
+time the grid opens the ranking fills that place, while a hole the user made
+stays. It is written on every change (a move, a divider drag at pointer-up, a
+tile added or removed, a count picked, a focus, a zoom) and kept, as
+`open: false`, however the grid closes: the toggle, a non-tiled tab,
+`leaveTiles` or a `#session=` link (which flips `open` only, so a gone id still
+frees its cell), Home, the width gate, the last tile, "Open group as tiles",
+closing or killing sessions. Nothing is written while a stored grid is being
+put back, so a half-built grid never overwrites it.
+
+A pure sanitizer drops unknown, deleted, detached and duplicate ids on load,
+reports the cells their sessions freed (`freed`), and derives `count` for a
+value written before it existed (the number of sessions the cells name); the
+old packed `ids` (no nulls) read as cells with no hole, and anything that is not
+a v1 object is ignored. The format stays `v: 1`, so an older build still reads
+a newer value (it ignores `count`). Never read or written in a solo window.
 
 The restore runs INSIDE `handleInit`, in place of its initial
 `selectSession(restoreId, { auto: true })` (the non-`keepTerminal` branch), not
@@ -395,10 +439,22 @@ the main terminal never loads on that page load. A later `handleInit` (SSE
 reconnect after a server restart, the `keepTerminal` branch) reconciles ids
 against the live list without rebuilding tiles that are still alive.
 
+A cell freed since the grid was stored is filled during that restore, from a
+ranking that knows each session's status and stamps (the init payload) but not
+yet its pending approvals: `seedApprovals` asks the server for them
+asynchronously, and the restore has run by the time they land. So on a reload a
+session waiting on a permission dialog or an unseen finished turn ranks with the
+quiet ones for that one fill (working sessions still rank first). Accepted: a
+fill held back for the approvals would open fewer tiles, which can be another
+shape, and then reshape the grid and move the user's tiles a second after the
+reload; so approvals that land later never re-form a restored grid. The Tiles
+toggle, run once the page has loaded, ranks with them.
+
 ### Gating
 
 - Setting `showTileGridButton`, per device (in `displayKeys`, stripped from the
-  settings PUT, NOT in `SettingsUpdateSchema`), default OFF. Independent of
+  settings PUT, NOT in `SettingsUpdateSchema`), default ON on desktop and OFF on
+  handhelds (specified OFF; superseded, see "As built"). Independent of
   `showSplitButton`, which is unchanged; a desk can show both buttons.
 - Hidden below 1180 px by both a JS width check with a `matchMedia` listener and
   a CSS `@media (max-width: 1179px)` backstop, exactly like the split button.
@@ -800,7 +856,8 @@ Separate follow-up PRs worth doing (see "Follow-ups").
   open, and an open menu owns the Escape (it closes alone and the keyboard goes
   back to the Tiles button, like the tab-group menu).
 - **User text** (names) via `textContent` / attributes, never `innerHTML`.
-- **No secrets in localStorage**: the stored grid holds ids only.
+- **No secrets in localStorage**: the stored grid holds session ids and its
+  layout only, never content.
 - **Memory**: everything a tile creates is released in `destroy()`.
 
 ## Delivery: two PRs
@@ -993,8 +1050,17 @@ exits green. Use the browser runner for those files and read the file count.
    viewer keeps a stale width and renders garbled output (#464).
 3. WebSocket backpressure (`bufferedAmount` threshold, drop and send `{t:'r'}`
    on drain) for grids over slow links.
-4. Tile parity extras: mouse-wheel forwarding for Claude's fullscreen renderer,
-   a "Load full history" action inside a tile.
+4. Tile parity extras: a "Load full history" action inside a tile. (Done
+   since: a tile pages a hollow buffer's CLI transcript with PageUp/PageDown,
+   the primary pane's #555 route, hand-reports a plain click while its session
+   has `cliMouseTracking` on, and forwards the wheel to Claude's fullscreen
+   renderer as SGR wheel reports from its own cells
+   (`TerminalTile._maybeForwardWheelToCli`, encoding shared with the primary
+   pane via `CodemanTerminalInput.sgrWheelReports`), all through the primary
+   pane's gates aimed at the tile. Before that, a fullscreen Claude tile left
+   the wheel to xterm, which scrolled only stale replayed frames. Shift+wheel
+   scrolls the tile's local scrollback itself (`_maybeScrollLocalOnShift`),
+   since xterm turns it into a horizontal no-op off macOS.)
 5. WebGL in tiles, after measuring the DOM renderer with nine busy tiles.
 6. Named grid presets, possibly per owner on the server.
 7. The end state: the main terminal becomes a 1x1 grid of `TerminalTile`,
@@ -1033,7 +1099,8 @@ exits green. Use the browser runner for those files and read the file count.
    is on right-click of the button (its title says so, as do the wiki and the
    Help modal). Superseded in part by decision 10: right-click is now the count
    menu, and a remembered grid is filled to the count instead of opening
-   exactly as stored.
+   exactly as stored; decision 11 then restored "exactly as stored" and put a
+   ranking in place of the tab order.
 9. **No + in the tile header.** Decided by the owner ("remove the + button from
    these views"): the header is `● name ……… ⋯ ⤢ ×`. The + menu and its "New
    session in this case" went with it. Tiles are added from the Tiles button
@@ -1046,12 +1113,32 @@ exits green. Use the browser runner for those files and read the file count.
    right-click menu offers 2, 4 and 6, remembered per device; the session
    picker is gone, and decision 8's "picker on right-click" is superseded. The
    owner's answers on the details: the count wins over a remembered grid's
-   size (its tiles first, in their cells, holes filled first, then tab order);
+   size (its tiles first, in their cells, holes filled first, then tab order;
+   superseded by decision 11: a click brings the remembered grid back as it
+   was, and only a count picked in the menu re-forms it);
    Ctrl/Cmd+click with the grid closed opens the count in total, that session
    focused; shrinking keeps the focused tile; only the toggle animates the
    close; a remembered count larger than the window stays checked but greyed
    and a click opens what fits; the close keeps its dimmed still until the
    single view has painted (at most 700 ms); paced connect is in.
+11. **The grid keeps the layout the user arranged, and a fresh one ranks by
+   work.** Decided by the owner ("when I hit the tiles button, it should prefer
+   to load in tiles that are working and then the most recent working, so the
+   oldest dont get opened ... when I moved around and modified it, save it per
+   browser the layout, so when I turn tiles off and on, always keep what the
+   last setting was, if there was no setting before take the working ones, that
+   ones needs input and then the most recent ones in order"). The layout
+   (cells and holes, tile count, divider sizes, focus, a zoom the user chose)
+   is saved per browser on every change and comes back exactly from the toggle,
+   however the grid closed, and from a reload when the grid was open (a grid
+   closed before the reload stays remembered for the toggle; the page shows the
+   single view); it is never filled to the remembered count nor trimmed to the
+   window. A session gone since frees its cell for the
+   ranking; with none left, the grid opens from the ranking (`rankTileSessions`:
+   working, then needing input, then most recent), which also fills every place
+   the grid fills on its own (a count picked in the menu, a freed cell, an open
+   split's fill). Supersedes decision 10's "the count wins over a remembered
+   grid's size"; the count menu itself, its counts and its other answers stay.
 
 ## Code anchors
 

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,18 @@ 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. Mobile tests call `createTestServer()` and
+read `server.boundPort`. Never 3000.
 
 ## Finding your way around
 

docs/wiki/Core-Concepts.md

@@ -15,7 +15,8 @@ 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                                                                                                 |
 | ----------------- | ------------------------------------------------------------------------------------------------------ |

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

@@ -4,7 +4,8 @@ Everything the dashboard does is HTTP, so an agent can do it too. This page is f
 that makes Codeman interesting: **Claude Code running inside a Codeman session, spawning and
 supervising other sessions.**
 
-Two routes. Start with the skill.
+Three routes. In a Claude session, start with the skill. In any other CLI mode, use the
+`codeman agent` commands. Raw HTTP is there for everything else.
 
 ## The agent skill
 
@@ -59,6 +60,36 @@ DeepSeek Harness workers the same way it drives Claude ones (`spawn_workers alph
 beta:deepseek` is a mixed fleet in one call), since those are the two modes with real
 completion signals.
 
+## The `codeman agent` commands
+
+The skill is Claude-shaped: Codeman seeds its preamble for Claude sessions only. An
+`opencode`, `codex`, `pi` or `gemini` agent runs in the same environment but has nothing
+that teaches it the API, so `codeman agent` packages the same verbs as shell commands. It is
+a thin client over the endpoints in [the manual path](#the-manual-path), so auth and
+ownership apply unchanged, and it refuses to act outside a Codeman session. One line in a
+case's `AGENTS.md` is enough: *"other sessions: `codeman agent --help`"*.
+
+```bash
+codeman agent ls                                          # sessions; * marks this one
+SID=$(codeman agent spawn scratch-1 --mode claude)        # quick-start + wait for the composer where the mode has a ready mark
+codeman agent send "$SID" 'review src/, then say DONE' --until stop,exit --timeout 300000
+codeman agent read "$SID"                                 # last answer (as the server reads it for that mode)
+codeman agent read "$SID" --tail 3000                     # terminal tail, ANSI stripped (every mode)
+codeman agent send "$SID" 'run the tests, then print WORKDONE followed by _4711'   # hook-less modes: the marker in halves …
+codeman agent wait "$SID" --match WORKDONE_4711           # … and the wait on the joined form
+codeman agent interrupt "$SID"                            # a bare ESC, conversation intact
+codeman agent rm "$SID"                                   # any session except this one
+```
+
+- **Ids** may be the 8-character form `ls` prints. Anything shorter refuses, and so does an
+  ambiguous prefix.
+- **`send`** takes ONE quoted argument of printable text and presses Enter. A prompt that
+  starts with `-` goes after `--`: `codeman agent send "$SID" -- "- fix the bug"`.
+- **Markers** follow [the split-marker trick](#the-split-marker-trick): the echo of your own
+  prompt is output too, so ask for the marker in halves and wait on the joined form.
+- **Exit codes** are the same for every verb: `0` done, `1` error, `2` timeout, `3` the
+  worker exited, `4` refused. `--json` prints the response's `data`.
+
 ## The manual path
 
 The same operations as raw HTTP, for a CI bot, a shell script, or an agent without skill
@@ -189,7 +220,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/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/Settings-Reference.md

@@ -63,12 +63,19 @@ Ultracode Windows, Cron.
 
 **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, 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
+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.
+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, and the gear.
+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. **Tiles** is desktop-only the same
@@ -83,18 +90,30 @@ every session or only the active tab.
 | Setting                | Notes                                                                                     |
 | ---------------------- | ----------------------------------------------------------------------------------------- |
 | Skin                   | Theme palettes, light ones included. Applied before first paint, so no flash of the wrong theme. |
-| Entrance Animations     | Per-surface animation styles for tabs, terminals, windows, and lineage lines. All default to the legacy no-animation behaviour. |
 | Display Name           | Your name in the UI. Cosmetic only; it never renames the package, CLI, API, or storage.    |
 | 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.                                                      |
 
+### Animations
+
+All per device, all off by default, applied as you pick them.
+
+| Setting                | Notes                                                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| Entrance Theme         | One look for how new tabs, terminal panes, agent windows and their lines arrive (Terminal, Beam down, Launch, Soft focus, Quiet, Playful). Off by default. |
+| Tile Animations        | How tiles arrive when the tile grid opens and leave when it closes: fly out of their tabs, dealt from the Tiles button, CRT, beam down, cascade, pop or soft; each screen then plays the theme's terminal animation. Off by default (the grid's quick fade); picking a theme presets it. |
+| Animation Lab          | Opens the per-surface lab (the same as `?animlab=1`): every style side by side, with replay, stagger and speed. Closes settings first. |
+
 ### Models
 
 Claude model cards, the 1M context window switch, the thinking effort segment and the
@@ -129,13 +148,19 @@ 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. |
+| MCP server sync                  | Copies the MCP servers each installed, enabled CLI (Claude, Codex, Gemini, OpenCode, Antigravity) and GitHub Copilot CLI has into the others' own config files. Synced, off by default, admin only in multi-user mode. Turn it on and **Apply** or **Save** (Apply keeps Settings open), 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`, `GEMINI_CLI_HOME` or `COPILOT_HOME` in Codeman's own environment is followed. |
 
 ### Notifications
 
-Master toggle, browser notifications, push subscription, audio alerts, the idle
+Master toggle, browser notifications, push subscription, audio alerts, how long a
+corner toast stays on screen (**Toast display time**, 1 to 300 seconds, default 3) and
+how long a desktop notification stays up before Codeman closes it (**Browser
+notification display time**, default 8; both per device, and your OS may close a
+desktop notification sooner), the idle
 threshold that decides when a quiet session counts as needing you, and the server-wide
 webhook (ntfy, Slack, Discord or generic JSON; admins only in multi-user mode). See
 [Notifications And Approvals](Notifications-And-Approvals).
@@ -154,7 +179,7 @@ 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. The **Diagnostics** group runs
+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.

docs/wiki/The-Dashboard.md

@@ -6,7 +6,7 @@ Most of Codeman's UI is **opt-in**. A stock install shows a deliberately small h
 feature you read about here may simply not be on screen yet. Where that is the case, this
 page says so and names the setting.
 
-![Codeman dashboard](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-tour-20260724.png)
+![Codeman dashboard](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-tour-20261010.png)
 
 ## Layout
 
@@ -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. **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. |
+| **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. **Search sessions** at the top of the rail narrows it to the tabs whose name matches (a web tab by its title), across every group, collapsed ones included, without changing the groups or the order; a tab with an alert stays visible even when its name does not match; Escape or × clears it, and it is never saved. 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                                                                 |
@@ -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,10 +161,23 @@ 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                  | Off, desktop only  | Up to six live sessions side by side. See [Tile Grid](Tile-Grid).                |
+| 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).
 
@@ -166,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

@@ -9,29 +9,39 @@ never offered in a popped-out session window.
 
 ## Turning it on
 
-**App Settings → Header & Panels → Tiles.** This is a per-device setting, off by default,
-so turning it on at your desk never puts the button on your phone. It shows a **Tiles**
-button in the header, beside Split, and enables `Ctrl+Shift+G`.
+**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.
+- **Tiles button**: one click shows the tiles straight away. If you have used the grid in
+  this browser before, you get it back exactly as you left it: the same sessions in the
+  same places, an empty place where you left one, the same number of tiles, your column
+  widths and row heights, the tile you were in, and a zoomed tile still zoomed. A session
+  closed since frees its place, which is filled the way a new grid is filled (below).
+  Otherwise, or when none of those sessions is left, you get as many tiles as you last
+  chose (six until you choose; fewer if the window is too small or you have fewer sessions
+  open): an open split's two first; otherwise the sessions that are working (the most
+  recently started first), then the ones waiting on you (red and yellow tabs), then the
+  rest, the most recently used first, so the oldest are the ones left out. The session you
+  are on always comes along and is 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.
+  count you chose 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.
+  **2**, **4** or **6**, each drawn as its layout. Your choice is remembered in this
+  browser. Picking a count opens the grid with that many tiles (the grid you left, its
+  tiles in their places, new ones in the empty places first), and it is what a click opens
+  when there is no grid to bring back. 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 working ones
+  first, then the ones waiting on you, then the most recent. 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
+  the grid closed it opens what the Tiles button would show with that session added: in the
+  empty place while the grid has fewer tiles than the count you chose, else in place of the
+  last tile (never more than the count). 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
@@ -58,7 +68,7 @@ Each tile has a small header: `● [logo] name · model ......... ⋯ ⤢ ×`
 | `●`    | 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. |
+| 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.                |
@@ -88,7 +98,8 @@ 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.
+the empty slot included, is saved with the grid and comes back when you turn the grid off
+and on, and on a page reload while the grid is open.
 
 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
@@ -121,8 +132,18 @@ session finder) shows that session on its own, the normal single view. The grid
 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.
+The grid is saved in this browser every time you change it (moving, resizing, adding or
+removing a tile, changing the count, focusing or zooming a tile), and never sent to the
+server. However you leave it (the Tiles button, another tab, Home, a link, closing its last
+tile or session), the Tiles button brings it back as it was. A page reload brings it back
+when the grid was open; after you left it, a reload shows the single view and the Tiles
+button still brings the grid back. A session that was closed or popped out into its own
+window in the meantime frees its place for another one, picked the way a new grid picks
+them; the place stays empty only when no other session is left. Right after a page reload
+the page does not know yet which sessions are waiting for your answer, so that pick goes by
+which sessions are working and which you used last. If the window has become too small for
+all the tiles, the tile you were in fills the grid until the window is wide enough again,
+and the rest of the layout is kept.
 
 Split shows the same logo, name and model above both of its panes.
 

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

@@ -14,9 +14,10 @@ It renders what it can:
 | Kind                     | Behaviour                                                                 |
 | ------------------------ | ------------------------------------------------------------------------- |
 | Text and code            | Plain preview with Lines (line numbers) and Wrap toggles in the header. Long files are truncated in plain preview. |
-| 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. |
+| 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). Links to another heading of the same file (`[Install](#installation)`) scroll to it, with GitHub's heading names (lower-case, punctuation dropped, repeats numbered `-1`, `-2`), and never leave the page. 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.                                                                  |
 
@@ -168,7 +169,7 @@ surface as an artifact attachment rather than a path you have to go and find.
 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, `✓` when everything is committed and pushed.
+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:
 
@@ -187,7 +188,10 @@ Click it for a draggable window, in the style of the File Viewer:
   **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. They all start collapsed (each summary line shows its branch and
+  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.
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "aicodeman",
-  "version": "1.35.0",
-  "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
+  "version": "1.41.0",
+  "description": "Self-hosted mission control for AI coding agents: run Claude Code, Codex, OpenCode, Gemini, DeepSeek, Grok and more 24/7 in tmux, from any device.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,7 +42,7 @@
     "check:lockfile": "node scripts/check-lockfile-sync.mjs",
     "check:plugin": "node scripts/sync-plugin.mjs --check && claude plugin validate --strict plugins/codeman && claude plugin validate --strict .claude-plugin/marketplace.json",
     "knip": "npx --yes knip@latest --config config/knip.json",
-    "release": "changeset publish"
+    "release": "node scripts/npm-release.mjs"
   },
   "prettier": {
     "singleQuote": true,
@@ -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",
@@ -169,7 +171,7 @@
   "bugs": {
     "url": "https://github.com/Ark0N/Codeman/issues"
   },
-  "homepage": "https://github.com/Ark0N/Codeman#readme",
+  "homepage": "https://getcodeman.com",
   "files": [
     "dist",
     "scripts/postinstall.js",

packages/xterm-zerolag-input/CHANGELOG.md

@@ -1,5 +1,51 @@
 # xterm-zerolag-input
 
+## 0.4.1
+
+### Patch Changes
+
+- 87f1c9c: ### Thanks
+  - @Randalix for `codeman agent` (#557), the session verbs (`ls`, `spawn`, `send`, `wait`, `read`, `interrupt`, `rm`) for agents in every CLI mode, and for moving every test server onto an ephemeral port (#570), which finishes #440. Thanks also for reporting and fixing git's clone errors on non-English hosts (#568, shipped as #572 with your commit).
+  - @opticon454 for five PRs: MCP server sync for GitHub Copilot CLI (#581), an Apply button that saves Settings without closing them (#565), configurable toast and browser-notification display times (#564), in-document links in rendered markdown that scroll to their heading (#563), and npm-based CLI installs that work when the system npm prefix is root-owned (#562).
+  - @JDProfresh for three PRs: pasted and uploaded files moving into a hidden, self-ignoring `.codeman-uploads/` folder (#574, after your #553 proposal), local echo that keeps painting on phones when the view sits above the bottom (#576), and upload failures that say why they failed (#578).
+  - @aakhter for session search on the vertical tab rail (#580), built on the sidebar's existing filter instead of a second one, and for keeping alerted tabs visible during a search.
+
+  ![Codeman tile grid: six live agents powering on and off with the CRT tile animation](https://raw.githubusercontent.com/Ark0N/Codeman/08694b5862534b2b1224e9e272ad9858c787ebef/release-1.41/tiles-crt-stats-800.gif)
+
+  **Tile Animations (#571).** The tile grid from 1.40.0 can now open with a show. App Settings has a new **Animations** section (right after Appearance) that holds every animation setting: the Entrance Theme (moved out of Appearance), the new **Tile Animations** row, and a button that opens the animation lab. Tile styles: **CRT** (each tile switches on as a hot line in a diagonal wave, and switches off to a line and a dot), **Fly from tab** (each tile grows out of its session tab and flies back into it), **Deal** (dealt out of the Tiles button like cards), **Beam down**, **Cascade**, **Pop**, **Soft** and **None**. A styled tile plays in two beats: the frame enters in the tile style, then its screen powers on in the terminal style of your Entrance Theme. Picking a theme presets a matching tile style, and a new **Launch** theme flies the tiles out of their tabs. Off by default (the grid keeps its quick fade), per device, nothing moves under reduced motion, and the animations never cost an extra PTY resize. The terminal pane's Boot entrance style is gone; a saved Boot falls back to off.
+
+  **Tiles open the sessions you care about, and keep your layout.** With no grid arranged yet, the Tiles button (or `Ctrl+Shift+G`) now fills the grid with the sessions that are working first (most recently started first), then the ones waiting on you (a permission prompt or a finished turn you have not seen), then the most recently used, instead of the tabs in strip order, which opened the oldest ones. The session you are on is still always included. Once you arrange a grid (which session sits where, empty cells, the tile count, divider sizes, the focused and zoomed tile), that layout is remembered in this browser and the Tiles button brings it back exactly, however the grid was closed, and so does a reload while it was open. A session that has gone since frees its place, which the same ranking fills. A grid larger than the window opens in full with the focused tile zoomed, instead of being trimmed (and losing the rest of your layout).
+
+  **The wheel scrolls Claude inside a tile (#577).** In a tile or the split's second pane, a Claude session on its fullscreen renderer now scrolls its own conversation with the mouse wheel, exactly like the main terminal: the wheel goes to Claude as mouse reports, aimed at that tile's session and computed from the tile's own screen. Before, the wheel did nothing or scrolled the stale frames left over from loading the tile. Shift+wheel (scroll local history) works in every tile on Windows and Linux too; it was dead there.
+
+  **`codeman agent`: session verbs for every CLI (#557).** Agents in any mode (Codex, OpenCode, Gemini, Pi and the rest, not just Claude) can now drive other Codeman sessions from the command line: `codeman agent ls | spawn | send | wait | read | interrupt | rm`. It is a thin client over the existing session API: every call names the session that made it, `wait` blocks on a signal (`--until stop,exit`) or a literal output marker (`--match`), and exit codes say what happened (`0` ok, `1` error, `2` timeout, `3` exited, `4` refused). Ids shorter than 8 characters are refused, so a stray `rm 9` can never pick a session at random, and `rm` never deletes the session it runs in. See the README section "`codeman agent`" and the wiki page Driving Codeman From An Agent. This is phase 1 of #445.
+
+  **Settings: Apply (#565).** Next to Save, an Apply button saves the same way but keeps Settings open. Switching on MCP server sync makes its Preview and Sync usable straight away, and CLI management's add, enable and disable work without closing and reopening Settings.
+
+  **MCP server sync reaches GitHub Copilot CLI (#581).** With MCP server sync on (App Settings, off by default), Copilot CLI's `~/.copilot/mcp-config.json` now takes part like the agent CLIs' own files: its servers are copied to the others and theirs to it, additively, with the previous file kept as `.codeman-bak`. Copilot joins only when it is installed or already has that file, a server switched off in Copilot is never copied, and `COPILOT_HOME` is followed. Copilot is a sync target only, not a new run mode.
+
+  **Notifications stay up longer if you want (#564).** Settings → Notifications has a Toast display time and a Browser notification display time (1 second to 5 minutes, per device; the defaults stay 3 s and 8 s).
+
+  **CLI logos on tabs can be switched off (#569).** App Settings → Appearance → Tabs → **CLI Logos on Tabs** hides the agent logo on every tab surface (header strip, rails, sidebar, phone chips, the desktop home list) on this device. On by default. Tile headers, split pane headers and the Run menus keep their logos.
+
+  **Search sessions on the vertical rail (#580).** The vertical tab rail has a **Search sessions** box at the top: type part of a name and the rail narrows to the tabs that match (a web tab by its title), across every group, collapsed ones included, without touching your groups, their collapse or the tab order. A tab with an alert stays visible even when its name does not match, so a prompt waiting on you is never filtered away. Escape or × clears it, you can still drag a found tab into a group, and nothing is saved. The sidebar's filter box shares the same filter: a tab with an alert stays visible there too, and in the by-case tab layout a case with no match now hides.
+
+  **Closing a tab is instant.** Closing a session used to take half a second or more before the tab went away. The tab, tile or split pane now goes (and the next session is selected) the moment you click, while the server shuts the session down in the background, and the server side is faster too (about 450 ms down to 200-260 ms for a Claude session): it no longer sleeps fixed intervals, no longer freezes for about 70 ms per close on a synchronous tmux call, and scans for a session's subagents once instead of once per subagent. If the server refuses the close, the tab comes back where it was with the error. This also fixes a bug where a failed close still said "Session closed" while the session kept running.
+
+  **Fixes.**
+  - **Clone errors on non-English hosts (#572, from #568).** Cloning a repository as a case now classifies a failed clone correctly whatever the host's language: a missing branch or tag is "does not exist on the remote" (400) and a missing repository is a 404, instead of a generic 422 with git's German (or any other) error text. Git runs with `LC_ALL=C` for clones and repo status, so the repo status card's error text is English on every host as well.
+  - **Links within a markdown file (#563).** A link to another heading of the same document (`[Install](#installation)`) in the File Viewer or Response Viewer scrolls to that heading instead of doing nothing. Headings get GitHub-style slugs, repeated titles are numbered, and non-ASCII headings work.
+  - **npm CLI installs on a root-owned prefix (#562).** Installing an npm-based CLI from Settings (DeepSeek's `dsh`, pi, ...) no longer fails with EACCES when the system node keeps its global prefix under `/usr`: the install goes to `~/.local`, where Codeman already looks for CLIs. A prefix you set yourself, or one you can write to, is left alone, including when Codeman runs under `npm run`.
+  - **Uploads go to a hidden `.codeman-uploads/` folder (#574).** Images you paste or upload into a prompt are saved in `<workspace>/.codeman-uploads/` instead of `.claude-images/`. The folder ignores itself in git (it carries a `.gitignore` of `*`), stays hidden in the Files panel, and is cleaned up as before: files older than 7 days in an hourly sweep, and the folder when the last session in that workspace closes. The old `.claude-images/` folder gets nothing new and is still swept and removed during 1.41.x. An upload to a remote (SSH) session is now refused with a clear message, since the file would land on the Codeman host where the remote agent cannot read it.
+  - **Typing on a phone after a tab switch (#576, fixes #575).** With local echo on (the default on touch devices), text typed while the terminal sat above the bottom was buffered but never painted, so the keyboard looked dead. The view sits there after every tab switch and after the keyboard closes. The overlay now paints whenever the prompt row is on screen, and hides only when you scroll the prompt out of view.
+  - **Upload failures say why (#578).** When a prompt image upload fails, the toast shows the server's reason (for example a rate limit) instead of only "1 failed".
+  - **The npm page shows the English README.** npmjs.com had been rendering the Chinese README, because npm picks the package's readme from an unsorted file match at publish time. The publish now moves `README.zh-CN.md` aside while it runs (the file and every link to it stay as they are), and the package description and homepage say what Codeman is and point at getcodeman.com.
+  - **New cases ask for clickable file paths.** The CLAUDE.md generated into a new case asks the agent to report every file it created as a full absolute path, which Codeman turns into a link that opens the File Viewer, and mentions the codeman skill for starting and managing worker sessions.
+
+  **For contributors (#570).** Every in-process test server binds an ephemeral port, the mobile suite included, and the port guard now also refuses raw listeners on a fixed port, so two test runs on one machine never collide.
+
+  **Fixes applied while landing.** zh-CN translations for the two new notification display-time settings and for the new Animations section. A session whose name matches an interface word ("Lab", "New session") is no longer translated in the tab strip when the interface is in Chinese. Plus test and doc cleanups left over from review.
+
 ## 0.4.0
 
 ### Minor Changes

packages/xterm-zerolag-input/README.md

@@ -537,7 +537,7 @@ While flushed text exists the prompt column is locked, so a full-screen redraw c
 
 ### Scroll awareness
 
-The overlay hides when the viewport is scrolled up (`viewportY !== baseY`) and re-renders, debounced, when you scroll back to the bottom.
+The overlay hides while the cursor row is scrolled out of the viewport and re-renders, debounced, when it scrolls back into view. A viewport parked a few rows above the bottom keeps painting as long as the cursor row is on screen. A buffer that reports no `cursorY` keeps the bottom-only rule.
 
 ---
 

packages/xterm-zerolag-input/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xterm-zerolag-input",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Instant keystroke feedback overlay for xterm.js: Mosh-inspired local echo that removes perceived input latency over SSH, tunnels and other high-RTT connections",
   "type": "module",
   "main": "dist/index.cjs",

packages/xterm-zerolag-input/src/prompt-finder.ts

@@ -72,3 +72,20 @@ export function readTextAfterPrompt(terminal: XtermTerminal, prompt: PromptPosit
     return '';
   }
 }
+
+/**
+ * Whether the row the overlay draws on (the cursor row) is inside the viewport. A bare
+ * `viewportY === baseY` test is wrong for a host that parks the viewport a few rows above
+ * the bottom with the prompt still on screen; a buffer without `cursorY` keeps that rule.
+ */
+export function promptRowInViewport(terminal: XtermTerminal): boolean {
+  try {
+    const buf = terminal.buffer.active;
+    if (buf.viewportY === buf.baseY) return true;
+    if (typeof buf.cursorY !== 'number') return false;
+    const cursorRow = buf.baseY + buf.cursorY;
+    return cursorRow >= buf.viewportY && cursorRow < buf.viewportY + terminal.rows;
+  } catch {
+    return false;
+  }
+}

packages/xterm-zerolag-input/src/zerolag-input-addon.ts

@@ -8,7 +8,7 @@ import type {
   FontStyle,
 } from './types.js';
 import { getCellDimensions } from './cell-dimensions.js';
-import { findPrompt, readTextAfterPrompt } from './prompt-finder.js';
+import { findPrompt, readTextAfterPrompt, promptRowInViewport } from './prompt-finder.js';
 import { renderOverlay, charCellWidth } from './overlay-renderer.js';
 
 const DEFAULT_PROMPT: PromptFinder = { type: 'character', char: '>', offset: 2 };
@@ -122,11 +122,10 @@ export class ZerolagInputAddon implements XtermAddon {
     // Cache font properties
     this._cacheFont();
 
-    // Scroll detection: hide overlay when scrolled away from bottom
+    // Scroll detection: hide the overlay while the cursor row is scrolled out of view
     this._scrollHandler = () => {
       try {
-        const buf = this._terminal!.buffer.active;
-        if (buf.viewportY !== buf.baseY) {
+        if (!promptRowInViewport(this._terminal!)) {
           this._overlay!.style.display = 'none';
           if (this._scrollTimer) {
             clearTimeout(this._scrollTimer);
@@ -565,8 +564,8 @@ export class ZerolagInputAddon implements XtermAddon {
     try {
       const buf = this._terminal.buffer.active;
 
-      // Hide overlay when scrolled up — prompt is at bottom, not in viewport
-      if (buf.viewportY !== buf.baseY) {
+      // Hide the overlay while the cursor row is scrolled out of view
+      if (!promptRowInViewport(this._terminal)) {
         this._overlay.style.display = 'none';
         return;
       }

packages/xterm-zerolag-input/test/prompt-finder.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { createMockTerminal } from './helpers.js';
-import { findPrompt, readTextAfterPrompt } from '../src/prompt-finder.js';
+import { promptRowInViewport, findPrompt, readTextAfterPrompt } from '../src/prompt-finder.js';
 import type { XtermTerminal, PromptFinder } from '../src/types.js';
 
 function term(lines: string[]) {
@@ -156,3 +156,28 @@ describe('readTextAfterPrompt', () => {
     cleanup();
   });
 });
+
+describe('promptRowInViewport', () => {
+  const term = (viewportY: number, baseY: number, cursorY: number | undefined, rows = 24) =>
+    ({ rows, buffer: { active: { viewportY, baseY, cursorY, getLine: () => undefined } } }) as never;
+
+  it('is true at the bottom regardless of the cursor', () => {
+    expect(promptRowInViewport(term(10, 10, undefined))).toBe(true);
+  });
+
+  it('is true for a viewport parked above the bottom while the cursor row is on screen', () => {
+    // scrollToLastNonEmptyLine() parks rows - 2 above the last non-empty row
+    expect(promptRowInViewport(term(0, 16, 5))).toBe(true);
+    // cursor exactly on the last visible row
+    expect(promptRowInViewport(term(0, 23, 0))).toBe(true);
+  });
+
+  it('is false once the cursor row is scrolled out of the viewport', () => {
+    expect(promptRowInViewport(term(0, 24, 0))).toBe(false); // one past the last row
+    expect(promptRowInViewport(term(0, 200, 3))).toBe(false); // deep in history
+  });
+
+  it('keeps the bottom-only rule when the buffer has no cursorY', () => {
+    expect(promptRowInViewport(term(0, 1, undefined))).toBe(false);
+  });
+});

packages/xterm-zerolag-input/test/zerolag-input-addon.test.ts

@@ -725,3 +725,34 @@ describe('ZerolagInputAddon', () => {
     });
   });
 });
+
+describe('viewport scrolled away from the bottom', () => {
+  function parked(viewportY: number, baseY: number, cursorY: number, rows = 24) {
+    const mock = createMockTerminal({ buffer: { lines: ['$ '], viewportY, baseY, cursorY }, rows });
+    const addon = new ZerolagInputAddon({ prompt: { type: 'character', char: '$', offset: 2 } });
+    mock.terminal.loadAddon(addon);
+    cleanups.push(() => {
+      addon.dispose();
+      mock.cleanup();
+    });
+    const overlay = mock.terminal.element.querySelector('.xterm-screen')!.lastElementChild as HTMLDivElement;
+    return { addon, mock, overlay };
+  }
+
+  it('still paints with the viewport parked above the bottom while the cursor row is on screen', () => {
+    // The host parks the viewport to keep trailing blank rows out of view; the
+    // prompt and cursor are still visible, so the user's text must be too.
+    const { addon, overlay } = parked(0, 1, 0);
+    addon.appendText('abc');
+    expect(addon.pendingText).toBe('abc');
+    expect(overlay.style.display).not.toBe('none');
+    expect(overlay.textContent).toContain('abc');
+  });
+
+  it('hides once the cursor row is scrolled out of the viewport, even over a stale prompt glyph', () => {
+    const { addon, overlay } = parked(0, 30, 0);
+    addon.appendText('abc');
+    expect(addon.pendingText).toBe('abc');
+    expect(overlay.style.display).toBe('none');
+  });
+});

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.35.0",
+  "version": "1.41.0",
   "author": {
     "name": "Ark0N",
     "url": "https://github.com/Ark0N"

plugins/codeman/skills/codeman/SKILL.md

@@ -29,6 +29,12 @@ worked multi-worker flows in [reference/recipes.md](reference/recipes.md), endpo
 tables and a symptom gallery in [reference/endpoints.md](reference/endpoints.md), and
 direct messaging to claude workers in [reference/messaging.md](reference/messaging.md).
 
+Workers in **every other mode** never receive this preamble, but they have the same
+environment: tell them *"other sessions: `codeman agent --help`"* — the bundled CLI
+(`ls`, `spawn`, `send`, `wait`, `read`, `interrupt`, `rm`) is the same verbs over the
+same endpoints, with the guards below (no control bytes, no self-delete, no guessed
+URL) enforced in code.
+
 ## 0. Guard and bootstrap
 
 If `CODEMAN_MUX` is not `1`, **stop and say so**. Do not guess an API URL; a server

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/npm-release.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview `npm run release`: `changeset publish` with `README.zh-CN.md` moved aside.
+ *
+ * npmjs.com renders the package's top-level `readme`, and npm picks it at publish time:
+ * @npmcli/package-json's normalize globs `{README,README.*}` in the package root UNSORTED and
+ * keeps the first `.md` it sees. With `README.zh-CN.md` next to `README.md` that was the
+ * Chinese one on this machine and on CI, so npmjs.com showed the Chinese README for months.
+ * `files` cannot help: npm-packlist always includes every root `README.*`.
+ *
+ * Renaming the file would break every link to it, so for the length of the publish only it
+ * moves to a name npm does not treat as a readme (a leading dot), and is put back afterwards,
+ * whatever the publish did. The move happens HERE, inside the publish command, never as a
+ * step before `changesets/action` in release.yml: that action also runs the version path and
+ * commits the working tree into its version PR, which would commit the deletion.
+ *
+ * A previous run killed between the move and the restore leaves the aside copy behind; the
+ * next run puts it back first. `xterm-zerolag-input` (packages/) has only a README.md.
+ *
+ *   node scripts/npm-release.mjs    what the Release workflow runs (via `npm run release`)
+ */
+import { existsSync, renameSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HIDDEN_README = 'README.zh-CN.md';
+export const ASIDE_NAME = '.README.zh-CN.md.release-aside';
+
+/**
+ * Runs `publish` with `HIDDEN_README` moved aside in `root`, restoring it afterwards, also
+ * when `publish` fails or throws. Returns the exit code `publish` returned.
+ *
+ * @param {{ root: string, publish: () => number, log?: (msg: string) => void }} opts
+ * @returns {number}
+ */
+export function publishWithReadmeAside({ root, publish, log = (msg) => console.log(msg) }) {
+  const original = join(root, HIDDEN_README);
+  const aside = join(root, ASIDE_NAME);
+  if (existsSync(aside) && !existsSync(original)) {
+    renameSync(aside, original);
+    log(`npm-release: restored ${HIDDEN_README} left aside by an earlier run`);
+  }
+  const moved = existsSync(original);
+  if (moved) {
+    renameSync(original, aside);
+    log(`npm-release: ${HIDDEN_README} moved aside so npm picks README.md as the readme`);
+  }
+  try {
+    return publish();
+  } finally {
+    if (moved) {
+      renameSync(aside, original);
+      log(`npm-release: ${HIDDEN_README} restored`);
+    }
+  }
+}
+
+function runChangesetPublish() {
+  const result = spawnSync('changeset', ['publish'], { stdio: 'inherit', shell: process.platform === 'win32' });
+  if (result.error) {
+    console.error(`npm-release: could not run changeset publish: ${result.error.message}`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const root = join(fileURLToPath(new URL('.', import.meta.url)), '..');
+  process.exitCode = publishWithReadmeAside({ root, publish: runChangesetPublish });
+}

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/SKILL.md

@@ -29,6 +29,12 @@ worked multi-worker flows in [reference/recipes.md](reference/recipes.md), endpo
 tables and a symptom gallery in [reference/endpoints.md](reference/endpoints.md), and
 direct messaging to claude workers in [reference/messaging.md](reference/messaging.md).
 
+Workers in **every other mode** never receive this preamble, but they have the same
+environment: tell them *"other sessions: `codeman agent --help`"* — the bundled CLI
+(`ls`, `spawn`, `send`, `wait`, `read`, `interrupt`, `rm`) is the same verbs over the
+same endpoints, with the guards below (no control bytes, no self-delete, no guessed
+URL) enforced in code.
+
 ## 0. Guard and bootstrap
 
 If `CODEMAN_MUX` is not `1`, **stop and say so**. Do not guess an API URL; a server

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-agent.ts

@@ -0,0 +1,980 @@
+/**
+ * @fileoverview `codeman agent …` — session-to-session verbs for the agent running
+ * inside a Codeman session, in every CLI mode.
+ *
+ * A thin HTTP client over endpoints that already exist (`quick-start`, `input`,
+ * `wait`, `wait-output`, `last-response`, `terminal`, `DELETE sessions/:id`). It
+ * invents no route and no transport: everything goes through `CODEMAN_API_URL`, so
+ * auth, ownership and the per-session waiter cap apply unchanged. The behaviour is
+ * the packaged agent skill's (`skills/codeman`), ported from shell prose into code
+ * with tests, so a `codex`/`opencode`/`pi` agent — which never gets the claude-only
+ * preamble — has the same verbs from one line in its AGENTS.md.
+ *
+ * Invariants (each asserted in `test/cli-agent.test.ts`):
+ * 1. Refuses outside a Codeman session (`CODEMAN_MUX=1` + `CODEMAN_API_URL`); it
+ *    never guesses a URL — a server you are not part of is not yours to drive.
+ * 2. `send` transmits printable text plus `\r` only. ESC exists solely as
+ *    `interrupt`, which never appends `\r`. A stray control byte is a dead session
+ *    in the fullscreen TUIs (opencode's `Ctrl+C` is `app_exit`).
+ * 3. `rm` fails closed: empty id, a short self id, or a prefix match in EITHER
+ *    direction refuses. Ids appear in full and 8-char form, so equality alone
+ *    misses a real combination — and the miss deletes the caller.
+ * 4. An id shorter than 8 characters refuses (exit 4) before any request, on every
+ *    verb. `9` would resolve to whichever session is alone with that first
+ *    character, the user's own interactive tab included.
+ *
+ * Commands live here as functions returning an exit code, not calling
+ * `process.exit`, so the whole surface is unit-testable against a fake server.
+ *
+ * @module cli-agent
+ */
+import http from 'node:http';
+import https from 'node:https';
+import type { Command } from 'commander';
+import {
+  basicAuthHeader,
+  credentialsFrom,
+  readCodemanEnvFile,
+  type CodemanCredentials,
+} from './codeman-credentials.js';
+import { getCli } from './config/cli-registry/registry.js';
+import { GLYPH, palette, table } from './cli-style.js';
+import { getErrorMessage } from './types.js';
+import { stripAnsi as stripAnsiSequences } from './utils/regex-patterns.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context and guard
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AgentContext {
+  /** Base URL of the Codeman server, from `CODEMAN_API_URL`. */
+  apiUrl: string;
+  /** This session's id, from `CODEMAN_SESSION_ID`. */
+  selfId: string;
+  /** Basic-auth credentials, when the server has a password. */
+  auth?: CodemanCredentials;
+}
+
+/** Thrown when the process is not inside a Codeman-managed session. */
+export class AgentGuardError extends Error {}
+
+/** Exit codes shared by every verb; a shell agent can branch on them. */
+export const EXIT = {
+  ok: 0,
+  error: 1,
+  timeout: 2,
+  dead: 3,
+  refused: 4,
+} as const;
+
+/**
+ * Resolve the context from the environment, or throw `AgentGuardError`.
+ *
+ * Credentials in the order every client of the API uses (`credentialsFrom`, shared
+ * with `codeman attach` and the TUI): each field from the environment (a session
+ * inherits the server's), then the data dir's `.env`. No password means the server
+ * is open (single-user) — or it is not, and the 401 says so.
+ */
+export function resolveAgentContext(
+  env: NodeJS.ProcessEnv = process.env,
+  envFile: () => Record<string, string> = readCodemanEnvFile
+): AgentContext {
+  if (env.CODEMAN_MUX !== '1') {
+    throw new AgentGuardError('Not inside a Codeman-managed session (CODEMAN_MUX is not 1); refusing to act.');
+  }
+  const apiUrl = env.CODEMAN_API_URL?.trim();
+  if (!apiUrl) {
+    throw new AgentGuardError('CODEMAN_API_URL is not set; refusing to guess a server.');
+  }
+  const selfId = env.CODEMAN_SESSION_ID?.trim();
+  if (!selfId) {
+    throw new AgentGuardError('CODEMAN_SESSION_ID is not set; cannot tell which session is me.');
+  }
+  const credentials = credentialsFrom(env, envFile());
+  return { apiUrl, selfId, auth: credentials.password ? credentials : undefined };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure helpers (the invariants)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Is `id` this session? Prefix in BOTH directions, because ids appear in full and
+ * in 8-char form (mux names, UI surfaces, Docker's truncated `$SELF`). A self id
+ * shorter than 8 characters cannot prove anything and is treated as "maybe me".
+ */
+export function isSelfSession(selfId: string, id: string): boolean {
+  if (!id || selfId.length < 8) return true;
+  return id.startsWith(selfId) || selfId.startsWith(id);
+}
+
+/** Why `rm` refuses, or `undefined` when the delete may go ahead. */
+export function deleteRefusal(selfId: string, id: string): string | undefined {
+  if (!id) return 'refusing: empty session id';
+  if (selfId.length < 8) return 'refusing: own session id unset or too short to prove this is not me';
+  if (isSelfSession(selfId, id)) return `refusing: ${id} is me`;
+  return undefined;
+}
+
+/**
+ * The prompt `send` was given, which must be ONE argument. Joining several with spaces
+ * would turn an unquoted `$(cat notes.txt)`, which the shell splits on every newline,
+ * back into a single line, so the multi-line refusal below would never see it.
+ */
+export function sendPromptFromArgs(words: readonly string[]): { text: string } | { error: string } {
+  if (words.length === 1) return { text: words[0] };
+  return {
+    error: `refusing: the prompt must be ONE argument, got ${words.length} — quote it (\`send <id> "…"\`; a prompt that starts with "-" goes after --: \`send <id> -- "- fix the bug"\`)`,
+  };
+}
+
+/**
+ * Why `send` refuses this text, or `undefined` when it is printable. The composer
+ * takes one line; the server strips `\r`/`\n` but everything else below 0x20 (and
+ * DEL) reaches the pane as a keypress. None of that is a prompt.
+ */
+export function inputRefusal(text: string): string | undefined {
+  if (text.length === 0) return 'refusing: empty input (use `interrupt` for ESC, `send <id> ""` is never a prompt)';
+  // The composer is one line: the server strips newlines, which silently joins the
+  // lines into one prompt, and a tab reaches the pane as a keypress (claude: mode toggle).
+  if (/[\n\r\t]/.test(text)) {
+    return 'refusing: input must be a single line (the composer strips newlines and would join your lines) — join them yourself, or write a file into the workspace and send its path';
+  }
+  // C0, DEL and C1 (U+0080–U+009F: an 8-bit CSI is still a CSI to a terminal).
+  // eslint-disable-next-line no-control-regex
+  const control = text.match(/[\x00-\x1f\x7f-\x9f]/);
+  if (control) {
+    const code = control[0].charCodeAt(0).toString(16).padStart(2, '0');
+    return `refusing: input contains control byte 0x${code}; send transmits printable text only (ESC is \`interrupt\`)`;
+  }
+  return undefined;
+}
+
+/**
+ * Body for `POST /sessions/:id/input` on the send path: text plus `\r` unless the
+ * caller asked to type without submitting. Never anything else.
+ */
+export function buildSendBody(
+  text: string,
+  options: { enter: boolean; clientId: string; seq: number; wait?: string | true; waitTimeout?: number }
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    input: options.enter ? `${text}\r` : text,
+    useMux: true,
+    clientId: options.clientId,
+    seq: options.seq,
+  };
+  if (options.wait !== undefined) body.wait = options.wait;
+  if (options.waitTimeout !== undefined) body.waitTimeout = options.waitTimeout;
+  return body;
+}
+
+/** Body for the interrupt path: a bare ESC, and nothing appended — ever. */
+export function buildInterruptBody(clientId: string, seq: number): Record<string, unknown> {
+  return { input: '\u001b', useMux: true, clientId, seq };
+}
+
+/** `clientId` for this caller: fixed per sending session, so `seq` stays monotonic. */
+export function defaultClientId(selfId: string, suffix = ''): string {
+  return `codeman-agent-cli-${selfId.slice(0, 8)}${suffix ? `-${suffix}` : ''}`;
+}
+
+/**
+ * Strip a terminal buffer for humans: the shared ANSI strip (CSI, OSC such as window
+ * titles, keypad modes) plus the charset designators (`ESC ( B`) it leaves in.
+ */
+export function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return stripAnsiSequences(text).replace(/\x1b[()][AB0]/g, '');
+}
+
+/** Parse a positive-integer option (`--timeout` ms, `--tail` bytes); the server rejects anything else. */
+export function parsePositiveInt(raw: string | undefined, fallback: number, flag = '--timeout'): number {
+  if (raw === undefined) return fallback;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`${flag} must be a positive integer, got "${raw}"`);
+  }
+  return n;
+}
+
+/**
+ * Exit code for a wait result: matched or a signal → ok, `exit` or `ended` → dead,
+ * timeout → timeout. `ended` is checked BEFORE the happy paths: a worker that dies
+ * during `--until stop` comes back as `ended:true, signal:null` (the registry only
+ * satisfies waiters that listed `exit`, then cancels the rest), and a `--match` on
+ * a dead worker as `ended:true, matched:false` — both are "dead", never "done".
+ */
+export function waitExitCode(wait: WaitResult | undefined): number {
+  if (!wait) return EXIT.error;
+  if (wait.signal === 'exit' || wait.ended) return EXIT.dead;
+  if (wait.timedOut) return EXIT.timeout;
+  if (wait.matched === false) return EXIT.timeout;
+  return EXIT.ok;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ApiEnvelope<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  errorCode?: string;
+}
+
+export interface ApiResponse<T = unknown> {
+  status: number;
+  /** Parsed envelope, or `undefined` when the body was not JSON (auth guards answer in plain text). */
+  json?: ApiEnvelope<T>;
+  text: string;
+}
+
+export interface WaitResult {
+  /** The signal that fired, or null when the wait ended without one. */
+  signal?: string | null;
+  timedOut?: boolean;
+  /** The session went away (deleted / torn down / the write failed) before the wait resolved. */
+  ended?: boolean;
+  timeoutMs?: number;
+  until?: string[];
+  matched?: boolean;
+  match?: string;
+  snippet?: string;
+  immediate?: boolean;
+}
+
+export interface RequestOptions {
+  method: 'GET' | 'POST' | 'DELETE';
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  /** Socket timeout; long-polls pass their own timeout plus headroom. */
+  timeoutMs?: number;
+}
+
+export type ApiRequest = (ctx: AgentContext, options: RequestOptions) => Promise<ApiResponse>;
+
+/** Every request carries these; they are ignored on endpoints that do not read them. */
+export function baseHeaders(ctx: AgentContext): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    // Tags sessions this caller spawns as its children (lineage in the web UI).
+    // Cosmetic, never fails a call. NOT X-Codeman-Agent-Origin: that one marks a case
+    // directory as deletable agent scratch, so it rides only the spawn request that
+    // may create one (see agentSpawn), never anything else.
+    'X-Codeman-Parent-Session': ctx.selfId,
+  };
+  const authorization = ctx.auth ? basicAuthHeader(ctx.auth) : undefined;
+  if (authorization) headers.Authorization = authorization;
+  return headers;
+}
+
+/** The real transport. `rejectUnauthorized:false` because the HTTPS install uses a self-signed cert. */
+export const httpRequest: ApiRequest = (ctx, options) => {
+  const url = new URL(options.path, ctx.apiUrl);
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    if (value !== undefined) url.searchParams.set(key, String(value));
+  }
+  const bodyText = options.body === undefined ? undefined : JSON.stringify(options.body);
+  const headers: Record<string, string | number> = { ...baseHeaders(ctx), ...(options.headers ?? {}) };
+  if (bodyText !== undefined) {
+    headers['Content-Type'] = 'application/json';
+    headers['Content-Length'] = Buffer.byteLength(bodyText);
+  }
+  const transport = url.protocol === 'https:' ? https : http;
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port,
+        method: options.method,
+        path: `${url.pathname}${url.search}`,
+        rejectUnauthorized: false,
+        headers,
+        timeout: options.timeoutMs ?? 30_000,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk: Buffer) => chunks.push(chunk));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf-8');
+          let json: ApiEnvelope | undefined;
+          try {
+            json = JSON.parse(text) as ApiEnvelope;
+          } catch {
+            json = undefined;
+          }
+          resolve({ status: res.statusCode ?? 0, json, text });
+        });
+      }
+    );
+    req.on('timeout', () => req.destroy(new Error(`request timed out after ${options.timeoutMs ?? 30_000} ms`)));
+    req.on('error', reject);
+    if (bodyText !== undefined) req.write(bodyText);
+    req.end();
+  });
+};
+
+/** One line describing a failed response, for humans. Plain-text guards (401/403/429) have no envelope. */
+export function describeFailure(res: ApiResponse): string {
+  if (res.json && !res.json.success) {
+    return `${res.json.errorCode ?? 'ERROR'}: ${res.json.error ?? 'request failed'} (HTTP ${res.status})`;
+  }
+  const text = res.text.trim().split('\n')[0] ?? '';
+  if (res.status === 401)
+    return `HTTP 401 ${text}: the server wants a password (CODEMAN_PASSWORD, or the data dir's .env)`;
+  return `HTTP ${res.status}${text ? ` ${text}` : ''}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commands
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AgentIo {
+  out: (line: string) => void;
+  err: (line: string) => void;
+}
+
+export interface AgentDeps {
+  ctx: AgentContext;
+  request: ApiRequest;
+  io: AgentIo;
+  json: boolean;
+  /** Clock for `seq`; injectable so tests are deterministic. */
+  now?: () => number;
+}
+
+/** Print `data` as JSON (the `--json` path) — always the envelope's `data`, never a reshaped copy. */
+function emitJson(deps: AgentDeps, data: unknown): void {
+  deps.io.out(JSON.stringify(data, null, 2));
+}
+
+function fail(deps: AgentDeps, message: string, code: number = EXIT.error): number {
+  if (deps.json) {
+    deps.io.out(JSON.stringify({ success: false, error: message }));
+  } else {
+    deps.io.err(palette.err(`${GLYPH.fail} ${message}`));
+  }
+  return code;
+}
+
+interface SessionRow {
+  id: string;
+  name?: string;
+  mode?: string;
+  status?: string;
+  workingDir?: string;
+  pid?: number | null;
+  parentSessionId?: string | null;
+}
+
+/** A full session id (the only form the routes accept); `ls` prints the 8-char prefix. */
+const FULL_ID_LENGTH = 36;
+
+/**
+ * Shortest prefix that may name a session: the 8-char form `ls` prints, and the floor
+ * the server's own resolver uses (`PARENT_SESSION_ID_MIN_PREFIX`, route-helpers.ts).
+ */
+export const MIN_ID_PREFIX_LENGTH = 8;
+
+/**
+ * Turn the id a human typed into the one the routes accept. `ls` prints 8-char
+ * prefixes and the routes answer 404 to those (measured live), so anything shorter
+ * than a full id resolves through the session list; an ambiguous prefix refuses
+ * rather than picking one. Below 8 characters it refuses before the list: "unique"
+ * means nothing for `9` — it names whatever session happens to be alone with that
+ * first character, and `rm`/`send` would act on it.
+ */
+export async function resolveSessionId(
+  deps: AgentDeps,
+  id: string
+): Promise<{ id: string } | { error: string; code: number }> {
+  if (!id) return { error: 'refusing: empty session id', code: EXIT.refused };
+  if (id.length < MIN_ID_PREFIX_LENGTH) {
+    return {
+      error: `refusing: "${id}" is shorter than ${MIN_ID_PREFIX_LENGTH} characters — use the 8-character id \`agent ls\` prints, or the full id`,
+      code: EXIT.refused,
+    };
+  }
+  if (id.length >= FULL_ID_LENGTH) return { id };
+  const res = await deps.request(deps.ctx, { method: 'GET', path: '/api/v1/sessions' });
+  if (!res.json?.success) return { error: describeFailure(res), code: EXIT.error };
+  const matches = ((res.json.data as SessionRow[] | undefined) ?? []).filter((s) => s.id.startsWith(id));
+  if (matches.length === 1) return { id: matches[0].id };
+  if (matches.length === 0) return { error: `no session starts with "${id}" (see \`agent ls\`)`, code: EXIT.error };
+  return { error: `"${id}" is ambiguous: ${matches.map((s) => s.id.slice(0, 13)).join(', ')}`, code: EXIT.error };
+}
+
+/** `agent ls` — every session the caller can see, self marked. */
+export async function agentLs(deps: AgentDeps): Promise<number> {
+  const res = await deps.request(deps.ctx, { method: 'GET', path: '/api/v1/sessions' });
+  if (!res.json?.success) return fail(deps, describeFailure(res));
+  const sessions = (res.json.data as SessionRow[] | undefined) ?? [];
+  if (deps.json) {
+    emitJson(
+      deps,
+      sessions.map((s) => ({ ...s, self: isSelfSession(deps.ctx.selfId, s.id) }))
+    );
+    return EXIT.ok;
+  }
+  if (sessions.length === 0) {
+    deps.io.out(palette.muted('(no sessions)'));
+    return EXIT.ok;
+  }
+  const rows = sessions.map((s) => [
+    isSelfSession(deps.ctx.selfId, s.id) ? '*' : ' ',
+    s.id.slice(0, 8),
+    s.mode ?? '?',
+    s.status ?? '?',
+    s.name || s.workingDir || '',
+  ]);
+  deps.io.out(table([[' ', 'ID', 'MODE', 'STATUS', 'NAME'], ...rows], { gap: 2 }));
+  deps.io.out(
+    palette.muted(`* = this session (${deps.ctx.selfId.slice(0, 8)}). status is a UI hint, never a sync signal.`)
+  );
+  return EXIT.ok;
+}
+
+export interface SpawnOptions {
+  caseName: string;
+  mode: string;
+  name?: string;
+  /** Wait for the composer before returning, where the registry gives the mode a ready mark. */
+  ready: boolean;
+  timeoutMs: number;
+}
+
+/**
+ * Agent-scratch label for a case directory a spawn CREATES (the server applies it only
+ * when quick-start makes the directory). The Add Case UI offers a recursive delete for
+ * such directories, so this header must never ride any other request: mislabelling a
+ * real repo there is the one failure in this area that costs actual work.
+ */
+export const AGENT_ORIGIN_HEADER = { 'X-Codeman-Agent-Origin': 'codeman-agent-cli' } as const;
+
+/**
+ * What the mode's TUI draws once its composer can take a prompt, from the CLI registry
+ * (`capabilities.composerReadyMark`); undefined means the mode has no readiness wait.
+ */
+export function composerReadyMark(mode: string): string | undefined {
+  return getCli(mode)?.capabilities.composerReadyMark;
+}
+/** `agent spawn` — quick-start with lineage, then the readiness ladder where the mode has one. */
+export async function agentSpawn(deps: AgentDeps, options: SpawnOptions): Promise<number> {
+  const body: Record<string, unknown> = {
+    caseName: options.caseName,
+    mode: options.mode,
+    parentSessionId: deps.ctx.selfId,
+  };
+  if (options.name) body.sessionName = options.name;
+  const res = await deps.request(deps.ctx, {
+    method: 'POST',
+    path: '/api/v1/quick-start',
+    body,
+    headers: { ...AGENT_ORIGIN_HEADER },
+  });
+  const data = res.json?.data as { sessionId?: string; caseName?: string; casePath?: string } | undefined;
+  if (!res.json?.success || !data?.sessionId) return fail(deps, describeFailure(res));
+  const sid = data.sessionId;
+
+  let ready: boolean | undefined;
+  let readinessError: string | undefined;
+  let dead = false;
+  const mark = composerReadyMark(options.mode);
+  if (options.ready && mark) {
+    const wait = await deps.request(deps.ctx, {
+      method: 'GET',
+      path: `/api/v1/sessions/${encodeURIComponent(sid)}/wait-output`,
+      query: { match: mark, from: 'buffer', timeout: options.timeoutMs },
+      timeoutMs: options.timeoutMs + 10_000,
+    });
+    // A failed readiness call (waiter cap, 400, network) is its own error, not "the
+    // composer never showed up": report the real reason instead of the trust-dialog hint.
+    if (!wait.json?.success) readinessError = describeFailure(wait);
+    else {
+      const result = (wait.json.data as { wait?: WaitResult } | undefined)?.wait;
+      // A worker that died while we waited is exit 3 like every other wait, not a
+      // "composer not seen" timeout that sends the caller looking for a dialog.
+      dead = waitExitCode(result) === EXIT.dead;
+      ready = !dead && Boolean(result?.matched);
+    }
+  }
+
+  if (deps.json) {
+    emitJson(deps, { ...data, ready, readinessError });
+  } else {
+    // Human lines go to stderr so `SID=$(codeman agent spawn …)` captures the id alone.
+    const say = (line: string) => deps.io.err(line);
+    say(palette.ok(`${GLYPH.ok} spawned ${sid} (${options.mode}, case ${data.caseName ?? options.caseName})`));
+    if (ready === true) say(palette.muted('  composer up: the worker can take a prompt'));
+    if (dead) say(palette.err(`${GLYPH.fail} the worker exited during the readiness wait`));
+    if (ready === false && !dead) {
+      say(
+        palette.warn(
+          `${GLYPH.warn} composer not seen within ${options.timeoutMs} ms — read \`agent read ${sid.slice(0, 8)} --tail 2000\` before sending (a startup dialog?)`
+        )
+      );
+    }
+    if (readinessError) say(palette.err(`${GLYPH.fail} readiness check failed: ${readinessError}`));
+    if (ready === undefined && !readinessError && options.ready) {
+      say(
+        palette.muted(
+          `  ${options.mode} has no readiness mark; give it a moment, then use --match markers to synchronize`
+        )
+      );
+    }
+    deps.io.out(sid);
+  }
+  if (readinessError) return EXIT.error;
+  if (dead) return EXIT.dead;
+  return ready === false ? EXIT.timeout : EXIT.ok;
+}
+
+export interface SendOptions {
+  id: string;
+  text: string;
+  enter: boolean;
+  /** `undefined` = fire-and-forget; `true` = default signal set; string = comma list. */
+  wait?: string | true;
+  timeoutMs?: number;
+  clientId?: string;
+  seq?: number;
+}
+
+/** `agent send` — printable text plus `\r`, exactly-once, optionally blocking on end of turn. */
+export async function agentSend(deps: AgentDeps, options: SendOptions): Promise<number> {
+  if (isSelfSession(deps.ctx.selfId, options.id)) {
+    return fail(deps, `refusing: ${options.id} is me — typing into my own composer is not a message`, EXIT.refused);
+  }
+  const refusal = inputRefusal(options.text);
+  if (refusal) return fail(deps, refusal, EXIT.refused);
+  const target = await resolveSessionId(deps, options.id);
+  if ('error' in target) return fail(deps, target.error, target.code);
+  const body = buildSendBody(options.text, {
+    enter: options.enter,
+    clientId: options.clientId ?? defaultClientId(deps.ctx.selfId),
+    seq: options.seq ?? (deps.now ?? Date.now)(),
+    wait: options.wait,
+    waitTimeout: options.wait !== undefined ? options.timeoutMs : undefined,
+  });
+  const res = await deps.request(deps.ctx, {
+    method: 'POST',
+    path: `/api/v1/sessions/${encodeURIComponent(target.id)}/input`,
+    body,
+    timeoutMs: (options.timeoutMs ?? 60_000) + 10_000,
+  });
+  if (!res.json?.success) return fail(deps, describeFailure(res));
+  const data = res.json.data as
+    | { delivered?: boolean; duplicate?: boolean; buffered?: boolean; dropped?: boolean; wait?: WaitResult }
+    | undefined;
+  if (deps.json) emitJson(deps, data ?? {});
+  // Fire-and-forget to a remote session whose host is asleep (wake-on-LAN): the server
+  // holds the chunk and types it once the pane is back (`buffered`), or the chunk was
+  // over the wake buffer's cap and is gone (`dropped`). The seq is spent either way,
+  // so a retry needs a new one (the default, the clock, gives it that).
+  if (data?.dropped) {
+    if (!deps.json) {
+      deps.io.err(
+        palette.err(
+          `${GLYPH.fail} dropped: ${target.id}'s host is waking and its input buffer is full — nothing will be typed; send again once it is back`
+        )
+      );
+    }
+    return EXIT.error;
+  }
+  // `delivered:false` without `duplicate` is the route's "the bytes went nowhere":
+  // the PTY exited or send-keys hit a dead pane. The field exists so a client does not
+  // say "wait longer" when the truth is "restart the worker" — so it is a failure here.
+  if (data?.delivered === false && !data.duplicate) {
+    if (!deps.json) {
+      deps.io.err(
+        palette.err(`${GLYPH.fail} not delivered: ${target.id} has no live worker (pane exited) — restart it`)
+      );
+    }
+    return EXIT.dead;
+  }
+  if (!deps.json) {
+    const noEnter = options.enter ? '' : ' (no Enter)';
+    if (data?.duplicate) {
+      deps.io.out(palette.warn(`${GLYPH.warn} duplicate (clientId/seq already applied): nothing typed`));
+    } else if (data?.buffered) {
+      deps.io.out(
+        palette.ok(
+          `${GLYPH.ok} buffered for ${target.id}${noEnter}: its host is asleep; Codeman is waking it and types this once the pane is back`
+        )
+      );
+    } else if (data?.delivered === true) {
+      deps.io.out(palette.ok(`${GLYPH.ok} delivered to ${target.id}${noEnter}`));
+    } else {
+      // Fire-and-forget answers before the write, so there is no delivery report here.
+      deps.io.out(palette.ok(`${GLYPH.ok} accepted for ${target.id}${noEnter} (no delivery report without --wait)`));
+    }
+    if (data?.wait) deps.io.out(describeWait(data.wait));
+  }
+  if (options.wait === undefined) return EXIT.ok;
+  return waitExitCode(data?.wait);
+}
+
+function describeWait(wait: WaitResult): string {
+  if (wait.signal === 'exit') return palette.err(`${GLYPH.fail} the session exited`);
+  if (wait.ended) {
+    return palette.err(
+      `${GLYPH.fail} the wait ended without an answer: the session went away (dead worker, deleted, or nothing was written)`
+    );
+  }
+  // A timeout is a 200 with `timedOut`, an answer rather than a failure: exit 2 says it,
+  // so the line stays neutral instead of looking like an error to whoever reads the log.
+  if (wait.timedOut) return palette.muted(`timed out after ${wait.timeoutMs ?? '?'} ms (exit 2)`);
+  if (wait.matched !== undefined) {
+    return wait.matched
+      ? palette.ok(`${GLYPH.ok} matched "${wait.match}"${wait.snippet ? `: ${wait.snippet}` : ''}`)
+      : palette.muted('not matched (exit 2)');
+  }
+  return palette.ok(
+    `${GLYPH.ok} signal: ${wait.signal}${wait.immediate ? ' (immediate: current state, not a transition)' : ''}`
+  );
+}
+
+export interface WaitOptions {
+  id: string;
+  until?: string;
+  match?: string;
+  from?: 'buffer' | 'now';
+  fresh?: boolean;
+  nocase?: boolean;
+  timeoutMs: number;
+}
+
+/** `agent wait` — a signal (`--until`) or a literal output marker (`--match`). */
+export async function agentWait(deps: AgentDeps, options: WaitOptions): Promise<number> {
+  if (options.until && options.match)
+    return fail(deps, 'use either --until <signals> or --match <marker>, not both', EXIT.refused);
+  const target = await resolveSessionId(deps, options.id);
+  if ('error' in target) return fail(deps, target.error, target.code);
+  const sid = encodeURIComponent(target.id);
+  const res = options.match
+    ? await deps.request(deps.ctx, {
+        method: 'GET',
+        path: `/api/v1/sessions/${sid}/wait-output`,
+        query: {
+          match: options.match,
+          from: options.from ?? 'buffer',
+          nocase: options.nocase ? 1 : undefined,
+          timeout: options.timeoutMs,
+        },
+        timeoutMs: options.timeoutMs + 10_000,
+      })
+    : await deps.request(deps.ctx, {
+        method: 'GET',
+        path: `/api/v1/sessions/${sid}/wait`,
+        query: { until: options.until, fresh: options.fresh ? 1 : undefined, timeout: options.timeoutMs },
+        timeoutMs: options.timeoutMs + 10_000,
+      });
+  // A 400 here is the server saying "this mode has no such signal" (until=stop on an
+  // external CLI). Passed through, never papered over: the marker path is the answer.
+  if (!res.json?.success) return fail(deps, describeFailure(res));
+  const data = res.json.data as { wait?: WaitResult; status?: string; limitPaused?: boolean } | undefined;
+  if (deps.json) {
+    emitJson(deps, data ?? {});
+  } else if (data?.wait) {
+    deps.io.out(describeWait(data.wait));
+    if (data.limitPaused)
+      deps.io.out(palette.warn(`${GLYPH.warn} session is paused on a usage limit; a timeout is expected`));
+  }
+  return waitExitCode(data?.wait);
+}
+
+export interface ReadOptions {
+  id: string;
+  /** Bytes of raw terminal to fetch; ANSI is stripped for humans. */
+  tail?: number;
+  /** Whole conversation (`context=full`) instead of the last assistant message. */
+  full?: boolean;
+}
+
+/** `agent read` — the last answer (the route picks the transcript reader or the pane segmenter) or a terminal tail. */
+export async function agentRead(deps: AgentDeps, options: ReadOptions): Promise<number> {
+  const target = await resolveSessionId(deps, options.id);
+  if ('error' in target) return fail(deps, target.error, target.code);
+  const sid = encodeURIComponent(target.id);
+  if (options.tail !== undefined) {
+    const res = await deps.request(deps.ctx, {
+      method: 'GET',
+      path: `/api/v1/sessions/${sid}/terminal`,
+      query: { tail: options.tail },
+    });
+    if (!res.json?.success) return fail(deps, describeFailure(res));
+    const buffer = (res.json.data as { terminalBuffer?: string } | undefined)?.terminalBuffer ?? '';
+    if (deps.json) emitJson(deps, res.json.data);
+    else deps.io.out(stripAnsi(buffer));
+    return EXIT.ok;
+  }
+  const res = await deps.request(deps.ctx, {
+    method: 'GET',
+    path: `/api/v1/sessions/${sid}/last-response`,
+    query: { context: options.full ? 'full' : undefined },
+  });
+  if (!res.json?.success) return fail(deps, describeFailure(res));
+  const data = res.json.data as
+    | { text?: string; timestamp?: string; messages?: Array<{ role: string; text: string }> }
+    | undefined;
+  if (deps.json) {
+    emitJson(deps, data ?? {});
+    return EXIT.ok;
+  }
+  if (options.full && data?.messages) {
+    for (const m of data.messages) deps.io.out(`${palette.emph(m.role)}: ${m.text}`);
+    return EXIT.ok;
+  }
+  const text = data?.text ?? '';
+  if (!text) {
+    deps.io.err(
+      palette.muted('(empty: nothing answered yet, or nothing the server could segment as an answer; try --tail 3000)')
+    );
+    return EXIT.ok;
+  }
+  deps.io.out(text);
+  return EXIT.ok;
+}
+
+/** `agent interrupt` — a bare ESC keypress, no Enter, conversation intact. */
+export async function agentInterrupt(deps: AgentDeps, options: { id: string }): Promise<number> {
+  if (isSelfSession(deps.ctx.selfId, options.id)) return fail(deps, `refusing: ${options.id} is me`, EXIT.refused);
+  const target = await resolveSessionId(deps, options.id);
+  if ('error' in target) return fail(deps, target.error, target.code);
+  const body = buildInterruptBody(defaultClientId(deps.ctx.selfId, 'interrupt'), (deps.now ?? Date.now)());
+  const res = await deps.request(deps.ctx, {
+    method: 'POST',
+    path: `/api/v1/sessions/${encodeURIComponent(target.id)}/input`,
+    body,
+  });
+  if (!res.json?.success) return fail(deps, describeFailure(res));
+  if (deps.json) emitJson(deps, res.json.data ?? {});
+  else
+    deps.io.out(
+      palette.ok(
+        `${GLYPH.ok} ESC sent to ${target.id} — one Esc does not always land; read the tail before the next prompt`
+      )
+    );
+  return EXIT.ok;
+}
+
+/** `agent rm` — delete a session that is provably not this one. */
+export async function agentRm(deps: AgentDeps, options: { id: string }): Promise<number> {
+  const refusal = deleteRefusal(deps.ctx.selfId, options.id);
+  if (refusal) return fail(deps, refusal, EXIT.refused);
+  const target = await resolveSessionId(deps, options.id);
+  if ('error' in target) return fail(deps, target.error, target.code);
+  // The guard again on the RESOLVED id: a prefix that is not me can still resolve
+  // to me only if the list is lying, but a delete is the one call worth the paranoia.
+  const resolvedRefusal = deleteRefusal(deps.ctx.selfId, target.id);
+  if (resolvedRefusal) return fail(deps, resolvedRefusal, EXIT.refused);
+  const res = await deps.request(deps.ctx, {
+    method: 'DELETE',
+    path: `/api/v1/sessions/${encodeURIComponent(target.id)}`,
+  });
+  if (!res.json?.success) return fail(deps, describeFailure(res));
+  if (deps.json) emitJson(deps, res.json.data ?? {});
+  else deps.io.out(palette.ok(`${GLYPH.ok} deleted ${target.id} (its case directory stays on disk)`));
+  return EXIT.ok;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commander wiring
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_WAIT_MS = 60_000;
+
+/** Build deps from the live environment; the guard's message is the only thing a non-session caller sees. */
+function liveDeps(json: boolean): AgentDeps | undefined {
+  try {
+    return {
+      ctx: resolveAgentContext(),
+      request: httpRequest,
+      json,
+      io: { out: (line) => console.log(line), err: (line) => console.error(line) },
+    };
+  } catch (err) {
+    if (err instanceof AgentGuardError) {
+      console.error(palette.err(`${GLYPH.fail} ${err.message}`));
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+/** Run a verb with the live transport and turn its exit code into the process exit. */
+async function run(json: boolean, verb: (deps: AgentDeps) => Promise<number>): Promise<void> {
+  const deps = liveDeps(json);
+  if (!deps) {
+    process.exitCode = EXIT.refused;
+    return;
+  }
+  try {
+    process.exitCode = await verb(deps);
+  } catch (err) {
+    console.error(palette.err(`${GLYPH.fail} ${getErrorMessage(err)}`));
+    process.exitCode = EXIT.error;
+  }
+}
+
+/** Register `codeman agent …` on the program. */
+export function registerAgentCommands(program: Command): Command {
+  const agent = program
+    .command('agent')
+    .description('Talk to other sessions from inside one (any CLI mode): list, spawn, send, wait, read, interrupt, rm');
+
+  agent
+    .command('ls')
+    .alias('list')
+    .description('List sessions; * marks this one')
+    .option('--json', 'Machine-readable output')
+    .action((options: { json?: boolean }) => run(Boolean(options.json), agentLs));
+
+  agent
+    .command('spawn <case>')
+    .description(
+      'Start a worker session in a case (created if missing) and wait for its composer where the mode draws one'
+    )
+    .option('-m, --mode <mode>', 'Run mode id, as the Run menu names it', 'claude')
+    .option('-n, --name <name>', 'Session name shown in the UI')
+    .option('--no-ready', 'Return as soon as the session exists, without the readiness wait')
+    .option('-t, --timeout <ms>', 'Readiness budget in ms', String(DEFAULT_WAIT_MS))
+    .option('--json', 'Machine-readable output')
+    .action(
+      (caseName: string, options: { mode: string; name?: string; ready: boolean; timeout?: string; json?: boolean }) =>
+        run(Boolean(options.json), (deps) =>
+          agentSpawn(deps, {
+            caseName,
+            mode: options.mode,
+            name: options.name,
+            ready: options.ready,
+            timeoutMs: parsePositiveInt(options.timeout, DEFAULT_WAIT_MS),
+          })
+        )
+    );
+
+  agent
+    .command('send <id> <text...>')
+    .description(
+      'Type a prompt into another session and press Enter (ONE quoted argument, printable text only; a prompt that starts with "-" goes after --: send <id> -- "- fix the bug")'
+    )
+    .option('-w, --wait', 'Block until end of turn (the default signal set; see --until)')
+    .option('-u, --until <signals>', 'Signals to wait for, comma list such as stop,exit (implies --wait)')
+    .option('-t, --timeout <ms>', 'Wait budget in ms (with --wait)', String(DEFAULT_WAIT_MS))
+    .option('--no-enter', 'Type the text without submitting it')
+    .option('--client-id <id>', 'Exactly-once tag (default: one per calling session)')
+    .option(
+      '--seq <n>',
+      'Sequence number for the tag (default: the current epoch ms). Must stay monotonic per client id: a reused or lower value is a silent duplicate, nothing is typed'
+    )
+    .option('--json', 'Machine-readable output')
+    .action(
+      (
+        id: string,
+        words: string[],
+        options: {
+          wait?: boolean;
+          until?: string;
+          timeout?: string;
+          enter: boolean;
+          clientId?: string;
+          seq?: string;
+          json?: boolean;
+        }
+      ) =>
+        run(Boolean(options.json), (deps) => {
+          const prompt = sendPromptFromArgs(words);
+          if ('error' in prompt) return Promise.resolve(fail(deps, prompt.error, EXIT.refused));
+          return agentSend(deps, {
+            id,
+            text: prompt.text,
+            enter: options.enter,
+            wait: options.until ?? (options.wait ? true : undefined),
+            timeoutMs: parsePositiveInt(options.timeout, DEFAULT_WAIT_MS),
+            clientId: options.clientId,
+            seq: options.seq === undefined ? undefined : parsePositiveInt(options.seq, 1, '--seq'),
+          });
+        })
+    );
+
+  agent
+    .command('wait <id>')
+    .description(
+      'Block until a signal (--until) or an output marker (--match) — timeout exits 2, a dead worker exits 3'
+    )
+    .option(
+      '-u, --until <signals>',
+      'Comma list: stop,idle,exit,working,blocked (stop/blocked need hook signals for the session; where there are none the server answers 400, passed through)'
+    )
+    .option(
+      '-m, --match <marker>',
+      'Literal substring to wait for in the output (ANSI-stripped, no regex). The echo of your own prompt is output too, so never put the marker verbatim in the prompt: ask for it in halves ("print WORKDONE followed by _4711") and wait on the joined form (WORKDONE_4711)'
+    )
+    .option('--from <where>', 'buffer (scan existing output first, the default) or now', 'buffer')
+    .option('--nocase', 'Case-insensitive --match')
+    .option('--fresh', 'Require an actual transition (--until only)')
+    .option('-t, --timeout <ms>', 'Budget in ms', String(DEFAULT_WAIT_MS))
+    .option('--json', 'Machine-readable output')
+    .action(
+      (
+        id: string,
+        options: {
+          until?: string;
+          match?: string;
+          from: string;
+          nocase?: boolean;
+          fresh?: boolean;
+          timeout?: string;
+          json?: boolean;
+        }
+      ) =>
+        run(Boolean(options.json), (deps) =>
+          agentWait(deps, {
+            id,
+            until: options.until,
+            match: options.match,
+            from: options.from === 'now' ? 'now' : 'buffer',
+            nocase: options.nocase,
+            fresh: options.fresh,
+            timeoutMs: parsePositiveInt(options.timeout, DEFAULT_WAIT_MS),
+          })
+        )
+    );
+
+  agent
+    .command('read <id>')
+    .description("Print a session's last answer (as the server reads it for that mode) or, with --tail, its terminal")
+    .option('--tail <bytes>', 'Raw terminal tail in bytes, ANSI stripped (works in every mode)')
+    .option('--full', 'The whole conversation instead of the last assistant message')
+    .option('--json', 'Machine-readable output')
+    .action((id: string, options: { tail?: string; full?: boolean; json?: boolean }) =>
+      run(Boolean(options.json), (deps) =>
+        agentRead(deps, {
+          id,
+          tail: options.tail === undefined ? undefined : parsePositiveInt(options.tail, 3000, '--tail'),
+          full: options.full,
+        })
+      )
+    );
+
+  agent
+    .command('interrupt <id>')
+    .description('Send a bare ESC to stop the current turn (the conversation survives; deleting would not)')
+    .option('--json', 'Machine-readable output')
+    .action((id: string, options: { json?: boolean }) =>
+      run(Boolean(options.json), (deps) => agentInterrupt(deps, { id }))
+    );
+
+  agent
+    .command('rm <id>')
+    .description('Delete any session except this one (refuses your own id)')
+    .option('--json', 'Machine-readable output')
+    .action((id: string, options: { json?: boolean }) => run(Boolean(options.json), (deps) => agentRm(deps, { id })));
+
+  return agent;
+}

src/cli.ts

@@ -15,15 +15,17 @@ import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { homedir } from 'node:os';
 import { dataPath } from './config/instance.js';
+import { readCodemanCredentials } from './codeman-credentials.js';
 import { casePath } from './config/cases-dir.js';
 import { assertValidBasePath } from './config/base-path.js';
 import { installAgentSkillInto, removeAgentSkillFrom, type AgentSkillApplyResult } from './hooks-config.js';
+import { registerAgentCommands } from './cli-agent.js';
 import { getSessionManager } from './session-manager.js';
 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';
@@ -42,32 +44,8 @@ function makeAttachmentMagicLink(filePath: string): string {
   return `codeman://attach?path=${encodeURIComponent(filePath)}`;
 }
 
-function readCodemanEnv(): Record<string, string> {
-  const envPath = dataPath('.env');
-  try {
-    const text = readFileSync(envPath, 'utf-8');
-    const result: Record<string, string> = {};
-    for (const rawLine of text.split(/\r?\n/)) {
-      const line = rawLine.trim();
-      if (!line || line.startsWith('#')) continue;
-      const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-      if (!match) continue;
-      let value = match[2].trim();
-      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-        value = value.slice(1, -1);
-      }
-      result[match[1]] = value;
-    }
-    return result;
-  } catch {
-    return {};
-  }
-}
-
 async function postAttachment(apiUrl: string, sessionId: string, filePath: string): Promise<boolean> {
-  const envFile = readCodemanEnv();
-  const username = process.env.CODEMAN_USERNAME || envFile.CODEMAN_USERNAME || 'admin';
-  const password = process.env.CODEMAN_PASSWORD || envFile.CODEMAN_PASSWORD;
+  const { username, password } = readCodemanCredentials();
   const url = new URL(`/api/sessions/${encodeURIComponent(sessionId)}/attachments`, apiUrl);
   const body = JSON.stringify({ path: filePath });
   const transport = url.protocol === 'https:' ? https : http;
@@ -111,7 +89,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);
     }
 
@@ -248,6 +230,10 @@ skillCmd
     }
   });
 
+// ============ Agent Commands (session-to-session, any CLI mode) ============
+
+registerAgentCommands(program);
+
 // ============ Session Commands ============
 
 const sessionCmd = program.command('session').alias('s').description('Manage Claude sessions');
@@ -637,9 +623,7 @@ function probeWebServerAt(base: string): Promise<WebServerProbe | null> {
   } catch {
     return Promise.resolve(null);
   }
-  const envFile = readCodemanEnv();
-  const username = process.env.CODEMAN_USERNAME || envFile.CODEMAN_USERNAME || 'admin';
-  const password = process.env.CODEMAN_PASSWORD || envFile.CODEMAN_PASSWORD;
+  const { username, password } = readCodemanCredentials();
   const transport = url.protocol === 'https:' ? https : http;
   const headers: Record<string, string> = { Accept: 'application/json' };
   if (password) {

src/codeman-credentials.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Credentials for a client of this Codeman instance's own API.
+ *
+ * Env first, the data dir's `.env` as the fallback — the hand-authored file
+ * `codeman attach`, `codeman tui` and `codeman agent` all read. One reader, so the
+ * three clients cannot drift on quoting, comments or the default username.
+ *
+ * @module codeman-credentials
+ */
+import { readFileSync } from 'node:fs';
+import { dataPath } from './config/instance.js';
+
+export interface CodemanCredentials {
+  username: string;
+  /** Absent when no password is configured (or only the server's environment has it). */
+  password?: string;
+}
+
+/**
+ * Parse a `KEY=value` env file: blank lines and `#` comments skipped, an `export `
+ * prefix tolerated (the file is hand-authored, often sourced by a shell too), one
+ * layer of matching quotes stripped, anything that is not an assignment ignored.
+ */
+export function parseEnvFile(text: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) continue;
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    result[match[1]] = value;
+  }
+  return result;
+}
+
+/** The data dir's `.env`, parsed. Absent or unreadable means `{}`. */
+export function readCodemanEnvFile(envFilePath: string = dataPath('.env')): Record<string, string> {
+  try {
+    return parseEnvFile(readFileSync(envFilePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The lookup order every client uses, per field: the environment, then the `.env`
+ * file, then (username only) `admin`. Pure, so a caller with its own environment
+ * object (`codeman agent`'s guard takes one for testability) gets the same answer.
+ */
+export function credentialsFrom(env: NodeJS.ProcessEnv, fileEnv: Record<string, string>): CodemanCredentials {
+  const username = env.CODEMAN_USERNAME || fileEnv.CODEMAN_USERNAME || 'admin';
+  const password = env.CODEMAN_PASSWORD || fileEnv.CODEMAN_PASSWORD;
+  return password ? { username, password } : { username };
+}
+
+/**
+ * Credentials for the API. No password means no auth is configured, or the user has
+ * it only in the server's environment, in which case the API answers 401.
+ */
+export function readCodemanCredentials(
+  envFilePath: string = dataPath('.env'),
+  env: NodeJS.ProcessEnv = process.env
+): CodemanCredentials {
+  return credentialsFrom(env, readCodemanEnvFile(envFilePath));
+}
+
+/** `Authorization` header value, or undefined when there is no password to send. */
+export function basicAuthHeader(credentials: CodemanCredentials): string | undefined {
+  if (!credentials.password) return undefined;
+  return `Basic ${Buffer.from(`${credentials.username}:${credentials.password}`).toString('base64')}`;
+}

src/config/cli-registry/schema.ts

@@ -15,7 +15,7 @@
 import { z } from 'zod';
 import { compileVersionRegex, countCaptureGroups, TOKEN_PATTERNS } from './patterns.js';
 import { isKnownLauncherProfile, isKnownSetenvProfile } from './profiles.js';
-import type { McpConfigFormat, ModelConfigResolverName } 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() })
@@ -320,6 +320,8 @@ const capabilitiesSchema = z
     // A declared width cannot do either. Absent means no strip, so a CLI whose
     // transcript layout nobody has measured is never touched.
     transcriptGutter: z.number().int().min(1).max(8).optional(),
+    // Literal text matched by a `wait-output` long-poll, never compiled as a regex.
+    composerReadyMark: z.string().min(1).max(64).optional(),
     workDetect: z
       .object({
         promptGlyph: z.string().min(1).max(8),
@@ -385,8 +387,10 @@ const capabilitiesSchema = z
           )
           .optional(),
         // Bounded hard, like watchingLines: every row it adds is one more row the agent
-        // itself may be able to write.
-        screenLines: z.number().int().min(1).max(4).optional(),
+        // 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.
@@ -407,6 +411,17 @@ const capabilitiesSchema = z
         '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
@@ -436,6 +451,7 @@ const capabilitiesSchema = z
           'codex-toml',
           'opencode-json',
           'antigravity-json',
+          'copilot-json',
         ] as const satisfies readonly McpConfigFormat[]),
         // The env var the CLI reads to move the file, and the path under it (same no-traversal
         // rule: sync writes there too). Resolved from the server env at call time, never here.
@@ -625,6 +641,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

@@ -218,6 +218,9 @@ const CLAUDE: CliEntry = {
     // in them, so a copy can drop two and paste flush. Claude and codex are the only
     // entries that declare this, because theirs are the only gutters that have been measured.
     transcriptGutter: 2,
+    // The composer's own hint text (`⏵⏵ … (shift+tab to cycle)`), not `❯`, which the
+    // trust dialog's selected row also carries. Measured by the agent skill's spawn_worker.
+    composerReadyMark: 'shift+tab',
     // The historical hard-coded pair, now stated as data. `workingLine` matches both the
     // `✻ Actualizing… (39s · ↓ 2.0k tokens)` status line and the bare `esc to interrupt`
     // footer, because tmux repaints partially and only one of the two may land in a chunk.
@@ -491,8 +494,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 +638,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,18 +665,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 is the pane's LAST row, 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.
+    // 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`^ {2}([A-Za-z0-9][\w.:/@+-]{0,79}) (?:none|minimal|low|medium|high|xhigh|max|default) · `,
+      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,
@@ -754,6 +818,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.
@@ -935,6 +1021,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.
@@ -1052,8 +1169,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.
@@ -1227,6 +1345,8 @@ const DEEPSEEK: CliEntry = {
     // supervisor and Codeman is that supervisor. 'supervised' rather than 'always' because
     // the session can disarm the bridge, and docker/remote cannot reach it at all.
     hooks: 'supervised',
+    // dsh's composer glyph, drawn once the harness TUI can take a prompt.
+    composerReadyMark: '❯',
     transcript: 'deepseek-zstd',
     altScreen: 'strip-mux-only',
     echo: { policy: 'buffer', anchor: { kind: 'cursor' } },
@@ -1386,13 +1506,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

@@ -96,8 +96,22 @@ 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';
+export type McpConfigFormat =
+  | 'claude-json'
+  | 'gemini-json'
+  | 'codex-toml'
+  | 'opencode-json'
+  | 'antigravity-json'
+  | 'copilot-json';
 
 export interface CliLaunch {
   params: Record<string, ParamSpec>;
@@ -365,8 +379,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`.
      */
@@ -408,6 +422,17 @@ export interface CliCapabilities {
    * Absent means no strip at all, the same fail-safe direction `workDetect` takes.
    */
   transcriptGutter?: number;
+  /**
+   * Literal text the TUI draws once its composer can take a prompt — what `codeman agent
+   * spawn` waits for (a `wait-output` match) before it calls a worker ready.
+   *
+   * Deliberately NOT `workDetect.promptGlyph`: claude's `❯` also marks the selected row
+   * of its workspace-trust dialog, which is exactly the screen a readiness wait must not
+   * mistake for a composer, so claude declares its composer's own hint text instead.
+   * Absent means no readiness wait: a spawn returns as soon as the session exists, and
+   * the caller synchronizes on `wait-output` markers.
+   */
+  composerReadyMark?: string;
   /** No direct-PTY fallback: the CLI must run inside tmux (secrets ride tmux setenv). */
   requiresMux: boolean;
   /**
@@ -439,11 +464,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. */
@@ -500,6 +554,20 @@ export interface CliCapabilities {
     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/git-clone.ts

@@ -495,6 +495,10 @@ export function gitNonInteractiveEnv(base: NodeJS.ProcessEnv = process.env): Nod
     SSH_ASKPASS_REQUIRE: 'never',
     DISPLAY: '',
     GCM_INTERACTIVE: 'never',
+    // classifyGitFailure() matches git's ENGLISH stderr; a German or French locale would
+    // turn a missing ref into a generic FAILED (422 instead of 400).
+    LC_ALL: 'C',
+    LANG: 'C',
     GIT_SSH_COMMAND:
       base.GIT_SSH_COMMAND || 'ssh -oBatchMode=yes -oStrictHostKeyChecking=accept-new -oConnectTimeout=10',
   };

src/git-workspace-status.ts

@@ -15,8 +15,8 @@
  *     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 (`MAX_REPOS` of them, skipping dot-folders, `node_modules` and the like, never following
- *     symlinks), each reported separately;
+ *     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.
  *
@@ -52,7 +52,10 @@ import { gitNonInteractiveEnv, redactGitCredentials } from './git-clone.js';
 
 const execFileAsync = promisify(execFile);
 
-const GIT_TIMEOUT_MS = 10_000;
+/** 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. */
@@ -258,9 +261,9 @@ export function parseCommitLog(text: string): GitCommitEntry[] {
 // ---------------------------------------------------------------------------
 
 /** 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[]) => Promise<string>;
+export type GitRunner = (cwd: string, args: string[], opts?: { timeoutMs?: number }) => Promise<string>;
 
-export const runGit: GitRunner = async (cwd, args) => {
+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
@@ -269,7 +272,7 @@ export const runGit: GitRunner = async (cwd, args) => {
     ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'log.showSignature=false', ...args],
     {
       cwd,
-      timeout: GIT_TIMEOUT_MS,
+      timeout: opts?.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
       maxBuffer: MAX_OUTPUT_BYTES,
       env: { ...gitNonInteractiveEnv(), LC_ALL: 'C', LANG: 'C', GIT_OPTIONAL_LOCKS: '0' },
     }
@@ -288,17 +291,14 @@ function describeFailure(err: unknown): { notARepo: boolean; message: string } {
   return { notARepo: false, message: redactGitCredentials(text).slice(0, 300) };
 }
 
-async function collect(cwd: string, git: GitRunner): Promise<GitWorkspaceStatus> {
+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',
-    ]);
+    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 });
@@ -307,7 +307,7 @@ async function collect(cwd: string, git: GitRunner): Promise<GitWorkspaceStatus>
 
   const safe = async (args: string[]): Promise<string> => {
     try {
-      return await git(cwd, args);
+      return await git(cwd, args, { timeoutMs });
     } catch {
       return '';
     }
@@ -415,10 +415,12 @@ async function singleFlight<T>(
  */
 export async function getGitWorkspaceStatus(
   cwd: string,
-  opts: { git?: GitRunner; now?: () => number; fresh?: boolean } = {}
+  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));
+  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 };
@@ -427,12 +429,12 @@ 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 }
+  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'])).trim();
+      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);
@@ -451,6 +453,16 @@ const DISCOVERY_MAX_DEPTH = 2;
 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. */
@@ -472,8 +484,10 @@ export interface GitWorkspaceOverview {
   reason?: 'remote' | 'docker';
   error?: string;
   repos: GitRepoEntry[];
-  /** More than `MAX_REPOS` repositories were found; only the first are reported. */
+  /** 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;
 }
 
@@ -553,7 +567,8 @@ async function readDirBounded(dir: string): Promise<import('node:fs').Dirent[] |
 /** Repositories up to `DISCOVERY_MAX_DEPTH` levels below `cwd`, nearest and alphabetical first. Never follows symlinks. */
 export async function discoverChildRepos(
   cwd: string,
-  excludeRealRoots: string[] = []
+  excludeRealRoots: string[] = [],
+  maxRepos: number = MAX_REPOS
 ): Promise<{ dirs: string[]; truncated: boolean }> {
   const found: string[] = [];
   let level = [cwd];
@@ -576,7 +591,7 @@ export async function discoverChildRepos(
     }
     level = next;
   }
-  return { dirs: found.slice(0, MAX_REPOS), truncated: found.length > MAX_REPOS };
+  return { dirs: found.slice(0, maxRepos), truncated: found.length > maxRepos };
 }
 
 const discoveryCache = new Map<string, { at: number; value: { dirs: string[]; truncated: boolean } }>();
@@ -602,13 +617,28 @@ export interface GitOverviewOptions {
   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 };
+  | { kind: 'children'; dirs: string[]; truncated: boolean; limit: number };
 
 /**
  * WHICH repositories belong to the workspace (the module header has the rules), without a full
@@ -617,6 +647,7 @@ type WorkspaceRepos =
  */
 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.
@@ -624,7 +655,7 @@ async function resolveWorkspaceRepos(cwd: string, opts: GitOverviewOptions): Pro
   // 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);
+  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' };
@@ -633,18 +664,20 @@ async function resolveWorkspaceRepos(cwd: string, opts: GitOverviewOptions): Pro
   }
 
   // Not inside a repository of this workspace: look below for projects.
-  const hit = discoveryCache.get(cwd);
+  // 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);
-    discoveryCache.set(cwd, { at: now(), value: found });
+    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 };
+  return { kind: 'children', dirs, truncated: found.truncated, limit: maxRepos };
 }
 
 /**
@@ -659,7 +692,7 @@ export async function getGitWorkspaceOverview(
   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);
+    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;
@@ -671,14 +704,21 @@ export async function getGitWorkspaceOverview(
     };
   }
 
-  const statuses = await mapLimited(where.dirs, STATUS_CONCURRENCY, (dir) => getGitWorkspaceStatus(dir, opts));
+  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];
-    if (status.state === 'ok') repos.push({ name: basename(dir), path: relative(cwd, dir), status });
+    // 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, checkedAt: Date.now() };
+  return { state: 'ok', repos, reposTruncated: where.truncated, repoLimit: where.limit, checkedAt: Date.now() };
 }
 
 /**
@@ -726,7 +766,7 @@ export function isSafeRepoRelativePath(p: string): boolean {
 export async function getGitFileDiff(
   repoRoot: string,
   file: { path: string; origPath?: string; kind: GitFileKind },
-  opts: { git?: GitRunner } = {}
+  opts: { git?: GitRunner; timeoutMs?: number } = {}
 ): Promise<GitFileDiff> {
   if (!isSafeRepoRelativePath(file.path) || (file.origPath && !isSafeRepoRelativePath(file.origPath))) {
     throw new Error('Invalid path');
@@ -742,7 +782,7 @@ export async function getGitFileDiff(
   let out: string;
   let cutShort = false;
   try {
-    out = await git(repoRoot, args);
+    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.

src/image-watcher.ts

@@ -14,6 +14,7 @@ import { basename, extname, relative } from 'node:path';
 import { statSync } from 'node:fs';
 import type { AttachmentDetectedEvent, AttachmentDetectedType, ImageDetectedEvent } from './types.js';
 import { KeyedDebouncer } from './utils/index.js';
+import { UPLOAD_DIR_NAMES } from './web/paste-image-gc.js';
 
 // ========== Types ==========
 
@@ -157,12 +158,15 @@ export class ImageWatcher extends EventEmitter {
         // Watch all subdirectories (images may be saved in src/, assets/, etc.)
         // Ignore common heavy directories for performance
         ignored: (path: string) => {
-          // Skip node_modules, .git, and other heavy directories
+          // Skip node_modules, .git, and other heavy directories, and Codeman's
+          // own upload folders: a pdf the user handed to the agent is not a file
+          // the agent produced.
           if (
             path.includes('/node_modules/') ||
             path.includes('/.git/') ||
             path.includes('/dist/') ||
-            path.includes('/.next/')
+            path.includes('/.next/') ||
+            UPLOAD_DIR_NAMES.some((name) => path.includes(`/${name}/`))
           ) {
             return true;
           }

src/mcp-sync-targets.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview MCP sync targets that are not Codeman run modes.
+ *
+ * `mcpSyncTargets()` (routes/mcp-sync-routes.ts) takes the registry's enabled CLIs that declare an
+ * `mcpConfig`. Some tools read an MCP server list worth keeping in step with the others but are not
+ * something Codeman launches, so they have no registry entry (and no id to branch on): GitHub
+ * Copilot CLI is the first. They are plain data here, take part only when installed or when their
+ * config file already exists (an absent tool is reported `absent`, never created), and sort after
+ * the registry CLIs, so when two definitions of a name differ the registry CLI's is the one copied.
+ *
+ * @module mcp-sync-targets
+ */
+
+import { accessSync, constants as fsConstants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import type { McpConfigFormat } from './config/cli-registry/types.js';
+import type { McpSyncTarget } from './mcp-sync.js';
+
+export interface McpSyncOnlyTool {
+  id: string;
+  label: string;
+  /** Home-relative default location of the MCP config file. */
+  path: string;
+  format: McpConfigFormat;
+  /** The env var the tool reads to move its home, and the file under it. */
+  relocation?: { envVar: string; path: string };
+  /** The executable whose presence on this machine means the tool is installed. */
+  binary: string;
+}
+
+export const MCP_SYNC_ONLY_TOOLS: readonly McpSyncOnlyTool[] = [
+  {
+    id: 'copilot',
+    label: 'GitHub Copilot CLI',
+    path: '.copilot/mcp-config.json',
+    format: 'copilot-json',
+    // COPILOT_HOME replaces ~/.copilot (checked: `COPILOT_HOME=<dir> copilot mcp list` reads <dir>).
+    relocation: { envVar: 'COPILOT_HOME', path: 'mcp-config.json' },
+    binary: 'copilot',
+  },
+];
+
+/** `name` is an executable file in the server's PATH, `~/.local/bin` or `/usr/local/bin`. */
+export function binaryOnPath(name: string, env: Record<string, string | undefined> = process.env): boolean {
+  const dirs = [
+    ...(env.PATH ?? '').split(delimiter).filter(Boolean),
+    join(homedir(), '.local', 'bin'),
+    '/usr/local/bin',
+  ];
+  return dirs.some((dir) => {
+    try {
+      accessSync(join(dir, name), fsConstants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** The sync-only tools as sync targets, skipping any id the registry already provides. */
+export function mcpSyncOnlyTargets(
+  taken: ReadonlySet<string>,
+  isInstalled: (binary: string) => boolean = binaryOnPath
+): McpSyncTarget[] {
+  return MCP_SYNC_ONLY_TOOLS.filter((t) => !taken.has(t.id)).map((t) => ({
+    id: t.id,
+    label: t.label,
+    path: t.path,
+    format: t.format,
+    ...(t.relocation ? { relocation: t.relocation } : {}),
+    installed: isInstalled(t.binary),
+  }));
+}

src/mcp-sync.ts

@@ -12,7 +12,8 @@
  *     does not understand) is never rewritten and nothing is ever removed. Same name with a
  *     different definition is reported as a conflict and left alone.
  *   - A server the user has switched off in its own CLI (codex `enabled = false`, opencode
- *     `enabled: false`, antigravity `disabled: true`) is not propagated: copying it would
+ *     `enabled: false`, antigravity `disabled: true`, Copilot's `disabledMcpServers` in its
+ *     `settings.json`) is not propagated: copying it would
  *     switch it on in every other CLI.
  *   - A file that does not parse (e.g. opencode JSONC with comments, a TOML file with a
  *     duplicate table) is never written, and a write is only made after the NEW text has been
@@ -284,6 +285,29 @@ function toOpencode(s: McpServer): Record<string, unknown> {
   return { type: 'remote', url: s.url, ...(s.headers ? { headers: s.headers } : {}), enabled: true };
 }
 
+/**
+ * GitHub Copilot CLI (`copilot mcp add`): `~/.copilot/mcp-config.json`, `mcpServers`. A stdio server is
+ * `type: "local"`; every entry carries `tools` (`["*"]` = all). Whether a server is switched off is NOT in
+ * this file: `copilot mcp disable` records the name in `settings.json` beside it (`disabledMcpServers`).
+ */
+function fromCopilot(raw: unknown): McpServer | null {
+  if (!isRecord(raw)) return null;
+  if ((raw.type === 'http' || raw.type === 'sse') && typeof raw.url === 'string') {
+    return clean({ transport: raw.type, url: raw.url, headers: strMap(raw.headers) });
+  }
+  if ((raw.type === undefined || raw.type === 'local' || raw.type === 'stdio') && typeof raw.command === 'string') {
+    return clean({ transport: 'stdio', command: raw.command, args: strArr(raw.args), env: strMap(raw.env) });
+  }
+  return null;
+}
+
+function toCopilot(s: McpServer): Record<string, unknown> {
+  if (s.transport === 'stdio') {
+    return { tools: ['*'], type: 'local', command: s.command, args: s.args ?? [], ...(s.env ? { env: s.env } : {}) };
+  }
+  return { tools: ['*'], type: s.transport, url: s.url, ...(s.headers ? { headers: s.headers } : {}) };
+}
+
 interface JsonDialect {
   /** Key holding the server table. */
   key: string;
@@ -291,12 +315,23 @@ interface JsonDialect {
   to(s: McpServer): Record<string, unknown> | null;
   /** Top-level keys to seed when creating the file from nothing. */
   seed?: Record<string, unknown>;
+  /**
+   * A file beside the config that lists the names of servers the user switched off (the switch is
+   * not stored on the server entry). Read, never written.
+   */
+  disabledIn?: { file: string; key: string };
 }
 
 const JSON_DIALECTS: Record<Exclude<McpFormat, 'codex-toml'>, JsonDialect> = {
   'claude-json': { key: 'mcpServers', from: fromClaude, to: toClaude },
   'gemini-json': { key: 'mcpServers', from: fromGemini, to: toGemini },
   'antigravity-json': { key: 'mcpServers', from: fromAntigravity, to: toAntigravity },
+  'copilot-json': {
+    key: 'mcpServers',
+    from: fromCopilot,
+    to: toCopilot,
+    disabledIn: { file: 'settings.json', key: 'disabledMcpServers' },
+  },
   'opencode-json': {
     key: 'mcp',
     from: fromOpencode,
@@ -558,6 +593,32 @@ function resolveFile(
   return { file: join(dir, rel.path) };
 }
 
+/**
+ * Mark the servers a CLI keeps switched off in a companion file (`JsonDialect.disabledIn`) as
+ * disabled, so they are not copied. If that file cannot be read as intended the target is
+ * reported unreadable rather than guessing: a guess could switch a server on everywhere.
+ */
+async function applyCompanionDisabled(format: McpFormat, file: string, servers: McpServerMap): Promise<void> {
+  if (format === 'codex-toml') return;
+  const companion = JSON_DIALECTS[format].disabledIn;
+  if (!companion) return;
+  const text = await readText(join(dirname(file), companion.file));
+  if (text === null || !text.trim()) return;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    throw new McpConfigError(
+      `${companion.file} next to the config is not valid JSON, so which servers are switched off is unknown`
+    );
+  }
+  const list = isRecord(doc) ? doc[companion.key] : undefined;
+  if (list === undefined) return;
+  const names = strArr(list);
+  if (!names) throw new McpConfigError(`"${companion.key}" in ${companion.file} is not a list of names`);
+  for (const n of names) if (n in servers) servers[n] = { ...servers[n], disabled: true };
+}
+
 let applying = false;
 
 /**
@@ -611,6 +672,7 @@ async function run(targets: McpSyncTarget[], opts: McpSyncOptions, unsupported:
         continue;
       }
       const parsed = parseConfig(s.t.format, await readText(s.file));
+      await applyCompanionDisabled(s.t.format, s.file, parsed.servers);
       s.servers = parsed.servers;
       s.names = parsed.names;
       s.res.servers = [...parsed.names];

src/session.ts

@@ -106,6 +106,7 @@ import {
   getClaudeBinaryPath,
   spawnPtyWithHelperRepair,
   resolveLocalShell,
+  waitForProcessesExit,
 } from './utils/index.js';
 import {
   MAX_TERMINAL_BUFFER_SIZE,
@@ -179,7 +180,10 @@ const WIRE_ACTIVITY_SETTLE_MS = 15_000;
 
 // Note: Auto-compact/clear timing constants moved to session-auto-ops.ts
 
-/** Graceful shutdown delay when stopping session (100ms) */
+/**
+ * Longest the PTY process gets to exit on SIGTERM before SIGKILL when stopping a
+ * session. A deadline, not a sleep: stop() moves on as soon as it has exited.
+ */
 const GRACEFUL_SHUTDOWN_DELAY_MS = 100;
 
 // Conversations kept in a pane's chain. A pane that /clears repeatedly would
@@ -277,10 +281,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
@@ -300,8 +305,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
@@ -326,7 +333,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)
@@ -1355,7 +1386,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;
@@ -2529,14 +2560,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
@@ -2555,14 +2593,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
+        data = data.replace(/\x1b\[3J/g, '');
+      }
+      if (fullStrip || mouseStrip) {
+        data = data.replace(
           // eslint-disable-next-line no-control-regex
-          .replace(/\x1b\[3J/g, '')
-          // 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 '';
-          });
+          }
+        );
       }
     }
 
@@ -2783,19 +2825,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(() => {
@@ -2827,6 +2864,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);
@@ -3433,14 +3472,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) {
-      this._isWorking = false;
-      this._status = 'idle';
-      this._lastPromptTime = Date.now();
-      if (wasWorking) this._maybeCaptureOmpSessionId();
-      this.emit('idle');
-    }
+    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();
+    // 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');
   }
 
   /**
@@ -4428,7 +4527,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
@@ -4706,8 +4805,10 @@ export class Session extends EventEmitter {
           console.warn('[Session] Failed to send SIGTERM to PTY process (may already be dead):', err);
         }
 
-        // Give it a moment to terminate gracefully
-        await new Promise((resolve) => setTimeout(resolve, GRACEFUL_SHUTDOWN_DELAY_MS));
+        // Give it a moment to terminate gracefully. For a tmux-backed session this
+        // is the attach client, gone within a few ms of SIGTERM, and this used to be
+        // a fixed 100ms sleep on every close.
+        if (pid) await waitForProcessesExit([pid], { timeoutMs: GRACEFUL_SHUTDOWN_DELAY_MS });
 
         // Force kill with SIGKILL if still alive
         try {

src/subagent-watcher.ts

@@ -761,13 +761,35 @@ export class SubagentWatcher extends EventEmitter {
    * by workingDir alone would kill subagents belonging to OTHER sessions.
    */
   async killSubagentsForSession(workingDir: string, sessionId?: string): Promise<void> {
-    const subagents = this.getSubagentsForSession(workingDir);
-    for (const agent of subagents) {
-      if (agent.status === 'active' || agent.status === 'idle') {
-        // Only kill subagents belonging to this specific session
-        if (sessionId && agent.sessionId !== sessionId) continue;
-        await this.killSubagent(agent.agentId);
+    const targets = this.getSubagentsForSession(workingDir).filter(
+      // Only kill subagents belonging to this specific session
+      (agent) => (agent.status === 'active' || agent.status === 'idle') && (!sessionId || agent.sessionId === sessionId)
+    );
+    if (targets.length === 0) return;
+
+    // ONE process scan for the lot. This used to call killSubagent() per agent, and
+    // each call ran its own `pgrep -f claude` plus a /proc read per match (~85ms on a
+    // box with ~100 matching processes), so closing a session right after a workflow
+    // paid that once per recently active subagent. The match rules are
+    // findSubagentProcess()'s: getClaudePids() skips CODEMAN_MUX=1 processes too.
+    const pidMap = await this.getClaudePids();
+    const signalled = new Set<number>();
+    for (const agent of targets) {
+      // The liveness checker may have completed it while the scan ran.
+      if (agent.status !== 'active' && agent.status !== 'idle') continue;
+      for (const [pid, procInfo] of pidMap) {
+        if (signalled.has(pid)) continue;
+        if (procInfo.environ.includes(agent.sessionId) || procInfo.cmdline.includes(agent.sessionId)) {
+          signalled.add(pid);
+          try {
+            process.kill(pid, 'SIGTERM');
+          } catch {
+            // Process may have already exited
+          }
+          break; // one process per agent, as killSubagent() does
+        }
       }
+      this.markSubagentAsCompleted(agent);
     }
   }
 

src/templates/case-template.md

@@ -56,3 +56,5 @@ This session is managed by Codeman and runs inside tmux (`CODEMAN_MUX=1` confirm
 - NEVER kill your own session: no `tmux kill-session`, `pkill tmux`, or `pkill claude`.
 - The session persists across disconnects — your work is safe.
 - Hooks may auto-format or validate after writes; unexpected tool behavior usually means a hook ran. Keep working.
+- After creating a file, write out its full absolute path in your final reply, e.g. `/home/me/project/docs/report.md`. Codeman makes absolute paths in the terminal clickable and opens them in its file viewer; a relative path (`docs/report.md`), a `~/` path or a markdown link (`[report](...)`) cannot be clicked.
+- If the `codeman` skill is available, use it to start other Codeman sessions as workers, send them prompts, wait for them to finish, read their output and clean them up. When asked to parallelize work and the skill is missing, tell the user they can install it with `codeman skill install`.

src/tmux-manager.ts

@@ -94,7 +94,13 @@ import {
   type DockerMount,
   type DockerSeedCopy,
 } from './docker-hosts.js';
-import { wrapWithNice, SAFE_PATH_PATTERN, resolveLocalShell, loginShellArgs } from './utils/index.js';
+import {
+  wrapWithNice,
+  SAFE_PATH_PATTERN,
+  resolveLocalShell,
+  loginShellArgs,
+  waitForProcessesExit,
+} from './utils/index.js';
 import type {
   TerminalMultiplexer,
   MuxSession,
@@ -144,12 +150,18 @@ const TMUX_CREATION_WAIT_MS = 100;
 const GET_PID_MAX_RETRIES = 5;
 const GET_PID_RETRY_MS = 200;
 
-/** Delay after tmux kill command (200ms) */
+/**
+ * How long killSession gives a pane's children to exit on SIGTERM before it
+ * re-scans and SIGKILLs. A deadline, not a sleep (see utils/process-exit-wait.ts).
+ */
 const TMUX_KILL_WAIT_MS = 200;
 
-/** Delay for graceful shutdown (100ms) */
+/** How long the pane's process group gets to exit on SIGTERM before SIGKILL. Also a deadline. */
 const GRACEFUL_SHUTDOWN_WAIT_MS = 100;
 
+/** How long killSession waits for every process it signalled to be gone before it warns. */
+const KILL_VERIFY_TIMEOUT_MS = 2000;
+
 /** Default stats collection interval (2 seconds) */
 const DEFAULT_STATS_INTERVAL_MS = 2000;
 
@@ -2350,6 +2362,28 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
   }
 
+  /**
+   * {@link getPanePid} without blocking the event loop, for the kill path: a close
+   * must not stall every other session's I/O while tmux answers.
+   */
+  private async getPanePidAsync(muxName: string): Promise<number | null> {
+    if (IS_TEST_MODE) return 99999;
+    if (!isValidMuxName(muxName)) {
+      console.error('[TmuxManager] Invalid session name in getPanePidAsync:', muxName);
+      return null;
+    }
+    try {
+      const { stdout } = await execAsync(`${this.tmux()} display-message -t "${muxName}" -p '#{pane_pid}'`, {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+      });
+      const pid = parseInt(stdout.trim(), 10);
+      return Number.isNaN(pid) ? null : pid;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Check if a tmux session exists.
    */
@@ -2604,7 +2638,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     });
   }
 
-  // Check if a process is still alive
+  // Check if a process is still alive. Signal decisions only: an unreaped zombie
+  // counts here, so its process group still gets the SIGKILL below. The WAITS use
+  // waitForProcessesExit(), which counts a zombie as exited.
   private isProcessAlive(pid: number): boolean {
     try {
       process.kill(pid, 0);
@@ -2614,20 +2650,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
   }
 
-  // Verify all PIDs are dead, with retry
+  // Verify all PIDs are dead, returning as soon as they are
   private async verifyProcessesDead(pids: number[], maxWaitMs: number = 1000): Promise<boolean> {
-    const startTime = Date.now();
-    const checkInterval = 100;
-
-    while (Date.now() - startTime < maxWaitMs) {
-      const aliveCount = pids.filter((pid) => this.isProcessAlive(pid)).length;
-      if (aliveCount === 0) {
-        return true;
-      }
-      await new Promise((resolve) => setTimeout(resolve, checkInterval));
-    }
-
-    const stillAlive = pids.filter((pid) => this.isProcessAlive(pid));
+    const stillAlive = await waitForProcessesExit(pids, { timeoutMs: maxWaitMs });
     if (stillAlive.length > 0) {
       console.warn(`[TmuxManager] ${stillAlive.length} processes still alive after kill: ${stillAlive.join(', ')}`);
     }
@@ -2685,7 +2710,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       if (isValidMuxName(session.muxName)) {
         try {
           // Local socket only — detaches the remote session by killing the local ssh pane.
-          execSync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
+          await execAsync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
             timeout: EXEC_TIMEOUT_MS,
           });
         } catch {
@@ -2702,7 +2727,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     // Get current PID (may have changed)
-    const currentPid = this.getPanePid(session.muxName) || session.pid;
+    const currentPid = (await this.getPanePidAsync(session.muxName)) || session.pid;
 
     console.log(`[TmuxManager] Killing session ${session.muxName} (PID ${currentPid})`);
 
@@ -2724,7 +2749,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         }
       }
 
-      await new Promise((resolve) => setTimeout(resolve, TMUX_KILL_WAIT_MS));
+      // Most children are gone within a few ms; the re-scan below still runs, to
+      // catch anything spawned since the first one.
+      await waitForProcessesExit(childPids, { timeoutMs: TMUX_KILL_WAIT_MS });
 
       childPids = await this.getChildPidsFresh(currentPid);
       for (const childPid of childPids) {
@@ -2742,7 +2769,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     if (this.isProcessAlive(currentPid)) {
       try {
         process.kill(-currentPid, 'SIGTERM');
-        await new Promise((resolve) => setTimeout(resolve, GRACEFUL_SHUTDOWN_WAIT_MS));
+        await waitForProcessesExit([currentPid], { timeoutMs: GRACEFUL_SHUTDOWN_WAIT_MS });
         if (this.isProcessAlive(currentPid)) {
           process.kill(-currentPid, 'SIGKILL');
         }
@@ -2751,10 +2778,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       }
     }
 
-    // Strategy 3: Kill tmux session by name (guard the name before it reaches the shell)
+    // Strategy 3: Kill tmux session by name (guard the name before it reaches the shell).
+    // Async: tmux takes tens of ms to tear a session down, and execSync held the
+    // whole server for that long on every close.
     if (isValidMuxName(session.muxName)) {
       try {
-        execSync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
+        await execAsync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
           timeout: EXEC_TIMEOUT_MS,
         });
       } catch {
@@ -2798,7 +2827,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     // Verify all processes are dead
-    const allDead = await this.verifyProcessesDead(allPids, 2000);
+    const allDead = await this.verifyProcessesDead(allPids, KILL_VERIFY_TIMEOUT_MS);
     if (!allDead) {
       console.error(`[TmuxManager] Warning: Some processes may still be alive for session ${session.muxName}`);
     }

src/tui/tui-client.ts

@@ -48,6 +48,12 @@ import https from 'node:https';
 import { hostname as osHostname } from 'node:os';
 import { promisify } from 'node:util';
 import { CODEMAN_INSTANCE, dataPath, resolveTmuxSocketName } from '../config/instance.js';
+import {
+  basicAuthHeader,
+  parseEnvFile,
+  readCodemanCredentials,
+  type CodemanCredentials,
+} from '../codeman-credentials.js';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
 import { probeServer } from '../daemon-control.js';
 import { getErrorMessage } from '../types/api.js';
@@ -281,53 +287,9 @@ export function tuiServerCandidates(env: { apiUrl?: string; port?: string | numb
   return [`https://127.0.0.1:${port}`, `http://127.0.0.1:${port}`];
 }
 
-/**
- * Parse a `KEY=value` env file. Mirrors `readCodemanEnv()` in `cli.ts`: blank
- * lines and `#` comments skipped, one layer of matching quotes stripped.
- */
-export function parseEnvFile(text: string): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith('#')) continue;
-    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-    if (!match) continue;
-    let value = match[2].trim();
-    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    result[match[1]] = value;
-  }
-  return result;
-}
-
-export interface TuiCredentials {
-  username: string;
-  password?: string;
-}
-
-/**
- * Credentials for the API, env first and the data dir's `.env` as the fallback,
- * exactly like the `codeman attach` path. No password means no auth is
- * configured (or the user has it only in the server's environment, in which
- * case the API answers 401 and `connect()` reports `authRequired`).
- */
-export function readCodemanCredentials(envFilePath = dataPath('.env')): TuiCredentials {
-  let fileEnv: Record<string, string> = {};
-  try {
-    fileEnv = parseEnvFile(readFileSync(envFilePath, 'utf-8'));
-  } catch {
-    /* absent or unreadable: env-only */
-  }
-  const username = process.env.CODEMAN_USERNAME || fileEnv.CODEMAN_USERNAME || 'admin';
-  const password = process.env.CODEMAN_PASSWORD || fileEnv.CODEMAN_PASSWORD;
-  return password ? { username, password } : { username };
-}
-
-export function basicAuthHeader(credentials: TuiCredentials): string | undefined {
-  if (!credentials.password) return undefined;
-  return `Basic ${Buffer.from(`${credentials.username}:${credentials.password}`).toString('base64')}`;
-}
+// One credential reader for every client of the API (attach, tui, agent).
+export { parseEnvFile, readCodemanCredentials, basicAuthHeader };
+export type TuiCredentials = CodemanCredentials;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Degraded mode

src/types/session.ts

@@ -812,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.
    */

src/types/tools.ts

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

src/utils/index.ts

@@ -12,6 +12,7 @@ export { Debouncer, KeyedDebouncer } from './debouncer.js';
 export { startEventLoopMonitor } from './event-loop-monitor.js';
 export type { EventLoopMonitorHandle } from './event-loop-monitor.js';
 export { StaleExpirationMap } from './stale-expiration-map.js';
+export { isProcessRunning, waitForProcessesExit, PROCESS_EXIT_POLL_MS } from './process-exit-wait.js';
 export {
   ANSI_ESCAPE_PATTERN_FULL,
   ANSI_ESCAPE_PATTERN_SIMPLE,

src/utils/process-exit-wait.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Wait for processes to exit, and return as soon as they have.
+ *
+ * The session kill path used to sleep a FIXED interval after each signal (100 ms
+ * for the PTY client, 200 ms for the pane's children, 100 ms for the process
+ * group) and then verified in 100 ms steps. A process that was gone after 3 ms
+ * still cost the whole interval, so closing a tab spent most of its ~0.5 s in
+ * timers. This keeps every deadline the kill path had; it only stops waiting
+ * once there is nothing left to wait for.
+ *
+ * A zombie counts as exited. It holds nothing but its pid until the parent reaps
+ * it, and on the kill path that parent is the tmux server or the service
+ * manager, which is no reason to hold up a close. `kill(pid, 0)` cannot tell a
+ * zombie from a running process, so on Linux the state letter in
+ * `/proc/<pid>/stat` decides; without procfs `kill(pid, 0)` is the answer.
+ *
+ * @module utils/process-exit-wait
+ */
+
+import { readFileSync } from 'node:fs';
+
+/** Poll step while waiting: an exit is noticed within about one frame. */
+export const PROCESS_EXIT_POLL_MS = 10;
+
+/**
+ * True while `pid` names a process that has not exited. A pid we may not signal
+ * reads as not running, which is what the kill path's own check always did:
+ * there is nothing it could do about such a process anyway.
+ */
+export function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  if (process.platform !== 'linux') return true;
+  let stat: string;
+  try {
+    stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+  } catch (err) {
+    // Gone between the two reads. Any other failure: trust kill(pid, 0).
+    return (err as NodeJS.ErrnoException).code !== 'ENOENT';
+  }
+  // "<pid> (<comm>) <state> …": comm may hold spaces and parentheses itself,
+  // so the state is the field after the LAST ')'.
+  const close = stat.lastIndexOf(')');
+  const state = close === -1 ? '' : stat.charAt(close + 2);
+  return state !== 'Z' && state !== 'X';
+}
+
+export interface WaitForExitOptions {
+  /** Give up after this long; the survivors are returned, never thrown. */
+  timeoutMs: number;
+  /** Poll step, {@link PROCESS_EXIT_POLL_MS} by default. */
+  pollMs?: number;
+  /** Liveness probe, {@link isProcessRunning} by default (injectable for tests). */
+  isRunning?: (pid: number) => boolean;
+}
+
+/**
+ * Resolve once every pid in `pids` has exited, or at the deadline with the ones
+ * that have not. Never rejects.
+ */
+export async function waitForProcessesExit(pids: readonly number[], options: WaitForExitOptions): Promise<number[]> {
+  const isRunning = options.isRunning ?? isProcessRunning;
+  const pollMs = Math.max(1, options.pollMs ?? PROCESS_EXIT_POLL_MS);
+  const deadline = Date.now() + options.timeoutMs;
+  let running = pids.filter((pid) => isRunning(pid));
+  while (running.length > 0) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(pollMs, remaining)));
+    running = running.filter((pid) => isRunning(pid));
+  }
+  return running;
+}

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/paste-image-gc.ts

@@ -1,25 +1,99 @@
 /**
- * @fileoverview Periodic GC for paste-image files.
+ * @fileoverview Periodic GC for prompt-upload files, and the one place that
+ * names the directories they live in.
  *
  * Without cleanup, /api/sessions/:id/paste-image accumulates files indefinitely
- * under {workingDir}/.claude-images/. The route only triggers cleanup on
+ * under {workingDir}/.codeman-uploads/. The route only triggers cleanup on
  * killMux=true session deletion, so long-lived sessions can fill disk under
  * heavy pasting. This sweeper bounds disk use by deleting `paste-*` files
- * older than MAX_AGE_MS from each live session's image dir on an interval.
+ * older than MAX_AGE_MS from each live session's upload dirs on an interval.
  *
  * Conservative defaults — only files matching the `paste-` prefix are
  * considered, and we lstat (not stat) so a planted symlink cannot escape the
- * image dir.
+ * upload dir.
  */
 import fs from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { join, resolve, sep } from 'node:path';
+import { getDataDir } from '../config/instance.js';
+import { probePathKind, type PathProbeOptions } from '../utils/bounded-path-probe.js';
 import type { SessionPort } from './ports/index.js';
 
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 const SWEEP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 const INITIAL_DELAY_MS = 30 * 1000; // 30s after startup
 
+/**
+ * Where a prompt upload is written, relative to the session's working
+ * directory. IN the workspace, because that is the only path that resolves
+ * identically for a local agent and a container (only the workspace is
+ * bind-mounted, at the same absolute path); hidden, so it stays out of
+ * `git status` and the agent's view of the repository; FLAT, because a nested
+ * `<workspace>/.codeman/` is Codeman's own data dir when the workspace is the
+ * home directory; and self-ignoring, through a `.gitignore` of `*` the route
+ * writes once.
+ */
+export const UPLOADS_DIR = '.codeman-uploads';
+/** Where uploads landed before the move: written to by nothing, readable for one release. */
+export const LEGACY_UPLOADS_DIR = '.claude-images';
+/** Every upload dir name, current first. Retiring the legacy one here retires it for every reader. */
+export const UPLOAD_DIR_NAMES = [UPLOADS_DIR, LEGACY_UPLOADS_DIR];
+
+/**
+ * Every directory a session's uploads sit in, current first. Both consumers
+ * act on what this returns, the hourly sweep and the recursive delete in
+ * cleanupSession(), so it lists only REAL directories (a link planted by a
+ * workspace script, `.codeman-uploads -> /other-case/.codeman-uploads`, is
+ * not one; readdir follows a link to a directory), none that is or contains
+ * this instance's data dir (a home workspace reaches it under a contrived
+ * instance name, `CODEMAN_INSTANCE=uploads`, and `CODEMAN_DATA_DIR` can point
+ * inside one; a directory strictly below the data dir only ever holds uploads
+ * and is listed, or the uploads of a workspace like `~/.codeman/app` would
+ * never be collected), and nothing for a remote (SSH) session, whose
+ * workingDir is the remote path and would name a same-named LOCAL directory
+ * here. The working directory is a user-chosen path, so it is probed BOUNDED
+ * first (#516): one on a mount that stopped answering reads `unknown` and is
+ * skipped, never touched. The sweep keeps the probe's stall cap; the delete,
+ * acting on one path at the user's request, passes `pastCap`. The check is
+ * made when listing: a same-user process that swaps a listed directory for a
+ * link afterwards is accepted, since it already writes anywhere this process
+ * can.
+ */
+export async function uploadDirs(
+  session: { workingDir: string; remote?: unknown },
+  probe: PathProbeOptions = {}
+): Promise<string[]> {
+  if (session.remote) return [];
+  if ((await probePathKind(session.workingDir, probe)) !== 'directory') return [];
+  const dataDir = await realDir(getDataDir());
+  const dirs: string[] = [];
+  for (const dir of UPLOAD_DIR_NAMES.map((name) => join(session.workingDir, name))) {
+    if (!(await isRealDir(dir))) continue;
+    const real = await realDir(dir);
+    if (real === dataDir || dataDir.startsWith(real + sep)) continue;
+    dirs.push(dir);
+  }
+  return dirs;
+}
+
+/** lstat, so a symlink is not a directory, whatever it points at. */
+async function isRealDir(p: string): Promise<boolean> {
+  try {
+    return (await fs.lstat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** `canonicalDir()` for the listing, which must not block the event loop on a user path. */
+async function realDir(dir: string): Promise<string> {
+  try {
+    return await fs.realpath(dir);
+  } catch {
+    return resolve(dir);
+  }
+}
+
 export async function sweepPasteImagesOnce(
   ctx: Pick<SessionPort, 'sessions'>,
   now: number = Date.now()
@@ -28,26 +102,27 @@ export async function sweepPasteImagesOnce(
   let scanned = 0;
   let deleted = 0;
   for (const session of ctx.sessions.values()) {
-    const dir = join(session.workingDir, '.claude-images');
-    let entries: string[];
-    try {
-      entries = await fs.readdir(dir);
-    } catch {
-      continue; // dir absent — nothing to do
-    }
-    for (const name of entries) {
-      if (!name.startsWith('paste-')) continue;
-      const p = join(dir, name);
-      scanned += 1;
+    for (const dir of await uploadDirs(session)) {
+      let entries: string[];
       try {
-        const st = await fs.lstat(p);
-        if (!st.isFile()) continue;
-        if (st.mtimeMs < cutoff) {
-          await fs.unlink(p);
-          deleted += 1;
-        }
+        entries = await fs.readdir(dir);
       } catch {
-        // best-effort: skip permission/race errors silently
+        continue; // gone since listed — nothing to do
+      }
+      for (const name of entries) {
+        if (!name.startsWith('paste-')) continue;
+        const p = join(dir, name);
+        scanned += 1;
+        try {
+          const st = await fs.lstat(p);
+          if (!st.isFile()) continue;
+          if (st.mtimeMs < cutoff) {
+            await fs.unlink(p);
+            deleted += 1;
+          }
+        } catch {
+          // best-effort: skip permission/race errors silently
+        }
       }
     }
   }
@@ -55,7 +130,7 @@ export async function sweepPasteImagesOnce(
 }
 
 /**
- * The path two sessions must share to share a paste-image dir: the canonical
+ * The path two sessions must share to share an upload dir: the canonical
  * path when it can be resolved, so a sibling that reaches the same directory
  * through a symlink matches, and the normalised path otherwise (a directory
  * that no longer exists has nothing left to protect).
@@ -68,7 +143,7 @@ function canonicalDir(dir: string): string {
   }
 }
 
-/** One session the paste-image guard weighs: its id, directory and, for a persisted record, its status. */
+/** One session the upload-dir guard weighs: its id, directory and, for a persisted record, its status. */
 export interface PasteImageDirUser {
   id: string;
   workingDir: string;
@@ -76,11 +151,11 @@ export interface PasteImageDirUser {
 }
 
 /**
- * Does another live session still use this working directory's paste-image
- * dir? Deleting a session removes `{workingDir}/.claude-images` recursively,
- * and several sessions routinely share one case directory, so without this
- * check closing one session deletes the pasted images a sibling in the same
- * case still refers to.
+ * Does another live session still use this working directory's upload dirs?
+ * Deleting a session removes them (`uploadDirs()`) recursively, and several
+ * sessions routinely share one case directory, so without this check closing
+ * one session deletes the pasted images a sibling in the same case still
+ * refers to.
  *
  * Two kinds of sibling count as live:
  *

src/web/public/entrance-animations.js

@@ -1,12 +1,13 @@
 /**
- * @fileoverview Entrance animations for the four things that appear when work
+ * @fileoverview Entrance animations for the things that appear when work
  * starts: session TABS, the main TERMINAL pane a session's CLI runs in, floating
- * agent WINDOWS, and the CONNECTION LINES tying a window back to its parent tab.
- * One picker per surface, plus themes that set all four to a matching look.
+ * agent WINDOWS, the CONNECTION LINES tying a window back to its parent tab, and
+ * the TILES of the tile grid (tile-grid.js). One picker per surface, plus themes
+ * that set all five to a matching look.
  *
  * Everything is OFF by default (the `legacy` theme), so an untouched install
  * behaves exactly as it did before this module existed. Opt in via App Settings
- * → Appearance → Entrance Animations.
+ * → Animations.
  *
  * Four constraints shape the design:
  *
@@ -34,13 +35,28 @@
  *    once-per-id even though the POST response and the SSE event both call
  *    `_onSessionCreated`.
  *
+ * Tiles are off by default (`settle`, the grid's own quick fade, exactly as
+ * before) and switched on in App Settings → Animations → Tile Animations, or
+ * preset by a theme. A styled tile plays in two beats that combine two
+ * surfaces. The FRAME enters as it mounts, in its own style
+ * (TILE_ANIM_STYLES); the SCREEN plays the terminal pane's style when its
+ * first capture lands (`.tile-body.term-enter`, the same keyframes as the main
+ * pane). The load queue serves one capture at a time, so
+ * the screens light up one after another, the focused tile first. The frame
+ * styles move transform and opacity only (six tiles animate at once; a blur
+ * belongs to the serialized screen beat), and each has its own way out on the
+ * closing grid's still copy. A reload restores with `settle` whatever the
+ * setting.
+ *
  * Styles are selected by `data-tab-anim` / `data-term-anim` / `data-win-anim` /
- * `data-line-anim` on <html>; the keyframes live in styles.css. `?animlab=1`
- * opens a floating picker that fakes tabs, a pane replay, a window and a line,
- * so styles can be compared without spawning real sessions or agents.
+ * `data-line-anim` / `data-tile-anim` on <html>; the keyframes live in
+ * styles.css. `?animlab=1` opens a floating picker that fakes tabs, a pane
+ * replay, a window and a line, and replays the tile grid in place, so styles
+ * can be compared without spawning real sessions or agents.
  *
  * @mixin Extends CodemanApp.prototype via Object.assign
- * @dependency app.js (tab render pipeline), subagent-windows.js (window + line hooks)
+ * @dependency app.js (tab render pipeline), subagent-windows.js (window + line hooks),
+ *   tile-grid.js (tile mount, reveal and still-copy hooks)
  * @dependency constants.js (escapeHtml)
  * @loadorder 12.6 of 16, after webview-tabs.js, before ralph-wizard.js
  */
@@ -94,7 +110,6 @@ const LINE_ANIM_STYLES = [
  */
 const TERM_ANIM_STYLES = [
   { key: 'crt', label: 'CRT', blurb: 'Power-on: a hot line that expands to full height.', duration: 560 },
-  { key: 'boot', label: 'Boot', blurb: 'Flickers on under a green scan sweep.', duration: 760 },
   { key: 'wipe', label: 'Wipe', blurb: 'Reveals top-to-bottom behind a bright edge.', duration: 520 },
   { key: 'slide', label: 'Slide up', blurb: 'Rises into place from below.', duration: 420 },
   { key: 'fade', label: 'Fade', blurb: 'Quiet fade with a touch of scale.', duration: 340 },
@@ -102,30 +117,79 @@ const TERM_ANIM_STYLES = [
   { key: 'off', label: 'Off', blurb: 'Current behaviour: the pane just appears.', duration: 0 },
 ];
 
+/**
+ * Tile grid entrance styles, for each tile's FRAME (its screen plays the
+ * TERM_ANIM_STYLES style once content lands). Transform and opacity only, plus
+ * a wash on ::before: FitAddon reads the untransformed layout box, so a tile
+ * still fits once at its final size (#464). `stagger` is the default gap
+ * between tiles and `order` the default cascade: `reading` (row by row),
+ * `wave` (diagonals from the top left) or `ripple` (outward from the focused
+ * tile). `from`: the tile is measured against a source after layout (its tab,
+ * the Tiles button), so it is held one frame and timed by _runTileEntrances.
+ */
+// prettier-ignore
+const TILE_ANIM_STYLES = [
+  { key: 'settle', label: 'Off (default)', blurb: "The grid's own quick fade and settle.", duration: 180, stagger: 24, order: 'reading' },
+  { key: 'fly', label: 'Fly from tab', blurb: 'Each tile flies out of its session tab, and back into it on close.', duration: 560, stagger: 55, order: 'reading', from: 'tab' },
+  { key: 'deal', label: 'Deal', blurb: 'Dealt out of the Tiles button like cards, gathered back on close.', duration: 600, stagger: 75, order: 'reading', from: 'button' },
+  { key: 'crt', label: 'CRT', blurb: 'Powers on as a hot line; switches off to a dot on close.', duration: 560, stagger: 70, order: 'wave' },
+  { key: 'beam', label: 'Beam down', blurb: 'A beam draws down from its tab, then the tile materializes.', duration: 620, stagger: 90, order: 'reading', from: 'tab' },
+  { key: 'cascade', label: 'Cascade', blurb: 'Swings down from its top edge in a diagonal wave.', duration: 600, stagger: 80, order: 'wave' },
+  { key: 'pop', label: 'Pop', blurb: 'Springs open, rippling out from the focused tile.', duration: 480, stagger: 70, order: 'ripple' },
+  { key: 'soft', label: 'Soft', blurb: 'Drifts in slowly, rippling out from the focused tile.', duration: 620, stagger: 60, order: 'ripple' },
+  { key: 'off', label: 'None', blurb: 'Tiles just appear.', duration: 0, stagger: 0, order: 'reading' },
+];
+
+/** Cascade orders for the tile grid; `auto` is each style's own. */
+const TILE_ANIM_ORDERS = [
+  { key: 'auto', label: 'Style default' },
+  { key: 'reading', label: 'Reading order' },
+  { key: 'wave', label: 'Diagonal wave' },
+  { key: 'ripple', label: 'Ripple from focus' },
+];
+
 /** How long a `beam` window waits before materializing. Just under the line draw. */
 const BEAM_HOLD_MS = 360;
 
+/** Gap between tiles leaving, in reading order, so the last copy ends last. */
+const TILE_EXIT_STAGGER_MS = 35;
+
+/** Tile exit durations per style (styles.css `tile-leave-*`); the rest use the default fade. */
+const TILE_EXIT_MS = { fly: 460, deal: 520, crt: 520, beam: 480, cascade: 480, pop: 380, soft: 520 };
+
 /** One-click combinations that read as a single look. */
 const ANIM_THEMES = [
-  { key: 'terminal', label: 'Terminal', tab: 'crt', win: 'crt', line: 'draw', term: 'crt' },
-  { key: 'beamdown', label: 'Beam down', tab: 'crt', win: 'beam', line: 'draw', term: 'wipe' },
-  { key: 'softfocus', label: 'Soft focus', tab: 'blur', win: 'blur', line: 'blur', term: 'blur' },
-  { key: 'quiet', label: 'Quiet', tab: 'slide', win: 'materialize', line: 'fade', term: 'fade' },
-  { key: 'playful', label: 'Playful', tab: 'pop', win: 'pop', line: 'packet', term: 'slide' },
-  { key: 'legacy', label: 'Legacy', tab: 'off', win: 'fly', line: 'off', term: 'off' },
+  { key: 'terminal', label: 'Terminal', tab: 'crt', win: 'crt', line: 'draw', term: 'crt', tile: 'crt' },
+  { key: 'beamdown', label: 'Beam down', tab: 'crt', win: 'beam', line: 'draw', term: 'wipe', tile: 'beam' },
+  { key: 'launch', label: 'Launch', tab: 'pop', win: 'fly', line: 'packet', term: 'fade', tile: 'fly' },
+  { key: 'softfocus', label: 'Soft focus', tab: 'blur', win: 'blur', line: 'blur', term: 'blur', tile: 'soft' },
+  { key: 'quiet', label: 'Quiet', tab: 'slide', win: 'materialize', line: 'fade', term: 'fade', tile: 'settle' },
+  { key: 'playful', label: 'Playful', tab: 'pop', win: 'pop', line: 'packet', term: 'slide', tile: 'deal' },
+  { key: 'legacy', label: 'Legacy', tab: 'off', win: 'fly', line: 'off', term: 'off', tile: 'settle' },
 ];
 
+/**
+ * The surfaces a theme is recognised by. A theme also PRESETS the tile style
+ * when it is picked, but the tile style is its own setting (App Settings →
+ * Animations → Tile Animations, off by default), so changing it afterwards
+ * does not turn the theme into "Custom".
+ */
+const ANIM_SURFACES = ['tab', 'win', 'line', 'term'];
+
 /**
  * Defaults are the `legacy` theme: every entrance OFF, and agent windows on the
  * `fly` behaviour Codeman already had before this module existed. So a user who
  * never opens the picker sees exactly the pre-existing UI, and each mark/apply
- * hook short-circuits on its first line. Opt in via App Settings → Appearance →
- * Entrance Animations, which persists to the localStorage keys below.
+ * hook short-circuits on its first line. Opt in via App Settings → Animations,
+ * which persists to the localStorage keys below.
  */
 const TAB_ANIM_DEFAULT = 'off';
 const WIN_ANIM_DEFAULT = 'fly';
 const LINE_ANIM_DEFAULT = 'off';
 const TERM_ANIM_DEFAULT = 'off';
+/** The grid's own fade and settle, unchanged for anyone who never picks a theme. */
+const TILE_ANIM_DEFAULT = 'settle';
+const TILE_ANIM_ORDER_DEFAULT = 'auto';
 const TAB_ANIM_STAGGER_DEFAULT = 90;
 /** A new id joins the current cascade if it arrives within this of the last one. */
 const TAB_ANIM_BATCH_WINDOW_MS = 600;
@@ -135,6 +199,8 @@ const ANIM_KEYS = {
   win: 'codeman:winAnim',
   line: 'codeman:lineAnim',
   term: 'codeman:termAnim',
+  tile: 'codeman:tileAnim',
+  tileOrder: 'codeman:tileAnimOrder',
   termSwitch: 'codeman:termAnimOnSwitch',
   stagger: 'codeman:tabAnimStagger',
   speed: 'codeman:tabAnimSpeed',
@@ -164,6 +230,10 @@ Object.assign(CodemanApp.prototype, {
     this.setWinAnimStyle(pick('winanim', WIN_ANIM_STYLES, ANIM_KEYS.win, WIN_ANIM_DEFAULT), { persist: false });
     this.setLineAnimStyle(pick('lineanim', LINE_ANIM_STYLES, ANIM_KEYS.line, LINE_ANIM_DEFAULT), { persist: false });
     this.setTermAnimStyle(pick('termanim', TERM_ANIM_STYLES, ANIM_KEYS.term, TERM_ANIM_DEFAULT), { persist: false });
+    // Off (the grid's own `settle`) until chosen: a theme saved before tiles
+    // were a surface gives them nothing new.
+    this.setTileAnimStyle(pick('tileanim', TILE_ANIM_STYLES, ANIM_KEYS.tile, TILE_ANIM_DEFAULT), { persist: false });
+    this.setTileAnimOrder(this._animRead(ANIM_KEYS.tileOrder, TILE_ANIM_ORDER_DEFAULT), { persist: false });
     this.setTermAnimOnSwitch(this._animRead(ANIM_KEYS.termSwitch, '0') === '1', { persist: false });
 
     this.setTabAnimStagger(Number(this._animRead(ANIM_KEYS.stagger, TAB_ANIM_STAGGER_DEFAULT)), { persist: false });
@@ -219,6 +289,18 @@ Object.assign(CodemanApp.prototype, {
     this._setAnimStyle('_termAnimStyle', key, TERM_ANIM_STYLES, TERM_ANIM_DEFAULT, 'data-term-anim', ANIM_KEYS.term, persist);
   },
 
+  setTileAnimStyle(key, { persist = true } = {}) {
+    // prettier-ignore
+    this._setAnimStyle('_tileAnimStyle', key, TILE_ANIM_STYLES, TILE_ANIM_DEFAULT, 'data-tile-anim', ANIM_KEYS.tile, persist);
+  },
+
+  /** The tile cascade: `auto` (the style's own) or a TILE_ANIM_ORDERS key. */
+  setTileAnimOrder(key, { persist = true } = {}) {
+    this._tileAnimOrder = TILE_ANIM_ORDERS.some((o) => o.key === key) ? key : TILE_ANIM_ORDER_DEFAULT;
+    if (persist) this._animWrite(ANIM_KEYS.tileOrder, this._tileAnimOrder);
+    this._syncAnimLab?.();
+  },
+
   /** Replay the terminal entrance on every tab switch, not just on a new session. */
   setTermAnimOnSwitch(on, { persist = true } = {}) {
     this._termAnimOnSwitch = !!on;
@@ -234,22 +316,29 @@ Object.assign(CodemanApp.prototype, {
     this.setWinAnimStyle(theme.win);
     this.setLineAnimStyle(theme.line);
     this.setTermAnimStyle(theme.term);
+    this.setTileAnimStyle(theme.tile);
     this._syncEntranceAnimSetting?.();
   },
 
-  /** The theme matching the four current styles, or 'custom' for a lab mix. */
+  /** The current style of each surface, keyed as ANIM_SURFACES. */
+  _currentAnimStyles() {
+    return {
+      tab: this._tabAnimStyle,
+      win: this._winAnimStyle,
+      line: this._lineAnimStyle,
+      term: this._termAnimStyle,
+      tile: this._tileAnimStyle,
+    };
+  },
+
+  /** The theme matching the current tab, window, line and pane styles, or 'custom' for a lab mix. */
   currentAnimTheme() {
-    const match = ANIM_THEMES.find(
-      (t) =>
-        t.tab === this._tabAnimStyle &&
-        t.win === this._winAnimStyle &&
-        t.line === this._lineAnimStyle &&
-        t.term === this._termAnimStyle
-    );
+    const current = this._currentAnimStyles();
+    const match = ANIM_THEMES.find((t) => ANIM_SURFACES.every((k) => t[k] === current[k]));
     return match ? match.key : 'custom';
   },
 
-  // ── App Settings picker ───────────────────────────────────────────────────
+  // ── App Settings → Animations ─────────────────────────────────────────────
   //
   // Wired straight to setAnimTheme() rather than through saveAppSettings(): the
   // styles live in their own localStorage keys, so they stay per-device and never
@@ -257,16 +346,40 @@ Object.assign(CodemanApp.prototype, {
 
   _syncEntranceAnimSetting() {
     const sel = document.getElementById('appSettingsEntranceAnim');
-    if (!sel) return;
-    sel.value = this.currentAnimTheme();
-    if (!sel.dataset.bound) {
-      sel.dataset.bound = '1';
-      sel.addEventListener('change', () => {
-        // 'custom' is a readout of a lab mix, not something you can select into.
-        if (sel.value === 'custom') sel.value = this.currentAnimTheme();
-        else this.setAnimTheme(sel.value);
+    if (sel) {
+      sel.value = this.currentAnimTheme();
+      if (!sel.dataset.bound) {
+        sel.dataset.bound = '1';
+        sel.addEventListener('change', () => {
+          // 'custom' is a readout of a lab mix, not something you can select into.
+          if (sel.value === 'custom') sel.value = this.currentAnimTheme();
+          else this.setAnimTheme(sel.value);
+        });
+      }
+    }
+    // App Settings → Animations → Animation Lab. Settings has no unsaved-edit
+    // tracking, so this closes it as Cancel does (the row says so).
+    const labBtn = document.getElementById('appSettingsOpenAnimLab');
+    if (labBtn && !labBtn.dataset.bound) {
+      labBtn.dataset.bound = '1';
+      labBtn.addEventListener('click', () => {
+        this.closeAppSettings?.();
+        this.openAnimLab();
       });
     }
+    // Tile Animations: its own row, off (`settle`) by default. A theme picked
+    // above presets it; picked here, it applies to tiles alone.
+    const tileSel = document.getElementById('appSettingsTileAnim');
+    if (tileSel) {
+      tileSel.value = this._tileAnimStyle || TILE_ANIM_DEFAULT;
+      if (!tileSel.dataset.bound) {
+        tileSel.dataset.bound = '1';
+        tileSel.addEventListener('change', () => {
+          this.setTileAnimStyle(tileSel.value);
+          this._syncEntranceAnimSetting();
+        });
+      }
+    }
   },
 
   setTabAnimStagger(ms, { persist = true } = {}) {
@@ -303,6 +416,10 @@ Object.assign(CodemanApp.prototype, {
     return this._styleDuration(TERM_ANIM_STYLES, this._termAnimStyle);
   },
 
+  _tileAnimDuration() {
+    return this._styleDuration(TILE_ANIM_STYLES, this._tileAnimStyle);
+  },
+
   // ── Tabs ──────────────────────────────────────────────────────────────────
 
   /** Queue a session id to animate on its next render. Idempotent per id. */
@@ -501,6 +618,317 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  // ── Tile grid ─────────────────────────────────────────────────────────────
+
+  /** The frame style a tile mounted now enters with (tile-grid.js _mountTile). */
+  tileEntranceStyle() {
+    return this._tileAnimStyle || TILE_ANIM_DEFAULT;
+  },
+
+  /**
+   * Holds a just-mounted tile (`.tile--enter-hold`: invisible, not animating)
+   * until the next frame, when its cell is final and _runTileEntrances can
+   * order it and measure it against its source. `setBackstop(ms)` arms the
+   * mount's own timer that ends the entrance should animationend never come
+   * (a hidden browser tab, a zoomed grid hiding the tile); armed long at once,
+   * so a frame that never comes cannot strand a tile invisible.
+   */
+  _stageTileEntrance(el, sessionId, setBackstop) {
+    el.classList.add('tile--enter-themed', 'tile--enter-hold');
+    (this._tileEnterQueue ||= []).push({ el, sessionId, setBackstop });
+    setBackstop(4000);
+    if (!this._tileEnterRaf) this._tileEnterRaf = requestAnimationFrame(() => this._runTileEntrances());
+  },
+
+  /**
+   * One frame after the tiles mounted, every cell is final (openTileGrid packs,
+   * then a stored grid moves its tiles back). Each held tile gets its delay
+   * from the cascade order and, for `fly`/`deal`, the offset that starts it on
+   * its tab or the Tiles button (FLIP: transform only, so the fit it already
+   * did at its real size stands). `beam` draws its lines instead.
+   */
+  _runTileEntrances() {
+    this._tileEnterRaf = 0;
+    const queue = (this._tileEnterQueue || []).filter((q) => q.el.isConnected);
+    this._tileEnterQueue = [];
+    if (queue.length === 0) return;
+    const def = TILE_ANIM_STYLES.find((s) => s.key === this._tileAnimStyle) || TILE_ANIM_STYLES[0];
+    const speed = this._animSpeed || 1;
+    const stagger = def.stagger / speed;
+    const duration = this._tileAnimDuration();
+    const hold = def.key === 'beam' ? BEAM_HOLD_MS / speed : 0;
+    const order = this._tileAnimOrder && this._tileAnimOrder !== 'auto' ? this._tileAnimOrder : def.order;
+    const ranks = this._tileEnterRanks(
+      queue.map((q) => q.sessionId),
+      order
+    );
+    const beams = [];
+    queue.forEach((item, k) => {
+      const { el, sessionId } = item;
+      const delay = ranks[k] * stagger;
+      el.style.setProperty('--tile-enter-delay', `${Math.round(delay + hold)}ms`);
+      if (def.from) {
+        const to = el.getBoundingClientRect();
+        const from = this._tileSourceRect(def.from, sessionId);
+        if (from && to.width > 0 && to.height > 0) {
+          if (def.key === 'beam') beams.push({ from, to, delay });
+          else this._setTileFlight(el, from, to, def.key, ranks[k], '--tile-from');
+          if (def.from === 'tab') this._flashTileSourceTab(sessionId, delay);
+        }
+      }
+      el.classList.remove('tile--enter-hold');
+      // When the frame lands, for a screen whose content arrives earlier.
+      el._tileEnterEndsAt = performance.now() + delay + hold + duration;
+      item.setBackstop(delay + hold + duration + 900);
+    });
+    if (beams.length > 0) this._drawTileBeams(beams);
+  },
+
+  /**
+   * Cascade steps for `ids` (tiles in this batch) by their cells: `reading`
+   * row by row, `wave` by diagonal (row + column), `ripple` by distance from
+   * the focused tile. Equal keys share a step, so a diagonal lands together.
+   */
+  _tileEnterRanks(ids, order) {
+    const grid = this._tileGrid;
+    const cols = Math.max(1, grid?.cols || 1);
+    const cellOf = (id) => (Array.isArray(grid?.cells) ? grid.cells.indexOf(id) : -1);
+    const pos = ids.map((id, k) => {
+      const c = cellOf(id);
+      return c < 0 ? { cell: k, row: 0, col: k } : { cell: c, row: Math.floor(c / cols), col: c % cols };
+    });
+    let keys;
+    if (order === 'wave') {
+      keys = pos.map((p) => p.row + p.col);
+    } else if (order === 'ripple') {
+      const f = cellOf(grid?.focusedId);
+      const fr = f < 0 ? 0 : Math.floor(f / cols);
+      const fc = f < 0 ? 0 : f % cols;
+      keys = pos.map((p) => Math.abs(p.row - fr) + Math.abs(p.col - fc));
+    } else {
+      keys = pos.map((p) => p.cell);
+    }
+    const steps = [...new Set(keys)].sort((a, b) => a - b);
+    return keys.map((v) => steps.indexOf(v));
+  },
+
+  /** On-screen rect of a tile's source: its session tab (`tab`), else the Tiles button. */
+  _tileSourceRect(kind, sessionId) {
+    const visible = (node) => {
+      const r = node?.getBoundingClientRect?.();
+      if (!r || !(r.width > 0 && r.height > 0)) return null;
+      return r.bottom > 0 && r.right > 0 && r.top < window.innerHeight && r.left < window.innerWidth ? r : null;
+    };
+    if (kind === 'tab') {
+      const tab = document.querySelector(`.session-tab[data-id="${CSS.escape(sessionId)}"]`);
+      const r = visible(tab);
+      if (r) return r;
+    }
+    return visible(document.querySelector('.btn-tile-grid'));
+  },
+
+  /**
+   * The transform that puts a tile laid out at `to` onto `from`, as custom
+   * properties `<prefix>-x/-y/-sx/-sy/-rot` for the keyframes: the tab's own
+   * size for `fly` (it grows out of it), a small card turned a little for
+   * `deal`.
+   */
+  _setTileFlight(el, from, to, kind, rank, prefix) {
+    const dx = from.left + from.width / 2 - (to.left + to.width / 2);
+    const dy = from.top + from.height / 2 - (to.top + to.height / 2);
+    const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+    let sx;
+    let sy;
+    let rot = 0;
+    if (kind === 'deal') {
+      sx = sy = clamp((from.width * 1.6) / to.width, 0.04, 0.3);
+      rot = [-14, 10, -7, 13, -11, 8][rank % 6];
+    } else {
+      sx = clamp(from.width / to.width, 0.02, 1);
+      sy = clamp(from.height / to.height, 0.02, 1);
+    }
+    el.style.setProperty(`${prefix}-x`, `${Math.round(dx)}px`);
+    el.style.setProperty(`${prefix}-y`, `${Math.round(dy)}px`);
+    el.style.setProperty(`${prefix}-sx`, sx.toFixed(4));
+    el.style.setProperty(`${prefix}-sy`, sy.toFixed(4));
+    el.style.setProperty(`${prefix}-rot`, `${rot}deg`);
+  },
+
+  /** The tab a tile leaves from glows as it goes (`fly`, `beam`). */
+  _flashTileSourceTab(sessionId, delay) {
+    const tab = document.querySelector(`.session-tab[data-id="${CSS.escape(sessionId)}"]`);
+    if (!tab) return;
+    tab.style.setProperty('--tab-launch-delay', `${Math.round(delay)}ms`);
+    tab.classList.remove('tab-launch');
+    void tab.offsetWidth;
+    tab.classList.add('tab-launch');
+    const onEnd = (e) => {
+      if (e.target === tab && /^tab-launch/.test(e.animationName || '')) done();
+    };
+    const done = () => {
+      clearTimeout(timer);
+      tab.removeEventListener('animationend', onEnd);
+      tab.classList.remove('tab-launch');
+      tab.style.removeProperty('--tab-launch-delay');
+    };
+    const timer = setTimeout(done, delay + 900);
+    tab.addEventListener('animationend', onEnd);
+  },
+
+  /**
+   * `beam`: a line draws from each tile's tab (or the Tiles button) down into
+   * the middle of its tile, in the connection-line look, with a packet riding it
+   * when the line style is `packet`; the tile materializes as it lands. Its
+   * own overlay: the agent lines' one is rebuilt from scratch on every redraw.
+   * The overlay goes once every line has faded.
+   */
+  _drawTileBeams(beams) {
+    const ns = 'http://www.w3.org/2000/svg';
+    let svg = document.getElementById('tileBeamLines');
+    if (!svg) {
+      svg = document.createElementNS(ns, 'svg');
+      svg.id = 'tileBeamLines';
+      svg.setAttribute('class', 'connection-lines-svg tile-beam-lines');
+      svg.setAttribute('aria-hidden', 'true');
+      document.body.appendChild(svg);
+    }
+    const packet = this._lineAnimStyle === 'packet';
+    let last = 0;
+    for (const { from, to, delay } of beams) {
+      const x1 = from.left + from.width / 2;
+      const y1 = from.bottom;
+      // Into the tile's middle: its top edge sits right under the tab strip,
+      // so a beam aimed there ran sideways along the strip instead of down.
+      const x2 = to.left + to.width / 2;
+      const y2 = to.top + to.height / 2;
+      const midY = (y1 + y2) / 2;
+      const path = document.createElementNS(ns, 'path');
+      path.setAttribute('d', `M ${x1} ${y1} C ${x1} ${midY}, ${x2} ${midY}, ${x2} ${y2}`);
+      path.setAttribute('class', 'connection-line tile-beam-line');
+      svg.appendChild(path);
+      const len = Math.max(1, Math.round(path.getTotalLength()));
+      path.style.setProperty('--line-len', `${len}px`);
+      path.style.setProperty('--line-enter-delay', `${Math.round(delay)}ms`);
+      if (packet) {
+        const dot = path.cloneNode(false);
+        dot.setAttribute('class', 'connection-line-packet');
+        svg.appendChild(dot);
+      }
+      last = Math.max(last, delay);
+    }
+    clearTimeout(this._tileBeamTimer);
+    this._tileBeamTimer = setTimeout(() => svg.remove(), last + 1500 / (this._animSpeed || 1));
+  },
+
+  /**
+   * A tile's screen lights up when its first capture lands (tile-grid.js load
+   * queue), in the terminal pane's style: the same keyframes as the main pane,
+   * on `.tile-body`. Transform, opacity and clip-path (and `blur`'s filter, one
+   * tile at a time, since the queue serves one capture at a time), so the
+   * xterm inside keeps its size and its fit.
+   */
+  playTileScreenEntrance(body) {
+    if (!body || (this._termAnimStyle || TERM_ANIM_DEFAULT) === 'off') return;
+    if (window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches) return;
+    body._codemanScreenDone?.();
+    // Content that lands while the frame is still flying in waits (held at
+    // its first keyframe, so hidden) until the frame has nearly landed: two
+    // beats, frame then screen, rather than both at once.
+    const frame = body.closest?.('.tile');
+    const endsAt = frame?.classList.contains('tile--entering') ? frame._tileEnterEndsAt || 0 : 0;
+    const wait = Math.max(0, Math.round(endsAt - performance.now() - 120 / (this._animSpeed || 1)));
+    body.style.setProperty('--tile-screen-delay', `${wait}ms`);
+    body.classList.remove('term-enter');
+    void body.offsetWidth;
+    body.classList.add('term-enter');
+    let timer = null;
+    const done = (e) => {
+      if (e && (e.target !== body || e.pseudoElement)) return;
+      clearTimeout(timer);
+      body.removeEventListener('animationend', done);
+      body.removeEventListener('animationcancel', done);
+      body.classList.remove('term-enter');
+      body.style.removeProperty('--tile-screen-delay');
+      if (body._codemanScreenDone === done) body._codemanScreenDone = null;
+    };
+    body._codemanScreenDone = done;
+    body.addEventListener('animationend', done);
+    body.addEventListener('animationcancel', done);
+    // Backstop, as the main pane's: a backgrounded tab never fires animationend.
+    timer = setTimeout(() => done(), wait + this._termAnimDuration() + 900);
+  },
+
+  /**
+   * The closing grid's still copy (tile-grid.js _ghostTileGrid) leaves the
+   * frame style's own way: `fly` back into each tab, `deal` gathered into the
+   * Tiles button, `crt` switched off to a dot, and so on. Copies leave in
+   * reading order, so the last one ends last (the layer goes on its
+   * animationend). Re-forming the grid (`now`) keeps the plain fade: that copy
+   * covers tiles that stay. Returns how long the slowest copy takes, for the
+   * layer's fallback timer, or 0 for the default fade.
+   */
+  _stageTileExit(copies, { now = false } = {}) {
+    const style = this._tileAnimStyle || TILE_ANIM_DEFAULT;
+    const ms = TILE_EXIT_MS[style];
+    if (now || !ms || copies.length === 0) return 0;
+    const speed = this._animSpeed || 1;
+    const def = TILE_ANIM_STYLES.find((s) => s.key === style);
+    copies.forEach(({ ghost, el, sessionId }, k) => {
+      ghost.style.setProperty('--tile-exit-delay', `${Math.round((k * TILE_EXIT_STAGGER_MS) / speed)}ms`);
+      if (style !== 'fly' && style !== 'deal') return;
+      const at = el.getBoundingClientRect();
+      const target = this._tileSourceRect(def.from, sessionId);
+      if (target && at.width > 0 && at.height > 0) this._setTileFlight(ghost, target, at, style, k, '--tile-to');
+    });
+    return (ms + copies.length * TILE_EXIT_STAGGER_MS) / speed + 250;
+  },
+
+  /**
+   * Lab: replay the open grid's entrance IN PLACE (frames re-enter, screens
+   * light up again in queue order): no remount, reconnect or resize. With the
+   * grid closed it opens it, the real path.
+   */
+  _demoTiles() {
+    const grid = this._tileGrid;
+    if (!grid?.open) {
+      if (this.canOpenTileGrid?.()) this.toggleTileGrid?.();
+      else this.showToast?.('The tile grid needs a window at least 1180 px wide', 'info');
+      return;
+    }
+    if (!this._tileMotionAllowed?.()) return;
+    const ids = grid.ids.slice();
+    ids.forEach((id, k) => {
+      const entry = grid.tiles.get(id);
+      if (entry) this._replayTileEntrance?.(entry.el, id, k);
+    });
+    // The screens, as the load queue would land them: focused first, then reading order.
+    const speed = this._animSpeed || 1;
+    const lead = Math.min(this._tileAnimDuration() * 0.55, 420);
+    const order = [grid.focusedId, ...ids.filter((id) => id !== grid.focusedId)].filter(Boolean);
+    clearTimeout(this._tileDemoTimer);
+    const timers = order.map((id, k) =>
+      setTimeout(() => this.playTileScreenEntrance(grid.tiles.get(id)?.body), lead + (k * 140) / speed)
+    );
+    this._tileDemoTimers?.forEach(clearTimeout);
+    this._tileDemoTimers = timers;
+  },
+
+  /** Lab: close the grid with its exit, then open it again with its entrance (the real paths). */
+  _demoTilesRoundTrip() {
+    if (!this._tileGrid?.open) {
+      this._demoTiles();
+      return;
+    }
+    this.toggleTileGrid?.();
+    clearTimeout(this._tileDemoTimer);
+    this._tileDemoTimer = setTimeout(
+      () => {
+        if (!this._tileGrid?.open) this.toggleTileGrid?.();
+      },
+      1400 / (this._animSpeed || 1)
+    );
+  },
+
   // ── Lab (compare styles without spawning sessions or agents) ───────────────
 
   /** Floating picker: switch styles per surface and replay fake entrances. */
@@ -538,6 +966,12 @@ Object.assign(CodemanApp.prototype, {
         </label>
         ${group('Agent windows', WIN_ANIM_STYLES, 'win')}
         ${group('Connection lines', LINE_ANIM_STYLES, 'line')}
+        ${group('Tile grid (frames; screens use the pane style)', TILE_ANIM_STYLES, 'tile')}
+        <label class="anim-lab-select">Tile order
+          <select data-select="tileOrder">
+            ${TILE_ANIM_ORDERS.map((o) => `<option value="${o.key}">${escapeHtml(o.label)}</option>`).join('')}
+          </select>
+        </label>
       </div>
       <label class="anim-lab-range">Tab stagger <output data-out="stagger"></output>
         <input type="range" data-range="stagger" min="0" max="260" step="10">
@@ -552,6 +986,11 @@ Object.assign(CodemanApp.prototype, {
         <button type="button" data-demo="window">Window</button>
         <button type="button" data-demo="all">All</button>
       </div>
+      <div class="anim-lab-demo">
+        <span>Tiles</span>
+        <button type="button" data-demo="tiles">Replay</button>
+        <button type="button" data-demo="tiles-roundtrip">Close + reopen</button>
+      </div>
       <p class="anim-lab-hint">Fake tabs, window and line, removed after the run. Real launches use the same timing.</p>
     `;
     document.body.appendChild(panel);
@@ -570,11 +1009,17 @@ Object.assign(CodemanApp.prototype, {
         if (attr === 'tab') this.setTabAnimStyle(style);
         else if (attr === 'win') this.setWinAnimStyle(style);
         else if (attr === 'term') this.setTermAnimStyle(style);
+        else if (attr === 'tile') this.setTileAnimStyle(style);
         else this.setLineAnimStyle(style);
         this._syncAnimLab();
-        this.demoEntrance({ tab: 'tabs', term: 'term' }[attr] || 'all');
+        this._syncEntranceAnimSetting?.();
+        this.demoEntrance({ tab: 'tabs', term: 'term', tile: 'tiles' }[attr] || 'all');
       });
     });
+    panel.querySelector('select[data-select="tileOrder"]').addEventListener('change', (e) => {
+      this.setTileAnimOrder(e.target.value);
+      this.demoEntrance('tiles');
+    });
     panel.querySelector('input[data-check="termSwitch"]').addEventListener('change', (e) => {
       this.setTermAnimOnSwitch(e.target.checked);
     });
@@ -601,19 +1046,16 @@ Object.assign(CodemanApp.prototype, {
   _syncAnimLab() {
     const panel = document.getElementById('animLab');
     if (!panel) return;
-    const current = {
-      tab: this._tabAnimStyle,
-      win: this._winAnimStyle,
-      line: this._lineAnimStyle,
-      term: this._termAnimStyle,
-    };
+    const current = this._currentAnimStyles();
     panel.querySelectorAll('.anim-lab-style').forEach((btn) => {
       btn.classList.toggle('selected', current[btn.dataset.attr] === btn.dataset.style);
     });
     panel.querySelectorAll('button[data-theme]').forEach((btn) => {
       const t = ANIM_THEMES.find((x) => x.key === btn.dataset.theme);
-      btn.classList.toggle('selected', !!t && ['tab', 'win', 'line', 'term'].every((k) => t[k] === current[k]));
+      btn.classList.toggle('selected', !!t && ANIM_SURFACES.every((k) => t[k] === current[k]));
     });
+    const order = panel.querySelector('select[data-select="tileOrder"]');
+    if (order) order.value = this._tileAnimOrder || TILE_ANIM_ORDER_DEFAULT;
     const check = panel.querySelector('input[data-check="termSwitch"]');
     if (check) check.checked = !!this._termAnimOnSwitch;
     panel.querySelector('input[data-range="stagger"]').value = String(this._tabAnimStagger);
@@ -647,10 +1089,15 @@ Object.assign(CodemanApp.prototype, {
     return svg;
   },
 
-  /** @param {'tabs'|'term'|'window'|'all'} what */
+  /** @param {'tabs'|'term'|'window'|'all'|'tiles'|'tiles-roundtrip'} what */
   demoEntrance(what = 'all') {
     this._clearEntranceDemo();
 
+    if (what === 'tiles') return this._demoTiles();
+    if (what === 'tiles-roundtrip') return this._demoTilesRoundTrip();
+    // With the grid open, the "pane" is every tile's screen.
+    if (what === 'term' && this._tileGrid?.open) return this._demoTiles();
+
     // The pane is a real, shared element rather than a throwaway, so replay it
     // through the same entry point a real launch uses (bypassing the owed-id
     // check, which only exists to keep background sessions from hijacking it).
@@ -692,6 +1139,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

@@ -117,7 +117,9 @@ Object.assign(CodemanApp.prototype, {
     const epoch = (this._gitStatusEpoch = (this._gitStatusEpoch || 0) + 1);
     this._gitStatusFetchedAt = Date.now();
     try {
-      const data = await this._apiJson(`/api/sessions/${encodeURIComponent(sid)}/git-status${fresh ? '?fresh=1' : ''}`);
+      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 {
@@ -131,6 +133,23 @@ Object.assign(CodemanApp.prototype, {
     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();
@@ -150,13 +169,16 @@ Object.assign(CodemanApp.prototype, {
     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;
     }
-    const tone = conflicted > 0 ? 'conflict' : uncommitted > 0 || unpushed > 0 ? 'dirty' : 'clean';
-    return { uncommitted, unpushed, conflicted, repos: overview.repos.length, tone };
+    // 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. */
@@ -168,12 +190,14 @@ Object.assign(CodemanApp.prototype, {
     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.detached ? 'detached HEAD' : d.branch || 'no branch';
+      where = d.state === 'error' ? overview.repos[0].name : d.detached ? 'detached HEAD' : d.branch || 'no branch';
     }
     return `Git (${where}): ${bits.join(', ')}. Click for details.`;
   },
@@ -196,6 +220,7 @@ Object.assign(CodemanApp.prototype, {
     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);
@@ -333,17 +358,23 @@ Object.assign(CodemanApp.prototype, {
     }
 
     const repos = overview.repos;
-    if (repos.length === 1) {
-      // One repository: the panel is that repository, as it always was.
+    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} repositories`;
+      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 ${repos.length} repositories found under this folder.`)
+          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.`
+          )
         );
       }
     }
@@ -364,6 +395,16 @@ Object.assign(CodemanApp.prototype, {
   _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());
@@ -582,7 +623,12 @@ Object.assign(CodemanApp.prototype, {
     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 });
+    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;

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

@@ -25,6 +25,7 @@
     '.response-viewer-content',
     '.file-preview-content',
     '.session-tab-name',
+    '.tab-name',
     '.session-name',
     '.case-name',
     '.notif-item-message',
@@ -45,6 +46,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': '会话标签页',
@@ -52,6 +62,8 @@
     'Collapse session sidebar': '收起会话侧边栏',
     'Expand session sidebar': '展开会话侧边栏',
     'Filter sessions': '筛选会话',
+    'Search sessions': '搜索会话',
+    'No sessions match': '没有匹配的会话',
     'Admin Panel': '管理面板',
     'Open admin panel': '打开管理面板',
     'Re-dock to dashboard (close window)': '重新停靠到主界面（关闭窗口）',
@@ -144,6 +156,14 @@
     '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': '调整窗格列宽',
@@ -214,10 +234,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': '最近会话',
@@ -295,6 +321,7 @@
     Running: '运行中',
     Idle: '空闲',
     Working: '工作中',
+    Waiting: '等待中',
     Today: '今天',
     Home: '主页',
     Local: '本地',
@@ -316,6 +343,36 @@
       '此设备使用的界面语言。动态状态消息与对话框也会使用同一语言。',
     English: 'English',
     Appearance: '外观',
+    // App Settings > Animations (#571). 平铺 is the grid, 窗格 one tile in it.
+    Animations: '动画',
+    'How tabs, terminal panes, agent windows and tiles arrive. All off by default, applied as you pick them.':
+      '标签页、终端面板、智能体窗口和平铺窗格如何出现。默认全部关闭，选择后立即生效。',
+    Entrances: '入场',
+    'Entrance Theme': '入场主题',
+    'One look for how new tabs, terminal panes, agent windows and their lines arrive.':
+      '为新标签页、终端面板、智能体窗口及其连线的出现方式选择统一的风格。',
+    'Off (default)': '关闭（默认）',
+    'Terminal (CRT)': '终端（CRT）',
+    'Beam down': '光束降临',
+    'Launch (tiles fly from tabs)': '发射（窗格从标签页飞出）',
+    'Soft focus (blur)': '柔焦（模糊）',
+    Quiet: '安静',
+    Playful: '活泼',
+    'Custom (set in the lab)': '自定义（在实验室中设置）',
+    'Tile Animations': '平铺动画',
+    'How tiles arrive when the grid opens and leave when it closes. A theme above presets it.':
+      '平铺打开时窗格如何出现、关闭时如何离开。上方的主题会预设此项。',
+    'Fly from tab': '从标签页飞出',
+    Deal: '发牌',
+    Cascade: '级联',
+    Pop: '弹出',
+    Soft: '柔和',
+    'None (tiles just appear)': '无（窗格直接出现）',
+    Lab: '实验室',
+    'Animation Lab': '动画实验室',
+    'Closes settings and opens every style per surface side by side, with replay and speed. Same as adding ?animlab=1 to the URL.':
+      '关闭设置，并按界面并排打开所有样式，可重放和调速。等同于在网址后添加 ?animlab=1。',
+    'Open lab': '打开实验室',
     Skin: '皮肤',
     'Visual theme for this device (not synced)': '此设备的视觉主题（不同步）',
     'Daylight Blue': '日光蓝',
@@ -345,6 +402,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': '项目洞察',
@@ -425,7 +532,6 @@
     'Remote Access': '远程访问',
     'Cloudflare Tunnel': 'Cloudflare 隧道',
     'Tunnel URL': '隧道地址',
-    'Upload URL': '上传地址',
     Updates: '更新',
     'Current Version': '当前版本',
     'Check for Updates': '检查更新',
@@ -522,6 +628,11 @@
     'Audio Alerts': '声音提醒',
     'Push Notifications': '推送通知',
     'Notification Levels': '通知级别',
+    'Toast display time': '弹出提示显示时长',
+    'How long the corner pop-ups stay on screen.': '角落弹出提示在屏幕上停留的时长。',
+    'Browser notification display time': '浏览器通知显示时长',
+    'How long a desktop notification stays up before Codeman closes it. Your OS may close it sooner.':
+      '桌面通知在 Codeman 关闭它之前保持显示的时长。系统可能会更早关闭它。',
     Critical: '严重',
     'Per-Event Settings': '按事件设置',
     'Permission prompts': '权限提示',
@@ -648,6 +759,8 @@
 
     // Dynamic common status / toasts
     'Settings saved': '设置已保存',
+    'Settings applied': '设置已应用',
+    'Save and keep Settings open': '保存并保持设置打开',
     'Settings saved locally': '设置已保存到本机',
     'Tunnel active': '隧道已启用',
     'Tunnel starting — QR code will appear when ready...': '隧道正在启动，准备好后将显示二维码…',
@@ -666,6 +779,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: '复制',
@@ -827,6 +947,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': '全部标为已读',
@@ -1054,6 +1208,11 @@
       [/^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}”`],
       [

src/web/public/image-input.js

@@ -150,6 +150,7 @@ Object.assign(CodemanApp.prototype, {
     const total = files.length;
     let done = 0;
     let failed = 0;
+    let failReason = ''; // first server reason, shown in the toast so a failure is not just a count
     const results = new Array(total); // preserve selection order for insertion
     const progress = () =>
       this.showToast(`Uploading ${Math.min(done + 1, total)}/${total} image${total > 1 ? 's' : ''}…`, 'info');
@@ -173,6 +174,7 @@ Object.assign(CodemanApp.prototype, {
           results[i] = await this._uploadPasteImage(sessionId, normalized);
         } catch (err) {
           failed++;
+          if (!failReason && err && err.message) failReason = err.message;
           console.warn('Image upload failed:', err);
           results[i] = null;
         } finally {
@@ -196,7 +198,7 @@ Object.assign(CodemanApp.prototype, {
     // Final status: successes, plus any failures / cap so nothing is silent.
     const parts = [];
     if (paths.length > 0) parts.push(`${paths.length} image${paths.length > 1 ? 's' : ''} ready`);
-    if (failed > 0) parts.push(`${failed} failed`);
+    if (failed > 0) parts.push(failReason ? `${failed} failed: ${failReason}` : `${failed} failed`);
     if (capped) parts.push(`max ${this._maxBatchImages} per batch`);
     const tone = paths.length > 0 ? (failed > 0 || capped ? 'info' : 'success') : 'error';
     this.showToast(parts.join(' · ') || 'No images uploaded', tone);

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>
@@ -391,6 +394,19 @@
     <!-- Main Terminal Area -->
     <main class="main">
       <aside class="tab-rail" id="tabRail" aria-label="Session navigation">
+        <!-- Session-name search (app.js setTabRailSearch): a view filter over the
+             rows below, in memory only. Shown with the rail, never elsewhere. -->
+        <div class="session-sidebar-filter tab-rail-search">
+          <input type="search" id="tabRailSearch" class="session-sidebar-filter-input"
+            placeholder="Search sessions" aria-label="Search sessions"
+            autocomplete="off" spellcheck="false"
+            oninput="app.setTabRailSearch(this.value)"
+            onkeydown="app.handleTabRailSearchKeydown(event)">
+          <button type="button" id="tabRailSearchClear" class="tab-rail-search-clear"
+            aria-label="Clear search" title="Clear search"
+            onclick="app.clearTabRailSearch()" hidden>&times;</button>
+        </div>
+        <div id="tabRailSearchEmpty" class="tab-rail-search-empty" role="status" hidden>No sessions match</div>
         <div
           id="tabRailResizeHandle"
           class="tab-rail-resize-handle"
@@ -457,9 +473,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>
@@ -697,11 +718,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
@@ -721,8 +740,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()">
@@ -1628,6 +1648,7 @@
                Save; row-reverse keeps Save to the left of it on phones. -->
           <div class="set-head-actions">
             <button class="modal-close" onclick="app.closeAppSettings()" aria-label="Close app settings">&times;</button>
+            <button class="set-head-save set-head-apply" onclick="app.applyAppSettings()" title="Save and keep Settings open">Apply</button>
             <button class="set-head-save" onclick="app.saveAppSettings()">Save</button>
           </div>
         </div>
@@ -1656,6 +1677,10 @@
                 <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="9"/><path d="M12 3a9 9 0 0 0 0 18 4.5 4.5 0 0 0 0-9 4.5 4.5 0 0 1 0-9z"/></svg>
                 <span>Appearance</span>
               </button>
+              <button type="button" class="set-rail-item" data-section="settings-animations">
+                <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3l1.8 4.7L18.5 9.5l-4.7 1.8L12 16l-1.8-4.7L5.5 9.5l4.7-1.8z"/><path d="M19 15l.8 2.2L22 18l-2.2.8L19 21l-.8-2.2L16 18l2.2-.8z"/><path d="M3 19h6"/></svg>
+                <span>Animations</span>
+              </button>
               <button type="button" class="set-rail-item" data-section="settings-models">
                 <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3l8 4.5v9L12 21l-8-4.5v-9L12 3z"/><path d="M12 12l8-4.5M12 12v9M12 12L4 7.5"/></svg>
                 <span>Models</span>
@@ -1937,6 +1962,17 @@
                     <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>
 
@@ -1991,6 +2027,20 @@
                     </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>
 
@@ -2021,7 +2071,7 @@
                 <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"><circle cx="12" cy="12" r="9"/><path d="M12 3a9 9 0 0 0 0 18 4.5 4.5 0 0 0 0-9 4.5 4.5 0 0 1 0-9z"/></svg>
                 <h2>Appearance</h2>
               </div>
-              <p class="set-section-blurb">Theme, motion, and what this install calls itself.</p>
+              <p class="set-section-blurb">Theme, and what this install calls itself.</p>
 
               <div class="set-group">
                 <div class="set-group-head"><h4>Theme</h4><span class="set-scope">device</span></div>
@@ -2045,21 +2095,6 @@
                       </optgroup>
                     </select>
                   </div>
-                  <div class="set-row has-field" data-search="entrance animations motion tabs windows">
-                    <div class="set-row-text">
-                      <span class="set-row-label">Entrance Animations</span>
-                      <span class="set-row-desc">How new tabs, panes and agent windows arrive. Add ?animlab=1 to the URL for per-surface control.</span>
-                    </div>
-                    <select id="appSettingsEntranceAnim" class="set-select">
-                      <option value="legacy">Off (default)</option>
-                      <option value="terminal">Terminal (CRT)</option>
-                      <option value="beamdown">Beam down</option>
-                      <option value="softfocus">Soft focus (blur)</option>
-                      <option value="quiet">Quiet</option>
-                      <option value="playful">Playful</option>
-                      <option value="custom">Custom (set in the lab)</option>
-                    </select>
-                  </div>
                 </div>
               </div>
 
@@ -2089,6 +2124,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>
@@ -2112,7 +2169,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>
@@ -2162,6 +2219,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>
@@ -2172,7 +2236,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>
@@ -2194,6 +2258,70 @@
               </div>
             </section>
 
+            <!-- ══ Animations ═══════════════════════════════════════════════
+                 Every entrance animation in one place (entrance-animations.js).
+                 All per-device localStorage keys, applied as they are picked,
+                 never part of PUT /api/settings. -->
+            <section class="set-section" id="settings-animations" data-label="Animations">
+              <div class="set-section-head">
+                <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"><path d="M12 3l1.8 4.7L18.5 9.5l-4.7 1.8L12 16l-1.8-4.7L5.5 9.5l4.7-1.8z"/><path d="M19 15l.8 2.2L22 18l-2.2.8L19 21l-.8-2.2L16 18l2.2-.8z"/><path d="M3 19h6"/></svg>
+                <h2>Animations</h2>
+              </div>
+              <p class="set-section-blurb">How tabs, terminal panes, agent windows and tiles arrive. All off by default, applied as you pick them.</p>
+
+              <div class="set-group">
+                <div class="set-group-head"><h4>Entrances</h4><span class="set-scope">device</span></div>
+                <div class="set-group-body">
+                  <div class="set-row has-field" data-search="entrance animations theme motion tabs windows panes lines">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Entrance Theme</span>
+                      <span class="set-row-desc">One look for how new tabs, terminal panes, agent windows and their lines arrive.</span>
+                    </div>
+                    <select id="appSettingsEntranceAnim" class="set-select">
+                      <option value="legacy">Off (default)</option>
+                      <option value="terminal">Terminal (CRT)</option>
+                      <option value="beamdown">Beam down</option>
+                      <option value="launch">Launch (tiles fly from tabs)</option>
+                      <option value="softfocus">Soft focus (blur)</option>
+                      <option value="quiet">Quiet</option>
+                      <option value="playful">Playful</option>
+                      <option value="custom">Custom (set in the lab)</option>
+                    </select>
+                  </div>
+                  <div class="set-row has-field" data-search="tile animations tiles grid motion entrance fly deal crt beam">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Tile Animations</span>
+                      <span class="set-row-desc">How tiles arrive when the grid opens and leave when it closes. A theme above presets it.</span>
+                    </div>
+                    <select id="appSettingsTileAnim" class="set-select">
+                      <option value="settle">Off (default)</option>
+                      <option value="fly">Fly from tab</option>
+                      <option value="deal">Deal</option>
+                      <option value="crt">CRT</option>
+                      <option value="beam">Beam down</option>
+                      <option value="cascade">Cascade</option>
+                      <option value="pop">Pop</option>
+                      <option value="soft">Soft</option>
+                      <option value="off">None (tiles just appear)</option>
+                    </select>
+                  </div>
+                </div>
+              </div>
+
+              <div class="set-group">
+                <div class="set-group-head"><h4>Lab</h4></div>
+                <div class="set-group-body">
+                  <div class="set-row has-field" data-search="animation lab compare replay styles per surface animlab">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Animation Lab</span>
+                      <span class="set-row-desc">Closes settings and opens every style per surface side by side, with replay and speed. Same as adding ?animlab=1 to the URL.</span>
+                    </div>
+                    <button type="button" id="appSettingsOpenAnimLab" class="btn-toolbar btn-sm">Open lab</button>
+                  </div>
+                </div>
+              </div>
+            </section>
+
             <!-- ══ Models ═══════════════════════════════════════════════════ -->
             <section class="set-section" id="settings-models" data-label="Models">
               <div class="set-section-head">
@@ -2546,6 +2674,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>
@@ -2566,17 +2718,17 @@
               <div class="set-group" id="mcpSyncGroup">
                 <div class="set-group-head"><h4>MCP servers</h4><span class="set-scope">synced</span></div>
                 <div class="set-group-body">
-                  <div class="set-row" data-search="mcp server sync enable claude codex gemini opencode antigravity">
+                  <div class="set-row" data-search="mcp server sync enable claude codex gemini opencode antigravity copilot github">
                     <div class="set-row-text">
                       <span class="set-row-label">Enable MCP server sync</span>
-                      <span class="set-row-desc">Adds a control that copies MCP servers between your enabled CLIs by writing their own config files. Off by default: this changes other tools' configuration, not just Codeman's.</span>
+                      <span class="set-row-desc">Adds a control that copies MCP servers between your enabled CLIs, and GitHub Copilot CLI if it is installed, by writing their own config files. Off by default: this changes other tools' configuration, not just Codeman's.</span>
                     </div>
                     <label class="switch switch-sm"><input type="checkbox" id="appSettingsMcpSync" onchange="app.applyMcpSyncVisibility()"><span class="slider"></span></label>
                   </div>
                   <div class="set-row" id="mcpSyncActionRow" style="display:none" data-search="mcp server sync preview">
                     <div class="set-row-text">
                       <span class="set-row-label">Sync MCP servers across CLIs</span>
-                      <span class="set-row-desc">Copies each installed, enabled CLI's MCP servers into the others. Only adds missing servers; never edits, removes or copies a server you switched off. Env values and headers are copied too, so a file that receives them is left readable by you only. The previous file is kept as <code>.codeman-bak</code> (overwritten by each sync). A config dir moved by the CLI's own env var (<code>CODEX_HOME</code>, <code>CLAUDE_CONFIG_DIR</code>, <code>XDG_CONFIG_HOME</code>, <code>GEMINI_CLI_HOME</code>) is followed as Codeman's server sees it; a per-session override is not.</span>
+                      <span class="set-row-desc">Copies each installed, enabled CLI's MCP servers (and GitHub Copilot CLI's) into the others. Only adds missing servers; never edits, removes or copies a server you switched off. Env values and headers are copied too, so a file that receives them is left readable by you only. The previous file is kept as <code>.codeman-bak</code> (overwritten by each sync). A config dir moved by the CLI's own env var (<code>CODEX_HOME</code>, <code>CLAUDE_CONFIG_DIR</code>, <code>XDG_CONFIG_HOME</code>, <code>GEMINI_CLI_HOME</code>, <code>COPILOT_HOME</code>) is followed as Codeman's server sees it; a per-session override is not.</span>
                     </div>
                     <span>
                       <button class="btn-toolbar btn-sm" id="mcpSyncPreviewBtn" onclick="app.mcpSync(false)">Preview</button>
@@ -2645,6 +2797,26 @@
                       <span class="set-unit">min</span>
                     </div>
                   </div>
+                  <div class="set-row" data-search="toast display time popup dismiss seconds notification">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Toast display time</span>
+                      <span class="set-row-desc">How long the corner pop-ups stay on screen.</span>
+                    </div>
+                    <div class="set-row-actions">
+                      <input type="number" id="appSettingsNotifToastSecs" class="set-num" value="3" min="1" max="300">
+                      <span class="set-unit">sec</span>
+                    </div>
+                  </div>
+                  <div class="set-row" data-search="browser notification auto close dismiss seconds">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Browser notification display time</span>
+                      <span class="set-row-desc">How long a desktop notification stays up before Codeman closes it. Your OS may close it sooner.</span>
+                    </div>
+                    <div class="set-row-actions">
+                      <input type="number" id="appSettingsNotifBrowserSecs" class="set-num" value="8" min="1" max="300">
+                      <span class="set-unit">sec</span>
+                    </div>
+                  </div>
                 </div>
               </div>
 
@@ -2952,10 +3124,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>
@@ -2963,6 +3131,7 @@
         </div>
         <div class="form-actions set-foot">
           <button class="btn-toolbar" onclick="app.closeAppSettings()">Cancel</button>
+          <button class="btn-toolbar" onclick="app.applyAppSettings()" title="Save and keep Settings open">Apply</button>
           <button class="btn-toolbar btn-primary" onclick="app.saveAppSettings()">Save</button>
         </div>
       </div>
@@ -3965,5 +4134,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);
@@ -3507,7 +3552,7 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
   }
 
   /* Save + Close are the two ways out of the sheet (save-and-close vs
-     discard-and-close), hit in the same corner with the same thumb, so here —
+     discard-and-close; Apply saves but keeps the sheet open), hit in the same corner with the same thumb, so here —
      and only here, since Save is header-only below 860px — they share a
      recessed tray and matching pill geometry instead of reading as a fat
      accent pill parked beside a stray × glyph. Tray colors come from skin
@@ -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/notification-manager.js

@@ -4,7 +4,7 @@
  * The NotificationManager class implements five notification layers:
  *   1. In-app notification drawer (slide-out panel with grouped notifications)
  *   2. Tab title flash (alternating "⚠️ (N) codeman:<host>" / "codeman:<host>" when tab is hidden; uses this.originalTitle so it tracks any per-host title)
- *   3. Browser Notification API (desktop push with auto-close after 8s)
+ *   3. Browser Notification API (desktop push; auto-closes after 8s by default, configurable per device in Settings → Notifications)
  *   4. Web Push via service worker (OS-level notifications when tab is closed)
  *   5. Audio alerts (Web Audio API beep, user-opt-in)
  *
@@ -93,6 +93,10 @@ class NotificationManager {
       browserNotifications: !isMobile,
       audioAlerts: false,
       stuckThresholdMs: STUCK_THRESHOLD_DEFAULT_MS,
+      // How long a corner toast stays on screen, and how long a browser notification
+      // stays up before Codeman closes it (ms; per-device like the rest of these)
+      toastDurationMs: DEFAULT_TOAST_DURATION_MS,
+      browserAutoCloseMs: AUTO_CLOSE_NOTIFICATION_MS,
       // Legacy urgency muting (keep for backwards compat)
       muteCritical: false,
       muteWarning: false,
@@ -167,11 +171,24 @@ class NotificationManager {
     return {
       ...defaults,
       ...prefs,
+      toastDurationMs: this.clampDuration(prefs.toastDurationMs, defaults.toastDurationMs),
+      browserAutoCloseMs: this.clampDuration(prefs.browserAutoCloseMs, defaults.browserAutoCloseMs),
       eventTypes: { ...defaults.eventTypes, ...prefs.eventTypes },
       _version: 5,
     };
   }
 
+  /** A display time in ms kept within [1s, 5min]; anything unusable falls back to the default. */
+  clampDuration(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+    return Math.min(MAX_NOTIFICATION_DURATION_MS, Math.max(MIN_NOTIFICATION_DURATION_MS, Math.round(value)));
+  }
+
+  /** Display time for corner toasts that do not set their own `duration`. */
+  getToastDurationMs() {
+    return this.clampDuration(this.preferences?.toastDurationMs, DEFAULT_TOAST_DURATION_MS);
+  }
+
   loadPreferences() {
     try {
       const storageKey = this.getStorageKey();
@@ -403,7 +420,7 @@ class NotificationManager {
     };
 
     // Auto-close
-    setTimeout(() => notif.close(), AUTO_CLOSE_NOTIFICATION_MS);
+    setTimeout(() => notif.close(), this.clampDuration(this.preferences.browserAutoCloseMs, AUTO_CLOSE_NOTIFICATION_MS));
   }
 
   async requestPermission() {

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;
@@ -5812,7 +5862,8 @@ Object.assign(CodemanApp.prototype, {
   },
 
   /**
-   * `duration` defaults to 3000ms for every toast type. A message worth
+   * `duration` defaults to the "Toast display time" preference (3000ms unless changed in
+   * Settings → Notifications) for every toast type. A message worth
    * reading rather than glancing at (e.g. "Session started on the native
    * backend — could not apply the custom endpoint: <the actual reason>")
    * passes an explicit `opts.duration: 0` at its own call site instead of
@@ -5824,7 +5875,7 @@ Object.assign(CodemanApp.prototype, {
    * regardless of duration.
    */
   showToast(message, type = 'info', opts = {}) {
-    const { duration = 3000, action } = opts;
+    const { duration = this.notificationManager?.getToastDurationMs?.() ?? 3000, action } = opts;
     const toast = document.createElement('div');
     toast.className = `toast toast-${type}`;
 
@@ -6028,6 +6079,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 +6101,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
-
-      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);
-      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.
-      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('class', 'lineage-line-dot' + working + (proxied ? ' lineage-line-dot--proxied' : ''));
-      dot.setAttribute('data-child-tab', edge.childId);
-      if (color) dot.style.setProperty('--lineage-color', color);
-      svg.appendChild(dot);
+      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', 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:' + 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(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', child.edge.childId);
+        if (color) dot.style.setProperty('--lineage-color', color);
+        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);
@@ -1803,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.
@@ -2082,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}...`,
@@ -2434,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
@@ -3094,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);
         }

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;
@@ -430,7 +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 ?? 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
@@ -454,6 +455,8 @@ Object.assign(CodemanApp.prototype, {
     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
@@ -484,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({
@@ -501,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(
@@ -527,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;
@@ -554,6 +564,12 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsNotifBrowser').checked = notifPrefs.browserNotifications ?? false;
     document.getElementById('appSettingsNotifAudio').checked = notifPrefs.audioAlerts ?? false;
     document.getElementById('appSettingsNotifStuckMins').value = Math.round((notifPrefs.stuckThresholdMs || 600000) / 60000);
+    document.getElementById('appSettingsNotifToastSecs').value = Math.round(
+      (this.notificationManager?.getToastDurationMs?.() ?? DEFAULT_TOAST_DURATION_MS) / 1000
+    );
+    document.getElementById('appSettingsNotifBrowserSecs').value = Math.round(
+      (notifPrefs.browserAutoCloseMs ?? AUTO_CLOSE_NOTIFICATION_MS) / 1000
+    );
     document.getElementById('appSettingsNotifCritical').checked = !notifPrefs.muteCritical;
     document.getElementById('appSettingsNotifWarning').checked = !notifPrefs.muteWarning;
     document.getElementById('appSettingsNotifInfo').checked = !notifPrefs.muteInfo;
@@ -1211,15 +1227,15 @@ Object.assign(CodemanApp.prototype, {
   /** Preview (apply=false) or run (apply=true) the MCP server sync across enabled CLIs. */
   async mcpSync(apply) {
     const out = this.$('mcpSyncResult');
-    const show = (html) => {
-      if (out) { out.style.display = 'block'; out.innerHTML = html; }
+    const show = (html, hint = '') => {
+      if (out) { out.style.display = 'block'; out.innerHTML = html; out.dataset.hint = hint; }
     };
     // Switched on in this modal but not saved yet: the routes would only answer "disabled".
     if (!this._mcpSyncSavedOn) {
-      show('Save settings to turn MCP sync on first, then reopen Settings to preview or sync.');
+      show('Apply or Save settings to turn MCP sync on first, then preview or sync.', 'save-first');
       return;
     }
-    if (apply && !confirm('Add missing MCP servers to every installed, enabled CLI\'s config file? Env values and headers on those servers are copied too.')) return;
+    if (apply && !confirm('Add missing MCP servers to every installed, enabled CLI\'s config file (and GitHub Copilot CLI\'s, when it is installed)? Env values and headers on those servers are copied too.')) return;
     show('Working…');
     const res = apply ? await this._apiPost('/api/mcp-sync', {}) : await this._api('/api/mcp-sync');
     let body = null;
@@ -1642,40 +1658,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 : [];
+    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.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 = () => {
-        this.setRunMode(cli.id);
-        void this.run();
-      };
-      container.appendChild(btn);
+    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);
   },
 
   /**
@@ -1709,17 +1773,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 {
@@ -1729,11 +1792,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();
@@ -2455,7 +2513,31 @@ Object.assign(CodemanApp.prototype, {
     claudeEl.className = 'voice-provider-status' + (status?.available ? ' active' : '');
   },
 
+  /**
+   * Apply button: the same save as Save, but the modal stays open and the MCP sync group (its
+   * Preview and Sync need the saved flag) and the CLI management writes are refreshed in place, so
+   * turning either on needs no close-and-reopen. It is a wrapper rather than an option on
+   * saveAppSettings() so that function's signature (which tests locate by text) stays as it was.
+   *
+   * `_keepSettingsOpenOnce` is the one-shot intent and `_applyInFlight` the double-click guard:
+   * saveAppSettings() consumes the intent before its first await, so a Save clicked while an Apply
+   * is still in flight is an ordinary Save and closes the modal.
+   */
+  async applyAppSettings() {
+    if (this._applyInFlight) return;
+    this._applyInFlight = true;
+    this._keepSettingsOpenOnce = true;
+    try {
+      await this.saveAppSettings();
+    } finally {
+      this._applyInFlight = false;
+      this._keepSettingsOpenOnce = false;
+    }
+  },
+
   async saveAppSettings() {
+    const keepOpen = this._keepSettingsOpenOnce === true;
+    this._keepSettingsOpenOnce = false;
     // Gesture overlay is injected at page render (server-side), so a change to it
     // only takes effect on reload — remember the prior value to decide below.
     const _prev = this.loadAppSettingsFromStorage();
@@ -2476,6 +2558,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,
@@ -2504,6 +2587,9 @@ Object.assign(CodemanApp.prototype, {
       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,
@@ -2522,10 +2608,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(
@@ -2536,6 +2625,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
@@ -2555,6 +2646,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
@@ -2599,6 +2699,8 @@ Object.assign(CodemanApp.prototype, {
       browserNotifications: document.getElementById('appSettingsNotifBrowser').checked,
       audioAlerts: document.getElementById('appSettingsNotifAudio').checked,
       stuckThresholdMs: (parseInt(document.getElementById('appSettingsNotifStuckMins').value) || 10) * 60000,
+      toastDurationMs: (parseInt(document.getElementById('appSettingsNotifToastSecs').value) || 3) * 1000,
+      browserAutoCloseMs: (parseInt(document.getElementById('appSettingsNotifBrowserSecs').value) || 8) * 1000,
       muteCritical: !document.getElementById('appSettingsNotifCritical').checked,
       muteWarning: !document.getElementById('appSettingsNotifWarning').checked,
       muteInfo: !document.getElementById('appSettingsNotifInfo').checked,
@@ -2668,7 +2770,7 @@ Object.assign(CodemanApp.prototype, {
       _version: 5,
     };
     if (this.notificationManager) {
-      this.notificationManager.preferences = notifPrefsToSave;
+      this.notificationManager.preferences = this.notificationManager.normalizePreferences(notifPrefsToSave);
       this.notificationManager.savePreferences();
     }
 
@@ -2762,6 +2864,8 @@ Object.assign(CodemanApp.prototype, {
       // 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,
@@ -2769,9 +2873,17 @@ 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 = '';
+    let serverSaved = false;
     try {
       const res = await this._apiPut('/api/settings', {
         ...serverSettings,
@@ -2789,10 +2901,14 @@ Object.assign(CodemanApp.prototype, {
         this.saveAppSettingsToStorage(settings);
         const cb = document.getElementById('appSettingsTunnelEnabled');
         if (cb) cb.checked = false;
-        this.closeAppSettings();
+        if (!keepOpen) this.closeAppSettings();
         return;
       }
 
+      // `_apiPut` answers null or a non-ok response instead of throwing, so this is the only
+      // evidence the server kept the flags the Apply refresh below reads.
+      serverSaved = !!res?.ok;
+
       // Save model configuration separately
       await this.saveModelConfigFromSettings();
 
@@ -2804,7 +2920,7 @@ Object.assign(CodemanApp.prototype, {
       if (webhookError) {
         this.showToast(`Settings saved, but not the webhook: ${webhookError}`, 'warning');
       } else {
-        this.showToast('Settings saved', 'success');
+        this.showToast(keepOpen ? 'Settings applied' : 'Settings saved', 'success');
       }
 
       // Show tunnel-specific feedback if toggled on
@@ -2816,9 +2932,13 @@ Object.assign(CodemanApp.prototype, {
       this.showToast('Settings saved locally', 'warning');
     }
 
+    // Only when the settings PUT landed: after a 400 or a dropped connection the server still has the
+    // old flags, and a webhook-only failure still saved the rest, so this runs ahead of that branch.
+    if (keepOpen && serverSaved) this._refreshSettingsAfterApply(settings);
+
     if (webhookError) {
       document.getElementById('webhookGroup')?.scrollIntoView({ block: 'center' });
-    } else {
+    } else if (!keepOpen) {
       this.closeAppSettings();
     }
 
@@ -2839,6 +2959,25 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * After Apply: bring the groups whose contents depend on a SAVED value up to date without
+   * reopening the modal. openAppSettings does the same on open; this is the part of it that
+   * a save can change, without touching what the user is editing or the scroll position.
+   */
+  _refreshSettingsAfterApply(settings) {
+    // The MCP routes read the saved flag, so switching it on is only usable from now.
+    this._mcpSyncSavedOn = settings.mcpSyncEnabled === true;
+    const out = this.$('mcpSyncResult');
+    if (this._mcpSyncSavedOn && out && out.dataset?.hint === 'save-first') {
+      out.style.display = 'none';
+      out.innerHTML = '';
+    }
+    this.applyMcpSyncVisibility();
+    this.applyCustomModelEndpointsVisibility();
+    this.applyCliManagementVisibility();
+    this._applyDoctorAdminGate();
+  },
+
   // Load model configuration from server for the settings modal
   async loadModelConfigForSettings() {
     try {
@@ -3165,12 +3304,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),
     }));
@@ -3450,10 +3595,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,
@@ -3464,7 +3612,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() {
@@ -3481,8 +3636,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;
   },
 
@@ -3528,6 +3690,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,
@@ -3555,6 +3721,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();
@@ -3563,7 +3814,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);
@@ -3585,6 +3840,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
@@ -3639,7 +3900,7 @@ Object.assign(CodemanApp.prototype, {
     this._applySplitButtonVisibility?.(showSplitButton);
 
     // Tiles button: same gate and backstop as Split (tile-grid.js).
-    const showTileGridButton = settings.showTileGridButton ?? defaults.showTileGridButton ?? false;
+    const showTileGridButton = settings.showTileGridButton ?? defaults.showTileGridButton ?? true;
     this._applyTileGridButtonVisibility?.(showTileGridButton);
 
     // Ultracode/Workflow agents launcher — hidden by default; reveal when enabled.
@@ -3736,6 +3997,10 @@ Object.assign(CodemanApp.prototype, {
           })
         : 'horizontal';
 
+    // The search box lives in the rail: a search left applied after the list
+    // moves out would hide tabs with no box to clear it from.
+    if (orientation !== 'vertical' && this._tabRailSearch) this._resetTabRailSearch?.();
+
     const root = document.documentElement;
     const previous = root.getAttribute('data-tab-orientation') || 'horizontal';
     root.setAttribute('data-tab-orientation', orientation);
@@ -3756,6 +4021,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');
@@ -3779,7 +4065,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?.();
@@ -3804,6 +4090,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
@@ -4049,16 +4343,16 @@ 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', 'showGitStatus', 'gitStatusTree',
+          'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds',
           'showTabDetachButton',
           'mobileOverviewEnabled',
           'sessionLineageLines',