chore: version packages

Codex plan usage in the header chip (#346), a visible inline rename in
the session sidebar (#345), and the install.sh Tailscale re-run fix plus
the README network-access prompt description.

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

CHANGELOG.md

@@ -1,5 +1,85 @@
 # aicodeman
 
+## 1.23.2
+
+### Patch Changes
+
+- Codex plan usage in the header chip, a visible inline rename in the session sidebar, and an installer that no longer loses Tailscale access on a re-run.
+
+  **Codex plan usage in the header chip** (#346): the plan-usage chip used to show Claude's 5-hour and weekly limits without saying they were Claude's, which stops being a detail the moment you run more than one CLI. It now renders one compact row per provider, Claude above Codex, each labelled and colour-coded by how much is used up. Claude's numbers still come from Codeman's marked `statusLine.command` exporter; Codex's come from the signed-in host CLI's read-only `account/rateLimits/read` app-server request at startup and every five minutes, so credentials stay inside the CLI and no auth material reaches the browser. Only the main `codex` bucket is read (model-specific buckets such as Spark are separate limits and are deliberately excluded), and the Codex row is omitted entirely when no 5-hour or weekly window is available, rather than inventing one.
+
+  **Inline rename is visible in the session sidebar** (#345): starting a rename on a sidebar row opened a focused input you could not see. The row's ellipsis clamp was still painting over the live editor, so text and caret went in blind. The sidebar now gets the same unclamped editor layout the vertical tab rail already had. Covered by a Chromium regression test that asserts the painted `overflow` and the input's measured width, not just the class name.
+
+  **install.sh keeps Tailscale access on a re-run**: a re-run whose build failed could drop a working Tailscale binding instead of preserving it. The installer now offers Tailscale setup again on re-run rather than losing it, and the README describes the three-way network-access prompt (Tailscale / LAN / local-only) as it actually behaves.
+
+  ### Thanks
+  - @JackStuart for #346
+  - @fibr for #345
+  - @tailong-wu for #342, whose analysis of the terminal refresh replay loop matched a fix that had landed on master a few hours earlier
+
+## 1.23.1
+
+### Patch Changes
+
+- Fix a fresh-Linux install failure, and bound the browser terminal's live write queue.
+
+  **install.sh now installs a build toolchain.** Reported against a stock Ubuntu 24 server: node-pty publishes prebuilt binaries for darwin and win32 only, so on Linux it is always compiled from source during `npm install`. The installer set up Node, tmux and git but never a compiler, so a machine without `build-essential` died deep inside node-gyp with `not found: make` — which reads like an npm bug rather than a missing system package. `make`, a C++ compiler and `python3` are now checked up front exactly like git and tmux, installed per distro (apt / dnf / pacman / apk / zypper) behind the same consent prompt, and re-verified afterwards rather than assumed. If `npm install` fails anyway — including on `install.sh update` — it now names the missing tools and the command that installs them instead of leaving a node-gyp stack trace as the last word.
+
+  **Bounded live xterm backpressure** (#339): live output is now one chunk in flight at a time, released by xterm's own parse callback, so xterm's private WriteBuffer can no longer hide an unbounded backlog behind the browser's 128 KiB render cap; queued, loading and incoming bytes all count against that cap. Automatic drop recovery for a shell stays on the bounded 1 MiB tail — a 100k-line shell capture is tens of MiB, and parsing it on the main thread is the freeze the cap exists to prevent — while TUI modes still recover full history behind the existing downgrade guard. Duplicate SSE terminal events are dropped before JSON parsing while WebSocket owns terminal I/O, and recovery is single-flight per active session. Follow-up hardening: the three write-queue reset paths now also release the in-flight gate, so a parse callback that never lands cannot leave live output permanently stalled.
+
+  **File Viewer searches the workspace** (#340): the File Viewer search box now queries the server-side file search endpoint with a 250 ms debounce and strict response validation, instead of filtering only the part of the tree already loaded. Tree and search state are scoped to the active session, the hidden-file preference and independent request epochs, so a stale response cannot repaint the panel; cached-tree restoration, directory results and reset behaviour survive session switches and both panel-hide paths.
+
+  ### Thanks
+  - @dignfei for #339
+  - @aakhter for #340
+
+- 858b15e: Search the full session workspace from File Viewer while keeping results scoped to the active session and hidden-file preference.
+
+## 1.23.0
+
+### Minor Changes
+
+- DeepSeek Harness as a ninth run mode, DeepSeek agent workers, and detailed rows for the vertical tab rail.
+
+  **DeepSeek Harness (`dsh`) run mode** (#337): DeepSeek's plugin-native agent framework joins Claude Code, shell, OpenCode, Codex, Gemini, Antigravity, Pi and Grok as a run mode. The harness is a profile launcher rather than an agent, so availability is two questions (binary AND a pane-capable profile): the Run button gates on both, a missing terminal profile is offered as a one-click install (`POST /api/deepseek/install-profile`, the only endpoint in Codeman that installs third-party code, fenced accordingly), and the resolver demands the harness's own help banner so Debian's unrelated `dsh` (dancer's shell) can never be spawned. Its permission switch is the `DSH_PERMISSION_MODE` env export (the harness has no bypass flag), injected via tmux setenv and clamped for non-granted owners in multi-user mode, including the env-override path. The community TUI's supervisor-reporting contract makes deepseek the first non-Claude mode with REAL lifecycle signals: a generated status shim turns its idle/working/blocked reports into definitive `stop`/`permission_prompt`/`agent_working` hook events, so dsh sessions get real respawn triggers, real wait signals and red "needs you" alerts instead of output-stabilization guesswork. The vendor's browser UI opens as a managed web tab through a background `dsh web` fenced to Codeman's origin. Docker image support included.
+
+  **DeepSeek agent workers** (#341): the codeman agent skill can spawn and drive dsh workers like claude ones — tasked, waited on and read with the same calls. `GET /api/sessions/:id/last-response` reads the harness's real zstd transcript (one frame per append; the reader walks frame boundaries itself, since a naive decode silently truncates to the first frame), distinguishes real prompts from plugin-injected context, and reports a failed turn's provider error instead of an empty answer.
+
+  **Vertical tab rail: detailed rows** (#338): the vertical rail can now show the home screen's per-session line (created stamp, state duration, status pill) via the new per-device `tabRailDetail` setting (default detailed; `simple` restores the 1.22.0 rows). One shared row model and one gate (`isRichTabRows()`) keep the rail, the rich sidebar and both home screens in agreement about what "working" means. A never-sized rail opens at the 320px Wide preset; below 288px the created stamp is dropped, below 240px rows fall back to simple. Also fixes Escape during an inline tab rename committing an empty name (the session then displayed its folder name).
+
+  **Review hardening across all three** (post-review commits on each PR): multi-user owners without the bypass grant can no longer redirect the server's forwarded `DEEPSEEK_API_KEY` via a `DEEPSEEK_BASE_URL` override; waits on `stop`/`blocked` are refused for docker/remote dsh sessions (their status bridge cannot reach the harness) and docker/remote dsh sessions keep the pane reader (their transcripts are not local); dsh approvals are alerts answered in the terminal, never blind keystrokes into a third-party TUI; the status shim forwards the contract's `--seq` token (stale retried reports are dropped server-side) and treats 4xx as permanent so a misconfigured session cannot rate-limit the hook endpoint for the whole instance; concurrent DeepSeek web-UI starts are serialized; cron deepseek jobs run the same launch gate as the HTTP paths; the installer's dsh identity probe is stdin-closed, bounded and memoized; transcript reads are memoized per (path, mtime, size) so 1s polling stops decoding unchanged files; the rail's width dialog, compact-threshold folder rows and reset affordances are rich-aware.
+
+### Patch Changes
+
+- b330f1d: Vertical tab rail: detailed rows, and a rename cancel that no longer wipes the name.
+
+  The vertical rail (Tab Orientation → Vertical) now draws the same per-session
+  line the home screen and the rich sidebar draw — when the session was created,
+  how long it has been in the state it is in, the folder it runs in, and a status
+  pill — instead of just the name. New per-device setting **Vertical Rail Rows**
+  (`tabRailDetail`, App Settings → Appearance → Tabs) with `Detailed` as the
+  default and `Simple (name only)` as the opt-out. A rail that has never been
+  sized now opens at 320px (the existing Wide preset) so the line fits; a narrower
+  rail sheds the created stamp below 288px and falls back to simple rows below
+  240px.
+
+  Also fixes a data-loss bug in the inline tab rename that predates the rail:
+  pressing Escape cleared the input and blurred it, and the blur handler commits —
+  so cancelling a rename stored an EMPTY session name and the tab fell back to its
+  folder label. Escape now cancels without a request, in every layout.
+
+## 1.22.0
+
+### Minor Changes
+
+- 3f8c8e9: Add Grok Build (xAI `grok`) as a seventh CLI run mode. SessionMode gains 'grok', with its own resolver (version-probed, since the name has npm squatters; GET /api/grok/status surfaces path + version), GrokConfig (model, alwaysApprove -> --always-approve, resume/continue), GROK*\*/XAI*\* env allowlist entries, the multi-user only-if-sent bypass clamp, Docker (own image step + per-file credential seeding) and remote-SSH command defaults, cron agentType, run-mode/welcome/tab UI with a charcoal identity, and docs (grok-integration.md + plan). Verified end to end against grok 1.0.5 on an isolated instance.
+- 74194e4: Add the owner-scoped tab-layout model, persistence, API, lifecycle repair, and synchronized legacy ordering foundation.
+- e3a2fb7: Add an optional resizable vertical session rail with responsive layout, complete labels, accessible controls, and stable inline rename.
+
+### Patch Changes
+
+- Fix the file preview's dead pop-out control: a real detach button now opens the previewed file in a browser tab (raw route for PDFs/images/media/text, converted-PDF preview for docx/pptx) and the copy button reports when a preview has no text to copy instead of silently doing nothing. Review-driven hardening for the new tab features: PUT /api/session-order drops unknown ids again instead of rejecting the whole write (a session deleted inside the browser's debounce window could silently lose the user's reorder), a failed mux restore no longer blocks explicit session/webview deletion for the process lifetime (the automated stale sweep stays fail-closed), and the vertical rail gains the axis-awareness the sidebar-only predicates missed: correct drag-reorder insertion, active-tab scroll-into-view, floating windows anchored beside rail tabs, connector redraws on rail scroll, server-seeded orientation applied on first load, a pre-paint stamp so vertical mode no longer flashes through the header strip, and a 12px session-name default matching the sidebar's historical size so untouched installs are not restyled.
+
 ## 1.21.0
 
 ### Minor Changes

README.md

@@ -5,7 +5,7 @@
 <h2 align="center">Mission control for AI coding agents</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Terminal - One Dashboard &bull; Any Device</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Grok &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>
 
 <p align="center">
@@ -27,7 +27,7 @@
   <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — parallel subagent visualization" width="900">
 </p>
 
-**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, or Pi 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.
+**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, or Grok 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.
 
 Get started in one line (macOS & Linux, Windows via WSL):
 
@@ -42,7 +42,7 @@ codeman web
 
 The installer asks before every system change, and re-running the same line updates in place. Full details: [Quick Start - Installation](#quick-start---installation).
 
-- **One dashboard, six CLIs** - run [Claude Code, OpenCode, Codex, Antigravity, Gemini, or Pi](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
+- **One dashboard, seven CLIs** - run [Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, or Grok](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
 - **Truly phone-friendly** - a [touch-optimized terminal](#mobile-optimized-web-ui) with instant local echo, QR login, swipe navigation, and push notifications
 - **Runs while you sleep** - [idle detection + respawn cycling](#respawn-controller) and auto-resume when a subscription limit resets, for 24+ hour unattended runs
 - **See your agents think** - [live floating windows](#live-agent-visualization) for every subagent and teammate, with real-time transcripts
@@ -61,14 +61,14 @@ The installer asks before every system change, and re-running the same line upda
 curl -fsSL https://getcodeman.com/install | bash
 ```
 
-This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
+This installs Node.js, tmux and a build toolchain if missing (node-pty ships no Linux prebuilds, so it compiles from source), clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
 
 - **It asks first.** Every system change (package installs, AI CLI download) is prompted, and a menu at the end lets you choose: run Codeman in this terminal, install it as a background service (systemd/launchd, auto-start on boot), or don't start yet. Nothing runs in the background unless you pick it.
-- **Network or local-only, your choice.** The installer asks whether the dashboard should be reachable from other devices on your network (`0.0.0.0`, the default, with a strongly recommended password prompt) or from this machine only (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. A bare `codeman web` started by hand still defaults to loopback.
+- **How it's reachable, your choice.** The installer offers three ways to reach the dashboard: **Tailscale** (loopback bind fronted by `tailscale serve`, so you get `https://<machine>.<tailnet>.ts.net` with a real certificate and your tailnet as the login, no password needed), **any device on your network** (`0.0.0.0`, with a strongly recommended password prompt), or **this machine only** (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. The highlighted default reflects what is already on the machine (Tailscale when it is already in use, your existing binding on a re-run), and a bare Enter never pulls in new software. A bare `codeman web` started by hand still defaults to loopback.
 - **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh update` and `install.sh uninstall` also exist.
 - **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
 
-You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi](https://pi.dev) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the six is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
+You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi](https://pi.dev), or [Grok Build](https://github.com/xai-org/grok-build) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the seven is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
 
 ```bash
 codeman web
@@ -171,7 +171,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi](https://pi.dev)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi](https://pi.dev), or [Grok Build](https://github.com/xai-org/grok-build)). After installing, `http://localhost:3000` is accessible from your Windows browser.
 
 </details>
 
@@ -253,7 +253,7 @@ Click **+ New Session** (or **Quick Start**). A session is one AI CLI running in
 | Field                        | What it does                                                                                                        |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers. **Add Case** creates one from scratch, links an existing folder, or clones a GitHub repo straight into one (**Clone Repo**). |
-| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Antigravity`, `Gemini`, `Pi`, or `Terminal` (plain shell).                 |
+| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Antigravity`, `Gemini`, `Pi`, `Grok`, or `Terminal` (plain shell).         |
 | **Model**                    | Per-session model (App Settings → Models → New Claude sessions). A soft default — `/model` still works in-session.                  |
 | **Effort / Ultracode**       | Reasoning effort (`low`–`max`) or `ultracode` for dynamic multi-agent workflows. Switchable anytime with `/effort`. |
 
@@ -437,7 +437,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 - **Background daemon & service install** — `codeman web -d` runs the server detached with a pidfile, `~/.codeman/web.log`, and verified startup (it polls the server until it answers, so a port clash never reads as success); `codeman service install` writes a systemd user unit (Linux) or LaunchAgent (macOS) with your shell's PATH baked in, so an nvm or Homebrew `node`, `tmux` and `claude` are actually found. Secrets are never written into unit files
 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → System → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
 - **Clone a GitHub repo as a case** — paste a repository URL into **Add Case → Clone Repo** and Codeman clones it into `~/codeman-cases/<name>` and registers it as a normal case, ready to run an agent in. It preflights the URL while you type (tells you whether it can be cloned anonymously and offers the repo's real branches and tags for the optional branch/tag field), fills the case name in from the URL, and lets you pick which CLI the Run button should use. Public repositories over `https://`; Codeman never collects or stores credentials
-- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, **Gemini**, or **Pi** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md) and [`docs/pi-integration.md`](docs/pi-integration.md)
+- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, **Gemini**, **Pi**, or **Grok** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*` vs `GROK_*`/`XAI_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md), [`docs/pi-integration.md`](docs/pi-integration.md) and [`docs/grok-integration.md`](docs/grok-integration.md)
 - **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
 - **Remote SSH sessions** — point a case at another machine and run the agent there inside a durable remote tmux: survives SSH drops, auto-reconnects, and can discover + attach sessions already running on the host. See [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too

README.zh-CN.md

@@ -5,7 +5,7 @@
 <h2 align="center">AI 编程智能体的任务控制中心</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Grok &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
 </p>
 
 <p align="center">
@@ -58,7 +58,7 @@ curl -fsSL https://getcodeman.com/install | bash
 - **重跑即更新。** 再次运行同一条命令即可原地更新已完成的安装：`~/.codeman/app` 中的本地改动会被 stash（绝不丢弃），运行中的服务会自动重启并校验。若首次安装中途失败，重跑会继续完成完整的安装流程。也可以使用 `install.sh update` 与 `install.sh uninstall`。
 - **CI / 无终端环境：** 没有终端时，涉及系统改动的步骤会带着说明中止，而不是静默执行；在自动化场景设置 `CODEMAN_NONINTERACTIVE=1` 即可批准这些步骤。
 
-你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google)、[Gemini CLI](https://github.com/google-gemini/gemini-cli) 或 [Pi](https://pi.dev)（任意组合均可；自 Google 面向消费者停售后，Gemini CLI 仅限企业版，Antigravity 是其继任者）。安装器会自动检测这六个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
+你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google)、[Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Pi](https://pi.dev) 或 [Grok Build](https://github.com/xai-org/grok-build)（任意组合均可；自 Google 面向消费者停售后，Gemini CLI 仅限企业版，Antigravity 是其继任者）。安装器会自动检测这七个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
 
 ```bash
 codeman web
@@ -141,7 +141,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google)、[Gemini CLI](https://github.com/google-gemini/gemini-cli) 或 [Pi](https://pi.dev)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google)、[Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Pi](https://pi.dev) 或 [Grok Build](https://github.com/xai-org/grok-build)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
 
 </details>
 
@@ -221,7 +221,7 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 | 字段                   | 作用                                                                                        |
 | ---------------------- | ------------------------------------------------------------------------------------------- |
 | **工作目录 / case**    | 智能体操作的文件夹。「case」就是一个 Codeman 记住的命名工作目录。                           |
-| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Antigravity`、`Gemini`、`Pi` 或 `Terminal`（普通 shell）。 |
+| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Antigravity`、`Gemini`、`Pi`、`Grok` 或 `Terminal`（普通 shell）。 |
 | **模型**               | 每会话模型（App Settings → Claude Model）。软默认值 —— 会话内 `/model` 依然有效。           |
 | **Effort / Ultracode** | 推理力度（`low`–`max`），或用 `ultracode` 开启动态多智能体工作流。随时可用 `/effort` 切换。 |
 
@@ -394,7 +394,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 ## 更多特性
 
 - **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
-- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex**、**Antigravity**、**Gemini** 或 **Pi**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*`、`ANTIGRAVITY_*`、`PI_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md) 与 [`docs/pi-integration.md`](docs/pi-integration.md)
+- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex**、**Antigravity**、**Gemini**、**Pi** 或 **Grok**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*`、`ANTIGRAVITY_*`、`PI_*`、`GROK_*`/`XAI_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)、[`docs/pi-integration.md`](docs/pi-integration.md) 与 [`docs/grok-integration.md`](docs/grok-integration.md)
 - **Docker 会话** —— 在隔离且加固的容器中运行案例。**Create New** 上勾选一个复选框即可用合理的默认值启动容器并在其中启动智能体；同一案例的多个会话共享一个容器；可将容器连同工作区导出为可移植的 `.tar.gz`，迁移到另一台机器。详见 [`docs/docker-cases.md`](docs/docker-cases.md)
 - **远程 SSH 会话**：把案例指向另一台机器，让智能体在那里一个持久的远程 tmux 中运行：SSH 断连不中断任务、自动重连，还能发现并附着主机上已在运行的会话。详见 [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置

config/test-suites.ts

@@ -19,6 +19,9 @@
  * why these are a runnable suite (`npm run test:browser`) rather than skipped.
  */
 export const BROWSER_TEST_GLOBS = [
+  'test/tab-rail-resize.browser.test.ts',
+  'test/session-sidebar-ux.browser.test.ts',
+  'test/session-options-responsive.browser.test.ts',
   'test/inline-rename.test.ts',
   'test/opencode-resize.test.ts',
   'test/webgl-fallback.test.ts',

docker/agent.Dockerfile

@@ -51,6 +51,35 @@ RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent \
  && npm cache clean --force \
  && pi --version
 
+# Grok Build (`grok`, xAI) is NOT on npm: a standalone ~160MB Rust binary through
+# xAI's installer, which targets $HOME/.grok/bin with no --dir override. At build
+# time that is root's home and unreachable by the `agent` user, so copy the binary
+# into /usr/local/bin and drop root's ~/.grok in the same layer so the image does
+# not carry the download twice. The staging cp -T is what makes this survive the
+# installer's own behavior EITHER way: newer installers already symlink
+# /usr/local/bin/grok -> /root/.grok/bin/grok, and a direct `cp -L` onto that
+# symlink fails with "same file" (2026-08-24 rebuild), while removing the link
+# first and copying fresh works for both old and new installers.
+RUN curl -fsSL https://x.ai/cli/install.sh | bash \
+ && cp -L /root/.grok/bin/grok /usr/local/bin/grok.real \
+ && rm -f /usr/local/bin/grok \
+ && mv /usr/local/bin/grok.real /usr/local/bin/grok \
+ && chmod 755 /usr/local/bin/grok \
+ && rm -rf /root/.grok /root/.local/bin/grok /root/.local/bin/agent \
+ && grok --version
+
+# DeepSeek Harness (`dsh`). A normal npm package, but the ONLY entry here whose
+# binary runs nothing on its own: `dsh` is a profile launcher, and DeepSeek ships
+# only `web` and `headless`, so without an interactive profile a
+# `mode: 'deepseek'` container would start a pane that dies on arrival. The
+# profile itself is installed further down, into the `agent` HOME, because
+# Codeman deliberately does NOT seed `profiles/` from the host: it is a
+# per-profile node_modules tree, host-arch-specific and far too large to copy on
+# every container start.
+RUN npm install -g @deepseek-ai/dsh \
+ && npm cache clean --force \
+ && dsh --version
+
 # `agent` user (gid 0) with an arbitrary-uid-writable HOME. The uid is
 # auto-assigned (node:22-slim already occupies uid 1000 with its `node` user); at
 # runtime Codeman overrides with `--user <hostUid>:0` on Linux, so the baked uid
@@ -68,11 +97,22 @@ ENV HOME=/home/agent
 # transcript/rollout dirs (`.claude/projects`, `.codex/sessions`) are bind-mounted from
 # the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir;
 # Antigravity nests its state inside `.gemini/antigravity-cli`, so it rides that seed.)
-# `.pi/agent` IS pre-created: pi is seeded per-FILE (auth/settings/trust/models), and a
+# `.pi/agent` and `.grok` ARE pre-created: both are seeded per-FILE (pi:
+# auth/settings/trust/models; grok: auth.json/config.toml/pager.toml), and a
 # per-file seed copy, unlike a whole-dir one, does not create its parent directory.
+# `.dsh` is pre-created for the same per-file reason (.env/settings.yaml/
+# cordis.patch.yml), and the interactive profile is built into it HERE rather than
+# after `USER agent`: this layer's closing chgrp/chmod is what makes the whole tree
+# writable by the arbitrary uid the container actually runs as, and a profile
+# installed after it would miss that fixup. DSH_HOME points the launcher at the
+# agent's dir while this still runs as root.
 RUN useradd -g 0 -m -d /home/agent -s /bin/bash agent \
  && mkdir -p /home/agent/.npm /home/agent/.cache /home/agent/.config /home/agent/.codeman \
-      /home/agent/.claude/projects /home/agent/.codex/sessions /home/agent/.pi/agent \
+      /home/agent/.claude/projects /home/agent/.codex/sessions /home/agent/.pi/agent /home/agent/.grok \
+      /home/agent/.dsh \
+ && DSH_HOME=/home/agent/.dsh HOME=/home/agent \
+      dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui \
+ && test -f /home/agent/.dsh/profiles/dsh-tui/package.json \
  && chgrp -R 0 /home/agent \
  && chmod -R g=u /home/agent
 

docs/cron-guide.md

@@ -91,7 +91,7 @@ These map 1:1 to `CronJobSchema` (`src/web/schemas.ts`) and the `CronJob` type
 | Field                      | Required    | Values / limits                                          | Notes                                                                                                                                                                                      |
 | -------------------------- | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `name`                     | ✅          | 1–200 chars                                              | Display name; also used as the created session's name.                                                                                                                                     |
-| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` \| `antigravity` \| `pi` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal. ⚠️ A `pi` job's readiness poll looks for `❯`/a token count, neither of which pi prints, so it burns the poll budget and then sends the prompt anyway (slower start, still works). |
+| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` \| `antigravity` \| `pi` \| `grok` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal. ⚠️ A `pi` or `grok` job's readiness poll looks for `❯`/a token count, which neither CLI prints, so it burns the poll budget and then sends the prompt anyway (slower start, still works). |
 | `workingDir`               | ✅          | valid path (allowlist-validated)                         | Validated at **create/update** (must exist, be a directory, and not resolve into a blocked tree — `/etc`, `/root`, `/proc`, `/sys`, `/dev`, or `/` itself) and again **at fire time**.     |
 | `launchCommand`            | —           | ≤ 2000 chars, single line                                | `shell` mode only: sent as the **first input line** once the shell is up, before the prompt. Ignored for other agent types.                                                                |
 | `promptMode`               | ✅          | `inline_text` \| `prompt_file_path`                      | See §5.                                                                                                                                                                                    |

docs/deepseek-integration-plan.md

@@ -0,0 +1,178 @@
+# DeepSeek Harness (`dsh`) integration plan
+
+> **Status**: Executed. This document records the plan, the decision behind each
+> wiring point, and what was and was not verified. The user-facing guide is
+> [`deepseek-integration.md`](./deepseek-integration.md); the per-decision
+> invariants live in
+> [`architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek`](./architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek).
+> Template: the grok integration ([`grok-integration-plan.md`](./grok-integration-plan.md)),
+> itself calibrated against pi. Every fact below was measured against a live
+> **dsh 0.1.1-rc.2** install and **@deepseek-harness-tui/dsh-tui 0.9.0**, not read
+> from documentation.
+
+## 1. What the DeepSeek Harness is
+
+[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)
+(open-sourced 2026-08-13, MIT) is a plugin-native agent framework: tools, skills,
+sessions, sandboxes and whole APPS are Cordis plugins composed into *profiles*.
+`dsh` is the launcher — `dsh --profile <name>` boots
+`$DSH_HOME/profiles/<name>`, an ordered stack of plugin-bundle patch layers under
+the user's own overrides. State lives in `~/.dsh` (`.env` 0600, `settings.yaml`,
+`cordis.patch.yml`, `profiles/`, `sessions/`, `storages/`).
+
+## 2. Shape decisions (why DeepSeek is wired the way it is)
+
+DeepSeek is a ninth run mode. Never a location overlay, never a web tab (the
+browser UI is handled separately, §3). Three of its decisions have no precedent
+in the six external CLIs before it.
+
+| Question | Decision | Why |
+| --- | --- | --- |
+| What does a pane run? | `dsh --profile <name>`, profile discovered | **The decision that shapes everything else.** DeepSeek ships `web`, `headless` and `base` — no terminal agent. The interactive front door is always a third-party plugin, so Codeman resolves a binary AND a profile inventory, and "available" means both. `resolveDefaultDeepSeekProfile()` prefers a recognized TUI, then an UNRECOGNIZED profile (anyone can publish an app bundle; a classifier that has not heard of one must not hide it), and refuses `web`/`headless`, which cannot occupy a pane. |
+| Which TUI? | none blessed; default for BOOTSTRAP only | `POST /api/deepseek/install-profile` defaults to `@deepseek-harness-tui/dsh-tui` (~27.5k weekly downloads, ~4x the next, MIT, and it speaks the status contract in §2.3), but accepts any npm name and the resolver never assumes that profile exists. Codeman offers a default; it does not pick a winner. |
+| Permission bypass | `DSH_PERMISSION_MODE` env export, no flag | The harness has NO command-line permission option; its sandbox/approval rows read one env var with three presets (`read-only` / `workspace-write` / `danger-full-access`, read off `dsh --dump-default-config`). This is the one legitimate exception to the `CLAUDE_CODE_EFFORT_LEVEL` ban: that var hard-locks in-session switching, whereas the harness reads this with `??` as a boot-time DEFAULT, so it stays soft. Exported via `tmux setenv`, never on the command line. The Run button sends `danger-full-access`, matching every sibling Run button. |
+| Multi-user clamp branch | only-if-sent, clamped to `workspace-write`, **plus an env-var half** | Omitting the export leaves the harness on `workspace-write`, which still ASKS, so an absent config is already safe (the codex/antigravity/grok shape, not pi's materialize). Clamping to `workspace-write` rather than `read-only` is deliberate: the clamp removes privilege, it must not break a session's ability to edit its own workspace. ⚠️ Unlike every sibling, clamping the CONFIG is only half the gate: the switch is an env var, `DSH_*` is an allowlisted `envOverrides` prefix, and `applyEnvOverrides()` runs AFTER `_configureDeepSeek()`, so `envOverrides: {DSH_PERMISSION_MODE: 'danger-full-access'}` on the same request would land last and win. `clampEnvOverridesForOwner()` drops `DSH_PERMISSION_MODE` and `DSH_HOME` for a non-granted owner (dropping falls through to the clamped export). `DSH_HOME` because it aims the launcher at a profile tree whose plugin code runs at BOOT, before any approval row. |
+| `hooksAvailableForMode()` granularity | per SESSION for deepseek, per mode for everything else | `deepSeekConfig.statusReporting: false` disarms the `HERDR_*` export, and the triple is the only reason a dsh session posts anything, so a mode-only answer would accept `until=stop` where nothing can send one — the infinite-wait the predicate exists to prevent. Call sites pass `sessionHookOptions(session)`; the default stays permissive so a forgotten one degrades to the old behaviour. ⚠️ Profile conformance stays unknowable at request time (an unrecognized profile is deliberately launchable), so a non-conforming TUI still times out on an explicit `stop`; the default set keeps `idle`/`exit` for that. ⚠️ The predicate is NOT "is this claude": Read My Mind and intent capture read Claude's transcript and were silently widened by this change, so they compare `mode === 'claude'` directly now. |
+| Profile install spawn | own process group, hand-rolled timeout | `dsh plugin add` fans out into package-manager children, and spawn's built-in `timeout` signals only the direct child: survivors keep the inherited stdio pipes open, `close` never fires, and the held-open request leaks with no route-level deadline. `detached: true` + negative-pid SIGTERM→SIGKILL, the same escalation `runGit()` uses for the same reason, plus a last-resort reap for a grandchild that escaped the group. |
+| Idle detection | **real hook events via a status shim** | The standout decision. The TUI already reports its lifecycle to a supervising process through a generic env-gated contract inherited from Herdr: `HERDR_ENV=1` + `HERDR_BIN_PATH` + `HERDR_PANE_ID` make it run `<bin> pane report-agent <id> --state idle\|working\|blocked …` on every state change, exit 0 = delivered. `deepseek-status-shim.ts` generates a script into the data dir and points `HERDR_BIN_PATH` at it. So deepseek is the only non-claude mode that passes `hooksAvailableForMode()` — earned by emitting definitive signals, not granted. An interface implementation, not an impersonation: no real `herdr` binary is ever executed, and a TUI that ignores the contract simply falls back to output stabilization. |
+| `agent_working` event | new, 157th SSE constant | The one hook event with no Claude Code hook behind it. A harness turn cannot run while its own modal approval is on screen, so "started working" proves a dialog was answered in the terminal. Without it a dsh red alert would survive until the next `stop` — the exact stuck-alert bug the claude path already fixed once, and its pane-capture staleness sweep is Claude-dialog-shaped and cannot help here. |
+| Resolver | identity probe THEN version probe | Strictest of the family, and not by preference. `dsh` is not merely a squattable npm name: Debian ships an unrelated `dsh` (dancer's shell, `apt install dsh`) which would answer a version probe convincingly and then be handed a spawn line. `dsh --help` must match `DeepSeek Harness` first. `DEEPSEEK_VERSION_REGEX` keeps the prerelease tail (`0.1.1-rc.2`), since truncating it would report an rc as a release. |
+| Env allowlist | `DSH_*` + `DEEPSEEK_*` | `DSH_*` covers the launcher's documented inputs (`DSH_HOME`, `DSH_PERMISSION_MODE`, `DSH_TELEMETRY_MODE`, the `DSH_TUI_*` knobs); `DEEPSEEK_*` is the vendor namespace holding `DEEPSEEK_API_KEY`/`DEEPSEEK_BASE_URL`, same reasoning that admitted `XAI_*` for grok. ⚠️ Pi's lesson repeats exactly: a dsh `settings.yaml` can nominate ANY env var as a provider credential (`apiKeyEnv`), and the allowlist is one GLOBAL list, so admitting those would widen every mode at once. They stay out. |
+| Model | NOT a session field | The model is a composition entry (`agent-default-model`) in the profile's config tree, set in `~/.dsh/settings.yaml` + `cordis.patch.yml`. Both create paths deliberately resolve no model for this mode rather than inventing a flag. |
+| Alt-screen strip | OUT of `isAltScreenStripMode()` | Third-party fullscreen TUIs with their own scrollback and mouse handling — the opencode case, not the Ink case. |
+| Local echo | `'buffer'` via the `_updateLocalEchoState` fallthrough | UNMEASURED against a live authenticated session (see §5), same honest gap grok shipped with. The leading TUI's composer supports `@` completion and history search, which *may* make it per-keystroke reactive like codex; if so the fallback is the `'off'` branch. |
+| Docker | image installs dsh AND a profile | Profiles are deliberately NOT seeded from the host: each is a per-profile `node_modules` tree, host-arch-specific and far too large to copy per container start. Only `~/.dsh/.env`, `settings.yaml`, `cordis.patch.yml` are seeded (auth + model composition). The profile install rides the `useradd` layer so the closing `chgrp`/`chmod g=u` covers it, which is what keeps it usable under the arbitrary uid the container runs as. |
+| Remote SSH | `exec "$SHELL" -i -l -c 'dsh'` | Boots the remote box's default profile; a remote with several needs the per-host `commands.deepseek` override, since `deepSeekConfig` does not cross ssh. |
+
+## 3. The web profile
+
+The browser UI is the only interactive surface DeepSeek ships itself, so it gets
+a **shortcut, not a run mode**: `Run ▸ DeepSeek web UI…` starts
+`dsh web --no-open --host 127.0.0.1 --port <free> --trusted-host <codeman-authority>`
+as a background process and opens the URL as an ordinary web tab.
+
+The server was a **shell session** first, on the reasoning that Codeman already
+supervises those (visible, scrollable, killable, dies with its tab) so nothing
+new had to own a long-lived HTTP server. That version worked and was still
+wrong in use: clicking "open the DeepSeek web UI" put a terminal tab on screen
+next to the web tab actually asked for, every single time, and after the first
+launch the terminal was pure noise. Opening a dashboard should open one tab.
+
+So `POST /api/deepseek/web` owns it instead (`src/deepseek-web-server.ts`), and
+what the session gave away for free is now explicit: exactly one server, reused
+rather than raced on a second click; restarted when the requested authority
+changes; killed on Codeman shutdown (a detached child would otherwise hold its
+port against the next start — the very EADDRINUSE this feature already got
+wrong once); and boot output captured, since with no shell tab there is nowhere
+else for a stack trace to land. It is fenced at the same bar as the profile
+installer: booting a dsh profile executes the plugin code in it, so it requires
+the privileged grant in multi-user mode.
+
+`--trusted-host` is load-bearing — dsh fences its `/api` behind a browser-trust
+check on the request authority, and a Codeman web tab reaches it through
+Codeman's own origin via the webview proxy, not directly. The authority comes
+from the CLIENT (`location.host`) because only the browser knows which of a
+multi-homed Codeman's origins is actually in play.
+
+Three things about this shortcut are load-bearing and each came from it failing
+in exactly that way against a real install:
+
+- **The port is chosen, never hardcoded.** `GET /api/deepseek/web-port` walks
+  3080..3119 for a free loopback port. 3080 is dsh's own default, which makes it
+  precisely the port a DeepSeek user is most likely to already be serving on:
+  binding it unconditionally killed the launch with `EADDRINUSE` against the
+  user's own `dsh web`.
+- **The tab is opened only after the server answers.** The launch polls
+  `POST /api/webviews/probe` until the URL responds, so a server that dies on
+  startup reports the failure and points at its shell tab, instead of silently
+  persisting a dashboard aimed at nothing.
+- **The saved tab is `trusted: true`, and must be.** An untrusted webview is
+  sandboxed without `allow-same-origin`, which breaks this dashboard twice: the
+  dsh client-runtime reads `localStorage` while loading plugins and dies there,
+  and an opaque-origin frame sends `Origin: null`, so dsh's trust check 403s
+  every `/api` call regardless of what `--trusted-host` names. Passing
+  `location.host` only means anything once the frame actually carries that
+  origin. The trade is real — a trusted proxied frame is same-origin with
+  Codeman and can reach Codeman's API — and is defensible only because this
+  particular dashboard is an agent harness Codeman just started itself on
+  loopback, which can already run code as the user. It is not a precedent for
+  trusting third-party dashboards generally.
+
+The record is marked `managed: 'deepseek-web'`, which keeps it out of the
+saved-dashboard list: the shortcut that maintains it is already a menu entry, so
+listing both showed the same dashboard twice. Being managed is also what lets a
+relaunch repoint the existing row instead of stacking one dead dashboard per
+restart, since the port is now chosen per launch.
+
+The authority baked into `--trusted-host` is the one the launch was clicked
+from, and reuse is conditional on it: a running server fenced for a *different*
+origin is stopped and restarted rather than reused, because reusing it renders a
+page whose every API call 403s — which reads as a broken dashboard rather than a
+misconfigured one.
+
+## 4. Touch points (the checklist)
+
+Backend: `types/session.ts` (SessionMode + `DeepSeekConfig` + SessionState),
+`utils/deepseek-cli-resolver.ts` (new) + barrel, `deepseek-status-shim.ts` (new),
+`tmux-manager.ts` (`buildDeepSeekCommand`, dispatch, resume flag, PATH export,
+truecolor, `_configureDeepSeek`, availability error, plumbing), `session.ts`
+(external-mode gate, label, config plumbing, tmux-required error, attach env),
+`mux-interface.ts`, `schemas.ts` (prefixes, `DeepSeekConfigSchema`,
+`DeepSeekInstallProfileSchema`, both mode enums, remote overrides, cron agentType,
+`agent_working`), `session-wait-registry.ts` (`hooksAvailableForMode`),
+`hook-event-routes.ts` (`APPROVAL_RESOLVING_EVENTS`), `session-routes.ts` (clamp +
+both create paths + `resolveDeepSeekLaunchError`), `system-routes.ts`
+(`GET /api/deepseek/status`, `POST /api/deepseek/install-profile`), `server.ts`
+(availability inject + mux restore), `sse-events.ts`, `docker-hosts.ts`,
+`remote-hosts.ts`, `config/dependency-registry.ts`,
+`response-viewer-transcript.ts`, `cron/cron-service.ts` (comment),
+`tui/tui-client.ts` + `tui-app.ts`.
+
+Frontend: `index.html` (welcome button, run-mode entry, install affordance, web-UI
+shortcut, cron option, clone Brain option), `session-ui.js` (`runDeepSeek()`,
+`runDeepSeekWeb()`, `installDeepSeekProfile()`, dispatch, availability, "Run DS"
+label, external-CLI gates), `app.js` (label, `ds` tab badge, kill-menu, SSE map),
+`settings-ui.js` (welcome gate + `_onHookAgentWorking`), `constants.js`,
+`mobile-overview.js`, `home-sessions.js`, `panels-ui.js`, `i18n.js`,
+`terminal-ui.js`, `styles.css` + `mobile.css` (brand-indigo identity; the non-og
+skin block and the mobile `!important` pair are both load-bearing).
+
+Meta: `docker/agent.Dockerfile`, `install.sh`, `package.json` keyword,
+`skills/codeman/reference/*`, CLAUDE.md, `architecture-invariants.md`.
+
+Tests: `test/deepseek-mode.test.ts` + `test/deepseek-cli-resolver.test.ts` (new);
+`run-mode-ui`, `render-index-html`, `mobile-overview`, `agent-skill-mode-lists`
+(extended).
+
+## 5. Verification performed
+
+See the summary at the end of the implementing session for the live run. In
+short: the CI gate green; the resolver, profile inventory, spawn-line and clamp
+behaviour covered by 31 new unit tests; and an isolated instance used to exercise
+`GET /api/deepseek/status` and a real session against the live dsh install.
+
+**Not verified (honest gaps):**
+
+- The local-echo `'buffer'` policy against the TUI's real composer (§2). If it
+  turns out per-keystroke reactive like codex's, flip it to the `'off'` branch;
+  teaching `PredictiveEchoAddon` its composer row is the larger follow-up.
+- Scrollback/repaint behaviour of a third-party fullscreen TUI under the narrow
+  strip during a long session.
+- A Docker case with `mode: 'deepseek'` (needs a `--no-cache` agent-image
+  rebuild — see the `--no-cache` rule in CLAUDE.md).
+- A remote-SSH deepseek case.
+- The web-UI shortcut against a tunnel authority. Loopback and a tailnet name are
+  both verified end to end through the webview proxy (dashboard renders, its
+  `/api` calls succeed, no shell session created).
+
+## 6. Follow-ups
+
+- **Response viewer**: read `~/.dsh/sessions/**` (JSONL) the way codex rollouts
+  are read back. Highest-value follow-up, and very achievable.
+- **`headless` as an execution backend** for Codeman's own AI checks
+  (`ai-idle-checker`, `ai-plan-checker`), today Claude-only.
+- **Profile/model picker in Session Options**, reading `GET /api/deepseek/status`
+  `.profiles`.
+- **`--patch` overlays per session**, which is the harness-native way to change
+  agent composition without touching the user's profile.
+- Measure the local-echo policy and pin the result the way pi did.

docs/deepseek-integration.md

@@ -0,0 +1,297 @@
+# DeepSeek Harness (`dsh`) in Codeman
+
+Codeman can run [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+as a session backend, alongside Claude Code, OpenCode, Codex, Gemini,
+Antigravity, Pi and Grok. It is the ninth run mode, and the one that is wired
+least like the others, for two reasons worth understanding before you use it.
+
+## 1. The agent is a profile, not the binary
+
+`dsh` is a **launcher**, not an agent. It boots a *profile*: an ordered stack of
+plugin-bundle patch layers under `$DSH_HOME/profiles/<name>` (`$DSH_HOME`
+defaults to `~/.dsh`). DeepSeek ships three bundles and none of them is a
+terminal agent:
+
+| Profile      | What it is                        | Can Codeman run it in a tab? |
+| ------------ | --------------------------------- | ---------------------------- |
+| `web`        | the browser UI, served on :3080   | no — but see §6              |
+| `headless`   | answers one task and exits        | no                           |
+| (`base`)     | the shared core, no app at all    | no                           |
+
+The interactive terminal front door is **always a third-party plugin**. So
+"DeepSeek is installed" and "Codeman can start a DeepSeek session" are different
+questions, and Codeman answers both separately:
+
+```bash
+curl -s localhost:3000/api/deepseek/status | jq
+{
+  "available": true,            # the `dsh` binary resolved and proved its identity
+  "runnable": false,            # ...but nothing installed can drive a pane
+  "path": "/home/you/.local/bin",
+  "version": "0.1.1-rc.2",
+  "dshHome": "/home/you/.dsh",
+  "defaultProfile": null,
+  "profiles": [ { "name": "web", "kind": "web", "bundles": [...] } ]
+}
+```
+
+### Installing a terminal profile
+
+From the UI: open the **Run** dropdown. When `dsh` is installed but no
+pane-capable profile is, the menu shows **DeepSeek — add a terminal profile…**.
+One click installs one and the normal DeepSeek entry appears.
+
+By hand, or to pick a different front door:
+
+```bash
+dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
+```
+
+Codeman's default is `@deepseek-harness-tui/dsh-tui` because it is by a wide
+margin the most used community TUI, it is MIT, and it implements the status
+contract described in §3. It is a **default, not a requirement**: any profile
+under `$DSH_HOME/profiles` that is not `web` or `headless` shows up in the
+inventory and can be launched, including one you compose yourself. The endpoint
+accepts any npm package name:
+
+```bash
+curl -sX POST localhost:3000/api/deepseek/install-profile \
+  -H 'Content-Type: application/json' \
+  -d '{"profile":"my-tui","package":"@someone/dsh-tui"}'
+```
+
+Installing a plugin is arbitrary code execution on the host, so in multi-user
+mode this endpoint requires the can-bypass-permissions grant (the same bar as a
+`shell` session). The request is held open while the package manager runs and is
+bounded at five minutes; the install runs in its own process group, so hitting
+that bound kills the whole tree rather than just the launcher.
+
+> **`dsh` is also a Debian program.** `apt install dsh` gives you "dancer's
+> shell", a distributed shell, which would answer `--version` convincingly.
+> Codeman's resolver therefore demands the harness's own help banner before it
+> will point a spawn line at a candidate, and `GET /api/deepseek/status` reports
+> `path` and `version` so a misresolution is diagnosable rather than presenting
+> as "the mode just doesn't work".
+
+## 2. Permissions are an env var, not a flag
+
+The harness has **no `--dangerously-skip-permissions` equivalent**. Its sandbox
+and approval rows are configuration, driven by one documented input,
+`DSH_PERMISSION_MODE`, with three presets (read off `dsh --dump-default-config`):
+
+| `DSH_PERMISSION_MODE` | sandbox              | approvals | notes                     |
+| --------------------- | -------------------- | --------- | ------------------------- |
+| `read-only`           | `read-only`          | ask       |                           |
+| `workspace-write`     | `workspace-write`    | ask       | the harness's own default |
+| `danger-full-access`  | `danger-full-access` | **never** | what the Run button sends |
+
+Codeman exports it via `tmux setenv`, never on the command line. Because the
+harness reads it with `??`, it is a **soft default**: it sets the boot-time
+preset and you can still change permission mode inside the session.
+
+Omitting it entirely leaves the harness on `workspace-write`, which still asks —
+which is why the multi-user clamp only needs to force a *sent* value down. A
+non-granted owner's `danger-full-access` becomes `workspace-write`, not
+`read-only`: the clamp removes privilege without breaking the session's ability
+to edit its own workspace.
+
+Because the switch is an env var rather than a flag, that clamp has a second half
+no other CLI needs. `DSH_*` is an allowlisted `envOverrides` prefix (it has to be:
+that is also how you set the harness's ordinary knobs), and env overrides are
+applied *after* the permission export, so in multi-user mode a non-granted owner
+sending
+
+```json
+{ "mode": "deepseek", "envOverrides": { "DSH_PERMISSION_MODE": "danger-full-access" } }
+```
+
+would otherwise hand back the privilege the config clamp just removed. For a
+non-granted owner Codeman therefore **drops `DSH_PERMISSION_MODE` and `DSH_HOME`
+from `envOverrides`**; dropping them falls through to the clamped config and the
+server's own `DSH_HOME`. `DSH_HOME` is in that list because it points the
+launcher at a profile tree, and a profile's plugin code runs at boot, before any
+approval row can apply. Single-user installs and granted owners are unaffected.
+
+## 3. Real idle detection (the interesting part)
+
+Every other external CLI mode in Codeman is **readiness-guessed**: Codeman
+watches the PTY go quiet and infers that a turn ended. Claude is the exception,
+because Claude Code fires hooks.
+
+DeepSeek is the second exception. The community terminal front door already
+reports its own lifecycle to a supervising process through a generic,
+env-var-gated contract (inherited from [Herdr](https://herdr.dev)): when
+`HERDR_ENV=1`, `HERDR_BIN_PATH` and `HERDR_PANE_ID` are set, it shells out on
+every state change with
+
+```
+"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
+    --source custom:dsh-tui --agent dsh-tui \
+    --state idle|working|blocked [--message ...] --seq N
+```
+
+Codeman points `HERDR_BIN_PATH` at a small generated shim
+(`~/.codeman/dsh-status-shim.mjs`, written at session create) which forwards each
+report to `POST /api/hook-event`. The mapping:
+
+| Harness state | Codeman hook event | What you get                                             |
+| ------------- | ------------------ | -------------------------------------------------------- |
+| `blocked`     | `permission_prompt`| red "needs you" tab alert + an Approvals Inbox item       |
+| `idle`        | `stop`             | definitive end-of-turn: respawn triggers, `wait` returns  |
+| `working`     | `agent_working`    | clears an alert answered in the terminal, at once         |
+
+So a DeepSeek session gets Claude-grade signals: `GET /api/sessions/:id/wait`
+really can block on `stop` and `blocked` for it, and it is the only non-Claude
+mode for which that is true (`hooksAvailableForMode`).
+
+That is a per-*session* answer, not a per-mode one. Turning the bridge off with
+`deepSeekConfig.statusReporting: false` means nothing will ever post a hook event
+for that session, so an explicit `until=stop` is refused up front (with a message
+naming the setting) rather than blocking for your whole timeout. Omitting `until`
+never fails: the hook-only signals are dropped from the default set and you still
+get `idle` and `exit`.
+
+One limit worth knowing: whether the *profile* implements the contract cannot be
+known at request time (Codeman deliberately treats an unrecognized profile as
+launchable). A dsh session running a non-conforming TUI therefore still accepts
+`until=stop` and will time out on it. `idle`/`exit` are the reliable pair there.
+
+This is an interface implementation, not an impersonation — nothing on your
+machine executes a real `herdr` binary. If you use a terminal profile that does
+*not* implement the contract, the shim is simply never called and the mode falls
+back to output-stabilization readiness like its siblings. Turn it off per session
+with `deepSeekConfig.statusReporting: false`.
+
+## 4. Starting a session
+
+From the UI, pick **DeepSeek** in the Run dropdown (or the **Run DeepSeek**
+welcome button) and press Run. Over the API:
+
+```bash
+curl -sX POST localhost:3000/api/quick-start \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "caseName": "myproject",
+        "mode": "deepseek",
+        "deepSeekConfig": {
+          "profile": "dsh-tui",
+          "permissionMode": "danger-full-access"
+        }
+      }'
+```
+
+`deepSeekConfig` fields: `profile`, `permissionMode`, `resumeSession`,
+`resumeSessionId`, `statusReporting`. Resume prefers an explicit id over the
+most-recent form, and both are passed through to the profile's app, which is
+where `--resume` is understood.
+
+**Models are not a session field.** The model is a composition entry in the
+profile's config tree (`agent-default-model`), not a CLI flag, so Codeman does
+not try to set one. Configure it where the harness does: `~/.dsh/settings.yaml`
+plus a home-level `~/.dsh/cordis.patch.yml`, or a `--patch` overlay on the
+profile. That is also how you point dsh at a local or third-party provider.
+
+**Environment.** `DSH_*` and `DEEPSEEK_*` are allowlisted for `envOverrides`
+(so `DSH_HOME`, `DSH_PERMISSION_MODE`, `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`
+all flow through). Provider keys with *other* names are deliberately not: a dsh
+`settings.yaml` can nominate any env var as a credential via `apiKeyEnv`, and
+Codeman's allowlist is global, so admitting them would widen it for every mode at
+once. Authenticate those the way dsh does, from the file or the server's own
+environment.
+
+## 5. Reading a session back, and driving one as a worker
+
+dsh writes a real transcript — `$DSH_HOME/sessions/<mangled-cwd>/<id>/session.jsonl.zstd`
+— so `GET /api/sessions/:id/last-response` reads that rather than segmenting the
+pane, and the Response Viewer shows a dsh conversation the way it shows a claude
+or codex one (`?context=full` returns prompt / response / tool blocks).
+
+Reading the pane instead is not merely coarse for this mode, it is wrong: dsh-TUI
+paints a full-screen splash, so the segmenter answered a `last-response` call for
+a fresh dsh session with its ASCII-art logo — which anything polling for a
+worker's first answer reads as an answer. Three things about the file shaped the
+reader (`src/deepseek-transcript.ts`):
+
+- **It is one zstd FRAME per append, not one zstd stream.** `zstd -dc` decodes all
+  of them, Node's `zlib` zstd decoder stops at the first: a real 56-line
+  transcript came back as 1 line. The reader walks frame headers itself. On a Node
+  older than 22.15 (no zstd at all) the mode falls back to the pane, as before.
+- **Not every `user/message` is the user.** Each turn also records a
+  plugin-sourced runtime-context snapshot; only `source.kind === 'user'` is a
+  prompt.
+- **A failed turn is not an empty one.** `turn/end` carries the provider's error,
+  which is returned as `Turn error: …` (and an early stop such as `max-tokens` as
+  `Turn ended: …`) instead of an empty string that reads as "still thinking".
+
+The transcript reader applies to **local** dsh sessions only. A Docker case's
+harness writes its transcript inside the container's own `~/.dsh` (the workspace
+bind mount does not cover it), and a remote-SSH case's lives on the remote host,
+so the local reader could never find those files — such sessions keep the pane
+segmenter, coarse but real. The splash caveat above applies to them accordingly.
+
+### As an agent worker
+
+Because dsh has both halves — a real end-of-turn signal and a real transcript — an
+agent can drive a dsh session the same way it drives a claude one, and the bundled
+`codeman` agent skill does. Spawning `beta:deepseek` in its worker list gives a
+worker that is tasked, waited on and read with the same calls as its claude
+siblings; no other external CLI mode qualifies. Two edges are worth repeating here:
+
+- **Readiness is not the stop signal.** The harness reports `idle` at boot roughly
+  300 ms *before* the composer paints (measured 2.26 s vs 2.56 s after spawn), so a
+  send-and-wait fired immediately after create resolves on that boot report,
+  reports a turn that never ran, and leaves the prompt in a pane that was not yet
+  accepting input. Wait for the composer (`❯`) instead.
+- **Wait on `stop`, not on the default signal set.** That set also carries `idle`,
+  which for every external CLI is inferred from output stabilization; a dsh TUI
+  that repaints rarely reads as idle mid-turn.
+
+## 6. The web UI as a tab
+
+The browser UI is the one interactive surface DeepSeek ships itself, so it gets a
+shortcut rather than a run mode: **Run ▸ DeepSeek web UI…** starts
+`dsh web --no-open --host 127.0.0.1 --port <free> --trusted-host <codeman-host>`
+as a background child process (`src/deepseek-web-server.ts`, behind
+`POST/GET/DELETE /api/deepseek/web`) and opens it as a Codeman web tab once the
+server actually answers.
+
+It is a child process rather than a shell session because the session version
+opened a terminal tab nobody asked for on every click. What the session gave for
+free is therefore explicit here: one instance with reuse, a restart when the
+requested `--trusted-host` authority differs from the running one, a kill on
+server stop, and captured boot output. The `--trusted-host` flag is load-bearing —
+dsh fences its `/api` behind a browser-trust check on the request authority, and a
+Codeman web tab reaches it through Codeman's own origin via the webview proxy, not
+directly. Without it the page renders and every API call fails.
+
+## 7. Docker and remote cases
+
+Docker cases work: the agent image installs `dsh` and bootstraps a `dsh-tui`
+profile into the container. Profiles are deliberately **not** seeded from the
+host (each is a per-profile `node_modules` tree, host-arch-specific and far too
+large to copy on every container start); only `~/.dsh/.env`, `settings.yaml` and
+`cordis.patch.yml` are seeded, which is what carries auth and model composition
+in. As with pi and grok, in-container sessions are invisible host-side:
+`~/.dsh/sessions` inside a container is that container's own.
+
+Remote SSH cases default to `dsh` through a login shell, which boots the remote
+box's default profile. If the remote has several, name one with the per-host
+`commands.deepseek` override — the local `deepSeekConfig` does not cross ssh.
+
+## 8. What is not wired
+
+Deliberately minimal, on the same reasoning as the grok integration: the harness
+is a fast-moving developer preview and every flag added is a flag validated
+forever.
+
+- `--patch` overlays per session (the profile's own layers apply as normal).
+- `dsh plugin` management beyond first-time profile install.
+- The `headless` profile as a one-shot execution backend for Codeman's own
+  internal AI checks (today those are Claude-only).
+- Model/provider selection from Session Options.
+
+## Verified against
+
+`dsh 0.1.1-rc.2` and `@deepseek-harness-tui/dsh-tui 0.9.0`. The permission
+presets, the profile layout, and the supervisor contract above were all read off
+the live install rather than from documentation.

docs/docker-cases.md

@@ -2,7 +2,7 @@
 
 Run a case inside an **isolated Docker container** instead of directly on the host. Any number of Codeman sessions can share one container (it is scoped to the case, not the session), so a whole project lives in a sandbox with its own network, resource caps, and filesystem, and you can **export the container to move it to another machine**.
 
-Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` / `antigravity` / `pi` all work inside the container.
+Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` / `antigravity` / `pi` / `grok` all work inside the container.
 
 ## One-time setup: build the base image
 
@@ -25,12 +25,12 @@ A zero exit code only proves the layers ran, not that the toolchain works. Verif
 
 ```bash
 docker run --rm codeman/agent:base bash -lc \
-  'for c in claude codex gemini opencode agy pi; do printf "%-9s " $c; $c --version 2>&1 | head -1; done'
+  'for c in claude codex gemini opencode agy pi grok; do printf "%-9s " $c; $c --version 2>&1 | head -1; done'
 ```
 
-Antigravity (`agy`) is the one CLI not installed from npm (Google ships a standalone binary), so it has its own Dockerfile step and adds roughly 190MB; a full image lands near 1.6GB. Pi also gets its own step, because upstream documents installing it with `--ignore-scripts` and that flag must not silently change how the other four npm CLIs install.
+Antigravity (`agy`) and Grok (`grok`) are the two CLIs not installed from npm (Google and xAI ship standalone binaries), so each has its own Dockerfile step, adding roughly 190MB and 160MB respectively. Pi also gets its own step, because upstream documents installing it with `--ignore-scripts` and that flag must not silently change how the other npm CLIs install.
 
-Pi's credentials are seeded per-FILE rather than as a whole directory (`auth.json`, `settings.json`, `trust.json`, `models.json`, `models-store.json` out of `~/.pi/agent`), because that directory also holds `sessions/`, `extensions/`, `skills/` and the installed package trees — gigabytes on an active host. Consequence: in-container pi sessions are invisible host-side, so `pi -c` inside a Docker case only sees that container's own history. See [`pi-integration.md`](./pi-integration.md).
+Pi's credentials are seeded per-FILE rather than as a whole directory (`auth.json`, `settings.json`, `trust.json`, `models.json`, `models-store.json` out of `~/.pi/agent`), because that directory also holds `sessions/`, `extensions/`, `skills/` and the installed package trees — gigabytes on an active host. Consequence: in-container pi sessions are invisible host-side, so `pi -c` inside a Docker case only sees that container's own history. See [`pi-integration.md`](./pi-integration.md). Grok is seeded per-file for the same reason (`auth.json`, `config.toml`, `pager.toml` out of `~/.grok`, which also holds `sessions/`, `memory/` and the ~160MB binary under `downloads/`), with the same consequence for `grok -c`. See [`grok-integration.md`](./grok-integration.md).
 
 ## Quickest path: one-click "Run in Docker"
 

docs/grok-integration-plan.md

@@ -0,0 +1,106 @@
+# Grok Build (xAI) integration plan
+
+> **Status**: Executed. This document records the plan, the decision behind each wiring
+> point, and what was and was not verified. The user-facing guide is
+> [`grok-integration.md`](./grok-integration.md); the per-decision invariants live in
+> [`architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok`](./architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok).
+> Template: the pi integration (`c5b5963`, [`pi-integration-plan.md`](./pi-integration-plan.md)),
+> which was itself calibrated against the four follow-up commits the antigravity
+> integration needed. All of grok's facts below were verified against **grok 1.0.5**
+> (`grok 1.0.5 (5115b46bc9)`), installed live during the work.
+
+## 1. What Grok Build is
+
+[xai-org/grok-build](https://github.com/xai-org/grok-build) is xAI's coding agent: a
+Rust fullscreen-TUI binary named `grok`, installed by
+`curl -fsSL https://x.ai/cli/install.sh | bash` into `~/.grok/bin` (with symlinks into
+`~/.local/bin`; the installer also ships an `agent` alias). Config lives in
+`~/.grok/config.toml`, TUI appearance in `~/.grok/pager.toml`, credentials in
+`~/.grok/auth.json` (0600), sessions under `~/.grok/sessions/`. Auth is browser OAuth
+on first launch, `grok login --device-auth` for SSH boxes, or `XAI_API_KEY` for
+headless use. It has Claude-style permission modes (`default`/`acceptEdits`/`auto`/
+`dontAsk`/`bypassPermissions`/`plan`), allow/deny rules, hooks, MCP, subagents, and a
+headless `-p` mode.
+
+## 2. Shape decisions (why grok is wired the way it is)
+
+Grok is a seventh run mode, alongside Claude Code, shell, OpenCode, Codex, Gemini,
+Antigravity and Pi. Never a location overlay, never a web tab. Its wiring mixes two
+existing shapes:
+
+| Question | Decision | Why |
+| --- | --- | --- |
+| Permission bypass | `GrokConfig.alwaysApprove` -> `--always-approve` | Grok's real flag (verified via `--help`): "Auto-approve all tool executions", i.e. its `bypassPermissions` mode. Config-level deny rules still apply on top. The Run button sends `true`, matching `runAntigravity()` and Claude's own `--dangerously-skip-permissions` default: Codeman sessions exist for autonomous work. |
+| Multi-user clamp branch | only-if-sent (codex/antigravity branch) | A bare `grok` spawn is grok's own ask-mode default, which is already safe, so the clamp only needs to force a SENT `alwaysApprove` off. Contrast pi, whose absent default is an answerable prompt and therefore needs the materialize branch. Cron needs nothing for grok for the same reason (`clampCronExternalCliConfigs`). |
+| Alt-screen strip | OUT of `isAltScreenStripMode()` | Grok is a fullscreen alternate-screen TUI with mouse support (its own scrollback pane, `pager.toml [terminal] alt_screen`), i.e. the opencode case, not the Ink repaint case. It falls through to the narrow tmux-attach strip like opencode/antigravity/pi. |
+| Resolver | version probe, like pi | `grok` has npm squatters (the unrelated `@vibe-kit/grok-cli` installs a `grok` bin). Candidates must pass `grok --version`; `GROK_VERSION_REGEX` is exported and shared with the dependency registry so doctor and run mode cannot disagree. The probe cannot tell two version-printing `grok`s apart, so `GET /api/grok/status` surfaces path AND version. Search dirs: `~/.grok/bin` first (installer target), then `~/.local/bin`, `/usr/local/bin`, `~/bin`. |
+| Env allowlist | `GROK_*` + `XAI_*` prefixes | `GROK_*` covers grok's documented inputs (`GROK_HOME`, `GROK_CONFIG`/`GROK_CONFIG_PATH`, `GROK_MEMORY`, `GROK_WORKFLOWS`, `GROK_SANDBOX`, `GROK_OIDC_*`, `GROK_AUTH_PROVIDER_COMMAND`). `XAI_*` is xAI's vendor namespace and carries `XAI_API_KEY`, grok's documented headless auth var: the same narrow-vendor-namespace reasoning that admitted `GOOGLE_*` for gemini. Foreign provider keys stay out, as always. |
+| Resume | `--resume <id>` / `--continue`, id-regexed | Grok's `--resume` also matches session TITLES (arbitrary user strings, case-insensitive). The `^[a-zA-Z0-9._-]+$` regex doubles as the no-titles rule, so nothing free-form can reach the `bash -c` spawn line. A valid explicit id wins over `-c`, mirroring pi. |
+| Local echo | `'buffer'` via the `_updateLocalEchoState` fallthrough | UNMEASURED against an authenticated session (see §4). If grok's composer turns out per-keystroke reactive like codex's, the fallback is one `'off'` branch; teaching `PredictiveEchoAddon` grok's composer row is the larger follow-up. |
+| Truecolor | `COLORTERM=truecolor` + `unset NO_COLOR` | Rust TUI with themes; joins the codex/gemini/antigravity/pi list in `buildEnvExports()` and `buildMuxAttachEnv()`. |
+| Docker credentials | per-file seed: `auth.json`, `config.toml`, `pager.toml` | `~/.grok` also holds `sessions/`, `memory/`, `completions/`, `docs/` and the ~160MB binary under `downloads/`; a whole-dir seed would copy all of it on every container start. Same trade-off as pi: in-container sessions are invisible host-side, so `grok -c` in a Docker case sees only that container's history. |
+| Docker install | own Dockerfile step | Not an npm package. xAI's installer has no `--dir` override, so the step copies `/root/.grok/bin/grok` (through the symlink, `cp -L`) into `/usr/local/bin` and removes root's `~/.grok` in the same layer. |
+| Remote SSH | `exec "$SHELL" -i -l -c 'grok'` | sshd's remote-command PATH does not include `~/.grok/bin`; same login-shell fix as every other agent CLI. |
+| What is NOT wired | `--permission-mode`, `--allow`/`--deny`, `-p` headless, `--worktree`, `--sandbox`, `--reasoning-effort`, `-s/--session-id`, `--fork-session`, `--agent`, `--output-format` | Follow-ups. The flag surface is kept minimal on purpose; grok is pre-1.0-style fast-moving and every flag added is a flag validated forever. |
+
+## 3. Touch points (the checklist)
+
+Backend: `types/session.ts` (SessionMode + GrokConfig + SessionState), `utils/grok-cli-resolver.ts` (new)
++ barrel, `tmux-manager.ts` (`buildGrokCommand`, dispatch, resume flag, PATH export, truecolor,
+availability error, plumbing), `session.ts` (external-mode gate, label, config plumbing,
+tmux-required error, attach env), `mux-interface.ts`, `schemas.ts` (prefixes, `GrokConfigSchema`,
+both mode enums, remote command overrides, cron agentType), `session-routes.ts` (clamp + both
+create paths), `system-routes.ts` (`GET /api/grok/status`), `server.ts` (availability inject +
+mux restore), `docker-hosts.ts`, `remote-hosts.ts`, `config/dependency-registry.ts`,
+`cron/cron-service.ts` (comment), `response-viewer-transcript.ts`, `tui/tui-client.ts` + `tui-app.ts`.
+
+Frontend: `index.html` (welcome button, run-mode entry, cron option, clone Brain option),
+`session-ui.js` (`runGrok()`, dispatch, availability, "Run GK" label, external-CLI gates,
+runMode setter), `app.js` (label, `gk` tab badge, kill-menu), `settings-ui.js`,
+`mobile-overview.js`, `home-sessions.js`, `panels-ui.js`, `i18n.js`, `styles.css` +
+`mobile.css` (charcoal monochrome identity; the non-og skin block and the mobile
+`!important` pair are both load-bearing, see the pi plan's §2.9 cascade trap).
+
+Meta: `docker/agent.Dockerfile`, `install.sh`, `package.json` keyword, changeset,
+`skills/codeman/reference/*`, CLAUDE.md, READMEs, `architecture-invariants.md`,
+`remote-sessions.md`, `security-architecture.md`, `docker-cases.md`, `cron-guide.md`.
+
+Tests: `test/grok-mode.test.ts` + `test/grok-cli-resolver.test.ts` (new);
+`external-cli-bypass-clamp`, `system-routes`, `render-index-html`, `run-mode-ui`,
+`mobile-overview`, `local-echo-codex-gating` (extended).
+
+## 4. Verification performed
+
+On this box, with grok 1.0.5 really installed and an isolated
+`CODEMAN_INSTANCE=grokwt` server (own data dir, own tmux socket, port 5077):
+
+1. `npm test` (the CI gate): green, 5900+ tests. `typecheck`, `lint`, `format:check`,
+   `check:frontend-syntax`, `check:public-assets`, `check:lockfile`: green.
+2. `GET /api/grok/status` -> `{available: true, path: "/home/arkon/.local/bin", version: "1.0.5"}`
+   through the real resolver and probe.
+3. `POST /api/quick-start {mode: "grok", grokConfig: {alwaysApprove: true}}` -> session
+   created, tmux pane spawned, real spawn line verified to end in `grok --always-approve`,
+   and the actual grok TUI rendered its OAuth device-approval screen in the pane
+   (unauthenticated box, so sign-in is exactly where a first run lands).
+4. `grokConfig` persisted into the instance's `state.json`.
+5. Session deleted by exact id; instance data dir and throwaway case removed.
+
+**Not verified (honest gaps, all requiring an xAI account or more hardware):**
+an authenticated conversation end to end; the local-echo buffer policy against grok's
+real composer (§2); scrollback/repaint behavior of the fullscreen TUI under the narrow
+strip during a long session; a Docker case with `mode: 'grok'` (needs a `--no-cache`
+agent-image rebuild); a remote-SSH grok case; cron readiness degradation (expected:
+same slow-start-then-send as pi, documented in `cron-guide.md`).
+
+## 5. Follow-ups
+
+- Idle/completion signal: grok has a hooks system (user-guide `10-hooks.md`); a hook
+  POSTing to `/api/hook-event` could give grok sessions real idle detection instead of
+  output-stabilization. Highest-value follow-up, same slot as pi's `agent_settled` idea.
+- Response viewer: sessions are ACP JSONL under `~/.grok/sessions/<encoded-cwd>/<id>/updates.jsonl`;
+  `grok -p ... --output-format json | jq -r '.sessionId'` exists for correlation.
+- Permission-mode picker (`--permission-mode`, `--allow`/`--deny`) in Session Options.
+- Measure the local-echo policy and the fullscreen-TUI scrollback behavior against an
+  authenticated session; pin the result in `local-echo-codex-gating` the way pi did.
+- `grok doctor` is a built-in terminal-support check worth pointing users at when a
+  pane renders oddly.

docs/grok-integration.md

@@ -0,0 +1,133 @@
+# Grok Build (xAI) sessions
+
+Codeman can drive [Grok Build](https://github.com/xai-org/grok-build) (xAI's `grok`
+CLI, the agent behind docs.x.ai/build) as a session backend, alongside Claude Code,
+OpenCode, Codex, Gemini, Antigravity and Pi. `grok` is a seventh **run mode**: its own
+PTY, its own tmux session, its own tab identity (monochrome charcoal, `gk` badge). It
+is not a location overlay like Docker or remote-SSH cases, and it is not a web tab.
+
+The design rationale behind each decision below lives in
+[`grok-integration-plan.md`](./grok-integration-plan.md). Everything here was verified
+against grok 1.0.5.
+
+## Install
+
+```bash
+curl -fsSL https://x.ai/cli/install.sh | bash
+```
+
+The installer places the binary in `~/.grok/bin` and symlinks it into `~/.local/bin`
+(it also installs an `agent` alias Codeman ignores). `grok update` self-updates.
+
+Codeman resolves the binary via the server PATH and then the usual install locations,
+`~/.grok/bin` first. **`grok` is a name with known squatters** (the unrelated
+`@vibe-kit/grok-cli` npm package also installs a `grok` bin), so like `pi` the
+resolver does not trust a PATH hit on its own: it runs `grok --version` once and
+requires version-shaped output (`grok 1.0.5 (5115b46bc9)`). Check what it resolved:
+
+```bash
+curl -s localhost:3000/api/grok/status | jq
+# { "available": true, "path": "/home/you/.grok/bin", "version": "1.0.5" }
+```
+
+The endpoint carries `version` on top of the sibling `/api/*/status` shape precisely
+so a misresolution is visible rather than presenting as "the mode just doesn't work".
+
+## Authenticate
+
+- **Browser OAuth (default)**: the first `grok` run opens a sign-in flow; in a
+  Codeman pane you get the device-code screen with a URL to open elsewhere.
+  Credentials land in `~/.grok/auth.json` (0600) and refresh automatically.
+- **Device code**: `grok login --device-auth`, made for SSH boxes and headless hosts.
+- **API key**: `export XAI_API_KEY="xai-..."` (console.x.ai). Used as a fallback when
+  no session token exists. As a per-session Codeman `envOverride` it flows through
+  socket-scoped `tmux setenv`, never the spawn command line.
+- **Enterprise OIDC**: `GROK_OIDC_ISSUER` / `GROK_OIDC_CLIENT_ID`.
+
+## What Codeman wires up
+
+`GrokConfig` (per session, persisted in `state.json`, round-trips through respawn):
+
+| Field             | Flag                        | Notes                                                                 |
+| ----------------- | --------------------------- | --------------------------------------------------------------------- |
+| `model`           | `--model <v>`               | e.g. `grok-4.5`, or a custom `[model.<name>]` from `config.toml`      |
+| `alwaysApprove`   | `--always-approve`          | Grok's `bypassPermissions` mode; deny rules still apply on top        |
+| `continueSession` | `--continue`                | Most recent session for the working directory; skipped when resuming  |
+| `resumeSessionId` | `--resume <v>`              | Ids only, never titles (grok's own `--resume` also matches titles)    |
+
+Every value is regex-validated and **dropped** (not escaped) if it fails, because the
+result is interpolated into the pane's `bash -c "..."` command.
+
+The Run button sends `grokConfig: { alwaysApprove: true }`, the same product decision
+as Claude's `--dangerously-skip-permissions` default and Antigravity's
+`--dangerously-skip-permissions`: Codeman sessions exist for autonomous work. Keep
+hard limits as `deny` rules in `~/.grok/config.toml` (they apply in every mode), and
+in **multi-user mode** a non-granted owner's `alwaysApprove` is forced off
+server-side; a bare `grok` spawn is grok's own ask-mode default.
+
+Env overrides: the `GROK_*` prefix (`GROK_HOME`, `GROK_CONFIG`, `GROK_MEMORY`,
+`GROK_WORKFLOWS`, `GROK_SANDBOX`, `GROK_OIDC_*`, ...) plus the `XAI_*` vendor
+namespace (`XAI_API_KEY`) are allowlisted. Foreign provider keys are not, as ever.
+
+## What Codeman deliberately does NOT wire up
+
+- **`--permission-mode`, `--allow`/`--deny`.** The boolean covers the autonomous
+  case; the full rule surface is a follow-up with UI.
+- **`-p`/headless, `--output-format`, `--json-schema`.** Codeman drives the TUI.
+- **`--worktree`, `--sandbox`, `--reasoning-effort`, `-s/--session-id`,
+  `--fork-session`, `--agent`/`--agents`.** Tracked as follow-ups in the plan doc.
+
+## Terminal behavior
+
+Grok renders a **fullscreen alternate-screen TUI** (scrollback pane + prompt, mouse
+supported). Under Codeman it runs inside tmux like every external CLI, so the
+fullscreen rendering stays inside the pane and the browser terminal shows tmux's
+repaints; grok stays out of the alt-screen strip list on purpose (the opencode case,
+not the Ink case). If a pane renders oddly, `grok doctor` checks terminal, color and
+input support without starting a session, and `~/.grok/pager.toml` can force
+`alt_screen = "inline"`.
+
+On touch devices grok currently gets the buffered local-echo overlay like Claude,
+Gemini, OpenCode and Pi. This is the fallthrough default and has not been measured
+against an authenticated grok composer; if grok turns out per-keystroke reactive the
+way codex was (issues #218/#219/#220/#222), the fix is the `'off'` branch in
+`_updateLocalEchoState` (terminal-ui.js).
+
+## Docker cases
+
+The agent image installs grok in its own Dockerfile step (not npm; xAI's installer
+targets `$HOME/.grok/bin` with no `--dir` override, so the binary is copied to
+`/usr/local/bin`). Rebuild with the mandatory `--no-cache`:
+
+```bash
+node scripts/build-agent-image.mjs --no-cache
+```
+
+Credentials are **seeded**, not shared: `auth.json`, `config.toml` and `pager.toml`
+are copied into the container's own `~/.grok`, so an in-container grok never writes
+refreshed OAuth tokens back to the host and `docker commit` exports stay secret-free.
+Only those three files, because `~/.grok` also holds `sessions/`, `memory/` and the
+~160MB binary under `downloads/`. Trade-off, same as pi: in-container sessions are
+invisible host-side, so `grok -c` inside a Docker case only sees that container's own
+history.
+
+## Remote SSH cases
+
+`grok` mode is routed through an interactive login shell
+(`exec "$SHELL" -i -l -c 'grok'`), because sshd's remote-command PATH does not include
+`~/.grok/bin`. Per-session config and `envOverrides` do not cross ssh and are rejected
+rather than silently ignored; use the per-host command override instead. For auth on
+the remote host, `grok login --device-auth` exists for exactly this.
+
+## Known gaps
+
+- **No idle/completion hook yet.** Idle detection falls back to output-stabilization
+  like the other external CLIs. Grok has a hooks system, so a Codeman hook POSTing to
+  `/api/hook-event` is the highest-value follow-up.
+- **No response viewer.** Grok writes ACP JSONL sessions under
+  `~/.grok/sessions/<encoded-cwd>/<session-id>/updates.jsonl`; nothing reads them yet.
+- **Cron jobs mis-detect readiness.** The readiness poll looks for `❯` or a token
+  count, neither of which grok prints, so a grok cron job burns its poll budget and
+  then sends the prompt anyway. It works; it is just slower to start.
+- **Ralph, respawn heuristics, token/CLI-info parsing and the `❯` readiness probe are
+  off** for grok, as for every external CLI.

docs/remote-sessions.md

@@ -1,7 +1,7 @@
 # Remote Sessions (SSH)
 
 Codeman can run a session's agent on a **remote host over SSH** instead of the
-local machine. The agent (Claude, OpenCode, Codex, Antigravity, Gemini, Pi, or a plain shell)
+local machine. The agent (Claude, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, or a plain shell)
 runs inside a `tmux` server **on the remote host**, so it survives the SSH
 connection dropping; Codeman attaches to it the same way it attaches to a local
 managed session.
@@ -30,7 +30,7 @@ Types live in `src/types/session.ts`; persistence in `src/remote-hosts.ts`.
 | `RemoteHost` (extends `RemoteSshOptions`) | A saved host: `id`, `label`, `host`, `username`, `port?`, `commands?` (per-mode launch command override). |
 | `RemoteCase` | A working directory on a host: `name`, `type: 'remote'`, `hostId`, `remotePath`. |
 | `SessionRemote` (extends `RemoteSshOptions`) | The resolved bundle stamped onto a live session: host coordinates + `remotePath` + `commands`, plus **`owned?`** and **`remoteSessionName?`** (COD-105 — see [Ownership](#ownership-launched-vs-discovered-and-attached-cod-105)). Built by `toSessionRemote(host, case)` (sets `owned: true`) for the launch path, or `toAttachedSessionRemote(host, name, path)` (sets `owned: false`) for the attach path. Both copy the advanced SSH options through so every connection is identical. |
-| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini' \| 'antigravity' \| 'pi'>` — the modes that can run remotely. |
+| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini' \| 'antigravity' \| 'pi' \| 'grok'>` — the modes that can run remotely. |
 | `RemoteSessionInfo` (COD-105) | One discovered remote tmux session: `name` (always `codeman-*`), `attached` (a client is connected), `created` (epoch s), `windows`. Returned by `listRemoteCodemanSessions()`. |
 
 Persistence is two flat JSON arrays in the instance data dir:

docs/security-architecture.md

@@ -489,7 +489,7 @@ production layout (`~/.codeman`, `-L codeman`, port 3000).
 Docker cases (1.4.0) run a session inside a per‑case container instead of on the host. The security posture:
 
 - **Hardened create flags, always** — `--cap-drop ALL`, `--security-opt no-new-privileges`, `--pids-limit` (fork‑bomb guard), `--memory` == `--memory-swap` (a real OOM cap), `--init`, and non‑root: `--user <hostUid>:0` on Linux (host uid → workspace files stay host‑owned; GID 0 keeps `$HOME` writable), `--userns=keep-id` on rootless Podman. **Never** `--privileged`, and **never** the docker socket — the pure builder in `docker-hosts.ts` cannot emit them and the schema cannot represent them.
-- **Credentials never enter an image** — the convenient default bind‑mounts host cred dirs (`~/.claude`, `~/.codex`, `~/.gemini` — which also carries Antigravity's `antigravity-cli/` state — `~/.config/{gcloud,opencode}`, and five seeded files from `~/.pi/agent`) read‑write. Bind mounts are physically excluded from `docker commit`, so exported images are secret‑free. API‑key CLIs get their key as an exec‑time NAME‑ONLY `--env OPENAI_API_KEY` (no `=value`, no `ps` leak, never committed); a create‑time `-e` for a secret is never used. The **sealed** profile (`mountCredentials:false` + `network:none`) drops the host mounts; full‑image export is then refused (an in‑container login would ride the committed layer) unless a pre‑commit scrub is opted into.
+- **Credentials never enter an image** — the convenient default bind‑mounts host cred dirs (`~/.claude`, `~/.codex`, `~/.gemini` — which also carries Antigravity's `antigravity-cli/` state — `~/.config/{gcloud,opencode}`, five seeded files from `~/.pi/agent`, and three from `~/.grok`) read‑write. Bind mounts are physically excluded from `docker commit`, so exported images are secret‑free. API‑key CLIs get their key as an exec‑time NAME‑ONLY `--env OPENAI_API_KEY` (no `=value`, no `ps` leak, never committed); a create‑time `-e` for a secret is never used. The **sealed** profile (`mountCredentials:false` + `network:none`) drops the host mounts; full‑image export is then refused (an in‑container login would ride the committed layer) unless a pre‑commit scrub is opted into.
 - **Blast radius — accept it explicitly** — the convenient profile mounts an arbitrary host workspace RW plus the host credential dirs RW into a network‑enabled container, so container‑run agent code can read/modify those host trees and reach the network at once. Still a net improvement over today's on‑host `--dangerously-skip-permissions` execution; use the sealed profile for genuinely untrusted work.
 - **Import is untrusted‑bundle‑safe** — `/api/docker-cases/import` validates the manifest + per‑member SHA‑256 before extraction, rejects absolute / `..` tar members (traversal guard), and re‑tags the loaded image into a quarantined namespace so it can never overwrite `codeman/agent:base` or a pre‑existing tag.
 - **Host guard & the bridge‑hooks listener** — in‑container hook callbacks carry `Host: host.docker.internal` / `host.containers.internal`; both are on the always‑on host‑header allowlist (`DOCKER_HOST_GATEWAY_ALIASES`) and resolve to the host only from inside a container netns, so they are not a browser DNS‑rebinding surface. On a loopback‑only server, in‑container hooks are opt‑in via `CODEMAN_DOCKER_BRIDGE_HOOKS=1`, which binds a SECOND listener on the docker bridge gateway serving **only** the hook endpoints (every other path → `403`) into the same hook‑secret‑gated pipeline. The bridge is host‑internal (containers + host), not the LAN, so it does not widen network exposure; the hook secret is bind‑mounted read‑only and referenced by path.

docs/wiki/HTTP-API.md

@@ -119,7 +119,7 @@ Shell and external CLI sessions accept `idle`, `working`, and `exit`.
 
 ## SSE
 
-`GET /api/events` is the live event stream. 155 event names, kept in sync between server and
+`GET /api/events` is the live event stream. 156 event names, kept in sync between server and
 client with a test that fails on drift.
 
 The heartbeat is a **named** `sse:heartbeat` event rather than an SSE comment, because

docs/wiki/The-Dashboard.md

@@ -136,7 +136,7 @@ Worth knowing:
 - **Scrollback.** Agent/TUI sessions pull their entire tmux scrollback on first open.
   Shell sessions open from a bounded recent tail so a large transcript cannot stall tab
   switching; press **Load full history** to pull the rest explicitly. Ordinary Shell scrolling
-  stays within the bounded browser buffer so dragging upward remains responsive.
+  and automatic output recovery stay within the bounded browser buffer.
 - **Wheel and touch scrolling** are forwarded into Claude's own transcript on recent Claude
   versions, so the wheel scrolls the conversation rather than the terminal. `Shift+Wheel` is
   always local scrollback. Other CLIs scroll locally.

install.sh

@@ -125,6 +125,22 @@ PI_SEARCH_PATHS=(
     "$HOME/bin/pi"
 )
 
+# DeepSeek Harness search paths (from src/utils/deepseek-cli-resolver.ts)
+DSH_SEARCH_PATHS=(
+    "$HOME/.local/bin/dsh"
+    "/usr/local/bin/dsh"
+    "$HOME/.npm-global/bin/dsh"
+    "$HOME/bin/dsh"
+)
+
+# Grok CLI search paths (from src/utils/grok-cli-resolver.ts)
+GROK_SEARCH_PATHS=(
+    "$HOME/.grok/bin/grok"
+    "$HOME/.local/bin/grok"
+    "/usr/local/bin/grok"
+    "$HOME/bin/grok"
+)
+
 # Antigravity CLI search paths (from src/utils/antigravity-cli-resolver.ts)
 ANTIGRAVITY_SEARCH_PATHS=(
     "$HOME/.local/bin/agy"
@@ -229,7 +245,11 @@ print_security_notice() {
             echo -e "  ${YELLOW}${BOLD}Security:${NC}"
             echo -e "    Codeman binds ${BOLD}127.0.0.1${NC} (this machine only) — no password needed by default."
             echo -e "    To reach it from another device, do ONE of:"
-            echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
+            if check_tailscale; then
+                echo -e "      ${CYAN}•${NC} ${CYAN}bash $INSTALL_DIR/install.sh tailscale${NC}   ${DIM}(Tailscale is installed here; HTTPS, recommended)${NC}, or"
+            else
+                echo -e "      ${CYAN}•${NC} tailscale serve / cloudflared tunnel   ${DIM}(recommended)${NC}, or"
+            fi
             echo -e "      ${CYAN}•${NC} ${CYAN}codeman web --host 0.0.0.0${NC}  AND set ${CYAN}CODEMAN_PASSWORD${NC}"
             echo -e "    A non-loopback bind without a password still starts, but warns loudly."
             echo -e "    ${DIM}Details: docs/security-architecture.md${NC}"
@@ -396,6 +416,27 @@ check_tmux() {
     command -v tmux &>/dev/null
 }
 
+# node-pty ships prebuilt binaries for darwin and win32 ONLY, so on Linux it is
+# always compiled from source during `npm install`. Without a toolchain that
+# fails deep inside node-gyp with `not found: make`, which reads like an npm bug
+# rather than a missing system package (issue: fresh Ubuntu 24 server install).
+# So the toolchain is checked up front, exactly like git and tmux.
+#
+# Returns a human-readable list of what is missing, empty when all present.
+missing_build_tools() {
+    local missing=""
+    command -v make &>/dev/null || missing="make"
+    if ! command -v c++ &>/dev/null && ! command -v g++ &>/dev/null && ! command -v clang++ &>/dev/null; then
+        missing="${missing:+$missing, }a C++ compiler (g++)"
+    fi
+    command -v python3 &>/dev/null || missing="${missing:+$missing, }python3"
+    printf '%s' "$missing"
+}
+
+check_build_tools() {
+    [[ -z "$(missing_build_tools)" ]]
+}
+
 check_claude() {
     # Check PATH first
     if command -v claude &>/dev/null; then
@@ -569,6 +610,88 @@ get_pi_path() {
     done
 }
 
+# `grok` has known squatters too (the unrelated @vibe-kit/grok-cli), so the
+# server-side resolver additionally probes `grok --version`. Detection here only
+# feeds the "you have no AI CLI" hint, so a plain executable test is enough.
+check_grok() {
+    if command -v grok &>/dev/null; then
+        return 0
+    fi
+
+    for path in "${GROK_SEARCH_PATHS[@]}"; do
+        if [[ -x "$path" ]]; then
+            return 0
+        fi
+    done
+
+    return 1
+}
+
+# `dsh` is the hardest name of the lot: Debian ships an unrelated `dsh`
+# (dancer's shell). The server-side resolver settles it by demanding the
+# harness's own help banner; detection here only feeds the "you have no AI CLI"
+# hint, so the same banner grep is enough — but unlike every sibling probe it
+# EXECUTES the candidate, so it must be bounded. </dev/null is load-bearing
+# twice over: a foreign binary that blocks on stdin would hang the install, and
+# under `curl | bash` a child that reads stdin EATS THE REST OF THIS SCRIPT.
+# The timeout (where coreutils ships one; stock macOS has none) bounds a binary
+# that ignores EOF, mirroring the server resolver's own EXEC_TIMEOUT_MS.
+dsh_banner_probe() {
+    local runner=()
+    if command -v timeout &>/dev/null; then runner=(timeout 5); fi
+    "${runner[@]}" "$1" --help </dev/null 2>/dev/null | grep -qi "DeepSeek Harness"
+}
+
+# Resolved ONCE and memoized: the probe executes a possibly-foreign binary, and
+# the check/get/reminder call sites together used to re-run the whole scan many
+# times per install.
+DSH_RESOLVE_DONE=""
+DSH_RESOLVED_PATH=""
+resolve_dsh() {
+    [[ -n "$DSH_RESOLVE_DONE" ]] && return 0
+    DSH_RESOLVE_DONE=1
+    local candidate path
+    if command -v dsh &>/dev/null; then
+        candidate="$(command -v dsh)"
+        if dsh_banner_probe "$candidate"; then
+            DSH_RESOLVED_PATH="$candidate"
+            return 0
+        fi
+    fi
+
+    for path in "${DSH_SEARCH_PATHS[@]}"; do
+        if [[ -x "$path" ]] && dsh_banner_probe "$path"; then
+            DSH_RESOLVED_PATH="$path"
+            return 0
+        fi
+    done
+    return 0
+}
+
+check_dsh() {
+    resolve_dsh
+    [[ -n "$DSH_RESOLVED_PATH" ]]
+}
+
+get_dsh_path() {
+    resolve_dsh
+    echo "$DSH_RESOLVED_PATH"
+}
+
+get_grok_path() {
+    if command -v grok &>/dev/null; then
+        command -v grok
+        return
+    fi
+
+    for path in "${GROK_SEARCH_PATHS[@]}"; do
+        if [[ -x "$path" ]]; then
+            echo "$path"
+            return
+        fi
+    done
+}
+
 check_cloudflared() {
     # Check ~/.local/bin first (matches tunnel-manager.ts resolution order)
     if [[ -x "$HOME/.local/bin/cloudflared" ]]; then
@@ -836,6 +959,50 @@ install_git_suse() {
     run_as_root zypper install -y git
 }
 
+# Build toolchain for node-pty's source compile (see missing_build_tools).
+install_buildtools_debian() {
+    info "Installing build tools via apt (build-essential, python3)..."
+    ensure_sudo
+    run_as_root apt-get update -qq
+    run_as_root apt-get install -y -qq build-essential python3
+}
+
+install_buildtools_fedora() {
+    info "Installing build tools (gcc, gcc-c++, make, python3)..."
+    ensure_sudo
+    if command -v dnf &>/dev/null; then
+        run_as_root dnf install -y gcc gcc-c++ make python3
+    else
+        run_as_root yum install -y gcc gcc-c++ make python3
+    fi
+}
+
+install_buildtools_arch() {
+    info "Installing build tools via pacman (base-devel, python)..."
+    ensure_sudo
+    run_as_root pacman -Sy --noconfirm base-devel python
+}
+
+install_buildtools_alpine() {
+    info "Installing build tools via apk (build-base, python3)..."
+    ensure_sudo
+    run_as_root apk add --no-cache build-base python3
+}
+
+install_buildtools_suse() {
+    info "Installing build tools via zypper..."
+    ensure_sudo
+    run_as_root zypper install -y gcc gcc-c++ make python3
+}
+
+install_buildtools_macos() {
+    # macOS normally never gets here: node-pty ships darwin prebuilds. Only a
+    # forced source build needs a compiler, and Xcode CLT is its only supplier.
+    info "Requesting Xcode Command Line Tools..."
+    xcode-select --install 2>/dev/null || true
+    die "Finish the Xcode Command Line Tools install in the dialog, then re-run this installer."
+}
+
 install_cloudflared_macos() {
     info "Installing cloudflared via Homebrew..."
     ensure_homebrew
@@ -1711,6 +1878,41 @@ setup_tailscale_access() {
     return 0
 }
 
+# A loopback install with Tailscale already connected but nothing fronting
+# Codeman is one command away from working remote access — and that is exactly
+# where a user lands when the first install died BEFORE the network-access
+# prompt (it runs after the build, so any build failure costs the network step
+# too) or when they finished a broken build by hand instead of re-running the
+# installer. Detect that state on re-run and offer the retrofit, rather than
+# leaving them to discover `install.sh tailscale` on their own. Never nags a
+# deliberate network bind, and never nags once a serve mapping already exists.
+maybe_offer_tailscale_repair() {
+    # A non-loopback bind already has network access; leave that choice alone.
+    if [[ "$EXISTING_FOUND" == "1" && -n "$EXISTING_HOST" && "$EXISTING_HOST" != "127.0.0.1" ]]; then
+        return 0
+    fi
+    check_tailscale || return 0
+    command -v node &>/dev/null || return 0
+    [[ "$(ts_status_field 's.BackendState')" == "Running" ]] || return 0
+    # Already fronting Codeman: nothing to repair.
+    [[ -z "$(detect_tailscale_serve_url)" ]] || return 0
+
+    echo ""
+    info "Tailscale is connected here, but no serve mapping fronts Codeman yet."
+    if [[ "$NONINTERACTIVE" == "1" ]] || ! has_tty; then
+        echo -e "  ${DIM}Enable HTTPS access from your tailnet with:${NC} ${CYAN}bash $INSTALL_DIR/install.sh tailscale${NC}"
+        return 0
+    fi
+    if ! prompt_yes_no "Set up Tailscale HTTPS access now? (your tailnet is the login; no password needed)" "y"; then
+        echo -e "  ${DIM}Any time later:${NC} ${CYAN}bash $INSTALL_DIR/install.sh tailscale${NC}"
+        return 0
+    fi
+    if setup_tailscale_access; then
+        verify_tailscale_access || true
+    fi
+    return 0
+}
+
 # `install.sh tailscale`: retrofit Tailscale access onto an existing install
 # (also the target of every "set it up later" hint above).
 setup_tailscale_subcommand() {
@@ -1963,6 +2165,29 @@ setup_tunnel_service() {
 # Installation Helpers
 # ============================================================================
 
+# npm install with an actionable message for the failure that actually happens
+# on a fresh Linux box: no toolchain, so node-pty cannot compile.
+npm_install_deps() {
+    if npm install --quiet --no-fund --no-audit 2>/dev/null; then
+        return 0
+    fi
+    if npm install --no-fund --no-audit; then
+        return 0
+    fi
+
+    error "npm install failed."
+    if [[ "$(detect_os)" == "linux" ]] && ! check_build_tools; then
+        error "Missing native build tools: $(missing_build_tools)"
+        error "node-pty has no Linux prebuilds, so it must compile from source."
+        error "Install them and re-run this installer:"
+        error "  Debian/Ubuntu:  sudo apt-get install -y build-essential python3"
+        error "  Fedora/RHEL:    sudo dnf install -y gcc gcc-c++ make python3"
+        error "  Arch:           sudo pacman -S --noconfirm base-devel python"
+        error "  Alpine:         sudo apk add build-base python3"
+    fi
+    exit 1
+}
+
 install_dependency() {
     local dep_name="$1"
     local os="$2"
@@ -2076,6 +2301,31 @@ main() {
         fi
     fi
 
+    # Native build toolchain. node-pty compiles from source on Linux, so this is
+    # a hard requirement there, not a nicety.
+    if [[ "$os" == "linux" ]]; then
+        info "Checking build tools (node-pty compiles from source on Linux)..."
+        local missing_tools
+        missing_tools="$(missing_build_tools)"
+        if [[ -z "$missing_tools" ]]; then
+            success "Build tools are installed"
+        else
+            warn "Missing build tools: $missing_tools"
+            headless_guard "install build tools (system package via sudo)"
+            if prompt_yes_no "Install the build tools now?"; then
+                install_dependency "buildtools" "$os" "$distro"
+                hash -r 2>/dev/null || true
+                missing_tools="$(missing_build_tools)"
+                if [[ -n "$missing_tools" ]]; then
+                    die "Build tools still missing after install: $missing_tools. Install them manually and re-run."
+                fi
+                success "Build tools installed"
+            else
+                die "A build toolchain (make, g++, python3) is required: node-pty has no Linux prebuilds and compiles from source."
+            fi
+        fi
+    fi
+
     # AI CLI (Codeman drives one of: Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi)
     local has_claude=false
     local has_opencode=false
@@ -2083,6 +2333,8 @@ main() {
     local has_gemini=false
     local has_antigravity=false
     local has_pi=false
+    local has_grok=false
+    local has_dsh=false
 
     info "Checking AI CLI tools..."
     if check_claude; then
@@ -2109,17 +2361,25 @@ main() {
         has_pi=true
         success "Pi CLI found at $(get_pi_path)"
     fi
+    if check_grok; then
+        has_grok=true
+        success "Grok CLI found at $(get_grok_path)"
+    fi
+    if check_dsh; then
+        has_dsh=true
+        success "DeepSeek Harness found at $(get_dsh_path)"
+    fi
 
-    if [[ "$has_claude" == "false" && "$has_opencode" == "false" && "$has_codex" == "false" && "$has_gemini" == "false" && "$has_antigravity" == "false" && "$has_pi" == "false" ]]; then
+    if [[ "$has_claude" == "false" && "$has_opencode" == "false" && "$has_codex" == "false" && "$has_gemini" == "false" && "$has_antigravity" == "false" && "$has_pi" == "false" && "$has_grok" == "false" && "$has_dsh" == "false" ]]; then
         echo ""
-        warn "No AI CLI found. Codeman needs at least one: Claude Code, OpenCode, Codex, Antigravity, Gemini, or Pi."
+        warn "No AI CLI found. Codeman needs at least one: Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, or DeepSeek Harness."
         headless_guard "install an AI CLI (curl | bash from its vendor)"
         echo ""
         echo -e "  ${BOLD}Which AI CLI would you like to install?${NC}"
         echo -e "    ${CYAN}1)${NC} Claude Code  (Anthropic)"
         echo -e "    ${CYAN}2)${NC} OpenCode     (open-source)"
         echo -e "    ${CYAN}3)${NC} Both"
-        echo -e "    ${CYAN}4)${NC} Skip         (I'll install one myself, e.g. Codex, Antigravity or Pi)"
+        echo -e "    ${CYAN}4)${NC} Skip         (I'll install one myself, e.g. Codex, Antigravity, Pi or Grok)"
         echo ""
 
         local cli_choice=""
@@ -2167,6 +2427,7 @@ main() {
             info "Install one later, e.g.: npm install -g @openai/codex                          (Codex)"
             info "                    or: curl -fsSL https://antigravity.google/cli/install.sh | bash  (Antigravity)"
             info "                    or: npm install -g --ignore-scripts @earendil-works/pi-coding-agent   (Pi)"
+            info "                    or: curl -fsSL https://x.ai/cli/install.sh | bash                     (Grok)"
         elif [[ "$has_claude" == "false" ]] && [[ "$has_opencode" == "false" ]]; then
             die "The selected AI CLI failed to install. Install one manually and re-run the installer."
         fi
@@ -2232,7 +2493,7 @@ main() {
     # ========================================================================
 
     info "Installing dependencies..."
-    npm install --quiet --no-fund --no-audit 2>/dev/null || npm install --no-fund --no-audit
+    npm_install_deps
 
     info "Building..."
     npm run build --quiet 2>/dev/null || npm run build
@@ -2467,13 +2728,14 @@ main() {
     echo -e "    https://github.com/Ark0N/Codeman"
     echo ""
 
-    if ! check_claude && ! check_opencode && ! check_codex && ! check_gemini && ! check_antigravity && ! check_pi; then
+    if ! check_claude && ! check_opencode && ! check_codex && ! check_gemini && ! check_antigravity && ! check_pi && ! check_grok && ! check_dsh; then
         echo -e "  ${YELLOW}${BOLD}Reminder:${NC} Install at least one AI CLI to start using Codeman:"
         echo -e "    ${CYAN}curl -fsSL https://claude.ai/install.sh | bash${NC}                # Claude Code"
         echo -e "    ${CYAN}curl -fsSL https://opencode.ai/install | bash${NC}                 # OpenCode"
         echo -e "    ${CYAN}npm install -g @openai/codex${NC}                                  # Codex"
         echo -e "    ${CYAN}curl -fsSL https://antigravity.google/cli/install.sh | bash${NC}   # Antigravity"
         echo -e "    ${CYAN}npm install -g --ignore-scripts @earendil-works/pi-coding-agent${NC}  # Pi"
+        echo -e "    ${CYAN}curl -fsSL https://x.ai/cli/install.sh | bash${NC}                 # Grok"
         echo ""
     fi
 
@@ -2527,7 +2789,7 @@ update() {
 
     git fetch --quiet origin
     git reset --hard "origin/$BRANCH" --quiet
-    npm install --quiet --no-fund --no-audit 2>/dev/null || npm install --no-fund --no-audit
+    npm_install_deps
     npm run build --quiet 2>/dev/null || npm run build
     date -u +%Y-%m-%dT%H:%M:%SZ > "$INSTALL_DIR/.install-complete"
     success "Updated to $(node -e "console.log(require('./package.json').version)")"
@@ -2564,6 +2826,10 @@ update() {
         BIND_ACK="$EXISTING_ACK"
     fi
 
+    # An update is the only place a half-configured install gets a second
+    # chance at remote access; the fresh-install path asks outright.
+    maybe_offer_tailscale_repair
+
     print_security_notice
 }
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.21.0",
+  "version": "1.23.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.21.0",
+      "version": "1.23.2",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.21.0",
+  "version": "1.23.2",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -62,6 +62,8 @@
     "codex",
     "antigravity",
     "pi",
+    "grok",
+    "deepseek",
     "gemini-cli",
     "ai-agents",
     "agent",

scripts/build.mjs

@@ -86,6 +86,7 @@ run('minify input-cjk.js', 'npx esbuild dist/web/public/input-cjk.js --minify --
 run('minify i18n.js', 'npx esbuild dist/web/public/i18n.js --minify --outfile=dist/web/public/i18n.js --allow-overwrite');
 run('minify sanitize-html.js', 'npx esbuild dist/web/public/sanitize-html.js --minify --outfile=dist/web/public/sanitize-html.js --allow-overwrite');
 run('minify app.js', 'npx esbuild dist/web/public/app.js --minify --outfile=dist/web/public/app.js --allow-overwrite');
+run('minify tab-rail-resize.js', 'npx esbuild dist/web/public/tab-rail-resize.js --minify --outfile=dist/web/public/tab-rail-resize.js --allow-overwrite');
 run('minify terminal-ui.js', 'npx esbuild dist/web/public/terminal-ui.js --minify --outfile=dist/web/public/terminal-ui.js --allow-overwrite');
 run('minify respawn-ui.js', 'npx esbuild dist/web/public/respawn-ui.js --minify --outfile=dist/web/public/respawn-ui.js --allow-overwrite');
 run('minify ralph-panel.js', 'npx esbuild dist/web/public/ralph-panel.js --minify --outfile=dist/web/public/ralph-panel.js --allow-overwrite');
@@ -111,6 +112,7 @@ console.log('\n[build] content-hash cache busting');
     'input-cjk.js',
     'sanitize-html.js',
     'app.js',
+    'tab-rail-resize.js',
     'terminal-ui.js',
     'respawn-ui.js',
     'ralph-panel.js',

skills/codeman/SKILL.md

@@ -47,7 +47,7 @@ later call opens with, and your first REAL call performs them anyway:
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null
-[ "${CODEMAN_PREAMBLE:-}" = 1.19.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.20.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 ```
 
 ⚠️ **Never spend a Bash call on this check alone.** §1's block opens with this same
@@ -75,8 +75,8 @@ PRE="${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh"
 mkdir -p "$(dirname "$PRE")"
 # Rewrite unless the file already ends with THIS version's stamp, so a stale or a
 # half-written file self-heals here instead of costing you a round trip to rm it.
-grep -qs '^CODEMAN_PREAMBLE=1.19.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
-# ---- Codeman agent preamble 1.19.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+grep -qs '^CODEMAN_PREAMBLE=1.20.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.20.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -121,23 +121,53 @@ _composer_up() {   # <sid> <timeoutMs> -> "true"/"false". `shift+tab` is the one
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \
     --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
 }
+_dsh_up() {        # <sid> <timeoutMs> -> "true"/"false". The DeepSeek Harness TUI's
+  # composer glyph. Override with DSH_READY_MARK for a profile that draws another one.
+  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+    --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \
+    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+}
 # spawn_worker <caseName> [mode] -> session id on stdout, diagnostics on stderr.
 # quick-start AND readiness in one call, with a strict contract: NON-EMPTY stdout means
-# a READY claude worker in a hook-carrying case. Anything less is rc 1 with EMPTY
-# stdout, and the half-spawned session is deleted here rather than handed back, because
-# a worker that never drew its composer would eat the task prompt with its trust
-# dialog. There is deliberately no pid poll: wait-output already blocks until the
-# composer draws, and pid!=null proved startup, never readiness.
+# a READY worker whose end-of-turn signal can be trusted -- a claude worker in a
+# hook-carrying case, or a `deepseek` worker whose harness TUI drew its composer.
+# Anything less is rc 1 with EMPTY stdout, and the half-spawned session is deleted here
+# rather than handed back, because a worker that never drew its composer would eat the
+# task prompt with its trust dialog. There is deliberately no pid poll: wait-output
+# already blocks until the composer draws, and pid!=null proved startup, never readiness.
 spawn_worker() {
   local name="${1:?spawn_worker needs a case name}" mode="${2:-claude}" q sid cp r
   # parentSessionId doubles the CURL header, so a spawn_worker copied off the shared
   # curl (or a body someone rebuilt from this recipe) still carries its lineage.
+  # deepseek: ask for the same permission posture the Run button sends, because the
+  # harness's own default (`workspace-write`) still ASKS, and a worker that stops on
+  # an approval row is a worker no fan-out can finish. It is not an escalation --
+  # claude workers already spawn with permissions skipped, and in multi-user mode the
+  # server clamps this back to `workspace-write` for an owner without the grant.
+  # Spawn by hand (§5.1) when you want a worker that asks.
   q=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" -H 'Content-Type: application/json' \
-      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" '{caseName:$n,mode:$m,parentSessionId:$p}')")
+      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" \
+        '{caseName:$n,mode:$m,parentSessionId:$p}
+         + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)')")
   sid=$(jq -r 'if .success then .data.sessionId else empty end' <<<"$q")
   # NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
   [ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
-  [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; }   # only claude draws a composer
+  if [ "$mode" = deepseek ]; then
+    # The one non-claude mode with REAL end-of-turn signals: its TUI reports
+    # idle/working/blocked to Codeman, so sendwait, until=stop and the Approvals
+    # Inbox all work here exactly as they do for claude. No hook file to vet
+    # (the bridge is env-injected, not a workspace file) and no trust dialog.
+    # ⚠️ Readiness is still not optional, and NOT interchangeable with the stop
+    # signal: the harness's boot report lands ~300ms BEFORE the composer paints
+    # (measured 2.26s vs 2.56s after spawn), so a sendwait fired straight after
+    # quick-start returns on that BOOT signal, reports a turn that never ran, and
+    # strands the prompt in a pane that was not yet taking input.
+    r=$(_dsh_up "$sid" 45000)
+    [ "$r" = true ] || { echo "dsh worker $sid never drew a composer: no pane-capable profile, a profile whose composer is not '${DSH_READY_MARK:-❯}' (set DSH_READY_MARK), or a harness that failed to boot -- check GET /api/v1/deepseek/status. Deleted it" >&2
+      delete_session "$sid" >/dev/null; return 1; }
+    printf '%s\n' "$sid"; return 0
+  fi
+  [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; }   # no other mode draws a composer to wait on
   # The server installs hooks into every claude workspace now, so this grep normally
   # passes; it stays because the install is gated on a setting the operator can turn
   # off, remote sessions never get hooks, and a session created by an older server
@@ -166,19 +196,25 @@ spawn_worker() {
     delete_session "$sid" >/dev/null; return 1; }
   printf '%s\n' "$sid"
 }
-# spawn_workers <caseName>... -> one "<caseName> <sessionId>" line per worker, in order;
-# the sessionId column is EMPTY for a spawn that failed (stderr has why). CONCURRENT:
-# N workers cost about what one costs. Spawning them one Bash call at a time is the
-# single biggest avoidable delay in this skill. Names must be UNIQUE: two workers in
-# one case directory co-edit the same tree (§4), so a repeat is an error here, not a race.
+# spawn_workers <caseName[:mode]>... -> one "<caseName> <sessionId>" line per worker, in
+# order; the sessionId column is EMPTY for a spawn that failed (stderr has why).
+# CONCURRENT: N workers cost about what one costs. Spawning them one Bash call at a time
+# is the single biggest avoidable delay in this skill. A bare name is a claude worker;
+# `beta:deepseek` makes that one a DeepSeek Harness worker, and a mixed fleet is one
+# call. Case names must be UNIQUE: two workers in one case directory co-edit the same
+# tree (§4), so a repeat is an error here, not a race (the mode never disambiguates two
+# workers, since they would still share the directory).
 spawn_workers() {
-  local d n i=0
+  local d spec n m i=0
   [ "$#" -gt 0 ] || { echo "spawn_workers: no case names given" >&2; return 1; }
-  [ -z "$(printf '%s\n' "$@" | sort | uniq -d)" ] || { echo "spawn_workers: duplicate case names" >&2; return 1; }
+  [ -z "$(printf '%s\n' "$@" | sed 's/:.*//' | sort | uniq -d)" ] || { echo "spawn_workers: duplicate case names" >&2; return 1; }
   d=$(mktemp -d "${TMPDIR:-/tmp}/codeman-spawn.XXXXXX") || return 1
-  for n in "$@"; do ( spawn_worker "$n" > "$d/$i" ) & i=$((i+1)); done
+  for spec in "$@"; do
+    n=${spec%%:*}; m=${spec#*:}; [ "$m" = "$spec" ] && m=claude
+    ( spawn_worker "$n" "$m" > "$d/$i" ) & i=$((i+1))
+  done
   wait
-  i=0; for n in "$@"; do printf '%s %s\n' "$n" "$(cat "$d/$i" 2>/dev/null)"; i=$((i+1)); done
+  i=0; for spec in "$@"; do printf '%s %s\n' "${spec%%:*}" "$(cat "$d/$i" 2>/dev/null)"; i=$((i+1)); done
   rm -rf "$d"
 }
 # sendwait <sid> <prompt> [seq] -> blocks until that worker's turn ENDS (~10 min ceiling
@@ -194,27 +230,46 @@ spawn_workers() {
 # (observed live). So the first wait is short; on its timeout a bare \r goes out (the
 # missing Enter when the prompt is stranded, a no-op when the turn is genuinely
 # running), then the ORIGINAL frame is resent unchanged, which the server takes as a
-# tagged duplicate: it re-waits without retyping (§5.3). Trustworthy only for a claude
-# worker spawn_worker handed back (hooks vetted); hook-less workspaces and other modes
-# resolve on flapping idle: markers instead (§5.5).
+# tagged duplicate: it re-waits without retyping (§5.3). Trustworthy for a worker
+# spawn_worker handed back -- claude (hooks vetted) or deepseek (status bridge) --
+# and for those only. Hook-less workspaces and the other modes resolve on flapping
+# idle: markers instead (§5.5). ⚠️ A dsh worker running a profile that does not
+# implement the status contract is the one case that LOOKS like claude but is not:
+# it accepts the send and then burns both waits. One timeout on a dsh worker whose
+# pane clearly finished means that profile, so switch that worker to markers.
 sendwait() {
   local sid="${1:?}" p="${2:?}" seq="${3:-$(date +%s)}" body r
+  # `wait:"stop,exit"`, never the `wait:true` default set: that set also carries
+  # `idle`, which is INFERRED from output stabilization and flaps mid-turn. On a
+  # dsh worker whose TUI repaints rarely the session reads `idle` while the model
+  # is still answering, and the re-wait below then resolved in 0 ms with
+  # `signal:"idle"` on a turn that had another three minutes to run (measured).
+  # A wait named after the end of a turn should only end with the turn, or with
+  # the worker. ⚠️ This is also what makes a wrong mode LOUD: the modes that
+  # cannot deliver `stop` answer 400 (before writing anything) instead of
+  # resolving on a flap, which is the answer that sends you to markers (§5.5).
   body=$(jq -nc --arg p "$p" --arg c "$CID-$sid" --argjson s "$seq" \
-    '{input:($p+"\r"),useMux:true,clientId:$c,seq:$s,wait:true,waitTimeout:20000}')
+    '{input:($p+"\r"),useMux:true,clientId:$c,seq:$s,wait:"stop,exit",waitTimeout:20000}')
   r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \
         -H 'Content-Type: application/json' --data-binary "$body")
   if jq -e '.data.delivered and .data.wait.timedOut' <<<"$r" >/dev/null 2>&1; then
     "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
       -d "$(jq -nc --arg c "$CID-$sid" --argjson s "$(date +%s)" \
         '{input:"\r",useMux:true,clientId:$c,seq:$s}')" >/dev/null
+    # The resend is a tagged DUPLICATE, so the server skips the write and reports
+    # `delivered:false` for it -- truthfully, but about the wrong send. The first
+    # one delivered, so carry that forward, or §1's cleanup reads a completed turn
+    # as an undelivered one and keeps a finished worker forever.
     r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \
-          -H 'Content-Type: application/json' --data-binary "$(jq -c '.waitTimeout=580000' <<<"$body")")
+          -H 'Content-Type: application/json' --data-binary "$(jq -c '.waitTimeout=580000' <<<"$body")" \
+        | jq -c 'if .success and (.data.wait.ended | not) then .data.delivered = true else . end')
   fi
   printf '%s\n' "$r"
 }
-# last_text <sid> [prev] -> that worker's last assistant message. Polled, because the
-# transcript write LAGS the stop signal, and "some text exists" is not "THIS turn's
-# text exists": right after a SECOND turn on the same worker the endpoint still serves
+# last_text <sid> [prev] -> that worker's last assistant message (claude, codex and
+# deepseek write a real transcript; the other modes have none, so read the terminal
+# instead -- §5.4). Polled, because the transcript write LAGS the stop signal, and
+# "some text exists" is not "THIS turn's text exists": right after a SECOND turn on the same worker the endpoint still serves
 # the previous answer for a beat (observed live). When reading consecutive turns, pass
 # the previous answer as [prev]: the poll then holds out for text that differs from it,
 # falling back to whatever it last saw if the budget runs dry, so an honestly repeated
@@ -233,10 +288,10 @@ last_text() {
 # The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
 # bare on purpose: the write condition above anchors on it with $, so an inline comment
 # here would fail that match and rewrite this file on every single bootstrap.
-CODEMAN_PREAMBLE=1.19.0
+CODEMAN_PREAMBLE=1.20.0
 PREAMBLE
 )
-. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.19.0 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
+. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.20.0 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
 ```
 
 Every later Bash call that touches the API starts with the same two loader lines from
@@ -287,8 +342,9 @@ and no per-call body to hand-build.
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null   # §0 loader
-[ "${CODEMAN_PREAMBLE:-}" = 1.19.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.20.0 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 N=(alpha beta)                    # INVENT one fresh case name per worker; never list cases first
+                                  # (a name may carry a mode: `beta:deepseek`, see below)
 T=('reply with one line: the absolute path of your working directory'
    'reply with one line: your model name')            # tasks, same order as N
 
@@ -353,6 +409,37 @@ Four things this block leans on, each one link away, no detour needed to run it:
 - Each `sendwait` costs that worker one billed turn, as does every prompt you send it.
 - Deleting the sessions does **not** remove the case directories: §5.14.
 
+### DeepSeek Harness workers
+
+The block above spawns claude workers. Any entry in `N` may instead name a mode
+(`beta:deepseek`), and **a `deepseek` worker is driven by the same four verbs, with no
+change to the rest of the block**: `spawn_workers` waits for its composer, `sendwait`
+blocks on its real end-of-turn signal, `last_text` reads its answer, `delete_session`
+removes it.
+
+That is true of no other non-claude mode, and it is worth knowing why: the DeepSeek
+Harness TUI reports `idle`/`working`/`blocked` to Codeman over the supervisor contract it
+implements, so dsh is the one external CLI with definitive `stop`/`blocked` signals
+instead of guessed-from-silence ones — and it writes a structured transcript, which is
+what `last-response` reads for it. `shell`, `opencode`, `codex`, `gemini`, `antigravity`,
+`pi` and `grok` have neither and still need markers ([§5.5](reference/verbs.md#55-markers-for-hook-less-workers)).
+
+Three things to know before you spawn one:
+
+- **It needs a pane-capable profile.** `dsh` ships only `web`/`headless`, so the terminal
+  agent is always an installed profile. `GET /api/v1/deepseek/status` answers both
+  questions separately (`available` = the binary, `runnable` = a profile that can drive a
+  pane); a spawn without one fails with `OPERATION_FAILED` rather than falling back.
+- **Do not task it on the strength of a `stop` alone.** The harness reports `idle` at
+  boot ~300 ms *before* its composer paints (measured 2.26 s vs 2.56 s), so a `sendwait`
+  fired straight after `quick-start` resolves on that boot signal, reports a turn that
+  never ran, and leaves the prompt in a pane that was not yet taking input. Letting
+  `spawn_worker` gate on readiness is what steps past that edge; it is not optional.
+- **A profile that does not implement the contract looks like a hang.** Codeman cannot
+  know at spawn time whether one does. The tell is a `sendwait` that times out on a
+  worker whose pane clearly finished: that profile is one of them, so drive it with
+  markers instead.
+
 ## 2. What do you want to do?
 
 One row per job. Acting on this table alone is correct; the §5 links are the detail.
@@ -360,10 +447,10 @@ One row per job. Acting on this table alone is correct; the §5 links are the de
 | I want to | Call | Detail |
 |-----------|------|--------|
 | start a worker **where the work is** | `POST /api/v1/quick-start {"caseName":…}`, which **creates** `~/codeman-cases/<name>` unless the name is already a case. Any other path (a git worktree): `POST /api/v1/sessions {"workingDir":…}` then `POST /api/v1/sessions/:id/interactive`. Both install hooks by default, so expect full signals in either, and **verify** rather than assume. N workers means N worktrees | [§5.1](reference/verbs.md#51-where-to-spawn) |
-| know a new worker can accept a prompt | `GET .../wait-output?match=shift+tab&from=buffer` (urlencode the `+`) | [§5.2](reference/verbs.md#52-readiness) |
-| deliver a task **and** know when it finished | `POST .../input` with `"input":"…\r"`, `clientId`, `seq`, `"wait":true`. Resolves on `stop`, so it is trustworthy only where the workspace **has hooks** (claude mode; installed by default, but the operator can disable it and remote sessions never get them). Costs the worker one billed turn | [§5.3](reference/verbs.md#53-send-a-task-and-wait) |
+| know a new worker can accept a prompt | `GET .../wait-output?match=shift+tab&from=buffer` (urlencode the `+`); a `deepseek` worker draws `❯` instead, and its boot `stop` fires ~300 ms BEFORE that, so never read the signal as readiness | [§5.2](reference/verbs.md#52-readiness) |
+| deliver a task **and** know when it finished | `POST .../input` with `"input":"…\r"`, `clientId`, `seq`, `"wait":true`. Resolves on `stop`, so it is trustworthy where the signal is real: claude mode with hooks (installed by default, but the operator can disable it and remote sessions never get them) and `deepseek` mode through its status bridge. Costs the worker one billed turn | [§5.3](reference/verbs.md#53-send-a-task-and-wait) |
 | know a hook-less worker finished | it has no `stop`, and `wait:true` there resolves on flapping `idle` **without erroring**: make it print a split, unique marker and `wait-output` on that instead | [§5.5](reference/verbs.md#55-markers-for-hook-less-workers) |
-| read the answer | `GET .../last-response`, **polled** (claude/codex only; empty for the other modes) | [§5.4](reference/verbs.md#54-read-the-answer) |
+| read the answer | `GET .../last-response`, **polled** (claude, codex and deepseek write a transcript; empty for the other modes) | [§5.4](reference/verbs.md#54-read-the-answer) |
 | know if it is alive | `GET .../wait?until=exit&timeout=1000`: an immediate `signal:"exit"` means dead. `status` and `pid` both lie | [§5.6](reference/verbs.md#56-alive-and-stuck) |
 | know if it is stuck | `GET .../active-tools` and `GET .../run-summary` are structured and free; two `terminal?tail=` samples are the crude fallback | [§5.6](reference/verbs.md#56-alive-and-stuck) |
 | make a runaway worker stop | `POST .../input {"input":"\u001b"}` (ESC, **no** `\r`). Deleting the session would destroy the conversation instead | [§5.7](reference/verbs.md#57-interrupt-without-destroying) |
@@ -464,7 +551,7 @@ these**; open the one row you actually hit.
 | [5.1 Where to spawn](reference/verbs.md#51-where-to-spawn) | the work is **not** a fresh scratch case: a linked case, a git worktree, any path that already existed. Hooks are absent there, which silently breaks send-and-wait. The costliest mistake in this skill |
 | [5.2 Readiness](reference/verbs.md#52-readiness) | a worker never drew its composer, or you need the trust-dialog ladder by hand |
 | [5.3 Send a task and wait](reference/verbs.md#53-send-a-task-and-wait) | the `sendwait` body, its signals, and the duplicate-resend loop |
-| [5.4 Read the answer](reference/verbs.md#54-read-the-answer) | `last_text` came back empty, or the mode is not claude/codex |
+| [5.4 Read the answer](reference/verbs.md#54-read-the-answer) | `last_text` came back empty, or the mode is not claude/codex/deepseek |
 | [5.5 Markers for hook-less workers](reference/verbs.md#55-markers-for-hook-less-workers) | the worker has no `stop` hook: synchronize on a split, unique printed marker |
 | [5.6 Alive and stuck](reference/verbs.md#56-alive-and-stuck) | is it dead or just slow? `status` and `pid` both lie |
 | [5.7 Interrupt without destroying](reference/verbs.md#57-interrupt-without-destroying) | a runaway worker you want to stop but keep |

skills/codeman/preamble.sh

@@ -1,4 +1,4 @@
-# ---- Codeman agent preamble 1.19.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# ---- Codeman agent preamble 1.20.0 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -43,23 +43,53 @@ _composer_up() {   # <sid> <timeoutMs> -> "true"/"false". `shift+tab` is the one
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' \
     --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
 }
+_dsh_up() {        # <sid> <timeoutMs> -> "true"/"false". The DeepSeek Harness TUI's
+  # composer glyph. Override with DSH_READY_MARK for a profile that draws another one.
+  "${CURL[@]}" -G "$API/api/v1/sessions/$1/wait-output" \
+    --data-urlencode "match=${DSH_READY_MARK:-❯}" --data-urlencode 'from=buffer' \
+    --data-urlencode "timeout=$2" | jq -r '.data.wait.matched // false'
+}
 # spawn_worker <caseName> [mode] -> session id on stdout, diagnostics on stderr.
 # quick-start AND readiness in one call, with a strict contract: NON-EMPTY stdout means
-# a READY claude worker in a hook-carrying case. Anything less is rc 1 with EMPTY
-# stdout, and the half-spawned session is deleted here rather than handed back, because
-# a worker that never drew its composer would eat the task prompt with its trust
-# dialog. There is deliberately no pid poll: wait-output already blocks until the
-# composer draws, and pid!=null proved startup, never readiness.
+# a READY worker whose end-of-turn signal can be trusted -- a claude worker in a
+# hook-carrying case, or a `deepseek` worker whose harness TUI drew its composer.
+# Anything less is rc 1 with EMPTY stdout, and the half-spawned session is deleted here
+# rather than handed back, because a worker that never drew its composer would eat the
+# task prompt with its trust dialog. There is deliberately no pid poll: wait-output
+# already blocks until the composer draws, and pid!=null proved startup, never readiness.
 spawn_worker() {
   local name="${1:?spawn_worker needs a case name}" mode="${2:-claude}" q sid cp r
   # parentSessionId doubles the CURL header, so a spawn_worker copied off the shared
   # curl (or a body someone rebuilt from this recipe) still carries its lineage.
+  # deepseek: ask for the same permission posture the Run button sends, because the
+  # harness's own default (`workspace-write`) still ASKS, and a worker that stops on
+  # an approval row is a worker no fan-out can finish. It is not an escalation --
+  # claude workers already spawn with permissions skipped, and in multi-user mode the
+  # server clamps this back to `workspace-write` for an owner without the grant.
+  # Spawn by hand (§5.1) when you want a worker that asks.
   q=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" -H 'Content-Type: application/json' \
-      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" '{caseName:$n,mode:$m,parentSessionId:$p}')")
+      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" \
+        '{caseName:$n,mode:$m,parentSessionId:$p}
+         + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)')")
   sid=$(jq -r 'if .success then .data.sessionId else empty end' <<<"$q")
   # NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
   [ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
-  [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; }   # only claude draws a composer
+  if [ "$mode" = deepseek ]; then
+    # The one non-claude mode with REAL end-of-turn signals: its TUI reports
+    # idle/working/blocked to Codeman, so sendwait, until=stop and the Approvals
+    # Inbox all work here exactly as they do for claude. No hook file to vet
+    # (the bridge is env-injected, not a workspace file) and no trust dialog.
+    # ⚠️ Readiness is still not optional, and NOT interchangeable with the stop
+    # signal: the harness's boot report lands ~300ms BEFORE the composer paints
+    # (measured 2.26s vs 2.56s after spawn), so a sendwait fired straight after
+    # quick-start returns on that BOOT signal, reports a turn that never ran, and
+    # strands the prompt in a pane that was not yet taking input.
+    r=$(_dsh_up "$sid" 45000)
+    [ "$r" = true ] || { echo "dsh worker $sid never drew a composer: no pane-capable profile, a profile whose composer is not '${DSH_READY_MARK:-❯}' (set DSH_READY_MARK), or a harness that failed to boot -- check GET /api/v1/deepseek/status. Deleted it" >&2
+      delete_session "$sid" >/dev/null; return 1; }
+    printf '%s\n' "$sid"; return 0
+  fi
+  [ "$mode" = claude ] || { printf '%s\n' "$sid"; return 0; }   # no other mode draws a composer to wait on
   # The server installs hooks into every claude workspace now, so this grep normally
   # passes; it stays because the install is gated on a setting the operator can turn
   # off, remote sessions never get hooks, and a session created by an older server
@@ -88,19 +118,25 @@ spawn_worker() {
     delete_session "$sid" >/dev/null; return 1; }
   printf '%s\n' "$sid"
 }
-# spawn_workers <caseName>... -> one "<caseName> <sessionId>" line per worker, in order;
-# the sessionId column is EMPTY for a spawn that failed (stderr has why). CONCURRENT:
-# N workers cost about what one costs. Spawning them one Bash call at a time is the
-# single biggest avoidable delay in this skill. Names must be UNIQUE: two workers in
-# one case directory co-edit the same tree (§4), so a repeat is an error here, not a race.
+# spawn_workers <caseName[:mode]>... -> one "<caseName> <sessionId>" line per worker, in
+# order; the sessionId column is EMPTY for a spawn that failed (stderr has why).
+# CONCURRENT: N workers cost about what one costs. Spawning them one Bash call at a time
+# is the single biggest avoidable delay in this skill. A bare name is a claude worker;
+# `beta:deepseek` makes that one a DeepSeek Harness worker, and a mixed fleet is one
+# call. Case names must be UNIQUE: two workers in one case directory co-edit the same
+# tree (§4), so a repeat is an error here, not a race (the mode never disambiguates two
+# workers, since they would still share the directory).
 spawn_workers() {
-  local d n i=0
+  local d spec n m i=0
   [ "$#" -gt 0 ] || { echo "spawn_workers: no case names given" >&2; return 1; }
-  [ -z "$(printf '%s\n' "$@" | sort | uniq -d)" ] || { echo "spawn_workers: duplicate case names" >&2; return 1; }
+  [ -z "$(printf '%s\n' "$@" | sed 's/:.*//' | sort | uniq -d)" ] || { echo "spawn_workers: duplicate case names" >&2; return 1; }
   d=$(mktemp -d "${TMPDIR:-/tmp}/codeman-spawn.XXXXXX") || return 1
-  for n in "$@"; do ( spawn_worker "$n" > "$d/$i" ) & i=$((i+1)); done
+  for spec in "$@"; do
+    n=${spec%%:*}; m=${spec#*:}; [ "$m" = "$spec" ] && m=claude
+    ( spawn_worker "$n" "$m" > "$d/$i" ) & i=$((i+1))
+  done
   wait
-  i=0; for n in "$@"; do printf '%s %s\n' "$n" "$(cat "$d/$i" 2>/dev/null)"; i=$((i+1)); done
+  i=0; for spec in "$@"; do printf '%s %s\n' "${spec%%:*}" "$(cat "$d/$i" 2>/dev/null)"; i=$((i+1)); done
   rm -rf "$d"
 }
 # sendwait <sid> <prompt> [seq] -> blocks until that worker's turn ENDS (~10 min ceiling
@@ -116,27 +152,46 @@ spawn_workers() {
 # (observed live). So the first wait is short; on its timeout a bare \r goes out (the
 # missing Enter when the prompt is stranded, a no-op when the turn is genuinely
 # running), then the ORIGINAL frame is resent unchanged, which the server takes as a
-# tagged duplicate: it re-waits without retyping (§5.3). Trustworthy only for a claude
-# worker spawn_worker handed back (hooks vetted); hook-less workspaces and other modes
-# resolve on flapping idle: markers instead (§5.5).
+# tagged duplicate: it re-waits without retyping (§5.3). Trustworthy for a worker
+# spawn_worker handed back -- claude (hooks vetted) or deepseek (status bridge) --
+# and for those only. Hook-less workspaces and the other modes resolve on flapping
+# idle: markers instead (§5.5). ⚠️ A dsh worker running a profile that does not
+# implement the status contract is the one case that LOOKS like claude but is not:
+# it accepts the send and then burns both waits. One timeout on a dsh worker whose
+# pane clearly finished means that profile, so switch that worker to markers.
 sendwait() {
   local sid="${1:?}" p="${2:?}" seq="${3:-$(date +%s)}" body r
+  # `wait:"stop,exit"`, never the `wait:true` default set: that set also carries
+  # `idle`, which is INFERRED from output stabilization and flaps mid-turn. On a
+  # dsh worker whose TUI repaints rarely the session reads `idle` while the model
+  # is still answering, and the re-wait below then resolved in 0 ms with
+  # `signal:"idle"` on a turn that had another three minutes to run (measured).
+  # A wait named after the end of a turn should only end with the turn, or with
+  # the worker. ⚠️ This is also what makes a wrong mode LOUD: the modes that
+  # cannot deliver `stop` answer 400 (before writing anything) instead of
+  # resolving on a flap, which is the answer that sends you to markers (§5.5).
   body=$(jq -nc --arg p "$p" --arg c "$CID-$sid" --argjson s "$seq" \
-    '{input:($p+"\r"),useMux:true,clientId:$c,seq:$s,wait:true,waitTimeout:20000}')
+    '{input:($p+"\r"),useMux:true,clientId:$c,seq:$s,wait:"stop,exit",waitTimeout:20000}')
   r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \
         -H 'Content-Type: application/json' --data-binary "$body")
   if jq -e '.data.delivered and .data.wait.timedOut' <<<"$r" >/dev/null 2>&1; then
     "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
       -d "$(jq -nc --arg c "$CID-$sid" --argjson s "$(date +%s)" \
         '{input:"\r",useMux:true,clientId:$c,seq:$s}')" >/dev/null
+    # The resend is a tagged DUPLICATE, so the server skips the write and reports
+    # `delivered:false` for it -- truthfully, but about the wrong send. The first
+    # one delivered, so carry that forward, or §1's cleanup reads a completed turn
+    # as an undelivered one and keeps a finished worker forever.
     r=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" \
-          -H 'Content-Type: application/json' --data-binary "$(jq -c '.waitTimeout=580000' <<<"$body")")
+          -H 'Content-Type: application/json' --data-binary "$(jq -c '.waitTimeout=580000' <<<"$body")" \
+        | jq -c 'if .success and (.data.wait.ended | not) then .data.delivered = true else . end')
   fi
   printf '%s\n' "$r"
 }
-# last_text <sid> [prev] -> that worker's last assistant message. Polled, because the
-# transcript write LAGS the stop signal, and "some text exists" is not "THIS turn's
-# text exists": right after a SECOND turn on the same worker the endpoint still serves
+# last_text <sid> [prev] -> that worker's last assistant message (claude, codex and
+# deepseek write a real transcript; the other modes have none, so read the terminal
+# instead -- §5.4). Polled, because the transcript write LAGS the stop signal, and
+# "some text exists" is not "THIS turn's text exists": right after a SECOND turn on the same worker the endpoint still serves
 # the previous answer for a beat (observed live). When reading consecutive turns, pass
 # the previous answer as [prev]: the poll then holds out for text that differs from it,
 # falling back to whatever it last saw if the budget runs dry, so an honestly repeated
@@ -155,4 +210,4 @@ last_text() {
 # The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
 # bare on purpose: the write condition above anchors on it with $, so an inline comment
 # here would fail that match and rewrite this file on every single bootstrap.
-CODEMAN_PREAMBLE=1.19.0
+CODEMAN_PREAMBLE=1.20.0

skills/codeman/reference/endpoints.md

@@ -237,7 +237,10 @@ minutes, never retry the credential.
 flushed slightly *after* the `stop` hook fires, so a read taken the instant the wait
 returns is too early (verified live: empty on the first call, full prose seconds later).
 It is also `""` before the worker's first completed turn, and permanently `""` for
-`shell`, `opencode`, `gemini`, `antigravity` and `pi`, which write no Claude transcript.
+`shell`, `opencode`, `gemini`, `antigravity`, `pi` and `grok`, which write no transcript at
+all. `deepseek` is NOT one of those — it is read from `$DSH_HOME/sessions/**` and lags
+for the same reason claude does (the harness finalizes the assistant message just after
+it reports `idle`), so poll it the same way.
 
 **Fix** Poll it, bounded (10 tries, 1 s apart). If it is still empty on a hook-less mode,
 that is expected, not a failure: read `terminal?tail=` and strip ANSI instead.
@@ -279,7 +282,7 @@ than into an existing checkout.
 | start case + session in one call | `POST /api/v1/quick-start` |
 | create a session in an arbitrary directory (no case, **no PTY**, id at `.data.session.id`) | `POST /api/v1/sessions`, then `POST /api/v1/sessions/:id/interactive` or `.../shell` to start it, see [Starting a worker](#starting-a-worker) |
 | send input | `POST /api/v1/sessions/:id/input` |
-| **read a worker's answer** (claude/codex) | `GET /api/v1/sessions/:id/last-response` → `.data.{text,timestamp}`, clean transcript text, no TUI noise. ⚠️ **Poll it**, see [symptom 7](#7-last-response-returns-an-empty-string-right-after-stop) |
+| **read a worker's answer** (claude/codex/deepseek) | `GET /api/v1/sessions/:id/last-response` → `.data.{text,timestamp}`, clean transcript text, no TUI noise. ⚠️ **Poll it**, see [symptom 7](#7-last-response-returns-an-empty-string-right-after-stop) |
 | read terminal (tail is in **BYTES**, raw ANSI) | `GET /api/v1/sessions/:id/terminal?tail=3000` → `.data.terminalBuffer`, for *diagnosis* (unsubmitted prompt?), not for reading answers |
 | full tmux scrollback (context bomb; post-mortems only) | `GET /api/v1/sessions/:id/terminal?full=1` |
 | background agents, one session | `GET /api/v1/sessions/:id/subagents` |
@@ -321,7 +324,7 @@ on signals and markers for exactly this reason.
 ⚠️ `GET /api/v1/sessions/:id/output` → `.data.textOutput` looks like the obvious read
 but stays **empty for interactive tmux-backed sessions** (it is fed only by the legacy
 JSON-stream path). Verified empty on live claude and shell sessions. Use
-`last-response` for claude/codex answers; only fall back to `terminal?tail=` for
+`last-response` for claude/codex/deepseek answers; only fall back to `terminal?tail=` for
 hook-less modes, or to diagnose a prompt that was never submitted, and strip ANSI:
 
 ```bash
@@ -336,19 +339,20 @@ ESC=$(printf '\033')
 
 `POST /api/v1/quick-start` body (all optional):
 `{"caseName":"worker-1","mode":"claude","sessionName":"w9-worker","effort":"high"}`
-,  `mode` ∈ `claude|shell|opencode|codex|gemini|antigravity|pi`; response is
+,  `mode` ∈ `claude|shell|opencode|codex|gemini|antigravity|pi|grok|deepseek`; response is
 `.data.{sessionId, caseName, casePath}`. Creates the case directory (a real directory
 on the user's disk) if missing, do not retry it in a loop, and remember the name.
 
 ⚠️ A `mode` whose CLI is **not installed on the server** fails the spawn with
 `OPERATION_FAILED`; it never falls back to claude. Probe first whenever you did not pick
 the mode yourself: `GET /api/v1/claude/status`, `GET /api/v1/opencode/status`,
-`GET /api/v1/codex/status`, `GET /api/v1/gemini/status`, `GET /api/v1/antigravity/status`
+`GET /api/v1/codex/status`, `GET /api/v1/gemini/status`, `GET /api/v1/antigravity/status`, `GET /api/v1/grok/status`, `GET /api/v1/deepseek/status`
 and `GET /api/v1/pi/status` each return `.data.{available, path}` (no session needed).
-Pi's also carries `.data.version`, because `pi` is a short generic name that an unrelated
-binary on `$PATH` can shadow: the resolver rejects one whose `--version` is not
-semver-shaped, so `available:false` there can mean "a different `pi` is in front" rather
-than "nothing is installed". `shell` has no CLI to probe.
+Pi's and grok's also carry `.data.version`, because `pi` is a short generic name and
+`grok` is a name with npm squatters, so an unrelated binary on `$PATH` can shadow either:
+the resolver rejects one whose `--version` is not version-shaped, so `available:false`
+there can mean "a different `pi`/`grok` is in front" rather than "nothing is installed".
+`shell` has no CLI to probe.
 
 ⚠️ **Branch on `.success` before reading `.data.sessionId`.** On any failure the field
 is absent, `jq -r` prints the literal string `null`, and every later call then targets
@@ -462,10 +466,10 @@ Quirks that will bite you:
   session answers with an empty timeline rather than a 404.
 - ⚠️ **`active-tools` proves presence, never absence.** It is fed by the BashToolParser,
   which reads Claude's rendered `● Bash(…)` lines, and `_processExpensiveParsers`
-  returns early for every external CLI mode (`session.ts:2136`), so it is permanently
-  `[]` on `opencode`/`codex`/`gemini`/`antigravity`/`pi`. ⚠️ **`shell` is NOT one of those**
-  (`isExternalCliMode`, `session.ts:165-167`, lists only those five), so the parser does
-  run on a shell worker, and `TEXT_COMMAND_PATTERN` (`bash-tool-parser.ts:88`) matches
+  returns early for every external CLI mode (`session.ts:2261`), so it is permanently
+  `[]` on `opencode`/`codex`/`gemini`/`antigravity`/`pi`/`grok`/`deepseek`. ⚠️ **`shell` is NOT one of those**
+  (`isExternalCliMode`, `session.ts:174-183`, lists only those six), so the parser does
+  run on a shell worker, and `TEXT_COMMAND_PATTERN` (`bash-tool-parser.ts:89`) matches
   bare `tail|cat|head|less|grep|watch|multitail <path>` lines with no `● Bash(` wrapper:
   a shell worker running `cat build.log` really does populate this. In practice it stays
   empty for most shell work. It also never sees non-Bash
@@ -639,10 +643,14 @@ block, so a linked case or a raw `workingDir` had no hooks at all. `POST
 session-create path installs hooks regardless of how the directory got there. See
 [symptom 8](#8-send-and-wait-resolves-instantly-with-signalidle-and-the-answer-is-last-turns).
 
-Default `until` set: `stop,idle,exit`. On non-claude modes the server silently drops
-`stop`/`blocked` from the *default* set (echoed back as `wait.until`, e.g.
+Default `until` set: `stop,idle,exit`. On modes with no hook signals the server silently
+drops `stop`/`blocked` from the *default* set (echoed back as `wait.until`, e.g.
 `["idle","exit"]` on shell); requesting them *explicitly* there is a 400 naming the
-mode. ⚠️ That 400 is about **mode**, so a hooks-less *claude* session accepts
+mode. ⚠️ `deepseek` is not one of those: its harness reports its own lifecycle, so it
+keeps the full default set and accepts an explicit `until=stop`. ⚠️ For dsh the answer is
+per-SESSION rather than per-mode — a session created with `statusReporting: false` has no
+bridge, and an explicit `until=stop` there is a 400 naming that setting. ⚠️ That 400 is
+otherwise about **mode**, so a hooks-less *claude* session accepts
 `until=stop` happily and then never resolves it. ⚠️ On hook-less modes the lifecycle
 signals are also **coarse in practice**: a
 short shell command produced **no** `idle` transition within 60 s (verified live), so
@@ -790,7 +798,8 @@ for environment and setup problems.
 | `CODEMAN_MUX` unset but you seem to be in a session | remote-SSH case: the env vars are not exported there. Fail closed, refuse to act |
 | connection refused from inside a container | a loopback-bound server is unreachable from a container, and `CODEMAN_DOCKER_BRIDGE_HOOKS=1` does **not** fix that: it opens a hooks-only listener, so hook events start flowing but `/api/v1/*` stays refused. Driving the API from inside a Docker case needs a reachable bind (an operator decision); report it, don't retry |
 | wait routes 404 on a valid session id | read the `.error` text: a `Route ...` prefix means the server predates the wait endpoints (< 1.13.0; a dev build can serve them while reporting an older version, so probe, never version-compare), poll `terminal?tail=` and say so. `Session ... not found` means your id is wrong, not the server |
-| wait on `stop` never resolves | non-claude mode, or hooks not reaching the server (Docker/remote), or a case created by Codeman < 1.13.0 against an `--https` install (its hook curls lacked `-k` and TLS-failed silently; a 1.13.0+ server rewrites them the next time a session starts in that case). Use markers or `idle,exit` |
+| wait on `stop` never resolves | a mode with no hook signals, or hooks not reaching the server (Docker/remote), or a case created by Codeman < 1.13.0 against an `--https` install (its hook curls lacked `-k` and TLS-failed silently; a 1.13.0+ server rewrites them the next time a session starts in that case). Use markers or `idle,exit` |
+| wait on `stop` never resolves, on a **dsh** worker whose pane clearly finished | that profile does not implement the harness's supervisor contract, which Codeman cannot detect at request time (an unrecognized profile is treated as launchable on purpose). The wait is accepted and then times out. Drive that worker with markers, or switch to a profile that reports — `@deepseek-harness-tui/dsh-tui` does |
 | new claude worker ignores its first prompt | it was showing the first-run trust dialog and Codeman's auto-accept did not fire (it is bounded by a 90 s window and an attempt cap); use the readiness recipe in SKILL.md, wait for `shift+tab` first, accept the dialog only as the bounded fallback |
 | readiness burns its whole budget, then the worker answers fine anyway | you matched `bypass`, which is the statusline of ONE permission mode. Codeman spawns `--dangerously-skip-permissions` by default, but the server's `claudeMode` setting also has `auto` (`auto mode on`), `allowedTools` and `normal` (both `don't ask on`), and the effective per-session value is not exposed on `GET /api/v1/sessions/:id`. Match **`shift+tab`** instead: every mode's status bar ends `(shift+tab to cycle)` (measured per mode against claude-cli 2.1.226). Expect `blocked` signals mid-turn on the non-default modes |
 | ANSI escapes survive the strip pipeline | `sed -e 's/\x1b…'` on macOS: `\x1b` is GNU-only, BSD sed matches nothing and strips nothing. Use the `ESC=$(printf '\033')` form above |

skills/codeman/reference/messaging.md

@@ -56,7 +56,7 @@ own head: the worker enforcing the cap is the one who has to be told about it.
 | synchronize on end of turn | HTTP `wait until=stop` (fires for message-initiated turns too, verified live) |
 | liveness / death check | HTTP `wait?until=exit` |
 | interrupt a running turn (break-glass) | HTTP input, a bare `\x1b` with no `\r` |
-| non-claude modes (`shell`/`opencode`/`codex`/`gemini`/`antigravity`/`pi`) | HTTP only (no other CLI has messaging) |
+| non-claude modes (`shell`/`opencode`/`codex`/`gemini`/`antigravity`/`pi`/`grok`/`deepseek`) | HTTP only (no other CLI has messaging) |
 | delete | HTTP, via SKILL.md's `delete_session` guard |
 
 ## Availability: probe, never assume
@@ -347,7 +347,7 @@ Without a break-glass, a pair with a bad brief is a token bonfire with no off sw
 
 ### Mixed fleets: the pairing matrix
 
-Non-claude workers (`shell`, `opencode`, `codex`, `gemini`, `antigravity`, `pi`) cannot be peers
+Non-claude workers (`shell`, `opencode`, `codex`, `gemini`, `antigravity`, `pi`, `grok`, `deepseek`) cannot be peers
 at all; no other CLI has this feature. Their tasks route over HTTP, and you never mention
 messaging in their briefs. The claude half of the fleet can use messaging among itself,
 subject to the namespace rule: **messaging works between two sessions that share one

skills/codeman/reference/recipes.md

@@ -188,7 +188,7 @@ for _ in $(seq 1 10); do
 done
 printf '%s\n' "$TXT"
 #    (.data is {text,timestamp}; text is also "" before the first completed turn and
-#     always "" for shell/opencode/gemini/antigravity/pi, which have no transcript, use
+#     always "" for shell/opencode/gemini/antigravity/pi/grok, which have no transcript, use
 #     the terminal tail there, and here only to diagnose an unsubmitted prompt.)
 
 # 6. clean up: exact id, own list only, through the fail-closed preamble helper
@@ -198,6 +198,59 @@ delete_session "$SID"
 Increment `SEQ` for every *new* input to the same worker. Reuse the same `SEQ` only to
 re-ask about the same delivery (the duplicate-wait loop above).
 
+## Flow 1b: DeepSeek Harness worker, end to end
+
+A `deepseek` worker is driven with the same four verbs as a claude one, because the
+harness reports its own lifecycle: its `stop` is a real end-of-turn signal, and its
+answer comes from a real transcript. The differences are all at the edges.
+
+```bash
+# 0. Is there anything to spawn? `available` is the binary, `runnable` is a profile
+#    that can drive a pane -- dsh ships only web/headless, so the two differ.
+"${CURL[@]}" "$API/api/v1/deepseek/status" | jq -c '{available:.data.available,runnable:.data.runnable,profile:.data.defaultProfile}'
+
+# 1. Spawn. `deepSeekConfig` is optional: an absent profile picks the first
+#    pane-capable one, and an absent permissionMode leaves the harness on its own
+#    workspace-write default, which still ASKS before it acts.
+Q=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" -H 'Content-Type: application/json' \
+  -d '{"caseName":"dsh-worker","mode":"deepseek","deepSeekConfig":{"permissionMode":"danger-full-access"}}')
+SID=$(jq -r 'if .success then .data.sessionId else empty end' <<<"$Q")
+[ -n "$SID" ] || { jq -c '{error, errorCode}' <<<"$Q"; exit 1; }   # OPERATION_FAILED = no runnable profile
+CREATED+=("$SID")
+
+# 2. Readiness, and ONLY readiness. ⚠️ Do not use the stop signal for this: the
+#    harness reports idle at BOOT, ~300 ms before the composer paints.
+"${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
+  --data-urlencode 'match=❯' --data-urlencode 'from=buffer' --data-urlencode 'timeout=45000' \
+  | jq -e '.data.wait.matched' >/dev/null || { echo "no composer"; delete_session "$SID"; exit 1; }
+
+# 3. Task it. Identical to a claude worker, including the \r and the (clientId, seq).
+"${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" -H 'Content-Type: application/json' \
+  -d '{"input":"Read calc.py and tell me in one sentence whether add() is correct.\r","useMux":true,"clientId":"codeman-dsh-1","seq":1,"wait":"stop,exit","waitTimeout":300000}' \
+  | jq -c '{delivered:.data.delivered,signal:.data.wait.signal,timedOut:.data.wait.timedOut}'
+
+# 4. Read it. From $DSH_HOME/sessions/**, not the pane -- scraping a dsh pane returns
+#    its ASCII-art splash. Poll: the harness finalizes the message just after it
+#    reports idle. Two answers are not the model's words and say so:
+#    "Turn error: …" (the provider or harness failed) and "Turn ended: …" (early stop).
+for _ in $(seq 1 15); do
+  TXT=$("${CURL[@]}" "$API/api/v1/sessions/$SID/last-response" | jq -r '.data.text')
+  [ -n "$TXT" ] && break; sleep 1
+done
+printf '%s\n' "$TXT"
+
+# 5. Full conversation, if you need the tool calls too:
+#    "${CURL[@]}" "$API/api/v1/sessions/$SID/last-response?context=full" | jq -r '.data.messages[]|"[\(.label)] \(.text)"'
+
+delete_session "$SID"
+```
+
+⚠️ **`wait:"stop,exit"`, not `wait:true`.** The default set also carries `idle`, which
+for an external CLI is inferred from output stabilization: a dsh TUI that repaints
+rarely reads as idle mid-turn, and a wait carrying `idle` then resolves in 0 ms on a
+turn with minutes left to run (measured). The same reason the preamble's `sendwait`
+asks for `stop,exit` on every mode.
+
 ## Flow 2: shell worker, marker-synchronized
 
 `shell` sessions have no hooks (`stop`/`blocked` are a 400 there), and their lifecycle

skills/codeman/reference/verbs.md

@@ -152,7 +152,19 @@ It is **decoration, and resolved rather than trusted**, so treat it accordingly:
 
 ### 5.2 Readiness
 
-A new session reports `idle` before its CLI has spawned, and a brand-new case shows a
+**dsh workers first**, because their trap is the opposite of claude's: they have no
+trust dialog and boot straight into a composer (`❯`, matched `from=buffer`), but the
+harness reports `idle` — which reaches you as a `stop` signal — about 300 ms BEFORE that
+composer paints (measured 2.26 s vs 2.56 s after spawn, twice). So the signal that means
+"this worker finished its turn" is also the first thing it emits at boot, and a
+send-and-wait fired straight after `quick-start` resolves on it, reports a turn that
+never ran, and leaves the prompt in a pane that was not yet taking input. Wait for the
+composer, not for the signal; `spawn_worker` does exactly that, and by the time it
+returns the boot edge is spent (signals are edge-triggered, so nothing can catch it
+later). A profile whose composer is not `❯` needs `DSH_READY_MARK` set to whatever it
+does draw.
+
+For claude: a new session reports `idle` before its CLI has spawned, and a brand-new case shows a
 **trust dialog** first, so neither "wait for idle" nor "wait for ❯" means ready (the
 trust dialog contains `❯` too, observed live). Codeman auto-accepts that dialog
 itself, reliably enough that stage 1 usually just works: `_maybeAcceptTrustDialog()`
@@ -341,17 +353,35 @@ If the loop exhausts its cap, do not keep looping: read the terminal, report wha
 see, and remember that a still-typed-but-unsubmitted prompt (missing `\r`) can only be
 recovered by submitting it with `{"input":"\r"}`.
 
-⚠️ `stop` and `blocked` fire for `claude` sessions only (they are Claude Code hooks,
-and only when the workspace actually has them, see [§5.1](#51-where-to-spawn)). On
-`shell`/`opencode`/`codex`/`gemini`/`antigravity`/`pi`, requesting them explicitly is a
+⚠️ `stop` and `blocked` fire for `claude` sessions (they are Claude Code hooks, and
+only when the workspace actually has them, see [§5.1](#51-where-to-spawn)) **and for
+`deepseek`** — the one external CLI that reports its own lifecycle, so its `stop` is a
+real end-of-turn signal rather than a guess. On
+`shell`/`opencode`/`codex`/`gemini`/`antigravity`/`pi`/`grok`, requesting them explicitly is a
 400, and lifecycle transitions there are coarse (a short shell command may emit **no**
 `idle` transition at all, verified live), so synchronize those with markers.
 
+⚠️ A dsh session can still refuse them for a per-SESSION reason: `statusReporting:
+false` at create time disarms the bridge, and an explicit `until=stop` is then a 400
+naming that setting. And a `stop` that is *accepted* is not proof it will ever fire —
+whether the installed profile implements the supervisor contract cannot be known at
+request time, so a non-conforming one accepts the wait and times out on it. One timeout
+on a dsh worker whose pane clearly finished identifies that profile; switch it to
+markers.
+
 ### 5.4 Read the answer
 
-For `claude` and `codex` workers this is the read path: `last-response` returns the
-agent's final message as clean text, taken from the transcript rather than the screen,
-so it carries none of the TUI's box-drawing or repaint noise.
+For `claude`, `codex` and `deepseek` workers this is the read path: `last-response`
+returns the agent's final message as clean text, taken from the transcript rather than
+the screen, so it carries none of the TUI's box-drawing or repaint noise.
+
+⚠️ For `deepseek` it reads `$DSH_HOME/sessions/**`, and reading it is the ONLY way to
+get that answer: dsh-TUI paints a full-screen splash, so scraping its pane returns the
+ASCII-art logo (that is what `last-response` itself used to return for dsh). Two dsh
+answers are not the model's words and say so: `Turn error: …` (the provider or the
+harness failed the turn) and `Turn ended: …` (an early stop such as `max-tokens`). A
+turn still streaming reads back as the partial answer so far, so a non-empty read is
+not by itself proof the turn ended — that is what the `stop` signal is for.
 
 ```bash
 for _ in $(seq 1 10); do          # the transcript write LAGS the stop signal
@@ -369,9 +399,10 @@ from the transcript file, which is flushed slightly *after* the `stop` hook fire
 single read taken the instant send-and-wait returns comes back `""` even though the
 turn finished (verified live: empty on the first call, full text seconds later). `text`
 is also `""` before the worker's first completed turn, and always `""` for modes with
-no transcript (`shell`, `opencode`, `gemini`, `antigravity`, `pi`; the first four
+no transcript (`shell`, `opencode`, `gemini`, `antigravity`, `pi`, `grok`; the first four
 verified live, pi from the same source path), which is
-why the loop above is bounded rather than open-ended. Fall back to the terminal buffer
+why the loop above is bounded rather than open-ended. A dsh worker lags too, for its own
+reason: the harness finalizes the assistant message just after it reports `idle`. Fall back to the terminal buffer
 there, tail in **bytes** (`textOutput` in `GET .../output` stays empty for interactive
 sessions; don't use it):
 
@@ -454,7 +485,7 @@ turn), and both better than diffing terminal samples:
 ```
 
 ⚠️ `active-tools` is parsed out of Claude's own output format, so it is **empty for
-`opencode`/`codex`/`gemini`/`antigravity`/`pi`** (those parsers are skipped wholesale) and
+`opencode`/`codex`/`gemini`/`antigravity`/`pi`/`grok`/`deepseek`** (those parsers are skipped wholesale) and
 in practice empty for `shell`. Source-verified, not measured live.
 
 Only if neither helps: sample `terminal?tail=` twice a few seconds apart. A changing

src/config/dependency-registry.ts

@@ -8,6 +8,8 @@
  */
 
 import { PI_VERSION_REGEX } from '../utils/pi-cli-resolver.js';
+import { GROK_VERSION_REGEX } from '../utils/grok-cli-resolver.js';
+import { DEEPSEEK_VERSION_REGEX } from '../utils/deepseek-cli-resolver.js';
 
 export type ProbeEnvironment = 'linux' | 'darwin' | 'win32' | 'wsl';
 
@@ -139,6 +141,55 @@ export const DEPENDENCY_REGISTRY: ToolDependency[] = [
       },
     ],
   },
+  {
+    id: 'grok',
+    label: 'Grok CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['Grok sessions'],
+    // Version match required for the same reason as pi: `grok` has known squatters
+    // (the unrelated @vibe-kit/grok-cli npm package also installs a `grok` bin), so a
+    // bare `which grok` hit is not the coding agent. Both sides share
+    // GROK_VERSION_REGEX, so the doctor and the run mode cannot drift.
+    resolvers: [
+      {
+        match: ALL,
+        resolver: {
+          kind: 'path',
+          bins: ['grok'],
+          versionArg: '--version',
+          versionRegex: GROK_VERSION_REGEX,
+          requireVersionMatch: true,
+        },
+      },
+    ],
+  },
+  {
+    id: 'dsh',
+    label: 'DeepSeek Harness CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['DeepSeek sessions'],
+    // Version match required, and for a sharper reason than pi or grok: `dsh` is
+    // not merely a squattable npm name, it is an existing Debian program
+    // (dancer's shell, `apt install dsh`). The run mode's resolver additionally
+    // demands the harness's own help banner before it will point a spawn line at
+    // a candidate; the doctor is advisory and settles for the shared
+    // DEEPSEEK_VERSION_REGEX, so the two cannot disagree about the VERSION even
+    // though the resolver is the stricter of the pair about IDENTITY.
+    resolvers: [
+      {
+        match: ALL,
+        resolver: {
+          kind: 'path',
+          bins: ['dsh'],
+          versionArg: '--version',
+          versionRegex: DEEPSEEK_VERSION_REGEX,
+          requireVersionMatch: true,
+        },
+      },
+    ],
+  },
   {
     id: 'libreoffice',
     label: 'LibreOffice',

src/cron/cron-service.ts

@@ -48,7 +48,9 @@ const delay = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms
  *    answer "yes" to, which then loads and EXECUTES repo-local `.pi/extensions` TypeScript,
  *    so `approveProjectTrust: false` (`--no-approve`) is materialized. Omitting `--approve`
  *    is NOT a clamp.
- * Codex and antigravity need nothing here: their absent config already spawns safe.
+ * Codex, antigravity, grok and deepseek need nothing here: their absent config already spawns safe
+ * (grok's bare spawn is its own ask-mode default and deepseek's omits DSH_PERMISSION_MODE
+ * entirely, leaving the harness on workspace-write, which asks; both switches are only ever sent).
  * Granted/admin/single-user get undefined for both, i.e. upstream defaults untouched.
  */
 export function clampCronExternalCliConfigs(
@@ -393,11 +395,23 @@ export class CronService {
     let session: Session;
     try {
       const mode = job.agentType;
+      // Same two-part availability gate the HTTP create paths run: `dsh` is a
+      // profile LAUNCHER, so without this a job on a box with only the stock
+      // web/headless profiles spawns a bare `dsh` that boots a profile unable
+      // to drive a pane, and the prompt is typed into a logging server or a
+      // dead pane instead of failing the run with the actionable message.
+      if (mode === 'deepseek') {
+        const { resolveDeepSeekLaunchError } = await import('../utils/deepseek-cli-resolver.js');
+        const launchError = resolveDeepSeekLaunchError();
+        if (launchError) return this.failRun(job, run, launchError);
+      }
       const globalNice = await this.deps.getGlobalNiceConfig();
       const modelConfig = await this.deps.getModelConfig();
       const claudeModeConfig = await this.deps.getClaudeModeConfig();
       const effectiveClaudeMode = await resolveClaudeModeForUsername(claudeModeConfig.claudeMode, job.owner);
-      const model = mode !== 'shell' ? modelConfig?.defaultModel || undefined : undefined;
+      // DeepSeek's model is a composition entry in the profile's config tree,
+      // not a session flag — mirror the HTTP routes' exclusion.
+      const model = mode !== 'shell' && mode !== 'deepseek' ? modelConfig?.defaultModel || undefined : undefined;
       // Section 6.3: materialize the safe default for a non-granted owner (see
       // clampCronExternalCliConfigs — cron sends no per-CLI config, so the CLI's own
       // spawn default is what would otherwise apply).
@@ -425,7 +439,7 @@ export class CronService {
         piConfig,
         owner: job.owner,
       });
-      this.deps.addSession(session);
+      await this.deps.addSession(session);
       this.store.incrementSessionsCreated();
       this.deps.persistSessionState(session);
       await this.deps.setupSessionListeners(session);

src/deepseek-status-shim.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview The DeepSeek Harness -> Codeman status bridge.
+ *
+ * ## Why this exists
+ *
+ * Every external CLI mode before this one (opencode, codex, gemini, antigravity,
+ * pi, grok) is READINESS-GUESSED: Codeman watches the PTY go quiet and infers a
+ * turn ended. Claude is the exception, because Claude Code fires real hooks. The
+ * DeepSeek Harness TUI gives us a third option, and a much better one than
+ * guessing: the community terminal front door already reports its own lifecycle
+ * to an owning supervisor, and it does so through a fully GENERIC, env-var-gated
+ * contract it inherited from Herdr (herdr.dev).
+ *
+ * When all three of `HERDR_ENV=1`, `HERDR_BIN_PATH` and `HERDR_PANE_ID` are set,
+ * the TUI shells out on every state change:
+ *
+ *     "$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
+ *         --source custom:dsh-tui --agent dsh-tui \
+ *         --state idle|working|blocked [--message <text>] --seq <n>
+ *
+ * and treats exit code 0 as "delivered" (retrying with backoff otherwise). So
+ * Codeman points `HERDR_BIN_PATH` at the script below and gets DEFINITIVE
+ * idle/working/blocked signals for dsh sessions: real respawn triggers, real
+ * `wait`/`wait-output` stop+blocked signals, and real Approvals Inbox items,
+ * on par with Claude's hooks rather than with output stabilization.
+ *
+ * This is an interface implementation, not an impersonation: we implement the
+ * one verb (`pane report-agent`) that the contract defines, and nothing on the
+ * machine ever executes a real `herdr` binary — `HERDR_BIN_PATH` is our own
+ * script, in our own data dir. `HERDR_ENV=1` is the flag the TUI checks to know
+ * a supervisor is present; a supervisor IS present, it is Codeman.
+ *
+ * ## Why it is generated rather than committed
+ *
+ * The shim must be an executable file at a stable absolute path in every
+ * install shape: a git clone (where `scripts/` exists), an `npm i -g aicodeman`
+ * (where `files` ships only `dist` plus two named scripts), and any
+ * `CODEMAN_INSTANCE`. Writing it into the data dir at session-create time makes
+ * one code path cover all of them, single-sources the content here in TS, and
+ * follows the precedent of `self-update-runner.sh`. It is rewritten whenever the
+ * embedded version marker changes, so an upgraded Codeman refreshes a stale shim
+ * without the user knowing it exists.
+ *
+ * @module deepseek-status-shim
+ */
+
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { dataPath } from './config/instance.js';
+
+/**
+ * Bumped whenever SHIM_SOURCE changes. The marker is embedded in the generated
+ * file, so `ensureDeepSeekStatusShim()` can tell a current shim from one written
+ * by an older Codeman and rewrite only when needed (rather than rewriting on
+ * every session create, or — worse — leaving a stale one in place forever).
+ */
+const SHIM_VERSION = 3;
+const SHIM_MARKER = `codeman-dsh-status-shim v${SHIM_VERSION}`;
+
+/**
+ * Mapping from the harness's three lifecycle states to Codeman hook events.
+ *
+ * - `blocked` -> `permission_prompt`: the TUI reports blocked when a tool
+ *   approval or an `ask_user_question` questionnaire is on screen, which is
+ *   exactly the red "needs you" alert and an answerable Approvals Inbox item.
+ * - `idle` -> `stop`: the definitive end-of-turn signal, the one respawn and the
+ *   wait endpoints care about.
+ * - `working` -> `agent_working`: a turn STARTED. Codeman infers "working" from
+ *   PTY output well enough on its own, but the event is what RESOLVES a pending
+ *   approval when the user answers a dialog in the terminal instead of in the
+ *   inbox. Without it a dsh session's red alert would survive until the next
+ *   `stop`, which is the exact stuck-alert bug the claude path already had to
+ *   fix once (and the pane-capture staleness sweep that fixed it there is
+ *   Claude-dialog-shaped, so it cannot help here).
+ */
+export const DEEPSEEK_STATE_TO_HOOK_EVENT: Readonly<Record<string, string>> = Object.freeze({
+  idle: 'stop',
+  blocked: 'permission_prompt',
+  working: 'agent_working',
+});
+
+/**
+ * The generated script.
+ *
+ * Constraints it must satisfy, each learned from an existing Codeman hook bug:
+ * - **TLS**: `CODEMAN_API_URL` is loopback HTTPS with a self-signed cert on
+ *   `--https`/tailscale installs, so certificate verification is disabled for
+ *   the request. Without this the whole bridge dies silently, exactly as the
+ *   claude hook curls did before they grew `-k`.
+ * - **Secret**: the hook-secret file is read AT EXECUTION TIME, never baked in,
+ *   so rotation needs no respawn and the value never lands on a command line.
+ * - **Exit codes**: 0 means delivered. Anything else makes the TUI retry with
+ *   backoff, so transport failures self-heal, but an unknown verb or an
+ *   unmapped state exits 0 to avoid a pointless retry storm over something that
+ *   will never succeed.
+ * - **Timeout**: bounded below the caller's own 2s budget, so we lose the race
+ *   deliberately rather than being killed mid-flight.
+ */
+const SHIM_SOURCE = `#!/usr/bin/env node
+// ${SHIM_MARKER}
+// GENERATED BY CODEMAN — do not edit. Rewritten from src/deepseek-status-shim.ts
+// whenever its version marker changes.
+//
+// Implements the one verb the DeepSeek Harness TUI's supervisor contract uses:
+//   pane report-agent <paneId> --state <idle|working|blocked> [--message <t>] ...
+// and forwards it to this Codeman instance as a hook event.
+import { readFileSync } from 'node:fs'
+import http from 'node:http'
+import https from 'node:https'
+
+const STATE_TO_EVENT = ${JSON.stringify(DEEPSEEK_STATE_TO_HOOK_EVENT)}
+const TIMEOUT_MS = 1500
+
+const argv = process.argv.slice(2)
+const flag = (name) => {
+  const i = argv.indexOf(name)
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined
+}
+
+// Unknown verb: succeed silently. Retrying could never make it succeed, and a
+// non-zero exit here would make the caller retry four times per state change.
+if (argv[0] !== 'pane' || argv[1] !== 'report-agent') process.exit(0)
+
+const event = STATE_TO_EVENT[String(flag('--state') ?? '')]
+if (!event) process.exit(0)
+
+// The pane id we hand the TUI IS the Codeman session id, but prefer the ambient
+// env: it is set by the same code that set HERDR_PANE_ID, so a TUI that mangles,
+// truncates or re-uses the pane argument still reports against the right session.
+// NOT a security boundary, and do not read it as one: the agent runs IN this pane
+// and can invoke the shim with CODEMAN_SESSION_ID unset and any argv it likes.
+// That buys it nothing it did not already have, since the hook-secret file is
+// readable from the same pane and any process there can POST /api/hook-event
+// directly. Attribution here is about accidents, not adversaries.
+const sessionId = process.env.CODEMAN_SESSION_ID || argv[2]
+const apiUrl = process.env.CODEMAN_API_URL
+if (!sessionId || !apiUrl) process.exit(1)
+
+let secret = ''
+try {
+  secret = readFileSync(process.env.CODEMAN_HOOK_SECRET_FILE || '', 'utf-8').trim()
+} catch {
+  // Missing file: the loopback bypass still applies when no tunnel is running.
+}
+
+// The contract's ordering token: the TUI retries failed deliveries with
+// backoff, so a stale report can land AFTER a newer one. Forwarded so the
+// server can drop out-of-order arrivals instead of, say, resolving an
+// approval with a retried 'working' while the harness sits blocked.
+const seq = Number(flag('--seq'))
+
+const body = JSON.stringify({
+  event,
+  sessionId,
+  data: {
+    source: 'dsh-status-shim',
+    agent: flag('--agent') || 'dsh',
+    ...(Number.isFinite(seq) ? { seq } : {}),
+    ...(flag('--message') ? { message: flag('--message') } : {}),
+  },
+})
+
+let url
+try {
+  url = new URL('/api/hook-event', apiUrl)
+} catch {
+  process.exit(1)
+}
+
+const transport = url.protocol === 'https:' ? https : http
+const req = transport.request(
+  {
+    protocol: url.protocol,
+    hostname: url.hostname,
+    port: url.port,
+    path: url.pathname,
+    method: 'POST',
+    timeout: TIMEOUT_MS,
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'X-Codeman-Hook-Secret': secret,
+    },
+    // Loopback HTTPS with a self-signed cert (--https / tailscale installs).
+    rejectUnauthorized: false,
+  },
+  (res) => {
+    res.resume()
+    const status = res.statusCode ?? 0
+    // 2xx: delivered. 4xx: PERMANENT — a 401 (missing/rotated secret) or 429
+    // can never be fixed by retrying, and each retry feeds the auth-failure
+    // rate-limit bucket, so a single misconfigured dsh session could 429 the
+    // hook endpoint for the whole instance (killing every claude session's
+    // real hooks). Exit 0 so the TUI does not retry; only transport errors
+    // and 5xx stay retryable.
+    process.exit(status >= 200 && status < 500 ? 0 : 1)
+  }
+)
+req.on('timeout', () => {
+  req.destroy()
+  process.exit(1)
+})
+req.on('error', () => process.exit(1))
+req.end(body)
+`;
+
+/** Absolute path of the generated shim for this instance. */
+export function deepSeekStatusShimPath(): string {
+  return dataPath('dsh-status-shim.mjs');
+}
+
+let ensuredThisProcess = false;
+
+/**
+ * Write the shim if it is missing or stale, and return its path.
+ *
+ * Idempotent and cheap: after the first call in a process it does nothing, and
+ * even the first call only rewrites when the on-disk marker differs. Never
+ * throws — a data dir that cannot be written is a degraded status bridge, not a
+ * failed session start, so callers fall back to output-stabilization readiness
+ * by receiving null.
+ */
+export function ensureDeepSeekStatusShim(): string | null {
+  const path = deepSeekStatusShimPath();
+  if (ensuredThisProcess) return path;
+  try {
+    let current = '';
+    try {
+      current = readFileSync(path, 'utf-8');
+    } catch {
+      // Missing — fall through to the write.
+    }
+    if (!current.includes(SHIM_MARKER)) {
+      mkdirSync(dirname(path), { recursive: true });
+      // Temp + rename, not a plain write: the TUI can be executing this exact
+      // path at the moment an upgraded Codeman refreshes it (every state change
+      // runs it, and session create is when the rewrite happens), and a reader
+      // that catches a half-written file gets a syntax error, exits non-zero,
+      // and is retried four times per state change for a file that will never
+      // parse. rename(2) is atomic within the directory, so a concurrent exec
+      // sees either the old shim or the new one, never a truncated one.
+      // Same reasoning as the state-store writes; pid-suffixed so two instances
+      // sharing a data dir cannot collide on the temp name.
+      const tempPath = `${path}.${process.pid}.tmp`;
+      try {
+        writeFileSync(tempPath, SHIM_SOURCE, { mode: 0o700 });
+        // The mode argument only applies when writeFileSync CREATES the file, so
+        // a leftover temp from a crashed run would keep its old permissions.
+        chmodSync(tempPath, 0o700);
+        renameSync(tempPath, path);
+      } catch (err) {
+        rmSync(tempPath, { force: true });
+        throw err;
+      }
+    }
+    // Re-assert the mode even when the content matched: a shim that lost its
+    // executable bit (a restored backup, a copied data dir) would make every
+    // report fail, and the TUI would retry four times per state change forever.
+    chmodSync(path, 0o700);
+    ensuredThisProcess = true;
+    return path;
+  } catch (err) {
+    console.warn(`[DeepSeek] Could not install the status shim at ${path}: ${(err as Error).message}`);
+    return null;
+  }
+}
+
+/** Test seam: forget the per-process memo so a fresh temp HOME is re-provisioned. */
+export function resetDeepSeekStatusShimForTest(): void {
+  ensuredThisProcess = false;
+}

src/deepseek-transcript.ts

@@ -0,0 +1,696 @@
+/**
+ * @fileoverview Reading a DeepSeek Harness (`dsh`) session transcript off disk.
+ *
+ * ## Why this exists
+ *
+ * `GET /api/sessions/:id/last-response` is how an agent (and the Response
+ * Viewer) reads what a worker actually said. For Claude it comes from
+ * `~/.claude/projects/**`, for Codex from `~/.codex/sessions/**`, and for every
+ * other external CLI it comes from segmenting the terminal buffer, because
+ * those CLIs write nothing a reader could open.
+ *
+ * dsh is not in that last group: it writes a complete, structured JSONL
+ * transcript per session. Falling back to the pane for it was measurably wrong
+ * rather than merely coarse — dsh-TUI paints a full-screen splash, so the pane
+ * segmenter answered a `last-response` call for a fresh dsh session with the
+ * ASCII-art logo:
+ *
+ *     {"text":"✦dsh-TUI v0.8.8█▀▀▀▄█▀▀▀▀█▀▀▀▀█▀▀▀▄█▀▀▀▀…","hasContext":true}
+ *
+ * which an agent polling for a worker's answer reads as an answer. This module
+ * is the real source: it locates the session's transcript, decodes it, and
+ * returns the last turn's text.
+ *
+ * ## The three things that make dsh transcripts unlike codex rollouts
+ *
+ * **1. One zstd FRAME per append, not one zstd stream.** The file is
+ * `session.jsonl.zstd`, and dsh appends by compressing each batch of lines into
+ * its own frame and writing it at the end. `zstd -dc` handles that (frames
+ * concatenate by definition), but Node's `zlib.zstdDecompress()` and
+ * `createZstdDecompress()` both stop at the first frame end: measured on a real
+ * 56-line transcript, Node returned 158 bytes / 1 line where the CLI returned
+ * 43,747 bytes / 56 lines. That is a silent truncation to the session header —
+ * every call would have reported "no answer yet" forever. `decodeZstdFrames()`
+ * below walks the frame headers itself and decompresses each frame, and
+ * `test/deepseek-transcript.test.ts` pins it against multi-frame fixtures.
+ *
+ * **2. The user's prompts are mixed with injected context.** Every turn also
+ * writes a `user/message` whose source is a plugin (the runtime-context
+ * snapshot: sandbox policy, approval policy, cwd). Those are `source.kind ===
+ * 'plugin'`; a real prompt is `source.kind === 'user'`. Rendering the plugin
+ * ones would show the agent its own boilerplate back as the user's words.
+ *
+ * **3. A failed turn is not an empty turn.** `turn/end` carries
+ * `reason.kind === 'error'` with the provider's message. Returning `""` there
+ * makes an agent poll `last-response` fifteen times and conclude the worker
+ * never answered, when the truth ("the provider rejected the request") was on
+ * disk the whole time. A turn that ends in an error and produced no text
+ * answers with that error, prefixed so it can never be mistaken for the model's
+ * own words.
+ *
+ * Verified against `dsh 0.1.1-rc.2` + `@deepseek-harness-tui/dsh-tui 0.8.8`.
+ */
+
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import * as zlib from 'node:zlib';
+
+/**
+ * One rendered block, in the shape the Response Viewer already speaks (see
+ * `web/response-viewer-transcript.ts`). Imported as a type only — this module
+ * must stay usable from the session layer without dragging web/ into it.
+ */
+export interface DeepSeekTranscriptBlock {
+  kind: 'prompt' | 'response' | 'status' | 'tool';
+  label: 'Prompt' | 'Response' | 'Status' | 'Tool';
+  role: 'user' | 'assistant';
+  text: string;
+}
+
+export interface DeepSeekTranscriptResult {
+  /** Last turn's answer (or its error, prefixed). Empty before the first turn. */
+  text: string;
+  /** ISO timestamp of the event `text` came from, or '' when unknown. */
+  timestamp: string;
+  /** Rendered blocks, oldest first. Only built when the caller asks for them. */
+  blocks: DeepSeekTranscriptBlock[];
+  /** dsh's own session id, from the header line. */
+  sessionId?: string;
+  /** Workspace the harness recorded for the session. */
+  cwd?: string;
+}
+
+/**
+ * zstd decompression is a RUNTIME capability here, not an import.
+ *
+ * Node grew `zlib` zstd support in 22.15 (and `@types/node` still does not
+ * declare it), while Codeman's floor is Node 22.0. So it is resolved through a
+ * narrow cast and checked before use: on an older 22.x a dsh session keeps the
+ * pane-segmenter behaviour it had before this module existed instead of
+ * throwing on every `last-response` call.
+ */
+type ZstdDecompressSync = (buf: Buffer) => Buffer;
+const zstdDecompressSync: ZstdDecompressSync | undefined = (
+  zlib as unknown as { zstdDecompressSync?: ZstdDecompressSync }
+).zstdDecompressSync;
+
+/** Whether this Node can decode the compressed transcripts dsh writes. */
+export function zstdSupported(): boolean {
+  return typeof zstdDecompressSync === 'function';
+}
+
+/** zstd frame magic (RFC 8878 §3.1.1). */
+const ZSTD_MAGIC = 0xfd2fb528;
+/** Skippable-frame magic range: 0x184D2A50..0x184D2A5F. */
+const ZSTD_SKIPPABLE_LO = 0x184d2a50;
+const ZSTD_SKIPPABLE_HI = 0x184d2a5f;
+
+const DID_FIELD_SIZE = [0, 1, 2, 4];
+const FCS_FIELD_SIZE = [0, 2, 4, 8];
+
+/**
+ * Byte ranges of the zstd frames in `buf`, in order.
+ *
+ * Walks frame headers and block headers only — no decompression — so the cost
+ * is proportional to the number of blocks, not to the content. Stops (rather
+ * than throws) at the first thing it cannot parse, so a transcript still being
+ * appended to mid-write yields every whole frame before the torn tail instead
+ * of failing the whole read.
+ *
+ * ⚠️ Splitting on the magic bytes instead would be wrong: the 4-byte sequence
+ * can occur inside compressed data, and a false split corrupts everything after
+ * it. The block walk is what makes the boundaries exact.
+ */
+export function zstdFrameRanges(buf: Buffer): Array<[number, number]> {
+  const ranges: Array<[number, number]> = [];
+  let offset = 0;
+
+  while (offset + 4 <= buf.length) {
+    const magic = buf.readUInt32LE(offset);
+
+    if (magic >= ZSTD_SKIPPABLE_LO && magic <= ZSTD_SKIPPABLE_HI) {
+      if (offset + 8 > buf.length) break;
+      const end = offset + 8 + buf.readUInt32LE(offset + 4);
+      if (end > buf.length || end <= offset) break;
+      offset = end;
+      continue;
+    }
+    if (magic !== ZSTD_MAGIC) break;
+
+    let p = offset + 4;
+    if (p >= buf.length) break;
+
+    const descriptor = buf[p] as number;
+    p += 1;
+    const fcsFlag = descriptor >> 6;
+    const singleSegment = (descriptor >> 5) & 1;
+    const hasChecksum = (descriptor >> 2) & 1;
+    const dictIdFlag = descriptor & 3;
+
+    if (!singleSegment) p += 1; // window descriptor
+    p += DID_FIELD_SIZE[dictIdFlag] as number;
+    // FCS is absent for flag 0 UNLESS Single_Segment is set, where it is 1 byte.
+    p += fcsFlag === 0 ? (singleSegment ? 1 : 0) : (FCS_FIELD_SIZE[fcsFlag] as number);
+    if (p > buf.length) break;
+
+    let lastBlock = false;
+    let torn = false;
+    while (!lastBlock) {
+      if (p + 3 > buf.length) {
+        torn = true;
+        break;
+      }
+      const header = (buf[p] as number) | ((buf[p + 1] as number) << 8) | ((buf[p + 2] as number) << 16);
+      p += 3;
+      lastBlock = (header & 1) === 1;
+      const blockType = (header >> 1) & 3;
+      const blockSize = header >> 3;
+      if (blockType === 3) {
+        torn = true; // reserved: refuse rather than guess
+        break;
+      }
+      p += blockType === 1 ? 1 : blockSize; // RLE stores a single byte
+      if (p > buf.length) {
+        torn = true;
+        break;
+      }
+    }
+    if (torn) break;
+
+    if (hasChecksum) p += 4;
+    if (p > buf.length) break;
+
+    ranges.push([offset, p]);
+    offset = p;
+  }
+
+  return ranges;
+}
+
+/**
+ * Decode a possibly multi-frame zstd buffer. A buffer that does not start with
+ * a zstd magic is passed through unchanged, which is what lets the same reader
+ * open a plain `session.jsonl` (dsh writes one when compression is off).
+ *
+ * A frame that fails to decompress truncates the decode THERE rather than
+ * failing it: everything decoded before it is kept, so a half-written tail
+ * frame does not cost the caller the whole conversation. (Not "skipped" — a
+ * frame after a corrupt one is never reached, which is the safe reading: dsh
+ * appends, so a bad frame means everything after it is suspect too.)
+ */
+export function decodeZstdFrames(buf: Buffer): string {
+  if (buf.length < 4) return buf.toString('utf8');
+  const magic = buf.readUInt32LE(0);
+  if (magic !== ZSTD_MAGIC && (magic < ZSTD_SKIPPABLE_LO || magic > ZSTD_SKIPPABLE_HI)) {
+    return buf.toString('utf8');
+  }
+
+  if (!zstdDecompressSync) return '';
+
+  const parts: Buffer[] = [];
+  for (const [start, end] of zstdFrameRanges(buf)) {
+    try {
+      parts.push(zstdDecompressSync(buf.subarray(start, end)));
+    } catch {
+      // Torn or corrupt frame: keep what decoded before it.
+      break;
+    }
+  }
+  return Buffer.concat(parts).toString('utf8');
+}
+
+interface DshEvent {
+  type?: string;
+  seq?: number | null;
+  time?: number;
+  data?: Record<string, unknown>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/**
+ * Strip a leaked reasoning prefix.
+ *
+ * Some providers stream reasoning into the same text block and close it with
+ * `</think>` without ever opening it (measured on a local deepseek-v4-flash
+ * route: `"I'll read the file first.</think>\n\nThe add function is…"`). The
+ * closing tag is the only reliable boundary, so everything up to the LAST one
+ * goes. A block with no tag is returned untouched.
+ */
+function stripReasoningPrefix(text: string): string {
+  const close = text.lastIndexOf('</think>');
+  return close === -1 ? text : text.slice(close + '</think>'.length);
+}
+
+/** `stripReasoning` is for ASSISTANT content only: a user prompt containing a
+ *  literal `</think>` (someone pasting a transcript, say) must render whole. */
+function textOfContent(content: unknown, stripReasoning = true): string {
+  const parts: string[] = [];
+  for (const entry of asArray(content)) {
+    const block = asRecord(entry);
+    if (!block) continue;
+    if (block.type === 'text' && typeof block.text === 'string') {
+      parts.push(stripReasoning ? stripReasoningPrefix(block.text) : block.text);
+    }
+  }
+  return parts.join('').trim();
+}
+
+function toolCallsOfContent(content: unknown): string[] {
+  const calls: string[] = [];
+  for (const entry of asArray(content)) {
+    const block = asRecord(entry);
+    if (!block || block.type !== 'tool-call') continue;
+    const name = typeof block.name === 'string' ? block.name : 'tool';
+    const args = typeof block.arguments === 'string' ? block.arguments : JSON.stringify(block.arguments ?? {});
+    calls.push(`${name}(${args})`);
+  }
+  return calls;
+}
+
+/** Flatten a `tool/result` message down to its text payload. */
+function textOfToolResult(message: unknown): string {
+  const parts: string[] = [];
+  for (const entry of asArray(asRecord(message)?.content)) {
+    const block = asRecord(entry);
+    if (!block) continue;
+    if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text);
+    if (block.type === 'tool-result') {
+      for (const inner of asArray(block.content)) {
+        const innerBlock = asRecord(inner);
+        if (innerBlock?.type === 'text' && typeof innerBlock.text === 'string') parts.push(innerBlock.text);
+      }
+    }
+  }
+  return parts.join('\n').trim();
+}
+
+function isoTime(time: unknown): string {
+  return typeof time === 'number' && Number.isFinite(time) ? new Date(time).toISOString() : '';
+}
+
+interface TurnAccumulator {
+  /** Finalized `assistant/message` text, in step order. */
+  finalized: Map<number, string>;
+  /** Steps that produced a finalized message AT ALL. ⚠️ Not the same as a
+   *  non-empty entry in `finalized`: a step whose whole reply was reasoning
+   *  strips to `''`, and without this the deltas — which are NOT stripped at
+   *  write time — would be resurrected in its place, putting the model's raw
+   *  `</think>` monologue in front of the caller (measured). */
+  finalizedSteps: Set<number>;
+  /** Streamed deltas per step, used only where no finalized message landed. */
+  streamed: Map<number, string>;
+  /** Step order as encountered, so a reply reads in the order it was produced. */
+  steps: number[];
+  timestamp: string;
+  /** Pre-rendered "Turn error: …" / "Turn ended: …" line, when the turn did not
+   *  end with `completed`. */
+  ending?: string;
+}
+
+function ensureStep(turn: TurnAccumulator, step: number): void {
+  if (!turn.steps.includes(step)) turn.steps.push(step);
+}
+
+function turnText(turn: TurnAccumulator): string {
+  const parts: string[] = [];
+  for (const step of turn.steps) {
+    // Deltas are only consulted for a step the model never finalized — a step
+    // that has both would otherwise render its text twice.
+    const text = turn.finalizedSteps.has(step)
+      ? (turn.finalized.get(step) ?? '')
+      : stripReasoningPrefix(turn.streamed.get(step) ?? '');
+    if (text.trim()) parts.push(text.trim());
+  }
+  return parts.join('\n\n').trim();
+}
+
+/**
+ * Parse a decoded dsh transcript.
+ *
+ * `text` is the LAST TURN's answer, not the last assistant message anywhere in
+ * the file: a turn that errored after an earlier turn answered must not hand
+ * back the earlier turn's text as though it were this turn's reply.
+ */
+export function parseDeepSeekTranscript(raw: string, options: { blocks?: boolean } = {}): DeepSeekTranscriptResult {
+  const wantBlocks = options.blocks === true;
+  const blocks: DeepSeekTranscriptBlock[] = [];
+  const turns = new Map<number, TurnAccumulator>();
+  const turnOrder: number[] = [];
+  let sessionId: string | undefined;
+  let cwd: string | undefined;
+
+  const getTurn = (n: number): TurnAccumulator => {
+    let turn = turns.get(n);
+    if (!turn) {
+      turn = { finalized: new Map(), finalizedSteps: new Set(), streamed: new Map(), steps: [], timestamp: '' };
+      turns.set(n, turn);
+      turnOrder.push(n);
+    }
+    return turn;
+  };
+
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let event: DshEvent;
+    try {
+      event = JSON.parse(line) as DshEvent;
+    } catch {
+      continue; // a torn tail line, or a frame we could not decode
+    }
+    const data = asRecord(event.data) ?? {};
+    const turnNo = typeof data.turn === 'number' ? data.turn : 0;
+    const stepNo = typeof data.step === 'number' ? data.step : 0;
+
+    switch (event.type) {
+      case 'session': {
+        const header = event as unknown as Record<string, unknown>;
+        if (typeof header.id === 'string') sessionId = header.id;
+        if (typeof header.cwd === 'string') cwd = header.cwd;
+        break;
+      }
+      case 'user/message': {
+        // ⚠️ Only a real prompt. The plugin-sourced twin is the runtime-context
+        // snapshot dsh injects every turn (sandbox policy, approvals, cwd).
+        if (asRecord(data.source)?.kind !== 'user') break;
+        if (!wantBlocks) break;
+        const text = textOfContent(data.content, false);
+        if (text) blocks.push({ kind: 'prompt', label: 'Prompt', role: 'user', text });
+        break;
+      }
+      case 'assistant/message': {
+        const message = asRecord(data.message);
+        const turn = getTurn(turnNo);
+        ensureStep(turn, stepNo);
+        const text = textOfContent(message?.content);
+        if (message) turn.finalizedSteps.add(stepNo);
+        if (text) {
+          turn.finalized.set(stepNo, text);
+          turn.timestamp = isoTime(event.time) || turn.timestamp;
+          if (wantBlocks) blocks.push({ kind: 'response', label: 'Response', role: 'assistant', text });
+        }
+        if (wantBlocks) {
+          for (const call of toolCallsOfContent(message?.content)) {
+            blocks.push({ kind: 'tool', label: 'Tool', role: 'assistant', text: call });
+          }
+        }
+        break;
+      }
+      case 'assistant/chunk': {
+        const chunk = asRecord(data.chunk);
+        if (chunk?.type !== 'text-delta' || typeof chunk.text !== 'string') break;
+        const turn = getTurn(turnNo);
+        ensureStep(turn, stepNo);
+        turn.streamed.set(stepNo, (turn.streamed.get(stepNo) ?? '') + chunk.text);
+        break;
+      }
+      case 'text-chunks': {
+        // The batched form of the same deltas (dsh coalesces once a stream gets
+        // going). ⚠️ These carry `seq: null`, so file order is the only order.
+        const turn = getTurn(turnNo);
+        ensureStep(turn, stepNo);
+        const texts = asArray(data.texts)
+          .filter((t): t is string => typeof t === 'string')
+          .join('');
+        if (texts) turn.streamed.set(stepNo, (turn.streamed.get(stepNo) ?? '') + texts);
+        break;
+      }
+      case 'tool/result': {
+        if (!wantBlocks) break;
+        const text = textOfToolResult(data.message);
+        if (text) blocks.push({ kind: 'tool', label: 'Tool', role: 'assistant', text });
+        break;
+      }
+      case 'turn/end': {
+        const turn = getTurn(turnNo);
+        const reason = asRecord(data.reason);
+        if (reason && reason.kind !== 'completed') {
+          // Two different things wear this field: a provider failure
+          // (`kind:'error'` with a message) and an ordinary early stop
+          // (`kind:'max-tokens'`, measured live). Calling the second one an
+          // error would misreport a truncated but real answer.
+          const error = asRecord(reason.error);
+          const message = typeof error?.message === 'string' ? error.message : undefined;
+          const kind = typeof reason.kind === 'string' ? reason.kind : 'unknown';
+          turn.ending = message ? `Turn error: ${message}` : `Turn ended: ${kind}`;
+          if (wantBlocks) {
+            blocks.push({ kind: 'status', label: 'Status', role: 'assistant', text: turn.ending });
+          }
+        }
+        turn.timestamp = isoTime(event.time) || turn.timestamp;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const lastTurn = turnOrder.length > 0 ? turns.get(turnOrder[turnOrder.length - 1] as number) : undefined;
+  let text = lastTurn ? turnText(lastTurn) : '';
+  // A turn that failed and said nothing answers with its failure, labelled so
+  // it can never read as the model's own words. Without this an agent polls
+  // `last-response` fifteen times and concludes the worker never answered.
+  if (!text && lastTurn?.ending) text = lastTurn.ending;
+
+  return { text, timestamp: lastTurn?.timestamp ?? '', blocks, sessionId, cwd };
+}
+
+/**
+ * `$DSH_HOME` for one session: a per-session override wins (`DSH_HOME` is an
+ * allowlisted `envOverrides` prefix, and pointing a worker at its own profile
+ * tree is a documented thing to do), then the server's own environment, then
+ * `~/.dsh`. Reading the wrong tree does not fail loudly — it silently finds no
+ * transcript — so this must resolve exactly the way the spawn did.
+ */
+/* ⚠️ The override is EPHEMERAL: `envOverrides` is applied at spawn and exported
+ * through `tmux setenv`, but is deliberately not persisted to state.json (it can
+ * carry provider keys). A session that overrode `DSH_HOME` and then outlived a
+ * server restart therefore resolves to the default tree and finds no transcript
+ * — it reads as "nothing said yet" rather than as another session's answer,
+ * because every candidate is matched on its recorded `cwd`. */
+export function resolveDeepSeekHome(session: { deepSeekHomeOverride?: string }): string {
+  const override = session.deepSeekHomeOverride;
+  if (override && override.trim()) return override.trim();
+  const fromEnv = process.env.DSH_HOME;
+  if (fromEnv && fromEnv.trim()) return fromEnv.trim();
+  return join(homedir(), '.dsh');
+}
+
+/**
+ * How far apart a session's start and its transcript's `createdAt` may be and
+ * still be the same session. dsh writes the header within ~2 s of pane start
+ * (measured); 60 s absorbs a cold profile boot without ever reaching a sibling
+ * started minutes later.
+ */
+const PAIRING_WINDOW_MS = 60_000;
+
+/** Transcript file names dsh has used, newest convention first. */
+const TRANSCRIPT_FILES = ['session.jsonl.zstd', 'session.jsonl'];
+
+/**
+ * Locate the transcript for a session.
+ *
+ * dsh buckets sessions by a mangled cwd (`--home-you-code-app--`) and then by
+ * its own session id, and the id form has changed between versions (`<uuid>`
+ * and `session-<uuid>` both exist on disk here). ⚠️ So the mangling is NOT
+ * reproduced: every candidate's own header line carries `cwd`, which is
+ * authoritative, and matching on it is immune to the next naming change.
+ *
+ * Pairing a Codeman session with ITS transcript then has one hard rule and one
+ * ladder. The rule: a transcript created BEFORE this session started belongs to
+ * an earlier conversation in the same directory and is never eligible. Measured
+ * cost of getting that wrong — a freshly spawned worker answered its very first
+ * `last-response` with the PREVIOUS session's reply, which is worse than saying
+ * nothing, because an agent cannot tell a stale answer from a fresh one.
+ *
+ * The ladder, once the older ones are out:
+ *
+ *   1. a transcript whose header `createdAt` sits within `PAIRING_WINDOW_MS` of
+ *      this session's start — that is this pane's own boot, and it stays right
+ *      even when a sibling session is running in the same case directory;
+ *   2. otherwise the newest transcript created after this session started;
+ *   3. otherwise nothing.
+ *
+ * ⚠️ The boot transcript wins for as long as it exists on disk — deliberately,
+ * and even over a LATER transcript in the same workspace. Step 2 cannot tell a
+ * `/new` from a sibling session that started later in the same directory, so
+ * preferring newest-eligible would hand a worker its busier sibling's reply
+ * (the exact bug the hard rule above was measured against, one seat over).
+ * The cost of that choice: after an interactive `/new` in a dsh tab, this
+ * reader keeps serving the pre-`/new` conversation (the same session's own
+ * earlier turns — stale, never foreign); step 2 is reached only when no
+ * boot-window transcript exists. Worker fleets never `/new`, so they only
+ * ever see step 1.
+ */
+export async function findDeepSeekTranscript(options: {
+  dshHome: string;
+  workingDir: string;
+  startedAt?: number;
+}): Promise<string | null> {
+  const sessionsDir = join(options.dshHome, 'sessions');
+  let buckets: string[];
+  try {
+    buckets = (await fs.readdir(sessionsDir, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    return null;
+  }
+
+  const candidates: Array<{ path: string; mtimeMs: number }> = [];
+  for (const bucket of buckets) {
+    const bucketPath = join(sessionsDir, bucket);
+    let sessions: string[];
+    try {
+      sessions = (await fs.readdir(bucketPath, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    } catch {
+      continue;
+    }
+    for (const sessionDir of sessions) {
+      for (const file of TRANSCRIPT_FILES) {
+        const path = join(bucketPath, sessionDir, file);
+        const stat = await fs.stat(path).catch(() => null);
+        if (!stat || !stat.isFile() || stat.size === 0) continue;
+        candidates.push({ path, mtimeMs: stat.mtimeMs });
+        break;
+      }
+    }
+  }
+  if (candidates.length === 0) return null;
+
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const startedAt = options.startedAt ?? 0;
+  // Slack in both directions: the harness writes its header a beat after the
+  // pane starts, and mtimes on a shared clock are not worth trusting to the ms.
+  const floor = startedAt > 0 ? startedAt - PAIRING_WINDOW_MS : 0;
+
+  let laterMatch: string | null = null;
+  for (const candidate of candidates) {
+    const header = await readTranscriptHeader(candidate.path);
+    if (!header || header.cwd !== options.workingDir) continue;
+    // No usable header timestamp: fall back to the file's own mtime, which is
+    // still enough to keep a pre-session transcript out.
+    const createdAt = header.createdAt ?? candidate.mtimeMs;
+    if (createdAt < floor) continue;
+    if (startedAt > 0 && Math.abs(createdAt - startedAt) <= PAIRING_WINDOW_MS) return candidate.path;
+    if (!laterMatch) laterMatch = candidate.path;
+  }
+  return laterMatch;
+}
+
+/**
+ * Read only the first frame of a transcript, which is where the header line
+ * lives. Bounded: a candidate scan must never decompress every conversation on
+ * the box to answer one `last-response` call.
+ */
+async function readTranscriptHeader(path: string): Promise<{ cwd?: string; id?: string; createdAt?: number } | null> {
+  let handle;
+  try {
+    handle = await fs.open(path, 'r');
+  } catch {
+    return null;
+  }
+  try {
+    const head = Buffer.alloc(65536);
+    const { bytesRead } = await handle.read(head, 0, head.length, 0);
+    if (bytesRead === 0) return null;
+    const text = decodeZstdFrames(head.subarray(0, bytesRead));
+    const firstLine = text.split('\n').find((line) => line.trim());
+    if (!firstLine) return null;
+    const parsed = JSON.parse(firstLine) as { type?: string; cwd?: string; id?: string; createdAt?: number };
+    if (parsed.type !== 'session') return null;
+    return {
+      cwd: parsed.cwd,
+      id: parsed.id,
+      createdAt: typeof parsed.createdAt === 'number' ? parsed.createdAt : undefined,
+    };
+  } catch {
+    return null;
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+/** Hard ceiling on a transcript read. A long agent run is a few hundred KB; a
+ *  file past this is pathological and is not worth a synchronous decode. */
+const MAX_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Memo of the last few decoded transcripts, keyed on (path, mtime, size,
+ * blocks). The skill's `last_text` polls once per second, and each poll used
+ * to zstdDecompressSync + reparse the WHOLE file on the event loop even when
+ * nothing had been appended — a multi-MB transcript made that a repeated
+ * ~100ms-class stall on the single-threaded server. A poll that finds the
+ * file unchanged now costs one stat. Insertion-order eviction; tiny, because
+ * an entry only earns its keep while a session is being actively polled.
+ */
+const parseMemo = new Map<string, DeepSeekTranscriptResult>();
+const PARSE_MEMO_MAX = 16;
+
+/** Test seam: a fixture that rewrites one path in place inside a single mtime
+ *  tick would otherwise read its predecessor back out of the memo. */
+export function resetDeepSeekTranscriptMemoForTest(): void {
+  parseMemo.clear();
+}
+
+/**
+ * Read one dsh session's last answer.
+ *
+ * ⚠️ The two empty outcomes are deliberately different, because the caller must
+ * treat them differently:
+ *
+ * - `null` means **this reader cannot run here** (a Node without zstd), and is
+ *   the signal to fall back to the pane segmenter.
+ * - an empty `text` means **read fine, nothing said yet** — no transcript for
+ *   this workspace, or a turn still in flight.
+ *
+ * Collapsing the two would put the ASCII-art splash back in front of an agent
+ * that is polling for a worker's first answer.
+ */
+export async function readDeepSeekLastResponse(
+  session: { workingDir: string; createdAt?: Date | number; deepSeekHomeOverride?: string },
+  options: { blocks?: boolean } = {}
+): Promise<DeepSeekTranscriptResult | null> {
+  const createdAt = session.createdAt instanceof Date ? session.createdAt.getTime() : session.createdAt;
+  // dsh compresses by default, so a Node without zstd can read nothing here.
+  // That is the one case the pane is still the better answer.
+  if (!zstdSupported()) return null;
+
+  const empty: DeepSeekTranscriptResult = { text: '', timestamp: '', blocks: [] };
+  const path = await findDeepSeekTranscript({
+    dshHome: resolveDeepSeekHome(session),
+    workingDir: session.workingDir,
+    startedAt: typeof createdAt === 'number' ? createdAt : undefined,
+  });
+  if (!path) return empty;
+
+  const stat = await fs.stat(path).catch(() => null);
+  if (!stat || stat.size > MAX_TRANSCRIPT_BYTES) return empty;
+
+  const memoKey = `${path}|${stat.mtimeMs}|${stat.size}|${options.blocks ? 1 : 0}`;
+  const memoized = parseMemo.get(memoKey);
+  if (memoized) return memoized;
+
+  let buf: Buffer;
+  try {
+    buf = await fs.readFile(path);
+  } catch {
+    return empty;
+  }
+  const result = parseDeepSeekTranscript(decodeZstdFrames(buf), options);
+  if (parseMemo.size >= PARSE_MEMO_MAX) {
+    const oldest = parseMemo.keys().next().value;
+    if (oldest !== undefined) parseMemo.delete(oldest);
+  }
+  parseMemo.set(memoKey, result);
+  return result;
+}

src/deepseek-web-server.ts

@@ -0,0 +1,283 @@
+/**
+ * @fileoverview Supervises the one background `dsh web` process behind the Run
+ * menu's "DeepSeek web UI..." entry.
+ *
+ * The shortcut originally started the server inside an ordinary SHELL SESSION,
+ * on the reasoning that Codeman already knows how to supervise those: it was
+ * visible, scrollable, killable, and died with its tab, and nothing new had to
+ * own a long-lived HTTP server. That reasoning was sound and the result was
+ * still wrong in use — clicking "open the DeepSeek web UI" spawned a terminal
+ * tab the user never asked for, next to the web tab they did, and the terminal
+ * was noise every time after the first.
+ *
+ * So the server moves here instead: one child process, no session, no tab.
+ * What that buys back has to be paid for explicitly, which is what this module
+ * is:
+ *
+ * - **Exactly one.** A second click reuses the running server rather than
+ *   racing it for a port. The old shell-session flow could not do this at all,
+ *   because two clicks were simply two sessions.
+ * - **Restarted when the authority changes.** `--trusted-host` fences dsh's
+ *   `/api` against the browser authority, and a Codeman reachable at both
+ *   loopback and a tailnet name has two. Whoever asks last wins, because the
+ *   asker is by definition the origin about to load the page.
+ * - **Killed on shutdown.** A detached child that outlived Codeman would hold
+ *   its port against the next start, which is exactly the EADDRINUSE this
+ *   feature already got wrong once.
+ * - **Failures reported, not swallowed.** The shell tab used to be where the
+ *   stack trace landed. With no tab, the spawn's own output is captured and
+ *   handed back to the caller instead.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { getErrorMessage } from './types.js';
+
+/**
+ * Where the port search starts, and how far it walks.
+ *
+ * 3080 is `dsh web`'s own default, so it is the friendly first choice — and
+ * emphatically not a fixed port. DeepSeek's web UI is a thing users run
+ * themselves, which makes the default precisely the port most likely to be
+ * taken already; hardcoding it made this feature die with EADDRINUSE against
+ * the user's own server.
+ */
+const PORT_BASE = 3080;
+const PORT_SPAN = 40;
+
+/** How long a freshly spawned server gets to answer before we call it failed. */
+const READY_TIMEOUT_MS = 30_000;
+const READY_POLL_MS = 400;
+/** Grace between SIGTERM and SIGKILL when stopping the tree. */
+const KILL_GRACE_MS = 3_000;
+/** Bound on captured child output, so a chatty boot cannot grow without limit. */
+const OUTPUT_CAP = 16_384;
+
+export interface DeepSeekWebStatus {
+  running: boolean;
+  port: number | null;
+  url: string | null;
+  /** Browser authority this server was started to trust (`--trusted-host`). */
+  authority: string | null;
+}
+
+interface RunningServer {
+  child: ChildProcess;
+  port: number;
+  authority: string;
+  output: () => string;
+}
+
+let current: RunningServer | null = null;
+
+/**
+ * True when nothing holds `port` on loopback.
+ *
+ * Binding is the only honest test: a connect probe cannot tell "free" from
+ * "listening but not answering yet", and this runs moments before `dsh web`
+ * binds the same port. It is inherently racy, which is why the caller still
+ * waits for the server to actually answer before reporting success.
+ */
+async function isLoopbackPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once('error', () => resolve(false));
+    probe.once('listening', () => probe.close(() => resolve(true)));
+    probe.listen(port, '127.0.0.1');
+  });
+}
+
+async function findFreePort(): Promise<number | null> {
+  for (let port = PORT_BASE; port < PORT_BASE + PORT_SPAN; port++) {
+    if (await isLoopbackPortFree(port)) return port;
+  }
+  return null;
+}
+
+/** Does the server answer HTTP yet? Any status counts: dsh may 4xx a bare GET. */
+async function answersHttp(port: number): Promise<boolean> {
+  try {
+    await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(2_000) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Signal the whole process group.
+ *
+ * `dsh web` boots a plugin tree and fans out, so signalling only the direct
+ * child leaves survivors holding the port. Same negative-pid escalation as
+ * `runGit()` in git-clone.ts and the profile installer.
+ */
+function killTree(child: ChildProcess, signal: NodeJS.Signals): void {
+  try {
+    if (child.pid) process.kill(-child.pid, signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+export function getDeepSeekWebStatus(): DeepSeekWebStatus {
+  if (!current) return { running: false, port: null, url: null, authority: null };
+  return {
+    running: true,
+    port: current.port,
+    url: `http://127.0.0.1:${current.port}`,
+    authority: current.authority,
+  };
+}
+
+/** Stop the background server, if one is running. Safe to call when none is. */
+export async function stopDeepSeekWeb(): Promise<void> {
+  const running = current;
+  current = null;
+  if (!running) return;
+
+  await new Promise<void>((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(hard);
+      resolve();
+    };
+    running.child.once('exit', finish);
+    killTree(running.child, 'SIGTERM');
+    const hard = setTimeout(() => {
+      killTree(running.child, 'SIGKILL');
+      finish();
+    }, KILL_GRACE_MS);
+  });
+}
+
+type StartResult = { ok: true; port: number; url: string; reused: boolean } | { ok: false; error: string };
+
+/**
+ * Serializes concurrent starts. Two POSTs racing (two devices, or a double
+ * click while the first boots) used to both see `current === null`, pick the
+ * SAME free port, and spawn twice: the loser died on EADDRINUSE while its exit
+ * handler nulled the singleton out from under the winner, leaving a live
+ * `dsh web` nothing tracked or killed — the exact orphan this module exists to
+ * prevent. The second caller now simply waits and reuses the first's server.
+ */
+let startLock: Promise<unknown> = Promise.resolve();
+
+/**
+ * Start (or reuse) the background `dsh web` for `authority`.
+ *
+ * @param dshDir directory holding the resolved `dsh` binary.
+ * @param authority browser authority to pass as `--trusted-host`.
+ */
+export function startDeepSeekWeb(dshDir: string, authority: string): Promise<StartResult> {
+  const run = startLock.then(
+    () => startDeepSeekWebLocked(dshDir, authority),
+    () => startDeepSeekWebLocked(dshDir, authority)
+  );
+  startLock = run.then(
+    () => undefined,
+    () => undefined
+  );
+  return run;
+}
+
+async function startDeepSeekWebLocked(dshDir: string, authority: string): Promise<StartResult> {
+  // Reuse only when the running server is BOTH healthy and fenced for the
+  // authority now asking. A server trusting the other origin renders a page
+  // whose every API call 403s, which looks like a broken dashboard rather than
+  // a misconfigured one.
+  if (current) {
+    if (current.authority === authority && (await answersHttp(current.port))) {
+      return { ok: true, port: current.port, url: `http://127.0.0.1:${current.port}`, reused: true };
+    }
+    await stopDeepSeekWeb();
+  }
+
+  const port = await findFreePort();
+  if (port === null) {
+    return { ok: false, error: `No free port for the DeepSeek web UI in ${PORT_BASE}-${PORT_BASE + PORT_SPAN - 1}` };
+  }
+
+  let child: ChildProcess;
+  try {
+    child = spawn(
+      join(dshDir, 'dsh'),
+      ['web', '--no-open', '--host', '127.0.0.1', '--port', String(port), '--trusted-host', authority],
+      {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // Own process group so the whole plugin tree can be signalled at once.
+        detached: true,
+        env: process.env,
+      }
+    );
+  } catch (err) {
+    return { ok: false, error: `Failed to start dsh web: ${getErrorMessage(err)}` };
+  }
+
+  // The pipes must be drained whether or not anyone reads them: a full pipe
+  // blocks the child. Storage is capped; draining is not.
+  let output = '';
+  const capture = (chunk: Buffer) => {
+    if (output.length < OUTPUT_CAP) output += chunk.toString('utf-8');
+  };
+  child.stdout?.on('data', capture);
+  child.stderr?.on('data', capture);
+
+  let exited = false;
+  child.once('exit', () => {
+    exited = true;
+    // Only clear if this is still the current server: a restart may have
+    // already replaced it, and clearing then would drop the live one.
+    if (current?.child === child) current = null;
+  });
+  child.once('error', () => {
+    exited = true;
+    if (current?.child === child) current = null;
+  });
+
+  const running: RunningServer = { child, port, authority, output: () => output };
+  current = running;
+
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (exited) {
+      // Guarded like the exit/error handlers: a concurrent stop (DELETE route,
+      // shutdown) may already have cleared or replaced the singleton, and an
+      // unconditional null here would drop a server this call does not own.
+      if (current === running) current = null;
+      const tail = output.trim().slice(-800);
+      return { ok: false, error: tail ? `dsh web exited during startup: ${tail}` : 'dsh web exited during startup' };
+    }
+    if (await answersHttp(port)) {
+      return { ok: true, port, url: `http://127.0.0.1:${port}`, reused: false };
+    }
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+
+  // Timeout: kill OUR child. Only route through stopDeepSeekWeb() while the
+  // singleton is still ours — signalling `current` unconditionally here could
+  // SIGTERM a healthy server a concurrent actor now owns.
+  if (current === running) {
+    await stopDeepSeekWeb();
+  } else {
+    killTree(running.child, 'SIGKILL');
+  }
+  const tail = output.trim().slice(-800);
+  return {
+    ok: false,
+    error: tail
+      ? `dsh web did not answer on port ${port} within ${READY_TIMEOUT_MS / 1000}s: ${tail}`
+      : `dsh web did not answer on port ${port} within ${READY_TIMEOUT_MS / 1000}s`,
+  };
+}
+
+/** Test seam: forget any tracked child without signalling it. */
+export function resetDeepSeekWebForTest(): void {
+  current = null;
+}

src/docker-hosts.ts

@@ -145,6 +145,8 @@ export function defaultDockerCommandForMode(mode: SessionMode): string {
     gemini: 'exec gemini',
     antigravity: 'exec agy',
     pi: 'exec pi',
+    grok: 'exec grok',
+    deepseek: 'exec dsh',
   };
   return commands[mode as DockerCommandMode] || commands.shell;
 }
@@ -614,6 +616,27 @@ const CRED_STORES: CredStorePolicy[] = [
     rel: '.pi/agent',
     seedFiles: ['auth.json', 'settings.json', 'trust.json', 'models.json', 'models-store.json'],
   },
+  // Grok (xAI) keeps auth + config in `~/.grok`, but that dir ALSO holds
+  // `sessions/`, `memory/`, `downloads/` (the ~100MB binary itself) and `bin/`,
+  // so seedWhole would copy all of it into every container start. Seed only what
+  // grok needs to authenticate and behave consistently. Same trade-off as pi:
+  // in-container grok sessions are invisible host-side, so `grok -c` inside a
+  // Docker case only sees that container's own history.
+  {
+    rel: '.grok',
+    seedFiles: ['auth.json', 'config.toml', 'pager.toml'],
+  },
+  // DeepSeek Harness keeps credentials in `~/.dsh/.env` (0600) and composition in
+  // `settings.yaml` / `cordis.patch.yml`. `profiles/` is deliberately NOT seeded:
+  // it is a pnpm workspace holding a full node_modules tree per profile, which is
+  // both enormous and host-arch-specific. An in-container dsh therefore needs its
+  // profile installed IN the image (see docker/agent.Dockerfile), and the seeded
+  // files only supply auth and model composition. Same host-invisibility trade-off
+  // as pi and grok: `~/.dsh/sessions` inside a container is that container's own.
+  {
+    rel: '.dsh',
+    seedFiles: ['.env', 'settings.yaml', 'cordis.patch.yml'],
+  },
   { rel: '.config/gcloud', seedWhole: true },
   { rel: '.config/opencode', seedWhole: true },
 ];

src/mux-interface.ts

@@ -19,6 +19,8 @@ import type {
   GeminiConfig,
   AntigravityConfig,
   PiConfig,
+  GrokConfig,
+  DeepSeekConfig,
   SessionRemote,
   SessionDocker,
 } from './types.js';
@@ -78,6 +80,8 @@ export interface CreateSessionOptions {
   geminiConfig?: GeminiConfig;
   antigravityConfig?: AntigravityConfig;
   piConfig?: PiConfig;
+  grokConfig?: GrokConfig;
+  deepSeekConfig?: DeepSeekConfig;
   /** When restoring after reboot, resume a previous Claude conversation by its session ID */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Ephemeral — not written to disk. */
@@ -110,6 +114,8 @@ export interface RespawnPaneOptions {
   geminiConfig?: GeminiConfig;
   antigravityConfig?: AntigravityConfig;
   piConfig?: PiConfig;
+  grokConfig?: GrokConfig;
+  deepSeekConfig?: DeepSeekConfig;
   /** Resume a previous Claude conversation when respawning */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (preserved across respawns). */

src/remote-hosts.ts

@@ -114,6 +114,11 @@ export function defaultRemoteCommandForMode(mode: SessionMode): string {
     gemini: remoteLoginShellCommand('gemini'),
     antigravity: remoteLoginShellCommand('agy'),
     pi: remoteLoginShellCommand('pi'),
+    grok: remoteLoginShellCommand('grok'),
+    // `dsh` alone boots nothing: the launcher needs a profile, and the remote box's
+    // profile inventory is unknown here. The per-host `commands.deepseek` override
+    // is the escape hatch for naming one.
+    deepseek: remoteLoginShellCommand('dsh'),
   };
   return commands[mode as RemoteCommandMode] || commands.shell;
 }

src/session.ts

@@ -51,6 +51,8 @@ import {
   type GeminiConfig,
   type AntigravityConfig,
   type PiConfig,
+  type GrokConfig,
+  type DeepSeekConfig,
   type SessionRemote,
   type SessionDocker,
 } from './types.js';
@@ -171,7 +173,15 @@ const NEWLINE_SPLIT_PATTERN = /\r?\n/;
 
 /** True for external-CLI run modes (non-Claude) that use their own TUI and output format. */
 export function isExternalCliMode(mode: SessionMode): boolean {
-  return mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi';
+  return (
+    mode === 'opencode' ||
+    mode === 'codex' ||
+    mode === 'gemini' ||
+    mode === 'antigravity' ||
+    mode === 'pi' ||
+    mode === 'grok' ||
+    mode === 'deepseek'
+  );
 }
 
 function getModeLabel(mode: SessionMode): string {
@@ -186,6 +196,10 @@ function getModeLabel(mode: SessionMode): string {
       return 'Antigravity';
     case 'pi':
       return 'Pi';
+    case 'grok':
+      return 'Grok';
+    case 'deepseek':
+      return 'DeepSeek';
     case 'shell':
       return 'Shell';
     case 'claude':
@@ -202,8 +216,9 @@ function getModeLabel(mode: SessionMode): string {
  * 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) and `pi` (below). Keep parity with the replay-side
- * strip in session-routes.ts.
+ * 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.
  *
  * ⚠️ Being excluded here does NOT preserve the alt screen. Every excluded mode
  * falls through to isMuxAltScreenOnlyStripMode(), which strips the alt-screen
@@ -508,6 +523,11 @@ export class Session extends EventEmitter {
   private _antigravityConfig: AntigravityConfig | undefined;
   // Pi configuration (only for mode === 'pi')
   private _piConfig: PiConfig | undefined;
+  // Grok configuration (only for mode === 'grok')
+  private _grokConfig: GrokConfig | undefined;
+
+  // DeepSeek Harness configuration (only for mode === 'deepseek')
+  private _deepSeekConfig: DeepSeekConfig | undefined;
   private _resumeSessionId: string | undefined;
 
   // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -603,6 +623,10 @@ export class Session extends EventEmitter {
       antigravityConfig?: AntigravityConfig;
       /** Pi configuration (only for mode === 'pi') */
       piConfig?: PiConfig;
+      /** Grok configuration (only for mode === 'grok') */
+      grokConfig?: GrokConfig;
+      /** DeepSeek Harness configuration (only for mode === 'deepseek') */
+      deepSeekConfig?: DeepSeekConfig;
       /** Resume a previous Claude conversation (used after server reboot) */
       resumeSessionId?: string;
       /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
@@ -712,6 +736,16 @@ export class Session extends EventEmitter {
       this._piConfig = config.piConfig;
     }
 
+    // Apply DeepSeek Harness configuration
+    if (config.deepSeekConfig) {
+      this._deepSeekConfig = config.deepSeekConfig;
+    }
+
+    // Apply Grok configuration
+    if (config.grokConfig) {
+      this._grokConfig = config.grokConfig;
+    }
+
     // Apply env overrides (exported at spawn, not persisted to disk).
     // Legacy migration: pre-0.7.2 carried effort as the CLAUDE_CODE_EFFORT_LEVEL env var,
     // which hard-locks /effort switching. Extract it into _effort (--settings soft default)
@@ -859,6 +893,34 @@ export class Session extends EventEmitter {
     return this._remote;
   }
 
+  /**
+   * `deepSeekConfig.statusReporting` verbatim: `undefined` when the caller sent
+   * none (i.e. ON), `false` when the user disarmed the status bridge for this
+   * session.
+   *
+   * Exposed because whether a dsh session can deliver `stop`/`blocked` is a
+   * per-SESSION fact, not a per-mode one, and `hooksAvailableForMode()` is pure
+   * and holds no `Session` reference by design. Undefined for every other mode,
+   * where the flag is meaningless.
+   */
+  get deepSeekStatusReporting(): boolean | undefined {
+    return this._deepSeekConfig?.statusReporting;
+  }
+
+  /**
+   * This session's `DSH_HOME` override, if it set one.
+   *
+   * Deliberately ONE key rather than an `envOverrides` getter: the map can hold
+   * provider credentials (`DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, …) and is
+   * kept off the public `SessionState` for exactly that reason. The transcript
+   * reader needs the profile tree's location and nothing else, so that is all
+   * this exposes.
+   */
+  get deepSeekHomeOverride(): string | undefined {
+    const value = this._envOverrides?.DSH_HOME;
+    return value && value.trim() ? value.trim() : undefined;
+  }
+
   /** Owning username in multi-user mode, else undefined. */
   get owner(): string | undefined {
     return this._owner;
@@ -1304,6 +1366,8 @@ export class Session extends EventEmitter {
       geminiConfig: this._geminiConfig,
       antigravityConfig: this._antigravityConfig,
       piConfig: this._piConfig,
+      grokConfig: this._grokConfig,
+      deepSeekConfig: this._deepSeekConfig,
       resumeSessionId: this._resumeSessionId,
       effort: this._effort,
       // COD-118: runtime-only — surfaced so the frontend can require explicit user
@@ -1476,7 +1540,12 @@ export class Session extends EventEmitter {
           // COD-75: codex/gemini/antigravity/pi get COLORTERM=truecolor — mirrors buildEnvExports()
           // in tmux-manager.ts so the attach client and the tmux session agree.
           env: buildMuxAttachEnv(
-            this.mode === 'codex' || this.mode === 'gemini' || this.mode === 'antigravity' || this.mode === 'pi'
+            this.mode === 'codex' ||
+              this.mode === 'gemini' ||
+              this.mode === 'antigravity' ||
+              this.mode === 'pi' ||
+              this.mode === 'grok' ||
+              this.mode === 'deepseek'
           ),
         })
       );
@@ -1546,6 +1615,8 @@ export class Session extends EventEmitter {
       geminiConfig: this._geminiConfig,
       antigravityConfig: this._antigravityConfig,
       piConfig: this._piConfig,
+      grokConfig: this._grokConfig,
+      deepSeekConfig: this._deepSeekConfig,
       resumeSessionId: this._resumeSessionId,
       envOverrides: this._envOverrides,
       effort: this._effort,
@@ -1804,6 +1875,8 @@ export class Session extends EventEmitter {
             geminiConfig: this._geminiConfig,
             antigravityConfig: this._antigravityConfig,
             piConfig: this._piConfig,
+            grokConfig: this._grokConfig,
+            deepSeekConfig: this._deepSeekConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
             effort: this._effort,
@@ -1893,6 +1966,16 @@ export class Session extends EventEmitter {
       if (this.mode === 'pi') {
         throw new Error('Pi sessions require tmux. Direct PTY fallback is not supported.');
       }
+      // Grok sessions require tmux for XAI_API_KEY / GROK_* injection via setenv
+      if (this.mode === 'grok') {
+        throw new Error('Grok sessions require tmux. Direct PTY fallback is not supported.');
+      }
+      // DeepSeek sessions require tmux for DEEPSEEK_API_KEY / DSH_PERMISSION_MODE
+      // injection via setenv — and for the HERDR_* status-bridge triple, without
+      // which the mode silently loses its definitive idle/blocked signals.
+      if (this.mode === 'deepseek') {
+        throw new Error('DeepSeek Harness sessions require tmux. Direct PTY fallback is not supported.');
+      }
       try {
         // Pass --session-id to use the SAME ID as the Codeman session
         // This ensures subagents can be directly matched to the correct tab

src/state-store.ts

@@ -40,6 +40,8 @@ import {
 } from './types.js';
 import { Debouncer, MAX_SESSION_TOKENS } from './utils/index.js';
 import { dataPath, CODEMAN_INSTANCE } from './config/instance.js';
+import { normalizeSessionOrder } from './session-order.js';
+import { validateTabLayout, type TabLayout } from './tab-layout.js';
 
 /** Debounce delay for batching state writes (ms) */
 const SAVE_DEBOUNCE_MS = 500;
@@ -281,6 +283,9 @@ export class StateStore {
     if (this.state.sessionOrder) {
       parts.push(`"sessionOrder":${JSON.stringify(this.state.sessionOrder)}`);
     }
+    if (this.state.tabLayouts !== undefined) {
+      parts.push(`"tabLayouts":${JSON.stringify(this.state.tabLayouts)}`);
+    }
 
     return `{${parts.join(',')}}`;
   }
@@ -514,22 +519,28 @@ export class StateStore {
    */
   cleanupStaleSessions(activeSessionIds: Set<string>): {
     count: number;
-    cleaned: Array<{ id: string; name?: string }>;
+    cleaned: Array<{ id: string; name?: string; owner?: string }>;
   } {
-    const allSessionIds = Object.keys(this.state.sessions);
-    const cleaned: Array<{ id: string; name?: string }> = [];
+    const staleIds = new Set(Object.keys(this.state.sessions).filter((sessionId) => !activeSessionIds.has(sessionId)));
+    return this.cleanupSessionsByIds(staleIds);
+  }
 
-    for (const sessionId of allSessionIds) {
-      if (!activeSessionIds.has(sessionId)) {
-        if (this.state.sessions[sessionId]?.pinned === true) continue; // COD-142: pinned records persist even with no live session
-        const name = this.state.sessions[sessionId]?.name;
-        cleaned.push({ id: sessionId, name });
-        delete this.state.sessions[sessionId];
-        this.cachedSessionJsons.delete(sessionId);
-        this.dirtySessions.delete(sessionId);
-        // Also clean up Ralph state for this session
-        this.ralphStates.delete(sessionId);
-      }
+  /** Deletes only confirmed stale session IDs, retaining records pinned after confirmation. */
+  cleanupSessionsByIds(sessionIds: ReadonlySet<string>): {
+    count: number;
+    cleaned: Array<{ id: string; name?: string; owner?: string }>;
+  } {
+    const cleaned: Array<{ id: string; name?: string; owner?: string }> = [];
+
+    for (const sessionId of sessionIds) {
+      const session = this.state.sessions[sessionId];
+      if (!session || session.pinned === true) continue; // COD-142: pinned records persist even with no live session
+      cleaned.push({ id: sessionId, name: session.name, owner: session.owner });
+      delete this.state.sessions[sessionId];
+      this.cachedSessionJsons.delete(sessionId);
+      this.dirtySessions.delete(sessionId);
+      // Also clean up Ralph state for this session
+      this.ralphStates.delete(sessionId);
     }
 
     if (cleaned.length > 0) {
@@ -664,6 +675,41 @@ export class StateStore {
     this.save();
   }
 
+  /** Returns an owner layout, or null before that owner has been migrated. */
+  getTabLayout(owner: string): TabLayout | null {
+    const layouts = this.state.tabLayouts;
+    return layouts && Object.hasOwn(layouts, owner) ? layouts[owner] : null;
+  }
+
+  /** Returns a defensive snapshot of every stored owner layout. */
+  getTabLayouts(): Record<string, TabLayout> {
+    return structuredClone(this.state.tabLayouts ?? {});
+  }
+
+  /** Validates and atomically persists one owner layout. */
+  setTabLayout(owner: string, layout: TabLayout): void {
+    const validated = validateTabLayout(layout);
+    this.state.tabLayouts = { ...(this.state.tabLayouts ?? {}), [owner]: validated };
+    this.save();
+  }
+
+  /** Atomically publishes validated owner layouts and their latest global compatibility projection. */
+  commitTabLayoutProjection(
+    layouts: Readonly<Record<string, TabLayout>>,
+    projectOrder: (latest: readonly string[]) => readonly string[]
+  ): { layouts: Record<string, TabLayout>; sessionOrder: string[] } {
+    const validated = Object.fromEntries(
+      Object.entries(layouts).map(([owner, layout]) => [owner, validateTabLayout(layout)])
+    );
+    const sessionOrder = normalizeSessionOrder(projectOrder([...(this.state.sessionOrder ?? [])]));
+    const nextLayouts = { ...(this.state.tabLayouts ?? {}), ...validated };
+
+    this.state.tabLayouts = nextLayouts;
+    this.state.sessionOrder = sessionOrder;
+    this.save();
+    return { layouts: structuredClone(validated), sessionOrder: [...sessionOrder] };
+  }
+
   /** Resets all state to initial values and saves immediately. */
   reset(): void {
     this.state = createInitialState();

src/tab-layout-legacy-order.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Pure compatibility translation between legacy session order and owner tab layouts.
+ */
+
+import { mergeSessionOrder, normalizeSessionOrder } from './session-order.js';
+import {
+  normalizeTabLayout,
+  validateTabLayout,
+  type TabLayout,
+  type TabRef,
+  type TabRefMetadata,
+} from './tab-layout.js';
+
+export interface OwnerOrderProjection {
+  owner: string;
+  ownedIds: readonly string[];
+  order: readonly string[];
+}
+
+export function applyLegacySessionRank(
+  input: TabLayout,
+  requestedOrder: readonly string[],
+  metadata: readonly TabRefMetadata[]
+): TabLayout {
+  const layout = validateTabLayout(input);
+  const requestedRank = new Map(normalizeSessionOrder(requestedOrder).map((id, index) => [id, index]));
+  const sessionMetadata = new Map<string, TabRefMetadata>();
+  for (const item of metadata) {
+    if (item.kind !== 'session' || !item.ownerValid || !item.visible || sessionMetadata.has(item.id)) continue;
+    sessionMetadata.set(item.id, item);
+  }
+
+  const isRanked = (ref: TabRef): boolean =>
+    ref.kind === 'session' && sessionMetadata.has(ref.id) && requestedRank.has(ref.id);
+  const prepare = (ref: TabRef): TabRef => {
+    if (ref.kind !== 'session') return { ...ref };
+    const item = sessionMetadata.get(ref.id);
+    const ownerValidParent = item?.parentSessionId && sessionMetadata.has(item.parentSessionId);
+    return ownerValidParent ? { ...ref, placement: 'manual' } : { ...ref };
+  };
+  const rankContainer = (refs: readonly TabRef[]): TabRef[] => {
+    const ranked = refs
+      .filter(isRanked)
+      .map(prepare)
+      .sort((a, b) => requestedRank.get(a.id)! - requestedRank.get(b.id)!);
+    let rankedIndex = 0;
+    return refs.map((ref) => (isRanked(ref) ? ranked[rankedIndex++] : { ...ref }));
+  };
+
+  const transformed: TabLayout = {
+    ...layout,
+    groups: layout.groups.map((group) => ({ ...group, refs: rankContainer(group.refs) })),
+    ungrouped: rankContainer(layout.ungrouped),
+  };
+  return normalizeTabLayout(transformed, metadata);
+}
+
+export function recomposeGlobalSessionOrder(
+  current: readonly string[],
+  projections: readonly OwnerOrderProjection[],
+  preferred?: readonly string[]
+): string[] {
+  let result = mergeSessionOrder([...(preferred ?? current)], [...current]);
+  for (const projection of projections) {
+    const ownedIds = normalizeSessionOrder(projection.ownedIds);
+    const owned = new Set(ownedIds);
+    const canonical = normalizeSessionOrder(projection.order).filter((id) => owned.has(id));
+    const canonicalSet = new Set(canonical);
+    for (const id of ownedIds) {
+      if (canonicalSet.has(id)) continue;
+      canonicalSet.add(id);
+      canonical.push(id);
+    }
+
+    let canonicalIndex = 0;
+    const recomposed = result.map((id) => (owned.has(id) ? canonical[canonicalIndex++] : id));
+    recomposed.push(...canonical.slice(canonicalIndex));
+    result = normalizeSessionOrder(recomposed);
+  }
+  return result;
+}

src/tab-layout-persistence.ts

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Owner-scoped tab-layout persistence and legacy migration primitives.
+ *
+ * This module is deliberately independent of routes and runtime managers. Callers
+ * provide persisted/live session facts plus saved webviews in server-store order.
+ */
+
+import { normalizeTabLayout, type TabLayout, type TabRef, type TabRefMetadata } from './tab-layout.js';
+
+export const SINGLE_USER_LAYOUT_OWNER = '@single';
+
+export interface TabLayoutSessionRecord {
+  id: string;
+  owner?: string;
+  createdAt: number;
+  parentSessionId?: string;
+}
+
+export interface TabLayoutWebviewRecord {
+  id: string;
+  owner?: string;
+}
+
+export interface TabLayoutMigrationInput {
+  owner: string;
+  layouts?: Readonly<Record<string, TabLayout>>;
+  sessionOrder?: readonly string[];
+  persistedSessions: readonly TabLayoutSessionRecord[];
+  liveSessions: readonly TabLayoutSessionRecord[];
+  /** Saved webviews in authoritative server-store order. */
+  webviews: readonly TabLayoutWebviewRecord[];
+  /** Required only when creating a layout, making migration deterministic in tests. */
+  updatedAt?: string;
+}
+
+export interface TabLayoutMigrationResult {
+  layout: TabLayout;
+  layouts: Record<string, TabLayout>;
+  created: boolean;
+}
+
+/** Resolve the persistence key without accepting an owner key from a client. */
+export function ownerLayoutKey(username?: string): string {
+  return username || SINGLE_USER_LAYOUT_OWNER;
+}
+
+function recordOwner(record: { owner?: string }): string {
+  return record.owner ?? SINGLE_USER_LAYOUT_OWNER;
+}
+
+function compareSessions(a: TabLayoutSessionRecord, b: TabLayoutSessionRecord): number {
+  return a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+
+function collectSessions(input: TabLayoutMigrationInput): Map<string, TabLayoutSessionRecord> {
+  const sessions = new Map<string, TabLayoutSessionRecord>();
+  for (const record of input.persistedSessions) sessions.set(record.id, { ...record });
+  // A matching live record is authoritative as a whole. In particular, absent
+  // optional owner/parent fields mean single-user ownership and root lineage;
+  // retaining those fields from a stale persisted copy changes their semantics.
+  for (const record of input.liveSessions) sessions.set(record.id, { ...record });
+  return sessions;
+}
+
+function buildMetadata(
+  input: TabLayoutMigrationInput,
+  sessions: ReadonlyMap<string, TabLayoutSessionRecord>
+): TabRefMetadata[] {
+  const ownerSessions = [...sessions.values()]
+    .filter((record) => recordOwner(record) === input.owner)
+    .sort(compareSessions);
+  const sessionOrder = new Map(ownerSessions.map((record, index) => [record.id, index]));
+  const metadata: TabRefMetadata[] = [...sessions.values()].map((record) => ({
+    kind: 'session',
+    id: record.id,
+    ownerValid: recordOwner(record) === input.owner,
+    visible: true,
+    order: sessionOrder.get(record.id) ?? record.createdAt,
+    parentSessionId: record.parentSessionId,
+  }));
+  const webviewOffset = ownerSessions.length;
+  input.webviews.forEach((record, index) => {
+    metadata.push({
+      kind: 'webview',
+      id: record.id,
+      ownerValid: recordOwner(record) === input.owner,
+      visible: true,
+      order: webviewOffset + index,
+    });
+  });
+  return metadata;
+}
+
+/**
+ * Normalize an existing owner layout, or idempotently migrate legacy flat order.
+ * Unknown stored refs remain unknown to metadata and are therefore preserved.
+ * No input object is mutated; validation/capacity failure is atomic.
+ */
+export function normalizeOrMigrateOwnerTabLayout(input: TabLayoutMigrationInput): TabLayoutMigrationResult {
+  const sessions = collectSessions(input);
+  const metadata = buildMetadata(input, sessions);
+  const existing = input.layouts && Object.hasOwn(input.layouts, input.owner) ? input.layouts[input.owner] : undefined;
+  if (existing) {
+    const layout = normalizeTabLayout(existing, metadata);
+    return { layout, layouts: { ...(input.layouts ?? {}), [input.owner]: layout }, created: false };
+  }
+
+  const ownerSessions = [...sessions.values()].filter((record) => recordOwner(record) === input.owner);
+  const ownerSessionById = new Map(ownerSessions.map((record) => [record.id, record]));
+  const liveOwnerIds = new Set(
+    input.liveSessions.filter((record) => recordOwner(record) === input.owner).map((record) => record.id)
+  );
+  const seen = new Set<string>();
+  const orderedSessions: TabLayoutSessionRecord[] = [];
+  for (const id of input.sessionOrder ?? []) {
+    const record = ownerSessionById.get(id);
+    if (!record || seen.has(id)) continue;
+    seen.add(id);
+    orderedSessions.push(record);
+  }
+  for (const record of ownerSessions.filter((item) => !seen.has(item.id)).sort(compareSessions)) {
+    seen.add(record.id);
+    orderedSessions.push(record);
+  }
+
+  const refs: TabRef[] = orderedSessions.map((record) => {
+    const manual = record.parentSessionId !== undefined && liveOwnerIds.has(record.parentSessionId);
+    return manual ? { kind: 'session', id: record.id, placement: 'manual' } : { kind: 'session', id: record.id };
+  });
+  for (const webview of input.webviews) {
+    if (recordOwner(webview) === input.owner) refs.push({ kind: 'webview', id: webview.id });
+  }
+
+  const layout = normalizeTabLayout(
+    {
+      version: 0,
+      groups: [],
+      ungrouped: refs,
+      updatedAt: input.updatedAt ?? new Date().toISOString(),
+    },
+    metadata
+  );
+  return { layout, layouts: { ...(input.layouts ?? {}), [input.owner]: layout }, created: true };
+}

src/tab-layout-service.ts

@@ -0,0 +1,678 @@
+/**
+ * @fileoverview Owner-scoped authoritative tab-layout coordination.
+ *
+ * This is the single mutation boundary between the pure layout model, persisted
+ * state, live sessions, saved webviews, and SSE. Lifecycle callers describe one
+ * completed server action; this service performs at most one versioned write.
+ */
+import type { StateStore } from './state-store.js';
+import { mergeSessionOrder, normalizeSessionOrder } from './session-order.js';
+import { applyLegacySessionRank, recomposeGlobalSessionOrder } from './tab-layout-legacy-order.js';
+import {
+  flattenOwnerSessionOrder,
+  materializeOrphans,
+  normalizeTabLayout,
+  TabLayoutValidationError,
+  validateTabLayout,
+  type TabLayout,
+  type TabRef,
+  type TabRefMetadata,
+} from './tab-layout.js';
+import {
+  normalizeOrMigrateOwnerTabLayout,
+  SINGLE_USER_LAYOUT_OWNER,
+  type TabLayoutSessionRecord,
+  type TabLayoutWebviewRecord,
+} from './tab-layout-persistence.js';
+import { SseEvent } from './web/sse-events.js';
+
+export interface TabLayoutSessionLike {
+  id: string;
+  owner?: string;
+  createdAt: number;
+  parentSessionId?: string;
+}
+
+interface TabLayoutServiceDeps {
+  store: Pick<
+    StateStore,
+    'getTabLayout' | 'getTabLayouts' | 'getSessions' | 'getSessionOrder' | 'commitTabLayoutProjection'
+  >;
+  sessions: ReadonlyMap<string, TabLayoutSessionLike>;
+  readWebviews(): Promise<readonly TabLayoutWebviewRecord[]>;
+  broadcast(event: string, data: unknown): void;
+  broadcastSessionOrder(change: SessionOrderProjectionChange): void;
+  now?: () => string;
+}
+
+export type TabLayoutPutResult = { status: 'updated'; layout: TabLayout } | { status: 'conflict'; layout: TabLayout };
+
+export interface LegacyOrderActor {
+  owner: string;
+  isAdmin: boolean;
+}
+
+export interface SessionOrderProjectionChange {
+  changedOwnerOrders: Record<string, string[]>;
+  globalOrder: string[];
+  globalChanged: boolean;
+}
+
+export interface LegacyOrderPutResult extends SessionOrderProjectionChange {
+  order: string[];
+}
+
+export interface RemovedTabLayoutSession {
+  id: string;
+  owner?: string;
+}
+
+interface PreparedOwnerLayout {
+  current: TabLayout | null;
+  authoritative: TabLayout;
+  metadata: TabRefMetadata[];
+  needsReconciliationCommit: boolean;
+}
+
+interface OwnerProjectionPublication {
+  owner: string;
+  previous: TabLayout | null;
+  next: TabLayout;
+  metadata: readonly TabRefMetadata[];
+  excludedSessionIds?: ReadonlySet<string>;
+}
+
+interface PreparedOrderProjection {
+  owner: string;
+  previousOrder: string[];
+  authoritativeBeforeIds: string[];
+  excludedIds: string[];
+  currentIds: string[];
+  order: string[];
+}
+
+const ownerOf = (record: { owner?: string }): string => record.owner ?? SINGLE_USER_LAYOUT_OWNER;
+const refKey = (ref: Pick<TabRef, 'kind' | 'id'>): string => `${ref.kind}\u0000${ref.id}`;
+const sameLayout = (a: TabLayout, b: TabLayout): boolean => JSON.stringify(a) === JSON.stringify(b);
+const sameOrder = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((id, index) => id === b[index]);
+
+export class TabLayoutService {
+  private restorationState: 'pending' | 'complete' | 'failed' | 'skipped' = 'pending';
+  private readonly ownerQueues = new Map<string, Promise<void>>();
+
+  constructor(private readonly deps: TabLayoutServiceDeps) {}
+
+  private async withOwner<T>(owner: string, task: () => Promise<T>): Promise<T> {
+    const previous = this.ownerQueues.get(owner) ?? Promise.resolve();
+    const run = previous.catch(() => undefined).then(task);
+    const tail = run.then(
+      () => undefined,
+      () => undefined
+    );
+    this.ownerQueues.set(owner, tail);
+    try {
+      return await run;
+    } finally {
+      if (this.ownerQueues.get(owner) === tail) this.ownerQueues.delete(owner);
+    }
+  }
+
+  /** Acquire multiple owner queues in stable order so overlapping bulk cleanups cannot deadlock. */
+  private async withOwners<T>(owners: readonly string[], task: () => Promise<T>, index = 0): Promise<T> {
+    if (index >= owners.length) return task();
+    return this.withOwner(owners[index], () => this.withOwners(owners, task, index + 1));
+  }
+
+  markRestorationComplete(): void {
+    this.restorationState = 'complete';
+  }
+
+  markRestorationFailed(): void {
+    this.restorationState = 'failed';
+  }
+
+  markRestorationSkipped(): void {
+    this.restorationState = 'skipped';
+  }
+
+  assertDeletionReady(): void {
+    if (this.restorationState === 'complete' || this.restorationState === 'skipped') return;
+    throw new Error(`Tab layout restoration is ${this.restorationState}; destructive deletion is unavailable`);
+  }
+
+  /** Repair/migrate every owner visible after startup restoration. */
+  async reconcileAfterRestoration(): Promise<void> {
+    if (this.restorationState !== 'complete') return;
+    const { persisted, live } = this.sessionRecords();
+    const webviews = await this.deps.readWebviews();
+    const owners = new Set<string>();
+    for (const record of [...persisted, ...live, ...webviews]) owners.add(ownerOf(record));
+    for (const owner of owners) await this.get(owner);
+  }
+
+  private sessionRecords(): { persisted: TabLayoutSessionRecord[]; live: TabLayoutSessionRecord[] } {
+    const persisted = Object.entries(this.deps.store.getSessions()).map(([id, record]) => ({
+      id,
+      owner: record.owner,
+      createdAt: record.createdAt,
+      parentSessionId: record.parentSessionId,
+    }));
+    const live = [...this.deps.sessions.values()].map((record) => ({
+      id: record.id,
+      owner: record.owner,
+      createdAt: record.createdAt,
+      parentSessionId: record.parentSessionId,
+    }));
+    return { persisted, live };
+  }
+
+  private async facts(owner: string): Promise<{
+    persisted: TabLayoutSessionRecord[];
+    live: TabLayoutSessionRecord[];
+    webviews: readonly TabLayoutWebviewRecord[];
+    metadata: TabRefMetadata[];
+  }> {
+    const { persisted, live } = this.sessionRecords();
+    const webviews = await this.deps.readWebviews();
+    const sessions = new Map<string, TabLayoutSessionRecord>();
+    for (const record of persisted) sessions.set(record.id, record);
+    for (const record of live) sessions.set(record.id, record);
+    const ownedSessions = [...sessions.values()]
+      .filter((record) => ownerOf(record) === owner)
+      .sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const sessionOrder = new Map(ownedSessions.map((record, index) => [record.id, index]));
+    const metadata: TabRefMetadata[] = [...sessions.values()].map((record) => ({
+      kind: 'session',
+      id: record.id,
+      ownerValid: ownerOf(record) === owner,
+      visible: true,
+      order: sessionOrder.get(record.id) ?? record.createdAt,
+      parentSessionId: record.parentSessionId,
+    }));
+    const offset = ownedSessions.length;
+    webviews.forEach((record, index) =>
+      metadata.push({
+        kind: 'webview',
+        id: record.id,
+        ownerValid: ownerOf(record) === owner,
+        visible: true,
+        order: offset + index,
+      })
+    );
+    return { persisted, live, webviews, metadata };
+  }
+
+  private prepareCommit(base: TabLayout, next: TabLayout): TabLayout {
+    return validateTabLayout({
+      ...next,
+      version: base.version + 1,
+      updatedAt: (this.deps.now ?? (() => new Date().toISOString()))(),
+    });
+  }
+
+  private prepareOrderProjection(item: OwnerProjectionPublication): PreparedOrderProjection {
+    const excluded = item.excludedSessionIds ?? new Set<string>();
+    const authoritativeBeforeIds = item.metadata
+      .filter((fact) => fact.kind === 'session' && fact.ownerValid && fact.visible)
+      .map((fact) => fact.id);
+    const facts = authoritativeBeforeIds.filter((id) => !excluded.has(id));
+    const visible = new Set(facts);
+    const rawPrevious = item.previous ? flattenOwnerSessionOrder(item.previous) : [];
+    const rawNext = flattenOwnerSessionOrder(item.next);
+    const previousOrder = rawPrevious.filter((id) => visible.has(id) || excluded.has(id));
+    const order = rawNext.filter((id) => visible.has(id) && !excluded.has(id));
+    const excludedIds = normalizeSessionOrder([...excluded]);
+    return {
+      owner: item.owner,
+      previousOrder,
+      authoritativeBeforeIds: normalizeSessionOrder([...authoritativeBeforeIds, ...excluded]),
+      excludedIds,
+      currentIds: normalizeSessionOrder([...order, ...facts]),
+      order,
+    };
+  }
+
+  private projectOrder(
+    latest: readonly string[],
+    projections: readonly PreparedOrderProjection[],
+    preferred?: readonly string[]
+  ): string[] {
+    const before = normalizeSessionOrder(latest);
+    const removed = new Set(
+      projections.flatMap((projection) => projection.excludedIds.filter((id) => !projection.currentIds.includes(id)))
+    );
+    return recomposeGlobalSessionOrder(
+      before.filter((id) => !removed.has(id)),
+      projections.map((projection) => ({
+        owner: projection.owner,
+        ownedIds: projection.currentIds,
+        order: projection.order,
+      })),
+      preferred
+    );
+  }
+
+  private publish(
+    layouts: Readonly<Record<string, TabLayout>>,
+    publications: readonly OwnerProjectionPublication[],
+    preferred?: readonly string[]
+  ): SessionOrderProjectionChange {
+    const projections = publications.map((item) => this.prepareOrderProjection(item));
+    let beforeOrder: string[] = [];
+    const accepted = this.deps.store.commitTabLayoutProjection(layouts, (latest) => {
+      beforeOrder = normalizeSessionOrder(latest);
+      return this.projectOrder(beforeOrder, projections, preferred);
+    });
+    const changedEntries: Array<[string, string[]]> = [];
+    for (const projection of projections) {
+      const beforeIds = new Set(projection.authoritativeBeforeIds);
+      const currentIds = new Set(projection.currentIds);
+      const persistedBefore = beforeOrder.filter((id) => beforeIds.has(id));
+      const persistedAfter = accepted.sessionOrder.filter((id) => currentIds.has(id));
+      const layoutOrderChanged = !sameOrder(projection.previousOrder, projection.order);
+      const persistedOwnerSliceChanged = !sameOrder(persistedBefore, persistedAfter);
+      if (layoutOrderChanged || persistedOwnerSliceChanged) {
+        changedEntries.push([projection.owner, persistedAfter]);
+      }
+    }
+    const change: SessionOrderProjectionChange = {
+      changedOwnerOrders: Object.fromEntries(changedEntries),
+      globalOrder: [...accepted.sessionOrder],
+      globalChanged: !sameOrder(beforeOrder, accepted.sessionOrder),
+    };
+    for (const [owner, layout] of Object.entries(accepted.layouts)) {
+      this.deps.broadcast(SseEvent.TabLayoutChanged, { owner, version: layout.version });
+    }
+    if (changedEntries.length > 0 || change.globalChanged) this.deps.broadcastSessionOrder(change);
+    return change;
+  }
+
+  private commit(
+    owner: string,
+    base: TabLayout,
+    next: TabLayout,
+    metadata: readonly TabRefMetadata[],
+    previous: TabLayout | null = base.version < 0 ? null : base
+  ): TabLayout {
+    const stored = this.prepareCommit(base, next);
+    this.publish({ [owner]: stored }, [{ owner, previous, next: stored, metadata }]);
+    return stored;
+  }
+
+  private async prepareUnlocked(owner: string): Promise<PreparedOwnerLayout> {
+    const facts = await this.facts(owner);
+    const current = this.deps.store.getTabLayout(owner);
+    const authoritative = normalizeOrMigrateOwnerTabLayout({
+      owner,
+      layouts: current ? { [owner]: current } : undefined,
+      sessionOrder: this.deps.store.getSessionOrder(),
+      persistedSessions: facts.persisted,
+      liveSessions: facts.live,
+      webviews: facts.webviews,
+      updatedAt: (this.deps.now ?? (() => new Date().toISOString()))(),
+    }).layout;
+    return {
+      current,
+      authoritative,
+      metadata: facts.metadata,
+      needsReconciliationCommit: !current || !sameLayout(current, authoritative),
+    };
+  }
+
+  private async getUnlocked(owner: string): Promise<TabLayout> {
+    const prepared = await this.prepareUnlocked(owner);
+    if (!prepared.needsReconciliationCommit) {
+      const publication = {
+        owner,
+        previous: prepared.current,
+        next: prepared.authoritative,
+        metadata: prepared.metadata,
+      };
+      const latest = this.deps.store.getSessionOrder();
+      const projected = this.projectOrder(latest, [this.prepareOrderProjection(publication)]);
+      if (!sameOrder(normalizeSessionOrder(latest), projected)) this.publish({}, [publication]);
+      return prepared.authoritative;
+    }
+    const base = prepared.current ?? { ...prepared.authoritative, version: -1 };
+    return this.commit(owner, base, prepared.authoritative, prepared.metadata);
+  }
+
+  async get(owner: string): Promise<TabLayout> {
+    return this.withOwner(owner, () => this.getUnlocked(owner));
+  }
+
+  async put(owner: string, desired: unknown, baseVersion: number): Promise<TabLayoutPutResult> {
+    return this.withOwner(owner, async () => {
+      const prepared = await this.prepareUnlocked(owner);
+      if (baseVersion !== prepared.authoritative.version) return { status: 'conflict', layout: prepared.authoritative };
+      const validated = validateTabLayout(desired);
+      const owned = new Set(prepared.metadata.filter((item) => item.ownerValid && item.visible).map(refKey));
+      const refs = [...validated.groups.flatMap((group) => group.refs), ...validated.ungrouped];
+      const invalid = refs.find((ref) => !owned.has(refKey(ref)));
+      if (invalid)
+        throw new TabLayoutValidationError(`ref is not owned by layout owner: ${invalid.kind}:${invalid.id}`);
+      const normalized = normalizeTabLayout(
+        { ...validated, version: prepared.authoritative.version },
+        prepared.metadata
+      );
+      return {
+        status: 'updated',
+        layout: this.commit(owner, prepared.authoritative, normalized, prepared.metadata, prepared.current),
+      };
+    });
+  }
+
+  async putLegacyOrder(actor: LegacyOrderActor, requested: readonly string[]): Promise<LegacyOrderPutResult> {
+    return actor.isAdmin ? this.putAdminLegacyOrder(requested) : this.putOwnerLegacyOrder(actor.owner, requested);
+  }
+
+  private async putOwnerLegacyOrder(owner: string, requested: readonly string[]): Promise<LegacyOrderPutResult> {
+    return this.withOwner(owner, async () => {
+      const prepared = await this.prepareUnlocked(owner);
+      const normalized = normalizeSessionOrder(requested);
+      const visible = new Set(
+        prepared.metadata
+          .filter((item) => item.kind === 'session' && item.ownerValid && item.visible)
+          .map((item) => item.id)
+      );
+      // Unknown or foreign ids are DROPPED, never a 400: the browser debounces
+      // its reorder push (and swallows errors), so a session deleted inside
+      // that window would otherwise cost the user the whole reorder — and the
+      // endpoint sits on the stable /api/v1 surface, where the pre-layout
+      // server merged leniently. Same philosophy as resolveParentSessionId.
+      const requestedVisible = normalized.filter((id) => visible.has(id));
+      const currentKnown = flattenOwnerSessionOrder(prepared.authoritative).filter((id) => visible.has(id));
+      const effective = mergeSessionOrder(requestedVisible, currentKnown);
+      const ranked = applyLegacySessionRank(prepared.authoritative, effective, prepared.metadata);
+      const needsLayout = prepared.needsReconciliationCommit || !sameLayout(prepared.authoritative, ranked);
+      const base = prepared.current ?? { ...prepared.authoritative, version: -1 };
+      const next = needsLayout ? this.prepareCommit(base, ranked) : prepared.authoritative;
+      const change = this.publish(needsLayout ? { [owner]: next } : {}, [
+        { owner, previous: prepared.current, next, metadata: prepared.metadata },
+      ]);
+      return { order: flattenOwnerSessionOrder(next).filter((id) => visible.has(id)), ...change };
+    });
+  }
+
+  private async putAdminLegacyOrder(requested: readonly string[]): Promise<LegacyOrderPutResult> {
+    const discoverOwners = (): string[] => {
+      const owners = new Set(Object.keys(this.deps.store.getTabLayouts()));
+      const { persisted, live } = this.sessionRecords();
+      for (const record of [...persisted, ...live]) owners.add(ownerOf(record));
+      return [...owners].sort();
+    };
+    for (;;) {
+      const owners = discoverOwners();
+      const result = await this.withOwners(owners, async (): Promise<LegacyOrderPutResult | null> => {
+        if (!sameOrder(owners, discoverOwners())) return null;
+        const normalized = normalizeSessionOrder(requested);
+        const knownOwners = new Map<string, string>();
+        const { persisted, live } = this.sessionRecords();
+        for (const record of persisted) knownOwners.set(record.id, ownerOf(record));
+        for (const record of live) knownOwners.set(record.id, ownerOf(record));
+        // Unknown ids are DROPPED, never a 400 — see putOwnerLegacyOrder. In
+        // single-user mode every request is the synthetic admin, so this path
+        // IS the one the browser's debounced (error-swallowing) push hits.
+        const known = normalized.filter((id) => knownOwners.has(id));
+
+        const publications: OwnerProjectionPublication[] = [];
+        const updates: Record<string, TabLayout> = Object.create(null) as Record<string, TabLayout>;
+        for (const owner of owners) {
+          const prepared = await this.prepareUnlocked(owner);
+          const visible = new Set(
+            prepared.metadata
+              .filter((item) => item.kind === 'session' && item.ownerValid && item.visible)
+              .map((item) => item.id)
+          );
+          const requestedOwner = known.filter((id) => visible.has(id));
+          const currentKnown = flattenOwnerSessionOrder(prepared.authoritative).filter((id) => visible.has(id));
+          const effective = mergeSessionOrder(requestedOwner, currentKnown);
+          const ranked = applyLegacySessionRank(prepared.authoritative, effective, prepared.metadata);
+          const needsLayout = prepared.needsReconciliationCommit || !sameLayout(prepared.authoritative, ranked);
+          const base = prepared.current ?? { ...prepared.authoritative, version: -1 };
+          const next = needsLayout ? this.prepareCommit(base, ranked) : prepared.authoritative;
+          if (needsLayout) updates[owner] = next;
+          publications.push({ owner, previous: prepared.current, next, metadata: prepared.metadata });
+        }
+        const change = this.publish(updates, publications, known);
+        return { order: [...change.globalOrder], ...change };
+      });
+      if (result) return result;
+    }
+  }
+
+  /** Reconcile one completed session creation into one versioned mutation. */
+  async sessionCreated(owner: string): Promise<TabLayout> {
+    return this.get(owner);
+  }
+
+  /** Reconcile one completed saved-webview creation into one versioned mutation. */
+  async webviewCreated(owner: string): Promise<TabLayout> {
+    return this.get(owner);
+  }
+
+  async sessionsRemoved(removed: readonly RemovedTabLayoutSession[]): Promise<void> {
+    if (this.restorationState !== 'complete' || removed.length === 0) return;
+    const byOwner = new Map<string, string[]>();
+    for (const item of removed) {
+      const owner = ownerOf(item);
+      const ids = byOwner.get(owner) ?? [];
+      ids.push(item.id);
+      byOwner.set(owner, ids);
+    }
+    const owners = [...byOwner.keys()].sort();
+    await this.withOwners(owners, async () => {
+      const publications: OwnerProjectionPublication[] = [];
+      const updates: Record<string, TabLayout> = Object.create(null) as Record<string, TabLayout>;
+      for (const owner of owners) {
+        const ids = byOwner.get(owner) ?? [];
+        const prepared = await this.prepareUnlocked(owner);
+        const current = prepared.current;
+        // Normalize and prune together so stale cleanup, orphan materialization,
+        // and missing-ref repair remain one versioned server mutation.
+        const next = normalizeTabLayout(
+          materializeOrphans(prepared.authoritative, ids, prepared.metadata),
+          prepared.metadata
+        );
+        const stored = current && !sameLayout(current, next) ? this.prepareCommit(current, next) : null;
+        if (stored) updates[owner] = stored;
+        publications.push({
+          owner,
+          previous: current,
+          next: stored ?? next,
+          metadata: prepared.metadata,
+          excludedSessionIds: new Set(ids),
+        });
+      }
+      if (publications.length > 0) this.publish(updates, publications);
+    });
+  }
+
+  /**
+   * Hold the owner mutation lock across an irreversible session deletion.
+   * All failure-prone normalization happens before `action`; the prepared layout
+   * commits only after the resource cleanup finishes.
+   */
+  async runSessionDeletion<T>(removed: readonly RemovedTabLayoutSession[], action: () => Promise<T>): Promise<T> {
+    // A failed restoration must not lock the user out of explicitly closing a
+    // tab for the rest of the process lifetime: degrade to best-effort deletion
+    // without layout coordination. Only the AUTOMATED stale sweep stays
+    // fail-closed on 'failed' (runStaleSessionCleanup), because that one picks
+    // its victims itself from state a failed restore may have left incomplete.
+    if (this.restorationState === 'failed') return action();
+    this.assertDeletionReady();
+    if (this.restorationState === 'skipped' || removed.length === 0) return action();
+    const owners = new Set(removed.map(ownerOf));
+    if (owners.size !== 1) throw new Error('A session deletion transaction must contain exactly one owner');
+    const owner = owners.values().next().value as string;
+    const ids = removed.map((item) => item.id);
+    return this.withOwner(owner, async () => {
+      const prepared = await this.prepareUnlocked(owner);
+      const current = prepared.current;
+      // Prepare while the soon-to-be-deleted sessions are still known, so
+      // direct children can be materialized before their parent ref is removed.
+      const next = materializeOrphans(prepared.authoritative, ids, prepared.metadata);
+      const stored = current && !sameLayout(current, next) ? this.prepareCommit(current, next) : null;
+      const result = await action();
+      this.publish(stored ? { [owner]: stored } : {}, [
+        {
+          owner,
+          previous: current,
+          next: stored ?? next,
+          metadata: prepared.metadata,
+          excludedSessionIds: new Set(ids),
+        },
+      ]);
+      return result;
+    });
+  }
+
+  /**
+   * Prepare every affected owner layout before bulk stale-state deletion.
+   * The StateStore action remains synchronous in production, so the candidate
+   * snapshot cannot change between successful preparation and resource removal.
+   */
+  async runStaleSessionCleanup<T>(
+    activeSessionIds: ReadonlySet<string>,
+    action: (ids: ReadonlySet<string>) => T | Promise<T>
+  ): Promise<T> {
+    this.assertDeletionReady();
+    const candidates = Object.entries(this.deps.store.getSessions())
+      .filter(([id, record]) => !activeSessionIds.has(id) && record.pinned !== true)
+      .map(([id, record]) => ({ id, owner: record.owner }));
+    if (this.restorationState === 'skipped') return action(new Set(candidates.map((item) => item.id)));
+    if (candidates.length === 0) return action(new Set());
+
+    const byOwner = new Map<string, string[]>();
+    for (const item of candidates) {
+      const owner = ownerOf(item);
+      const ids = byOwner.get(owner) ?? [];
+      ids.push(item.id);
+      byOwner.set(owner, ids);
+    }
+    const owners = [...byOwner.keys()].sort();
+    return this.withOwners(owners, async () => {
+      const webviews = await this.deps.readWebviews();
+      const persistedState = this.deps.store.getSessions();
+      const persisted = Object.entries(persistedState).map(([id, record]) => ({
+        id,
+        owner: record.owner,
+        createdAt: record.createdAt,
+        parentSessionId: record.parentSessionId,
+      }));
+      const liveIds = new Set(this.deps.sessions.keys());
+      const confirmed = candidates.filter((candidate) => {
+        const record = persistedState[candidate.id];
+        return (
+          record !== undefined &&
+          ownerOf(record) === ownerOf(candidate) &&
+          record.pinned !== true &&
+          !activeSessionIds.has(candidate.id) &&
+          !liveIds.has(candidate.id)
+        );
+      });
+      const confirmedByOwner = new Map<string, string[]>();
+      for (const item of confirmed) {
+        const owner = ownerOf(item);
+        const ids = confirmedByOwner.get(owner) ?? [];
+        ids.push(item.id);
+        confirmedByOwner.set(owner, ids);
+      }
+
+      const prepared: Array<{
+        owner: string;
+        current: TabLayout | null;
+        next: TabLayout;
+        stored: TabLayout | null;
+        metadata: TabRefMetadata[];
+        excludedSessionIds: ReadonlySet<string>;
+      }> = [];
+      for (const owner of owners) {
+        const ids = confirmedByOwner.get(owner) ?? [];
+        if (ids.length === 0) continue;
+        const current = this.deps.store.getTabLayout(owner);
+        const sessions = new Map<string, TabLayoutSessionRecord>();
+        for (const record of persisted) sessions.set(record.id, record);
+        for (const record of this.deps.sessions.values()) sessions.set(record.id, record);
+        const ownedSessions = [...sessions.values()]
+          .filter((record) => ownerOf(record) === owner)
+          .sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        const sessionOrder = new Map(ownedSessions.map((record, index) => [record.id, index]));
+        const metadata: TabRefMetadata[] = [...sessions.values()].map((record) => ({
+          kind: 'session',
+          id: record.id,
+          ownerValid: ownerOf(record) === owner,
+          visible: true,
+          order: sessionOrder.get(record.id) ?? record.createdAt,
+          parentSessionId: record.parentSessionId,
+        }));
+        const offset = ownedSessions.length;
+        webviews.forEach((record, index) =>
+          metadata.push({
+            kind: 'webview',
+            id: record.id,
+            ownerValid: ownerOf(record) === owner,
+            visible: true,
+            order: offset + index,
+          })
+        );
+        const authoritative = normalizeOrMigrateOwnerTabLayout({
+          owner,
+          layouts: current ? { [owner]: current } : undefined,
+          sessionOrder: this.deps.store.getSessionOrder(),
+          persistedSessions: persisted,
+          liveSessions: [...this.deps.sessions.values()],
+          webviews,
+          updatedAt: (this.deps.now ?? (() => new Date().toISOString()))(),
+        }).layout;
+        const next = materializeOrphans(authoritative, ids, metadata);
+        prepared.push({
+          owner,
+          current,
+          next,
+          stored: current && !sameLayout(current, next) ? this.prepareCommit(current, next) : null,
+          metadata,
+          excludedSessionIds: new Set(ids),
+        });
+      }
+
+      const result = await action(new Set(confirmed.map((item) => item.id)));
+      if (prepared.length > 0) {
+        this.publish(
+          Object.fromEntries(prepared.filter((item) => item.stored).map((item) => [item.owner, item.stored!])),
+          prepared.map((item) => ({
+            owner: item.owner,
+            previous: item.current,
+            next: item.stored ?? item.next,
+            metadata: item.metadata,
+            excludedSessionIds: item.excludedSessionIds,
+          }))
+        );
+      }
+      return result;
+    });
+  }
+
+  async webviewDeleted(owner: string, id: string): Promise<void> {
+    // Same explicit-user-action escape hatch as runSessionDeletion: a failed
+    // restore skips layout coordination instead of failing the delete.
+    if (this.restorationState === 'failed') return;
+    this.assertDeletionReady();
+    if (this.restorationState === 'skipped') return;
+    await this.withOwner(owner, async () => {
+      const current = this.deps.store.getTabLayout(owner);
+      if (!current) return;
+      const strip = (refs: readonly TabRef[]): TabRef[] =>
+        refs.filter((ref) => ref.kind !== 'webview' || ref.id !== id).map((ref) => ({ ...ref }));
+      const stripped: TabLayout = {
+        ...current,
+        groups: current.groups.map((group) => ({ ...group, refs: strip(group.refs) })),
+        ungrouped: strip(current.ungrouped),
+      };
+      const { metadata } = await this.facts(owner);
+      const next = normalizeTabLayout(stripped, metadata);
+      if (!sameLayout(current, next)) this.commit(owner, current, next, metadata);
+    });
+  }
+}

src/tab-layout.ts

@@ -0,0 +1,547 @@
+/**
+ * @fileoverview Framework-independent tab layout model.
+ *
+ * Callers provide owner-scoped session/webview metadata. This module deliberately
+ * has no dependency on session runtime, persistence, routes, or browser state.
+ */
+
+export const MAX_TAB_GROUPS = 32;
+export const MAX_TAB_GROUP_NAME_LENGTH = 60;
+export const MAX_TAB_REFS = 512;
+
+export type TabRefKind = 'session' | 'webview';
+
+export interface TabRef {
+  kind: TabRefKind;
+  id: string;
+  placement?: 'manual';
+}
+
+export interface TabGroup {
+  id: string;
+  name: string;
+  refs: TabRef[];
+}
+
+export interface TabLayout {
+  version: number;
+  groups: TabGroup[];
+  ungrouped: TabRef[];
+  updatedAt: string;
+}
+
+/** Owner and lineage facts supplied by the server or browser integration. */
+export interface TabRefMetadata {
+  kind: TabRefKind;
+  id: string;
+  /** False for missing, foreign-owned, or otherwise invalid refs. */
+  ownerValid: boolean;
+  /** False when the owner is not permitted to see/store this ref. */
+  visible: boolean;
+  /** Stable creation/sibling order. Ties fall back to kind and id. */
+  order: number;
+  /** Session-only lineage hint. Ignored for webviews. */
+  parentSessionId?: string;
+}
+
+export interface TabMoveTarget {
+  /** Null denotes the real ungrouped container. */
+  groupId: string | null;
+  /** Zero-based insertion index after removing the moved block. */
+  index: number;
+}
+
+export interface CreateTabGroupInput {
+  id: string;
+  name: string;
+  index?: number;
+}
+
+export interface VisibleTabProjectionOptions {
+  liveSessionIds: ReadonlySet<string>;
+  openWebviewIds: ReadonlySet<string>;
+  collapsedGroupIds?: ReadonlySet<string>;
+  highlighted?: TabRef;
+}
+
+export class TabLayoutValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TabLayoutValidationError';
+  }
+}
+
+const keyOf = (ref: Pick<TabRef, 'kind' | 'id'>): string => `${ref.kind}\u0000${ref.id}`;
+
+function assertRecord(value: unknown, label: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TabLayoutValidationError(`${label} must be an object`);
+  }
+}
+
+function parseNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TabLayoutValidationError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function parseName(value: unknown, label: string): string {
+  if (typeof value !== 'string') throw new TabLayoutValidationError(`${label} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_TAB_GROUP_NAME_LENGTH) {
+    throw new TabLayoutValidationError(`${label} must be 1-${MAX_TAB_GROUP_NAME_LENGTH} trimmed characters`);
+  }
+  return trimmed;
+}
+
+function parseRef(value: unknown, label: string): TabRef {
+  assertRecord(value, label);
+  if (value.kind !== 'session' && value.kind !== 'webview') {
+    throw new TabLayoutValidationError(`${label}.kind must be session or webview`);
+  }
+  const id = parseNonEmptyString(value.id, `${label}.id`);
+  if (value.placement !== undefined && value.placement !== 'manual') {
+    throw new TabLayoutValidationError(`${label}.placement must be manual when present`);
+  }
+  return value.placement === 'manual' ? { kind: value.kind, id, placement: 'manual' } : { kind: value.kind, id };
+}
+
+function parseTabLayout(input: unknown, repairDuplicates: boolean): TabLayout {
+  assertRecord(input, 'layout');
+  if (!Number.isSafeInteger(input.version) || (input.version as number) < 0) {
+    throw new TabLayoutValidationError('layout.version must be a non-negative safe integer');
+  }
+  if (!Array.isArray(input.groups)) throw new TabLayoutValidationError('layout.groups must be an array');
+  if (input.groups.length > MAX_TAB_GROUPS) {
+    throw new TabLayoutValidationError(`layout.groups cannot exceed ${MAX_TAB_GROUPS}`);
+  }
+  if (!Array.isArray(input.ungrouped)) throw new TabLayoutValidationError('layout.ungrouped must be an array');
+  const updatedAt = parseNonEmptyString(input.updatedAt, 'layout.updatedAt');
+  const groupIds = new Set<string>();
+  const refKeys = new Set<string>();
+  let refCount = input.ungrouped.length;
+  const parseStoredRef = (entry: unknown, label: string): TabRef => {
+    const ref = parseRef(entry, label);
+    const key = keyOf(ref);
+    if (!repairDuplicates && refKeys.has(key)) {
+      throw new TabLayoutValidationError(`duplicate ref: ${ref.kind}:${ref.id}`);
+    }
+    refKeys.add(key);
+    return ref;
+  };
+  const groups = input.groups.map((rawGroup, groupIndex): TabGroup => {
+    const label = `layout.groups[${groupIndex}]`;
+    assertRecord(rawGroup, label);
+    const id = parseNonEmptyString(rawGroup.id, `${label}.id`);
+    if (groupIds.has(id)) throw new TabLayoutValidationError(`duplicate group id: ${id}`);
+    groupIds.add(id);
+    if (!Array.isArray(rawGroup.refs)) throw new TabLayoutValidationError(`${label}.refs must be an array`);
+    refCount += rawGroup.refs.length;
+    return {
+      id,
+      name: parseName(rawGroup.name, `${label}.name`),
+      refs: rawGroup.refs.map((entry, refIndex) => parseStoredRef(entry, `${label}.refs[${refIndex}]`)),
+    };
+  });
+  if (refCount > MAX_TAB_REFS) {
+    throw new TabLayoutValidationError(`layout cannot contain more than ${MAX_TAB_REFS} refs`);
+  }
+  return {
+    version: input.version as number,
+    groups,
+    ungrouped: input.ungrouped.map((entry, index) => parseStoredRef(entry, `layout.ungrouped[${index}]`)),
+    updatedAt,
+  };
+}
+
+/** Validate and defensively clone a layout. Group names are normalized by trimming. */
+export function validateTabLayout(input: unknown): TabLayout {
+  return parseTabLayout(input, false);
+}
+
+function validMetadata(metadata: readonly TabRefMetadata[]): TabRefMetadata[] {
+  const byKey = new Map<string, TabRefMetadata>();
+  for (const item of metadata) {
+    if ((item.kind !== 'session' && item.kind !== 'webview') || typeof item.id !== 'string' || item.id.length === 0) {
+      throw new TabLayoutValidationError('metadata contains an invalid ref identity');
+    }
+    if (!Number.isFinite(item.order)) throw new TabLayoutValidationError(`metadata order is invalid for ${item.id}`);
+    if (!item.ownerValid || !item.visible) continue;
+    const key = keyOf(item);
+    if (!byKey.has(key)) byKey.set(key, { ...item });
+  }
+  const compareText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  const result = [...byKey.values()].sort(
+    (a, b) => a.order - b.order || compareText(a.kind, b.kind) || compareText(a.id, b.id)
+  );
+  if (result.length > MAX_TAB_REFS) {
+    throw new TabLayoutValidationError(`owner layout cannot exceed ${MAX_TAB_REFS} refs`);
+  }
+  return result;
+}
+
+interface LocatedRef {
+  ref: TabRef;
+  container: string | null;
+  position: number;
+}
+
+function locations(layout: TabLayout): LocatedRef[] {
+  const result: LocatedRef[] = [];
+  let position = 0;
+  for (const group of layout.groups) {
+    for (const ref of group.refs) result.push({ ref, container: group.id, position: position++ });
+  }
+  for (const ref of layout.ungrouped) result.push({ ref, container: null, position: position++ });
+  return result;
+}
+
+function withContainers(layout: TabLayout, refsByContainer: ReadonlyMap<string | null, TabRef[]>): TabLayout {
+  return {
+    ...layout,
+    groups: layout.groups.map((group) => ({ ...group, refs: [...(refsByContainer.get(group.id) ?? [])] })),
+    ungrouped: [...(refsByContainer.get(null) ?? [])],
+  };
+}
+
+/**
+ * Reconcile a layout against owner-valid metadata and session lineage.
+ * First stored occurrence wins; missing valid refs append to ungrouped.
+ */
+export function normalizeTabLayout(input: TabLayout, metadata: readonly TabRefMetadata[]): TabLayout {
+  const layout = parseTabLayout(input, true);
+  const valid = validMetadata(metadata);
+  const metadataByKey = new Map(valid.map((item) => [keyOf(item), item]));
+  const knownMetadataKeys = new Set(metadata.map((item) => keyOf(item)));
+  const seen = new Set<string>();
+  const dedupedByContainer = new Map<string | null, TabRef[]>();
+  for (const group of layout.groups) dedupedByContainer.set(group.id, []);
+  dedupedByContainer.set(null, []);
+
+  for (const located of locations(layout)) {
+    const key = keyOf(located.ref);
+    // Missing metadata is unknown rather than invalid (for example, during
+    // restoration). Preserve it until an explicit invalid/deletion fact arrives.
+    if ((knownMetadataKeys.has(key) && !metadataByKey.has(key)) || seen.has(key)) continue;
+    seen.add(key);
+    dedupedByContainer.get(located.container)!.push({ ...located.ref });
+  }
+  for (const item of valid) {
+    const key = keyOf(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    dedupedByContainer.get(null)!.push({ kind: item.kind, id: item.id });
+  }
+  if (seen.size > MAX_TAB_REFS) {
+    throw new TabLayoutValidationError(`normalized layout cannot exceed ${MAX_TAB_REFS} refs`);
+  }
+
+  let working = withContainers(layout, dedupedByContainer);
+  const located = locations(working);
+  const refByKey = new Map(located.map((item) => [keyOf(item.ref), item.ref]));
+  const sessionById = new Map(valid.filter((item) => item.kind === 'session').map((item) => [item.id, item]));
+  const manualCycleEdges = new Set<string>();
+  const state = new Map<string, 'visiting' | 'done'>();
+
+  const visit = (id: string): void => {
+    if (state.get(id) === 'done') return;
+    state.set(id, 'visiting');
+    const item = sessionById.get(id);
+    const stored = refByKey.get(keyOf({ kind: 'session', id }));
+    if (item?.parentSessionId && stored?.placement !== 'manual') {
+      const parent = sessionById.get(item.parentSessionId);
+      const parentStored = refByKey.get(keyOf({ kind: 'session', id: item.parentSessionId }));
+      if (parent && parentStored) {
+        if (state.get(parent.id) === 'visiting') manualCycleEdges.add(id);
+        else visit(parent.id);
+      }
+    }
+    state.set(id, 'done');
+  };
+  for (const item of located)
+    if (item.ref.kind === 'session' && state.get(item.ref.id) === undefined) visit(item.ref.id);
+
+  if (manualCycleEdges.size > 0) {
+    working = {
+      ...working,
+      groups: working.groups.map((group) => ({
+        ...group,
+        refs: group.refs.map((ref) =>
+          ref.kind === 'session' && manualCycleEdges.has(ref.id) ? { ...ref, placement: 'manual' } : ref
+        ),
+      })),
+      ungrouped: working.ungrouped.map((ref) =>
+        ref.kind === 'session' && manualCycleEdges.has(ref.id) ? { ...ref, placement: 'manual' } : ref
+      ),
+    };
+  }
+
+  const ordered = locations(working);
+  const updatedRefByKey = new Map(ordered.map((item) => [keyOf(item.ref), item.ref]));
+  const parentOf = new Map<string, string>();
+  const children = new Map<string, string[]>();
+  for (const item of ordered) {
+    if (item.ref.kind !== 'session' || item.ref.placement === 'manual') continue;
+    const info = sessionById.get(item.ref.id);
+    const parentId = info?.parentSessionId;
+    if (!parentId || !sessionById.has(parentId) || !updatedRefByKey.has(keyOf({ kind: 'session', id: parentId })))
+      continue;
+    parentOf.set(item.ref.id, parentId);
+    const siblings = children.get(parentId) ?? [];
+    siblings.push(item.ref.id);
+    children.set(parentId, siblings);
+  }
+
+  const emitted = new Set<string>();
+  const output = new Map<string | null, TabRef[]>();
+  for (const group of working.groups) output.set(group.id, []);
+  output.set(null, []);
+  const emitSubtree = (root: TabRef, container: string | null): void => {
+    const rootKey = keyOf(root);
+    if (emitted.has(rootKey)) return;
+    emitted.add(rootKey);
+    output.get(container)!.push({ ...root });
+    if (root.kind !== 'session') return;
+    for (const childId of children.get(root.id) ?? []) {
+      const child = updatedRefByKey.get(keyOf({ kind: 'session', id: childId }));
+      if (child) emitSubtree(child, container);
+    }
+  };
+  for (const item of ordered) {
+    if (item.ref.kind === 'session' && parentOf.has(item.ref.id)) continue;
+    emitSubtree(item.ref, item.container);
+  }
+  return withContainers(working, output);
+}
+
+function cloneForEdit(input: TabLayout): TabLayout {
+  return validateTabLayout(input);
+}
+
+function boundedIndex(index: number, length: number, label: string): number {
+  if (!Number.isSafeInteger(index) || index < 0 || index > length) {
+    throw new TabLayoutValidationError(`${label} index must be between 0 and ${length}`);
+  }
+  return index;
+}
+
+export function createGroup(input: TabLayout, group: CreateTabGroupInput): TabLayout {
+  const layout = cloneForEdit(input);
+  if (layout.groups.length >= MAX_TAB_GROUPS)
+    throw new TabLayoutValidationError(`cannot exceed ${MAX_TAB_GROUPS} groups`);
+  const id = parseNonEmptyString(group.id, 'group.id');
+  if (layout.groups.some((entry) => entry.id === id)) throw new TabLayoutValidationError(`duplicate group id: ${id}`);
+  const index = boundedIndex(group.index ?? layout.groups.length, layout.groups.length, 'group');
+  const groups = [...layout.groups];
+  groups.splice(index, 0, { id, name: parseName(group.name, 'group.name'), refs: [] });
+  return { ...layout, groups };
+}
+
+export function renameGroup(input: TabLayout, groupId: string, name: string): TabLayout {
+  const layout = cloneForEdit(input);
+  if (!layout.groups.some((group) => group.id === groupId))
+    throw new TabLayoutValidationError(`unknown group: ${groupId}`);
+  return {
+    ...layout,
+    groups: layout.groups.map((group) =>
+      group.id === groupId ? { ...group, name: parseName(name, 'group.name') } : group
+    ),
+  };
+}
+
+export function deleteGroup(input: TabLayout, groupId: string): TabLayout {
+  const layout = cloneForEdit(input);
+  const group = layout.groups.find((entry) => entry.id === groupId);
+  if (!group) throw new TabLayoutValidationError(`unknown group: ${groupId}`);
+  return {
+    ...layout,
+    groups: layout.groups.filter((entry) => entry.id !== groupId),
+    ungrouped: [...layout.ungrouped, ...group.refs.map((ref) => ({ ...ref }))],
+  };
+}
+
+export function reorderGroup(input: TabLayout, groupId: string, index: number): TabLayout {
+  const layout = cloneForEdit(input);
+  const from = layout.groups.findIndex((group) => group.id === groupId);
+  if (from < 0) throw new TabLayoutValidationError(`unknown group: ${groupId}`);
+  const groups = [...layout.groups];
+  const [group] = groups.splice(from, 1);
+  groups.splice(boundedIndex(index, groups.length, 'group'), 0, group);
+  return { ...layout, groups };
+}
+
+function mapRef(input: TabLayout, target: TabRef, transform: (ref: TabRef) => TabRef): TabLayout {
+  const layout = cloneForEdit(input);
+  let found = false;
+  const apply = (ref: TabRef): TabRef => {
+    if (keyOf(ref) !== keyOf(target)) return ref;
+    found = true;
+    return transform(ref);
+  };
+  const result = {
+    ...layout,
+    groups: layout.groups.map((group) => ({ ...group, refs: group.refs.map(apply) })),
+    ungrouped: layout.ungrouped.map(apply),
+  };
+  if (!found) throw new TabLayoutValidationError(`unknown ref: ${target.kind}:${target.id}`);
+  return result;
+}
+
+export function setManualPlacement(input: TabLayout, target: TabRef, manual: boolean): TabLayout {
+  if (!manual) {
+    throw new TabLayoutValidationError('manual placement can only be cleared through followParent');
+  }
+  return mapRef(input, target, (ref) => ({ ...ref, placement: 'manual' }));
+}
+
+export function followParent(input: TabLayout, target: TabRef, metadata: readonly TabRefMetadata[]): TabLayout {
+  const normalized = normalizeTabLayout(input, metadata);
+  if (target.kind !== 'session') {
+    throw new TabLayoutValidationError('only a session ref can follow a parent');
+  }
+
+  const valid = validMetadata(metadata);
+  const targetMetadata = valid.find((item) => item.kind === 'session' && item.id === target.id);
+  if (!targetMetadata?.parentSessionId) {
+    throw new TabLayoutValidationError(`session has no owner-valid parent: ${target.id}`);
+  }
+  const parentMetadata = valid.find((item) => item.kind === 'session' && item.id === targetMetadata.parentSessionId);
+  if (!parentMetadata) {
+    throw new TabLayoutValidationError(`session parent is not owner-valid: ${targetMetadata.parentSessionId}`);
+  }
+
+  const storedKeys = new Set(locations(normalized).map((item) => keyOf(item.ref)));
+  if (!storedKeys.has(keyOf(target))) {
+    throw new TabLayoutValidationError(`unknown ref: ${target.kind}:${target.id}`);
+  }
+  const parentRef: TabRef = { kind: 'session', id: targetMetadata.parentSessionId };
+  if (!storedKeys.has(keyOf(parentRef))) {
+    throw new TabLayoutValidationError(`session parent is not represented: ${targetMetadata.parentSessionId}`);
+  }
+
+  const cleared = mapRef(normalized, target, (ref) => ({ kind: ref.kind, id: ref.id }));
+  return normalizeTabLayout(cleared, metadata);
+}
+
+function descendantKeys(root: TabRef, layout: TabLayout, metadata: readonly TabRefMetadata[]): Set<string> {
+  const valid = validMetadata(metadata);
+  const stored = new Map(locations(layout).map((item) => [keyOf(item.ref), item.ref]));
+  const children = new Map<string, string[]>();
+  for (const item of valid) {
+    if (item.kind !== 'session' || !item.parentSessionId) continue;
+    const child = stored.get(keyOf(item));
+    if (!child || child.placement === 'manual' || !stored.has(keyOf({ kind: 'session', id: item.parentSessionId })))
+      continue;
+    const siblings = children.get(item.parentSessionId) ?? [];
+    siblings.push(item.id);
+    children.set(item.parentSessionId, siblings);
+  }
+  const result = new Set<string>();
+  const add = (ref: TabRef): void => {
+    const key = keyOf(ref);
+    if (result.has(key)) return;
+    result.add(key);
+    if (ref.kind !== 'session') return;
+    for (const childId of children.get(ref.id) ?? []) add({ kind: 'session', id: childId });
+  };
+  add(root);
+  return result;
+}
+
+export function moveRef(
+  input: TabLayout,
+  target: TabRef,
+  destination: TabMoveTarget,
+  metadata: readonly TabRefMetadata[]
+): TabLayout {
+  let layout = normalizeTabLayout(input, metadata);
+  const targetKey = keyOf(target);
+  if (!locations(layout).some((item) => keyOf(item.ref) === targetKey)) {
+    throw new TabLayoutValidationError(`unknown ref: ${target.kind}:${target.id}`);
+  }
+  if (destination.groupId !== null && !layout.groups.some((group) => group.id === destination.groupId)) {
+    throw new TabLayoutValidationError(`unknown group: ${destination.groupId}`);
+  }
+
+  const blockKeys = descendantKeys(target, layout, metadata);
+  const block = locations(layout)
+    .filter((item) => blockKeys.has(keyOf(item.ref)))
+    .map((item) => ({ ...item.ref }));
+  const metadataItem = validMetadata(metadata).find((item) => keyOf(item) === targetKey);
+  if (target.kind === 'session' && metadataItem?.parentSessionId) block[0] = { ...block[0], placement: 'manual' };
+
+  const remaining = new Map<string | null, TabRef[]>();
+  for (const group of layout.groups)
+    remaining.set(
+      group.id,
+      group.refs.filter((ref) => !blockKeys.has(keyOf(ref)))
+    );
+  remaining.set(
+    null,
+    layout.ungrouped.filter((ref) => !blockKeys.has(keyOf(ref)))
+  );
+  const destinationRefs = remaining.get(destination.groupId)!;
+  const index = boundedIndex(destination.index, destinationRefs.length, 'destination');
+  destinationRefs.splice(index, 0, ...block);
+  layout = withContainers(layout, remaining);
+  return normalizeTabLayout(layout, metadata);
+}
+
+/**
+ * Remove explicitly deleted session parents and pin their direct inherited
+ * children at their current stored positions so a later reused ID cannot adopt them.
+ */
+export function materializeOrphans(
+  input: TabLayout,
+  removedParentIds: readonly string[],
+  metadata: readonly TabRefMetadata[]
+): TabLayout {
+  const layout = cloneForEdit(input);
+  const removed = new Set(removedParentIds);
+  const directChildren = new Set(
+    validMetadata(metadata)
+      .filter((item) => item.kind === 'session' && item.parentSessionId && removed.has(item.parentSessionId))
+      .map((item) => item.id)
+  );
+  const transform = (refs: readonly TabRef[]): TabRef[] =>
+    refs
+      .filter((ref) => ref.kind !== 'session' || !removed.has(ref.id))
+      .map((ref) =>
+        ref.kind === 'session' && directChildren.has(ref.id) && ref.placement !== 'manual'
+          ? { ...ref, placement: 'manual' }
+          : { ...ref }
+      );
+  return {
+    ...layout,
+    groups: layout.groups.map((group) => ({ ...group, refs: transform(group.refs) })),
+    ungrouped: transform(layout.ungrouped),
+  };
+}
+
+/** Session-only compatibility order; collapse and webviews do not affect it. */
+export function flattenOwnerSessionOrder(input: TabLayout): string[] {
+  return locations(validateTabLayout(input))
+    .map((item) => item.ref)
+    .filter((ref): ref is TabRef & { kind: 'session' } => ref.kind === 'session')
+    .map((ref) => ref.id);
+}
+
+/** Locally renderable order used by tab painting and Alt-number consumers. */
+export function flattenVisibleRefs(input: TabLayout, options: VisibleTabProjectionOptions): TabRef[] {
+  const layout = validateTabLayout(input);
+  const collapsed = options.collapsedGroupIds ?? new Set<string>();
+  const renderable = (ref: TabRef): boolean =>
+    ref.kind === 'session' ? options.liveSessionIds.has(ref.id) : options.openWebviewIds.has(ref.id);
+  const highlightedKey = options.highlighted ? keyOf(options.highlighted) : undefined;
+  const result: TabRef[] = [];
+  for (const group of layout.groups) {
+    for (const ref of group.refs) {
+      if (!renderable(ref)) continue;
+      if (collapsed.has(group.id) && keyOf(ref) !== highlightedKey) continue;
+      result.push({ ...ref });
+    }
+  }
+  for (const ref of layout.ungrouped) if (renderable(ref)) result.push({ ...ref });
+  return result;
+}

src/tmux-manager.ts

@@ -52,6 +52,8 @@ import {
   type GeminiConfig,
   type AntigravityConfig,
   type PiConfig,
+  type GrokConfig,
+  type DeepSeekConfig,
   type SessionRemote,
   type SessionDocker,
   type DockerCommandMode,
@@ -92,6 +94,11 @@ import {
   getAntigravityNotFoundMessage,
   resolvePiDir,
   getPiNotFoundMessage,
+  resolveGrokDir,
+  getGrokNotFoundMessage,
+  resolveDeepSeekDir,
+  getDeepSeekNotFoundMessage,
+  resolveDefaultDeepSeekProfile,
   resolveLocalShell,
   loginShellArgs,
 } from './utils/index.js';
@@ -116,6 +123,7 @@ import {
 // ============================================================================
 
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
+import { ensureDeepSeekStatusShim } from './deepseek-status-shim.js';
 
 /** How long a cached process snapshot stays usable. */
 const PROC_SNAPSHOT_TTL_MS = 2000;
@@ -802,6 +810,92 @@ function buildPiCommand(config?: PiConfig): string {
   return parts.join(' ');
 }
 
+/**
+ * Build the Grok Build CLI (xAI `grok`) command with appropriate flags.
+ *
+ * The bypass switch is `--always-approve` ("auto-approve all tool executions",
+ * grok's `bypassPermissions` permission mode; config-level deny rules still
+ * apply on top). Absent config spawns bare `grok`, i.e. grok's own default
+ * ask-mode, which is why the multi-user clamp only needs the only-if-sent
+ * branch for grok. Flag surface verified against grok 1.0.5.
+ *
+ * `XAI_API_KEY` is deliberately never wired as a flag: secrets flow through
+ * socket-scoped `tmux setenv` (envOverrides), never the spawn command line.
+ *
+ * Like the sibling builders, every user value is regex-allowlisted and silently
+ * DROPPED on failure: the result is interpolated into a `bash -c "..."` string.
+ */
+function buildGrokCommand(config?: GrokConfig): string {
+  const parts = ['grok'];
+
+  if (config?.alwaysApprove) {
+    parts.push('--always-approve');
+  }
+
+  if (config?.model) {
+    const safeModel = /^[a-zA-Z0-9._\-/]+$/.test(config.model) ? config.model : undefined;
+    if (safeModel) parts.push('--model', safeModel);
+  }
+
+  // --resume and -c conflict; a valid explicit session id wins. Ids only:
+  // grok's --resume also accepts session TITLES, which are arbitrary user
+  // strings, so the id regex doubles as the no-titles rule here.
+  const safeSessionId =
+    config?.resumeSessionId && /^[a-zA-Z0-9._-]+$/.test(config.resumeSessionId) ? config.resumeSessionId : undefined;
+  if (safeSessionId) {
+    parts.push('--resume', safeSessionId);
+  } else if (config?.continueSession) {
+    parts.push('--continue');
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Build the DeepSeek Harness (`dsh`) command with appropriate flags.
+ *
+ * Unlike every sibling builder, the interesting decision here is not a flag but
+ * WHICH PROFILE to boot: `dsh` is a launcher over `$DSH_HOME/profiles/<name>`,
+ * and DeepSeek ships no interactive terminal profile of its own, so the agent a
+ * pane runs is always one the user installed. An absent `profile` resolves to
+ * the first pane-capable profile on the box; when there is none we still emit a
+ * bare `dsh --profile <default>` rather than inventing a name, because the
+ * availability gate in createSession() has already refused the spawn by then and
+ * this path only runs for a session that passed it.
+ *
+ * There is deliberately NO permission flag: the harness has none. The sandbox
+ * and approval rows read `DSH_PERMISSION_MODE`, exported through `tmux setenv`
+ * in buildEnvExports() so it never lands on this command line.
+ *
+ * Like the sibling builders, every user value is regex-allowlisted and silently
+ * DROPPED on failure: the result is interpolated into a `bash -c "..."` string.
+ */
+function buildDeepSeekCommand(config?: DeepSeekConfig): string {
+  const parts = ['dsh'];
+
+  // A profile name is a single path segment: it is both interpolated into the
+  // shell line and joined into a filesystem path.
+  const requested = config?.profile;
+  const safeProfile =
+    requested && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(requested)
+      ? requested
+      : (resolveDefaultDeepSeekProfile() ?? undefined);
+  if (safeProfile) parts.push('--profile', safeProfile);
+
+  // The launcher forwards everything after its own flags to the profile's app,
+  // which is where `--resume` is understood. An explicit id wins over the
+  // most-recent-session form, mirroring the sibling builders.
+  const safeSessionId =
+    config?.resumeSessionId && /^[a-zA-Z0-9._-]+$/.test(config.resumeSessionId) ? config.resumeSessionId : undefined;
+  if (safeSessionId) {
+    parts.push('--resume', safeSessionId);
+  } else if (config?.resumeSession) {
+    parts.push('--resume');
+  }
+
+  return parts.join(' ');
+}
+
 /**
  * Build the spawn command for any session mode.
  * Shared by createSession() and respawnPane() to avoid duplication.
@@ -845,6 +939,8 @@ export function buildSpawnCommand(options: {
   geminiConfig?: GeminiConfig;
   antigravityConfig?: AntigravityConfig;
   piConfig?: PiConfig;
+  grokConfig?: GrokConfig;
+  deepSeekConfig?: DeepSeekConfig;
   resumeSessionId?: string;
   effort?: EffortLevel;
   /** Codeman session name, passed to claude as `--name` (version-gated, sanitized; local spawns only). */
@@ -894,6 +990,12 @@ export function buildSpawnCommand(options: {
   if (options.mode === 'pi') {
     return buildPiCommand(options.piConfig);
   }
+  if (options.mode === 'grok') {
+    return buildGrokCommand(options.grokConfig);
+  }
+  if (options.mode === 'deepseek') {
+    return buildDeepSeekCommand(options.deepSeekConfig);
+  }
   // #208: NOT the literal '$SHELL'. This string is embedded in the `bash -c "…"`
   // argument of the respawn-pane line, which execSync runs through `/bin/sh -c`,
   // so a `$SHELL` here is expanded by the SERVER process's shell against the
@@ -1109,6 +1211,10 @@ function appendResumeFlag(modeCommand: string, mode: SessionMode, resumeId: stri
       return `${modeCommand} --conversation ${resumeId}`;
     case 'pi':
       return `${modeCommand} --session ${resumeId}`;
+    case 'grok':
+      return `${modeCommand} --resume ${resumeId}`;
+    case 'deepseek':
+      return `${modeCommand} --resume ${resumeId}`;
     default:
       return modeCommand; // shell / opencode: no resume
   }
@@ -1699,10 +1805,22 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const exports = [
       'export LANG=en_US.UTF-8',
       'export LC_ALL=en_US.UTF-8',
-      mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi'
+      mode === 'codex' ||
+      mode === 'gemini' ||
+      mode === 'antigravity' ||
+      mode === 'pi' ||
+      mode === 'grok' ||
+      mode === 'deepseek'
         ? 'export COLORTERM=truecolor'
         : 'unset COLORTERM',
-      ...(mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi' ? ['unset NO_COLOR'] : []),
+      ...(mode === 'codex' ||
+      mode === 'gemini' ||
+      mode === 'antigravity' ||
+      mode === 'pi' ||
+      mode === 'grok' ||
+      mode === 'deepseek'
+        ? ['unset NO_COLOR']
+        : []),
       // Stamp each Codex pane with a unique originator so the response-viewer
       // can locate THIS pane's rollout exactly — codex writes the value into
       // session_meta.originator of every rollout it creates. Without it,
@@ -1797,6 +1915,14 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       const dir = resolvePiDir();
       return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
     }
+    if (mode === 'grok') {
+      const dir = resolveGrokDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
+    if (mode === 'deepseek') {
+      const dir = resolveDeepSeekDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
     return { pathExport: '', dir: null };
   }
 
@@ -1827,6 +1953,65 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     setGeminiEnvVars(this.tmux(), muxName);
   }
 
+  /**
+   * Configure DeepSeek Harness environment on a tmux session.
+   *
+   * Two independent things, both via `tmux setenv` so they are inherited by the
+   * pane without appearing in `ps`:
+   *
+   * 1. `DSH_PERMISSION_MODE` — the harness's only permission input. Exported
+   *    ONLY when the caller sent one, so an absent config lands on the harness's
+   *    own `workspace-write` default (which asks) rather than on ours. That
+   *    "only if sent" shape is what the multi-user clamp relies on.
+   * 2. The `HERDR_*` triple — the supervisor contract the terminal front door
+   *    uses to report idle/working/blocked. Pointing `HERDR_BIN_PATH` at our own
+   *    generated shim is what upgrades this mode from output-stabilization
+   *    guessing to definitive hook events (see deepseek-status-shim.ts). The
+   *    pane id IS the Codeman session id, which is how the shim attributes a
+   *    report without trusting anything the agent could influence.
+   *
+   * Also forwards DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL from the server env when
+   * present, matching the codex/gemini precedent for headless auth.
+   */
+  private _configureDeepSeek(muxName: string, sessionId: string, config?: DeepSeekConfig): void {
+    const tmuxCmd = this.tmux();
+    const setenv = (key: string, value: string): void => {
+      const escaped = value.replace(/'/g, "'\\''");
+      try {
+        execSync(`${tmuxCmd} setenv -t '${muxName}' ${key} '${escaped}'`, {
+          encoding: 'utf8',
+          timeout: EXEC_TIMEOUT_MS,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch {
+        /* Non-critical */
+      }
+    };
+
+    for (const key of ['DEEPSEEK_API_KEY', 'DEEPSEEK_BASE_URL', 'DSH_HOME']) {
+      const val = process.env[key];
+      if (val) setenv(key, val);
+    }
+
+    // Enum-validated at the schema boundary; re-checked here because this value
+    // reaches a shell line, and a builder must never trust its caller.
+    if (
+      config?.permissionMode &&
+      ['read-only', 'workspace-write', 'danger-full-access'].includes(config.permissionMode)
+    ) {
+      setenv('DSH_PERMISSION_MODE', config.permissionMode);
+    }
+
+    if (config?.statusReporting !== false) {
+      const shim = ensureDeepSeekStatusShim();
+      if (shim) {
+        setenv('HERDR_ENV', '1');
+        setenv('HERDR_BIN_PATH', shim);
+        setenv('HERDR_PANE_ID', sessionId);
+      }
+    }
+  }
+
   /**
    * Creates a new tmux session wrapping Claude CLI or a shell.
    * In test mode: creates an in-memory session only (no real tmux session).
@@ -1846,6 +2031,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
       resumeSessionId,
       envOverrides,
       effort,
@@ -1906,6 +2093,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     if (mode === 'pi' && !cliDir) {
       throw new Error(getPiNotFoundMessage());
     }
+    if (mode === 'deepseek' && !cliDir) {
+      throw new Error(getDeepSeekNotFoundMessage());
+    }
+    if (mode === 'grok' && !cliDir) {
+      throw new Error(getGrokNotFoundMessage());
+    }
 
     const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
 
@@ -1920,6 +2113,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
       resumeSessionId,
       effort,
       sessionName: name,
@@ -1988,6 +2183,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       if (mode === 'gemini') {
         this._configureGemini(muxName);
       }
+      // For DeepSeek: permission mode + the Herdr-compatible status bridge.
+      if (mode === 'deepseek') {
+        this._configureDeepSeek(muxName, sessionId, deepSeekConfig);
+      }
 
       // Apply user-supplied env overrides (e.g., CLAUDE_CODE_EFFORT_LEVEL) via tmux setenv
       // so secret values stay off the bash command line. Must run before respawn-pane.
@@ -2144,6 +2343,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
       resumeSessionId,
       envOverrides,
       effort,
@@ -2173,6 +2374,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
       resumeSessionId,
       effort,
       sessionName: name,
@@ -2197,6 +2400,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       if (mode === 'gemini') {
         this._configureGemini(muxName);
       }
+      // For DeepSeek: permission mode + the Herdr-compatible status bridge.
+      if (mode === 'deepseek') {
+        this._configureDeepSeek(muxName, sessionId, deepSeekConfig);
+      }
 
       // Re-apply user env overrides before respawn so the new shell inherits them.
       this.applyEnvOverrides(muxName, envOverrides);

src/tui/tui-app.ts

@@ -1013,6 +1013,8 @@ const MODE_ITEMS: ReadonlyArray<{ id: TuiRunMode; label: string; detail: string
   { id: 'gemini', label: 'gemini', detail: 'Google Gemini' },
   { id: 'antigravity', label: 'antigravity', detail: 'Google Antigravity' },
   { id: 'pi', label: 'pi', detail: 'pi.dev' },
+  { id: 'grok', label: 'grok', detail: 'xAI Grok Build' },
+  { id: 'deepseek', label: 'deepseek', detail: 'DeepSeek Harness (dsh)' },
 ];
 
 // ─────────────────────────────────────────────────────────────────────────────

src/tui/tui-client.ts

@@ -149,7 +149,7 @@ export type TuiAnswerResult =
 
 export interface TuiQuickStartOptions {
   caseName: string;
-  mode?: 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi';
+  mode?: 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek';
   sessionName?: string;
   /** The tab this spawn came from, for the lineage lines (cosmetic, dropped if unresolvable). */
   parentSessionId?: string;

src/types/api.ts

@@ -109,7 +109,11 @@ export type HookEventType =
   | 'elicitation_response'
   | 'stop'
   | 'teammate_idle'
-  | 'task_completed';
+  | 'task_completed'
+  // No Claude Code hook behind this one: it is the DeepSeek status bridge's
+  // "a turn STARTED" report (see deepseek-status-shim.ts). Keep in step with
+  // HookEventSchema in web/schemas.ts.
+  | 'agent_working';
 
 // ========== API Response Types ==========
 

src/types/app-state.ts

@@ -24,6 +24,7 @@ import type { TaskState } from './task.js';
 import type { RalphLoopState } from './ralph.js';
 import type { RespawnConfig } from './respawn.js';
 import type { CronJob, CronJobRun } from './cron.js';
+import type { TabLayout } from '../tab-layout.js';
 
 // ========== Global Stats Types ==========
 
@@ -118,6 +119,8 @@ export interface AppState {
   cronJobRuns?: Record<string, CronJobRun>;
   /** Global tab order shared across devices (ordered list of sessionIds) — COD-131 */
   sessionOrder?: string[];
+  /** Owner-scoped authoritative grouped tab layouts. */
+  tabLayouts?: Record<string, TabLayout>;
 }
 
 // ========== Default Configuration ==========

src/types/session.ts

@@ -8,7 +8,7 @@
  * - SessionConfig — creation-time config (id, workingDir, createdAt)
  * - SessionOutput — captured stdout/stderr/exitCode
  * - SessionStatus — 'idle' | 'busy' | 'stopped' | 'error'
- * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' (which CLI backend)
+ * - SessionMode — 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' (which CLI backend)
  * - ClaudeMode — CLI permission mode ('dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools')
  * - SessionColor — visual differentiation color
  * - OpenCodeConfig — OpenCode-specific settings (model, autoAllowTools, continueSession)
@@ -16,6 +16,8 @@
  * - GeminiConfig — Gemini CLI-specific settings (model, approvalMode, resumeSession)
  * - AntigravityConfig — Antigravity CLI (agy) settings (model, dangerouslySkipPermissions, resumeConversationId)
  * - PiConfig — Pi CLI (pi.dev) settings (model, provider, thinking, resume/continue, project trust)
+ * - GrokConfig — Grok Build CLI (xAI `grok`) settings (model, alwaysApprove, resume/continue)
+ * - DeepSeekConfig — DeepSeek Harness (`dsh`) settings (profile, permissionMode, resume, status bridge)
  *
  * Cross-domain relationships:
  * - SessionState.respawnConfig embeds RespawnConfig (respawn domain)
@@ -44,11 +46,20 @@ export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
 export type ClaudeMode = 'dangerously-skip-permissions' | 'auto' | 'normal' | 'allowedTools';
 
 /** Session mode: which CLI backend a session runs */
-export type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi';
+export type SessionMode =
+  | 'claude'
+  | 'shell'
+  | 'opencode'
+  | 'codex'
+  | 'gemini'
+  | 'antigravity'
+  | 'pi'
+  | 'grok'
+  | 'deepseek';
 
 export type RemoteCommandMode = Extract<
   SessionMode,
-  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek'
 >;
 
 /**
@@ -157,7 +168,7 @@ export interface RemoteSessionInfo {
 /** Which CLI backends a Docker case can run (same set as remote). */
 export type DockerCommandMode = Extract<
   SessionMode,
-  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek'
 >;
 
 /** Container engine. Docker and Podman differ in the uid/userns + host-gateway alias. */
@@ -363,6 +374,85 @@ export interface PiConfig {
   approveProjectTrust?: boolean;
 }
 
+/**
+ * Grok Build CLI (xAI `grok`) session configuration.
+ *
+ * Grok has Claude-style permission modes; the bypass switch is `--always-approve`
+ * ("auto-approve all tool executions", the CLI's `bypassPermissions` mode). Deny
+ * rules from `~/.grok/config.toml` / project `.grok/config.toml` still apply on
+ * top of it. Verified against grok 1.0.5.
+ */
+export interface GrokConfig {
+  /** Model ID (e.g. "grok-4.5", or a custom `[model.<name>]` from config.toml). Passed via --model. */
+  model?: string;
+  /**
+   * Auto-approve all tool executions (passes --always-approve). Absent = grok's
+   * own default permission mode (ask). Multi-user: forced off for non-granted
+   * owners by the only-if-sent clamp branch, like codex/antigravity — the
+   * absent-config spawn already defaults safe.
+   */
+  alwaysApprove?: boolean;
+  /** Continue the most recent session for the working directory (-c). Skipped when resumeSessionId is set. */
+  continueSession?: boolean;
+  /** Resume a specific session by ID (--resume). Ids only, never titles or paths. */
+  resumeSessionId?: string;
+}
+
+/**
+ * DeepSeek Harness (`dsh`) session configuration.
+ *
+ * Two things make this config shaped unlike every sibling above it.
+ *
+ * **1. The agent is a PROFILE, not the binary.** `dsh` is a launcher: it boots
+ * `$DSH_HOME/profiles/<name>`, an ordered stack of plugin-bundle patch layers.
+ * DeepSeek ships only `web`, `headless` and `base`, so the interactive terminal
+ * agent is always a third-party profile the user installed. `profile` is
+ * therefore the primary knob, and an absent one resolves to the first
+ * pane-capable profile found (see resolveDefaultDeepSeekProfile).
+ *
+ * **2. Permissions are an ENV VAR, not a flag.** The harness has no
+ * `--dangerously-skip-permissions` equivalent; its sandbox and approval rows are
+ * config, driven by one documented input, `DSH_PERMISSION_MODE`, with three
+ * presets (measured from `dsh --dump-default-config`):
+ *
+ *   read-only          sandbox read-only,          approval ask
+ *   workspace-write    sandbox workspace-write,    approval ask     <- default
+ *   danger-full-access sandbox danger-full-access, approval never
+ *
+ * This is the one place a Codeman env export is the RIGHT mechanism rather than
+ * the forbidden one: unlike `CLAUDE_CODE_EFFORT_LEVEL` (which hard-locks
+ * in-session `/effort`), `DSH_PERMISSION_MODE` is read with `??` as a boot-time
+ * DEFAULT, so it stays a soft default the user can still change in-session. It
+ * is exported via `tmux setenv`, never on the spawn command line.
+ */
+export interface DeepSeekConfig {
+  /**
+   * Profile under `$DSH_HOME/profiles` to boot (`dsh --profile <name>`). Absent
+   * = the first pane-capable profile installed. A `web`/`headless` profile is
+   * refused at spawn time: neither can drive an interactive pane.
+   */
+  profile?: string;
+  /**
+   * Sandbox + approval preset, exported as `DSH_PERMISSION_MODE`. Absent = the
+   * harness's own `workspace-write` default, which still ASKS — which is why the
+   * multi-user clamp only needs the only-if-sent branch here, like
+   * codex/antigravity/grok rather than pi.
+   */
+  permissionMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
+  /** Resume the most recent session for this workspace (`--resume`). */
+  resumeSession?: boolean;
+  /** Resume a specific session by ID (`--resume <id>`). Wins over resumeSession. */
+  resumeSessionId?: string;
+  /**
+   * Report idle/working/blocked back to Codeman through the Herdr-compatible
+   * status shim (see `deepseek-status-shim.ts`). Default ON: it upgrades this
+   * mode from output-stabilization guessing to definitive hook events. Only
+   * TUIs that implement the contract report; for one that does not, this is
+   * inert rather than harmful.
+   */
+  statusReporting?: boolean;
+}
+
 /**
  * Configuration for creating a new session
  */
@@ -526,6 +616,10 @@ export interface SessionState {
   antigravityConfig?: AntigravityConfig;
   /** Pi-specific configuration (only for mode === 'pi') */
   piConfig?: PiConfig;
+  /** Grok-specific configuration (only for mode === 'grok') */
+  grokConfig?: GrokConfig;
+  /** DeepSeek Harness configuration (only for mode === 'deepseek') */
+  deepSeekConfig?: DeepSeekConfig;
   /** Claude conversation session ID to resume after reboot (set by restore script) */
   resumeSessionId?: string;
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */

src/types/webview.ts

@@ -32,6 +32,16 @@
 export type WebviewEmbedMode = 'proxy' | 'direct';
 
 /** A saved dashboard, persisted to `~/.codeman/webviews.json`. */
+/**
+ * Dashboards Codeman creates and maintains on the user's behalf.
+ *
+ * A managed record is hidden from the saved-dashboard list, because the shortcut
+ * that maintains it is already a menu entry of its own: listing both showed the
+ * same dashboard twice, once as "DeepSeek web UI..." and once as the row it had
+ * just written.
+ */
+export type WebviewManagedKind = 'deepseek-web';
+
 export interface Webview {
   id: string;
   /** Display name shown on the tab. */
@@ -49,6 +59,12 @@ export interface Webview {
    * cookies/localStorage, only for dashboards the user fully trusts.
    */
   trusted: boolean;
+  /**
+   * Set when Codeman owns this record rather than the user (see
+   * `WebviewManagedKind`). Managed rows are maintained by the shortcut that
+   * created them, including repointing the URL when the port changes.
+   */
+  managed?: WebviewManagedKind;
   /** Multi-user owner (username). Undefined in single-user mode. */
   owner?: string;
   createdAt: number;

src/usage-telemetry.ts

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Pure parsing + formatting of Claude Code statusline telemetry.
+ * @fileoverview Pure parsing + formatting of Claude and Codex plan telemetry.
  *
  * Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command`
  * on each render. On Pro/Max subscriptions that blob carries a `rate_limits`
@@ -15,7 +15,10 @@
  * Only those two windows exist (no Opus-weekly field). `rate_limits` is absent
  * before the first API response and for non-subscriber auth — both yield null.
  *
- * All functions are pure for testability. See `test/usage-telemetry.test.ts`.
+ * The Codex parser consumes the read-only `account/rateLimits/read` app-server
+ * response and selects only the main `codex` bucket, excluding model-specific
+ * buckets. All functions are pure for testability. See
+ * `test/usage-telemetry.test.ts` and `test/codex-plan-usage.test.ts`.
  *
  * @module usage-telemetry
  */
@@ -51,6 +54,22 @@ export interface RawStatuslinePayload {
   model?: { display_name?: string };
 }
 
+interface RawCodexRateLimitWindow {
+  usedPercent?: unknown;
+  windowDurationMins?: unknown;
+  resetsAt?: unknown;
+}
+
+interface RawCodexRateLimitSnapshot {
+  primary?: RawCodexRateLimitWindow | null;
+  secondary?: RawCodexRateLimitWindow | null;
+}
+
+interface RawCodexRateLimitsResponse {
+  rateLimits?: RawCodexRateLimitSnapshot | null;
+  rateLimitsByLimitId?: Record<string, RawCodexRateLimitSnapshot | null> | null;
+}
+
 function clampPct(n: number): number {
   if (!Number.isFinite(n)) return 0;
   return Math.max(0, Math.min(100, n));
@@ -88,6 +107,29 @@ export function parseStatusTelemetry(data: RawStatuslinePayload | undefined): St
   return t;
 }
 
+/** Normalize the main Codex app-server bucket into the chip's two known windows. */
+export function parseCodexRateLimitsResponse(value: unknown): StatusTelemetry | null {
+  if (!value || typeof value !== 'object') return null;
+  const response = value as RawCodexRateLimitsResponse;
+  const snapshot = response.rateLimitsByLimitId?.codex ?? response.rateLimits;
+  if (!snapshot || typeof snapshot !== 'object') return null;
+
+  const telemetry: StatusTelemetry = {};
+  for (const window of [snapshot.primary, snapshot.secondary]) {
+    if (!window || typeof window.usedPercent !== 'number' || !Number.isFinite(window.usedPercent)) continue;
+    if (window.windowDurationMins !== 300 && window.windowDurationMins !== 10_080) continue;
+    const resetsAt =
+      typeof window.resetsAt === 'number' && Number.isFinite(window.resetsAt) && window.resetsAt > 0
+        ? Math.round(window.resetsAt * 1000)
+        : 0;
+    const normalized = { usedPercentage: clampPct(window.usedPercent), resetAt: resetsAt };
+    if (window.windowDurationMins === 300) telemetry.fiveHour = normalized;
+    if (window.windowDurationMins === 10_080) telemetry.sevenDay = normalized;
+  }
+
+  return telemetry.fiveHour || telemetry.sevenDay ? telemetry : null;
+}
+
 /**
  * Current-session status for the in-terminal statusline footer. This is the
  * "status of the current session" the user sees in Claude's footer — distinct

src/utils/cli-executable-resolver.ts

@@ -1,8 +1,8 @@
 /**
  * @fileoverview Shared CLI executable resolution for the per-CLI resolvers.
  *
- * One lookup chain behind all six *-cli-resolver modules (claude, opencode,
- * codex, gemini, antigravity, pi): the server process PATH first, then the
+ * One lookup chain behind all seven *-cli-resolver modules (claude, opencode,
+ * codex, gemini, antigravity, pi, grok): the server process PATH first, then the
  * CLI's common install directories in order, then — last, because it is the
  * only step that spawns anything — an interactive login shell, which is what
  * finds nvm/Homebrew/user-npm installs when Codeman runs as a systemd/launchd

src/utils/codex-cli-resolver.ts

@@ -9,7 +9,9 @@
 
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
 import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
+import { parseCodexRateLimitsResponse, type StatusTelemetry } from '../usage-telemetry.js';
 
 /** Common directories where the Codex CLI binary may be installed */
 const CODEX_SEARCH_DIRS = [
@@ -21,7 +23,8 @@ const CODEX_SEARCH_DIRS = [
   join(homedir(), 'bin'), // User bin
 ];
 
-const codexResolver = createCliExecutableResolver({ binary: 'codex', searchDirs: CODEX_SEARCH_DIRS });
+const CODEX_BINARY = process.platform === 'win32' ? 'codex.exe' : 'codex';
+const codexResolver = createCliExecutableResolver({ binary: CODEX_BINARY, searchDirs: CODEX_SEARCH_DIRS });
 const CODEX_NOT_FOUND = 'Codex CLI not found. Install with: npm install -g @openai/codex';
 
 /**
@@ -35,6 +38,11 @@ export function resolveCodexDir(): string | null {
   return codexResolver.resolve()?.directory ?? null;
 }
 
+/** Absolute Codex executable path, for direct app-server requests. */
+export function resolveCodexBinaryPath(): string | null {
+  return codexResolver.resolve()?.binaryPath ?? null;
+}
+
 /**
  * Check if Codex CLI is available on the system.
  */
@@ -45,3 +53,80 @@ export function isCodexAvailable(): boolean {
 export function getCodexNotFoundMessage(): string {
   return formatCliNotFoundMessage(CODEX_NOT_FOUND, codexResolver.diagnostics());
 }
+
+type CodexRateLimitsRequest = (binaryPath: string, clientVersion: string) => Promise<unknown>;
+
+const APP_SERVER_TIMEOUT_MS = 10_000;
+const APP_SERVER_MAX_OUTPUT_BYTES = 256 * 1024;
+
+function requestCodexRateLimits(binaryPath: string, clientVersion: string): Promise<unknown> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let initialized = false;
+    let buffer = '';
+    const child = spawn(binaryPath, ['app-server', '--stdio'], {
+      stdio: ['pipe', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    const timeout = setTimeout(() => finish(null), APP_SERVER_TIMEOUT_MS);
+
+    const finish = (value: unknown): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      child.stdin.end();
+      child.kill();
+      resolve(value);
+    };
+    const send = (message: unknown): void => {
+      if (!settled && child.stdin.writable) child.stdin.write(`${JSON.stringify(message)}\n`);
+    };
+    const handleLine = (line: string): void => {
+      if (!line.trim()) return;
+      let message: { id?: number; result?: unknown; error?: unknown };
+      try {
+        message = JSON.parse(line) as { id?: number; result?: unknown; error?: unknown };
+      } catch {
+        return;
+      }
+      if (message.id === 1) {
+        if (message.error) return finish(null);
+        if (!initialized) {
+          initialized = true;
+          send({ method: 'account/rateLimits/read', id: 2 });
+        }
+      } else if (message.id === 2) {
+        finish(message.error ? null : message.result);
+      }
+    };
+
+    child.on('error', () => finish(null));
+    child.on('close', () => finish(null));
+    child.stdin.on('error', () => finish(null));
+    child.stdout.on('data', (chunk: Buffer) => {
+      buffer += chunk.toString('utf8');
+      if (Buffer.byteLength(buffer) > APP_SERVER_MAX_OUTPUT_BYTES) return finish(null);
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() ?? '';
+      for (const line of lines) handleLine(line);
+    });
+
+    send({
+      method: 'initialize',
+      id: 1,
+      params: {
+        clientInfo: { name: 'codeman', title: 'Codeman', version: clientVersion },
+        capabilities: null,
+      },
+    });
+  });
+}
+
+/** Read the signed-in host account's main Codex limits without exposing credentials. */
+export async function readCodexPlanUsage(
+  binaryPath: string,
+  clientVersion: string,
+  request: CodexRateLimitsRequest = requestCodexRateLimits
+): Promise<StatusTelemetry | null> {
+  return parseCodexRateLimitsResponse(await request(binaryPath, clientVersion));
+}

src/utils/deepseek-cli-resolver.ts

@@ -0,0 +1,401 @@
+/**
+ * @fileoverview Resolve the DeepSeek Harness CLI (`dsh`) binary and its bootable profiles.
+ *
+ * Mirrors pi-cli-resolver.ts / grok-cli-resolver.ts, but the identity probe here
+ * is STRICTER than either, and deliberately so: `dsh` is not merely a short name
+ * with npm squatters, it is an EXISTING, widely packaged Unix program. Debian and
+ * Ubuntu ship `dsh` = "dancer's shell" / distributed shell (`apt install dsh`),
+ * which like nearly every Unix tool prints a version-shaped string of its own.
+ * A version-token probe alone (which is all pi and grok need) would
+ * therefore ACCEPT dancer's shell as the DeepSeek Harness and hand it to a spawn
+ * line, so every candidate must additionally prove its identity by printing the
+ * harness's own help banner.
+ *
+ * Two probes per candidate, both bounded and both cached behind the shared
+ * resolver's positive/negative caching:
+ *   1. `dsh --help`    must match DEEPSEEK_IDENTITY_REGEX (`DeepSeek Harness`)
+ *   2. `dsh --version` must yield a version token (real output: `0.1.1-rc.2`)
+ * Order matters: identity is checked FIRST, so a foreign `dsh` is rejected on the
+ * cheaper, more discriminating signal and never contributes a version number.
+ *
+ * `dsh` is a profile LAUNCHER, not an agent: `dsh --profile <name>` boots an
+ * ordered stack of plugin-bundle patch layers, and DeepSeek ships only `web`
+ * (browser UI), `headless` (one-shot) and `base` (no app). The interactive
+ * terminal agent Codeman actually drives is a THIRD-PARTY profile the user
+ * installs. That is why this module resolves two independent things — a binary
+ * AND a profile inventory — and why "available" for the deepseek run mode means
+ * both (`isDeepSeekRunnable`, and `resolveDeepSeekLaunchError` in session-routes.ts
+ * for the actionable per-half message).
+ *
+ * @module utils/deepseek-cli-resolver
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import {
+  createCliExecutableResolver,
+  formatCliNotFoundMessage,
+  type CliResolverHost,
+} from './cli-executable-resolver.js';
+
+/**
+ * Common directories where the `dsh` binary may be installed.
+ *
+ * `dsh` is an npm package (`@deepseek-ai/dsh`), so unlike grok there is no
+ * vendor-owned install dir to lead with: the global npm bin is wherever the
+ * user's prefix points. `~/.local/bin` heads the list because it is the default
+ * for a prefix-relocated npm (and is where this box's install landed).
+ */
+const DEEPSEEK_SEARCH_DIRS = [
+  join(homedir(), '.local', 'bin'),
+  '/usr/local/bin',
+  join(homedir(), '.npm-global', 'bin'),
+  join(homedir(), 'bin'),
+];
+
+/**
+ * A real `dsh --version` prints a bare `0.1.1-rc.2` (measured, 0.1.1-rc.2), so
+ * the prerelease suffix is part of the token — truncating it to `0.1.1` would
+ * misreport a release-candidate as a release in `codeman doctor`.
+ *
+ * Exported and SHARED with the `dsh` entry in `config/dependency-registry.ts`,
+ * so the doctor and the run mode cannot disagree about what counts as an
+ * installed dsh (the same single-source rule as PI_VERSION_REGEX /
+ * GROK_VERSION_REGEX). Shape is dictated by the doctor's `extractVersion()`
+ * (first capture group, whole-output scan): hence a capturing group and a
+ * leading boundary instead of `^`. No `g` flag, so there is no shared
+ * `lastIndex` to reset.
+ */
+export const DEEPSEEK_VERSION_REGEX = /(?:^|\s)v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?)/;
+
+/**
+ * The identity marker that separates DeepSeek's `dsh` from Debian's dancer's
+ * shell. The real launcher's `--help` banner reads:
+ *
+ *   dsh: boot a DeepSeek Harness profile — an ordered stack of plugin-bundle …
+ *
+ * Matched case-insensitively against the help output. This is the check that
+ * makes the resolver safe to point a spawn line at; see the module header.
+ */
+export const DEEPSEEK_IDENTITY_REGEX = /DeepSeek\s+Harness/i;
+
+const DEEPSEEK_NOT_FOUND = 'DeepSeek Harness CLI (dsh) not found. Install with: npm install -g @deepseek-ai/dsh';
+
+/** Where profiles live: `$DSH_HOME/profiles`, defaulting to `~/.dsh/profiles`. */
+export function resolveDshHome(): string {
+  const fromEnv = process.env.DSH_HOME?.trim();
+  return fromEnv && fromEnv.length > 0 ? fromEnv : join(homedir(), '.dsh');
+}
+
+/**
+ * What a profile is FOR, inferred from the bundles it composes.
+ *
+ * `interactive` is the only kind a tmux pane can drive: `web` serves a browser
+ * UI and would occupy the pane with a logging server, `headless` answers one
+ * task and exits (which reads as an instantly-dead pane). `unknown` is treated
+ * as interactive-capable on purpose — the whole point of the harness is that
+ * anyone can publish an app bundle, so an unrecognized third-party profile must
+ * not be hidden from the picker just because this list has not heard of it.
+ */
+export type DeepSeekProfileKind = 'interactive' | 'web' | 'headless' | 'unknown';
+
+export interface DeepSeekProfile {
+  /** Directory name under `$DSH_HOME/profiles`, i.e. the `--profile` argument. */
+  name: string;
+  /** Bundle package names composed by the profile, in order. */
+  bundles: string[];
+  kind: DeepSeekProfileKind;
+}
+
+/** Bundles that positively identify a non-interactive profile. */
+const WEB_BUNDLE_PATTERN = /dsh-web-app|dsh-web-frontend/i;
+const HEADLESS_BUNDLE_PATTERN = /dsh-headless/i;
+/**
+ * Bundles that positively identify a terminal app. Intentionally a loose
+ * community-wide pattern rather than one blessed package: the terminal front
+ * door is third-party by construction (DeepSeek ships none), and a dozen
+ * scoped `dsh-tui` packages from a dozen different authors compete. Anything
+ * matching is a TUI; anything unmatched is `unknown`, which still counts as
+ * launchable.
+ *
+ * `tui` carries word boundaries so the loose arm stays a TOKEN match: `-` and
+ * `/` are non-word characters, so `@someone/tui-app` and `dsh-tui` both match
+ * while `intuition` and `gratuitous` do not. Being wrong here is cheap (an
+ * unmatched profile is `unknown`, which is launchable too) but it decides which
+ * profile a session boots by DEFAULT, and "the one whose name happens to contain
+ * t-u-i" is not a rule anyone could predict.
+ */
+const TUI_BUNDLE_PATTERN = /dsh-tui|dsh-terminal-app|\btui\b/i;
+
+/**
+ * The profile names DeepSeek itself ships for its non-interactive surfaces.
+ *
+ * Consulted only AFTER the bundle patterns have found nothing, and only against
+ * the directory name. `readProfile()` yields an empty bundle list for any
+ * `package.json` without a `dsh.profile.bundles` array — a hand-edited file, an
+ * older layout, a profile mid-install — and with no bundles to read, the stock
+ * `web` and `headless` profiles look exactly like an unrecognized third-party
+ * one and inherit its launchable-by-default treatment. That is the single
+ * "unknown" that is knowably wrong, and it produces precisely the
+ * pane-dies-on-arrival failure the two-part availability gate exists to prevent.
+ *
+ * Deliberately a fallback rather than a first check: a third-party profile that
+ * legitimately composes a terminal app is identified by its BUNDLES, and its
+ * directory name (which the user chose) must never override that evidence.
+ */
+const STOCK_NON_INTERACTIVE_PROFILES = new Map<string, DeepSeekProfileKind>([
+  ['web', 'web'],
+  ['headless', 'headless'],
+]);
+
+/** Profile directory names that are not profiles. */
+const NON_PROFILE_DIRS = new Set(['node_modules', '.bin', '.pnpm']);
+
+function classifyProfile(name: string, bundles: string[]): DeepSeekProfileKind {
+  const haystack = [name, ...bundles].join(' ');
+  // Order matters: a profile that composes BOTH a web app and a tui bundle is a
+  // web profile as far as a tmux pane is concerned, because the web app owns the
+  // process and blocks.
+  if (WEB_BUNDLE_PATTERN.test(haystack)) return 'web';
+  if (HEADLESS_BUNDLE_PATTERN.test(haystack)) return 'headless';
+  if (TUI_BUNDLE_PATTERN.test(haystack)) return 'interactive';
+  return STOCK_NON_INTERACTIVE_PROFILES.get(name.toLowerCase()) ?? 'unknown';
+}
+
+/**
+ * Read a single profile directory's `package.json` and return its bundle list.
+ * Returns null for anything that is not a readable dsh profile, so a stray
+ * directory under `profiles/` cannot break the inventory.
+ */
+function readProfile(profilesDir: string, name: string): DeepSeekProfile | null {
+  try {
+    const raw = readFileSync(join(profilesDir, name, 'package.json'), 'utf-8');
+    const parsed = JSON.parse(raw) as { dsh?: { profile?: { bundles?: unknown } } };
+    const rawBundles = parsed?.dsh?.profile?.bundles;
+    const bundles = Array.isArray(rawBundles) ? rawBundles.filter((b): b is string => typeof b === 'string') : [];
+    return { name, bundles, kind: classifyProfile(name, bundles) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inventory the profiles installed under `$DSH_HOME/profiles`.
+ *
+ * Never throws: a missing DSH_HOME (dsh installed but never run) is an empty
+ * list, which the callers render as "no profile yet" rather than an error.
+ * Deliberately un-cached — a user can create a profile at any moment (including
+ * through Codeman's own bootstrap), and the directory scan is cheap next to the
+ * two process spawns the binary probe already costs.
+ */
+export function listDeepSeekProfiles(): DeepSeekProfile[] {
+  const profilesDir = join(resolveDshHome(), 'profiles');
+  let entries: string[];
+  try {
+    entries = readdirSync(profilesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !NON_PROFILE_DIRS.has(e.name) && !e.name.startsWith('.'))
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+  return entries
+    .map((name) => readProfile(profilesDir, name))
+    .filter((p): p is DeepSeekProfile => p !== null)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The profile a session should boot when the user picked none.
+ *
+ * Prefers a positively-identified terminal profile, then an unrecognized one
+ * (third-party by construction — see TUI_BUNDLE_PATTERN), and refuses to fall
+ * back to `web`/`headless`, which cannot drive a pane. Returns null when nothing
+ * launchable is installed, which is what makes the mode report unavailable
+ * instead of spawning a pane that dies on arrival.
+ */
+export function resolveDefaultDeepSeekProfile(profiles: DeepSeekProfile[] = listDeepSeekProfiles()): string | null {
+  return (
+    profiles.find((p) => p.kind === 'interactive')?.name ?? profiles.find((p) => p.kind === 'unknown')?.name ?? null
+  );
+}
+
+/** True when the profile can occupy a tmux pane as an interactive agent. */
+export function isLaunchableProfile(profile: DeepSeekProfile): boolean {
+  return profile.kind === 'interactive' || profile.kind === 'unknown';
+}
+
+/**
+ * Run the two-stage identity+version probe on a candidate path.
+ *
+ * Returns the version token only when the binary proves it is the DeepSeek
+ * Harness launcher. Returns null for anything else: a missing binary, a
+ * non-zero exit, a hang (timeout), a help banner without the harness marker
+ * (this is the dancer's-shell rejection), or output with no version-shaped
+ * token.
+ *
+ * Never runs under vitest: the suites must stay hermetic and must not depend on
+ * whether the dev box happens to have dsh installed — and since `dsh` names a
+ * real Debian program, this probe would EXECUTE whatever binary of that name the
+ * machine carries. The shared resolver host is already inert under vitest, so
+ * this gate is defense in depth for any opted-in host that still carries the
+ * default probe; tests drive resolution via `createDeepSeekResolverForTest`,
+ * whose injected probe bypasses it. Pinned by test/deepseek-cli-resolver.test.ts.
+ */
+function probeDeepSeekVersion(binPath: string): string | null {
+  if (process.env.VITEST) return null;
+  const run = (args: string[]): string | null => {
+    try {
+      return execFileSync(binPath, args, {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        // A stuck or hostile `dsh` that ignores SIGTERM would survive the timeout
+        // and block the server (execFileSync keeps waiting after the signal).
+        killSignal: 'SIGKILL',
+      }).trim();
+    } catch (err) {
+      console.warn(
+        `[DeepSeekResolver] Ignoring ${binPath}: "dsh ${args.join(' ')}" failed (${(err as Error).message})`
+      );
+      return null;
+    }
+  };
+
+  // Identity first — the discriminating signal, and the one that keeps Debian's
+  // dancer's shell out of a spawn line.
+  const help = run(['--help']);
+  if (help === null) return null;
+  if (!DEEPSEEK_IDENTITY_REGEX.test(help)) {
+    console.warn(
+      `[DeepSeekResolver] Ignoring ${binPath}: "dsh --help" is not the DeepSeek Harness launcher ` +
+        `(printed ${JSON.stringify(help.slice(0, 80))}). A different program named "dsh" (e.g. Debian's ` +
+        `dancer's shell) is earlier on PATH.`
+    );
+    return null;
+  }
+
+  const out = run(['--version']);
+  if (out === null) return null;
+  const candidate = DEEPSEEK_VERSION_REGEX.exec(out)?.[1];
+  if (candidate) return candidate;
+  console.warn(`[DeepSeekResolver] Ignoring ${binPath}: "dsh --version" printed ${JSON.stringify(out.slice(0, 80))}`);
+  return null;
+}
+
+type DeepSeekVersionProbe = (binPath: string) => string | null;
+
+function createDeepSeekResolver(
+  host?: CliResolverHost,
+  versionProbe: DeepSeekVersionProbe = probeDeepSeekVersion,
+  now?: () => number
+) {
+  return createCliExecutableResolver<string>(
+    {
+      binary: 'dsh',
+      searchDirs: DEEPSEEK_SEARCH_DIRS,
+      validateCandidate: (binPath) => {
+        const version = versionProbe(binPath);
+        return version ? { accepted: true, metadata: version } : { accepted: false };
+      },
+      now,
+    },
+    host
+  );
+}
+
+/**
+ * Creates an isolated DeepSeek wrapper around an injected host, version probe
+ * and clock. Omitting `versionProbe` keeps the ambient (VITEST-gated) probe,
+ * which is exactly what the hermeticity test exercises.
+ */
+export function createDeepSeekResolverForTest(
+  host: CliResolverHost,
+  versionProbe?: DeepSeekVersionProbe,
+  now?: () => number
+) {
+  return createDeepSeekResolver(host, versionProbe ?? probeDeepSeekVersion, now);
+}
+
+const deepSeekResolver = createDeepSeekResolver();
+
+/**
+ * Finds the directory containing a verified `dsh` binary.
+ * Checks the server PATH first, then the common install locations. Every
+ * candidate must pass the identity+version probe before it is accepted.
+ *
+ * @returns Directory path, or null if not found
+ */
+export function resolveDeepSeekDir(): string | null {
+  return deepSeekResolver.resolve()?.directory ?? null;
+}
+
+/**
+ * Whether the `dsh` BINARY is installed. Note this is deliberately weaker than
+ * what the run mode needs: a dsh with no launchable profile cannot start a
+ * session. Callers gating the Run button want `isDeepSeekRunnable()`.
+ */
+export function isDeepSeekAvailable(): boolean {
+  return resolveDeepSeekDir() !== null;
+}
+
+/** Binary present AND at least one profile that can occupy a pane. */
+export function isDeepSeekRunnable(): boolean {
+  return isDeepSeekAvailable() && resolveDefaultDeepSeekProfile() !== null;
+}
+
+export function getDeepSeekNotFoundMessage(): string {
+  return formatCliNotFoundMessage(DEEPSEEK_NOT_FOUND, deepSeekResolver.diagnostics());
+}
+
+/**
+ * Version reported by the resolved `dsh` binary, or null when dsh is
+ * unavailable. Surfaced through `GET /api/deepseek/status` so a misresolution
+ * is diagnosable from the UI.
+ */
+export function getDeepSeekCliVersion(): string | null {
+  return deepSeekResolver.resolve()?.metadata ?? null;
+}
+
+/** Does the named profile exist and can it drive a pane? */
+export function profileExists(name: string): boolean {
+  return existsSync(join(resolveDshHome(), 'profiles', name, 'package.json'));
+}
+
+/**
+ * Why a DeepSeek session cannot start, or null when it can.
+ *
+ * Availability for this mode is TWO questions, not one, because `dsh` is a
+ * profile launcher rather than an agent: the binary must resolve (and prove it
+ * is the harness and not Debian's dancer's shell), AND a profile that can occupy
+ * a pane must exist. Every create path — both HTTP routes AND cron fires — must
+ * ask this before constructing a Session, or the pane boots the box's default
+ * profile, which may be a logging web server or a one-shot that exits on
+ * arrival, and the prompt is typed into it.
+ */
+export function resolveDeepSeekLaunchError(requestedProfile?: string): string | null {
+  if (!isDeepSeekAvailable()) return getDeepSeekNotFoundMessage();
+
+  const profiles = listDeepSeekProfiles();
+  if (requestedProfile) {
+    const match = profiles.find((p) => p.name === requestedProfile);
+    if (!match) {
+      return `DeepSeek Harness profile "${requestedProfile}" does not exist. Create it with: dsh plugin --profile ${requestedProfile} add <package>`;
+    }
+    if (match.kind === 'web' || match.kind === 'headless') {
+      return `DeepSeek Harness profile "${requestedProfile}" is a ${match.kind} profile and cannot run in a terminal session. Pick an interactive profile, or open the web profile as a Codeman web tab.`;
+    }
+    return null;
+  }
+
+  if (!resolveDefaultDeepSeekProfile(profiles)) {
+    return (
+      'No interactive DeepSeek Harness profile is installed. DeepSeek ships only the web and headless ' +
+      'profiles, so the terminal agent comes from a plugin — install one with: ' +
+      'dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui'
+    );
+  }
+  return null;
+}

src/utils/grok-cli-resolver.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Resolve the Grok Build CLI (`grok`, xAI) binary across common install paths.
+ *
+ * Mirrors pi-cli-resolver.ts, version probe included: `grok` is another short
+ * name with known squatters (the unrelated `@vibe-kit/grok-cli` npm package also
+ * installs a `grok` bin), so a `which grok` hit is not by itself evidence that
+ * xAI's coding agent is installed. Every candidate is sanity-probed with
+ * `grok --version` and required to print a version-shaped string (the real CLI
+ * prints `grok 1.0.5 (5115b46bc9)`); a binary that fails the probe is treated
+ * as absent and the rejected path is logged. The probe cannot tell two
+ * version-printing `grok`s apart, which is why `GET /api/grok/status` surfaces
+ * path AND version: a misresolution is diagnosable rather than presenting as
+ * "the mode just doesn't work".
+ *
+ * The official installer (`curl -fsSL https://x.ai/cli/install.sh | bash`)
+ * places the binary in `~/.grok/bin` and symlinks it into `~/.local/bin`, so
+ * those two head the search list.
+ *
+ * @module utils/grok-cli-resolver
+ */
+
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import {
+  createCliExecutableResolver,
+  formatCliNotFoundMessage,
+  type CliResolverHost,
+} from './cli-executable-resolver.js';
+
+/** Common directories where the Grok CLI binary may be installed */
+const GROK_SEARCH_DIRS = [
+  join(homedir(), '.grok', 'bin'),
+  join(homedir(), '.local', 'bin'),
+  '/usr/local/bin',
+  join(homedir(), 'bin'),
+];
+
+/**
+ * A real `grok --version` prints `grok 1.0.5 (5115b46bc9)` (measured, 1.0.5).
+ *
+ * Exported and SHARED with the `grok` entry in `config/dependency-registry.ts`,
+ * so `codeman doctor` and the run mode cannot disagree about what counts as an
+ * installed grok (the same single-source rule as PI_VERSION_REGEX). Shape is
+ * dictated by the doctor's `extractVersion()` (first capture group, whole-output
+ * scan): hence a capturing group and a leading boundary instead of `^`. No `g`
+ * flag, so there is no shared `lastIndex` to reset.
+ */
+export const GROK_VERSION_REGEX = /(?:^|\s)(\d+\.\d+\.\d+)/;
+
+const GROK_NOT_FOUND = 'Grok CLI not found. Install with: curl -fsSL https://x.ai/cli/install.sh | bash';
+
+/**
+ * Run `grok --version` on a candidate path and return the version token when it
+ * looks like the coding agent. Returns null for anything else: a missing
+ * binary, a non-zero exit, a hang (timeout), or output with no version-shaped
+ * token (which is how an unrelated `grok` on PATH gets rejected).
+ *
+ * Never runs under vitest: the suites must stay hermetic and must not depend on
+ * whether the dev box happens to have grok installed, and since `grok` is a
+ * name with known squatters, this probe would EXECUTE whatever binary of that
+ * name the machine carries. The shared resolver host is already inert under
+ * vitest, so this gate is defense in depth for any opted-in host that still
+ * carries the default probe; tests drive resolution via
+ * `createGrokResolverForTest`, whose injected probe bypasses it. Pinned by
+ * test/grok-cli-resolver.test.ts.
+ */
+function probeGrokVersion(binPath: string): string | null {
+  if (process.env.VITEST) return null;
+  try {
+    const out = execFileSync(binPath, ['--version'], {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      // A stuck or hostile `grok` that ignores SIGTERM would survive the timeout
+      // and block the server (execFileSync keeps waiting after the signal).
+      killSignal: 'SIGKILL',
+    }).trim();
+    const candidate = GROK_VERSION_REGEX.exec(out)?.[1];
+    if (candidate) return candidate;
+    console.warn(`[GrokResolver] Ignoring ${binPath}: "grok --version" printed ${JSON.stringify(out.slice(0, 80))}`);
+  } catch (err) {
+    console.warn(`[GrokResolver] Ignoring ${binPath}: "grok --version" failed (${(err as Error).message})`);
+  }
+  return null;
+}
+
+type GrokVersionProbe = (binPath: string) => string | null;
+
+function createGrokResolver(
+  host?: CliResolverHost,
+  versionProbe: GrokVersionProbe = probeGrokVersion,
+  now?: () => number
+) {
+  return createCliExecutableResolver<string>(
+    {
+      binary: 'grok',
+      searchDirs: GROK_SEARCH_DIRS,
+      validateCandidate: (binPath) => {
+        const version = versionProbe(binPath);
+        return version ? { accepted: true, metadata: version } : { accepted: false };
+      },
+      now,
+    },
+    host
+  );
+}
+
+/**
+ * Creates an isolated Grok wrapper around an injected host, version probe and
+ * clock. Omitting `versionProbe` keeps the ambient (VITEST-gated) probe, which
+ * is exactly what the hermeticity test exercises.
+ */
+export function createGrokResolverForTest(host: CliResolverHost, versionProbe?: GrokVersionProbe, now?: () => number) {
+  return createGrokResolver(host, versionProbe ?? probeGrokVersion, now);
+}
+
+const grokResolver = createGrokResolver();
+
+/**
+ * Finds the directory containing a verified `grok` binary.
+ * Checks the server PATH first, then the common install locations
+ * (`~/.grok/bin` leading, the official installer's target). Every candidate
+ * must pass the `grok --version` sanity probe before it is accepted.
+ *
+ * @returns Directory path, or null if not found
+ */
+export function resolveGrokDir(): string | null {
+  return grokResolver.resolve()?.directory ?? null;
+}
+
+/**
+ * Check if the Grok CLI is available on the system.
+ */
+export function isGrokAvailable(): boolean {
+  return resolveGrokDir() !== null;
+}
+
+export function getGrokNotFoundMessage(): string {
+  return formatCliNotFoundMessage(GROK_NOT_FOUND, grokResolver.diagnostics());
+}
+
+/**
+ * Version reported by the resolved `grok` binary, or null when grok is
+ * unavailable. Surfaced through `GET /api/grok/status` so a misresolution is
+ * diagnosable from the UI.
+ */
+export function getGrokCliVersion(): string | null {
+  return grokResolver.resolve()?.metadata ?? null;
+}

src/utils/index.ts

@@ -37,7 +37,13 @@ export {
 } from './claude-cli-resolver.js';
 export { spawnPtyWithHelperRepair } from './node-pty-repair.js';
 export { resolveOpenCodeDir, getOpenCodeNotFoundMessage } from './opencode-cli-resolver.js';
-export { resolveCodexDir, isCodexAvailable, getCodexNotFoundMessage } from './codex-cli-resolver.js';
+export {
+  resolveCodexDir,
+  resolveCodexBinaryPath,
+  isCodexAvailable,
+  getCodexNotFoundMessage,
+  readCodexPlanUsage,
+} from './codex-cli-resolver.js';
 export { resolveGeminiDir, isGeminiAvailable, getGeminiNotFoundMessage } from './gemini-cli-resolver.js';
 export {
   resolveAntigravityDir,
@@ -45,5 +51,19 @@ export {
   getAntigravityNotFoundMessage,
 } from './antigravity-cli-resolver.js';
 export { resolvePiDir, isPiAvailable, getPiCliVersion, getPiNotFoundMessage } from './pi-cli-resolver.js';
+export { resolveGrokDir, isGrokAvailable, getGrokCliVersion, getGrokNotFoundMessage } from './grok-cli-resolver.js';
+export {
+  resolveDeepSeekDir,
+  isDeepSeekAvailable,
+  isDeepSeekRunnable,
+  getDeepSeekCliVersion,
+  getDeepSeekNotFoundMessage,
+  listDeepSeekProfiles,
+  resolveDefaultDeepSeekProfile,
+  isLaunchableProfile,
+  resolveDshHome,
+  profileExists,
+} from './deepseek-cli-resolver.js';
+export type { DeepSeekProfile, DeepSeekProfileKind } from './deepseek-cli-resolver.js';
 export { compileFileQuery, matchFileQuery } from './file-query.js';
 export type { FileQueryMatcher } from './file-query.js';

src/web/plan-usage-latest.ts

@@ -1,10 +1,11 @@
 /**
  * @fileoverview Process-wide last-known plan-usage telemetry (account-global).
  *
- * The status-telemetry route writes the latest broadcast value here; the SSE
- * init snapshot (`getLightState`) replays it so the header "Plan Usage Limits"
- * chip shows immediately on a fresh page load / SSE reconnect — before any new
- * statusline render arrives, and without relying on per-browser localStorage.
+ * The Claude status-telemetry route and host Codex poll merge their latest
+ * values here. The SSE init snapshot (`getLightState`) replays the combined
+ * value so the header "Plan Usage Limits" chip shows immediately on a fresh
+ * page load / SSE reconnect — before either source emits another sample, and
+ * without relying on per-browser localStorage.
  *
  * Null until the first telemetry of the process; cleared naturally on restart.
  *
@@ -13,8 +14,15 @@
 
 let latest: Record<string, unknown> | null = null;
 
-export function setLatestPlanUsage(value: Record<string, unknown>): void {
-  latest = value;
+export function setLatestPlanUsage(value: Record<string, unknown>): Record<string, unknown> {
+  const codex = latest?.codex;
+  latest = { ...value, ...(codex !== undefined ? { codex } : {}) };
+  return latest;
+}
+
+export function setLatestCodexPlanUsage(value: object | null): Record<string, unknown> {
+  latest = { ...(latest ?? {}), codex: value };
+  return latest;
 }
 
 export function getLatestPlanUsage(): Record<string, unknown> | null {

src/web/ports/index.ts

@@ -14,3 +14,4 @@ export type { InfraPort, ScheduledRun } from './infra-port.js';
 export type { AuthPort } from './auth-port.js';
 export type { OrchestratorPort } from './orchestrator-port.js';
 export type { CronPort } from './cron-port.js';
+export type { TabLayoutPort } from './tab-layout-port.js';

src/web/ports/session-port.ts

@@ -7,7 +7,7 @@ import type { Session } from '../../session.js';
 
 export interface SessionPort {
   readonly sessions: ReadonlyMap<string, Session>;
-  addSession(session: Session): void;
+  addSession(session: Session): Promise<void>;
   cleanupSession(sessionId: string, killMux?: boolean, reason?: string): Promise<void>;
   setupSessionListeners(session: Session): Promise<void>;
   persistSessionState(session: Session): void;

src/web/ports/tab-layout-port.ts

@@ -0,0 +1,8 @@
+/** @fileoverview Owner-scoped tab-layout capabilities exposed to route modules. */
+import type { TabLayoutService } from '../../tab-layout-service.js';
+
+export type { LegacyOrderActor, LegacyOrderPutResult, SessionOrderProjectionChange } from '../../tab-layout-service.js';
+
+export interface TabLayoutPort {
+  readonly tabLayouts: TabLayoutService;
+}

src/web/public/app.js

@@ -240,6 +240,7 @@ const _SSE_HANDLER_MAP = [
   [SSE_EVENTS.HOOK_ELICITATION_COMPLETE, '_onHookElicitationComplete'],
   [SSE_EVENTS.HOOK_ELICITATION_RESPONSE, '_onHookElicitationResponse'],
   [SSE_EVENTS.HOOK_STOP, '_onHookStop'],
+  [SSE_EVENTS.HOOK_AGENT_WORKING, '_onHookAgentWorking'],
   [SSE_EVENTS.HOOK_TEAMMATE_IDLE, '_onHookTeammateIdle'],
   [SSE_EVENTS.HOOK_TASK_COMPLETED, '_onHookTaskCompleted'],
 
@@ -678,12 +679,19 @@ class CodemanApp {
     // Terminal write batching with DEC 2026 sync support
     this.pendingWrites = [];
     this.writeFrameScheduled = false;
+    // xterm.write() parses asynchronously. Keep at most one live-output chunk
+    // inside xterm so its private WriteBuffer cannot bypass our 128KB cap.
+    this._terminalWriteInFlight = false;
+    this._terminalWriteInFlightBytes = 0;
     this._wasAtBottomBeforeWrite = true; // Default to true for sticky scroll
     this.syncWaitTimeout = null; // Timeout for incomplete sync blocks
     this._isLoadingBuffer = false; // true during chunkedTerminalWrite — blocks live SSE writes
     this._loadBufferQueue = null;  // queued SSE events during buffer load
     this._bufferLoadSeq = 0;
     this._bufferLoadOwner = null;
+    // Single-flight token for terminal buffer recovery. The identity check also
+    // lets a session switch invalidate an older fetch without blocking the new tab.
+    this._terminalRefreshOwner = null;
 
     // Flicker filter state (buffers output after screen clears)
     this.flickerFilterBuffer = '';
@@ -919,6 +927,8 @@ class CodemanApp {
     // Calls applyTabWrapSettings() itself (it owns tabs-two-rows / tabs-show-folder)
     // and then applies the sidebar variant on top — do not call both.
     this.applySessionListLayout();
+    this.applyTabOrientation();
+    this.initTabRailResize?.();
     this.applyMonitorVisibility();
     this.applyLineageLineSettings?.();
     this._installLineageStripScrollListener?.();
@@ -986,6 +996,11 @@ class CodemanApp {
       this.applySkin();
       this.applyLocalization();
       this.applySessionListLayout();
+      // A fresh device seeding tabOrientation from the server would otherwise
+      // show no rail until a resize or a settings save: the boot-time call ran
+      // before this async load resolved. Must stay AFTER applySessionListLayout
+      // (same ordering rule as the settings-save path).
+      this.applyTabOrientation?.();
       this.applyMonitorVisibility();
       this.applyLineageLineSettings?.();
       // ultracodeFloatingWindows syncs from the server (non-display key), but on a
@@ -1598,7 +1613,15 @@ class CodemanApp {
       this._sseHandlerWrappers = new Map();
       for (const [event, method] of _SSE_HANDLER_MAP) {
         const fn = this[method];
+        const wsOwnsTerminal =
+          method === '_onSSETerminal' ||
+          method === '_onSSENeedsRefresh' ||
+          method === '_onSSEClearTerminal';
         this._sseHandlerWrappers.set(event, (e) => {
+          // While WS owns terminal I/O, the parallel SSE stream is redundant.
+          // Drop it before JSON.parse so a busy terminal cannot turn duplicate
+          // SSE traffic/backpressure into another expensive buffer replay.
+          if (wsOwnsTerminal && this._wsReady) return;
           try {
             fn.call(this, e.data ? JSON.parse(e.data) : {});
           } catch (err) {
@@ -1845,18 +1868,18 @@ class CodemanApp {
     if (this.sessions.size === 0) this.stopSystemStatsPolling();
   }
 
-  // SSE wrappers — skip terminal events when WebSocket is delivering for this session.
+  // SSE wrappers — skip terminal events while WebSocket owns active terminal I/O.
   // WS handler calls the underlying _onSession* methods directly.
   _onSSETerminal(data) {
-    if (this._wsReady && this._wsSessionId === data.id) return;
+    if (this._wsReady) return;
     this._onSessionTerminal(data);
   }
   _onSSENeedsRefresh(data) {
-    if (this._wsReady && this._wsSessionId === data?.id) return;
+    if (this._wsReady) return;
     this._onSessionNeedsRefresh(data);
   }
   _onSSEClearTerminal(data) {
-    if (this._wsReady && this._wsSessionId === data?.id) return;
+    if (this._wsReady) return;
     this._onSessionClearTerminal(data);
   }
 
@@ -1864,15 +1887,15 @@ class CodemanApp {
     if (data.id === this.activeSessionId) {
       if (data.data.length > 32768) _crashDiag.log(`TERMINAL: ${(data.data.length/1024).toFixed(0)}KB`);
 
-      // Hard cap: track total bytes queued in render buffers (pendingWrites +
-      // flickerFilterBuffer). When rAF is throttled (tab
-      // backgrounded, GPU busy), data accumulates with no flush, reaching
-      // 889KB+ and freezing Chrome for minutes. Drop data beyond 128KB and
-      // schedule a buffer reload to recover the display once the burst subsides.
+      // Hard cap all app-owned render queues plus the one xterm chunk currently
+      // parsing. Check the incoming frame too; otherwise a single large frame can
+      // jump over the cap. Dropped data is recovered from the canonical buffer.
       const queued = (this.pendingWrites?.reduce((s, w) => s + w.length, 0) || 0)
-        + (this.flickerFilterBuffer?.length || 0);
-      if (queued > 131072) { // 128KB — drop to prevent accumulation
-        // Schedule a self-recovery: reload the full terminal buffer once the
+        + (this.flickerFilterBuffer?.length || 0)
+        + (this._loadBufferQueue?.reduce((s, w) => s + w.length, 0) || 0)
+        + (this._terminalWriteInFlightBytes || 0);
+      if (queued + data.data.length > 131072) { // 128KB — drop to prevent accumulation
+        // Schedule a self-recovery once the
         // queue drains (debounced to avoid hammering the API during sustained bursts).
         if (!this._clientDropRecoveryTimer) {
           this._clientDropRecoveryTimer = setTimeout(() => {
@@ -2243,9 +2266,13 @@ class CodemanApp {
           ? 'Antigravity'
           : mode === 'pi'
             ? 'Pi'
-            : mode === 'opencode'
-              ? 'OpenCode'
-              : 'Claude';
+            : mode === 'grok'
+              ? 'Grok'
+              : mode === 'deepseek'
+                ? 'DeepSeek'
+                : mode === 'opencode'
+                  ? 'OpenCode'
+                  : 'Claude';
   }
 
   async toggleResponseViewer() {
@@ -2345,33 +2372,38 @@ class CodemanApp {
     }
   }
 
-  async _onSessionNeedsRefresh() {
+  async _onSessionNeedsRefresh(event = {}) {
     // Server sends this after SSE backpressure clears — terminal data was dropped,
     // so reload the buffer to recover from any display corruption.
-    if (!this.activeSessionId || !this.terminal) return;
+    const sessionId = this.activeSessionId;
+    if (event?.id && event.id !== sessionId) return;
+    if (!sessionId || !this.terminal) return;
     // Skip if buffer load already in progress — avoids competing clear+rewrite cycles
     if (this._isLoadingBuffer) return;
-    const sessionId = this.activeSessionId;
+    if (this._terminalRefreshOwner?.sessionId === sessionId) return;
+    const refreshOwner = { sessionId };
+    this._terminalRefreshOwner = refreshOwner;
     try {
-      // Recovery should restore the WHOLE picture, so ask for full history
-      // rather than a tail. Measured on a 900-line shell pane: the tail rewrite
-      // replaced an 869-row buffer with 158 rows, so every backpressure refresh
-      // silently destroyed most of the scrollback it was meant to repair.
-      //
-      // A repaint-mode pane is the opposite case (tmux keeps ~one frame for it),
-      // so the full capture can be SMALLER than what xterm already holds. Reuse
-      // the same downgrade guard as the scroll-to-top re-pull and fall back to
-      // the historical tail there, leaving that case exactly as it was.
-      let res = await fetch(`/api/sessions/${sessionId}/terminal?full=1`);
+      // A shell can retain a multi-megabyte/100k-line tmux history. Automatic
+      // recovery stays bounded just like normal shell selection; only the
+      // explicit "Load full history" action is allowed to pay for a full replay.
+      // TUI modes still recover the whole picture, with the downgrade guard for
+      // repaint-mode panes whose tmux capture can be smaller than xterm's buffer.
+      const useFullHistory = this.sessions.get(sessionId)?.mode !== 'shell';
+      let res = await fetch(
+        useFullHistory
+          ? `/api/sessions/${sessionId}/terminal?full=1`
+          : `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`
+      );
       let data = (await res.json())?.data ?? {};
-      if (data.terminalBuffer && this._replayWouldShrinkBuffer(data.terminalBuffer)) {
+      if (useFullHistory && data.terminalBuffer && this._replayWouldShrinkBuffer(data.terminalBuffer)) {
         res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
         data = (await res.json())?.data ?? {};
       }
       // Bail on a tab switch mid-fetch: writing here would paint this session's
       // history into the terminal the user is now looking at. The window is two
       // fetches wide in the fallback case, so this guard is not optional.
-      if (this.activeSessionId !== sessionId) return;
+      if (this.activeSessionId !== sessionId || this._terminalRefreshOwner !== refreshOwner) return;
       if (data.terminalBuffer) {
         // This refresh is SERVER-triggered, so a user quietly reading scrollback
         // did not ask for it and must not be dragged to the bottom by it (#259).
@@ -2401,6 +2433,8 @@ class CodemanApp {
       }
     } catch (err) {
       console.error('needsRefresh reload failed:', err);
+    } finally {
+      if (this._terminalRefreshOwner === refreshOwner) this._terminalRefreshOwner = null;
     }
   }
 
@@ -2563,8 +2597,8 @@ class CodemanApp {
     }
   }
 
-  // Claude plan usage limits (5-hour + weekly) — account-global, so the latest
-  // sample from any session drives the shared header chip.
+  // Claude + Codex plan usage limits — account-global, so the latest sample
+  // drives the shared header chip.
   _onSessionStatusTelemetry(data) {
     this.updatePlanUsageChip(data);
     // Persist last-known so the chip shows immediately on the next page load /
@@ -2591,9 +2625,6 @@ class CodemanApp {
     const chip = document.getElementById('planUsageChip');
     if (!chip || !data) return;
     const pct = (w) => (w && typeof w.usedPercentage === 'number' ? Math.round(w.usedPercentage) : null);
-    const five = pct(data.fiveHour);
-    const seven = pct(data.sevenDay);
-    if (five === null && seven === null) return;
     // Per-window color by how much is used up: green < 60%, yellow 60–84%, red ≥ 85%.
     const colorClass = (p) => (p >= 85 ? 'pu-red' : p >= 60 ? 'pu-yellow' : 'pu-green');
     // innerHTML here is XSS-safe ONLY because every interpolated value is a
@@ -2607,12 +2638,23 @@ class CodemanApp {
       if (!Number.isFinite(n)) return '';
       return `<span class="pu-win"><span class="pu-label">${label}</span><span class="pu-val ${colorClass(n)}">${n}%</span></span>`;
     };
-    chip.innerHTML = [seg('5h', five), seg('7d', seven)].filter(Boolean).join('<span class="pu-sep">·</span>');
+    const row = (provider, usage) => {
+      const windows = [seg('5h', pct(usage?.fiveHour)), seg('7d', pct(usage?.sevenDay))].filter(Boolean);
+      if (!windows.length) return '';
+      return `<span class="pu-row"><span class="pu-provider">${provider}</span><span class="pu-windows">${windows.join('<span class="pu-sep">·</span>')}</span></span>`;
+    };
+    const rows = [row('Claude', data), row('Codex', data.codex)].filter(Boolean);
+    chip.innerHTML = rows.length ? rows.join('') : '—';
     const resetStr = (w) => (w && w.resetAt ? new Date(w.resetAt).toLocaleString() : '—');
-    chip.title =
-      `Claude plan usage\n` +
-      `5-hour limit: ${five ?? '—'}% used (resets ${resetStr(data.fiveHour)})\n` +
-      `Weekly limit: ${seven ?? '—'}% used (resets ${resetStr(data.sevenDay)})`;
+    const details = (provider, usage) => {
+      const lines = [];
+      const five = pct(usage?.fiveHour);
+      const seven = pct(usage?.sevenDay);
+      if (five !== null) lines.push(`5-hour limit: ${five}% used (resets ${resetStr(usage.fiveHour)})`);
+      if (seven !== null) lines.push(`Weekly limit: ${seven}% used (resets ${resetStr(usage.sevenDay)})`);
+      return lines.length ? `${provider} plan usage\n${lines.join('\n')}` : '';
+    };
+    chip.title = [details('Claude', data), details('Codex', data.codex)].filter(Boolean).join('\n\n') || 'Plan usage limits';
   }
 
   // Scheduled runs
@@ -3454,11 +3496,21 @@ class CodemanApp {
     this.flickerFilterActive = false;
     // Clear pending terminal writes
     this._clearTimer('syncWaitTimeout');
+    this._clearTimer('_clientDropRecoveryTimer');
     this.pendingWrites = [];
     this.writeFrameScheduled = false;
+    // Release the one-chunk-in-flight gate with the rest of the write queue.
+    // flushPendingWrites() early-returns while this is set, so a reset that
+    // cleared everything EXCEPT this flag would leave live output permanently
+    // stalled if xterm's parse callback never lands (disposed terminal, or a
+    // throw inside the async parse). A late callback is harmless: it clears an
+    // already-clear flag and schedules a flush.
+    this._terminalWriteInFlight = false;
+    this._terminalWriteInFlightBytes = 0;
     this._isLoadingBuffer = false;
     this._loadBufferQueue = null;
     this._bufferLoadOwner = null;
+    this._terminalRefreshOwner = null;
     // Abort any in-flight chunkedTerminalWrite (SSE reconnect reloads buffers)
     this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
     // Preserve local echo overlay text across SSE reconnect — just hide until
@@ -3756,6 +3808,21 @@ class CodemanApp {
     return layout === 'sidebar' || layout === 'sidebar-rich' ? layout : 'header';
   }
 
+  resolveSessionSidebarFontSize(value) {
+    const size = Number(value);
+    // Default 12, matching the sidebar's historical 0.75rem name size: a user
+    // who never touches the slider must not get silently restyled (14 here
+    // bumped every existing sidebar install on the rail feature's release).
+    return Number.isInteger(size) && size >= 11 && size <= 18 ? size : 12;
+  }
+
+  applySessionSidebarFontSize(settings = null) {
+    const resolvedSettings = settings ?? this.loadAppSettingsFromStorage();
+    const size = this.resolveSessionSidebarFontSize(resolvedSettings?.sessionSidebarFontSize);
+    document.documentElement.style.setProperty('--session-sidebar-name-font-size', `${size}px`);
+    return size;
+  }
+
   /**
    * Reads the APPLIED layout off <html>, not the settings blob: this is called
    * per dragover event and per tab in render loops, and getSessionListLayout()
@@ -3767,6 +3834,26 @@ class CodemanApp {
     return document.documentElement.dataset.sessionList === 'sidebar';
   }
 
+  _tabOrientation() {
+    return document.documentElement.getAttribute('data-tab-orientation') === 'vertical' ? 'vertical' : 'horizontal';
+  }
+
+  /**
+   * True when the session list renders as a vertical column: the sidebar layout
+   * OR the vertical tab rail. Axis decisions (drag insertion side, active-tab
+   * scroll-into-view, floating-window anchors) must use THIS, not
+   * isSessionSidebarActive() alone — the rail leaves data-session-list at
+   * 'header', so the sidebar predicate reads a vertical rail as horizontal.
+   */
+  _isVerticalTabList() {
+    return this.isSessionSidebarActive() || this._tabOrientation() === 'vertical';
+  }
+
+  shouldInlineSessionActions() {
+    if (this.isSessionSidebarActive()) return !this.isSessionSidebarCollapsed();
+    return this._tabOrientation() === 'vertical' && !document.documentElement.classList.contains('tab-rail-compact');
+  }
+
   /**
    * True when the sidebar is showing the DETAILED rows: the home screen's
    * per-session line ("created 3d ago · working 12m") plus a status pill.
@@ -3782,6 +3869,38 @@ class CodemanApp {
     return root.dataset.sessionList === 'sidebar' && root.dataset.sidebarDetail === 'rich';
   }
 
+  /**
+   * True when the VERTICAL TAB RAIL (tabOrientation 'vertical') is showing the
+   * detailed rows: the same "created 3d ago · working 12m" line and status pill
+   * the rich sidebar and both home screens carry.
+   *
+   * A docked column is not a tab strip — that was the argument for the rich
+   * sidebar, and the rail is a docked column too, so it defaults to rich and
+   * `tabRailDetail: 'simple'` is the opt-out.
+   *
+   * The compact carve-out is not cosmetic: below 240px the rail already drops
+   * the row actions to a hover affordance, and three lines of stamps in a
+   * ~208px column ellipsize into noise. `_setTabRailWidth()` re-renders the
+   * tabs whenever that class flips, so this gate is re-read at the right moment.
+   */
+  isTabRailRich() {
+    const root = document.documentElement;
+    return (
+      root.getAttribute('data-tab-orientation') === 'vertical' &&
+      root.dataset.tabRailDetail === 'rich' &&
+      !root.classList.contains('tab-rail-compact')
+    );
+  }
+
+  /**
+   * The one gate the render paths ask: does THIS list draw detailed rows?
+   * Either vertical surface can, and neither can be on at once (the sidebar
+   * owns the tabs whenever it is active, which forces the rail off).
+   */
+  isRichTabRows() {
+    return this.isSessionSidebarRich() || this.isTabRailRich();
+  }
+
   /**
    * True where the sidebar is a MODAL off-canvas drawer over the terminal
    * instead of a docked column.
@@ -3859,17 +3978,22 @@ class CodemanApp {
    */
   applySessionListLayout() {
     const mode = this.getSessionListLayout();
+    this.applySessionSidebarFontSize();
     // 'sidebar' and 'sidebar-rich' are the same column; only row detail differs.
     const sidebar = mode === 'sidebar' || mode === 'sidebar-rich';
     const collapsed = this.isSessionSidebarCollapsed();
     const prevMode = document.documentElement.dataset.sessionList;
     const prevDetail = document.documentElement.dataset.sidebarDetail;
+    const prevCollapsed = document.documentElement.dataset.sidebar;
     const tabsEl = document.getElementById('sessionTabs');
     const headerHost = document.getElementById('sessionTabsHost');
     const sidebarList = document.getElementById('sessionSidebarList');
     if (!tabsEl || !headerHost || !sidebarList) return;
 
-    const host = sidebar ? sidebarList : headerHost;
+    const rail = document.getElementById('tabRail');
+    const railOwnsTabs =
+      !sidebar && document.documentElement.getAttribute('data-tab-orientation') === 'vertical';
+    const host = sidebar ? sidebarList : railOwnsTabs && rail ? rail : headerHost;
     if (tabsEl.parentElement !== host) host.appendChild(tabsEl);
 
     document.documentElement.dataset.sessionList = sidebar ? 'sidebar' : 'header';
@@ -3878,7 +4002,7 @@ class CodemanApp {
     // would let the sidebar CSS style a strip that has nothing to style.
     document.documentElement.dataset.sidebarDetail = mode === 'sidebar-rich' ? 'rich' : 'simple';
     document.documentElement.dataset.sidebar = collapsed ? 'collapsed' : 'expanded';
-    tabsEl.setAttribute('aria-orientation', sidebar ? 'vertical' : 'horizontal');
+    tabsEl.setAttribute('aria-orientation', host === headerHost ? 'horizontal' : 'vertical');
 
     const btn = document.getElementById('sidebarToggleBtn');
     if (btn) {
@@ -3931,7 +4055,8 @@ class CodemanApp {
     const layoutChanged =
       prevMode !== document.documentElement.dataset.sessionList ||
       prevDetail !== document.documentElement.dataset.sidebarDetail;
-    if (layoutChanged && prevTall === this._tallTabsEnabled) {
+    const collapseChanged = prevCollapsed !== document.documentElement.dataset.sidebar;
+    if ((layoutChanged || collapseChanged) && prevTall === this._tallTabsEnabled) {
       this._fullRenderSessionTabs();
     }
     // tabs-auto-wrap is measured, not derived from settings — updateTabOverflowMode()
@@ -3949,7 +4074,7 @@ class CodemanApp {
       this.showHomeSessions?.();
     }
     // Only the rich rows carry stamps that go stale with no event behind them.
-    if (this.isSessionSidebarRich()) this._startSidebarRichClock();
+    if (this.isRichTabRows()) this._startSidebarRichClock();
     else this._stopSidebarRichClock();
   }
 
@@ -4066,13 +4191,14 @@ class CodemanApp {
   }
 
   /**
-   * The per-row model for a rich sidebar row: which state the session is in,
-   * when it was first created, and how long it has been in that state.
+   * The per-row model for a rich row (detailed sidebar or vertical tab rail):
+   * which state the session is in, when it was first created, and how long it
+   * has been in that state.
    *
    * Classification is `_mobileOverviewState()` and the state duration is
    * `_mobileOverviewSince()` (both mobile-overview.js), NOT re-derived here —
-   * the sidebar, the desktop home rail and the phone overview must never
-   * disagree about what "working" means or about which stamp measures it.
+   * the sidebar, the rail, the desktop home rail and the phone overview must
+   * never disagree about what "working" means or about which stamp measures it.
    *
    * Guarded like every other cross-file consumer in this app: a stale cached
    * mobile-overview.js must degrade to a row with no meta line, not throw and
@@ -4119,7 +4245,21 @@ class CodemanApp {
       parts.push(stamp(row.since.key, row.since.at, 'for', 'tab-meta-since'));
     }
     parts.push(`<span class="tab-pill tab-pill--${escapeHtml(row.state)}">${escapeHtml(row.pill)}</span>`);
-    return `<span class="tab-meta" data-i18n-skip>${parts.join('')}</span>`;
+    // Both absolute stamps ALSO on the line itself, not only on the two items.
+    // Below 288px the rail hides `.tab-meta-created` (the `tab-rail-tight`
+    // rule), and a tooltip on a `display: none` element has no hover target —
+    // so without this the created stamp is not merely shrunk, it is gone with
+    // no way to ask for it. The pill and the gaps around the stamps are the
+    // hover targets that remain; an item's own title still wins over this one
+    // where the item is visible.
+    const lineTitle = [
+      row.createdAt ? `First created: ${new Date(row.createdAt).toLocaleString()}` : '',
+      row.since && row.since.at ? `${row.since.key}: ${new Date(row.since.at).toLocaleString()}` : '',
+    ]
+      .filter(Boolean)
+      .join('  \u00B7  ');
+    const lineTitleAttr = lineTitle ? ` title="${escapeHtml(lineTitle)}"` : '';
+    return `<span class="tab-meta"${lineTitleAttr} data-i18n-skip>${parts.join('')}</span>`;
   }
 
   /** Same formatter as both home screens, so a duration is written the same way everywhere. */
@@ -4164,7 +4304,7 @@ class CodemanApp {
   _startSidebarRichClock() {
     if (this._sidebarRichClock) return;
     this._sidebarRichClock = setInterval(() => {
-      if (!this.isSessionSidebarRich()) {
+      if (!this.isRichTabRows()) {
         this._stopSidebarRichClock();
         return;
       }
@@ -4235,12 +4375,13 @@ class CodemanApp {
       container.querySelector('.session-tab.active');
     if (!tab) return;
 
-    // Sidebar layout: the list scrolls VERTICALLY in its own scroller, so the
-    // horizontal computeTabScrollLeft math below would always no-op (scrollLeft
-    // pinned at 0). With 25+ sessions the active row is routinely below the
-    // fold; 'nearest' never scrolls when it is already visible, and only the
-    // list's own scroller moves — the drawer and document stay put.
-    if (this.isSessionSidebarActive()) {
+    // Sidebar layout AND the vertical rail: the list scrolls VERTICALLY in its
+    // own scroller, so the horizontal computeTabScrollLeft math below would
+    // always no-op (scrollLeft pinned at 0). With 25+ sessions the active row
+    // is routinely below the fold; 'nearest' never scrolls when it is already
+    // visible, and only the list's own scroller moves — drawer/rail and
+    // document stay put.
+    if (this._isVerticalTabList()) {
       tab.scrollIntoView({ block: 'nearest' });
       return;
     }
@@ -4271,12 +4412,13 @@ class CodemanApp {
 
   /**
    * Where a floating window (subagent / ultracode) attaches to its parent tab.
-   * Header strip: below the tab, connector runs vertically. Sidebar: to the
-   * RIGHT of the tab, connector runs horizontally — otherwise the window spawns
-   * on top of the sidebar and its bezier loops backwards underneath it.
+   * Header strip: below the tab, connector runs vertically. Sidebar AND the
+   * vertical rail: to the RIGHT of the tab, connector runs horizontally —
+   * otherwise the window spawns on top of the list and its bezier loops
+   * backwards underneath it.
    */
   _tabAnchor(rect) {
-    if (this.isSessionSidebarActive()) {
+    if (this._isVerticalTabList()) {
       return {
         x: rect.right,
         y: rect.top + rect.height / 2,
@@ -4379,7 +4521,7 @@ class CodemanApp {
     if (canIncremental) {
       // Read once for the whole pass, like the full-rebuild path: this touches
       // the DOM and the loop below runs for every session on every SSE tick.
-      const richRows = this.isSessionSidebarRich();
+      const richRows = this.isRichTabRows();
       // Incremental update - only modify changed properties
       for (const [id, session] of this.sessions) {
         const tab = container.querySelector(`.session-tab[data-id="${id}"]`);
@@ -4474,9 +4616,17 @@ class CodemanApp {
         const nameEl = tab.querySelector('.tab-name');
         if (nameEl) {
           const _p = parseSessionPrefix(name);
-          const _label = _p && _p.suffix ? _p.suffix : name;
-          if (nameEl.textContent !== _label) {
-            nameEl.textContent = _label;
+          if (nameEl.dataset.fullName !== name) {
+            nameEl.replaceChildren();
+            if (_p && _p.suffix) {
+              const prefix = document.createElement('span');
+              prefix.className = 'tab-name-prefix';
+              prefix.textContent = `${_p.prefix}: `;
+              nameEl.append(prefix, document.createTextNode(_p.suffix));
+            } else {
+              nameEl.textContent = name;
+            }
+            nameEl.dataset.fullName = name;
             tab.title = _p && _p.suffix
               ? (session.workingDir ? `${_p.prefix} (${session.workingDir})` : _p.prefix)
               : (session.workingDir || '');
@@ -4527,9 +4677,11 @@ class CodemanApp {
           // Need to add badge - insert before the action-icon overlay so the
           // badge stays a direct child of the tab (outside .tab-actions)
           const badgeHtml = this.renderSubagentTabBadge(id, minimizedAgents);
-          const actionsEl = tab.querySelector('.tab-actions');
+          const actionsEl = tab.querySelector(':scope > .tab-actions');
           if (actionsEl) {
             actionsEl.insertAdjacentHTML('beforebegin', badgeHtml);
+          } else {
+            tab.insertAdjacentHTML('beforeend', badgeHtml);
           }
         } else if (minimizedCount === 0 && subagentBadgeEl) {
           // Count went to 0 - remove badge
@@ -4559,11 +4711,12 @@ class CodemanApp {
     // The full-render path already redraws the connection SVG; this incremental
     // one does not, and a badge appearing widens a tab and shifts every tab after
     // it, sliding the lineage arcs off their anchors. Only pay for it when there
-    // is something anchored to tab rects: lineage arcs, or — in sidebar layout,
-    // where lineage is skipped and the edge count stays 0 — the subagent/
-    // ultracode connectors, whose rows a badge changes the HEIGHT of. Same
-    // widening as the strip-scroll listener in session-lineage.js.
-    if (this._lineageEdgeCount > 0 || this.isSessionSidebarActive()) this.updateConnectionLines();
+    // is something anchored to tab rects: lineage arcs, or — in a VERTICAL list
+    // (sidebar, where lineage is skipped and the edge count stays 0, or the
+    // rail, which can show connectors with zero lineage edges too) — the
+    // subagent/ultracode connectors, whose rows a badge changes the HEIGHT of.
+    // Same widening as the strip-scroll listener in session-lineage.js.
+    if (this._lineageEdgeCount > 0 || this._isVerticalTabList()) this.updateConnectionLines();
 
     this.applySidebarFilter(this._sidebarFilter);
   }
@@ -4587,6 +4740,17 @@ class CodemanApp {
     const defaults = this.getDefaultSettings();
     const manualTwoRows = deviceType === 'desktop' ? (settings.tabTwoRows ?? defaults.tabTwoRows ?? false) : false;
 
+    const orientation = window.CodemanTabOverflow?.resolveTabOrientation
+      ? window.CodemanTabOverflow.resolveTabOrientation({
+          deviceType,
+          setting: settings.tabOrientation ?? defaults.tabOrientation ?? 'horizontal',
+        })
+      : 'horizontal';
+    if (orientation === 'vertical') {
+      container.classList.remove('tabs-auto-wrap');
+      return;
+    }
+
     if (manualTwoRows || deviceType !== 'desktop') {
       container.classList.remove('tabs-auto-wrap');
       return;
@@ -4627,6 +4791,7 @@ class CodemanApp {
   }
 
   _fullRenderSessionTabs() {
+    this.closeTabRailActionMenu?.();
     if (this._inlineRenameActive) return;
     const container = this.$('sessionTabs');
 
@@ -4665,9 +4830,9 @@ class CodemanApp {
     // into view replaces it.
     const parts = [];
     const tabOrder = this.sessionOrder;
-    // Read once, not per session: isSessionSidebarRich() touches the DOM and
+    // Read once, not per session: isRichTabRows() touches the DOM and
     // this loop runs for every tab on every full rebuild.
-    const richRows = this.isSessionSidebarRich();
+    const richRows = this.isRichTabRows();
     let _tabIdx = 0;
     for (const id of tabOrder) {
       const session = this.sessions.get(id);
@@ -4704,14 +4869,17 @@ class CodemanApp {
       // JUST the description on the tab; the generated w<n>-<case> id moves to the
       // tooltip and stays visible in the session settings modal.
       const parsedName = parseSessionPrefix(name);
-      const tabLabel = parsedName && parsedName.suffix ? parsedName.suffix : name;
+      const tabLabel = parsedName && parsedName.suffix
+        ? `<span class="tab-name-prefix">${escapeHtml(parsedName.prefix)}: </span>${escapeHtml(parsedName.suffix)}`
+        : escapeHtml(name);
       const tabTooltip = parsedName && parsedName.suffix
         ? (session.workingDir ? `${parsedName.prefix} (${session.workingDir})` : parsedName.prefix)
         : (session.workingDir || '');
 
-      // Rich sidebar rows only: the home screen's created/state stamps and a
-      // status pill. richRow is null in every other layout, and both helpers
-      // below collapse to '' — the header strip's markup is unchanged.
+      // Rich rows only (the detailed sidebar OR the vertical tab rail): the home
+      // screen's created/state stamps and a status pill. richRow is null in every
+      // other layout, and both helpers below collapse to '' — the header strip's
+      // markup is unchanged.
       const richRow = richRows ? this._sidebarRichRow(id, session) : null;
       const richMeta = this._sidebarRichMetaHTML(richRow);
       const richClass = richRow ? ` tab-state-${richRow.state}` : '';
@@ -4719,14 +4887,18 @@ class CodemanApp {
         ? ` data-tab-state="${richRow.state}" data-tab-meta-sig="${richRow.state}:${richRow.since ? richRow.since.at : 0}:${richRow.createdAt}"`
         : '';
 
+      const inlineSessionActions = this.shouldInlineSessionActions();
+      const tabActionsHtml = `<span class="tab-actions"><span class="tab-gear" onclick="event.stopPropagation(); app.openSessionOptions(${escapeHtml(JSON.stringify(id))})" title="Session options" aria-label="Session options" tabindex="0">&#x2699;</span><span class="tab-detach" onclick="event.stopPropagation(); app.detachSession(${escapeHtml(JSON.stringify(id))})" title="Open in a new window" aria-label="Open session in a new window" tabindex="0">&#x29C9;</span><span class="tab-close" onclick="event.stopPropagation(); app.requestCloseSession(${escapeHtml(JSON.stringify(id))})" title="Close session" aria-label="Close session" tabindex="0">&times;</span><button type="button" class="tab-more" onclick="event.stopPropagation(); app.openTabRailActionMenu(event, ${escapeHtml(JSON.stringify(id))})" title="Session actions" aria-label="Session actions">&#x22EF;</button></span>`;
+
       parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${richClass}${loadState ? ' tab-loading' : ''}${this.hasTabDetachOverride(id) ? ' tab-show-detach' : ''}"${richData} data-id="${id}" data-color="${color}" ${loadState ? `data-load-phase="${escapeHtml(loadState.phase)}"` : ''} onclick="app.handleSessionTabClick(event, ${escapeHtml(JSON.stringify(id))})" oncontextmenu="event.preventDefault(); app.startInlineRename(${escapeHtml(JSON.stringify(id))})" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-busy="${loadState ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${tabTooltip ? `title="${escapeHtml(tabTooltip)}"` : ''}>
           ${_tabIdx < 9 ? '<span class="tab-number">' + (_tabIdx + 1) + '</span>' : ''}
           ${loadState ? '<span class="tab-load-spinner" aria-hidden="true"></span>' : ''}
           <span class="tab-status ${status}" aria-hidden="true"></span>
           <span class="tab-info">
             <span class="tab-name-row">
-              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : mode === 'antigravity' ? '<span class="tab-mode antigravity" aria-hidden="true">ag</span>' : mode === 'pi' ? '<span class="tab-mode pi" aria-hidden="true">pi</span>' : ''}
-              <span class="tab-name" data-session-id="${id}">${escapeHtml(tabLabel)}</span>
+              ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : mode === 'antigravity' ? '<span class="tab-mode antigravity" aria-hidden="true">ag</span>' : mode === 'pi' ? '<span class="tab-mode pi" aria-hidden="true">pi</span>' : mode === 'grok' ? '<span class="tab-mode grok" aria-hidden="true">gk</span>' : mode === 'deepseek' ? '<span class="tab-mode deepseek" aria-hidden="true">ds</span>' : ''}
+              <span class="tab-name" data-session-id="${id}" data-full-name="${escapeHtml(name)}">${tabLabel}</span>
+              ${inlineSessionActions ? tabActionsHtml : ''}
               <span class="tab-detached-badge" aria-hidden="true">detached</span>
             </span>
             ${showFolder ? `<span class="tab-folder">\u{1F4C1} ${escapeHtml(folderName)}</span>` : ''}
@@ -4735,7 +4907,7 @@ class CodemanApp {
           ${hasRunningTasks ? `<span class="tab-badge" onclick="event.stopPropagation(); app.toggleTaskPanel()" aria-label="${taskStats.running} running tasks">${taskStats.running}</span>` : ''}
           ${subagentBadge}
           ${ultracodeBadge}
-          <span class="tab-actions"><span class="tab-gear" onclick="event.stopPropagation(); app.openSessionOptions(${escapeHtml(JSON.stringify(id))})" title="Session options" aria-label="Session options" tabindex="0">&#x2699;</span><span class="tab-detach" onclick="event.stopPropagation(); app.detachSession(${escapeHtml(JSON.stringify(id))})" title="Open in a new window" aria-label="Open session in a new window" tabindex="0">&#x29C9;</span><span class="tab-close" onclick="event.stopPropagation(); app.requestCloseSession(${escapeHtml(JSON.stringify(id))})" title="Close session" aria-label="Close session" tabindex="0">&times;</span></span>
+          ${inlineSessionActions ? '' : tabActionsHtml}
         </div>`);
       _tabIdx++;
     }
@@ -4958,9 +5130,9 @@ class CodemanApp {
         // inside the handler — these listeners survive a layout flip between
         // renders, so capturing the axis at bind time would go stale.
         // drag-over-left/-right keep their names and now read as before/after;
-        // the sidebar CSS just draws them as top/bottom edges.
+        // the sidebar/rail CSS just draws them as top/bottom edges.
         const rect = tab.getBoundingClientRect();
-        const insertBefore = this.isSessionSidebarActive()
+        const insertBefore = this._isVerticalTabList()
           ? e.clientY < rect.top + rect.height / 2
           : e.clientX < rect.left + rect.width / 2;
 
@@ -4984,7 +5156,7 @@ class CodemanApp {
 
         // Determine insertion position (same axis rule as the dragover handler)
         const rect = tab.getBoundingClientRect();
-        const insertBefore = this.isSessionSidebarActive()
+        const insertBefore = this._isVerticalTabList()
           ? e.clientY < rect.top + rect.height / 2
           : e.clientX < rect.left + rect.width / 2;
 
@@ -5202,11 +5374,20 @@ class CodemanApp {
     this._tabCompletionBaseText = null;
     this._clearTimer('_tabCompletionFallback');
     this._clearTimer('_clientDropRecoveryTimer');
+    this._terminalRefreshOwner = null;
 
     // Clean up pending terminal writes to prevent old session data from appearing in new session
     this._clearTimer('syncWaitTimeout');
     this.pendingWrites = [];
     this.writeFrameScheduled = false;
+    // Release the one-chunk-in-flight gate with the rest of the write queue.
+    // flushPendingWrites() early-returns while this is set, so a reset that
+    // cleared everything EXCEPT this flag would leave live output permanently
+    // stalled if xterm's parse callback never lands (disposed terminal, or a
+    // throw inside the async parse). A late callback is harmless: it clears an
+    // already-clear flag and schedules a flush.
+    this._terminalWriteInFlight = false;
+    this._terminalWriteInFlightBytes = 0;
     this._isLoadingBuffer = false;
     this._loadBufferQueue = null;
     this._bufferLoadOwner = null;
@@ -5520,8 +5701,11 @@ class CodemanApp {
       this._clearTimer('syncWaitTimeout');
       this.pendingWrites = [];
       this.writeFrameScheduled = false;
+      this._terminalWriteInFlight = false;
+      this._terminalWriteInFlightBytes = 0;
       this._isLoadingBuffer = false;
       this._loadBufferQueue = null;
+      this._terminalRefreshOwner = null;
       this._chunkedWriteGen = (this._chunkedWriteGen || 0) + 1;
       this.activeSessionId = null;
     }
@@ -5552,6 +5736,7 @@ class CodemanApp {
 
     this._cleanupPreviousSession(sessionId);
     this.activeSessionId = sessionId;
+    this._activateFileBrowserSession?.(sessionId);
     // Repaint the partial-history banner for the tab being switched TO. The
     // replay paths refresh it when their fetch lands; without this the previous
     // session's notice stays on screen until then (#258).
@@ -6025,6 +6210,7 @@ class CodemanApp {
 
   // Shared cleanup for all session data — called from both closeSession() and session:deleted handler
   _cleanupSessionData(sessionId) {
+    this.closeTabRailActionMenu?.();
     // If the deleted session is currently being renamed, abort the rename
     // so the inline <input> doesn't ghost as a stale tab on screen.
     if (this._activeRename?.sessionId === sessionId) {
@@ -6154,7 +6340,11 @@ class CodemanApp {
               ? 'Kill Tmux & Antigravity'
               : session.mode === 'pi'
                 ? 'Kill Tmux & Pi'
-                : 'Kill Tmux & Claude Code';
+                : session.mode === 'grok'
+                  ? 'Kill Tmux & Grok'
+                  : session.mode === 'deepseek'
+                    ? 'Kill Tmux & DeepSeek'
+                    : 'Kill Tmux & Claude Code';
     }
 
     document.getElementById('closeConfirmModal').classList.add('active');

src/web/public/constants.js

@@ -10,7 +10,7 @@
  * @globals {function} scheduleBackground - scheduler.postTask wrapper (background priority)
  * @globals {function} getEventCoords - Unified mouse/touch coordinate extractor
  * @globals {function} escapeHtml - XSS-safe HTML escaping
- * @globals {object} SSE_EVENTS - Centralized SSE event type constants (120 event types; must match backend src/web/sse-events.ts)
+ * @globals {object} SSE_EVENTS - Centralized SSE event type constants (156 event types; must match backend src/web/sse-events.ts)
  * @globals {Array} BUILTIN_RESPAWN_PRESETS - Built-in respawn configuration presets
  *
  * @dependency None (first in load order)
@@ -156,6 +156,48 @@ function shouldAutoWrapTabs(input) {
   return scrollWidth > clientWidth + 1;
 }
 
+function resolveTabOrientation(input) {
+  if (!input || input.setting !== 'vertical') return 'horizontal';
+  if (input.deviceType === 'mobile') return 'horizontal';
+  return 'vertical';
+}
+
+const TAB_RAIL_MIN_WIDTH = 208;
+const TAB_RAIL_DEFAULT_WIDTH = 256;
+/** Detailed rows carry a third line, and it ellipsizes at 256px — see the
+    rich sidebar's own 300px column. 320px is the existing Wide preset. */
+const TAB_RAIL_RICH_DEFAULT_WIDTH = 320;
+const TAB_RAIL_MAX_WIDTH = 360;
+
+function resolveTabRailWidth(input = {}) {
+  const viewportWidth = Number(input.viewportWidth);
+  const mainWidth = Number(input.mainWidth);
+  const minTerminalWidth = Number(input.minTerminalWidth);
+  const limits = [TAB_RAIL_MAX_WIDTH];
+  if (Number.isFinite(viewportWidth) && viewportWidth > 0) limits.push(Math.floor(viewportWidth * 0.4));
+  if (Number.isFinite(mainWidth) && mainWidth > 0 && Number.isFinite(minTerminalWidth) && minTerminalWidth > 0) {
+    limits.push(Math.floor(mainWidth - minTerminalWidth));
+  }
+  const effectiveMax = Math.max(TAB_RAIL_MIN_WIDTH, Math.min(...limits));
+  const requested = Number(input.width);
+  const width = Number.isFinite(requested) ? requested : TAB_RAIL_DEFAULT_WIDTH;
+  return Math.round(Math.min(effectiveMax, Math.max(TAB_RAIL_MIN_WIDTH, width)));
+}
+
+function resolveTabRailKeyboardWidth(input = {}) {
+  let width;
+  if (input.key === 'Home') width = TAB_RAIL_MIN_WIDTH;
+  else if (input.key === 'End') width = TAB_RAIL_MAX_WIDTH;
+  // Enter resets to the caller's effective default (the rich rail's is the
+  // Wide preset, not 256 — see _defaultTabRailWidth); absent, the base default.
+  else if (input.key === 'Enter') width = Number(input.defaultWidth) || TAB_RAIL_DEFAULT_WIDTH;
+  else if (input.key === 'ArrowLeft' || input.key === 'ArrowRight') {
+    const direction = input.key === 'ArrowLeft' ? -1 : 1;
+    width = (Number(input.currentWidth) || TAB_RAIL_DEFAULT_WIDTH) + direction * (input.shiftKey ? 32 : 8);
+  } else return null;
+  return resolveTabRailWidth({ ...input, width });
+}
+
 // Sliver of the neighbouring tab left visible when the strip scrolls a tab into
 // view. Landing a tab flush against the edge reads as "this is the last one";
 // the gap is what tells the user there is more strip to swipe to.
@@ -243,6 +285,9 @@ const LINEAGE_DIP_MAX_PX = 64;
 // apart bled into one thick band instead of reading as three separate lines.
 const LINEAGE_SIBLING_STEP_PX = 8;
 const LINEAGE_STRIP_TOLERANCE_PX = 4;
+const LINEAGE_VERTICAL_TRACK_INSET_PX = 6;
+const LINEAGE_VERTICAL_SIBLING_STEP_PX = 3;
+const LINEAGE_VERTICAL_ANCHOR_CLEARANCE_PX = 4;
 // Lineage palette, assigned per SPAWNING TAB in first-seen order and cycled
 // (session-lineage.js). Every arc leaving one tab shares its colour however many
 // workers it spawns; a child that spawns in turn gets its own for the arcs below it.
@@ -265,21 +310,44 @@ function computeLineagePath(input) {
   const ch = Number(child.height) || 0;
   if (pw <= 0 || ph <= 0 || cw <= 0 || ch <= 0) return null;
 
-  const px = Number(parent.left) + pw / 2;
-  const cx = Number(child.left) + cw / 2;
-  if (!Number.isFinite(px) || !Number.isFinite(cx)) return null;
-
+  const orientation = input?.orientation === 'vertical' ? 'vertical' : 'horizontal';
   const strip = input?.strip;
+  const depth = Math.max(0, Math.min(6, Number(input?.depth) || 0));
+  const pLeft = Number(parent.left);
+  const cLeft = Number(child.left);
+  const pTop = Number(parent.top);
+  const cTop = Number(child.top);
+  if (![pLeft, cLeft, pTop, cTop].every(Number.isFinite)) return null;
+
+  if (orientation === 'vertical') {
+    const py = pTop + ph / 2;
+    const cy = cTop + ch / 2;
+    if (strip && Number(strip.height) > 0) {
+      const min = Number(strip.top) - LINEAGE_STRIP_TOLERANCE_PX;
+      const max = Number(strip.top) + Number(strip.height) + LINEAGE_STRIP_TOLERANCE_PX;
+      if (py < min || py > max || cy < min || cy > max) return null;
+    }
+
+    const stripLeft =
+      strip && Number.isFinite(Number(strip.left))
+        ? Number(strip.left)
+        : Math.min(pLeft, cLeft) - LINEAGE_VERTICAL_TRACK_INSET_PX * 2;
+    const requestedTrack =
+      stripLeft + LINEAGE_VERTICAL_TRACK_INSET_PX + depth * LINEAGE_VERTICAL_SIBLING_STEP_PX;
+    const trackX = Math.min(requestedTrack, Math.min(pLeft, cLeft) - LINEAGE_VERTICAL_ANCHOR_CLEARANCE_PX);
+    const d = `M ${r1(pLeft)} ${r1(py)} H ${r1(trackX)} V ${r1(cy)} H ${r1(cLeft)}`;
+    return { d, endX: cLeft, endY: cy, sameRow: false };
+  }
+
+  const px = pLeft + pw / 2;
+  const cx = cLeft + cw / 2;
   if (strip && Number(strip.width) > 0) {
     const min = Number(strip.left) - LINEAGE_STRIP_TOLERANCE_PX;
     const max = Number(strip.left) + Number(strip.width) + LINEAGE_STRIP_TOLERANCE_PX;
     if (px < min || px > max || cx < min || cx > max) return null;
   }
 
-  const depth = Math.max(0, Math.min(6, Number(input?.depth) || 0));
-  const pTop = Number(parent.top);
   const pBottom = pTop + ph;
-  const cTop = Number(child.top);
   const cBottom = cTop + ch;
   const sameRow = Math.abs(pTop + ph / 2 - (cTop + ch / 2)) <= Math.min(ph, ch) / 2;
 
@@ -617,9 +685,18 @@ if (typeof window !== 'undefined') {
   window.shouldSkipWebGL = shouldSkipWebGL;
   window.CodemanTabOverflow = {
     shouldAutoWrapTabs,
+    resolveTabOrientation,
     computeTabScrollLeft,
     TAB_SCROLL_REVEAL_PX,
   };
+  window.CodemanTabRail = {
+    DEFAULT_WIDTH: TAB_RAIL_DEFAULT_WIDTH,
+    RICH_DEFAULT_WIDTH: TAB_RAIL_RICH_DEFAULT_WIDTH,
+    MIN_WIDTH: TAB_RAIL_MIN_WIDTH,
+    MAX_WIDTH: TAB_RAIL_MAX_WIDTH,
+    resolveWidth: resolveTabRailWidth,
+    resolveKeyboardWidth: resolveTabRailKeyboardWidth,
+  };
   window.CodemanWsReconnect = {
     plan: planWsReconnect,
   };
@@ -628,6 +705,8 @@ if (typeof window !== 'undefined') {
     DIP_MIN_PX: LINEAGE_DIP_MIN_PX,
     DIP_MAX_PX: LINEAGE_DIP_MAX_PX,
     SIBLING_STEP_PX: LINEAGE_SIBLING_STEP_PX,
+    VERTICAL_TRACK_INSET_PX: LINEAGE_VERTICAL_TRACK_INSET_PX,
+    VERTICAL_SIBLING_STEP_PX: LINEAGE_VERTICAL_SIBLING_STEP_PX,
     COLORS: LINEAGE_COLORS,
   };
   window.CodemanConnectionLoss = {
@@ -876,6 +955,7 @@ const SSE_EVENTS = {
   HOOK_ELICITATION_COMPLETE: 'hook:elicitation_complete',
   HOOK_ELICITATION_RESPONSE: 'hook:elicitation_response',
   HOOK_STOP: 'hook:stop',
+  HOOK_AGENT_WORKING: 'hook:agent_working',
   HOOK_TEAMMATE_IDLE: 'hook:teammate_idle',
   HOOK_TASK_COMPLETED: 'hook:task_completed',
 
@@ -969,6 +1049,7 @@ const SSE_EVENTS = {
 
   // Web tabs (dashboard URLs)
   WEBVIEW_CHANGED: 'webview:changed',
+  TAB_LAYOUT_CHANGED: 'tab:layoutChanged',
 };
 
 // ═══════════════════════════════════════════════════════════════

src/web/public/home-sessions.js

@@ -78,6 +78,8 @@ const HOME_SESSIONS_MODE_BADGE = {
   gemini: 'gm',
   antigravity: 'ag',
   pi: 'pi',
+  grok: 'gk',
+  deepseek: 'ds',
 };
 
 Object.assign(CodemanApp.prototype, {
@@ -87,12 +89,14 @@ Object.assign(CodemanApp.prototype, {
 
   /**
    * Width-driven, like every other layout decision in the app. Explicitly yields
-   * to the phone overview: that surface already lists the same sessions, and two
-   * lists of the same thing on one screen is worse than none.
+   * to the phone overview and persistent vertical tab rail: those surfaces already
+   * list the same sessions, and two lists of the same thing on one screen is worse
+   * than none.
    */
   shouldShowHomeSessions() {
     if (this.isSoloWindow) return false;
     if (this.shouldUseMobileOverview?.()) return false;
+    if (document.documentElement.getAttribute('data-tab-orientation') === 'vertical') return false;
     // The sidebar layout already docks the full session list flush left at full
     // height — the rail would render the same list right next to it (and z-wise
     // UNDER it: sidebar 11, welcome overlay 10, rail inside the overlay).

src/web/public/i18n.js

@@ -109,6 +109,8 @@
     'Run Gemini': '运行 Gemini',
     'Run Antigravity': '运行 Antigravity',
     'Run Pi': '运行 Pi',
+    'Run Grok': '运行 Grok',
+    'Run DeepSeek': '运行 DeepSeek',
     'Run Shell': '运行 Shell',
     'Select AI backend': '选择 AI 后端',
     'Create New Case': '新建案例',
@@ -232,6 +234,8 @@
     'Redraw Terminal Button': '重绘终端按钮',
     'Tab Bar': '标签栏',
     'Session List Layout': '会话列表布局',
+    'Session Name Font Size': '会话名称字体大小',
+    'Adjust only session names in the vertical sidebar.': '仅调整垂直侧边栏中的会话名称。',
     'Header tab strip': '顶栏标签条',
     'Left sidebar': '左侧边栏',
     'Left sidebar simple': '左侧边栏（简洁）',

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 L=JSON.parse(localStorage.getItem(k)||'{}').sessionListLayout;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';}catch(e){document.documentElement.dataset.sessionList='header';document.documentElement.dataset.sidebarDetail='simple';document.documentElement.dataset.sidebar='expanded';}</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';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';}</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)}
@@ -192,7 +192,7 @@
         <button class="btn-icon-header btn-file-viewer" onclick="app.toggleFileBrowserButton()" title="File Viewer" aria-label="Open file viewer" aria-expanded="false"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
         <button class="btn-icon-header btn-ultracode-agents btn-ultracode-agents--hidden" onclick="app.toggleUltracodeAgentsPanel()" title="Ultracode / Workflow agents" aria-label="Open ultracode workflow agents"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><path d="M8.2 7.2 15.6 11M8.2 16.8 15.6 13"/></svg></button>
-        <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude plan usage limits">—</div>
+        <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude and Codex plan usage limits">—</div>
         <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
           <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="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
           <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
@@ -358,6 +358,20 @@
 
     <!-- Main Terminal Area -->
     <main class="main">
+      <aside class="tab-rail" id="tabRail" aria-label="Session navigation">
+        <div
+          id="tabRailResizeHandle"
+          class="tab-rail-resize-handle"
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize session rail"
+          aria-valuemin="208"
+          aria-valuemax="360"
+          aria-valuenow="256"
+          tabindex="0"
+        ></div>
+      </aside>
+
       <!-- Collapsible session sidebar (opt-in layout). Deliberately EMPTY in
            markup: applySessionListLayout() moves #sessionTabs in here, so the
            vertical list is the exact same DOM node as the header strip and every
@@ -430,6 +444,14 @@
               <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
               Run Pi
             </button>
+            <button class="welcome-btn welcome-btn-grok" id="welcomeGrokBtn" style="display: none;" onclick="app.setRunMode('grok'); app.runGrok()">
+              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+              Run Grok
+            </button>
+            <button class="welcome-btn welcome-btn-deepseek" id="welcomeDeepSeekBtn" style="display: none;" onclick="app.setRunMode('deepseek'); app.runDeepSeek()">
+              <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+              Run DeepSeek
+            </button>
           </div>
           <div class="welcome-qr" id="welcomeQr" onclick="app.toggleWelcomeQrSize()">
             <div class="welcome-qr-inner" id="welcomeQrInner"></div>
@@ -509,6 +531,7 @@
            desktop (which never loads mobile.css) can never render it. -->
       <div class="mobile-overview" id="mobileOverview" hidden></div>
     </main>
+    <div class="tab-rail-resize-shield" id="tabRailResizeShield" aria-hidden="true" hidden></div>
 
     <!-- Project Insights Panel (shows file-viewing Bash commands) -->
     <div class="project-insights-panel" id="projectInsightsPanel">
@@ -548,6 +571,7 @@
           <div class="file-preview-actions">
             <button class="btn-icon-sm file-preview-edit-btn" id="filePreviewEditBtn" onclick="app.enterFilePreviewEdit()" title="Edit file" aria-label="Edit file" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5z"/></svg></button>
             <button class="btn-icon-sm" onclick="app.copyFilePreviewContent()" title="Copy content">&#x2398;</button>
+            <button class="btn-icon-sm" id="filePreviewDetachBtn" onclick="app.detachFilePreview()" title="Open in new tab" aria-label="Open in new tab" hidden><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg></button>
             <button class="btn-icon-sm" onclick="app.closeFilePreview()" title="Close">&times;</button>
           </div>
         </div>
@@ -607,6 +631,18 @@
               <button class="run-mode-option" data-mode="pi" onclick="app.setRunMode('pi')">
                 <span class="run-mode-dot pi"></span>Pi
               </button>
+              <button class="run-mode-option" data-mode="grok" onclick="app.setRunMode('grok')">
+                <span class="run-mode-dot grok"></span>Grok
+              </button>
+              <button class="run-mode-option" data-mode="deepseek" onclick="app.setRunMode('deepseek')">
+                <span class="run-mode-dot deepseek"></span>DeepSeek
+              </button>
+              <!-- Shown only when `dsh` is installed but no pane-capable profile is:
+                   DeepSeek ships no terminal front door, so the fix is an install,
+                   not a greyed-out entry the user cannot act on. -->
+              <button class="run-mode-option run-mode-option-install" data-action="deepseek-install" id="runModeDeepSeekInstall" style="display: none;" onclick="app.installDeepSeekProfile()">
+                <span class="run-mode-dot deepseek"></span>DeepSeek — add a terminal profile…
+              </button>
               <div class="run-mode-sep"></div>
               <button class="run-mode-option" data-mode="shell" onclick="app.setRunMode('shell')">
                 <span class="run-mode-dot shell"></span>Terminal / Shell
@@ -619,6 +655,14 @@
               <button class="run-mode-option run-mode-option--add" onclick="app.showWebviewModal()">
                 <span class="run-mode-dot web"></span>Add URL&hellip;
               </button>
+              <!-- The DeepSeek Harness browser UI is the vendor's OWN interactive
+                   surface (the terminal one is third-party), so it gets a shortcut:
+                   POST /api/deepseek/web starts a background `dsh web` fenced to
+                   this origin, and the URL opens as a managed web tab.
+                   Shown only when dsh is installed. -->
+              <button class="run-mode-option run-mode-option--web" id="runModeDeepSeekWeb" style="display: none;" onclick="app.runDeepSeekWeb()">
+                <span class="run-mode-dot deepseek"></span>DeepSeek web UI&hellip;
+              </button>
               <div class="run-mode-sep"></div>
               <div class="run-mode-header">Recent Sessions</div>
               <div class="run-mode-history" id="runModeHistory"></div>
@@ -884,6 +928,8 @@
                 <option value="gemini">Gemini</option>
                 <option value="antigravity">Antigravity</option>
                 <option value="pi">Pi</option>
+                <option value="grok">Grok</option>
+                <option value="deepseek">DeepSeek</option>
               </select>
             </div>
             <div class="form-row"><label>Working Directory</label><input type="text" id="schWorkingDir" placeholder="/absolute/path"></div>
@@ -1869,6 +1915,39 @@
               <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 orientation horizontal vertical side rail">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Tab Orientation</span>
+                      <span class="set-row-desc">Keep tabs in the header or place them beside the terminal. Phones stay horizontal.</span>
+                    </div>
+                    <select id="appSettingsTabOrientation" class="set-select">
+                      <option value="horizontal">Horizontal (top)</option>
+                      <option value="vertical">Vertical (side rail)</option>
+                    </select>
+                  </div>
+                  <div class="set-row has-field" data-search="tab rail detail rows created working idle status pill simple">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Vertical Rail Rows</span>
+                      <span class="set-row-desc">Detailed rows carry the home screen's per-session line (created, how long it has been working or idle) and a status pill. Needs ~280px of rail; a rail narrower than 240px drops back to simple rows.</span>
+                    </div>
+                    <select id="appSettingsTabRailDetail" class="set-select">
+                      <option value="rich">Detailed</option>
+                      <option value="simple">Simple (name only)</option>
+                    </select>
+                  </div>
+                  <div class="set-row has-field" data-search="tab rail width resize compact wide maximum">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Vertical Rail Width</span>
+                      <span class="set-row-desc">Set the preferred rail width for this device.</span>
+                    </div>
+                    <select id="appSettingsTabRailWidth" class="set-select">
+                      <option value="208">Compact (208px)</option>
+                      <option value="256">Default (256px)</option>
+                      <option value="320">Wide (320px)</option>
+                      <option value="360">Maximum (360px)</option>
+                      <option value="custom" disabled>Custom</option>
+                    </select>
+                  </div>
                   <div class="set-row has-field" data-search="session list layout sidebar tab strip vertical">
                     <div class="set-row-text">
                       <span class="set-row-label">Session List Layout</span>
@@ -1880,6 +1959,18 @@
                       <option value="sidebar-rich">Left sidebar</option>
                     </select>
                   </div>
+                  <div class="set-row has-field" data-search="session sidebar name font size text">
+                    <div class="set-row-text">
+                      <span class="set-row-label" id="appSettingsSessionSidebarFontSizeLabel">Session Name Font Size</span>
+                      <span class="set-row-desc">Adjust only session names in the vertical sidebar.</span>
+                    </div>
+                    <label class="set-range-field" for="appSettingsSessionSidebarFontSize">
+                      <input type="range" id="appSettingsSessionSidebarFontSize" min="11" max="18" step="1" value="12"
+                        aria-labelledby="appSettingsSessionSidebarFontSizeLabel"
+                        oninput="document.getElementById('appSettingsSessionSidebarFontSizeValue').textContent=this.value+' px'">
+                      <output id="appSettingsSessionSidebarFontSizeValue" for="appSettingsSessionSidebarFontSize">12 px</output>
+                    </label>
+                  </div>
                   <div class="set-row" data-search="tall tabs folder name two rows">
                     <div class="set-row-text">
                       <span class="set-row-label">Tall Tabs</span>
@@ -2616,6 +2707,8 @@
                 <option value="opencode" data-cli="opencode">OpenCode</option>
                 <option value="antigravity" data-cli="antigravity">Antigravity</option>
                 <option value="pi" data-cli="pi">Pi</option>
+                <option value="grok" data-cli="grok">Grok</option>
+                <option value="deepseek" data-cli="deepseek">DeepSeek</option>
                 <option value="shell">Shell (no agent)</option>
               </select>
               <span class="form-hint">Which CLI to point the Run button at once the clone finishes. Changeable any time from the Run dropdown.</span>
@@ -2756,7 +2849,7 @@
             <div class="form-row">
               <label>Image</label>
               <input type="text" id="dockerImage" placeholder="codeman/agent:base" autocomplete="off" autocapitalize="off" spellcheck="false">
-              <span class="form-hint">Build it once with <code>node scripts/build-agent-image.mjs</code>. Contains node + claude/codex/gemini/opencode/agy/pi + tmux.</span>
+              <span class="form-hint">Build it once with <code>node scripts/build-agent-image.mjs</code>. Contains node + claude/codex/gemini/opencode/agy/pi/grok/dsh + tmux.</span>
             </div>
             <div class="form-row">
               <label>Network</label>
@@ -3323,6 +3416,7 @@
   <!-- Hardened markdown HTML sanitizer (wires DOMPurify). Must precede app.js. -->
   <script defer src="sanitize-html.js"></script>
   <script defer src="app.js"></script>
+  <script defer src="tab-rail-resize.js"></script>
   <script defer src="terminal-ui.js"></script>
   <script defer src="respawn-ui.js"></script>
   <script defer src="ralph-panel.js"></script>

src/web/public/mobile-overview.js

@@ -54,6 +54,8 @@ const MOBILE_OVERVIEW_RUN_MODES = [
   { mode: 'gemini', label: 'Gemini', short: 'Gemini' },
   { mode: 'antigravity', label: 'Antigravity', short: 'Antigravity' },
   { mode: 'pi', label: 'Pi', short: 'Pi' },
+  { mode: 'grok', label: 'Grok', short: 'Grok' },
+  { mode: 'deepseek', label: 'DeepSeek', short: 'DeepSeek' },
   { mode: 'shell', label: 'Terminal / Shell', short: 'Shell' },
 ];
 
@@ -579,6 +581,11 @@ Object.assign(CodemanApp.prototype, {
     menu.appendChild(header);
 
     for (const webview of this.webviews ? this.webviews.values() : []) {
+      // Managed records are Codeman-owned shortcut state (the DeepSeek web UI
+      // writes one), not saved dashboards: same filter as the desktop run menu,
+      // or the phone picker lists a stale 127.0.0.1:<port> row that dies on the
+      // next server restart with no affordance here to restart it.
+      if (webview.managed) continue;
       const option = document.createElement('button');
       option.type = 'button';
       option.className = 'mobile-overview-run-option';

src/web/public/mobile.css

@@ -972,6 +972,37 @@ html.mobile-init .file-browser-panel {
     border-color: rgba(244, 114, 182, 0.5) !important;
   }
 
+  /* Grok mode colors on mobile. Same `!important` rationale as the pi block above. */
+  .btn-toolbar.btn-run.mode-grok,
+  .btn-toolbar.btn-run-gear.mode-grok {
+    background: #1c1c1f !important;
+    border-color: rgba(212, 212, 216, 0.3) !important;
+    color: #f4f4f5 !important;
+  }
+
+  .btn-toolbar.btn-run.mode-grok:active,
+  .btn-toolbar.btn-run-gear.mode-grok:active {
+    background: #3f3f46 !important;
+    border-color: rgba(212, 212, 216, 0.5) !important;
+  }
+
+  /* DeepSeek mode colors on mobile. Same `!important` rationale as the pi and
+     grok blocks above: styles.css nests its skin rules inside
+     `html:not([data-skin="og"])`, so a bare `.btn-toolbar` rule there outranks a
+     `.btn-toolbar.btn-x` rule here regardless of load order. */
+  .btn-toolbar.btn-run.mode-deepseek,
+  .btn-toolbar.btn-run-gear.mode-deepseek {
+    background: #16225f !important;
+    border-color: rgba(124, 147, 255, 0.35) !important;
+    color: #eef2ff !important;
+  }
+
+  .btn-toolbar.btn-run.mode-deepseek:active,
+  .btn-toolbar.btn-run-gear.mode-deepseek:active {
+    background: #3350e6 !important;
+    border-color: rgba(150, 170, 255, 0.55) !important;
+  }
+
   /* Run mode dropdown menu — positioned above toolbar on mobile */
   .run-mode-menu {
     bottom: 100%;
@@ -3055,6 +3086,18 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
   color: #ffffff;
 }
 
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-grok, .btn-toolbar.btn-run-gear.mode-grok) {
+  background: linear-gradient(135deg, #27272a, #52525b);
+  border-color: #18181b;
+  color: #ffffff;
+}
+
+html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-toolbar.btn-run.mode-deepseek, .btn-toolbar.btn-run-gear.mode-deepseek) {
+  background: linear-gradient(135deg, #2740c4, #4d6bfe);
+  border-color: #1b2a8f;
+  color: #ffffff;
+}
+
 html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) .btn-toolbar.btn-run-gear {
   border-left-color: var(--control-border-hover) !important;
 }

src/web/public/panels-ui.js

@@ -432,7 +432,7 @@ Object.assign(CodemanApp.prototype, {
 
   _buildCommandPaletteNewSessionItem(query = '') {
     const mode = this.runMode || this._runMode || 'claude';
-    const labels = { claude: 'Claude', opencode: 'OpenCode', codex: 'Codex', gemini: 'Gemini', antigravity: 'Antigravity', pi: 'Pi' };
+    const labels = { claude: 'Claude', opencode: 'OpenCode', codex: 'Codex', gemini: 'Gemini', antigravity: 'Antigravity', pi: 'Pi', grok: 'Grok', deepseek: 'DeepSeek' };
     const caseName = this._findCommandPaletteCaseMatch(query) || document.getElementById('quickStartCase')?.value || 'testcase';
     return {
       id: 'new-session',
@@ -2980,54 +2980,423 @@ Object.assign(CodemanApp.prototype, {
     btn.setAttribute('aria-label', label);
   },
 
+  _ensureFileBrowserState() {
+    if (!this._fileBrowserState) {
+      const ownerSessionId = this.activeSessionId || null;
+      const showHidden = this.fileBrowserShowHidden === true;
+      this._fileBrowserState = {
+        treeEpoch: 0,
+        searchEpoch: 0,
+        ownerSessionId,
+        view: 'normal',
+        normalState: this.fileBrowserData
+          ? { sessionId: ownerSessionId, showHidden, treeEpoch: 0, phase: 'ready', data: this.fileBrowserData }
+          : null,
+        treeInFlight: null,
+        inFlight: null,
+        matches: [],
+        deferredDirectoryTarget: null,
+        filter: typeof this.fileBrowserFilter === 'string' ? this.fileBrowserFilter : '',
+      };
+    }
+    return this._fileBrowserState;
+  },
+
+  _activateFileBrowserSession(sessionId) {
+    if (!sessionId) return;
+
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.treeEpoch++;
+    state.ownerSessionId = sessionId;
+    state.treeInFlight = null;
+    state.inFlight = null;
+    state.normalState = null;
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.filter = '';
+    state.view = 'normal';
+    this.fileBrowserData = null;
+    this.fileBrowserFilter = '';
+    this.fileBrowserExpandedDirs?.clear?.();
+    this.fileBrowserAllExpanded = false;
+
+    const searchInput = this.$?.('fileBrowserSearch');
+    if (searchInput) searchInput.value = '';
+    this._syncFileBrowserExpandBtn();
+    const expandBtn = this.$?.('fileBrowserExpandBtn');
+    if (expandBtn) expandBtn.innerHTML = '\u229E';
+
+    const panel = this.$?.('fileBrowserPanel');
+    const treeEl = this.$?.('fileBrowserTree');
+    const statusEl = this.$?.('fileBrowserStatus');
+    const visible = panel?.classList.contains('visible') === true;
+    if (treeEl) {
+      treeEl.innerHTML = visible
+        ? `<div class="file-browser-loading">${escapeHtml('Loading files...')}</div>`
+        : '';
+    }
+    if (statusEl) statusEl.textContent = visible ? 'Loading files...' : '';
+
+    if (visible) {
+      const load = this.loadFileBrowser?.(sessionId);
+      load?.catch?.(() => {});
+    }
+  },
+
+  _resetFileBrowserForHide() {
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.treeEpoch++;
+    state.treeInFlight = null;
+    state.inFlight = null;
+    state.normalState = null;
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.filter = '';
+    state.view = 'normal';
+    this.fileBrowserData = null;
+    this.fileBrowserFilter = '';
+    this.fileBrowserExpandedDirs?.clear?.();
+    this.fileBrowserAllExpanded = false;
+
+    const searchInput = this.$?.('fileBrowserSearch');
+    if (searchInput) searchInput.value = '';
+    this._syncFileBrowserExpandBtn();
+    const expandBtn = this.$?.('fileBrowserExpandBtn');
+    if (expandBtn) expandBtn.innerHTML = '\u229E';
+    const treeEl = this.$?.('fileBrowserTree');
+    if (treeEl) treeEl.innerHTML = '';
+    const statusEl = this.$?.('fileBrowserStatus');
+    if (statusEl) statusEl.textContent = '';
+  },
+
+  _setFileBrowserExpandDisabled(disabled) {
+    const btn = this.$('fileBrowserExpandBtn');
+    if (btn) btn.disabled = disabled;
+  },
+
+  _hasFileBrowserQuery() {
+    const state = this._ensureFileBrowserState();
+    const input = this.$?.('fileBrowserSearch');
+    const inputValue = typeof input?.value === 'string' ? input.value : '';
+    const filterValue = typeof state.filter === 'string' ? state.filter : '';
+    return inputValue.trim() !== '' || filterValue.trim() !== '';
+  },
+
+  _syncFileBrowserExpandBtn() {
+    this._setFileBrowserExpandDisabled(this._hasFileBrowserQuery());
+  },
+
+  _renderFileBrowserNormalStatus(data, showHidden) {
+    const statusEl = this.$('fileBrowserStatus');
+    if (!statusEl || !data) return;
+    const { totalFiles, totalDirectories, truncated } = data;
+    statusEl.textContent = `${totalFiles} files, ${totalDirectories} dirs${truncated ? ' (truncated)' : ''}${showHidden ? ' · hidden shown' : ''}`;
+  },
+
+  _isFileBrowserNormalCompatible(candidate, sessionId, showHidden, treeEpoch) {
+    return (
+      candidate?.sessionId === sessionId &&
+      candidate.showHidden === showHidden &&
+      candidate.treeEpoch === treeEpoch
+    );
+  },
+
+  _isFileBrowserTreeContextCurrent(request, requireCurrentRecord = false) {
+    const state = this._ensureFileBrowserState();
+    return (
+      (!requireCurrentRecord || state.treeInFlight === request) &&
+      state.ownerSessionId === request.sessionId &&
+      state.treeEpoch === request.treeEpoch &&
+      (this.fileBrowserShowHidden === true) === request.showHidden
+    );
+  },
+
+  _canRenderFileBrowserNormal(normalState) {
+    const state = this._ensureFileBrowserState();
+    return (
+      state.view === 'normal' &&
+      this.activeSessionId === normalState?.sessionId &&
+      this._isFileBrowserNormalCompatible(
+        normalState,
+        state.ownerSessionId,
+        this.fileBrowserShowHidden === true,
+        state.treeEpoch,
+      ) &&
+      this.$('fileBrowserPanel')?.classList.contains('visible') === true
+    );
+  },
+
+  _renderFileBrowserNormalState(normalState) {
+    if (!normalState || !this._canRenderFileBrowserNormal(normalState)) return;
+    const treeEl = this.$('fileBrowserTree');
+    const statusEl = this.$('fileBrowserStatus');
+    if (!treeEl) return;
+
+    if (normalState.phase === 'loading') {
+      this.fileBrowserData = null;
+      treeEl.innerHTML = `<div class="file-browser-loading">${escapeHtml('Loading files...')}</div>`;
+      if (statusEl) statusEl.textContent = 'Loading files...';
+      return;
+    }
+
+    if (normalState.phase === 'error') {
+      this.fileBrowserData = null;
+      const detail = normalState.error && normalState.error !== 'Failed to load files'
+        ? `: ${normalState.error}`
+        : '';
+      const message = `Failed to load files${detail}`;
+      treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml(message)}</div>`;
+      if (statusEl) statusEl.textContent = message;
+      return;
+    }
+
+    if (normalState.phase !== 'ready') return;
+    this.fileBrowserData = normalState.data;
+    this._syncFileBrowserExpandBtn();
+    this.renderFileBrowserTree(normalState.sessionId);
+    this._renderFileBrowserNormalStatus(normalState.data, normalState.showHidden);
+  },
+
+  _validateFileBrowserTreeEnvelope(result) {
+    if (!result || typeof result !== 'object' || result.success !== true) return null;
+    const data = result.data;
+    if (!data || typeof data !== 'object' || !Array.isArray(data.tree)) return null;
+    if (data.mode === 'search') return null;
+    if (
+      typeof data.totalFiles !== 'number' ||
+      !Number.isFinite(data.totalFiles) ||
+      data.totalFiles < 0 ||
+      typeof data.totalDirectories !== 'number' ||
+      !Number.isFinite(data.totalDirectories) ||
+      data.totalDirectories < 0 ||
+      typeof data.truncated !== 'boolean'
+    ) {
+      return null;
+    }
+
+    const validNodes = nodes => nodes.every(node => {
+      if (!node || typeof node !== 'object') return false;
+      if (typeof node.name !== 'string' || typeof node.path !== 'string') return false;
+      if (node.type !== 'file' && node.type !== 'directory') return false;
+      if (node.size !== undefined && (typeof node.size !== 'number' || !Number.isFinite(node.size))) return false;
+      if (node.extension !== undefined && typeof node.extension !== 'string') return false;
+      if (node.children !== undefined && (!Array.isArray(node.children) || !validNodes(node.children))) return false;
+      return true;
+    });
+
+    return validNodes(data.tree) ? data : null;
+  },
+
+  _normalizeFileBrowserTreeError(error) {
+    return typeof error?.message === 'string' && error.message ? error.message : 'Failed to load files';
+  },
+
+  _validateFileBrowserSearchEnvelope(result) {
+    if (!result || typeof result !== 'object' || result.success !== true) return null;
+    const data = result.data;
+    if (!data || typeof data !== 'object' || data.mode !== 'search' || !Array.isArray(data.matches)) return null;
+    if (typeof data.truncated !== 'boolean') return null;
+    if (
+      data.matchCount !== undefined &&
+      (typeof data.matchCount !== 'number' || !Number.isFinite(data.matchCount) || data.matchCount < 0)
+    ) {
+      return null;
+    }
+    for (const match of data.matches) {
+      if (!match || typeof match !== 'object') return null;
+      if (typeof match.name !== 'string' || typeof match.path !== 'string') return null;
+      if (match.type !== 'file' && match.type !== 'directory') return null;
+      if (match.size !== undefined && (typeof match.size !== 'number' || !Number.isFinite(match.size))) return null;
+      if (match.extension !== undefined && typeof match.extension !== 'string') return null;
+    }
+    return data;
+  },
+
+  _canRenderFileBrowserSearch(request) {
+    const state = this._ensureFileBrowserState();
+    const panel = this.$('fileBrowserPanel');
+    return (
+      state.searchEpoch === request.epoch &&
+      state.ownerSessionId === request.ownerSessionId &&
+      this.activeSessionId === request.ownerSessionId &&
+      (this.fileBrowserShowHidden === true) === request.showHidden &&
+      state.filter === request.rawInput &&
+      panel?.classList.contains('visible') === true
+    );
+  },
+
+  _renderFileBrowserSearchError() {
+    const treeEl = this.$('fileBrowserTree');
+    const statusEl = this.$('fileBrowserStatus');
+    const message = 'Search failed';
+    if (treeEl) treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml(message)}</div>`;
+    if (statusEl) statusEl.textContent = message;
+  },
+
+  _canContinueFileBrowserHiddenReload(continuation, normalState) {
+    const state = this._ensureFileBrowserState();
+    const input = this.$?.('fileBrowserSearch');
+    const currentInput = typeof input?.value === 'string' ? input.value : state.filter;
+    return (
+      state.view === 'normal' &&
+      state.searchEpoch === continuation.searchEpoch &&
+      state.treeEpoch === continuation.treeEpoch &&
+      state.ownerSessionId === continuation.ownerSessionId &&
+      this.activeSessionId === continuation.ownerSessionId &&
+      (this.fileBrowserShowHidden === true) === continuation.showHidden &&
+      state.filter === continuation.rawInput &&
+      currentInput === continuation.rawInput &&
+      currentInput.trim() === continuation.query &&
+      this.$?.('fileBrowserPanel')?.classList.contains('visible') === true &&
+      normalState?.phase === 'ready' &&
+      this._isFileBrowserNormalCompatible(
+        normalState,
+        continuation.ownerSessionId,
+        continuation.showHidden,
+        continuation.treeEpoch,
+      )
+    );
+  },
+
   async toggleFileBrowserHidden() {
+    const state = this._ensureFileBrowserState();
+    const rawInput = typeof state.filter === 'string' ? state.filter : '';
+    const query = rawInput.trim();
     this.fileBrowserShowHidden = !this.fileBrowserShowHidden;
     try {
       localStorage.setItem(FILE_BROWSER_SHOW_HIDDEN_KEY, this.fileBrowserShowHidden ? '1' : '0');
     } catch {}
     this._syncFileBrowserHiddenBtn();
+
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.inFlight = null;
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.normalState = null;
+    this.fileBrowserData = null;
+    if (query.length <= 256) state.view = 'normal';
+    this._syncFileBrowserExpandBtn();
+
     // Expanded-directory state is deliberately preserved so toggling does not
     // collapse the tree the user just navigated.
-    if (this.activeSessionId) await this.loadFileBrowser(this.activeSessionId);
-  },
+    const ownerSessionId = state.ownerSessionId || this.activeSessionId;
+    if (!ownerSessionId || this.activeSessionId !== ownerSessionId) return;
 
-  async loadFileBrowser(sessionId) {
-    if (!sessionId) return;
+    const searchEpoch = state.searchEpoch;
+    const showHidden = this.fileBrowserShowHidden === true;
+    const load = this.loadFileBrowser(ownerSessionId, { force: true });
+    const treeEpoch = state.treeEpoch;
+    if (!load?.then) return;
+    await load;
 
-    const treeEl = this.$('fileBrowserTree');
-    const statusEl = this.$('fileBrowserStatus');
-    this._syncFileBrowserHiddenBtn();
-    if (!treeEl) return;
-
-    // Show loading state
-    treeEl.innerHTML = '<div class="file-browser-loading">Loading files...</div>';
-
-    try {
-      const showHidden = this.fileBrowserShowHidden === true;
-      const res = await fetch(`/api/sessions/${sessionId}/files?depth=5&showHidden=${showHidden}`);
-      if (!res.ok) throw new Error('Failed to load files');
-
-      const result = await res.json();
-      if (!result.success) throw new Error(result.error || 'Failed to load files');
-
-      this.fileBrowserData = result.data;
-      this.renderFileBrowserTree();
-
-      // Update status
-      if (statusEl) {
-        const { totalFiles, totalDirectories, truncated } = result.data;
-        statusEl.textContent = `${totalFiles} files, ${totalDirectories} dirs${truncated ? ' (truncated)' : ''}${showHidden ? ' · hidden shown' : ''}`;
-      }
-    } catch (err) {
-      console.error('Failed to load file browser:', err);
-      treeEl.innerHTML = `<div class="file-browser-empty">Failed to load files: ${escapeHtml(err.message)}</div>`;
+    if (!query || query.length > 256) return;
+    const continuation = { ownerSessionId, showHidden, treeEpoch, searchEpoch, rawInput, query };
+    if (this._canContinueFileBrowserHiddenReload(continuation, state.normalState)) {
+      this.filterFileBrowser(rawInput);
     }
   },
 
-  renderFileBrowserTree() {
+  loadFileBrowser(sessionId, { force = false } = {}) {
+    if (!sessionId) return undefined;
+
+    const state = this._ensureFileBrowserState();
+    const treeEl = this.$('fileBrowserTree');
+    this._syncFileBrowserHiddenBtn();
+    if (!treeEl) return undefined;
+    if (!state.ownerSessionId) state.ownerSessionId = sessionId;
+    if (state.ownerSessionId !== sessionId) return undefined;
+
+    if (force) state.treeEpoch++;
+    const showHidden = this.fileBrowserShowHidden === true;
+    const treeEpoch = state.treeEpoch;
+    const inFlight = state.treeInFlight;
+    if (
+      !force &&
+      this._isFileBrowserNormalCompatible(inFlight, sessionId, showHidden, treeEpoch)
+    ) {
+      return inFlight.promise;
+    }
+
+    const settled = state.normalState;
+    if (
+      !force &&
+      this._isFileBrowserNormalCompatible(settled, sessionId, showHidden, treeEpoch) &&
+      (settled.phase === 'ready' || settled.phase === 'error')
+    ) {
+      if (settled.phase === 'ready') this.fileBrowserData = settled.data;
+      this._renderFileBrowserNormalState(settled);
+      return Promise.resolve(settled);
+    }
+
+    const loadingState = { sessionId, showHidden, treeEpoch, phase: 'loading' };
+    state.normalState = loadingState;
+    this.fileBrowserData = null;
+    this._renderFileBrowserNormalState(loadingState);
+
+    const record = { sessionId, showHidden, treeEpoch, promise: null };
+    const request = (async () => {
+      try {
+        const res = await fetch(
+          `/api/sessions/${encodeURIComponent(sessionId)}/files?depth=5&showHidden=${showHidden}`,
+        );
+        if (!res.ok) throw new Error('Failed to load files');
+        const result = await res.json();
+        const data = this._validateFileBrowserTreeEnvelope(result);
+        if (!data) {
+          const detail = result && typeof result === 'object' && typeof result.error === 'string'
+            ? result.error
+            : 'Failed to load files';
+          throw new Error(detail);
+        }
+        if (!this._isFileBrowserTreeContextCurrent(record, true)) return;
+
+        const nextNormalState = { sessionId, showHidden, treeEpoch, phase: 'ready', data };
+        state.normalState = nextNormalState;
+        this.fileBrowserData = data;
+        const deferredRendered = this._completeDeferredFileBrowserDirectory?.(nextNormalState) === true;
+        if (!deferredRendered) this._renderFileBrowserNormalState(nextNormalState);
+      } catch (error) {
+        if (!this._isFileBrowserTreeContextCurrent(record, true)) return;
+        const nextNormalState = {
+          sessionId,
+          showHidden,
+          treeEpoch,
+          phase: 'error',
+          error: this._normalizeFileBrowserTreeError(error),
+        };
+        state.normalState = nextNormalState;
+        this.fileBrowserData = null;
+        this._completeDeferredFileBrowserDirectory?.(nextNormalState);
+        console.error('Failed to load file browser:', error);
+        this._renderFileBrowserNormalState(nextNormalState);
+      }
+    })();
+    record.promise = request.finally(() => {
+      if (state.treeInFlight === record) state.treeInFlight = null;
+    });
+    state.treeInFlight = record;
+    return record.promise;
+  },
+
+  renderFileBrowserTree(ownerSessionId) {
     const treeEl = this.$('fileBrowserTree');
     if (!treeEl || !this.fileBrowserData) return;
 
+    const state = this._ensureFileBrowserState();
+    const owner = ownerSessionId || state.normalState?.sessionId || state.ownerSessionId || this.activeSessionId;
+    if (!owner) return;
+
     const { tree } = this.fileBrowserData;
     if (!tree || tree.length === 0) {
       treeEl.innerHTML = '<div class="file-browser-empty">No files found</div>';
@@ -3035,21 +3404,10 @@ Object.assign(CodemanApp.prototype, {
     }
 
     const html = [];
-    const filter = this.fileBrowserFilter.toLowerCase();
 
     const renderNode = (node, depth) => {
       const isDir = node.type === 'directory';
       const isExpanded = this.fileBrowserExpandedDirs.has(node.path);
-      const matchesFilter = !filter || node.name.toLowerCase().includes(filter);
-
-      // For directories, check if any children match
-      let hasMatchingChildren = false;
-      if (isDir && filter && node.children) {
-        hasMatchingChildren = this.hasMatchingChild(node, filter);
-      }
-
-      const shouldShow = matchesFilter || hasMatchingChildren;
-      const hiddenClass = !shouldShow && filter ? ' hidden-by-filter' : '';
 
       const icon = isDir
         ? (isExpanded ? '\uD83D\uDCC2' : '\uD83D\uDCC1')
@@ -3066,11 +3424,11 @@ Object.assign(CodemanApp.prototype, {
       const nameClass = isDir ? 'file-tree-name directory' : 'file-tree-name';
 
       const downloadBtn = !isDir
-        ? `<a class="file-tree-download" href="/api/sessions/${this.activeSessionId}/file-raw?path=${encodeURIComponent(node.path)}&download=true" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
+        ? `<a class="file-tree-download" href="${escapeHtml(`/api/sessions/${encodeURIComponent(owner)}/file-raw?path=${encodeURIComponent(node.path)}&download=true`)}" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
         : '';
 
       html.push(`
-        <div class="file-tree-item${hiddenClass}" data-path="${escapeHtml(node.path)}" data-type="${node.type}" data-depth="${depth}">
+        <div class="file-tree-item" data-path="${escapeHtml(node.path)}" data-type="${escapeHtml(node.type)}" data-depth="${depth}">
           ${expandIcon}
           <span class="file-tree-icon">${icon}</span>
           <span class="${nameClass}">${escapeHtml(node.name)}</span>
@@ -3102,21 +3460,12 @@ Object.assign(CodemanApp.prototype, {
         if (type === 'directory') {
           this.toggleFileBrowserFolder(path);
         } else {
-          this.openFilePreview(path);
+          this.openFilePreview(path, owner);
         }
       });
     });
   },
 
-  hasMatchingChild(node, filter) {
-    if (!node.children) return false;
-    for (const child of node.children) {
-      if (child.name.toLowerCase().includes(filter)) return true;
-      if (child.type === 'directory' && this.hasMatchingChild(child, filter)) return true;
-    }
-    return false;
-  },
-
   toggleFileBrowserFolder(path) {
     if (this.fileBrowserExpandedDirs.has(path)) {
       this.fileBrowserExpandedDirs.delete(path);
@@ -3127,12 +3476,291 @@ Object.assign(CodemanApp.prototype, {
   },
 
   filterFileBrowser(value) {
-    this.fileBrowserFilter = value;
-    // Auto-expand all if filtering
-    if (value) {
-      this.expandAllDirectories(this.fileBrowserData?.tree || []);
+    const state = this._ensureFileBrowserState();
+    const rawInput = String(value ?? '');
+    const query = rawInput.trim();
+    state.searchEpoch++;
+    state.filter = rawInput;
+    state.deferredDirectoryTarget = null;
+    this.fileBrowserFilter = rawInput;
+    this._syncFileBrowserExpandBtn();
+
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
     }
-    this.renderFileBrowserTree();
+    state.inFlight = null;
+
+    if (!state.ownerSessionId && this.activeSessionId) state.ownerSessionId = this.activeSessionId;
+    const ownerSessionId = state.ownerSessionId || null;
+    if (!this.activeSessionId || !ownerSessionId || this.activeSessionId !== ownerSessionId) return;
+    if (!query) {
+      state.view = 'normal';
+      state.matches = [];
+      this._syncFileBrowserExpandBtn();
+      const normal = state.normalState;
+      if (
+        ownerSessionId &&
+        this._isFileBrowserNormalCompatible(
+          normal,
+          ownerSessionId,
+          this.fileBrowserShowHidden === true,
+          state.treeEpoch,
+        )
+      ) {
+        this._renderFileBrowserNormalState(normal);
+      }
+      return;
+    }
+
+    if (query.length > 256) {
+      const message = 'Search queries are limited to 256 characters';
+      state.view = 'query-error';
+      state.matches = [];
+      this._syncFileBrowserExpandBtn();
+      const treeEl = this.$('fileBrowserTree');
+      const statusEl = this.$('fileBrowserStatus');
+      if (treeEl) treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml(message)}</div>`;
+      if (statusEl) statusEl.textContent = message;
+      return;
+    }
+
+    const panel = this.$('fileBrowserPanel');
+    const treeEl = this.$('fileBrowserTree');
+    if (!ownerSessionId || !panel || !treeEl) return;
+
+    const request = {
+      epoch: state.searchEpoch,
+      treeEpoch: state.treeEpoch,
+      ownerSessionId,
+      showHidden: this.fileBrowserShowHidden === true,
+      rawInput,
+      query,
+      timer: null,
+    };
+    state.view = 'search-pending';
+    state.matches = [];
+    state.inFlight = request;
+    this._syncFileBrowserExpandBtn();
+    treeEl.innerHTML = `<div class="file-browser-loading">${escapeHtml('Searching...')}</div>`;
+    const statusEl = this.$('fileBrowserStatus');
+    if (statusEl) statusEl.textContent = 'Searching...';
+
+    request.timer = setTimeout(async () => {
+      request.timer = null;
+      try {
+        const res = await fetch(
+          `/api/sessions/${encodeURIComponent(ownerSessionId)}/files?depth=5&showHidden=${request.showHidden}&q=${encodeURIComponent(query)}`,
+        );
+        if (!res.ok) throw new Error('Search failed');
+        const result = await res.json();
+        const data = this._validateFileBrowserSearchEnvelope(result);
+        if (!data) throw new Error('Search failed');
+        const canRender = this._canRenderFileBrowserSearch(request);
+        if (state.inFlight === request) state.inFlight = null;
+        if (!canRender) return;
+        state.view = 'search-results';
+        state.matches = data.matches;
+        this._renderFileBrowserSearchResults(data.matches, ownerSessionId, data);
+      } catch (err) {
+        const canRender = this._canRenderFileBrowserSearch(request);
+        if (state.inFlight === request) state.inFlight = null;
+        if (!canRender) return;
+        console.error('Failed to search file browser:', err);
+        state.view = 'search-error';
+        state.matches = [];
+        this._renderFileBrowserSearchError();
+      }
+    }, 250);
+  },
+
+  _renderFileBrowserSearchResults(matches, ownerSessionId, data) {
+    const treeEl = this.$('fileBrowserTree');
+    if (!treeEl || !ownerSessionId) return;
+    const state = this._ensureFileBrowserState();
+    const searchContext = {
+      ownerSessionId,
+      showHidden: this.fileBrowserShowHidden === true,
+      treeEpoch: state.treeEpoch,
+      searchEpoch: state.searchEpoch,
+      rawInput: state.filter,
+      query: state.filter.trim(),
+      view: state.view,
+    };
+    if (matches.length === 0) {
+      treeEl.innerHTML = `<div class="file-browser-empty">${escapeHtml('No matches')}</div>`;
+    } else {
+      const ownerPath = encodeURIComponent(ownerSessionId);
+      treeEl.innerHTML = matches
+        .map(match => {
+          const isDir = match.type === 'directory';
+          const icon = isDir ? '📁' : this.getFileIcon(match.extension || '');
+          const sizeStr = !isDir && match.size !== undefined
+            ? `<span class="file-tree-size">${this.formatFileSize(match.size)}</span>`
+            : '';
+          const nameClass = isDir ? 'file-tree-name directory' : 'file-tree-name';
+          const downloadBtn = !isDir
+            ? `<a class="file-tree-download" href="${escapeHtml(`/api/sessions/${ownerPath}/file-raw?path=${encodeURIComponent(match.path)}&download=true`)}" title="Download" onclick="event.stopPropagation()">&#x2B07;</a>`
+            : '';
+          return `
+            <div class="file-tree-item" data-path="${escapeHtml(match.path)}" data-type="${escapeHtml(match.type)}" data-owner="${escapeHtml(ownerSessionId)}">
+              <span class="file-tree-expand"></span>
+              <span class="file-tree-icon">${icon}</span>
+              <span class="${nameClass}">${escapeHtml(match.name)}</span>
+              ${sizeStr}
+              ${downloadBtn}
+            </div>
+          `;
+        })
+        .join('');
+    }
+
+    treeEl.querySelectorAll('.file-tree-item').forEach(item => {
+      item.addEventListener('click', () => {
+        const path = item.dataset.path;
+        if (item.dataset.type === 'directory') {
+          this._openFileBrowserSearchDirectory({ ...searchContext, path });
+        } else {
+          this.openFilePreview(path, ownerSessionId);
+        }
+      });
+    });
+
+    const statusEl = this.$('fileBrowserStatus');
+    if (statusEl) {
+      const count = data.matchCount === undefined ? matches.length : data.matchCount;
+      statusEl.textContent = `${count} ${count === 1 ? 'match' : 'matches'}${data.truncated ? ' (truncated)' : ''}`;
+    }
+  },
+
+  _findFileBrowserDirectory(nodes, targetPath, ancestors = []) {
+    if (!Array.isArray(nodes)) return null;
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') continue;
+      if (node.type === 'directory' && node.path === targetPath) {
+        return { target: node, ancestors: [...ancestors] };
+      }
+      if (node.type !== 'directory' || !Array.isArray(node.children)) continue;
+      const found = this._findFileBrowserDirectory(node.children, targetPath, [...ancestors, node.path]);
+      if (found) return found;
+    }
+    return null;
+  },
+
+  _isFileBrowserDirectoryContextCurrent(target) {
+    const state = this._ensureFileBrowserState();
+    const input = this.$?.('fileBrowserSearch');
+    const currentInput = typeof input?.value === 'string' ? input.value : state.filter;
+    return (
+      target &&
+      state.ownerSessionId === target.ownerSessionId &&
+      this.activeSessionId === target.ownerSessionId &&
+      state.treeEpoch === target.treeEpoch &&
+      state.searchEpoch === target.searchEpoch &&
+      (this.fileBrowserShowHidden === true) === target.showHidden &&
+      state.filter === target.rawInput &&
+      currentInput === target.rawInput &&
+      currentInput.trim() === target.query &&
+      state.view === target.view &&
+      this.$?.('fileBrowserPanel')?.classList.contains('visible') === true
+    );
+  },
+
+  _promptFileBrowserDirectoryReload() {
+    this.showToast?.('Reload files before opening this folder', 'info');
+  },
+
+  _openFileBrowserSearchDirectory(target) {
+    if (!this._isFileBrowserDirectoryContextCurrent(target)) return;
+    const state = this._ensureFileBrowserState();
+    const normalState = state.normalState;
+    if (
+      !this._isFileBrowserNormalCompatible(
+        normalState,
+        target.ownerSessionId,
+        target.showHidden,
+        target.treeEpoch,
+      )
+    ) {
+      state.deferredDirectoryTarget = null;
+      this._promptFileBrowserDirectoryReload();
+      return;
+    }
+
+    if (normalState.phase === 'loading') {
+      state.deferredDirectoryTarget = { ...target };
+      return;
+    }
+
+    state.deferredDirectoryTarget = null;
+    if (normalState.phase !== 'ready') {
+      this._promptFileBrowserDirectoryReload();
+      return;
+    }
+
+    const found = this._findFileBrowserDirectory(normalState.data?.tree, target.path);
+    if (!found) {
+      this._promptFileBrowserDirectoryReload();
+      return;
+    }
+    this._leaveFileBrowserSearchForDirectory([...found.ancestors, found.target.path], normalState);
+  },
+
+  _completeDeferredFileBrowserDirectory(normalState) {
+    const state = this._ensureFileBrowserState();
+    const target = state.deferredDirectoryTarget;
+    if (!target) return false;
+    if (!this._isFileBrowserDirectoryContextCurrent(target)) {
+      if (state.deferredDirectoryTarget === target) state.deferredDirectoryTarget = null;
+      return false;
+    }
+    if (
+      !this._isFileBrowserNormalCompatible(
+        normalState,
+        target.ownerSessionId,
+        target.showHidden,
+        target.treeEpoch,
+      ) ||
+      (normalState.phase !== 'ready' && normalState.phase !== 'error')
+    ) {
+      return false;
+    }
+
+    state.deferredDirectoryTarget = null;
+    if (normalState.phase === 'error') {
+      this._promptFileBrowserDirectoryReload();
+      return false;
+    }
+
+    const found = this._findFileBrowserDirectory(normalState.data?.tree, target.path);
+    if (!found) {
+      this._promptFileBrowserDirectoryReload();
+      return false;
+    }
+    this._leaveFileBrowserSearchForDirectory([...found.ancestors, found.target.path], normalState);
+    return true;
+  },
+
+  _leaveFileBrowserSearchForDirectory(paths, normalState) {
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
+    }
+    state.searchEpoch++;
+    state.inFlight = null;
+    state.filter = '';
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.view = 'normal';
+    this.fileBrowserFilter = '';
+
+    const input = this.$?.('fileBrowserSearch');
+    if (input) input.value = '';
+    this._syncFileBrowserExpandBtn();
+    for (const path of paths) {
+      if (typeof path === 'string') this.fileBrowserExpandedDirs?.add?.(path);
+    }
+    this.fileBrowserData = normalState.data;
+    this._renderFileBrowserNormalState(normalState);
   },
 
   expandAllDirectories(nodes) {
@@ -3151,6 +3779,10 @@ Object.assign(CodemanApp.prototype, {
   },
 
   toggleFileBrowserExpand() {
+    if (this._hasFileBrowserQuery()) {
+      this._syncFileBrowserExpandBtn();
+      return;
+    }
     this.fileBrowserAllExpanded = !this.fileBrowserAllExpanded;
     const btn = this.$('fileBrowserExpandBtn');
 
@@ -3165,14 +3797,28 @@ Object.assign(CodemanApp.prototype, {
   },
 
   refreshFileBrowser() {
-    if (this.activeSessionId) {
-      this.fileBrowserExpandedDirs.clear();
-      this.fileBrowserFilter = '';
-      this.fileBrowserAllExpanded = false;
-      const searchInput = this.$('fileBrowserSearch');
-      if (searchInput) searchInput.value = '';
-      this.loadFileBrowser(this.activeSessionId);
+    const state = this._ensureFileBrowserState();
+    if (state.inFlight?.timer !== undefined && state.inFlight?.timer !== null) {
+      clearTimeout(state.inFlight.timer);
     }
+    state.inFlight = null;
+    state.searchEpoch++;
+    state.filter = '';
+    state.matches = [];
+    state.deferredDirectoryTarget = null;
+    state.view = 'normal';
+    this.fileBrowserFilter = '';
+    this.fileBrowserExpandedDirs.clear();
+    this.fileBrowserAllExpanded = false;
+    const expandBtn = this.$('fileBrowserExpandBtn');
+    if (expandBtn) expandBtn.innerHTML = '\u229E';
+    const searchInput = this.$('fileBrowserSearch');
+    if (searchInput) searchInput.value = '';
+    this._syncFileBrowserExpandBtn();
+
+    const ownerSessionId = state.ownerSessionId || this.activeSessionId;
+    if (!ownerSessionId || this.activeSessionId !== ownerSessionId) return undefined;
+    return this.loadFileBrowser(ownerSessionId, { force: true });
   },
 
   // Header "File Viewer" button (opt-in via App Settings → Header Displays →
@@ -3203,6 +3849,7 @@ Object.assign(CodemanApp.prototype, {
 
   closeFileBrowserPanel() {
     const panel = this.$('fileBrowserPanel');
+    this._resetFileBrowserForHide();
     if (panel) {
       panel.classList.remove('visible');
       // Reset position so it reopens at default location
@@ -3313,6 +3960,11 @@ Object.assign(CodemanApp.prototype, {
     // Stop whatever the previous preview was playing. Overwriting innerHTML
     // only DETACHES a <video>/<audio>; a detached media element keeps playing.
     this._stopFilePreviewMedia();
+    // Disarm detach until this load has a URL of its own: an early error return
+    // must not leave the button opening the PREVIOUS file in a new tab.
+    this.filePreviewDetachUrl = '';
+    const detachBtn = this.$('filePreviewDetachBtn');
+    if (detachBtn) detachBtn.hidden = true;
 
     // Show overlay with loading state
     overlay.classList.add('visible');
@@ -3340,6 +3992,19 @@ Object.assign(CodemanApp.prototype, {
       return;
     }
 
+    // Every branch below renders from one of these routes, so the detach button
+    // can always offer the same bytes in a browser tab: docx/pptx through the
+    // server-converted PDF preview, everything else through the raw route.
+    // (html/htm arrive as a download there by design — file-raw serves them
+    // attachment-only so widening READ never widens RUN.)
+    const officeDoc = ext === 'docx' || ext === 'pptx';
+    this.filePreviewDetachUrl = attachmentId
+      ? `/api/sessions/${sessionId}/attachments/${encodeURIComponent(attachmentId)}/${officeDoc ? 'preview' : 'raw'}`
+      : officeDoc
+        ? `/api/sessions/${sessionId}/file-preview?path=${encodeURIComponent(filePath)}`
+        : `/api/sessions/${sessionId}/file-raw?path=${encodeURIComponent(filePath)}`;
+    if (detachBtn) detachBtn.hidden = false;
+
     // Registered attachment: render straight from its by-id routes — images and
     // PDFs inline, Office docs via the server-converted PDF preview, text fetched
     // raw. (Workspace-path previews fall through to the file-content endpoint.)
@@ -3489,6 +4154,29 @@ Object.assign(CodemanApp.prototype, {
     // audible and keeps streaming from the server. Closing has to stop it.
     this._stopFilePreviewMedia();
     this.filePreviewContent = '';
+    this.filePreviewDetachUrl = '';
+    const detachBtn = this.$('filePreviewDetachBtn');
+    if (detachBtn) detachBtn.hidden = true;
+  },
+
+  /**
+   * Open the previewed file in a browser tab and close the overlay.
+   *
+   * window.open is called WITHOUT the 'noopener' feature string: with it the
+   * call returns null even on success, which would make a blocked pop-up
+   * indistinguishable from a working one. The opener link is severed by hand
+   * instead, and a null return then reliably means the browser blocked it, in
+   * which case the overlay stays up so the user has not lost the file.
+   */
+  detachFilePreview() {
+    if (!this.filePreviewDetachUrl) 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');
+      return;
+    }
+    win.opener = null;
+    this.closeFilePreview();
   },
 
   /**
@@ -4127,6 +4815,10 @@ Object.assign(CodemanApp.prototype, {
       }).catch(() => {
         this.showToast('Failed to copy', 'error');
       });
+    } else {
+      // Media/PDF/binary previews have no text buffer. Saying so beats the
+      // dead-button silence this used to be.
+      this.showToast('Nothing to copy in this preview', 'info');
     }
   },
 

src/web/public/session-lineage.js

@@ -160,6 +160,8 @@ Object.assign(CodemanApp.prototype, {
     const strip = document.getElementById('sessionTabs');
     if (!strip) return;
     const stripRect = strip.getBoundingClientRect();
+    const orientation =
+      document.documentElement.getAttribute('data-tab-orientation') === 'vertical' ? 'vertical' : 'horizontal';
     for (const edge of edges) {
       for (const id of [edge.parentId, edge.childId]) {
         const key = 'tab:' + id;
@@ -175,7 +177,13 @@ Object.assign(CodemanApp.prototype, {
       const childRect = rects.get('tab:' + edge.childId);
       if (!parentRect || !childRect) continue;
 
-      const geom = compute({ parent: parentRect, child: childRect, strip: stripRect, depth: edge.depth });
+      const geom = compute({
+        parent: parentRect,
+        child: childRect,
+        strip: stripRect,
+        depth: edge.depth,
+        orientation,
+      });
       if (!geom) continue; // scrolled out of the strip, or a degenerate rect
 
       const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
@@ -222,10 +230,12 @@ Object.assign(CodemanApp.prototype, {
     const strip = document.getElementById('sessionTabs');
     if (!strip) return;
     this._lineageScrollHandler = () => {
-      // Sidebar layout scrolls the SAME element vertically, and there the
-      // subagent/ultracode connectors anchor to tab rects too (lineage arcs are
-      // skipped, so _lineageEdgeCount alone would never redraw them).
-      if (this._lineageEdgeCount > 0 || this.isSessionSidebarActive?.()) this.updateConnectionLines();
+      // 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).
+      if (this._lineageEdgeCount > 0 || this._isVerticalTabList?.()) this.updateConnectionLines();
     };
     strip.addEventListener('scroll', this._lineageScrollHandler, { passive: true });
   },

src/web/public/session-ui.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini/Antigravity/Pi),
+ * @fileoverview Quick start (case loading, session spawning for Claude/Shell/OpenCode/Codex/Gemini/Antigravity/Pi/Grok/DeepSeek),
  * session options modal (per-session settings, color picker, rename),
  * session options tabs (Ralph config tab), case settings (CRUD, links),
  * create case modal, and mobile case picker.
@@ -403,6 +403,12 @@ Object.assign(CodemanApp.prototype, {
       if (mode === 'pi') {
         return await this.runPi();
       }
+      if (mode === 'grok') {
+        return await this.runGrok();
+      }
+      if (mode === 'deepseek') {
+        return await this.runDeepSeek();
+      }
       if (mode === 'shell') {
         return await this.runShell();
       }
@@ -468,10 +474,149 @@ Object.assign(CodemanApp.prototype, {
    * run modes like the rest, and neither `agy` nor `pi` is likely to be installed.
    */
   _refreshRunModeAvailability(menu) {
-    for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']) {
+    for (const mode of ['claude', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']) {
       const btn = menu.querySelector(`.run-mode-option[data-mode="${mode}"]`);
       if (btn) btn.style.display = this.isCliAvailable(mode) ? 'flex' : 'none';
     }
+    // DeepSeek is the one mode whose availability has two halves: `dsh` can be
+    // perfectly installed while no pane-capable profile exists, because DeepSeek
+    // ships no terminal front door. In that state the honest offer is "add one",
+    // not a hidden entry with no explanation anywhere.
+    const avail = window.__codemanCliAvailable || {};
+    const dsInstall = menu.querySelector('#runModeDeepSeekInstall');
+    if (dsInstall) {
+      dsInstall.style.display = !avail.deepseek && avail.deepseekBinary ? 'flex' : 'none';
+    }
+    // The web UI needs only the BINARY: it is the one interactive surface
+    // DeepSeek ships itself, so it works on a box with no terminal profile at
+    // all (and is the honest thing to offer there).
+    const dsWeb = menu.querySelector('#runModeDeepSeekWeb');
+    if (dsWeb) dsWeb.style.display = avail.deepseekBinary ? 'flex' : 'none';
+  },
+
+  /**
+   * Start the DeepSeek Harness browser UI and open it as a Codeman web tab.
+   *
+   * The server is a background child process owned by
+   * `deepseek-web-server.ts`, NOT a shell session. It was a shell session first,
+   * on the reasoning that Codeman already supervises those, and that version
+   * worked - it just put a terminal tab on screen beside the web tab the user
+   * actually asked for, on every click. Opening a dashboard should open one tab.
+   *
+   * `--trusted-host` is the load-bearing flag: dsh fences its `/api` behind a
+   * browser-trust check on the request authority, and a Codeman web tab reaches
+   * it through Codeman's own origin via the webview proxy, not directly. Without
+   * passing Codeman's authority the page renders and every API call fails.
+   *
+   * The tab is saved `trusted: true`, and that is REQUIRED rather than a
+   * convenience: an untrusted webview is sandboxed without `allow-same-origin`,
+   * which breaks this dashboard twice over. The dsh client-runtime reads
+   * `localStorage` while loading its plugins and dies there ("the document is
+   * sandboxed and lacks the 'allow-same-origin' flag"), and an opaque-origin
+   * frame sends `Origin: null`, so dsh's own trust check 403s every `/api` call
+   * no matter which authority `--trusted-host` names. Passing `location.host`
+   * only means anything once the frame actually carries that origin.
+   *
+   * The trade this makes is real and worth stating: a trusted proxied frame is
+   * same-origin with Codeman and can therefore reach Codeman's own API. It is
+   * defensible only because of what this specific dashboard already is - an
+   * agent harness Codeman just started itself, on loopback, which can run code
+   * as the user regardless. It is not a precedent for trusting third-party
+   * dashboards generally, which is why it is set here rather than defaulted.
+   */
+  async runDeepSeekWeb() {
+    document.getElementById('runModeMenu')?.classList.remove('active');
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus('Starting the DeepSeek web UI...');
+
+    try {
+      // One request, and the server owns everything behind it: picking a free
+      // port, spawning, waiting for the port to answer, and reusing an already
+      // running server instead of racing it. This used to start the server in a
+      // shell SESSION, which worked but put a terminal tab on screen next to the
+      // web tab actually asked for, every single time.
+      //
+      // `authority` is what dsh fences its own `/api` behind (`--trusted-host`),
+      // so it must be the origin this page is loaded from rather than anything
+      // the server could guess: a Codeman reachable at both loopback and a
+      // tailnet name has two, and only the browser knows which one is in play.
+      const startRes = await fetch('/api/deepseek/web', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ authority: location.host }),
+      });
+      const startData = await startRes.json();
+      if (!startData.success) throw new Error(startData.error || 'Failed to start the DeepSeek web UI');
+      const url = startData.data.url;
+
+      // One managed record, repointed rather than duplicated: the port is chosen
+      // per launch, so creating a fresh row each time would stack a dashboard
+      // per restart, each pointing at a port nothing serves any more.
+      let webview = [...(this.webviews?.values() || [])].find((w) => w.managed === 'deepseek-web');
+      if (webview) {
+        const patchRes = await fetch(`/api/webviews/${webview.id}`, {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ url, trusted: true }),
+        });
+        const patchData = await patchRes.json();
+        if (!patchData.success) throw new Error(patchData.error || 'Failed to update the web tab');
+        webview = patchData.data.webview || patchData.data;
+      } else {
+        const wvRes = await fetch('/api/webviews', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name: 'DeepSeek Harness',
+            url,
+            icon: '\u{1F433}',
+            managed: 'deepseek-web',
+            trusted: true,
+          }),
+        });
+        const wvData = await wvRes.json();
+        if (!wvData.success) throw new Error(wvData.error || 'Failed to save the web tab');
+        webview = wvData.data.webview || wvData.data;
+      }
+      // refreshWebviews, not a hopeful optional-chain: openWebview() reads
+      // this.webviews and silently no-ops on an id it has not loaded, so
+      // skipping the refresh made the FIRST click create the record but open
+      // nothing (the SSE round-trip had not landed yet).
+      await this.refreshWebviews?.();
+
+      this._appendSessionLaunchStatus(ownsLaunchTerminal, `Serving on ${url} - opening it as a tab.`);
+      if (webview?.id) await this.openWebview(webview.id);
+    } catch (err) {
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
+    }
+  },
+
+  /**
+   * Install a DeepSeek Harness terminal profile from the run menu.
+   *
+   * Held open for as long as the package manager takes (the endpoint bounds it),
+   * so the button reports progress rather than appearing to do nothing. On
+   * success the availability map is patched in place, which is what makes the
+   * real DeepSeek entry appear without a reload.
+   */
+  async installDeepSeekProfile() {
+    const label = 'Installing a DeepSeek terminal profile (this can take a minute)...';
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(label);
+    try {
+      const res = await fetch('/api/deepseek/install-profile', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to install the profile');
+      window.__codemanCliAvailable = { ...(window.__codemanCliAvailable || {}), deepseek: !!data.data.runnable };
+      this._appendSessionLaunchStatus(ownsLaunchTerminal, `Installed ${data.data.package} into profile "${data.data.profile}".`);
+      this.showToast?.(`DeepSeek profile "${data.data.profile}" installed`, 'success');
+      const menu = document.getElementById('runModeMenu');
+      if (menu) this._refreshRunModeAvailability(menu);
+    } catch (err) {
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
+    }
   },
 
   async _loadRunModeHistory() {
@@ -565,7 +710,7 @@ Object.assign(CodemanApp.prototype, {
       gearBtn.className = `btn-toolbar btn-run-gear mode-${mode}`;
     }
     if (label) {
-      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : mode === 'antigravity' ? 'Run AG' : mode === 'pi' ? 'Run PI' : mode === 'shell' ? 'Run SH' : 'Run';
+      label.textContent = mode === 'opencode' ? 'Run OC' : mode === 'codex' ? 'Run CX' : mode === 'gemini' ? 'Run GM' : mode === 'antigravity' ? 'Run AG' : mode === 'pi' ? 'Run PI' : mode === 'grok' ? 'Run GK' : mode === 'deepseek' ? 'Run DS' : mode === 'shell' ? 'Run SH' : 'Run';
     }
   },
 
@@ -1278,6 +1423,144 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  /**
+   * Launch a Grok Build (xAI `grok`) session.
+   *
+   * Sends `grokConfig: { alwaysApprove: true }` the way runAntigravity() sends
+   * `dangerouslySkipPermissions: true`: Codeman sessions exist for autonomous
+   * work, so the Run button opts into grok's bypassPermissions mode
+   * (`--always-approve`; config-level deny rules still apply on top). The
+   * multi-user clamp forces it back off for non-granted owners server-side.
+   */
+  async runGrok() {
+    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // Remote/docker cases run grok on the OTHER side: skip the local status probe and the
+    // local-only config/env below (quick-start rejects them for remote cases).
+    const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
+    const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
+
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting Grok session in ${caseName}...`);
+    this.terminal.focus();
+
+    try {
+      if (!isRemote) {
+        const statusRes = await fetch('/api/grok/status');
+        const status = (await statusRes.json()).data;
+        if (!status.available) {
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'Grok CLI not found. Install with: curl -fsSL https://x.ai/cli/install.sh | bash'
+          );
+          return;
+        }
+      }
+
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
+      const res = await fetch('/api/quick-start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          caseName,
+          mode: 'grok',
+          sessionName: `w${this._nextCaseSessionStartNumber(caseName)}-${caseName}`,
+          ...(isRemote ? {} : {
+            grokConfig: { alwaysApprove: true },
+            ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+          }),
+        })
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to start Grok');
+      await this._ensureCreatedSessionVisible(data.data.sessionId, data.data.session);
+
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
+      }
+
+      this.terminal.focus();
+    } catch (err) {
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
+    }
+  },
+
+  /**
+   * Launch a DeepSeek Harness (`dsh`) session.
+   *
+   * Sends `permissionMode: 'danger-full-access'` for the same reason every
+   * sibling Run button sends its bypass switch: Codeman sessions exist for
+   * autonomous work. The harness has no bypass FLAG, so this rides the
+   * `DSH_PERMISSION_MODE` export instead, and the multi-user clamp forces it
+   * back down to `workspace-write` for non-granted owners server-side.
+   *
+   * `statusReporting` is left unset, i.e. ON: it is what upgrades this mode from
+   * output-stabilization guessing to definitive idle/blocked hook events.
+   *
+   * The two-part availability check is deliberate. `dsh` being installed is not
+   * enough — DeepSeek ships no terminal front door, so a box can have a perfect
+   * binary and nothing a pane can run. Reporting that precisely, with the exact
+   * command that fixes it, is the difference between "the Run button is broken"
+   * and a 30-second fix.
+   */
+  async runDeepSeek() {
+    const caseName = document.getElementById('quickStartCase').value || 'testcase';
+    // Remote/docker cases run dsh on the OTHER side: skip the local status probe and the
+    // local-only config/env below (quick-start rejects them for remote cases).
+    const _runLoc = (this.cases || []).find(c => c.name === caseName)?.location;
+    const isRemote = _runLoc === 'remote' || _runLoc === 'docker';
+
+    const ownsLaunchTerminal = this._beginSessionLaunchStatus(`Starting DeepSeek session in ${caseName}...`);
+    this.terminal.focus();
+
+    try {
+      if (!isRemote) {
+        const statusRes = await fetch('/api/deepseek/status');
+        const status = (await statusRes.json()).data;
+        if (!status.available) {
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'DeepSeek Harness CLI (dsh) not found. Install with: npm install -g @deepseek-ai/dsh'
+          );
+          return;
+        }
+        if (!status.runnable) {
+          this._reportSessionLaunchError(
+            ownsLaunchTerminal,
+            'No interactive DeepSeek Harness profile is installed. DeepSeek ships only web and headless ' +
+            'profiles, so the terminal agent comes from a plugin. Install one from the Run menu, or run: ' +
+            'dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui'
+          );
+          return;
+        }
+      }
+
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
+      const res = await fetch('/api/quick-start', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          caseName,
+          mode: 'deepseek',
+          sessionName: `w${this._nextCaseSessionStartNumber(caseName)}-${caseName}`,
+          ...(isRemote ? {} : {
+            deepSeekConfig: { permissionMode: 'danger-full-access' },
+            ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+          }),
+        })
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error || 'Failed to start DeepSeek');
+      await this._ensureCreatedSessionVisible(data.data.sessionId, data.data.session);
+
+      if (data.data.sessionId) {
+        await this.selectSession(data.data.sessionId);
+      }
+
+      this.terminal.focus();
+    } catch (err) {
+      this._reportSessionLaunchError(ownsLaunchTerminal, err.message);
+    }
+  },
+
 
   // ═══════════════════════════════════════════════════════════════
   // Session Options Modal
@@ -1343,7 +1626,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 = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi';
+    const isAltMode = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi' || session.mode === 'grok' || session.mode === 'deepseek';
     this.switchOptionsTab(isAltMode ? 'summary' : 'respawn');
 
     // Update respawn status display and buttons
@@ -1373,7 +1656,7 @@ Object.assign(CodemanApp.prototype, {
     }
 
     // Hide Claude-specific options for external CLI sessions
-    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi';
+    const isExternalCli = session.mode === 'opencode' || session.mode === 'codex' || session.mode === 'gemini' || session.mode === 'antigravity' || session.mode === 'pi' || session.mode === 'grok' || session.mode === 'deepseek';
     const claudeOnlyEls = document.querySelectorAll('[data-claude-only]');
     claudeOnlyEls.forEach(el => { el.style.display = isExternalCli ? 'none' : ''; });
 
@@ -1788,15 +2071,22 @@ Object.assign(CodemanApp.prototype, {
     const session = this.sessions.get(sessionId);
     if (!session) return;
 
+    this._activeRename?.cancel();
+
     const tabName = document.querySelector(`.tab-name[data-session-id="${sessionId}"]`);
     if (!tabName) return;
 
     // Prevent tab re-renders from destroying the input while renaming
     this._inlineRenameActive = true;
+    tabName.classList.add('tab-name-renaming');
 
     const currentName = this.getSessionName(session);
     const parsed = parseSessionPrefix(session.name);
     const originalContent = tabName.textContent;
+    const originalChildren = [...tabName.childNodes].map((node) => node.cloneNode(true));
+    const restoreOriginalChildren = () => {
+      tabName.replaceChildren(...originalChildren.map((node) => node.cloneNode(true)));
+    };
     // Clear existing content to make room for the input element
     tabName.textContent = '';
     while (tabName.firstChild) tabName.removeChild(tabName.firstChild);
@@ -1804,6 +2094,7 @@ Object.assign(CodemanApp.prototype, {
     // If prefix detected, show it as non-editable label
     if (parsed) {
       const prefixLabel = document.createElement('span');
+      prefixLabel.className = 'tab-rename-prefix';
       prefixLabel.textContent = parsed.prefix + ': ';
       prefixLabel.style.cssText = 'color: var(--text-muted); font-size: 0.75rem; white-space: nowrap;';
       tabName.appendChild(prefixLabel);
@@ -1816,36 +2107,67 @@ Object.assign(CodemanApp.prototype, {
     input.className = 'tab-rename-input';
     // 80px is tuned for the narrow header tab; a full-width sidebar row can and
     // should give the whole line to the input.
-    const renameWidth = this.isSessionSidebarActive?.() ? '100%' : '80px';
+    const renameWidth = tabName.closest('.tab-rail') ? 'auto' : this.isSessionSidebarActive?.() ? '100%' : '80px';
     input.style.cssText = `width: ${renameWidth}; min-width: 0; font-size: 0.75rem; padding: 2px 4px; background: var(--bg-input); border: 1px solid var(--accent); border-radius: 3px; color: var(--text); outline: none;`;
 
     tabName.appendChild(input);
     input.focus();
     input.select();
 
-    const finishRename = async ({ commit }) => {
-      if (!this._inlineRenameActive) return; // prevent double-fire
+    let editSettled = false;
+    let invalidated = false;
+    let completed = false;
+
+    const releaseRenderGuard = () => {
+      if (this._activeRename !== renameHandle) return;
       this._inlineRenameActive = false;
+    };
+
+    const completeCurrentRename = () => {
+      if (this._activeRename !== renameHandle) return;
+      completed = true;
+      releaseRenderGuard();
       this._activeRename = null;
+      this.renderSessionTabs();
+    };
+
+    const cancelRename = () => {
+      if (invalidated || completed) return;
+      invalidated = true;
+      editSettled = true;
+      tabName.classList.remove('tab-name-renaming');
+      restoreOriginalChildren();
+      completeCurrentRename();
+    };
+
+    const finishRename = async ({ commit }) => {
+      if (editSettled || invalidated) return;
+      editSettled = true;
+      tabName.classList.remove('tab-name-renaming');
 
       // Aborted (e.g. the session was deleted mid-rename, or Escape): re-render
       // so any ghost DOM is replaced with the canonical tab list, and skip the
       // API call — a cancel must not fire a stale rename PUT.
       if (!commit) {
-        this.renderSessionTabs();
+        cancelRename();
         return;
       }
 
+      if (this._activeRename !== renameHandle) return;
+      releaseRenderGuard();
+
       const suffix = input.value.trim();
       const fullName = parsed ? parsed.prefix + (suffix ? ': ' + suffix : '') : suffix;
-      tabName.textContent = fullName || originalContent;
+      if (fullName === session.name) restoreOriginalChildren();
+      else tabName.textContent = fullName || originalContent;
 
       // Skip the API call if the session vanished between focus and blur.
       const stillExists = this.sessions.has(sessionId);
       if (stillExists && fullName !== session.name) {
         const confirmed = await this._putSessionName(sessionId, fullName);
+        if (invalidated || this._activeRename !== renameHandle || !this.sessions.has(sessionId)) return;
         if (confirmed === null) {
-          tabName.textContent = originalContent;
+          restoreOriginalChildren();
           this.showToast('Failed to rename', 'error');
         } else {
           // The re-render below repaints from this.sessions, so the new name has
@@ -1854,14 +2176,15 @@ Object.assign(CodemanApp.prototype, {
         }
       }
       // Re-render tabs to restore full tab structure
-      this.renderSessionTabs();
+      completeCurrentRename();
     };
 
     // Register only after the input is wired so a throw above can't strand state.
-    this._activeRename = {
+    const renameHandle = {
       sessionId,
-      cancel: () => finishRename({ commit: false }),
+      cancel: cancelRename,
     };
+    this._activeRename = renameHandle;
 
     input.addEventListener('blur', () => finishRename({ commit: true }));
     input.addEventListener('keydown', (e) => {
@@ -1873,8 +2196,13 @@ Object.assign(CodemanApp.prototype, {
         e.preventDefault();
         input.blur();
       } else if (e.key === 'Escape') {
-        input.value = '';
-        input.blur();
+        // Cancel, never commit. This used to clear the field and blur, and the
+        // blur handler commits — so Escape RENAMED the session to an empty
+        // string (measured: the tab fell back to its folder name and the server
+        // stored ""), in every layout. cancelRename() marks the edit
+        // invalidated, so the blur that follows the input's removal is a no-op.
+        e.preventDefault();
+        cancelRename();
       }
     });
   },
@@ -3114,7 +3442,7 @@ Object.defineProperty(CodemanApp.prototype, 'runMode', {
   },
   set(mode) {
     this._runMode =
-      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi' || mode === 'claude'
+      mode === 'opencode' || mode === 'codex' || mode === 'gemini' || mode === 'antigravity' || mode === 'pi' || mode === 'grok' || mode === 'deepseek' || mode === 'claude'
         ? mode
         : 'claude';
   },

src/web/public/settings-ui.js

@@ -67,6 +67,19 @@ Object.assign(CodemanApp.prototype, {
     this._notifySession(data.sessionId, 'info', 'hook-stop', 'Response Complete', data.reason || 'Claude has finished responding');
   },
 
+  _onHookAgentWorking(data) {
+    // The agent started a turn, so whatever it was blocked on is gone. Reported
+    // by the DeepSeek status bridge; a harness turn cannot run while one of its
+    // own modal approvals is on screen, so this means the dialog was answered in
+    // the terminal. Same clearing as _onHookElicitationComplete, and notably NOT
+    // a notification: a turn STARTING is not news.
+    if (data.sessionId) {
+      this.clearPendingHooks(data.sessionId, 'elicitation_dialog');
+      this.clearPendingHooks(data.sessionId, 'permission_prompt');
+      this.clearPendingHooks(data.sessionId, 'idle_prompt');
+    }
+  },
+
   _onHookTeammateIdle(data) {
     const session = this.sessions.get(data.sessionId);
     this._notifySession(data.sessionId, 'warning', 'hook-teammate-idle', 'Teammate Idle', `A teammate is idle in ${session?.name || data.sessionId}`);
@@ -400,9 +413,29 @@ 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('appSettingsTabOrientation').value =
+      settings.tabOrientation ?? defaults.tabOrientation ?? 'horizontal';
+    const tabRailWidth = window.CodemanTabRail?.resolveWidth({
+      // Same default resolution as applyTabRailWidth(): a rail that has never
+      // been sized shows the width it is actually rendering at, which for
+      // detailed rows is the Wide preset rather than 256. The rich-aware
+      // default must come BEFORE the per-device defaults blob: the handheld
+      // blob carries tabRailWidth: 256, which applyTabRailWidth() never reads,
+      // so consulting it first showed a tablet's unsized rich rail as 256 while
+      // it rendered at 320 — and a routine Save then PERSISTED the 256.
+      width: settings.tabRailWidth ?? this._defaultTabRailWidth?.() ?? defaults.tabRailWidth ?? 256,
+    }) ?? 256;
+    this.syncTabRailWidthSetting?.(tabRailWidth);
+    document.getElementById('appSettingsTabRailDetail').value =
+      settings.tabRailDetail ?? defaults.tabRailDetail ?? 'rich';
     document.getElementById('appSettingsShowTabDetachButton').checked = settings.showTabDetachButton ?? defaults.showTabDetachButton ?? false;
     document.getElementById('appSettingsSessionListLayout').value =
       settings.sessionListLayout ?? defaults.sessionListLayout ?? 'header';
+    const sessionSidebarFontSize = this.resolveSessionSidebarFontSize(
+      settings.sessionSidebarFontSize ?? defaults.sessionSidebarFontSize
+    );
+    document.getElementById('appSettingsSessionSidebarFontSize').value = String(sessionSidebarFontSize);
+    document.getElementById('appSettingsSessionSidebarFontSizeValue').textContent = `${sessionSidebarFontSize} px`;
     // Claude CLI settings
     const claudeModeSelect = document.getElementById('appSettingsClaudeMode');
     const allowedToolsRow = document.getElementById('allowedToolsRow');
@@ -1199,6 +1232,8 @@ Object.assign(CodemanApp.prototype, {
       ['welcomeAntigravityBtn', 'antigravity'],
       ['welcomeGeminiBtn', 'gemini'],
       ['welcomePiBtn', 'pi'],
+      ['welcomeGrokBtn', 'grok'],
+      ['welcomeDeepSeekBtn', 'deepseek'],
       // Not a run mode, same reasoning: offering a Cloudflare Tunnel on a box
       // without cloudflared can only ever produce "cloudflared not found".
       ['welcomeTunnelBtn', 'cloudflared'],
@@ -2027,8 +2062,14 @@ Object.assign(CodemanApp.prototype, {
       webglRendererEnabled: document.getElementById('appSettingsWebglRenderer').checked,
       extendedKeyboardBar: document.getElementById('appSettingsExtendedKeyboardBar').checked,
       tabTwoRows: document.getElementById('appSettingsTabTwoRows').checked,
+      tabOrientation: document.getElementById('appSettingsTabOrientation').value,
+      tabRailWidth: this.readTabRailWidthSetting?.() ?? 256,
+      tabRailDetail: document.getElementById('appSettingsTabRailDetail').value,
       showTabDetachButton: document.getElementById('appSettingsShowTabDetachButton').checked,
       sessionListLayout: document.getElementById('appSettingsSessionListLayout').value,
+      sessionSidebarFontSize: this.resolveSessionSidebarFontSize(
+        document.getElementById('appSettingsSessionSidebarFontSize').value
+      ),
       skin: document.getElementById('appSettingsSkin').value,
       // Claude CLI settings
       claudeMode: document.getElementById('appSettingsClaudeMode').value,
@@ -2178,6 +2219,7 @@ Object.assign(CodemanApp.prototype, {
     // Re-parents #sessionTabs between header host and sidebar if the layout
     // changed, then calls applyTabWrapSettings() itself — do not call both.
     this.applySessionListLayout();
+    this.applyTabOrientation({ settleRailWidth: true });
     this.applyLineageLineSettings?.();
     this._updateTokensImmediate();  // Re-render token display (picks up showCost change)
     this.applyMonitorVisibility();
@@ -2423,7 +2465,11 @@ Object.assign(CodemanApp.prototype, {
         imageWatcherEnabled: false,
         ralphTrackerEnabled: false,
         tabTwoRows: false,
+        tabOrientation: 'horizontal',
+        tabRailWidth: 256,
+        tabRailDetail: 'rich',
         sessionListLayout: 'header',
+        sessionSidebarFontSize: 12,
         cjkInputEnabled: false,
         terminalWheelLocalScrollback: false, // mobile scrolls via touch, not wheel
         webglRendererEnabled: false, // mobile always uses the DOM renderer
@@ -2664,6 +2710,86 @@ Object.assign(CodemanApp.prototype, {
     }
   },
 
+  applyTabOrientation(options = {}) {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    const sidebarOwnsTabs = this.isSessionSidebarActive?.() === true;
+    const orientation =
+      !this.isSoloWindow && !sidebarOwnsTabs && window.CodemanTabOverflow?.resolveTabOrientation
+        ? window.CodemanTabOverflow.resolveTabOrientation({
+            deviceType: MobileDetection.getDeviceType(),
+            setting: settings.tabOrientation ?? defaults.tabOrientation ?? 'horizontal',
+          })
+        : 'horizontal';
+
+    const root = document.documentElement;
+    const previous = root.getAttribute('data-tab-orientation') || 'horizontal';
+    root.setAttribute('data-tab-orientation', orientation);
+
+    // Row detail rides on its OWN attribute, exactly like the sidebar's
+    // data-sidebar-detail: every html[data-tab-orientation='vertical'] rule in
+    // styles.css keeps matching both variants untouched, and the gate in app.js
+    // reads one attribute instead of re-parsing localStorage per tab.
+    const previousDetail = root.dataset.tabRailDetail || 'rich';
+    const detail = (settings.tabRailDetail ?? defaults.tabRailDetail ?? 'rich') === 'simple' ? 'simple' : 'rich';
+    root.dataset.tabRailDetail = detail;
+
+    const tabsEl = document.getElementById('sessionTabs');
+    const rail = document.getElementById('tabRail');
+    const headerHost = document.getElementById('sessionTabsHost');
+    if (!sidebarOwnsTabs && tabsEl && rail && headerHost) {
+      if (orientation === 'vertical') {
+        if (tabsEl.parentElement !== rail) rail.appendChild(tabsEl);
+      } else if (tabsEl.parentElement !== headerHost) {
+        headerHost.appendChild(tabsEl);
+      }
+    }
+    if (tabsEl) {
+      tabsEl.setAttribute('aria-orientation', sidebarOwnsTabs || orientation === 'vertical' ? 'vertical' : 'horizontal');
+    }
+
+    const settleRailWidth =
+      options.settleRailWidth === true && (orientation === 'vertical' || previous !== orientation);
+    this.applyTabRailWidth?.({ settle: settleRailWidth });
+    const orientationChanged = previous !== orientation;
+    // A detail flip counts as a change on its own: simple ⟷ detailed leaves the
+    // orientation on 'vertical' both times, and the stamps line is emitted by
+    // 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;
+    if (orientationChanged) {
+      this.updateTabOverflowMode?.();
+      if (!settleRailWidth) this.fitAddon?.fit();
+    }
+    // applyTabWrapSettings() is the ONE owner of tabs-show-folder and is
+    // rail-aware, so it has to run AFTER the two attributes above — the
+    // applySessionListLayout() call that precedes this one on the settings-save
+    // path ran while data-tab-rail-detail still held the old value. It
+    // re-renders by itself when the folder row appears or disappears, which is
+    // why the render below is skipped in that case rather than doubled.
+    const prevTall = this._tallTabsEnabled;
+    if (changed) this.applyTabWrapSettings?.();
+    if (changed) {
+      // Mirror of applyTabWrapSettings()'s OWN render condition, which is
+      // `prevTallTabs !== undefined && prevTallTabs !== showFolder`: its first
+      // call ever only establishes the baseline and deliberately renders
+      // nothing. Reading an undefined previous value as "it rendered" skips
+      // BOTH renders and leaves the rows stale — reachable whenever this is the
+      // first call, i.e. when the pre-paint script threw and left the
+      // attributes on their fallbacks for applyTabOrientation() to correct.
+      const wrapRendered = prevTall !== undefined && prevTall !== this._tallTabsEnabled;
+      if (!wrapRendered) this._fullRenderSessionTabs?.();
+      this._updateConnectionLinesImmediate?.();
+      this._refreshHomeSessionsIfVisible?.();
+    }
+    // Only detailed rows carry stamps that go stale with no event behind them.
+    // _fullRenderSessionTabs() settles this too, but applyTabOrientation() runs
+    // on paths where nothing re-rendered (boot with the layout already applied).
+    if (this.isRichTabRows?.()) this._startSidebarRichClock?.();
+    else this._stopSidebarRichClock?.();
+  },
+
   applyTabWrapSettings() {
     const settings = this.loadAppSettingsFromStorage();
     const defaults = this.getDefaultSettings();
@@ -2683,7 +2809,13 @@ Object.assign(CodemanApp.prototype, {
     const twoRows = !sidebar && deviceType === 'desktop'
       ? (settings.tabTwoRows ?? defaults.tabTwoRows ?? false)
       : false;
-    const showFolder = sidebar || twoRows;
+    // The DETAILED vertical rail is the third tall-row surface, for the same
+    // reason as the sidebar: it is a docked column with a row per session, and
+    // the stamps line below the name says nothing about WHICH project the
+    // session is in. Read from the applied attribute, which applyTabOrientation()
+    // has already written (app.js calls it before this).
+    const railRich = this.isTabRailRich?.() === true;
+    const showFolder = sidebar || twoRows || railRich;
     const prevTallTabs = this._tallTabsEnabled;
     this._tallTabsEnabled = showFolder;
     const tabsEl = document.getElementById('sessionTabs');
@@ -2769,7 +2901,8 @@ Object.assign(CodemanApp.prototype, {
             this.fileBrowserDragListeners._onFirstDrag = onFirstDrag;
           }
         }
-      } else {
+      } else if (fileBrowserPanel.classList.contains('visible')) {
+        this._resetFileBrowserForHide?.();
         fileBrowserPanel.classList.remove('visible');
       }
     }
@@ -2897,7 +3030,7 @@ Object.assign(CodemanApp.prototype, {
           'showFontControls', 'showSystemStats', 'showTokenCount', 'showCost',
           'showLifecycleLog', 'showResponseViewer', 'showRedrawButton',
           'showMonitor', 'showProjectInsights', 'showFileBrowser', 'showSubagents',
-          'subagentActiveTabOnly', 'tabTwoRows', 'sessionListLayout', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
+          'subagentActiveTabOnly', 'tabTwoRows', 'tabOrientation', 'tabRailWidth', 'tabRailDetail', 'sessionListLayout', 'sessionSidebarFontSize', 'localEchoEnabled', 'cjkInputEnabled', 'extendedKeyboardBar',
           'skin', 'showPlanUsageLimits', 'showAttachmentsButton', 'showFileViewerButton', 'webglRendererEnabled',
           'terminalFontFamily',
           'language',

src/web/public/styles.css

@@ -62,6 +62,7 @@
   --ring-glow: 0 0 12px -2px rgba(56, 182, 240, 0.55);
   --header-height: 36px;
   --toolbar-height: 42px;
+  --tab-rail-width: 256px;
   --sidebar-width: 260px;
   --sidebar-width-rich: 300px; /* detailed rows carry a stamps line as well */
   --sidebar-width-collapsed: 44px; /* == --touch-target-min */
@@ -347,7 +348,8 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
   .history-view-all-btn,
   .session-tab .tab-mode.gemini,
   .session-tab .tab-mode.antigravity,
-  .session-tab .tab-mode.pi
+  .session-tab .tab-mode.pi,
+  .session-tab .tab-mode.grok
 ) {
   color: var(--accent-d);
 }
@@ -574,6 +576,99 @@ body {
   background: var(--border-light);
 }
 
+.tab-rail {
+  display: none;
+  flex: 0 0 var(--tab-rail-width);
+  width: var(--tab-rail-width);
+  min-width: 0;
+  overflow: hidden;
+  background: var(--glass-bg);
+  border-right: 1px solid var(--glass-border);
+  position: relative;
+  z-index: 11;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail {
+  display: flex;
+  flex-direction: column;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tabs {
+  --lineage-vertical-gutter: 24px;
+  flex-direction: column;
+  flex-wrap: nowrap;
+  align-items: stretch;
+  gap: 2px;
+  padding: 0.35rem;
+  padding-left: calc(0.35rem + var(--lineage-vertical-gutter));
+  overflow-x: hidden;
+  overflow-y: auto;
+  max-height: none;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tab {
+  width: 100%;
+  max-width: none;
+  justify-content: flex-start;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tab > * {
+  flex-shrink: 0;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-info {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+html[data-tab-orientation='vertical'] .header-right {
+  margin-left: auto;
+}
+
+.tab-rail-resize-handle {
+  position: absolute;
+  z-index: 2;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 16px;
+  cursor: ew-resize;
+  touch-action: none;
+  transition: background-color 0.15s ease;
+}
+
+.tab-rail-resize-handle:hover,
+.tab-rail-resize-handle:focus-visible {
+  background: color-mix(in srgb, var(--accent) 24%, transparent);
+  outline: 2px solid var(--accent);
+  outline-offset: -2px;
+}
+
+html:not([data-tab-orientation='vertical']) .tab-rail-resize-handle {
+  display: none;
+}
+
+.tab-rail-resize-shield:not([hidden]) {
+  display: block;
+  position: fixed;
+  inset: 0;
+  z-index: 10000;
+  cursor: ew-resize;
+}
+
+body.tab-rail-resizing,
+body.tab-rail-resizing * {
+  cursor: ew-resize !important;
+  user-select: none !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tab-rail,
+  .tab-rail-resize-handle {
+    transition: none !important;
+  }
+}
+
 .session-tab {
   display: flex;
   align-items: center;
@@ -1421,6 +1516,53 @@ html[data-line-anim="packet"] .connection-line.line-enter {
   text-overflow: ellipsis;
 }
 
+.session-tab .tab-name-prefix {
+  display: none;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  overflow: hidden;
+  overflow-wrap: anywhere;
+  white-space: normal;
+  line-height: 1.25;
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name-prefix {
+  display: inline;
+}
+
+:is(
+  html[data-tab-orientation='vertical'] .tab-rail,
+  html[data-session-list='sidebar'] .session-sidebar
+) .session-tab .tab-name.tab-name-renaming {
+  display: flex;
+  align-items: center;
+  -webkit-box-orient: initial;
+  -webkit-line-clamp: unset;
+  line-clamp: unset;
+  overflow: visible;
+}
+
+:is(
+  html[data-tab-orientation='vertical'] .tab-rail,
+  html[data-session-list='sidebar'] .session-sidebar
+) .tab-name-renaming .tab-rename-prefix {
+  flex: 0 0 auto;
+}
+
+:is(
+  html[data-tab-orientation='vertical'] .tab-rail,
+  html[data-session-list='sidebar'] .session-sidebar
+) .tab-name-renaming .tab-rename-input {
+  flex: 1 1 0;
+  width: auto;
+  min-width: 0;
+}
+
 /* Tab folder path — hidden by default, shown via .tabs-show-folder on container */
 .session-tab .tab-folder {
   font-size: 0.6rem;
@@ -2152,6 +2294,123 @@ html[data-line-anim="packet"] .connection-line.line-enter {
   align-items: center;
 }
 
+.session-tab .tab-more {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.5rem;
+  padding: 0;
+  visibility: hidden;
+  pointer-events: none;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--text-muted);
+  font: 700 1rem/1 monospace;
+  cursor: pointer;
+}
+
+html[data-session-list='sidebar'][data-sidebar='expanded'] .session-sidebar .tab-name-row > .tab-actions > .tab-more,
+html[data-tab-orientation='vertical']:not(.tab-rail-compact) .tab-rail .tab-name-row > .tab-actions > .tab-more,
+html[data-tab-orientation='vertical'].tab-rail-compact .session-tab.active > .tab-actions > .tab-more {
+  display: inline-flex;
+}
+
+.session-tab:hover > .tab-actions > .tab-more,
+.session-tab:focus-within > .tab-actions > .tab-more,
+.session-tab.active > .tab-actions > .tab-more,
+html[data-session-list='sidebar'][data-sidebar='expanded'] .session-sidebar
+  :is(.session-tab:hover, .session-tab:focus-within, .session-tab.active)
+  .tab-name-row
+  > .tab-actions
+  > .tab-more,
+html[data-tab-orientation='vertical']:not(.tab-rail-compact) .tab-rail
+  :is(.session-tab:hover, .session-tab:focus-within, .session-tab.active)
+  .tab-name-row
+  > .tab-actions
+  > .tab-more {
+  visibility: visible;
+  pointer-events: auto;
+}
+
+html[data-tab-orientation='vertical'].tab-rail-compact .session-tab .tab-actions > :is(.tab-gear, .tab-detach, .tab-close) {
+  display: none;
+}
+
+@media (pointer: coarse) {
+  .session-tab > .tab-actions > .tab-more,
+  html[data-session-list='sidebar'][data-sidebar='expanded']
+    .session-sidebar
+    .session-tab
+    .tab-name-row
+    > .tab-actions
+    > .tab-more,
+  html[data-tab-orientation='vertical']:not(.tab-rail-compact)
+    .tab-rail
+    .session-tab
+    .tab-name-row
+    > .tab-actions
+    > .tab-more {
+    visibility: visible;
+    pointer-events: auto;
+  }
+}
+
+.tab-rail-action-menu {
+  position: fixed;
+  z-index: 2000;
+  display: grid;
+  min-width: 180px;
+  padding: 0.3rem;
+  border: 1px solid var(--glass-border);
+  border-radius: var(--btn-radius);
+  background: var(--floating-bg);
+  box-shadow: var(--elevated-shadow);
+}
+
+.tab-rail-action-menu button {
+  padding: 0.45rem 0.6rem;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--text);
+  text-align: left;
+  cursor: pointer;
+}
+
+.tab-rail-action-menu button:hover,
+.tab-rail-action-menu button:focus-visible {
+  background: var(--control-bg-hover);
+  outline: 2px solid var(--accent);
+  outline-offset: -2px;
+}
+
+.tab-rail-action-menu .danger {
+  color: var(--red);
+}
+
+:is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-range-field {
+  display: grid;
+  grid-template-columns: minmax(112px, 1fr) 44px;
+  align-items: center;
+  gap: 8px;
+  width: min(220px, 44vw);
+}
+
+:is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-range-field input {
+  width: 100%;
+  accent-color: var(--accent);
+}
+
+:is(#appSettingsModal, #sessionOptionsModal, #createCaseModal) .set-range-field output {
+  color: var(--text);
+  font-family: var(--font-mono);
+  font-size: 0.7rem;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+
 /* Pop-out button is opt-in (App Settings → Tab Bar, default off; per-device).
    settings-ui.js mirrors the setting as the tabs-show-detach class on <html>.
    A tab that is ALREADY detached keeps its icon regardless: it is the
@@ -2246,6 +2505,21 @@ body.solo-mode .btn-lifecycle-log {
   color: #f472b6;
 }
 
+.session-tab .tab-mode.grok {
+  background: rgba(212, 212, 216, 0.18);
+  color: #d4d4d8;
+}
+
+/* DeepSeek: the vendor's own brand blue. Deliberately NOT added to the
+   light-skin `--accent-d` override list above (which rescues gemini/antigravity/
+   pi/grok, whose pastels wash out on paper backgrounds) — this indigo already
+   carries enough contrast on the light skins, and overriding it would throw away
+   the one cue that separates a dsh tab from its neighbours. */
+.session-tab .tab-mode.deepseek {
+  background: rgba(77, 107, 254, 0.18);
+  color: #7c93ff;
+}
+
 /* Timer Banner - Compact */
 .timer-banner {
   display: flex;
@@ -3610,6 +3884,41 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   transform: translateY(-1px);
 }
 
+/* Grok (xAI): monochrome charcoal identity, matching .btn-toolbar.btn-run.mode-grok
+   and .run-mode-dot.grok so the welcome action reads as the same backend. */
+.welcome-btn-grok {
+  background: linear-gradient(135deg, #131316 0%, #27272a 55%, #3f3f46 100%);
+  border-color: rgba(212, 212, 216, 0.4);
+  color: #f4f4f5;
+  box-shadow: 0 2px 8px rgba(212, 212, 216, 0.12), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+.welcome-btn-grok:hover {
+  background: linear-gradient(135deg, #1f1f23 0%, #3f3f46 55%, #52525b 100%);
+  box-shadow: 0 4px 20px rgba(212, 212, 216, 0.22), 0 0 40px rgba(161, 161, 170, 0.1), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(228, 228, 231, 0.5);
+  color: #fafafa;
+  transform: translateY(-1px);
+}
+
+/* DeepSeek Harness: the #4d6bfe blue identity, matching
+   .btn-toolbar.btn-run.mode-deepseek and .run-mode-dot.deepseek so the welcome
+   action reads as the same backend. */
+.welcome-btn-deepseek {
+  background: linear-gradient(135deg, #101a4d 0%, #2740c4 55%, #4d6bfe 100%);
+  border-color: rgba(124, 147, 255, 0.4);
+  color: #eef2ff;
+  box-shadow: 0 2px 8px rgba(77, 107, 254, 0.16), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+.welcome-btn-deepseek:hover {
+  background: linear-gradient(135deg, #16225f 0%, #3350e6 55%, #6b83ff 100%);
+  box-shadow: 0 4px 20px rgba(77, 107, 254, 0.3), 0 0 40px rgba(39, 64, 196, 0.12), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(150, 170, 255, 0.5);
+  color: #f8faff;
+  transform: translateY(-1px);
+}
+
 .welcome-btn-gemini {
   background: linear-gradient(135deg, #10243f 0%, #174ea6 55%, #4f46e5 100%);
   border-color: rgba(96, 165, 250, 0.4);
@@ -4684,6 +4993,44 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
   color: #fff1f7;
 }
 
+/* Grok mode colors. Same cascade note as pi above: this base-sheet pair only
+   renders on the `og` skin — the nested `html:not([data-skin="og"])` block
+   re-declares `.btn-toolbar.btn-run` at a HIGHER specificity, so grok also
+   carries a rule inside that block (search `.btn-toolbar.btn-run.mode-grok`). */
+.btn-toolbar.btn-run.mode-grok,
+.btn-toolbar.btn-run-gear.mode-grok {
+  background: linear-gradient(135deg, #131316 0%, #27272a 55%, #3f3f46 100%);
+  border-color: rgba(212, 212, 216, 0.5);
+  color: #f4f4f5;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+.btn-toolbar.btn-run.mode-grok:hover,
+.btn-toolbar.btn-run-gear.mode-grok:hover {
+  background: linear-gradient(135deg, #1f1f23 0%, #3f3f46 55%, #52525b 100%);
+  box-shadow: 0 0 12px rgba(212, 212, 216, 0.28), 0 2px 8px rgba(63, 63, 70, 0.3), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(228, 228, 231, 0.6);
+  color: #fafafa;
+}
+
+/* DeepSeek mode colors. Same cascade note as pi/grok above: this base-sheet pair
+   only renders on the `og` skin — the nested `html:not([data-skin="og"])` block
+   re-declares `.btn-toolbar.btn-run` at a HIGHER specificity, so deepseek also
+   carries a rule inside that block (search `.btn-toolbar.btn-run.mode-deepseek`). */
+.btn-toolbar.btn-run.mode-deepseek,
+.btn-toolbar.btn-run-gear.mode-deepseek {
+  background: linear-gradient(135deg, #101a4d 0%, #2740c4 55%, #4d6bfe 100%);
+  border-color: rgba(124, 147, 255, 0.55);
+  color: #eef2ff;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+.btn-toolbar.btn-run.mode-deepseek:hover,
+.btn-toolbar.btn-run-gear.mode-deepseek:hover {
+  background: linear-gradient(135deg, #16225f 0%, #3350e6 55%, #6b83ff 100%);
+  box-shadow: 0 0 12px rgba(77, 107, 254, 0.35), 0 2px 8px rgba(39, 64, 196, 0.3), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  border-color: rgba(150, 170, 255, 0.65);
+  color: #f8faff;
+}
+
 /* Dropdown menu */
 .run-mode-menu {
   display: none;
@@ -4767,6 +5114,8 @@ body.touch-device .terminal-container .xterm .xterm-helper-textarea {
 .run-mode-dot.gemini { background: #8ab4f8; }
 .run-mode-dot.antigravity { background: #22d3ee; }
 .run-mode-dot.pi { background: #f472b6; }
+.run-mode-dot.grok { background: #a1a1aa; }
+.run-mode-dot.deepseek { background: #4d6bfe; }
 .run-mode-dot.shell { background: #94a3b8; }
 
 /* Phone-only Enter button (see index.html). Hidden by default at every width;
@@ -12023,17 +12372,20 @@ kbd {
 }
 
 /* Plan-usage chip (App Settings → Display → "Plan Usage Limits"). Shows the
-   live 5-hour + weekly plan limits parsed from the Claude statusline. Ships
+   live Claude and Codex plan limits in provider rows. Ships
    hidden via the marker class below because display is PER-DEVICE and the
    server cannot read localStorage; settings-ui.js reveals it on load (desktop
    default ON, handhelds OFF) and on a live toggle. */
 .header-plan-usage {
   display: inline-flex !important;
-  align-items: center;
-  height: 22px;
-  padding: 0 0.5rem;
-  border-radius: 11px;
+  flex-direction: column;
+  align-items: stretch;
+  justify-content: center;
+  min-height: 22px;
+  padding: 3px 0.5rem;
+  border-radius: 8px;
   font-size: 0.7rem;
+  line-height: 1.1;
   font-weight: 500;
   font-family: 'SF Mono', Monaco, monospace;
   color: var(--text-dim);
@@ -12042,6 +12394,23 @@ kbd {
   white-space: nowrap;
   cursor: default;
 }
+.header-plan-usage .pu-row {
+  display: flex;
+  align-items: baseline;
+}
+.header-plan-usage .pu-provider {
+  width: 46px;
+  flex: 0 0 46px;
+  font-size: 0.58rem;
+  font-weight: 700;
+  color: var(--text-dim);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.header-plan-usage .pu-windows {
+  display: inline-flex;
+  align-items: baseline;
+}
 /* Readable two-window layout: dim uppercase label + bold, color-coded value. */
 .header-plan-usage .pu-win {
   display: inline-flex;
@@ -14102,6 +14471,25 @@ html:not([data-skin="og"]) {
   color: #fff1f7;
 }
 .btn-toolbar.btn-run.mode-pi:hover { box-shadow: 0 0 14px -2px rgba(244, 114, 182, 0.45); }
+/* Grok keeps its charcoal identity on the non-og skins. Same specificity trap
+   as pi above: without this rule the generic `.btn-toolbar.btn-run` in this
+   nested block wins and grok renders as generic claude blue. */
+.btn-toolbar.btn-run.mode-grok {
+  background: linear-gradient(135deg, #27272a, #52525b);
+  border-color: #18181b;
+  color: #fafafa;
+}
+.btn-toolbar.btn-run.mode-grok:hover { box-shadow: 0 0 14px -2px rgba(161, 161, 170, 0.5); }
+/* DeepSeek keeps its indigo on the non-og skins — same specificity trap as pi
+   and grok above: without this rule the generic `.btn-toolbar.btn-run` in this
+   nested block wins and deepseek renders as generic claude blue, which is the
+   one colour it must not be mistaken for. */
+.btn-toolbar.btn-run.mode-deepseek {
+  background: linear-gradient(135deg, #2740c4, #4d6bfe);
+  border-color: #1b2a8f;
+  color: #f8faff;
+}
+.btn-toolbar.btn-run.mode-deepseek:hover { box-shadow: 0 0 14px -2px rgba(77, 107, 254, 0.55); }
 .btn-toolbar.btn-run-gear {
   background: var(--accent-d);
   border-color: var(--accent);
@@ -14754,6 +15142,10 @@ html[data-skin="daylight-blue"] .welcome-btn-tunnel.active:hover {
   display: none;
 }
 
+html[data-tab-orientation='vertical'] .home-sessions {
+  display: none !important;
+}
+
 /* Belt and braces with shouldShowHomeSessions(): a resize that outruns the
    matchMedia listener must never leave the column overlapping the content. */
 @media (max-width: 1179px) {
@@ -16530,6 +16922,13 @@ html[data-skin="daylight-blue"] .welcome-btn-tunnel.active:hover {
   padding: 0 22px 22px;
 }
 
+#sessionOptionsModal #context-tab {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 0.25rem 1rem;
+  align-items: start;
+}
+
 #sessionOptionsModal .set-section {
   padding-top: 18px;
 }
@@ -16547,6 +16946,22 @@ html[data-skin="daylight-blue"] .welcome-btn-tunnel.active:hover {
   font-size: 0.75rem;
 }
 
+@media (min-width: 1200px) {
+  #sessionOptionsModal .modal-content.modal-lg {
+    width: min(1120px, 96vw);
+    max-width: min(1120px, 96vw);
+  }
+
+  #sessionOptionsModal #context-tab {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  #sessionOptionsModal #context-tab > .set-section-head,
+  #sessionOptionsModal #context-tab > .set-section-blurb {
+    grid-column: 1 / -1;
+  }
+}
+
 #sessionOptionsModal .set-group + .set-group {
   margin-top: 16px;
 }
@@ -16836,10 +17251,27 @@ html[data-session-list="sidebar"] .session-sidebar .tab-info {
   min-width: 0;
 }
 
+html[data-session-list="sidebar"] .session-sidebar .tab-name-row,
 html[data-session-list="sidebar"] .session-sidebar .tab-name {
+  min-width: 0;
   max-width: none;
 }
 
+html[data-session-list='sidebar'] .session-sidebar .tab-name {
+  flex: 0 1 auto;
+  white-space: nowrap;
+  font-size: var(--session-sidebar-name-font-size, 12px);
+}
+
+html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name {
+  font-size: var(--session-sidebar-name-font-size, 12px);
+}
+
+html[data-session-list='sidebar'] .session-sidebar .tab-actions,
+html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name-row > .tab-actions {
+  flex-shrink: 0;
+}
+
 /* Reveal-on-hover reads badly on a 40px-tall full-width row, so keep the row
    actions permanently visible on the active session — no layout jitter when
    the pointer crosses the list. */
@@ -16853,11 +17285,13 @@ html[data-session-list="sidebar"] .session-sidebar .session-tab.active .tab-clos
 /* Drag-reorder indicators become horizontal edges. The class names stay
    drag-over-left / drag-over-right (they read as before/after now) so app.js,
    the base rules above and the generated gesture bundle need no renaming. */
-html[data-session-list="sidebar"] .session-sidebar .session-tab.drag-over-left {
+html[data-session-list="sidebar"] .session-sidebar .session-tab.drag-over-left,
+html[data-tab-orientation='vertical'] .tab-rail .session-tab.drag-over-left {
   box-shadow: 0 -2px 0 0 var(--accent);
 }
 
-html[data-session-list="sidebar"] .session-sidebar .session-tab.drag-over-right {
+html[data-session-list="sidebar"] .session-sidebar .session-tab.drag-over-right,
+html[data-tab-orientation='vertical'] .tab-rail .session-tab.drag-over-right {
   box-shadow: 0 2px 0 0 var(--accent);
 }
 
@@ -16870,19 +17304,31 @@ html[data-session-list="sidebar"] .session-tab.tab-filtered-out {
   display: none !important;
 }
 
-/* --- Rich rows (sessionListLayout 'sidebar-rich') ----------------------- */
+/* --- Rich rows (sessionListLayout 'sidebar-rich' + tabRailDetail 'rich') --- */
 /* The detailed variant of the SAME sidebar: identical column, identical
    re-parented #sessionTabs, identical filter and Alt+B toggle. The only
    difference is that each row also carries the line the desktop home rail and
    the phone overview carry — when the session was first created, how long it
    has been in the state it is in, and a status pill.
 
-   Everything here is scoped to html[data-sidebar-detail="rich"], which
+   The VERTICAL TAB RAIL is the second surface that draws those rows (it is a
+   docked column too, and #sessionTabs is the same element re-parented into it),
+   so every rule below carries a rail twin as an extra COMMA-GROUPED selector.
+   Deliberately not :is(): an :is() list takes its most specific argument's
+   specificity, which would silently raise the sidebar arm from (0,3,1) to the
+   rail arm's (0,5,1) and let these paint rules outrank things they never used
+   to. Grouped selectors each keep their own weight.
+
+   Sidebar rules are scoped to html[data-sidebar-detail="rich"], which
    applySessionListLayout() only ever sets to 'rich' while data-session-list is
-   'sidebar'. `.tab-meta` is emitted by the row template exclusively in that
-   mode, so these rules have nothing to match anywhere else — the display:none
-   below is the second lock, not the mechanism. */
-html[data-sidebar-detail="rich"] .session-sidebar .tab-meta {
+   'sidebar'; rail rules to html[data-tab-orientation='vertical']
+   [data-tab-rail-detail='rich']:not(.tab-rail-compact), so a rail dragged below
+   240px drops back to simple rows the same way the collapsed sidebar does.
+   `.tab-meta` is emitted by the row template exclusively in those modes, so
+   these rules have nothing to match anywhere else — the display:none below is
+   the second lock, not the mechanism. */
+html[data-sidebar-detail="rich"] .session-sidebar .tab-meta,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta {
   display: flex;
   align-items: center;
   gap: 0.35em;
@@ -16904,33 +17350,56 @@ html[data-sidebar-detail="rich"] .session-sidebar .tab-meta {
   display: none;
 }
 
-html[data-sidebar-detail="rich"] .session-sidebar .tab-meta-item {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-meta-item,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta-item {
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
 }
 
-html[data-sidebar-detail="rich"] .session-sidebar .tab-meta-key {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-meta-key,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta-key {
   margin-right: 0.35em;
   opacity: 0.7;
   text-transform: uppercase;
   letter-spacing: 0.06em;
 }
 
-html[data-sidebar-detail="rich"] .session-sidebar .tab-meta-sep {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-meta-sep,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta-sep {
   opacity: 0.45;
 }
 
+/* Narrower than the detailed default (the .tab-rail-tight class,
+   _setTabRailWidth): the created stamp is dropped rather than shown as
+   "CREA…". Its value stays reachable as the tooltip on the meta LINE
+   (`.tab-meta` carries both absolute stamps, _sidebarRichMetaHTML) — the title
+   on the hidden `.tab-meta-created` itself goes away with it, since a
+   `display: none` element has no hover target. */
+html.tab-rail-tight[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta-created,
+html.tab-rail-tight[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta-sep {
+  display: none;
+}
+
+/* On a rail narrower than the detailed default, the state duration is the last
+   thing that should go: it is the number the row is sorted by, and the pill
+   next to it is only a word. The created stamp ellipsizes instead. */
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-meta-since {
+  flex-shrink: 0;
+}
+
 /* While a session is actually doing something, how long it has been doing it is
    what the eye should land on — same emphasis the home rail gives it. */
-html[data-sidebar-detail="rich"] .session-sidebar .session-tab.tab-state-working .tab-meta-since {
+html[data-sidebar-detail="rich"] .session-sidebar .session-tab.tab-state-working .tab-meta-since,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .session-tab.tab-state-working .tab-meta-since {
   color: var(--green);
   opacity: 0.95;
 }
 
 /* Pushed hard right and never shrinking, so the stamps ellipsize before the
    status word does. */
-html[data-sidebar-detail="rich"] .session-sidebar .tab-pill {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill {
   flex-shrink: 0;
   margin-left: auto;
   padding: 0.1em 0.5em;
@@ -16947,19 +17416,23 @@ html[data-sidebar-detail="rich"] .session-sidebar .tab-pill {
 /* Same three colors as every other session surface: red means a question is
    pending, yellow means it wants input, green means work is happening. */
 html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--needs,
-html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--error {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--error,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--needs,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--error {
   background: color-mix(in srgb, var(--red) 18%, transparent);
   border-color: color-mix(in srgb, var(--red) 45%, transparent);
   color: var(--red);
 }
 
-html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--waiting {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--waiting,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--waiting {
   background: color-mix(in srgb, var(--yellow) 18%, transparent);
   border-color: color-mix(in srgb, var(--yellow) 45%, transparent);
   color: var(--yellow);
 }
 
-html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--working {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--working,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--working {
   background: color-mix(in srgb, var(--green) 15%, transparent);
   border-color: color-mix(in srgb, var(--green) 40%, transparent);
   color: var(--green);
@@ -16967,7 +17440,8 @@ html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--working {
 
 /* Muted one step further than the idle dot: the pill is a block of color, so it
    reads louder than a 9px dot at the same mix. */
-html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--idle {
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--idle,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--idle {
   background: color-mix(in srgb, var(--green) 7%, transparent);
   border-color: color-mix(in srgb, var(--green) 18%, var(--border));
   color: color-mix(in srgb, var(--green) 45%, var(--text-muted));
@@ -16982,7 +17456,8 @@ html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--idle {
    then just a status dot and its badges. Without the guard, `align-items:
    flex-start` and a 0.15rem top margin on .tab-status would push that dot off
    the centre line of every row in the rail. */
-html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sidebar .session-tab {
+html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sidebar .session-tab,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .session-tab {
   align-items: flex-start;
   padding: 0.45rem 0.5rem;
 }
@@ -16991,7 +17466,10 @@ html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sideba
    three-line one it drifts low, so pin it to the name it acts on. */
 html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sidebar .session-tab .tab-actions,
 html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sidebar .session-tab .tab-number,
-html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sidebar .session-tab .tab-status {
+html[data-sidebar-detail="rich"]:not([data-sidebar="collapsed"]) .session-sidebar .session-tab .tab-status,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .session-tab .tab-name-row > .tab-actions,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .session-tab .tab-number,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .session-tab .tab-status {
   margin-top: 0.15rem;
 }
 

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

@@ -0,0 +1,371 @@
+/**
+ * @fileoverview Accessible, device-local vertical session-rail sizing.
+ *
+ * Pointer + keyboard resizing for the vertical tab rail (`tabOrientation:
+ * 'vertical'`), with a preferred width persisted per device (`tabRailWidth`)
+ * and re-clamped against the viewport on resize. During a drag it takes
+ * ownership of terminal refits (`_tabRailResizeOwnsObserver` suppresses
+ * terminal-ui's throttled ResizeObserver) and performs ONE settle-time resize,
+ * reverting per-frame below 40 columns so the PTY is never thrashed.
+ *
+ * @dependency CodemanApp (app.js) - methods attach to its prototype
+ * @dependency CodemanTabRail (constants.js) - width policy (resolveWidth, bounds)
+ * @loadorder 6.5 (after app.js, before terminal-ui.js)
+ */
+
+Object.assign(CodemanApp.prototype, {
+  _getTabRailMinimumTerminalWidth() {
+    const cellWidth = this.terminal?._core?._renderService?.dimensions?.css?.cell?.width;
+    if (Number.isFinite(cellWidth) && cellWidth > 0) return Math.ceil(cellWidth * 40 + 24);
+    return 420;
+  },
+
+  _getTabRailBounds() {
+    const main = document.querySelector('.main');
+    return {
+      viewportWidth: window.innerWidth,
+      mainWidth: main?.clientWidth || window.innerWidth,
+      minTerminalWidth: this._getTabRailMinimumTerminalWidth(),
+    };
+  },
+
+  _getCurrentTabRailWidth() {
+    const fromCss = Number.parseFloat(document.documentElement.style.getPropertyValue('--tab-rail-width'));
+    if (Number.isFinite(fromCss)) return fromCss;
+    const measured = document.getElementById('tabRail')?.getBoundingClientRect?.().width;
+    return Number.isFinite(measured) && measured > 0 ? measured : window.CodemanTabRail?.DEFAULT_WIDTH || 256;
+  },
+
+  readTabRailWidthSetting() {
+    const select = document.getElementById('appSettingsTabRailWidth');
+    if (!select) return this._getCurrentTabRailWidth();
+    if (select.value === 'custom') return Number(select.dataset.currentWidth) || this._getCurrentTabRailWidth();
+    return Number(select.value) || window.CodemanTabRail?.DEFAULT_WIDTH || 256;
+  },
+
+  syncTabRailWidthSetting(width) {
+    const select = document.getElementById('appSettingsTabRailWidth');
+    if (!select) return;
+    const rounded = Math.round(width);
+    select.dataset.currentWidth = String(rounded);
+    const preset = select.querySelector(`option[value="${rounded}"]`);
+    if (preset) {
+      select.value = String(rounded);
+      return;
+    }
+    const custom = select.querySelector('option[value="custom"]');
+    if (custom) custom.textContent = `Custom (${rounded}px)`;
+    select.value = 'custom';
+  },
+
+  _setTabRailWidth(width) {
+    const policy = window.CodemanTabRail;
+    if (!policy) return 256;
+    const preferred = policy.resolveWidth({ width });
+    const bounds = this._getTabRailBounds();
+    const resolved = policy.resolveWidth({ width: preferred, ...bounds });
+    const effectiveMax = policy.resolveWidth({ width: policy.MAX_WIDTH, ...bounds });
+    const root = document.documentElement;
+    root.style.setProperty('--tab-rail-width', `${resolved}px`);
+    const wasCompact = root.classList.contains('tab-rail-compact');
+    const compact = resolved < 240;
+    root.classList.toggle('tab-rail-compact', compact);
+    // Second, softer threshold, CSS-only: a detailed row carries two stamps and
+    // below ~288px the created one ellipsizes to "CREA…", which says nothing.
+    // It is dropped there instead, leaving the state duration (the number the
+    // list is ordered by) and its pill intact. No re-render — unlike the rows
+    // themselves, this is a display toggle on markup that is already there.
+    root.classList.toggle('tab-rail-tight', resolved < 288);
+    if (wasCompact !== compact) {
+      // The folder line is owned by applyTabWrapSettings(), whose railRich
+      // input reads the compact class this function just toggled — without
+      // re-running it, a rich rail dragged below 240px kept emitting folder
+      // rows (and, for a stored width < 240, kept them across reloads: the
+      // boot-time wrap pass runs before this function first applies the
+      // class). It re-renders only when the folder flag actually flipped, so
+      // cover the flip-without-folder-change case (a simple-detail rail
+      // crossing 240px still changes the row-action affordance) without
+      // rendering twice.
+      const prevTall = this._tallTabsEnabled;
+      this.applyTabWrapSettings?.();
+      const wrapRendered = prevTall !== undefined && this._tallTabsEnabled !== prevTall;
+      if (!wrapRendered) this._fullRenderSessionTabs?.();
+    }
+    const handle = document.getElementById('tabRailResizeHandle');
+    if (handle) {
+      handle.setAttribute('aria-valuemax', String(effectiveMax));
+      handle.setAttribute('aria-valuenow', String(resolved));
+    }
+    this.syncTabRailWidthSetting(preferred);
+    return resolved;
+  },
+
+  _persistTabRailWidth(width) {
+    const settings = this.loadAppSettingsFromStorage();
+    if (settings.tabRailWidth === width) return;
+    settings.tabRailWidth = width;
+    this.saveAppSettingsToStorage(settings);
+  },
+
+  _claimTabRailResize() {
+    this._tabRailResizeOwnsObserver = true;
+    clearTimeout(this._tabRailResizeWatchdog);
+    clearTimeout(this._tabRailReleaseTimer);
+    if (this._tabRailReleaseRaf) cancelAnimationFrame(this._tabRailReleaseRaf);
+    this._armTabRailResizeWatchdog();
+    if (this._resizeRaf) cancelAnimationFrame(this._resizeRaf);
+    if (this._resizeTimeout) clearTimeout(this._resizeTimeout);
+    this._resizeRaf = null;
+    this._resizeTimeout = null;
+  },
+
+  _armTabRailResizeWatchdog() {
+    this._tabRailResizeWatchdog = setTimeout(() => {
+      this._tabRailResizeWatchdog = null;
+      if (document.body.classList.contains('tab-rail-resizing')) {
+        this._armTabRailResizeWatchdog();
+        return;
+      }
+      this._tabRailResizeOwnsObserver = false;
+    }, 1000);
+  },
+
+  _releaseTabRailResize() {
+    clearTimeout(this._tabRailResizeWatchdog);
+    this._tabRailResizeWatchdog = null;
+    const release = () => {
+      clearTimeout(this._tabRailReleaseTimer);
+      this._tabRailReleaseTimer = null;
+      this._tabRailReleaseRaf = null;
+      this._tabRailResizeOwnsObserver = false;
+    };
+    if (typeof requestAnimationFrame === 'function') {
+      this._tabRailReleaseRaf = requestAnimationFrame(() => {
+        this._tabRailReleaseRaf = requestAnimationFrame(release);
+      });
+      this._tabRailReleaseTimer = setTimeout(release, 250);
+    } else release();
+  },
+
+  _scheduleTabRailSettle(effective, preferred = effective) {
+    clearTimeout(this._tabRailSettleTimer);
+    this._tabRailSettleTimer = setTimeout(async () => {
+      this._tabRailSettleTimer = null;
+      this._persistTabRailWidth(preferred);
+      try {
+        if (this.activeSessionId && this.sendResize) await this.sendResize(this.activeSessionId);
+        else this.fitAddon?.fit();
+        this._updateConnectionLinesImmediate?.();
+      } catch (error) {
+        console.warn('Failed to resize terminal after rail resize:', error);
+      } finally {
+        this._releaseTabRailResize();
+      }
+    }, 150);
+  },
+
+  /**
+   * The width a rail gets when the user has never picked one.
+   *
+   * Detailed rows carry a third line ("created 3d ago · working 12m" plus a
+   * status pill) and at 256px that line ellipsizes before it is finished — the
+   * same reason the rich SIDEBAR is 300px and the simple one 260px. 320px is
+   * the existing Wide preset, so a fresh detailed rail lands on a named choice
+   * rather than reading "Custom" in the settings select.
+   *
+   * Only the DEFAULT moves: a width the user has actually chosen (stored) is
+   * never overridden, and dragging the rail narrower is never fought — below
+   * 240px the rows drop back to simple ones on their own.
+   */
+  _defaultTabRailWidth() {
+    const rich = document.documentElement.dataset.tabRailDetail !== 'simple';
+    if (rich) return window.CodemanTabRail?.RICH_DEFAULT_WIDTH ?? 320;
+    return window.CodemanTabRail?.DEFAULT_WIDTH ?? 256;
+  },
+
+  applyTabRailWidth(options = {}) {
+    const settings = this.loadAppSettingsFromStorage();
+    const requested = settings.tabRailWidth ?? this._defaultTabRailWidth();
+    const preferred = window.CodemanTabRail?.resolveWidth({ width: requested }) ?? 256;
+    if (options.settle) this._claimTabRailResize();
+    const resolved = this._setTabRailWidth(preferred);
+    if (options.persist !== false && requested !== preferred) this._persistTabRailWidth(preferred);
+    if (options.settle) this._scheduleTabRailSettle(resolved, preferred);
+    return resolved;
+  },
+
+  _applyTabRailPointerWidth(clientX) {
+    const main = document.querySelector('.main');
+    if (!main) return this._getCurrentTabRailWidth();
+    const previous = this._getCurrentTabRailWidth();
+    const width = this._setTabRailWidth(clientX - main.getBoundingClientRect().left);
+    let proposed = null;
+    try {
+      proposed = this.fitAddon?.proposeDimensions?.();
+    } catch {}
+    return proposed && proposed.cols < 40 ? this._setTabRailWidth(previous) : width;
+  },
+
+  _queueTabRailPointerWidth(clientX) {
+    this._tabRailPendingClientX = clientX;
+    if (this._tabRailPointerRaf) return;
+    this._tabRailPointerRaf = requestAnimationFrame(() => {
+      this._tabRailPointerRaf = null;
+      this._tabRailDragWidth = this._applyTabRailPointerWidth(this._tabRailPendingClientX);
+    });
+  },
+
+  _finishTabRailDrag(handle, pointerId) {
+    if (!document.body.classList.contains('tab-rail-resizing')) return;
+    if (this._tabRailPointerRaf) {
+      cancelAnimationFrame(this._tabRailPointerRaf);
+      this._tabRailPointerRaf = null;
+      this._tabRailDragWidth = this._applyTabRailPointerWidth(this._tabRailPendingClientX);
+    }
+    document.body.classList.remove('tab-rail-resizing');
+    const shield = document.getElementById('tabRailResizeShield');
+    if (shield) shield.hidden = true;
+    try {
+      if (handle.hasPointerCapture?.(pointerId)) handle.releasePointerCapture(pointerId);
+    } catch {}
+    const preferred = window.CodemanTabRail?.resolveWidth({ width: this._tabRailDragWidth }) ?? this._tabRailDragWidth;
+    this._scheduleTabRailSettle(this._tabRailDragWidth || this._getCurrentTabRailWidth(), preferred);
+  },
+
+  _onTabRailKeyDown(event) {
+    const width = window.CodemanTabRail?.resolveKeyboardWidth({
+      key: event.key,
+      shiftKey: event.shiftKey,
+      currentWidth: this._getCurrentTabRailWidth(),
+      defaultWidth: this._defaultTabRailWidth?.(),
+      ...this._getTabRailBounds(),
+    });
+    if (width === null || width === undefined) return;
+    event.preventDefault();
+    this._claimTabRailResize();
+    const effective = this._setTabRailWidth(width);
+    this._scheduleTabRailSettle(effective, window.CodemanTabRail.resolveWidth({ width }));
+  },
+
+  initTabRailResize() {
+    const handle = document.getElementById('tabRailResizeHandle');
+    if (!handle || handle.dataset.ready === '1') return;
+    handle.dataset.ready = '1';
+    this.applyTabRailWidth();
+    handle.addEventListener('pointerdown', (event) => {
+      if (event.button !== 0) return;
+      event.preventDefault();
+      this.closeTabRailActionMenu();
+      this._claimTabRailResize();
+      this._tabRailDragWidth = this._getCurrentTabRailWidth();
+      this._tabRailPendingClientX = event.clientX;
+      document.body.classList.add('tab-rail-resizing');
+      const shield = document.getElementById('tabRailResizeShield');
+      if (shield) shield.hidden = false;
+      try {
+        handle.setPointerCapture(event.pointerId);
+      } catch {
+        document.body.classList.remove('tab-rail-resizing');
+        if (shield) shield.hidden = true;
+        this._releaseTabRailResize();
+      }
+    });
+    handle.addEventListener('pointermove', (event) => {
+      if (handle.hasPointerCapture?.(event.pointerId)) this._queueTabRailPointerWidth(event.clientX);
+    });
+    handle.addEventListener('pointerup', (event) => this._finishTabRailDrag(handle, event.pointerId));
+    handle.addEventListener('pointercancel', (event) => this._finishTabRailDrag(handle, event.pointerId));
+    handle.addEventListener('lostpointercapture', (event) => this._finishTabRailDrag(handle, event.pointerId));
+    handle.addEventListener('keydown', (event) => this._onTabRailKeyDown(event));
+    handle.addEventListener('dblclick', (event) => {
+      event.preventDefault();
+      this._claimTabRailResize();
+      // Rich-aware: resetting a detailed rail to 256 would land it below the
+      // 288px tight threshold and silently drop the created stamp.
+      const preferred = this._defaultTabRailWidth?.() ?? (window.CodemanTabRail?.DEFAULT_WIDTH || 256);
+      const effective = this._setTabRailWidth(preferred);
+      this._scheduleTabRailSettle(effective, preferred);
+    });
+
+    let resizeTimer = null;
+    window.addEventListener('resize', () => {
+      clearTimeout(resizeTimer);
+      resizeTimer = setTimeout(() => {
+        this.applyTabOrientation?.();
+        this.applyTabRailWidth({ persist: false });
+      }, 100);
+    });
+  },
+
+  closeTabRailActionMenu(options = {}) {
+    const menu = document.querySelector('.tab-rail-action-menu');
+    const trigger = this._tabRailActionMenuTrigger;
+    menu?.remove();
+    if (this._tabRailActionMenuOutside) {
+      document.removeEventListener('pointerdown', this._tabRailActionMenuOutside, true);
+      this._tabRailActionMenuOutside = null;
+    }
+    if (this._tabRailActionMenuViewport) {
+      window.removeEventListener('resize', this._tabRailActionMenuViewport);
+      this._tabRailActionMenuViewport = null;
+    }
+    this._tabRailActionMenuTrigger = null;
+    if (options.restoreFocus) trigger?.focus?.();
+  },
+
+  openTabRailActionMenu(event, sessionId) {
+    event.preventDefault();
+    event.stopPropagation();
+    this.closeTabRailActionMenu();
+    const trigger = event.currentTarget;
+    const menu = document.createElement('div');
+    menu.className = 'tab-rail-action-menu';
+    menu.setAttribute('role', 'menu');
+    menu.setAttribute('aria-label', 'Session actions');
+    const settings = this.loadAppSettingsFromStorage();
+    const actions = [
+      { label: 'Session options', run: () => this.openSessionOptions(sessionId) },
+      ...(settings.showTabDetachButton || this.detachedSessions?.has(sessionId)
+        ? [{ label: 'Open in a new window', run: () => this.detachSession(sessionId) }]
+        : []),
+      { label: 'Close session', className: 'danger', run: () => this.requestCloseSession(sessionId) },
+    ];
+    for (const action of actions) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.setAttribute('role', 'menuitem');
+      button.textContent = action.label;
+      if (action.className) button.className = action.className;
+      button.addEventListener('click', () => {
+        this.closeTabRailActionMenu();
+        action.run();
+      });
+      menu.appendChild(button);
+    }
+    document.body.appendChild(menu);
+    const rect = trigger.getBoundingClientRect();
+    const menuRect = menu.getBoundingClientRect();
+    menu.style.left = `${Math.max(8, Math.min(rect.right - menuRect.width, window.innerWidth - menuRect.width - 8))}px`;
+    menu.style.top = `${Math.max(8, Math.min(rect.bottom + 4, window.innerHeight - menuRect.height - 8))}px`;
+    this._tabRailActionMenuTrigger = trigger;
+    this._tabRailActionMenuOutside = (pointerEvent) => {
+      if (!menu.contains(pointerEvent.target) && pointerEvent.target !== trigger) this.closeTabRailActionMenu();
+    };
+    document.addEventListener('pointerdown', this._tabRailActionMenuOutside, true);
+    this._tabRailActionMenuViewport = () => this.closeTabRailActionMenu();
+    window.addEventListener('resize', this._tabRailActionMenuViewport, { once: true });
+    menu.addEventListener('keydown', (keyEvent) => {
+      const buttons = [...menu.querySelectorAll('button')];
+      const index = buttons.indexOf(document.activeElement);
+      if (keyEvent.key === 'Escape') {
+        keyEvent.preventDefault();
+        this.closeTabRailActionMenu({ restoreFocus: true });
+      } else if (keyEvent.key === 'ArrowDown' || keyEvent.key === 'ArrowUp') {
+        keyEvent.preventDefault();
+        const direction = keyEvent.key === 'ArrowDown' ? 1 : -1;
+        buttons[(index + direction + buttons.length) % buttons.length]?.focus();
+      }
+    });
+    menu.querySelector('button')?.focus();
+  },
+});

src/web/public/terminal-ui.js

@@ -901,6 +901,7 @@ Object.assign(CodemanApp.prototype, {
     const MIN_ROWS = 10;
 
     const throttledResize = () => {
+      if (this._tabRailResizeOwnsObserver) return;
       // Trailing-edge debounce: ALL resize work (fit + clear + SIGWINCH) happens
       // once after the user stops resizing. During active resize, the terminal
       // stays at its old dimensions for up to 300ms.
@@ -2213,7 +2214,7 @@ Object.assign(CodemanApp.prototype, {
     }
     titleSpan.appendChild(document.createTextNode(this._historyRowLabel(s, shortDir)));
 
-    // Badge row: mode (claude/codex/opencode/gemini/antigravity/pi/shell) + a LIVE pill.
+    // Badge row: mode (claude/codex/opencode/gemini/antigravity/pi/grok/deepseek/shell) + a LIVE pill.
     const badgeRow = document.createElement('div');
     badgeRow.className = 'history-item-badges';
     if (s.mode) {
@@ -3166,7 +3167,7 @@ Object.assign(CodemanApp.prototype, {
    * arrived, which looked like truncated responses and idle shell commands.
    */
   _scheduleTerminalWriteFlush() {
-    if (this.writeFrameScheduled || this.pendingWrites.length === 0) return;
+    if (this._terminalWriteInFlight || this.writeFrameScheduled || this.pendingWrites.length === 0) return;
     this.writeFrameScheduled = true;
     this._safeYield(() => {
       this.writeFrameScheduled = false;
@@ -3357,7 +3358,7 @@ Object.assign(CodemanApp.prototype, {
    * Strips markers and writes content atomically within a single frame.
    */
   flushPendingWrites() {
-    if (this.pendingWrites.length === 0 || !this.terminal) return;
+    if (this._terminalWriteInFlight || this.pendingWrites.length === 0 || !this.terminal) return;
 
     const _t0 = performance.now();
     // xterm.js 6.0+ natively handles DEC 2026 synchronized output markers.
@@ -3388,14 +3389,25 @@ Object.assign(CodemanApp.prototype, {
     const preserveViewportY =
       this.terminal.buffer?.active && !this.isTerminalAtBottom() ? this.terminal.buffer.active.viewportY : null;
 
-    if (_joinedLen <= MAX_FRAME_BYTES) {
-      this.terminal.write(joined);
-    } else {
-      // Write first chunk now, defer rest to next frame
-      this.terminal.write(joined.slice(0, MAX_FRAME_BYTES));
+    const writeChunk = joined.slice(0, MAX_FRAME_BYTES);
+    if (_joinedLen > MAX_FRAME_BYTES) {
+      // Keep the remainder app-side where the 128KB cap can see it. The next
+      // chunk is scheduled only after xterm confirms this one was parsed.
       this.pendingWrites.push(joined.slice(MAX_FRAME_BYTES));
       deferred = true;
-      this._scheduleTerminalWriteFlush();
+    }
+    this._terminalWriteInFlight = true;
+    this._terminalWriteInFlightBytes = writeChunk.length;
+    try {
+      this.terminal.write(writeChunk, () => {
+        this._terminalWriteInFlight = false;
+        this._terminalWriteInFlightBytes = 0;
+        this._scheduleTerminalWriteFlush();
+      });
+    } catch (err) {
+      this._terminalWriteInFlight = false;
+      this._terminalWriteInFlightBytes = 0;
+      throw err;
     }
     if (
       preserveViewportY !== null &&

src/web/public/webview-tabs.js

@@ -302,7 +302,10 @@ Object.assign(CodemanApp.prototype, {
   renderWebviewMenuItems() {
     const container = document.getElementById('runModeWebviews');
     if (!container) return;
-    const list = [...(this.webviews?.values() || [])];
+    // Managed records are maintained by their own menu entry (the DeepSeek web
+    // UI shortcut), so listing them here showed one dashboard twice: the
+    // shortcut that starts it, and the row it wrote on the previous click.
+    const list = [...(this.webviews?.values() || [])].filter((w) => !w.managed);
     if (list.length === 0) {
       container.innerHTML = '<div class="run-mode-empty">No URLs yet</div>';
       return;

src/web/response-viewer-transcript.ts

@@ -11,7 +11,7 @@ export interface ResponseViewerTranscriptBlock {
 // Keep in lockstep with isExternalCliMode() in src/session.ts. Importing it here
 // would drag node-pty and the whole session layer into this pure module, so the
 // list is duplicated and test/response-viewer-transcript.test.ts pins the parity.
-const EXTERNAL_CLI_MODES = new Set(['codex', 'gemini', 'opencode', 'antigravity', 'pi']);
+const EXTERNAL_CLI_MODES = new Set(['codex', 'gemini', 'opencode', 'antigravity', 'pi', 'grok', 'deepseek']);
 
 function isPromptLine(line: string): boolean {
   return /^\s*›\s*/.test(line);

src/web/routes/approval-routes.ts

@@ -23,7 +23,7 @@ import { ApiErrorCode, createErrorResponse } from '../../types.js';
 import { ApprovalAnswerSchema } from '../schemas.js';
 import { parseBody, getAuthUser, canAccessOwned, findSessionOrFail } from '../route-helpers.js';
 import { approvalInbox, type ApprovalItem } from '../approval-inbox.js';
-import { hooksAvailableForMode } from '../session-wait-registry.js';
+import { hooksAvailableForMode, sessionHookOptions } from '../session-wait-registry.js';
 import type { SessionPort } from '../ports/index.js';
 
 /**
@@ -99,9 +99,22 @@ export function registerApprovalRoutes(app: FastifyInstance, ctx: SessionPort):
     // Throws 404 (not 403) for sessions the caller does not own, same
     // no-existence-leak rule as every other session route.
     const session = findSessionOrFail(ctx, item.sessionId, req);
-    if (!hooksAvailableForMode(session.mode)) {
+    if (!hooksAvailableForMode(session.mode, sessionHookOptions(session))) {
       return createErrorResponse(ApiErrorCode.CONFLICT, 'Session mode cannot have pending approvals');
     }
+    // A dsh approval is an ALERT, not an answerable card: the dialog belongs to
+    // a third-party TUI whose keystroke contract Codeman has not measured, the
+    // Claude-shaped option parser never reads options off its frames, and
+    // verifyStillAnswerable() can therefore never be conclusive for it — so the
+    // '1'/Esc below would be a blind keystroke into a foreign composer. The item
+    // still raises the red alert and clears on the harness's own working/stop
+    // reports; answering happens in the terminal.
+    if (session.mode === 'deepseek') {
+      return createErrorResponse(
+        ApiErrorCode.INVALID_INPUT,
+        'DeepSeek Harness approvals must be answered in the terminal: the dialog belongs to a third-party TUI whose keystrokes Codeman cannot verify.'
+      );
+    }
 
     // Re-capture the pane before aiming keystrokes at it: if the dialog was
     // answered in the terminal moments ago, the digit would land in whatever

src/web/routes/hook-event-routes.ts

@@ -13,7 +13,7 @@ import { HookEventSchema, isValidWorkingDir } from '../schemas.js';
 import { sanitizeHookData, parseBody } from '../route-helpers.js';
 import { persistDockerCaseClaudeSessionId } from '../../docker-hosts.js';
 import { getDataDir } from '../../config/instance.js';
-import { sessionWaits, hooksAvailableForMode } from '../session-wait-registry.js';
+import { sessionWaits, hooksAvailableForMode, sessionHookOptions } from '../session-wait-registry.js';
 import { approvalInbox, type ApprovalKind } from '../approval-inbox.js';
 import type { SessionPort, EventPort, RespawnPort, ConfigPort, InfraPort } from '../ports/index.js';
 
@@ -24,8 +24,34 @@ const APPROVAL_KIND_BY_EVENT: Record<string, ApprovalKind> = {
   idle_prompt: 'idle',
 };
 
-/** Hook events that close a session's pending item without an inbox answer. */
-const APPROVAL_RESOLVING_EVENTS = new Set(['stop', 'elicitation_complete', 'elicitation_response']);
+/**
+ * Hook events that close a session's pending item without an inbox answer.
+ *
+ * `agent_working` is here because it is the DeepSeek status bridge's report that
+ * a turn STARTED, and a harness turn cannot be running while one of its own
+ * modal approvals is on screen — so the agent moving means the dialog was
+ * answered, in the terminal, by the user. That is the same conclusion the claude
+ * path reaches through pane capture, which cannot help here because its frame
+ * parser is Claude-dialog-shaped.
+ */
+const APPROVAL_RESOLVING_EVENTS = new Set(['stop', 'elicitation_complete', 'elicitation_response', 'agent_working']);
+
+/**
+ * Last DeepSeek status-bridge sequence number seen per session.
+ *
+ * The Herdr contract the dsh TUI speaks stamps every report with `--seq <n>`
+ * and RETRIES failed deliveries with backoff — so a stale report can land
+ * AFTER a newer one, and applying it in arrival order resolves an approval
+ * with a retried `working` while the harness sits blocked, or releases a wait
+ * with a retried `idle` mid-turn. A report whose seq is not newer than the
+ * last accepted one is dropped, but only inside a short window: the TUI's
+ * retry backoff is seconds, so a LOWER seq arriving after the window is a
+ * restarted TUI's fresh numbering (same pane, new generation), not a stale
+ * retry, and must be accepted. Insertion-order eviction bounds the map.
+ */
+const dshSeqBySession = new Map<string, { seq: number; at: number }>();
+const DSH_SEQ_STALE_WINDOW_MS = 60_000;
+const DSH_SEQ_MAX_SESSIONS = 500;
 
 export function registerHookEventRoutes(
   app: FastifyInstance,
@@ -37,6 +63,22 @@ export function registerHookEventRoutes(
       return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
     }
 
+    // DeepSeek status-bridge ordering: drop a stale retried report (see
+    // dshSeqBySession above). Success rather than an error, so the shim exits 0
+    // and the TUI does not keep retrying a report that will stay stale.
+    if (data && data.source === 'dsh-status-shim' && typeof data.seq === 'number') {
+      const last = dshSeqBySession.get(sessionId);
+      const now = Date.now();
+      if (last && data.seq <= last.seq && now - last.at < DSH_SEQ_STALE_WINDOW_MS) {
+        return {};
+      }
+      if (!dshSeqBySession.has(sessionId) && dshSeqBySession.size >= DSH_SEQ_MAX_SESSIONS) {
+        const oldest = dshSeqBySession.keys().next().value;
+        if (oldest !== undefined) dshSeqBySession.delete(oldest);
+      }
+      dshSeqBySession.set(sessionId, { seq: data.seq, at: now });
+    }
+
     // Wake anything blocked on `GET /api/sessions/:id/wait`. Hooks are the only
     // DEFINITIVE signals Codeman gets (`idle` is inferred from output stabilization
     // and can flap mid-turn), so these two are what an orchestrating agent should
@@ -50,7 +92,7 @@ export function registerHookEventRoutes(
     // could never legitimately emit one is now dropped instead of steering another
     // agent's control flow.
     const waitSession = ctx.sessions.get(sessionId);
-    if (waitSession && hooksAvailableForMode(waitSession.mode)) {
+    if (waitSession && hooksAvailableForMode(waitSession.mode, sessionHookOptions(waitSession))) {
       if (event === 'stop') {
         sessionWaits.notifySignal(sessionId, 'stop');
       } else if (event === 'permission_prompt' || event === 'elicitation_dialog') {
@@ -111,7 +153,7 @@ export function registerHookEventRoutes(
     // session that can never show one must not create an answerable item).
     let approvalId: string | undefined;
     const approvalKind = APPROVAL_KIND_BY_EVENT[event];
-    if (session && hooksAvailableForMode(session.mode)) {
+    if (session && hooksAvailableForMode(session.mode, sessionHookOptions(session))) {
       if (approvalKind) {
         const toolInput =
           safeData.tool_input && typeof safeData.tool_input === 'object'
@@ -154,12 +196,15 @@ export function registerHookEventRoutes(
     // the browser loaded with. Debounced, so a hook burst costs one broadcast.
     ctx.broadcastSessionStateDebounced(sessionId);
 
-    // Send push notifications for hook events
+    // Send push notifications for hook events. Push Approve/Deny actions ride
+    // on approvalId, and the answer route refuses keystrokes for dsh dialogs
+    // (third-party TUI, unmeasured contract) — so a dsh push stays a plain
+    // notification instead of offering buttons whose answer would be refused.
     ctx.sendPushNotifications(`hook:${event}`, {
       sessionId,
       sessionName,
       ...safeData,
-      ...(approvalId && { approvalId }),
+      ...(approvalId && session?.mode !== 'deepseek' && { approvalId }),
     });
 
     // Track in run summary

src/web/routes/index.ts

@@ -26,3 +26,4 @@ export { registerAdminRoutes } from './admin-routes.js';
 export { registerWsRoutes } from './ws-routes.js';
 export { registerVoiceRoutes } from './voice-routes.js';
 export { registerWebviewRoutes, tryWebviewRefererFallback } from './webview-routes.js';
+export { registerTabLayoutRoutes } from './tab-layout-routes.js';

src/web/routes/ralph-routes.ts

@@ -411,7 +411,7 @@ export function registerRalphRoutes(
     writeFileSync(promptPath, fullPrompt, 'utf-8');
 
     // Register session
-    ctx.addSession(session);
+    await ctx.addSession(session);
     ctx.store.incrementSessionsCreated();
     ctx.persistSessionState(session);
     await ctx.setupSessionListeners(session);

src/web/routes/readmymind-routes.ts

@@ -38,7 +38,6 @@ import { IntentGoalsSchema, ReadMyMindPredictSchema } from '../schemas.js';
 import { parseBody, findSessionOrFail } from '../route-helpers.js';
 import { intentStore } from '../../intent-store.js';
 import { approvalInbox } from '../approval-inbox.js';
-import { hooksAvailableForMode } from '../session-wait-registry.js';
 import { buildPredictionContext, type PredictionContextInputs } from '../../readmymind-context.js';
 import { collectWorkspaceSignals, readTranscriptSignals } from '../../readmymind-collectors.js';
 import { readMyMindPredictor } from '../../readmymind-predictor.js';
@@ -72,7 +71,11 @@ export function registerReadMyMindRoutes(app: FastifyInstance, ctx: SessionPort
     const body = parseBody(ReadMyMindPredictSchema, req.body ?? {});
     const session = findSessionOrFail(ctx, id, req);
 
-    if (!hooksAvailableForMode(session.mode)) {
+    // `mode === 'claude'` directly, NOT hooksAvailableForMode(): that predicate
+    // answers "can this session deliver stop/blocked", and once `deepseek` earned
+    // a yes it silently widened this gate to a mode whose sessions have no Claude
+    // transcript for readTranscriptSignals() to read.
+    if (session.mode !== 'claude') {
       reply.code(400);
       return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Read My Mind predicts claude-mode sessions only');
     }

src/web/routes/session-routes.ts

@@ -24,6 +24,8 @@ import {
   type GeminiConfig,
   type AntigravityConfig,
   type PiConfig,
+  type GrokConfig,
+  type DeepSeekConfig,
 } from '../../types.js';
 import { Session, isAltScreenStripMode, isMuxAltScreenOnlyStripMode } from '../../session.js';
 import { SseEvent } from '../sse-events.js';
@@ -47,10 +49,12 @@ import {
   SessionWaitQuerySchema,
   SessionWaitOutputQuerySchema,
 } from '../schemas.js';
-import { mergeSessionOrder } from '../../session-order.js';
+import { ownerLayoutKey } from '../../tab-layout-persistence.js';
+import { TabLayoutValidationError } from '../../tab-layout.js';
 import {
   sessionWaits,
   resolveWaitSignals,
+  sessionHookOptions,
   signalForStatus,
   WaitCapacityError,
   type WaitSignal,
@@ -107,7 +111,7 @@ import {
   setHistoryIndexRefresher,
   setHistorySessionIndex,
 } from '../session-history-index.js';
-import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
+import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort, TabLayoutPort } from '../ports/index.js';
 import { RunSummaryTracker } from '../../run-summary.js';
 
 import { MAX_INPUT_LENGTH, MAX_SESSION_NAME_LENGTH } from '../../config/terminal-limits.js';
@@ -137,6 +141,7 @@ import {
   isExternalCliTranscriptMode,
   parseExternalCliTranscript,
 } from '../response-viewer-transcript.js';
+import { readDeepSeekLastResponse } from '../../deepseek-transcript.js';
 
 // Path to linked-cases registry (same file used by case-routes resolveCasePath)
 const LINKED_CASES_FILE = dataPath('linked-cases.json');
@@ -331,21 +336,37 @@ export function _resetPasteRateBuckets(): void {
  * session user could simply answer "yes" to in the terminal, so merely omitting
  * `--approve` is not a clamp. Forcing `approveProjectTrust: false` makes
  * buildPiCommand emit `--no-approve`, and the prompt never appears.
+ *
+ * Grok is like Codex/Antigravity: the bypass switch is `alwaysApprove`
+ * (`--always-approve`), and an ABSENT config already spawns in grok's own
+ * ask-mode default, so only a sent config needs the flag forced off.
+ *
+ * DeepSeek joins the same only-if-sent branch, but its switch is not a flag: the
+ * harness has no command-line permission option, and its sandbox/approval rows
+ * read `DSH_PERMISSION_MODE`. Omitting that export leaves the harness on its own
+ * `workspace-write` preset, which still asks, so an absent config is already
+ * safe; a sent one is forced down to `workspace-write` rather than to
+ * `read-only`, because the clamp exists to remove PRIVILEGE, not to break a
+ * session's ability to edit its own workspace.
  */
 async function clampExternalCliBypassForOwner(
   owner: string | undefined,
   codexConfig: CodexConfig | undefined,
   geminiConfig: GeminiConfig | undefined,
   antigravityConfig: AntigravityConfig | undefined,
-  piConfig: PiConfig | undefined
+  piConfig: PiConfig | undefined,
+  grokConfig: GrokConfig | undefined,
+  deepSeekConfig: DeepSeekConfig | undefined
 ): Promise<{
   codexConfig: CodexConfig | undefined;
   geminiConfig: GeminiConfig | undefined;
   antigravityConfig: AntigravityConfig | undefined;
   piConfig: PiConfig | undefined;
+  grokConfig: GrokConfig | undefined;
+  deepSeekConfig: DeepSeekConfig | undefined;
 }> {
   const granted = await canUsernameRunPrivilegedCommands(owner);
-  if (granted) return { codexConfig, geminiConfig, antigravityConfig, piConfig };
+  if (granted) return { codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, deepSeekConfig };
   // Non-granted: force codex/antigravity bypass off (only meaningful when a config was
   // sent) and materialize gemini to auto_edit (clamps an explicit 'yolo' and the yolo default)
   // and pi to --no-approve (clamps an explicit true AND pi's own "ask" default).
@@ -355,17 +376,101 @@ async function clampExternalCliBypassForOwner(
     ? { ...antigravityConfig, dangerouslySkipPermissions: false }
     : antigravityConfig;
   const clampedPi: PiConfig = { ...(piConfig ?? {}), approveProjectTrust: false };
+  const clampedGrok = grokConfig ? { ...grokConfig, alwaysApprove: false } : grokConfig;
+  const clampedDeepSeek = deepSeekConfig
+    ? { ...deepSeekConfig, permissionMode: 'workspace-write' as const }
+    : deepSeekConfig;
   return {
     codexConfig: clampedCodex,
     geminiConfig: clampedGemini,
     antigravityConfig: clampedAntigravity,
     piConfig: clampedPi,
+    grokConfig: clampedGrok,
+    deepSeekConfig: clampedDeepSeek,
   };
 }
 
 /** Test hook: the clamp is the multi-user safety gate for the external CLIs' privileged flags. */
 export const _clampExternalCliBypassForOwner = clampExternalCliBypassForOwner;
 
+/**
+ * Env-var keys a non-granted owner must not be able to set, because each one
+ * hands back privilege the config clamp above just removed — or, for the last,
+ * redirects a credential the server injects.
+ *
+ * All are DeepSeek's, and all are reachable because `DSH_*` and `DEEPSEEK_*` are
+ * allowlisted `envOverrides` prefixes (schemas.ts) — which they have to be, since
+ * that is also how a user configures the harness's non-privileged knobs.
+ *
+ * - `DSH_PERMISSION_MODE` IS the harness's permission switch. Every other CLI's
+ *   bypass is a command-line FLAG, reachable only through the per-CLI config the
+ *   clamp already owns; this one is an env var, so the config clamp alone is
+ *   half a gate.
+ * - `DSH_HOME` points the launcher at a profile tree, and a profile's plugin code
+ *   executes at BOOT, before any approval row can apply. A user who can write a
+ *   workspace can put a profile in it, so this is the wider of the two.
+ * - `DEEPSEEK_BASE_URL` aims the provider endpoint, and `_configureDeepSeek()`
+ *   forwards the SERVER's own `DEEPSEEK_API_KEY` into every dsh pane before
+ *   `applyEnvOverrides()` runs — so a non-granted owner who could set the base
+ *   URL would have the operator's API key sent as a bearer credential to a host
+ *   of their choosing. (`DEEPSEEK_API_KEY` itself stays overridable: supplying
+ *   your OWN key removes privilege rather than granting it.)
+ */
+const OWNER_CLAMPED_ENV_KEYS = ['DSH_PERMISSION_MODE', 'DSH_HOME', 'DEEPSEEK_BASE_URL'] as const;
+
+/**
+ * Env-var half of the multi-user bypass clamp.
+ *
+ * `clampExternalCliBypassForOwner()` clamps the per-CLI CONFIG, and for every CLI
+ * but DeepSeek that is the whole story. Here it is not: `applyEnvOverrides()` runs
+ * AFTER `_configureDeepSeek()` in tmux-manager, so an override sent on the SAME
+ * request lands last and wins, and a non-granted owner could restore
+ * `danger-full-access` on the very request the config clamp downgraded.
+ *
+ * Keys are DROPPED rather than rewritten: dropping falls through to what
+ * `_configureDeepSeek()` exports, which is the clamped config and the server's own
+ * `DSH_HOME`, i.e. exactly the intended state. No-op in single-user mode and for a
+ * granted owner, like every other clamp here
+ * (`canUsernameRunPrivilegedCommands()` returns true when `!isMultiUserMode()`),
+ * and it returns the caller's own object untouched when there is nothing to strip.
+ */
+async function clampEnvOverridesForOwner(
+  owner: string | undefined,
+  envOverrides: Record<string, string> | undefined
+): Promise<Record<string, string> | undefined> {
+  if (!envOverrides) return envOverrides;
+  if (!OWNER_CLAMPED_ENV_KEYS.some((key) => key in envOverrides)) return envOverrides;
+  if (await canUsernameRunPrivilegedCommands(owner)) return envOverrides;
+  const clamped = { ...envOverrides };
+  for (const key of OWNER_CLAMPED_ENV_KEYS) delete clamped[key];
+  return clamped;
+}
+
+/** Test hook: the env-var half of the same multi-user safety gate. */
+export const _clampEnvOverridesForOwner = clampEnvOverridesForOwner;
+
+/**
+ * Why a DeepSeek session cannot start, or null when it can.
+ *
+ * Availability for this mode is TWO questions, not one, because `dsh` is a
+ * profile launcher rather than an agent: the binary must resolve (and prove it
+ * is the harness and not Debian's dancer's shell), AND a profile that can occupy
+ * a pane must exist. Reporting only the first would let the Run button spawn a
+ * pane that dies instantly, which is the single most confusing failure this mode
+ * can produce, so each half gets its own actionable message.
+ *
+ * A profile named EXPLICITLY is checked on both counts: existence, and whether
+ * it is pane-capable — `web` serves a browser UI and `headless` answers one task
+ * and exits, so both would present as "the tab immediately died".
+ */
+async function resolveDeepSeekLaunchError(requestedProfile?: string): Promise<string | null> {
+  // Thin async wrapper: the implementation moved into the resolver module so
+  // CRON fires can ask the same question before constructing a Session; the
+  // dynamic import keeps this file's startup free of the probe machinery.
+  const { resolveDeepSeekLaunchError: impl } = await import('../../utils/deepseek-cli-resolver.js');
+  return impl(requestedProfile);
+}
+
 // ═══════════════════════════════════════════════════════════════
 // Agent wait helpers (shared by GET /wait, GET /wait-output, POST /input)
 // ═══════════════════════════════════════════════════════════════
@@ -641,7 +746,7 @@ async function injectAgentSkill(casePath: string): Promise<void> {
 
 export function registerSessionRoutes(
   app: FastifyInstance,
-  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
+  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort & TabLayoutPort
 ): void {
   // ═══════════════════════════════════════════════════════════════
   // Auth
@@ -673,16 +778,23 @@ export function registerSessionRoutes(
     return (list as Array<{ owner?: string }>).filter((s) => canAccessOwned(user, s.owner));
   });
 
-  // ========== Session Tab Order (global sync, COD-131) ==========
+  // ========== Legacy Session Tab Order (temporary synchronized compatibility bridge) ==========
 
-  app.put('/api/session-order', async (req): Promise<ApiResponse<{ order: string[] }>> => {
-    const { order } = parseBody(SessionOrderUpdateSchema, req.body, 'Invalid session order');
-    // Server is authoritative but never drops ids it knows about that the
-    // pushing device hadn't loaded yet — those fall to the end (mergeSessionOrder).
-    const merged = mergeSessionOrder(order, ctx.store.getSessionOrder());
-    ctx.store.setSessionOrder(merged);
-    ctx.broadcast(SseEvent.SessionOrderChanged, { order: merged });
-    return { success: true, data: { order: merged } };
+  app.put('/api/session-order', async (req, reply): Promise<ApiResponse<{ order: string[] }>> => {
+    try {
+      const { order } = parseBody(SessionOrderUpdateSchema, req.body, 'Invalid session order');
+      const user = getAuthUser(req);
+      const result = await ctx.tabLayouts.putLegacyOrder(
+        { owner: ownerLayoutKey(ownerFor(req)), isAdmin: user.role === 'admin' },
+        order
+      );
+      return { success: true, data: { order: result.order } };
+    } catch (error) {
+      if (error instanceof TabLayoutValidationError) {
+        return reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, error.message));
+      }
+      throw error;
+    }
   });
 
   // ========== Session Creation ==========
@@ -752,6 +864,8 @@ export function registerSessionRoutes(
       body.mode !== 'gemini' &&
       body.mode !== 'antigravity' &&
       body.mode !== 'pi' &&
+      body.mode !== 'grok' &&
+      body.mode !== 'deepseek' &&
       body.envOverrides &&
       Object.keys(body.envOverrides).length > 0 &&
       (workingDir.startsWith(CASES_DIR + '/') || workingDir.startsWith(managedCasesBase + '/'));
@@ -841,6 +955,16 @@ export function registerSessionRoutes(
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getPiNotFoundMessage());
       }
     }
+    if (body.mode === 'deepseek') {
+      const err = await resolveDeepSeekLaunchError(body.deepSeekConfig?.profile);
+      if (err) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, err);
+    }
+    if (body.mode === 'grok') {
+      const { isGrokAvailable, getGrokNotFoundMessage } = await import('../../utils/grok-cli-resolver.js');
+      if (!isGrokAvailable()) {
+        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getGrokNotFoundMessage());
+      }
+    }
 
     // Pre-validate resumeSessionId: check that the conversation file actually exists
     // in Claude's projects directory. If not, skip resume to avoid confusing
@@ -886,9 +1010,14 @@ export function registerSessionRoutes(
               ? body.antigravityConfig?.model
               : mode === 'pi'
                 ? body.piConfig?.model
-                : mode !== 'shell'
-                  ? modelConfig?.defaultModel || undefined
-                  : undefined;
+                : mode === 'grok'
+                  ? body.grokConfig?.model
+                  : // DeepSeek's model is a composition entry in the profile's config
+                    // tree, not a session flag, so there is deliberately nothing to
+                    // read here (see docs/deepseek-integration.md).
+                    mode !== 'shell' && mode !== 'deepseek'
+                    ? modelConfig?.defaultModel || undefined
+                    : undefined;
     const claudeModeConfig = await ctx.getClaudeModeConfig();
     // Section 6.3: force non-granted users to a classifier-guarded mode.
     const effectiveClaudeMode = await resolveClaudeModeForUsername(claudeModeConfig.claudeMode, owner);
@@ -898,12 +1027,16 @@ export function registerSessionRoutes(
       geminiConfig: gatedGeminiConfig,
       antigravityConfig: gatedAntigravityConfig,
       piConfig: gatedPiConfig,
+      grokConfig: gatedGrokConfig,
+      deepSeekConfig: gatedDeepSeekConfig,
     } = await clampExternalCliBypassForOwner(
       owner,
       body.codexConfig,
       body.geminiConfig,
       body.antigravityConfig,
-      body.piConfig
+      body.piConfig,
+      body.grokConfig,
+      body.deepSeekConfig
     );
     const terminalHistoryConfig = await ctx.getTerminalHistoryConfig();
     const session = new Session({
@@ -921,8 +1054,10 @@ export function registerSessionRoutes(
       geminiConfig: mode === 'gemini' ? gatedGeminiConfig : undefined,
       antigravityConfig: mode === 'antigravity' ? gatedAntigravityConfig : undefined,
       piConfig: mode === 'pi' ? gatedPiConfig : undefined,
+      grokConfig: mode === 'grok' ? gatedGrokConfig : undefined,
+      deepSeekConfig: mode === 'deepseek' ? gatedDeepSeekConfig : undefined,
       resumeSessionId: validatedResumeId,
-      envOverrides: body.envOverrides,
+      envOverrides: await clampEnvOverridesForOwner(owner, body.envOverrides),
       effort: body.effort,
       tmuxHistoryLimit: terminalHistoryConfig.tmuxHistoryLimit,
       remote,
@@ -930,7 +1065,7 @@ export function registerSessionRoutes(
       parentSessionId: resolveParentSessionId(ctx, req, body.parentSessionId, owner),
     });
 
-    ctx.addSession(session);
+    await ctx.addSession(session);
     ctx.store.incrementSessionsCreated();
     ctx.persistSessionState(session);
     await ctx.setupSessionListeners(session);
@@ -1152,6 +1287,8 @@ export function registerSessionRoutes(
         session.mode !== 'gemini' &&
         session.mode !== 'antigravity' &&
         session.mode !== 'pi' &&
+        session.mode !== 'grok' &&
+        session.mode !== 'deepseek' &&
         ctx.store.getConfig().ralphEnabled &&
         !session.ralphTracker.autoEnableDisabled
       ) {
@@ -1247,7 +1384,10 @@ export function registerSessionRoutes(
       wait === true || (typeof wait === 'string' && wait.trim().length > 0) || (Array.isArray(wait) && wait.length > 0);
     let until: readonly WaitSignal[] = [];
     if (wantsWait) {
-      const resolved = resolveWaitSignals(wait === true ? undefined : wait, { mode: session.mode });
+      const resolved = resolveWaitSignals(wait === true ? undefined : wait, {
+        mode: session.mode,
+        ...sessionHookOptions(session),
+      });
       if (resolved.error) return createErrorResponse(ApiErrorCode.INVALID_INPUT, resolved.error);
       until = resolved.until;
     }
@@ -1424,7 +1564,7 @@ export function registerSessionRoutes(
 
     // Shared with the `wait` field on POST .../input: unknown token is a 400,
     // hook-only signals are rejected explicitly but dropped from the default.
-    const { until, error } = resolveWaitSignals(query.until, { mode: session.mode });
+    const { until, error } = resolveWaitSignals(query.until, { mode: session.mode, ...sessionHookOptions(session) });
     if (error) return createErrorResponse(ApiErrorCode.INVALID_INPUT, error);
 
     // The value actually applied after clamping, echoed below: a caller that asked
@@ -1892,6 +2032,35 @@ export function registerSessionRoutes(
       return await readCodexLastResponse(session, codexQuery.context === 'full');
     }
 
+    // DeepSeek Harness writes a real structured transcript under
+    // `$DSH_HOME/sessions/**`, so read that rather than segmenting the pane.
+    // ⚠️ For dsh the pane fallback is not merely coarse, it is WRONG: dsh-TUI
+    // paints a full-screen splash, and the segmenter served its ASCII-art logo
+    // back as the worker's answer (measured), which an agent polling for a
+    // reply reads as a reply. So an EMPTY transcript result still wins over the
+    // pane — "nothing said yet" is the honest answer. Only `null`, meaning a
+    // Node too old to decode zstd, falls through to the segmenter below.
+    // ⚠️ Local sessions only: a docker case's harness writes its transcript
+    // inside the CONTAINER's ~/.dsh (the workspace bind-mount does not cover
+    // it) and a remote-SSH case's lives on the remote host, so the local
+    // reader would scan a $DSH_HOME that can never hold this session's file
+    // and return "nothing said yet" forever — an agent polling that worker
+    // would starve on an answer that exists. Those configurations keep the
+    // pane segmenter below: coarse, but the real conversation.
+    if (session.mode === 'deepseek' && !session.docker && !session.remote) {
+      const deepSeekQuery = req.query as { context?: string };
+      const full = deepSeekQuery.context === 'full';
+      const transcript = await readDeepSeekLastResponse(session, { blocks: full });
+      if (transcript) {
+        return {
+          text: transcript.text,
+          timestamp: transcript.timestamp,
+          hasContext: transcript.text.length > 0 || transcript.blocks.length > 0,
+          messages: full ? transcript.blocks : undefined,
+        };
+      }
+    }
+
     // OpenCode / Gemini / Antigravity / Pi render their own TUIs and write no
     // Claude transcript, so the scan below finds nothing and the response viewer
     // renders permanently empty for them. Segment the terminal buffer instead —
@@ -2643,7 +2812,7 @@ export function registerSessionRoutes(
       allowedTools: runClaudeModeConfig.allowedTools,
       owner: runOwner,
     });
-    ctx.addSession(session);
+    await ctx.addSession(session);
     ctx.store.incrementSessionsCreated();
     ctx.persistSessionState(session);
     await ctx.setupSessionListeners(session);
@@ -2686,6 +2855,8 @@ export function registerSessionRoutes(
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
       envOverrides,
       effort,
       parentSessionId,
@@ -2734,6 +2905,8 @@ export function registerSessionRoutes(
         geminiConfig ||
         antigravityConfig ||
         piConfig ||
+        grokConfig ||
+        deepSeekConfig ||
         openCodeConfig
       ) {
         return createErrorResponse(
@@ -2766,6 +2939,8 @@ export function registerSessionRoutes(
         geminiConfig ||
         antigravityConfig ||
         piConfig ||
+        grokConfig ||
+        deepSeekConfig ||
         openCodeConfig
       ) {
         return createErrorResponse(
@@ -2868,6 +3043,20 @@ export function registerSessionRoutes(
         }
       }
 
+      // Check Grok availability if requested
+      if (mode === 'grok') {
+        const { isGrokAvailable, getGrokNotFoundMessage } = await import('../../utils/grok-cli-resolver.js');
+        if (!isGrokAvailable()) {
+          return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getGrokNotFoundMessage());
+        }
+      }
+
+      // Check DeepSeek Harness availability if requested (binary AND a pane-capable profile).
+      if (mode === 'deepseek') {
+        const err = await resolveDeepSeekLaunchError(deepSeekConfig?.profile);
+        if (err) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, err);
+      }
+
       // Resolve case path: check linked-cases registry first, then fall back to CASES_DIR.
       // This mirrors the behaviour of resolveCasePath() in case-routes so that linked
       // external project directories are honoured by quick-start just like regular case routes.
@@ -2914,8 +3103,15 @@ export function registerSessionRoutes(
         writeFileSync(join(resolvedCasePath, 'CLAUDE.md'), claudeMd);
 
         // Write .claude/settings.local.json with hooks for desktop notifications
-        // (Claude-specific — OpenCode, Codex, Gemini, and Antigravity use their own systems)
-        if (mode !== 'opencode' && mode !== 'codex' && mode !== 'gemini' && mode !== 'antigravity' && mode !== 'pi') {
+        // (Claude-specific — OpenCode, Codex, Gemini, Antigravity, Pi and Grok use their own systems)
+        if (
+          mode !== 'opencode' &&
+          mode !== 'codex' &&
+          mode !== 'gemini' &&
+          mode !== 'antigravity' &&
+          mode !== 'pi' &&
+          mode !== 'grok'
+        ) {
           await writeHooksConfig(resolvedCasePath);
         }
 
@@ -2987,6 +3183,8 @@ export function registerSessionRoutes(
       mode !== 'gemini' &&
       mode !== 'antigravity' &&
       mode !== 'pi' &&
+      mode !== 'grok' &&
+      mode !== 'deepseek' &&
       !remote &&
       envOverrides &&
       Object.keys(envOverrides).length > 0
@@ -3009,9 +3207,12 @@ export function registerSessionRoutes(
               ? antigravityConfig?.model
               : mode === 'pi'
                 ? piConfig?.model
-                : mode !== 'shell'
-                  ? qsModelConfig?.defaultModel || undefined
-                  : undefined;
+                : mode === 'grok'
+                  ? grokConfig?.model
+                  : // DeepSeek's model lives in the profile's config tree, not here.
+                    mode !== 'shell' && mode !== 'deepseek'
+                    ? qsModelConfig?.defaultModel || undefined
+                    : undefined;
     const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
     const qsEffectiveClaudeMode = await resolveClaudeModeForUsername(qsClaudeModeConfig.claudeMode, owner);
     // Section 6.3: clamp Codex/Gemini/Antigravity bypass switches for a non-granted owner (no-op single-user/granted).
@@ -3020,8 +3221,19 @@ export function registerSessionRoutes(
       geminiConfig: qsGatedGeminiConfig,
       antigravityConfig: qsGatedAntigravityConfig,
       piConfig: qsGatedPiConfig,
-    } = await clampExternalCliBypassForOwner(owner, codexConfig, geminiConfig, antigravityConfig, piConfig);
+      grokConfig: qsGatedGrokConfig,
+      deepSeekConfig: qsGatedDeepSeekConfig,
+    } = await clampExternalCliBypassForOwner(
+      owner,
+      codexConfig,
+      geminiConfig,
+      antigravityConfig,
+      piConfig,
+      grokConfig,
+      deepSeekConfig
+    );
     const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
+    const qsGatedEnvOverrides = await clampEnvOverridesForOwner(owner, envOverrides);
     const session = new Session({
       workingDir: resolvedCasePath,
       name: sessionName ? sessionName.slice(0, MAX_SESSION_NAME_LENGTH) : '',
@@ -3038,7 +3250,9 @@ export function registerSessionRoutes(
       geminiConfig: mode === 'gemini' ? qsGatedGeminiConfig : undefined,
       antigravityConfig: mode === 'antigravity' ? qsGatedAntigravityConfig : undefined,
       piConfig: mode === 'pi' ? qsGatedPiConfig : undefined,
-      envOverrides,
+      grokConfig: mode === 'grok' ? qsGatedGrokConfig : undefined,
+      deepSeekConfig: mode === 'deepseek' ? qsGatedDeepSeekConfig : undefined,
+      envOverrides: qsGatedEnvOverrides,
       effort,
       remote,
       docker,
@@ -3057,7 +3271,7 @@ export function registerSessionRoutes(
       }
     }
 
-    ctx.addSession(session);
+    await ctx.addSession(session);
     ctx.store.incrementSessionsCreated();
     ctx.persistSessionState(session);
     await ctx.setupSessionListeners(session);
@@ -3088,7 +3302,7 @@ export function registerSessionRoutes(
         });
         ctx.broadcast(SseEvent.SessionInteractive, { id: session.id, mode: 'shell' });
       } else {
-        // 'claude', 'opencode', 'codex', 'gemini', and 'antigravity' modes use startInteractive()
+        // every non-shell mode ('claude', the external CLIs) uses startInteractive()
         await session.startInteractive();
         getLifecycleLog().log({
           event: 'started',

src/web/routes/status-telemetry-routes.ts

@@ -57,9 +57,9 @@ export function registerStatusTelemetryRoutes(app: FastifyInstance, ctx: Session
             if (!ctx.sessions.has(id)) lastSig.delete(id);
           }
         }
-        const payload = { sessionId, ...telemetry };
-        setLatestPlanUsage(payload); // replayed in the SSE init snapshot for fresh loads
-        ctx.broadcast(SessionStatusTelemetry, payload);
+        const update = { sessionId, ...telemetry };
+        const snapshot = setLatestPlanUsage(update); // replayed in the SSE init snapshot for fresh loads
+        ctx.broadcast(SessionStatusTelemetry, snapshot);
       }
     }
 

src/web/routes/system-routes.ts

@@ -16,7 +16,7 @@ import { dataPath } from '../../config/instance.js';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, type NiceConfig } from '../../types.js';
 import { isUnauthenticatedNetworkAcknowledged } from '../network-auth-policy.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
-import { findUser } from '../../user-store.js';
+import { findUser, canUsernameRunPrivilegedCommands } from '../../user-store.js';
 import { getAuthUser, requireAdmin, canAccessOwned } from '../route-helpers.js';
 import {
   ConfigUpdateSchema,
@@ -26,6 +26,8 @@ import {
   SubagentWindowStatesSchema,
   SubagentParentMapSchema,
   RevokeSessionSchema,
+  DeepSeekInstallProfileSchema,
+  DeepSeekWebStartSchema,
 } from '../schemas.js';
 import { subagentWatcher } from '../../subagent-watcher.js';
 import { imageWatcher } from '../../image-watcher.js';
@@ -48,13 +50,29 @@ import {
 } from '../route-helpers.js';
 import { SseEvent } from '../sse-events.js';
 import { getInstallInfo, checkForUpdate, startUpdate, getUpdateStatusForApi } from '../self-update.js';
+
 import { getRepositoryStatus } from '../repo-status.js';
-import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
+import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort, TabLayoutPort } from '../ports/index.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { QR_AUTH_FAILURE_MAX } from '../../config/tunnel-config.js';
 import { AUTH_SESSION_TTL_MS } from '../../config/auth-config.js';
 import { resolveTerminalHistoryConfig } from '../../config/terminal-history.js';
 
+/**
+ * Defaults for `POST /api/deepseek/install-profile`.
+ *
+ * The package is the community terminal front door with by far the widest use
+ * (~27.5k weekly downloads at time of writing, roughly 4x the next), MIT, and
+ * the one whose supervisor-reporting contract Codeman's status bridge speaks.
+ * It is a DEFAULT, not a hardcoding: the endpoint accepts any npm name, and the
+ * resolver never assumes this profile exists.
+ */
+const DEEPSEEK_DEFAULT_TUI_PACKAGE = '@deepseek-harness-tui/dsh-tui';
+const DEEPSEEK_DEFAULT_PROFILE = 'dsh-tui';
+
+/** A plugin install compiles and links a dependency tree; npm-scale, not curl-scale. */
+const DEEPSEEK_INSTALL_TIMEOUT_MS = 300_000;
+
 // Maximum screenshot upload size (10MB)
 const MAX_SCREENSHOT_SIZE = 10 * 1024 * 1024;
 // Screenshots directory
@@ -129,7 +147,7 @@ export function resolveSpanUrl(hostHeader: string | undefined, fallbackPort = '3
 
 export function registerSystemRoutes(
   app: FastifyInstance,
-  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
+  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort & TabLayoutPort
 ): void {
   const windowStatesPath = dataPath('subagent-window-states.json');
   const parentMapPath = dataPath('subagent-parents.json');
@@ -380,7 +398,7 @@ export function registerSystemRoutes(
   });
 
   // ═══════════════════════════════════════════════════════════════
-  // CLI Integrations (Claude, OpenCode, Codex, Gemini, Antigravity, Pi)
+  // CLI Integrations (Claude, OpenCode, Codex, Gemini, Antigravity, Pi, Grok)
   // ═══════════════════════════════════════════════════════════════
 
   // ========== Claude ==========
@@ -446,6 +464,236 @@ export function registerSystemRoutes(
     };
   });
 
+  // ========== Grok ==========
+
+  // Carries `version` on top of the sibling shape, same reason as pi: `grok` is a
+  // binary name with known squatters, so the resolver version-probes candidates and
+  // this endpoint is where a misresolution shows up (path + version) instead of
+  // presenting as "the mode just doesn't work".
+  app.get('/api/grok/status', async () => {
+    const { isGrokAvailable, resolveGrokDir, getGrokCliVersion } = await import('../../utils/grok-cli-resolver.js');
+    return {
+      available: isGrokAvailable(),
+      path: resolveGrokDir(),
+      version: getGrokCliVersion(),
+    };
+  });
+
+  // ========== DeepSeek Harness ==========
+
+  // The widest of the per-CLI status shapes, because this mode has the widest
+  // failure surface. Three fields beyond the sibling `available`/`path`:
+  //
+  // - `version`, like pi/grok, so a misresolution is diagnosable — and here the
+  //   stakes are higher, since `dsh` is also an existing Debian program
+  //   (dancer's shell) rather than merely a squattable npm name.
+  // - `profiles`, because `dsh` is a LAUNCHER: a perfectly installed binary with
+  //   no pane-capable profile cannot start a session, and the UI has to be able
+  //   to say which of the two halves is missing.
+  // - `runnable` + `defaultProfile`, the answer the Run button actually needs,
+  //   so no caller has to re-derive it from the parts and get it subtly wrong.
+  app.get('/api/deepseek/status', async () => {
+    const {
+      isDeepSeekAvailable,
+      isDeepSeekRunnable,
+      resolveDeepSeekDir,
+      getDeepSeekCliVersion,
+      listDeepSeekProfiles,
+      resolveDefaultDeepSeekProfile,
+      resolveDshHome,
+    } = await import('../../utils/deepseek-cli-resolver.js');
+    return {
+      available: isDeepSeekAvailable(),
+      runnable: isDeepSeekRunnable(),
+      path: resolveDeepSeekDir(),
+      version: getDeepSeekCliVersion(),
+      dshHome: resolveDshHome(),
+      defaultProfile: resolveDefaultDeepSeekProfile(),
+      profiles: listDeepSeekProfiles(),
+    };
+  });
+
+  // Start (or reuse) the background `dsh web` behind the Run menu shortcut.
+  //
+  // This runs as a plain child process rather than a shell SESSION on purpose.
+  // The session version worked, but it put a terminal tab on screen next to the
+  // web tab the user actually asked for, every single time. Nothing about a
+  // long-lived HTTP server needs to be a tab.
+  //
+  // Fenced at the same bar as the profile installer, and for the same reason:
+  // booting a dsh profile executes the plugin code in it, so this is a
+  // privileged action even though it reads as "open a page".
+  app.post('/api/deepseek/web', async (req) => {
+    const { authority } = parseBody(DeepSeekWebStartSchema, req.body);
+    if (isMultiUserMode() && !(await canUsernameRunPrivilegedCommands(getAuthUser(req).username))) {
+      return createErrorResponse(
+        ApiErrorCode.FORBIDDEN,
+        'Starting the DeepSeek web UI requires the can-bypass-permissions grant'
+      );
+    }
+
+    const { resolveDeepSeekDir, getDeepSeekNotFoundMessage } = await import('../../utils/deepseek-cli-resolver.js');
+    const dir = resolveDeepSeekDir();
+    if (!dir) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getDeepSeekNotFoundMessage());
+
+    const { startDeepSeekWeb } = await import('../../deepseek-web-server.js');
+    const result = await startDeepSeekWeb(dir, authority);
+    if (!result.ok) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, result.error);
+    return { success: true, data: { port: result.port, url: result.url, reused: result.reused } };
+  });
+
+  app.get('/api/deepseek/web', async () => {
+    const { getDeepSeekWebStatus } = await import('../../deepseek-web-server.js');
+    return { success: true, data: getDeepSeekWebStatus() };
+  });
+
+  app.delete('/api/deepseek/web', async (req) => {
+    // Same bar as POST: the server is a single shared instance, so in
+    // multi-user mode stopping it out from under other users' tabs is a
+    // privileged act (single-user and granted owners are unaffected).
+    if (isMultiUserMode() && !(await canUsernameRunPrivilegedCommands(getAuthUser(req).username))) {
+      return createErrorResponse(
+        ApiErrorCode.FORBIDDEN,
+        'Stopping the DeepSeek web UI requires the can-bypass-permissions grant'
+      );
+    }
+    const { stopDeepSeekWeb } = await import('../../deepseek-web-server.js');
+    await stopDeepSeekWeb();
+    return { success: true, data: { stopped: true } };
+  });
+
+  // Bootstrap an interactive profile so the mode becomes usable.
+  //
+  // This exists because DeepSeek ships NO terminal front door: `dsh` on its own
+  // can only serve a browser UI or answer one headless task, and the agent a
+  // Codeman pane runs is always a plugin the user installed. Without this the
+  // mode's first-run experience is a dead Run button and a paragraph of shell
+  // instructions.
+  //
+  // It is the only endpoint in Codeman that installs third-party code, so it is
+  // fenced accordingly:
+  //   - the privileged grant is required in multi-user mode (same bar as a
+  //     `shell` session, which can already do strictly more);
+  //   - the specifier is regex-confined to an npm name at the schema boundary —
+  //     no path, URL, git spec, or leading dash;
+  //   - the spawn is an argv ARRAY through the resolved `dsh`, never a shell
+  //     string, so even a specifier that slipped the regex could not become a
+  //     second command;
+  //   - the request is held open with a bounded timeout, mirroring the
+  //     synchronous-clone precedent in `POST /api/cases/clone` rather than
+  //     introducing a job store for a once-per-install action — and the bound is
+  //     real, because the install runs in its own process GROUP and the timeout
+  //     kills the whole tree (see the spawn below for why the built-in one is
+  //     not enough).
+  app.post('/api/deepseek/install-profile', async (req) => {
+    const body = parseBody(DeepSeekInstallProfileSchema, req.body);
+    if (isMultiUserMode() && !(await canUsernameRunPrivilegedCommands(getAuthUser(req).username))) {
+      return createErrorResponse(
+        ApiErrorCode.FORBIDDEN,
+        'Installing a DeepSeek Harness profile requires the can-bypass-permissions grant'
+      );
+    }
+
+    const { resolveDeepSeekDir, getDeepSeekNotFoundMessage } = await import('../../utils/deepseek-cli-resolver.js');
+    const dir = resolveDeepSeekDir();
+    if (!dir) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getDeepSeekNotFoundMessage());
+
+    const profile = body.profile || DEEPSEEK_DEFAULT_PROFILE;
+    const pkg = body.package || DEEPSEEK_DEFAULT_TUI_PACKAGE;
+    const result = await new Promise<{ code: number | null; output: string; timedOut: boolean }>((resolve) => {
+      let child: ReturnType<typeof spawn>;
+      try {
+        child = spawn(join(dir, 'dsh'), ['plugin', '--profile', profile, 'add', pkg], {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          // Own process group, and the timeout enforced by hand rather than by
+          // spawn's `timeout` option. A plugin install fans out into
+          // package-manager resolver/build children, and spawn's own timeout
+          // signals ONLY the direct child: the survivors keep the inherited stdio
+          // pipes open, `close` never fires, and this request hangs forever with
+          // no route-level deadline behind it. Same fan-out, same escalation and
+          // same negative-pid signal as runGit() in git-clone.ts, which is the
+          // synchronous-spawn precedent this endpoint is modelled on.
+          detached: true,
+          // dsh bundles its own package manager, so no system pnpm is required —
+          // but it still needs a HOME to resolve $DSH_HOME against.
+          env: process.env,
+        });
+      } catch (err) {
+        resolve({ code: null, output: `spawn failed: ${getErrorMessage(err)}`, timedOut: false });
+        return;
+      }
+
+      let output = '';
+      let timedOut = false;
+      let settled = false;
+      let killTimer: NodeJS.Timeout | undefined;
+      let reapTimer: NodeJS.Timeout | undefined;
+
+      const capture = (chunk: Buffer) => {
+        // Bounded: a package manager can emit megabytes of progress.
+        if (output.length < 16_384) output += chunk.toString('utf-8');
+      };
+      child.stdout?.on('data', capture);
+      child.stderr?.on('data', capture);
+
+      const killTree = (signal: NodeJS.Signals) => {
+        try {
+          if (child.pid) process.kill(-child.pid, signal);
+        } catch {
+          try {
+            child.kill(signal);
+          } catch {
+            /* already gone */
+          }
+        }
+      };
+
+      const finish = (code: number | null) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (killTimer) clearTimeout(killTimer);
+        if (reapTimer) clearTimeout(reapTimer);
+        resolve({ code, output, timedOut });
+      };
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        killTree('SIGTERM');
+        killTimer = setTimeout(() => killTree('SIGKILL'), 3_000);
+        // Last resort: a grandchild that escaped the group (double-fork/setsid)
+        // can hold the pipes open past SIGKILL, and `close` would still never
+        // arrive. Answer the caller anyway rather than leaking the request.
+        reapTimer = setTimeout(() => finish(null), 8_000);
+      }, DEEPSEEK_INSTALL_TIMEOUT_MS);
+
+      child.on('error', (err) => {
+        output = `${output}\n${err.message}`;
+        finish(null);
+      });
+      child.on('close', (code) => finish(code));
+    });
+
+    if (result.code !== 0) {
+      const detail = result.timedOut
+        ? `timed out after ${Math.round(DEEPSEEK_INSTALL_TIMEOUT_MS / 1000)}s`
+        : result.output.slice(-1000).trim() || 'no output';
+      return createErrorResponse(
+        ApiErrorCode.OPERATION_FAILED,
+        `Installing ${pkg} into profile "${profile}" failed: ${detail}`
+      );
+    }
+    const { listDeepSeekProfiles, resolveDefaultDeepSeekProfile, isDeepSeekRunnable } =
+      await import('../../utils/deepseek-cli-resolver.js');
+    return {
+      profile,
+      package: pkg,
+      runnable: isDeepSeekRunnable(),
+      defaultProfile: resolveDefaultDeepSeekProfile(),
+      profiles: listDeepSeekProfiles(),
+    };
+  });
+
   // ═══════════════════════════════════════════════════════════════
   // State & Lifecycle (cleanup, lifecycle log, stats)
   // ═══════════════════════════════════════════════════════════════
@@ -454,7 +702,9 @@ export function registerSystemRoutes(
 
   app.post('/api/cleanup-state', async () => {
     const activeSessionIds = new Set(ctx.sessions.keys());
-    const result = ctx.store.cleanupStaleSessions(activeSessionIds);
+    const result = await ctx.tabLayouts.runStaleSessionCleanup(activeSessionIds, (ids) =>
+      ctx.store.cleanupSessionsByIds(ids)
+    );
     const lifecycleLog = getLifecycleLog();
     for (const s of result.cleaned) {
       lifecycleLog.log({ event: 'stale_cleaned', sessionId: s.id, name: s.name });

src/web/routes/tab-layout-routes.ts

@@ -0,0 +1,50 @@
+/** @fileoverview Authenticated owner-scoped tab-layout read/write API. */
+import type { FastifyInstance } from 'fastify';
+import { ownerLayoutKey } from '../../tab-layout-persistence.js';
+import { TabLayoutValidationError } from '../../tab-layout.js';
+import { ApiErrorCode, createErrorResponse } from '../../types.js';
+import { ownerFor } from '../route-helpers.js';
+import type { TabLayoutPort } from '../ports/index.js';
+
+export const TAB_LAYOUT_BODY_LIMIT = 128 * 1024;
+
+function parseWriteBody(body: unknown): { baseVersion: number; layout: unknown } {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    throw new TabLayoutValidationError('body must be an object');
+  }
+  const keys = Object.keys(body);
+  if (keys.length !== 2 || !Object.hasOwn(body, 'baseVersion') || !Object.hasOwn(body, 'layout')) {
+    throw new TabLayoutValidationError('body must contain exactly baseVersion and layout');
+  }
+  const input = body as { baseVersion?: unknown; layout?: unknown };
+  if (!Number.isSafeInteger(input.baseVersion) || (input.baseVersion as number) < 0 || input.layout === undefined) {
+    throw new TabLayoutValidationError('baseVersion must be a non-negative safe integer and layout is required');
+  }
+  return { baseVersion: input.baseVersion as number, layout: input.layout };
+}
+
+export function registerTabLayoutRoutes(app: FastifyInstance, ctx: TabLayoutPort): void {
+  app.get('/api/tab-layout', async (req) => ({
+    success: true,
+    data: { layout: await ctx.tabLayouts.get(ownerLayoutKey(ownerFor(req))) },
+  }));
+
+  app.put('/api/tab-layout', { bodyLimit: TAB_LAYOUT_BODY_LIMIT }, async (req, reply) => {
+    try {
+      const { baseVersion, layout } = parseWriteBody(req.body);
+      const result = await ctx.tabLayouts.put(ownerLayoutKey(ownerFor(req)), layout, baseVersion);
+      if (result.status === 'conflict') {
+        return reply.code(409).send({
+          ...createErrorResponse(ApiErrorCode.CONFLICT, 'Tab layout version conflict'),
+          data: { layout: result.layout },
+        });
+      }
+      return { success: true, data: { layout: result.layout } };
+    } catch (error) {
+      if (error instanceof TabLayoutValidationError) {
+        return reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, error.message));
+      }
+      throw error;
+    }
+  });
+}

src/web/routes/webview-routes.ts

@@ -53,7 +53,8 @@ import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
 import { canAccessOwned, getAuthUser, ownerFor, parseBody } from '../route-helpers.js';
 import { WebviewCreateSchema, WebviewProbeSchema, WebviewUpdateSchema } from '../schemas.js';
 import { SseEvent } from '../sse-events.js';
-import type { EventPort } from '../ports/index.js';
+import type { EventPort, TabLayoutPort } from '../ports/index.js';
+import { ownerLayoutKey } from '../../tab-layout-persistence.js';
 import {
   buildDownstreamResponseHeaders,
   buildProxyCorsHeaders,
@@ -98,14 +99,14 @@ function withWebviews<T>(fn: (list: Webview[]) => Promise<T> | T): Promise<T> {
   return next;
 }
 
-export function registerWebviewRoutes(app: FastifyInstance, ctx: EventPort): void {
+export function registerWebviewRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort): void {
   registerCrudRoutes(app, ctx);
   registerProxyRoutes(app);
 }
 
 // ───────────────────────────── CRUD ─────────────────────────────
 
-function registerCrudRoutes(app: FastifyInstance, ctx: EventPort): void {
+function registerCrudRoutes(app: FastifyInstance, ctx: EventPort & TabLayoutPort): void {
   app.get('/api/webviews', async (req) => {
     const user = getAuthUser(req);
     const all = await readWebviews(configDir());
@@ -131,6 +132,7 @@ function registerCrudRoutes(app: FastifyInstance, ctx: EventPort): void {
         // dashboard on an HTTPS Codeman, which is the common case.
         embedMode: input.embedMode ?? 'proxy',
         trusted: input.trusted ?? false,
+        managed: input.managed,
         owner,
         createdAt: Date.now(),
       };
@@ -145,6 +147,21 @@ function registerCrudRoutes(app: FastifyInstance, ctx: EventPort): void {
         .send(createErrorResponse(ApiErrorCode.INVALID_INPUT, `Webview limit reached (max ${MAX_WEBVIEWS})`));
     }
 
+    try {
+      await ctx.tabLayouts.webviewCreated(ownerLayoutKey(created.owner));
+    } catch (error) {
+      // The saved webview and its layout ref are one logical creation. If the
+      // layout rejects the new ref (for example at MAX_TAB_REFS), roll back the
+      // already-written JSON record and publish neither creation event.
+      await withWebviews(async (list) => {
+        const index = list.findIndex((webview) => webview.id === created.id);
+        if (index >= 0) {
+          list.splice(index, 1);
+          await writeWebviews(configDir(), list);
+        }
+      });
+      throw error;
+    }
     ctx.broadcast(SseEvent.WebviewChanged, { action: 'created', id: created.id });
     return { success: true, data: created };
   });
@@ -187,9 +204,19 @@ function registerCrudRoutes(app: FastifyInstance, ctx: EventPort): void {
       const index = list.findIndex((w) => w.id === id);
       if (index === -1) return 'not-found' as const;
       if (!canAccessOwned(user, list[index].owner)) return 'forbidden' as const;
+      const removed = list[index];
       list.splice(index, 1);
       await writeWebviews(configDir(), list);
-      return 'deleted' as const;
+      try {
+        await ctx.tabLayouts.webviewDeleted(ownerLayoutKey(removed.owner), id);
+      } catch (error) {
+        // Still inside withWebviews' mutex: restore the exact record at its
+        // original position without overwriting any concurrent mutation.
+        list.splice(index, 0, removed);
+        await writeWebviews(configDir(), list);
+        throw error;
+      }
+      return { status: 'deleted' as const, owner: removed.owner };
     });
 
     if (result === 'not-found') {

src/web/schemas.ts

@@ -122,7 +122,26 @@ export const FileWriteSchema = z
 // ========== Env Var Allowlist ==========
 
 /** Allowlisted env var key prefixes */
-const ALLOWED_ENV_PREFIXES = ['CLAUDE_CODE_', 'OPENCODE_', 'CODEX_', 'GEMINI_', 'GOOGLE_', 'ANTIGRAVITY_', 'PI_'];
+const ALLOWED_ENV_PREFIXES = [
+  'CLAUDE_CODE_',
+  'OPENCODE_',
+  'CODEX_',
+  'GEMINI_',
+  'GOOGLE_',
+  'ANTIGRAVITY_',
+  'PI_',
+  'GROK_',
+  'XAI_',
+  // DeepSeek Harness: `DSH_*` carries the launcher's own documented inputs
+  // (DSH_HOME, DSH_PERMISSION_MODE, DSH_TELEMETRY_MODE, and the DSH_TUI_* knobs
+  // the terminal front door reads); `DEEPSEEK_*` is the vendor namespace holding
+  // DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL, the same narrow-vendor reasoning that
+  // admitted XAI_* for grok. Foreign provider keys stay out: a dsh settings.yaml
+  // can name ANY env var as a provider credential (apiKeyEnv), which is pi's
+  // 34-provider-key problem in a new shape, and the answer is the same one.
+  'DSH_',
+  'DEEPSEEK_',
+];
 
 /**
  * Allowlisted exact env var keys (checked alongside the prefixes).
@@ -161,7 +180,7 @@ const safeEnvOverridesSchema = z
     },
     {
       message:
-        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, CODEX_*, GEMINI_*, GOOGLE_*, ANTIGRAVITY_*, PI_* keys and CLAUDE_CONFIG_DIR are allowed.',
+        'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, CODEX_*, GEMINI_*, GOOGLE_*, ANTIGRAVITY_*, PI_*, GROK_*, XAI_*, DSH_*, DEEPSEEK_* keys and CLAUDE_CONFIG_DIR are allowed.',
     }
   );
 
@@ -300,6 +319,114 @@ const PiConfigSchema = z
   })
   .optional();
 
+/**
+ * Schema for Grok Build CLI (xAI `grok`)-specific configuration.
+ *
+ * `alwaysApprove` maps to `--always-approve` (grok's bypassPermissions mode).
+ * An ABSENT config spawns bare `grok` = grok's own ask-mode default, so the
+ * multi-user clamp only needs the only-if-sent branch (like codex/antigravity).
+ */
+const GrokConfigSchema = z
+  .object({
+    model: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._\-/]+$/)
+      .optional(),
+    alwaysApprove: z.boolean().optional(),
+    continueSession: z.boolean().optional(),
+    // Ids only: grok's --resume also matches session TITLES (arbitrary user
+    // strings), which this regex deliberately cannot express.
+    resumeSessionId: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._-]+$/)
+      .optional(),
+  })
+  .optional();
+
+/**
+ * Schema for DeepSeek Harness (`dsh`)-specific configuration.
+ *
+ * `permissionMode` maps to the `DSH_PERMISSION_MODE` env export, NOT to a flag —
+ * the harness has no command-line permission switch. An ABSENT config spawns the
+ * profile under the harness's own `workspace-write` default, which still asks
+ * for approval, so the multi-user clamp only needs the only-if-sent branch (like
+ * codex/antigravity/grok).
+ *
+ * `profile` is a directory name under `$DSH_HOME/profiles`, so it is constrained
+ * to a single path SEGMENT: no separators, no dots-only names. It is interpolated
+ * into the `bash -c "…"` spawn line and joined into a filesystem path, and this
+ * regex is what keeps both safe.
+ */
+const DeepSeekConfigSchema = z
+  .object({
+    profile: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/)
+      .optional(),
+    permissionMode: z.enum(['read-only', 'workspace-write', 'danger-full-access']).optional(),
+    resumeSession: z.boolean().optional(),
+    resumeSessionId: z
+      .string()
+      .max(100)
+      .regex(/^[a-zA-Z0-9._-]+$/)
+      .optional(),
+    statusReporting: z.boolean().optional(),
+  })
+  .optional();
+
+/**
+ * Body of POST /api/deepseek/install-profile.
+ *
+ * `package` is a package SPECIFIER handed to `dsh plugin … add`, which runs a
+ * real package-manager install, so it is the security-relevant field. Two things
+ * contain it: this regex (an npm name, optionally scoped, optionally with an
+ * `@version` tail, and NOTHING else — no path, no URL, no git spec, no leading
+ * dash that could be read as a flag), and the route, which spawns an argv ARRAY
+ * with no shell. The route additionally requires the privileged grant in
+ * multi-user mode: installing a plugin is arbitrary code execution on the host,
+ * the same bar as a `shell` session.
+ */
+export const DeepSeekInstallProfileSchema = z
+  .object({
+    profile: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/)
+      .optional(),
+    package: z
+      .string()
+      .min(1)
+      .max(214)
+      .regex(/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-zA-Z0-9][a-zA-Z0-9._-]*)?$/)
+      .optional(),
+  })
+  .strict();
+
+/**
+ * POST /api/deepseek/web: start the background `dsh web` for one browser authority.
+ *
+ * `authority` becomes `--trusted-host`, which is what dsh fences its own `/api`
+ * behind, so it must be the origin the browser will actually load the tab from
+ * (`location.host`). It reaches a spawn as one element of an argv ARRAY, never a
+ * shell string, so this regex is defence in depth rather than the only guard: it
+ * admits host:port in the shapes a browser authority can take (dotted names,
+ * IPv4, bracketed IPv6) and nothing that could be read as a second argument.
+ */
+export const DeepSeekWebStartSchema = z
+  .object({
+    authority: z
+      .string()
+      .min(1)
+      .max(255)
+      .regex(/^(?:\[[0-9a-fA-F:]+\]|[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?)(?::\d{1,5})?$/),
+  })
+  .strict();
+
 /**
  * The session that spawned the one being created — pure UI decoration, drawn as a
  * lineage line between the two tabs. Accepted here and, equivalently, as the
@@ -313,7 +440,7 @@ const parentSessionIdSchema = z.string().max(100).optional();
 
 export const CreateSessionSchema = z.object({
   workingDir: safePathSchema.optional(),
-  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']).optional(),
   name: z.string().max(100).optional(),
   /** Session that spawned this one — see parentSessionIdSchema. */
   parentSessionId: parentSessionIdSchema,
@@ -322,13 +449,15 @@ export const CreateSessionSchema = z.object({
   effort: effortLevelSchema,
   /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
   modelOverride: z.string().max(50).optional(),
-  /** Inject the plan-usage statusLine exporter into the case (App Settings → Display → "Plan Usage Limits"). Claude-only. */
+  /** Inject the Claude statusLine source for the shared plan-usage chip. Claude sessions only; Codex is host-polled. */
   statusLineTelemetry: z.boolean().optional(),
   openCodeConfig: OpenCodeConfigSchema,
   codexConfig: CodexConfigSchema,
   geminiConfig: GeminiConfigSchema,
   antigravityConfig: AntigravityConfigSchema,
   piConfig: PiConfigSchema,
+  grokConfig: GrokConfigSchema,
+  deepSeekConfig: DeepSeekConfigSchema,
   /** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
   resumeSessionId: z
     .string()
@@ -464,6 +593,8 @@ const RemoteCommandOverridesSchema = z
     gemini: z.string().min(1).max(300).optional(),
     antigravity: z.string().min(1).max(300).optional(),
     pi: z.string().min(1).max(300).optional(),
+    grok: z.string().min(1).max(300).optional(),
+    deepseek: z.string().min(1).max(300).optional(),
   })
   .strict()
   .optional();
@@ -738,12 +869,14 @@ export const QuickStartSchema = z.object({
    *  a real host dir, so the settings file crosses the bind mount); rejected for
    *  remote cases (the file would be written on the WRONG machine). */
   modelOverride: z.string().max(50).optional(),
-  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']).optional(),
+  mode: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']).optional(),
   openCodeConfig: OpenCodeConfigSchema,
   codexConfig: CodexConfigSchema,
   geminiConfig: GeminiConfigSchema,
   antigravityConfig: AntigravityConfigSchema,
   piConfig: PiConfigSchema,
+  grokConfig: GrokConfigSchema,
+  deepSeekConfig: DeepSeekConfigSchema,
   envOverrides: safeEnvOverridesSchema,
   /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
   effort: effortLevelSchema,
@@ -765,6 +898,11 @@ export const HookEventSchema = z.object({
     'stop',
     'teammate_idle',
     'task_completed',
+    // A turn STARTED. Unlike the others this one has no Claude Code hook behind
+    // it: it is reported by the DeepSeek Harness status shim, and exists so a
+    // dialog answered in the terminal resolves its Approvals Inbox item at once
+    // instead of lingering red until the next `stop`.
+    'agent_working',
   ]),
   sessionId: z.string().min(1),
   data: z.record(z.string(), z.unknown()).nullable().optional(),
@@ -956,6 +1094,9 @@ export const SettingsUpdateSchema = z
     // CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK env var. Stripped before persisting.
     acknowledgeUnauthTunnel: z.boolean().optional(),
     tabTwoRows: z.boolean().optional(),
+    tabOrientation: z.enum(['horizontal', 'vertical']).optional(),
+    tabRailWidth: z.number().int().min(208).max(360).optional(),
+    tabRailDetail: z.enum(['simple', 'rich']).optional(),
     /**
      * Session list layout. Display key (per-device).
      * 'header'       = horizontal tab strip
@@ -967,6 +1108,8 @@ export const SettingsUpdateSchema = z
      * on data-sidebar-detail. See applySessionListLayout() in app.js.
      */
     sessionListLayout: z.enum(['header', 'sidebar', 'sidebar-rich']).optional(),
+    /** Session-name text size in vertical navigation. Display key (per-device). */
+    sessionSidebarFontSize: z.number().int().min(11).max(18).optional(),
     agentTeamsEnabled: z.boolean().optional(),
     /** Model for new Claude sessions (e.g. "claude-fable-5[1m]", "opus[1m]"); takes precedence over opusContext1mEnabled */
     claudeModel: z.string().max(50).optional(),
@@ -1267,7 +1410,7 @@ const noNewlines = (v: string) => !/[\r\n]/.test(v);
 /** Shared field shape for creating/updating a scheduled job. */
 const CronJobBaseSchema = z.object({
   name: z.string().min(1).max(200),
-  agentType: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi']),
+  agentType: z.enum(['claude', 'shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok', 'deepseek']),
   workingDir: safePathSchema,
   launchCommand: z.string().max(2000).refine(noNewlines, 'launchCommand must be a single line').optional(),
   promptMode: z.enum(['inline_text', 'prompt_file_path']),
@@ -1557,6 +1700,12 @@ const WebviewBaseSchema = z.object({
    * and call the API that spawns agents.
    */
   trusted: z.boolean().optional(),
+  /**
+   * Marks a record Codeman maintains itself. Declared here because a plain
+   * `z.object` STRIPS undeclared keys, so an undeclared marker would be dropped
+   * on the way in and the dedup it drives would never fire.
+   */
+  managed: z.enum(['deepseek-web']).optional(),
 });
 
 /** POST /api/webviews */

src/web/server.ts

@@ -50,6 +50,9 @@ import { RespawnController, RespawnConfig } from '../respawn-controller.js';
 import type { TerminalMultiplexer } from '../mux-interface.js';
 import { createMultiplexer } from '../mux-factory.js';
 import { getStore } from '../state-store.js';
+import { TabLayoutService } from '../tab-layout-service.js';
+import { ownerLayoutKey } from '../tab-layout-persistence.js';
+import { readWebviews } from '../webview-store.js';
 import { extractCompletionPhrase } from '../ralph-config.js';
 import { fileStreamManager } from '../file-stream-manager.js';
 import {
@@ -81,16 +84,18 @@ import { applyWorkspaceHooks } from '../hooks-config.js';
 import { PushSubscriptionStore } from '../push-store.js';
 import webpush from 'web-push';
 import { SseStreamManager } from './sse-stream-manager.js';
+import { deriveTabLayoutSseHint } from './tab-layout-sse.js';
 import {
   type SessionListenerRefs,
   createSessionListeners,
   attachSessionListeners,
   detachSessionListeners,
 } from './session-listener-wiring.js';
-import { sessionWaits, hooksAvailableForMode } from './session-wait-registry.js';
+import { sessionWaits } from './session-wait-registry.js';
 import { intentStore } from '../intent-store.js';
 import { AI_CHECK_MODEL } from '../config/ai-defaults.js';
 import { approvalInbox } from './approval-inbox.js';
+import { stopDeepSeekWeb } from '../deepseek-web-server.js';
 import {
   wireRespawnListeners,
   setupTimedRespawn,
@@ -138,7 +143,9 @@ import { MAX_CONCURRENT_SESSIONS, MAX_SSE_CLIENTS } from '../config/map-limits.j
 import { MAX_PASTE_IMAGE_BYTES } from '../config/buffer-limits.js';
 import { resolveTerminalHistoryConfig } from '../config/terminal-history.js';
 import { SseEvent } from './sse-events.js';
-import { getLatestPlanUsage } from './plan-usage-latest.js';
+import { getLatestPlanUsage, setLatestCodexPlanUsage } from './plan-usage-latest.js';
+import { telemetrySignature } from '../usage-telemetry.js';
+import { readCodexPlanUsage, resolveCodexBinaryPath } from '../utils/codex-cli-resolver.js';
 import type { ScheduledRun } from './ports/index.js';
 import { registerAuthMiddleware, registerSecurityHeaders, registerHostGuard } from './middleware/auth.js';
 import { isMultiUserMode } from '../config/multiuser.js';
@@ -170,6 +177,7 @@ import {
   registerWsRoutes,
   registerVoiceRoutes,
   registerWebviewRoutes,
+  registerTabLayoutRoutes,
   tryWebviewRefererFallback,
 } from './routes/index.js';
 import { CronService } from '../cron/cron-service.js';
@@ -180,6 +188,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Length range covers crypto.randomUUID() (36 chars) plus any short stable IDs,
 // while capping growth of `sseClientsById` and blocking pathological inputs.
 const SSE_CLIENT_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+const CODEX_USAGE_POLL_INTERVAL_MS = 5 * 60_000;
 
 function escapeHtmlText(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
@@ -247,6 +256,7 @@ export class WebServer extends EventEmitter {
   private cronService!: CronService;
   private sse: SseStreamManager;
   private store = getStore();
+  private tabLayouts!: TabLayoutService;
   private port: number;
   private host: string;
   private https: boolean;
@@ -261,6 +271,8 @@ export class WebServer extends EventEmitter {
   private cachedSessionsList: { data: unknown[]; timestamp: number } | null = null;
   // Token recording for daily stats (track what's been recorded to avoid double-counting)
   private lastRecordedTokens: Map<string, { input: number; output: number }> = new Map();
+  private codexUsageRefreshInFlight = false;
+  private lastCodexUsageSignature: string | null = null;
   // Server startup time for respawn grace period calculation
   private readonly serverStartTime: number = Date.now();
   // Pending respawn start timers (for cleanup on shutdown)
@@ -350,6 +362,17 @@ export class WebServer extends EventEmitter {
       },
       this.cleanup
     );
+    this.tabLayouts = new TabLayoutService({
+      store: this.store,
+      sessions: this.sessions,
+      readWebviews: () => readWebviews(getDataDir()),
+      broadcast: this.broadcast.bind(this),
+      broadcastSessionOrder: (change) => {
+        this.cachedLightState = null;
+        this.sse.broadcastSessionOrder(change);
+      },
+    });
+    if (this.testMode) this.tabLayouts.markRestorationSkipped();
 
     // Approvals Inbox → SSE. The singleton has no server reference; these
     // callbacks are its only way out. Broadcasts carry sessionId, so the
@@ -595,6 +618,17 @@ export class WebServer extends EventEmitter {
     }
   }
 
+  /** Add a tentative session only after its owner layout accepts the creation. */
+  private async registerSessionWithLayout(session: Session): Promise<void> {
+    this.sessions.set(session.id, session);
+    try {
+      await this.tabLayouts.sessionCreated(ownerLayoutKey(session.owner));
+    } catch (error) {
+      this.sessions.delete(session.id);
+      throw error;
+    }
+  }
+
   /**
    * Build a route context object satisfying all 5 port interfaces.
    * Single object with zero runtime cost — ISP enforced at the type level.
@@ -605,9 +639,8 @@ export class WebServer extends EventEmitter {
     return {
       // SessionPort
       sessions: this.sessions as ReadonlyMap<string, Session>,
-      addSession: (session: Session) => {
-        this.sessions.set(session.id, session);
-      },
+      addSession: this.registerSessionWithLayout.bind(this),
+      tabLayouts: this.tabLayouts,
       cleanupSession: this.cleanupSession.bind(this),
       setupSessionListeners: this.setupSessionListeners.bind(this),
       persistSessionState: this.persistSessionState.bind(this),
@@ -991,6 +1024,7 @@ export class WebServer extends EventEmitter {
     registerAdminRoutes(this.app, ctx);
     registerOrchestratorRoutes(this.app, ctx);
     registerWebviewRoutes(this.app, ctx);
+    registerTabLayoutRoutes(this.app, ctx);
 
     // Cron: build the service from the same context, recompute
     // due times for any persisted jobs, then expose it to its routes.
@@ -1065,7 +1099,10 @@ export class WebServer extends EventEmitter {
    */
   private async captureIntentPrompt(sessionId: string, text: string): Promise<void> {
     const session = this.sessions.get(sessionId);
-    if (!session || !hooksAvailableForMode(session.mode)) return;
+    // `mode === 'claude'` directly: the intent profile is fed from Claude's own
+    // transcript, so this is a claude question, not a hooks-available one (which
+    // `deepseek` now answers yes to).
+    if (!session || session.mode !== 'claude') return;
     try {
       const settings = await this.readSettings();
       if (settings.readMyMindEnabled !== true) return;
@@ -1154,8 +1191,19 @@ export class WebServer extends EventEmitter {
     }
   }
 
-  private async _doCleanupSession(sessionId: string, killMux: boolean, reason?: string): Promise<void> {
+  private async _doCleanupSession(
+    sessionId: string,
+    killMux: boolean,
+    reason?: string,
+    coordinateLayout = true
+  ): Promise<void> {
     const session = this.sessions.get(sessionId);
+    const pinned = session?.pinned === true || this.store.getSession(sessionId)?.pinned === true;
+    if (coordinateLayout && session && killMux && !pinned) {
+      return this.tabLayouts.runSessionDeletion([{ id: sessionId, owner: session.owner }], () =>
+        this._doCleanupSession(sessionId, killMux, reason, false)
+      );
+    }
     const lifecycleLog = getLifecycleLog();
     lifecycleLog.log({
       event: killMux ? 'deleted' : 'detached',
@@ -1396,6 +1444,8 @@ export class WebServer extends EventEmitter {
         { isGeminiAvailable },
         { isAntigravityAvailable },
         { isPiAvailable },
+        { isGrokAvailable },
+        { isDeepSeekRunnable, isDeepSeekAvailable },
         { isCloudflaredAvailable },
         { isGitAvailable },
       ] = await Promise.all([
@@ -1405,6 +1455,8 @@ export class WebServer extends EventEmitter {
         import('../utils/gemini-cli-resolver.js'),
         import('../utils/antigravity-cli-resolver.js'),
         import('../utils/pi-cli-resolver.js'),
+        import('../utils/grok-cli-resolver.js'),
+        import('../utils/deepseek-cli-resolver.js'),
         import('../utils/cloudflared-resolver.js'),
         import('../git-clone.js'),
       ]);
@@ -1415,6 +1467,14 @@ export class WebServer extends EventEmitter {
         gemini: isGeminiAvailable(),
         antigravity: isAntigravityAvailable(),
         pi: isPiAvailable(),
+        grok: isGrokAvailable(),
+        // RUNNABLE, not merely installed: `dsh` is a profile launcher, and a dsh
+        // with no pane-capable profile would offer a Run button that spawns a
+        // pane which dies on arrival. The Add-Profile affordance in the run menu
+        // keys off `deepseekBinary` instead, so a user who has the binary but no
+        // profile is offered the fix rather than a greyed-out entry.
+        deepseek: isDeepSeekRunnable(),
+        deepseekBinary: isDeepSeekAvailable(),
         cloudflared: isCloudflaredAvailable(),
         // Not a run mode: the Add Case → Clone tab is an offer this box cannot
         // keep without git (issue #236), same reasoning as cloudflared above.
@@ -1857,7 +1917,7 @@ export class WebServer extends EventEmitter {
           // mode) so the flag-off path stays byte-identical.
           session = new Session({ workingDir: run.workingDir });
         }
-        this.sessions.set(session.id, session);
+        await this.registerSessionWithLayout(session);
         this.store.incrementSessionsCreated();
         this.persistSessionState(session);
         await this.setupSessionListeners(session);
@@ -1987,9 +2047,11 @@ export class WebServer extends EventEmitter {
    * Called on startup and can be called via API endpoint.
    * @returns Number of sessions cleaned up
    */
-  private cleanupStaleSessions(): number {
+  private async cleanupStaleSessions(): Promise<number> {
     const activeSessionIds = new Set(this.sessions.keys());
-    const result = this.store.cleanupStaleSessions(activeSessionIds);
+    const result = await this.tabLayouts.runStaleSessionCleanup(activeSessionIds, (ids) =>
+      this.store.cleanupSessionsByIds(ids)
+    );
     const lifecycleLog = getLifecycleLog();
     for (const s of result.cleaned) {
       lifecycleLog.log({ event: 'stale_cleaned', sessionId: s.id, name: s.name });
@@ -2013,11 +2075,13 @@ export class WebServer extends EventEmitter {
 
   /** Shallow-filter the light-state blob to what a non-admin user may see. */
   private filterLightStateForUser(base: Record<string, unknown>, username: string): Record<string, unknown> {
-    const ownedIds = new Set<string>();
+    const authoritativeOwners = new Map<string, string | undefined>();
+    for (const [id, session] of Object.entries(this.store.getSessions())) authoritativeOwners.set(id, session.owner);
+    for (const [id, session] of this.sessions) authoritativeOwners.set(id, session.owner);
+    const ownedIds = new Set([...authoritativeOwners].filter(([, owner]) => owner === username).map(([id]) => id));
     const ownedClaudeIds = new Set<string>();
-    for (const [id, s] of this.sessions) {
+    for (const s of this.sessions.values()) {
       if (s.owner === username) {
-        ownedIds.add(id);
         if (s.claudeSessionId) ownedClaudeIds.add(s.claudeSessionId);
       }
     }
@@ -2035,6 +2099,9 @@ export class WebServer extends EventEmitter {
     const filtered: Record<string, unknown> = {
       ...base,
       sessions,
+      sessionOrder: Array.isArray(base.sessionOrder)
+        ? (base.sessionOrder as string[]).filter((id) => ownedIds.has(id))
+        : [],
       respawnStatus,
       scheduledRuns: [], // legacy ScheduledRun has no owner yet → admin-only
       subagents: bySession(base.subagents, 'sessionId'),
@@ -2071,6 +2138,7 @@ export class WebServer extends EventEmitter {
     const result = {
       version: APP_VERSION,
       sessions: this.getLightSessionsState(),
+      sessionOrder: this.store.getSessionOrder(),
       scheduledRuns: Array.from(this.scheduledRuns.values()),
       respawnStatus,
       globalStats: this.store.getAggregateStats(activeSessionTokens),
@@ -2079,7 +2147,6 @@ export class WebServer extends EventEmitter {
       timestamp: now,
       inputCjkForm: process.env.INPUT_CJK_FORM?.toUpperCase() === 'ON',
       planUsage: getLatestPlanUsage(), // last-known plan-usage telemetry, for the header chip on fresh load
-      sessionOrder: this.store.getSessionOrder(), // global tab order, synced across devices (COD-131)
     };
 
     this.cachedLightState = { data: result, timestamp: now };
@@ -2118,6 +2185,11 @@ export class WebServer extends EventEmitter {
     ) {
       return { adminOnly: true };
     }
+    // Layout payloads contain only trusted routing metadata. Route them to that
+    // exact owner plus admins, never by resolving a client-supplied ref.
+    if (event.startsWith('tab:')) {
+      return deriveTabLayoutSseHint(data);
+    }
     // Session-scoped families: resolve the owner from the payload's session id.
     const SESSION_PREFIXES = [
       'session:',
@@ -2327,6 +2399,23 @@ export class WebServer extends EventEmitter {
     }
   }
 
+  private async refreshCodexPlanUsage(): Promise<void> {
+    if (this.codexUsageRefreshInFlight) return;
+    this.codexUsageRefreshInFlight = true;
+    try {
+      const binaryPath = resolveCodexBinaryPath();
+      const usage = binaryPath ? await readCodexPlanUsage(binaryPath, APP_VERSION) : null;
+      const signature = usage ? telemetrySignature(usage) : '';
+      if (signature === this.lastCodexUsageSignature) return;
+      this.lastCodexUsageSignature = signature;
+      const snapshot = setLatestCodexPlanUsage(usage);
+      this.cachedLightState = null;
+      this.broadcast(SseEvent.SessionStatusTelemetry, snapshot);
+    } finally {
+      this.codexUsageRefreshInFlight = false;
+    }
+  }
+
   async start(): Promise<void> {
     // Multi-user first boot: create the initial admin from CODEMAN_USERNAME/PASSWORD
     // if there are no users yet, else refuse to start (there would be no way in).
@@ -2363,26 +2452,26 @@ export class WebServer extends EventEmitter {
     // This prevents race conditions where clients connect before state is ready
     // CRITICAL: Skip in test mode to prevent tests from picking up user sessions
     if (!this.testMode) {
-      await this.restoreMuxSessions();
+      const restored = await this.restoreMuxSessions();
+      await this.finalizeRestoredState(restored);
 
       // Instance-scoped reaper: after restore, `docker rm -f` managed containers of
       // THIS instance whose case is gone from docker-cases.json (best-effort, never
       // touches another instance's containers). Runs after restore so containers
       // still referenced by a restored session are preserved.
-      void import('../docker-hosts.js')
-        .then(({ reapOrphanedDockerContainers }) => reapOrphanedDockerContainers(getDataDir(), CODEMAN_INSTANCE))
-        .then((reaped) => {
-          if (reaped.length > 0)
-            console.log(`[Docker] reaped ${reaped.length} orphaned container(s): ${reaped.join(', ')}`);
-        })
-        .catch(() => {
-          /* best-effort — daemon may be absent */
-        });
+      if (restored) {
+        void import('../docker-hosts.js')
+          .then(({ reapOrphanedDockerContainers }) => reapOrphanedDockerContainers(getDataDir(), CODEMAN_INSTANCE))
+          .then((reaped) => {
+            if (reaped.length > 0)
+              console.log(`[Docker] reaped ${reaped.length} orphaned container(s): ${reaped.join(', ')}`);
+          })
+          .catch(() => {
+            /* best-effort — daemon may be absent */
+          });
+      }
     }
 
-    // Clean up stale sessions from state file that don't have active mux sessions
-    this.cleanupStaleSessions();
-
     // Bound disk use under heavy paste-image traffic: delete `paste-*` files
     // older than 7 days from each live session's .claude-images/ hourly.
     if (!this.testMode) {
@@ -2464,6 +2553,15 @@ export class WebServer extends EventEmitter {
     // $CODEMAN_HOOK_SECRET_FILE — hook curls cat that path at execution time.
     getHookSecret();
 
+    // Main Codex subscription limits come from the signed-in local CLI. Keep
+    // this read-only and host-scoped; multi-user SSE routing makes it admin-only.
+    if (!this.testMode) {
+      void this.refreshCodexPlanUsage();
+      this.cleanup.setInterval(() => void this.refreshCodexPlanUsage(), CODEX_USAGE_POLL_INTERVAL_MS, {
+        description: 'Codex plan-usage refresh',
+      });
+    }
+
     // Start scheduled runs cleanup timer
     this.cleanup.setInterval(
       () => {
@@ -2618,7 +2716,7 @@ export class WebServer extends EventEmitter {
     return false;
   }
 
-  private async restoreMuxSessions(): Promise<void> {
+  private async restoreMuxSessions(): Promise<boolean> {
     try {
       // Reconcile mux sessions to find which ones are still alive (also discovers unknown ones)
       const { alive, dead, discovered } = await this.mux.reconcileSessions();
@@ -2683,6 +2781,8 @@ export class WebServer extends EventEmitter {
               geminiConfig: muxSession.mode === 'gemini' ? savedState?.geminiConfig : undefined,
               antigravityConfig: muxSession.mode === 'antigravity' ? savedState?.antigravityConfig : undefined,
               piConfig: muxSession.mode === 'pi' ? savedState?.piConfig : undefined,
+              grokConfig: muxSession.mode === 'grok' ? savedState?.grokConfig : undefined,
+              deepSeekConfig: muxSession.mode === 'deepseek' ? savedState?.deepSeekConfig : undefined,
               envOverrides: savedEnvOverrides,
               effort: savedState?.effort,
               attachmentHistory: savedAttachmentHistory,
@@ -2897,11 +2997,24 @@ export class WebServer extends EventEmitter {
       if (dead.length > 0) {
         console.log(`[Server] Cleaned up ${dead.length} dead mux session(s)`);
       }
+      return true;
     } catch (err) {
       console.error('[Server] Failed to restore mux sessions:', err);
+      return false;
     }
   }
 
+  /** Unlock destructive reconciliation only after mux restoration fully succeeds. */
+  private async finalizeRestoredState(restored: boolean): Promise<void> {
+    if (!restored) {
+      this.tabLayouts.markRestorationFailed();
+      return;
+    }
+    this.tabLayouts.markRestorationComplete();
+    await this.cleanupStaleSessions();
+    await this.tabLayouts.reconcileAfterRestoration();
+  }
+
   /**
    * Install Codeman's hooks into the workspaces of the sessions just recovered.
    *
@@ -3054,6 +3167,12 @@ export class WebServer extends EventEmitter {
       this._dockerBridgeServer = null;
     }
 
+    // The background `dsh web` is detached so its whole plugin tree can be
+    // signalled at once, which also means it would OUTLIVE Codeman and hold its
+    // port against the next start — the exact EADDRINUSE this feature already
+    // got wrong once.
+    void stopDeepSeekWeb();
+
     // Dispose all managed timers (intervals + resettable timeouts)
     this.cleanup.dispose();
 

src/web/session-order-sse.ts

@@ -0,0 +1,15 @@
+/** @fileoverview Trusted per-recipient payload selection for legacy session-order invalidations. */
+import type { SessionOrderProjectionChange } from '../tab-layout-service.js';
+import type { AuthUser } from '../types.js';
+
+export function sessionOrderPayloadFor(
+  identity: AuthUser | undefined,
+  change: SessionOrderProjectionChange
+): { order: string[] } | undefined {
+  if (!identity || identity.role === 'admin') {
+    return change.globalChanged ? { order: [...change.globalOrder] } : undefined;
+  }
+  if (!Object.hasOwn(change.changedOwnerOrders, identity.username)) return undefined;
+  const order = change.changedOwnerOrders[identity.username];
+  return Array.isArray(order) ? { order: [...order] } : undefined;
+}

src/web/session-wait-registry.ts

@@ -170,19 +170,91 @@ export function signalForStatus(status: SessionStatus): WaitSignal | null {
 /** Signals that arrive only via Claude Code hooks, so only `claude` mode can emit them. */
 const HOOK_ONLY_SIGNALS: readonly WaitSignal[] = ['stop', 'blocked'];
 
+/** Per-session facts that can turn a mode's hook capability OFF for one session. */
+export interface HookCapabilityOptions {
+  /**
+   * `deepSeekConfig.statusReporting`, verbatim (so `undefined` means "not sent",
+   * i.e. ON). `false` is the per-session opt-out that stops `_configureDeepSeek()`
+   * exporting the `HERDR_*` triple, which is the ONLY thing that makes a dsh
+   * session emit hook events at all.
+   */
+  deepSeekStatusReporting?: boolean;
+  /**
+   * True when the pane's harness runs somewhere the status bridge cannot reach:
+   * a docker case (`docker exec` does not carry the local tmux env into the
+   * container, and the loopback-bound API is unreachable from it) or a
+   * remote-SSH case (the `HERDR_*` triple is set on the LOCAL ssh process, not
+   * the remote shell). Such a session never posts a hook event however the
+   * statusReporting flag is set, so `until=stop` on it would burn its whole
+   * timeout on every turn.
+   */
+  deepSeekBridgeUnreachable?: boolean;
+}
+
 /**
- * Whether a session in this mode ever POSTs Codeman hook events, and therefore
- * whether `stop` / `blocked` can ever fire for it.
+ * Whether this session ever POSTs Codeman hook events, and therefore whether
+ * `stop` / `blocked` can ever fire for it.
  *
- * True for `claude` and nothing else. The tempting predicate is
+ * `claude` always (Claude Code fires the hooks itself), `deepseek` when its
+ * status bridge is armed, nothing else. The tempting predicate is
  * `!isExternalCliMode(mode)`, and it is WRONG: that helper covers only
  * opencode/codex/gemini/antigravity, so `shell` falls through it — and a shell session
  * is a plain bash PTY with no Claude Code and no hooks installed. `until=stop` on one
  * was accepted and then blocked for the caller's whole timeout, which is precisely the
  * infinite-wait-dressed-as-a-timeout this guard exists to prevent.
+ *
+ * ⚠️ `deepseek` is a per-SESSION answer, not a per-mode one, which is why the
+ * options argument exists: `deepSeekConfig.statusReporting: false` disarms the
+ * bridge for one session, and answering from the mode alone re-creates the exact
+ * infinite-wait this guard is for. Every call site therefore passes the session's
+ * own flag; the default stays permissive so a forgotten one degrades to the old
+ * behavior rather than 400ing a session that works.
+ *
+ * ⚠️ It is also the LIMIT of what can be known at request time. Whether the
+ * installed profile actually implements the supervisor contract is only
+ * observable once it reports, and `resolveDefaultDeepSeekProfile()` deliberately
+ * treats an unrecognized profile as launchable, so a dsh session running a
+ * non-conforming TUI still answers true here and still times out on an explicit
+ * `until=stop`. The default signal set keeps `idle`/`exit` for exactly that case.
+ *
+ * ⚠️ NOT a stand-in for "is this a claude session". It reads like one and it was
+ * used as one (Read My Mind, intent capture) until `deepseek` joined and silently
+ * widened both. Those sites compare `mode === 'claude'` directly now; ask this
+ * function only about hook SIGNALS.
  */
-export function hooksAvailableForMode(mode: SessionMode): boolean {
-  return mode === 'claude';
+export function hooksAvailableForMode(mode: SessionMode, options: HookCapabilityOptions = {}): boolean {
+  if (mode === 'claude') return true;
+  // `deepseek` earns this the same way `claude` does — by emitting DEFINITIVE
+  // signals rather than having them inferred. The DeepSeek Harness terminal
+  // front door reports idle/working/blocked to its supervisor, and Codeman is
+  // that supervisor (see deepseek-status-shim.ts), so a dsh session really can
+  // deliver `stop` and `blocked` — unless the user turned the bridge off, in
+  // which case nothing on the box will ever post one. Every other mode is
+  // output-stabilization guesswork and must keep failing the ask.
+  if (mode === 'deepseek') {
+    return options.deepSeekStatusReporting !== false && options.deepSeekBridgeUnreachable !== true;
+  }
+  return false;
+}
+
+/**
+ * Lift the per-session hook facts off a live session.
+ *
+ * Structurally typed on purpose: this module is pure and deliberately imports no
+ * `Session` (importing it would drag node-pty and the session layer into every
+ * consumer). One helper rather than an inline object literal at each of the four
+ * call sites, so a future per-session fact is added in one place instead of
+ * being forgotten at three of them.
+ */
+export function sessionHookOptions(session: {
+  deepSeekStatusReporting?: boolean;
+  docker?: unknown;
+  remote?: unknown;
+}): HookCapabilityOptions {
+  return {
+    deepSeekStatusReporting: session.deepSeekStatusReporting,
+    deepSeekBridgeUnreachable: Boolean(session.docker || session.remote),
+  };
 }
 
 /** Outcome of resolving a caller-supplied wait target against a session's mode. */
@@ -206,10 +278,15 @@ export interface ResolvedWaitSignals {
  * not drift; the second-guessing that produces is worse than the duplication.
  *
  * @param raw - the caller's value (comma string, array, `true` for "the default")
- * @param options - `mode` decides whether the hook-only signals are available, and
- *                  names the mode in the error message so the caller can see why
+ * @param options - `mode` plus the per-session facts `hooksAvailableForMode()` needs
+ *                  (a dsh session with its status bridge disarmed emits no hooks even
+ *                  though the mode can). The mode also names itself in the error
+ *                  message so the caller can see why.
  */
-export function resolveWaitSignals(raw: unknown, options: { mode: SessionMode }): ResolvedWaitSignals {
+export function resolveWaitSignals(
+  raw: unknown,
+  options: { mode: SessionMode } & HookCapabilityOptions
+): ResolvedWaitSignals {
   const parsed = parseWaitSignals(raw);
   if (parsed.invalid.length > 0) {
     return {
@@ -218,7 +295,7 @@ export function resolveWaitSignals(raw: unknown, options: { mode: SessionMode })
     };
   }
 
-  const unsupported = new Set<WaitSignal>(hooksAvailableForMode(options.mode) ? [] : HOOK_ONLY_SIGNALS);
+  const unsupported = new Set<WaitSignal>(hooksAvailableForMode(options.mode, options) ? [] : HOOK_ONLY_SIGNALS);
 
   if (parsed.signals.length === 0) {
     return { until: DEFAULT_WAIT_SIGNALS.filter((signal) => !unsupported.has(signal)), error: null };
@@ -228,7 +305,17 @@ export function resolveWaitSignals(raw: unknown, options: { mode: SessionMode })
   if (rejected.length > 0) {
     return {
       until: [],
-      error: `Signal(s) ${rejected.join(', ')} never fire for ${options.mode} sessions (no Claude Code hooks). Use idle or exit.`,
+      // A dsh session is the one case where the mode is capable and THIS session
+      // is not, so saying "never fire for deepseek sessions" would send the
+      // caller looking for a bug that is really a setting they chose.
+      error:
+        options.mode === 'deepseek'
+          ? options.deepSeekBridgeUnreachable
+            ? `Signal(s) ${rejected.join(', ')} never fire for this deepseek session: it runs in a container or on ` +
+              `a remote host, where the local status bridge cannot reach the harness. Use idle or exit.`
+            : `Signal(s) ${rejected.join(', ')} never fire for this deepseek session: its status bridge is off ` +
+              `(deepSeekConfig.statusReporting: false), so nothing posts hook events. Use idle or exit.`
+          : `Signal(s) ${rejected.join(', ')} never fire for ${options.mode} sessions (no Claude Code hooks). Use idle or exit.`,
     };
   }
   return { until: parsed.signals, error: null };

src/web/sse-events.ts

@@ -5,7 +5,7 @@
  * and referenced by the frontend (`SSE_EVENTS` in `constants.js`).
  * Both files MUST be kept in sync.
  *
- * 155 event constants organized by category:
+ * 157 event constants organized by category:
  * - **Core** (1): init
  * - **Transport** (1): sse:heartbeat
  * - **Session lifecycle** (23): created, updated, deleted, terminal, idle, working, ...
@@ -25,14 +25,15 @@
  * - **Plan orchestration** (5): started, progress, subagent, completed, cancelled
  * - **Tunnel** (7): started, stopped, progress, error, qrRotated, qrRegenerated, qrAuthUsed
  * - **Image / attachments** (2): image:detected, attachment:detected
- * - **Hooks** (8): idle_prompt, permission_prompt, elicitation_dialog, elicitation_complete, elicitation_response, stop, teammate_idle, task_completed
+ * - **Hooks** (9): idle_prompt, permission_prompt, elicitation_dialog, elicitation_complete, elicitation_response, stop, agent_working, teammate_idle, task_completed
+ *   (agent_working is the odd one out: reported by the DeepSeek Harness status bridge, not by a Claude Code hook)
  * - **Approvals** (3): pending, updated, resolved (cross-session Approvals Inbox)
  * - **Orchestrator** (12): stateChanged, planProgress, planReady, phase*, verification, task*, completed, error
  * - **Clipboard** (1): write
  * - **Cases** (4): created, linked, deleted, order-changed
  * - **Docker cases** (8): exportComplete/Failed, importComplete, imageBuild*, containerRecreated
  * - **Multi-user** (3): admin:usersChanged, auth:passwordChangeRequired, session:orderChanged
- * - **Web tabs** (1): webview:changed
+ * - **Web tabs** (2): webview:changed, tab:layoutChanged
  *
  * Naming convention: `domain:action` (e.g., `session:created`, `respawn:stateChanged`)
  *
@@ -115,7 +116,7 @@ export const SessionMessage = 'session:message' as const;
 export const SessionInteractive = 'session:interactive' as const;
 /** Prompt sent to session for execution. */
 export const SessionRunning = 'session:running' as const;
-/** Claude plan-usage telemetry (5-hour + weekly limits) parsed from the statusline. */
+/** Combined Claude and main Codex plan-usage telemetry for the shared header chip. */
 export const SessionStatusTelemetry = 'session:statusTelemetry' as const;
 
 // ─── Session: Ralph ──────────────────────────────────────────────────────────
@@ -360,6 +361,13 @@ export const HookElicitationComplete = 'hook:elicitation_complete' as const;
 export const HookElicitationResponse = 'hook:elicitation_response' as const;
 /** Claude Code hook: response complete. */
 export const HookStop = 'hook:stop' as const;
+/**
+ * Agent started a turn. NOT a Claude Code hook: this one is reported by the
+ * DeepSeek Harness status bridge, which is why the name is agent-generic. It
+ * exists so a dialog answered in the terminal clears its alert immediately
+ * instead of waiting for the turn to end.
+ */
+export const HookAgentWorking = 'hook:agent_working' as const;
 /** Claude Code hook: teammate went idle. */
 export const HookTeammateIdle = 'hook:teammate_idle' as const;
 /** Claude Code hook: teammate task completed. */
@@ -449,6 +457,8 @@ export const SessionOrderChanged = 'session:orderChanged' as const;
  *  Payload: `{ action: 'created' | 'updated' | 'deleted', id }`. The client
  *  re-fetches the list rather than patching from the payload. */
 export const WebviewChanged = 'webview:changed' as const;
+/** Owner-scoped layout invalidation. Payload contains only `{ owner, version }`. */
+export const TabLayoutChanged = 'tab:layoutChanged' as const;
 
 // ─── Namespace Re-export ─────────────────────────────────────────────────────
 
@@ -617,6 +627,7 @@ export const SseEvent = {
   HookElicitationComplete,
   HookElicitationResponse,
   HookStop,
+  HookAgentWorking,
   HookTeammateIdle,
   HookTaskCompleted,
 
@@ -665,4 +676,5 @@ export const SseEvent = {
 
   // Web tabs (dashboard URLs)
   WebviewChanged,
+  TabLayoutChanged,
 } as const;

src/web/sse-stream-manager.ts

@@ -17,9 +17,11 @@
 
 import type { FastifyReply } from 'fastify';
 import type { BackgroundTask } from '../session.js';
+import type { SessionOrderProjectionChange } from '../tab-layout-service.js';
 import type { AuthUser } from '../types.js';
 import { CleanupManager, StaleExpirationMap } from '../utils/index.js';
 import { SseEvent } from './sse-events.js';
+import { sessionOrderPayloadFor } from './session-order-sse.js';
 import {
   TERMINAL_BATCH_INTERVAL,
   TASK_UPDATE_BATCH_INTERVAL,
@@ -34,6 +36,7 @@ import {
 // Appending SSE comment padding (ignored by EventSource) forces the proxy to flush.
 // Pre-computed once at startup to avoid repeated string allocation.
 const SSE_PADDING = ':' + 'p'.repeat(SSE_PADDING_SIZE) + '\n';
+const UNROUTED_TAB_LAYOUT = Symbol('unrouted-tab-layout');
 
 /** Dependencies injected by WebServer — keeps SseStreamManager decoupled from session/respawn state. */
 interface SseStreamManagerDeps {
@@ -77,6 +80,10 @@ export class SseStreamManager {
   private remoteSseClients: Set<FastifyReply> = new Set();
   /** Clients with backpressure — skip writes until 'drain' fires */
   private backpressuredClients: Set<FastifyReply> = new Set();
+  /** Latest already recipient-filtered legacy order frame awaiting a client's drain. */
+  private pendingSessionOrderFrames: Map<FastifyReply, string> = new Map();
+  /** Latest owner-filtered tab-layout invalidation per affected owner awaiting a client's drain. */
+  private pendingTabLayoutFrames: Map<FastifyReply, Map<string | symbol, string>> = new Map();
 
   // ─── Tunnel State ───────────────────────────────────────
   /** Cached tunnel active state — updated on TunnelStarted/TunnelStopped to avoid getUrl() on every broadcast */
@@ -144,10 +151,7 @@ export class SseStreamManager {
       // If a previous reply registered the same id (reconnect), drop the old one.
       const prev = this.sseClientsById.get(clientId);
       if (prev && prev !== reply) {
-        this.sseClients.delete(prev);
-        this.remoteSseClients.delete(prev);
-        this.backpressuredClients.delete(prev);
-        this.sseClientIdentity.delete(prev);
+        this.removeClient(prev);
       }
       this.sseClientsById.set(clientId, reply);
     }
@@ -157,6 +161,8 @@ export class SseStreamManager {
     this.sseClients.delete(reply);
     this.remoteSseClients.delete(reply);
     this.backpressuredClients.delete(reply);
+    this.pendingSessionOrderFrames.delete(reply);
+    this.pendingTabLayoutFrames.delete(reply);
     this.sseClientIdentity.delete(reply);
     // Clear any clientId mappings pointing at this reply
     for (const [id, r] of this.sseClientsById) {
@@ -199,8 +205,7 @@ export class SseStreamManager {
     try {
       reply.raw.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
     } catch {
-      this.sseClients.delete(reply);
-      this.remoteSseClients.delete(reply);
+      this.removeClient(reply);
     }
   }
 
@@ -210,7 +215,44 @@ export class SseStreamManager {
     try {
       reply.raw.write(SSE_PADDING);
     } catch {
-      /* client gone */
+      this.removeClient(reply);
+    }
+  }
+
+  private markBackpressured(reply: FastifyReply): void {
+    this.backpressuredClients.add(reply);
+    reply.raw.once('drain', () => this.flushBackpressuredClient(reply));
+  }
+
+  private flushBackpressuredClient(reply: FastifyReply): void {
+    if (!this.sseClients.has(reply)) return;
+    this.backpressuredClients.delete(reply);
+    try {
+      const drainPadding = this._isTunnelActive ? SSE_PADDING : '';
+      const recovered = reply.raw.write(`event: ${SseEvent.SessionNeedsRefresh}\ndata: {}\n\n${drainPadding}`);
+      if (!recovered) {
+        this.markBackpressured(reply);
+        return;
+      }
+      const pendingLayouts = this.pendingTabLayoutFrames.get(reply);
+      if (pendingLayouts) {
+        for (const [owner, pendingLayout] of pendingLayouts) {
+          pendingLayouts.delete(owner);
+          this.sendSSEPreformatted(reply, pendingLayout);
+          if (!this.sseClients.has(reply)) return;
+          if (this.backpressuredClients.has(reply)) {
+            if (pendingLayouts.size === 0) this.pendingTabLayoutFrames.delete(reply);
+            return;
+          }
+        }
+        this.pendingTabLayoutFrames.delete(reply);
+      }
+      const pendingOrder = this.pendingSessionOrderFrames.get(reply);
+      if (!pendingOrder) return;
+      this.pendingSessionOrderFrames.delete(reply);
+      this.sendSSEPreformatted(reply, pendingOrder);
+    } catch {
+      this.removeClient(reply);
     }
   }
 
@@ -224,24 +266,11 @@ export class SseStreamManager {
     try {
       const ok = reply.raw.write(message);
       if (!ok) {
-        // Buffer is full — mark as backpressured, resume on drain
-        this.backpressuredClients.add(reply);
-        reply.raw.once('drain', () => {
-          this.backpressuredClients.delete(reply);
-          // Client may have missed terminal data during backpressure.
-          // Tell it to reload the active session's buffer to recover.
-          try {
-            const drainPadding = this._isTunnelActive ? SSE_PADDING : '';
-            reply.raw.write(`event: ${SseEvent.SessionNeedsRefresh}\ndata: {}\n\n${drainPadding}`);
-          } catch {
-            /* client gone */
-          }
-        });
+        // Buffer is full — mark as backpressured, resume on drain.
+        this.markBackpressured(reply);
       }
     } catch {
-      this.sseClients.delete(reply);
-      this.remoteSseClients.delete(reply);
-      this.backpressuredClients.delete(reply);
+      this.removeClient(reply);
     }
   }
 
@@ -276,6 +305,36 @@ export class SseStreamManager {
     for (const [client] of this.sseClients) {
       // Multi-user ownership routing (no-op for identity-less single-user clients).
       if (!this.canDeliver(client, hint)) continue;
+      if (event === SseEvent.TabLayoutChanged && this.backpressuredClients.has(client)) {
+        const owner =
+          data !== null &&
+          typeof data === 'object' &&
+          Object.hasOwn(data, 'owner') &&
+          typeof (data as { owner?: unknown }).owner === 'string'
+            ? (data as { owner: string }).owner
+            : (hint?.username ?? hint?.owner ?? UNROUTED_TAB_LAYOUT);
+        let pending = this.pendingTabLayoutFrames.get(client);
+        if (!pending) {
+          pending = new Map();
+          this.pendingTabLayoutFrames.set(client, pending);
+        }
+        pending.set(owner, message);
+        continue;
+      }
+      this.sendSSEPreformatted(client, message);
+    }
+  }
+
+  /** Dispatch the legacy order projection selected from each trusted client identity. */
+  broadcastSessionOrder(change: SessionOrderProjectionChange): void {
+    for (const [client] of this.sseClients) {
+      const payload = sessionOrderPayloadFor(this.sseClientIdentity.get(client), change);
+      if (!payload) continue;
+      const message = `event: ${SseEvent.SessionOrderChanged}\ndata: ${JSON.stringify(payload)}\n\n`;
+      if (this.backpressuredClients.has(client)) {
+        this.pendingSessionOrderFrames.set(client, message);
+        continue;
+      }
       this.sendSSEPreformatted(client, message);
     }
   }
@@ -504,9 +563,7 @@ export class SseStreamManager {
 
     // Remove dead clients
     for (const client of deadClients) {
-      this.sseClients.delete(client);
-      this.remoteSseClients.delete(client);
-      this.backpressuredClients.delete(client);
+      this.removeClient(client);
     }
 
     if (deadClients.length > 0) {
@@ -553,6 +610,8 @@ export class SseStreamManager {
     this.sseClients.clear();
     this.remoteSseClients.clear();
     this.backpressuredClients.clear();
+    this.pendingSessionOrderFrames.clear();
+    this.pendingTabLayoutFrames.clear();
 
     // Clear per-session batch timers
     for (const timer of this.terminalBatchTimers.values()) {

src/web/tab-layout-sse.ts

@@ -0,0 +1,6 @@
+/** @fileoverview Trusted owner routing metadata for tab-layout invalidations. */
+import type { SseRoutingHint } from './sse-stream-manager.js';
+
+export function deriveTabLayoutSseHint(data: unknown): SseRoutingHint {
+  return { username: (data as { owner?: string }).owner, sessionScoped: true };
+}

test/agent-skill-mode-lists.test.ts

@@ -26,11 +26,20 @@
  *     external CLIs: those lists exist to describe what `isExternalCliMode()` gates
  *     (no Claude transcript, no hooks, no Claude-format parsers), so naming some but
  *     not all of them is the drift itself. Runs of one or two modes are exempt, since
- *     a legitimate pair ("claude or shell") is not a class claim. ONE exception is
- *     allowed and it is a real one: the "writes no transcript" lists drop `codex`,
- *     which does write a rollout Codeman reads back (the pane carries a unique
- *     originator precisely so `last-response` can find it), so external-minus-codex
- *     is a meaningful class rather than an oversight.
+ *     a legitimate pair ("claude or shell") is not a class claim. The exceptions are
+ *     the REAL classes inside the external family, each one a capability some of those
+ *     CLIs have and the rest do not:
+ *
+ *       - "writes no transcript" drops `codex` (a rollout Codeman reads back) and
+ *         `deepseek` (a JSONL session file Codeman reads back);
+ *       - "delivers no hook signals" drops `deepseek`, whose harness reports its own
+ *         lifecycle -- that one is derived from `hooksAvailableForMode()` rather than
+ *         restated, so the predicate and the prose cannot drift apart;
+ *       - the positive twin of the first: the modes whose answers CAN be read.
+ *
+ *     Anything else partial is still the drift. A NEW backend belongs to none of these
+ *     classes until someone says so, so every one of them grows by a mode and every
+ *     stale list fails here -- which is the whole point.
  *
  * Port: N/A (pure static analysis).
  */
@@ -41,6 +50,7 @@ import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { CreateSessionSchema, QuickStartSchema } from '../src/web/schemas.js';
 import { isExternalCliMode } from '../src/session.js';
+import { hooksAvailableForMode } from '../src/web/session-wait-registry.js';
 import type { SessionMode } from '../src/types/session.js';
 
 const HERE = fileURLToPath(new URL('.', import.meta.url));
@@ -63,6 +73,15 @@ function schemaModes(schema: typeof CreateSessionSchema | typeof QuickStartSchem
 const MODES = schemaModes(CreateSessionSchema);
 const EXTERNAL_MODES = MODES.filter(isExternalCliMode);
 
+/**
+ * External modes whose ANSWERS Codeman can read: codex from its rollout,
+ * deepseek from `$DSH_HOME/sessions/**`. Stated here rather than derived because
+ * `last-response` branches per mode into a per-CLI reader and there is no single
+ * predicate to import; the runtime facts are `readCodexLastResponse` and
+ * `readDeepSeekLastResponse` in session-routes.ts.
+ */
+const TRANSCRIPT_EXTERNAL_MODES = new Set<string>(['codex', 'deepseek']);
+
 /**
  * Mode tokens appearing back to back, separated only by list punctuation — `a|b|c`,
  * `a`/`b`/`c`, "`a`, `b` and `c`". Newlines collapse to spaces first so a wrapped list
@@ -109,9 +128,12 @@ describe('agent skill run-mode lists', () => {
 
   it('never enumerates a partial set of external CLI modes', () => {
     const complete = new Set<string>(EXTERNAL_MODES);
-    /** The documented exception: codex writes a rollout, so it is absent from the
-     *  "no transcript" lists on purpose. Every OTHER external mode must still be there. */
-    const withoutCodex = new Set<string>(EXTERNAL_MODES.filter((m) => m !== 'codex'));
+    // The real classes inside the family (see the fileoverview). Each is derived, so
+    // an eighth backend joins none of them and every list naming the other seven fails.
+    const noTranscript = new Set<string>(EXTERNAL_MODES.filter((m) => !TRANSCRIPT_EXTERNAL_MODES.has(m)));
+    const withTranscript = new Set<string>(EXTERNAL_MODES.filter((m) => TRANSCRIPT_EXTERNAL_MODES.has(m)));
+    const noHookSignals = new Set<string>(EXTERNAL_MODES.filter((m) => !hooksAvailableForMode(m)));
+    const allowed = [complete, noTranscript, withTranscript, noHookSignals];
     const sameSet = (a: Set<string>, b: Set<string>) => a.size === b.size && [...a].every((v) => b.has(v));
 
     const offenders: string[] = [];
@@ -121,7 +143,7 @@ describe('agent skill run-mode lists', () => {
         if (listed.length < 3) continue;
         const externals = new Set<string>(listed.filter(isExternalCliMode));
         // Empty is fine (a claude/shell-only list); partial is the drift.
-        if (externals.size === 0 || sameSet(externals, complete) || sameSet(externals, withoutCodex)) continue;
+        if (externals.size === 0 || allowed.some((set) => sameSet(externals, set))) continue;
         const missing = EXTERNAL_MODES.filter((m) => !externals.has(m));
         offenders.push(`${file}: "${run.trim()}" is missing ${missing.join(', ')}`);
       }

test/codex-plan-usage.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Main Codex subscription usage for the shared header chip.
+ *
+ * Codex can return multiple model buckets. The header deliberately follows the
+ * backward-compatible `codex` bucket only; model-specific buckets such as Spark
+ * are separate limits and are not part of the requested row.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import * as telemetryModule from '../src/usage-telemetry.js';
+import * as codexResolverModule from '../src/utils/codex-cli-resolver.js';
+
+const REAL_RESPONSE = {
+  rateLimits: {
+    limitId: 'codex',
+    primary: { usedPercent: 40, windowDurationMins: 10080, resetsAt: 1788306836 },
+    secondary: null,
+  },
+  rateLimitsByLimitId: {
+    codex_bengalfox: {
+      limitId: 'codex_bengalfox',
+      limitName: 'GPT-5.3-Codex-Spark',
+      primary: { usedPercent: 12, windowDurationMins: 300, resetsAt: 1787750984 },
+      secondary: { usedPercent: 23, windowDurationMins: 10080, resetsAt: 1788337784 },
+    },
+    codex: {
+      limitId: 'codex',
+      primary: { usedPercent: 40, windowDurationMins: 10080, resetsAt: 1788306836 },
+      secondary: null,
+    },
+  },
+};
+
+type ParseCodexRateLimits = (value: unknown) => {
+  fiveHour?: { usedPercentage: number; resetAt: number };
+  sevenDay?: { usedPercentage: number; resetAt: number };
+} | null;
+
+function parser(): ParseCodexRateLimits {
+  const candidate = (telemetryModule as Record<string, unknown>).parseCodexRateLimitsResponse;
+  expect(candidate, 'usage telemetry must expose the Codex rate-limit parser').toBeTypeOf('function');
+  return candidate as ParseCodexRateLimits;
+}
+
+describe('parseCodexRateLimitsResponse', () => {
+  it('uses only the main codex bucket and maps its duration-tagged weekly window', () => {
+    expect(parser()(REAL_RESPONSE)).toEqual({
+      sevenDay: { usedPercentage: 40, resetAt: 1788306836 * 1000 },
+    });
+  });
+
+  it('maps 5-hour and 7-day windows by duration even when their positions are reversed', () => {
+    const result = parser()({
+      rateLimitsByLimitId: {
+        codex: {
+          primary: { usedPercent: 44, windowDurationMins: 10080, resetsAt: 200 },
+          secondary: { usedPercent: 17, windowDurationMins: 300, resetsAt: 100 },
+        },
+      },
+    });
+
+    expect(result).toEqual({
+      fiveHour: { usedPercentage: 17, resetAt: 100_000 },
+      sevenDay: { usedPercentage: 44, resetAt: 200_000 },
+    });
+  });
+
+  it('falls back to the backward-compatible rateLimits snapshot', () => {
+    expect(
+      parser()({
+        rateLimits: {
+          limitId: 'codex',
+          primary: { usedPercent: 8, windowDurationMins: 300, resetsAt: 300 },
+          secondary: null,
+        },
+      })
+    ).toEqual({ fiveHour: { usedPercentage: 8, resetAt: 300_000 } });
+  });
+
+  it('ignores unrelated duration buckets and malformed percentages', () => {
+    expect(
+      parser()({
+        rateLimitsByLimitId: {
+          codex: {
+            primary: { usedPercent: '40', windowDurationMins: 10080, resetsAt: 200 },
+            secondary: { usedPercent: 20, windowDurationMins: 60, resetsAt: 100 },
+          },
+        },
+      })
+    ).toBeNull();
+  });
+});
+type CodexRequest = (
+  binaryPath: string,
+  clientVersion: string,
+  request?: (binaryPath: string, clientVersion: string) => Promise<unknown>
+) => Promise<ReturnType<ParseCodexRateLimits>>;
+
+describe('readCodexPlanUsage', () => {
+  it('queries through the supplied app-server boundary and normalizes the result', async () => {
+    const candidate = (codexResolverModule as Record<string, unknown>).readCodexPlanUsage;
+    expect(candidate, 'the Codex resolver must expose a read-only usage query').toBeTypeOf('function');
+    const request = vi.fn(async () => REAL_RESPONSE);
+
+    await expect((candidate as CodexRequest)('/opt/codex', '1.23.0', request)).resolves.toEqual({
+      sevenDay: { usedPercentage: 40, resetAt: 1788306836 * 1000 },
+    });
+    expect(request).toHaveBeenCalledWith('/opt/codex', '1.23.0');
+  });
+});

test/cron-service.test.ts

@@ -434,6 +434,46 @@ describe('CronService', () => {
   });
 
   describe('runNow', () => {
+    it('awaits layout insertion and stops lifecycle work when registration rejects', async () => {
+      const store = makeStore();
+      const sessions = new Map<string, FakeSession>();
+      let rejectRegistration!: (error: Error) => void;
+      const addSession = vi.fn(
+        () =>
+          new Promise<void>((_resolve, reject) => {
+            rejectRegistration = reject;
+          })
+      );
+      const persistSessionState = vi.fn();
+      const setupSessionListeners = vi.fn(async () => {});
+      const service = new CronService({
+        store,
+        sessions,
+        addSession,
+        persistSessionState,
+        setupSessionListeners,
+        broadcast: vi.fn(),
+        getGlobalNiceConfig: vi.fn(async () => undefined),
+        getModelConfig: vi.fn(async () => null),
+        getClaudeModeConfig: vi.fn(async () => ({})),
+        getCheckpointDefaultEnabled: vi.fn(async () => true),
+        mux: { backend: 'tmux' },
+      } as unknown as CronDeps);
+      const job = service.createJob(mkInput({ enabled: false }));
+
+      const pending = service.runNow(job.id);
+      await vi.waitFor(() => expect(addSession).toHaveBeenCalledTimes(1));
+      expect(persistSessionState).not.toHaveBeenCalled();
+      expect(setupSessionListeners).not.toHaveBeenCalled();
+
+      rejectRegistration(new Error('layout capacity exceeded'));
+      const run = await pending;
+      expect(run!.status).toBe('failed');
+      expect(run!.errorMessage).toMatch(/layout capacity exceeded/);
+      expect(persistSessionState).not.toHaveBeenCalled();
+      expect(setupSessionListeners).not.toHaveBeenCalled();
+    });
+
     it('launches regardless of enabled/schedule state', async () => {
       const job = svc.service.createJob(mkInput({ enabled: false }));
       const run = await svc.service.runNow(job.id);

test/deepseek-cli-resolver.test.ts

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Tests for the DeepSeek Harness (`dsh`) resolver and profile inventory.
+ *
+ * `dsh` needs the strictest identity probe of any CLI Codeman resolves. pi and
+ * grok are short names with npm squatters; `dsh` is worse — it is an EXISTING,
+ * widely packaged Unix program (Debian's dancer's shell, `apt install dsh`),
+ * which would sail through a version-token probe and then be handed a spawn
+ * line. So the resolver demands the harness's own help banner first, and the
+ * headline test below is the one that pins that rejection.
+ *
+ * The second half covers something no sibling resolver has: a profile
+ * inventory. `dsh` is a launcher, so "is it installed" and "can it run a
+ * session" are different questions, and the availability gate needs both.
+ */
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  createDeepSeekResolverForTest,
+  DEEPSEEK_VERSION_REGEX,
+  DEEPSEEK_IDENTITY_REGEX,
+  listDeepSeekProfiles,
+  resolveDefaultDeepSeekProfile,
+  isLaunchableProfile,
+  resolveDshHome,
+} from '../src/utils/deepseek-cli-resolver.js';
+import {
+  cliResolveRetryDelayMs,
+  createProductionCliResolverHost,
+  type CliResolverHost,
+} from '../src/utils/cli-executable-resolver.js';
+
+const temporaryDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function createHost(
+  options: {
+    processPathResult?: string | null;
+    loginShellResults?: Array<string | null>;
+    existingPaths?: string[];
+  } = {}
+): CliResolverHost {
+  const loginShellResults = [...(options.loginShellResults ?? [])];
+  const existingPaths = new Set(options.existingPaths ?? []);
+  return {
+    processPath: '/service/bin',
+    shellPath: '/bin/zsh',
+    shellArgs: ['-l'],
+    findOnProcessPath: () => options.processPathResult ?? null,
+    findInLoginShell: () => loginShellResults.shift() ?? null,
+    exists: (path) => existingPaths.has(path),
+  };
+}
+
+describe('DeepSeek CLI resolver', () => {
+  it('accepts a candidate the probe verifies and carries the version as metadata', () => {
+    const binaryPath = '/service/bin/dsh';
+    const probe = vi.fn(() => '0.1.1-rc.2');
+    const resolver = createDeepSeekResolverForTest(
+      createHost({ processPathResult: binaryPath, existingPaths: [binaryPath] }),
+      probe
+    );
+
+    expect(resolver.resolve()).toMatchObject({
+      binaryPath,
+      directory: '/service/bin',
+      source: 'process-path',
+      metadata: '0.1.1-rc.2',
+    });
+    expect(probe).toHaveBeenCalledWith(binaryPath);
+  });
+
+  it('does not let a foreign `dsh` earlier on PATH mask the real one', () => {
+    // The dancer's-shell case, at resolver level: a `dsh` that is a real program
+    // and answers --version must still be refused, and must not stop the search.
+    const impostor = '/usr/bin/dsh';
+    const genuine = '/login-shell/bin/dsh';
+    const probe = vi.fn((binPath: string) => (binPath === genuine ? '0.1.1-rc.2' : null));
+    const resolver = createDeepSeekResolverForTest(
+      createHost({
+        processPathResult: impostor,
+        loginShellResults: [genuine],
+        existingPaths: [impostor, genuine],
+      }),
+      probe
+    );
+
+    expect(resolver.resolve()).toMatchObject({ binaryPath: genuine, source: 'login-shell' });
+  });
+
+  it('negative-caches a miss and retries only after the backoff elapses', () => {
+    const binaryPath = '/late/bin/dsh';
+    let now = 0;
+    const probe = vi.fn(() => '0.1.1-rc.2');
+    const resolver = createDeepSeekResolverForTest(
+      createHost({ loginShellResults: [null, binaryPath], existingPaths: [binaryPath] }),
+      probe,
+      () => now
+    );
+
+    expect(resolver.resolve()).toBeNull();
+    expect(resolver.resolve()).toBeNull(); // within the backoff: no re-run
+    expect(probe).not.toHaveBeenCalled();
+    now = cliResolveRetryDelayMs(1);
+    expect(resolver.resolve()?.metadata).toBe('0.1.1-rc.2');
+  });
+
+  it('extracts the version from the real output shape (a bare `0.1.1-rc.2`)', () => {
+    // Shared with the dependency registry (doctor), so the accepted shape is
+    // contract. The prerelease tail is part of the token on purpose: dropping it
+    // would report a release candidate as a release.
+    expect(DEEPSEEK_VERSION_REGEX.exec('0.1.1-rc.2')?.[1]).toBe('0.1.1-rc.2');
+    expect(DEEPSEEK_VERSION_REGEX.exec('dsh 1.2.3')?.[1]).toBe('1.2.3');
+    expect(DEEPSEEK_VERSION_REGEX.exec('not a version')).toBeNull();
+  });
+
+  it('identifies the harness by its help banner and rejects a foreign dsh', () => {
+    expect(DEEPSEEK_IDENTITY_REGEX.test('dsh: boot a DeepSeek Harness profile — an ordered stack')).toBe(true);
+    // Debian's dancer's shell: a real program, a real version, not our agent.
+    expect(DEEPSEEK_IDENTITY_REGEX.test('Usage: dsh [options] [command] ...\nDistributed shell')).toBe(false);
+  });
+
+  it('never executes a dsh candidate under vitest (the ambient probe is VITEST-gated)', () => {
+    // A REAL executable fixture that answers BOTH probes convincingly. If the
+    // guard in probeDeepSeekVersion is ever removed, this script runs, the
+    // resolution SUCCEEDS, and this test fails — pinning hermeticity by
+    // behavior rather than by source text. That matters more here than for any
+    // sibling: `dsh` is a name real machines genuinely carry.
+    const root = mkdtempSync(join(tmpdir(), 'codeman-dsh-vitest-gate-'));
+    temporaryDirectories.push(root);
+    const binaryPath = join(root, 'dsh');
+    writeFileSync(
+      binaryPath,
+      '#!/bin/sh\ncase "$1" in --help) echo "dsh: boot a DeepSeek Harness profile";; *) echo "9.9.9";; esac\n'
+    );
+    chmodSync(binaryPath, 0o755);
+    const hostOptions = {
+      processPath: root,
+      shellPath: '/bin/bash',
+      shellArgs: ['-i', '-l'] as string[],
+      runCommand: () => '',
+      isExecutableFile: (path: string) => path === binaryPath,
+    };
+
+    const gated = createDeepSeekResolverForTest(createProductionCliResolverHost(hostOptions));
+    expect(gated.resolve()).toBeNull();
+
+    // Control: identical setup with an injected probe resolves, proving the null
+    // above comes from the gate, not from the fixture or the host.
+    const control = createDeepSeekResolverForTest(createProductionCliResolverHost(hostOptions), () => '9.9.9');
+    expect(control.resolve()).toMatchObject({ binaryPath, metadata: '9.9.9' });
+  });
+});
+
+describe('DeepSeek profile inventory', () => {
+  let home: string;
+  const ORIGINAL_DSH_HOME = process.env.DSH_HOME;
+
+  function writeProfile(name: string, bundles: string[]): void {
+    const dir = join(home, 'profiles', name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: `dsh-profile-${name}`, dsh: { profile: { bundles } } })
+    );
+  }
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'codeman-dsh-home-'));
+    temporaryDirectories.push(home);
+    process.env.DSH_HOME = home;
+  });
+
+  afterEach(() => {
+    if (ORIGINAL_DSH_HOME === undefined) delete process.env.DSH_HOME;
+    else process.env.DSH_HOME = ORIGINAL_DSH_HOME;
+  });
+
+  it('honours DSH_HOME over the default ~/.dsh', () => {
+    expect(resolveDshHome()).toBe(home);
+  });
+
+  it('is empty (not an error) when dsh has never been run', () => {
+    rmSync(home, { recursive: true, force: true });
+    expect(listDeepSeekProfiles()).toEqual([]);
+    expect(resolveDefaultDeepSeekProfile()).toBeNull();
+  });
+
+  it('classifies the profiles DeepSeek ships as unable to drive a pane', () => {
+    writeProfile('web', ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app']);
+    writeProfile('headless', ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless']);
+
+    const profiles = listDeepSeekProfiles();
+    expect(profiles.map((p) => `${p.name}:${p.kind}`).sort()).toEqual(['headless:headless', 'web:web']);
+    expect(profiles.every((p) => !isLaunchableProfile(p))).toBe(true);
+    // The whole point: a perfectly installed dsh with only the shipped profiles
+    // still cannot start a Codeman session.
+    expect(resolveDefaultDeepSeekProfile()).toBeNull();
+  });
+
+  it('prefers an interactive profile and ignores node_modules', () => {
+    writeProfile('web', ['@deepseek-ai/dsh-web-app']);
+    writeProfile('dsh-tui', ['@deepseek-ai/dsh-base', '@deepseek-harness-tui/dsh-tui']);
+    mkdirSync(join(home, 'profiles', 'node_modules', 'something'), { recursive: true });
+
+    const names = listDeepSeekProfiles().map((p) => p.name);
+    expect(names).not.toContain('node_modules');
+    expect(resolveDefaultDeepSeekProfile()).toBe('dsh-tui');
+  });
+
+  it('treats an unrecognized third-party profile as launchable', () => {
+    // Anyone can publish an app bundle, so an unknown profile must not be hidden
+    // from the picker just because this classifier has not heard of it.
+    writeProfile('custom', ['@someone/dsh-my-own-surface']);
+    const profile = listDeepSeekProfiles().find((p) => p.name === 'custom')!;
+    expect(profile.kind).toBe('unknown');
+    expect(isLaunchableProfile(profile)).toBe(true);
+    expect(resolveDefaultDeepSeekProfile()).toBe('custom');
+  });
+
+  it('does not treat a bundle-less stock profile as launchable', () => {
+    // readProfile() yields an empty bundle list for any package.json without a
+    // `dsh.profile.bundles` array (hand-edited, older layout, mid-install), and
+    // with no bundles to read the shipped web/headless profiles used to look
+    // exactly like an unrecognized third-party one — inheriting its
+    // launchable-by-default treatment and producing the pane-dies-on-arrival
+    // failure the two-part availability gate exists to prevent.
+    const bare = (name: string) => {
+      const dir = join(home, 'profiles', name);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: `dsh-profile-${name}` }));
+    };
+    bare('web');
+    bare('headless');
+
+    const profiles = listDeepSeekProfiles();
+    expect(profiles.map((p) => `${p.name}:${p.kind}`).sort()).toEqual(['headless:headless', 'web:web']);
+    expect(profiles.every((p) => !isLaunchableProfile(p))).toBe(true);
+    expect(resolveDefaultDeepSeekProfile()).toBeNull();
+  });
+
+  it('lets bundle evidence beat the name fallback', () => {
+    // The name check is a LAST resort, so a profile the user happened to call
+    // `web` that really composes a terminal app is still interactive. Otherwise
+    // a directory name would override what the profile actually contains.
+    writeProfile('web', ['@deepseek-ai/dsh-base', '@someone/dsh-tui']);
+    const profile = listDeepSeekProfiles().find((p) => p.name === 'web')!;
+    expect(profile.kind).toBe('interactive');
+    expect(resolveDefaultDeepSeekProfile()).toBe('web');
+  });
+
+  it('does not read `tui` out of the middle of an unrelated word', () => {
+    // The loose arm is a TOKEN match: `@someone/tui-app` is a TUI, `intuition`
+    // is a word. Being wrong is cheap (unknown is launchable too) but it decides
+    // which profile boots by DEFAULT, and "its name contains t-u-i" is not a
+    // rule anyone could predict.
+    writeProfile('intuition', ['@someone/gratuitous-surface']);
+    expect(listDeepSeekProfiles().find((p) => p.name === 'intuition')!.kind).toBe('unknown');
+
+    writeProfile('mine', ['@someone/tui-app']);
+    expect(listDeepSeekProfiles().find((p) => p.name === 'mine')!.kind).toBe('interactive');
+    // Preferred over the merely-unknown one, which is the whole point of ranking.
+    expect(resolveDefaultDeepSeekProfile()).toBe('mine');
+  });
+
+  it('survives a stray directory under profiles/', () => {
+    mkdirSync(join(home, 'profiles', 'not-a-profile'), { recursive: true });
+    writeProfile('dsh-tui', ['@deepseek-harness-tui/dsh-tui']);
+    expect(listDeepSeekProfiles().map((p) => p.name)).toEqual(['dsh-tui']);
+  });
+});

test/deepseek-mode.test.ts

@@ -0,0 +1,402 @@
+/**
+ * DeepSeek Harness (`dsh`) run mode.
+ *
+ * The interesting assertions here are the ones that differ from every sibling
+ * CLI, because dsh is shaped differently in two ways:
+ *
+ *  1. the agent is a PROFILE, not the binary, so the spawn line carries
+ *     `--profile <name>` and a profile name has to be treated as a path segment;
+ *  2. the permission switch is an ENV VAR (`DSH_PERMISSION_MODE`), not a flag,
+ *     so the thing to pin is that nothing permission-shaped ever reaches the
+ *     command line.
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { CreateSessionSchema, QuickStartSchema, HookEventSchema } from '../src/web/schemas.js';
+import { buildSpawnCommand } from '../src/tmux-manager.js';
+import { defaultDockerCommandForMode } from '../src/docker-hosts.js';
+import { defaultRemoteCommandForMode } from '../src/remote-hosts.js';
+import { isExternalCliMode, isAltScreenStripMode } from '../src/session.js';
+import { hooksAvailableForMode, resolveWaitSignals, sessionHookOptions } from '../src/web/session-wait-registry.js';
+import { _clampExternalCliBypassForOwner, _clampEnvOverridesForOwner } from '../src/web/routes/session-routes.js';
+import { DEEPSEEK_STATE_TO_HOOK_EVENT } from '../src/deepseek-status-shim.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+vi.mock('../src/utils/deepseek-cli-resolver.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/utils/deepseek-cli-resolver.js')>();
+  return { ...actual, resolveDefaultDeepSeekProfile: vi.fn(() => 'dsh-tui') };
+});
+
+describe('DeepSeek mode schemas', () => {
+  it('accepts DeepSeek session creation config', () => {
+    const parsed = CreateSessionSchema.parse({
+      workingDir: '/tmp',
+      mode: 'deepseek',
+      deepSeekConfig: { profile: 'dsh-tui', permissionMode: 'danger-full-access' },
+    });
+
+    expect(parsed.mode).toBe('deepseek');
+    expect(parsed.deepSeekConfig).toEqual({ profile: 'dsh-tui', permissionMode: 'danger-full-access' });
+  });
+
+  it('accepts DeepSeek quick-start config', () => {
+    const parsed = QuickStartSchema.parse({
+      caseName: 'dsh-case',
+      mode: 'deepseek',
+      deepSeekConfig: { resumeSessionId: 'sess_01H9', statusReporting: false },
+    });
+
+    expect(parsed.mode).toBe('deepseek');
+    expect(parsed.deepSeekConfig?.resumeSessionId).toBe('sess_01H9');
+    expect(parsed.deepSeekConfig?.statusReporting).toBe(false);
+  });
+
+  it('rejects a profile name that is not a single path segment', () => {
+    // A profile is BOTH interpolated into a `bash -c "…"` line and joined into a
+    // filesystem path under $DSH_HOME/profiles, so separators and traversal have
+    // to die at the schema boundary.
+    for (const profile of ['../../etc/passwd', 'a/b', './x', '-rf', 'has space', 'semi;colon']) {
+      expect(() =>
+        CreateSessionSchema.parse({ workingDir: '/tmp', mode: 'deepseek', deepSeekConfig: { profile } })
+      ).toThrow();
+    }
+  });
+
+  it('rejects an unknown permission preset', () => {
+    // The three presets are the harness's own; anything else would be exported
+    // verbatim as DSH_PERMISSION_MODE and silently fall back to its default.
+    expect(() =>
+      CreateSessionSchema.parse({
+        workingDir: '/tmp',
+        mode: 'deepseek',
+        deepSeekConfig: { permissionMode: 'yolo' },
+      })
+    ).toThrow();
+  });
+
+  it('rejects unsafe resumeSessionId values', () => {
+    expect(() =>
+      CreateSessionSchema.parse({
+        workingDir: '/tmp',
+        mode: 'deepseek',
+        deepSeekConfig: { resumeSessionId: '../../etc/passwd' },
+      })
+    ).toThrow();
+  });
+
+  it('allows DSH_* and DEEPSEEK_* env overrides but not a foreign provider key', () => {
+    const ok = CreateSessionSchema.parse({
+      workingDir: '/tmp',
+      mode: 'deepseek',
+      envOverrides: { DSH_HOME: '/tmp/dsh', DEEPSEEK_API_KEY: 'sk-test' },
+    });
+    expect(ok.envOverrides).toEqual({ DSH_HOME: '/tmp/dsh', DEEPSEEK_API_KEY: 'sk-test' });
+
+    // A dsh settings.yaml can name ANY env var as a provider credential
+    // (apiKeyEnv), which is pi's 34-provider-key problem in a new shape. The
+    // allowlist is global, so admitting them would widen every mode at once.
+    expect(() =>
+      CreateSessionSchema.parse({
+        workingDir: '/tmp',
+        mode: 'deepseek',
+        envOverrides: { QWEN5090_API_KEY: 'sk-test' },
+      })
+    ).toThrow();
+  });
+});
+
+describe('DeepSeek spawn command', () => {
+  it('boots the requested profile', () => {
+    const cmd = buildSpawnCommand({
+      mode: 'deepseek',
+      sessionId: 's1',
+      deepSeekConfig: { profile: 'dsh-tui' },
+    });
+    expect(cmd).toBe('dsh --profile dsh-tui');
+  });
+
+  it('falls back to the resolved default profile when none was requested', () => {
+    const cmd = buildSpawnCommand({ mode: 'deepseek', sessionId: 's1' });
+    expect(cmd).toBe('dsh --profile dsh-tui');
+  });
+
+  it('never puts anything permission-shaped on the command line', () => {
+    // The harness has NO permission flag: the switch is the DSH_PERMISSION_MODE
+    // env export, applied via `tmux setenv`. If this ever starts failing, someone
+    // has invented a flag that does not exist.
+    const cmd = buildSpawnCommand({
+      mode: 'deepseek',
+      sessionId: 's1',
+      deepSeekConfig: { profile: 'dsh-tui', permissionMode: 'danger-full-access' },
+    });
+    expect(cmd).toBe('dsh --profile dsh-tui');
+    expect(cmd).not.toMatch(/danger|approve|permission|yolo|dangerously/i);
+  });
+
+  it('prefers an explicit resume id over the most-recent form', () => {
+    const cmd = buildSpawnCommand({
+      mode: 'deepseek',
+      sessionId: 's1',
+      deepSeekConfig: { profile: 'p', resumeSession: true, resumeSessionId: 'sess_42' },
+    });
+    expect(cmd).toBe('dsh --profile p --resume sess_42');
+  });
+
+  it('resumes the most recent session when only the flag is set', () => {
+    const cmd = buildSpawnCommand({
+      mode: 'deepseek',
+      sessionId: 's1',
+      deepSeekConfig: { profile: 'p', resumeSession: true },
+    });
+    expect(cmd).toBe('dsh --profile p --resume');
+  });
+
+  it('drops an unsafe profile rather than interpolating it', () => {
+    // Defense in depth behind the schema: builders must not trust their callers,
+    // because this string is interpolated into a `bash -c "…"` argument.
+    const cmd = buildSpawnCommand({
+      mode: 'deepseek',
+      sessionId: 's1',
+      deepSeekConfig: { profile: 'evil; rm -rf /' },
+    });
+    expect(cmd).not.toContain('rm -rf');
+    expect(cmd).toBe('dsh --profile dsh-tui');
+  });
+});
+
+describe('DeepSeek mode wiring', () => {
+  it('is an external CLI mode', () => {
+    expect(isExternalCliMode('deepseek')).toBe(true);
+  });
+
+  it('is NOT an alt-screen strip mode', () => {
+    // The strip is for Ink-style repaint TUIs (claude/codex/gemini). A dsh
+    // terminal profile is a third-party fullscreen TUI, i.e. the opencode case.
+    expect(isAltScreenStripMode('deepseek')).toBe(false);
+  });
+
+  it('has default remote and docker commands', () => {
+    expect(defaultRemoteCommandForMode('deepseek')).toContain('dsh');
+    expect(defaultDockerCommandForMode('deepseek')).toBe('exec dsh');
+  });
+});
+
+describe('DeepSeek status bridge', () => {
+  it('is the only non-claude mode allowed to deliver hook signals', () => {
+    // Earned, not granted: the harness terminal front door REPORTS its state to
+    // a supervisor, so `stop` and `blocked` for a dsh session are definitive
+    // rather than inferred. Every other external CLI must keep failing this.
+    expect(hooksAvailableForMode('deepseek')).toBe(true);
+    expect(hooksAvailableForMode('claude')).toBe(true);
+    for (const mode of ['shell', 'opencode', 'codex', 'gemini', 'antigravity', 'pi', 'grok'] as const) {
+      expect(hooksAvailableForMode(mode)).toBe(false);
+    }
+  });
+
+  it('is a per-SESSION answer for deepseek: a disarmed status bridge emits nothing', () => {
+    // `statusReporting: false` is what stops _configureDeepSeek() exporting the
+    // HERDR_* triple, and the triple is the ONLY reason a dsh session posts hook
+    // events. Answering from the mode alone would accept `until=stop` on a
+    // session where nothing can ever send one, which is the exact
+    // infinite-wait-dressed-as-a-timeout this predicate exists to prevent.
+    expect(hooksAvailableForMode('deepseek', { deepSeekStatusReporting: false })).toBe(false);
+    expect(hooksAvailableForMode('deepseek', { deepSeekStatusReporting: true })).toBe(true);
+    // Not sent = ON, so an ordinary session is unaffected.
+    expect(hooksAvailableForMode('deepseek', {})).toBe(true);
+    expect(hooksAvailableForMode('deepseek', { deepSeekStatusReporting: undefined })).toBe(true);
+    // The flag is meaningless for every other mode and must not move them.
+    expect(hooksAvailableForMode('claude', { deepSeekStatusReporting: false })).toBe(true);
+    expect(hooksAvailableForMode('codex', { deepSeekStatusReporting: true })).toBe(false);
+  });
+
+  it('refuses an explicit stop/blocked on a dsh session whose bridge is off, and says why', () => {
+    const off = { mode: 'deepseek' as const, deepSeekStatusReporting: false };
+    const on = { mode: 'deepseek' as const };
+
+    expect(resolveWaitSignals('stop', on)).toEqual({ until: ['stop'], error: null });
+
+    const rejected = resolveWaitSignals('stop', off);
+    expect(rejected.until).toEqual([]);
+    // The generic "no Claude Code hooks" wording would send the caller hunting a
+    // bug that is really a setting they chose, so this arm names the setting.
+    expect(rejected.error).toContain('statusReporting');
+    expect(rejected.error).not.toContain('no Claude Code hooks');
+
+    // An OMITTED `until` must never 400: the hook-only signals are dropped from
+    // the default set instead, leaving the two that still work.
+    expect(resolveWaitSignals(undefined, off)).toEqual({ until: ['idle', 'exit'], error: null });
+    expect(resolveWaitSignals(undefined, on).until).toContain('stop');
+  });
+
+  it('refuses stop/blocked on a docker or remote dsh session, where the bridge cannot reach the harness', () => {
+    // `docker exec` does not carry the local tmux env into the container and the
+    // remote shell never sees the local `HERDR_*` setenv, so such a session can
+    // never post a hook event however statusReporting is set — accepting
+    // `until=stop` there burns the caller's whole timeout on every turn.
+    expect(hooksAvailableForMode('deepseek', { deepSeekBridgeUnreachable: true })).toBe(false);
+    const unreachable = { mode: 'deepseek' as const, deepSeekBridgeUnreachable: true };
+    const rejected = resolveWaitSignals('stop', unreachable);
+    expect(rejected.until).toEqual([]);
+    expect(rejected.error).toContain('container or on a remote host');
+    // The default set degrades instead of erroring, exactly like the disarmed case.
+    expect(resolveWaitSignals(undefined, unreachable)).toEqual({ until: ['idle', 'exit'], error: null });
+    // sessionHookOptions() is what lifts the fact off a live session.
+    expect(sessionHookOptions({ docker: { containerName: 'c' } }).deepSeekBridgeUnreachable).toBe(true);
+    expect(sessionHookOptions({ remote: { hostId: 'h' } }).deepSeekBridgeUnreachable).toBe(true);
+    expect(sessionHookOptions({}).deepSeekBridgeUnreachable).toBe(false);
+  });
+
+  it('keeps the hook predicate out of the two gates that mean "is this claude"', () => {
+    // Read My Mind and intent capture read Claude's own transcript, so they mean
+    // mode === 'claude'. They used to ask hooksAvailableForMode(), which was the
+    // same question until `deepseek` earned a yes and silently widened both to a
+    // mode with no transcript to read. Static, because the alternative is
+    // standing up a predictor and a transcript watcher to observe one `if`.
+    const rmm = readFileSync(join(process.cwd(), 'src/web/routes/readmymind-routes.ts'), 'utf-8');
+    expect(rmm).toContain("session.mode !== 'claude'");
+    // Comment lines dropped first: the comment above that `if` names the
+    // predicate in order to explain why it is NOT the one being called there.
+    const uncommented = (src: string) =>
+      src
+        .split('\n')
+        .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+        .join('\n');
+    expect(uncommented(rmm)).not.toMatch(/hooksAvailableForMode\(/);
+
+    const server = readFileSync(join(process.cwd(), 'src/web/server.ts'), 'utf-8');
+    expect(server).toContain("if (!session || session.mode !== 'claude') return;");
+  });
+
+  it('keeps the transcript reader off docker and remote-SSH sessions', () => {
+    // A docker case's harness writes its transcript inside the CONTAINER's
+    // ~/.dsh and a remote-SSH case's lives on the remote host, so the local
+    // reader would scan a $DSH_HOME that can never hold the file and return
+    // "nothing said yet" forever — starving an agent that polls the worker.
+    // Those sessions must keep the pane segmenter. Static, because standing up
+    // a docker/remote session in the unit harness is exactly what the tmux
+    // test-mode mocks exist to avoid.
+    const routes = readFileSync(join(process.cwd(), 'src/web/routes/session-routes.ts'), 'utf-8');
+    expect(routes).toMatch(/session\.mode === 'deepseek' && !session\.docker && !session\.remote/);
+  });
+
+  it('maps the harness lifecycle states onto real hook events', () => {
+    expect(DEEPSEEK_STATE_TO_HOOK_EVENT.idle).toBe('stop');
+    expect(DEEPSEEK_STATE_TO_HOOK_EVENT.blocked).toBe('permission_prompt');
+    expect(DEEPSEEK_STATE_TO_HOOK_EVENT.working).toBe('agent_working');
+    // Every mapped event must be one the hook endpoint actually accepts, or the
+    // bridge would post reports the schema silently rejects.
+    for (const event of Object.values(DEEPSEEK_STATE_TO_HOOK_EVENT)) {
+      expect(() => HookEventSchema.parse({ event, sessionId: 's1' })).not.toThrow();
+    }
+  });
+});
+
+describe('DeepSeek multi-user clamp', () => {
+  const ORIGINAL = process.env.CODEMAN_MULTIUSER;
+  beforeEach(() => {
+    process.env.CODEMAN_MULTIUSER = '1';
+  });
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = ORIGINAL;
+  });
+
+  it('clamps a sent danger-full-access down to workspace-write, not read-only', () => {
+    // The clamp removes PRIVILEGE; it must not also break the session's ability
+    // to edit its own workspace, which read-only would.
+    return _clampExternalCliBypassForOwner('nobody', undefined, undefined, undefined, undefined, undefined, {
+      permissionMode: 'danger-full-access',
+    }).then((out) => {
+      expect(out.deepSeekConfig?.permissionMode).toBe('workspace-write');
+    });
+  });
+
+  it('leaves an ABSENT config absent (the only-if-sent branch)', async () => {
+    // Omitting DSH_PERMISSION_MODE leaves the harness on its own workspace-write
+    // preset, which still asks — so there is nothing to materialize, unlike pi.
+    const out = await _clampExternalCliBypassForOwner(
+      'nobody',
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined
+    );
+    expect(out.deepSeekConfig).toBeUndefined();
+  });
+});
+
+describe('DeepSeek multi-user clamp: the env-var half', () => {
+  const ORIGINAL = process.env.CODEMAN_MULTIUSER;
+  beforeEach(() => {
+    process.env.CODEMAN_MULTIUSER = '1';
+  });
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = ORIGINAL;
+  });
+
+  it('strips DSH_PERMISSION_MODE, which would otherwise undo the config clamp on the same request', async () => {
+    // applyEnvOverrides() runs AFTER _configureDeepSeek() in tmux-manager, so an
+    // override sent alongside the config lands last and WINS. Clamping the config
+    // alone is therefore half a gate: this is the other half.
+    const out = await _clampEnvOverridesForOwner('nobody', {
+      DSH_PERMISSION_MODE: 'danger-full-access',
+      DSH_TELEMETRY_MODE: 'off',
+    });
+    expect(out).toEqual({ DSH_TELEMETRY_MODE: 'off' });
+  });
+
+  it('strips DSH_HOME, which points the launcher at a profile tree that executes at boot', async () => {
+    const out = await _clampEnvOverridesForOwner('nobody', { DSH_HOME: '/home/attacker/evil-dsh' });
+    expect(out).toEqual({});
+  });
+
+  it("strips DEEPSEEK_BASE_URL, which would aim the server's own forwarded API key at a foreign host", async () => {
+    // _configureDeepSeek() exports the SERVER's DEEPSEEK_API_KEY into every dsh
+    // pane, and applyEnvOverrides() lands after it — so a non-granted owner who
+    // could set the base URL would have the operator's key sent as a bearer
+    // credential to an endpoint of their choosing. Their OWN key stays settable:
+    // that removes privilege rather than granting it.
+    const out = await _clampEnvOverridesForOwner('nobody', {
+      DEEPSEEK_BASE_URL: 'https://attacker.example/v1',
+      DEEPSEEK_API_KEY: 'sk-their-own',
+    });
+    expect(out).toEqual({ DEEPSEEK_API_KEY: 'sk-their-own' });
+  });
+
+  it('leaves unrelated overrides alone, and returns the same object when there is nothing to strip', async () => {
+    const input = { DEEPSEEK_API_KEY: 'sk-test', CODEX_HOME: '/tmp/cx' };
+    const out = await _clampEnvOverridesForOwner('nobody', input);
+    expect(out).toBe(input);
+    expect(await _clampEnvOverridesForOwner('nobody', undefined)).toBeUndefined();
+  });
+
+  it('is a no-op in single-user mode', async () => {
+    delete process.env.CODEMAN_MULTIUSER;
+    const input = { DSH_PERMISSION_MODE: 'danger-full-access', DSH_HOME: '/opt/dsh' };
+    // canUsernameRunPrivilegedCommands() returns true when !isMultiUserMode(), so
+    // the single-user behaviour has to be byte-identical to before this clamp.
+    expect(await _clampEnvOverridesForOwner(undefined, input)).toBe(input);
+  });
+});
+
+describe('DeepSeek profile install is bounded for real', () => {
+  it('runs in its own process group and escalates the kill to the whole tree', () => {
+    // `dsh plugin add` fans out into package-manager resolver/build children, and
+    // spawn's own `timeout` signals only the direct child: survivors hold the
+    // inherited stdio pipes open, `close` never fires, and the held-open request
+    // leaks forever. Same failure and same fix as runGit() in git-clone.ts.
+    // Static, because reproducing it needs a real package manager that hangs.
+    const src = readFileSync(join(process.cwd(), 'src/web/routes/system-routes.ts'), 'utf-8');
+    const handler = src.slice(src.indexOf("app.post('/api/deepseek/install-profile'"));
+    const body = handler.slice(0, handler.indexOf('app.post(', 1) + 1 || handler.length);
+    expect(body).toContain('detached: true');
+    expect(body).toContain('process.kill(-child.pid, signal)');
+    expect(body).toContain("killTree('SIGTERM')");
+    expect(body).toContain("killTree('SIGKILL')");
+    // The built-in option is the thing that did NOT work here; it must not come back.
+    expect(body).not.toContain('timeout: DEEPSEEK_INSTALL_TIMEOUT_MS');
+  });
+});

test/deepseek-status-shim.test.ts

@@ -0,0 +1,207 @@
+/**
+ * The generated DeepSeek Harness status shim.
+ *
+ * This file is the one piece of DeepSeek's wiring that is neither TypeScript we
+ * typecheck nor a route we can `inject()` into: it is a script emitted as a
+ * string, dropped in the data dir, and executed by a third-party TUI as a
+ * SUBPROCESS. So the assertions here run it the way the harness does — a real
+ * `node` process, real argv, real env, against a real listener — rather than
+ * inspecting the source text.
+ *
+ * The exit codes are the contract's load-bearing half: the caller retries with
+ * backoff on any non-zero, so "cannot ever succeed" (unknown verb, unmapped
+ * state) must exit 0 or one typo becomes four HTTP requests per state change,
+ * forever.
+ */
+import { describe, expect, it, beforeEach, beforeAll, afterAll } from 'vitest';
+import { execFileSync, spawn } from 'node:child_process';
+import { createServer, type Server } from 'node:http';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  ensureDeepSeekStatusShim,
+  deepSeekStatusShimPath,
+  resetDeepSeekStatusShimForTest,
+  DEEPSEEK_STATE_TO_HOOK_EVENT,
+} from '../src/deepseek-status-shim.js';
+
+const PORT = 3251;
+
+describe('DeepSeek status shim: provisioning', () => {
+  beforeEach(() => {
+    resetDeepSeekStatusShimForTest();
+  });
+
+  it('writes an executable shim that node can actually parse', () => {
+    const path = ensureDeepSeekStatusShim();
+    expect(path).toBeTruthy();
+    expect(existsSync(path!)).toBe(true);
+    // 0700: the TUI execs it directly, so a lost exec bit means every report
+    // fails and is retried four times per state change.
+    expect(statSync(path!).mode & 0o777).toBe(0o700);
+    // `node --check` on the real file, because a template-literal typo in
+    // SHIM_SOURCE is invisible to tsc — the shim is a STRING as far as the
+    // compiler is concerned.
+    expect(() => execFileSync(process.execPath, ['--check', path!], { stdio: 'pipe' })).not.toThrow();
+  });
+
+  it('refreshes a shim written by an older Codeman, and leaves no temp file behind', () => {
+    const path = deepSeekStatusShimPath();
+    ensureDeepSeekStatusShim();
+    const current = readFileSync(path, 'utf-8');
+
+    // A v1 shim from an older install: right path, stale content.
+    writeFileSync(path, '#!/usr/bin/env node\n// codeman-dsh-status-shim v1\nprocess.exit(0)\n', { mode: 0o700 });
+    resetDeepSeekStatusShimForTest();
+    ensureDeepSeekStatusShim();
+
+    expect(readFileSync(path, 'utf-8')).toBe(current);
+    // The rewrite goes through a temp + rename so a TUI exec'ing this path mid
+    // refresh can never read a half-written file. The temp must not survive it.
+    const strays = readdirSync(dirname(path)).filter((f) => f.startsWith('dsh-status-shim') && f.endsWith('.tmp'));
+    expect(strays).toEqual([]);
+  });
+
+  it('re-asserts the exec bit even when the content already matches', () => {
+    const path = ensureDeepSeekStatusShim()!;
+    chmodSync(path, 0o600); // a restored backup / copied data dir
+    resetDeepSeekStatusShimForTest();
+    ensureDeepSeekStatusShim();
+    expect(statSync(path).mode & 0o777).toBe(0o700);
+  });
+});
+
+describe('DeepSeek status shim: the supervisor contract', () => {
+  let server: Server | undefined;
+  const received: Array<{ body: unknown; secret: string | undefined }> = [];
+  let status = 200;
+
+  const listen = () =>
+    new Promise<void>((resolve) => {
+      server = createServer((req, res) => {
+        let raw = '';
+        req.on('data', (c) => (raw += c));
+        req.on('end', () => {
+          received.push({
+            body: (() => {
+              try {
+                return JSON.parse(raw);
+              } catch {
+                return raw;
+              }
+            })(),
+            secret: req.headers['x-codeman-hook-secret'] as string | undefined,
+          });
+          res.writeHead(status, { 'Content-Type': 'application/json' });
+          res.end('{}');
+        });
+      });
+      server.listen(PORT, '127.0.0.1', resolve);
+    });
+
+  beforeAll(() => listen());
+
+  afterAll(() => {
+    server?.close();
+  });
+
+  /**
+   * Run the shim the way the TUI does, and ASYNCHRONOUSLY.
+   *
+   * Never spawnSync here: the listener above lives in this same process, so a
+   * synchronous spawn blocks the event loop that has to accept the connection.
+   * The shim then waits out its own 1500ms socket timeout and exits 1, which
+   * reads exactly like a broken shim (measured: `Socket._onTimeout` in its exit
+   * trace, and the server logging nothing).
+   */
+  const run = (args: string[], env: Record<string, string> = {}) =>
+    new Promise<{ status: number | null; stderr: string }>((resolve) => {
+      const path = ensureDeepSeekStatusShim()!;
+      const child = spawn(process.execPath, [path, ...args], {
+        env: {
+          ...process.env,
+          CODEMAN_API_URL: `http://127.0.0.1:${PORT}`,
+          CODEMAN_SESSION_ID: 'sess-from-env',
+          ...env,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let stderr = '';
+      child.stderr.on('data', (c: Buffer) => (stderr += c.toString('utf-8')));
+      child.on('close', (status) => resolve({ status, stderr }));
+    });
+
+  // The exact command line the harness TUI runs, from the Herdr contract.
+  const report = (state: string, extra: string[] = []) => [
+    'pane',
+    'report-agent',
+    'pane-arg-id',
+    '--source',
+    'custom:dsh-tui',
+    '--agent',
+    'dsh-tui',
+    '--state',
+    state,
+    ...extra,
+    '--seq',
+    '7',
+  ];
+
+  it('forwards each harness state as its mapped hook event, and exits 0 on delivery', async () => {
+    resetDeepSeekStatusShimForTest();
+    for (const [state, event] of Object.entries(DEEPSEEK_STATE_TO_HOOK_EVENT)) {
+      received.length = 0;
+      const out = await run(report(state, ['--message', 'needs a decision']));
+      expect(out.status, `${state}: ${out.stderr}`).toBe(0);
+      expect(received).toHaveLength(1);
+      const body = received[0].body as { event: string; sessionId: string; data: Record<string, unknown> };
+      expect(body.event).toBe(event);
+      // The ambient env wins over the pane argument: same code set both, and the
+      // argument is whatever the TUI chose to pass.
+      expect(body.sessionId).toBe('sess-from-env');
+      expect(body.data.agent).toBe('dsh-tui');
+      expect(body.data.message).toBe('needs a decision');
+    }
+  });
+
+  it('sends the hook secret read at EXECUTION time, so rotation needs no respawn', async () => {
+    resetDeepSeekStatusShimForTest();
+    const secretFile = `${deepSeekStatusShimPath()}.secret-fixture`;
+    writeFileSync(secretFile, 'rotated-secret\n', { mode: 0o600 });
+    received.length = 0;
+    const out = await run(report('idle'), { CODEMAN_HOOK_SECRET_FILE: secretFile });
+    expect(out.status).toBe(0);
+    expect(received[0].secret).toBe('rotated-secret');
+  });
+
+  it('exits 0 without posting for anything a retry could never fix', async () => {
+    resetDeepSeekStatusShimForTest();
+    for (const args of [
+      ['pane', 'list'], // unknown verb
+      ['something-else', 'report-agent', 'id', '--state', 'idle'], // unknown noun
+      [...report('rebooting')], // a state this bridge does not map
+      ['pane', 'report-agent', 'id'], // no --state at all
+    ]) {
+      received.length = 0;
+      const out = await run(args);
+      expect(out.status, `args ${args.join(' ')}`).toBe(0);
+      expect(received).toEqual([]);
+    }
+  });
+
+  it('exits non-zero when the post genuinely fails, so the caller retries', async () => {
+    resetDeepSeekStatusShimForTest();
+
+    // A rejecting server: transport worked, Codeman said no.
+    status = 500;
+    received.length = 0;
+    expect((await run(report('idle'))).status).not.toBe(0);
+    expect(received).toHaveLength(1);
+    status = 200;
+
+    // Nothing listening at all.
+    expect((await run(report('idle'), { CODEMAN_API_URL: 'http://127.0.0.1:1' })).status).not.toBe(0);
+    // No API url to post to.
+    expect((await run(report('idle'), { CODEMAN_API_URL: '' })).status).not.toBe(0);
+  });
+});

test/deepseek-transcript.test.ts

@@ -0,0 +1,395 @@
+/**
+ * Reading a DeepSeek Harness session transcript.
+ *
+ * Two of these assertions exist because the obvious implementation was measured
+ * to be wrong against real files:
+ *
+ * - dsh appends ONE ZSTD FRAME PER WRITE, and Node's `zlib` zstd decoder stops
+ *   at the first frame end. A 56-line transcript decoded as 1 line / 158 bytes,
+ *   which reads as "the worker never answered" rather than as an error. The
+ *   multi-frame fixtures below are the guard.
+ * - a fresh worker in a case directory that had been used before answered its
+ *   first `last-response` with the PREVIOUS session's reply. Session-to-
+ *   transcript pairing is therefore its own describe block.
+ */
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm, utimes } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import * as zlib from 'node:zlib';
+
+import {
+  decodeZstdFrames,
+  findDeepSeekTranscript,
+  parseDeepSeekTranscript,
+  readDeepSeekLastResponse,
+  resetDeepSeekTranscriptMemoForTest,
+  resolveDeepSeekHome,
+  zstdFrameRanges,
+  zstdSupported,
+} from '../src/deepseek-transcript.js';
+
+const zstdCompressSync = (zlib as unknown as { zstdCompressSync?: (b: Buffer) => Buffer }).zstdCompressSync;
+
+/** Compress each line into its own frame — exactly how dsh appends. */
+function framed(lines: string[]): Buffer {
+  if (!zstdCompressSync) throw new Error('zstd unavailable');
+  return Buffer.concat(lines.map((line) => zstdCompressSync(Buffer.from(`${line}\n`, 'utf8'))));
+}
+
+const sessionHeader = (cwd: string, createdAt: number, id = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee') =>
+  JSON.stringify({ type: 'session', version: 0, id, createdAt, cwd, delegationDepth: 0 });
+
+const userPrompt = (text: string) =>
+  JSON.stringify({
+    type: 'user/message',
+    data: { content: [{ type: 'text', text }], source: { kind: 'user' }, role: 'user' },
+  });
+
+const pluginContext = (text: string) =>
+  JSON.stringify({
+    type: 'user/message',
+    data: { content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' } },
+  });
+
+const assistantMessage = (text: string, turn = 1, step = 1, time = 1_700_000_000_000) =>
+  JSON.stringify({
+    type: 'assistant/message',
+    time,
+    data: { turn, step, message: { role: 'assistant', content: [{ type: 'text', text }] } },
+  });
+
+const turnEnd = (turn: number, reason: Record<string, unknown>, time = 1_700_000_000_001) =>
+  JSON.stringify({ type: 'turn/end', time, data: { turn, reason } });
+
+describe.skipIf(!zstdSupported())('zstd frame walking', () => {
+  it('decodes every frame, not just the first (the silent-truncation bug)', () => {
+    const lines = Array.from({ length: 40 }, (_, i) => JSON.stringify({ type: 'noise', seq: i }));
+    const buf = framed(lines);
+
+    // The one-shot decoder is what this module had to replace.
+    const oneShot = (zlib as unknown as { zstdDecompressSync?: (b: Buffer) => Buffer }).zstdDecompressSync!(buf);
+    expect(oneShot.toString('utf8').trim().split('\n')).toHaveLength(1);
+
+    expect(zstdFrameRanges(buf)).toHaveLength(40);
+    expect(decodeZstdFrames(buf).trim().split('\n')).toHaveLength(40);
+  });
+
+  it('round-trips a single-frame file', () => {
+    const buf = framed(['{"type":"session"}']);
+    expect(decodeZstdFrames(buf)).toBe('{"type":"session"}\n');
+  });
+
+  it('passes an uncompressed transcript straight through', () => {
+    const plain = Buffer.from('{"type":"session"}\n{"type":"turn/start"}\n', 'utf8');
+    expect(decodeZstdFrames(plain)).toBe('{"type":"session"}\n{"type":"turn/start"}\n');
+  });
+
+  it('keeps the whole frames before a torn tail instead of failing the read', () => {
+    const buf = framed(['{"a":1}', '{"b":2}', '{"c":3}']);
+    const torn = buf.subarray(0, buf.length - 4);
+    const decoded = decodeZstdFrames(torn);
+    expect(decoded).toContain('{"a":1}');
+    expect(decoded).toContain('{"b":2}');
+    expect(decoded).not.toContain('{"c":3}');
+  });
+
+  it('refuses to walk a buffer that is not zstd', () => {
+    expect(zstdFrameRanges(Buffer.from('not zstd at all', 'utf8'))).toEqual([]);
+  });
+});
+
+describe('parseDeepSeekTranscript', () => {
+  it('returns the last turn text and skips plugin-injected context', () => {
+    const raw = [
+      sessionHeader('/w', 1),
+      userPrompt('what is 2+2?'),
+      pluginContext('Current runtime context. This snapshot supersedes earlier snapshots.'),
+      assistantMessage('4.'),
+      turnEnd(1, { kind: 'completed' }),
+    ].join('\n');
+
+    const result = parseDeepSeekTranscript(raw, { blocks: true });
+    expect(result.text).toBe('4.');
+    expect(result.cwd).toBe('/w');
+    expect(result.blocks.filter((b) => b.kind === 'prompt').map((b) => b.text)).toEqual(['what is 2+2?']);
+    expect(result.blocks.some((b) => b.text.includes('runtime context'))).toBe(false);
+  });
+
+  it('drops a leaked reasoning prefix at the closing tag', () => {
+    const raw = [
+      sessionHeader('/w', 1),
+      assistantMessage('I should read the file first.</think>\n\nThe add function is wrong.'),
+      turnEnd(1, { kind: 'completed' }),
+    ].join('\n');
+    expect(parseDeepSeekTranscript(raw).text).toBe('The add function is wrong.');
+  });
+
+  it('renders tool calls and tool results as tool blocks', () => {
+    const raw = [
+      sessionHeader('/w', 1),
+      JSON.stringify({
+        type: 'assistant/message',
+        data: {
+          turn: 1,
+          step: 1,
+          message: {
+            role: 'assistant',
+            content: [
+              { type: 'text', text: 'Reading it.' },
+              { type: 'tool-call', id: 'c1', name: 'read', arguments: '{"file_path":"calc.py"}' },
+            ],
+          },
+        },
+      }),
+      JSON.stringify({
+        type: 'tool/result',
+        data: {
+          turn: 1,
+          step: 1,
+          message: {
+            content: [{ type: 'tool-result', toolCallId: 'c1', content: [{ type: 'text', text: 'def add' }] }],
+          },
+        },
+      }),
+      assistantMessage('It subtracts instead of adding.', 1, 2),
+      turnEnd(1, { kind: 'completed' }),
+    ].join('\n');
+
+    const result = parseDeepSeekTranscript(raw, { blocks: true });
+    expect(result.blocks.filter((b) => b.kind === 'tool').map((b) => b.text)).toEqual([
+      'read({"file_path":"calc.py"})',
+      'def add',
+    ]);
+    // Both steps of the turn read back, in order.
+    expect(result.text).toBe('Reading it.\n\nIt subtracts instead of adding.');
+  });
+
+  it('uses streamed deltas only for a step the model never finalized', () => {
+    const raw = [
+      sessionHeader('/w', 1),
+      JSON.stringify({
+        type: 'assistant/chunk',
+        data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'Par' } },
+      }),
+      JSON.stringify({
+        type: 'text-chunks',
+        seq: null,
+        data: { turn: 1, step: 1, index: 0, texts: ['is is ', 'the'] },
+      }),
+      JSON.stringify({
+        type: 'assistant/chunk',
+        data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: ' capital.' } },
+      }),
+    ].join('\n');
+    // Still streaming: the partial answer is readable.
+    expect(parseDeepSeekTranscript(raw).text).toBe('Paris is the capital.');
+
+    // Once finalized, the deltas must not be appended a second time.
+    const finalized = `${raw}\n${assistantMessage('Paris is the capital.')}\n${turnEnd(1, { kind: 'completed' })}`;
+    expect(parseDeepSeekTranscript(finalized).text).toBe('Paris is the capital.');
+  });
+
+  it('does not resurrect raw deltas for a step whose reply was all reasoning', () => {
+    // Measured on a real conversation: step 1 finalized as reasoning only, so
+    // its text stripped to '' and the (unstripped) deltas took its place,
+    // putting `</think>` and the monologue back in front of the caller.
+    const raw = [
+      sessionHeader('/w', 1),
+      JSON.stringify({
+        type: 'assistant/chunk',
+        data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: "I'll read the file.</think>\n\n" } },
+      }),
+      assistantMessage("I'll read the file.</think>\n\n", 1, 1),
+      assistantMessage('The add function is wrong.', 1, 2),
+      turnEnd(1, { kind: 'completed' }),
+    ].join('\n');
+    expect(parseDeepSeekTranscript(raw).text).toBe('The add function is wrong.');
+  });
+
+  it('answers a failed turn with its error rather than the previous turn text', () => {
+    const raw = [
+      sessionHeader('/w', 1),
+      assistantMessage('First answer.', 1),
+      turnEnd(1, { kind: 'completed' }),
+      turnEnd(2, { kind: 'error', error: { message: '400: model does not support tools', code: 'INVALID_REQUEST' } }),
+    ].join('\n');
+    expect(parseDeepSeekTranscript(raw).text).toBe('Turn error: 400: model does not support tools');
+  });
+
+  it('calls an early stop an ending, not an error, and keeps the text it did produce', () => {
+    const raw = [sessionHeader('/w', 1), assistantMessage('Most'), turnEnd(1, { kind: 'max-tokens' })].join('\n');
+    const result = parseDeepSeekTranscript(raw, { blocks: true });
+    expect(result.text).toBe('Most');
+    expect(result.blocks.map((b) => b.text)).toContain('Turn ended: max-tokens');
+  });
+
+  it('survives a torn last line', () => {
+    const raw = [sessionHeader('/w', 1), assistantMessage('Complete.'), '{"type":"turn/e'].join('\n');
+    expect(parseDeepSeekTranscript(raw).text).toBe('Complete.');
+  });
+
+  it('is empty for a session that has said nothing', () => {
+    expect(parseDeepSeekTranscript(sessionHeader('/w', 1)).text).toBe('');
+  });
+});
+
+describe('resolveDeepSeekHome', () => {
+  it('prefers the session override over the environment', () => {
+    const previous = process.env.DSH_HOME;
+    process.env.DSH_HOME = '/from-env';
+    try {
+      expect(resolveDeepSeekHome({ deepSeekHomeOverride: '/from-session' })).toBe('/from-session');
+      expect(resolveDeepSeekHome({})).toBe('/from-env');
+    } finally {
+      if (previous === undefined) delete process.env.DSH_HOME;
+      else process.env.DSH_HOME = previous;
+    }
+  });
+
+  it('falls back to ~/.dsh', () => {
+    const previous = process.env.DSH_HOME;
+    delete process.env.DSH_HOME;
+    try {
+      expect(resolveDeepSeekHome({})).toMatch(/\.dsh$/);
+    } finally {
+      if (previous !== undefined) process.env.DSH_HOME = previous;
+    }
+  });
+});
+
+describe.skipIf(!zstdSupported())('session-to-transcript pairing', () => {
+  let dshHome: string;
+  const workspace = '/home/tester/cases/worker-1';
+  const sessionStart = 1_800_000_000_000;
+
+  /** Write a transcript for `cwd`, created at `createdAt`, mtime `mtime`. */
+  async function writeTranscript(name: string, cwd: string, createdAt: number, mtime: number, answer?: string) {
+    const dir = join(dshHome, 'sessions', '--home-tester-cases-worker-1--', name);
+    await mkdir(dir, { recursive: true });
+    const lines = [sessionHeader(cwd, createdAt, name)];
+    if (answer) lines.push(assistantMessage(answer), turnEnd(1, { kind: 'completed' }));
+    const path = join(dir, 'session.jsonl.zstd');
+    await writeFile(path, framed(lines));
+    await utimes(path, new Date(mtime), new Date(mtime));
+    return path;
+  }
+
+  beforeAll(async () => {
+    dshHome = await mkdtemp(join(tmpdir(), 'dsh-home-'));
+  });
+  afterAll(async () => {
+    await rm(dshHome, { recursive: true, force: true });
+  });
+
+  it("never hands a fresh session its predecessor's answer", async () => {
+    await writeTranscript('older', workspace, sessionStart - 600_000, sessionStart - 590_000, 'stale answer');
+    const found = await findDeepSeekTranscript({ dshHome, workingDir: workspace, startedAt: sessionStart });
+    expect(found).toBeNull();
+
+    const result = await readDeepSeekLastResponse({
+      workingDir: workspace,
+      createdAt: sessionStart,
+      deepSeekHomeOverride: dshHome,
+    });
+    expect(result).not.toBeNull();
+    expect(result?.text).toBe('');
+  });
+
+  it('pairs on the boot window even when a sibling wrote more recently', async () => {
+    await writeTranscript('mine', workspace, sessionStart + 2_000, sessionStart + 2_000, 'my answer');
+    await writeTranscript('sibling', workspace, sessionStart + 300_000, sessionStart + 400_000, 'sibling answer');
+
+    const found = await findDeepSeekTranscript({ dshHome, workingDir: workspace, startedAt: sessionStart });
+    expect(found).toContain('/mine/');
+
+    const result = await readDeepSeekLastResponse({
+      workingDir: workspace,
+      createdAt: new Date(sessionStart),
+      deepSeekHomeOverride: dshHome,
+    });
+    expect(result?.text).toBe('my answer');
+  });
+
+  it('ignores a transcript recorded for another workspace', async () => {
+    const other = await mkdtemp(join(tmpdir(), 'dsh-home-'));
+    try {
+      const dir = join(other, 'sessions', '--home-tester-cases-worker-1--', 'foreign');
+      await mkdir(dir, { recursive: true });
+      await writeFile(
+        join(dir, 'session.jsonl.zstd'),
+        framed([sessionHeader('/somewhere/else', sessionStart + 1_000), assistantMessage('not yours')])
+      );
+      const found = await findDeepSeekTranscript({ dshHome: other, workingDir: workspace, startedAt: sessionStart });
+      expect(found).toBeNull();
+    } finally {
+      await rm(other, { recursive: true, force: true });
+    }
+  });
+
+  it('reads a transcript created later in the session (a /new conversation)', async () => {
+    const later = await mkdtemp(join(tmpdir(), 'dsh-home-'));
+    try {
+      const dir = join(later, 'sessions', '--home-tester-cases-worker-1--', 'after-new');
+      await mkdir(dir, { recursive: true });
+      await writeFile(
+        join(dir, 'session.jsonl.zstd'),
+        framed([
+          sessionHeader(workspace, sessionStart + 1_800_000),
+          assistantMessage('after /new'),
+          turnEnd(1, { kind: 'completed' }),
+        ])
+      );
+      const result = await readDeepSeekLastResponse({
+        workingDir: workspace,
+        createdAt: sessionStart,
+        deepSeekHomeOverride: later,
+      });
+      expect(result?.text).toBe('after /new');
+    } finally {
+      await rm(later, { recursive: true, force: true });
+    }
+  });
+
+  it('reports an unreadable home as empty, not as an error', async () => {
+    const result = await readDeepSeekLastResponse({
+      workingDir: workspace,
+      createdAt: sessionStart,
+      deepSeekHomeOverride: join(tmpdir(), 'dsh-home-that-does-not-exist'),
+    });
+    expect(result).toEqual({ text: '', timestamp: '', blocks: [] });
+  });
+
+  it('serves an unchanged transcript from the memo and re-reads when the stat moves', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'dsh-home-'));
+    try {
+      const dir = join(home, 'sessions', '--home-tester-cases-worker-1--', 'memo');
+      await mkdir(dir, { recursive: true });
+      const path = join(dir, 'session.jsonl');
+      const stamp = new Date(sessionStart + 1_000);
+      const read = () =>
+        readDeepSeekLastResponse({ workingDir: workspace, createdAt: sessionStart, deepSeekHomeOverride: home });
+      const body = (answer: string) =>
+        `${[sessionHeader(workspace, sessionStart + 1_000), assistantMessage(answer), turnEnd(1, { kind: 'completed' })].join('\n')}\n`;
+
+      resetDeepSeekTranscriptMemoForTest();
+      await writeFile(path, body('AAAA'));
+      await utimes(path, stamp, stamp);
+      expect((await read())?.text).toBe('AAAA');
+
+      // Same byte length, same forced mtime: indistinguishable from unchanged
+      // by stat, and deliberately served from the memo — the 1s/poll skill loop
+      // must not decode an unchanged file, and dsh only ever APPENDS, so a
+      // same-stat rewrite does not exist outside a test.
+      await writeFile(path, body('BBBB'));
+      await utimes(path, stamp, stamp);
+      expect((await read())?.text).toBe('AAAA');
+
+      // An append moves mtime (and normally size), which is the invalidation.
+      await utimes(path, new Date(sessionStart + 2_000), new Date(sessionStart + 2_000));
+      expect((await read())?.text).toBe('BBBB');
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});

test/deepseek-web-server.test.ts

@@ -0,0 +1,73 @@
+/**
+ * The background `dsh web` supervisor and the authority boundary in front of it.
+ *
+ * Two things here are worth pinning and neither is obvious from reading the
+ * module:
+ *
+ * 1. `authority` becomes an argv element of a spawned process (`--trusted-host
+ *    <authority>`). The spawn is an argv ARRAY so a shell can never see it, but
+ *    the schema is the layer that stops a value which is not a browser
+ *    authority at all from reaching the command line, and a regex is easy to
+ *    widen by accident.
+ * 2. The supervisor tracks at most ONE server. The status accessor is what every
+ *    caller reads to decide whether to start another, so "no server" must report
+ *    as absent rather than as a half-populated record.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import { DeepSeekWebStartSchema } from '../src/web/schemas.js';
+import { getDeepSeekWebStatus, resetDeepSeekWebForTest, stopDeepSeekWeb } from '../src/deepseek-web-server.js';
+
+describe('DeepSeekWebStartSchema: the authority reaching --trusted-host', () => {
+  it('accepts the authority shapes a browser can actually report', () => {
+    for (const authority of [
+      'localhost:3000',
+      '127.0.0.1:5013',
+      'tnode.tailf80371.ts.net:8444',
+      'codeman.example.com',
+      '[::1]:3000',
+      'host-with-dashes.local:80',
+    ]) {
+      expect(DeepSeekWebStartSchema.safeParse({ authority }).success, authority).toBe(true);
+    }
+  });
+
+  it('rejects values that are not an authority at all', () => {
+    for (const authority of [
+      '',
+      'http://localhost:3000', // a URL, not an authority
+      'localhost:3000 --trusted-host evil', // an embedded second argument
+      '-oProxyCommand=evil', // leading dash, readable as a flag
+      'localhost:3000/../path',
+      'local host:3000',
+      'user:pass@localhost:3000',
+      'a'.repeat(256),
+    ]) {
+      expect(DeepSeekWebStartSchema.safeParse({ authority }).success, authority).toBe(false);
+    }
+  });
+
+  it('is strict, so an unexpected field cannot ride along', () => {
+    expect(DeepSeekWebStartSchema.safeParse({ authority: 'localhost:3000', port: 1 }).success).toBe(false);
+  });
+
+  it('requires the field rather than defaulting it', () => {
+    // A guessed default would silently fence dsh's /api against the wrong
+    // origin, which presents as a dashboard whose every call 403s.
+    expect(DeepSeekWebStartSchema.safeParse({}).success).toBe(false);
+  });
+});
+
+describe('DeepSeek web supervisor: status', () => {
+  beforeEach(() => {
+    resetDeepSeekWebForTest();
+  });
+
+  it('reports absent as fully null, not a half-filled record', () => {
+    expect(getDeepSeekWebStatus()).toEqual({ running: false, port: null, url: null, authority: null });
+  });
+
+  it('stopping when nothing runs resolves rather than throwing', async () => {
+    await expect(stopDeepSeekWeb()).resolves.toBeUndefined();
+    expect(getDeepSeekWebStatus().running).toBe(false);
+  });
+});

test/file-browser-hidden.test.ts

@@ -38,7 +38,7 @@ interface FakeElement {
   textContent: string;
   classes: Set<string>;
   attrs: Record<string, string>;
-  classList: { toggle: (name: string, on: boolean) => void };
+  classList: { toggle: (name: string, on: boolean) => void; contains: (name: string) => boolean };
   setAttribute: (name: string, value: string) => void;
 }
 
@@ -55,6 +55,9 @@ function fakeElement(): FakeElement {
         if (on) classes.add(name);
         else classes.delete(name);
       },
+      contains(name: string) {
+        return classes.has(name);
+      },
     },
     setAttribute(name: string, value: string) {
       attrs[name] = value;
@@ -92,10 +95,12 @@ function loadPanel(store: Map<string, string> | null) {
   vm.runInContext(panelsJs, context, { filename: 'panels-ui.js' });
 
   const elements: Record<string, FakeElement> = {
+    fileBrowserPanel: fakeElement(),
     fileBrowserTree: fakeElement(),
     fileBrowserStatus: fakeElement(),
     fileBrowserHiddenBtn: fakeElement(),
   };
+  elements.fileBrowserPanel.classList.toggle('visible', true);
   const requests: string[] = [];
   const app = new CodemanApp() as Record<string, any>;
   app.$ = (id: string) => elements[id] ?? null;
@@ -149,10 +154,12 @@ describe('File Viewer show-hidden toggle', () => {
     const { app, requests } = loadPanel(store);
     await app.loadFileBrowser('sess-1');
     expect(requests[0]).toContain('showHidden=false');
+    const previousTreeEpoch = app._fileBrowserState.treeEpoch;
 
     await app.toggleFileBrowserHidden();
 
     expect(app.fileBrowserShowHidden).toBe(true);
+    expect(app._fileBrowserState.treeEpoch).toBe(previousTreeEpoch + 1);
     expect(requests).toHaveLength(2);
     expect(requests[1]).toContain('showHidden=true');
     expect(store.get(STORAGE_KEY)).toBe('1');