feat(models): offer Fable 5.1 in the model picker and task routing

Claude Code 2.1.258's baked-in model catalog carries `claude-fable-5-1`
("Fable 5.1", June 2026 cutoff), but App Settings only offered Fable 5, so
pinning it meant hand-editing a case's .claude/settings.local.json.

Fable 5.1 is added exactly the way Fable 5 already is: a base option carrying
`data-ctx="1"` plus its `[1m]` companion row. The card grid and the context
switch are built from those options, so this needs no settings-ui.js logic
change at all - the card appears with the "1M capable" badge, the switch stays
live for it, and base + switch compose back into `claude-fable-5-1[1m]`.
Both strings are accepted by the CLI's catalog (verified: neither warns
`unrecognized_model`, unlike a made-up id).

The four per-agent-type routing selects and Default-for-tasks get the plain
`claude-fable-5-1` value, matching how Fable 5 appears there.

Deliberately NOT claimed: that Fable 5.1's 1M window is what sets it apart.
The catalog marks BOTH fable entries `native_1m` with a 1e6 window, so a
picker that gave 5.1 an always-on window and left 5 switchable would be
drawing a distinction the models do not have.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BHZgohZC5TbetqgETDnAve

.changeset/46d20534.md

@@ -1,23 +0,0 @@
----
-"aicodeman": patch
----
-
-Clear every production-reachable npm advisory, and fix a service-worker caching regression the upgrade exposed.
-
-`npm audit` reported 20 advisories, but 16 were devDependencies-only (Remotion, Puppeteer, postcss, the eslint/tsx toolchain) and never reached anyone installing the package. Four reached production and are now resolved:
-
-- **`@fastify/static` 9.1.3 to 10.1.3** — GHSA-8pvw-jcv7-9cmj, authorization bypass via non-canonical URL paths. The advisory covers `<=10.1.1`, so the entire 9.x line is affected and the fix only exists on 10.x.
-- **`find-my-way` 9.6.0 to 9.8.0** — GHSA-c96f-x56v-gq3h (HTTP/2 DDoS). Not exploitable here since Codeman does not enable HTTP/2, fixed anyway.
-- **`fast-uri` 3.1.2 to 3.1.5** — GHSA-v2hh-gcrm-f6hx, host confusion via a literal backslash authority delimiter.
-- **`brace-expansion` to 5.0.9 / 1.1.18** — GHSA-3jxr-9vmj-r5cp, exponential-time expansion DoS.
-
-The last three were transitive and only needed a lockfile re-resolve; no `overrides` were added.
-
-The `@fastify/static` major changes the `setHeaders` callback's first argument from a Node `ServerResponse` to a `FastifyReply`, which required two fixes:
-
-- `res.setHeader()` became `reply.header()`. A v9-style body throws `TypeError: res.setHeader is not a function` from inside the plugin on every static request.
-- **That change also flips precedence, silently.** The callback used to write to the raw response and be overwritten by the route's staged reply headers; it now writes to the reply and wins instead. That handed `/sw.js` a year of `immutable` in place of the `no-cache, no-store` its route sets, which would pin a service worker on every client with no server-side way to recover. A route that already set `Cache-Control` now keeps it.
-
-`ws` also appears in `npm audit` but production is already on 8.21.0, outside the vulnerable range; the only affected copy is bundled under `@remotion/renderer` and is dev-only.
-
-Adds `test/static-cache-headers.test.ts`, which drives a real server and covers the caching contract that had no test at all, and moves the floors in `test/dependency-security.test.ts` up to the patched versions.

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.agents
+.claude
+.codex
+# `**/` matters: a .dockerignore pattern is matched against the WHOLE
+# context-relative path, so a bare `.env` excludes ONLY the root file and
+# `COPY . .` would bake docker/.env -- CODEMAN_PASSWORD and any provider API
+# keys -- into the published image at /opt/codeman/docker/.env (verified).
+**/.env
+**/.env.*
+!**/.env.example
+node_modules
+dist
+coverage
+out
+test-results
+tmp
+*.log

.gitignore

@@ -2,6 +2,9 @@
 .agents/
 skills-lock.json
 
+
+# In-session decision scratchpad (context-survival mechanism, not a deliverable)
+DECISIONS.md
 # Written by install.sh into end-user clones when setup finishes
 .install-complete
 
@@ -93,8 +96,6 @@ packages/gesture-control/.vite/
 # Claude Code plan tracking
 plan.json
 
-# Unfinished TUI (local development only)
-src/tui/
 .claude/
 media-assets/
 commands

AGENTS.md

@@ -2,7 +2,8 @@
 
 Canonical agent/contributor guidance for this repository lives in [CLAUDE.md](CLAUDE.md) —
 project structure, build/test/lint commands, code style, testing safety rules
-(never run the full suite inside a managed tmux session), security notes, and
+(`npm test` is the CI gate and is safe to run bare; the three excluded suites
+have their own runners), security notes, and
 the deployment workflow are all maintained there. Please read it before making
 changes, and keep it the single source of truth rather than duplicating
 sections here.

CHANGELOG.md

@@ -1,5 +1,318 @@
 # aicodeman
 
+## 1.24.4
+
+### Patch Changes
+
+- The Compose deployment image ships the Docker CLI instead of the whole Docker engine.
+
+  `docker/server.Dockerfile` installed Debian's `docker.io` to get a client for the mounted
+  host socket. That package is the full **engine**: even with `--no-install-recommends` it
+  pulls 15 packages including containerd, runc, dmsetup and iptables, none of which a
+  container that only talks to a socket can use. It also ships Docker 20.10.24, from 2023.
+
+  The CLI and the buildx plugin are now copied from the official `docker:29-cli` image
+  instead. Measured on the same `node:22-bookworm-slim` base: **266 MB → 108 MB**, a 158 MB
+  saving, with the current CLI (29.7.2) in place of a two-year-old one.
+
+  Verified by building the real image and running it: the binaries are static Go builds, so
+  they work on this glibc image even though they come from an Alpine one, and `docker
+--version`, `docker ps` and `docker build` all succeed against a mounted host socket as
+  the unprivileged runtime user. buildx is copied deliberately — `scripts/build-agent-image.mjs`
+  shells out to `docker build` and Codeman auto-builds the agent image on the first Docker
+  case, which without the plugin falls back to the classic builder Docker has deprecated.
+  `docker-compose` is not copied; Codeman never shells out to it.
+
+## 1.24.3
+
+### Patch Changes
+
+- Docker Compose deployment, and the plan-usage chip stops losing its 5-hour window.
+
+  **Run Codeman itself in a container** (#349, @opticon454). `docker/` now carries a
+  local-image Compose deployment: copy `docker/.env.example` to `docker/.env`, set
+  `CODEMAN_PASSWORD`, run `bash docker/Start-Codeman.sh`. Docker cases then start as
+  **sibling** containers through the mounted host socket rather than nested ones, which
+  inverts an assumption the bare-host path takes for granted: the daemon no longer shares
+  Codeman's filesystem, so a bind source that is valid inside Codeman means nothing to it.
+  `CODEMAN_DOCKER_HOST_HOME` translates sources under HOME into the daemon's namespace and
+  `CODEMAN_CASES_PATH` points the cases dir at a host-absolute bind mount, so a workspace
+  resolves to the same absolute path on both sides. `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1`
+  drops `--memory-swap` for hosts without swap accounting (`--memory` still applies) and
+  filters only that one kernel warning. Guides: `docs/docker-compose.md`, `docker/README.md`.
+
+  Three things were fixed while landing it:
+  - **`docker/.env` was being baked into the image.** A `.dockerignore` pattern matches the
+    whole context-relative path, so the bare `.env` line excluded only the root file while
+    `COPY . .` picked up `docker/.env` — the file the deployment's own README tells you to
+    fill with `CODEMAN_PASSWORD` and provider API keys — and left it at
+    `/opt/codeman/docker/.env`. Now excluded via `**/.env`, verified in both directions
+    against a real build context with a canary secret.
+  - **`codeman skill install --case <name>` could not find a case under Compose.**
+    `CODEMAN_CASES_PATH` moved the server's cases dir but not the CLI's, which still
+    hardcoded `~/codeman-cases`. Both now resolve through one place.
+  - **A Docker case handed its Claude conversation id to every other CLI.** `resumeOnStart`
+    seeded `dockerResumeId` from `lastClaudeSessionId` regardless of mode, and
+    `appendResumeFlag()` maps a resume id onto codex/gemini/pi/grok/deepseek/omp/antigravity.
+    This one is a plain master bug, unrelated to Compose.
+
+  **The plan-usage chip keeps its 5-hour slot.** It silently shrank from `5h 4% · 7d 52%`
+  to a lone `7d 52%`, which reads as half the feature breaking. Nothing was broken: Claude
+  Code ships `rate_limits.five_hour` "only while the API reports it and its resets_at has
+  not passed", so between 5-hour session windows the key simply leaves the statusline
+  payload. The slot now stays with a dimmed em dash and the tooltip says "no active session
+  window". Claude only — a missing Codex bucket means that plan has no such limit, so those
+  stay omitted.
+
+  ### Thanks
+  - @opticon454 for #349, and for a write-up that made an infrastructure PR quick to review
+
+## 1.24.2
+
+### Patch Changes
+
+- Fix every new claude session dying on Claude Code 2.1.252's rewritten folder-trust dialog.
+
+  That dialog used to offer `❯ 1. Yes, I trust this folder` / `2. No, exit`, so Codeman
+  answered it by pressing Enter on the highlighted default. 2.1.252 dropped the numbers,
+  reversed the options and highlights `No, exit`, so the same Enter now answers _exit_: a
+  session in any directory claude had not seen before died (`Pane is dead (status 1)`)
+  about six seconds after it started, before the agent ever drew a composer.
+  - `trustDialogNextKey()` (`src/session-trust-dialog.ts`) now reads the `❯` marker off
+    the rendered pane and returns ONE keystroke at a time: an arrow while the cursor is on
+    the wrong option, Enter only once the screen shows it on the trust option. A frame it
+    cannot read presses nothing. Both the 2.1.252 and the older numbered layout are
+    handled, and the direction is derived from the frame rather than assumed, so a further
+    reordering costs a repaint instead of a session.
+  - The scan schedules its own follow-up read. It had only ever run from the PTY data
+    handler, which was enough while one Enter answered the dialog; the arrow that moves the
+    cursor is the last output the pane produces, so a two-keystroke answer would otherwise
+    stall with the cursor sitting on the right option forever. The keystroke cap goes from
+    3 to 6 for the same reason.
+  - The bundled `codeman` agent skill gets the same treatment (preamble 1.21.0): its
+    `_accept_trust` fallback reads `terminal?full=1`, steers onto the trust option and
+    confirms only after re-reading, instead of posting a blind `\r`. It sends those
+    keystrokes under its own `clientId`, because input sequence numbers are monotonic per
+    client and spending prompt numbers on dialog keys would make the next send-and-wait
+    look like a stale duplicate and vanish silently.
+  - Readiness recipes in `docs/extending-codeman.md`, `docs/api-reference.md` and the
+    skill's own reference carry the corrected answer and a new symptom-table entry for a
+    worker whose pane is dead seconds after the spawn.
+
+  Also included: a CLAUDE.md audit against the tree, correcting counted drift (route
+  modules, handler counts, frontend module count and app.js size, install.sh size) and
+  documenting several subsystems that had no entry.
+
+## 1.24.1
+
+### Patch Changes
+
+- The Docker agent base image builds again.
+
+  **`docker/agent.Dockerfile` could not be built from a fresh checkout** (#352, fix in #350): the DeepSeek Harness step died with `dsh: pnpm not found on PATH` and exit 127, which took the whole image with it and, because Codeman auto-builds this image on the first Docker case, left Docker mode unusable on a clean host. `dsh plugin` does not bundle a package manager; it spawns a literal `pnpm` with no npm fallback, so pnpm is now installed alongside `dsh` and the layer proves it with `pnpm --version`.
+
+  The profile install also passes `--config.dangerouslyAllowAllBuilds=true`, because pnpm, unlike npm, refuses dependency lifecycle scripts by default and fails the install over it (`ERR_PNPM_IGNORED_BUILDS`, exit 1). Which packages that hits moves between rebuilds, since the terminal profile is resolved by dist-tag rather than pinned: the tree that broke the build in August pulled `@google/genai`, today's does not. An allowlist of those names would have gone stale rather than prevented the next break, and running those scripts is the same exposure the image already accepts three layers up, where `npm install -g` runs the install scripts of every transitive dependency of the five CLIs above it with no gate at all.
+
+  Documentation caught up with two things it had wrong: the image smoke test in `docs/docker-cases.md` now covers `dsh` and `omp`, and checks the dsh **profile** rather than only the binary (`dsh` is a launcher, so `dsh --version` says nothing about whether a session can start), and `docs/deepseek-integration.md` names pnpm as a prerequisite for installing a terminal profile at all, by hand or through the UI button. A comment in the `/api/deepseek/install-profile` route claimed the opposite of what this bug proved, and is corrected; the route's behaviour was already right, surfacing dsh's own "pnpm not found on PATH" line as the install error.
+
+  ### Thanks
+  - @opticon454 for #350, with a reproduction that made this a confirmation rather than a hunt
+  - @timkjr for reporting #352, and for finding it while verifying Docker support for someone else's PR
+
+## 1.24.0
+
+### Minor Changes
+
+- OMP (Oh My Pi) as a tenth run mode, mode-faithful Resume for external CLIs, and a cleaner plan-usage chip.
+
+  **OMP (`omp`) run mode** (#353): Oh My Pi joins Claude Code, shell, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build and DeepSeek Harness as a run mode, in local, Docker and remote-SSH sessions: toolbar dropdown, welcome button, phone overview, command palette, clone-repo brain picker, cron agent types, tab badges and per-mode colours, plus `GET /api/omp/status`, a `codeman doctor` entry, install.sh detection and the docker agent image. The resolver leads with `~/.local/bin` (the upstream installer's real target) and demands `omp/<semver>` from `--version`, so an unrelated binary with the same three-letter name is never spawned. Past omp conversations appear in Past Sessions, read from omp's own session files (the header line carries the real working directory, so nothing has to reverse-engineer omp's directory mangling), and a respawned or resumed omp session is pinned to an exact conversation with `--resume <id>` instead of omp's newest-file `--continue`. Review hardening before merge: the pin is resolved only at the moment a respawn is actually confirmed (an eager resolve on boot recovery used to alias two omp tabs in one case directory onto one conversation), candidates are verified against their own header `cwd` and claimed process-wide so siblings cannot double-pin; `OMP_*` joins the env-override allowlist and `OMP_AUTH_BROKER_URL`/`OMP_AUTH_BROKER_TOKEN` are clamped for non-granted owners in multi-user mode, the same shape as `DEEPSEEK_BASE_URL`. Known and documented: omp's own knobs are mostly `PI_*` (it is a pi fork), its default `tools.approvalMode` is `yolo`, and in-container `--resume` pinning does not reach a Docker omp pane.
+
+  **Resume keeps the row's own CLI** (#353): clicking Resume on an OpenCode, Pi, Grok, DeepSeek or OMP row used to create a plain Claude session, since the create request never carried the row's mode. Resume now relaunches in the row's own mode with that CLI's continue flag, and retires the stale row it came from so three clicks no longer leave three copies of the same name. Codex, Gemini and Antigravity rows have no continuation wired yet, so their rows are deliberately left in place. `DELETE /api/sessions/:id` accepts a persisted-only session (ownership enforced through the same helper as live lookups, 404 rather than 403 so nothing leaks) and broadcasts `session_deleted` so other tabs drop the row too.
+
+  **Plan-usage chip drops the provider label when there is only one**: a machine with only Claude limits rendered `CLAUDE 5H 60% 7D 23%`, a 46px label naming the only thing it could be. The name exists to tell two rows apart, so it now appears only when both Claude and Codex have windows; the tooltip still names the provider either way.
+
+  ### Thanks
+  - @timkjr for #353, and for turning every review finding around within a day
+
+## 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
+
+- **`codeman tui`: a terminal dashboard for your sessions.** For the times you are in SSH or Termius instead of a browser. The web UI remains the primary surface and bare `codeman` still prints help, so the dashboard itself is strictly additive.
+
+  Sessions are grouped NEEDS YOU / WORKING / IDLE / RECENT in the same status language as the web tabs and the phone overview, and the states come from the server (hooks, idle confirmation, the approvals inbox) over the existing HTTP/SSE API rather than being screen-scraped. That is what lets the dashboard answer a permission dialog instead of only reporting one.
+  - `↑↓`/`j`/`k` select; `1`-`9`, `[`/`]` and `Tab` switch between sessions
+  - `Enter` attaches and hands the terminal to tmux; **`F1` comes back**, one key, no modifier. Inside the pane a bar across the top carries the session strip and `Alt+1`..`Alt+9` switch without returning to the dashboard first
+  - `Enter` on a RECENT row resumes that conversation; on a session whose pane has died it refuses and offers `r` to resume it in a fresh pane
+  - `y`/`n`/digits answer the selected session's pending permission or question card (the server re-captures the pane first, so a keystroke can never land in the composer)
+  - `p` sends a one-line prompt without attaching, `x` kills (`y` confirms), `n` starts a session and opens straight into it
+  - `/` cross-session search, `g` away digest, `?` help, live preview pane, plan-usage chip in the header, a terminal bell when a new approval arrives
+  - `codeman tui --list` and `codeman tui <n>` are scriptable fast paths; with no server running it lists panes straight from the instance's tmux socket, attach-only, and upgrades live when the server comes back
+
+  Narrow terminals (under 72 columns, a phone SSH client) drop the preview and get a single-column layout. `NO_COLOR`, non-UTF-8 glyph fallback and a non-TTY refusal are all handled. Zero new dependencies: hand-rolled ANSI over chalk and commander. User guide: `docs/tui.md`.
+
+  **Breaking: the `sc` tmux chooser is retired.** `scripts/tmux-chooser.sh` is deleted and `install.sh` no longer creates the `tmux-chooser` symlink or the `sc` alias; it sweeps both up instead, on update and on uninstall. `codeman tui` replaces it and does the job better: `sc` numbered its entries globally but only accepted a single `[1-9]` keypress, so sessions 10+ were listed and could not be selected, and it inferred nothing about what an agent was doing. The alias cleanup is marker-owned, matching the exact line the installer wrote, so a user's own `alias sc=` for another tool is untouched.
+
+  **CLI polish that came with it.**
+  - New shared style kit (`src/cli-style.ts`) used across the CLI: semantic palette, glyphs, width-aware table, spinner, confirm.
+  - `codeman doctor` is colorized and its table is measured, so the "Antigravity CLI" label no longer pushes its row out of column. `--json` output is unchanged.
+  - `codeman web` no longer prints its "running at" line twice, and the server's non-loopback security warning is painted like the CLI's (chalk degrades off a TTY, so journald and `web.log` stay free of escape codes).
+  - Spinners on the silent up-to-30s waits in `codeman web -d`, `codeman web --stop` and `codeman service install`.
+  - `codeman reset` asks a real y/N confirmation on a TTY; non-interactive callers keep the old `--force` refusal.
+  - `codeman list` and `codeman session list` share one renderer instead of drifting copies.
+  - `codeman attach` is described correctly in the README (it shows an attachment card for a local file).
+  - `test/cli-commands.test.ts` now derives its inventory from the real commander program instead of a hand-written fixture that had drifted.
+
+  **Internal.** New `tmux -L` callers resolve the socket through `resolveTmuxSocketName()`, now exported from `config/instance.ts`, so a second process can never point a beta instance at prod's panes. CLAUDE.md and `docs/architecture-invariants.md` both record the rule.
+
+  ### Thanks
+
+  The TUI went through seven rounds of beta testing over PuTTY/SSH by **@Ark0N**, which is where the way out of an attach, the session strip, the preview repaint handling and the glyph set all came from.
+
+## 1.20.1
+
+### Patch Changes
+
+- Terminal input and scrollback fixes (PRs #327, #331):
+  - IME punctuation preserved (#327): keyCode 229 / `Process` key events are now delegated to xterm's CompositionHelper instead of being suppressed, so an active Chinese IME committing numbers and full-width punctuation (，。！？ and friends) reaches the terminal correctly. The CJK input field sends the browser's committed text instead of guessing from `KeyboardEvent.key`, and the redundant Android orphan-input fallback is removed so xterm is the single input owner.
+  - Shell history replay bounded (#331): selecting a Shell session loads a bounded 1 MiB tail instead of replaying the entire multi-megabyte tmux scrollback on xterm's main thread; full history stays available via the explicit "Load full history" action. tmux history limits now apply correctly on both legacy tmux (global default set in the same command queue before pane creation) and tmux 3.7+ (per-pane targeting that never resizes or trims unrelated live panes). Also adds `Server-Timing` and `[TERMINAL-PERF]` timing stages for terminal loads, fixes `scrollToLastNonEmptyLine` double-counting scrollback rows, and keeps live output ordered behind snapshot replays.
+
+  ### Thanks
+  - @dignfei for both fixes: the IME punctuation root-cause fix (#327) and the bounded shell history replay with the tmux history-limit correctness work (#331).
+
+## 1.20.0
+
+### Minor Changes
+
+- Response viewer for OpenCode, Gemini, Antigravity and Pi sessions (#326). External CLIs render their own TUIs, so the viewer used to come up empty for them; a new transcript parser (`response-viewer-transcript.ts`) reconstructs the conversation from the pane text instead, and the `?context=full` view now tags every block with a role so prompts render as "You" and agent output as the assistant. The divider normalizer was rewritten as a linear scan after review found catastrophic backtracking on agent-controlled input (minutes of stall on a long dash run), with an equivalence corpus pinning the old accept set.
+
+  CLIs installed via nvm or Homebrew are now found when Codeman runs as a service (#329). A shared resolver falls back to a login-shell probe when the direct PATH lookup misses, so systemd and LaunchAgent installs no longer report every CLI as missing. Review hardening on top: a failed resolution is negative-cached with doubling backoff instead of re-spawning a login shell on every request, all probes pass `killSignal: 'SIGKILL'` (interactive bash shrugs off SIGTERM, and a blocking `.bash_profile` could have hung the server indefinitely), the resolvers are inert under vitest again so test suites cannot execute binaries found on the dev box, and the improved not-found guidance is wired into both the session-create errors and the per-CLI status endpoints.
+
+  `GET /api/system/repo-status` reports branch, upstream, ahead/behind and remote reachability for git-clone installs (#328). Review hardening: the git network calls moved off the synchronous path onto a single-flight 45s cache (one slow remote could previously freeze the whole server for up to a minute per request), remote URLs and git stderr are credential-redacted before they leave the server, the spawns use the same non-interactive git env as the clone path, and a local-branch upstream no longer parses into garbage.
+
+  Auto Copy for the terminal (#325, opt-in, per-device): a finished selection (mouse drag, double or triple click, or a phone long-press) lands on the clipboard by itself, so select-then-copy becomes select. Alongside it, hand-encoded tap reports are now gated on the server-observed `cliMouseTracking` state, so a pane that has fallen back to a plain shell no longer receives `[<0;88;20M` junk on tap.
+
+  The Ralph loop no longer stops polling after two ticks (#330): the reschedule guard read a stale timer handle that the timer callback never cleared, so the loop silently died while its status stayed `running`. The handle is now nulled as the callback's first statement, and a regression test pins the bug.
+
+  The red "needs you" tab alert clears when a dialog is answered in the terminal instead of surviving until the end of the turn: the post-hook re-capture could erase the parsed dialog options that the staleness sweep relies on (`applyCapture` is now add-only for options), and a delayed staleness pass now runs while a page is open. The unreachable `copyTerminal()` was removed, closing out #322.
+
+  ### Thanks
+  - @aakhter contributed the external-CLI response viewer (#326), the repo-status endpoint (#328), the login-shell CLI resolution (#329) and the Ralph reschedule fix (#330)
+  - @rounakdatta reported the mobile copy gap (#322) closed out in this release
+
+## 1.19.7
+
+### Patch Changes
+
+- Mobile catches up: links open from a tap, terminal text can be selected and copied, long prompts stay visible while you type. Plus Files panel search, a bundled Nerd Font symbols fallback, and a per-device terminal font setting.
+  - **Terminal and chat links work on phones** (#321): tapping a URL or file path in terminal output now opens it (new tab, file preview, or log viewer), resolved through the same provider desktop hover uses, so tap and click can never disagree about what is a link. Dialog rows and the composer keep their existing meaning. Response-viewer links open in a new tab with `rel="noopener noreferrer"` instead of navigating the dashboard away. Wrapped links open whole: the logical-line reconstruction now stitches hard wraps through the indent their continuation carries, which also fixes desktop hover-click truncating wrapped URLs.
+  - **Terminal text can be copied on touch devices** (#321): long-press selects the token under the finger, drag or tap the other end to extend, and a small bar offers Copy, Line (the whole logical line, wraps included) and dismiss. Copy works on plain-HTTP installs too. Three guards keep the keyboard down and the selection alive through the browser's own long-press handling.
+  - **A long prompt stays visible on phones** (#321): the local-echo overlay grows upward once it would run past the last visible row (a prompt taller than the screen keeps its tail, where the cursor is), and the keyboard-driven padding shrink can no longer reclaim the space the fixed toolbar and accessory bar stand in.
+  - **Files panel search** (#324): `GET /api/sessions/:id/files?q=...` answers a flat match list (name or path substring, `*`/`?` globs), recursing past non-matching directories with its own match cap on top of the existing bounds; without `q` the response is byte-identical to before. Glob queries are matched without regex so a pathological pattern cannot stall the server.
+  - **Nerd Font prompt glyphs out of the box, custom terminal font** (#320): a bundled icons-only Symbols Nerd Font Mono fallback renders powerlevel10k/starship/oh-my-posh glyphs on every device with no font install, and App Settings gains a per-device terminal font family that is prepended to the built-in stack.
+
+  ### Thanks
+
+  Three contributor PRs in one release: thanks to @rounakdatta (#321), @aakhter (#324) and @comzine (#320).
+
+- 8a54b33: Clear every production-reachable npm advisory, and fix a service-worker caching regression the upgrade exposed.
+
+  `npm audit` reported 20 advisories, but 16 were devDependencies-only (Remotion, Puppeteer, postcss, the eslint/tsx toolchain) and never reached anyone installing the package. Four reached production and are now resolved:
+  - **`@fastify/static` 9.1.3 to 10.1.3** — GHSA-8pvw-jcv7-9cmj, authorization bypass via non-canonical URL paths. The advisory covers `<=10.1.1`, so the entire 9.x line is affected and the fix only exists on 10.x.
+  - **`find-my-way` 9.6.0 to 9.8.0** — GHSA-c96f-x56v-gq3h (HTTP/2 DDoS). Not exploitable here since Codeman does not enable HTTP/2, fixed anyway.
+  - **`fast-uri` 3.1.2 to 3.1.5** — GHSA-v2hh-gcrm-f6hx, host confusion via a literal backslash authority delimiter.
+  - **`brace-expansion` to 5.0.9 / 1.1.18** — GHSA-3jxr-9vmj-r5cp, exponential-time expansion DoS.
+
+  The last three were transitive and only needed a lockfile re-resolve; no `overrides` were added.
+
+  The `@fastify/static` major changes the `setHeaders` callback's first argument from a Node `ServerResponse` to a `FastifyReply`, which required two fixes:
+  - `res.setHeader()` became `reply.header()`. A v9-style body throws `TypeError: res.setHeader is not a function` from inside the plugin on every static request.
+  - **That change also flips precedence, silently.** The callback used to write to the raw response and be overwritten by the route's staged reply headers; it now writes to the reply and wins instead. That handed `/sw.js` a year of `immutable` in place of the `no-cache, no-store` its route sets, which would pin a service worker on every client with no server-side way to recover. A route that already set `Cache-Control` now keeps it.
+
+  `ws` also appears in `npm audit` but production is already on 8.21.0, outside the vulnerable range; the only affected copy is bundled under `@remotion/renderer` and is dev-only.
+
+  Adds `test/static-cache-headers.test.ts`, which drives a real server and covers the caching contract that had no test at all, and moves the floors in `test/dependency-security.test.ts` up to the patched versions.
+
 ## 1.19.6
 
 ### Patch Changes

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 >
 > **This file is in `.prettierignore` on purpose.** Prettier's markdown printer escapes underscores inside the glob-heavy paths used throughout (`agent-*.jsonl` became `agent-\_.jsonl`, collapsing backtick spans and corrupting a whole paragraph). Do not remove the ignore entry, and do not run `prettier --write` on it.
 >
-> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those.
+> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection), `.dockerignore` (the build context is the repo root, so Docker resolves it there and nowhere else) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those.
 
 ## Quick Reference
 
@@ -75,19 +75,19 @@ When user says "COM":
 
 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.
 
-**Version**: 1.19.6 (must match `package.json`)
+**Version**: 1.24.4 (must match `package.json`)
 
 ## Project Overview
 
 Codeman is a Claude Code session manager with web interface and autonomous Ralph Loop. Spawns Claude CLI via PTY, streams via SSE, supports respawn cycling for 24+ hour autonomous runs.
 
-**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), Antigravity (`agy`, Google) and Pi (pi.dev) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'`).
+**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), Antigravity (`agy`, Google), Pi (pi.dev), Grok Build (`grok`, xAI), DeepSeek Harness (`dsh`) and OMP (`omp`) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp'`).
 
 **TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`.
 
 **Requirements**: Node.js 22+, Claude CLI, tmux
 
-**Git**: Main branch is `master`. SSH session chooser: `sc` (interactive), `sc 2` (quick attach), `sc -l` (list).
+**Git**: Main branch is `master`. Terminal session dashboard: `codeman tui` (`--list` to list, `codeman tui <n>` to attach).
 
 ## Additional Commands
 
@@ -95,6 +95,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 | Task                           | Command                                                                                                                                                                                                        |
 | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Terminal dashboard             | `codeman tui` (`--list` prints the numbered list and exits, `codeman tui <n>` attaches to row n; both short-circuit before any screen setup). Needs a TTY; without a server it starts attach-only. `docs/tui.md` |
 | Dev with TLS                   | `npx tsx src/index.ts web --https`                                                                                                                                                                             |
 | Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix)                                        |
 | Bind a non-loopback host       | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
@@ -112,6 +113,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | Production logs                | `journalctl --user -u codeman-web -f`                                                                                                                                                                          |
 | Detached server                | `codeman web -d` (`--status`, `--stop`; pidfile+log at `dataPath('web.pid'/'web.log')`). ⚠ Refuses to start a 2nd server on one data dir — see Instance isolation                                              |
 | Install/remove the service     | `codeman service install` / `status` / `uninstall` (systemd user unit on Linux, LaunchAgent on macOS; names from `config/service-names.ts`)                                                                     |
+| Dependency doctor              | `codeman doctor` (alias `check-deps`; `--json`, `--category core\|office\|other`). Probes Node/Claude CLI/tmux/LibreOffice/MS Office against `config/dependency-registry.ts`; engine is pure given an injectable `ProbeHost` |
+| Multi-user accounts            | `codeman users add <name>` / `passwd <name>` / `list` / `rm <name>` (writes `~/.codeman/users.json`, mode 0600; see Multi-user mode)                                                                            |
 
 **CI**: `.github/workflows/ci.yml` (push to master/main + PRs, Node 22) runs two jobs: **(1)** `check:lockfile`, `typecheck`, `lint`, `check:frontend-syntax`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s); **(2)** the **unit/integration test suite** via `npm run test:ci` (`config/vitest.ci.config.ts` — excludes the browser-driven `test/mobile/**` suite, `perf-*` benchmarks, and 5 Playwright tests; globs live in `config/test-suites.ts`). `npm test` runs this same config, so local green == CI green. Tests are tmux-safe in CI: `TmuxManager` no-ops all shell commands under `VITEST` (see Testing).
 
@@ -125,15 +128,16 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
 - **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly. Both `aicodeman` and `codeman` bin aliases are installed (`package.json` `bin`)
 - **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
-- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` / `ANTIGRAVITY_*` / `PI_*` env vars, plus exact-key `CLAUDE_CONFIG_DIR`** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.) `CLAUDE_CONFIG_DIR` (#255, exact match via `ALLOWED_ENV_KEYS` in `schemas.ts`) points a session at a separate Claude account/config dir for per-client subscriptions; it persists to state.json (a path, not a secret; losing it on restart would silently switch accounts). ⚠️ A relocated config dir writes transcripts outside `~/.claude/projects`, so the response viewer, subagent windows, ultracode panel and Read My Mind capture go blind for that session unless the user symlinks `projects` back into the shared tree (`ln -s ~/.claude/projects <configDir>/projects`). → [architecture-invariants#per-session-env-overrides-exact-key-allowlist-and-claude_config_dir](docs/architecture-invariants.md#per-session-env-overrides-exact-key-allowlist-and-claude_config_dir)
+- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` / `ANTIGRAVITY_*` / `PI_*` / `GROK_*` / `XAI_*` / `DSH_*` / `DEEPSEEK_*` env vars, plus exact-key `CLAUDE_CONFIG_DIR`** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.) `CLAUDE_CONFIG_DIR` (#255, exact match via `ALLOWED_ENV_KEYS` in `schemas.ts`) points a session at a separate Claude account/config dir for per-client subscriptions; it persists to state.json (a path, not a secret; losing it on restart would silently switch accounts). ⚠️ A relocated config dir writes transcripts outside `~/.claude/projects`, so the response viewer, subagent windows, ultracode panel and Read My Mind capture go blind for that session unless the user symlinks `projects` back into the shared tree (`ln -s ~/.claude/projects <configDir>/projects`). → [architecture-invariants#per-session-env-overrides-exact-key-allowlist-and-claude_config_dir](docs/architecture-invariants.md#per-session-env-overrides-exact-key-allowlist-and-claude_config_dir)
 - **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
 - **Model choice flows via `settings.local.json`, NOT `--model` or env** — the App Settings **Claude Model** picker (`claudeModel` in `settings.json`) is read by `session-ui.js` at session create (wins over the legacy 1M-Opus toggles `opusContext1m`/`opusContext1mEnabled`), sent as the `modelOverride` payload field, and `updateCaseModel()` (`hooks-config.ts`) writes/deletes the `model` key in `<case>/.claude/settings.local.json`. This is the intended exception to the envOverrides rule above: model legitimately lives in `settings.local.json` (a soft default — in-session `/model` still works); env vars do not
-- **Multi-CLI prefix discipline** — env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*` vs `ANTIGRAVITY_*` vs `PI_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this; non-prefix exceptions are exact keys in `ALLOWED_ENV_KEYS` (currently only `CLAUDE_CONFIG_DIR`), never a widened prefix. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional: Vertex AI auth needs `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI`; it is the loosest allowlist entry, affecting only the user's own spawned CLI). When adding a setting, decide which CLI(s) it applies to and gate the env export accordingly. Never blanket-forward all prefixes. ⚠️ Pi is the case that proves the rule: its ~34 provider keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `HF_TOKEN`, …) share NO prefix, and the allowlist is one GLOBAL list applied by a refine with no mode context, so admitting them for pi would widen it for every mode at once — they stay out, and pi users authenticate via `/login` or the server process's own env. Resolver design pattern: `docs/opencode-integration.md`, `docs/pi-integration.md`
+- **Multi-CLI prefix discipline** — env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*` vs `ANTIGRAVITY_*` vs `PI_*` vs `GROK_*` vs `DSH_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this; non-prefix exceptions are exact keys in `ALLOWED_ENV_KEYS` (currently only `CLAUDE_CONFIG_DIR`), never a widened prefix. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional: Vertex AI auth needs `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI`; it is the loosest allowlist entry, affecting only the user's own spawned CLI), and Grok allowlists **`XAI_*`** for the same vendor-namespace reason (`XAI_API_KEY` is grok's documented auth var). When adding a setting, decide which CLI(s) it applies to and gate the env export accordingly. Never blanket-forward all prefixes. ⚠️ Pi is the case that proves the rule: its ~34 provider keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `HF_TOKEN`, …) share NO prefix, and the allowlist is one GLOBAL list applied by a refine with no mode context, so admitting them for pi would widen it for every mode at once — they stay out, and pi users authenticate via `/login` or the server process's own env. ⚠️ DeepSeek repeats pi's lesson exactly: a dsh `settings.yaml` can nominate ANY env var as a provider credential (`apiKeyEnv`), so only the vendor namespaces `DSH_*` (launcher inputs incl. `DSH_PERMISSION_MODE`) and `DEEPSEEK_*` (`DEEPSEEK_API_KEY`/`DEEPSEEK_BASE_URL`) are admitted; foreign provider keys authenticate from dsh's own files or the server env. Resolver design pattern: `docs/opencode-integration.md`, `docs/pi-integration.md`, `docs/grok-integration.md`, `docs/deepseek-integration.md`
 - **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. This has caused real shipped bugs twice
+- **Local-echo overlay stays on screen**: the overlay lays its wrapped lines out DOWNWARD from the prompt row, and the text has not reached the PTY yet, so the CLI never learns the prompt is long and nothing scrolls to make room. With the keyboard up only a handful of rows are visible, so a long prompt used to run off the bottom and the user typed blind. The block now grows UPWARD once it would pass the last visible row (optional `totalRows` in `RenderParams`; the line divs are opaque, so they cover transcript above), and a prompt taller than the viewport keeps its TAIL. ⚠️ Separately, `_shrinkPaddingToFit()` (mobile-handlers.js) must never shrink `main`'s padding-bottom below the MEASURED height of the fixed bars: on phones the toolbar and accessory bar are `position: fixed`, so that padding is the only thing reserving room for them, and taking it pulled the terminal's bottom row behind them. Tests: `packages/xterm-zerolag-input/test/overlay-renderer.test.ts`, `test/mobile-keyboard-bottom-padding.test.ts`.
 - **`xterm-zerolag-input` is single-source** — BOTH echo addons live ONLY in `packages/xterm-zerolag-input/src/`, bundled into TWO **gitignored** vendor files: `vendor/xterm-zerolag-input.js` (buffer overlay, entry `zerolag-input-addon.ts`) and `vendor/xterm-predictive-echo.js` (codex write-through, entry `predictive-echo-addon.ts`) — dev by `scripts/postinstall.js`, prod by `scripts/build.mjs`. `app.js`/terminal-ui.js only **consume** them via `new LocalEchoOverlay(terminal)` / `new PredictiveEchoOverlay(terminal)`; there is no inline copy. So: change the package source, then rerun the bundle step (`npm install` for dev, `npm run build` for prod). **Never hand-edit `app.js` for overlay behavior, and never commit the gitignored vendor bundles.** Always test on mobile after touching it. → [architecture-invariants#xterm-zerolag-input-is-single-source](docs/architecture-invariants.md#xterm-zerolag-input-is-single-source), `docs/local-echo-overlay-plan.md`
 - **Default bind is loopback-only; non-loopback without a password starts but warns** — the server defaults to `--host 127.0.0.1`. Binding non-loopback (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` starts anyway but prints a loud warning; `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges it. ⚠️ The production systemd unit passes no `--host`, so prod binds **localhost only**: reach it via `tailscale serve`/tunnel to `127.0.0.1`. A loopback bind is reachable through a same-host tunnel but NOT by a browser hitting the box's LAN IP. `install.sh` is separate and prompts for the binding (defaulting to LAN + a password), and preserves the existing binding on re-runs. → [architecture-invariants#default-bind-and-the-non-loopback-warning-path](docs/architecture-invariants.md#default-bind-and-the-non-loopback-warning-path), `docs/security-architecture.md`
-- **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
-- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
+- **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`, and **any new `tmux -L` caller through `resolveTmuxSocketName()`** (both in `config/instance.ts`): the TUI shells out to tmux from a second process, and a hardcoded `codeman` there would point a beta instance at prod's panes. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
+- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ The flip side of that: since Linux has no prebuild, `npm install` **needs a C/C++ toolchain there** (`make`, `g++`, `python3`), so `install.sh` checks for and installs one alongside Node/tmux/git — a stock Ubuntu 24 server has none and died inside node-gyp with `not found: make`. Do not drop that step. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
 - **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — under DSF=2 xterm's WebGL renderer draws glyphs at ~2× nominal size while still *reporting* nominal cell dims, so only the pixels reveal it and only the terminal font looks wrong. And overwriting a fixed output path leaves OS image viewers showing the old render, which reads as "the fix didn't work"; `scripts/capture-real-overview.mjs` mints a timestamped filename per run. Seed the per-device `localStorage` keys (`codeman:skin`, `codeman-font-size`, `codeman-app-settings`) so the capture matches a real device. → [architecture-invariants#headless-screenshot-capture](docs/architecture-invariants.md#headless-screenshot-capture)
 
 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
@@ -144,9 +148,11 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 | Domain           | Key files                                                                                              | Notes                                                                                            |
 | ---------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| **Entry**        | `src/index.ts`, `src/cli.ts`, `daemon-control`, `service-installer`, `config/service-names`             | The last three back `web -d` / `service install`                                                 |
-| **Session**      | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose                                 |
-| **Mux**          | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★                                  |                                                                                                  |
+| **Entry**        | `src/index.ts`, `src/cli.ts`, `daemon-control`, `service-installer`, `config/service-names`, `cli-style` | The last three back `web -d` / `service install`; `cli-style` is the shared palette/table/spinner/confirm kit |
+| **TUI**          | `src/tui/`: `tui-app` ★ + `tui-client` (the only IO) over a pure core (`-model`, `-layout`, `-render`, `-keys`, `-ansi`, `-composer`, `-approvals`, `-digest`, `-sse`, `-types`) | `codeman tui`, a CLIENT of the server, never a second brain. Design doc: `docs/tui-plan.md`; user guide `docs/tui.md` |
+| **DeepSeek**     | `src/utils/deepseek-cli-resolver.ts`, `src/deepseek-status-shim.ts`, `src/deepseek-web-server.ts` (background `dsh web`, not a session) | `dsh` is a PROFILE LAUNCHER, not an agent; read `docs/deepseek-integration.md` first |
+| **Session**      | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `session-trust-dialog` (pure), `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose                                 |
+| **Mux**          | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★, `src/proc-tree.ts` (pure, bounded descendant walk)                                  |                                                                                                  |
 | **Respawn**      | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`)      | Read `docs/respawn-state-machine.md` first                                                       |
 | **Ralph**        | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first                                                          |
 | **Orchestrator** | `src/orchestrator-loop.ts`, `-planner`, `-verifier`                                                    | Read `docs/orchestrator-loop-architecture.md` first                                              |
@@ -154,14 +160,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Agents**       | `src/subagent-watcher.ts` ★, `team-watcher`, `bash-tool-parser`, `transcript-watcher`, `workflow-run-watcher` | `workflow-run-watcher` is STANDALONE and never touches `subagent-watcher`                        |
 | **AI**           | `src/ai-checker-base.ts`, `ai-idle-checker.ts`, `ai-plan-checker.ts`                                   |                                                                                                  |
 | **Tasks**        | `src/task.ts`, `task-queue.ts`, `task-tracker.ts`                                                      |                                                                                                  |
-| **State**        | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`, `intent-store.ts`                                     |                                                                                                  |
+| **State**        | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`, `intent-store.ts`, `tab-layout.ts` (pure model) + `-service` (sole mutation boundary) + `-persistence` + `-legacy-order`                                     |                                                                                                  |
 | **Infra**        | `src/hooks-config.ts`, `push-store`, `tunnel-manager`, `image-watcher`, `file-stream-manager`, `remote-hosts` + `remote-reconnect` (pure), `docker-hosts` + `docker-export` | Remote/docker case overlays; see Key Patterns                                                    |
 | **Web tabs**     | `src/webview-store.ts`, `webview-capabilities.ts`, `src/web/webview-proxy.ts` (pure), `src/web/routes/webview-routes.ts` | Dashboard URLs as tabs; NOT a SessionMode                                                        |
 | **Search**       | `src/search-service.ts`                                                                                | Pure in-memory core for `GET /api/search`                                                        |
 | **Attachments**  | `src/attachment-registry.ts`, `attachment-magic`, `generated-artifact-attachments`, `session-attachment-history`, `document-preview-cache`, `document-thumbnailer`, `document-conversion-limiter`, `config/attachment-guard` | See Key Patterns                                                                                 |
 | **Plan**         | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`) | `templates/` holds the CLAUDE.md scaffold generated into new cases                                |
-| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (24 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
-| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 30 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
+| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (25 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
+| **Frontend**     | `src/web/public/app.js` (~6.7K lines, core) + 31 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
 | **Types**        | `src/types/index.ts` (barrel) → 22 domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
 
 ★ = Large, central file (>50KB) — read its `@fileoverview` first. All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.
@@ -170,7 +176,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Config**: `src/config/` — 21 files, no barrel (`index.ts`) exists; import from the specific file.
 
-**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver`/`antigravity-cli-resolver`/`pi-cli-resolver` (CLI path resolution; ⚠ `pi-cli-resolver` additionally version-probes the binary, since `pi` is a generic name), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
+**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver`/`antigravity-cli-resolver`/`pi-cli-resolver`/`grok-cli-resolver`/`deepseek-cli-resolver`/`omp-cli-resolver` (CLI path resolution, one per `SessionMode`, all nine sharing the lookup chain in `cli-executable-resolver`: server PATH, then that CLI's install dirs, then an interactive login shell LAST, since it is the only step that spawns anything and it is what finds nvm/Homebrew installs under a service manager's minimal PATH; ⚠ `pi-`, `grok-` and `deepseek-cli-resolver` additionally probe the binary's identity, since `pi` is a generic name, `grok` has npm squatters, and Debian ships an unrelated `dsh`), `file-query` (⚠ Files-panel search matcher, glob-by-two-pointer, never RegExp), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority), `shell-resolver` (⚠ resolves a real login shell for `mode: 'shell'`; the literal string `$SHELL` used to be expanded by the SERVER's shell, which is empty in a container), `event-loop-monitor` (a sync `execSync` freezes the port while the process stays alive, leaving no trace), `dependency-checker` + `dependency-report` (the `codeman doctor` probe engine, registry in `config/dependency-registry.ts`).
 
 ### Data Flow
 
@@ -183,15 +189,19 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Input**: `session.writeViaMux()` for programmatic/curl input via tmux `send-keys -l` + `send-keys Enter`, single-line only. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
 
-**Agent wait primitives**: bounded long-polls so an agent driving Codeman from a shell can block instead of poll: `GET /api/sessions/:id/wait` (lifecycle signal), `GET /api/sessions/:id/wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST /api/sessions/:id/input`. Registry in `session-wait-registry.ts` (pure, no `Session` reference), bounds in `config/agent-wait.ts`. ⚠️ **A timeout is a 200** (`wait.timedOut`), never an error, so callers loop over short waits. ⚠️ `stop`/`blocked` come from Claude Code hooks and therefore fire for **`claude` mode ONLY** (`shell` installs none either); asking for one explicitly on another mode is a 400, the default set silently drops them. ⚠️ Send-and-wait registers the waiter BEFORE the write (a separate POST-then-wait races and reports the PREVIOUS turn), and both teardown paths must `notifySignal('exit')` BEFORE `cancelAll()`. ⚠️ Client-hangup abort listens on **`reply.raw`** guarded by `writableFinished`: on `req.raw`, `close` fires when the request BODY ends, which on a POST killed every send-and-wait instantly and no `app.inject()` test could see it. ⚠️ Worker liveness cannot come from `session.pid` — for a tmux session that is the local attach client, which outlives a worker dying inside its pane — so it is probed at the mux layer (`isPaneDead`, ~750 ms cache) on blocking waits only, never on the input hot path. ⚠️ Signals are edge-triggered with no history: one that fires with no waiter registered is unobservable afterwards, so gather fan-outs with send-and-wait or latched `wait-output` markers, never fire-and-forget-then-sequential-signal-waits. The primitives are packaged as the **`skills/codeman` agent skill**: installable via `codeman skill install [--case <name>]` / `skill uninstall`, or auto-injected into a case's `.claude/skills/` on Claude session create behind `agentSkillEnabled` (SYNCED, default OFF). Injection is ADD-ONLY at create, marker-owned (`applyAgentSkill` in `hooks-config.ts` never touches an unmarked user copy) and refuses symlinks (this repo's own `.claude/skills/codeman` is a symlink to the source, which the injector must never write through). ⚠️ Claude Code loads a same-named USER-LEVEL skill (`~/.claude/skills/codeman`, written once by `codeman skill install` with no `--case`) over the per-case copy, and nothing used to refresh it: a stale Aug-9 user copy shadowed every fresh injection (2026-08-14: agents ran the old recipes, spawned workers serially and lost their lineage arcs), so session create now also refreshes a marker-owned user copy (`refreshUserAgentSkill`; refresh-only, never installs, foreign/symlink refused). Session create additionally pre-seeds the skill's §0 preamble cache (`seedAgentSessionPreamble` → `${XDG_CACHE_HOME:-~/.cache}/codeman-agent-<id>.sh`, local claude sessions only), single-sourced from `skills/codeman/preamble.sh` and pinned byte-identical to SKILL.md's §0 heredoc by `test/agent-skill.test.ts`, so the skill's bootstrap is a two-line loader instead of a ~150-line paste the model types out (~47 s of generation, measured live). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
+**Agent wait primitives**: bounded long-polls so an agent driving Codeman from a shell can block instead of poll: `GET /api/sessions/:id/wait` (lifecycle signal), `GET /api/sessions/:id/wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST /api/sessions/:id/input`. Registry in `session-wait-registry.ts` (pure, no `Session` reference), bounds in `config/agent-wait.ts`. ⚠️ **A timeout is a 200** (`wait.timedOut`), never an error, so callers loop over short waits. ⚠️ `stop`/`blocked` are hook-driven and fire for **`claude` and `deepseek` ONLY** (`shell` installs none either); asking for one explicitly on any other mode is a 400, the default set silently drops them. `deepseek` qualifies because the DeepSeek Harness TUI REPORTS idle/working/blocked to its supervisor and Codeman is that supervisor (`deepseek-status-shim.ts`), so its signals are definitive rather than inferred — `hooksAvailableForMode()` in `session-wait-registry.ts` is the one place that rule lives. ⚠️ Send-and-wait registers the waiter BEFORE the write (a separate POST-then-wait races and reports the PREVIOUS turn), and both teardown paths must `notifySignal('exit')` BEFORE `cancelAll()`. ⚠️ Client-hangup abort listens on **`reply.raw`** guarded by `writableFinished`: on `req.raw`, `close` fires when the request BODY ends, which on a POST killed every send-and-wait instantly and no `app.inject()` test could see it. ⚠️ Worker liveness cannot come from `session.pid` — for a tmux session that is the local attach client, which outlives a worker dying inside its pane — so it is probed at the mux layer (`isPaneDead`, ~750 ms cache) on blocking waits only, never on the input hot path. ⚠️ Signals are edge-triggered with no history: one that fires with no waiter registered is unobservable afterwards, so gather fan-outs with send-and-wait or latched `wait-output` markers, never fire-and-forget-then-sequential-signal-waits. ⚠️ **`deepseek` is therefore the one non-claude mode the skill drives like claude** — `spawn_workers alpha beta:deepseek` is a mixed fleet in one call, and `sendwait`/`last_text` need no variant. Two traps are baked into the preamble rather than left to the agent: the harness's boot `idle` report lands ~300 ms BEFORE its composer paints (2.26 s vs 2.56 s, measured), so readiness must come from the composer and never from the signal, or a send-and-wait resolves on the boot edge and reports a turn that never ran; and `sendwait` asks for `wait:"stop,exit"` rather than the default set, because that set also carries `idle`, which for an external CLI is inferred from output stabilization — on a dsh worker whose TUI repaints rarely, a re-wait resolved in 0 ms with `signal:"idle"` on a turn with minutes left to run. The primitives are packaged as the **`skills/codeman` agent skill**: installable via `codeman skill install [--case <name>]` / `skill uninstall`, or auto-injected into a case's `.claude/skills/` on Claude session create behind `agentSkillEnabled` (SYNCED, default OFF). Injection is ADD-ONLY at create, marker-owned (`applyAgentSkill` in `hooks-config.ts` never touches an unmarked user copy) and refuses symlinks (this repo's own `.claude/skills/codeman` is a symlink to the source, which the injector must never write through). ⚠️ Claude Code loads a same-named USER-LEVEL skill (`~/.claude/skills/codeman`, written once by `codeman skill install` with no `--case`) over the per-case copy, and nothing used to refresh it: a stale Aug-9 user copy shadowed every fresh injection (2026-08-14: agents ran the old recipes, spawned workers serially and lost their lineage arcs), so session create now also refreshes a marker-owned user copy (`refreshUserAgentSkill`; refresh-only, never installs, foreign/symlink refused). Session create additionally pre-seeds the skill's §0 preamble cache (`seedAgentSessionPreamble` → `${XDG_CACHE_HOME:-~/.cache}/codeman-agent-<id>.sh`, local claude sessions only), single-sourced from `skills/codeman/preamble.sh` and pinned byte-identical to SKILL.md's §0 heredoc by `test/agent-skill.test.ts`, so the skill's bootstrap is a two-line loader instead of a ~150-line paste the model types out (~47 s of generation, measured live). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
 
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
 ⚠️ **A `❯` sighting is NOT the end of a turn, and neither is silence.** Claude redraws the composer (`❯`) about once a second all through a turn, so the old "saw a ❯, wait 2s → idle" rule flipped every working session to idle two seconds in (measured: a session mid-tool-call at 17 minutes reporting `status:"idle"`). Its working indicator is `✻ Actualizing… (13m 23s · ↓ 47.5k tokens)`: the glyph animates through `· ✢ ✳ ∗ ✻ ✽`, the gerund is randomized, and the finished line (`✻ Cooked for 2m 49s`) carries the same glyph, so neither `SPINNER_PATTERN` (braille, not what current versions draw) nor a keyword list can see it. Matching the new line in the STREAM does not work either: tmux ships partial repaints, so the whole line reaches the PTY only every few tens of seconds. So: `_confirmIdle()` (session.ts) requires the pane to go quiet, and then asks the SCREEN via `capturePaneText()` + `CLAUDE_WORKING_LINE_PATTERN` before believing it; a sustained run of repaints (`session-activity.ts`, pure + unit tested) is what marks a turn as started, with the same screen probe vetoing keystroke echo. Idle now lands ~3-5s after a turn ends instead of 2s into one. Claude-mode only, since an external CLI has no `❯`, so nothing would ever arm the confirmation and the session would latch busy.
 
+**Workspace-trust dialog auto-accept** (`session-trust-dialog.ts`, pure + unit tested): Claude Code asks once per directory ("Is this a project you created or one you trust?") before it will read or edit anything, and since Codeman sessions run permission-skipping or classifier-guarded modes the answer is always yes, so a session parked on that dialog is simply stuck. ⚠️ **Match the compacted SCREEN, never the stream.** tmux repaints a row by writing each word and then a cursor-forward (`\x1b[C`) instead of a space, and Ink colours each word separately, so the wire carries `I\x1b[Ctrust\x1b[Cthis\x1b[Cfolder`; stripping the escapes leaves `Itrustthisfolder`, because the spaces are not there to strip, they were never sent. A plain `includes('trust this folder')` therefore never matched a single chunk and the auto-accept was silently DEAD for every session that hit the dialog. `compactScreenText()` removes ALL whitespace instead (plus the `ESC ( B` charset selects that `stripAnsi` does not cover, which would otherwise land inside a phrase as a literal `(B`), which survives both that repaint style and the spaced full-screen redraw. ⚠️ **Never answer it with a blind `\r`.** The layout has changed under us at least twice, and Claude Code 2.1.252 dropped the option numbers, put "No, exit" FIRST and highlights IT by default, so the Enter that answered the old dialog now picks *exit* and the pane dies (`Pane is dead (status 1)`) seconds after the session starts. `trustDialogNextKey()` reads the `❯` marker and returns ONE step at a time (an arrow while the cursor is on the wrong option, Enter only once the screen shows it on the trust option), with the pane re-read between steps, so a dropped arrow costs a repaint instead of the session; a frame that does not say which option is highlighted returns null and waits for the next repaint. ⚠️ The LAST marked option in the text wins, because the direct-PTY fallback reads an append-only buffer where every repaint since launch is still present and an older frame must not out-vote the freshest one. ⚠️ Answering types into a live session, so THREE guards must all hold and none is redundant: a **startup-only window** (`TRUST_DIALOG_WINDOW_MS`, 90s, since the dialog renders before the main UI and leaving it open forever would let an agent transcript that merely QUOTES the dialog trigger an Enter, this file being an example), a **two-marker match** requiring a trust phrase AND one of the dialog's own confirm affordances (`isTrustDialogScreen`), and an **attempt cap** (`TRUST_DIALOG_MAX_ATTEMPTS`, 6: a keystroke can land while Ink is still mounting the widget and be dropped, which is the other half of why sessions got stuck here, but retrying forever would hammer keys into whatever came next; it was 3 while one Enter answered the dialog, and answering now costs at least two keystrokes). ⚠️ It reads `capturePaneText()` and falls back to a deliberately SHORT tail of the terminal buffer only on a direct-PTY session, which has no pane: that buffer is append-only, so a longer tail would keep re-matching a dialog answered minutes ago. ⚠️ **The scan must schedule its own next read** (`_trustDialogTimer`, cleared in `_clearAllTimers()`): it runs from the PTY `onData` handler, which was enough while one Enter answered the dialog, but the arrow that moves the cursor is the LAST output the pane produces, so a two-keystroke answer waiting on more output parks forever with the cursor sitting on the right option (measured on a live 2.1.252 spawn: cursor moved at 6 s, then nothing).
+
+**Process-tree walks are bounded** (`proc-tree.ts`, pure + unit tested): `collectDescendants(pid, byParent)` is the ONE descendant traversal, fed by a single cached `ps -eo pid=,ppid=` snapshot (`refreshProcSnapshot()` in tmux-manager.ts: in-flight-shared, async because `execSync`'s timeout cannot return at all while spawnSync waits on an unkillable child, and ANY error discards the result rather than caching a truncated `ps`, which would make whole subtrees invisible to the kill path). ⚠️ **The unbounded version took a machine down** (2026-07-30): it ran `pgrep -P <pid>` once per node and recursed with no visited set, no depth limit and no node cap, so across ~28 adopted tmux trees the fan-out exploded while each `pgrep` blocked in the WSL kernel reading `/proc/<pid>/cgroup`, ending at ~13,000 `pgrep` processes in D-state, a load average above 13,000, and a machine recoverable only by restarting WSL, which cost every running session. Three properties make that impossible and each has a test: a cycle terminates (a real tree has none, a stale snapshot can still produce one), depth is capped (`PROC_WALK_MAX_DEPTH`), node count is capped (`PROC_WALK_MAX_NODES`). The fourth is structural: the function takes a snapshot and cannot spawn anything at all. ⚠️ It lives in its own module because as a private method of `tmux-manager.ts` the regression test had to keep its own COPY of the algorithm, which is a test that passes while the shipped code rots. ⚠️ Truncation is reported through `onTruncated` rather than silently, with BOTH caps named: a silent depth cap hides a deep tree exactly as effectively as a silent node cap hides a wide one.
+
 **Auto-resume on usage limit** (opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit, `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time and `SessionAutoOps` arms a timer for reset+2min, then sends Esc + `continue`. ⚠️ Respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected`), which is what prevents `/clear` from wiping the paused conversation. Claude-mode only. → [architecture-invariants#auto-resume-on-usage-limit](docs/architecture-invariants.md#auto-resume-on-usage-limit)
 
-**Plan-usage chip** (statusLine telemetry, `showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the `statusLineTelemetry` flag on session create). A chip shown without telemetry renders `—` forever. Codeman injects its own `statusLine.command` exporter which POSTs Claude's `rate_limits` blob to `POST /api/status-telemetry`. The exporter is identified by a marker, so it only ever adds/updates/removes a statusLine that is **ours**, never a user's hand-authored one, and it prints the footer through so the in-terminal statusline is not blanked. Claude-mode only; distinct from auto-resume, which reacts to the limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`
+**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the Claude `statusLineTelemetry` flag on session create). It renders compact Claude and Codex provider rows. Claude data comes from Codeman's marked `statusLine.command` exporter, which POSTs `rate_limits` to `POST /api/status-telemetry`, never overwrites a user's hand-authored statusLine, and prints the footer through. Main Codex usage comes from a read-only host `account/rateLimits/read` app-server poll at startup and every 5 minutes; exclude model-specific buckets such as Spark, and omit the Codex row when no signed-in limit is available. Distinct from auto-resume, which reacts to Claude's limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`
 
 **Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.
 
@@ -199,9 +209,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs inside a durable remote `tmux -L codeman-remote` (session name `codeman-ssh-<id>`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so an instance on the target host never adopts it), fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill** on tab close; owned ones propagate `kill-session`. A bounded-backoff watcher auto-reconnects dropped sessions (`remoteAutoReconnect`, default ON). ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**, which `shellescape`s every user field. Never hand-build an ssh line elsewhere. ⚠️ Run flows must route remote cases through `POST /api/quick-start`, not `POST /api/sessions` (which stat-validates `workingDir` locally and has no `caseName`). → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md`
 
-**Docker cases**: a case can point at a **container**, with any of the five CLI backends running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design)
+**Docker cases**: a case can point at a **container**, with any of the CLI run modes running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a `SessionMode` of its own**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design)
 
-**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All five **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. ⚠️ **Codex sessions use PREDICTIVE WRITE-THROUGH echo, never the buffer overlay** (`_localEchoPolicy` in `_updateLocalEchoState`, terminal-ui.js): codex's composer reacts per keystroke ("/" pops a live-filtering picker, arrows edit server-side state, the composer grows as it wraps), so buffer-until-Enter starved it into issues #218/#219/#220/#222 and stays disabled (`_localEchoEnabled` remains false for codex). Instead, `PredictiveEchoAddon` (separate `vendor/xterm-predictive-echo.js` bundle) paints each keystroke at the predicted cell while the wire path stays BYTE-IDENTICAL: the onData hook (`_predictHookOnData`) is a plain statement with no `return`, so control always falls through into the untouched send path — pinned by vm and E2E byte-identity tests. Predictions reconcile against the parsed buffer and only while the cursor sits on the measured composer row (`isCodexComposerRow`, `/^› /`). Codex also **drops keystrokes that share a PTY read with a bracketed paste**, so flushed text and the paste sequence must go out as separate delayed writes (mirroring the Enter branch's delayed `\r`). Tests: `test/local-echo-codex-gating.test.ts`, `test/codex-predictive-echo.test.ts` (E2E vs real codex), `packages/xterm-zerolag-input/test/codex-replay.test.ts`. ⚠️ **Pi is the opposite kind of CLI and needs the opposite instincts**: it has NO permission prompts and no sandbox, so there is no bypass flag to send and Codeman must not invent one; its privileged knob is the tri-state `approveProjectTrust` (`--approve`/`--no-approve`), which makes pi EXECUTE repo-local `.pi/extensions` TypeScript, so the multi-user clamp puts pi in the **materialize** branch (an absent config still yields `--no-approve` for a non-granted owner) and `--api-key` is never wired. Pi stays OUT of `isAltScreenStripMode()` (main-screen TUI, and its 0.84.0 fullscreen mode is runtime-switchable via `/settings`, where the alt screen is load-bearing), and lands on the `'buffer'` echo policy via the `_updateLocalEchoState` fallthrough. Pi's own tests: `test/pi-mode.test.ts`, `test/routes/external-cli-bypass-clamp.test.ts`; user guide `docs/pi-integration.md`. → [architecture-invariants#external-cli-modes-opencode-codex-gemini-antigravity-pi](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi)
+**Docker Compose deployment** (`docker/`, contributed): Codeman itself runs in a container and spawns Docker cases as **SIBLING** containers through the mounted host socket (Docker-outside-of-Docker), never nested. That inverts one assumption the bare-host path takes for granted: the daemon no longer shares Codeman's filesystem, so a bind source valid *inside* Codeman means nothing to it. `resolveDockerDaemonMountSource()` translates sources under HOME into the daemon's namespace via `CODEMAN_DOCKER_HOST_HOME`, and `CODEMAN_CASES_PATH` points the cases dir at a host-absolute bind mount so a workspace resolves to the SAME absolute path on both sides (which is what keeps the transcript projHash matching, per Docker cases above). ⚠️ **`CODEMAN_CASES_PATH` must move every consumer or none**: it is resolved once in `config/cases-dir.ts` because `src/cli.ts` resolves case paths too, and when only the server's `CASES_DIR` learned the override, `codeman skill install --case <name>` reported "Case not found" on exactly the deployment the override exists for. ⚠️ **`.dockerignore` patterns match the WHOLE context-relative path**, so a bare `.env` line excludes only the ROOT file: `docker/.env` (which holds `CODEMAN_PASSWORD` and any provider keys) rode `COPY . .` into the image until `**/.env` was added — verified in both directions with a real build context. ⚠️ A Compose LONG-form bind (`type: bind`) **creates a missing host source directory ROOT-OWNED** rather than refusing, so any bind source the runtime user must write to has to be pre-created and chowned. `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1` drops `--memory-swap` (and filters only that one kernel warning) for hosts without swap accounting; `--memory` still applies. `docs/docker-compose.md` + `docker/README.md` (user guides)
+
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All eight **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. ⚠️ **Codex sessions use PREDICTIVE WRITE-THROUGH echo, never the buffer overlay** (`_localEchoPolicy` in `_updateLocalEchoState`, terminal-ui.js): codex's composer reacts per keystroke ("/" pops a live-filtering picker, arrows edit server-side state, the composer grows as it wraps), so buffer-until-Enter starved it into issues #218/#219/#220/#222 and stays disabled (`_localEchoEnabled` remains false for codex). Instead, `PredictiveEchoAddon` (separate `vendor/xterm-predictive-echo.js` bundle) paints each keystroke at the predicted cell while the wire path stays BYTE-IDENTICAL: the onData hook (`_predictHookOnData`) is a plain statement with no `return`, so control always falls through into the untouched send path — pinned by vm and E2E byte-identity tests. Predictions reconcile against the parsed buffer and only while the cursor sits on the measured composer row (`isCodexComposerRow`, `/^› /`). Codex also **drops keystrokes that share a PTY read with a bracketed paste**, so flushed text and the paste sequence must go out as separate delayed writes (mirroring the Enter branch's delayed `\r`). Tests: `test/local-echo-codex-gating.test.ts`, `test/codex-predictive-echo.test.ts` (E2E vs real codex), `packages/xterm-zerolag-input/test/codex-replay.test.ts`. ⚠️ **Pi is the opposite kind of CLI and needs the opposite instincts**: it has NO permission prompts and no sandbox, so there is no bypass flag to send and Codeman must not invent one; its privileged knob is the tri-state `approveProjectTrust` (`--approve`/`--no-approve`), which makes pi EXECUTE repo-local `.pi/extensions` TypeScript, so the multi-user clamp puts pi in the **materialize** branch (an absent config still yields `--no-approve` for a non-granted owner) and `--api-key` is never wired. Pi stays OUT of `isAltScreenStripMode()` (main-screen TUI, and its 0.84.0 fullscreen mode is runtime-switchable via `/settings`, where the alt screen is load-bearing), and lands on the `'buffer'` echo policy via the `_updateLocalEchoState` fallthrough. Pi's own tests: `test/pi-mode.test.ts`, `test/routes/external-cli-bypass-clamp.test.ts`; user guide `docs/pi-integration.md`. ⚠️ **Grok is codex-shaped on permissions but opencode-shaped on rendering**: its bypass switch is `alwaysApprove` (`--always-approve`, grok's `bypassPermissions` mode — the Run button sends it `true` like antigravity's, and the clamp's only-if-sent branch strips it for non-granted owners), while its fullscreen alt-screen TUI keeps it OUT of `isAltScreenStripMode()`; the resolver version-probes `grok --version` like pi's (npm squatters exist for the name — `GET /api/grok/status` surfaces path + version), and grok lands on the `'buffer'` echo policy via the fallthrough (UNMEASURED against a live authenticated session; if its composer turns out per-keystroke-reactive like codex, flip it to the `'off'` branch). Grok's own tests: `test/grok-mode.test.ts`, `test/grok-cli-resolver.test.ts`; user guide `docs/grok-integration.md`. ⚠️ **DeepSeek breaks three of this family's assumptions, so do not pattern-match it onto its siblings.** (1) The agent is a **PROFILE, not the binary**: `dsh` is a launcher over `$DSH_HOME/profiles/<name>` and DeepSeek ships only `web`/`headless`/`base`, so the terminal front door is ALWAYS third-party and "installed" ≠ "runnable" — the Run button gates on `isDeepSeekRunnable()` (binary AND a pane-capable profile) while `isDeepSeekAvailable()` gates the "add a profile" affordance; a `web`/`headless` profile is refused at spawn because it cannot drive a pane. (2) The permission switch is the **`DSH_PERMISSION_MODE` env export, not a flag** (`read-only`/`workspace-write`/`danger-full-access`) — the harness has none, and this is the one legitimate exception to the effort-style env-var ban because it is read with `??` as a boot-time default, so it stays soft; absent = `workspace-write`, which asks, hence the only-if-sent clamp branch, clamping to `workspace-write` (never `read-only`, which would break the workspace). ⚠️ **That clamp needs a second half no other CLI needs**, because the switch is an env var and `DSH_*` is an allowlisted `envOverrides` prefix: `applyEnvOverrides()` runs AFTER `_configureDeepSeek()` in tmux-manager, so a non-granted owner sending `DSH_PERMISSION_MODE` on the SAME request would land last and hand back exactly the privilege the confLine truncated
+
+**DeepSeek web UI** (`POST`/`GET`/`DELETE /api/deepseek/web`, `deepseek-web-server.ts`): the Run menu's "DeepSeek web UI..." entry supervises ONE background `dsh web` child process, deliberately **NOT a shell session**. The session version worked and was still wrong in use: it put a terminal tab on screen next to the web tab the user actually asked for, every single time, and nothing about a long-lived HTTP server needs to be a tab. ⚠️ What a session gave for free now has to be paid for explicitly, and every piece is load-bearing: **exactly one** server (a second click REUSES it rather than racing it for a port, which two sessions structurally could not do), **restarted when the browser 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, so whoever asks last wins: the asker is by definition the origin about to load the page), **killed on shutdown** (`stopDeepSeekWeb()` in the server teardown, because the child 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), and **failures returned to the caller**, since with no tab there is nowhere for a stack trace to land. ⚠️ The port search starts at dsh's own default 3080 and walks 40, never fixed: that default is precisely the port most likely to be taken already by the user's own `dsh web`, and hardcoding it killed this feature with EADDRINUSE once. Free-port detection BINDS rather than connects (a connect probe cannot tell "free" from "listening but not answering yet"), so it is racy by nature and the caller still waits for the server to really answer before reporting success. ⚠️ Both `POST` and `DELETE` sit at the **same privilege bar as the profile installer** (`canUsernameRunPrivilegedCommands`) even though the action reads as "open a page": booting a dsh profile executes the plugin code in it, and the server is a single shared instance, so stopping it in multi-user mode takes it out from under other users' tabs.
 
 **Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. ⚠️ **Closing has the mirror-image race and one owner**: `closeSession()` reads `wasActive` BEFORE its `await` and announces the delete via `_closingSessions`, while `_onSessionDeleted` skips the active-session handoff for an id in that set. Both used to read `activeSessionId` after the fact, so the `session_deleted` broadcast for your own delete could null it first and closing the tab you were on landed on the welcome screen instead of the next session, on the same build, depending on timing. The fallback also picks the first order entry that is still in `sessions` (a dead id can linger in `sessionOrder`, same reason Alt+N indexes a live-filtered list). A delete from ANOTHER client still shows the welcome screen, which is the honest answer when what you were looking at was taken away. Tests: `test/session-close-fallback.test.ts`. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)
 
@@ -209,9 +223,11 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows fold into their owning session via a `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
 
+**Owner tab layouts** (COD-359, `tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat tab strip, scoped per owner (`SINGLE_USER_LAYOUT_OWNER` = `@single` when multi-user is off), persisted under the `tabLayouts` key in state.json. A layout is `{version, groups[], ungrouped[], updatedAt}` whose refs point at either a session or a saved webview (`TabRefKind`), capped at 32 groups / 512 refs. ⚠️ **BACKEND ONLY as of 1.24.1**: nothing in `src/web/public/` calls these routes yet, so a UI built on top is new frontend work, not a rewiring job. ⚠️ **`TabLayoutService` is the single mutation boundary** and every lifecycle caller (session created/removed, webview created/deleted, a legacy order PUT) describes ONE completed server action and gets AT MOST ONE versioned write; writing layout state from a route or a manager directly is what the service exists to prevent. ⚠️ The layout does not replace `PUT /api/session-order`, it PROJECTS onto it: `tab-layout-legacy-order.ts` is the pure translation both ways (`putLegacyOrder()` recomposes a global order from the owner's groups), so changing one side without the other silently desyncs the tab strip from the stored layout. ⚠️ **Reconciliation is gated on a SUCCESSFUL restore** (`markRestorationComplete` / `markRestorationFailed` / `markRestorationSkipped`, plus `assertDeletionReady()`): pruning refs against a session list that failed to load would delete live tabs, so a failed restore must leave the layout untouched. `PUT` takes exactly `{baseVersion, layout}` (any other key shape is a validation error), answers a stale `baseVersion` with the current layout rather than clobbering, and is capped at 128 KiB. Broadcasts `tab:layoutChanged`, owner-routed via `deriveTabLayoutSseHint`.
+
 **Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`. ⚠️ **Every claude session INSTALLS the hooks block into its workspace** (`applyWorkspaceHooks` in hooks-config.ts → `ensureCodemanHooks`, an add-only merge that keeps a user's own handlers), from EVERY claude create path — both interactive routes, cron fires, legacy scheduled runs, the plan-orchestrator one-shots — and from `restoreMuxSessions()` for sessions recovered on server start (that boot sweep skips a workspace that no longer exists, so a deleted repo with a surviving tmux session is never resurrected as an empty dir). Before 2026-08-15 hooks were written ONLY when Codeman created the case DIRECTORY, so a linked case / cloned repo — where most sessions actually run — had no hooks at all and every hook-driven surface was silently dead there: an AskUserQuestion dialog blocked the pane while the tab and the phone overview both read a calm `idle`, with no Approvals Inbox item, no push, no definitive `stop`/`idle_prompt` for respawn and no `stop`/`blocked` for the wait endpoints. The escape hatch is the synced `workspaceHooksEnabled` setting (App Settings → Agents & CLIs → Claude, **default ON**); OFF restores the old behavior, where a Codeman block that is already there is still refreshed when stale (COD-91) but one is never added. ⚠️ Route the decision through `applyWorkspaceHooks` rather than calling `ensureCodemanHooks` at a new site, or the setting silently stops applying to that path. ⚠️ Claude Code RE-READS `settings.local.json`, so an already-running session starts firing hooks without a restart (measured 2026-08-15) — and the notification for a blocking dialog is delayed by Claude Code (~30s), so the alert trails the dialog. ⚠️ An AskUserQuestion / plan-selection dialog arrives as **`permission_prompt`**, not `elicitation_dialog` (that one is MCP elicitation), so it renders as the RED "needs you" alert, not the yellow idle one.
 
-**Approvals Inbox** (cross-session queue of prompts waiting on a human; `approvalsInboxEnabled`, SYNCED, default OFF: every surface is opt-in; only the store and answer endpoints run regardless, so flipping it ON shows anything already pending): `web/approval-inbox.ts` is a `sessionWaits`-style singleton fed by `/api/hook-event`, holding at most ONE item per session (a new prompt supersedes), claude-mode only, in-memory. Cards are answered via `POST /api/approvals/:id/answer`, which sends a digit / Esc / idle-prompt text through `writeViaMux` (menu answers never carry `\r`). ⚠️ `option` digits are accepted ONLY when they match options parsed from the captured pane frame, and the answer path RE-CAPTURES the pane first (a dialog that no longer parses on screen means the keystroke would land in the composer, so refuse with 409). ⚠️ Resolution on the heuristic `working` signal is restricted to `idle` items; permission/question items clear only on definitive signals (`stop`, `elicitation_complete`/`elicitation_response`, exit/delete, answer, supersede, 12h TTL). ⚠️ **Viewing a session ACKNOWLEDGES its idle item, it does not resolve it** (`POST /api/approvals/session/:sessionId/viewed` → `acknowledgedAt` → `approval:updated`): the item stays pending (still answerable, still Read My Mind context) and only stops arming the yellow tab alert. That flag is what makes the clear durable, since the view-clears-idle rule used to live in one browser's memory and `seedApprovals()` re-armed the alert on the next reload while other devices never heard about it at all; the local half is `markIdleAlertSeen()` (app.js), called from BOTH `selectSession` paths, including the already-active early return, where a click could otherwise never clear the alert. ⚠️ **Only a HUMAN opening a session acknowledges**: `selectSession(id, { auto: true })` marks the three selections the APP makes (boot restore, a solo window opening its target, the fallback after the active session is closed) and skips the acknowledgement, so a page load cannot silently spend an alert the user never saw. The flag defaults to user-initiated, so an untagged call site fails toward acknowledging rather than toward an alert nothing can clear; `test/session-select-ack-gate.test.ts` pins both the gate and the tagged call sites. Idle-only by construction (`acknowledge()` defaults to `['idle']`): looking at a permission/question dialog does not answer it. ⚠️ Same rule on the input path: `_ackDelivery` (app.js) spends the IDLE alert only, via that same `markIdleAlertSeen()`. It used to `clearPendingHooks(sessionId)` with no kind, so one keystroke wiped a RED alert on that device while the dialog was still up, the other devices stayed red, and a reload re-seeded it. ⚠️ Claude Code fires no "permission answered" hook (only `elicitation_complete`/`elicitation_response`, i.e. the question flavor), so an answered-in-the-terminal dialog would otherwise sit pending until `stop`: `GET /api/approvals` therefore runs a **staleness sweep** over the caller's own items via `verifyStillAnswerable()`, which is deliberately the conservative check the answer path uses (only an item whose ORIGINAL frame parsed options can be dropped, so an unreadable capture keeps the alert rather than losing a live one). The frontend seeds from `GET /api/approvals` in `handleInit` **regardless of the setting**: the seed re-arms the tab-alert state machine (`setPendingHook`) unconditionally, and only populating `this.approvals` (the inbox surfaces) is gated — seeding used to be gated wholesale, which left a reloaded page with NO red tab while a permission dialog sat blocking a session (2026-08-15); `_onApprovalResolved` clears the pending-hook alert unconditionally for the same reason. ⚠️ The red/yellow tab alert itself is a STEADY border/background/dot with a pulse on top: the original keyframes swung to transparent at 0%/100%, so half of every cycle looked like a normal tab. Push Approve/Deny buttons stay gated on the setting (`sendPushNotifications` strips `actions`/`approvalId` when OFF) and are answered from `sw.js` directly so they work with no tab open. Surfaces (all gated on the setting): header bell (marker-hidden until count > 0, phones never show it) + drawer (`approvals-ui.js`), phone overview NEEDS YOU answer strips (`mobile-overview.js`). Design: `docs/approvals-inbox-plan.md`.
+**Approvals Inbox** (cross-session queue of prompts waiting on a human; `approvalsInboxEnabled`, SYNCED, default OFF: every surface is opt-in; only the store and answer endpoints run regardless, so flipping it ON shows anything already pending): `web/approval-inbox.ts` is a `sessionWaits`-style singleton fed by `/api/hook-event`, holding at most ONE item per session (a new prompt supersedes), claude-mode only, in-memory. Cards are answered via `POST /api/approvals/:id/answer`, which sends a digit / Esc / idle-prompt text through `writeViaMux` (menu answers never carry `\r`). ⚠️ `option` digits are accepted ONLY when they match options parsed from the captured pane frame, and the answer path RE-CAPTURES the pane first (a dialog that no longer parses on screen means the keystroke would land in the composer, so refuse with 409). ⚠️ Resolution on the heuristic `working` signal ALONE is restricted to `idle` items; a permission/question item gets the pane-VERIFIED variant on that same signal (`resolveIfDialogGone()` → `verifyStillAnswerable()`), so the heuristic only decides when to LOOK and the screen decides the outcome. That is what clears a dialog answered in the terminal mid-turn; the other definitive signals are `stop`, `elicitation_complete`/`elicitation_response`, exit/delete, answer, supersede and the 12h TTL. ⚠️ **Viewing a session ACKNOWLEDGES its idle item, it does not resolve it** (`POST /api/approvals/session/:sessionId/viewed` → `acknowledgedAt` → `approval:updated`): the item stays pending (still answerable, still Read My Mind context) and only stops arming the yellow tab alert. That flag is what makes the clear durable, since the view-clears-idle rule used to live in one browser's memory and `seedApprovals()` re-armed the alert on the next reload while other devices never heard about it at all; the local half is `markIdleAlertSeen()` (app.js), called from BOTH `selectSession` paths, including the already-active early return, where a click could otherwise never clear the alert. ⚠️ **Only a HUMAN opening a session acknowledges**: `selectSession(id, { auto: true })` marks the three selections the APP makes (boot restore, a solo window opening its target, the fallback after the active session is closed) and skips the acknowledgement, so a page load cannot silently spend an alert the user never saw. The flag defaults to user-initiated, so an untagged call site fails toward acknowledging rather than toward an alert nothing can clear; `test/session-select-ack-gate.test.ts` pins both the gate and the tagged call sites. Idle-only by construction (`acknowledge()` defaults to `['idle']`): looking at a permission/question dialog does not answer it. ⚠️ Same rule on the input path: `_ackDelivery` (app.js) spends the IDLE alert only, via that same `markIdleAlertSeen()`. It used to `clearPendingHooks(sessionId)` with no kind, so one keystroke wiped a RED alert on that device while the dialog was still up, the other devices stayed red, and a reload re-seeded it. ⚠️ Claude Code fires no "permission answered" hook (only `elicitation_complete`/`elicitation_response`, i.e. the question flavor), so an answered-in-the-terminal dialog would otherwise sit pending until `stop`: `GET /api/approvals` therefore runs a **staleness sweep** over the caller's own items via `verifyStillAnswerable()`, which is deliberately the conservative check the answer path uses (only an item whose ORIGINAL frame parsed options can be dropped, so an unreadable capture keeps the alert rather than losing a live one). ⚠️ **`applyCapture()` is therefore ADD-ONLY for `options`**: a re-capture that parses nothing must never erase a parse an earlier one found. Claude Code delays the Notification hook behind the dialog (measured 6s, documented ~30s), so the 600ms re-capture routinely lands on a frame the user has ALREADY answered; clearing the field there made the item permanently unsweepable, because `verifyStillAnswerable()` reads a MISSING `options` as "we never could read this dialog" and keeps such items answerable by design. The red "needs you" then survived every sweep AND every page reload, went away only on `stop` (2026-08-20: a confirmed question left a tab flowing red for ~8 minutes while the turn ran on), and the stale card still accepted an answer, typing a bare `1` into a composer with no dialog under it. Pinned by `test/approval-inbox.test.ts`. ⚠️ A frame that parses no options is CONCLUSIVE in exactly two cases, and the second one closes the late-hook hole: the item once parsed options (they cannot vanish while the dialog is up), or the frame shows Claude actively running a turn. A modal dialog BLOCKS the turn, so the two cannot coexist — measured on v2.1.237, a live-dialog frame carries neither the `… (13s` timer NOR the `esc to interrupt` footer, which the dialog replaces with `Enter to select · ↑/↓ to navigate · Esc to cancel`. Anything else stays answerable, so an unreadable capture Line truncated
 
 **Read My Mind intent profiles** (phase 1 of `docs/readmymind-plan.md`; `readMyMindEnabled`, SYNCED, default OFF): per-CASE profiles (user-stated `goals` + the user's recent real prompts), keyed by owner + realpath(workingDir) so they survive `/clear`/respawns and multi-user scoping is structural. Capture rides the transcript (`transcript:user_prompt` from `transcript-watcher.ts`), NOT the input paths: `POST /input` sees only programmatic prompts and the WS channel is raw keystrokes. The listener lives inside `startTranscriptWatcher()`'s `if (!watcher)` block (outside it would duplicate per hook event) and is claude-only + gated on the setting per event. Store: `src/intent-store.ts` singleton, `intents.json` written 0600 tmp+rename (prompts can contain secrets; never fed to `/api/search`). Endpoints: GET/PUT/DELETE `/api/sessions/:id/intent` + POST `/api/sessions/:id/readmymind` (`readmymind-routes.ts`, ownership via `findSessionOrFail` WITH `req`; registrations stay the bare `app.<method>('path')` shape, the endpoints.md drift scanner cannot see generics). **Phase 2 (predictor + 🧠 button)**: `readmymind-context.ts` is the PURE budgeted assembler (9 ranked sources, drop order siblings→away→workspace→tools, sections 1-4 truncate only); IO lives in `readmymind-collectors.ts` (transcript TAIL read — the live watcher keeps only a 500-char snippet — + git signals, skipped for remote-SSH cases) and the route; `readmymind-predictor.ts` reuses the AiCheckerBase spawn mechanics standalone (verdict-shaped base vs freeform JSON) as a mutable singleton routes call and tests stub. Claude-mode only (400), one in flight per session (409 CONFLICT), model = `readMyMindModel` setting defaulting to `AI_CHECK_MODEL` (opus, decided). Frontend `readmymind-ui.js`: header 🧠 marker-hidden (`btn-readmymind--hidden`) until the setting is ON; phones hide it in mobile.css and get a keyboard-accessory 🧠 key instead (ships in BOTH bar templates, revealed by the `rmm-enabled` class on the BAR element — setMode() rebuilds button innerHTML, so per-key state would be wiped; synced at init + every `applyHeaderVisibilitySettings()`). Alternate suggestions render as tappable rows that swap into the editable field without losing edits; Rethink rejects the whole shown set and carries the optional steer note (`#readMyMindSteer`, sent as `steer`, shown in ready + empty-result phases, cleared on each open). Suggestions render via value/`textContent` ONLY and Send/Insert go through `POST /input` (server-side, so the sendEnterKey/local-echo trap does not apply) — nothing auto-sends, ever. User guide: `docs/readmymind.md`.
 
@@ -221,10 +237,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Circuit breakers**: the Ralph breaker prevents respawn thrashing (`CLOSED` → `HALF_OPEN` → `OPEN`; reset via `/api/sessions/:id/ralph-circuit-breaker/reset`). **Distinct: the PTY-exit breaker** (`session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits and blocks auto-restarts. ⚠️ It resets ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive`; the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. → [architecture-invariants#circuit-breakers-ralph--pty-exit](docs/architecture-invariants.md#circuit-breakers-ralph-and-pty-exit)
 
-**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. The first load of EACH session per page load requests `full=1` (`_fullHistoryLoaded` Set); tab switches keep the cheap `?tail=` path, and scrolling up at the TOP of the buffer re-pulls `full=1` on demand (cooldown-guarded — tmux repaints bursty output in place, so browser scrollback shrinks while tmux's history stays complete). ⚠️ That re-pull must never DOWNGRADE the buffer: a repaint-mode CLI pane keeps no tmux history, so its capture is one frame and the reset+rewrite would delete history mid-scroll — `_replayWouldShrinkBuffer()` refuses it and slows that session's cooldown to 60s. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
+**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set); Shell selection and automatic drop recovery always use a bounded 1 MiB `?tail=` window. Shell loads the rest only when **Load full history** is pressed; ordinary scrolling must not trigger a multi-megabyte reset+replay on xterm's main thread. Other modes may re-pull at the TOP (cooldown-guarded — tmux repaints bursty output in place, so browser scrollback shrinks while tmux's history stays complete). Live writes are one-chunk-in-flight, released by xterm's parse callback, so xterm's private queue cannot bypass the browser's 128 KiB render cap. While WebSocket owns terminal I/O, duplicate SSE terminal events are dropped before JSON parsing, and recovery is single-flight per active session. ⚠️ A full re-pull must never DOWNGRADE the buffer: a repaint-mode CLI pane keeps no tmux history, so its capture is one frame and the reset+rewrite would delete history mid-scroll — `_replayWouldShrinkBuffer()` refuses it and slows that session's cooldown to 60s. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
 
-**Terminal scrollback strip + wheel/touch forwarding** (#205): codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed shell/opencode/antigravity get a NARROW strip (alt-screen toggles only — it removes tmux's own attach-time `smcup`, which otherwise parks xterm in the scrollback-less alt buffer and turns the wheel into arrow keys). ⚠️ Gated on `useMux`: direct-PTY fallback sessions must keep the alt screen for vim/less/htop. Wheel AND touch forward to the CLI transcript for **claude ≥ 2.1.187 ONLY** at ANY scroll position (snap-to-bottom first); Shift+wheel and the `terminalWheelLocalScrollback` setting stay local. ⚠️ Codex was in that list and must never go back without a fresh measurement: codex-cli 0.147.0 ignores SGR wheel reports entirely (`mouse_any_flag=0`, inline viewport, transcript pushed into terminal scrollback), so forwarding produced a dead wheel (#227 follow-up). `_wheelScrollLines()` reads `ev.deltaMode` (Firefox = LINE units). ⚠️ When that gate is FALSE on a claude session whose local buffer is hollow (`baseY === 0`), the gesture becomes coalesced PageUp/PageDown key sends (`_maybePageCliTranscript`) instead of a no-op; ⚠️ and `getClaudeCliVersion()` must never cache a FAILED probe (one timeout used to disable forwarding process-wide until restart). `_logScrollRouting()` prints the routing decision and its inputs once per session — read it before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding)
+**Terminal touch gestures: link taps and text selection**: on a touch device xterm's own handlers see neither — `touch-action: none` plus touchstart's preventDefault suppress the browser's compatibility mouse events, `_installMobileTapMouseGuard` drops the trusted ones that still arrive, and the synthetic `mousedown`/`mouseup` pair dispatched for mouse REPORTING goes to the `.xterm` root, an ANCESTOR of the screen element the linkifier and SelectionService listen on. So both gestures are driven explicitly. ⚠️ **A tap activates the link under it** through the SAME provider that feeds the hover linkifier (`_terminalLinkAtPoint`, containment mirroring xterm's `_linkAtPosition`), synchronously inside `touchend` — that is what keeps the user gesture `window.open` needs — and BEFORE any mouse report, mirroring `_handleDesktopTerminalClick`'s skip for a hovered link. Two rows keep their meaning: the caret's logical line (`_tapIsOnCaretLine`, where a tap places the cursor in text the USER typed) and TUI-owned rows (`_isActionableMobileTerminalTap`, answering a dialog). ⚠️ The caret line is the boundary rather than the tap INTENT, because a shell classifies every tap as `'input'` and gating on that would leave every URL in shell output inert. ⚠️ **Long-press selects** by driving xterm's public `select()` (renderer-independent — under WebGL the glyphs are pixels and native selection cannot exist), drag or a further tap extends, and Copy goes through `copyTerminalSelection()` for its execCommand fallback on plain-HTTP installs. Three guards are load-bearing and each came from a real phone: the compat mouse pair after `touchend` (xterm focuses on mousedown and SelectionService resets the model there, so the keyboard sprang up and the selection vanished on lift), the platform's own ~500ms long-press (Android Chrome focuses the nearest editable element — the helper textarea — through no event a handler can preventDefault, so a bounded focus guard blurs it and `contextmenu` is suppressed for the gesture window), and `copyTerminalSelection()`'s closing `terminal.focus()` (right on desktop, wrong on a phone). Tests: `test/terminal-touch-tap.test.ts`.
 
+**Auto Copy (copy-on-select)** (`autoCopySelection`, per-device, default OFF): a finished terminal selection lands on the clipboard with no keystroke. ⚠️ It fires at the END of a gesture, never in `onSelectionChange` (that callback runs per cell crossed, so copying there is one clipboard write per mouse move); it only ARMS `_autoCopyPending`, and a document-level `mouseup` listener flushes. ⚠️ The flush is SYNCHRONOUS inside the handler because both clipboard paths need user activation (Firefox gates `navigator.clipboard.writeText` on it, and the plain-HTTP `execCommand` fallback must run in the gesture's own task); a timer or a wait for `onSelectionChange` loses it, invisibly in Chrome. ⚠️ Touch needs its OWN calls from `_endTouchSelectionGesture()`/`_selectTouchSelectionLine()`: that path `preventDefault()`s its touchend, so no mouseup ever arrives and the toggle would be dead on phones. ⚠️ Unlike `copyTerminalSelection()` it must NOT clear the selection (the text would vanish under the cursor that highlighted it) and must NOT focus the terminal (that opens the on-screen keyboard over it); focus is RESTORED to whatever held it, which only matters for the `execCommand` fallback. Guards are pure in `decideAutoCopy()` (constants.js): off, blank/whitespace-only, and a 1M-char cap (an autoscrolling drag can sweep the whole 50k-line scrollback), refused rather than truncated with a toast pointing at Ctrl+C. Silent on success except once per page load; failures toast, throttled 10s. Tests: `test/terminal-auto-copy.test.ts`.
+
+**Terminal scrollback strip + wheel/touch forwarding** (#205): codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed shell/opencode/antigravity/omp get a NARROW strip (alt-screen toggles only — it removes tmux's own attach-time `smcup`, which otherwise parks xterm in the scrollback-less alt buffer and turns the wheel into arrow keys). ⚠️ Gated on `useMux`: direct-PTY fallback sessions must keep the alt screen for vim/less/htop. Wheel AND touch forward to the CLI transcript for **claude ≥ 2.1.187 ONLY** at ANY scroll position (snap-to-bottom first); Shift+wheel and the `terminalWheelLocalScrollback` setting stay local. ⚠️ Codex was in that list and must never go back without a fresh measurement: codex-cli 0.147.0 ignores SGR wheel reports entirely (`mouse_any_flag=0`, inline viewport, transcript pushed into terminal scrollback), so forwarding produced a dead wheel (#227 follow-up). `_wheelScrollLines()` reads `ev.deltaMode` (Firefox = LINE units). ⚠️ When that gate is FALSE on a claude session whose local buffer is hollow (`baseY === 0`), the gesture becomes coalesced PageUp/PageDown key sends (`_maybePageCliTranscript`) instead of a no-op; ⚠️ and `getClaudeCliVersion()` must never cache a FAILED probe (one timeout used to disable forwarding process-wide until restart). ⚠️ **A click is hand-reported to the CLI only while the CLI actually has mouse tracking on.** The full strip removes the mouse DECSETs, so xterm's `mouseTrackingMode` is permanently `none` there and the browser hand-encodes SGR reports (`_sendSyntheticSgrTap`); without state it did that on EVERY click, so a stripped-mode pane running a plain shell (CLI exited, or a shell started inside a claude-mode session) received reports it never asked for and printed them as literal text (`[<0;88;20M`), garbling the next typed line. `_recordStrippedMouseMode()` (session.ts) records what the strip removes, `toState()` publishes `cliMouseTracking`, and `_shouldReportMouseToCli()` gates all three report sites on it. Only 1000/1001/1002/1003 count (1005/1006 are encodings, 1007 is alt-scroll), and the change broadcasts UNdebounced since a dialog can be clicked inside the 500ms window. `_logScrollRouting()` prints the routing decision and its inputs once per session — read it before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding)
 **Detached start + service install** (issue #231): `codeman web -d` relaunches the SAME entry script with `detached:true` (setsid), so there is no controlling terminal and no shell job entry. ⚠️ `nohup` is NOT what makes this work: Node re-arms SIGHUP to its default disposition even when it inherits "ignore", and `cli.ts` handles SIGHUP with a graceful shutdown, so a delivered HUP still stops the server. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile check + `/api/status` probe): a second instance on the shared tmux socket attaches PTYs to the first one's live sessions. ⚠️ Neither may report success it has not observed — the parent polls `/api/status` until the child answers or dies, since `launchctl load` and a clean spawn are both silent about a server that starts and immediately exits. `--stop` verifies the pid still LOOKS like a Codeman server (`ps -o command=`) before signalling, because pids get recycled. Unit/label names live in `config/service-names.ts` so install.sh, `detectSupervisor()` and `service install` cannot drift into supervising two copies; they are instance-scoped, and identical to the historical names for the default instance. `service install` bakes the installing shell's PATH into the unit (launchd gives a job `/usr/bin:/bin:/usr/sbin:/sbin`, which finds neither a Homebrew/nvm `node` nor `tmux`/`claude`) and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install)
 
 **Self-update** (App Settings → System → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
@@ -237,6 +256,8 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **File Viewer edit mode** (issue #212): the file-preview overlay edits workspace text files in place — `GET .../file-content?edit=1` + `PUT /api/sessions/:id/file-content`, policy in `src/config/file-editing.ts`. This is a **third file surface and the only one that WRITES**: read-path confinement (realpath + workspace + ownership) plus sensitive/blocked/`.git` denies and an extension **allowlist**; writes are `wx`-temp + rename (no `O_CREAT` anywhere = edit-in-place is structural); optimistic concurrency via sha256 `baseHash` → 409. ⚠️ `edit=1` never truncates and the client must never save a plain-preview buffer (the 500-line truncation would silently delete the rest). ⚠️ CRLF/UTF-8 guards: EOL re-applied server-side, non-UTF-8 refused via round-trip compare. → [architecture-invariants#file-viewer-edit-mode](docs/architecture-invariants.md#file-viewer-edit-mode), `docs/file-viewer-edit-plan.md`
 
+**Files panel search** (COD-236, the `q` param on `GET /api/sessions/:id/files`): `compileFileQuery()` (`utils/file-query.ts`, pure, no IO, so it unit-tests directly) compiles the query into a reusable predicate, which is what lets the server-side walk prune instead of streaming the whole tree. ⚠️ **A query turns that endpoint into a FLAT match list rather than a nested tree**, and the walk deliberately recurses past non-matching directories, since the whole point of searching is to reach a file whose ancestors do not match. An empty or whitespace-only query compiles to `null`, which is what keeps the default tree response byte-identical when no search is requested. ⚠️ **Globs are never compiled into a RegExp**: `*a*a*a…` translated to `^.*a.*a.*a…$` is a classic backtracking blowup evaluated synchronously against every walked path, so one pathological query would freeze the event loop for the whole server (the same reason `search-service.ts` is regex-free). `globMatch()` is a two-pointer wildcard walk instead, O(text · pattern) with both operands short by construction, and an overlong query (`MAX_QUERY_LENGTH`, 256) also compiles to `null` rather than running. A query containing `/` matches the relative path, otherwise the bare entry name; globs match anchored and case-insensitively (`*` spans any run, slashes included, `?` exactly one character), everything else is a plain case-insensitive substring.
+
 **Raw file bodies are streamed and range-aware**: `file-raw` and the attachments `/raw` route always advertise `Accept-Ranges: bytes` and answer a `Range` header with `206` + `Content-Range` (single-range only; parser is pure + unit-tested in `src/web/http-range.ts`, a malformed spec is ignored → 200 while an out-of-bounds one is a 416). ⚠️ A 200-only response is what made the File Viewer's `<video>` unseekable: Chrome then reports `video.seekable` as `[0, 0]`, the scrub bar is inert and `currentTime = x` silently reverts (measured on an 18MB mp4), and Safari refuses to start the media at all. ⚠️ These bodies go out through `reply.hijack()`, which bypasses Fastify's status handling — `sendRawStream` must copy the status onto `reply.raw` by hand or a partial body ships labelled `200` and the browser treats a slice as the whole file. ⚠️ Closing the preview must **pause and unload** the media (`_stopFilePreviewMedia` in panels-ui.js): dropping the overlay's `visible` class is `display:none` and nothing else, and a DETACHED `HTMLMediaElement` keeps playing, which is how the X button used to leave a video audible with no player to pause.
 
 **Ultracode / workflow-run visualization** (opt-in, default OFF): the Workflow tool writes a completion artifact only at run *end*, so live in-flight runs exist solely as transcript dirs. `workflow-run-watcher.ts` therefore synthesizes ACTIVE runs from transcripts until the completion artifact appears and supersedes them. It is **STANDALONE** and deliberately never imports or touches `subagent-watcher.ts`, despite reading the same tree. Two independent toggles: `showUltracodeAgents` (docked panel) and `ultracodeFloatingWindows` (floating windows); the watcher starts if **either** is on. → [architecture-invariants#ultracode--workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)
@@ -245,7 +266,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. PAST sessions (#261) come from `session-history-index.ts`, a capped snapshot of the unified list filled **outside** the request path (`/api/sessions/unified` publishes it; a stale one is rebuilt fire-and-forget), that indirection is what keeps the no-fs property. ⚠️ The snapshot is stored UNSCOPED with a per-row owner and MUST be re-filtered through `canAccessOwned()` on read; history rows carry `jumpTo.kind:'resume-session'`, since a closed session has no tab to select. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
 
-**Web tabs** (dashboard URLs as tabs): a saved URL renders as a tab beside agent sessions. **NOT a sixth `SessionMode`** (no PTY, no tmux, no respawn), same reasoning that keeps Docker/remote-SSH as case overlays. Dashboards are **proxied through Codeman's own origin** by default, because a direct iframe fails three ways at once: prod is HTTPS so `http://` targets are blocked as mixed content, many dashboards send `X-Frame-Options: DENY`, and our own `default-src 'self'` CSP blocks cross-origin frames. Proxying leaves the prod CSP unchanged (`/webview/...` is `'self'`). ⚠️ The proxy is **NOT an API surface**: it authenticates on an in-memory capability in the path and is correspondingly exempt from the cookie + Origin checks; that exemption is fenced to safe methods and non-`/api` paths and is pinned by `test/webview-auth-exemption.test.ts`. ⚠️ Iframes omit `allow-same-origin` unless a dashboard is explicitly marked `trusted`, and `Authorization`/`codeman_session` are stripped upstream in **both** modes so `CODEMAN_PASSWORD` cannot leak. ⚠️ A sandboxed frame is **opaque-origin**, which breaks two things `curl` can never reproduce: its runtime-built root-absolute URLs escape `<base>` (fixed by an injected `runtimeUrlShim()`), and its same-host `fetch`/XHR are CORS-checked with `Origin: null` (fixed by `buildProxyCorsHeaders()` plus exempting the proxy from the global `OPTIONS`-204 short-circuit in `registerSecurityHeaders`). Both present as the dashboard's own "Failed to fetch" while the page renders fine. → [architecture-invariants#web-tabs](docs/architecture-invariants.md#web-tabs), `docs/web-tabs.md`
+**Web tabs** (dashboard URLs as tabs): a saved URL renders as a tab beside agent sessions. **NOT a `SessionMode` of its own** (no PTY, no tmux, no respawn), same reasoning that keeps Docker/remote-SSH as case overlays. Dashboards are **proxied through Codeman's own origin** by default, because a direct iframe fails three ways at once: prod is HTTPS so `http://` targets are blocked as mixed content, many dashboards send `X-Frame-Options: DENY`, and our own `default-src 'self'` CSP blocks cross-origin frames. Proxying leaves the prod CSP unchanged (`/webview/...` is `'self'`). ⚠️ The proxy is **NOT an API surface**: it authenticates on an in-memory capability in the path and is correspondingly exempt from the cookie + Origin checks; that exemption is fenced to safe methods and non-`/api` paths and is pinned by `test/webview-auth-exemption.test.ts`. ⚠️ Iframes omit `allow-same-origin` unless a dashboard is explicitly marked `trusted`, and `Authorization`/`codeman_session` are stripped upstream in **both** modes so `CODEMAN_PASSWORD` cannot leak. ⚠️ A sandboxed frame is **opaque-origin**, which breaks two things `curl` can never reproduce: its runtime-built root-absolute URLs escape `<base>` (fixed by an injected `runtimeUrlShim()`), and its same-host `fetch`/XHR are CORS-checked with `Origin: null` (fixed by `buildProxyCorsHeaders()` plus exempting the proxy from the global `OPTIONS`-204 short-circuit in `registerSecurityHeaders`). Both present as the dashboard's own "Failed to fetch" while the page renders fine. → [architecture-invariants#web-tabs](docs/architecture-invariants.md#web-tabs), `docs/web-tabs.md`
 
 **Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default): named users with scrypt-hashed passwords in `~/.codeman/users.json`. Gated everywhere by `isMultiUserMode()`; when OFF, behavior is byte-identical to single-user because every scoping helper short-circuits. ⚠️ **Not a security boundary at the agent layer**: every session still runs as the SAME OS account. This separates WORKSPACES; it does not sandbox users (Docker cases are the isolation story). Ownership threads through `Session.owner` and is enforced in `findSessionOrFail`, list endpoints, SSE routing (fail-closed), WS, search, and file-preview. → [architecture-invariants#multi-user-mode](docs/architecture-invariants.md#multi-user-mode), `docs/multi-user-plan.md`
 
@@ -257,13 +278,13 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Frontend
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `readmymind-ui.js`(11.3) → `ultracode-panel.js`(11.5) → `approvals-ui.js`(11.6) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `webview-tabs.js`(12.5) → `mobile-overview.js`(12.55) → `home-sessions.js`(12.56) → `entrance-animations.js`(12.6) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `session-lineage.js`(15.6) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `tab-rail-resize.js`(6.5) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `readmymind-ui.js`(11.3) → `ultracode-panel.js`(11.5) → `approvals-ui.js`(11.6) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `webview-tabs.js`(12.5) → `mobile-overview.js`(12.55) → `home-sessions.js`(12.56) → `entrance-animations.js`(12.6) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `session-lineage.js`(15.6) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
 
 **Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for the four things that appear when work starts, chosen per surface via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` on `<html>`. Defaults are the `legacy` theme, so an untouched install behaves exactly as before and every hook short-circuits on its first line. ⚠️ Tabs and connection lines are **destroyed mid-animation** on every re-render (`_fullRenderSessionTabs()` replaces the strip's innerHTML; `_updateConnectionLinesImmediate()` does `svg.innerHTML = ''`), so both are tracked by id and re-applied to the fresh element with a **negative `animation-delay`** to resume rather than restart. ⚠️ The terminal-pane styles may animate **transform / opacity / clip-path only**, xterm's FitAddon derives rows+cols from `getComputedStyle(parent).width/height`, so animating width/height/padding there would resize the PTY. ⚠️ Window styles other than `beam` transform the window, which moves the rect its connection line is aimed at; `beam` deliberately animates opacity/filter only so its line can draw toward a stable target. Persisted to its own `codeman:*Anim` localStorage keys (per-device, deliberately NOT in the `.strict()` `SettingsUpdateSchema`); picker in App Settings → Appearance, full per-surface lab at `?animlab=1`.
 
 **Mobile tab strip scrolling** (issue #257): under 768px the tab strip is a horizontal scroller (desktop wraps to a second row instead), so the active tab can sit off-screen. Three rules keep it reachable and they only work together: `_updateActiveTabImmediate()` scrolls the selected tab into view via `computeTabScrollLeft()` (pure, in constants.js) using **rect math on the strip's own `scrollLeft`**, never `scrollIntoView()`, which would also scroll the document under a fixed header; `_fullRenderSessionTabs()` **restores `scrollLeft`** across the `innerHTML` rebuild, since ambient rebuilds (a task badge appearing, a session created elsewhere) otherwise snap a mid-swipe strip back to 0; and it re-reveals the active tab **only when it changed** (`_lastRenderedActiveTabId`), so browsing the far end of the strip is not undone by background renders. ⚠️ **The ACTIVE tab is the only one with action icons, and on a phone they can eat it**: `.session-tab.active .tab-name` reserves `min-width: 44px` in the ≤430px block, because a short session name rendered a 13px label against a 50px gear+close cluster, putting the tab's geometric CENTRE on the gear, so a thumb aiming at the tab opened Session Options instead of switching (measured at 360/393/430px; only long names cleared it). ⚠️ **The floor is set by the 10th tab onward, not by the tabs you can see**: `.tab-number` renders only for `_tabIdx < 9`, so tab 10 loses 16px + a gap off its left and its centre sits 10px further right. The centre clears the icons when `reserved > icons + rightEdge - leftRunUp - gap` (= 50 + 9 - 17 - 4 = **38px**), hit-testing snaps to whole pixels so 39px still lands on the gear, and the practical floor is 40px — a NUMBERED tab clears it at 20px, which is exactly why reasoning from the tabs on screen would put the centre back on the gear. `test/mobile-tab-tap-zones.test.ts` recomputes that inequality from the stylesheet, so widening the gear or the padding fails there rather than on a phone. The guarantee is centre-off-the-ICONS, not centre-inside-the-label (on a numberless tab it lands in the gap between them, which still switches). Non-active tabs keep their icons hidden and stay tappable end to end. ⚠️ Mobile no longer hoists the active session to the front of the strip: that reordering ran on full renders only, so tab order flipped depending on which render path fired, and it renumbered the Alt+N badges. Scroll-into-view replaces it; do not reintroduce it.
 
-**Session list layout: header strip or left sidebar** (`sessionListLayout`, App Settings → Appearance → Tabs, default `header`; per-device policy — it IS in `SettingsUpdateSchema` and persists server-side, but `displayKeys` makes a device keep its own value): with many sessions the horizontal strip stops being scannable, so the list can move into a vertical `<aside>` with a filter box and a live count, collapsible to a 44px rail (`--sidebar-width` 260 / `--sidebar-width-collapsed` 44) via **Alt+B** (`toggleSessionSidebar`; Alt, not Ctrl+B, which must reach tmux/readline in the terminal). ⚠️ **There is ONE `#sessionTabs` element and it is MOVED between two hosts** (`#sessionTabsHost` in the header, `#sessionSidebarList` in the aside), never a second list — so every render path, drag-reorder handler and Alt+N index keeps working unchanged, and `applySessionListLayout()` is the only thing that reparents it. ⚠️ It sets `data-session-list` / `data-sidebar` on `<html>` and must run BEFORE `applyTabWrapSettings()`, which is the one owner of `tabs-two-rows`/`tabs-show-folder` and reads those attributes. ⚠️ Leaving sidebar mode **clears `_sidebarFilter`**: the filter box only exists in the aside, so a stale filter would hide sessions from the header strip with no reachable control to clear it. ⚠️ On handhelds the aside is an off-canvas overlay rather than a docked rail, and a closed drawer keeps `display: flex`, so it is marked `inert` + `aria-hidden` (`_isSessionSidebarOverlay()`) or its filter box and ~4 tab stops per session stay in the tab order; the DOCKED desktop rail must never be inerted, its rows are still clickable. The desktop home rail (`home-sessions.js`) defers to it, since both dock the session list flush left.
+**Session list layout: header strip or left sidebar** (`sessionListLayout`, App Settings → Appearance → Tabs, default `header`; per-device policy — it IS in `SettingsUpdateSchema` and persists server-side, but `displayKeys` makes a device keep its own value): with many sessions the horizontal strip stops being scannable, so the list can move into a vertical `<aside>` with a filter box and a live count, collapsible to a 44px rail (`--sidebar-width` 260 / `--sidebar-width-collapsed` 44) via **Alt+B** (`toggleSessionSidebar`; Alt, not Ctrl+B, which must reach tmux/readline in the terminal). ⚠️ **There is ONE `#sessionTabs` element and it is MOVED between hosts** (`#sessionTabsHost` in the header, `#sessionSidebarList` in the aside, `#tabRail` for the vertical rail below), never a second list — so every render path, drag-reorder handler and Alt+N index keeps working unchanged. Exactly TWO functions reparent it and they must run in this order: `applySessionListLayout()` first (sidebar wins), then `applyTabOrientation()` (settings-ui.js), which moves the tabs into `#tabRail` only when the sidebar does not own them. ⚠️ It sets `data-session-list` / `data-sidebar` on `<html>` and must run BEFORE `applyTabWrapSettings()`, which is the one owner of `tabs-two-rows`/`tabs-show-folder` and reads those attributes. ⚠️ **The vertical tab rail** (`tabOrientation`/`tabRailWidth`/`sessionSidebarFontSize`, all per-device display keys that ARE in the schema, like `sessionListLayout`) is a SECOND vertical list next to the sidebar: the orientation setting is silently ignored while the sidebar layout is chosen, desktop/tablet only (`resolveTabOrientation` forces horizontal on mobile), resizable via `tab-rail-resize.js` (which owns terminal refits during the drag). ⚠️ **Detailed rows are a property of a vertical LIST, not of one surface** (`sessionListLayout: 'sidebar-rich'` for the sidebar, `tabRailDetail: 'rich'|'simple'` for the rail, rail default **rich**): both draw the home screen's per-session line (`created 3d ago · working 12m`) plus a status pill, from the SAME row model (`_sidebarRichRow`/`_sidebarRichMetaHTML` in app.js, classified by `_mobileOverviewState`/`_mobileOverviewSince`), and the render paths ask ONE gate, `isRichTabRows()` (= `isSessionSidebarRich() || isTabRailRich()`). ⚠️ Detail rides on its own attribute (`data-sidebar-detail` / `data-tab-rail-detail`) so every existing `[data-session-list="sidebar"]` / `[data-tab-orientation='vertical']` rule keeps matching both variants untouched; a flip of detail ALONE still needs a full render (the stamps line is emitted by the row template, not toggled by CSS) and must re-run `applyTabWrapSettings()`, which owns the folder line and is now rail-aware. ⚠️ The rich CSS rules carry a rail twin as a COMMA-GROUPED selector, never `:is()` (an `:is()` list takes its most specific argument, which would lift the sidebar arm from (0,3,1) to the rail's (0,5,1)). ⚠️ Width is the whole reason there are thresholds: the rich sidebar is 300px (`--sidebar-width-rich`) and a rail that has never been sized defaults to **320** (`RICH_DEFAULT_WIDTH`, the existing Wide preset) instead of 256, because at 256 the stamps line ellipsizes mid-word; a user-narrowed rail drops the created stamp below 288 (`tab-rail-tight`, CSS only) and drops rich rows entirely below 240 (`tab-rail-compact`, which re-renders). A stored width is never overridden. ⚠️ Only detailed rows carry stamps that go stale with no event behind them, so `_startSidebarRichClock()` (20s, rewrites text in place — a re-render would restart every row's animation) must be armed and disarmed by BOTH `applySessionListLayout()` and `applyTabOrientation()`. ⚠️ **Axis decisions must use `_isVerticalTabList()`** (sidebar OR rail), never `isSessionSidebarActive()` alone: the rail leaves `data-session-list` at `header`, and the sidebar-only predicate shipped four rail bugs at once (drag insertion side read from clientX, active tab never scrolled into view, floating windows anchored below tabs instead of beside them, connector redraws skipped on rail scroll). The pre-paint script stamps `data-tab-orientation` (+ `--tab-rail-width`) like it stamps the sidebar keys, or vertical mode flashes through the header strip; the name font size defaults to 12px, the sidebar's historical size, so untouched installs are never restyled. ⚠️ Leaving sidebar mode **clears `_sidebarFilter`**: the filter box only exists in the aside, so a stale filter would hide sessions from the header strip with no reachable control to clear it. ⚠️ On handhelds the aside is an off-canvas overlay rather than a docked rail, and a closed drawer keeps `display: flex`, so it is marked `inert` + `aria-hidden` (`_isSessionSidebarOverlay()`) or its filter box and ~4 tab stops per session stay in the tab order; the DOCKED desktop rail must never be inerted, its rows are still clickable. The desktop home rail (`home-sessions.js`) dLine truncated
 
 **Phone overview home screen** (`mobile-overview.js`, phones only, per-device `mobileOverviewEnabled`, default ON): under 430px the "C" logo shows a session overview (NEEDS YOU / CURRENT SESSIONS / PAST SESSIONS) instead of the welcome overlay; tablet and desktop are unchanged. The branch lives in `showWelcome()`/`hideWelcome()` (terminal-ui.js) behind `shouldUseMobileOverview()`, which is **width-driven** (`getDeviceType() === 'mobile'`) because this is a layout decision, unlike the settings namespace which stays handheld-based. ⚠️ The container ships with the `hidden` attribute and only this module removes it: never give `.mobile-overview` a bare `display` rule, since desktop does not load `mobile.css` (`media="(max-width: 1023px)"`) and would then render it unstyled. Live re-renders ride on the tail of `_renderSessionTabsImmediate()` (every state change it needs already funnels there); PAST rows come from one `_fetchUnifiedSessions(60)` per home-screen visit and resume through the shared `resumeHistorySession()`, so they behave exactly like the welcome screen's Resume list. ⚠️ Two things must stay in lockstep with surfaces outside this module, because divergence reads as a bug rather than a style: the split Run button carries the **toolbar's own classes** (`btn-toolbar btn-run mode-<backend>` / `btn-run-gear`) so the per-backend gradient and the light-skin overrides apply unchanged (mobile.css must therefore set no `background`/`color` on it), and row status uses the **session-tab language** (green dot when fine, `pulse` while working, yellow blinking row when waiting for input, red blinking row when a question is pending, mirroring `tab-alert-idle`/`tab-alert-action`). The picker mirrors the toolbar run-mode menu (`setRunMode()` + `run()`, `openWebviewFromMenu()` for saved dashboards) and deliberately omits its Recent-Sessions block, since PAST SESSIONS is that. Status pills carry `data-i18n-skip` (generic words like "idle" collide with state strings elsewhere).
 
@@ -303,7 +324,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **SSE staleness watchdog** (`computeSseStale()` in constants.js, `_checkSseStale()` + a 5s interval in app.js): an `EventSource` that stops delivering does not always error, so `onerror` never fires, the header dot stays green, and every SSE-driven surface (tab status dots, sessions created on another device, renames) freezes until the user reloads. ⚠️ The 15s server keepalive was an SSE **comment** (`:keepalive`), and comments are **invisible to `EventSource` by spec**, so there was nothing a client could observe: it is now the named `sse:heartbeat` event (`cleanupDeadClients()`, sse-stream-manager.ts), which is exactly why the frame had to change type. ⚠️ Staleness is judged **only while the status is `connected`** and the device is online; that guard is the loop breaker, since a forced `connectSSE()` leaves `connected` immediately and cannot re-fire while a reconnect is in flight. ⚠️ The liveness stamp is applied inside `addListener` itself, so every registered handler (the `_SSE_HANDLER_MAP` wrappers AND the directly-registered ones) feeds it from one place; the heartbeat's own listener is a no-op that exists **only** to be registered, since `EventSource` drops named events nobody listens for. ⚠️ The watchdog interval is cleared at the top of `connectSSE()` and nowhere else (its only teardown path); clearing it elsewhere stacks intervals. Recovery needs no new sync path: the reconnect re-runs `handleInit` → `_resetAllAppState()`. The forced reconnect logs one diagnostic line, because a middlebox that strips heartbeats presents as "silently reconnects every 45s".
 
-**Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried), log viewers (2000), connection-loss overlay (2500, above the fixed header and modals), image popups (3000), response viewer (5000, backdrop 4999), file-preview overlay (5100 — must outrank the response viewer, which can launch it; at its old 2000 a path clicked in the chat opened BEHIND the chat), toasts/path picker (10000+, deliberately above the preview), local echo overlay (7).
+**Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried), log viewers (2000), connection-loss overlay (2500, above the fixed header and modals), image popups (3000), response viewer (5000, backdrop 4999), file-preview overlay (5100 — must outrank the response viewer, which can launch it; at its old 2000 a path clicked in the chat opened BEHIND the chat), toasts/path picker (10000+, deliberately above the preview), terminal touch-selection bar (900 — above terminal content and the local-echo overlay, deliberately BELOW floating agent windows so it can never cover their controls), local echo overlay (7).
 
 **Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).
 
@@ -324,18 +345,18 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 | **Rate limit**    | 10 failed auth/IP → 429 (15min decay). QR and hook-secret have separate buckets, so neither can lock out login                                                                                              |
 | **Hook bypass**   | `/api/hook-event` + `/api/status-telemetry` skip Basic auth (localhost-only, schema-validated), but when auth is active the loopback bypass requires `X-Codeman-Hook-Secret` **unconditionally** (Codeman cannot detect a user's own loopback reverse proxy) |
 | **Tunnel**        | Enabling a tunnel **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` or the per-request `acknowledgeUnauthTunnel:true` action field (never persisted) |
-| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`/`ANTIGRAVITY_*`)                                                        |
+| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`/`ANTIGRAVITY_*`/`PI_*`/`GROK_*`/`XAI_*`/`DSH_*`/`DEEPSEEK_*`)                                                        |
 | **Headers**       | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS                                                                                                                                                     |
 
 **Security-relevant env vars**: `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies; bare `.suffix` matches subdomains), `CODEMAN_DOCKER_BRIDGE_HOOKS=1` (opt-in hooks-only listener on the docker bridge gateway).
 
 ### SSE Event Registry
 
-155 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync**, and `test/sse-registry-parity.test.ts` is the guard that pins it (currently exactly in sync, 155 = 155, no drift either direction). The backend file's `@fileoverview` carries the per-category breakdown.
+157 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync**, and `test/sse-registry-parity.test.ts` is the guard that pins it (currently exactly in sync, 157 = 157, no drift either direction). ⚠️ `hook:agent_working` is the one hook event with no Claude Code hook behind it — the DeepSeek status bridge reports it (see External CLI modes). The backend file's `@fileoverview` carries the per-category breakdown, including the two Web tab events.
 
 ### API Routes
 
-~217 handlers across 24 route files in `src/web/routes/`: system (48), sessions (34), cases (29), files (17), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), webviews (6 + the `/webview/:cap/*` proxy), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), approvals (4), readmymind (4), me (2), teams (2), search (1), hooks (1), clipboard (1), status-telemetry (1), voice (1 + the `/ws/voice/stream` relay), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+~227 handlers across 25 route files in `src/web/routes/`: system (56), sessions (34), cases (29), files (17), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), webviews (6 + the `/webview/:cap/*` proxy), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), approvals (4), readmymind (4), me (2), teams (2), tab-layout (2), search (1), hooks (1), clipboard (1), status-telemetry (1), voice (1 + the `/ws/voice/stream` relay), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
 
 **HTTP contract** (stable since 0.9.x, see `docs/versioning-policy.md`; full envelope/status/error-code/SSE spec in `docs/api-reference.md`): responses use the `ApiResponse<T>` envelope — `{ success: true, data? }` or `{ success: false, error, errorCode }` (`src/types/api.ts`). `/api/v1/*` is a versioned alias of `/api/*` (URL rewrite in `server.ts`).
 
@@ -353,7 +374,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
 
 **Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored.
 
@@ -410,12 +431,12 @@ Mobile screenshots: `~/.codeman/screenshots/`, accessed via `GET/POST /api/scree
 
 Target: 20 sessions, 50 agent windows at 60fps. Limits live in `src/config/` (terminal 32MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100), most env-overridable.
 
-Two constraints worth knowing before you touch them: the env-derived PTY buffer trim is **clamped to ≤75% of max**, because a trim ≥ max would disable `BufferAccumulator` trimming entirely and make memory unbounded; and browser xterm scrollback is a **separate hardcoded 50k** (`DEFAULT_SCROLLBACK` in constants.js), deliberately lower than tmux's 100k history because 100k per tab is a mobile-memory hazard. The settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but **inert**; only `tmuxHistoryLimit` is wired live. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history), `docs/terminal-anti-flicker.md`
+Two constraints worth knowing before you touch them: the env-derived PTY buffer trim is **clamped to ≤75% of max**, because a trim ≥ max would disable `BufferAccumulator` trimming entirely and make memory unbounded; and browser xterm scrollback is a **separate hardcoded 50k** (`DEFAULT_SCROLLBACK` in constants.js), deliberately lower than tmux's 100k history because 100k per tab is a mobile-memory hazard. tmux <3.7 allocates `history-limit` at pane creation, while tmux 3.7+ can resize live panes (lowering the value can discard retained lines); already-evicted lines never return. The settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but **inert**; only `tmuxHistoryLimit` is wired. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history), `docs/terminal-anti-flicker.md`
 
 **Memory leaks (24+ hour sessions)**: use `CleanupManager`, clear Maps in `stop()`, guard async with `if (this.cleanup.isStopped) return`. Frontend: store handler refs, clean in `close*()`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Verify: `npm test -- test/memory-leak-prevention.test.ts`.
 
 ## Scripts & Tunnel
 
-**`install.sh`** (repo root, 92KB) is the public entry point: `curl -fsSL <raw url> | bash` installs Node/tmux if missing, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service. The network-access prompt is 3-way: **Tailscale** (loopback bind + guided `tailscale serve --bg <port>` HTTPS setup: install/login/operator/tailnet-HTTPS-toggle, then curl-verified end-to-end), **LAN** (0.0.0.0 + password prompt), or **local-only**; it preserves the existing binding on re-runs via `read_existing_binding()`. Tailscale state is detected dynamically from `tailscale serve status --json` (no marker files); the installer must NEVER `tailscale serve reset` or touch serve mappings other than 443→Codeman's port (users have unrelated serve config). `install.sh update`, `install.sh uninstall`, and `install.sh tailscale` (retrofit Tailscale access onto an existing install) also exist; `CODEMAN_NONINTERACTIVE=1` approves system changes for automation, `CODEMAN_TAILSCALE=1` presets the Tailscale choice (never installs Tailscale non-interactively).
+**`install.sh`** (repo root, 104KB) is the public entry point: `curl -fsSL <raw url> | bash` installs Node/tmux if missing, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service. The network-access prompt is 3-way: **Tailscale** (loopback bind + guided `tailscale serve --bg <port>` HTTPS setup: install/login/operator/tailnet-HTTPS-toggle, then curl-verified end-to-end), **LAN** (0.0.0.0 + password prompt), or **local-only**; it preserves the existing binding on re-runs via `read_existing_binding()`. Tailscale state is detected dynamically from `tailscale serve status --json` (no marker files); the installer must NEVER `tailscale serve reset` or touch serve mappings other than 443→Codeman's port (users have unrelated serve config). `install.sh update`, `install.sh uninstall`, and `install.sh tailscale` (retrofit Tailscale access onto an existing install) also exist; `CODEMAN_NONINTERACTIVE=1` approves system changes for automation, `CODEMAN_TAILSCALE=1` presets the Tailscale choice (never installs Tailscale non-interactively).
 
 Other key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh [quick|named] start|stop|status|url` (quick = random trycloudflare URL, default; `named setup|enable` = fixed-hostname tunnel via `scripts/codeman-tunnel-named.service`; bare `start|stop|url` still means quick), `scripts/run-beta.sh` (isolated beta instance), `scripts/build-agent-image.mjs` (docker base image), `scripts/self-update.sh` (detached updater). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.

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; OMP &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, Grok, or OMP inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
 
 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, eight CLIs** - run [Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, or OMP](#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), [Grok Build](https://github.com/xai-org/grok-build), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), or [OMP](https://github.com/can1357/oh-my-pi) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the nine 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
@@ -82,6 +82,8 @@ codeman users add alice --admin      # create the first admin account
 codeman web --multiuser              # named logins + per-user case spaces
 ```
 
+**Prefer Docker Compose?** A local-image Compose deployment ships in `docker/`: copy `docker/.env.example` to `docker/.env`, set `CODEMAN_PASSWORD`, then run `bash docker/Start-Codeman.sh` on Linux. Codeman runs in a container and spawns Docker cases as sibling containers through the host socket. See the [Docker deployment guide](docker/README.md) for direct Compose commands, storage and networking options.
+
 Details in [Multi-User Mode](#multi-user-mode-opt-in) below.
 
 <details>
@@ -171,7 +173,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), [Grok Build](https://github.com/xai-org/grok-build), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), or [OMP](https://github.com/can1357/oh-my-pi)). After installing, `http://localhost:3000` is accessible from your Windows browser.
 
 </details>
 
@@ -253,7 +255,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`, `OMP`, 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`. |
 
@@ -285,7 +287,7 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 
 - **Phone/tablet** — the UI is fully touch-optimized; scan the desktop **QR code** to log in without typing a password.
 - **Outside your network** — `./scripts/tunnel.sh start` opens a Cloudflare tunnel (set `CODEMAN_PASSWORD` first).
-- **SSH** — the `sc` chooser attaches to any session from a terminal (`sc` interactive, `sc 2` quick-attach, `sc -l` list).
+- **SSH** — `codeman tui` is a full-screen dashboard in the terminal (`codeman tui --list` to list, `codeman tui 2` to attach straight to one).
 
 ### 7. Operate & maintain
 
@@ -437,7 +439,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**, **Grok**, or **OMP** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*` vs `GROK_*`/`XAI_*` vs `OMP_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md), [`docs/pi-integration.md`](docs/pi-integration.md), [`docs/grok-integration.md`](docs/grok-integration.md) and [`docs/omp-integration.md`](docs/omp-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
@@ -460,7 +462,7 @@ Run a case inside its own hardened Docker container instead of directly on your
 - **Shared per-case container** — many sessions can `docker exec` into the same container; killing one session never tears the container out from under the others.
 - **Hardened by default** — non-root, `--cap-drop ALL`, `no-new-privileges`, PID/memory caps, never `--privileged` or the docker socket; a **sealed** profile (no host credentials, network off) is one toggle away.
 - **Seamless auth, isolated credentials** — your host Claude / Codex / Antigravity / Gemini / OpenCode / Pi logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
-- **Move it to another machine** — export a container's whole environment (toolchain + workspace) to a portable `.tar.gz`, `docker load` it on the other side, and import it into a fresh case.
+- **Seamless auth, isolated credentials** — your host Claude / Codex / Antigravity / Gemini / OpenCode / OMP logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.- **Move it to another machine** — export a container's whole environment (toolchain + workspace) to a portable `.tar.gz`, `docker load` it on the other side, and import it into a fresh case.
 - **Durable** — reconnect after a restart lands back in the same live agent; a container stop/reboot resumes the conversation from the bind-mounted transcript.
 
 Prerequisite: just Docker (or Podman). The agent base image builds itself automatically on first use, with progress streamed to the UI (or pre-build it with `node scripts/build-agent-image.mjs`). Full guide: [`docs/docker-cases.md`](docs/docker-cases.md).
@@ -658,17 +660,19 @@ These run for **every** request — before auth, even on the default no-password
 
 ---
 
-## SSH Alternative (`sc`)
+## Terminal UI (`codeman tui`)
 
-If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:
+A full-screen dashboard for your sessions, in the terminal. Same states as the web UI, because it is a client of the same server:
 
 ```bash
-sc              # Interactive chooser
-sc 2            # Quick attach to session 2
-sc -l           # List sessions
+codeman tui              # the dashboard
+codeman tui --list       # numbered session list, then exit (scriptable)
+codeman tui 2            # attach straight to session 2 of that list
 ```
 
-Single-digit selection (1-9), color-coded status, token counts, auto-refresh. Detach with `Ctrl+A D`.
+Sessions are grouped **NEEDS YOU → WORKING → IDLE → RECENT**, longest-waiting first. `↑↓`/`j`/`k` select, `1`-`9` and `[`/`]` switch between sessions, `Enter` attaches into the tmux pane (**`F1`** to come back). Inside a pane the bar across the top keeps the session strip visible and `Alt+1`-`Alt+9` switch without leaving. `y`/`n`/digit answer a pending permission dialog right from the list, `p` sends a one-line prompt, `n` starts a session and opens straight into it, `x` kills one (`y` confirms), `/` searches, `g` shows the away digest, `?` is help, `q` quits. Below 72 columns it drops the preview pane and becomes a single-column list, so it stays usable in Termius on a phone. With no server running it still starts in attach-only degraded mode.
+
+The web UI remains the primary surface; see **[docs/tui.md](docs/tui.md)** for the full guide.
 
 ---
 
@@ -793,7 +797,7 @@ When a CLI runs in a Codeman-managed session, these environment variables are se
 5. **`/api/v1/*`** is a stable alias of `/api/*`.
 6. **Wait instead of polling, and don't treat a timeout as an error.** The wait endpoints answer with HTTP `200` and `wait.timedOut: true` when nothing happened in time, so loop over short waits (60s is the default) rather than issuing one long call, because tunnels cut idle connections. `wait.timeoutMs` tells you the timeout the server actually applied after clamping (600s ceiling).
 7. **Only `claude` sessions emit `stop` and `blocked`.** Those two come from Claude Code hooks; `shell` and the external CLIs (opencode/codex/gemini/antigravity/pi) accept only `idle`, `working` and `exit`. Asking for `stop` explicitly on those is a `400`; omitting `until` is always safe. ⚠️ On a `shell` session `idle` fires **once**, at startup, and never again, so send-and-wait there can only time out; synchronize hook-less sessions with a `wait-output` marker.
-8. **Nothing reports "ready", so wait for it explicitly.** A new session answers `{"signal":"exit","immediate":true}` (that means *not started*, not *crashed*) until its PID exists, and a `claude` worker in a fresh case then sits on the CLI's trust dialog. Prompt it there and the wait resolves on `idle` in ~2s looking exactly like a finished turn, while the text sits stuck in the dialog. Recipe 2b below is the sequence that avoids it.
+7. **Only `claude` sessions emit `stop` and `blocked`.** Those two come from Claude Code hooks; `shell` and the external CLIs (opencode/codex/gemini/antigravity/omp) accept only `idle`, `working` and `exit`. Asking for `stop` explicitly on those is a `400`; omitting `until` is always safe. ⚠️ On a `shell` session `idle` fires **once**, at startup, and never again, so send-and-wait there can only time out; synchronize hook-less sessions with a `wait-output` marker.8. **Nothing reports "ready", so wait for it explicitly.** A new session answers `{"signal":"exit","immediate":true}` (that means *not started*, not *crashed*) until its PID exists, and a `claude` worker in a fresh case then sits on the CLI's trust dialog. Prompt it there and the wait resolves on `idle` in ~2s looking exactly like a finished turn, while the text sits stuck in the dialog. Recipe 2b below is the sequence that avoids it.
 
 ### Recipes
 
@@ -893,7 +897,9 @@ codeman session start -d /path/to/repo   # (s)  start a session
 codeman session list                     #      list sessions
 codeman session logs <id>                #      tail output
 codeman task add "fix the failing test"  # (t)  queue a task
-codeman attach <path>                     #      attach a Claude hook context
+codeman attach <path>                    #      show an attachment card for a local file
+codeman tui --list                       #      numbered session list (plain text when piped)
+codeman tui 3                            #      attach to session 3 of that list
 ```
 
 ### Hooks (events flowing _back_ to Codeman)
@@ -1007,7 +1013,7 @@ flowchart TB
 
         subgraph External["External"]
             CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini / Pi</small>"]
-            BG["Background Agents<br/><small>(Task tool)</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini / OMP</small>"]            BG["Background Agents<br/><small>(Task tool)</small>"]
         end
     end
 

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)、[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 或 [OMP](https://github.com/can1357/oh-my-pi)（任意组合均可；自 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)、[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 或 [OMP](https://github.com/can1357/oh-my-pi)）。安装完成后，即可从 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` 切换。 |
 
@@ -253,7 +253,7 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 - **手机/平板** —— UI 完全触控优化；扫描桌面上的**二维码**即可免密码登录。
 - **网络之外** —— `./scripts/tunnel.sh start` 打开一条 Cloudflare 隧道（先设置 `CODEMAN_PASSWORD`）。
-- **SSH** —— `sc` 选择器可从终端附着任意会话（`sc` 交互式，`sc 2` 快速附着，`sc -l` 列表）。
+- **SSH** —— `codeman tui` 是终端里的全屏会话面板（`codeman tui --list` 列出，`codeman tui 2` 直接附着到某个会话）。
 
 ### 7. 运维与维护
 
@@ -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` 切换。扩展思考预算也可配置
@@ -615,20 +615,6 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI
 
 ---
 
-## SSH 替代方案（`sc`）
-
-如果你更喜欢 SSH（Termius、Blink 等），`sc` 命令是一个便于拇指操作的会话选择器：
-
-```bash
-sc              # 交互式选择器
-sc 2            # 快速附着到会话 2
-sc -l           # 列出会话
-```
-
-单数字选择（1–9）、颜色编码的状态、token 计数、自动刷新。用 `Ctrl+A D` 分离。
-
----
-
 ## 键盘快捷键
 
 > Ctrl 绑定在 macOS 上也接受 Cmd。

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/.env.example

@@ -0,0 +1,69 @@
+# =============================================================================
+# Codeman Docker Compose environment template
+# Copy this file to .env and set the values for the Docker host.
+# =============================================================================
+
+TZ=Australia/Perth
+
+# Optional overrides for direct `docker compose` use. The Bash start script
+# detects these values from CODEMAN_APPDATA_PATH automatically. Compose uses
+# 1000:1000 when the variables are omitted.
+# PUID=1000
+# PGID=1000
+
+# Name of the account that runs Codeman and all local CLI sessions. Changing
+# this value rebuilds the image with a matching account.
+CODEMAN_RUNTIME_USER=opencode
+
+# Required. Persistent Codeman application data, CLI credentials, and session
+# state are stored here on the host and mounted at the runtime account's home
+# directory in the container.
+CODEMAN_APPDATA_PATH=/mnt/user/appdata/Coding/codeman
+
+# Required for Docker cases. This must be an absolute path on the Docker host.
+# Codeman and each isolated case use this same path, so it cannot be a
+# container-only path such as /home/opencode/codeman-cases.
+CODEMAN_CASES_PATH=/mnt/user/appdata/Coding/codeman/codeman-cases
+
+# Required. Network bind address, host port, and local image tag.
+CODEMAN_HOST=0.0.0.0
+CODEMAN_PORT=3000
+CODEMAN_IMAGE=codeman:local
+
+# Required for any network-accessible Codeman instance. Use a unique, strong
+# password. This file is safe to commit; copy it to .env and set the value.
+CODEMAN_PASSWORD=changeme
+
+# Required. Username for Codeman HTTP Basic authentication.
+CODEMAN_USERNAME=admin
+
+# Optional: authenticate Gemini CLI without an interactive login.
+GEMINI_API_KEY=
+
+# Linux default. On Docker Desktop, use the socket path supported by your
+# Docker installation when it differs from /var/run/docker.sock.
+DOCKER_SOCKET=/var/run/docker.sock
+
+# Optional override for direct `docker compose` use. The Bash start script
+# detects this from DOCKER_SOCKET automatically. The direct Compose default is
+# 999, but the correct value depends on the Docker host.
+# DOCKER_SOCKET_GID=999
+
+# Set to 1 only when Docker-case hook callbacks are required.
+CODEMAN_DOCKER_BRIDGE_HOOKS=0
+
+# Set to 1 when `docker info` reports `SwapLimit=false`. The case memory limit
+# remains active; Codeman omits --memory-swap and filters the daemon's exact
+# unsupported-swap warning while preserving all other Docker create errors.
+CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=0
+
+# Required only when applying the macvlan example in README.md.
+CODEMAN_MACVLAN_NETWORK=br0.11
+CODEMAN_IPV4_ADDRESS=10.10.11.236
+CODEMAN_MAC_ADDRESS=02:10:11:00:00:EC
+
+# Required only when creating a new managed macvlan network, rather than using
+# the external-network macvlan example.
+CODEMAN_MACVLAN_PARENT=br0.11
+CODEMAN_MACVLAN_SUBNET=10.10.11.0/24
+CODEMAN_MACVLAN_GATEWAY=10.10.11.1

docker/README.md

@@ -0,0 +1,96 @@
+# Codeman Docker deployment
+
+This folder contains the Compose configuration, server image Dockerfile, and environment template for a locally built Codeman server.
+
+## Start
+
+From the repository root, create the runtime environment file and set the required values, especially `CODEMAN_PASSWORD`.
+
+```sh
+cp docker/.env.example docker/.env
+bash docker/Start-Codeman.sh
+```
+
+On PowerShell, use the following command instead.
+
+```powershell
+Copy-Item docker/.env.example docker/.env
+docker compose --env-file docker/.env -f docker/docker-compose.yaml up --build -d
+```
+
+Every required value is defined and explained in `.env.example`. `GEMINI_API_KEY` is intentionally optional and may remain blank.
+
+On Linux, `Start-Codeman.sh` stops with an error when required paths are missing. It creates the application-data directory when safe, detects its numeric owner as `PUID:PGID`, and detects `DOCKER_SOCKET_GID` from the configured Docker socket. It rejects a root-owned application-data directory because Codeman and its local CLI sessions must remain unprivileged.
+
+Codeman, Claude, OpenCode, and other local sessions run as the unprivileged account named by `CODEMAN_RUNTIME_USER`, which defaults to `opencode`. When Compose is run directly, `PUID` and `PGID` default to `1000:1000`; set them in `.env` when the application-data directory has a different owner. The Bash start script determines them automatically instead.
+
+To retain Docker-case support without root when running Compose directly, set `DOCKER_SOCKET_GID` to the numeric group ID of the host socket. On a standard Linux Docker host, obtain it with `stat -c '%g' /var/run/docker.sock`. The Bash start script detects it automatically.
+
+## Application data storage
+
+The default configuration uses a host-folder bind mount:
+
+```yaml
+volumes:
+  - type: bind
+    source: ${CODEMAN_APPDATA_PATH}
+    target: /home/${CODEMAN_RUNTIME_USER}
+```
+
+Set `CODEMAN_APPDATA_PATH` in `.env` to a directory that the Docker daemon can access. The example value is `/mnt/user/appdata/Coding/codeman`.
+
+`CODEMAN_CASES_PATH` is the separate host directory for managed case workspaces. It is mounted into Codeman at the same absolute path, allowing the host Docker daemon to bind it into an isolated case container. Set it to a child directory of `CODEMAN_APPDATA_PATH` unless you deliberately store workspaces elsewhere.
+
+Compose also exposes `CODEMAN_APPDATA_PATH` to Codeman as `CODEMAN_DOCKER_HOST_HOME`. This lets Docker case seed files, CLI credentials and the hook secret be mounted using paths that exist in the host daemon's filesystem. Direct host installations do not set this variable and retain their existing behaviour.
+
+Set `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1` when `docker info` reports `SwapLimit=false`. Codeman continues to apply the configured case memory limit, omits Docker's unsupported `--memory-swap` option, and filters only the daemon's exact swap-capability warning. Every other Docker create error and its exit status remain visible.
+
+For an existing installation created by a root-running image, change ownership of the application-data directory before upgrading so the configured `PUID` and `PGID` can read the saved credentials and state:
+
+```sh
+chown -R 99:100 /mnt/user/appdata/Coding/codeman
+```
+
+Replace `99:100` and the path with the values from your `.env` file.
+
+Do not replace this bind mount with a Docker-managed named volume when Docker cases are enabled. Codeman passes seed, credential, transcript and hook-secret bind sources to the host Docker daemon, so their source files must have stable paths in the daemon's filesystem. A named volume does not provide the required host path mapping.
+
+## Static macvlan networking
+
+The default configuration publishes a host port. It does not use `network_mode: host`. To attach Codeman directly to an existing external macvlan network with a static IP address and MAC address, remove the `ports:` section and add the following to the `codeman` service:
+
+```yaml
+mac_address: ${CODEMAN_MAC_ADDRESS}
+networks:
+  codeman_lan:
+    ipv4_address: ${CODEMAN_IPV4_ADDRESS}
+```
+
+Then add this top-level network declaration:
+
+```yaml
+networks:
+  codeman_lan:
+    external: true
+    name: ${CODEMAN_MACVLAN_NETWORK}
+```
+
+Set `CODEMAN_MACVLAN_NETWORK`, `CODEMAN_IPV4_ADDRESS`, and `CODEMAN_MAC_ADDRESS` in `.env`. The values in `.env.example` match the supplied Unraid example network and should be changed for other hosts.
+
+### Create a managed macvlan network
+
+If an external macvlan network does not already exist, use this top-level declaration instead. Do not use it together with the external-network declaration.
+
+```yaml
+networks:
+  codeman_lan:
+    driver: macvlan
+    driver_opts:
+      parent: ${CODEMAN_MACVLAN_PARENT}
+    ipam:
+      config:
+        - subnet: ${CODEMAN_MACVLAN_SUBNET}
+          gateway: ${CODEMAN_MACVLAN_GATEWAY}
+```
+
+Macvlan containers are ordinarily not reachable from their Docker host without additional host-network routing. Confirm the selected address, MAC address, parent interface, and subnet are reserved and valid for the target network before starting the stack.

docker/Start-Codeman.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+env_file="$script_dir/.env"
+compose_file="$script_dir/docker-compose.yaml"
+
+if [[ ! -f "$env_file" ]]; then
+  printf 'Error: Docker environment file is missing: %s\n' "$env_file" >&2
+  printf 'Create it from %s/.env.example before starting Codeman.\n' "$script_dir" >&2
+  exit 1
+fi
+
+compose_command=(docker compose --env-file "$env_file" -f "$compose_file")
+appdata_path=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "CODEMAN_APPDATA_PATH" { sub(/^[^=]*=/, ""); print; exit }'
+)
+docker_socket=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "DOCKER_SOCKET" { sub(/^[^=]*=/, ""); print; exit }'
+)
+
+if [[ -z "$appdata_path" ]]; then
+  printf 'Error: CODEMAN_APPDATA_PATH is not set in %s\n' "$env_file" >&2
+  exit 1
+fi
+
+if [[ ! -d "$appdata_path" ]]; then
+  if [[ "$EUID" == '0' ]]; then
+    printf 'Error: Refusing to create CODEMAN_APPDATA_PATH as root: %s\n' "$appdata_path" >&2
+    printf 'Create it as the unprivileged account that should run Codeman, then retry.\n' >&2
+    exit 1
+  fi
+  mkdir -p -- "$appdata_path"
+fi
+
+if owner_ids=$(stat -c '%u:%g' -- "$appdata_path" 2>/dev/null); then
+  :
+elif owner_ids=$(stat -f '%u:%g' "$appdata_path" 2>/dev/null); then
+  :
+else
+  printf 'Error: Cannot determine the owner of CODEMAN_APPDATA_PATH: %s\n' "$appdata_path" >&2
+  exit 1
+fi
+
+export PUID=${owner_ids%%:*}
+export PGID=${owner_ids##*:}
+
+if [[ "$PUID" == '0' ]]; then
+  printf 'Error: CODEMAN_APPDATA_PATH is owned by root: %s\n' "$appdata_path" >&2
+  printf 'Change the directory ownership to the unprivileged account that should run Codeman.\n' >&2
+  exit 1
+fi
+
+if [[ -z "$docker_socket" || ! -S "$docker_socket" ]]; then
+  printf 'Error: DOCKER_SOCKET is not a Unix socket: %s\n' "${docker_socket:-<unset>}" >&2
+  exit 1
+fi
+
+if socket_ids=$(stat -c '%u:%g' -- "$docker_socket" 2>/dev/null); then
+  :
+elif socket_ids=$(stat -f '%u:%g' "$docker_socket" 2>/dev/null); then
+  :
+else
+  printf 'Error: Cannot determine the owner of DOCKER_SOCKET: %s\n' "$docker_socket" >&2
+  exit 1
+fi
+
+export DOCKER_SOCKET_GID=${socket_ids##*:}
+
+exec docker compose --env-file "$env_file" -f "$compose_file" up --build -d

docker/agent.Dockerfile

@@ -51,6 +51,58 @@ 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.
+# ⚠️ `pnpm` is a HARD dependency of `dsh plugin`, not optional tooling: the
+# subcommand is a thin forwarder that `spawnSync`s a literal `pnpm` with no
+# fallback to npm, so on an image without it the profile install below dies
+# with `dsh: pnpm not found on PATH` / exit 127 and takes the whole build with
+# it (issue #352). It stays on PATH at runtime too, so a container user can run
+# `dsh plugin add` themselves.
+RUN npm install -g @deepseek-ai/dsh pnpm \
+ && npm cache clean --force \
+ && dsh --version \
+ && pnpm --version
+
+# OMP (Oh My Pi) is NOT on npm: a standalone binary via omp.sh's installer, which
+# targets $HOME/.local/bin with no --dir override (verified 2026-08-27 — the
+# resolver's OMP_SEARCH_DIRS lists ~/.omp/bin first, which turned out to be the
+# WRONG guess for the installer's actual target; build this step for real
+# rather than trust that ordering). At build time $HOME is root's home and
+# unreachable by the `agent` user, so copy the binary into /usr/local/bin and
+# drop root's ~/.local/bin/omp in the same layer so the image does not carry
+# the download twice.
+RUN curl -fsSL https://omp.sh/install | sh \
+ && cp -L /root/.local/bin/omp /usr/local/bin/omp.real \
+ && rm -f /usr/local/bin/omp \
+ && mv /usr/local/bin/omp.real /usr/local/bin/omp \
+ && chmod 755 /usr/local/bin/omp \
+ && rm -f /root/.local/bin/omp \
+ && omp --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 +120,37 @@ 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.
+# ⚠️ `dangerouslyAllowAllBuilds` is what keeps that profile install from becoming
+# the next #352. pnpm (unlike npm) blocks dependency lifecycle scripts by default
+# and FAILS the install over it — `ERR_PNPM_IGNORED_BUILDS`, exit 1, measured on
+# pnpm 11.24 — so any package in the tui's tree that ships one stops the build
+# dead. An allowlist of the offenders rots: `@deepseek-harness-tui/dsh-tui` is
+# resolved by dist-tag, not pinned, and 0.9.3 pulled `@google/genai` (a
+# `preinstall: no-op`) where 0.10.0-beta.x does not, so the names to allow move
+# under us between rebuilds. Allowing them wholesale is also the SAME exposure
+# this image already accepts three layers up: `npm install -g` runs the install
+# scripts of every transitive dep of the five CLIs above it, with no gate at all.
+# `.omp/agent` is pre-created for the same reason `.codex` is: it is a MIXED
+# store (per-file config seeds PLUS a shared `sessions/` RW bind mount for
+# Codeman's own host-side history/resume reads), and neither kind of artifact
+# creates its own parent directory.
 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 /home/agent/.omp/agent \
+ && DSH_HOME=/home/agent/.dsh HOME=/home/agent \
+      dsh plugin --profile dsh-tui add --config.dangerouslyAllowAllBuilds=true \
+      @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
 

docker/docker-compose.yaml

@@ -0,0 +1,65 @@
+name: codeman
+
+services:
+  codeman:
+    build:
+      context: ..
+      dockerfile: docker/server.Dockerfile
+      args:
+        CODEMAN_RUNTIME_USER: ${CODEMAN_RUNTIME_USER}
+        PGID: ${PGID:-1000}
+        PUID: ${PUID:-1000}
+    image: ${CODEMAN_IMAGE}
+    init: true
+    restart: unless-stopped
+    ports:
+      - "${CODEMAN_PORT}:${CODEMAN_PORT}"
+    environment:
+      CODEMAN_DOCKER_BRIDGE_HOOKS: ${CODEMAN_DOCKER_BRIDGE_HOOKS}
+      # Host-side equivalent of the runtime user's HOME. Docker case seed,
+      # credential and hook mounts are translated into the daemon namespace.
+      CODEMAN_DOCKER_HOST_HOME: ${CODEMAN_APPDATA_PATH}
+      CODEMAN_DOCKER_DISABLE_SWAP_LIMIT: ${CODEMAN_DOCKER_DISABLE_SWAP_LIMIT}
+      CODEMAN_CASES_PATH: ${CODEMAN_CASES_PATH}
+      CODEMAN_HOST: ${CODEMAN_HOST}
+      CODEMAN_PASSWORD: ${CODEMAN_PASSWORD}
+      CODEMAN_PORT: ${CODEMAN_PORT}
+      CODEMAN_USERNAME: ${CODEMAN_USERNAME}
+      GEMINI_API_KEY: ${GEMINI_API_KEY}
+      PGID: ${PGID:-1000}
+      PUID: ${PUID:-1000}
+      TZ: ${TZ}
+    group_add:
+      # Retain access to the host Docker socket without running as root.
+      - ${DOCKER_SOCKET_GID:-999}
+    volumes:
+      # Application data and CLI credentials persist on the configured host
+      # path, rather than in a Docker-managed volume.
+      - type: bind
+        source: ${CODEMAN_APPDATA_PATH}
+        target: /home/${CODEMAN_RUNTIME_USER}
+      # Docker cases are sibling containers on the host daemon. Their workspace
+      # must be visible to Codeman at the same absolute path used by that daemon.
+      - type: bind
+        source: ${CODEMAN_CASES_PATH}
+        target: ${CODEMAN_CASES_PATH}
+      # Codeman uses the host daemon to create isolated Docker cases. This is
+      # Docker-outside-of-Docker, not Docker-in-Docker.
+      - type: bind
+        source: ${DOCKER_SOCKET}
+        target: /var/run/docker.sock
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >-
+          node -e "fetch('http://127.0.0.1:${CODEMAN_PORT}/api/status').then((response) => process.exit(response.status < 500 ? 0 : 1)).catch(() => process.exit(1))"
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s

docker/server.Dockerfile

@@ -0,0 +1,114 @@
+# syntax=docker/dockerfile:1
+
+# Build the application from the checkout supplied as the Docker build context.
+# No published Codeman application image is required.
+FROM node:22-bookworm-slim AS build
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends python3 make g++ \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /opt/codeman
+
+COPY . .
+
+RUN npm ci \
+ && npm run build \
+ && npm prune --omit=dev --ignore-scripts \
+ && npm cache clean --force
+
+# The Docker CLI talks to the host daemon through the socket mounted by
+# docker/docker-compose.yaml. It does not run a Docker daemon in this container.
+FROM node:22-bookworm-slim
+
+ARG CODEMAN_RUNTIME_USER=opencode
+ARG PUID=1000
+ARG PGID=1000
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      ca-certificates \
+      curl \
+      git \
+      openssh-client \
+      procps \
+      ripgrep \
+      tmux \
+ && rm -rf /var/lib/apt/lists/*
+
+# The Docker CLI, taken from the official image rather than Debian's `docker.io`.
+# That package is the full ENGINE: with --no-install-recommends it still pulls 15
+# packages including containerd, runc, dmsetup and iptables, none of which a
+# client that only talks to a mounted socket can use. Measured on top of this
+# base image: `docker.io` costs 266 MB and ships Docker 20.10.24 (2023), while
+# these two files cost 108 MB and ship the current CLI (493 MB vs 335 MB total).
+#
+# The binaries are STATIC Go builds, so they run on this glibc image even though
+# the image they come from is Alpine (verified: `docker --version`, `docker ps`
+# and `docker build` all work here against a mounted host socket).
+#
+# buildx is copied on purpose. `scripts/build-agent-image.mjs` shells out to
+# `docker build` — Codeman auto-builds the agent image on the first Docker case —
+# and without the plugin that silently falls back to the CLASSIC builder, which
+# Docker has deprecated and will eventually drop. `docker-compose` is NOT copied:
+# Codeman never shells out to it.
+COPY --from=docker:29-cli /usr/local/bin/docker /usr/local/bin/docker
+COPY --from=docker:29-cli \
+     /usr/local/libexec/docker/cli-plugins/docker-buildx \
+     /usr/local/libexec/docker/cli-plugins/docker-buildx
+
+# Keep credentials out of the image. Users authenticate these CLIs at runtime
+# through Codeman sessions, and the configured host bind mount retains state.
+RUN npm install --global \
+      @anthropic-ai/claude-code \
+      @google/gemini-cli \
+      @openai/codex \
+      opencode-ai \
+ && npm cache clean --force
+
+# Keep the web server and every local Codeman session unprivileged. PUID and
+# PGID match the host-owned application-data directory mounted by Compose. The
+# requested GID may not exist in the base image, and a host UID such as 1000 may
+# already belong to the baked `node` account, so handle both cases explicitly.
+RUN set -eux; \
+    case "${PUID}" in ''|*[!0-9]*) echo "PUID must be numeric" >&2; exit 1;; esac; \
+    case "${PGID}" in ''|*[!0-9]*) echo "PGID must be numeric" >&2; exit 1;; esac; \
+    if [ "${PUID}" -eq 0 ]; then \
+      echo "PUID must identify an unprivileged account, not root" >&2; \
+      exit 1; \
+    fi; \
+    if ! getent group "${PGID}" >/dev/null; then \
+      groupadd --gid "${PGID}" codeman-runtime; \
+    fi; \
+    existing_user="$(getent passwd "${PUID}" | cut -d: -f1 || true)"; \
+    if [ -n "${existing_user}" ]; then \
+      usermod \
+        --login "${CODEMAN_RUNTIME_USER}" \
+        --gid "${PGID}" \
+        --home "/home/${CODEMAN_RUNTIME_USER}" \
+        --move-home \
+        --shell /bin/bash \
+        "${existing_user}"; \
+    else \
+      useradd \
+        --uid "${PUID}" \
+        --gid "${PGID}" \
+        --create-home \
+        --home-dir "/home/${CODEMAN_RUNTIME_USER}" \
+        --shell /bin/bash \
+        "${CODEMAN_RUNTIME_USER}"; \
+    fi
+
+WORKDIR /opt/codeman
+
+COPY --from=build /opt/codeman /opt/codeman
+
+ENV CODEMAN_PORT=3000 \
+    HOME=/home/${CODEMAN_RUNTIME_USER} \
+    NODE_ENV=production
+
+EXPOSE 3000
+
+USER ${CODEMAN_RUNTIME_USER}
+
+CMD ["node", "dist/index.js", "web"]

docs/api-reference.md

@@ -204,11 +204,16 @@ turn.
 The reliable sequence is: poll `GET /api/v1/sessions/:id` until `.data.pid` is
 non-null, then `wait-output` for the composer's own marker (`bypass`, the status
 bar of a CLI spawned in bypass mode) with a short timeout, handling the trust
-dialog only as the bounded fallback (`trust` matched → send `\r` → wait for
-`bypass` again). Do not probe `trust` first and Enter blindly: the dialog text
-stays in the terminal buffer for the life of the session, so a `trust` probe with
-`from=buffer` keeps matching on every later run and the Enter lands in a ready
-composer. A worked version is in
+dialog only as the bounded fallback.
+
+⚠️ **The fallback is not a bare `\r`.** Claude Code 2.1.252 unnumbered the dialog's
+options, reversed them and highlights `No, exit`, so an Enter sent blind quits the
+CLI and the pane dies seconds after the spawn. Read the `❯` marker off the current
+frame (`GET /api/v1/sessions/:id/terminal?full=1`), send `ESC [ B` while it is on
+`No, exit`, re-read, and confirm only once it is on `Yes, I trust this folder`.
+Reading the current frame is also what keeps this correct on later runs: the dialog
+text stays in the terminal buffer for the life of the session, so a `trust` probe
+with `from=buffer` keeps matching long after the dialog is gone. A worked version is in
 [`extending-codeman.md`](extending-codeman.md#seam-3-http-api-and-cli).
 
 ### `GET /api/v1/sessions/:id/wait`

docs/architecture-invariants.md

@@ -14,16 +14,36 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### Instance isolation and the multi-instance attach danger
 
-**Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`.
+**Instance isolation / multi-instance attach danger** — data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts` (`getDataDir()`/`dataPath()`/`DEFAULT_TMUX_SOCKET`). ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions** (`tmux -L codeman attach-session …`), resizing/mutating them — `$HOME` isolation is NOT enough (tmux is system-global). To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes BOTH dir+socket: `~/.codeman-<name>` + `-L codeman-<name>`), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually. **`CODEMAN_INSTANCE` defaults to empty = the production layout (`~/.codeman`, `-L codeman`, port 3000)**, so this branch is safe to ship to master without disturbing existing installs. To run THIS beta alongside prod, launch with `scripts/run-beta.sh` (`CODEMAN_INSTANCE=beta` + `CODEMAN_PORT=5000`) — it never collides with prod's data dir/socket/port. Any new `~/.codeman/...` path MUST go through `dataPath()`, never `join(homedir(), '.codeman', …)`, and any new `tmux -L` caller through `resolveTmuxSocketName()` (same module): it applies the `CODEMAN_TMUX_SOCKET` override only when the name is safe and falls back to `DEFAULT_TMUX_SOCKET` otherwise. `TmuxManager` was the only such caller until `codeman tui` shelled out to tmux from a SECOND process for its degraded-mode listing and its attach handoff; a hardcoded `codeman` there would have pointed a beta instance straight at prod's panes.
 
 ## Session launch modes
 
-### External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi)
+### External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)
 
-**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini' || 'antigravity' || 'pi'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). All five modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Antigravity specifics: command built by `buildAntigravityCommand()` (`--model`, `--conversation <id>` resume, `--dangerously-skip-permissions` from the `antigravityConfig` payload); availability via `GET /api/antigravity/status` — routes fail with `OPERATION_FAILED` + install hint (`curl -fsSL https://antigravity.google/cli/install.sh | bash`) when missing. Unlike the other three it is NOT an npm package (standalone binary, `~/.local/bin/agy`), which is why `docker/agent.Dockerfile` installs it with its own `--dir /usr/local/bin` step rather than in the `npm install -g` line, and why it does NOT join `isAltScreenStripMode()`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Agents & CLIs → Codex; Respawn/Ralph options are Claude-only, so session options open on the Session tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM).
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` (`mode === 'opencode' || 'codex' || 'gemini' || 'antigravity' || 'pi' || 'grok' || 'deepseek'`) gates Claude-specific behavior — Ralph tracker, BashToolParser, token/CLI-info parsing, and ❯-prompt readiness detection are all skipped (these CLIs render their own TUIs; readiness = output stabilization instead). All seven modes **require tmux — no direct PTY fallback** — because secrets are injected via `tmux setenv` (socket-scoped `${this.tmux()} setenv`, never on the spawn command line): OpenCode gets `OPENCODE_CONFIG_CONTENT` etc., Codex gets `OPENAI_API_KEY`/`CODEX_API_KEY`/`CODEX_HOME` (`setCodexEnvVars`), Gemini gets `GEMINI_API_KEY`/`GOOGLE_API_KEY`/`GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI` etc. (`setGeminiEnvVars`, all in `tmux-manager.ts`). Codex specifics: command built by `buildCodexCommand()` (`--model`, `resume <id>`, `--dangerously-bypass-approvals-and-sandbox` from the `codexConfig` payload / `codexDangerouslyBypassApprovals` app setting; `renderMode` is schema-coerced to `'hybrid'`, the only supported mode). Gemini specifics: command built by `buildGeminiCommand()` (`--skip-trust` always, `--approval-mode <default|auto_edit|yolo|plan>` defaulting to `yolo` for parity with Claude's `--dangerously-skip-permissions`, `--model`, `--resume` from the `geminiConfig` payload); availability via `GET /api/gemini/status` — session/quick-start routes fail with `OPERATION_FAILED` + install hint (`npm install -g @google/gemini-cli`) when missing. Codex AND Gemini export `COLORTERM=truecolor` + unset `NO_COLOR` (other modes unset `COLORTERM`); Gemini joins `isAltScreenStripMode()` (Codex/Claude/Gemini are Ink TUIs that repaint inline → strip alt-screen/`3J` so scrollback survives). Codex availability via `GET /api/codex/status`. Antigravity specifics: command built by `buildAntigravityCommand()` (`--model`, `--conversation <id>` resume, `--dangerously-skip-permissions` from the `antigravityConfig` payload); availability via `GET /api/antigravity/status` — routes fail with `OPERATION_FAILED` + install hint (`curl -fsSL https://antigravity.google/cli/install.sh | bash`) when missing. Unlike the other three it is NOT an npm package (standalone binary, `~/.local/bin/agy`), which is why `docker/agent.Dockerfile` installs it with its own `--dir /usr/local/bin` step rather than in the `npm install -g` line, and why it does NOT join `isAltScreenStripMode()`. Frontend: run-mode dropdown → `runCodex()`/`runGemini()` in `session-ui.js` ("Run CX"/"Run GM" labels), App Settings → Agents & CLIs → Codex; Respawn/Ralph options are Claude-only, so session options open on the Session tab for external CLI sessions. ⚠️ `run*()` MUST unwrap the `{success,data}` envelope (`(await res.json()).data.available` / `data.data.sessionId`) — reading the raw shape silently breaks the run. Tests: `test/run-mode-ui.test.ts` + `test/gemini-mode.test.ts` (vm-sandbox harness, no real DOM). Grok specifics: command built by `buildGrokCommand()` (`--always-approve` from `grokConfig.alwaysApprove` — grok's `bypassPermissions` permission mode, deny rules still apply; `--model`; `--resume <id>` / `--continue`, id-regexed so grok's resume-by-TITLE feature can never put an arbitrary string on the spawn line); availability via `GET /api/grok/status`, which carries `version` because the resolver version-probes candidates (`grok` has npm squatters, e.g. @vibe-kit/grok-cli — `GROK_VERSION_REGEX` is shared with the dependency registry so doctor and run mode agree). Like antigravity it is a standalone binary (xAI installer → `~/.grok/bin`, symlinked into `~/.local/bin`), so `docker/agent.Dockerfile` installs it in its own step (copy to `/usr/local/bin`, drop root's `~/.grok` in the same layer) and it stays OUT of `isAltScreenStripMode()` (fullscreen alt-screen TUI with mouse support — the opencode case, not the Ink case). Env allowlist: `GROK_*` plus the vendor namespace `XAI_*` (`XAI_API_KEY` is grok's documented headless auth var — the same narrow-vendor-namespace reasoning as `GOOGLE_*` for gemini). Docker cred seeding is per-file (`auth.json`, `config.toml`, `pager.toml` from `~/.grok` — the dir also holds `sessions/`, `memory/`, and the ~160MB binary under `downloads/`). Grok tests: `test/grok-mode.test.ts`, `test/grok-cli-resolver.test.ts`.
+
+**DeepSeek Harness (`dsh`) specifics** — the mode that breaks three of the assumptions the six above share, so read this before changing anything about it.
+
+⚠️ **The agent is a PROFILE, not the binary.** `dsh` is a launcher over `$DSH_HOME/profiles/<name>` (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 front door is ALWAYS third-party. So availability is TWO questions, not one, and `isDeepSeekRunnable()` (binary AND a pane-capable profile) is what the Run button gates on while `isDeepSeekAvailable()` (binary only) gates the "add a profile" affordance and the web-UI shortcut. Reporting only the binary would let Run spawn a pane that dies on arrival, which is this mode's single most confusing failure. `buildDeepSeekCommand()` emits `dsh --profile <name> [--resume [id]]`; an absent profile resolves through `resolveDefaultDeepSeekProfile()`, which prefers a recognized TUI, then an UNRECOGNIZED profile (third-party by construction — a classifier that has not heard of a bundle must not hide it), and refuses `web`/`headless`, which cannot drive a pane.
+
+⚠️ **The permission switch is an ENV VAR, not a flag.** The harness has no `--dangerously-skip-permissions` equivalent; its sandbox/approval rows read `DSH_PERMISSION_MODE` with three presets (`read-only` / `workspace-write` / `danger-full-access`; measured from `dsh --dump-default-config`). It is exported via `tmux setenv` in `_configureDeepSeek()`, never on the command line, and `test/deepseek-mode.test.ts` pins that nothing permission-shaped ever reaches the spawn line. 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`), the harness reads it with `??` as a boot-time DEFAULT, so it stays soft. Absent = `workspace-write`, which still asks, so the multi-user clamp is the only-if-sent branch (codex/antigravity/grok shape, not pi's materialize) — and it clamps down to `workspace-write`, NOT `read-only`, because the clamp removes privilege without breaking a session's ability to edit its own workspace. ⚠️ **Clamping the config is only HALF the gate here, and this is the only CLI where that is true.** Every sibling's bypass is a command-line flag, reachable only through the per-CLI config `clampExternalCliBypassForOwner()` already owns. DeepSeek's is an env var, `DSH_*` is an allowlisted `envOverrides` prefix (it must be — that is also how the harness's ordinary knobs are set), and `applyEnvOverrides()` runs AFTER `_configureDeepSeek()` in tmux-manager, so `envOverrides: {DSH_PERMISSION_MODE: 'danger-full-access'}` sent on the SAME request as a clamped config lands last and wins. `clampEnvOverridesForOwner()` (session-routes.ts, exported as `_clampEnvOverridesForOwner` for tests) DROPS `DSH_PERMISSION_MODE`, `DSH_HOME` and `DEEPSEEK_BASE_URL` for a non-granted owner (the last because `_configureDeepSeek()` forwards the SERVER's own `DEEPSEEK_API_KEY` into the pane, so a redirected base URL would send it to a foreign host) rather than rewriting them, since dropping falls through to what `_configureDeepSeek()` exports, which is already the clamped value. `DSH_HOME` is on that list because it aims the launcher at a profile tree and a profile's plugin code executes at BOOT, before any approval row can apply — the wider of the two holes. No-op in single-user mode and for a granted owner, like every other clamp.
+
+⚠️ **It is the only non-claude mode that passes `hooksAvailableForMode()`, and it earned that.** The community terminal front door reports its own lifecycle to a supervising process through a generic env-var-gated contract inherited from Herdr: with `HERDR_ENV=1` + `HERDR_BIN_PATH` + `HERDR_PANE_ID` set it shells out `<bin> pane report-agent <paneId> --state idle|working|blocked …` on every state change and treats exit 0 as delivered. `deepseek-status-shim.ts` GENERATES a small script into the data dir (like `self-update-runner.sh`, so npm installs and git clones behave alike) and points `HERDR_BIN_PATH` at it; it forwards to `POST /api/hook-event` as `idle→stop`, `blocked→permission_prompt`, `working→agent_working`. So a dsh session gets real respawn triggers, real `wait` stop/blocked signals and real Approvals Inbox items instead of output-stabilization guesswork. This is an interface implementation, not an impersonation — no real `herdr` binary is ever executed. A TUI that does not implement the contract simply never calls the shim and falls back to stabilization, so the feature is inert rather than harmful there. ⚠️ **For deepseek alone, `hooksAvailableForMode()` is a per-SESSION question**, which is why it takes a `HookCapabilityOptions` second argument and every call site passes `sessionHookOptions(session)`: `deepSeekConfig.statusReporting: false` skips the `HERDR_*` export, and that triple is the only reason a dsh session posts anything, so answering from the mode alone would accept `until=stop` on a session where nothing can ever send one — the infinite-wait-dressed-as-a-timeout the predicate exists to prevent. The option defaults permissive (`!== false`), so a call site that forgets it degrades to the old behaviour instead of 400ing a working session. ⚠️ Profile conformance is the LIMIT of what is knowable at request time: `resolveDefaultDeepSeekProfile()` deliberately treats an unrecognized profile as launchable, so a non-conforming TUI still answers true and still times out on an explicit `stop` — which is why the DEFAULT signal set keeps `idle`/`exit`. ⚠️ **The predicate is not a stand-in for "is this a claude session"**, though it read like one while `claude` was the only true answer: Read My Mind (`POST /api/sessions/:id/readmymind`) and intent capture (`captureIntentPrompt`) read Claude's own transcript and were silently widened to deepseek by this change, so both compare `mode === 'claude'` directly and a static check in `test/deepseek-mode.test.ts` keeps them there.
+
+⚠️ **`agent_working` is a hook event with no Claude Code hook behind it** (157th SSE constant). It exists because a harness turn cannot run while one of its own modal approvals is on screen, so "the agent started working" proves a dialog was answered in the terminal. It joins `APPROVAL_RESOLVING_EVENTS`; without it a dsh session's red alert would survive until the next `stop`, 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 and cannot help here.
+
+⚠️ **Answers are READ FROM DISK for this mode, not scraped off the pane** (`src/deepseek-transcript.ts`, behind `GET /api/sessions/:id/last-response`). dsh writes a structured JSONL transcript at `$DSH_HOME/sessions/<mangled-cwd>/<dsh-session-id>/session.jsonl.zstd`, so it belongs with claude and codex rather than with the pane-segmented modes — and for dsh specifically the segmenter was not merely coarse but WRONG: dsh-TUI paints a full-screen splash, so a `last-response` call on a fresh dsh session returned its ASCII-art logo, which anything polling for a worker's first answer reads as an answer. Four mechanisms in that file are load-bearing. **(1)** dsh appends **one zstd FRAME per write**, and Node's `zlib` zstd decoder — one-shot AND streaming — stops at the first frame end: a real 56-line transcript decoded as 1 line / 158 bytes, i.e. the session header alone, so every call would have reported "nothing said yet" forever. `zstdFrameRanges()` walks frame and block headers (no decompression) to find exact boundaries and decompresses each frame; splitting on the 4-byte magic instead would corrupt everything after a magic sequence that happens to occur inside compressed data. zstd itself is resolved at RUNTIME (`zstdSupported()`), because it landed in Node 22.15 while the project floor is 22.0 and `@types/node` still does not declare it; without it the mode falls back to the pane exactly as before, which is why `readDeepSeekLastResponse()` distinguishes `null` ("this reader cannot run here") from an empty result ("read fine, nothing said yet"). **(2)** Every turn also records a plugin-sourced `user/message` (dsh's runtime-context snapshot: sandbox policy, approval policy, cwd), so only `source.kind === 'user'` is a real prompt. **(3)** A turn that ends in `reason.kind: 'error'` is surfaced as `Turn error: …` (and a non-error early stop such as `max-tokens` as `Turn ended: …`) rather than as an empty string, which an agent reads as "still thinking" through fifteen polls. **(4)** Reply text is assembled per (turn, step): a finalized `assistant/message` wins, and the streamed `assistant/chunk` / `text-chunks` deltas are consulted ONLY for a step that never finalized (so a partial answer is readable mid-turn without ever being appended twice) — ⚠️ and "finalized" is tracked as a SET of steps, not as non-empty text, because a step whose whole reply was reasoning strips to `''` at the `</think>` boundary and would otherwise resurrect the raw, unstripped deltas in its place (measured on a real conversation). ⚠️ Session→transcript pairing is by the transcript's own header `cwd` plus a ±60 s boot window against the Codeman session's `createdAt`, never by reproducing dsh's directory mangling (which already has two forms on disk, `<uuid>` and `session-<uuid>`) and never by newest-mtime alone: mtime alone handed a freshly spawned worker its PREDECESSOR's answer in the same case directory, which is worse than saying nothing because an agent cannot tell a stale answer from a fresh one. The `DSH_HOME` override reaches the reader through the narrow `Session.deepSeekHomeOverride` getter rather than an `envOverrides` accessor, since that map can hold provider credentials; it is ephemeral by design (never persisted), so a session that overrode it and outlived a server restart resolves the default tree and reads as "nothing said yet". Tests: `test/deepseek-transcript.test.ts`.
+
+⚠️ **This is also what makes dsh the one non-claude mode the `codeman` agent skill drives like claude** (`skills/codeman/preamble.sh`, preamble 1.20.0): with a real end-of-turn signal AND a real transcript, `spawn_workers alpha beta:deepseek` is a mixed fleet in one call and `sendwait`/`last_text` need no per-mode variant. Two traps are handled in the preamble rather than left to the agent. **Readiness is not the stop signal**: the harness reports `idle` at BOOT roughly 300 ms before its composer paints (measured 2.26 s vs 2.56 s after spawn, twice), so a send-and-wait fired straight after `quick-start` resolves on the boot edge, reports a turn that never ran, and strands the prompt in a pane that was not yet accepting input — `spawn_worker`'s dsh branch gates on the composer glyph (`❯`, overridable via `DSH_READY_MARK`) instead, after which the boot edge is spent and unobservable. And `sendwait` asks for `wait:"stop,exit"` rather than the `wait:true` default set, because that set also carries `idle`, which for any external CLI is inferred from output stabilization: on a dsh worker whose TUI repaints rarely, a re-wait resolved in 0 ms with `signal:"idle"` on a turn that had three minutes left to run. The skill also sends `deepSeekConfig.permissionMode: 'danger-full-access'` for its own workers, matching what the Run button sends, because the harness default still asks and a worker parked on an approval row cannot finish a fan-out (the multi-user clamp still applies).
+
+⚠️ **The resolver needs the strictest identity probe of any CLI**, because `dsh` is not merely a squattable npm name: Debian ships an unrelated `dsh` (dancer's shell, `apt install dsh`) that would answer a version probe convincingly. `probeDeepSeekVersion()` therefore checks `dsh --help` against `DEEPSEEK_IDENTITY_REGEX` (`DeepSeek Harness`) FIRST and only then reads a version, and `test/deepseek-cli-resolver.test.ts` pins both the rejection and the VITEST hermeticity gate with a real executable fixture. `DEEPSEEK_VERSION_REGEX` keeps the prerelease tail (`0.1.1-rc.2`), since truncating it would report an rc as a release; it is shared with the `dsh` dependency-registry entry so doctor and run mode agree about the version even though the resolver is stricter about identity.
+
+Model is NOT a session field: it is a composition entry in the profile's config tree (`agent-default-model`), configured in `~/.dsh/settings.yaml` + `cordis.patch.yml`, so both create paths deliberately resolve no model for this mode. Env allowlist: `DSH_*` + `DEEPSEEK_*`; provider keys named by a settings-file `apiKeyEnv` stay OUT, which is pi's 34-provider-key problem in a new shape and gets the same answer. Docker seeds `~/.dsh` per-file (`.env`, `settings.yaml`, `cordis.patch.yml`) and the image installs its OWN profile, because `profiles/` is a per-profile `node_modules` tree — host-arch-specific and far too large to copy per container start. Stays OUT of `isAltScreenStripMode()` (third-party fullscreen TUI — the opencode case). ⚠️ `classifyProfile()` reads the profile's BUNDLES, and "unknown means launchable" is deliberate (anyone can publish an app bundle), but it has one knowably-wrong case: `readProfile()` returns an empty bundle list for a `package.json` with no `dsh.profile.bundles`, which made the SHIPPED `web`/`headless` profiles look third-party and launchable. The directory name is therefore consulted as a LAST resort (`STOCK_NON_INTERACTIVE_PROFILES`), after the bundle patterns, so real bundle evidence always wins over a name the user chose. The loose `tui` arm carries word boundaries for the same reason: it decides which profile boots by default, and matching the middle of `intuition` is not a rule anyone could predict. ⚠️ The generated shim is written **temp + rename**, not in place: the TUI can be exec'ing that exact path while an upgraded Codeman refreshes it, and a half-written file is a syntax error the caller then retries four times per state change forever. Bump `SHIM_VERSION` whenever `SHIM_SOURCE` changes, or an existing shim keeps matching the embedded marker and is never refreshed. Availability via `GET /api/deepseek/status`, the widest per-CLI status shape (`available`/`runnable`/`path`/`version`/`dshHome`/`defaultProfile`/`profiles`); `POST /api/deepseek/install-profile` bootstraps a profile and is the only endpoint in Codeman that installs third-party code — regex-confined specifier, argv-array spawn, privileged grant required in multi-user mode, and the held-open request is bounded by a HAND-ROLLED timeout over a `detached: true` process group (negative-pid SIGTERM→SIGKILL, as `runGit()` does in git-clone.ts). ⚠️ Node's own `spawn` `timeout` is NOT enough: a plugin install fans out into package-manager children, the built-in timeout signals only the direct child, and the survivors hold the inherited stdio pipes open so `close` never fires and the request leaks forever. User guide: `docs/deepseek-integration.md`. Tests: `test/deepseek-mode.test.ts`, `test/deepseek-cli-resolver.test.ts`.
 
 **Pi specifics** (#206, `docs/pi-integration.md`): command built by `buildPiCommand()` (`--model` — the only builder whose model regex admits `:` and `/`, for `sonnet:high` and `openai/gpt-4o` — plus `--provider`, `--thinking`, `--session <id>` / `-c`, and the TRI-STATE `--approve`/`--no-approve`). ⚠️ **Pi has no permission prompts and no sandbox**, so there is no `--dangerously-skip-permissions` analog and Codeman must not invent one; the privilege-shaped knob is `approveProjectTrust`, which makes pi LOAD AND EXECUTE repo-local `.pi/extensions` TypeScript and npm-install missing project packages. It therefore joins `clampExternalCliBypassForOwner()`'s **materialize** branch (gemini's, not codex/antigravity's only-if-sent one): an absent config still yields `--no-approve` for a non-granted owner, because pi's own default is an interactive prompt the session user could answer themselves. ⚠️ `--api-key` is NEVER wired — it would put a provider secret on the spawn command line. ⚠️ Pi stays **out** of `isAltScreenStripMode()`: its default TUI renders into the main screen with terminal-owned scrollback (nothing to strip), and since 0.84.0 the user can flip to a fullscreen TUI at runtime via `/settings`, where the alt screen is load-bearing — being out of the list is exactly what makes that switch safe. ⚠️ Only the `PI_*` env prefix was added; pi's ~34 provider keys share no prefix and `ALLOWED_ENV_PREFIXES` is a single GLOBAL list with no mode context, so admitting them would widen the allowlist for every mode at once (a mode-aware allowlist is the tracked follow-up). ⚠️ `pi` is a short, GENERIC binary name, so unlike the sibling resolvers `pi-cli-resolver.ts` sanity-probes `pi --version` (cached, vitest-skipped) and requires semver-shaped output; `GET /api/pi/status` carries `version` on top of the sibling `{available, path}` shape so a misresolution is diagnosable. Local echo: pi lands on the `'buffer'` overlay via the fallthrough in `_updateLocalEchoState` (pinned in `test/local-echo-codex-gating.test.ts`); if pi's live composer turns out to fight it the way codex's did, the fallback is one `'off'` branch. Tests: `test/pi-mode.test.ts`, `test/routes/external-cli-bypass-clamp.test.ts` (first-ever coverage of the clamp).
 
+**OMP (`omp`, Oh My Pi) specifics** (`docs/omp-integration.md`): architecturally the simplest of the family — omp owns its own auth, provider routing, and trust decisions entirely in `~/.omp` config files (default `tools.approvalMode: yolo`), so `buildOmpCommand()` only ever emits `--model`/`--resume <id>`/`--continue`, and there is no bypass-permissions flag for Codeman to wire or clamp. ⚠️ **That does NOT make the multi-user clamp a no-op**: `OMP_*` is an allowlisted `envOverrides` prefix and admits `OMP_AUTH_BROKER_URL`/`OMP_AUTH_BROKER_TOKEN` (where omp resolves credentials from), both dropped for a non-granted owner in `clampEnvOverridesForOwner()` — the same shape as `DEEPSEEK_BASE_URL` — even though, unlike DeepSeek, Codeman forwards no operator-held key into an omp pane today (found in Ark0N/Codeman#353 review). `--continue` alone is ambiguous the moment any other omp conversation has touched the same working directory more recently, since it just picks the newest session file on disk — `resolveAndClaimOmpSessionId()` (`src/utils/omp-session-resolver.ts`) resolves and PINS the real id instead, verifying each candidate's own file header (`{"type":"session","id",cwd"}`, not just the mangled-directory match) and tracking already-claimed ids in a process-wide registry so two omp tabs in the same case dir can't alias onto each other's conversation. ⚠️ Resolution/pinning happens ONLY at the point a respawn is actually confirmed (`_pinOmpRespawnId()`, called from `_setupOrAttachMuxSession()`'s dead-pane branch and `reattachRemote()`) — earlier code resolved eagerly while merely building respawn options, which could mis-pin a still-ALIVE session's id purely from boot-recovery timing. `src/omp-transcript.ts` independently scans `~/.omp/agent/sessions/**/*.jsonl` for Past Sessions history, the omp analog of Claude's own transcript scan, so a conversation survives even a full "Kill Tmux". ⚠️ omp's own env knobs are mostly `PI_*`, not `OMP_*` (`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, `PI_SUBPROCESS_CMD`, `PI_SHELL_PREFIX`), and `PI_*` is already allowlisted globally for pi — so a redirected `PI_CONFIG_DIR` silently moves the `~/.omp` tree the resolver and transcript scanner hardcode, degrading pinning/history with no error; a known gap shared with pi, not fixed here. ⚠️ Docker: `appendResumeFlag()`'s `case 'omp'` keys off the top-level `resumeSessionId`, which Docker panes never receive for omp (built from `defaultDockerCommandForMode`, with no `ompConfig` threaded through) — host-side history recovery and pinning work through the shared `sessions/` mount, but `--resume` does not currently reach an in-container omp process on respawn (flagged in review, not yet fixed). Stays out of `isAltScreenStripMode()` (narrow scrollback strip, alt-screen toggles only) and lands on the `'buffer'` local-echo policy via the `_updateLocalEchoState` fallthrough, same as grok and pi. Resolver: `omp-cli-resolver.ts` version-probes like pi/grok (`omp` is a short, generic name) and requires `omp/<semver>`-shaped output; `OMP_SEARCH_DIRS` leads with `~/.local/bin` (omp.sh's installer targets `$HOME/.local/bin` with no `--dir` override — verified against a real `--no-cache` Docker build, `~/.omp/bin` was the wrong first guess). Tests: `test/omp-mode.test.ts`, `test/omp-cli-resolver.test.ts`, `test/omp-session-resolver.test.ts`, `test/omp-fresh-run-no-resume.test.ts`.
+
 **Codex input path (issues #218/#219/#220/#222)**: codex-mode sessions use **predictive write-through echo, never the buffer overlay**. The buffer overlay stays disabled exactly as 1.12.2 left it (`_updateLocalEchoState` in terminal-ui.js, same branch as shell; `_localEchoEnabled` remains false for codex), and the additive `_localEchoPolicy` field selects `'predict'` for codex when `localEchoEnabled` is on. Codex's composer is interactive per keystroke: typing "/" pops a live-filtering command picker (#222 was "picker never appears" because the "/" sat in the overlay until Enter), the composer grows/rewraps as it fills (#220: a long typed prompt existed ONLY in the overlay DOM, so codex never grew the composer), arrows and Ctrl+Backspace edit server-side state (#218: arrows were forwarded to an EMPTY composer while the typed text sat pending; the `\x08` control-char flush then left the overlay stateless so `\x7f` was swallowed as "nothing to remove"), and pastes arrive bracketed (#219: `terminal.paste()` wraps in `\x1b[200~..201~`, which the multi-byte-ESC branch forwarded WITHOUT flushing pending text, so the paste landed before it). The shared overlay branch (claude/gemini/opencode still buffer) gained three fixes: bracketed pastes flush pending text first, composer nav keys (`isComposerNavKey` allowlist in `CodemanTerminalInput` — arrows/Home/End/Delete/PgUp/PgDn incl. modifiers, deliberately excluding DA/CPR/DSR query responses) flush and hand the session to **pass-through** (plain PTY echo until Enter/Ctrl+C, because after cursor movement the append-only overlay cannot track edits), and a backspace that finds no overlay state is FORWARDED instead of swallowed. ⚠️ **Codex drops keystrokes that arrive in the same PTY read as a bracketed paste** (upstream `bottom_pane/paste_burst.rs` holds rapid chars for paste classification; verified against codex 0.147.0 by writing `hello\x1b[200~PASTED\x1b[201~` into the tmux client PTY in one write → composer shows only `PASTED`, while a 100ms gap yields `helloPASTED`), so the flush sends the typed text immediately and delays the paste sequence by 80ms — the same two-phase shape as the Enter branch's delayed `\r`. Related protocol fact: xterm.js sends `0x08` for Ctrl+Backspace, which codex's keymap binds to delete-ONE-char (`ctrl(Char('h'))`); real word-delete needs the kitty CSI-u encoding (`\x1b[127;5u`), which xterm.js 6.0.0 cannot emit (kitty support lands in 6.1.0-beta) — an upstream limitation, not a Codeman bug. E2E technique: codex 0.147 reaches its composer with any dummy key in `$CODEX_HOME/auth.json` (`{"OPENAI_API_KEY":"sk-test-..."}`), so a real TUI can be driven headlessly (envOverrides `CODEX_HOME` rides the `CODEX_*` allowlist) without real credentials. **Predictive write-through echo invariants** (the codex echo mode, `PredictiveEchoAddon` in `packages/xterm-zerolag-input`): (1) the onData hook `_predictHookOnData` is a PLAIN STATEMENT between the buffer block and Normal Mode — no `return`, try/catch-wrapped, never touches `_pendingInput` — so the wire path is byte-identical with the predictor active, absent or throwing (pinned at vm level and by an end-to-end trace-equality E2E); (2) it ships as a SEPARATE bundle `vendor/xterm-predictive-echo.js` so the zerolag bundle stays byte-identical, and a missing/broken bundle degrades codex to plain 1.12.2 echo (`typeof PredictiveEchoOverlay !== 'undefined'` guard); (3) predictions paint only while the cursor sits on the measured composer row (`isCodexComposerRow`, `CODEX_COMPOSER_ROW_RE = /^› /` — matches the empty-composer placeholder, typing, and the slash picker; rejects modal rows and 2-space wrapped continuation rows, the #220 ghost zone, which deliberately fall back to real echo); (4) reconciliation reads the PARSED buffer with `baseY + row` (xterm's `cursorY` is baseY-relative; `viewportY` only coincides while scrolled to bottom), confirms prefix-only on cell match PLUS cursor advance, cascades only on TWO consecutive foreign NON-BLANK passes (blanks are neutral: codex clears its placeholder on first echo), and TTL-bounds the rest; (5) after an UNPREDICTED wire edit (backspace into echoed text, any 'clear'-classified input, an IME/plain-paste 'text' commit, or every bypass send incl. `_handleCjkInput`) the addon holds new predictions until the next PARSED write: the displayed cursor is stale for one RTT and anchoring on it paints ghosts one cell off; (6) the per-device `localEchoEnabled` toggle is the kill switch returning exact 1.12.2 behavior. Measured constants + fixtures: `docs/predictive-echo-plan.md`, recorded via `scripts/dev/record-codex-frames.mjs` through the production tmux+strip pipeline. Tests: `test/local-echo-codex-gating.test.ts` (vm harness: nav-key + predict classifier truth tables, policy matrix, wire-neutrality pins), `packages/xterm-zerolag-input/test/` (addon laws, real-fixture replay, seeded fuzz), `test/codex-predictive-echo.test.ts` (E2E vs real codex incLine truncated
 
 ### Remote sessions over SSH
@@ -36,7 +56,7 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### Docker cases
 
-**Docker cases** (shipped 1.4.0; user guide `docs/docker-cases.md`, design `docs/docker-cases-plan.md`): a case can point at a **container** instead of a local/remote path, and any of the five CLI backends runs INSIDE it. Like remote-SSH, it is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`** (`SessionMode` is unchanged). Storage `~/.codeman/docker-hosts.json` + `docker-cases.json` via `src/docker-hosts.ts` (direct mirror of `remote-hosts.ts`: `readDockerHosts`/`readDockerCases`, `toSessionDocker`, `dockerDisplayPath`, and the PURE builders `buildDockerBaseArgs`/`buildDockerCreateArgs`/`containerApiUrl`/`hostGatewayAlias`/`dockerConfigHash`). CRUD `/api/docker-hosts` + `/api/cases/docker-link`, plus **one-click** `/api/cases/docker-quickcreate` (Create New "Run in Docker" checkbox → case folder in `CASES_DIR` + auto-provisioned shared `default` host + auto-start a session inside; an expandable Template picker Small/Medium/Large/GPU or any override creates a per-case `q-<name>` host), and export/import (`/api/docker-cases/:name/export`, `/api/docker-cases/import`, `GET/DELETE /api/docker-exports`) — all in `case-routes.ts`. Run flows route through `POST /api/quick-start` like remote (session-routes.ts docker branch, skips LOCAL CLI-availability gates). **Launch model**: exactly one long-lived container **per case** (`codeman-case-<slug>`, PID1 `sleep infinity` under `--init`); a LOCAL tmux pane runs `docker exec -it` into a **durable in-container tmux** on dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>` (deliberately fails `SAFE_MUX_NAME_PATTERN` so a Codeman running INSIDE the container never adopts it, exactly like remote's `codeman-ssh-<id8>`). Builders `buildDockerLaunchCommand`/`buildDockerKillCommand` in `tmux-manager.ts` (image-check → `docker inspect||create` → start → exec, all idempotent). The container is **shared by all sessions of the case**: `buildDockerKillCommand` kills ONLY that session's in-container tmux session, NEVER `docker stop` while siblings remain; `docker rm -f` happens only on case-delete (plus an instance-scoped boot reaper keyed on the `codeman.instance` label). **Two-layer durability/resume** (the central design point): (1) Codeman-PROCESS restart with the container still up → `tmux new-session -A` reattaches the SAME live agent (paneCommand ignored); (2) container stop/reboot/OOM → inner tmux is gone, so the re-run pane command resumes the conversation from the bind-mounted transcript: claude mode pins a DETERMINISTIC conversation id via `claudeDockerPaneCommand()` (`tmux-manager.ts`) — fresh launch `claude --session-id <sessionId> || claude --resume <sessionId>` (a duplicate `--session-id` exits 1 "already in use", so the fallback RESUMES after a container stop; verified CLI behavior), explicit resume `--resume <rid> || --session-id <sid>` so a stale id never dead-panes (leading `exec ` is stripped — an exec'd first branch could never fall back); codex `resume <id>` / gemini `--resume` keep `appendResumeFlag`. The resume id rides `resumeSessionId` through create/respawn options and persists on `DockerCase.lastClaudeSessionId` via `persistDockerCaseClaudeSessionId()` (written at quick-start launch, and again on hook/last-response conversation-id adoption so post-`/clear` switches track; seeded back when `resumeOnStart`, default true); `-A` makes the pane command self-selecting (inert on reattach, active only when tmux was re-created). **Config drift** (`dockerConfigHash` → `codeman.confighash` label): quick-start compares via `checkDockerConfigDrift()` and REFUSES a drifted launch with `CONFLICT`; the UI confirm calls `POST /api/docker-cases/:name/recreate` (refused while case sessions are live) which `docker rm -f`s so the next launch recreates with the new config — host config edits actually take effect. **Workspace** is a REAL host dir bind-mounted at the SAME absolute path (mirror, `dst==src`), so `Session.workingDir = hostWorkspacePath` keeps file-routes/attachments/watchers on real host bytes AND the in-container transcript projHash matches the host so subagent/workflow correlation (and thus resume-id capture) works; `resolveMuxAttachCwd` returns `/tmp` for docker (the local pane only runs `docker exec`). **Creds** arrive commit-safe and ISOLATED (1.4.1; replaced the whole-dir RW mounts that let in-container CLIs write refreshed tokens/state back to the host): shared RW across the boundary is ONLY what host-side reads/resume need (`~/.claude/projects` transcripts; codex `sessions/` + `history.jsonl` for response-viewer/`codex resume`); everything else is SEEDED (RO mount, copied into container HOME once at launch via `[ -e ] || cp`; the container refreshes its own copy and never writes back): `~/.claude.json` is merged through `buildSeamlessClaudeConfig()` (forces `hasCompletedOnboarding` + theme + workspace trust, so no login wizard/theme picker/trust prompt inside the container), plus `.claude/{.credentials.json,settLine truncated
+**Docker cases** (shipped 1.4.0; user guide `docs/docker-cases.md`, design `docs/docker-cases-plan.md`): a case can point at a **container** instead of a local/remote path, and any of the CLI run modes runs INSIDE it. Like remote-SSH, it is a **LOCATION OVERLAY on cases, never a `SessionMode` of its own** (`SessionMode` is unchanged). Storage `~/.codeman/docker-hosts.json` + `docker-cases.json` via `src/docker-hosts.ts` (direct mirror of `remote-hosts.ts`: `readDockerHosts`/`readDockerCases`, `toSessionDocker`, `dockerDisplayPath`, and the PURE builders `buildDockerBaseArgs`/`buildDockerCreateArgs`/`containerApiUrl`/`hostGatewayAlias`/`dockerConfigHash`). CRUD `/api/docker-hosts` + `/api/cases/docker-link`, plus **one-click** `/api/cases/docker-quickcreate` (Create New "Run in Docker" checkbox → case folder in `CASES_DIR` + auto-provisioned shared `default` host + auto-start a session inside; an expandable Template picker Small/Medium/Large/GPU or any override creates a per-case `q-<name>` host), and export/import (`/api/docker-cases/:name/export`, `/api/docker-cases/import`, `GET/DELETE /api/docker-exports`) — all in `case-routes.ts`. Run flows route through `POST /api/quick-start` like remote (session-routes.ts docker branch, skips LOCAL CLI-availability gates). **Launch model**: exactly one long-lived container **per case** (`codeman-case-<slug>`, PID1 `sleep infinity` under `--init`); a LOCAL tmux pane runs `docker exec -it` into a **durable in-container tmux** on dedicated socket `-L codeman-docker`, session `codeman-dkr-<id8>` (deliberately fails `SAFE_MUX_NAME_PATTERN` so a Codeman running INSIDE the container never adopts it, exactly like remote's `codeman-ssh-<id8>`). Builders `buildDockerLaunchCommand`/`buildDockerKillCommand` in `tmux-manager.ts` (image-check → `docker inspect||create` → start → exec, all idempotent). The container is **shared by all sessions of the case**: `buildDockerKillCommand` kills ONLY that session's in-container tmux session, NEVER `docker stop` while siblings remain; `docker rm -f` happens only on case-delete (plus an instance-scoped boot reaper keyed on the `codeman.instance` label). **Two-layer durability/resume** (the central design point): (1) Codeman-PROCESS restart with the container still up → `tmux new-session -A` reattaches the SAME live agent (paneCommand ignored); (2) container stop/reboot/OOM → inner tmux is gone, so the re-run pane command resumes the conversation from the bind-mounted transcript: claude mode pins a DETERMINISTIC conversation id via `claudeDockerPaneCommand()` (`tmux-manager.ts`) — fresh launch `claude --session-id <sessionId> || claude --resume <sessionId>` (a duplicate `--session-id` exits 1 "already in use", so the fallback RESUMES after a container stop; verified CLI behavior), explicit resume `--resume <rid> || --session-id <sid>` so a stale id never dead-panes (leading `exec ` is stripped — an exec'd first branch could never fall back); codex `resume <id>` / gemini `--resume` keep `appendResumeFlag`. The resume id rides `resumeSessionId` through create/respawn options and persists on `DockerCase.lastClaudeSessionId` via `persistDockerCaseClaudeSessionId()` (written at quick-start launch, and again on hook/last-response conversation-id adoption so post-`/clear` switches track; seeded back when `resumeOnStart`, default true); `-A` makes the pane command self-selecting (inert on reattach, active only when tmux was re-created). **Config drift** (`dockerConfigHash` → `codeman.confighash` label): quick-start compares via `checkDockerConfigDrift()` and REFUSES a drifted launch with `CONFLICT`; the UI confirm calls `POST /api/docker-cases/:name/recreate` (refused while case sessions are live) which `docker rm -f`s so the next launch recreates with the new config — host config edits actually take effect. **Workspace** is a REAL host dir bind-mounted at the SAME absolute path (mirror, `dst==src`), so `Session.workingDir = hostWorkspacePath` keeps file-routes/attachments/watchers on real host bytes AND the in-container transcript projHash matches the host so subagent/workflow correlation (and thus resume-id capture) works; `resolveMuxAttachCwd` returns `/tmp` for docker (the local pane only runs `docker exec`). **Creds** arrive commit-safe and ISOLATED (1.4.1; replaced the whole-dir RW mounts that let in-container CLIs write refreshed tokens/state back to the host): shared RW across the boundary is ONLY what host-side reads/resume need (`~/.claude/projects` transcripts; codex `sessions/` + `history.jsonl` for response-viewer/`codex resume`); everything else is SEEDED (RO mount, copied into container HOME once at launch via `[ -e ] || cp`; the container refreshes its own copy and never writes back): `~/.claude.json` is merged through `buildSeamlessClaudeConfig()` (forces `hasCompletedOnboarding` + theme + workspace trust, so no login wizard/theme picker/trust prompt inside the container), plus `.claude/{.credentials.json,setLine truncated
 
 ## Session data and lifecycle
 
@@ -68,7 +88,7 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### Plan-usage chip (statusLine telemetry)
 
-**Plan-usage chip** (statusLine telemetry, `showPlanUsageLimits`, per-device: desktop default **ON** since 1.9.3, handhelds OFF): Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, identified by the `/api/status-telemetry` marker — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through** (so injecting our statusLine doesn't blank the in-terminal footer). `plan-usage-latest.ts` holds the process-wide last value, replayed in the SSE init snapshot (`getLightState`) so the header chip (`#planUsageChip`, revealed by `planUsageChipEnabled()` in settings-ui.js, the single resolver behind the checkbox, the chip and the create-time `statusLineTelemetry` flag) renders immediately on page load / reconnect without per-browser localStorage. Claude-mode only. **Distinct from auto-resume** (which reacts to the limit _message_; this proactively shows the live %). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`.
+**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON** since 1.9.3, handhelds OFF) renders compact Claude and Codex provider rows. Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command` on each render; on Pro/Max it carries a `rate_limits` object (`five_hour`/`seven_day` windows only — no Opus weekly field — each `{used_percentage 0-100, resets_at epoch-SECONDS}`). Codeman injects its OWN statusLine exporter (`generateStatusLineCommand()` in `hooks-config.ts`, identified by the `/api/status-telemetry` marker — it only ever adds/updates/removes a statusLine that is _ours_, never a user's hand-authored one) that POSTs the blob to `POST /api/status-telemetry`. That route (auth-exempt like `/api/hook-event` — localhost-only, hook-secret-gated whenever auth is active, COD-91) parses via `usage-telemetry.ts` (pure, unit-tested), broadcasts SSE `session:statusTelemetry` (de-duped per session by `telemetrySignature` since the statusline fires on every assistant message), and returns a compact plain-text footer for the exporter to **print-through**. Main Codex subscription usage comes from the signed-in host CLI's read-only app-server `account/rateLimits/read` request at startup and every 5 minutes; `usage-telemetry.ts` selects only the main `codex` bucket (never model-specific buckets such as Spark), maps whatever 5-hour/7-day windows it supplies, and omits the provider row when unavailable. Credentials stay inside the CLI and no auth material is sent to the browser. `plan-usage-latest.ts` merges both process-wide sources and replays them in the SSE init snapshot (`getLightState`) so `#planUsageChip` renders immediately on page load/reconnect. `planUsageChipEnabled()` remains the single resolver behind the checkbox, chip visibility, and Claude create-time exporter flag. **Distinct from auto-resume** (which reacts to the Claude limit _message_; this proactively shows live percentages). Design: `docs/usage-limits-display-plan.md`. Tests: `test/usage-telemetry.test.ts`, `test/codex-plan-usage.test.ts`, `test/plan-usage-chip.test.ts`, `test/plan-usage-latest.test.ts`.
 
 ### Cron jobs
 
@@ -92,13 +112,15 @@ Implementation detail extracted from `CLAUDE.md` so that file stays small enough
 
 ### Full-scrollback replay
 
-**Full-scrollback replay** (COD-164/#148, reworked for #205): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). The first load OF EACH SESSION per page load requests `full=1` (`_fullHistoryLoaded` Set in app.js — the old one-shot `_initialFullBufferLoad` flag was consumed by whichever tab auto-selected, leaving every other tab one frame of history); later switches keep the cheap `?tail=` visible-frame path. On top of that, scrolling up while already at the TOP of the buffer re-pulls `full=1` on demand (`_maybeRefetchFullHistory`, 4s per-session cooldown, in-flight + tab-switch guards, viewport position held across the replay). The re-pull exists because xterm's buffer is only a WINDOW onto tmux's history and two things shrink it: tmux coalesces bursty output into pane REPAINTS that overwrite rows instead of emitting linefeeds (measured: a 60-line burst added 1 row of browser scrollback and destroyed 34), and a tab switch replays only the visible frame. tmux's own history is intact throughout — the browser just has to ask for it again. On-demand rather than automatic because at a 100k history limit the capture can be megabytes. ⚠️ **The re-pull must never DOWNGRADE the buffer** (#205 round 2): the same reasoning that makes it a win for a shell pane makes it destructive for a repaint-mode CLI pane, where tmux keeps no history of its own (`history_size≈0` measured for a Claude pane) and the capture is roughly ONE frame while xterm may hold hundreds of rows of replayed frames — `_resetTerminalForReplay()` + rewrite then deletes history mid-scroll ("goes back a bit, repeats blocks, gets worse the further up I go"; measured A/B on a live pane: 341 rows → 42 with the guard off). `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the capture's rendered rows — escape sequences stripped, `capture-pane -J` re-wrapping accounted for — and the pull is skipped when that is more than one screen short of `buffer.active.length`. The one-screen tolerance matters: both sides are estimates (the buffer length counts trailing blank rows), so only a clear downgrade is refused. A refused session joins `_fullHistoryRepullUseless`, raising its cooldown from 4s to 60s so a hollow pane stops re-fetching megabytes on every scroll-up. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`, `test/terminal-scroll-routing.test.ts`.
+**Full-scrollback replay** (COD-164/#148, reworked for #205): `GET /api/sessions/:id/terminal?full=1` returns the ENTIRE tmux scrollback (capture-pane `-e -S -<lines>` bounded by the configured history limit, explicit `maxBuffer` from the terminal-history config, early byte-cap before normalization, CRLF-normalized for shell panes). On success the capture is returned ALONE (`source='mux-full-history'` — it supersedes the byte buffer; no duplication). The first load of each non-shell TUI session per page requests `full=1` (`_fullHistoryLoaded` Set in app.js — the old one-shot `_initialFullBufferLoad` flag was consumed by whichever tab auto-selected, leaving every other TUI tab one frame of history). Shell sessions instead load a bounded 1 MiB `?tail=` window on every selection and automatic drop recovery: a 100k-line shell capture can be tens of MiB, and automatically parsing it makes tab-switch latency scale with the entire session. Shell full history is explicit-button-only; reaching the top during an ordinary wheel/touch gesture must not reset xterm and replay the multi-megabyte capture on its main thread. Other modes may still re-pull `full=1` at the TOP, and pressing **Load full history** forces the request for any recoverably truncated session (`_maybeRefetchFullHistory`, 4s per-session gesture cooldown, in-flight + tab-switch guards, viewport position held across the replay); Shell full pulls are not retained in the tab cache, so the next switch stays bounded. Chunked replay enqueues 32 KiB pieces across safe yields, appends an xterm parse marker, then releases the live-output gate; output arriving after that release stays ordered behind the snapshot, while the marker callback supplies accurate parse timing without extending the pre-existing queued-event discard window. Live output is separately one-chunk-in-flight: xterm's callback releases each 32/64 KiB write before the next is submitted, keeping the remainder in the app queue where the 128 KiB cap can observe it instead of hiding an unbounded backlog in xterm's private WriteBuffer. While WebSocket owns terminal I/O, parallel SSE terminal/output-recovery events are discarded before JSON parsing; fallback recovery is single-flight per active session so backpressure cannot start overlapping reset+replay cycles. The route exposes capture/prepare totals in `Server-Timing`, while `[TERMINAL-PERF]` separates TTFB, body/JSON, reset+parse and total time for both selection and on-demand full pulls; parse completion is not a browser compositor/GPU paint measurement. The re-pull exists because xterm's buffer is only a WINDOW onto tmux's history and two things shrink it: tmux coalesces bursty output into pane REPAINTS that overwrite rows instead of emitting linefeeds (measured: a 60-line burst added 1 row of browser scrollback and destroyed 34), and a tab switch replays only the visible frame. tmux's own history is intact throughout — the browser just has to ask for it again. On-demand rather than automatic because at a 100k history limit the capture can be megabytes. ⚠️ **The re-pull must never DOWNGRADE the buffer** (#205 round 2): the same reasoning that makes it a win for a shell pane makes it destructive for a repaint-mode CLI pane, where tmux keeps no history of its own (`history_size≈0` measured for a Claude pane) and the capture is roughly ONE frame while xterm may hold hundreds of rows of replayed frames — `_resetTerminalForReplay()` + rewrite then deletes history mid-scroll ("goes back a bit, repeats blocks, gets worse the further up I go"; measured A/B on a live pane: 341 rows → 42 with the guard off). `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the capture's rendered rows — escape sequences stripped, `capture-pane -J` re-wrapping accounted for — and the pull is skipped when that is more than one screen short of `buffer.active.length`. The one-screen tolerance matters: both sides are estimates (the buffer length counts trailing blank rows), so only a clear downgrade is refused. A refused session joins `_fullHistoryRepullUseless`, raising its cooldown from 4s to 60s so a hollow pane stops re-fetching megabytes on every scroll-up. Tests: `test/tmux-capture-full-history.test.ts`, `test/tmux-scrollback-eol.test.ts`, `test/terminal-scroll-routing.test.ts`, `test/terminal-flush-budget.test.ts`.
 
 ### Terminal scrollback: strip flavors and wheel/touch forwarding
 
-**Two strip flavors, one carry** (#205, `session.ts:_handleTerminalOutput`): the FULL strip (`isAltScreenStripMode` = codex/claude/gemini) removes alt-screen toggles, `3J`, and mouse-tracking DECSETs. Every other mode (shell/opencode/antigravity/pi) gets the NARROW strip (`isMuxAltScreenOnlyStripMode`) — alt-screen toggles ONLY — and only when tmux-backed (`useMux`). Rationale: the tmux CLIENT emits `smcup` as its first bytes at attach, before any program runs, parking xterm in the scrollback-less alternate buffer for the whole session (touch scrolling no-ops; xterm's own wheel handler converts the wheel to Up/Down arrows = readline history cycling — both #205 symptoms). tmux never forwards a pane program's alt-screen toggles to its client (it repaints instead; measured — vim/less inside a pane emit zero to the client), so the only thing the narrow strip ever removes is tmux's own smcup. It keeps `3J` (a user's `clear` is a deliberate scrollback wipe) and the mouse DECSETs (tmux passes those through even with `mouse off`; stripping them would break htop/vim mouse support). ⚠️ The `useMux` gate is load-bearing: `startShell()`/`startInteractive()` fall back to a DIRECT PTY when mux creation fails, and there the inner program's own `?1049h` really does reach xterm — stripping it would break vim/less/htop for real. The replay path (`session-routes.ts`, via `session.usesMux`) applies the same narrow branch; the frontend `_sessionUsesServerMouseStrip()` mirror stays claude/codex/gemini because only the FULL strip touches mouse DECSETs. The chunk-boundary carry (`_altScreenSeqCarry`) runs for both flavors. Tests: `test/claude-scrollback-strip.test.ts`.
+**Two strip flavors, one carry** (#205, `session.ts:_handleTerminalOutput`): the FULL strip (`isAltScreenStripMode` = codex/claude/gemini) removes alt-screen toggles, `3J`, and mouse-tracking DECSETs. Every other mode (shell/opencode/antigravity/pi) gets the NARROW strip (`isMuxAltScreenOnlyStripMode`) — alt-screen toggles ONLY — and only when tmux-backed (`useMux`). Rationale: the tmux CLIENT emits `smcup` as its first bytes at attach, before any program runs, parking xterm in the scrollback-less alternate buffer for the whole session (touch scrolling no-ops; xterm's own wheel handler converts the wheel to Up/Down arrows = readline history cycling — both #205 symptoms). tmux never forwards a pane program's alt-screen toggles to its client (it repaints instead; measured — vim/less inside a pane emit zero to the client), so the only thing the narrow strip ever removes is tmux's own smcup. It keeps `3J` (a user's `clear` is a deliberate scrollback wipe) and the mouse DECSETs (tmux passes those through even with `mouse off`; stripping them would break htop/vim mouse support). ⚠️ The `useMux` gate is load-bearing: `startShell()`/`startInteractive()` fall back to a DIRECT PTY when mux creation fails, and there the inner program's own `?1049h` really does reach xterm — stripping it would break vim/less/htop for real. The replay path (`session-routes.ts`, via `session.usesMux`) applies the same narrow branch; the frontend mirror (`_shouldReportMouseToCli()`) stays claude/codex/gemini because only the FULL strip touches mouse DECSETs. The chunk-boundary carry (`_altScreenSeqCarry`) runs for both flavors. Tests: `test/claude-scrollback-strip.test.ts`.
 
-**Only claude ≥ 2.1.187 forwards the wheel; every other mode scrolls local scrollback** (#227 follow-up, `terminal-ui.js:_shouldForwardWheelToApp`). Codex was in the forward list until a reporter hit a completely dead wheel in codex tabs while the scrollbar drag worked. Measured against codex-cli 0.147.0 in a bare tmux: it never enables mouse tracking (`mouse_any_flag=0`) and SGR wheel reports fed to its PTY change nothing on screen, because it runs an INLINE viewport (`alternate_on=0`) and pushes its transcript into the terminal's own scrollback (tmux `history_size` grows) instead of paging in-app. So for codex, local scrollback IS the transcript and forwarding swallowed every tick. ⚠️ "The TUI is a strip mode" is NOT evidence that it consumes wheel reports — verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR TAPS stay enabled for codex (`_sessionUsesServerMouseStrip`); measured, they are no-ops that insert nothing, so click-to-position is simply unavailable there rather than harmful.
+⚠️ **What the full strip removes, it must REMEMBER.** Stripping the mouse DECSETs means xterm's `modes.mouseTrackingMode` is permanently `'none'` for those modes, so the browser hand-encodes click reports to compensate (`_sendSyntheticSgrTap`). With no state to consult it did that on EVERY click, which delivered mouse reports to programs that never asked for them: the same pane runs a plain shell whenever the CLI has exited or a `shell` was started inside a claude-mode session, and a shell prints the report as literal text (`[<0;88;20M`), garbling the next line typed. `_recordStrippedMouseMode()` therefore records each stripped sequence as it goes and publishes `cliMouseTracking` through `toState()`, and `_shouldReportMouseToCli()` requires it. ⚠️ Only the TRACKING modes count (1000/1001/1002/1003): 1005/1006 select an ENCODING and 1007 is alt-scroll, and counting those would put the stray reports straight back. ⚠️ The change broadcasts IMMEDIATELY rather than through `broadcastSessionStateDebounced`, because the flag flips when a dialog opens and the user can click that dialog inside the 500ms debounce window. Measured on a live claude 2.x: the CLI holds a tracking mode on continuously (so clicks keep being reported exactly as before), while a bash prompt in the same stripped mode reports nothing. Fails toward silence: after a server restart the flag is false until the CLI re-emits, which tmux does at client attach.
+
+**Only claude ≥ 2.1.187 forwards the wheel; every other mode scrolls local scrollback** (#227 follow-up, `terminal-ui.js:_shouldForwardWheelToApp`). Codex was in the forward list until a reporter hit a completely dead wheel in codex tabs while the scrollbar drag worked. Measured against codex-cli 0.147.0 in a bare tmux: it never enables mouse tracking (`mouse_any_flag=0`) and SGR wheel reports fed to its PTY change nothing on screen, because it runs an INLINE viewport (`alternate_on=0`) and pushes its transcript into the terminal's own scrollback (tmux `history_size` grows) instead of paging in-app. So for codex, local scrollback IS the transcript and forwarding swallowed every tick. ⚠️ "The TUI is a strip mode" is NOT evidence that it consumes wheel reports — verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR TAPS are gated by `_shouldReportMouseToCli()` (strip mode AND the server-observed `cliMouseTracking` flag, recorded by `_recordStrippedMouseMode` in session.ts as it strips): codex never enables mouse tracking, so since #325 no tap report is sent there at all — click-to-position was already a measured no-op in codex, and a pane that has fallen back to a shell no longer receives `[<0;88;20M` junk.
 
 **Wheel/touch forwarding is NOT gated on viewport-at-bottom** (#205, `terminal-ui.js:_shouldForwardWheelToApp`): for sessions verified to scroll their own transcript on SGR wheel reports (claude ≥ 2.1.187 — version via the local/docker/remote `--version` probes), the plain wheel AND touch drags forward as coalesced SGR reports (`_forwardScrollToApp` → `_sendSyntheticSgrWheel`, 40ms batches, 5-tick cap, 512-byte queue bound). It used to gate on the viewport being at the bottom so both scrollbacks stayed reachable, but a repaint-mode CLI keeps NO terminal scrollback of its own — xterm's buffer holds only replayed repaint frames, so local scrolling drags the CLI's pinned prompt box up the screen over stale frames; and `scrollToLastNonEmptyLine()` routinely parked the viewport off-bottom, silently pinning the wheel to local. Forwarding now snaps the viewport home first (SGR coordinates address the LIVE screen — a report computed from a scrolled-up viewport would hit-test the wrong row). Local scrollback remains on Shift+wheel and the `terminalWheelLocalScrollback` opt-out (both also cover touch via the shared gate; touch has no Shift, so the setting is its only local pin). `_wheelScrollLines()` normalizes `deltaMode` (Firefox fires LINE deltas ≈3/notch — read as pixels that rounded to 0 and fell to the ±1 fallback, ~4× too slow; PAGE deltas scale by `terminal.rows`) while keeping the #154 Shift-axis trap (macOS trackpads put Shift+scroll magnitude on deltaX). Tests: `test/terminal-touch-tap.test.ts`.
 
@@ -217,7 +239,7 @@ Invariants:
 
 ### Web tabs
 
-**Web tabs** (saved dashboard URLs rendered as tabs beside agent sessions; user guide `docs/web-tabs.md`). A webview is **NOT a sixth `SessionMode`**: no PTY, no tmux, no respawn, no idle detection. It is a separate resource (`~/.codeman/webviews.json` via `src/webview-store.ts`, types in `src/types/webview.ts`, limits in `src/config/webview-limits.ts`) that shares only the tab strip and the main content area, exactly as Docker and remote-SSH are case overlays rather than modes.
+**Web tabs** (saved dashboard URLs rendered as tabs beside agent sessions; user guide `docs/web-tabs.md`). A webview is **NOT a `SessionMode` of its own**: no PTY, no tmux, no respawn, no idle detection. It is a separate resource (`~/.codeman/webviews.json` via `src/webview-store.ts`, types in `src/types/webview.ts`, limits in `src/config/webview-limits.ts`) that shares only the tab strip and the main content area, exactly as Docker and remote-SSH are case overlays rather than modes.
 
 **Why there is a reverse proxy at all.** A direct `<iframe src="http://box:4000">` fails three independent ways in the shipped deployment: (1) prod serves `--https` behind `tailscale serve`, and browsers hard-block `http://` iframes on an HTTPS page with no override (none at all on iOS Safari); (2) Grafana/Portainer/Home-Assistant-class dashboards send `X-Frame-Options: DENY` or `frame-ancestors 'none'`; (3) our own `default-src 'self'` CSP makes `frame-src` fall back to `'self'`. Serving the dashboard through Codeman's origin dissolves all three, and as a bonus leaves the production CSP **byte-for-byte unchanged**, because `/webview/...` is already covered by `'self'`. A `direct` mode still exists for HTTPS targets that permit framing; `POST /api/webviews/probe` runs a server-side reachability + framing check and recommends which to use.
 
@@ -258,6 +280,22 @@ Invariants:
 
 Copy goes through `_copyText()` (Clipboard API, then hidden-textarea + `execCommand`), not raw `navigator.clipboard`, because `install.sh`'s LAN option serves plain HTTP where `navigator.clipboard` is undefined; the fallback steals focus, so the terminal is refocused afterwards. Related: xterm registers its own `copy` listener on the terminal element gated on `hasSelection()`, which is why right-click → Copy has always worked. Selection itself is unavailable on touch devices by design (`user-select: none` on the terminal subtree), and in `shell`/`opencode`/`antigravity` tabs the TUI owns the mouse, so selecting there needs Shift+drag. Tests: `test/terminal-copy-selection.test.ts` (gate + wiring invariants), `test/terminal-copy-shortcut.test.ts` (browser, real key presses).
 
+### Auto Copy (copy-on-select)
+
+**Auto Copy** (`autoCopySelection`, per-device, default OFF) puts a finished terminal selection on the clipboard without a keystroke. It is a thin layer over the smart-copy machinery above and shares `_copyText()` with it, but the two paths differ in every decision that matters:
+
+- **It fires at the END of a gesture, never on selection change.** `onSelectionChange` runs for every cell a drag crosses, so copying there would be one clipboard write per mouse move. The callback only ARMS `_autoCopyPending`; the flush is a document-level `mouseup` listener installed once in `initTerminal`, plus explicit calls from the touch selection path.
+- **The flush is synchronous inside the handler.** Both clipboard paths need user activation: Firefox gates `navigator.clipboard.writeText` on it, and `document.execCommand('copy')` (the plain-HTTP fallback that `install.sh`'s LAN option lands on) has to run in the gesture's own task. Deferring to a timer or waiting for `onSelectionChange` loses it, and the failure is browser-specific and invisible in Chrome.
+- **The listener is on `document`, not the terminal container**, because a drag that ends outside the terminal (sweeping up past the header) delivers its mouseup to the document. Unrelated mouseups elsewhere on the page are filtered by the decision helper, not by the listener's target.
+- **Touch has its own entry point.** `_endTouchSelectionGesture()` and `_selectTouchSelectionLine()` call the flush directly, because the touch path `preventDefault()`s its touchend (that is what stops the compat mouse pair from stealing the selection back), so no mouseup ever reaches the document there. Without those two calls the toggle is simply dead on a phone.
+- **It must NOT do what `copyTerminalSelection()` does.** That one clears the selection (so a second `Ctrl+C` is an interrupt) and focuses the terminal. Clearing would make text vanish from under the cursor that just highlighted it, and focusing opens the on-screen keyboard over it on a phone. Focus is instead RESTORED to whatever held it before the copy, which only matters for the `execCommand` fallback (it focuses a temp textarea on the way through); the Clipboard API path never moves focus at all.
+
+`decideAutoCopy()` (constants.js, pure) holds the guards: setting off, blank or whitespace-only text (what a drag across empty cells produces), and a `AUTO_COPY_MAX_CHARS` (1M) cap. ⚠️ The cap is not decoration: a drag off the top of the viewport autoscrolls, so one gesture can sweep the whole 50k-line scrollback. Past it the copy is REFUSED rather than truncated, with a toast pointing at `Ctrl+C`, which still copies everything through the explicit path.
+
+⚠️ **Two dedupe rules, and both earn their place.** A genuine selection change (`pending`) always copies, so re-selecting the same text after copying something else in between still works. Otherwise only text differing from the last auto-copy does, which is what stops an unrelated mouseup from re-copying a stale selection AND what makes the first copy of a drag work at all: xterm fires `onSelectionChange` from its own document `mouseup` handler, and listener order between the two is registration order, not something this code controls. Gating on `pending` alone silently drops that first copy.
+
+Feedback is silent on success except ONCE per page load (a feature that works by doing nothing visible cannot otherwise be told from a dead toggle); failures and refusals toast, throttled to 10s so a permanently blocked clipboard cannot paint a toast on every drag. The setting is per-device on both counts required by the settings rule: it is in `displayKeys` AND absent from the `.strict()` `SettingsUpdateSchema` (clipboard access differs by device and by origin, and the plain-HTTP LAN install has no `navigator.clipboard` at all). Tests: `test/terminal-auto-copy.test.ts`.
+
 ### Settings surface: App Settings, Session Options, Add Case
 
 **One visual language, three modals.** `#appSettingsModal`, `#sessionOptionsModal` and `#createCaseModal` share the `set-*` surface (left rail, sections of grouped row cards, label + description on the left, control pinned right) through a single `:is(#appSettingsModal, #sessionOptionsModal, #createCaseModal)` scope in `styles.css`. An `:is()` list takes the specificity of its **most specific argument**, and all three arguments are ids, so every rule kept exactly the weight it had when the block was `#appSettingsModal`-only: nothing downstream shifted in the cascade. That property is what let the surface absorb Session Options and then Add Case in two separate commits without a cascade audit each time.
@@ -359,7 +397,7 @@ Anatomy: `.set-shell` → `.set-shell-head` (title + `.set-head-actions`) + `.se
 
 ### Buffers, uploads, and terminal history
 
-Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired live); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
+Target: 20 sessions, 50 agent windows at 60fps. Limits in `src/config/`: terminal 32MB (see below), text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100. **Terminal history** (`src/config/terminal-history.ts`, COD-80): tmux history-limit 100k lines, PTY buffer 32MB max / 24MB trim (env `CODEMAN_MAX_TERMINAL_BUFFER`/`CODEMAN_TRIM_TERMINAL_TO`; the env-derived trim is clamped ≤75% of max — trim ≥ max would disable `BufferAccumulator` trimming entirely = unbounded memory); browser xterm scrollback stays a separate hardcoded 50k (`DEFAULT_SCROLLBACK` in constants.js — 100k/tab is a mobile-memory hazard). tmux <3.7 allocates history at pane creation, so `createSession()` sets the global default in the same command queue immediately before `new-session`; tmux 3.7+ instead creates the session and targets only that pane, because changing the global option can resize and trim unrelated live panes. A settings change resizes tracked panes only on 3.7+ and otherwise affects future panes; no version can recover lines already evicted. Settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but inert (only `tmuxHistoryLimit` is wired); `buffer-limits.ts` re-exports the defaults. Text/message limits are env-overridable too (`CODEMAN_MAX_TEXT_OUTPUT`/`CODEMAN_TRIM_TEXT_TO`/`CODEMAN_MAX_MESSAGES`). **Image upload** (`image-input.js` / `config/buffer-limits.ts`): up to `_maxBatchImages` 20 images/batch (bounded concurrency 3), per-file `MAX_PASTE_IMAGE_BYTES` 50MB (env `CODEMAN_MAX_PASTE_IMAGE_BYTES`); the mobile camera-roll picker auto-downscales to fit before upload. **HEIC paste uploads** (#151): converted server-side to JPEG in a `worker_threads` worker (`web/heic-jpeg-worker.ts`, resourceLimits + 30s timeout) gated by `runWithConversionLimit()`; detection is magic-byte based (covers Android/MIUI HEIFs mislabeled as JPEG); headers declaring > 64MP are rejected 415 BEFORE decode (decompression-bomb guard). Deps: `heic-decode` + `jpeg-js`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Anti-flicker pipeline: `docs/terminal-anti-flicker.md`.
 
 ## Local packages and build artifacts
 

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,305 @@
+# 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
+```
+
+⚠️ **`pnpm` has to be on PATH for either route.** `dsh plugin` is a thin forwarder
+that spawns a literal `pnpm` with no npm fallback, so without one it exits 127 with
+`dsh: pnpm not found on PATH` — both by hand and behind the UI button, which
+surfaces that same line as the install error. `npm install -g pnpm` (or
+`corepack enable pnpm`) is the fix. This is what broke the Docker agent image in
+[#352](https://github.com/Ark0N/Codeman/issues/352); the image now installs pnpm
+alongside `dsh`.
+
+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` / `deepseek` / `omp` all work inside the container.
 
 ## One-time setup: build the base image
 
@@ -25,12 +25,24 @@ 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 dsh omp; 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.
+⚠️ `dsh --version` is the one line above that answers a different question than the
+others: `dsh` is a profile launcher, so a working binary says nothing about whether
+the image can actually run a DeepSeek session. Check the profile the Dockerfile
+installs into the agent's HOME as well, or a `mode: 'deepseek'` case starts a pane
+that dies on arrival:
 
-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).
+```bash
+docker run --rm codeman/agent:base ls ~/.dsh/profiles/dsh-tui/package.json
+```
+
+Building that profile is also why `pnpm` is in the image: `dsh plugin` forwards straight to a literal `pnpm` and exits 127 without it (issue #352), and pnpm — unlike npm — blocks dependency lifecycle scripts by default and fails the install over it, so the profile step passes `--config.dangerouslyAllowAllBuilds=true`.
+
+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). 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). OMP is the one CLI in this family where `sessions/` is the EXCEPTION rather than the rule: `~/.omp/agent/{config.yml,mcp.json,models.yml,settings.yml}` are seeded per-file (the dir also holds SQLite caches and `terminal-sessions/`), but `~/.omp/agent/sessions/` is shared RW like codex's, not seeded, because Codeman reads it host-side for history recovery and `--resume` pinning. See [`omp-integration.md`](./omp-integration.md).
 
 ## Quickest path: one-click "Run in Docker"
 

docs/docker-compose.md

@@ -0,0 +1,68 @@
+# Docker Compose deployment
+
+This configuration builds the Codeman application image locally from this checkout. It does not download or depend on a pre-built Codeman image.
+
+For the Compose configuration, environment settings, storage migration, and macvlan networking examples, see the [Docker deployment guide](../docker/README.md).
+
+The image includes Claude Code, Codex, Gemini CLI, and OpenCode. Authenticate a CLI from its Codeman session; credentials are never baked into the image.
+
+## Prerequisites
+
+- Docker Engine or Docker Desktop with Docker Compose v2
+- A reachable Docker daemon
+
+The application container mounts the Docker daemon socket so Codeman can create and manage its isolated Docker cases. Treat anyone who can administer this Compose project as having Docker-host-equivalent access.
+
+## Start
+
+Copy the environment template, set a strong password, and confirm `CODEMAN_APPDATA_PATH`. The example maps `/mnt/user/appdata/Coding/codeman` on the host to `/home/${CODEMAN_RUNTIME_USER}` in the container, preserving Codeman state and CLI credentials outside Docker-managed volumes.
+
+```sh
+cp docker/.env.example docker/.env
+```
+
+On PowerShell, use the following command instead.
+
+```powershell
+Copy-Item docker/.env.example docker/.env
+```
+
+On Linux, run the stack with the start script. It determines `PUID` and `PGID` from the owner of `CODEMAN_APPDATA_PATH`, and `DOCKER_SOCKET_GID` from the configured Docker socket, before invoking Compose. A root-owned application-data directory is rejected so the runtime account cannot become UID 0.
+
+```sh
+bash docker/Start-Codeman.sh
+```
+
+On other platforms, run Compose directly. `PUID` and `PGID` default to `1000:1000`; set them in `docker/.env` when the application-data directory has a different owner.
+
+```sh
+docker compose --env-file docker/.env -f docker/docker-compose.yaml up --build -d
+```
+
+Open `http://localhost:3000` and sign in with the username and password from `docker/.env`.
+
+## Operations
+
+The local image is tagged `codeman:local` by default. Change `CODEMAN_IMAGE` in `docker/.env` if a different local tag suits your environment.
+
+```sh
+docker compose --env-file docker/.env -f docker/docker-compose.yaml logs -f codeman
+bash docker/Start-Codeman.sh
+docker compose --env-file docker/.env -f docker/docker-compose.yaml down
+```
+
+`CODEMAN_APPDATA_PATH` holds Codeman state and survives container recreation. Remove that host directory only when deliberately resetting the installation.
+
+`CODEMAN_CASES_PATH` must be an absolute path on the Docker host. Compose mounts it at the same path inside Codeman, so the host daemon can bind the managed workspace into isolated Docker cases. Do not set it to `/home/${CODEMAN_RUNTIME_USER}/codeman-cases`.
+
+Compose passes `CODEMAN_APPDATA_PATH` into Codeman as `CODEMAN_DOCKER_HOST_HOME`. Codeman uses that value to translate generated Docker seed, credential and hook-secret bind sources from the container's home path into paths visible to the host Docker daemon.
+
+If `docker info` reports `SwapLimit=false`, set `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1`. Isolated cases retain their configured memory limit. Codeman omits the unsupported swap-limit option and filters only the daemon's exact swap-capability warning while retaining every other Docker create error.
+
+If that directory was created by an earlier root-running image, change its ownership to the configured `PUID:PGID` before starting this version. This preserves existing CLI credentials and session state while allowing the unprivileged runtime account to use them.
+
+## Docker cases
+
+The default socket path is `/var/run/docker.sock`, which works with a standard Linux Docker Engine. The Bash start script detects its numeric group ID. When running Compose directly, set `DOCKER_SOCKET_GID`, for example using `stat -c '%g' /var/run/docker.sock`, so the unprivileged `CODEMAN_RUNTIME_USER` account can create Docker cases. Docker Desktop users should set `DOCKER_SOCKET` in `docker/.env` only when their Docker installation exposes a different compatible socket path.
+
+Codeman Docker cases are sibling containers on the host daemon, not children of the application container. The Compose configuration handles their workspace bind mount through `CODEMAN_CASES_PATH`; the `/home/${CODEMAN_RUNTIME_USER}` application-data mapping is for Codeman state and ordinary in-container sessions, not sibling-case workspaces.

docs/extending-codeman.md

@@ -228,6 +228,14 @@ window: the wait resolves on `idle` in a couple of seconds with `timedOut: false
 indistinguishable from a finished turn. Wait for the pid, then wait for the
 composer, answering the dialog only as the bounded fallback.
 
+⚠️ **Answering it is not "press Enter".** Claude Code 2.1.252 dropped the options'
+numbers, reversed them, and highlights `No, exit` by default, so a blind `\r` quits
+the CLI and the pane is dead seconds after the spawn. Read the `❯` marker off the
+rendered pane (`GET .../terminal?full=1`), send `ESC [ B` while it sits on `No, exit`,
+re-read, and confirm only once the marker is on `Yes, I trust this folder`. Codeman's
+own auto-accept (`trustDialogNextKey()` in `src/session-trust-dialog.ts`) does exactly
+this, inside a 90 s startup window and a 6-keystroke cap.
+
 A worked orchestration: start a worker, get it ready, prompt it, wait, clean up.
 
 ```bash
@@ -244,24 +252,36 @@ SID=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" \
 [ -n "$SID" ] && [ "$SID" != null ] || { echo "quick-start failed"; exit 1; }
 
 # 2. READINESS: composer marker first, trust dialog only as the bounded fallback.
-#    Skip this and step 3 reports a turn that never ran. Do NOT probe trust first
-#    and Enter blindly: the dialog text stays in the buffer for the life of the
-#    session, so on every later run that probe matches stale text and the Enter
-#    lands in a ready composer. Match single tokens only: TUI text can arrive
-#    without its spaces. Stage 1 is short on purpose (an already-trusted case
-#    matches in <1 s; a first-run case can never pass it and pays it in full).
+#    Skip this and step 3 reports a turn that never ran. Match single tokens only:
+#    TUI text can arrive without its spaces. Stage 1 is short on purpose (an
+#    already-trusted case matches in <1 s; a first-run case can never pass it and
+#    pays it in full).
+#    ⚠️ NEVER answer the dialog with a bare \r. Its highlighted option is `No, exit`
+#    (claude-cli 2.1.252), so a blind Enter quits the CLI; and the dialog text stays
+#    in the buffer for the life of the session, so a `from=buffer` probe for `trust`
+#    keeps matching long after it is gone. Read the CURRENT pane instead and steer.
 until [ "$("${CURL[@]}" "$API/api/v1/sessions/$SID" | jq '.data.pid')" != null ]
 do sleep 1; done
 R=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
       --data-urlencode 'match=bypass' --data-urlencode 'from=buffer' \
       --data-urlencode 'timeout=5000')           # composer's status bar = ready
 if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
-  T=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
-        --data-urlencode 'match=trust' --data-urlencode 'from=buffer' \
-        --data-urlencode 'timeout=2000')
-  jq -e '.data.wait.matched' <<<"$T" >/dev/null && \
+  ESC=$(printf '\033')   # \x1b is GNU-sed only; this form also works on macOS
+  for _ in 1 2 3 4 5 6; do
+    # Which option the ❯ marker sits on, read off the CURRENT frame.
+    K=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/terminal" --data-urlencode 'full=1' \
+        | jq -r '.data.terminalBuffer // empty' \
+        | sed -e "s/$ESC\[[0-9;?]*[a-zA-Z]//g" -e "s/$ESC[()][AB0]//g" | tr -d ' \t' \
+        | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
+        | sed -e 's/.*[Yy]es,.*/confirm/' -e 's/.*[Nn]o,.*/move/')
+    [ -n "$K" ] || break                      # no dialog on screen: nothing to answer
+    [ "$K" = confirm ] && IN="\r" || IN="$ESC[B"
     "${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" \
-      -H 'Content-Type: application/json' -d '{"input":"\r","useMux":true}' >/dev/null
+      -H 'Content-Type: application/json' \
+      -d "$(jq -nc --arg i "$IN" '{input:$i,useMux:true}')" >/dev/null
+    [ "$K" = confirm ] && break
+    sleep 1                                   # re-read: confirm the arrow landed
+  done
   "${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
     --data-urlencode 'match=bypass' --data-urlencode 'from=buffer' \
     --data-urlencode 'timeout=45000' >/dev/null

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/omp-integration.md

@@ -0,0 +1,171 @@
+# OMP (Oh My Pi) sessions
+
+Codeman can drive [OMP](https://github.com/can1357/oh-my-pi) (`omp`, Oh My Pi) as a session
+backend, alongside Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok and
+DeepSeek Harness. `omp` is the ninth CLI backend (tenth `SessionMode`, counting
+`shell`): its own PTY, its own tmux session, its own tab identity. It is not a
+location overlay like Docker or remote-SSH cases, and it is not a web tab.
+
+## Install
+
+```bash
+curl -fsSL https://omp.sh/install | sh
+```
+
+The installer places the binary in `~/.local/bin` (verified against a real
+`--no-cache` Docker build — see `docker/agent.Dockerfile`; an earlier guess of
+`~/.omp/bin` was wrong). Codeman resolves the binary via the server PATH and then
+the usual install locations (`~/.local/bin` first, then `~/.omp/bin`,
+`/usr/local/bin`, `~/.bun/bin`, `~/.npm-global/bin`, `~/bin`).
+
+**`omp` is a short name**, so like `pi` and `grok` the resolver does not trust a PATH
+hit on its own: it runs `omp --version` and requires `omp/<semver>`-shaped output
+(e.g. `omp/18.0.8`) before accepting a candidate. Check what it resolved:
+
+```bash
+curl -s localhost:3000/api/omp/status | jq
+# { "available": true, "path": "/home/you/.local/bin", "version": "18.0.8" }
+```
+
+## Authenticate
+
+OMP owns its own auth and provider configuration entirely in `~/.omp` — there is
+no Codeman-side login flow, API key field, or bypass switch to configure. Run `omp`
+directly once outside Codeman to complete whatever onboarding the CLI itself asks
+for; every session started through Codeman afterward inherits that config.
+
+## What Codeman wires up
+
+`OmpConfig` (per session, persisted in `state.json`, round-trips through respawn):
+
+| Field              | Flag            | Notes                                                     |
+| ------------------ | --------------- | ---------------------------------------------------------- |
+| `model`            | `--model <v>`   | Regex-validated (`[a-zA-Z0-9._-/]+`); `provider/model` forms like `crof/glm-5.2` pass |
+| `continueSession`  | `--continue`    | omp's own "most recent conversation in this directory" heuristic |
+| `resumeSessionId`  | `--resume <id>` | Ids only, id-regexed; wins over `--continue` when both are present |
+
+Every value is regex-validated and **dropped** (not escaped) if it fails, because the
+result is interpolated into the pane's spawn command.
+
+**omp reads its own model routing and hooks from `~/.omp`, so no trust or
+permission flags are needed** — unlike every sibling CLI in this family, there is no
+bypass-permissions equivalent to wire up, so `buildOmpCommand()` only ever passes
+`--model`/`--resume`/`--continue`. ⚠️ That does NOT mean omp is unrestricted: its
+documented default `tools.approvalMode` is `yolo`, so an omp pane auto-approves exec
+with no flag from Codeman — the CLI's own config, not Codeman, is what would need to
+change that.
+
+Env overrides: the `OMP_*` prefix is allowlisted, and per omp's own
+`docs/environment-variables.md` it is not the narrow surface it looks like. omp reads
+roughly 40 provider keys from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`XAI_API_KEY`, `HF_TOKEN`, ...) — pi's 34-key problem in the same shape — which is why
+none of those get a dedicated allowlist entry; a session authenticates from `~/.omp`
+config or the server process's own env instead, like pi. omp's own documented knobs
+are mostly `PI_*`, not `OMP_*` (`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`,
+`PI_CODING_AGENT_SESSION_DIR`, `PI_SUBPROCESS_CMD`, `PI_SHELL_PREFIX`,
+`OMP_PROFILE`/`PI_PROFILE`), and `PI_*` is already allowlisted globally because pi
+mode needs it — so an omp session today already accepts all of those. The first three
+also move the tree `omp-session-resolver.ts` and `omp-transcript.ts` hardcode
+(`resolveOmpHome()` assumes `~/.omp` unconditionally), so pinning and history quietly
+stop working under a redirected config root; this is a known gap, not fixed here.
+
+The `OMP_` prefix itself brings in `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN`,
+where omp resolves credentials from — the same shape `DEEPSEEK_BASE_URL` is dropped
+for in `clampEnvOverridesForOwner()` (session-routes.ts), so both are clamped there
+for a non-granted owner in multi-user mode. None of this matters in single-user mode.
+
+## Exact-id pinning: why `--resume`, not just `--continue`
+
+`--continue` alone is ambiguous the moment **any** other omp conversation has
+touched the same working directory more recently — it just picks the newest session
+file on disk, silently. That happens routinely: a closed-then-resumed Codeman row
+plus a still-running duplicate, two Codeman sessions pointed at the same case, or a
+plain reattach after a server restart.
+
+`src/utils/omp-session-resolver.ts` resolves and **pins** the exact conversation id
+once (`findLatestOmpSessionId()` reads `~/.omp/agent/sessions/<mangled-workingDir>/`,
+the newest `.jsonl` file's embedded uuid), then every later respawn reuses that
+pinned id via `--resume` instead of re-guessing with `--continue`.
+
+⚠️ **The directory mangling is NOT a straight `/` → `-` replace.** Unlike Claude
+Code's `~/.claude/projects/*` convention (which keeps the full path, e.g.
+`-home-user-codeman-cases-foo`), omp strips the `$HOME` prefix FIRST and only then
+dash-replaces (`/home/user/codeman-cases/foo` → `-codeman-cases-foo`; a path outside
+`$HOME`, like `/tmp/...`, is dash-replaced as-is with no stripping). Getting this
+wrong doesn't error — `findLatestOmpSessionId()` just silently returns null for
+every case under `$HOME` (virtually all real Codeman cases), so pinning quietly
+degrades to omp's own ambiguous `--continue`. This was found and fixed 2026-08-27
+after months of testing had only ever exercised `/tmp`-based working directories,
+where the bug's wrong output happened to coincidentally match the right one.
+
+## Surviving a full session kill
+
+`src/omp-transcript.ts` scans `~/.omp/agent/sessions/**/*.jsonl` directly — a second,
+independent history source alongside Codeman's own state. This means an OMP
+conversation's history (working directory, first/last prompt, size) is recoverable
+in the Past Sessions list even when **both** the Codeman session record and the
+underlying tmux pane are gone — verified live against a full OS reboot, not just a
+"Kill Tmux" button click.
+
+## Terminal behavior
+
+OMP renders inside tmux like every external CLI (narrow scrollback strip — alt-screen
+toggles only, not the full Claude/Codex/Gemini strip). It stays out of the
+alt-screen-strip list and lands on the `'buffer'` local-echo policy via the
+`_updateLocalEchoState` fallthrough, same as grok and pi.
+
+## Docker cases
+
+The agent image installs omp in its own Dockerfile step (not npm; omp's installer
+targets `$HOME/.local/bin` with no `--dir` override, the same shape as grok's
+installer). Rebuild with the mandatory `--no-cache`:
+
+```bash
+node scripts/build-agent-image.mjs --no-cache
+```
+
+⚠️ **`--resume` pinning does not currently reach an in-container omp process.**
+Docker panes are built from `defaultDockerCommandForMode`, which never sees
+`ompConfig` — `appendResumeFlag()`'s `case 'omp'` keys off the top-level
+`resumeSessionId` field, which nothing populates for omp today. Host-side history
+recovery still works (the shared `sessions/` mount below), but a respawned
+in-container omp pane falls back to its own ambiguous `--continue`, not a pinned
+id. Flagged in upstream review, not yet fixed.
+
+Credentials are **mostly seeded**, but `sessions/` is the one exception in this CLI
+family: `~/.omp/agent/{config.yml,mcp.json,models.yml,settings.yml}` are seeded
+(read-only mount, copied into the container's own `~/.omp/agent` once), so an
+in-container omp never writes refreshed config back to the host and `docker commit`
+exports stay secret-free. But `~/.omp/agent/sessions/` is **shared (RW)**, not
+seeded — the same treatment as codex's `sessions/`, and for the identical reason:
+Codeman reads it host-side (`omp-transcript.ts`, `omp-session-resolver.ts`) for
+history recovery and `--resume` pinning. Seeding it instead of sharing it would make
+an in-container OMP conversation invisible to Codeman's own history/resume logic,
+silently breaking Docker support for the kill-survival feature above. The rest of
+`~/.omp/agent` (`agent.db`/`history.db`/`models.db` SQLite caches,
+`terminal-sessions/`, `blobs/`, `cache/`) stays container-local and is neither
+shared nor seeded.
+
+## Remote SSH cases
+
+`omp` mode is routed through an interactive login shell
+(`exec "$SHELL" -i -l -c 'omp'`), because sshd's remote-command PATH does not
+include `~/.local/bin`. Per-session config and `envOverrides` do not cross ssh and are
+rejected rather than silently ignored; use the per-host command override instead.
+
+## Known gaps
+
+- **No idle/completion hook.** Idle detection falls back to output-stabilization
+  like every other external CLI. If omp ever ships a hooks system, a Codeman hook
+  POSTing to `/api/hook-event` would be the highest-value follow-up.
+- **Killing a pane mid-turn loses the conversation for real.** `tmux kill-session`
+  before an in-TUI `/exit` beats omp's own session-file flush — confirmed by direct
+  testing (kill after a clean `/exit` resumes correctly; kill without `/exit` first
+  does not). This is not something Codeman can compensate for from outside the
+  process; it would need an upstream omp fix (e.g. flush-on-SIGTERM).
+- **Unverified: `$HOME` as a symlink.** The directory-mangling fix above compares
+  against the literal `homedir()` string, not a `realpath()`-resolved one. Whether
+  omp itself canonicalizes symlinks before mangling is unconfirmed — this has not
+  been tested against a symlinked-home setup.
+- Ralph, respawn heuristics, token/CLI-info parsing and the `❯` readiness probe are
+  off for omp, as for every external CLI.

docs/pi-integration.md

@@ -139,7 +139,7 @@ set -g extended-keys-format csi-u
 
 Codeman's browser input path sends `\r` for submit, so basic use works
 unconfigured — what degrades is newline-in-editor, mostly when you attach to the
-pane directly (`sc`).
+pane directly (`codeman tui`).
 
 ⚠️ Upstream notes the setting may need a full `tmux kill-server` to take effect.
 **Never run `tmux kill-server` on Codeman's socket** — it would kill every live

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/tui-plan.md

@@ -0,0 +1,219 @@
+# Codeman TUI Rework Plan
+
+Status: **phases 0-2 implemented** on `feat/tui`; phases 3-4 remain follow-ups. The user guide is [`docs/tui.md`](tui.md); this document stays the design record.
+
+- Phase 0: `src/cli-style.ts` (palette, glyphs, `heading`/`kv`/`table`/`spinner`/`confirm`) plus the mechanical fixes of §5, and `test/cli-commands.test.ts` now derives its inventory from the real commander `program` instead of parsing a fixture.
+- Phases 1-2: `src/tui/`. `tui-app.ts` (main loop, attach handoff, verbs) and `tui-client.ts` (API, SSE, degraded enumeration) are the only IO; `tui-model`, `tui-layout`, `tui-render`, `tui-keys`, `tui-ansi`, `tui-composer`, `tui-approvals`, `tui-digest`, `tui-sse` and `tui-types` are pure and unit-tested, with an E2E suite driving the real binary under node-pty.
+- Deferred with the rest of phase 3: `r` (resume a RECENT row) is not wired up, so the help overlay does not advertise it.
+- Not started: phase 3 (mouse, `--pick` popup switcher, opt-in attach status line, OSC 9) and phase 4 (retiring the bash choosers).
+
+The goal: replace Codeman's scattered terminal surfaces with one first-class TUI, `codeman tui`, that gives SSH/terminal users the same at-a-glance awareness the web UI gives browsers. The reference point is herdr (herdr.dev), the trending Rust "agent multiplexer" whose defining feature is a live agent-state sidebar. Codeman can match and beat that sidebar in the terminal because the states herdr infers from screen-scraping heuristics are states our server already computes from hooks, pane probing, and the approvals inbox.
+
+---
+
+## 1. What we have today (inventory)
+
+Three disconnected surfaces, three visual idioms, two data sources:
+
+| Surface | What it is | Data source | Idiom |
+| --- | --- | --- | --- |
+| `codeman` CLI (`src/cli.ts`, 1214 lines) | commander + chalk, ~20 commands | HTTP API + state files | `✓`/`✗` line-per-fact, no interactivity |
+| `sc` (`scripts/tmux-chooser.sh`, 663 lines) | bash number-menu chooser, mobile-tuned (44 cols) | `tmux -L codeman` + `state.json` via jq | 256-color, numbered, full repaint per key |
+| `scripts/tmux-manager.sh` (529 lines) | bash cursor TUI with kill/info | `mux-sessions.json` (and writes it back) | 8-color, box-drawn, arrow keys |
+
+Weaknesses found in the audit (file:line refs verified 2026-08-16):
+
+1. **No interactive picker in the Node CLI at all.** Every `session stop`, `task status`, `session logs` requires a pasted UUID prefix. There is no `codeman attach <session>`; `codeman attach` is actually the attachment-card command (and `README.md:895` describes it wrongly).
+2. **`sc` cannot reach sessions 10+ interactively**: entries are numbered globally (`tmux-chooser.sh:343`) but input accepts a single `[1-9]` keypress (`:487-493`). Page 2 shows items 8-14 that mostly cannot be selected.
+3. **No cursor/selection concept in `sc`** (`BG_SEL` at `:90` is dead code); arrows only page.
+4. The two bash tools can disagree about which sessions exist (different data files), and only `sc` is on PATH.
+5. **Zero live feedback anywhere**: `codeman web -d` and `service install` block silently up to 30s (`daemon-control.ts:395-412`); no spinner exists in the codebase.
+6. Styling drift: `doctor` is the only table and is deliberately monochrome with a colorize hook nobody wired up (`dependency-report.ts:5-7`); `codeman web` prints its "running at" line twice (colored `cli.ts:934`, plain `server.ts:2366`); the server's security warning is colorless `console.warn` while the CLI's version of the same warning is yellow; `tmux-manager.sh`'s header box is visibly misaligned; `padEnd(14)` overflows on "Antigravity CLI".
+7. Bash TUIs emit raw escapes unconditionally (no TTY/NO_COLOR gate); `install.sh` and `postinstall.js` do it right.
+8. Detach hint inconsistency: chooser says Ctrl+B D, `README.md:671` says Ctrl+A D.
+9. Inside an attached session there is **no chrome at all**: Codeman turns the tmux status bar off (`tmux-manager.ts:1978`), so an SSH user in a pane has no session identity, no state, no way back to a picker except detach.
+10. `test/cli-commands.test.ts` asserts against a hand-written fixture, not the real `program`, and that fixture already lists a `tui` command that does not exist (`:57-61`). The name is pre-approved by our own test file.
+
+## 2. Research: how herdr does it
+
+herdr (github.com/herdrdev/herdr, ~30k stars, single Rust binary, pre-1.0) is a background terminal multiplexer "your coding agents live on". What matters for us:
+
+- **The agent-state sidebar is the product.** Every pane is classified live as `working` / `blocked` / `done` / `idle` and grouped in a sidebar, so you see who needs you without switching tabs. Reviews unanimously call this "the killer feature tmux can't match".
+- **Detection is heuristic-first**: process-name matching + screen-manifest TOML rules parsing the visible frame; optional per-agent "integration install" adds lifecycle hooks over JSON-RPC on a unix socket for accurate states. Claude Code there is on the heuristic path and reviewers note blocked-state lag.
+- **Model**: workspaces → tabs → panes, tmux-style prefix keys (Ctrl+B V split, arrows navigate, D detach), mouse-first (click select, drag resize, right-click menus, touch over SSH), adapts to narrow widths.
+- **Agent-shaped API**: socket API with `pane read` (visible/recent/detection), `send-text`/`send-keys`/`run`, `agent start|prompt|wait|explain`, `pane wait-output` with regex, plugins placed as overlay/split/tab/popup.
+- **Persistence**: sessions survive disconnects, reattach from any terminal / SSH.
+- Weaknesses reviewers cite: pre-1.0 churn, bus factor 1, no session resurrection, rendering lag with many panes.
+
+What is striking is how much of herdr Codeman already has, server-side: our hooks give exact `permission_prompt`/`stop`/`idle_prompt` events (herdr's "integration" path, but installed by default), `_confirmIdle()` does the screen-probe fallback, the approvals inbox parses the actual dialog options, and the agent skill + wait primitives are our socket API. What we lack is purely the presentation layer in the terminal.
+
+Prior art for the architecture we want: **agent-deck** (Bubble Tea + tmux) proves the "TUI list + attach into tmux" model works great: session list with live glyphs (● ◐ ○ ✕), Enter attaches into a tmux pane, status polling, groups, fuzzy search. We take the shape, not the code.
+
+Licensing note: herdr is reported variously as Apache-2.0/AGPL-3.0. Irrelevant either way: we copy concepts, never code.
+
+### What we take / what we skip
+
+Take: the four-state sidebar as the organizing principle; grouping by "needs you first"; narrow-width adaptation; mouse support; tmux-familiar keys; the "attention at a glance" framing.
+
+Skip: being a multiplexer. tmux already backs every Codeman session and is a hard dependency; herdr had to build pane management because it owns terminals, we do not. Also skip (for now): plugin marketplace, split layouts, pane drag. Our TUI is a **dashboard + switchboard over tmux**, not a tmux replacement.
+
+## 3. Design: `codeman tui`
+
+One command, one full-screen client of the existing HTTP/SSE API.
+
+**Positioning (owner decision, 2026-08-16): the web UI remains THE primary surface.** The TUI is strictly additive, for users who want a terminal workflow (SSH, Termius, tmux die-hards). Bare `codeman` keeps printing help; nothing existing changes behavior. The `sc` bash chooser also stays untouched for now; flipping its alias to `codeman tui` is deferred to a follow-up release once the TUI has mileage.
+
+### Layout (≥100 cols)
+
+```
+ codeman  tnode · v1.19.0 · 6 sessions · 5h ▂▂▅ 32% wk 61%                    ? help  q quit
+ ────────────────────────────────────────────────────────────────────────────────────────────
+  NEEDS YOU ──────────────────────────┐ ┌ w4-api-refactor ── claude · ~/dev/api ────────────
+  ▶ 1 w4-api-refactor  ⚠ approval  2m │ │ ✻ Actualizing… (2m 14s · ↓ 12.3k tokens)
+    2 w6-docs          ✋ waiting  11m │ │
+                                      │ │ ⚠ Claude requests: Bash(git push origin main)
+  WORKING ────────────────────────────┤ │   1. Yes  2. Yes, don't ask again  3. No
+    3 w1-codeman       ✻ 17m    45.2k │ │
+    4 w2-gallery       ✻ 3m      8.1k │ │ [y] approve   [n] deny   [Enter] attach
+  IDLE ───────────────────────────────┤ │
+    5 w3-promo         ○ 2h           │ │  …live tail of the selected session's
+  RECENT ─────────────────────────────┤ │   terminal (ANSI colors preserved),
+    · api-hotfix       ✔ done Fri     │ │   updating while you browse the list…
+ ────────────────────────────────────────────────────────────────────────────────────────────
+  ↑↓ select · ⏎ attach · 1-9 jump · y/n answer · p prompt · n new · x kill · / search · g digest
+```
+
+- **Header**: hostname/instance, server version, session count, plan-usage chip (same telemetry that feeds the web chip, when available). Degrades gracefully when the server is down (see §3.6).
+- **Sidebar**: sessions grouped `NEEDS YOU` → `WORKING` → `IDLE` → `RECENT` (past sessions from the unified list, resumable). Within groups, reuse the activity ordering already built for the home screens in PR #303 (blocked first, running longest, quiet newest); that logic is pure and shared.
+- **Preview pane**: live tail of the selected session, SGR colors preserved, cursor-movement stripped. When the selected session has a pending approval, the parsed dialog is rendered as a card above the tail with one-key answer bindings.
+- **Footer**: contextual keymap (changes when a dialog/confirm is active).
+
+### States and vocabulary
+
+Exactly the web's language so the two surfaces read the same:
+
+| Group | Glyph | Color | Source |
+| --- | --- | --- | --- |
+| NEEDS YOU (question/permission) | `⚠` | red, blinking row | approvals inbox / `permission_prompt` |
+| NEEDS YOU (waiting for input) | `✋` | yellow | `idle_prompt` / waiting classification |
+| WORKING | `✻` animating through `· ✢ ✳ ∗ ✻ ✽` at 2Hz | green | working classification (the same glyph family Claude itself draws, a deliberate nod) |
+| IDLE | `○` | muted | idle |
+| RECENT / done | `✔` | muted green | unified list history rows |
+
+Nerd-font/glyph fallback exactly like `sc` does today (`[!] [w] [*] [-] [ok]` when the terminal is not known-capable), plus full NO_COLOR / `tput colors` degradation (8-color and mono renderings are designed, not accidental).
+
+### Keymap
+
+- `↑/↓` or `j/k` select · `Enter` attach · `1-9` jump-attach (parity with `sc`, but now the cursor covers 10+)
+- `y`/`n` (or the digit keys) answer the selected session's pending approval right from the dashboard, via `POST /api/approvals/:id/answer`. The server already re-captures the pane and 409s if the dialog is gone, so this is safe by construction.
+- `p` send a one-line prompt to the selected session without attaching (`POST /input` with `\r`, the composer opens in the footer)
+- `n` new session (case picker → mode picker, drives `POST /api/quick-start`) · `x` kill with typed confirm (never bulk; refuses the session hosting the TUI itself, like tmux-manager.sh does)
+- `/` fuzzy search across sessions/history/attachments (`GET /api/search`) · `g` away digest (`GET /api/away-digest`) rendered as a panel
+- `r` resume selected RECENT row (unified list `resume-session` flow) · `?` help overlay · `q` quit
+- Mouse (phase 3): SGR mouse reporting, click selects, wheel scrolls list/preview, click on footer keys triggers them. Works over SSH, same as herdr's touch story.
+
+### Responsive behavior
+
+The `sc` design constraint survives: below ~72 cols (Termius, iPhone portrait) the preview pane drops and the TUI is a single-column list with two-line rows, nearly identical to today's `sc` but with a cursor, live states, and the answer/prompt/new/kill verbs. The layout switch is width-driven at draw time, no mode flag.
+
+### Attach model
+
+Enter suspends the TUI (restore main screen + cooked mode), then hands the terminal to `tmux -L <socket> attach-session -t <name>` with `stdio: inherit`. On tmux exit/detach, the TUI resumes and refreshes. Full fidelity (mouse, paste, colors) is tmux's, we never proxy bytes.
+
+- Inside tmux already: same socket → `switch-client -t`; different socket → warn about nesting and offer detach-first. `$TMUX` + `CODEMAN_MUX` detection.
+- **Return path**: a tmux binding installed for codeman sessions (opt-in) runs `codeman tui --pick` inside `tmux display-popup -E`, a minimal picker-only mode (list + jump, no preview) so switching sessions from inside a pane is one keystroke, fzf-style.
+- Optional per-attach chrome (opt-in setting, default off since `status off` at `tmux-manager.ts:1978` is deliberate): a minimal codeman-styled tmux status line showing `name · state · alert`, set on attach, restored on detach.
+
+### Notifications
+
+While the TUI is open and a session flips to NEEDS YOU: flash the row, ring BEL, and optionally emit OSC 9 (desktop notification in kitty/WezTerm/iTerm2, and it traverses SSH). This is the herdr sidebar promise delivered even when the terminal is backgrounded.
+
+### Degraded mode (server down)
+
+`sc` works without the server today and the TUI must too: when no server answers, enumerate `tmux -L codeman list-sessions` + read `state.json` (read-only), show a "server not running" header line, and offer attach only (no states, no approvals). This keeps the "web server crashed, get me to my sessions" path alive.
+
+## 4. Architecture
+
+### A client of the server, not a second brain
+
+Everything live comes from the API the web UI already uses:
+
+| Need | Endpoint |
+| --- | --- |
+| Session list + history | `GET /api/sessions/unified` |
+| Live updates | SSE `GET /api/events` (heartbeat `sse:heartbeat` already exists; fall back to 2s polling) |
+| Pending approvals + parsed options | `GET /api/approvals`, answer via `POST /api/approvals/:id/answer` |
+| Preview tail | `GET /api/sessions/:id/terminal?tail=N` (throttled to the selected session only) |
+| Prompt send | `POST /api/sessions/:id/input` (single line + `\r`, per the composer contract) |
+| New session | `POST /api/quick-start` (routes remote/docker cases correctly) |
+| Search | `GET /api/search` |
+| Away digest | `GET /api/away-digest` |
+| Plan usage chip | latest status-telemetry snapshot (`plan-usage-latest`) |
+
+Server discovery and auth reuse what exists: instance config from `src/config/instance.ts` (`CODEMAN_INSTANCE`, `CODEMAN_PORT`), the probe logic from `daemon-control.ts`, credentials from `~/.codeman/.env` (the established `codeman attach` pattern), self-signed HTTPS accepted for loopback probes (the hooks-on-HTTPS lesson). Multi-user scoping comes free: the API only returns what the authenticated user owns.
+
+### Renderer: hand-rolled, zero new dependencies (decision)
+
+Options considered:
+
+- **Ink (React for CLIs)**: what Claude Code uses. Pros: layout engine, ecosystem. Cons: pulls React into a CLI that today ships only commander+chalk; rerender model fights the two things we care most about (a raw-ANSI preview region and 2Hz glyph animation without flicker); version-pins React for every `npm i -g aicodeman`.
+- **blessed/neo-blessed**: unmaintained, skip.
+- **Hand-rolled screen core** (recommended): this repo hand-rolls ANSI everywhere already and has the expertise (regex-patterns, stripAnsi, the xterm work). The core is small and boring: alt screen + raw mode + cursor-home full-frame repaint from an off-screen string buffer, throttled to state changes and the 2Hz animation tick, wrapped in DECSET 2026 (synchronized output) where supported so repaints are atomic in modern terminals (tmux, kitty, WezTerm, iTerm2). No diffing needed at these frame rates.
+
+The one genuinely tricky pure function: SGR-aware line clipping for the preview (keep colors, strip cursor movement/OSC/DECSET, clip to width while carrying SGR state, reset at EOL). That is a pure module with exhaustive unit tests, and it is exactly the kind of function Ink would not have given us anyway.
+
+### Module layout
+
+```
+src/tui/
+  tui-app.ts        entry + main loop + attach handoff (IO)
+  tui-client.ts     API + SSE client, degraded-mode enumeration (IO)
+  tui-model.ts      pure: state store, grouping, ordering (reuses PR #303 helpers)
+  tui-layout.ts     pure: responsive layout math, row building
+  tui-render.ts     pure: model+layout -> frame string (palette, glyphs, fallbacks)
+  tui-keys.ts       pure: byte stream -> key/mouse events (incl. SGR mouse decode)
+  tui-ansi.ts       pure: SGR-aware clip/filter for the preview
+```
+
+Pure modules unit-test with no TTY. `cli.ts` gains one thin `tui` command registration (and `--list`/`<n>` fast paths for `sc -l` / `sc 2` parity, which must stay fast: they short-circuit before any screen setup).
+
+## 5. CLI-wide polish (the rest of "make it much nicer")
+
+A shared style kit, `src/cli-style.ts`: one palette (mirroring the web's status colors), one glyph set with fallback, `heading()`, `kv()`, `table()` (width-aware, fixes the Antigravity overflow), `spinner()` (finally: the 30s silent daemon/service waits get a live line), `confirm()` (used by `reset --force`'s missing prompt and `x` in the TUI). Then the mechanical fixes from §1: colorize `doctor` through the hook that already exists for it, dedupe the `codeman web` startup line, colorize the server's security warning, fix the README `codeman attach` description and the Ctrl+B/Ctrl+A detach drift, TTY/NO_COLOR gates everywhere.
+
+## 6. Phasing
+
+| Phase | Contents | Size |
+| --- | --- | --- |
+| 0 | `cli-style.ts` + mechanical fixes (§5), real CLI tests (retire the fixture parser in `test/cli-commands.test.ts`) | S |
+| 1 | `codeman tui` core: list + states via SSE, cursor + 1-9, attach/return loop, kill w/ confirm, new session, narrow mode, degraded mode, `sc` alias flip + `--list`/`<n>` parity | M/L |
+| 2 | Preview pane (SGR clip), approvals answering, prompt composer, search, digest, resume, plan-usage header | M |
+| 3 | Mouse support, `--pick` popup switcher + tmux binding, opt-in attach status line, BEL/OSC 9 notifications | M |
+| 4 | Retire `tmux-chooser.sh`/fold `tmux-manager.sh` (keep as thin wrappers for one release), docs/README/wiki, screenshots for promo | S |
+
+Phases 0-1 are the useful minimum; 2 is where it beats herdr's sidebar (answering approvals from the dashboard); 3 is delight.
+
+## 7. Testing
+
+- Pure modules (`tui-model/layout/render/keys/ansi`): plain vitest, frame snapshots as stripped strings plus targeted ANSI assertions.
+- Interactive E2E: spawn the built TUI under `node-pty` (already a dependency), feed keys, assert on captured frames; the vitest tmux mock (`IS_TEST_MODE`) keeps attach paths inert. Port rules per CLAUDE.md (3150+, `app.inject()` where possible by testing `tui-client` against injected routes).
+- Manual: Termius/iPhone portrait (the 44-col case), tmux nesting, server-down mode, NO_COLOR, non-nerd-font terminal.
+
+## 8. Invariants this plan respects
+
+- tmux socket and data dir always via instance config (`dataPath()`, `-L codeman`); a beta instance TUI sees only its own world.
+- Never bulk kill, always confirm, never touch another session implicitly, refuse killing the session the TUI runs in (w1/w2/w3 are sacred).
+- Input is single-line with `\r`, via the server (never raw tmux send-keys from the TUI while the server owns the session).
+- Approvals answering goes through the server's re-capture + 409 path, never blind keystrokes.
+- `status off` on panes stays the default; any chrome is opt-in.
+- No new runtime dependencies; the npm package stays light.
+
+## 9. Decisions (resolved 2026-08-16)
+
+1. **Bare `codeman` does NOT open the TUI** (owner decision): the web UI is the main thing, the TUI is additional. `codeman tui` only.
+2. **`sc` stays the bash chooser for now**; the alias flip is a follow-up once the TUI has mileage. `codeman tui --list` / `codeman tui <n>` provide the same fast paths for people who want to switch.
+3. Opt-in tmux status line: deferred to phase 3 along with the `--pick` popup switcher.
+4. Preview tail goes over the API (auth/multi-user/remote-consistent); previews are simply unavailable in degraded server-down mode.
+5. Name is `codeman tui` (the test fixture historically expected it).
+
+Initial PR scope: phases 0-2. Phase 3 (mouse, popup switcher, status line, OSC 9) and phase 4 (bash chooser retirement) are follow-ups.

docs/tui.md

@@ -0,0 +1,278 @@
+# Terminal UI (`codeman tui`)
+
+`codeman tui` is a full-screen dashboard for your Codeman sessions, in the terminal.
+It shows every session grouped by whether it needs you, lets you answer a permission
+dialog or send a prompt without switching anywhere, and puts you inside a session's
+tmux pane with one keystroke.
+
+It is **additional, not a replacement**: the web UI stays the primary surface and
+gets every feature first. The TUI exists for the terminal workflow (SSH, Termius,
+a tmux window you keep open all day), and it is a *client* of the running server,
+so the two surfaces can never disagree about what a session is doing. It is also
+not a multiplexer: tmux still owns every pane, and attaching hands the terminal to
+tmux rather than proxying bytes.
+
+## Starting it
+
+```bash
+codeman tui              # the dashboard
+codeman tui --list       # print the numbered session list and exit
+codeman tui 2            # attach straight to session 2 of that list
+```
+
+The two fast paths are the scriptable ones.
+Neither sets up a screen, so both are as quick as the one API call they make, and
+`--list` prints plain text when piped, so it composes with `grep`/`awk`.
+
+What it needs:
+
+| Needs | What you get |
+| --- | --- |
+| **Full features** | A running Codeman server (states, approvals, preview, prompts, search, digest). The TUI finds it the way `codeman attach` does: `CODEMAN_API_URL`, else loopback on `CODEMAN_PORT` for this `CODEMAN_INSTANCE`. The self-signed certificate an `--https` install generates is accepted, as it is everywhere else in the CLI. |
+| **Server down** | It still starts, in **degraded mode**: sessions are enumerated straight from `tmux -L codeman` plus a read-only peek at `state.json`, and attach is the only verb. See [Troubleshooting](#troubleshooting). |
+| **A terminal** | `codeman tui` refuses to run when stdin/stdout are not a TTY, and says to use `--list` instead. A cron job or a pipe therefore fails loudly rather than emitting escape codes into a log. |
+
+## What it looks like
+
+A real frame at 100x30 (`NO_COLOR`, trailing blank rows trimmed). The selected
+session has a pending permission dialog, so the preview pane leads with the card:
+
+```
+ codeman  ⚠ 2  tnode · v1.19.0 · 5 sessions · 5h 32% · wk 61%                        ? help  q quit
+ NEEDS YOU ─────────────────────────│ w4-api-refactor · claude · /home/you/dev/api · blocked
+  1 w6-docs                   ✋ 11m│ ⚠ requests: Bash(git push origin main)
+▶ 2 w4-api-refactor             ⚠ 2m│   1. Yes
+ WORKING ───────────────────────────│   2. Yes, and do not ask again
+  3 w1-codeman                  ∗ 1h│   3. No, tell Claude what to do
+  4 w2-gallery                 ∗ 15m│ y approve · n deny · digit chooses
+ IDLE ──────────────────────────────│
+  5 w3-promo shell              ○ 2h│ > refactor the api routes onto the shared port interface
+ RECENT ────────────────────────────│
+  6 api-hotfix                  ✔ 3d│   Read src/web/ports/session-port.ts (48 lines)
+                                    │   Read src/api/routes.ts (312 lines)
+                                    │   Edit src/api/routes.ts
+                                    │    1  -import { SessionManager } from "../session-manager.js";
+                                    │    2  +import type { SessionPort } from "../web/ports/session-
+                                    │
+                                    │   Bash(npm run typecheck)
+                                    │   └ tsc --noEmit: no errors
+                                    │
+                                    │ ✻ Actualizing… (2m 14s · ↓ 12.3k tokens)
+ ↑↓ select · ⏎ attach · y approve · n deny · 1-9 option · p prompt · x kill · / search · g digest ·
+```
+
+- **Header**: the machine, the server version, how many sessions are live, and the
+  plan-usage chip (the same statusLine telemetry that feeds the web chip, when the
+  server has a snapshot). A `⚠ n` badge counts pending approvals.
+- **Sidebar**: every session, grouped and numbered.
+- **Preview**: a live tail of the selected session, its own colors preserved, with
+  the parsed dialog card on top when that session is blocked.
+- **Footer**: only the keys that work right now. `n` reads `n new` normally and
+  `n deny` when the selected session has a dialog, because it cannot be both.
+
+The same world through `--list`:
+
+```
+  1 waiting w6-docs         /home/you/dev/docs
+  2 blocked w4-api-refactor /home/you/dev/api
+  3 working w1-codeman      /home/you/dev/codeman
+  4 working w2-gallery      /home/you/dev/gallery
+  5 idle    w3-promo        /home/you/dev/promo
+  6 done    api-hotfix      /home/you/dev/api
+```
+
+The numbers are the same on both surfaces, so `codeman tui --list` then
+`codeman tui 4` is one thought.
+
+## The four groups
+
+Groups are always in this order, and a session is in exactly one of them:
+
+| Group | Glyph | Means | Comes from |
+| --- | --- | --- | --- |
+| **NEEDS YOU** | `⚠` | A permission or question dialog is blocking the agent | The approvals inbox (`permission_prompt` hooks, with the on-screen options parsed) |
+| | `✋` | Waiting for your next instruction, or errored | `idle_prompt`, or an errored session (equally something only a human clears) |
+| **WORKING** | `✻` animating | A turn is running | The same working classification the web dashboard uses |
+| **IDLE** | `○` | Live, but sitting there | |
+| **RECENT** | `✔` | A past session from the unified list | History rows, no live pane |
+
+Ordering inside a group is "the one that has waited longest, first": blocked
+sessions sort by how long the dialog has been up, working sessions by when their
+turn started (the pane's last Enter, since a working pane repaints every second
+and would otherwise always look freshly started), and quiet ones by last activity.
+That is the ordering the web home screens already use.
+
+The cursor sticks to a **session**, not a row number, so a session that jumps to
+NEEDS YOU does not drag your selection with it. The number beside each row is what
+`1-9` and `codeman tui <n>` mean, and it is renumbered on every re-sort.
+
+When a new dialog appears, the terminal bell rings once, for that dialog only: the
+same item announced twice does not ring twice.
+
+## Keymap
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` or `j` `k` | Move the cursor. PageUp/PageDown jump five rows. |
+| `Enter` | Attach to the selected session (see [Attaching](#attaching)) |
+| `1`-`9` | Jump to that row and attach. When a dialog is on screen, a digit answers it instead (see below). |
+| `y` | Approve the selected session's dialog |
+| `n` | Deny it, or **start a new session** when there is no dialog |
+| `p` | Send one line to the selected session without attaching |
+| `x` | Kill the selected session; `y` confirms, any other key cancels |
+| `/` | Search sessions, events and files |
+| `g` | Away digest: what happened while you were gone |
+| `?` | Help overlay |
+| `Esc` | Close whatever overlay is open |
+| `q` or `Ctrl+C` | Quit, restoring the screen you started with |
+
+Inside the `p` composer and the `/` query: `←` `→` `Home` `End` `Delete`
+`Backspace` plus `Ctrl+A` / `Ctrl+E` / `Ctrl+U` / `Ctrl+W`, `Enter` to send or open,
+`Esc` (or `Ctrl+C`) to cancel. In the kill confirmation you retype the session name;
+anything else cancels. In the `n` pickers, type to filter, `Enter` chooses.
+
+Verbs that need the server (`y`/`n`/`p`/`x`/`/`/`g`) say so in degraded mode
+instead of failing silently; `Enter` and `1-9` keep working.
+
+### `p` sends exactly one line
+
+The composer is a single line by design, ending in a carriage return: that is the
+input contract every Codeman path follows, because multi-line text breaks the
+agent's own composer. Pasted newlines become spaces rather than being rejected, so
+a paste cannot silently run a different command than the one you read.
+
+## Answering approvals
+
+This is the thing the terminal could not do before. Select a blocked session and:
+
+- `y` approves.
+- `n` picks the parsed "No" option, or sends Esc when the dialog did not parse one.
+- A digit picks that numbered option, **but only a digit the dialog actually
+  offers**. A digit with no matching option falls through to the list's own
+  jump-and-attach binding, so it can never be typed at whatever has focus.
+
+The answer goes through `POST /api/approvals/:id/answer`, which **re-captures the
+pane before it types anything**. If the dialog is no longer on screen (you answered
+it in tmux a moment ago, or the agent moved on), the server refuses with a 409 and
+the TUI says `that dialog is no longer on screen` rather than pressing a key into a
+live composer. The answer is scoped to the options the server parsed off the actual
+frame, never to a guess.
+
+An idle prompt (`✋`) is not a dialog: there is nothing to approve, so `p` is the
+reply path and the footer says `p reply` instead of `p prompt`.
+
+## Attaching
+
+`Enter` suspends the dashboard (main screen back, cooked mode back) and hands the
+terminal to tmux with `stdio: inherit`. Colors, mouse and paste are tmux's, at full
+fidelity.
+
+**Press `F1` to come back.** One key, no modifier to hold or release, nothing to
+type in a particular order. tmux's own way out is a chord — press the prefix, let
+go, then a letter — and beta testing showed that is genuinely hard to convey: the
+bar first named the wrong letter (tmux binds lowercase `d` to `detach-client` and
+capital `D` to `choose-client`), and once corrected it still failed for anyone who
+kept Ctrl held, because that sends `Ctrl+D`, which tmux leaves unbound. So the TUI
+claims `F1` in tmux's prefix-less key table for the length of the attach and gives
+it back afterwards. The chord still works; it is simply not what you are told to
+press.
+
+You do not have to remember any of it. For as long as the attach lasts the pane
+wears a bar across the top:
+
+```
+ 1 w3-codeman-…  2 w4-codeman-…  3 testcase …     alt+1-9 switch · F1 back to the codeman dashboard
+```
+
+That is the **session strip**: the other sessions stay visible from inside a pane,
+numbered exactly as the dashboard numbers them, with the one you are in inverted.
+`Alt+1`..`Alt+9` switch between them without going back to the dashboard first. With
+more sessions than fit, the strip shows a window around the current one and marks
+each cut end with `…`; the way-out hint is measured first and always keeps its space.
+
+Codeman keeps the status bar off on its panes (the web UI carries that information
+around the terminal instead), so the TUI turns it on for the attach and puts it back
+exactly as it was on detach, along with each window's size. Every session the strip
+can switch to is dressed and sized the same way, so switching is instant and lands
+in a pane that already fills your terminal.
+
+Detaching leaves the agent running; typing `exit` or pressing `Ctrl+D` would end it,
+which is the difference the bar exists to make obvious. If an agent does exit, its
+pane stays as a corpse: the TUI refuses to attach to a dead pane and offers `r` to
+resume the conversation in a fresh one instead.
+
+Three cases:
+
+| Where you are | What happens |
+| --- | --- |
+| Not in tmux | `tmux -L codeman attach-session` |
+| Already in tmux on Codeman's socket | `switch-client`, so you do not nest |
+| In tmux on a **different** socket | Refused, with an explanation: detach from that tmux first, then run `codeman tui` again |
+
+A direct-PTY session has no pane to attach to, and says so.
+
+**`Enter` on a RECENT row resumes that conversation** instead: there is no pane to
+attach to, so the TUI creates a new claude session carrying the old transcript
+(`resumeSessionId`, exactly what the web UI's "Resume Conversation" list does), in
+the directory it originally ran in and under its old name, then attaches to it. It
+is claude-only, and a row with no working directory or no conversation id says why
+rather than resuming something else.
+
+`x` never bulk-kills: it kills one session, only after you retype its name, never a
+history row, and never the session the TUI itself is running in.
+
+## Over SSH, and on a phone
+
+The TUI is an ordinary terminal program with no local dependencies beyond tmux, so
+`ssh box` then `codeman tui` works exactly like running it locally. There is no
+separate remote mode.
+
+Below 72 columns (Termius, an iPhone in portrait) the preview pane is dropped and
+rows take two lines each, keeping the cursor, the live states and the
+answer/prompt/kill verbs. The switch is
+width-driven at draw time, so unfolding a foldable or resizing a window re-lays out
+immediately; there is no mode flag to set.
+
+## Troubleshooting
+
+**"The Codeman server rejected these credentials."** The server has
+`CODEMAN_PASSWORD` set. Export `CODEMAN_PASSWORD` (and `CODEMAN_USERNAME` if it is
+not `admin`), or put them in the data dir's `.env` (`~/.codeman/.env`), which is
+where `codeman attach` already reads them from.
+
+**`server not running: attach only`** in a yellow banner. Nothing answered on the
+expected port, so the TUI fell back to enumerating tmux. You get names and attach;
+you do not get states, approvals or previews, because those only exist on the
+server. Start the server (`codeman web -d`, or `systemctl --user start codeman-web`)
+and the banner clears on its own: the TUI keeps re-probing.
+
+**It found the wrong server, or none.** Discovery is instance-scoped. A beta
+instance (`CODEMAN_INSTANCE=beta`) has its own data dir *and* its own tmux socket,
+so its TUI sees only its own sessions. Set `CODEMAN_PORT` or `CODEMAN_API_URL`
+explicitly when you run more than one.
+
+**"this terminal is already inside tmux on socket ..."** You are in a tmux session
+on a socket that is not Codeman's, so attaching would nest two multiplexers whose
+prefix keys collide. Detach from that tmux and run `codeman tui` from outside.
+
+**Boxes and glyphs render as garbage.** The TUI picks a glyph tier from the
+environment: no `TERM` (or `dumb`), or a non-UTF-8 locale, gets the ASCII set
+(`[!] [w] [*] [-]`, `+`/`-`/`|` frames). Force it either way with
+`CODEMAN_TUI_GLYPHS=ascii|unicode|nerd`.
+
+**Colors.** Standard `NO_COLOR` / `FORCE_COLOR` handling (chalk's, the same as the
+rest of the CLI). Under `NO_COLOR` the frame is cursor addressing and text only,
+and the preview's own colors are stripped too, so a session's output cannot repaint
+the dashboard.
+
+**It refuses to open at all**, saying it needs an interactive terminal. stdout or
+stdin is not a TTY. That is the guard: use `codeman tui --list`.
+
+## Related
+
+- [`docs/tui-plan.md`](tui-plan.md): the design record. Why hand-rolled ANSI, why a
+  client and not a second brain, and what is deliberately deferred.
+- [`docs/approvals-inbox-plan.md`](approvals-inbox-plan.md): where the parsed
+  dialogs and the answer endpoint come from.
+- [`docs/remote-sessions.md`](remote-sessions.md): remote-SSH cases, which the TUI
+  lists like any other session.

docs/wiki/Core-Concepts.md

@@ -88,7 +88,7 @@ would. That indirection buys:
 - **Real scrollback.** History is held by tmux, so reconnecting replays what happened while
   you were gone instead of starting from blank.
 - **Attach from anywhere else.** The same session is reachable from a terminal over SSH
-  with the `sc` chooser, or plain `tmux -L codeman attach`.
+  with `codeman tui`, or plain `tmux -L codeman attach`.
 - **Secrets off the command line.** Environment overrides are injected with socket-scoped
   `tmux setenv` rather than being visible in the spawn command.
 

docs/wiki/FAQ.md

@@ -73,8 +73,10 @@ features are Claude-only; [Agent CLIs](Agent-CLIs) lists exactly which.
 
 ### Can I attach to a session from a terminal instead of the browser?
 
-Yes. `sc` is an interactive chooser (`sc 2` attaches directly, `sc -l` lists), or use tmux
-directly on the `codeman` socket. Detach with `Ctrl+A D`.
+Yes. `codeman tui` is a full-screen dashboard of your sessions, with the same
+NEEDS YOU / WORKING / IDLE grouping the web UI uses. `codeman tui --list` prints the
+numbered list and exits, and `codeman tui 2` attaches straight to session 2. `Enter`
+attaches, `F1` comes back. You can also use tmux directly on the `codeman` socket.
 
 ## Running unattended
 

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/Mobile-Guide.md

@@ -88,6 +88,22 @@ looks exactly like a dead button.
 On phones this button replaces the desktop's **Run Shell** control; starting a shell moved
 into the Run dropdown.
 
+## Tapping, links and copying
+
+- **Tap a link** in terminal output and it opens in a new tab. Same for a link in an agent's
+  answer in the response viewer — it opens a tab rather than navigating the dashboard away,
+  which on a phone would unload the whole session view.
+- **Tap a file path** an agent printed and the file-preview overlay opens; a log path opens the
+  log viewer. Works in scrolled-up transcript too.
+- A tap on the prose *beside* a link still places the cursor as usual, and a tap on a dialog's
+  numbered choice still answers the dialog even when the row contains a path — the dialog wins,
+  because on a phone it is the only interaction that matters.
+- **Long-press to select text**, then drag, or tap the other end to extend the selection — no
+  hairline handles to grab. A small bar offers **Copy**, **Line** (the whole logical line,
+  wrapped rows included) and dismiss. Copy works on plain-HTTP installs too, where the browser
+  clipboard API is unavailable.
+- A swipe is never mistaken for a long-press, and the keyboard stays down while you select.
+
 ## Scrolling and the keyboard
 
 - The terminal and toolbar shift up when the keyboard opens, tracked through the browser's
@@ -97,6 +113,10 @@ into the Run dropdown.
   keeps focus so you can place the caret.
 - A scroll is never mistaken for a tap: travel is measured from the start of the gesture, and
   multi-touch never counts.
+- **A long prompt stays visible.** Once what you are typing wraps past the last visible row it
+  grows upward over the transcript instead of sliding under the keyboard, so the end of the
+  sentence — where the cursor is — is always on screen. A prompt taller than the visible strip
+  shows its tail.
 
 ## Voice
 

docs/wiki/Remote-Access.md

@@ -179,16 +179,19 @@ the same IP, which matters because all tunnel traffic arrives from one loopback
 
 ## Terminal alternatives
 
-You do not have to use a browser. `sc` is a thumb-friendly session chooser for SSH clients
-like Termius or Blink:
+You do not have to use a browser. `codeman tui` is a full-screen session dashboard that
+works well in SSH clients like Termius or Blink:
 
 ```bash
-sc          # interactive chooser
-sc 2        # attach to session 2
-sc -l       # list
+codeman tui           # the dashboard
+codeman tui 2         # attach straight to session 2
+codeman tui --list    # numbered list, then exit
 ```
 
-Detach with `Ctrl+A D`. The sessions are the same ones the dashboard shows.
+`Enter` attaches into the pane and `F1` comes back. Under 72 columns it drops the preview
+and becomes a single-column list, so it stays usable on a phone. The sessions are the same
+ones the dashboard shows. See [docs/tui.md](https://github.com/Ark0N/Codeman/blob/master/docs/tui.md)
+for the full guide.
 
 ## Common problems
 

docs/wiki/Settings-Reference.md

@@ -45,6 +45,7 @@ supervised by systemd or launchd; npm installs report as non-updatable. See
 | CJK Input                     | Off                  | IME composition through a dedicated text field.                        |
 | Extended Keyboard Bar         | Per device           | Which accessory bar phones get. Shell sessions override it while they are active. |
 | Wheel Scrolls Local History   | Off                  | Keeps the wheel on the local buffer instead of forwarding it to the CLI. |
+| Auto Copy Selection           | Off                  | Copies highlighted terminal text to the clipboard the moment you finish selecting it. Ctrl+C still copies on demand. |
 | WebGL Renderer                | On                   | With a GPU-stall watchdog that falls back to DOM rendering.            |
 | Gesture Control               | Off                  | Camera hand tracking. Also needs `CODEMAN_GESTURE=1` on the server.    |
 

docs/wiki/The-Dashboard.md

@@ -133,8 +133,10 @@ TUIs render correctly.
 
 Worth knowing:
 
-- **Scrollback.** The first time you open a session, Codeman pulls the entire tmux
-  scrollback, not just the recent tail. Scrolling to the very top pulls again on demand.
+- **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
+  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"
@@ -133,6 +149,17 @@ ANTIGRAVITY_SEARCH_PATHS=(
     "$HOME/bin/agy"
 )
 
+# OMP CLI search paths (from src/utils/omp-cli-resolver.ts's OMP_SEARCH_DIRS —
+# ~/.local/bin leads, omp.sh's installer target; ~/.omp/bin is a fallback only)
+OMP_SEARCH_PATHS=(
+    "$HOME/.local/bin/omp"
+    "$HOME/.omp/bin/omp"
+    "/usr/local/bin/omp"
+    "$HOME/.bun/bin/omp"
+    "$HOME/.npm-global/bin/omp"
+    "$HOME/bin/omp"
+)
+
 # ============================================================================
 # Color Output
 # ============================================================================
@@ -229,7 +256,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 +427,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 +621,119 @@ 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
+}
+
+# `omp` is a short name too, so like grok/pi the server-side resolver
+# additionally probes `omp --version`. Detection here only feeds the
+# "you have no AI CLI" hint, so a plain executable test is enough.
+check_omp() {
+    if command -v omp &>/dev/null; then
+        return 0
+    fi
+
+    for path in "${OMP_SEARCH_PATHS[@]}"; do
+        if [[ -x "$path" ]]; then
+            return 0
+        fi
+    done
+
+    return 1
+}
+
+get_omp_path() {
+    if command -v omp &>/dev/null; then
+        command -v omp
+        return
+    fi
+
+    for path in "${OMP_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 +1001,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
@@ -1072,21 +1281,28 @@ add_to_path() {
     success "Added to $profile"
 }
 
-setup_sc_alias() {
+# The `sc` bash chooser was retired in favour of `codeman tui`, which reaches
+# sessions 10+, carries the server's real states and leaves an attach with one
+# key. Older installers wrote this alias, so take it back out.
+#
+# Marker-owned on purpose: it matches the exact line WE wrote, so a user's own
+# `alias sc=` for something entirely different is never touched. The rewrite
+# goes through `cat >` rather than `mv` so the profile keeps its own mode and
+# ownership.
+remove_sc_alias() {
     local profile
     profile=$(detect_shell_profile)
+    [[ -f "$profile" ]] || return 0
+    grep -qE "^alias sc='tmux-chooser'\$" "$profile" 2>/dev/null || return 0
 
-    # Check if alias already exists
-    if [[ -f "$profile" ]] && grep -qE "^alias sc=" "$profile" 2>/dev/null; then
-        info "Alias 'sc' already configured in $profile"
-        return 0
+    local tmp
+    tmp=$(mktemp 2>/dev/null) || return 0
+    if sed -e "/^alias sc='tmux-chooser'\$/d" \
+           -e '/^# Codeman tmux session shortcut$/d' "$profile" > "$tmp" 2>/dev/null; then
+        cat "$tmp" > "$profile"
+        info "Removed the retired 'sc' alias from $profile (use: codeman tui)"
     fi
-
-    echo "" >> "$profile"
-    echo "# Codeman tmux session shortcut" >> "$profile"
-    echo "alias sc='tmux-chooser'" >> "$profile"
-
-    info "Added 'sc' alias for tmux-chooser"
+    rm -f "$tmp"
 }
 
 # ============================================================================
@@ -1704,6 +1920,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() {
@@ -1956,6 +2207,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"
@@ -2069,6 +2343,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
@@ -2076,6 +2375,9 @@ main() {
     local has_gemini=false
     local has_antigravity=false
     local has_pi=false
+    local has_grok=false
+    local has_dsh=false
+    local has_omp=false
 
     info "Checking AI CLI tools..."
     if check_claude; then
@@ -2102,17 +2404,29 @@ 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 check_omp; then
+        has_omp=true
+        success "OMP CLI found at $(get_omp_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" && "$has_omp" == "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, DeepSeek Harness, or OMP."
         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, Gemini, Pi, Grok, DeepSeek Harness or OMP)"
         echo ""
 
         local cli_choice=""
@@ -2160,6 +2474,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
@@ -2225,7 +2540,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
@@ -2243,13 +2558,14 @@ main() {
         ln -sf "$INSTALL_DIR/dist/index.js" "$symlink_dir/codeman"
         info "Created symlink: $symlink_dir/codeman"
 
-        # Install tmux-chooser as 'tmux-chooser' command
-        if [[ -f "$INSTALL_DIR/scripts/tmux-chooser.sh" ]]; then
-            ln -sf "$INSTALL_DIR/scripts/tmux-chooser.sh" "$symlink_dir/tmux-chooser"
-            info "Created symlink: $symlink_dir/tmux-chooser"
-            # Add 'sc' alias for quick access
-            setup_sc_alias
+        # tmux-chooser/`sc` is retired; `codeman tui` replaces it. Sweep up what
+        # an older installer left behind, so an update does not leave a symlink
+        # pointing at a script this version no longer ships.
+        if [[ -L "$symlink_dir/tmux-chooser" ]]; then
+            rm -f "$symlink_dir/tmux-chooser"
+            info "Removed the retired tmux-chooser symlink (use: codeman tui)"
         fi
+        remove_sc_alias
 
         # Add ~/.local/bin to PATH if not already there
         if [[ ":$PATH:" != *":$symlink_dir:"* ]]; then
@@ -2450,23 +2766,28 @@ main() {
 
     echo -e "  ${BOLD}Mobile Access (Termius/SSH):${NC}"
     echo ""
-    echo -e "    ${CYAN}sc${NC}              # Interactive tmux session chooser"
-    echo -e "    ${CYAN}sc 2${NC}            # Quick attach to session 2"
-    echo -e "    ${CYAN}sc -h${NC}           # Help"
+    echo -e "    ${CYAN}codeman tui${NC}     # Full-screen session dashboard"
+    echo -e "    ${CYAN}codeman tui 2${NC}   # Attach straight to session 2"
+    echo -e "    ${CYAN}codeman tui -l${NC}  # Numbered list, then exit"
     echo ""
 
     echo -e "  ${BOLD}Documentation:${NC}"
     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 && ! check_omp; 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 -e "    ${CYAN}curl -fsSL https://omp.sh/install | sh${NC}                        # OMP"
         echo ""
+        echo -e "  DeepSeek Harness has no vendor one-liner — install it from within Codeman"
+        echo -e "  once the server is up (Run dropdown → Install DeepSeek Profile, or see"
+        echo -e "  docs/deepseek-integration.md)."
     fi
 
     # Security notice — last informational block so it stays visible (when not
@@ -2519,7 +2840,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)")"
@@ -2556,6 +2877,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
 }
 
@@ -2620,6 +2945,7 @@ uninstall() {
         rm -f "$symlink_dir/tmux-chooser"
         success "Removed symlink: $symlink_dir/tmux-chooser"
     fi
+    remove_sc_alias
 
     # Remove install directory
     if [[ -d "$INSTALL_DIR" ]]; then

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.19.6",
+  "version": "1.24.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.19.6",
+      "version": "1.24.4",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -12361,7 +12361,7 @@
       }
     },
     "packages/xterm-zerolag-input": {
-      "version": "0.3.0",
+      "version": "0.3.1",
       "license": "MIT",
       "devDependencies": {
         "@xterm/headless": "^6.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.19.6",
+  "version": "1.24.4",
   "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",

packages/xterm-zerolag-input/CHANGELOG.md

@@ -1,5 +1,20 @@
 # xterm-zerolag-input
 
+## 0.3.1
+
+### Patch Changes
+
+- Mobile catches up: links open from a tap, terminal text can be selected and copied, long prompts stay visible while you type. Plus Files panel search, a bundled Nerd Font symbols fallback, and a per-device terminal font setting.
+  - **Terminal and chat links work on phones** (#321): tapping a URL or file path in terminal output now opens it (new tab, file preview, or log viewer), resolved through the same provider desktop hover uses, so tap and click can never disagree about what is a link. Dialog rows and the composer keep their existing meaning. Response-viewer links open in a new tab with `rel="noopener noreferrer"` instead of navigating the dashboard away. Wrapped links open whole: the logical-line reconstruction now stitches hard wraps through the indent their continuation carries, which also fixes desktop hover-click truncating wrapped URLs.
+  - **Terminal text can be copied on touch devices** (#321): long-press selects the token under the finger, drag or tap the other end to extend, and a small bar offers Copy, Line (the whole logical line, wraps included) and dismiss. Copy works on plain-HTTP installs too. Three guards keep the keyboard down and the selection alive through the browser's own long-press handling.
+  - **A long prompt stays visible on phones** (#321): the local-echo overlay grows upward once it would run past the last visible row (a prompt taller than the screen keeps its tail, where the cursor is), and the keyboard-driven padding shrink can no longer reclaim the space the fixed toolbar and accessory bar stand in.
+  - **Files panel search** (#324): `GET /api/sessions/:id/files?q=...` answers a flat match list (name or path substring, `*`/`?` globs), recursing past non-matching directories with its own match cap on top of the existing bounds; without `q` the response is byte-identical to before. Glob queries are matched without regex so a pathological pattern cannot stall the server.
+  - **Nerd Font prompt glyphs out of the box, custom terminal font** (#320): a bundled icons-only Symbols Nerd Font Mono fallback renders powerlevel10k/starship/oh-my-posh glyphs on every device with no font install, and App Settings gains a per-device terminal font family that is prepended to the built-in stack.
+
+  ### Thanks
+
+  Three contributor PRs in one release: thanks to @rounakdatta (#321), @aakhter (#324) and @comzine (#320).
+
 ## 0.3.0
 
 ### Minor Changes

packages/xterm-zerolag-input/package.json

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

packages/xterm-zerolag-input/src/overlay-renderer.ts

@@ -65,38 +65,71 @@ export function renderOverlay(container: HTMLDivElement, params: RenderParams):
     charTop,
     charHeight,
     promptRow,
+    totalRows,
     font,
     showCursor,
     cursorColor,
     terminal,
   } = params;
 
-  // Position container at prompt row.
+  // ── Keep what is being typed ON SCREEN ────────────────────────────
+  //
+  // The overlay lays its wrapped lines out DOWNWARD from the prompt row, and
+  // nothing past the last terminal row is visible. On a phone the strip left
+  // above the on-screen keyboard is only a handful of rows, so a prompt long
+  // enough to wrap ran off the bottom and the user was typing blind — the tail
+  // of their own sentence, the part they are actually looking at, hidden behind
+  // the keyboard.
+  //
+  // So the composer grows UPWARD once it reaches the last row, exactly as a real
+  // terminal's does: every line div is opaque (see makeLine), so the lines cover
+  // transcript rows above instead of vanishing under the keyboard below, and the
+  // newest text stays where the eye is. A prompt taller than the whole viewport
+  // keeps its TAIL for the same reason.
+  //
+  // `startCol` indents only the line that begins at the prompt marker, so it is
+  // dropped along with that line when the tail is all that fits.
+  const rows = totalRows && totalRows > 0 ? totalRows : terminal?.rows;
+  let visibleLines = lines;
+  let keepsPromptLine = true;
+  let topRow = promptRow;
+  if (rows && rows > 0) {
+    if (lines.length > rows) {
+      visibleLines = lines.slice(lines.length - rows);
+      keepsPromptLine = false;
+      topRow = 0;
+    } else if (promptRow + lines.length > rows) {
+      topRow = rows - lines.length;
+    }
+  }
+  topRow = Math.max(0, topRow);
+
   container.style.left = '0px';
-  container.style.top = promptRow * cellH + 'px';
+  container.style.top = topRow * cellH + 'px';
 
   // Clear and rebuild (typically 1-3 line divs, negligible cost)
   container.innerHTML = '';
   const fullWidthPx = totalCols * cellW;
 
-  for (let i = 0; i < lines.length; i++) {
-    const leftPx = i === 0 ? startCol * cellW : 0;
-    const widthPx = i === 0 ? fullWidthPx - leftPx : fullWidthPx;
+  for (let i = 0; i < visibleLines.length; i++) {
+    const indents = i === 0 && keepsPromptLine;
+    const leftPx = indents ? startCol * cellW : 0;
+    const widthPx = indents ? fullWidthPx - leftPx : fullWidthPx;
     const topPx = i * cellH;
-    const lineEl = makeLine(lines[i], leftPx, topPx, widthPx, cellH, cellW, charTop, charHeight, font, terminal);
+    const lineEl = makeLine(visibleLines[i], leftPx, topPx, widthPx, cellH, cellW, charTop, charHeight, font, terminal);
     container.appendChild(lineEl);
   }
 
   // Block cursor at end of last line (use visual width for CJK support)
   if (showCursor) {
-    const lastLine = lines[lines.length - 1];
-    const lastLineLeft = lines.length === 1 ? startCol : 0;
+    const lastLine = visibleLines[visibleLines.length - 1];
+    const lastLineLeft = visibleLines.length === 1 && keepsPromptLine ? startCol : 0;
     const cursorCol = lastLineLeft + stringCellWidth(terminal, lastLine);
     if (cursorCol < totalCols) {
       const cursor = document.createElement('span');
       cursor.style.cssText = 'position:absolute;display:inline-block';
       cursor.style.left = cursorCol * cellW + 'px';
-      cursor.style.top = (lines.length - 1) * cellH + 'px';
+      cursor.style.top = (visibleLines.length - 1) * cellH + 'px';
       cursor.style.width = cellW + 'px';
       cursor.style.height = cellH + 'px';
       cursor.style.backgroundColor = cursorColor;

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

@@ -172,6 +172,13 @@ export interface RenderParams {
   /** Height of the character rendering area (px). */
   charHeight: number;
   promptRow: number;
+  /**
+   * Visible terminal rows. When given, the overlay is kept ON SCREEN: it grows
+   * upward instead of running off the bottom edge, and a wrapped prompt taller
+   * than the viewport keeps its tail. Omit to lay out straight down from
+   * `promptRow` (the historical behaviour).
+   */
+  totalRows?: number;
   font: FontStyle;
   showCursor: boolean;
   cursorColor: string;

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

@@ -565,7 +565,10 @@ export class ZerolagInputAddon implements XtermAddon {
 
       // Skip redundant re-renders — include text content to detect
       // same-length changes (e.g., setFlushed with different text)
-      const renderKey = `${displayText}:${startCol}:${activePrompt.row}:${activePrompt.col}:${totalCols}:${this._flushedOffset}`;
+      // `rows` is part of the key: the layout is clamped to the visible rows
+      // (see renderOverlay), so a keyboard opening — which changes rows without
+      // changing the text — must not be skipped as a redundant render.
+      const renderKey = `${displayText}:${startCol}:${activePrompt.row}:${activePrompt.col}:${totalCols}:${this._terminal.rows}:${this._flushedOffset}`;
       if (renderKey === this._lastRenderKey && this._overlay.style.display !== 'none') return;
       this._lastRenderKey = renderKey;
 
@@ -612,6 +615,7 @@ export class ZerolagInputAddon implements XtermAddon {
         charTop,
         charHeight,
         promptRow: activePrompt.row,
+        totalRows: this._terminal.rows,
         font: this._font,
         showCursor: this._options.showCursor,
         cursorColor,

packages/xterm-zerolag-input/test/overlay-renderer.test.ts

@@ -418,3 +418,88 @@ describe('stringCellWidth', () => {
     expect(stringCellWidth(null, '')).toBe(0);
   });
 });
+
+describe('renderOverlay — staying on screen (totalRows)', () => {
+  // A phone with the keyboard up leaves only a handful of terminal rows. The
+  // overlay lays its wrapped lines out downward from the prompt row, so a long
+  // prompt used to run off the bottom edge and the user typed blind, with the
+  // tail of their own sentence behind the keyboard. With totalRows known, the
+  // composer grows UPWARD instead — the line divs are opaque, so they cover
+  // transcript above rather than disappearing below.
+  const linesOf = (n: number) => Array.from({ length: n }, (_, i) => `line${i}`);
+  const lineDivs = (container: HTMLDivElement) =>
+    Array.from(container.children).filter((el) => el.tagName === 'DIV') as HTMLDivElement[];
+
+  it('lifts the block so its last line lands on the last visible row', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: linesOf(5), promptRow: 10, totalRows: 12, cellH: 17 }));
+
+    // 10 + 5 would end on row 14 of a 12-row screen; the block starts at 7 instead.
+    expect(container.style.top).toBe(7 * 17 + 'px');
+    expect(lineDivs(container)).toHaveLength(5);
+  });
+
+  it('leaves the prompt row alone when the block already fits', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: linesOf(3), promptRow: 5, totalRows: 24, cellH: 17 }));
+
+    expect(container.style.top).toBe(5 * 17 + 'px');
+  });
+
+  it('keeps the TAIL when the prompt is taller than the whole viewport', () => {
+    // The end is where the cursor is, and where the user is looking.
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: linesOf(6), promptRow: 2, totalRows: 3, cellH: 20 }));
+
+    const divs = lineDivs(container);
+    expect(container.style.top).toBe('0px');
+    expect(divs).toHaveLength(3);
+    expect(divs.map((d) => d.textContent)).toEqual(['line3', 'line4', 'line5']);
+  });
+
+  it('drops the prompt indent once the prompt line is no longer shown', () => {
+    // startCol indents only the line that begins at the prompt marker.
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({ lines: linesOf(6), promptRow: 2, totalRows: 3, startCol: 5, cellW: 10, totalCols: 80 })
+    );
+
+    const first = lineDivs(container)[0];
+    expect(first.style.left).toBe('0px');
+    expect(first.style.width).toBe(80 * 10 + 'px');
+  });
+
+  it('rides the cursor on the last VISIBLE line', () => {
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({ lines: ['aaa', 'bbb', 'ccc', 'ddd'], promptRow: 9, totalRows: 3, cellH: 20, cellW: 10, startCol: 4 })
+    );
+
+    const cursor = Array.from(container.children).find((el) => el.tagName === 'SPAN') as HTMLSpanElement;
+    // Tail is the last 3 lines, so the cursor sits on row 2 (0-based) of the block…
+    expect(cursor.style.top).toBe(2 * 20 + 'px');
+    // …at column 3, NOT startCol + 3: the indented prompt line is not shown.
+    expect(cursor.style.left).toBe(3 * 10 + 'px');
+  });
+
+  it('lays out straight down when totalRows is absent (unchanged behaviour)', () => {
+    const container = document.createElement('div');
+    renderOverlay(container, makeParams({ lines: linesOf(9), promptRow: 20, cellH: 17 }));
+
+    expect(container.style.top).toBe(20 * 17 + 'px');
+    expect(lineDivs(container)).toHaveLength(9);
+  });
+
+  it('falls back to the terminal row count when totalRows is not passed', () => {
+    // The addon passes totalRows, but a stale bundle / third-party caller may not.
+    const container = document.createElement('div');
+    renderOverlay(
+      container,
+      makeParams({ lines: linesOf(4), promptRow: 8, cellH: 17, terminal: { rows: 10, cols: 80 } as never })
+    );
+
+    expect(container.style.top).toBe(6 * 17 + 'px');
+  });
+});

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',

scripts/tmux-chooser.sh

@@ -1,662 +0,0 @@
-#!/bin/bash
-# ============================================================================
-# Codeman Sessions - Mobile-friendly Tmux Session Chooser
-# Optimized for iPhone/Termius (portrait ~45 chars, landscape ~95 chars)
-# ============================================================================
-#
-# Design principles:
-#   - Single-digit selection (1-9) for fast thumb typing
-#   - Compact display, no wasted space
-#   - Color-coded status for quick scanning
-#   - Names pulled from Codeman state.json
-#   - Minimal keystrokes to attach
-#
-# Usage:
-#   tmux-chooser          # Interactive chooser
-#   tmux-chooser 1        # Quick attach to session 1
-#   tmux-chooser -l       # List only (non-interactive)
-#   tmux-chooser -h       # Help
-#
-# Alias: alias sc='tmux-chooser'
-#   Then: sc      (interactive)
-#         sc 2    (attach session 2)
-#
-# ============================================================================
-
-set -e
-
-# ============================================================================
-# Configuration
-# ============================================================================
-
-CODEMAN_STATE="$HOME/.codeman/state.json"
-CODEMAN_SESSIONS="$HOME/.codeman/mux-sessions.json"
-
-# Dedicated tmux socket all Codeman sessions live on. MUST match
-# DEFAULT_CODEMAN_TMUX_SOCKET / CODEMAN_TMUX_SOCKET in src/tmux-manager.ts —
-# otherwise list-sessions would enumerate the user's default tmux server
-# (missing the real Codeman sessions, surfacing unrelated ones).
-CODEMAN_TMUX_SOCKET="${CODEMAN_TMUX_SOCKET:-codeman}"
-TMUX_CMD=(tmux -L "$CODEMAN_TMUX_SOCKET")
-
-
-# iPhone 17 Pro portrait width (conservative)
-MAX_WIDTH=44
-MAX_NAME_LEN=28
-
-# Page size for pagination (leave room for header/footer)
-PAGE_SIZE=7
-
-# Auto-refresh timeout (seconds) - 0 to disable
-AUTO_REFRESH=60
-
-# ============================================================================
-# Icon Detection (Nerd Fonts vs ASCII)
-# ============================================================================
-
-detect_icons() {
-    if [[ "$TERM_PROGRAM" == "iTerm"* ]] || \
-       [[ "$TERM" == "xterm-kitty" ]] || \
-       [[ -n "$WEZTERM_PANE" ]] || \
-       [[ "$LC_TERMINAL" == "iTerm2" ]]; then
-        ICON_SESSION="󰆍"
-        ICON_ATTACHED="●"
-        ICON_DETACHED="○"
-        ICON_UNKNOWN="◌"
-    else
-        ICON_SESSION="[T]"
-        ICON_ATTACHED="*"
-        ICON_DETACHED="-"
-        ICON_UNKNOWN="?"
-    fi
-}
-
-detect_icons
-
-# ============================================================================
-# Colors - ANSI 256 for better Termius compatibility
-# ============================================================================
-
-R='\033[0m'        # Reset
-B='\033[1m'        # Bold
-D='\033[2m'        # Dim
-GREEN='\033[38;5;82m'
-YELLOW='\033[38;5;220m'
-BLUE='\033[38;5;75m'
-CYAN='\033[38;5;87m'
-RED='\033[38;5;203m'
-GRAY='\033[38;5;245m'
-WHITE='\033[38;5;255m'
-BG_SEL='\033[48;5;236m'
-
-# ============================================================================
-# Utilities
-# ============================================================================
-
-truncate() {
-    local str="$1"
-    local max="$2"
-    local len=${#str}
-
-    if [ "$len" -le "$max" ]; then
-        echo "$str"
-        return
-    fi
-
-    if [[ "$str" == *"/"* ]]; then
-        echo "..${str: -$((max-2))}"
-    else
-        echo "${str:0:$((max-1))}…"
-    fi
-}
-
-find_full_session_id() {
-    local short_id="$1"
-
-    if [ -f "$CODEMAN_STATE" ]; then
-        local full_id
-        full_id=$(jq -r --arg short "$short_id" '
-            .sessions | keys[] | select(startswith($short))
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-        if [ -n "$full_id" ]; then
-            echo "$full_id"
-            return
-        fi
-    fi
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local full_id
-        full_id=$(jq -r --arg short "$short_id" '
-            .[] | select(.sessionId | startswith($short)) | .sessionId
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-        if [ -n "$full_id" ]; then
-            echo "$full_id"
-            return
-        fi
-    fi
-
-    echo "$short_id"
-}
-
-get_session_name() {
-    local session_id="$1"
-    local name=""
-    local workdir=""
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local result
-        result=$(jq -r --arg id "$session_id" '
-            .[] | select(.sessionId | startswith($id)) | "\(.name // "")\t\(.workingDir // "")"
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-        if [ -n "$result" ]; then
-            name="${result%%	*}"
-            workdir="${result#*	}"
-        fi
-    fi
-
-    if [ -z "$name" ] && [ -f "$CODEMAN_STATE" ]; then
-        local result
-        result=$(jq -r --arg id "$session_id" '
-            .sessions | to_entries[] | select(.key | startswith($id)) | "\(.value.name // "")\t\(.value.workingDir // "")"
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-        if [ -n "$result" ]; then
-            name="${result%%	*}"
-            [ -z "$workdir" ] && workdir="${result#*	}"
-        fi
-    fi
-
-    if [ -n "$name" ]; then
-        echo "$name"
-        return
-    fi
-
-    if [ -n "$workdir" ]; then
-        echo "${workdir##*/}"
-        return
-    fi
-
-    echo "${session_id:0:8}"
-}
-
-get_working_dir() {
-    local session_id="$1"
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local dir
-        dir=$(jq -r --arg id "$session_id" '
-            .[] | select(.sessionId | startswith($id)) | .workingDir // empty
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-        if [ -n "$dir" ] && [ "$dir" != "null" ]; then
-            echo "${dir/#$HOME/~}"
-            return
-        fi
-    fi
-
-    if [ -f "$CODEMAN_STATE" ]; then
-        local dir
-        dir=$(jq -r --arg id "$session_id" '
-            .sessions | to_entries[] | select(.key | startswith($id)) | .value.workingDir // empty
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-        if [ -n "$dir" ] && [ "$dir" != "null" ]; then
-            echo "${dir/#$HOME/~}"
-            return
-        fi
-    fi
-    echo ""
-}
-
-get_tokens() {
-    local session_id="$1"
-
-    if [ -f "$CODEMAN_STATE" ]; then
-        local tokens
-        tokens=$(jq -r --arg id "$session_id" '
-            .sessions | to_entries[] | select(.key | startswith($id)) |
-            ((.value.inputTokens // 0) + (.value.outputTokens // 0))
-        ' "$CODEMAN_STATE" 2>/dev/null | head -1)
-
-        if [ -n "$tokens" ] && [ "$tokens" != "null" ] && [ "$tokens" -gt 0 ] 2>/dev/null; then
-            if [ "$tokens" -gt 1000 ]; then
-                echo "$((tokens / 1000))k"
-            else
-                echo "${tokens}"
-            fi
-            return
-        fi
-    fi
-    echo ""
-}
-
-get_respawn_status() {
-    local session_id="$1"
-
-    if [ -f "$CODEMAN_SESSIONS" ]; then
-        local respawn_enabled
-        respawn_enabled=$(jq -r --arg id "$session_id" '
-            .[] | select(.sessionId | startswith($id)) | .respawnConfig.enabled // false
-        ' "$CODEMAN_SESSIONS" 2>/dev/null | head -1)
-
-        if [ "$respawn_enabled" = "true" ]; then
-            echo "R"
-            return
-        fi
-    fi
-    echo ""
-}
-
-check_deps() {
-    if ! command -v jq &>/dev/null; then
-        echo -e "${YELLOW}Note: Install jq for session names${R}"
-        echo ""
-    fi
-}
-
-# ============================================================================
-# Tmux Session Parser
-# ============================================================================
-
-declare -a SESSION_PIDS
-declare -a MUX_NAMES
-declare -a SESSION_STATES
-declare -a SESSION_IDS
-declare -a DISPLAY_NAMES
-declare -a WORKING_DIRS
-declare -a TOKEN_COUNTS
-declare -a RESPAWN_STATUS
-
-parse_sessions() {
-    SESSION_PIDS=()
-    MUX_NAMES=()
-    SESSION_STATES=()
-    SESSION_IDS=()
-    DISPLAY_NAMES=()
-    WORKING_DIRS=()
-    TOKEN_COUNTS=()
-    RESPAWN_STATUS=()
-
-    local i=0
-
-    # Parse tmux list-sessions output
-    while IFS= read -r line; do
-        local session_name="${line%%:*}"
-
-        # Only show codeman sessions
-        if [[ "$session_name" != codeman-* ]]; then
-            continue
-        fi
-
-        # Check if attached
-        local state="Detached"
-        if [[ "$line" == *"(attached)"* ]]; then
-            state="Attached"
-        fi
-
-        # Get PID from tmux
-        local pid
-        pid=$("${TMUX_CMD[@]}" display-message -t "$session_name" -p '#{pane_pid}' 2>/dev/null || echo "0")
-
-        SESSION_PIDS+=("$pid")
-        MUX_NAMES+=("$session_name")
-        SESSION_STATES+=("$state")
-
-        # Extract session ID from codeman session name
-        local session_id=""
-        local cm_regex='^codeman-(.+)$'
-        if [[ "$session_name" =~ $cm_regex ]]; then
-            session_id="${BASH_REMATCH[1]}"
-        fi
-        SESSION_IDS+=("$session_id")
-
-        # Get display name and metadata
-        if [ -n "$session_id" ]; then
-            DISPLAY_NAMES+=("$(get_session_name "$session_id")")
-            WORKING_DIRS+=("$(get_working_dir "$session_id")")
-            TOKEN_COUNTS+=("$(get_tokens "$session_id")")
-            RESPAWN_STATUS+=("$(get_respawn_status "$session_id")")
-        else
-            DISPLAY_NAMES+=("$session_name")
-            WORKING_DIRS+=("")
-            TOKEN_COUNTS+=("")
-            RESPAWN_STATUS+=("")
-        fi
-
-        i=$((i + 1))
-    done < <("${TMUX_CMD[@]}" list-sessions 2>/dev/null || true)
-}
-
-# ============================================================================
-# Display Functions
-# ============================================================================
-
-clear_screen() {
-    printf '\033[2J\033[H'
-}
-
-print_header() {
-    local count=${#SESSION_PIDS[@]}
-    echo -e "${B}${CYAN}Codeman Sessions${R} ${D}($count)${R}"
-    echo -e "${D}$(printf '%.0s─' {1..32})${R}"
-}
-
-print_entry() {
-    local idx="$1"
-    local num=$((idx + 1))
-    local name="${DISPLAY_NAMES[$idx]}"
-    local state="${SESSION_STATES[$idx]}"
-    local dir="${WORKING_DIRS[$idx]}"
-    local tokens="${TOKEN_COUNTS[$idx]}"
-    local respawn="${RESPAWN_STATUS[$idx]}"
-
-    local name_max=$MAX_NAME_LEN
-    [ -n "$respawn" ] && name_max=$((name_max - 2))
-    [ -n "$tokens" ] && name_max=$((name_max - 4))
-    name=$(truncate "$name" $name_max)
-
-    local status_icon status_color
-    if [[ "$state" == *"Attached"* ]]; then
-        status_icon="$ICON_ATTACHED"
-        status_color="$GREEN"
-    elif [[ "$state" == *"Detached"* ]]; then
-        status_icon="$ICON_DETACHED"
-        status_color="$GRAY"
-    else
-        status_icon="$ICON_UNKNOWN"
-        status_color="$YELLOW"
-    fi
-
-    local num_str="${B}${WHITE}${num})${R}"
-    local name_str="${B}${WHITE}${name}${R}"
-    local status_str="${status_color}${status_icon}${R}"
-
-    local respawn_str=""
-    if [ -n "$respawn" ]; then
-        respawn_str=" ${GREEN}${respawn}${R}"
-    fi
-
-    local token_str=""
-    if [ -n "$tokens" ]; then
-        token_str=" ${D}${tokens}${R}"
-    fi
-
-    echo -e " ${num_str} ${name_str} ${status_str}${respawn_str}${token_str}"
-
-    if [ -n "$dir" ]; then
-        dir=$(truncate "$dir" $((MAX_NAME_LEN - 2)))
-        echo -e "    ${D}${dir}${R}"
-    fi
-}
-
-print_footer() {
-    local page="$1"
-    local total_pages="$2"
-
-    echo ""
-    echo -e "${D}────────────────────────────────${R}"
-
-    if [ "$total_pages" -gt 1 ]; then
-        echo -e " ${D}Page $((page+1))/$total_pages${R}  ${GRAY}[${WHITE}n${GRAY}]ext [${WHITE}p${GRAY}]rev${R}"
-    fi
-
-    echo -e " ${GRAY}[${WHITE}1-9${GRAY}]attach [${WHITE}r${GRAY}]efresh [${WHITE}q${GRAY}]uit${R}"
-}
-
-print_no_sessions() {
-    clear_screen
-    echo -e "${B}${CYAN}Codeman Sessions${R}"
-    echo -e "${D}$(printf '%.0s─' {1..32})${R}"
-    echo ""
-    echo -e "  ${YELLOW}No tmux sessions found${R}"
-    echo ""
-    echo -e "  ${D}Start one with:${R}"
-    echo -e "  ${WHITE}codeman web${R}"
-    echo ""
-    echo -e "${D}$(printf '%.0s─' {1..32})${R}"
-    echo -e " ${GRAY}[${WHITE}r${GRAY}]efresh [${WHITE}q${GRAY}]uit${R}"
-}
-
-# ============================================================================
-# Main Display Loop
-# ============================================================================
-
-current_page=0
-
-render() {
-    clear_screen
-    parse_sessions
-
-    local count=${#SESSION_PIDS[@]}
-
-    if [ "$count" -eq 0 ]; then
-        print_no_sessions
-        return
-    fi
-
-    local total_pages=$(( (count + PAGE_SIZE - 1) / PAGE_SIZE ))
-
-    if [ "$current_page" -ge "$total_pages" ]; then
-        current_page=$((total_pages - 1))
-    fi
-    if [ "$current_page" -lt 0 ]; then
-        current_page=0
-    fi
-
-    local start=$((current_page * PAGE_SIZE))
-    local end=$((start + PAGE_SIZE))
-    if [ "$end" -gt "$count" ]; then
-        end=$count
-    fi
-
-    print_header
-    echo ""
-
-    for ((i = start; i < end; i++)); do
-        print_entry $i
-    done
-
-    print_footer $current_page $total_pages
-}
-
-attach_session() {
-    local idx="$1"
-    local mux_name="${MUX_NAMES[$idx]}"
-
-    if [ -z "$mux_name" ]; then
-        return 1
-    fi
-
-    clear_screen
-    echo -e "${GREEN}Attaching to ${B}${DISPLAY_NAMES[$idx]}${R}${GREEN}...${R}"
-    echo -e "${D}(Ctrl+B D to detach)${R}"
-    sleep 0.3
-
-    "${TMUX_CMD[@]}" attach-session -t "$mux_name"
-
-    return 0
-}
-
-# ============================================================================
-# Input Handler
-# ============================================================================
-
-handle_input() {
-    local key="$1"
-    local count=${#SESSION_PIDS[@]}
-    local total_pages=$(( (count + PAGE_SIZE - 1) / PAGE_SIZE ))
-
-    case "$key" in
-        [1-9])
-            local idx=$((key - 1))
-            if [ "$idx" -lt "$count" ]; then
-                attach_session "$idx"
-                return 0
-            fi
-            ;;
-
-        $'\e')
-            read -rsn2 -t 0.1 seq 2>/dev/null || true
-            case "$seq" in
-                '[A'|'[D')
-                    if [ "$total_pages" -gt 1 ]; then
-                        current_page=$(( (current_page - 1 + total_pages) % total_pages ))
-                    fi
-                    ;;
-                '[B'|'[C')
-                    if [ "$total_pages" -gt 1 ]; then
-                        current_page=$(( (current_page + 1) % total_pages ))
-                    fi
-                    ;;
-            esac
-            ;;
-
-        n|N|j|J)
-            if [ "$total_pages" -gt 1 ]; then
-                current_page=$(( (current_page + 1) % total_pages ))
-            fi
-            ;;
-
-        p|P|k|K)
-            if [ "$total_pages" -gt 1 ]; then
-                current_page=$(( (current_page - 1 + total_pages) % total_pages ))
-            fi
-            ;;
-
-        r|R)
-            ;;
-
-        q|Q)
-            clear_screen
-            exit 0
-            ;;
-
-        '')
-            if [ "$count" -eq 1 ]; then
-                attach_session 0
-                return 0
-            fi
-            ;;
-    esac
-
-    return 0
-}
-
-# ============================================================================
-# List Mode
-# ============================================================================
-
-list_mode() {
-    parse_sessions
-    local count=${#SESSION_PIDS[@]}
-
-    if [ "$count" -eq 0 ]; then
-        echo "No tmux sessions"
-        exit 0
-    fi
-
-    for ((i = 0; i < count; i++)); do
-        local num=$((i + 1))
-        local name="${DISPLAY_NAMES[$i]}"
-        local state="${SESSION_STATES[$i]}"
-        local respawn="${RESPAWN_STATUS[$i]}"
-        local indicator="-"
-        [[ "$state" == *"Attached"* ]] && indicator="*"
-        [ -n "$respawn" ] && indicator="${indicator}R"
-
-        echo "$num) $name [$indicator]"
-    done
-}
-
-# ============================================================================
-# Quick Attach
-# ============================================================================
-
-quick_attach() {
-    local num="$1"
-    parse_sessions
-
-    local count=${#SESSION_PIDS[@]}
-    local idx=$((num - 1))
-
-    if [ "$idx" -lt 0 ] || [ "$idx" -ge "$count" ]; then
-        echo -e "${RED}Invalid session: $num${R}"
-        echo "Available: 1-$count"
-        exit 1
-    fi
-
-    attach_session "$idx"
-}
-
-# ============================================================================
-# Help
-# ============================================================================
-
-show_help() {
-    cat << 'EOF'
-Codeman Sessions - Mobile-friendly Tmux Session Chooser
-
-USAGE:
-  sc              Interactive chooser
-  sc <number>     Quick attach to session N
-  sc -l           List sessions (non-interactive)
-  sc -h           Show this help
-
-INTERACTIVE KEYS:
-  1-9      Attach to session
-  n/j/↓    Next page
-  p/k/↑    Previous page
-  r        Refresh
-  q        Quit
-
-INDICATORS:
-  * / ●    Attached (someone connected)
-  - / ○    Detached (available)
-  R        Respawn enabled
-  45k      Token count
-
-TIPS:
-  - Detach from tmux: Ctrl+B D
-  - Session names from Codeman state
-  - Optimized for Termius/iPhone
-
-EOF
-}
-
-# ============================================================================
-# Main
-# ============================================================================
-
-main() {
-    case "${1:-}" in
-        -h|--help)
-            show_help
-            exit 0
-            ;;
-        -l|--list)
-            list_mode
-            exit 0
-            ;;
-        [1-9]|[1-9][0-9])
-            quick_attach "$1"
-            exit $?
-            ;;
-    esac
-
-    check_deps
-
-    render
-
-    while true; do
-        local timeout_opt=""
-        if [ "$AUTO_REFRESH" -gt 0 ]; then
-            timeout_opt="-t $AUTO_REFRESH"
-        fi
-
-        if read -rsn1 $timeout_opt key 2>/dev/null; then
-            handle_input "$key"
-        fi
-        render
-    done
-}
-
-trap 'clear_screen; exit 0' INT
-
-main "$@"

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.21.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.21.0$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.21.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,90 @@ _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'
+}
+# ---- the workspace-trust dialog: READ the screen, never press Enter blind ----
+# Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights
+# "No, exit" by default:
+#     Security guide
+#   ❯ No, exit
+#     Yes, I trust this folder
+#   Enter to confirm . Esc to cancel
+# so the bare \r that answered the old layout now answers *exit* and the pane is
+# dead (`status 1`) seconds after the spawn -- measured on a live 2.1.252 case.
+# These two read the rendered pane and steer onto the trust option instead.
+_trust_key() {     # <sid> -> "confirm" | "move" | "" (nothing safe to press)
+  # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that
+  # is the current frame rather than every repaint since launch. tail -1 anyway,
+  # because the freshest marked row is the only one still true.
+  "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+    | jq -r '.data.terminalBuffer // empty' \
+    | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
+    | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
+    | sed -e 's/.*[Yy]es,.*/confirm/' -e 's/.*[Nn]o,.*/move/'
+}
+_accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could not
+  local sid="$1" k i=1
+  while [ "$i" -le 6 ]; do
+    k=$(_trust_key "$sid")
+    [ -n "$k" ] || return 1   # no dialog on screen, or a layout this cannot read
+    # A SEPARATE clientId for these keys. seq is monotonic per clientId, so
+    # spending prompt numbers here would make the next sendwait -- whose default
+    # seq is the epoch second -- look like a stale duplicate and vanish silently.
+    "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
+      -d "$(jq -nc --arg k "$([ "$k" = confirm ] && printf '\r' || printf '\033[B')" \
+              --arg c "$CID-trust-$sid" --argjson s "$i" \
+              '{input:$k,useMux:true,clientId:$c,seq:$s}')" >/dev/null
+    [ "$k" = confirm ] && return 0
+    sleep 1; i=$((i+1))   # re-read: the arrow is CONFIRMED before Enter goes out
+  done
+  return 1
+}
 # 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
@@ -147,38 +214,41 @@ spawn_worker() {
   grep -qs '/api/hook-event' "$cp/.claude/settings.local.json" || {
     echo "case '$name' resolved to '$cp', which has no Codeman hooks (workspaceHooksEnabled off, remote, or an older server?): turn the setting on, or work §5.1+§5.5 by hand with markers" >&2
     delete_session "$sid" >/dev/null; return 1; }
-  # Short composer wait FIRST, then the trust-dialog probe: a case still showing the
-  # dialog can never pass the composer wait, so probing early keeps a cold case from
+  # Short composer wait FIRST, then the trust dialog: a case still showing the
+  # dialog can never pass the composer wait, so acting early keeps a cold case from
   # paying the whole long wait before the fallback even runs (§5.2). A warm case
-  # matches in under a second and never reaches the probe.
+  # matches in under a second and never reaches it, and _accept_trust returns in a
+  # blink when there is no dialog, so this costs nothing in the ordinary slow case.
   r=$(_composer_up "$sid" 5000)
   if [ "$r" != true ]; then
-    if "${CURL[@]}" -G "$API/api/v1/sessions/$sid/wait-output" \
-         --data-urlencode 'match=trust' --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000' \
-       | jq -e '.data.wait.matched' >/dev/null; then
-      # Codeman's own auto-accept gives up after 90 s / 3 tries; this is that bounded fallback.
-      "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
-        -d "$(jq -nc --arg c "$CID-$sid" '{input:"\r",useMux:true,clientId:$c,seq:1}')" >/dev/null
-    fi
+    # Codeman answers this dialog itself and normally wins the race; this is the
+    # bounded fallback for when its 90 s window / 6-keystroke cap has run out.
+    _accept_trust "$sid"
     r=$(_composer_up "$sid" 45000)
   fi
   [ "$r" = true ] || { echo "worker $sid never drew a composer; deleted it. Retry by hand via the §5.2 ladder (its billed stage-4 probe included)" >&2
     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 +264,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 +322,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.21.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.21.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 +376,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.21.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 +443,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`, `grok` and `omp` 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 +481,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 +585,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.21.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,90 @@ _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'
+}
+# ---- the workspace-trust dialog: READ the screen, never press Enter blind ----
+# Claude Code 2.1.252 dropped the option numbers, REVERSED them, and highlights
+# "No, exit" by default:
+#     Security guide
+#   ❯ No, exit
+#     Yes, I trust this folder
+#   Enter to confirm . Esc to cancel
+# so the bare \r that answered the old layout now answers *exit* and the pane is
+# dead (`status 1`) seconds after the spawn -- measured on a live 2.1.252 case.
+# These two read the rendered pane and steer onto the trust option instead.
+_trust_key() {     # <sid> -> "confirm" | "move" | "" (nothing safe to press)
+  # full=1 returns the RENDERED pane; a claude pane keeps no tmux history, so that
+  # is the current frame rather than every repaint since launch. tail -1 anyway,
+  # because the freshest marked row is the only one still true.
+  "${CURL[@]}" -G "$API/api/v1/sessions/$1/terminal" --data-urlencode 'full=1' \
+    | jq -r '.data.terminalBuffer // empty' \
+    | sed -e "s/$(printf '\033')\[[0-9;?]*[a-zA-Z]//g" -e "s/$(printf '\033')[()][AB0]//g" \
+    | tr -d ' \t' | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
+    | sed -e 's/.*[Yy]es,.*/confirm/' -e 's/.*[Nn]o,.*/move/'
+}
+_accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could not
+  local sid="$1" k i=1
+  while [ "$i" -le 6 ]; do
+    k=$(_trust_key "$sid")
+    [ -n "$k" ] || return 1   # no dialog on screen, or a layout this cannot read
+    # A SEPARATE clientId for these keys. seq is monotonic per clientId, so
+    # spending prompt numbers here would make the next sendwait -- whose default
+    # seq is the epoch second -- look like a stale duplicate and vanish silently.
+    "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
+      -d "$(jq -nc --arg k "$([ "$k" = confirm ] && printf '\r' || printf '\033[B')" \
+              --arg c "$CID-trust-$sid" --argjson s "$i" \
+              '{input:$k,useMux:true,clientId:$c,seq:$s}')" >/dev/null
+    [ "$k" = confirm ] && return 0
+    sleep 1; i=$((i+1))   # re-read: the arrow is CONFIRMED before Enter goes out
+  done
+  return 1
+}
 # 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
@@ -69,38 +136,41 @@ spawn_worker() {
   grep -qs '/api/hook-event' "$cp/.claude/settings.local.json" || {
     echo "case '$name' resolved to '$cp', which has no Codeman hooks (workspaceHooksEnabled off, remote, or an older server?): turn the setting on, or work §5.1+§5.5 by hand with markers" >&2
     delete_session "$sid" >/dev/null; return 1; }
-  # Short composer wait FIRST, then the trust-dialog probe: a case still showing the
-  # dialog can never pass the composer wait, so probing early keeps a cold case from
+  # Short composer wait FIRST, then the trust dialog: a case still showing the
+  # dialog can never pass the composer wait, so acting early keeps a cold case from
   # paying the whole long wait before the fallback even runs (§5.2). A warm case
-  # matches in under a second and never reaches the probe.
+  # matches in under a second and never reaches it, and _accept_trust returns in a
+  # blink when there is no dialog, so this costs nothing in the ordinary slow case.
   r=$(_composer_up "$sid" 5000)
   if [ "$r" != true ]; then
-    if "${CURL[@]}" -G "$API/api/v1/sessions/$sid/wait-output" \
-         --data-urlencode 'match=trust' --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000' \
-       | jq -e '.data.wait.matched' >/dev/null; then
-      # Codeman's own auto-accept gives up after 90 s / 3 tries; this is that bounded fallback.
-      "${CURL[@]}" -X POST "$API/api/v1/sessions/$sid/input" -H 'Content-Type: application/json' \
-        -d "$(jq -nc --arg c "$CID-$sid" '{input:"\r",useMux:true,clientId:$c,seq:1}')" >/dev/null
-    fi
+    # Codeman answers this dialog itself and normally wins the race; this is the
+    # bounded fallback for when its 90 s window / 6-keystroke cap has run out.
+    _accept_trust "$sid"
     r=$(_composer_up "$sid" 45000)
   fi
   [ "$r" = true ] || { echo "worker $sid never drew a composer; deleted it. Retry by hand via the §5.2 ladder (its billed stage-4 probe included)" >&2
     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 +186,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 +244,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.21.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`, `grok` and `omp`, 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|omp`; 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`
-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.
+`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`,
+`GET /api/v1/pi/status` and `GET /api/v1/omp/status` each return `.data.{available, path}` (no session needed).
+Pi's, grok's and OMP's also carry `.data.version`, because `pi` is a short generic name,
+`grok` is a name with npm squatters, and `omp` is a similarly short name, so an unrelated
+binary on `$PATH` can shadow any of them: the resolver rejects one whose `--version` is
+not version-shaped, so `available:false` there can mean "a different program of the same
+name 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:~2225`), so it is permanently
+  `[]` on `opencode`/`codex`/`gemini`/`antigravity`/`pi`/`grok`/`deepseek`/`omp`. ⚠️ **`shell` is NOT one of those**
+  (`isExternalCliMode`, `session.ts:176-187`, lists only those seven), 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,8 +798,10 @@ 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` |
-| 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 |
+| 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 a keystroke cap); use the readiness recipe in SKILL.md, wait for `shift+tab` first, answer the dialog only as the bounded fallback |
+| a brand-new claude worker's pane is DEAD (`status 1`) seconds after the spawn | something pressed Enter at the first-run trust dialog. Since claude-cli 2.1.252 its options are unnumbered, reversed, and the highlighted default is `No, exit`, so a blind `\r` — an up-front Enter, or a task prompt typed into the dialog — quits the CLI. Answer it by reading the `❯` marker off `terminal?full=1` and arrowing onto `Yes, I trust this folder` first: `_accept_trust` in the §0 preamble |
 | 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 |
 | `wait-output` times out although the pane shows the text | multi-word match against a TUI screen; the stream has no spaces there, match one token |

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`/`omp`) | 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`, `omp`) 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

@@ -69,9 +69,14 @@ SEQ=1               # $CID is the fixed literal from the preamble; never rebuild
 #    plus a two-marker screen match in session-trust-dialog.ts), not the output stream.
 #    It still misses two ways, and both leave the dialog up until someone answers it:
 #    it only scans in the first 90 s after the pane started (TRUST_DIALOG_WINDOW_MS),
-#    and it gives up after 3 Enter presses (TRUST_DIALOG_MAX_ATTEMPTS). So: composer
-#    marker first, dialog only as the bounded fallback (a blind Enter up front would
-#    land in an already-ready composer).
+#    and it gives up after 6 keystrokes (TRUST_DIALOG_MAX_ATTEMPTS). So: composer
+#    marker first, dialog only as the bounded fallback.
+#    ⚠️ The dialog is NOT answered with Enter. Since claude-cli 2.1.252 the options
+#    lost their numbers, swapped places, and the highlighted one is `No, exit`, so a
+#    blind \r quits the CLI and the pane is dead seconds after the spawn (measured).
+#    _accept_trust (§0 preamble) reads the ❯ marker off the rendered pane, arrows onto
+#    `Yes, I trust this folder`, re-reads to confirm the move landed, and only then
+#    presses Enter.
 #    Stage 1 is SHORT on purpose: an already-trusted case matches in <1 s, while a
 #    virgin case can never pass it (the dialog is up) and always pays it in full,
 #    the long budget belongs to stage 3, after the dialog is answered.
@@ -92,13 +97,8 @@ done
 R=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' --data-urlencode 'timeout=5000')
 if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
-  T=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
-      --data-urlencode 'match=trust' --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000')
-  if jq -e '.data.wait.matched' <<<"$T" >/dev/null; then
-    "${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" -H 'Content-Type: application/json' \
-      -d '{"input":"\r","useMux":true,"clientId":"'"$CID"'","seq":'$SEQ'}' >/dev/null
-    SEQ=$((SEQ+1))
-  fi
+  _accept_trust "$SID"   # reads the marker and steers; never a blind \r. Own clientId,
+                         # so it spends none of $SEQ's numbers.
   R=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
       --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' --data-urlencode 'timeout=45000')
 fi
@@ -106,8 +106,8 @@ if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
   # stage 4, mode-agnostic and bounded: answering a trivial prompt IS readiness.
   # COSTS THE WORKER ONE BILLED TURN, so it only runs when the fast marker missed.
   # Split token (the typed line echoes into the stream) and unique per call. Must stay
-  # AFTER the dialog fallback: free text plus \r into a trust dialog still up answers
-  # it blind, the same footgun as an up-front Enter.
+  # AFTER the dialog fallback: the select widget swallows the text and the \r answers
+  # whatever is highlighted, which on a live dialog is `No, exit`.
   TOK="${RANDOM}_$$"
   "${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" -H 'Content-Type: application/json' \
     -d '{"input":"reply with the word READY immediately followed by _'"$TOK"' and nothing else\r","useMux":true,"clientId":"'"$CID"'","seq":'$SEQ'}' >/dev/null
@@ -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/omp, 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
@@ -474,9 +527,10 @@ done
   circuit breaker, which exists to stop a worker that crashes on every start from being
   restarted in a loop; clearing it unasked re-arms that loop.
 - Then run **Flow 1's readiness stages 1-3** on each SID. A path claude has never been
-  run in shows the trust dialog, and typing your task into a dialog answers it blind and
-  loses the task. Stages 1-3 cost no turn; stage 4, if it fires, costs that worker one
-  billed turn.
+  run in shows the trust dialog, and typing your task into it does not just lose the
+  task: the select widget swallows the text and the trailing `\r` answers the
+  highlighted option, which since claude-cli 2.1.252 is `No, exit`. Stages 1-3 cost no
+  turn; stage 4, if it fires, costs that worker one billed turn.
 
 ### 4. Hand out the tasks: markers, not send-and-wait
 

skills/codeman/reference/verbs.md

@@ -152,17 +152,46 @@ 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()`
 reads the **rendered pane** via `capturePaneText()` rather than the arriving chunk
 (the per-chunk `includes()` version could never match, because tmux repaints the row
 with cursor-forward escapes in place of spaces, and it is documented in-source as the
-historical bug). The remaining miss modes are structural: the auto-accept only runs
-inside a 90 s window after interactive start and gives up after 3 attempts. So keep
-the dialog handling as a bounded fallback, and never send a blind Enter up front (if
-auto-accept already fired, it lands in the composer).
+historical bug).
+
+⚠️ **The answer is no longer "press Enter".** Claude Code 2.1.252 dropped the option
+numbers, reversed the two options, and highlights the one that quits:
+
+```
+  ❯ No, exit
+    Yes, I trust this folder
+  Enter to confirm · Esc to cancel
+```
+
+so a blind `\r` answers *exit*: the pane is dead (`Pane is dead (status 1)`) about six
+seconds after the spawn, measured on a fresh case. Read the marker off the rendered
+pane (`GET .../terminal?full=1`), send `ESC [ B` while it sits on `No, exit`, re-read,
+and press Enter only once the marker is on the trust option. `_accept_trust` in the
+§0 preamble is exactly that, and `trustDialogNextKey()` is the server-side twin.
+
+The remaining miss modes are structural: the auto-accept only runs inside a 90 s window
+after interactive start and gives up after 6 keystrokes. So keep the dialog handling as
+a bounded fallback, and never send a blind Enter up front — landing in an already-ready
+composer only wastes a turn, landing in this dialog ends the worker.
 
 Stage 1 is short on purpose: an already-trusted case matches `shift+tab` in under a
 second, while a case still showing the dialog cannot pass stage 1 at all and always
@@ -220,14 +249,11 @@ SEQ=1   # $CID came from the §0 preamble; do NOT rebuild it from $$
 R=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
     --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' --data-urlencode 'timeout=5000')
 if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
-  # composer never appeared, so the trust dialog is probably still up; accept it once
-  T=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
-      --data-urlencode 'match=trust' --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000')
-  if jq -e '.data.wait.matched' <<<"$T" >/dev/null; then
-    "${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" -H 'Content-Type: application/json' \
-      -d '{"input":"\r","useMux":true,"clientId":"'"$CID"'","seq":'$SEQ'}' >/dev/null
-    SEQ=$((SEQ+1))
-  fi
+  # Composer never appeared, so the trust dialog is probably still up. NEVER a blind
+  # Enter here: the highlighted option is "No, exit". _accept_trust (§0 preamble) reads
+  # the marker off the pane, arrows onto the trust option, re-reads, then confirms. It
+  # carries its OWN clientId, so it spends none of $SEQ's numbers.
+  _accept_trust "$SID"
   R=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
       --data-urlencode 'match=shift+tab' --data-urlencode 'from=buffer' --data-urlencode 'timeout=45000')
 fi
@@ -236,8 +262,10 @@ if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
   # of a broken worker, and answering is proof that it works. Split the token (your
   # keystrokes echo into the stream) and keep it unique per call. This costs the worker
   # one billed turn, so it runs only after the fast path missed. It must stay AFTER
-  # stage 2, which is the only thing that clears the trust dialog: free text plus \r
-  # into a dialog still up answers it blind, the same footgun as the up-front Enter.
+  # stage 2, which is the only thing that clears the trust dialog: the typed text is
+  # swallowed by the select widget and the \r then answers whatever is highlighted,
+  # which since 2.1.252 is "No, exit" -- the same footgun as the up-front Enter, except
+  # that it kills the worker rather than wasting a turn.
   TOK="${RANDOM}_$$"
   "${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" -H 'Content-Type: application/json' \
     -d '{"input":"reply with the word READY immediately followed by _'"$TOK"' and nothing else\r","useMux":true,"clientId":"'"$CID"'","seq":'$SEQ'}' >/dev/null
@@ -341,17 +369,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`/`omp`, 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 +415,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`, `omp`; 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 +501,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`/`omp`** (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/cli-style.ts

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview One style vocabulary for everything the `codeman` CLI prints:
+ * palette, glyphs, the small block helpers (heading/rule/kv), width-aware table
+ * layout, a stderr spinner and a y/N confirm.
+ *
+ * Color detection is chalk's alone. It already honors NO_COLOR, FORCE_COLOR,
+ * TERM=dumb and TTY-ness, and a second detector here would disagree with it on
+ * some terminal with no way to tell which one was right.
+ *
+ * The layout math is pure and exported separately from anything that touches a
+ * terminal, which is what lets it be unit-tested with no TTY and reused by
+ * `utils/dependency-report.ts` while that file stays color-free.
+ *
+ * @module cli-style
+ */
+
+import chalk, { type ChalkInstance } from 'chalk';
+import { createInterface } from 'node:readline';
+// Direct import, not the `utils` barrel: the barrel pulls in node-pty and every
+// CLI resolver, which a style module has no business loading.
+import { stripAnsi } from './utils/regex-patterns.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Palette and glyphs
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Semantic roles, mirroring the web UI's status language (green fine, yellow waiting, red blocked). */
+export const palette = {
+  ok: chalk.green,
+  warn: chalk.yellow,
+  err: chalk.red,
+  info: chalk.cyan,
+  muted: chalk.gray,
+  emph: chalk.bold,
+  accent: chalk.magenta,
+} as const satisfies Record<string, ChalkInstance>;
+
+/** The glyph vocabulary the CLI already used, in one place. */
+export const GLYPH = {
+  ok: '✓',
+  fail: '✗',
+  warn: '⚠',
+  idle: '○',
+  dot: '●',
+  arrow: '→',
+} as const;
+
+/** Spinner frames (braille, one cell wide in every terminal we support). */
+export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const;
+
+/** What a line is reporting, independent of how it is painted. */
+export type Tone = 'ok' | 'warn' | 'err' | 'idle' | 'info';
+
+const TONE_GLYPH: Record<Tone, string> = {
+  ok: GLYPH.ok,
+  warn: GLYPH.warn,
+  err: GLYPH.fail,
+  idle: GLYPH.idle,
+  info: GLYPH.dot,
+};
+
+const TONE_STYLE: Record<Tone, ChalkInstance> = {
+  ok: palette.ok,
+  warn: palette.warn,
+  err: palette.err,
+  idle: palette.muted,
+  info: palette.info,
+};
+
+/** Glyph for a tone. Pure, so the mapping is testable without a terminal. */
+export function glyphFor(tone: Tone): string {
+  return TONE_GLYPH[tone];
+}
+
+/** Paint text in a tone's color. */
+export function tint(tone: Tone, text: string): string {
+  return TONE_STYLE[tone](text);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Blocks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Section heading. The blank line above it is part of the existing block idiom. */
+export function heading(text: string): string {
+  return `\n${palette.emph(text)}`;
+}
+
+/** Horizontal rule under a title. */
+export function rule(width = 40): string {
+  return palette.muted('─'.repeat(Math.max(0, width)));
+}
+
+/**
+ * Indented `Label: value` line. `pad` aligns the values of a block by padding
+ * the label column (including its colon), for blocks whose labels differ in
+ * length.
+ */
+export function kv(label: string, value: string, pad = 0): string {
+  const key = pad > 0 ? padCell(`${label}:`, pad) : `${label}:`;
+  return `  ${key} ${value}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Width-aware layout (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Printed width of a cell: ANSI sequences take no columns. */
+export function displayWidth(text: string): number {
+  return stripAnsi(text).length;
+}
+
+export type CellAlign = 'left' | 'right';
+
+/** Pad to `width` columns, measuring by display width so colored cells still align. */
+export function padCell(text: string, width: number, align: CellAlign = 'left'): string {
+  const fill = ' '.repeat(Math.max(0, width - displayWidth(text)));
+  return align === 'right' ? `${fill}${text}` : `${text}${fill}`;
+}
+
+/**
+ * Pad AFTER the paint, so the fill stays outside the color run and a trailing
+ * empty column can be trimmed away instead of ending in a reset sequence with
+ * invisible spaces before it.
+ */
+export function padStyled(text: string, width: number, paint: (t: string) => string): string {
+  return `${paint(text)}${' '.repeat(Math.max(0, width - displayWidth(text)))}`;
+}
+
+/** Widest cell per column. Short rows count as empty cells, never as narrower columns. */
+export function columnWidths(rows: readonly (readonly string[])[]): number[] {
+  const widths: number[] = [];
+  for (const row of rows) {
+    for (let i = 0; i < row.length; i++) {
+      widths[i] = Math.max(widths[i] ?? 0, displayWidth(row[i] ?? ''));
+    }
+  }
+  return widths;
+}
+
+export interface TableOptions {
+  /** Per-column alignment; missing entries are left-aligned. */
+  align?: readonly CellAlign[];
+  /** Spaces between columns. */
+  gap?: number;
+  /** Prefix for every row. */
+  indent?: string;
+}
+
+/**
+ * Lay rows out in columns sized to their widest cell. The last cell of a row is
+ * never padded, so no line carries trailing whitespace.
+ */
+export function layoutTable(rows: readonly (readonly string[])[], options: TableOptions = {}): string[] {
+  const { align = [], gap = 1, indent = '' } = options;
+  const widths = columnWidths(rows);
+  const separator = ' '.repeat(Math.max(0, gap));
+  return rows.map((row) => {
+    const cells = row.map((cell, i) => (i === row.length - 1 ? cell : padCell(cell, widths[i], align[i] ?? 'left')));
+    return `${indent}${cells.join(separator)}`;
+  });
+}
+
+/** `layoutTable()` as one printable block. */
+export function table(rows: readonly (readonly string[])[], options: TableOptions = {}): string {
+  return layoutTable(rows, options).join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Spinner
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\x1b[K';
+
+/** The slice of a stream a spinner needs; `process.stderr` satisfies it. */
+export interface SpinnerStream {
+  isTTY?: boolean;
+  write(chunk: string): unknown;
+}
+
+export interface Spinner {
+  start(): Spinner;
+  /** Change the text mid-flight. Silent on a non-TTY, which prints once and stops. */
+  setText(text: string): void;
+  /** Clear the line, restore the cursor and optionally print a final line. */
+  stop(finalLine?: string): void;
+}
+
+export interface SpinnerOptions {
+  stream?: SpinnerStream;
+  intervalMs?: number;
+}
+
+/**
+ * In-place progress line on stderr, for the calls that block for tens of seconds
+ * (daemon start, service install). Only a TTY gets the animation: piped output
+ * and journald get the text once, so a log file never fills with `\r` frames.
+ */
+export function spinner(text: string, options: SpinnerOptions = {}): Spinner {
+  const stream = options.stream ?? process.stderr;
+  const intervalMs = options.intervalMs ?? 90;
+  const animated = Boolean(stream.isTTY);
+  let label = text;
+  let frame = 0;
+  let timer: NodeJS.Timeout | null = null;
+  let started = false;
+  let stopped = false;
+
+  const restoreCursor = () => {
+    if (animated) stream.write(SHOW_CURSOR);
+  };
+
+  const render = () => {
+    stream.write(`\r${palette.info(SPINNER_FRAMES[frame % SPINNER_FRAMES.length])} ${label}${CLEAR_LINE}`);
+    frame++;
+  };
+
+  const handle: Spinner = {
+    start() {
+      if (started || stopped) return handle;
+      started = true;
+      if (!animated) {
+        stream.write(`${label}\n`);
+        return handle;
+      }
+      stream.write(HIDE_CURSOR);
+      // A hidden cursor left behind by a Ctrl+C outlives the process, so the
+      // exit hook is not optional.
+      process.once('exit', restoreCursor);
+      render();
+      // Unref'd: a spinner must never be the reason the process stays alive.
+      timer = setInterval(render, intervalMs);
+      timer.unref();
+      return handle;
+    },
+    setText(next: string) {
+      label = next;
+      if (animated && started && !stopped) render();
+    },
+    stop(finalLine?: string) {
+      if (stopped) return;
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (animated && started) {
+        stream.write(`\r${CLEAR_LINE}`);
+        restoreCursor();
+        process.off('exit', restoreCursor);
+      }
+      if (finalLine && animated) stream.write(`${finalLine}\n`);
+    },
+  };
+  return handle;
+}
+
+/** Run `work` with a spinner up, stopping it however `work` ends. */
+export async function withSpinner<T>(text: string, work: () => Promise<T>, options?: SpinnerOptions): Promise<T> {
+  const handle = spinner(text, options).start();
+  try {
+    return await work();
+  } finally {
+    handle.stop();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Confirm
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Is there a human on the other end of both halves of the terminal? */
+export function isInteractive(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+/**
+ * y/N prompt. Answers `false` immediately when stdin is not a TTY (a script
+ * piping into the CLI must never hang on an invisible question), so callers
+ * that support a `--force` flag can branch on `isInteractive()` to keep printing
+ * their "pass --force" hint instead.
+ */
+export async function confirm(question: string): Promise<boolean> {
+  if (!isInteractive()) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise<string>((resolve) => {
+      rl.once('SIGINT', () => resolve(''));
+      rl.question(`${question} ${palette.muted('[y/N]')} `, resolve);
+    });
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+    // readline resumes stdin; a still-flowing stdin keeps the process alive.
+    process.stdin.pause();
+  }
+}

src/cli.ts

@@ -8,7 +8,6 @@
  */
 
 import { Command } from 'commander';
-import chalk from 'chalk';
 import { createRequire } from 'module';
 import http from 'node:http';
 import https from 'node:https';
@@ -16,6 +15,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { homedir } from 'node:os';
 import { dataPath } from './config/instance.js';
+import { casePath } from './config/cases-dir.js';
 import { installAgentSkillInto, removeAgentSkillFrom, type AgentSkillApplyResult } from './hooks-config.js';
 import { getSessionManager } from './session-manager.js';
 import { getTaskQueue } from './task-queue.js';
@@ -26,6 +26,9 @@ import { isSupportedAttachmentExtension } from './attachment-registry.js';
 import { daemonStatus, startDaemon, stopDaemon, type WebLaunchOptions } from './daemon-control.js';
 import { installService, serviceStatus, uninstallService } from './service-installer.js';
 import { isLoopbackBindHost, isUnauthenticatedNetworkAcknowledged } from './web/network-auth-policy.js';
+import { confirm, heading, isInteractive, kv, palette, rule, tint, withSpinner, type Tone } from './cli-style.js';
+import type { ToolResult } from './utils/dependency-checker.js';
+import type { ReportStyle } from './utils/dependency-report.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json') as { version: string };
@@ -107,14 +110,14 @@ program
   .action(async (filePath, options) => {
     const extension = String(filePath).split('.').pop()?.toLowerCase() || '';
     if (!isAbsolute(filePath) || !isSupportedAttachmentExtension(extension)) {
-      console.error(chalk.red('✗ attach requires an absolute path to a png, pdf, docx, pptx, md, or txt file'));
+      console.error(palette.err('✗ attach requires an absolute path to a png, pdf, docx, pptx, md, or txt file'));
       process.exit(1);
     }
 
     const sessionId = options.session || process.env.CODEMAN_SESSION_ID;
     const apiUrl = options.url || process.env.CODEMAN_API_URL || 'https://127.0.0.1:3000';
     if (sessionId && (await postAttachment(apiUrl, sessionId, filePath))) {
-      console.log(chalk.green('✓ Attachment card requested'));
+      console.log(palette.ok('✓ Attachment card requested'));
       return;
     }
 
@@ -144,7 +147,9 @@ export function resolveCliCasePath(name: string): string {
   } catch {
     // no registry yet, or unreadable/invalid JSON: fall through to the cases dir
   }
-  return join(homedir(), 'codeman-cases', name);
+  // Same resolver the server uses, so CODEMAN_CASES_PATH (Docker Compose) moves
+  // the CLI's idea of a case with it instead of leaving it on the home default.
+  return casePath(name);
 }
 
 /**
@@ -174,7 +179,7 @@ export function resolveSkillTargetPath(options: {
 function resolveSkillTarget(options: { case?: string }): string {
   const resolved = resolveSkillTargetPath(options);
   if (resolved.missingCase !== undefined) {
-    console.error(chalk.red(`✗ Case not found: ${resolved.missingCase}`));
+    console.error(palette.err(`✗ Case not found: ${resolved.missingCase}`));
     process.exit(1);
   }
   return resolved.target;
@@ -199,9 +204,9 @@ function reportSkillResult(result: AgentSkillApplyResult, target: string): void
   };
   const message = messages[result];
   if (message.ok) {
-    console.log(chalk.green(`✓ ${message.text}`));
+    console.log(palette.ok(`✓ ${message.text}`));
   } else {
-    console.error(chalk.red(`✗ ${message.text}`));
+    console.error(palette.err(`✗ ${message.text}`));
     process.exit(1);
   }
 }
@@ -220,7 +225,7 @@ skillCmd
       const target = resolveSkillTarget(options);
       reportSkillResult(await installAgentSkillInto(target), target);
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to install agent skill: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to install agent skill: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -235,7 +240,7 @@ skillCmd
       const target = resolveSkillTarget(options);
       reportSkillResult(await removeAgentSkillFrom(target), target);
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to remove agent skill: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to remove agent skill: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -252,11 +257,11 @@ sessionCmd
     try {
       const manager = getSessionManager();
       const session = await manager.createSession(options.dir);
-      console.log(chalk.green(`✓ Session started: ${session.id}`));
+      console.log(palette.ok(`✓ Session started: ${session.id}`));
       console.log(`  Working directory: ${session.workingDir}`);
       console.log(`  PID: ${session.pid}`);
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to start session: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to start session: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -268,70 +273,81 @@ sessionCmd
     try {
       const manager = getSessionManager();
       await manager.stopSession(id);
-      console.log(chalk.green(`✓ Session stopped: ${id}`));
+      console.log(palette.ok(`✓ Session stopped: ${id}`));
     } catch (err) {
-      console.error(chalk.red(`✗ Failed to stop session: ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ Failed to stop session: ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
 
+/** Session status in the shared vocabulary: idle is fine, busy is working, anything else is a problem. */
+function sessionStatusLabel(status: string): string {
+  if (status === 'idle') return palette.ok('idle');
+  if (status === 'busy') return palette.warn('busy');
+  return palette.err(status);
+}
+
+/**
+ * The one session listing. `codeman list` used to be a copy of this that had
+ * drifted (it lost the stopped and web-server sections), so it now calls the
+ * same renderer and only opts out of those two sections.
+ */
+function printSessionList(options: { includeStored: boolean }): void {
+  const manager = getSessionManager();
+  const sessions = manager.getAllSessions();
+  const stored = manager.getStoredSessions();
+
+  if (sessions.length === 0 && Object.keys(stored).length === 0) {
+    console.log(palette.warn('No sessions found'));
+    return;
+  }
+
+  console.log(heading('Active Sessions:'));
+  if (sessions.length === 0) {
+    console.log('  (none)');
+  } else {
+    for (const session of sessions) {
+      console.log(
+        `  ${palette.info(session.id.slice(0, 8))} ${sessionStatusLabel(session.status)} ${session.workingDir}`
+      );
+    }
+  }
+
+  if (options.includeStored) {
+    const stoppedSessions = Object.values(stored).filter((s) => s.status === 'stopped');
+    if (stoppedSessions.length > 0) {
+      console.log(heading('Stopped Sessions:'));
+      for (const session of stoppedSessions) {
+        const name = session.name ? ` (${session.name})` : '';
+        console.log(
+          `  ${palette.muted(session.id.slice(0, 8))} ${palette.muted('stopped')}${name} ${session.workingDir}`
+        );
+      }
+    }
+
+    // Sessions the web server owns: this process has no PTY for them, so they
+    // only exist in the shared state file.
+    const activeSessions = Object.values(stored).filter((s) => s.status !== 'stopped');
+    if (sessions.length === 0 && activeSessions.length > 0) {
+      console.log(heading('Active Sessions (from web server):'));
+      for (const session of activeSessions) {
+        const name = session.name ? ` (${session.name})` : '';
+        const mode = session.mode === 'shell' ? palette.muted(' [shell]') : '';
+        const cost = session.totalCost ? palette.muted(` $${session.totalCost.toFixed(4)}`) : '';
+        console.log(
+          `  ${palette.info(session.id.slice(0, 8))} ${sessionStatusLabel(session.status)}${name}${mode}${cost} ${session.workingDir}`
+        );
+      }
+    }
+  }
+  console.log('');
+}
+
 sessionCmd
   .command('list')
   .alias('ls')
   .description('List all sessions')
-  .action(() => {
-    const manager = getSessionManager();
-    const sessions = manager.getAllSessions();
-    const stored = manager.getStoredSessions();
-
-    if (sessions.length === 0 && Object.keys(stored).length === 0) {
-      console.log(chalk.yellow('No sessions found'));
-      return;
-    }
-
-    console.log(chalk.bold('\nActive Sessions:'));
-    if (sessions.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const session of sessions) {
-        const status =
-          session.status === 'idle'
-            ? chalk.green('idle')
-            : session.status === 'busy'
-              ? chalk.yellow('busy')
-              : chalk.red(session.status);
-        console.log(`  ${chalk.cyan(session.id.slice(0, 8))} ${status} ${session.workingDir}`);
-      }
-    }
-
-    const stoppedSessions = Object.values(stored).filter((s) => s.status === 'stopped');
-    if (stoppedSessions.length > 0) {
-      console.log(chalk.bold('\nStopped Sessions:'));
-      for (const session of stoppedSessions) {
-        const name = session.name ? ` (${session.name})` : '';
-        console.log(`  ${chalk.gray(session.id.slice(0, 8))} ${chalk.gray('stopped')}${name} ${session.workingDir}`);
-      }
-    }
-
-    // Show active sessions from state (when web server manages them)
-    const activeSessions = Object.values(stored).filter((s) => s.status !== 'stopped');
-    if (sessions.length === 0 && activeSessions.length > 0) {
-      console.log(chalk.bold('\nActive Sessions (from web server):'));
-      for (const session of activeSessions) {
-        const status =
-          session.status === 'idle'
-            ? chalk.green('idle')
-            : session.status === 'busy'
-              ? chalk.yellow('busy')
-              : chalk.red(session.status);
-        const name = session.name ? ` (${session.name})` : '';
-        const mode = session.mode === 'shell' ? chalk.gray(' [shell]') : '';
-        const cost = session.totalCost ? chalk.gray(` $${session.totalCost.toFixed(4)}`) : '';
-        console.log(`  ${chalk.cyan(session.id.slice(0, 8))} ${status}${name}${mode}${cost} ${session.workingDir}`);
-      }
-    }
-    console.log('');
-  });
+  .action(() => printSessionList({ includeStored: true }));
 
 sessionCmd
   .command('logs <id>')
@@ -342,12 +358,12 @@ sessionCmd
     const output = options.errors ? manager.getSessionError(id) : manager.getSessionOutput(id);
 
     if (output === null) {
-      console.log(chalk.yellow(`Session ${id} not found or not active`));
+      console.log(palette.warn(`Session ${id} not found or not active`));
       return;
     }
 
     if (output === '') {
-      console.log(chalk.gray('(no output)'));
+      console.log(palette.muted('(no output)'));
       return;
     }
 
@@ -374,7 +390,7 @@ taskCmd
       completionPhrase: options.completion,
       timeoutMs: options.timeout ? parseInt(options.timeout, 10) : undefined,
     });
-    console.log(chalk.green(`✓ Task added: ${task.id}`));
+    console.log(palette.ok(`✓ Task added: ${task.id}`));
     console.log(`  Prompt: ${prompt.slice(0, 50)}${prompt.length > 50 ? '...' : ''}`);
     console.log(`  Priority: ${task.priority}`);
   });
@@ -393,26 +409,28 @@ taskCmd
     }
 
     if (tasks.length === 0) {
-      console.log(chalk.yellow('No tasks found'));
+      console.log(palette.warn('No tasks found'));
       return;
     }
 
     const statusColors = {
-      pending: chalk.gray,
-      running: chalk.yellow,
-      completed: chalk.green,
-      failed: chalk.red,
+      pending: palette.muted,
+      running: palette.warn,
+      completed: palette.ok,
+      failed: palette.err,
     };
 
-    console.log(chalk.bold('\nTasks:'));
+    console.log(palette.emph('\nTasks:'));
     for (const task of tasks) {
       const color = statusColors[task.status];
       const prompt = task.prompt.slice(0, 40) + (task.prompt.length > 40 ? '...' : '');
-      console.log(`  ${chalk.cyan(task.id.slice(0, 8))} ${color(task.status.padEnd(10))} [${task.priority}] ${prompt}`);
+      console.log(
+        `  ${palette.info(task.id.slice(0, 8))} ${color(task.status.padEnd(10))} [${task.priority}] ${prompt}`
+      );
     }
 
     const counts = queue.getCount();
-    console.log(chalk.bold('\nSummary:'));
+    console.log(palette.emph('\nSummary:'));
     console.log(
       `  Pending: ${counts.pending}, Running: ${counts.running}, Completed: ${counts.completed}, Failed: ${counts.failed}`
     );
@@ -427,11 +445,11 @@ taskCmd
     const task = queue.getTask(id);
 
     if (!task) {
-      console.log(chalk.red(`Task ${id} not found`));
+      console.log(palette.err(`Task ${id} not found`));
       return;
     }
 
-    console.log(chalk.bold('\nTask Details:'));
+    console.log(palette.emph('\nTask Details:'));
     console.log(`  ID: ${task.id}`);
     console.log(`  Status: ${task.status}`);
     console.log(`  Priority: ${task.priority}`);
@@ -441,10 +459,10 @@ taskCmd
       console.log(`  Session: ${task.assignedSessionId}`);
     }
     if (task.error) {
-      console.log(`  Error: ${chalk.red(task.error)}`);
+      console.log(`  Error: ${palette.err(task.error)}`);
     }
     if (task.output) {
-      console.log(chalk.bold('\nOutput:'));
+      console.log(palette.emph('\nOutput:'));
       console.log(task.output.slice(0, 500) + (task.output.length > 500 ? '...' : ''));
     }
     console.log('');
@@ -457,9 +475,9 @@ taskCmd
   .action((id) => {
     const queue = getTaskQueue();
     if (queue.removeTask(id)) {
-      console.log(chalk.green(`✓ Task removed: ${id}`));
+      console.log(palette.ok(`✓ Task removed: ${id}`));
     } else {
-      console.log(chalk.red(`Task ${id} not found`));
+      console.log(palette.err(`Task ${id} not found`));
     }
   });
 
@@ -474,13 +492,13 @@ taskCmd
 
     if (options.all) {
       count = queue.clearAll();
-      console.log(chalk.green(`✓ Cleared ${count} tasks`));
+      console.log(palette.ok(`✓ Cleared ${count} tasks`));
     } else if (options.failed) {
       count = queue.clearFailed();
-      console.log(chalk.green(`✓ Cleared ${count} failed tasks`));
+      console.log(palette.ok(`✓ Cleared ${count} failed tasks`));
     } else {
       count = queue.clearCompleted();
-      console.log(chalk.green(`✓ Cleared ${count} completed tasks`));
+      console.log(palette.ok(`✓ Cleared ${count} completed tasks`));
     }
   });
 
@@ -503,38 +521,38 @@ ralphCmd
     }
 
     if (loop.isRunning()) {
-      console.log(chalk.yellow('Ralph loop is already running'));
+      console.log(palette.warn('Ralph loop is already running'));
       return;
     }
 
     loop.on('taskAssigned', (taskId, sessionId) => {
-      console.log(chalk.cyan(`→ Task ${taskId.slice(0, 8)} assigned to session ${sessionId.slice(0, 8)}`));
+      console.log(palette.info(`→ Task ${taskId.slice(0, 8)} assigned to session ${sessionId.slice(0, 8)}`));
     });
 
     loop.on('taskCompleted', (taskId) => {
-      console.log(chalk.green(`✓ Task ${taskId.slice(0, 8)} completed`));
+      console.log(palette.ok(`✓ Task ${taskId.slice(0, 8)} completed`));
     });
 
     loop.on('taskFailed', (taskId, error) => {
-      console.log(chalk.red(`✗ Task ${taskId.slice(0, 8)} failed: ${error}`));
+      console.log(palette.err(`✗ Task ${taskId.slice(0, 8)} failed: ${error}`));
     });
 
     loop.on('stopped', () => {
-      console.log(chalk.yellow('\nRalph loop stopped'));
+      console.log(palette.warn('\nRalph loop stopped'));
       printStats(loop.getStats());
       process.exit(0);
     });
 
     await loop.start();
-    console.log(chalk.green('✓ Ralph loop started'));
+    console.log(palette.ok('✓ Ralph loop started'));
     if (options.minHours) {
       console.log(`  Minimum duration: ${options.minHours} hours`);
     }
-    console.log(chalk.gray('  Press Ctrl+C to stop\n'));
+    console.log(palette.muted('  Press Ctrl+C to stop\n'));
 
     // Keep process running
     process.on('SIGINT', () => {
-      console.log(chalk.yellow('\nStopping Ralph loop...'));
+      console.log(palette.warn('\nStopping Ralph loop...'));
       loop.stop();
     });
   });
@@ -545,11 +563,11 @@ ralphCmd
   .action(() => {
     const loop = getRalphLoop();
     if (!loop.isRunning()) {
-      console.log(chalk.yellow('Ralph loop is not running'));
+      console.log(palette.warn('Ralph loop is not running'));
       return;
     }
     loop.stop();
-    console.log(chalk.green('✓ Ralph loop stopped'));
+    console.log(palette.ok('✓ Ralph loop stopped'));
   });
 
 ralphCmd
@@ -562,9 +580,10 @@ ralphCmd
   });
 
 function printStats(stats: ReturnType<ReturnType<typeof getRalphLoop>['getStats']>) {
-  const statusColor = stats.status === 'running' ? chalk.green : stats.status === 'paused' ? chalk.yellow : chalk.gray;
+  const statusColor =
+    stats.status === 'running' ? palette.ok : stats.status === 'paused' ? palette.warn : palette.muted;
 
-  console.log(chalk.bold('\nRalph Loop Status:'));
+  console.log(palette.emph('\nRalph Loop Status:'));
   console.log(`  Status: ${statusColor(stats.status)}`);
   console.log(`  Elapsed: ${stats.elapsedHours.toFixed(2)} hours`);
   if (stats.minDurationMs) {
@@ -574,14 +593,14 @@ function printStats(stats: ReturnType<ReturnType<typeof getRalphLoop>['getStats'
     );
   }
 
-  console.log(chalk.bold('\nTasks:'));
+  console.log(palette.emph('\nTasks:'));
   console.log(`  Pending: ${stats.pending}`);
   console.log(`  Running: ${stats.running}`);
   console.log(`  Completed: ${stats.completed} (${stats.tasksCompleted} this session)`);
   console.log(`  Failed: ${stats.failed}`);
   console.log(`  Generated: ${stats.tasksGenerated}`);
 
-  console.log(chalk.bold('\nSessions:'));
+  console.log(palette.emph('\nSessions:'));
   console.log(`  Active: ${stats.activeSessions}`);
   console.log(`  Idle: ${stats.idleSessions}`);
   console.log(`  Busy: ${stats.busySessions}`);
@@ -695,20 +714,20 @@ program
       }
     }
 
-    console.log(chalk.bold('\nCodeman Status'));
-    console.log('─'.repeat(40));
+    console.log(heading('Codeman Status'));
+    console.log(rule(40));
 
-    console.log(chalk.bold('\nWeb Server:'));
+    console.log(heading('Web Server:'));
     if (probe.reachable) {
       const version = probe.version ? ` (v${probe.version})` : '';
-      console.log(`  Status: ${chalk.green('running')}${version} at ${probe.url}`);
+      console.log(kv('Status', `${palette.ok('running')}${version} at ${probe.url}`));
       if (probe.authRequired) {
-        console.log(chalk.gray('  (answers 401: set CODEMAN_PASSWORD/CODEMAN_USERNAME to see session details)'));
+        console.log(palette.muted('  (answers 401: set CODEMAN_PASSWORD/CODEMAN_USERNAME to see session details)'));
       }
     } else {
-      console.log(`  Status: ${chalk.red('not reachable')} at ${candidates.join(' or ')}`);
+      console.log(kv('Status', `${palette.err('not reachable')} at ${candidates.join(' or ')}`));
       console.log(
-        chalk.gray('  (start it with `codeman web`, or check your service: systemctl --user status codeman-web)')
+        palette.muted('  (start it with `codeman web`, or check your service: systemctl --user status codeman-web)')
       );
     }
 
@@ -716,26 +735,26 @@ program
     // as such, so the numbers are never silently a different thing.
     if (probe.sessions) {
       const live = probe.sessions;
-      console.log(chalk.bold('\nSessions (live, from the server):'));
-      console.log(`  Total: ${live.length}`);
-      console.log(`  Idle: ${live.filter((s) => s.status === 'idle').length}`);
-      console.log(`  Busy: ${live.filter((s) => s.status === 'busy').length}`);
+      console.log(heading('Sessions (live, from the server):'));
+      console.log(kv('Total', String(live.length)));
+      console.log(kv('Idle', String(live.filter((s) => s.status === 'idle').length)));
+      console.log(kv('Busy', String(live.filter((s) => s.status === 'busy').length)));
     } else {
       const manager = getSessionManager();
       const storedValues = Object.values(manager.getStoredSessions());
-      console.log(chalk.bold('\nSessions (from saved state):'));
-      console.log(`  Active: ${storedValues.filter((s) => s.status !== 'stopped').length}`);
-      console.log(`  Idle: ${storedValues.filter((s) => s.status === 'idle').length}`);
-      console.log(`  Busy: ${storedValues.filter((s) => s.status === 'busy').length}`);
+      console.log(heading('Sessions (from saved state):'));
+      console.log(kv('Active', String(storedValues.filter((s) => s.status !== 'stopped').length)));
+      console.log(kv('Idle', String(storedValues.filter((s) => s.status === 'idle').length)));
+      console.log(kv('Busy', String(storedValues.filter((s) => s.status === 'busy').length)));
     }
 
     const taskCounts = getTaskQueue().getCount();
-    console.log(chalk.bold('\nTasks:'));
-    console.log(`  Total: ${taskCounts.total}`);
-    console.log(`  Pending: ${taskCounts.pending}`);
-    console.log(`  Running: ${taskCounts.running}`);
-    console.log(`  Completed: ${taskCounts.completed}`);
-    console.log(`  Failed: ${taskCounts.failed}`);
+    console.log(heading('Tasks:'));
+    console.log(kv('Total', String(taskCounts.total)));
+    console.log(kv('Pending', String(taskCounts.pending)));
+    console.log(kv('Running', String(taskCounts.running)));
+    console.log(kv('Completed', String(taskCounts.completed)));
+    console.log(kv('Failed', String(taskCounts.failed)));
     console.log('');
   });
 
@@ -745,9 +764,17 @@ program
   .option('-f, --force', 'Skip confirmation')
   .action(async (options) => {
     if (!options.force) {
-      console.log(chalk.yellow('This will stop all sessions and clear all state.'));
-      console.log(chalk.yellow('Use --force to confirm.'));
-      return;
+      console.log(palette.warn('This will stop all sessions and clear all state.'));
+      // Non-interactive callers keep the old refusal: a script piping into the
+      // CLI must never be able to reset state by hanging on an unseen question.
+      if (!isInteractive()) {
+        console.log(palette.warn('Use --force to confirm.'));
+        return;
+      }
+      if (!(await confirm('Reset all Codeman state?'))) {
+        console.log(palette.muted('○ Cancelled, nothing was changed'));
+        return;
+      }
     }
 
     const manager = getSessionManager();
@@ -756,7 +783,7 @@ program
     await manager.stopAllSessions();
     store.reset();
 
-    console.log(chalk.green('✓ All state reset'));
+    console.log(palette.ok('✓ All state reset'));
   });
 
 // Shorthand commands at root level
@@ -767,38 +794,45 @@ program
   .action(async (options) => {
     const manager = getSessionManager();
     const session = await manager.createSession(options.dir);
-    console.log(chalk.green(`✓ Session started: ${session.id}`));
+    console.log(palette.ok(`✓ Session started: ${session.id}`));
   });
 
 program
   .command('list')
   .alias('ls')
-  .description('List all sessions (shorthand)')
-  .action(() => {
-    const manager = getSessionManager();
-    const sessions = manager.getAllSessions();
-    const stored = manager.getStoredSessions();
+  .description('List active sessions (shorthand; `codeman session list` also shows stopped ones)')
+  .action(() => printSessionList({ includeStored: false }));
 
-    if (sessions.length === 0 && Object.keys(stored).length === 0) {
-      console.log(chalk.yellow('No sessions found'));
+// ============ TUI ============
+
+program
+  .command('tui')
+  .argument('[n]', 'attach straight to the nth session of `codeman tui --list`')
+  .description('Terminal dashboard for your sessions (the web UI remains the primary surface)')
+  .option('-l, --list', 'Print the numbered session list and exit, instead of opening the dashboard')
+  .action(async (position: string | undefined, options: { list?: boolean }) => {
+    // Imported here, not at the top: the dashboard pulls in the whole TUI core,
+    // and every other command would pay for it at startup.
+    const { runTui, runTuiAttach, runTuiList } = await import('./tui/tui-app.js');
+
+    if (options.list) {
+      process.exitCode = await runTuiList();
       return;
     }
-
-    console.log(chalk.bold('\nActive Sessions:'));
-    if (sessions.length === 0) {
-      console.log('  (none)');
-    } else {
-      for (const session of sessions) {
-        const status =
-          session.status === 'idle'
-            ? chalk.green('idle')
-            : session.status === 'busy'
-              ? chalk.yellow('busy')
-              : chalk.red(session.status);
-        console.log(`  ${chalk.cyan(session.id.slice(0, 8))} ${status} ${session.workingDir}`);
+    if (position !== undefined) {
+      const n = Number.parseInt(position, 10);
+      if (!Number.isSafeInteger(n) || n < 1) {
+        console.error(palette.err(`"${position}" is not a session number.`));
+        console.error(`Run ${palette.info('codeman tui --list')} to see them.`);
+        process.exitCode = 1;
+        return;
       }
+      process.exitCode = await runTuiAttach(n);
+      return;
     }
-    console.log('');
+    // The dashboard owns the terminal until it quits; exiting explicitly keeps a
+    // stray handle (a socket mid-close) from stranding the user's shell.
+    process.exit(await runTui());
   });
 
 // ============ Web / daemon / service Commands ============
@@ -831,7 +865,7 @@ function toWebLaunchOptions(options: {
 }): WebLaunchOptions {
   const port = parseInt(options.port, 10);
   if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    console.error(chalk.red(`✗ Invalid port: ${options.port}`));
+    console.error(palette.err(`✗ Invalid port: ${options.port}`));
     process.exit(1);
   }
   return {
@@ -852,11 +886,11 @@ function warnIfUnauthenticatedNetwork(launch: WebLaunchOptions): void {
   if (isLoopbackBindHost(launch.host)) return;
   if (isUnauthenticatedNetworkAcknowledged(launch.allowUnauthenticatedNetwork)) return;
   console.log(
-    chalk.yellow(
+    palette.warn(
       `⚠ Binding ${launch.host} without CODEMAN_PASSWORD: anyone who can reach this port gets terminal control.`
     )
   );
-  console.log(chalk.yellow('  Set CODEMAN_PASSWORD, or bind 127.0.0.1 and front it with tailscale serve.'));
+  console.log(palette.warn('  Set CODEMAN_PASSWORD, or bind 127.0.0.1 and front it with tailscale serve.'));
 }
 
 // Web interface command
@@ -872,17 +906,18 @@ webCmd.action(async (options) => {
   const launch = toWebLaunchOptions(options);
 
   if (options.stop) {
-    const result = await stopDaemon(launch);
+    // stopDaemon waits for the process to actually exit (up to 15s).
+    const result = await withSpinner('Stopping Codeman...', () => stopDaemon(launch));
     if (result.ok && result.reason === 'not-running') {
-      console.log(chalk.gray(`○ ${result.message}`));
+      console.log(palette.muted(`○ ${result.message}`));
       return;
     }
     if (result.ok) {
-      console.log(chalk.green(`✓ ${result.message ?? `Stopped Codeman (pid ${result.pid})`}`));
-      console.log(chalk.gray('  Your agents keep running in tmux.'));
+      console.log(palette.ok(`✓ ${result.message ?? `Stopped Codeman (pid ${result.pid})`}`));
+      console.log(palette.muted('  Your agents keep running in tmux.'));
       return;
     }
-    console.error(chalk.red(`✗ ${result.message ?? 'Could not stop the server'}`));
+    console.error(palette.err(`✗ ${result.message ?? 'Could not stop the server'}`));
     process.exit(1);
   }
 
@@ -890,31 +925,33 @@ webCmd.action(async (options) => {
     const status = await daemonStatus(launch);
     if (status.responding) {
       const version = status.version ? ` (v${status.version})` : '';
-      console.log(chalk.green(`✓ Responding at ${status.url}${version}`));
+      console.log(palette.ok(`✓ Responding at ${status.url}${version}`));
     } else {
-      console.log(chalk.yellow(`○ Nothing answering at ${status.url}`));
+      console.log(palette.warn(`○ Nothing answering at ${status.url}`));
     }
-    console.log(`  Daemon pid:  ${status.running ? chalk.green(String(status.pid)) : chalk.gray('not running')}`);
-    console.log(chalk.gray(`  Pidfile:     ${status.pidFile}`));
-    console.log(chalk.gray(`  Log:         ${status.logPath}`));
+    console.log(kv('Daemon pid', status.running ? palette.ok(String(status.pid)) : palette.muted('not running'), 11));
+    console.log(palette.muted(kv('Pidfile', status.pidFile, 11)));
+    console.log(palette.muted(kv('Log', status.logPath, 11)));
     if (!status.running && status.responding) {
-      console.log(chalk.gray('  (running, but not started with --daemon: probably a service or a foreground run)'));
+      console.log(palette.muted('  (running, but not started with --daemon: probably a service or a foreground run)'));
     }
     return;
   }
 
   if (options.daemon) {
     warnIfUnauthenticatedNetwork(launch);
-    console.log(chalk.cyan('Starting Codeman in the background...'));
-    const result = await startDaemon(launch);
+    // The start polls /api/status for up to 30s; without this the shell just sits there.
+    const result = await withSpinner('Starting Codeman in the background, waiting for it to answer...', () =>
+      startDaemon(launch)
+    );
     if (result.ok) {
-      console.log(chalk.green(`\n✓ Codeman is running at ${result.url} (pid ${result.pid})`));
-      console.log(chalk.gray(`  Logs: ${result.logPath}`));
-      console.log(chalk.gray('  Stop it with: codeman web --stop'));
-      console.log(chalk.gray('  Want it back after a reboot? codeman service install'));
+      console.log(palette.ok(`\n✓ Codeman is running at ${result.url} (pid ${result.pid})`));
+      console.log(palette.muted(`  Logs: ${result.logPath}`));
+      console.log(palette.muted('  Stop it with: codeman web --stop'));
+      console.log(palette.muted('  Want it back after a reboot? codeman service install'));
       return;
     }
-    console.error(chalk.red(`\n✗ ${result.message ?? 'Failed to start'}`));
+    console.error(palette.err(`\n✗ ${result.message ?? 'Failed to start'}`));
     process.exit(1);
   }
 
@@ -924,29 +961,29 @@ webCmd.action(async (options) => {
   const https = launch.https;
   const titleHostname = options.titleHostname;
   const allowUnauthenticatedNetwork = launch.allowUnauthenticatedNetwork ?? false;
-  const protocol = https ? 'https' : 'http';
   const displayHost = host === '0.0.0.0' ? 'localhost' : host;
 
-  console.log(chalk.cyan(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`));
+  console.log(palette.info(`Starting Codeman web interface on ${displayHost}:${port}${https ? ' (HTTPS)' : ''}...`));
 
   try {
+    // The server prints its own "running at" line (it also covers the daemon and
+    // service launch paths), so this one used to be a duplicate of it.
     const server = await startWebServer(port, https, false, host, titleHostname, allowUnauthenticatedNetwork);
-    console.log(chalk.green(`\n✓ Web interface running at ${protocol}://${displayHost}:${port}`));
     if (https) {
-      console.log(chalk.yellow('  Note: Accept the self-signed certificate in your browser on first visit'));
+      console.log(palette.warn('  Note: Accept the self-signed certificate in your browser on first visit'));
     }
-    console.log(chalk.gray('  Press Ctrl+C to stop\n'));
+    console.log(palette.muted('  Press Ctrl+C to stop\n'));
 
     // Graceful shutdown handler — flush state and clean up on SIGTERM/SIGINT
     let shuttingDown = false;
     const shutdown = async (signal: string) => {
       if (shuttingDown) return;
       shuttingDown = true;
-      console.log(chalk.yellow(`\n${signal} received, shutting down gracefully...`));
+      console.log(palette.warn(`\n${signal} received, shutting down gracefully...`));
       try {
         await server.stop();
       } catch (err) {
-        console.error(chalk.red(`Error during shutdown: ${getErrorMessage(err)}`));
+        console.error(palette.err(`Error during shutdown: ${getErrorMessage(err)}`));
       }
       process.exit(0);
     };
@@ -954,7 +991,7 @@ webCmd.action(async (options) => {
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGHUP', () => shutdown('SIGHUP'));
   } catch (err) {
-    console.error(chalk.red(`✗ Failed to start web server: ${getErrorMessage(err)}`));
+    console.error(palette.err(`✗ Failed to start web server: ${getErrorMessage(err)}`));
     process.exit(1);
   }
 });
@@ -970,20 +1007,23 @@ addWebLaunchOptions(
 ).action(async (options) => {
   const launch = toWebLaunchOptions(options);
   warnIfUnauthenticatedNetwork(launch);
-  console.log(chalk.cyan('Installing the Codeman service...'));
 
-  const result = await installService(launch);
-  for (const warning of result.warnings ?? []) console.log(chalk.yellow(`⚠ ${warning}`));
+  // Install polls the new unit's /api/status for up to 30s before it can honestly
+  // report success, so the wait needs a visible heartbeat.
+  const result = await withSpinner('Installing the Codeman service, waiting for it to answer...', () =>
+    installService(launch)
+  );
+  for (const warning of result.warnings ?? []) console.log(palette.warn(`⚠ ${warning}`));
 
   if (!result.ok) {
-    console.error(chalk.red(`✗ ${result.message}`));
+    console.error(palette.err(`✗ ${result.message}`));
     process.exit(1);
   }
-  console.log(chalk.green(`✓ ${result.message}`));
-  console.log(chalk.gray(`  Unit: ${result.unitPath}`));
+  console.log(palette.ok(`✓ ${result.message}`));
+  console.log(palette.muted(`  Unit: ${result.unitPath}`));
   if (process.env.CODEMAN_PASSWORD) {
     console.log(
-      chalk.yellow(
+      palette.warn(
         '  Note: CODEMAN_PASSWORD was NOT copied into the unit file. Add it there yourself if the service needs auth.'
       )
     );
@@ -996,10 +1036,10 @@ serviceCmd
   .action(() => {
     const result = uninstallService();
     if (!result.ok) {
-      console.error(chalk.red(`✗ ${result.message}`));
+      console.error(palette.err(`✗ ${result.message}`));
       process.exit(1);
     }
-    console.log(chalk.green(`✓ ${result.message}`));
+    console.log(palette.ok(`✓ ${result.message}`));
   });
 
 addWebLaunchOptions(
@@ -1007,15 +1047,15 @@ addWebLaunchOptions(
 ).action(async (options) => {
   const status = await serviceStatus(toWebLaunchOptions(options));
   if (!status.kind) {
-    console.log(chalk.yellow(`No supported supervisor on ${process.platform}. Use \`codeman web -d\` instead.`));
+    console.log(palette.warn(`No supported supervisor on ${process.platform}. Use \`codeman web -d\` instead.`));
     return;
   }
   console.log(`  Supervisor: ${status.kind} (${status.name})`);
-  console.log(`  Unit file:  ${status.installed ? chalk.green(status.unitPath) : chalk.gray('not installed')}`);
-  console.log(`  Loaded:     ${status.loaded ? chalk.green('yes') : chalk.gray('no')}`);
+  console.log(`  Unit file:  ${status.installed ? palette.ok(status.unitPath) : palette.muted('not installed')}`);
+  console.log(`  Loaded:     ${status.loaded ? palette.ok('yes') : palette.muted('no')}`);
   const version = status.version ? ` (v${status.version})` : '';
   console.log(
-    `  Responding: ${status.responding ? chalk.green(`yes at ${status.url}${version}`) : chalk.gray(`no at ${status.url}`)}`
+    `  Responding: ${status.responding ? palette.ok(`yes at ${status.url}${version}`) : palette.muted(`no at ${status.url}`)}`
   );
 });
 
@@ -1085,7 +1125,7 @@ usersCmd
   .action(async (name, options) => {
     const { createUser, isValidUsername } = await import('./user-store.js');
     if (!isValidUsername(name)) {
-      console.error(chalk.red('✗ Username must be lowercase, start alphanumeric, 2-32 chars ([a-z0-9_-])'));
+      console.error(palette.err('✗ Username must be lowercase, start alphanumeric, 2-32 chars ([a-z0-9_-])'));
       process.exit(1);
     }
     try {
@@ -1096,18 +1136,18 @@ usersCmd
         password = await promptHiddenPassword('New password: ');
         const confirm = await promptHiddenPassword('Confirm password: ');
         if (password !== confirm) {
-          console.error(chalk.red('✗ Passwords do not match'));
+          console.error(palette.err('✗ Passwords do not match'));
           process.exit(1);
         }
       }
       if (!password || password.length < 8) {
-        console.error(chalk.red('✗ Password must be at least 8 characters'));
+        console.error(palette.err('✗ Password must be at least 8 characters'));
         process.exit(1);
       }
       const user = await createUser({ username: name, role: options.admin ? 'admin' : 'user', password });
-      console.log(chalk.green(`✓ Created ${user.role} "${user.username}"`));
+      console.log(palette.ok(`✓ Created ${user.role} "${user.username}"`));
     } catch (err) {
-      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -1126,14 +1166,14 @@ usersCmd
         password = await promptHiddenPassword('New password: ');
         const confirm = await promptHiddenPassword('Confirm password: ');
         if (password !== confirm) {
-          console.error(chalk.red('✗ Passwords do not match'));
+          console.error(palette.err('✗ Passwords do not match'));
           process.exit(1);
         }
       }
       await setPassword(name, password, { mustChangePassword: false });
-      console.log(chalk.green(`✓ Password updated for "${name}"`));
+      console.log(palette.ok(`✓ Password updated for "${name}"`));
     } catch (err) {
-      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
@@ -1146,17 +1186,17 @@ usersCmd
     const { readUsers } = await import('./user-store.js');
     const users = await readUsers(true);
     if (users.length === 0) {
-      console.log(chalk.yellow('No users defined (run: codeman users add <name> --admin)'));
+      console.log(palette.warn('No users defined (run: codeman users add <name> --admin)'));
       return;
     }
-    console.log(chalk.bold('\nUsers:'));
+    console.log(palette.emph('\nUsers:'));
     for (const u of users) {
-      const role = u.role === 'admin' ? chalk.magenta('admin') : chalk.cyan('user ');
-      const state = u.disabled ? chalk.red('disabled') : chalk.green('enabled ');
+      const role = u.role === 'admin' ? palette.accent('admin') : palette.info('user ');
+      const state = u.disabled ? palette.err('disabled') : palette.ok('enabled ');
       const flags = [u.mustChangePassword ? 'must-change-pw' : '', u.canBypassPermissions ? 'can-bypass' : '']
         .filter(Boolean)
         .join(' ');
-      console.log(`  ${role} ${state} ${u.username}${flags ? chalk.gray(`  [${flags}]`) : ''}`);
+      console.log(`  ${role} ${state} ${u.username}${flags ? palette.muted(`  [${flags}]`) : ''}`);
     }
     console.log('');
   });
@@ -1171,16 +1211,43 @@ usersCmd
       await deleteUser(name);
       if (options.deleteSpace) {
         await deleteUserSpace(name);
-        console.log(chalk.green(`✓ Deleted user "${name}" and their space`));
+        console.log(palette.ok(`✓ Deleted user "${name}" and their space`));
       } else {
-        console.log(chalk.green(`✓ Deleted user "${name}" (space left on disk)`));
+        console.log(palette.ok(`✓ Deleted user "${name}" (space left on disk)`));
       }
     } catch (err) {
-      console.error(chalk.red(`✗ ${getErrorMessage(err)}`));
+      console.error(palette.err(`✗ ${getErrorMessage(err)}`));
       process.exit(1);
     }
   });
 
+/**
+ * Missing REQUIRED tools are failures; a missing optional one or a skipped check
+ * is just absence, so it stays muted rather than shouting red at everyone
+ * without LibreOffice installed.
+ */
+function dependencyTone(result: ToolResult): Tone {
+  if (result.status === 'ok') return 'ok';
+  if (result.status === 'skipped') return 'idle';
+  return result.required ? 'err' : 'idle';
+}
+
+/**
+ * The colorize hook `dependency-report.ts` was written for. Versions stay in the
+ * default color (they are data, not a verdict); everything that IS a verdict is
+ * painted, and the supporting detail is muted so the glyph column reads first.
+ */
+const DOCTOR_STYLE: ReportStyle = {
+  title: (text) => palette.emph(text),
+  heading: (text) => palette.emph(palette.info(text)),
+  glyph: (result, glyph) => tint(dependencyTone(result), glyph),
+  label: (text) => text,
+  status: (result, text) => (result.status === 'ok' ? text : tint(dependencyTone(result), text)),
+  path: (text) => palette.muted(text),
+  meta: (text) => palette.muted(text),
+  summary: (text) => palette.emph(text),
+};
+
 program
   .command('doctor')
   .alias('check-deps')
@@ -1204,9 +1271,10 @@ program
     const results = checkAll(registry, host);
 
     if (options.json) {
+      // Raw JSON, never styled: this output is parsed, not read.
       console.log(JSON.stringify(renderJson(results, host.environment), null, 2));
     } else {
-      console.log(renderTable(results, host.environment));
+      console.log(renderTable(results, host.environment, DOCTOR_STYLE));
     }
     process.exit(computeExitCode(results));
   });

src/config/cases-dir.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Where case (project) folders live.
+ *
+ * Deliberately NOT instance-scoped, unlike `dataPath()`: `~/codeman-cases` is
+ * shared by every Codeman on the machine, the same way `~/codeman-users/<u>`
+ * user spaces are, so a beta instance sees the same projects as prod.
+ *
+ * `CODEMAN_CASES_PATH` overrides the location. Docker Compose deployments set
+ * it to a host-absolute bind mount so a Docker case's workspace resolves to the
+ * SAME absolute path inside Codeman and on the host daemon that mounts it.
+ *
+ * ⚠️ **One resolver, every caller.** This started life as three hardcoded
+ * `join(homedir(), 'codeman-cases')` copies. When only the web server's copy
+ * learned the override, `codeman skill install --case <name>` still looked in
+ * the home default and reported "Case not found" on exactly the deployment the
+ * override exists for. A new cases-dir consumer imports this; it does not
+ * rebuild the path.
+ *
+ * (`state-store.ts` keeps its own literal on purpose: that one migrates the
+ * historical `~/claudeman-cases` directory to `~/codeman-cases` by name, and is
+ * about the old default location rather than the active one.)
+ *
+ * @module config/cases-dir
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Absolute path to the shared cases directory. */
+export function getCasesDir(): string {
+  return process.env.CODEMAN_CASES_PATH || join(homedir(), 'codeman-cases');
+}
+
+/** Absolute path to one case folder inside it. */
+export function casePath(name: string): string {
+  return join(getCasesDir(), name);
+}

src/config/dependency-registry.ts

@@ -8,6 +8,9 @@
  */
 
 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';
+import { OMP_VERSION_REGEX } from '../utils/omp-cli-resolver.js';
 
 export type ProbeEnvironment = 'linux' | 'darwin' | 'win32' | 'wsl';
 
@@ -139,6 +142,79 @@ 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: 'omp',
+    label: 'OMP CLI',
+    category: 'core',
+    required: false,
+    usedBy: ['OMP sessions'],
+    // Same version-match discipline as pi: `omp` is a short generic name, so a
+    // `which omp` hit alone is not the coding agent. Both sides share
+    // OMP_VERSION_REGEX, so the doctor and the run mode cannot drift into telling
+    // the user opposite things about the same binary.
+    resolvers: [
+      {
+        match: ALL,
+        resolver: {
+          kind: 'path',
+          bins: ['omp'],
+          versionArg: '--version',
+          versionRegex: OMP_VERSION_REGEX,
+          requireVersionMatch: true,
+        },
+      },
+    ],
+    installHint: { linux: 'curl -fsSL https://omp.sh/install | sh', darwin: 'brew install can1357/tap/omp' },
+  },
   {
     id: 'libreoffice',
     label: 'LibreOffice',

src/config/instance.ts

@@ -40,6 +40,21 @@ const INSTANCE_SUFFIX = CODEMAN_INSTANCE ? `-${CODEMAN_INSTANCE}` : '';
 /** Default tmux socket for this instance. `CODEMAN_TMUX_SOCKET` still overrides. */
 export const DEFAULT_TMUX_SOCKET = `codeman${INSTANCE_SUFFIX}`;
 
+/** Characters tmux accepts in a `-L` socket name. */
+export const SAFE_TMUX_SOCKET_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+
+/**
+ * This instance's tmux socket: the `CODEMAN_TMUX_SOCKET` override when it is a
+ * safe name, else the instance default. Every process that runs `tmux -L` has
+ * to resolve it through here (the server via TmuxManager, the TUI for its
+ * degraded-mode listing), or a beta instance ends up driving prod's sessions.
+ */
+export function resolveTmuxSocketName(): string {
+  const raw = process.env.CODEMAN_TMUX_SOCKET;
+  if (raw !== undefined && SAFE_TMUX_SOCKET_PATTERN.test(raw)) return raw;
+  return DEFAULT_TMUX_SOCKET;
+}
+
 let _ensured = false;
 
 /**

src/config/terminal-history.ts

@@ -8,7 +8,8 @@
  * src/web/public/constants.js and deliberately stays at 50k — 100k xterm lines per tab
  * is a mobile-memory hazard — so DEFAULT_TERMINAL_SCROLLBACK_LINES stays 50,000 to match.
  * The terminalScrollbackLines/terminalBufferMaxBytes/terminalBufferTrimBytes settings keys
- * remain schema-validated but inert (a follow-up wires them); only tmuxHistoryLimit is live.
+ * remain schema-validated but inert (a follow-up wires them); only tmuxHistoryLimit is wired.
+ * tmux <3.7 applies it to new panes; tmux 3.7+ can also resize live panes.
  * All values remain env- and settings-overridable and bounds-clamped via
  * resolveTerminalHistoryConfig().
  */

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

@@ -23,7 +23,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
@@ -145,6 +145,9 @@ export function defaultDockerCommandForMode(mode: SessionMode): string {
     gemini: 'exec gemini',
     antigravity: 'exec agy',
     pi: 'exec pi',
+    grok: 'exec grok',
+    deepseek: 'exec dsh',
+    omp: 'exec omp',
   };
   return commands[mode as DockerCommandMode] || commands.shell;
 }
@@ -274,6 +277,24 @@ export interface DockerMount {
   readonly?: boolean;
 }
 
+/**
+ * Resolve a bind source into the Docker daemon's filesystem namespace.
+ *
+ * A bare-host Codeman process and its Docker daemon see the same HOME, so the
+ * source is returned unchanged. In Docker-outside-of-Docker deployments,
+ * `runtimeHome` is the path inside Codeman while `daemonHome` is the host path
+ * bind-mounted there. Sources beneath HOME must therefore be translated before
+ * they are sent through the Docker socket.
+ */
+export function resolveDockerDaemonMountSource(source: string, runtimeHome: string, daemonHome?: string): string {
+  const configuredDaemonHome = daemonHome?.trim();
+  if (!configuredDaemonHome) return source;
+
+  const relativeSource = relative(resolve(runtimeHome), resolve(source));
+  if (relativeSource.startsWith('..') || isAbsolute(relativeSource)) return source;
+  return resolve(configuredDaemonHome, relativeSource);
+}
+
 /**
  * Resolved, IO-free context for buildDockerCreateArgs. The caller (tmux-manager)
  * resolves the environment-dependent bits (host uid, existing cred mounts, the
@@ -297,6 +318,8 @@ export interface DockerCreateContext {
   addHostGateway: boolean;
   /** Engine host-gateway alias (host.docker.internal / host.containers.internal). */
   gatewayAlias: string;
+  /** Omit --memory-swap when the host kernel cannot enforce swap limits. */
+  disableSwapLimit?: boolean;
 }
 
 /**
@@ -314,12 +337,15 @@ function mountSpec(m: DockerMount): string {
   return `type=bind,src=${m.src},dst=${m.dst}${m.readonly ? ',readonly' : ''}`;
 }
 
-function resourceFlags(resources?: DockerResourceLimits): string[] {
+function resourceFlags(resources?: DockerResourceLimits, disableSwapLimit = false): string[] {
   if (!resources) return [];
   const flags: string[] = [];
   if (resources.memory) {
-    // memory-swap == memory disables swap, making --memory a REAL OOM cap.
-    flags.push('--memory', resources.memory, '--memory-swap', resources.memory);
+    flags.push('--memory', resources.memory);
+    // memory-swap == memory disables swap where the daemon supports swap
+    // accounting. Some kernels, including the deployed Unraid host, do not;
+    // requesting it there emits a warning and Docker ignores the value.
+    if (!disableSwapLimit) flags.push('--memory-swap', resources.memory);
   }
   if (resources.cpus) flags.push('--cpus', resources.cpus);
   if (resources.pidsLimit) flags.push('--pids-limit', String(resources.pidsLimit));
@@ -384,7 +410,7 @@ export function buildDockerCreateArgs(ctx: DockerCreateContext): string[] {
   if (addHostGateway) args.push('--add-host', `${gatewayAlias}:host-gateway`);
 
   args.push(
-    ...resourceFlags(docker.resources),
+    ...resourceFlags(docker.resources, ctx.disableSwapLimit),
     // GPU passthrough (needs the NVIDIA container toolkit on the host). No storage
     // cap is set, so the container's writable layer + volumes grow elastically as
     // data flows in (bounded only by host disk).
@@ -614,8 +640,45 @@ 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 },
+  // OMP keeps its config in `~/.omp/agent` (config.yml/mcp.json/models.yml/
+  // settings.yml — small, no bigger than grok's config.toml/pager.toml), but
+  // that dir ALSO holds agent.db/history.db/models.db (SQLite caches) and
+  // terminal-sessions/blobs/cache (large, regenerable), so seed only the
+  // config files. UNLIKE pi/grok, `sessions/` is SHARED (RW), not
+  // host-invisible: Codeman reads `~/.omp/agent/sessions/**/*.jsonl`
+  // HOST-SIDE for history recovery and --resume pinning
+  // (omp-transcript.ts, omp-session-resolver.ts) — the same reason codex's
+  // `sessions/` is shared rather than seeded. Without this, an in-container
+  // OMP conversation would be invisible to Codeman's own history-scan/resume
+  // logic, silently breaking the kill-survival feature for Docker cases.
+  {
+    rel: '.omp/agent',
+    shareDirs: ['sessions'],
+    seedFiles: ['config.yml', 'mcp.json', 'models.yml', 'settings.yml'],
+  },
 ];
 
 /**

src/git-clone.ts

@@ -479,14 +479,23 @@ export function gitNonInteractiveEnv(base: NodeJS.ProcessEnv = process.env): Nod
 
 // ─── Pure: output handling ───────────────────────────────────────────────────
 
+/**
+ * Redact any `scheme://user:secret@host` credential pair embedded in text — a
+ * remote URL stored with an inline token, or git stderr echoing such a URL
+ * back. Shared by the clone error path (`sanitizeGitOutput`) and the
+ * repository-status card fields (`web/repo-status.ts`).
+ */
+export function redactGitCredentials(text: string): string {
+  return text.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@\s]*:[^/@\s]*@/g, '$1***:***@');
+}
+
 /**
  * Make git's stderr safe to show in the browser: strip ANSI/control bytes,
  * redact any `scheme://user:secret@host` that a credential helper echoed back,
  * and keep only the tail (the last lines are the ones that say why it failed).
  */
 export function sanitizeGitOutput(text: string, maxBytes = MAX_STDERR_BYTES): string {
-  const redacted = text
-    .replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@\s]*:[^/@\s]*@/g, '$1***:***@')
+  const redacted = redactGitCredentials(text)
     // eslint-disable-next-line no-control-regex -- deliberate: strip C0/C1 and DEL.
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '')
     .trim();

src/mux-interface.ts

@@ -19,6 +19,9 @@ import type {
   GeminiConfig,
   AntigravityConfig,
   PiConfig,
+  GrokConfig,
+  DeepSeekConfig,
+  OmpConfig,
   SessionRemote,
   SessionDocker,
 } from './types.js';
@@ -78,13 +81,16 @@ export interface CreateSessionOptions {
   geminiConfig?: GeminiConfig;
   antigravityConfig?: AntigravityConfig;
   piConfig?: PiConfig;
+  grokConfig?: GrokConfig;
+  deepSeekConfig?: DeepSeekConfig;
+  ompConfig?: OmpConfig;
   /** 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. */
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level, injected as a `--settings` soft default (overridable via /effort in-session) */
   effort?: EffortLevel;
-  /** tmux history-limit (scrollback lines) to set for this session. */
+  /** tmux history-limit (scrollback lines) allocated when this session is created. */
   historyLimit?: number;
   /** Remote execution metadata for local tmux sessions wrapping SSH */
   remote?: SessionRemote;
@@ -110,13 +116,16 @@ export interface RespawnPaneOptions {
   geminiConfig?: GeminiConfig;
   antigravityConfig?: AntigravityConfig;
   piConfig?: PiConfig;
+  grokConfig?: GrokConfig;
+  deepSeekConfig?: DeepSeekConfig;
+  ompConfig?: OmpConfig;
   /** Resume a previous Claude conversation when respawning */
   resumeSessionId?: string;
   /** Extra env vars exported before launching the CLI (preserved across respawns). */
   envOverrides?: Record<string, string>;
   /** Claude CLI effort level (preserved across respawns, injected via `--settings`) */
   effort?: EffortLevel;
-  /** tmux history-limit (scrollback lines) to set for this session after respawn. */
+  /** Original tmux history-limit retained for config parity; respawn cannot resize the existing pane. */
   historyLimit?: number;
   /** Remote execution metadata for local tmux sessions wrapping SSH */
   remote?: SessionRemote;
@@ -216,7 +225,7 @@ export interface TerminalMultiplexer extends EventEmitter {
   /** Update Ralph enabled state for a session */
   updateRalphEnabled(sessionId: string, enabled: boolean): void;
 
-  /** Apply a tmux history-limit to all tracked sessions. */
+  /** Apply history-limit to live panes where tmux supports it, otherwise to future panes. */
   setHistoryLimit(limit: number): Promise<void>;
 
   // ========== Discovery ==========

src/omp-transcript.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview Scan `~/.omp/agent/sessions/*/*.jsonl` for Past Sessions rows,
+ * the omp analog of what `scanProjectDir()` (session-routes.ts) does for
+ * Claude's own `~/.claude/projects` transcripts.
+ *
+ * Without this, an omp conversation exists ONLY as a Codeman-level live/
+ * persisted session record — delete that (a "Kill Tmux" close, or any other
+ * cleanup) and the conversation vanishes from Past Sessions entirely, even
+ * though `omp` itself never forgot it. Claude conversations don't have that
+ * problem because Codeman already reads them back from Claude's own
+ * transcript files independent of its own session bookkeeping; this gives
+ * omp conversations the same treatment.
+ *
+ * Each omp session file's SECOND line is a `{"type":"session","id":...,
+ * "cwd":...}` header carrying the real (unmangled) working directory and the
+ * session's own id directly — no need to reverse-engineer the mangled
+ * directory name the way Claude Code's own scanner has to (see
+ * `decodeProjectKey()` in session-routes.ts and its "lossy" caveat). Prompt
+ * text comes from each `{"type":"message","message":{"role":"user",...}}`
+ * entry, giving a real first-message title instead of a bare case name.
+ *
+ * Unlike Claude's transcripts (which can run to tens of MB of tool-call
+ * output), an omp session file is the conversation only, so this reads each
+ * file whole rather than doing head/tail windows — bounded by a size cap so
+ * one unexpectedly huge file can't blow up memory.
+ *
+ * @module omp-transcript
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function ompSessionsRoot(): string {
+  return join(homedir(), '.omp', 'agent', 'sessions');
+}
+
+/** Skip anything absurdly large rather than parsing it whole into memory. */
+const MAX_OMP_SESSION_FILE_BYTES = 2 * 1024 * 1024;
+
+/** Defensive cap on total files scanned across every directory, mirroring
+ *  the Claude scanner's own instinct not to let one pathological tree stall
+ *  a request — a real omp install has, at most, a few hundred of these. */
+const MAX_OMP_SESSION_FILES = 2000;
+
+export interface OmpHistorySession {
+  sessionId: string;
+  workingDir: string;
+  sizeBytes: number;
+  /** ISO timestamp, from the file's own mtime. */
+  lastModified: string;
+  firstPrompt?: string;
+  lastPrompt?: string;
+}
+
+function extractUserPromptText(message: unknown): string | undefined {
+  if (!message || typeof message !== 'object') return undefined;
+  const m = message as { role?: unknown; content?: unknown };
+  if (m.role !== 'user' || !Array.isArray(m.content)) return undefined;
+  const parts: string[] = [];
+  for (const block of m.content) {
+    if (block && typeof block === 'object' && (block as { type?: unknown }).type === 'text') {
+      const text = (block as { text?: unknown }).text;
+      if (typeof text === 'string') parts.push(text);
+    }
+  }
+  const joined = parts.join(' ').trim();
+  return joined || undefined;
+}
+
+/** Parse one omp session `.jsonl` file, or null when it's unreadable, empty, or has no session header. */
+function parseOmpSessionFile(filePath: string): OmpHistorySession | null {
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(filePath);
+  } catch {
+    return null;
+  }
+  if (stat.size === 0 || stat.size > MAX_OMP_SESSION_FILE_BYTES) return null;
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  let sessionId: string | undefined;
+  let workingDir: string | undefined;
+  let firstPrompt: string | undefined;
+  let lastPrompt: string | undefined;
+
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    let entry: unknown;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!entry || typeof entry !== 'object') continue;
+    const e = entry as Record<string, unknown>;
+    if (e.type === 'session' && typeof e.id === 'string' && typeof e.cwd === 'string' && e.cwd.startsWith('/')) {
+      // A corrupted or malformed session file could carry a relative or empty
+      // cwd; requiring an absolute path keeps a downstream resume attempt
+      // from being pointed at a nonsense working directory.
+      sessionId = e.id;
+      workingDir = e.cwd;
+    } else if (e.type === 'message') {
+      const prompt = extractUserPromptText(e.message);
+      if (prompt) {
+        if (!firstPrompt) firstPrompt = prompt;
+        lastPrompt = prompt;
+      }
+    }
+  }
+
+  if (!sessionId || !workingDir) return null;
+  return {
+    sessionId,
+    workingDir,
+    sizeBytes: stat.size,
+    lastModified: stat.mtime.toISOString(),
+    firstPrompt,
+    lastPrompt,
+  };
+}
+
+/**
+ * Scan every omp conversation on disk into Past-Sessions rows. Best-effort
+ * throughout: a missing `~/.omp` (never installed/used), an unreadable
+ * directory, or one corrupt file yields fewer rows rather than throwing —
+ * this feeds the same unified merge the Claude transcript scanner does, and
+ * one broken source must never blank the whole Past Sessions list.
+ */
+export function scanOmpSessionsHistory(): OmpHistorySession[] {
+  const root = ompSessionsRoot();
+  let dirEntries: string[];
+  try {
+    dirEntries = readdirSync(root);
+  } catch {
+    return [];
+  }
+
+  const out: OmpHistorySession[] = [];
+  for (const dirName of dirEntries) {
+    if (out.length >= MAX_OMP_SESSION_FILES) break;
+    const dirPath = join(root, dirName);
+    let dirStat: ReturnType<typeof statSync>;
+    try {
+      dirStat = statSync(dirPath);
+    } catch {
+      continue;
+    }
+    if (!dirStat.isDirectory()) continue;
+
+    let files: string[];
+    try {
+      files = readdirSync(dirPath);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (out.length >= MAX_OMP_SESSION_FILES) break;
+      if (!file.endsWith('.jsonl')) continue;
+      try {
+        const parsed = parseOmpSessionFile(join(dirPath, file));
+        if (parsed) out.push(parsed);
+      } catch {
+        // One bad file must not sink the whole scan.
+      }
+    }
+  }
+  return out;
+}

src/ralph-loop.ts

@@ -281,7 +281,14 @@ export class RalphLoop extends EventEmitter {
         // Guard: only reschedule if still running AND no timer is pending
         // (prevents race where stop() clears timer between our check and setTimeout)
         if (this._status === 'running' && this.loopTimer === null) {
-          this.loopTimer = setTimeout(() => this.runLoop(), this.pollIntervalMs);
+          // Null the handle when the timer fires, BEFORE re-entering runLoop —
+          // otherwise the `loopTimer === null` guard above stays false on the
+          // next pass and the loop stops rescheduling after 2 ticks.
+          // Mirrors the orchestrator-loop reschedule pattern.
+          this.loopTimer = setTimeout(() => {
+            this.loopTimer = null;
+            this.runLoop();
+          }, this.pollIntervalMs);
         }
       });
   }

src/remote-hosts.ts

@@ -114,6 +114,12 @@ 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'),
+    omp: remoteLoginShellCommand('omp'),
   };
   return commands[mode as RemoteCommandMode] || commands.shell;
 }
@@ -269,6 +275,7 @@ const REMOTE_CLI_BIN: Partial<Record<SessionMode, string>> = {
   gemini: 'gemini',
   antigravity: 'agy',
   pi: 'pi',
+  omp: 'omp',
 };
 
 /**

src/services/unified-session-service.ts

@@ -99,6 +99,13 @@ export type HistoryInput = {
   gitBranch?: string;
   worktreeName?: string;
   worktreeRepo?: string;
+  /**
+   * Set only by a non-claude transcript source (currently omp); the Claude
+   * scanner never stamps this; the meaningfulness floor below still counts a
+   * row with a `mode` as real, since that also signals "not claude" — see
+   * where it's read below for the isReal check this touches.
+   */
+  mode?: string;
 };
 
 /** Mux process-stat view. */
@@ -175,6 +182,10 @@ export function mergeUnifiedSessions(sources: UnifiedSources): UnifiedSessionIte
     overwrite(item, 'gitBranch', h.gitBranch);
     overwrite(item, 'worktreeName', h.worktreeName);
     overwrite(item, 'worktreeRepo', h.worktreeRepo);
+    // Claude rows never set this (they're implicitly claude); a non-claude
+    // transcript source (currently only omp) does, so a history-only row
+    // still gets a mode badge instead of reading as claude by default.
+    overwrite(item, 'mode', h.mode);
     const ms = Date.parse(h.lastModified);
     if (!Number.isNaN(ms) && item.lastActivityAt === undefined) item.lastActivityAt = ms;
   }

src/session-trust-dialog.ts

@@ -1,16 +1,32 @@
 /**
- * @fileoverview Recognizing Claude Code's workspace-trust dialog on screen.
+ * @fileoverview Recognizing Claude Code's workspace-trust dialog on screen, and
+ * working out which keystroke answers it.
  *
- * Claude asks once per directory before it will read or edit anything:
+ * Claude asks once per directory before it will read or edit anything. The
+ * layout has changed under us at least twice; both of these are live shapes:
  *
- *   Quick safety check: Is this a project you created or one you trust? ...
+ *   Quick safety check: Is this a project you created or one you trust? ...     (<= 2.1.220)
  *   ❯ 1. Yes, I trust this folder
  *     2. No, exit
  *   Enter to confirm · Esc to cancel
  *
+ *   Quick safety check: Is this a project you created or one you trust? ...     (2.1.252)
+ *   Security guide
+ *   ❯ No, exit
+ *     Yes, I trust this folder
+ *   Enter to confirm · Esc to cancel
+ *
  * Codeman sessions run permission-skipping or classifier-guarded modes, so the
  * answer is always yes, and a session parked on this dialog is simply stuck.
  *
+ * ⚠️ **Never press Enter without reading the selection.** The options are now
+ * unnumbered, REVERSED, and the highlighted default is "No, exit" — so the blind
+ * `\r` that answered the old layout picks *exit* on the new one and the pane
+ * dies (`Pane is dead (status 1)`) seconds after the session starts, which is
+ * exactly what a fresh case did on Claude Code 2.1.252. `trustDialogNextKey()`
+ * reads the `❯` marker instead and moves the cursor onto the trust option before
+ * it confirms anything.
+ *
  * **Why the text has to be compacted.** tmux repaints a row by writing each word
  * and then a cursor-forward (`\x1b[C`) instead of a space, and Ink colours each
  * word separately, so the wire carries `I\x1b[Ctrust\x1b[Cthis\x1b[Cfolder`.
@@ -39,6 +55,25 @@ const TRUST_PHRASES = [
 /** The dialog's own affordances. Prose that quotes the question will not have these. */
 const CONFIRM_PHRASES = ['entertoconfirm', 'esctocancel', '2.no,exit'];
 
+/** The option that answers yes, compacted. Identical text in both layouts. */
+const YES_OPTION = 'yes,itrustthisfolder';
+
+/** The option that quits Claude. It is the highlighted DEFAULT since 2.1.252. */
+const NO_OPTION = 'no,exit';
+
+/** Ink's selection marker. The only marked row while the dialog is up. */
+const SELECTION_MARK = '❯';
+
+/** A numbered option's `1.` / `2.` prefix, which the 2.1.220 layout put after the marker. */
+const OPTION_NUMBER_PREFIX = /^\d+\./;
+
+/** Move the selection one row down / up. Literal, so `send-keys -l` carries them. */
+export const TRUST_KEY_DOWN = '\x1b[B';
+export const TRUST_KEY_UP = '\x1b[A';
+
+/** Confirm the highlighted option. */
+export const TRUST_KEY_CONFIRM = '\r';
+
 /**
  * Charset-select sequences (`ESC ( B`), which tmux emits around styled runs and
  * `stripAnsi` does not cover. Left in, they would land inside a phrase as a
@@ -65,6 +100,50 @@ export function isTrustDialogScreen(text: string): boolean {
   return TRUST_PHRASES.some((p) => compact.includes(p)) && CONFIRM_PHRASES.some((p) => compact.includes(p));
 }
 
+/**
+ * Which option the `❯` marker sits on, or null when this text does not say.
+ *
+ * The LAST marked option wins. A pane capture holds exactly one frame and so
+ * exactly one marker, but the direct-PTY fallback reads an append-only buffer
+ * where every repaint since launch is still present — there the freshest frame
+ * is the one at the end, and an older one must not out-vote it.
+ */
+function selectedTrustOption(compact: string): { at: number; option: 'yes' | 'no' } | null {
+  let selected: { at: number; option: 'yes' | 'no' } | null = null;
+  for (let at = compact.indexOf(SELECTION_MARK); at >= 0; at = compact.indexOf(SELECTION_MARK, at + 1)) {
+    const after = compact.slice(at + SELECTION_MARK.length).replace(OPTION_NUMBER_PREFIX, '');
+    if (after.startsWith(YES_OPTION)) selected = { at, option: 'yes' };
+    else if (after.startsWith(NO_OPTION)) selected = { at, option: 'no' };
+  }
+  return selected;
+}
+
+/**
+ * The single keystroke that moves this dialog one step closer to "yes", or null
+ * when the screen does not show clearly enough to touch.
+ *
+ * One step per call on purpose: the caller re-reads the screen between
+ * keystrokes, so a moved cursor is CONFIRMED before Enter is pressed rather than
+ * assumed. Firing arrow+Enter together would re-create the failure this exists
+ * to prevent whenever the arrow is dropped (Ink drops keystrokes while it is
+ * still mounting a widget) — the Enter would then land on "No, exit".
+ *
+ * Returning null is the safe answer, not a failure: an unreadable frame means
+ * wait for the next repaint, and a layout whose options this cannot name means
+ * leave the dialog to the human. The caller's startup window bounds the waiting.
+ */
+export function trustDialogNextKey(text: string): string | null {
+  const compact = compactScreenText(text);
+  if (!compact.includes(YES_OPTION)) return null; // no trust option to steer onto
+  const selected = selectedTrustOption(compact);
+  if (!selected) return null; // marker missing, or not on an option we recognize
+  if (selected.option === 'yes') return TRUST_KEY_CONFIRM;
+  // On "No, exit". Which way the trust option lies is read from THIS frame — it
+  // sits below in 2.1.252 and above in the numbered layout before it — so the
+  // order flipping again costs a repaint, not a killed session.
+  return compact.includes(YES_OPTION, selected.at) ? TRUST_KEY_DOWN : TRUST_KEY_UP;
+}
+
 /**
  * How long after the pane starts the dialog is still plausible. It renders
  * before the main UI, so this only has to cover a slow first launch; leaving it
@@ -72,16 +151,21 @@ export function isTrustDialogScreen(text: string): boolean {
  */
 export const TRUST_DIALOG_WINDOW_MS = 90_000;
 
-/** Minimum gap between two Enter presses, and between two screen reads. */
+/** Minimum gap between two keystrokes, and between two screen reads. */
 export const TRUST_DIALOG_RETRY_MS = 1500;
 
 /**
- * Attempts before giving up and leaving the dialog to the user. A keystroke can
- * land while Ink is still mounting the widget and be dropped, which is the other
- * half of why sessions got stuck here; retrying costs nothing, but retrying
- * forever would hammer Enter into whatever came next.
+ * Keystrokes before giving up and leaving the dialog to the user. A keystroke
+ * can land while Ink is still mounting the widget and be dropped, which is the
+ * other half of why sessions got stuck here; retrying costs nothing, but
+ * retrying forever would hammer Enter into whatever came next.
+ *
+ * Six rather than three because answering is no longer one press: the 2.1.252
+ * layout needs an arrow onto the trust option and then Enter, each confirmed
+ * against a re-read of the screen, so a cap of three left only one dropped
+ * keystroke of slack.
  */
-export const TRUST_DIALOG_MAX_ATTEMPTS = 3;
+export const TRUST_DIALOG_MAX_ATTEMPTS = 6;
 
 /**
  * How much of the append-only terminal buffer to read on a direct-PTY session,

src/session.ts

@@ -51,9 +51,13 @@ import {
   type GeminiConfig,
   type AntigravityConfig,
   type PiConfig,
+  type GrokConfig,
+  type DeepSeekConfig,
+  type OmpConfig,
   type SessionRemote,
   type SessionDocker,
 } from './types.js';
+import { resolveAndClaimOmpSessionId } from './utils/omp-session-resolver.js';
 import { probeDockerCliVersion } from './docker-hosts.js';
 import { probeRemoteCliVersion } from './remote-hosts.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
@@ -62,6 +66,8 @@ import { RalphTracker } from './ralph-tracker.js';
 import { BashToolParser } from './bash-tool-parser.js';
 import {
   isTrustDialogScreen,
+  trustDialogNextKey,
+  TRUST_KEY_CONFIRM,
   TRUST_DIALOG_WINDOW_MS,
   TRUST_DIALOG_RETRY_MS,
   TRUST_DIALOG_MAX_ATTEMPTS,
@@ -171,7 +177,16 @@ 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' ||
+    mode === 'omp'
+  );
 }
 
 function getModeLabel(mode: SessionMode): string {
@@ -186,6 +201,12 @@ function getModeLabel(mode: SessionMode): string {
       return 'Antigravity';
     case 'pi':
       return 'Pi';
+    case 'grok':
+      return 'Grok';
+    case 'deepseek':
+      return 'DeepSeek';
+    case 'omp':
+      return 'OMP';
     case 'shell':
       return 'Shell';
     case 'claude':
@@ -202,8 +223,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
@@ -415,6 +437,15 @@ export class Session extends EventEmitter {
   // sequences split across PTY chunks can't slip past the alt-screen/scrollback
   // strip (see _handleTerminalOutput / isAltScreenStripMode)
   private _altScreenSeqCarry: string = '';
+
+  /**
+   * Mouse-tracking DECSET modes the CLI currently has ON, as observed while
+   * STRIPPING them out of the stream below. Kept as a set rather than a boolean
+   * because a TUI may enable 1002 and later disable 1000 (a mode it never
+   * enabled); tracking is on while any of them is.
+   */
+  private _cliMouseModes = new Set<number>();
+  private _cliMouseTracking = false;
   private resolvePromise: ((value: { result: string; cost: number }) => void) | null = null;
   private rejectPromise: ((reason: Error) => void) | null = null;
   private _promptResolved: boolean = false; // Guard against race conditions in runPrompt
@@ -426,8 +457,9 @@ export class Session extends EventEmitter {
   private _lastPaneProbeAt = 0; // Throttle for the tmux screen probe
   private _lastPaneProbeWorking: boolean | null = null; // Its last verdict (null = could not read)
   private _trustDialogAccepted: boolean = false; // Stops the trust-dialog scan (answered, or given up)
-  private _trustDialogAttempts = 0; // Enter presses sent at the trust dialog
+  private _trustDialogAttempts = 0; // Keystrokes sent at the trust dialog
   private _lastTrustDialogScanAt = 0; // Throttle for the trust-dialog screen read
+  private _trustDialogTimer: NodeJS.Timeout | null = null; // Re-read after a keystroke (see below)
   private _interactiveStartedAt = 0; // When the interactive pane launched (bounds that scan)
   private _taskTracker: TaskTracker;
 
@@ -499,6 +531,13 @@ 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;
+  // OMP configuration (only for mode === 'omp')
+  private _ompConfig: OmpConfig | undefined;
   private _resumeSessionId: string | undefined;
 
   // Ephemeral env overrides (e.g., CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Exported by tmux
@@ -510,7 +549,7 @@ export class Session extends EventEmitter {
   // the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session.
   private _effort: EffortLevel | undefined;
 
-  // tmux history-limit (scrollback lines) applied to this session's pane.
+  // tmux history-limit (scrollback lines) allocated when this session's pane is created.
   private readonly _tmuxHistoryLimit: number;
 
   // Remote execution metadata, present when this session runs over SSH through local tmux.
@@ -594,13 +633,19 @@ 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;
+      /** OMP configuration (only for mode === 'omp') */
+      ompConfig?: OmpConfig;
       /** Resume a previous Claude conversation (used after server reboot) */
       resumeSessionId?: string;
       /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
       envOverrides?: Record<string, string>;
       /** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
       effort?: EffortLevel;
-      /** tmux history-limit (scrollback lines) for this session's pane. */
+      /** tmux history-limit (scrollback lines) allocated when this session's pane is created. */
       tmuxHistoryLimit?: number;
       /** Restored per-session attachment history. May include server-private external paths. */
       attachmentHistory?: SessionAttachmentHistoryItem[];
@@ -649,7 +694,13 @@ export class Session extends EventEmitter {
     this._wireActivityAt = config.lastActivityAt || Date.now();
     this._wireActivitySettleUntil = config.lastActivityAt ? Date.now() + WIRE_ACTIVITY_SETTLE_MS : 0;
     // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
-    this._claudeSessionId = config.resumeSessionId || this.id;
+    // For omp, `claudeSessionId` doubles as the generic "external transcript id"
+    // alias key mergeUnifiedSessions() folds a history row into its owning
+    // session by: omp mints its OWN uuid, unrelated to this Codeman id, so
+    // without this an omp conversation's Past-Sessions row (keyed by omp's
+    // id) would never merge with its own live/persisted row (keyed by this
+    // id) — it would just show up a second time.
+    this._claudeSessionId = config.resumeSessionId || config.ompConfig?.resumeSessionId || this.id;
     // Restored from state.json on boot recovery. start() resets _claudeSessionId
     // to the launch id even when re-attaching to a mux session whose CLI has
     // moved on (a `/clear` before the restart), so this anchor is what lets the
@@ -702,6 +753,20 @@ export class Session extends EventEmitter {
     if (config.piConfig) {
       this._piConfig = config.piConfig;
     }
+    // Apply OMP configuration
+    if (config.ompConfig) {
+      this._ompConfig = config.ompConfig;
+    }
+
+    // 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,
@@ -850,6 +915,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;
@@ -1285,6 +1378,7 @@ export class Session extends EventEmitter {
       niceValue: this._niceConfig.niceValue,
       color: this._color,
       flickerFilterEnabled: this._flickerFilterEnabled,
+      cliMouseTracking: this._cliMouseTracking || undefined,
       cliVersion: this._cliVersion || undefined,
       cliModel: this._cliModel || undefined,
       cliAccountType: this._cliAccountType || undefined,
@@ -1294,6 +1388,9 @@ export class Session extends EventEmitter {
       geminiConfig: this._geminiConfig,
       antigravityConfig: this._antigravityConfig,
       piConfig: this._piConfig,
+      grokConfig: this._grokConfig,
+      deepSeekConfig: this._deepSeekConfig,
+      ompConfig: this._ompConfig,
       resumeSessionId: this._resumeSessionId,
       effort: this._effort,
       // COD-118: runtime-only — surfaced so the frontend can require explicit user
@@ -1420,7 +1517,11 @@ export class Session extends EventEmitter {
     let needsNewSession = false;
     if (this._muxSession && mux.isPaneDead(this._muxSession.muxName)) {
       console.log('[Session] Dead pane detected, respawning:', this._muxSession.muxName);
-      const newPid = await mux.respawnPane(options.respawnPaneOptions);
+      // Confirmed dead — safe to resolve/pin now (see `_pinOmpRespawnId()`).
+      // `options.respawnPaneOptions` was built eagerly before this dead-pane
+      // check ran, so it still carries the pre-pin ompConfig; rebuild it.
+      this._pinOmpRespawnId();
+      const newPid = await mux.respawnPane(this._buildRespawnPaneOptions());
       if (!newPid) {
         console.error('[Session] Failed to respawn pane, will create new session');
         needsNewSession = true;
@@ -1466,7 +1567,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'
           ),
         })
       );
@@ -1506,6 +1612,9 @@ export class Session extends EventEmitter {
       return false;
     }
 
+    // Confirmed the mux session (and thus the pane) exists but this reattach
+    // is about to respawn it — safe to resolve/pin now.
+    this._pinOmpRespawnId();
     const newPid = await mux.respawnPane(this._buildRespawnPaneOptions());
     if (!newPid) {
       console.error('[Session] reattachRemote: respawnPane failed for', this._muxSession.muxName);
@@ -1536,6 +1645,18 @@ export class Session extends EventEmitter {
       geminiConfig: this._geminiConfig,
       antigravityConfig: this._antigravityConfig,
       piConfig: this._piConfig,
+      grokConfig: this._grokConfig,
+      deepSeekConfig: this._deepSeekConfig,
+      // OMP resolution/pinning does NOT happen here. This object is built
+      // EAGERLY — including on every boot-recovery reattach, before anyone
+      // knows whether the pane is actually dead — so resolving here mutated
+      // `_ompConfig`/`_claudeSessionId` even for a pane that was simply being
+      // reattached to, not respawned; with two omp tabs in the same case dir
+      // that mis-pinned the ALIVE session onto whichever file happened to be
+      // newest on disk (reported live in the Ark0N/Codeman#353 review). The
+      // real pin now happens in `_pinOmpRespawnId()`, called by callers ONLY
+      // once they've confirmed an actual respawn is about to happen.
+      ompConfig: this._ompConfig,
       resumeSessionId: this._resumeSessionId,
       envOverrides: this._envOverrides,
       effort: this._effort,
@@ -1546,6 +1667,85 @@ export class Session extends EventEmitter {
     };
   }
 
+  /**
+   * OMP-only: resolve and PIN the exact conversation to continue when
+   * respawning a dead pane, so every later respawn reuses the same id
+   * instead of re-resolving (and re-risking picking up a DIFFERENT
+   * conversation that happened to touch this directory more recently). See
+   * the comment at the call site in {@link _buildRespawnPaneOptions} for why
+   * "newest file on disk" is safe here specifically. Non-omp modes and a
+   * session that already carries an explicit id pass through untouched.
+   */
+  private _pinOmpRespawnId(): void {
+    if (this.mode !== 'omp') return;
+    if (this._ompConfig?.resumeSessionId) return;
+    // Callers MUST call this only immediately before an ACTUAL respawn (a
+    // confirmed-dead pane, or a genuine remote reattach) — never while merely
+    // building options that might not lead to a respawn. A fresh "Run OMP"
+    // click has no _muxSession yet and must never inherit whatever omp
+    // conversation happens to be newest on disk for this working directory
+    // (reported live 2026-08-27, fixed in 13a19f79); this guard keeps that
+    // fix intact now that resolution has moved out of the eager options build.
+    if (!this._muxSession) return;
+    const resolvedId = resolveAndClaimOmpSessionId(this.workingDir);
+    if (resolvedId) {
+      this._ompConfig = { ...this._ompConfig, resumeSessionId: resolvedId };
+      // Alias omp's own session uuid to this Codeman id — see the
+      // constructor's claudeSessionId comment for why this field is the
+      // (generically-named) mechanism that folds a Past-Sessions row back
+      // into its live/persisted session instead of duplicating it.
+      this._claudeSessionId = resolvedId;
+      return;
+    }
+    // Nothing unclaimed on disk (the dying process never got far enough to
+    // write a session file, or a sibling already claimed the only candidate)
+    // — fall back to the CLI's own "most recent" heuristic.
+    console.warn(
+      `[Session] OMP: no session file found under ${this.workingDir} to pin --resume on respawn; falling back to ambiguous --continue`
+    );
+    this._ompConfig = { ...this._ompConfig, continueSession: true };
+  }
+
+  /**
+   * Remember whether the CLI currently wants to be told about mouse clicks.
+   *
+   * The strip in {@link _handleTerminalOutput} is the ONLY place these sequences
+   * exist. After it, neither the browser nor xterm can ever learn that the CLI
+   * asked for mouse tracking, so `terminal.modes.mouseTrackingMode` is
+   * permanently 'none' for a stripped mode. The browser hand-encodes SGR reports
+   * to compensate (`_sendSyntheticSgrTap` in terminal-ui.js), and with no state
+   * to consult it had to do that on EVERY click, delivering mouse reports to a
+   * CLI that never asked for them. Publishing this through `toState()` is what
+   * lets the browser report a click only when the CLI is listening.
+   *
+   * Only the TRACKING modes count. 1005/1006 select an encoding and 1007 is
+   * alt-scroll; a CLI that picks SGR encoding without turning a tracking mode on
+   * is not asking about clicks, and counting those would put the stray reports
+   * straight back.
+   *
+   * This must stay in lockstep with the strip regex that calls it: a sequence
+   * removed from the stream but not recorded here is one the browser can neither
+   * see nor be told about.
+   */
+  private _recordStrippedMouseMode(seq: string): void {
+    // eslint-disable-next-line no-control-regex
+    const match = /\x1b\[\?(\d+)([hl])$/.exec(seq);
+    if (!match) return;
+    const mode = Number(match[1]);
+    if (mode !== 1000 && mode !== 1001 && mode !== 1002 && mode !== 1003) return;
+    if (match[2] === 'h') this._cliMouseModes.add(mode);
+    else this._cliMouseModes.delete(mode);
+    this._syncCliMouseTracking();
+  }
+
+  /** Emit only on a real transition: a TUI re-emitting its enable on every repaint costs nothing. */
+  private _syncCliMouseTracking(): void {
+    const active = this._cliMouseModes.size > 0;
+    if (active === this._cliMouseTracking) return;
+    this._cliMouseTracking = active;
+    this.emit('mouseTrackingChanged', active);
+  }
+
   private _handleTerminalOutput(data: string): void {
     // Codex AND Claude Code emit sequences that wipe xterm.js scrollback, plus
     // mouse-tracking enables that hijack the scroll wheel so the user can't reach
@@ -1598,7 +1798,10 @@ export class Session extends EventEmitter {
           // eslint-disable-next-line no-control-regex
           .replace(/\x1b\[3J/g, '')
           // eslint-disable-next-line no-control-regex
-          .replace(/\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g, '');
+          .replace(/\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g, (seq) => {
+            this._recordStrippedMouseMode(seq);
+            return '';
+          });
       }
     }
 
@@ -1641,6 +1844,10 @@ export class Session extends EventEmitter {
     this._interactiveStartedAt = Date.now();
     this._trustDialogAttempts = 0;
     this._lastTrustDialogScanAt = 0;
+    if (this._trustDialogTimer) {
+      clearTimeout(this._trustDialogTimer);
+      this._trustDialogTimer = null;
+    }
 
     // COD-118: if the PTY exit breaker has tripped (repeated non-zero exits in a
     // short window), refuse to respawn. This is the uniform choke point that stops
@@ -1751,6 +1958,9 @@ export class Session extends EventEmitter {
             geminiConfig: this._geminiConfig,
             antigravityConfig: this._antigravityConfig,
             piConfig: this._piConfig,
+            grokConfig: this._grokConfig,
+            deepSeekConfig: this._deepSeekConfig,
+            ompConfig: this._ompConfig,
             resumeSessionId: this._resumeSessionId,
             envOverrides: this._envOverrides,
             effort: this._effort,
@@ -1762,8 +1972,14 @@ export class Session extends EventEmitter {
           spawnErrLabel: 'mux attachment',
         });
 
-        // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
-        this._claudeSessionId = this._resumeSessionId || this.id;
+        // Set claudeSessionId — when resuming, the Claude conversation ID is the
+        // resumed one. `_pinOmpRespawnId()` (called just above, inside
+        // `_setupOrAttachMuxSession()`'s dead-pane branch) may have JUST aliased
+        // this to omp's own session uuid — that already-resolved id must win
+        // over the generic `this.id` fallback, or this line clobbers it back
+        // to the Codeman id
+        // on every single respawn.
+        this._claudeSessionId = this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id;
 
         // For NEW mux sessions: wait for readiness then clean buffer
         // For RESTORED mux sessions: don't do anything - client will fetch buffer on tab switch
@@ -1840,6 +2056,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
@@ -1871,7 +2097,12 @@ export class Session extends EventEmitter {
     }
 
     // Set claudeSessionId — when resuming, the Claude conversation ID is the resumed one.
-    this._claudeSessionId = this._resumeSessionId || this.id;
+    // Mirrors the mux branch above and must not clobber it: this line runs
+    // unconditionally after both the mux and direct-PTY paths, so it also needs
+    // the ompConfig fallback or it stomps the mux branch's correctly-resolved
+    // OMP alias back to this.id on every mux/plain-reattach boot recovery
+    // (the "third reset point" — see DECISIONS.md).
+    this._claudeSessionId = this._resumeSessionId || this._ompConfig?.resumeSessionId || this.id;
 
     this._pid = this.ptyProcess.pid;
     console.log('[Session] Interactive PTY spawned with PID:', this._pid);
@@ -2005,6 +2236,15 @@ export class Session extends EventEmitter {
    * makes a retry safe, since the terminal buffer is append-only and keeps the
    * dialog in its tail long after it has been answered.
    *
+   * ⚠️ **The keystroke is read off the screen, never assumed.** Claude Code
+   * 2.1.252 dropped the option numbers, put "No, exit" first, and highlights IT
+   * by default, so the bare `\r` this used to send now answers *exit*: a fresh
+   * case died (`Pane is dead (status 1)`) about six seconds after spawning.
+   * `trustDialogNextKey()` returns one step at a time — an arrow while the
+   * cursor is on the wrong option, Enter only once the screen shows it on the
+   * trust option — and this method re-reads the pane between the two, so a
+   * dropped arrow costs a repaint instead of the session.
+   *
    * Three guards keep an Enter press off a live session: a startup-only window,
    * a two-marker match (isTrustDialogScreen), and an attempt cap.
    */
@@ -2025,17 +2265,39 @@ export class Session extends EventEmitter {
       this._terminalBuffer.value.slice(-TRUST_DIALOG_SCAN_BYTES);
     if (!isTrustDialogScreen(screen)) return;
 
+    // Null means the frame does not say which option is highlighted. Waiting for
+    // the next repaint is the safe move; pressing Enter blind is the bug.
+    const key = trustDialogNextKey(screen);
+    if (key === null) return;
+
     this._trustDialogAttempts++;
     if (this._trustDialogAttempts > TRUST_DIALOG_MAX_ATTEMPTS) {
       this._trustDialogAccepted = true; // leave it to the user rather than keep typing
       console.warn(`[Session] Workspace trust dialog did not clear after retries: ${this.id}`);
       return;
     }
+    const step = key === TRUST_KEY_CONFIRM ? 'confirming' : 'moving to the trust option';
     console.log(
-      `[Session] Auto-accepting workspace trust dialog for: ${this.id} (attempt ${this._trustDialogAttempts})`
+      `[Session] Auto-accepting workspace trust dialog for: ${this.id} (attempt ${this._trustDialogAttempts}, ${step})`
     );
-    // Enter confirms the highlighted default, "1. Yes, I trust this folder".
-    this.writeViaMux('\r');
+    this.writeViaMux(key);
+
+    // ⚠️ Schedule the next read; do NOT wait for more PTY output. This scan only
+    // ever ran from `onData`, which was enough while one Enter answered the
+    // dialog. It is not enough now: the arrow that moves the cursor is the LAST
+    // output the pane produces, so a dialog left sitting on the trust option
+    // never gets its Enter and the worker stays parked on it forever (measured
+    // on a live 2.1.252 spawn: cursor moved at 6 s, then nothing). The timer is
+    // one-shot and self-rearming through this same path, and every exit route
+    // goes through _clearAllTimers().
+    // The +100ms puts the re-entry OUTSIDE the scan throttle above; firing at
+    // exactly the throttle boundary would let the scan return early and break
+    // the chain with the dialog still on screen.
+    if (this._trustDialogTimer) clearTimeout(this._trustDialogTimer);
+    this._trustDialogTimer = setTimeout(() => {
+      this._trustDialogTimer = null;
+      this._maybeAcceptTrustDialog();
+    }, TRUST_DIALOG_RETRY_MS + 100);
   }
 
   /**
@@ -2162,10 +2424,36 @@ export class Session extends EventEmitter {
       this._isWorking = false;
       this._status = 'idle';
       this._lastPromptTime = Date.now();
+      if (wasWorking) this._maybeCaptureOmpSessionId();
       this.emit('idle');
     }
   }
 
+  /**
+   * A brand-new omp session (never yet respawned, so
+   * {@link _pinOmpRespawnId} has never run) has no captured
+   * omp-native session id: `_claudeSessionId` still defaults to this
+   * session's OWN Codeman id from the constructor. Until something aliases
+   * it, the omp history scan's row for this exact conversation (keyed by
+   * omp's own uuid) merges with nothing and shows up a second time. The
+   * first turn going idle is the first moment omp has definitely written
+   * its session file, so resolve and alias it here — best-effort, and only
+   * once (skips once `_claudeSessionId` differs from `this.id`, whether from
+   * this capture or a resume/respawn that already resolved one).
+   */
+  private _maybeCaptureOmpSessionId(): void {
+    if (this.mode !== 'omp' || this._claudeSessionId !== this.id) return;
+    try {
+      const resolvedId = resolveAndClaimOmpSessionId(this.workingDir);
+      if (resolvedId) {
+        this._claudeSessionId = resolvedId;
+        this._ompConfig = { ...this._ompConfig, resumeSessionId: resolvedId };
+      }
+    } catch {
+      // Best-effort: a failed capture just means the next respawn tries again.
+    }
+  }
+
   /**
    * Process expensive parsers (ANSI strip, Ralph, bash tool, token, CLI info, task descriptions).
    * Called on a throttled schedule (every EXPENSIVE_PROCESS_INTERVAL_MS) instead of on every
@@ -2525,10 +2813,21 @@ export class Session extends EventEmitter {
     this._messages = [];
     this._lineBuffer = '';
     this._altScreenSeqCarry = '';
+    // A restarted pane starts with no mouse mode: the new program has not asked
+    // for one yet, and carrying the old CLI's state over would report clicks
+    // into a program that never enabled tracking.
+    this._cliMouseModes.clear();
+    this._syncCliMouseTracking();
     this._markActivity(true);
   }
 
   private _clearAllTimers(): void {
+    // Clear the workspace-trust follow-up read
+    if (this._trustDialogTimer) {
+      clearTimeout(this._trustDialogTimer);
+      this._trustDialogTimer = null;
+    }
+
     // Clear activity timeout to prevent memory leak
     if (this.activityTimeout) {
       clearTimeout(this.activityTimeout);

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

@@ -31,7 +31,13 @@ import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { writeFile, rename } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { dataPath, DEFAULT_TMUX_SOCKET, CODEMAN_INSTANCE } from './config/instance.js';
+import {
+  dataPath,
+  DEFAULT_TMUX_SOCKET,
+  CODEMAN_INSTANCE,
+  SAFE_TMUX_SOCKET_PATTERN,
+  resolveTmuxSocketName,
+} from './config/instance.js';
 import {
   ProcessStats,
   PersistedRespawnConfig,
@@ -46,6 +52,9 @@ import {
   type GeminiConfig,
   type AntigravityConfig,
   type PiConfig,
+  type GrokConfig,
+  type DeepSeekConfig,
+  type OmpConfig,
   type SessionRemote,
   type SessionDocker,
   type DockerCommandMode,
@@ -66,6 +75,7 @@ import {
   hostGatewayAlias,
   resolveDockerClaudeArtifacts,
   resolveDockerCredentialArtifacts,
+  resolveDockerDaemonMountSource,
   type DockerCreateContext,
   type DockerMount,
   type DockerSeedCopy,
@@ -75,11 +85,24 @@ import {
   SAFE_PATH_PATTERN,
   findClaudeDir,
   getClaudeCliVersion,
+  getClaudeNotFoundMessage,
   resolveOpenCodeDir,
+  getOpenCodeNotFoundMessage,
   resolveCodexDir,
+  getCodexNotFoundMessage,
   resolveGeminiDir,
+  getGeminiNotFoundMessage,
   resolveAntigravityDir,
+  getAntigravityNotFoundMessage,
   resolvePiDir,
+  getPiNotFoundMessage,
+  resolveGrokDir,
+  getGrokNotFoundMessage,
+  resolveDeepSeekDir,
+  getDeepSeekNotFoundMessage,
+  resolveDefaultDeepSeekProfile,
+  getOmpNotFoundMessage,
+  resolveOmpDir,
   resolveLocalShell,
   loginShellArgs,
 } from './utils/index.js';
@@ -104,6 +127,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;
@@ -194,9 +218,6 @@ const SAFE_PANE_TARGET_PATTERN = /^(%\d+|\d+)$/;
  *  `codeman` for prod, `codeman-beta` on the beta branch). */
 const DEFAULT_CODEMAN_TMUX_SOCKET = DEFAULT_TMUX_SOCKET;
 
-/** Regex to validate tmux socket names passed to `tmux -L`. */
-const SAFE_TMUX_SOCKET_PATTERN = /^[a-zA-Z0-9_.-]+$/;
-
 /**
  * Separator used in `tmux list-panes -F` output between session name and pid.
  *
@@ -591,9 +612,8 @@ function resolveConfiguredTmuxSocket(): string {
   const raw = process.env.CODEMAN_TMUX_SOCKET ?? DEFAULT_CODEMAN_TMUX_SOCKET;
   if (!SAFE_TMUX_SOCKET_PATTERN.test(raw)) {
     console.warn(`[TmuxManager] Ignoring invalid CODEMAN_TMUX_SOCKET: ${JSON.stringify(raw)}`);
-    return DEFAULT_CODEMAN_TMUX_SOCKET;
   }
-  return raw;
+  return resolveTmuxSocketName();
 }
 
 /** Build the `tmux -L <socket>` command prefix. Socket name is shell-escaped. */
@@ -794,6 +814,120 @@ 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 OMP CLI command with appropriate flags.
+ *
+ * omp reads its model routing and hooks from ~/.omp (agent dir), so no
+ * trust/permission flags are needed: the CLI's own config governs. The only
+ * CLI flags passed are the per-session overrides Codeman knows about.
+ */
+function buildOmpCommand(config?: OmpConfig): string {
+  const parts = ['omp'];
+
+  if (config?.model) {
+    const safeModel = /^[a-zA-Z0-9._\-/]+$/.test(config.model) ? config.model : undefined;
+    if (safeModel) parts.push('--model', safeModel);
+  }
+
+  // --resume and --continue conflict; a valid explicit session id wins,
+  // mirroring the sibling builders (grok/pi/opencode).
+  const safeId =
+    config?.resumeSessionId && /^[a-zA-Z0-9._-]+$/.test(config.resumeSessionId) ? config.resumeSessionId : undefined;
+  if (safeId) {
+    parts.push('--resume', safeId);
+  } else if (config?.continueSession) {
+    parts.push('--continue');
+  }
+
+  return parts.join(' ');
+}
+
 /**
  * Build the spawn command for any session mode.
  * Shared by createSession() and respawnPane() to avoid duplication.
@@ -837,6 +971,9 @@ export function buildSpawnCommand(options: {
   geminiConfig?: GeminiConfig;
   antigravityConfig?: AntigravityConfig;
   piConfig?: PiConfig;
+  grokConfig?: GrokConfig;
+  deepSeekConfig?: DeepSeekConfig;
+  ompConfig?: OmpConfig;
   resumeSessionId?: string;
   effort?: EffortLevel;
   /** Codeman session name, passed to claude as `--name` (version-gated, sanitized; local spawns only). */
@@ -886,6 +1023,15 @@ 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);
+  }
+  if (options.mode === 'omp') {
+    return buildOmpCommand(options.ompConfig);
+  }
   // #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
@@ -1069,7 +1215,6 @@ export function buildRemoteKillCommand(options: { remote: SessionRemote; session
  * adopts/resizes/respawns our session (same defence as the remote socket).
  */
 const DOCKER_TMUX_SOCKET = 'codeman-docker';
-
 /**
  * Deterministic, reattach-stable in-container tmux session name. Derived from the
  * same stable field the local muxName uses (first 8 chars of the sessionId), so a
@@ -1101,6 +1246,11 @@ 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':
+    case 'omp':
+      return `${modeCommand} --resume ${resumeId}`;
     default:
       return modeCommand; // shell / opencode: no resume
   }
@@ -1205,8 +1355,23 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string {
   const startFailMsg = shellescape(`Codeman: container ${docker.containerName} failed to start (docker daemon down?)`);
 
   const imageCheck = `${base} image inspect ${image} >/dev/null 2>&1 || { echo ${imageMissingMsg}; exit 1; }`;
-  // create-if-missing (idempotent): reconnect / boot recovery re-runs this exact chain.
-  const ensure = `${base} inspect ${name} >/dev/null 2>&1 || ${base} ${createArgs}`;
+  // create-if-missing (idempotent): reconnect / boot recovery re-runs this exact
+  // chain. A daemon without swap accounting warns whenever --memory is present,
+  // even when --memory-swap is omitted. In compatibility mode, retain the memory
+  // cap and filter ONLY that exact warning; all other stdout/stderr and the real
+  // create exit status are preserved so mount/config failures remain visible.
+  // A session-unique file avoids shell variables and command substitution, both
+  // of which would be expanded too early by the nested bash/tmux launch layers.
+  const createOutputPath = shellescape(`/tmp/codeman-create-${sessionId}.log`);
+  const filteredCreateOutput = `sed '/^WARNING: Your kernel does not support swap limit capabilities or the cgroup is not mounted\\. Memory limited without swap\\.$/d' ${createOutputPath}`;
+  const removeCreateOutput = `rm -f ${createOutputPath}`;
+  const createCommand = createContext.disableSwapLimit
+    ? `{ if ${base} ${createArgs} >${createOutputPath} 2>&1; ` +
+      `then ${filteredCreateOutput}; ${removeCreateOutput}; ` +
+      `elif ${base} inspect ${name} >/dev/null 2>&1; then ${removeCreateOutput}; ` +
+      `else ${filteredCreateOutput} >&2; ${removeCreateOutput}; false; fi; }`
+    : `${base} ${createArgs}`;
+  const ensure = `${base} inspect ${name} >/dev/null 2>&1 || ${createCommand}`;
   const start = `${base} start ${name} >/dev/null 2>&1 || { echo ${startFailMsg}; exit 1; }`;
   // Seed writable credential config from read-only host mounts ONCE per container
   // (guarded by [ -e ] so reconnects never clobber in-container config; `cp -a` for
@@ -1317,11 +1482,18 @@ export function resolveDockerLaunchOptions(
     sessionId,
     instance: CODEMAN_INSTANCE,
     userArgs,
-    credentialMounts,
-    extraMounts,
+    credentialMounts: credentialMounts.map((mount) => ({
+      ...mount,
+      src: resolveDockerDaemonMountSource(mount.src, home, process.env.CODEMAN_DOCKER_HOST_HOME),
+    })),
+    extraMounts: extraMounts.map((mount) => ({
+      ...mount,
+      src: resolveDockerDaemonMountSource(mount.src, home, process.env.CODEMAN_DOCKER_HOST_HOME),
+    })),
     envCreate,
     addHostGateway: !isDesktop,
     gatewayAlias,
+    disableSwapLimit: process.env.CODEMAN_DOCKER_DISABLE_SWAP_LIMIT === '1',
   };
 
   const execEnv: Record<string, string> = {
@@ -1562,6 +1734,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   private reconnectGuard: Set<string> = new Set();
 
   private trueColorConfigured = false;
+  /** tmux 3.7+ can resize pane history after creation; older releases cannot. */
+  private liveHistoryResizeSupported: boolean | null = null;
 
   constructor() {
     super();
@@ -1580,6 +1754,26 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     return tmuxCommand(this.tmuxSocket);
   }
 
+  private supportsLiveHistoryResize(): boolean {
+    if (this.liveHistoryResizeSupported !== null) return this.liveHistoryResizeSupported;
+
+    try {
+      const output = execSync(`${this.tmux()} -V`, {
+        encoding: 'utf8',
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const match = output.match(/(?:^|\D)(\d+)\.(\d+)/);
+      const major = match ? Number(match[1]) : 0;
+      const minor = match ? Number(match[2]) : 0;
+      this.liveHistoryResizeSupported = major > 3 || (major === 3 && minor >= 7);
+    } catch {
+      // Unknown versions take the legacy path required by tmux <3.7.
+      this.liveHistoryResizeSupported = false;
+    }
+    return this.liveHistoryResizeSupported;
+  }
+
   // Load saved sessions from disk (NEVER called in test mode)
   private loadSessions(): void {
     if (IS_TEST_MODE) return;
@@ -1669,10 +1863,24 @@ 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' ||
+      mode === 'omp'
         ? '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' ||
+      mode === 'omp'
+        ? ['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,
@@ -1767,6 +1975,18 @@ 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 };
+    }
+    if (mode === 'omp') {
+      const dir = resolveOmpDir();
+      return { pathExport: dir ? `export PATH="${dir}:$PATH" && ` : '', dir };
+    }
     return { pathExport: '', dir: null };
   }
 
@@ -1797,6 +2017,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).
@@ -1816,6 +2095,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
+      ompConfig,
       resumeSessionId,
       envOverrides,
       effort,
@@ -1853,29 +2135,37 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       return session;
     }
 
-    // Resolve CLI binary directory based on mode
+    // Resolve CLI binary directory based on mode. The not-found messages come
+    // from the resolvers (formatCliNotFoundMessage) so the error names WHERE it
+    // looked — server PATH, login shell, checked directories — instead of just
+    // asserting the CLI is missing (the classic systemd/launchd PATH trap).
     const { pathExport, dir: cliDir } = this.buildPathExport(mode);
     if (mode === 'claude' && !cliDir) {
-      throw new Error('Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash');
+      throw new Error(getClaudeNotFoundMessage());
     }
     if (mode === 'opencode' && !cliDir) {
-      throw new Error('OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash');
+      throw new Error(getOpenCodeNotFoundMessage());
     }
     if (mode === 'codex' && !cliDir) {
-      throw new Error('Codex CLI not found. Install with: npm install -g @openai/codex');
+      throw new Error(getCodexNotFoundMessage());
     }
     if (mode === 'gemini' && !cliDir) {
-      throw new Error('Gemini CLI not found. Install with: npm install -g @google/gemini-cli');
+      throw new Error(getGeminiNotFoundMessage());
     }
     if (mode === 'antigravity' && !cliDir) {
-      throw new Error(
-        'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash'
-      );
+      throw new Error(getAntigravityNotFoundMessage());
     }
     if (mode === 'pi' && !cliDir) {
-      throw new Error(
-        'Pi CLI not found. Install with: npm install -g --ignore-scripts @earendil-works/pi-coding-agent'
-      );
+      throw new Error(getPiNotFoundMessage());
+    }
+    if (mode === 'deepseek' && !cliDir) {
+      throw new Error(getDeepSeekNotFoundMessage());
+    }
+    if (mode === 'grok' && !cliDir) {
+      throw new Error(getGrokNotFoundMessage());
+    }
+    if (mode === 'omp' && !cliDir) {
+      throw new Error(getOmpNotFoundMessage());
     }
 
     const envExportsStr = this.buildEnvExports(sessionId, muxName, mode).join(' && ');
@@ -1891,6 +2181,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
+      ompConfig,
       resumeSessionId,
       effort,
       sessionName: name,
@@ -1921,7 +2214,16 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       // launched in TMUX_LAUNCH_CWD (/tmp) rather than the real workingDir: a FUSE/rclone
       // mount that isn't ready yet makes `getcwd` fail and breaks the spawn (see #110). The
       // pane cd's into workingDir below via respawn-pane.
-      execSync(`${this.tmux()} new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD}`, {
+      // tmux <3.7 allocates history only at pane creation, so its global default
+      // must be set immediately BEFORE new-session. tmux 3.7+ can resize a pane
+      // after creation; target only the new session there because changing the
+      // global option can resize (and when lowered, trim) unrelated live panes.
+      const safeHistoryLimit =
+        Number.isSafeInteger(historyLimit) && historyLimit > 0 ? Math.trunc(historyLimit) : DEFAULT_TMUX_HISTORY_LIMIT;
+      const createSessionCommand = this.supportsLiveHistoryResize()
+        ? `${this.tmux()} new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD} \\; set-option -t "${muxName}" history-limit ${safeHistoryLimit}`
+        : `${this.tmux()} set-option -g history-limit ${safeHistoryLimit} \\; new-session -ds "${muxName}" -c ${TMUX_LAUNCH_CWD} \\; set-option -t "${muxName}" history-limit ${safeHistoryLimit}`;
+      execSync(createSessionCommand, {
         cwd: TMUX_LAUNCH_CWD,
         timeout: EXEC_TIMEOUT_MS,
         stdio: 'ignore',
@@ -1950,6 +2252,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.
@@ -1986,16 +2292,6 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
           .catch(() => {
             /* Already set globally as fallback */
           }),
-        // Raise tmux scrollback from its 2000-line default so re-attach preserves
-        // more context. Intentionally exceeds the xterm-side DEFAULT_SCROLLBACK (50k
-        // in constants.js), which stays lower to protect browser/mobile memory.
-        execAsync(`${this.tmux()} set-option -t "${muxName}" history-limit ${historyLimit}`, {
-          timeout: EXEC_TIMEOUT_MS,
-        })
-          .then(() => {})
-          .catch(() => {
-            /* Non-critical — falls back to tmux default */
-          }),
       ];
 
       // Enable 24-bit true color passthrough — server-wide, set once per lifetime
@@ -2116,10 +2412,12 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
+      ompConfig,
       resumeSessionId,
       envOverrides,
       effort,
-      historyLimit = DEFAULT_TMUX_HISTORY_LIMIT,
       remote,
       docker,
       name,
@@ -2130,16 +2428,6 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
 
-    // Re-apply the configured tmux history-limit after respawn (kept in sync
-    // with the live setting via setHistoryLimit()).
-    if (!IS_TEST_MODE) {
-      await execAsync(`${this.tmux()} set-option -t ${shellescape(muxName)} history-limit ${historyLimit}`, {
-        timeout: EXEC_TIMEOUT_MS,
-      }).catch(() => {
-        /* Non-critical — keeps existing tmux history-limit */
-      });
-    }
-
     // Resolve CLI binary directory based on mode
     const { pathExport } = this.buildPathExport(mode);
 
@@ -2156,6 +2444,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       geminiConfig,
       antigravityConfig,
       piConfig,
+      grokConfig,
+      deepSeekConfig,
+      ompConfig,
       resumeSessionId,
       effort,
       sessionName: name,
@@ -2180,6 +2471,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);
@@ -2998,9 +3293,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   }
 
   /**
-   * Apply a tmux history-limit to all tracked sessions (e.g. when the user
-   * changes the terminal-history setting). Invalid limits fall back to the
-   * default. Best-effort per session.
+   * Apply a tmux history limit. tmux 3.7+ safely targets tracked live sessions;
+   * older releases can only change the global default for future panes. Invalid
+   * limits fall back to the default.
    */
   async setHistoryLimit(limit: number): Promise<void> {
     const safeLimit = Number.isSafeInteger(limit) && limit > 0 ? Math.trunc(limit) : DEFAULT_TMUX_HISTORY_LIMIT;
@@ -3009,12 +3304,22 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       return;
     }
 
-    const updates = Array.from(this.sessions.values()).map((session) =>
-      execAsync(`${this.tmux()} set-option -t ${shellescape(session.muxName)} history-limit ${safeLimit}`, {
-        timeout: EXEC_TIMEOUT_MS,
-      })
-    );
-    await Promise.allSettled(updates);
+    if (this.supportsLiveHistoryResize()) {
+      const updates = Array.from(this.sessions.values()).map((session) =>
+        execAsync(`${this.tmux()} set-option -t ${shellescape(session.muxName)} history-limit ${safeLimit}`, {
+          timeout: EXEC_TIMEOUT_MS,
+        })
+      );
+      await Promise.allSettled(updates);
+      return;
+    }
+
+    await execAsync(`${this.tmux()} set-option -g history-limit ${safeLimit}`, {
+      timeout: EXEC_TIMEOUT_MS,
+    }).catch(() => {
+      // No tmux server yet is fine: legacy createSession sets the same default
+      // immediately before it creates the first pane.
+    });
   }
 
   /**

src/tui/tui-ansi.ts

@@ -0,0 +1,598 @@
+/**
+ * @fileoverview Pure ANSI helpers for the TUI preview pane.
+ *
+ * The preview shows the tail of a session's raw terminal stream, which is
+ * xterm-bound bytes: SGR colors, cursor jumps, OSC titles, DECSET modes and
+ * carriage-return repaints. This is NOT a terminal emulator. It reconstructs a
+ * readable, color-preserving tail: SGR survives, everything else that steers a
+ * cursor is dropped, and a `\r` is honored as "back to column 0" so a spinner
+ * that repaints its line 200 times contributes one line instead of 200.
+ *
+ * CURSOR ADDRESSING (`ESC [ r ; c H`) is honored too, and it has to be: an Ink
+ * TUI like Claude Code repaints by ROW and emits almost no newlines, so
+ * dropping those sequences collapses a whole screen into one unreadable line
+ * (measured against a live pane, 2026-08-16). A jump to column 1 starts a new
+ * display line, a jump within a row moves the write position, which is the same
+ * reading `normalizeCapturedFrame` in `web/approval-inbox.ts` takes of the same
+ * kind of frame.
+ *
+ * Two approximations are deliberate, because the alternative is an emulator:
+ * a carriage-return overwrite counts CODE POINTS, not display columns (so a
+ * repaint over CJK text can land one cell off), and tab stops are counted the
+ * same way. Neither can corrupt output, they only shift a repaint's alignment.
+ * Absolute ROW numbers are ignored as well: rows arrive in the order they are
+ * painted, which for a tail is the order worth reading.
+ *
+ * @module tui/tui-ansi
+ */
+
+const ESC = 0x1b;
+const BEL = 0x07;
+const ST_C1 = 0x9c;
+const DEL = 0x7f;
+
+/** SGR reset, appended by `clipStyledLine` so a clipped line cannot bleed. */
+export const SGR_RESET = '\x1b[0m';
+
+const TAB_WIDTH = 8;
+/** Cap on remembered SGR sequences per cell, so a pathological stream cannot grow one unboundedly. */
+const MAX_ACTIVE_SGR = 32;
+/** Ceiling on a display line's cells: a stream may address column 99999, a terminal has none. */
+const MAX_LINE_CELLS = 1000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Escape-sequence scanning
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface EscapeScan {
+  /** Index just past the sequence; `text.length` for a truncated one. */
+  next: number;
+  /** The sequence itself, only when it is SGR (`CSI ... m`) and therefore kept. */
+  sgr?: string;
+  /** 1-based column of a cursor-position sequence (`CSI r ; c H` or `f`). */
+  column?: number;
+  /** 1-based row of that same sequence. Row 1 means a repaint is starting. */
+  row?: number;
+}
+
+/** The row and column a `CSI r ; c H` addresses. Both parameters default to 1. */
+function cursorPosition(params: string): { row: number; column: number } {
+  const parts = params.split(';');
+  const read = (index: number): number => {
+    const value = Number.parseInt(parts[index] ?? '', 10);
+    return Number.isSafeInteger(value) && value > 0 ? value : 1;
+  };
+  return { row: read(0), column: read(1) };
+}
+
+/** Scan a CSI body starting at `from` (params, then intermediates, then a final byte). */
+function readCsi(text: string, start: number, from: number, keepSgr: boolean): EscapeScan {
+  let j = from;
+  while (j < text.length && text.charCodeAt(j) >= 0x30 && text.charCodeAt(j) <= 0x3f) j++;
+  while (j < text.length && text.charCodeAt(j) >= 0x20 && text.charCodeAt(j) <= 0x2f) j++;
+  if (j >= text.length) return { next: text.length };
+  const next = j + 1;
+  if (keepSgr && text[j] === 'm') return { next, sgr: text.slice(start, next) };
+  if (keepSgr && (text[j] === 'H' || text[j] === 'f')) {
+    return { next, ...cursorPosition(text.slice(from, j)) };
+  }
+  return { next };
+}
+
+/** Scan an OSC/DCS/PM/APC body: everything up to BEL, C1 ST or `ESC \`. */
+function readStringSequence(text: string, from: number): number {
+  let j = from;
+  while (j < text.length) {
+    const code = text.charCodeAt(j);
+    if (code === BEL || code === ST_C1) return j + 1;
+    if (code === ESC && text[j + 1] === '\\') return j + 2;
+    j++;
+  }
+  return text.length;
+}
+
+/** Scan the escape sequence starting at `i` (which must be an ESC). */
+function readEscape(text: string, i: number): EscapeScan {
+  const second = text[i + 1];
+  if (second === undefined) return { next: text.length };
+  if (second === '[') return readCsi(text, i, i + 2, true);
+  if (second === ']' || second === 'P' || second === 'X' || second === '^' || second === '_') {
+    return { next: readStringSequence(text, i + 2) };
+  }
+  // Charset / character-set selection: one more byte belongs to the sequence.
+  if (second === '(' || second === ')' || second === '*' || second === '+' || second === '#' || second === '%') {
+    return { next: Math.min(text.length, i + 3) };
+  }
+  return { next: i + 2 };
+}
+
+/** Scan a single-byte C1 control at `i` (0x80-0x9f). */
+function readC1(text: string, i: number): number {
+  const code = text.charCodeAt(i);
+  if (code === 0x9b) return readCsi(text, i, i + 1, false).next;
+  if (code === 0x90 || code === 0x9d || code === 0x9e || code === 0x9f) return readStringSequence(text, i + 1);
+  return i + 1;
+}
+
+function isC1(code: number): boolean {
+  return code >= 0x80 && code <= 0x9f;
+}
+
+/** `CSI 0 m`, `CSI m` and `CSI 0;0 m` all mean "back to plain". */
+function isSgrReset(seq: string): boolean {
+  const params = seq.slice(2, -1);
+  return params === '' || /^0(?:;0)*$/.test(params);
+}
+
+/**
+ * Fold one SGR sequence into the active set. Sequences accumulate in arrival
+ * order (a later color simply wins when replayed), a reset clears them, and a
+ * repeat moves rather than duplicates.
+ */
+function applySgr(active: string[], seq: string): string[] {
+  if (isSgrReset(seq)) return [];
+  const next = active.filter((s) => s !== seq);
+  next.push(seq);
+  return next.length > MAX_ACTIVE_SGR ? next.slice(-MAX_ACTIVE_SGR) : next;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Display width
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Combining marks, variation selectors and other zero-advance code points.
+ * Pragmatic, not exhaustive: enough that accents and emoji modifiers do not
+ * inflate a measured width.
+ */
+const ZERO_WIDTH_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0x0300, 0x036f],
+  [0x0483, 0x0489],
+  [0x0591, 0x05bd],
+  [0x05bf, 0x05bf],
+  [0x0610, 0x061a],
+  [0x064b, 0x065f],
+  [0x0670, 0x0670],
+  [0x06d6, 0x06dc],
+  [0x0e31, 0x0e31],
+  [0x0e34, 0x0e3a],
+  [0x0e47, 0x0e4e],
+  [0x200b, 0x200f],
+  [0x2028, 0x202e],
+  [0x2060, 0x2064],
+  [0x20d0, 0x20f0],
+  [0xfe00, 0xfe0f],
+  [0xfe20, 0xfe2f],
+  [0xfeff, 0xfeff],
+];
+
+/**
+ * East Asian Wide + Fullwidth, plus the standalone code points UAX #11 marks
+ * Wide because they are emoji-presentation by default. This repo ships a zh-CN
+ * locale, so CJK correctness is the point; exhaustive Unicode is not required,
+ * but the scattered BMP entries below are not optional either: `✋` (U+270B) is
+ * one of them and it is a glyph this TUI draws in every waiting row, so getting
+ * it wrong mis-pads a column on every frame.
+ */
+const WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0x1100, 0x115f],
+  [0x231a, 0x231b],
+  [0x23e9, 0x23ec],
+  [0x23f0, 0x23f0],
+  [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe],
+  [0x2614, 0x2615],
+  [0x2648, 0x2653],
+  [0x267f, 0x267f],
+  [0x2693, 0x2693],
+  [0x26a1, 0x26a1],
+  [0x26aa, 0x26ab],
+  [0x26bd, 0x26be],
+  [0x26c4, 0x26c5],
+  [0x26ce, 0x26ce],
+  [0x26d4, 0x26d4],
+  [0x26ea, 0x26ea],
+  [0x26f2, 0x26f3],
+  [0x26f5, 0x26f5],
+  [0x26fa, 0x26fa],
+  [0x26fd, 0x26fd],
+  [0x2705, 0x2705],
+  [0x270a, 0x270b],
+  [0x2728, 0x2728],
+  [0x274c, 0x274c],
+  [0x274e, 0x274e],
+  [0x2753, 0x2755],
+  [0x2757, 0x2757],
+  [0x2795, 0x2797],
+  [0x27b0, 0x27b0],
+  [0x27bf, 0x27bf],
+  [0x2b1b, 0x2b1c],
+  [0x2b50, 0x2b50],
+  [0x2b55, 0x2b55],
+  [0x2e80, 0x303e],
+  [0x3041, 0x33ff],
+  [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff],
+  [0xa000, 0xa4cf],
+  [0xa960, 0xa97f],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe10, 0xfe19],
+  [0xfe30, 0xfe6f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x1f004, 0x1f004],
+  [0x1f0cf, 0x1f0cf],
+  [0x1f18e, 0x1f18e],
+  [0x1f191, 0x1f19a],
+  [0x1f200, 0x1f320],
+  [0x1f32d, 0x1f335],
+  [0x1f337, 0x1f37c],
+  [0x1f37e, 0x1f393],
+  [0x1f3a0, 0x1f3ca],
+  [0x1f3cf, 0x1f3d3],
+  [0x1f3e0, 0x1f3f0],
+  [0x1f3f4, 0x1f3f4],
+  [0x1f3f8, 0x1f43e],
+  [0x1f440, 0x1f440],
+  [0x1f442, 0x1f4fc],
+  [0x1f4ff, 0x1f53d],
+  [0x1f54b, 0x1f54e],
+  [0x1f550, 0x1f567],
+  [0x1f57a, 0x1f57a],
+  [0x1f595, 0x1f596],
+  [0x1f5a4, 0x1f5a4],
+  [0x1f5fb, 0x1f64f],
+  [0x1f680, 0x1f6c5],
+  [0x1f6cc, 0x1f6cc],
+  [0x1f6d0, 0x1f6d2],
+  [0x1f6eb, 0x1f6ec],
+  [0x1f6f4, 0x1f6fc],
+  [0x1f7e0, 0x1f7eb],
+  [0x1f90c, 0x1f93a],
+  [0x1f93c, 0x1f945],
+  [0x1f947, 0x1f9ff],
+  [0x1fa70, 0x1faff],
+  [0x20000, 0x2fffd],
+  [0x30000, 0x3fffd],
+];
+
+function inRanges(cp: number, ranges: ReadonlyArray<readonly [number, number]>): boolean {
+  for (const [lo, hi] of ranges) {
+    if (cp < lo) return false;
+    if (cp <= hi) return true;
+  }
+  return false;
+}
+
+/** Columns one code point advances the cursor by: 0, 1 or 2. */
+export function charWidth(codePoint: number): number {
+  if (codePoint < 0x20 || (codePoint >= DEL && codePoint <= 0x9f)) return 0;
+  if (inRanges(codePoint, ZERO_WIDTH_RANGES)) return 0;
+  if (inRanges(codePoint, WIDE_RANGES)) return 2;
+  return 1;
+}
+
+/** Display width of a string: escape sequences take no columns, CJK takes two. */
+export function visibleWidth(text: string): number {
+  let width = 0;
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === ESC) {
+      i = readEscape(text, i).next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(text, i);
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = text.codePointAt(i) as number;
+    i += cp > 0xffff ? 2 : 1;
+    width += charWidth(cp);
+  }
+  return width;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Raw stream to display lines
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** One printed code point (plus any combining marks) and the SGR state under it. */
+interface Cell {
+  text: string;
+  sgr: string;
+}
+
+/**
+ * Replay cells into a string, emitting an SGR change only where the state
+ * actually changes and closing the line so it is self-contained.
+ */
+function renderCells(cells: Cell[]): string {
+  let out = '';
+  let active = '';
+  for (const cell of cells) {
+    if (cell.sgr !== active) {
+      if (active !== '') out += SGR_RESET;
+      out += cell.sgr;
+      active = cell.sgr;
+    }
+    out += cell.text;
+  }
+  if (active !== '') out += SGR_RESET;
+  return out;
+}
+
+/**
+ * Turn a raw terminal stream into display lines: SGR preserved, every other
+ * escape sequence dropped, `\r` treated as a return to column 0 (the following
+ * text overwrites what is there), tabs expanded, other control characters
+ * dropped.
+ *
+ * Splitting matches `String.split('\n')`, so `''` yields `['']` and a trailing
+ * newline yields a trailing empty line.
+ */
+/**
+ * Glyphs a CLI draws as chrome that a plain terminal font very often has no
+ * coverage for, and the ASCII that means the same thing.
+ *
+ * ⚠️ This is NOT a substitute for the glyph TIER. The tier answers "can this
+ * terminal do Unicode at all", which is a locale question, and it says yes for
+ * exactly the terminals this table exists for: a beta tester's font rendered
+ * `·`, `─`, `│` and `▶` perfectly while drawing claude's `❯` prompt and its
+ * `⏵⏵` mode marker as empty boxes. Coverage is per-glyph and undetectable from
+ * here, so the rare ones are folded and the common ones are left alone.
+ *
+ * Kept deliberately SHORT. Every entry is a glyph seen rendering as tofu in a
+ * real terminal, not a guess, and each maps to the arrow it already looks like.
+ */
+const PREVIEW_GLYPH_FOLD: ReadonlyMap<string, string> = new Map([
+  ['\u276F', '>'], // ❯ heavy right-pointing angle quotation mark (claude, starship, zsh prompts)
+  ['\u276E', '<'], // ❮
+  ['\u23F5', '>'], // ⏵ black medium right-pointing triangle (claude's bypass-permissions marker)
+  ['\u23F4', '<'], // ⏴
+  ['\u23F6', '^'], // ⏶
+  ['\u23F7', 'v'], // ⏷
+  ['\u2771', '>'], // ❱
+  ['\u2770', '<'], // ❰
+  // claude's own working/done spinner cycles through these, and they are the
+  // same sparse-Dingbats class as `❯`: the animated line is exactly where a
+  // reader looks, so tofu there is the most visible kind.
+  ['\u2722', '*'], // ✢
+  ['\u2733', '*'], // ✳
+  ['\u2217', '*'], // ∗
+  ['\u273B', '*'], // ✻
+  ['\u273D', '*'], // ✽
+  ['\u2734', '*'], // ✴
+  ['\u26A0', '!'], // ⚠ Misc Symbols, and emoji-presentation on many terminals
+]);
+
+/**
+ * Replace preview glyphs a plain font is likely to draw as an empty box.
+ *
+ * Applied to ANOTHER program's output on its way into the preview pane, never
+ * to the TUI's own chrome, and skipped at the `nerd` tier where the user has
+ * declared a font that can draw anything.
+ */
+export function foldPreviewGlyphs(line: string): string {
+  let out = '';
+  for (const char of line) out += PREVIEW_GLYPH_FOLD.get(char) ?? char;
+  return out;
+}
+
+export function toDisplayLines(raw: string): string[] {
+  const lines: string[] = [];
+  let cells: Cell[] = [];
+  let col = 0;
+  let active: string[] = [];
+  let sgr = '';
+
+  const endLine = (): void => {
+    lines.push(renderCells(cells));
+    cells = [];
+    col = 0;
+  };
+
+  /**
+   * Park the write position at a column, padding the gap so the cell array
+   * never grows a hole (a hole would crash the replay, and a stream can address
+   * any column it likes).
+   */
+  const moveTo = (column: number): void => {
+    const target = Math.min(column, MAX_LINE_CELLS);
+    while (cells.length < target) cells.push({ text: ' ', sgr: '' });
+    col = target;
+  };
+
+  const write = (text: string, width: number): void => {
+    if (width === 0) {
+      // A combining mark belongs to the character it follows, never to a cell
+      // of its own: keeping them together is what stops a clip from severing
+      // an accent from its base letter.
+      if (col > 0) cells[col - 1].text += text;
+      return;
+    }
+    cells[col] = { text, sgr };
+    col++;
+  };
+
+  let i = 0;
+  while (i < raw.length) {
+    const code = raw.charCodeAt(i);
+    if (code === ESC) {
+      const scan = readEscape(raw, i);
+      if (scan.sgr !== undefined) {
+        active = applySgr(active, scan.sgr);
+        sgr = active.join('');
+      } else if (scan.row === 1 && scan.column === 1) {
+        // ⚠️ A HOME is a full-screen app announcing that it is repainting from
+        // the top, and everything already on screen is about to be overwritten
+        // in place. This replay is line-based and cannot overwrite, so the
+        // faithful equivalent is to start over — without it every repaint was
+        // APPENDED, and a claude pane's tail carried fifty stacked copies of
+        // the same frame. The preview then showed the last N lines, which on a
+        // tall terminal spanned two of them (reported from the beta as the
+        // overview showing the session twice).
+        lines.length = 0;
+        cells = [];
+        col = 0;
+      } else if (scan.column !== undefined) {
+        // Column 1 is a fresh row, which is the only thing a repainting TUI
+        // gives us to split lines on.
+        if (scan.column <= 1) endLine();
+        else moveTo(scan.column - 1);
+      }
+      i = scan.next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(raw, i);
+      continue;
+    }
+    if (code === 0x0a) {
+      endLine();
+      i++;
+      continue;
+    }
+    if (code === 0x0d) {
+      col = 0;
+      i++;
+      continue;
+    }
+    if (code === 0x09) {
+      const stop = TAB_WIDTH - (col % TAB_WIDTH);
+      for (let n = 0; n < stop; n++) write(' ', 1);
+      i++;
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = raw.codePointAt(i) as number;
+    const text = String.fromCodePoint(cp);
+    i += text.length;
+    write(text, charWidth(cp));
+  }
+  endLine();
+  return lines;
+}
+
+/**
+ * The parameter bytes plus final byte of a CSI sequence whose `ESC [` was cut
+ * off. Requires at least one parameter byte, so ordinary text starting with a
+ * letter is never mistaken for one.
+ */
+const SEVERED_CSI = /^[0-9;?:<>=]+[A-Za-z]/;
+
+/**
+ * Drop the remains of an escape sequence a byte-sliced tail begins in the
+ * middle of.
+ *
+ * `GET /api/sessions/:id/terminal?tail=N` cuts the buffer at a byte offset, so
+ * a tail can start inside `ESC [ 12 ; 1 H` and hand the parser `;1H` as text,
+ * which is exactly what it then prints (observed against a live Claude pane).
+ * Only the severed head is dropped, never a whole line.
+ */
+export function dropSeveredEscape(raw: string): string {
+  return raw.replace(SEVERED_CSI, '');
+}
+
+/**
+ * Drop every escape sequence, keeping the visible text. Needed because the
+ * preview carries the session's OWN colors: under NO_COLOR the frame must not
+ * smuggle them back in.
+ */
+export function stripStyles(text: string): string {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (code === ESC) {
+      i = readEscape(text, i).next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(text, i);
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = text.codePointAt(i) as number;
+    const size = cp > 0xffff ? 2 : 1;
+    out += text.slice(i, i + size);
+    i += size;
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Clipping and padding
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Clip a line that carries SGR to `width` display columns, keeping the styling
+ * that is active up to the clip point and closing it with a reset. Never splits
+ * a code point, a combining sequence or an escape sequence, and never emits
+ * half of a double-width character (the cell is dropped instead).
+ */
+export function clipStyledLine(line: string, width: number): string {
+  if (width <= 0) return '';
+  let out = '';
+  let used = 0;
+  let active: string[] = [];
+  // Styles are emitted lazily, right before the character that wears them, so a
+  // sequence sitting exactly on the clip boundary is not carried into a line it
+  // no longer styles.
+  let emitted = '';
+  let i = 0;
+  while (i < line.length) {
+    const code = line.charCodeAt(i);
+    if (code === ESC) {
+      const scan = readEscape(line, i);
+      if (scan.sgr !== undefined) active = applySgr(active, scan.sgr);
+      i = scan.next;
+      continue;
+    }
+    if (isC1(code)) {
+      i = readC1(line, i);
+      continue;
+    }
+    if (code < 0x20 || code === DEL) {
+      i++;
+      continue;
+    }
+    const cp = line.codePointAt(i) as number;
+    const w = charWidth(cp);
+    if (used + w > width) break;
+    const style = active.join('');
+    if (style !== emitted) {
+      if (emitted !== '') out += SGR_RESET;
+      out += style;
+      emitted = style;
+    }
+    out += String.fromCodePoint(cp);
+    used += w;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return emitted !== '' ? out + SGR_RESET : out;
+}
+
+/**
+ * Pad or clip to exactly `width` display columns. A clip that lands on a
+ * double-width boundary leaves one column short, so the pad runs after it.
+ */
+export function padDisplay(text: string, width: number): string {
+  if (width <= 0) return '';
+  const w = visibleWidth(text);
+  if (w === width) return text;
+  if (w < width) return text + ' '.repeat(width - w);
+  const clipped = clipStyledLine(text, width);
+  return clipped + ' '.repeat(Math.max(0, width - visibleWidth(clipped)));
+}

src/tui/tui-approvals.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Pure reading of an approvals-inbox item: what the card says,
+ * which keys are live for it, and which of them just appeared.
+ *
+ * This is the half of "answer the dialog from the dashboard" that can be stated
+ * as a function of the item. The IO half (`POST /api/approvals/:id/answer`)
+ * lives in `tui-client.ts`, and the server re-captures the pane before it aims
+ * any keystroke, so a card that went stale is refused rather than mis-answered.
+ *
+ * The key matrix is deliberately narrow, because the alternative is typing a
+ * digit into whatever now has focus:
+ *
+ * | kind       | y            | n                      | 1-9                       |
+ * | ---------- | ------------ | ---------------------- | ------------------------- |
+ * | permission | approve      | the parsed "No" option, | only digits the server     |
+ * | question   | approve      | else Esc               | actually parsed off screen |
+ * | idle       | not a dialog: `p` (the composer) is the reply path      |
+ *
+ * A digit that is not among the parsed options returns null, which is what lets
+ * the caller fall back to the list's own 1-9 jump instead of sending a keystroke
+ * the dialog has no answer for.
+ *
+ * PURE: no IO, no timers, no `process.*`.
+ *
+ * @module tui/tui-approvals
+ */
+
+import type { ApprovalItem, ApprovalOption } from '../web/approval-inbox.js';
+import type { TuiApprovalAnswer } from './tui-client.js';
+
+/** Card severity, in the same red/yellow vocabulary the web inbox uses. */
+export type TuiApprovalTone = 'err' | 'warn';
+
+export interface TuiApprovalCard {
+  tone: TuiApprovalTone;
+  /** One line: what is being asked. */
+  title: string;
+  /** Extra context, one entry per line, already trimmed. May be empty. */
+  detail: string[];
+  /** Numbered choices parsed off the pane, empty when the frame did not parse. */
+  options: ApprovalOption[];
+  /** What the user can press right now, in words. */
+  hint: string;
+}
+
+/** Longest single line the card contributes before the renderer clips it. */
+const MAX_CARD_TEXT = 400;
+
+function clean(text: string | undefined): string {
+  return (text ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_CARD_TEXT);
+}
+
+export function approvalTone(item: ApprovalItem): TuiApprovalTone {
+  return item.kind === 'idle' ? 'warn' : 'err';
+}
+
+/**
+ * What the card says. Permission prompts lead with the tool (that is the whole
+ * question), questions lead with their message, and an idle prompt says what it
+ * is, since there is nothing to approve.
+ */
+export function approvalCard(item: ApprovalItem): TuiApprovalCard {
+  const options = item.options ?? [];
+  const message = clean(item.message);
+  const summary = clean(item.toolSummary) || clean(item.toolName);
+
+  if (item.kind === 'idle') {
+    return {
+      tone: 'warn',
+      title: message || 'waiting for your reply',
+      detail: [],
+      options: [],
+      hint: 'p to reply',
+    };
+  }
+
+  const title =
+    item.kind === 'permission'
+      ? `requests: ${summary || 'permission'}`
+      : message || `question: ${summary || 'Claude is asking'}`;
+  const detail: string[] = [];
+  if (item.kind === 'permission' && message && message !== summary) detail.push(message);
+
+  return {
+    tone: 'err',
+    title,
+    detail,
+    options,
+    hint: options.length > 0 ? 'y approve · n deny · digit chooses' : 'y approve · n deny',
+  };
+}
+
+/**
+ * The parsed option that means "no". Claude renders it as `3. No, tell Claude
+ * what to do (esc)`, and answering with its digit is the same keystroke the
+ * dialog itself is waiting for; without a parsed one the answer route's `deny`
+ * sends Esc, which every dialog understands.
+ */
+export function approvalDenyOption(item: ApprovalItem): number | null {
+  const match = (item.options ?? []).find((option) => /^no\b/i.test(option.label));
+  return match ? match.n : null;
+}
+
+/**
+ * The answer one key produces, or null when that key means nothing here (so the
+ * caller can let its normal binding through).
+ */
+export function approvalAnswerForKey(item: ApprovalItem, key: string): TuiApprovalAnswer | null {
+  // An idle prompt has no dialog on screen: a digit or a `1` would land in the
+  // composer as text. The card points at `p` instead.
+  if (item.kind === 'idle') return null;
+  if (key === 'y') return { action: 'approve' };
+  if (key === 'n') {
+    const deny = approvalDenyOption(item);
+    return deny === null ? { action: 'deny' } : { action: 'option', option: deny };
+  }
+  if (key >= '1' && key <= '9') {
+    const option = Number.parseInt(key, 10);
+    return (item.options ?? []).some((entry) => entry.n === option) ? { action: 'option', option } : null;
+  }
+  return null;
+}
+
+/**
+ * Ids in `items` that `seen` has not recorded. The bell rings for these and for
+ * nothing else, which is what keeps a repaint (or a refetch that returns the
+ * same pending item) silent.
+ *
+ * Answered ids stay in `seen` on purpose: the inbox restores an item under its
+ * ORIGINAL id when a write fails, and re-ringing for a prompt the user already
+ * heard about is worse than missing one.
+ */
+export function newApprovalIds(seen: ReadonlySet<string>, items: readonly ApprovalItem[]): string[] {
+  const fresh: string[] = [];
+  for (const item of items) if (!seen.has(item.id) && !fresh.includes(item.id)) fresh.push(item.id);
+  return fresh;
+}

src/tui/tui-composer.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Pure single-line editor behind the TUI's prompt composer (`p`)
+ * and search query (`/`).
+ *
+ * Text is held as CODE POINTS rather than a string, because every operation
+ * here is index-based and a cursor that can land inside a surrogate pair
+ * eventually deletes half an emoji. Combining marks are their own entries: they
+ * are zero-width, so they neither move the cursor's column nor cost a cell, and
+ * backspace peeling one off a base letter is what a terminal editor does.
+ *
+ * Scrolling is derived, never remembered implicitly: `composerScroll()` takes
+ * the width and returns the state whose window holds the cursor, which is what
+ * keeps "what the footer shows" a function of the state plus the terminal width
+ * rather than of the order the user pressed keys in.
+ *
+ * PURE: no IO, no timers, no `process.*`. Enter and Escape are reported as
+ * `submit`/`cancel` rather than acted on, since only the caller knows whether
+ * Enter means "send this prompt" or "open the highlighted search result".
+ *
+ * @module tui/tui-composer
+ */
+
+import { charWidth } from './tui-ansi.js';
+import type { TuiInputEvent } from './tui-keys.js';
+
+export interface TuiComposerState {
+  /** Code points. `chars.join('')` is the text. */
+  readonly chars: readonly string[];
+  /** 0..chars.length. The cursor sits BEFORE `chars[cursor]`. */
+  readonly cursor: number;
+  /** First visible code point, as `composerScroll()` last resolved it. */
+  readonly scroll: number;
+}
+
+export function createComposer(text = ''): TuiComposerState {
+  const chars = [...text];
+  return { chars, cursor: chars.length, scroll: 0 };
+}
+
+export function composerText(state: TuiComposerState): string {
+  return state.chars.join('');
+}
+
+function withChars(chars: readonly string[], cursor: number, scroll: number): TuiComposerState {
+  const clampedCursor = Math.min(Math.max(0, cursor), chars.length);
+  return { chars, cursor: clampedCursor, scroll: Math.min(Math.max(0, scroll), chars.length) };
+}
+
+/** Insert typed text at the cursor. Newlines are stripped: this is one line. */
+export function composerInsert(state: TuiComposerState, value: string): TuiComposerState {
+  const inserted = [...value.replace(/[\r\n]+/g, ' ')];
+  if (inserted.length === 0) return state;
+  const chars = [...state.chars.slice(0, state.cursor), ...inserted, ...state.chars.slice(state.cursor)];
+  return withChars(chars, state.cursor + inserted.length, state.scroll);
+}
+
+/** Delete the code point before the cursor. */
+export function composerBackspace(state: TuiComposerState): TuiComposerState {
+  if (state.cursor === 0) return state;
+  const chars = [...state.chars.slice(0, state.cursor - 1), ...state.chars.slice(state.cursor)];
+  return withChars(chars, state.cursor - 1, state.scroll);
+}
+
+/** Delete the code point under the cursor (the Delete key). */
+export function composerDelete(state: TuiComposerState): TuiComposerState {
+  if (state.cursor >= state.chars.length) return state;
+  const chars = [...state.chars.slice(0, state.cursor), ...state.chars.slice(state.cursor + 1)];
+  return withChars(chars, state.cursor, state.scroll);
+}
+
+/** Delete back to the start of the word before the cursor (Ctrl+W). */
+export function composerDeleteWord(state: TuiComposerState): TuiComposerState {
+  let start = state.cursor;
+  while (start > 0 && state.chars[start - 1] === ' ') start--;
+  while (start > 0 && state.chars[start - 1] !== ' ') start--;
+  if (start === state.cursor) return state;
+  const chars = [...state.chars.slice(0, start), ...state.chars.slice(state.cursor)];
+  return withChars(chars, start, state.scroll);
+}
+
+export function composerMove(state: TuiComposerState, delta: number): TuiComposerState {
+  const cursor = Math.min(Math.max(0, state.cursor + Math.trunc(delta)), state.chars.length);
+  return cursor === state.cursor ? state : withChars(state.chars, cursor, state.scroll);
+}
+
+export function composerHome(state: TuiComposerState): TuiComposerState {
+  return state.cursor === 0 ? state : withChars(state.chars, 0, state.scroll);
+}
+
+export function composerEnd(state: TuiComposerState): TuiComposerState {
+  return state.cursor === state.chars.length ? state : withChars(state.chars, state.chars.length, state.scroll);
+}
+
+export function composerClear(state: TuiComposerState): TuiComposerState {
+  return state.chars.length === 0 ? state : { chars: [], cursor: 0, scroll: 0 };
+}
+
+/** Display columns of `chars[from..to)`. */
+function widthOf(chars: readonly string[], from: number, to: number): number {
+  let width = 0;
+  for (let i = from; i < to; i++) width += charWidth(chars[i].codePointAt(0) ?? 0);
+  return width;
+}
+
+/**
+ * Resolve `scroll` so the cursor is inside a window `width` columns wide,
+ * scrolling the minimum needed. One column is reserved for the cursor itself,
+ * so a cursor at the end of the text still has a cell to sit in instead of
+ * hanging one past the edge where the terminal would wrap it.
+ */
+export function composerScroll(state: TuiComposerState, width: number): TuiComposerState {
+  const usable = Math.max(0, Math.trunc(width) - 1);
+  let scroll = Math.min(Math.max(0, state.scroll), state.cursor);
+  while (scroll < state.cursor && widthOf(state.chars, scroll, state.cursor) > usable) scroll++;
+  return scroll === state.scroll ? state : { chars: state.chars, cursor: state.cursor, scroll };
+}
+
+export interface TuiComposerWindow {
+  /** The visible slice of the text. */
+  text: string;
+  /** Cursor offset in display columns from the start of `text`. */
+  cursorColumn: number;
+  /** Resolved first visible code point (may differ from `state.scroll`). */
+  scroll: number;
+}
+
+/**
+ * The slice the footer draws plus where the terminal cursor belongs. The scroll
+ * is resolved here too, so a renderer that never writes state back still shows
+ * the cursor.
+ */
+export function composerWindow(state: TuiComposerState, width: number): TuiComposerWindow {
+  const columns = Math.max(1, Math.trunc(width));
+  const scrolled = composerScroll(state, columns);
+  const { chars, cursor, scroll } = scrolled;
+  let used = 0;
+  let end = scroll;
+  while (end < chars.length) {
+    const next = charWidth(chars[end].codePointAt(0) ?? 0);
+    if (used + next > columns) break;
+    used += next;
+    end++;
+  }
+  return {
+    text: chars.slice(scroll, Math.max(end, cursor)).join(''),
+    cursorColumn: widthOf(chars, scroll, cursor),
+    scroll,
+  };
+}
+
+export type TuiComposerStep =
+  | { kind: 'edit'; state: TuiComposerState }
+  | { kind: 'submit'; text: string }
+  | { kind: 'cancel' }
+  | { kind: 'ignore' };
+
+/**
+ * One keystroke. Enter and Escape are REPORTED rather than applied: `p` sends
+ * the line while `/` opens the highlighted result, and only the caller knows
+ * which.
+ */
+export function composerStep(state: TuiComposerState, event: TuiInputEvent): TuiComposerStep {
+  switch (event.type) {
+    case 'char':
+      return { kind: 'edit', state: composerInsert(state, event.value) };
+    case 'backspace':
+      return { kind: 'edit', state: composerBackspace(state) };
+    case 'enter':
+      return { kind: 'submit', text: composerText(state) };
+    case 'escape':
+      return { kind: 'cancel' };
+    case 'key':
+      switch (event.name) {
+        case 'left':
+          return { kind: 'edit', state: composerMove(state, -1) };
+        case 'right':
+          return { kind: 'edit', state: composerMove(state, 1) };
+        case 'home':
+          return { kind: 'edit', state: composerHome(state) };
+        case 'end':
+          return { kind: 'edit', state: composerEnd(state) };
+        case 'delete':
+          return { kind: 'edit', state: composerDelete(state) };
+        default:
+          return { kind: 'ignore' };
+      }
+    case 'ctrl':
+      switch (event.key) {
+        case 'c':
+          return { kind: 'cancel' };
+        case 'a':
+          return { kind: 'edit', state: composerHome(state) };
+        case 'e':
+          return { kind: 'edit', state: composerEnd(state) };
+        case 'u':
+          return { kind: 'edit', state: composerClear(state) };
+        case 'w':
+          return { kind: 'edit', state: composerDeleteWord(state) };
+        default:
+          return { kind: 'ignore' };
+      }
+    default:
+      return { kind: 'ignore' };
+  }
+}

src/tui/tui-digest.ts

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Pure formatting of `GET /api/away-digest` into the lines the
+ * `g` overlay scrolls.
+ *
+ * The digest answers "what happened while I was away", so it is read top-down
+ * and never studied: every entry is one line (age, session, what happened), a
+ * long section is capped with a "… n more" tail rather than allowed to push the
+ * next section off screen, and the counts that matter live in the first line
+ * where they are visible without scrolling at all.
+ *
+ * PURE: no IO, no clock of its own (the caller passes `now`), no `process.*`.
+ *
+ * @module tui/tui-digest
+ */
+
+import { formatElapsed, formatTokens } from './tui-render.js';
+import type { AwayDigestItem, AwayDigestResponse, AwayDigestSectionName } from '../web/away-digest.js';
+
+/** Entries per section before the tail takes over. */
+export const DIGEST_SECTION_LIMIT = 6;
+
+const SECTION_ORDER: ReadonlyArray<readonly [AwayDigestSectionName, string]> = [
+  ['needsAttention', 'NEEDS ATTENTION'],
+  ['completed', 'COMPLETED'],
+  ['stillRunning', 'STILL RUNNING'],
+  ['idle', 'IDLE'],
+  ['informational', 'INFO'],
+];
+
+const RANGE_WORDS: Record<string, string> = {
+  'since-last-visit': 'since your last visit',
+  '1h': 'the last hour',
+  today: 'today',
+  '24h': 'the last 24 hours',
+  custom: 'the selected window',
+};
+
+export interface TuiDigestOptions {
+  now: number;
+  sectionLimit?: number;
+}
+
+function ageColumn(item: AwayDigestItem, now: number): string {
+  const age = item.timestamp > 0 ? formatElapsed(now - item.timestamp) : '';
+  return age.padEnd(4);
+}
+
+function itemLine(item: AwayDigestItem, now: number): string {
+  const who = item.sessionName ?? item.sessionId?.slice(0, 8) ?? '';
+  const what = [item.title, item.detail].filter((part) => part && part.trim() !== '').join(' · ');
+  return `  ${ageColumn(item, now)} ${[who, what].filter((part) => part !== '').join('  ')}`.replace(/\s+$/, '');
+}
+
+/**
+ * The digest as display lines. The first line is the summary, then one block
+ * per non-empty section, then the token totals when the range had any.
+ */
+export function formatAwayDigest(digest: AwayDigestResponse, options: TuiDigestOptions): string[] {
+  const limit = Math.max(1, Math.trunc(options.sectionLimit ?? DIGEST_SECTION_LIMIT));
+  const { totals } = digest;
+  const lines: string[] = [
+    [
+      RANGE_WORDS[digest.range.range] ?? 'recently',
+      `${totals.sessionsCreated} started`,
+      `${totals.sessionsExited} exited`,
+      `${totals.activeSessions} running`,
+    ].join(' · '),
+  ];
+
+  let entries = 0;
+  for (const [key, label] of SECTION_ORDER) {
+    const items = digest.sections[key] ?? [];
+    if (items.length === 0) continue;
+    entries += items.length;
+    lines.push('', `${label} (${items.length})`);
+    for (const item of items.slice(0, limit)) lines.push(itemLine(item, options.now));
+    if (items.length > limit) lines.push(`  … ${items.length - limit} more`);
+  }
+
+  if (entries === 0) lines.push('', 'nothing happened while you were away');
+
+  const tokens = [
+    formatTokens(totals.inputTokens ?? 0) ? `${formatTokens(totals.inputTokens ?? 0)} in` : '',
+    formatTokens(totals.outputTokens ?? 0) ? `${formatTokens(totals.outputTokens ?? 0)} out` : '',
+    typeof totals.estimatedCost === 'number' && totals.estimatedCost > 0 ? `$${totals.estimatedCost.toFixed(2)}` : '',
+  ].filter((part) => part !== '');
+  if (tokens.length > 0) lines.push('', `tokens: ${tokens.join(' · ')}`);
+
+  return lines;
+}

src/tui/tui-keys.ts

@@ -0,0 +1,240 @@
+/**
+ * @fileoverview Pure byte-stream to input-event parser for raw-mode stdin.
+ *
+ * Stateful (a sequence can arrive split across reads, and a UTF-8 character can
+ * be split mid-code-point) but pure: it owns a byte buffer and nothing else, no
+ * stdin, no timers. The one timing decision a terminal forces on us stays with
+ * the caller: a lone ESC is indistinguishable from the start of an arrow key
+ * until something either follows it or does not, so the parser HOLDS a trailing
+ * ESC and the caller calls `flush()` after ~30ms of silence to turn it into an
+ * Escape event.
+ *
+ * Unknown sequences are swallowed rather than leaked as text: a stray
+ * `CSI 200~` must never end up typed into a prompt composer.
+ *
+ * @module tui/tui-keys
+ */
+
+/** Keys with a name rather than a character. */
+export type TuiNamedKey =
+  | 'up'
+  | 'down'
+  | 'left'
+  | 'right'
+  | 'home'
+  | 'end'
+  | 'pageup'
+  | 'pagedown'
+  | 'delete'
+  | 'insert';
+
+export type TuiMouseKind = 'press' | 'release' | 'wheel-up' | 'wheel-down';
+
+/** Discriminated union, exhaustive-switch friendly (see `utils/assertNever`). */
+export type TuiInputEvent =
+  | { type: 'char'; value: string }
+  | { type: 'enter' }
+  | { type: 'tab' }
+  | { type: 'backspace' }
+  | { type: 'escape' }
+  | { type: 'ctrl'; key: string }
+  | { type: 'alt'; value: string }
+  | { type: 'key'; name: TuiNamedKey }
+  | { type: 'mouse'; kind: TuiMouseKind; x: number; y: number; button: number };
+
+export interface TuiKeyParser {
+  /** Decode a chunk. Incomplete tails are held for the next call. */
+  feed(chunk: Buffer | string): TuiInputEvent[];
+  /** Resolve a held ESC (the caller's disambiguation timer fired). */
+  flush(): TuiInputEvent[];
+  /** Bytes currently held back. Exposed for the ESC timer and for tests. */
+  pending(): number;
+}
+
+/**
+ * An unterminated sequence longer than this is not a sequence: the held bytes
+ * are dropped whole, so a garbage burst can neither wedge the parser nor leak
+ * its bytes into a prompt as typed characters.
+ */
+const MAX_PENDING_BYTES = 64;
+
+/** Bytes in a UTF-8 sequence given its lead byte; 0 for a byte that cannot lead one. */
+function utf8SequenceLength(lead: number): number {
+  if (lead < 0x80) return 1;
+  if (lead >= 0xc2 && lead <= 0xdf) return 2;
+  if (lead >= 0xe0 && lead <= 0xef) return 3;
+  if (lead >= 0xf0 && lead <= 0xf4) return 4;
+  return 0;
+}
+
+const CSI_FINAL_KEYS: Record<string, TuiNamedKey> = {
+  A: 'up',
+  B: 'down',
+  C: 'right',
+  D: 'left',
+  H: 'home',
+  F: 'end',
+};
+
+/** `CSI <n> ~` keys, by their first numeric parameter. */
+const CSI_TILDE_KEYS: Record<number, TuiNamedKey> = {
+  1: 'home',
+  2: 'insert',
+  3: 'delete',
+  4: 'end',
+  5: 'pageup',
+  6: 'pagedown',
+  7: 'home',
+  8: 'end',
+};
+
+/** Result of trying to parse one sequence off the front of the buffer. */
+type ParseStep = { consumed: number; events: TuiInputEvent[] } | 'incomplete';
+
+const NOTHING: TuiInputEvent[] = [];
+
+export function createKeyParser(): TuiKeyParser {
+  let buf: Buffer = Buffer.alloc(0);
+
+  /** Parse the CSI/SS3 sequence that starts at buf[0] === ESC. */
+  const parseEscape = (): ParseStep => {
+    if (buf.length < 2) return 'incomplete';
+    const second = buf[1];
+
+    // SS3 (`ESC O <final>`): the arrows/Home/End of application-cursor mode.
+    if (second === 0x4f) {
+      if (buf.length < 3) return 'incomplete';
+      const name = CSI_FINAL_KEYS[String.fromCharCode(buf[2])];
+      return { consumed: 3, events: name ? [{ type: 'key', name }] : NOTHING };
+    }
+
+    // ESC followed by a printable character IN THE SAME READ is Alt+that key:
+    // that is how every terminal sends a meta chord. A lone Esc cannot look
+    // like this, because a buffer holding only ESC returns 'incomplete' above
+    // and is flushed as `escape` when the read ends, which is the standard way
+    // to tell the two apart without a timer.
+    //
+    // ⚠️ Three characters are deliberately NOT treated as Alt chords, because
+    // the terminal uses them to introduce sequences and a chord is
+    // indistinguishable from one: `[` (CSI) and `O` (SS3) would swallow every
+    // arrow key, and `]` (OSC) would swallow a terminal's colour-query reply.
+    // Alt+[ and Alt+] therefore cannot exist in a terminal at all, which is why
+    // the list binds bare `[` and `]` for the same job.
+    if (second !== 0x5b) {
+      if (second >= 0x20 && second <= 0x7e && second !== 0x4f && second !== 0x5d) {
+        return { consumed: 2, events: [{ type: 'alt', value: String.fromCharCode(second) }] };
+      }
+      return { consumed: 1, events: [{ type: 'escape' }] };
+    }
+
+    let j = 2;
+    while (j < buf.length && buf[j] >= 0x30 && buf[j] <= 0x3f) j++;
+    while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x2f) j++;
+    if (j >= buf.length) return 'incomplete';
+    const final = String.fromCharCode(buf[j]);
+    const params = buf.subarray(2, j).toString('latin1');
+    const consumed = j + 1;
+
+    // X10 mouse (`CSI M` + 3 raw bytes): swallowed, but its payload bytes must
+    // be consumed or they would surface as typed characters.
+    if (params === '' && final === 'M') {
+      if (buf.length < consumed + 3) return 'incomplete';
+      return { consumed: consumed + 3, events: NOTHING };
+    }
+
+    if (params.startsWith('<') && (final === 'M' || final === 'm')) {
+      return { consumed, events: parseSgrMouse(params.slice(1), final) };
+    }
+
+    if (final === '~') {
+      const name = CSI_TILDE_KEYS[Number.parseInt(params, 10)];
+      return { consumed, events: name ? [{ type: 'key', name }] : NOTHING };
+    }
+
+    // Modified arrows (`CSI 1;5A`) carry the same final byte; the modifier is
+    // dropped rather than exposed, since nothing in the keymap wants it yet.
+    const named = CSI_FINAL_KEYS[final];
+    return { consumed, events: named ? [{ type: 'key', name: named }] : NOTHING };
+  };
+
+  const parseSgrMouse = (params: string, final: string): TuiInputEvent[] => {
+    const parts = params.split(';');
+    if (parts.length < 3) return NOTHING;
+    const button = Number.parseInt(parts[0], 10);
+    const x = Number.parseInt(parts[1], 10);
+    const y = Number.parseInt(parts[2], 10);
+    if (!Number.isFinite(button) || !Number.isFinite(x) || !Number.isFinite(y)) return NOTHING;
+    if (button >= 64) {
+      // 64 = wheel up, 65 = wheel down (the low bit is the direction).
+      const kind: TuiMouseKind = (button & 1) === 1 ? 'wheel-down' : 'wheel-up';
+      return [{ type: 'mouse', kind, x, y, button }];
+    }
+    // Motion reports (bit 32) would fire on every pixel of a drag; nothing in
+    // the keymap consumes them, so they are swallowed here rather than upstream.
+    if ((button & 32) === 32) return NOTHING;
+    return [{ type: 'mouse', kind: final === 'M' ? 'press' : 'release', x, y, button }];
+  };
+
+  /** Parse one non-escape byte (or one UTF-8 character) off the front. */
+  const parseByte = (): ParseStep => {
+    const b = buf[0];
+    // LF counts as Enter because some terminals send it for Return; the cost is
+    // that Ctrl+J is not bindable, which no key in the plan's keymap wants.
+    if (b === 0x0d || b === 0x0a) return { consumed: 1, events: [{ type: 'enter' }] };
+    if (b === 0x09) return { consumed: 1, events: [{ type: 'tab' }] };
+    if (b === 0x7f || b === 0x08) return { consumed: 1, events: [{ type: 'backspace' }] };
+    if (b === 0x00) return { consumed: 1, events: [{ type: 'ctrl', key: '@' }] };
+    if (b >= 0x01 && b <= 0x1a) {
+      return { consumed: 1, events: [{ type: 'ctrl', key: String.fromCharCode(b + 0x60) }] };
+    }
+    if (b >= 0x1c && b <= 0x1f) {
+      return { consumed: 1, events: [{ type: 'ctrl', key: String.fromCharCode(b + 0x40) }] };
+    }
+    const length = utf8SequenceLength(b);
+    if (length === 0) return { consumed: 1, events: NOTHING };
+    if (buf.length < length) return 'incomplete';
+    const value = buf.subarray(0, length).toString('utf8');
+    // A lead byte followed by junk decodes to U+FFFD; that is corruption on the
+    // wire, not something to type into a composer. Only the bad lead byte is
+    // dropped, so whatever valid input followed it still decodes.
+    if (value.includes('�')) return { consumed: 1, events: NOTHING };
+    return { consumed: length, events: [{ type: 'char', value }] };
+  };
+
+  /** Drain the buffer, stopping at the first incomplete sequence. */
+  const drain = (events: TuiInputEvent[]): void => {
+    while (buf.length > 0) {
+      const step = buf[0] === 0x1b ? parseEscape() : parseByte();
+      if (step === 'incomplete') {
+        if (buf.length > MAX_PENDING_BYTES) buf = Buffer.alloc(0);
+        return;
+      }
+      for (const event of step.events) events.push(event);
+      buf = buf.subarray(step.consumed);
+    }
+  };
+
+  return {
+    feed(chunk: Buffer | string): TuiInputEvent[] {
+      const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+      buf = buf.length === 0 ? Buffer.from(bytes) : Buffer.concat([buf, bytes]);
+      const events: TuiInputEvent[] = [];
+      drain(events);
+      return events;
+    },
+
+    flush(): TuiInputEvent[] {
+      const events: TuiInputEvent[] = [];
+      if (buf.length > 0 && buf[0] === 0x1b) {
+        events.push({ type: 'escape' });
+        buf = buf.subarray(1);
+        drain(events);
+      }
+      return events;
+    },
+
+    pending(): number {
+      return buf.length;
+    },
+  };
+}

src/tui/tui-layout.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Pure responsive layout math for the TUI frame.
+ *
+ * One rule decides the shape: below 72 columns (Termius, iPhone portrait) the
+ * preview pane is gone and rows take two lines, which is the constraint the
+ * `sc` chooser was built around and the reason it is still usable on a phone.
+ * Above it, a clamped sidebar carries the session list and the preview takes
+ * the rest.
+ *
+ * Rectangles are 1-based (row 1, column 1 is the top-left cell) because that is
+ * what `ESC [ <row>;<col> H` takes, and every region is clamped to a
+ * non-negative size so a 5x5 terminal degrades instead of producing negative
+ * widths that would crash the renderer.
+ *
+ * @module tui/tui-layout
+ */
+
+import type { TuiConnectionStatus } from './tui-types.js';
+
+/** Width at which the preview pane is dropped and rows become two lines. */
+export const NARROW_BREAKPOINT = 72;
+/** Sidebar clamp: narrower than this and a session name stops being readable. */
+export const SIDEBAR_MIN_WIDTH = 34;
+/** Sidebar clamp: wider than this is wasted on a list of short names. */
+export const SIDEBAR_MAX_WIDTH = 44;
+/** A preview thinner than this shows nothing useful, so the layout goes narrow instead. */
+export const PREVIEW_MIN_WIDTH = 24;
+/** Share of the width the sidebar aims for between the clamps. */
+const SIDEBAR_RATIO = 0.36;
+
+export interface TuiRect {
+  /** 1-based terminal row of the first line. */
+  row: number;
+  /** 1-based terminal column of the first cell. */
+  col: number;
+  width: number;
+  height: number;
+}
+
+export interface TuiLayoutOptions {
+  /**
+   * Reserve one line under the header for the connection banner. The caller
+   * decides with `needsBanner(model.connection)`, so layout stays pure math.
+   */
+  banner?: boolean;
+}
+
+export interface TuiLayout {
+  cols: number;
+  rows: number;
+  /** No preview pane, two-line rows. */
+  narrow: boolean;
+  /** Terminal lines one session row occupies. */
+  rowHeight: 1 | 2;
+  header: TuiRect;
+  /** Connection banner, when the caller asked for one and there was room. */
+  banner: TuiRect | null;
+  /** Everything between header and footer, banner included. */
+  body: TuiRect;
+  /** The session list. */
+  list: TuiRect;
+  /** The one-column rule between list and preview; null in narrow mode. */
+  divider: TuiRect | null;
+  /** The preview pane; null in narrow mode. */
+  preview: TuiRect | null;
+  footer: TuiRect;
+}
+
+/** Which connection states get a banner line under the header. */
+export function needsBanner(connection: TuiConnectionStatus): boolean {
+  return connection !== 'connected';
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/**
+ * Rectangles for one frame at `cols` x `rows`.
+ *
+ * The header always exists; the footer appears from 2 rows up; the body is
+ * whatever is left, which may legitimately be zero lines high.
+ */
+export function computeLayout(cols: number, rows: number, options: TuiLayoutOptions = {}): TuiLayout {
+  const width = Math.max(1, Math.floor(cols) || 1);
+  const height = Math.max(1, Math.floor(rows) || 1);
+
+  const headerHeight = 1;
+  const footerHeight = height >= 2 ? 1 : 0;
+  const bodyHeight = Math.max(0, height - headerHeight - footerHeight);
+  const bodyRow = headerHeight + 1;
+
+  const header: TuiRect = { row: 1, col: 1, width, height: headerHeight };
+  const footer: TuiRect = { row: height, col: 1, width, height: footerHeight };
+  const body: TuiRect = { row: bodyRow, col: 1, width, height: bodyHeight };
+
+  const bannerHeight = options.banner === true && bodyHeight > 0 ? 1 : 0;
+  const banner: TuiRect | null = bannerHeight > 0 ? { row: bodyRow, col: 1, width, height: 1 } : null;
+
+  const contentRow = bodyRow + bannerHeight;
+  const contentHeight = Math.max(0, bodyHeight - bannerHeight);
+
+  const sidebarTarget = Math.floor(width * SIDEBAR_RATIO);
+  const sidebarWidth = clamp(sidebarTarget, SIDEBAR_MIN_WIDTH, SIDEBAR_MAX_WIDTH);
+  const previewWidth = width - sidebarWidth - 1;
+  const narrow = width < NARROW_BREAKPOINT || previewWidth < PREVIEW_MIN_WIDTH;
+
+  if (narrow) {
+    return {
+      cols: width,
+      rows: height,
+      narrow: true,
+      rowHeight: 2,
+      header,
+      banner,
+      body,
+      list: { row: contentRow, col: 1, width, height: contentHeight },
+      divider: null,
+      preview: null,
+      footer,
+    };
+  }
+
+  return {
+    cols: width,
+    rows: height,
+    narrow: false,
+    rowHeight: 1,
+    header,
+    banner,
+    body,
+    list: { row: contentRow, col: 1, width: sidebarWidth, height: contentHeight },
+    divider: { row: contentRow, col: sidebarWidth + 1, width: 1, height: contentHeight },
+    preview: { row: contentRow, col: sidebarWidth + 2, width: previewWidth, height: contentHeight },
+    footer,
+  };
+}

src/tui/tui-model.ts

@@ -0,0 +1,562 @@
+/**
+ * @fileoverview Pure state, classification and grouping for the TUI dashboard.
+ *
+ * Classification speaks the web UI's language on purpose (red blocked, yellow
+ * waiting, green working, muted idle), because a user who has both surfaces
+ * open must never have to translate between them. The inputs are the ones the
+ * server already computes: a unified-list row and, when the session is blocked,
+ * the approvals-inbox item that blocks it. Nothing here screen-scrapes.
+ *
+ * Selection is tracked by session id, never by row index: rows re-sort under
+ * the cursor constantly (a session starts working, an approval lands), and an
+ * index-tracked cursor would silently move the selection to a different
+ * session between two keystrokes.
+ *
+ * PURE: no IO, no timers, no `process.*`. The store mutates its own state and
+ * nothing else.
+ *
+ * @module tui/tui-model
+ */
+
+import type { SearchResultGroup, SearchSourceType } from '../types/search.js';
+import type { ApprovalItem } from '../web/approval-inbox.js';
+import type {
+  TuiConfirmState,
+  TuiConnectionStatus,
+  TuiDigestState,
+  TuiGroup,
+  TuiGroupKey,
+  TuiHeaderInfo,
+  TuiMessage,
+  TuiPickerState,
+  TuiPreview,
+  TuiPromptState,
+  TuiRenderModel,
+  TuiRow,
+  TuiSearchEntry,
+  TuiSearchState,
+  TuiSessionRow,
+  TuiSessionState,
+  TuiUiMode,
+} from './tui-types.js';
+
+/** How many history rows the RECENT group shows before it stops being a dashboard. */
+export const DEFAULT_RECENT_LIMIT = 8;
+
+export const GROUP_ORDER: readonly TuiGroupKey[] = ['needs-you', 'working', 'idle', 'recent'];
+
+export const GROUP_LABELS: Record<TuiGroupKey, string> = {
+  'needs-you': 'NEEDS YOU',
+  working: 'WORKING',
+  idle: 'IDLE',
+  recent: 'RECENT',
+};
+
+const STATE_GROUP: Record<TuiSessionState, TuiGroupKey> = {
+  'blocked-question': 'needs-you',
+  'blocked-permission': 'needs-you',
+  waiting: 'needs-you',
+  working: 'working',
+  idle: 'idle',
+  recent: 'recent',
+};
+
+/** A row is live when the unified merge saw it in the in-memory session map. */
+export function isLiveRow(session: TuiSessionRow): boolean {
+  return Array.isArray(session.sources) && session.sources.includes('live');
+}
+
+/**
+ * Classify one row.
+ *
+ * Order matters and mirrors `_mobileOverviewState()` in the web UI: a pending
+ * prompt outranks everything (it is literally blocking the agent), and it
+ * outranks a stale `busy` status because the hook is the newer signal. An
+ * errored session has no state of its own here and joins the waiting tier,
+ * since it is equally something only a human can clear.
+ */
+export function classifySession(session: TuiSessionRow, approval?: ApprovalItem): TuiSessionState {
+  if (!isLiveRow(session)) return 'recent';
+  if (approval) {
+    if (approval.kind === 'permission') return 'blocked-permission';
+    if (approval.kind === 'question') return 'blocked-question';
+    return 'waiting';
+  }
+  if (session.status === 'error') return 'waiting';
+  if (session.isWorking === true || session.status === 'busy') return 'working';
+  return 'idle';
+}
+
+/**
+ * Epoch ms the session entered its current state, which is what the intra-group
+ * ordering sorts on. 0 when nothing usable is known.
+ *
+ * A WORKING pane repaints about once a second, so its `lastActivityAt` is
+ * always "now" and would report every running turn as freshly started; the
+ * turn's own start is the pane's last Enter.
+ */
+export function stateSince(state: TuiSessionState, session: TuiSessionRow, approval?: ApprovalItem): number {
+  if (approval) return approval.createdAt;
+  if (state === 'working') return session.lastSubmitAt ?? session.createdAt ?? 0;
+  return session.lastActivityAt ?? session.createdAt ?? 0;
+}
+
+/** Classify a batch of rows against the pending approvals, keyed by session id. */
+export function buildRows(
+  sessions: readonly TuiSessionRow[],
+  approvals: ReadonlyMap<string, ApprovalItem> = new Map()
+): TuiRow[] {
+  return sessions.map((session) => {
+    const approval = approvals.get(session.sessionId);
+    const state = classifySession(session, approval);
+    const row: TuiRow = {
+      session,
+      state,
+      group: STATE_GROUP[state],
+      since: stateSince(state, session, approval),
+    };
+    if (approval) row.approval = approval;
+    return row;
+  });
+}
+
+function compareIds(a: TuiRow, b: TuiRow): number {
+  if (a.session.sessionId < b.session.sessionId) return -1;
+  if (a.session.sessionId > b.session.sessionId) return 1;
+  return 0;
+}
+
+/** Longest first: the oldest anchor wins, and an unknown anchor sorts last. */
+function compareLongestFirst(a: TuiRow, b: TuiRow): number {
+  const left = a.since || Number.MAX_SAFE_INTEGER;
+  const right = b.since || Number.MAX_SAFE_INTEGER;
+  return left !== right ? left - right : compareIds(a, b);
+}
+
+/** Newest first: the freshest anchor wins, and an unknown anchor sorts last. */
+function compareNewestFirst(a: TuiRow, b: TuiRow): number {
+  const left = a.since || 0;
+  const right = b.since || 0;
+  return left !== right ? right - left : compareIds(a, b);
+}
+
+export interface GroupOptions {
+  /** RECENT is a tail, not a list: everything past this is dropped. */
+  recentLimit?: number;
+}
+
+/**
+ * Split classified rows into the four display groups.
+ *
+ * Always returns all four in display order (empty ones included) so callers
+ * never have to guess the shape; the renderer skips the empty ones.
+ *
+ * NEEDS YOU and WORKING are ordered by how long they have been in that state
+ * (longest first: the thing that has waited longest for you is the thing to
+ * look at). IDLE and RECENT are ordered by recency, newest first.
+ */
+export function groupSessions(rows: readonly TuiRow[], options: GroupOptions = {}): TuiGroup[] {
+  const recentLimit = Math.max(0, Math.floor(options.recentLimit ?? DEFAULT_RECENT_LIMIT));
+  const buckets: Record<TuiGroupKey, TuiRow[]> = {
+    'needs-you': [],
+    working: [],
+    idle: [],
+    recent: [],
+  };
+  for (const row of rows) buckets[row.group].push(row);
+
+  buckets['needs-you'].sort(compareLongestFirst);
+  buckets.working.sort(compareLongestFirst);
+  buckets.idle.sort(compareNewestFirst);
+  buckets.recent.sort(compareNewestFirst);
+  buckets.recent = buckets.recent.slice(0, recentLimit);
+
+  return GROUP_ORDER.map((key) => ({ key, label: GROUP_LABELS[key], rows: buckets[key] }));
+}
+
+/** The cursor's list: group headers are chrome, only sessions are selectable. */
+export function flattenRows(groups: readonly TuiGroup[]): TuiRow[] {
+  const rows: TuiRow[] = [];
+  for (const group of groups) rows.push(...group.rows);
+  return rows;
+}
+
+/**
+ * Fold an incoming row into a known one. Defined fields win, `undefined` never
+ * clobbers (a live SSE payload carries no transcript fields, a unified refresh
+ * carries no token counters), but a non-empty `sources` list REPLACES rather
+ * than unions: a session that ended must be able to lose its `live` source and
+ * fall to RECENT.
+ */
+export function mergeSessionRow(existing: TuiSessionRow, incoming: TuiSessionRow): TuiSessionRow {
+  const merged: TuiSessionRow = { ...existing };
+  for (const [key, value] of Object.entries(incoming)) {
+    if (value === undefined) continue;
+    (merged as unknown as Record<string, unknown>)[key] = value;
+  }
+  merged.sources = incoming.sources?.length ? [...incoming.sources] : [...(existing.sources ?? [])];
+  return merged;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Search results (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SEARCH_GROUP_LABELS: Record<SearchSourceType, string> = {
+  session: 'SESSIONS',
+  event: 'EVENTS',
+  file: 'FILES',
+};
+
+/**
+ * A session snippet opens with the session's own name, which the row already
+ * shows in its first column (`search-service.ts` builds it as
+ * `w1-alpha <em dash> /tmp/alpha`, hence the separator in the pattern).
+ * Dropping the repeat is what keeps a result row from reading as a stutter.
+ */
+function withoutLabelPrefix(snippet: string, label: string): string {
+  const rest = snippet.startsWith(label) ? snippet.slice(label.length) : snippet;
+  return rest === snippet ? snippet : rest.replace(/^\s*(?:[—:-]\s*)?/, '');
+}
+
+/**
+ * Flatten `GET /api/search`'s typed groups into the overlay's lines: a header
+ * per group, then its results. Only a result row carries a session id, which is
+ * what the cursor uses to skip headers.
+ *
+ * `isLive` decides which rows can hand the dashboard a session: a history hit
+ * has a session id too, but selecting it would move the cursor to a row that is
+ * not on the list.
+ */
+export function buildSearchEntries(
+  groups: readonly SearchResultGroup[],
+  isLive: (sessionId: string) => boolean
+): TuiSearchEntry[] {
+  const entries: TuiSearchEntry[] = [];
+  for (const group of groups) {
+    if (group.results.length === 0) continue;
+    entries.push({ kind: 'header', text: SEARCH_GROUP_LABELS[group.type] ?? group.type.toUpperCase() });
+    for (const result of group.results) {
+      const live = result.jumpTo.kind === 'session' && isLive(result.sessionId);
+      const label = result.jumpTo.relativePath ?? result.sessionName ?? result.sessionId.slice(0, 8);
+      entries.push({
+        kind: 'result',
+        text: label,
+        detail: withoutLabelPrefix(result.snippet, label),
+        sessionId: result.sessionId,
+        live,
+      });
+    }
+  }
+  return entries;
+}
+
+/** First selectable row, or -1 when the list is all headers (or empty). */
+export function firstSearchIndex(entries: readonly TuiSearchEntry[]): number {
+  return entries.findIndex((entry) => entry.kind === 'result');
+}
+
+/**
+ * Move the search cursor by `delta` result rows, skipping headers and stopping
+ * at both ends (wrapping a search result list scrolls past the answer the user
+ * was reading).
+ */
+export function moveSearchIndex(entries: readonly TuiSearchEntry[], index: number, delta: number): number {
+  const step = Math.trunc(delta);
+  if (step === 0) return index;
+  const direction = step > 0 ? 1 : -1;
+  let current = index;
+  for (let remaining = Math.abs(step); remaining > 0; remaining--) {
+    let next = current + direction;
+    while (next >= 0 && next < entries.length && entries[next].kind !== 'result') next += direction;
+    if (next < 0 || next >= entries.length) break;
+    current = next;
+  }
+  return current;
+}
+
+/**
+ * The dashboard's state. Update methods mutate in place (one store per TUI
+ * process, no subscribers) and every derived view is recomputed from scratch,
+ * which keeps "what is on screen" a pure function of the stored facts.
+ */
+export class TuiModelStore implements TuiRenderModel {
+  private sessionsById = new Map<string, TuiSessionRow>();
+  private approvalsBySession = new Map<string, ApprovalItem>();
+  private _revision = 0;
+
+  selectedId: string | null = null;
+  connection: TuiConnectionStatus = 'connected';
+  mode: TuiUiMode = 'list';
+  header: TuiHeaderInfo = {};
+  preview: TuiPreview | null = null;
+  message: TuiMessage | null = null;
+  confirm: TuiConfirmState | null = null;
+  picker: TuiPickerState | null = null;
+  prompt: TuiPromptState | null = null;
+  search: TuiSearchState | null = null;
+  digest: TuiDigestState | null = null;
+  recentLimit: number;
+
+  constructor(options: GroupOptions = {}) {
+    this.recentLimit = Math.max(0, Math.floor(options.recentLimit ?? DEFAULT_RECENT_LIMIT));
+  }
+
+  /**
+   * Bumped by every mutating method. The app layer repaints when this changed
+   * (plus on resize and on the animation tick), which is what keeps an idle
+   * dashboard from redrawing itself. Writing a public field directly bypasses
+   * it, so state changes go through the methods below.
+   */
+  get revision(): number {
+    return this._revision;
+  }
+
+  private touch(): void {
+    this._revision++;
+  }
+
+  // ── Data ───────────────────────────────────────────────────────────────────
+
+  upsertSession(session: TuiSessionRow): void {
+    this.mutate(() => {
+      const existing = this.sessionsById.get(session.sessionId);
+      this.sessionsById.set(session.sessionId, existing ? mergeSessionRow(existing, session) : { ...session });
+    });
+  }
+
+  removeSession(sessionId: string): void {
+    this.mutate(() => {
+      this.sessionsById.delete(sessionId);
+      this.approvalsBySession.delete(sessionId);
+    });
+  }
+
+  /** Full refresh (a `GET /api/sessions/unified` poll): the server is authoritative. */
+  replaceSessions(sessions: readonly TuiSessionRow[]): void {
+    this.mutate(() => {
+      this.sessionsById.clear();
+      for (const session of sessions) this.sessionsById.set(session.sessionId, { ...session });
+    });
+  }
+
+  setApprovals(items: readonly ApprovalItem[]): void {
+    this.mutate(() => {
+      this.approvalsBySession.clear();
+      // One active item per session is an inbox invariant; the newest wins if
+      // that ever stops being true.
+      for (const item of items) this.approvalsBySession.set(item.sessionId, item);
+    });
+  }
+
+  sessions(): TuiSessionRow[] {
+    return [...this.sessionsById.values()];
+  }
+
+  // ── Chrome ─────────────────────────────────────────────────────────────────
+
+  setConnection(status: TuiConnectionStatus): void {
+    if (this.connection === status) return;
+    this.connection = status;
+    this.touch();
+  }
+
+  setHeader(header: TuiHeaderInfo): void {
+    this.header = { ...this.header, ...header };
+    this.touch();
+  }
+
+  setPreview(preview: TuiPreview | null): void {
+    this.preview = preview;
+    this.touch();
+  }
+
+  setMode(mode: TuiUiMode): void {
+    if (this.mode === mode) return;
+    this.mode = mode;
+    this.touch();
+  }
+
+  setMessage(message: TuiMessage | null): void {
+    this.message = message;
+    this.mode = message ? 'message' : 'list';
+    this.touch();
+  }
+
+  /** Show (or clear) the overlay chooser. Setting one takes the keyboard. */
+  setPicker(picker: TuiPickerState | null): void {
+    this.picker = picker;
+    this.mode = picker ? 'new-session' : 'list';
+    this.touch();
+  }
+
+  /** Open (or close) the one-line prompt composer. Setting one takes the keyboard. */
+  setPrompt(prompt: TuiPromptState | null): void {
+    this.prompt = prompt;
+    this.mode = prompt ? 'prompt' : 'list';
+    this.touch();
+  }
+
+  /** Replace the composer's editor state, keeping the target session. */
+  updatePrompt(composer: TuiPromptState['composer']): void {
+    if (!this.prompt || this.prompt.composer === composer) return;
+    this.prompt = { ...this.prompt, composer };
+    this.touch();
+  }
+
+  setSearch(search: TuiSearchState | null): void {
+    this.search = search;
+    this.mode = search ? 'search' : 'list';
+    this.touch();
+  }
+
+  /** Fold a partial update into the open search overlay. No-op when it is closed. */
+  updateSearch(patch: Partial<TuiSearchState>): void {
+    if (!this.search) return;
+    this.search = { ...this.search, ...patch };
+    this.touch();
+  }
+
+  setDigest(digest: TuiDigestState | null): void {
+    this.digest = digest;
+    this.mode = digest ? 'digest' : 'list';
+    this.touch();
+  }
+
+  /**
+   * Scroll the digest by `delta` lines. `capacity` is how many lines the box
+   * shows, so the last page cannot scroll into empty space.
+   */
+  scrollDigest(delta: number, capacity: number): void {
+    if (!this.digest) return;
+    const room = Math.max(0, this.digest.lines.length - Math.max(1, Math.trunc(capacity)));
+    const offset = Math.min(Math.max(0, this.digest.offset + Math.trunc(delta)), room);
+    if (offset === this.digest.offset) return;
+    this.digest = { ...this.digest, offset };
+    this.touch();
+  }
+
+  /**
+   * Arm the typed-name confirmation for `x` (kill). Whether what the user typed
+   * AUTHORIZES the kill is `confirmAccepts()` in tui-app, which owns that rule
+   * for every caller: a second copy here answered the same question differently
+   * (it refused the id prefix a mux name carries) and nothing consulted it.
+   */
+  beginConfirmKill(row: TuiRow, label: string): void {
+    this.confirm = {
+      sessionId: row.session.sessionId,
+      // ⚠️ Passed in, not derived here. `row.session.name ?? id.slice(0,8)`
+      // used to compute it, and `??` falls back only on null/undefined: a
+      // session whose name is the EMPTY STRING (every session the server did
+      // not name) sailed through it and the dialog read "Kill ?". A destructive
+      // prompt that cannot say what it is about to destroy is worse than no
+      // prompt, and it is now one keystroke. The caller passes the same label
+      // the LIST shows, so the dialog names the row the user is looking at.
+      name: label,
+    };
+    this.mode = 'confirm-kill';
+    this.touch();
+  }
+
+  /** Drop whatever overlay owns the keyboard and go back to the list. */
+  closeOverlay(): void {
+    this.confirm = null;
+    this.message = null;
+    this.picker = null;
+    this.prompt = null;
+    this.search = null;
+    this.digest = null;
+    this.mode = 'list';
+    this.touch();
+  }
+
+  // ── Derived views ──────────────────────────────────────────────────────────
+
+  groups(): TuiGroup[] {
+    return groupSessions(buildRows(this.sessions(), this.approvalsBySession), { recentLimit: this.recentLimit });
+  }
+
+  rows(): TuiRow[] {
+    return flattenRows(this.groups());
+  }
+
+  get sessionCount(): number {
+    let count = 0;
+    for (const session of this.sessionsById.values()) if (isLiveRow(session)) count++;
+    return count;
+  }
+
+  // ── Cursor ─────────────────────────────────────────────────────────────────
+
+  selectedSession(): TuiRow | null {
+    if (!this.selectedId) return null;
+    return this.rows().find((row) => row.session.sessionId === this.selectedId) ?? null;
+  }
+
+  /** Select a session by id. Returns false when it is not on screen. */
+  select(sessionId: string): boolean {
+    if (!this.rows().some((row) => row.session.sessionId === sessionId)) return false;
+    this.moveTo(sessionId);
+    return true;
+  }
+
+  /** Move by `delta` rows, skipping group headers and wrapping at both ends. */
+  moveCursor(delta: number): void {
+    const rows = this.rows();
+    if (rows.length === 0) {
+      this.moveTo(null);
+      return;
+    }
+    const current = this.indexOfSelected(rows);
+    if (current < 0) {
+      this.moveTo(rows[delta >= 0 ? 0 : rows.length - 1].session.sessionId);
+      return;
+    }
+    const step = Math.trunc(delta);
+    const next = (((current + step) % rows.length) + rows.length) % rows.length;
+    this.moveTo(rows[next].session.sessionId);
+  }
+
+  /** The 1-9 jump: `n` is the 1-based position in the flattened list. */
+  cursorToIndex(n: number): boolean {
+    const rows = this.rows();
+    const index = Math.trunc(n) - 1;
+    if (index < 0 || index >= rows.length) return false;
+    this.moveTo(rows[index].session.sessionId);
+    return true;
+  }
+
+  private moveTo(sessionId: string | null): void {
+    if (this.selectedId === sessionId) return;
+    this.selectedId = sessionId;
+    this.touch();
+  }
+
+  private indexOfSelected(rows: readonly TuiRow[] = this.rows()): number {
+    if (!this.selectedId) return -1;
+    return rows.findIndex((row) => row.session.sessionId === this.selectedId);
+  }
+
+  /**
+   * Run a data mutation and keep the cursor sane afterwards: the selected
+   * session stays selected wherever it moved to, and a session that vanished
+   * hands the cursor to whatever now occupies its place.
+   */
+  private mutate(apply: () => void): void {
+    const previousIndex = this.indexOfSelected();
+    apply();
+    this.touch();
+    const rows = this.rows();
+    if (rows.length === 0) {
+      this.moveTo(null);
+      return;
+    }
+    if (this.selectedId !== null && rows.some((row) => row.session.sessionId === this.selectedId)) return;
+    const index = Math.min(Math.max(previousIndex, 0), rows.length - 1);
+    this.moveTo(rows[index].session.sessionId);
+  }
+}
+
+export function createTuiModel(options: GroupOptions = {}): TuiModelStore {
+  return new TuiModelStore(options);
+}

src/tui/tui-render.ts

@@ -0,0 +1,921 @@
+/**
+ * @fileoverview Pure frame renderer: model + layout in, one string out.
+ *
+ * The frame is absolute-addressed, one `ESC [ <row>;1 H` per line followed by
+ * `ESC [ K`, so nothing ever scrolls and a repaint cannot leave debris. The
+ * caller wraps the result in synchronized-output brackets (DECSET 2026) where
+ * the terminal supports it; that is an IO decision and stays out of here.
+ *
+ * Color is decided by the caller and passed in, never detected here: chalk's
+ * auto-detection is the right answer for the one-shot CLI (see `cli-style.ts`)
+ * but it would make a frame non-deterministic, and "same inputs, same string"
+ * is what makes this module testable. The palette below is the same semantic
+ * vocabulary chalk gives `cli-style` (ok green, warn yellow, err red, info
+ * cyan, muted gray, emph bold), written as raw SGR so the mapping is fixed.
+ *
+ * With `color: false` the frame contains no escape sequences at all beyond the
+ * cursor addressing that puts each line in place.
+ *
+ * @module tui/tui-render
+ */
+
+import { clipStyledLine, padDisplay, stripStyles, visibleWidth } from './tui-ansi.js';
+import { approvalCard } from './tui-approvals.js';
+import { composerText, composerWindow } from './tui-composer.js';
+import type { TuiLayout, TuiRect } from './tui-layout.js';
+import type { ApprovalItem } from '../web/approval-inbox.js';
+import type { StatusTelemetry } from '../usage-telemetry.js';
+import type {
+  TuiDigestState,
+  TuiGlyphTier,
+  TuiGroup,
+  TuiPickerState,
+  TuiPromptState,
+  TuiRenderModel,
+  TuiRow,
+  TuiSearchState,
+  TuiSessionRow,
+  TuiSessionState,
+} from './tui-types.js';
+
+export interface TuiRenderOptions {
+  /** Emit SGR color. False is NO_COLOR: cursor addressing and nothing else. */
+  color: boolean;
+  glyphs: TuiGlyphTier;
+  /** Animation counter. The WORKING glyph cycles with it. */
+  tick: number;
+  /** Wall clock for elapsed times, passed in so a frame is reproducible. */
+  now: number;
+  /**
+   * Footer entries, already labelled, joined here with the separator glyph.
+   * The app layer passes the keys that actually do something right now (which
+   * verbs are wired up, whether a server is answering); omitting it falls back
+   * to the full keymap below.
+   */
+  footerKeys?: readonly string[];
+  /**
+   * `[key, what it does]` pairs for the help overlay, same reasoning as
+   * `footerKeys`: the app layer knows which verbs are wired up. Omitting it
+   * falls back to the full keymap.
+   */
+  helpKeys?: ReadonlyArray<readonly [string, string]>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Palette and glyphs
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SGR = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  inverse: '\x1b[7m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+} as const;
+
+/**
+ * One word per state, shared by the preview title and the `--list` output so
+ * both surfaces call a session the same thing.
+ */
+export const STATE_WORDS: Record<TuiSessionState, string> = {
+  'blocked-permission': 'blocked',
+  'blocked-question': 'blocked',
+  waiting: 'waiting',
+  working: 'working',
+  idle: 'idle',
+  recent: 'done',
+};
+
+const STATE_COLOR: Record<TuiSessionState, string> = {
+  'blocked-permission': SGR.red,
+  'blocked-question': SGR.red,
+  waiting: SGR.yellow,
+  working: SGR.green,
+  idle: SGR.gray,
+  recent: SGR.gray,
+};
+
+export interface TuiGlyphSet {
+  blockedPermission: string;
+  blockedQuestion: string;
+  waiting: string;
+  /** WORKING animates through Claude's own glyph family, a deliberate nod. */
+  working: readonly string[];
+  idle: string;
+  recent: string;
+  cursor: string;
+  rule: string;
+  divider: string;
+  boxTopLeft: string;
+  boxTopRight: string;
+  boxBottomLeft: string;
+  boxBottomRight: string;
+  boxHorizontal: string;
+  boxVertical: string;
+  enter: string;
+  updown: string;
+  separator: string;
+  ellipsis: string;
+}
+
+/**
+ * ⚠️ Every glyph here must clear TWO bars that are easy to miss, and both were
+ * failed at once by the first version of this table.
+ *
+ * WIDTH: the renderer addresses cells by column, so a glyph the terminal draws
+ * two cells wide shifts everything after it. `east_asian_width` W or F is
+ * therefore disqualifying. `✋` (U+270B) was Wide, and being an emoji is also
+ * why fonts render it at emoji size in the middle of a text row.
+ *
+ * COVERAGE: a plain terminal font carries far less than the unicode TIER
+ * implies. The tier answers "is the locale UTF-8", which says nothing about
+ * whether a given codepoint has a glyph.
+ *
+ * One beta tester's font mapped the blocks like this, and it is the profile to
+ * design against because it is an ordinary terminal font, not a broken one:
+ *
+ *   RENDERS   Latin-1 (·), Box Drawing (─ │), Block Elements (█ ▛ ▐),
+ *             Geometric Shapes (○ ▶), General Punctuation (…), Arrows
+ *   TOFU      Misc Technical (⏎ U+23CE, ⏵ U+23F5), the sparse end of
+ *             Dingbats (❯ U+276F)
+ *
+ * So: draw from the blocks on the first line. Dingbats, Miscellaneous
+ * Technical, Miscellaneous Symbols and anything with emoji presentation are
+ * out — that class produced three separate "why are there boxes" reports, one
+ * per glyph, because each was fixed on its own instead of as a class.
+ */
+const UNICODE_GLYPHS: TuiGlyphSet = {
+  blockedPermission: '▲',
+  blockedQuestion: '▲',
+  waiting: '!',
+  // Quadrant blocks, which rotate as a spinner and live in the same block as
+  // the `▛█▐` art claude itself draws — proven to render on the font that
+  // failed the dingbats this used to use.
+  working: ['▖', '▘', '▝', '▗'],
+  idle: '○',
+  recent: '✔',
+  cursor: '▶',
+  rule: '─',
+  divider: '│',
+  boxTopLeft: '┌',
+  boxTopRight: '┐',
+  boxBottomLeft: '└',
+  boxBottomRight: '┘',
+  boxHorizontal: '─',
+  boxVertical: '│',
+  enter: '↵',
+  updown: '↑↓',
+  separator: '·',
+  ellipsis: '…',
+};
+
+/**
+ * The lowest tier, for terminals that are not known-capable. Every state token
+ * is three columns wide so rows still line up, mirroring what `sc` falls back
+ * to today.
+ */
+const ASCII_GLYPHS: TuiGlyphSet = {
+  blockedPermission: '[!]',
+  blockedQuestion: '[?]',
+  waiting: '[w]',
+  working: ['[*]', '[+]', '[x]', '[+]'],
+  idle: '[-]',
+  recent: '[v]',
+  cursor: '>',
+  rule: '-',
+  divider: '|',
+  boxTopLeft: '+',
+  boxTopRight: '+',
+  boxBottomLeft: '+',
+  boxBottomRight: '+',
+  boxHorizontal: '-',
+  boxVertical: '|',
+  enter: 'enter',
+  updown: 'up/dn',
+  separator: '-',
+  ellipsis: '..',
+};
+
+/**
+ * Glyphs for a tier. `nerd` currently renders like `unicode`: the tier exists
+ * so detection has somewhere to land and a nerd-font-only set has a home,
+ * without shipping glyphs nobody has reviewed on a real font.
+ */
+export function glyphsFor(tier: TuiGlyphTier): TuiGlyphSet {
+  return tier === 'ascii' ? ASCII_GLYPHS : UNICODE_GLYPHS;
+}
+
+/**
+ * Glyph tier from the environment. IO-ish by nature (it reads env), so it takes
+ * the env as an argument and the app layer calls it once at startup. The
+ * known-capable list is a TERM allowlist, plus a UTF-8 locale check and an
+ * explicit override.
+ */
+export function detectGlyphTier(env: Record<string, string | undefined>): TuiGlyphTier {
+  const override = env.CODEMAN_TUI_GLYPHS;
+  if (override === 'ascii' || override === 'unicode' || override === 'nerd') return override;
+  const term = env.TERM ?? '';
+  if (term === '' || term === 'dumb') return 'ascii';
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+  if (!/utf-?8/i.test(locale)) return 'ascii';
+  const termProgram = env.TERM_PROGRAM ?? '';
+  if (termProgram.startsWith('iTerm') || term === 'xterm-kitty' || env.WEZTERM_PANE || env.LC_TERMINAL === 'iTerm2') {
+    return 'nerd';
+  }
+  return 'unicode';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Formatting helpers (pure, exported for tests and for the app layer)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Compact age: `45s`, `11m`, `2h`, `3d`. Empty when the anchor is unknown. */
+export function formatElapsed(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return '';
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+function trimTrailingZero(value: string): string {
+  return value.endsWith('.0') ? value.slice(0, -2) : value;
+}
+
+/** Compact token count: `842`, `45.2k`, `1.2M`. Empty when there is nothing to show. */
+export function formatTokens(total: number): string {
+  if (!Number.isFinite(total) || total <= 0) return '';
+  if (total < 1000) return String(Math.floor(total));
+  if (total < 1_000_000) return `${trimTrailingZero((total / 1000).toFixed(1))}k`;
+  return `${trimTrailingZero((total / 1_000_000).toFixed(1))}M`;
+}
+
+/**
+ * The header's plan-usage chip: `5h 32% · wk 61%`, the same two windows the web
+ * chip shows (the statusline telemetry carries no others). Empty when the
+ * account reports neither, so the header shows no placeholder for a fact that
+ * does not exist. The separator is passed in because the header's own comes
+ * from the glyph tier, and an ASCII terminal must not get a stray `·`.
+ */
+export function formatPlanUsage(usage: StatusTelemetry | null | undefined, separator = ' · '): string {
+  if (!usage) return '';
+  const parts: string[] = [];
+  if (typeof usage.fiveHour?.usedPercentage === 'number') {
+    parts.push(`5h ${Math.round(usage.fiveHour.usedPercentage)}%`);
+  }
+  if (typeof usage.sevenDay?.usedPercentage === 'number') {
+    parts.push(`wk ${Math.round(usage.sevenDay.usedPercentage)}%`);
+  }
+  return parts.join(separator);
+}
+
+/**
+ * What a row is called. Same rule as the web history rows, including the
+ * "(no content)" placeholder the transcript reader emits, which is not a title.
+ */
+export function rowLabel(session: TuiSessionRow): string {
+  if (session.name) return session.name;
+  const base = (session.workingDir ?? '').split('/').filter(Boolean).pop();
+  // ⚠️ A LIVE pane (it has a mux name) is identified by WHERE it runs, never by
+  // a line scraped out of its transcript. A session created before the user has
+  // typed anything has no prompt to be named after, so the fallback took
+  // whatever the CLI happened to print first: a beta tester's new session
+  // appeared in the list called "Login interrupted", which reads like a failure
+  // report and was in fact a healthy session. A history row is the opposite
+  // case, where the prompt IS the identity, so it keeps the old order.
+  if (session.muxName && base) return base;
+  const prompt = (session.firstPrompt ?? '').trim();
+  if (prompt && prompt !== '(no content)') return prompt;
+  return base || session.sessionId.slice(0, 8);
+}
+
+/** Keep the tail of a path: the last segments identify it, the root never does. */
+function truncatePathLeft(path: string, width: number, ellipsis: string): string {
+  if (width <= 0) return '';
+  if (visibleWidth(path) <= width) return path;
+  const keep = Math.max(0, width - visibleWidth(ellipsis));
+  return ellipsis + path.slice(path.length - keep);
+}
+
+function tokensOf(session: TuiSessionRow): number {
+  return (session.inputTokens ?? 0) + (session.outputTokens ?? 0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Painting
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Painter = (text: string, code: string) => string;
+
+function painterFor(enabled: boolean): Painter {
+  return enabled ? (text, code) => (text === '' ? text : `${code}${text}${SGR.reset}`) : (text) => text;
+}
+
+function stateGlyph(row: TuiRow, glyphs: TuiGlyphSet, tick: number): string {
+  switch (row.state) {
+    case 'blocked-permission':
+      return glyphs.blockedPermission;
+    case 'blocked-question':
+      return glyphs.blockedQuestion;
+    case 'waiting':
+      return glyphs.waiting;
+    case 'working': {
+      const frames = glyphs.working;
+      const index = ((Math.trunc(tick) % frames.length) + frames.length) % frames.length;
+      return frames[index];
+    }
+    case 'idle':
+      return glyphs.idle;
+    case 'recent':
+      return glyphs.recent;
+  }
+}
+
+function centered(text: string, width: number): string {
+  const pad = Math.max(0, Math.floor((width - visibleWidth(text)) / 2));
+  return padDisplay(`${' '.repeat(pad)}${text}`, width);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rows and groups
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RowContext {
+  width: number;
+  /** 1-based position in the flattened list; only 1-9 get a jump digit. */
+  index: number;
+  selected: boolean;
+  twoLine: boolean;
+  glyphs: TuiGlyphSet;
+  opts: TuiRenderOptions;
+}
+
+function renderRowLines(row: TuiRow, ctx: RowContext): string[] {
+  // A selected row is one inverse-video block, so its parts are built unpainted:
+  // an inner reset would punch a hole in the highlight.
+  const inverse = ctx.selected && ctx.opts.color;
+  const paint = painterFor(ctx.opts.color && !inverse);
+  const { session } = row;
+
+  const marker = ctx.selected ? padDisplay(ctx.glyphs.cursor, 2) : '  ';
+  const digit = ctx.index >= 1 && ctx.index <= 9 ? `${ctx.index} ` : '  ';
+
+  const glyph = paint(stateGlyph(row, ctx.glyphs, ctx.opts.tick), STATE_COLOR[row.state]);
+  const elapsed = row.since > 0 ? formatElapsed(ctx.opts.now - row.since) : '';
+  const tokens = formatTokens(tokensOf(session));
+  const rightParts = [glyph, paint(elapsed, SGR.gray)];
+  if (!ctx.twoLine && tokens) rightParts.push(paint(tokens, SGR.gray));
+  const right = rightParts.filter((part) => part !== '').join(' ');
+
+  const mode = session.mode && session.mode !== 'claude' ? session.mode : '';
+  const nameWidth = Math.max(4, ctx.width - visibleWidth(marker + digit) - visibleWidth(right) - 1);
+  const label = rowLabel(session);
+  const name = mode ? `${label} ${paint(mode, SGR.magenta)}` : label;
+
+  const first = padDisplay(`${marker}${digit}${padDisplay(name, nameWidth)} ${right}`, ctx.width);
+  const lines = [first];
+
+  if (ctx.twoLine) {
+    const detail = [truncatePathLeft(session.workingDir ?? '', Math.max(0, ctx.width - 8), ctx.glyphs.ellipsis)];
+    if (mode) detail.push(mode);
+    if (tokens) detail.push(tokens);
+    const text = detail.filter((part) => part !== '').join(` ${ctx.glyphs.separator} `);
+    lines.push(padDisplay(`    ${paint(text, SGR.gray)}`, ctx.width));
+  }
+
+  return inverse ? lines.map((line) => `${SGR.inverse}${line}${SGR.reset}`) : lines;
+}
+
+function renderGroupHeader(group: TuiGroup, width: number, glyphs: TuiGlyphSet, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const label = ` ${group.label} `;
+  const fill = Math.max(0, width - visibleWidth(label));
+  return padDisplay(`${paint(label, SGR.bold)}${paint(glyphs.rule.repeat(fill), SGR.gray)}`, width);
+}
+
+export interface TuiListEntry {
+  text: string;
+  /** Set on the lines that belong to a session row, so the window can chase the cursor. */
+  sessionId?: string;
+}
+
+function buildListEntries(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): TuiListEntry[] {
+  const glyphs = glyphsFor(opts.glyphs);
+  const width = layout.list.width;
+  const entries: TuiListEntry[] = [];
+  let index = 0;
+  for (const group of model.groups()) {
+    if (group.rows.length === 0) continue;
+    entries.push({ text: renderGroupHeader(group, width, glyphs, opts) });
+    for (const row of group.rows) {
+      index++;
+      const ctx: RowContext = {
+        width,
+        index,
+        selected: row.session.sessionId === model.selectedId,
+        twoLine: layout.rowHeight === 2,
+        glyphs,
+        opts,
+      };
+      for (const text of renderRowLines(row, ctx)) entries.push({ text, sessionId: row.session.sessionId });
+    }
+  }
+  return entries;
+}
+
+/**
+ * First visible entry, scrolling the minimum needed to keep the selected row on
+ * screen. Deterministic on purpose: the window is derived, never remembered, so
+ * two identical models render identically.
+ */
+export function computeListWindow(
+  entries: readonly TuiListEntry[],
+  capacity: number,
+  selectedId: string | null
+): number {
+  if (capacity <= 0 || entries.length <= capacity) return 0;
+  const maxStart = entries.length - capacity;
+  if (!selectedId) return 0;
+  const first = entries.findIndex((entry) => entry.sessionId === selectedId);
+  if (first < 0) return 0;
+  let last = first;
+  while (last + 1 < entries.length && entries[last + 1].sessionId === selectedId) last++;
+  let start = 0;
+  if (last >= capacity) start = Math.min(last - capacity + 1, maxStart);
+  if (first < start) start = first;
+  return start;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Preview
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The pending dialog, drawn above the tail: the question, the parsed options
+ * with their digits, and the keys that answer them. Red for a permission or
+ * question prompt, yellow for an idle one, the same severity vocabulary the web
+ * inbox uses.
+ */
+export function renderApprovalCard(
+  item: ApprovalItem,
+  width: number,
+  glyphs: TuiGlyphSet,
+  opts: TuiRenderOptions
+): string[] {
+  const paint = painterFor(opts.color);
+  const card = approvalCard(item);
+  const color = card.tone === 'err' ? SGR.red : SGR.yellow;
+  const glyph = card.tone === 'err' ? glyphs.blockedPermission : glyphs.waiting;
+  const lines: string[] = [];
+  const push = (text: string, style: string): void => {
+    lines.push(padDisplay(paint(clipStyledLine(text, width), style), width));
+  };
+
+  push(` ${glyph} ${card.title}`, color);
+  for (const detail of card.detail) push(`   ${detail}`, SGR.gray);
+  for (const option of card.options) push(`   ${option.n}. ${option.label}`, '');
+  push(` ${card.hint}`, SGR.gray);
+  return lines;
+}
+
+/** The card may take half the pane at most: the tail is why the pane exists. */
+function cardCapacity(height: number): number {
+  return Math.max(0, Math.floor((height - 1) / 2));
+}
+
+/**
+ * `name · mode · dir · state`, with the DIRECTORY absorbing the squeeze: the
+ * state word is the one fact the pane exists to confirm, so it must survive a
+ * narrow preview that a full path would push off the end.
+ */
+function previewTitle(row: TuiRow, width: number, glyphs: TuiGlyphSet): string {
+  const { session } = row;
+  const sep = ` ${glyphs.separator} `;
+  const head = ` ${rowLabel(session)}${sep}${session.mode ?? 'claude'}`;
+  const tail = `${sep}${STATE_WORDS[row.state]}`;
+  const dirBudget = width - visibleWidth(head) - visibleWidth(tail) - visibleWidth(sep);
+  const dir = session.workingDir ? truncatePathLeft(session.workingDir, Math.max(0, dirBudget), glyphs.ellipsis) : '';
+  return clipStyledLine(dir ? `${head}${sep}${dir}${tail}` : `${head}${tail}`, width);
+}
+
+function buildPreviewLines(model: TuiRenderModel, rect: TuiRect, opts: TuiRenderOptions): string[] {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const lines: string[] = [];
+  const selected = model.selectedId
+    ? (model
+        .groups()
+        .flatMap((group) => group.rows)
+        .find((row) => row.session.sessionId === model.selectedId) ?? null)
+    : null;
+
+  if (!selected) {
+    lines.push(padDisplay(paint(' no session selected', SGR.gray), rect.width));
+  } else {
+    lines.push(padDisplay(paint(previewTitle(selected, rect.width, glyphs), SGR.bold), rect.width));
+  }
+
+  const budget = cardCapacity(rect.height);
+  if (selected?.approval && budget > 0) {
+    for (const line of renderApprovalCard(selected.approval, rect.width, glyphs, opts).slice(0, budget)) {
+      lines.push(line);
+    }
+    if (lines.length < rect.height) lines.push(' '.repeat(rect.width));
+  }
+
+  const body = previewBody(model, selected, rect, opts, rect.height - lines.length);
+  for (const line of body) lines.push(line);
+  while (lines.length < rect.height) lines.push(' '.repeat(rect.width));
+  return lines.slice(0, Math.max(0, rect.height));
+}
+
+function previewBody(
+  model: TuiRenderModel,
+  selected: TuiRow | null,
+  rect: TuiRect,
+  opts: TuiRenderOptions,
+  capacity: number
+): string[] {
+  const paint = painterFor(opts.color);
+  if (capacity <= 0) return [];
+  const hint = (text: string): string[] => [padDisplay(paint(` ${text}`, SGR.gray), rect.width)];
+
+  if (!selected) return [];
+  if (model.connection === 'degraded' || model.connection === 'down') {
+    return hint('preview unavailable while the server is down');
+  }
+  const preview = model.preview;
+  if (!preview || preview.sessionId !== selected.session.sessionId) return hint('loading preview…');
+  if (preview.note) return hint(preview.note);
+  if (preview.error) return hint(preview.error);
+
+  const trimmed = [...preview.lines];
+  while (trimmed.length > 0 && trimmed[trimmed.length - 1].trim() === '') trimmed.pop();
+  if (trimmed.length === 0) return hint('(no output yet)');
+  // The tail carries the session's OWN colors, which is the point of the pane,
+  // but under NO_COLOR they must go too.
+  return trimmed
+    .slice(-capacity)
+    .map((line) => padDisplay(` ${clipStyledLine(opts.color ? line : stripStyles(line), rect.width - 1)}`, rect.width));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Chrome
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Sessions with a prompt waiting on a human, which is what the badge counts. */
+export function pendingApprovalCount(model: TuiRenderModel): number {
+  let count = 0;
+  for (const group of model.groups()) for (const row of group.rows) if (row.approval) count++;
+  return count;
+}
+
+function renderHeaderLine(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const { hostname, instance, version, planUsage } = model.header;
+  const facts = [
+    instance ? `${hostname ?? ''}:${instance}` : (hostname ?? ''),
+    version ? `v${version}` : '',
+    `${model.sessionCount} session${model.sessionCount === 1 ? '' : 's'}`,
+    planUsage ?? '',
+  ].filter((part) => part !== '');
+
+  const pending = pendingApprovalCount(model);
+  const badge = pending > 0 ? `${paint(`${glyphs.blockedPermission} ${pending}`, SGR.red)}  ` : '';
+  const left = ` ${paint('codeman', SGR.bold)}  ${badge}${paint(facts.join(` ${glyphs.separator} `), SGR.gray)}`;
+  const right = paint('? help  q quit ', SGR.gray);
+  const gap = layout.cols - visibleWidth(left) - visibleWidth(right);
+  if (gap < 1) return padDisplay(left, layout.cols);
+  return `${left}${' '.repeat(gap)}${right}`;
+}
+
+function renderBannerLine(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const [text, color] =
+    model.connection === 'degraded'
+      ? ['server not running: attach only', SGR.yellow]
+      : model.connection === 'reconnecting'
+        ? ['reconnecting to the server…', SGR.yellow]
+        : ['server unreachable', SGR.red];
+  return padDisplay(paint(` ${glyphs.blockedPermission} ${text}`, color), layout.cols);
+}
+
+const FOOTER_KEYS: Record<string, (glyphs: TuiGlyphSet) => string> = {
+  list: (g) =>
+    [
+      `${g.updown} select`,
+      `${g.enter} attach`,
+      '1-9 switch',
+      'y/n answer',
+      'p prompt',
+      'n new',
+      'x kill',
+      '/ search',
+      'g digest',
+      '? help',
+      'q quit',
+    ].join(` ${g.separator} `),
+  help: (g) => `esc ${g.separator} ? close`,
+  'confirm-kill': (g) => `y kill ${g.separator} any other key cancels`,
+  message: () => 'esc dismiss',
+  prompt: (g) => `${g.enter} send ${g.separator} esc cancel`,
+  search: (g) => `${g.updown} results ${g.separator} ${g.enter} open ${g.separator} esc close`,
+  digest: (g) => `j/k ${g.separator} ${g.updown} scroll ${g.separator} esc close`,
+  'new-session': (g) => `${g.updown} select ${g.separator} ${g.enter} choose ${g.separator} esc cancel`,
+};
+
+/**
+ * The composer's prefix. Fixed width on purpose: the terminal cursor is placed
+ * by column arithmetic (`composerCursorCell`), and a prefix that changed with
+ * the session name would move the cursor with it.
+ */
+export const COMPOSER_PREFIX = ' > ';
+
+function renderComposerLine(prompt: TuiPromptState, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const window = composerWindow(prompt.composer, Math.max(1, layout.cols - visibleWidth(COMPOSER_PREFIX)));
+  return padDisplay(`${paint(COMPOSER_PREFIX, SGR.cyan)}${window.text}`, layout.cols);
+}
+
+/**
+ * Where the terminal's own cursor belongs, or null when nothing is being typed
+ * into a single-line editor. The app shows the cursor there and hides it
+ * otherwise, because a blinking cursor parked in a dashboard reads as a bug.
+ */
+export function composerCursorCell(model: TuiRenderModel, layout: TuiLayout): { row: number; col: number } | null {
+  if (model.mode !== 'prompt' || !model.prompt || layout.footer.height <= 0) return null;
+  const prefix = visibleWidth(COMPOSER_PREFIX);
+  const window = composerWindow(model.prompt.composer, Math.max(1, layout.cols - prefix));
+  return { row: layout.footer.row, col: Math.min(layout.cols, prefix + 1 + window.cursorColumn) };
+}
+
+function renderFooterLine(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  if (model.mode === 'prompt' && model.prompt) return renderComposerLine(model.prompt, layout, opts);
+  const text = opts.footerKeys
+    ? opts.footerKeys.join(` ${glyphs.separator} `)
+    : (FOOTER_KEYS[model.mode] ?? FOOTER_KEYS.list)(glyphs);
+  return padDisplay(paint(clipStyledLine(` ${text}`, layout.cols), SGR.gray), layout.cols);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Overlays
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface OverlayContent {
+  title: string;
+  lines: string[];
+  /**
+   * Floor for the box's inner width. The search and digest panels are lists
+   * people scan, so they keep a stable width instead of snapping around their
+   * longest current line.
+   */
+  minWidth?: number;
+}
+
+function wrapText(text: string, width: number): string[] {
+  if (width <= 0) return [];
+  const out: string[] = [];
+  let line = '';
+  for (const word of text.split(/\s+/).filter((part) => part !== '')) {
+    const candidate = line === '' ? word : `${line} ${word}`;
+    if (visibleWidth(candidate) > width && line !== '') {
+      out.push(line);
+      line = word;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line !== '') out.push(line);
+  return out.length > 0 ? out : [''];
+}
+
+function helpLines(glyphs: TuiGlyphSet, custom?: ReadonlyArray<readonly [string, string]>): string[] {
+  const pairs: ReadonlyArray<readonly [string, string]> = custom ?? [
+    [`${glyphs.updown} / j k`, 'select'],
+    [glyphs.enter, 'attach'],
+    ['1-9', 'jump'],
+    ['y / n', 'answer the pending approval'],
+    ['p', 'send a prompt'],
+    ['n', 'new session'],
+    ['x', 'kill (typed confirmation)'],
+    ['/', 'search'],
+    ['g', 'away digest'],
+    ['?', 'this help'],
+    ['q', 'quit'],
+  ];
+  const keyWidth = Math.max(...pairs.map(([key]) => visibleWidth(key)));
+  return pairs.map(([key, description]) => `${padDisplay(key, keyWidth)}  ${description}`);
+}
+
+/** Longest item list a picker overlay shows, however tall the terminal is. */
+const PICKER_MAX_ROWS = 10;
+
+/**
+ * A picker's lines: hint, a window of items around the cursor, then the filter
+ * echo. Windowed rather than clipped, so the selected item is always visible in
+ * a long case list.
+ */
+function pickerLines(picker: TuiPickerState, glyphs: TuiGlyphSet, capacity: number): string[] {
+  const head: string[] = picker.hint ? [picker.hint, ''] : [];
+  const tail: string[] = picker.filter === undefined ? [] : ['', `filter: ${picker.filter}_`];
+  if (picker.items.length === 0) return [...head, '(nothing to choose)', ...tail];
+
+  const budget = Math.max(1, Math.min(PICKER_MAX_ROWS, capacity - head.length - tail.length));
+  const first = Math.max(0, Math.min(picker.index - Math.floor(budget / 2), picker.items.length - budget));
+  const rows = picker.items.slice(first, first + budget).map((item, i) => {
+    const marker = first + i === picker.index ? glyphs.cursor : ' '.repeat(visibleWidth(glyphs.cursor));
+    return `${marker} ${item.label}${item.detail ? `  ${item.detail}` : ''}`;
+  });
+  return [...head, ...rows, ...tail];
+}
+
+/**
+ * The `/` overlay: the query with a caret, one status line, then the results.
+ *
+ * The caret is a trailing `_` rather than the terminal's own cursor, and that is
+ * why the search keymap leaves left/right to the result list: a caret that
+ * cannot move is honest, an invisible one that can is not.
+ */
+function searchLines(state: TuiSearchState, glyphs: TuiGlyphSet, capacity: number): string[] {
+  const head = [`${composerText(state.composer)}_`];
+  if (state.note) head.push(state.note);
+  head.push('');
+
+  const budget = Math.max(1, capacity - head.length);
+  if (state.entries.length === 0) {
+    return [...head, state.status === 'searching' ? 'searching…' : '(type to search sessions, events and files)'];
+  }
+  const first = Math.max(0, Math.min(state.index - Math.floor(budget / 2), state.entries.length - budget));
+  const rows = state.entries.slice(first, first + budget).map((entry, i) => {
+    if (entry.kind === 'header') return entry.text;
+    const marker = first + i === state.index ? glyphs.cursor : ' '.repeat(visibleWidth(glyphs.cursor));
+    return `${marker} ${entry.text}${entry.detail ? `  ${entry.detail}` : ''}`;
+  });
+  return [...head, ...rows];
+}
+
+/** Lines an overlay box can show inside its border, given the body's height. */
+function overlayCapacity(height: number): number {
+  return Math.max(1, height - 2);
+}
+
+/**
+ * How many digest lines fit. Exported because the app scrolls by pages and must
+ * not scroll the last page into empty space, which needs this exact number.
+ */
+export function digestCapacity(layout: TuiLayout): number {
+  return overlayCapacity(layout.body.height);
+}
+
+function digestLines(state: TuiDigestState, capacity: number): string[] {
+  const offset = Math.min(Math.max(0, state.offset), Math.max(0, state.lines.length - 1));
+  return state.lines.slice(offset, offset + capacity);
+}
+
+function overlayContent(
+  model: TuiRenderModel,
+  opts: TuiRenderOptions,
+  width: number,
+  height: number
+): OverlayContent | null {
+  const glyphs = glyphsFor(opts.glyphs);
+  const panelWidth = Math.max(20, Math.min(width - 8, 72));
+  switch (model.mode) {
+    case 'help':
+      return { title: 'Keys', lines: helpLines(glyphs, opts.helpKeys) };
+    case 'search': {
+      if (!model.search) return null;
+      return {
+        title: 'Search',
+        lines: searchLines(model.search, glyphs, overlayCapacity(height)),
+        minWidth: panelWidth,
+      };
+    }
+    case 'digest': {
+      if (!model.digest) return null;
+      return {
+        title: model.digest.title,
+        lines: digestLines(model.digest, overlayCapacity(height)),
+        minWidth: panelWidth,
+      };
+    }
+    case 'new-session': {
+      if (!model.picker) return null;
+      return { title: model.picker.title, lines: pickerLines(model.picker, glyphs, Math.max(1, height - 2)) };
+    }
+    case 'confirm-kill': {
+      if (!model.confirm) return null;
+      return {
+        title: 'Kill session',
+        lines: [`Kill ${model.confirm.name}?`, '', 'press y to kill, any other key cancels'],
+      };
+    }
+    case 'message':
+      if (!model.message) return null;
+      return {
+        title: model.message.tone === 'err' ? 'Error' : model.message.tone === 'warn' ? 'Warning' : 'Notice',
+        lines: wrapText(model.message.text, Math.max(8, width - 8)),
+      };
+    default:
+      return null;
+  }
+}
+
+/** Paint an overlay box over the body, centered, replacing whole terminal rows. */
+function applyOverlay(lines: string[], model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): void {
+  const body = layout.body;
+  if (body.height < 3 || body.width < 12) return;
+  const content = overlayContent(model, opts, body.width, body.height);
+  if (!content) return;
+
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+  const maxInner = body.width - 4;
+  const visible = content.lines.slice(0, Math.max(1, body.height - 2));
+  const inner = Math.min(
+    maxInner,
+    Math.max(content.minWidth ?? 0, visibleWidth(content.title) + 2, ...visible.map((line) => visibleWidth(line)))
+  );
+  const boxWidth = inner + 4;
+  const boxHeight = visible.length + 2;
+  const left = body.col + Math.max(0, Math.floor((body.width - boxWidth) / 2));
+  const top = body.row + Math.max(0, Math.floor((body.height - boxHeight) / 2));
+
+  const titleText = ` ${content.title} `;
+  const titleFill = Math.max(0, inner + 2 - visibleWidth(titleText));
+  const boxLines = [
+    `${glyphs.boxTopLeft}${titleText}${glyphs.boxHorizontal.repeat(titleFill)}${glyphs.boxTopRight}`,
+    ...visible.map((line) => `${glyphs.boxVertical} ${padDisplay(line, inner)} ${glyphs.boxVertical}`),
+    `${glyphs.boxBottomLeft}${glyphs.boxHorizontal.repeat(inner + 2)}${glyphs.boxBottomRight}`,
+  ];
+
+  for (let i = 0; i < boxLines.length; i++) {
+    const row = top + i - 1;
+    if (row < 0 || row >= lines.length) continue;
+    lines[row] = `${' '.repeat(left - 1)}${paint(boxLines[i], SGR.cyan)}`;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frame
+// ─────────────────────────────────────────────────────────────────────────────
+
+function writeBody(lines: string[], model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): void {
+  const { list, preview, divider } = layout;
+  if (list.height <= 0) return;
+  const paint = painterFor(opts.color);
+  const glyphs = glyphsFor(opts.glyphs);
+
+  const entries = buildListEntries(model, layout, opts);
+  if (entries.length === 0) {
+    const hint = paint('No sessions. n to start one, q to quit.', SGR.gray);
+    const row = list.row + Math.floor((list.height - 1) / 2);
+    lines[row - 1] = centered(hint, layout.cols);
+    return;
+  }
+
+  const start = computeListWindow(entries, list.height, model.selectedId);
+  const previewLines = preview ? buildPreviewLines(model, preview, opts) : [];
+
+  for (let i = 0; i < list.height; i++) {
+    const left = entries[start + i]?.text ?? ' '.repeat(list.width);
+    if (!preview || !divider) {
+      lines[list.row - 1 + i] = left;
+      continue;
+    }
+    const right = previewLines[i] ?? ' '.repeat(preview.width);
+    lines[list.row - 1 + i] = `${left}${paint(glyphs.divider, SGR.gray)}${right}`;
+  }
+}
+
+/**
+ * The whole frame as one string: absolute cursor addressing per line, each line
+ * closed with an erase-to-end so a shorter line cannot leave the previous
+ * frame's tail behind.
+ */
+export function renderFrame(model: TuiRenderModel, layout: TuiLayout, opts: TuiRenderOptions): string {
+  const lines: string[] = new Array<string>(layout.rows).fill('');
+  lines[0] = renderHeaderLine(model, layout, opts);
+  if (layout.banner) lines[layout.banner.row - 1] = renderBannerLine(model, layout, opts);
+  writeBody(lines, model, layout, opts);
+  if (layout.footer.height > 0) lines[layout.footer.row - 1] = renderFooterLine(model, layout, opts);
+  applyOverlay(lines, model, layout, opts);
+
+  let frame = '';
+  for (let i = 0; i < lines.length; i++) {
+    frame += `\x1b[${i + 1};1H${clipStyledLine(lines[i], layout.cols)}\x1b[K`;
+  }
+  return frame;
+}

src/tui/tui-sse.ts

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Pure SSE wire parsing, event classification and reconnect math.
+ *
+ * Node has no `EventSource`, so the TUI reads `GET /api/events` as a raw stream
+ * and decodes the wire format here. Everything in this module is pure: bytes
+ * (as decoded strings) in, frames out. The socket, the timers and the backoff
+ * loop live in `tui-client.ts`.
+ *
+ * Three wire details this parser exists to get right:
+ *
+ * 1. **Frames split across chunk boundaries.** A TCP read can end anywhere,
+ *    including between the `\r` and the `\n` of a CRLF, so a lone trailing
+ *    `\r` is held back rather than treated as a line end.
+ * 2. **Comments are not frames.** The server appends a `:pppp…` padding line
+ *    after a frame while a Cloudflare tunnel is up (it flushes the proxy
+ *    buffer) and that line carries no blank line after it. Dispatch happens on
+ *    a blank line and on nothing else, so padding cannot split a frame.
+ * 3. **The keepalive is a NAMED event** (`sse:heartbeat`), because an SSE
+ *    comment is invisible to a browser `EventSource` by spec. We treat ANY
+ *    inbound bytes as liveness, comments included, which is why comments need
+ *    no representation in the returned frames.
+ *
+ * @module tui/tui-sse
+ */
+
+import {
+  ApprovalPending,
+  ApprovalResolved,
+  ApprovalUpdated,
+  Heartbeat,
+  Init,
+  MuxCreated,
+  MuxDied,
+  MuxKilled,
+  RemoteSessionDropped,
+  RemoteSessionReconnected,
+  SessionCliInfo,
+  SessionCompletion,
+  SessionCreated,
+  SessionDeleted,
+  SessionError,
+  SessionExit,
+  SessionIdle,
+  SessionInteractive,
+  SessionPinned,
+  SessionRunning,
+  SessionStatusTelemetry,
+  SessionUpdated,
+  SessionWorking,
+} from '../web/sse-events.js';
+
+/** One dispatched SSE frame. `event` defaults to `message` per the spec. */
+export interface SseFrame {
+  event: string;
+  data: string;
+  id?: string;
+  retry?: number;
+}
+
+/**
+ * Ceiling on the unterminated tail the parser will hold. The `init` frame
+ * carries the whole light state and is legitimately large, so this is not a
+ * frame-size limit but a guard against a non-SSE endpoint streaming something
+ * with no line terminators at all.
+ */
+export const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+
+/** Incremental decoder. One instance per connection; `reset()` on reconnect. */
+export class SseFrameParser {
+  private buffer = '';
+  private eventName = '';
+  private dataLines: string[] = [];
+  private lastId: string | undefined;
+  private retry: number | undefined;
+
+  /** Decode one chunk, returning every frame it completed (possibly none). */
+  feed(chunk: string): SseFrame[] {
+    this.buffer += chunk;
+    const frames: SseFrame[] = [];
+    let start = 0;
+
+    for (let i = 0; i < this.buffer.length; i++) {
+      const ch = this.buffer[i];
+      if (ch !== '\n' && ch !== '\r') continue;
+      // A trailing CR may be the first half of a CRLF the next chunk finishes.
+      if (ch === '\r' && i === this.buffer.length - 1) break;
+      const line = this.buffer.slice(start, i);
+      if (ch === '\r' && this.buffer[i + 1] === '\n') i++;
+      start = i + 1;
+      const frame = this.consumeLine(line);
+      if (frame) frames.push(frame);
+    }
+
+    this.buffer = this.buffer.slice(start);
+    if (this.buffer.length > MAX_PENDING_BYTES) this.reset();
+    return frames;
+  }
+
+  /** Drop every partial frame. Called when a connection is torn down. */
+  reset(): void {
+    this.buffer = '';
+    this.eventName = '';
+    this.dataLines = [];
+    this.lastId = undefined;
+    this.retry = undefined;
+  }
+
+  private consumeLine(line: string): SseFrame | null {
+    if (line === '') return this.dispatch();
+    if (line.startsWith(':')) return null;
+
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? '' : line.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+
+    switch (field) {
+      case 'event':
+        this.eventName = value;
+        break;
+      case 'data':
+        this.dataLines.push(value);
+        break;
+      case 'id':
+        this.lastId = value;
+        break;
+      case 'retry': {
+        const ms = Number.parseInt(value, 10);
+        if (Number.isSafeInteger(ms) && ms >= 0) this.retry = ms;
+        break;
+      }
+      default:
+        break;
+    }
+    return null;
+  }
+
+  /**
+   * A blank line ends a frame. Per the spec an empty data buffer dispatches
+   * nothing (it still clears the event name), which is what makes a bare
+   * `event:` line or a stray blank line harmless.
+   */
+  private dispatch(): SseFrame | null {
+    if (this.dataLines.length === 0) {
+      this.eventName = '';
+      return null;
+    }
+    const frame: SseFrame = {
+      event: this.eventName || 'message',
+      data: this.dataLines.join('\n'),
+    };
+    if (this.lastId !== undefined) frame.id = this.lastId;
+    if (this.retry !== undefined) frame.retry = this.retry;
+    this.eventName = '';
+    this.dataLines = [];
+    return frame;
+  }
+}
+
+/** What the app layer should do with a frame. */
+export type SseEventClass = 'init' | 'heartbeat' | 'resync' | 'approval' | 'plan-usage' | 'ignore';
+
+/**
+ * Events that change WHICH sessions exist or WHAT state they are in.
+ *
+ * The TUI never patches a single row from a payload: it re-fetches the unified
+ * list, which is the only source that also carries history rows, so this set
+ * only has to answer "is a refetch worth it". `session:terminal` is
+ * deliberately absent (it is the bulk of the stream and the preview pane pulls
+ * its own tail), as are the ralph/respawn/subagent/orchestrator families, which
+ * change nothing the dashboard draws.
+ */
+const RESYNC_EVENTS: ReadonlySet<string> = new Set<string>([
+  SessionCreated,
+  SessionUpdated,
+  SessionDeleted,
+  SessionExit,
+  SessionError,
+  SessionIdle,
+  SessionWorking,
+  SessionCompletion,
+  SessionInteractive,
+  SessionRunning,
+  SessionPinned,
+  SessionCliInfo,
+  MuxCreated,
+  MuxKilled,
+  MuxDied,
+  RemoteSessionDropped,
+  RemoteSessionReconnected,
+]);
+
+const APPROVAL_EVENTS: ReadonlySet<string> = new Set<string>([ApprovalPending, ApprovalUpdated, ApprovalResolved]);
+
+/** Which approval event this is, or null when the name is not one. */
+export function approvalEventKind(name: string): 'pending' | 'updated' | 'resolved' | null {
+  if (name === ApprovalPending) return 'pending';
+  if (name === ApprovalUpdated) return 'updated';
+  if (name === ApprovalResolved) return 'resolved';
+  return null;
+}
+
+/** Route one event name. Unknown names are ignored, never a resync. */
+export function classifySseEvent(name: string): SseEventClass {
+  if (name === Init) return 'init';
+  if (name === Heartbeat) return 'heartbeat';
+  if (APPROVAL_EVENTS.has(name)) return 'approval';
+  if (name === SessionStatusTelemetry) return 'plan-usage';
+  if (RESYNC_EVENTS.has(name)) return 'resync';
+  return 'ignore';
+}
+
+/**
+ * Silence that means the stream is dead even though the socket never errored.
+ * The server heartbeats every 15s, so three missed beats is the signal.
+ */
+export const SSE_STALE_TIMEOUT_MS = 45_000;
+
+/** Reconnect delay ceiling. A local server is back in milliseconds, not minutes. */
+export const SSE_MAX_BACKOFF_MS = 15_000;
+
+/** First reconnect delay; doubles per consecutive failure up to the ceiling. */
+export const SSE_BASE_BACKOFF_MS = 500;
+
+/**
+ * Delay before reconnect attempt `attempt` (1-based). Deterministic, with no
+ * jitter on purpose: one client talks to one loopback server, so there is no
+ * herd to spread out and a reproducible delay is testable.
+ */
+export function sseBackoffDelay(attempt: number, base = SSE_BASE_BACKOFF_MS, max = SSE_MAX_BACKOFF_MS): number {
+  const step = Math.max(1, Math.trunc(attempt));
+  const exponent = Math.min(step - 1, 30);
+  return Math.min(max, base * 2 ** exponent);
+}

src/tui/tui-types.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Shared types for the `codeman tui` pure core.
+ *
+ * The TUI is a client of the server, never a second brain: its rows are the
+ * rows `GET /api/sessions/unified` already returns (`UnifiedSessionItem`) and
+ * its blocked states are the items `GET /api/approvals` already parsed
+ * (`ApprovalItem`). Both are imported as TYPES only, so nothing here pulls the
+ * server, node-pty or the utils barrel into a CLI process.
+ *
+ * Everything in `src/tui/*` except `tui-app.ts` / `tui-client.ts` is pure:
+ * deterministic outputs from inputs, no `process.*`, no timers, no IO.
+ *
+ * @module tui/tui-types
+ */
+
+import type { UnifiedSessionItem } from '../services/unified-session-service.js';
+import type { ApprovalItem } from '../web/approval-inbox.js';
+import type { TuiComposerState } from './tui-composer.js';
+
+/**
+ * A unified-list row plus the few live-only extras the dashboard shows.
+ *
+ * The unified list is the spine (it is the only source that carries history
+ * rows), but it has no token counters and no turn-start stamp, so the client
+ * merges those from the live session payload (`GET /api/sessions` /
+ * `session_updated` SSE) when a row is live. History rows simply lack them.
+ */
+export interface TuiSessionRow extends UnifiedSessionItem {
+  /**
+   * Wall-clock ms of the pane's last Enter (`SessionState.lastSubmitAt`). The
+   * only usable "working since" anchor: a working pane repaints about once a
+   * second, so its `lastActivityAt` is always "now".
+   */
+  lastSubmitAt?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  /**
+   * tmux session name to attach to (`codeman-<first 8 of the id>`).
+   *
+   * The unified list does not carry it (no server view merges the mux name into
+   * a row), so the app layer fills it in from the local tmux enumeration, which
+   * is also the only thing that proves the pane really exists. A row without one
+   * cannot be attached: it is either history or a direct-PTY session.
+   */
+  muxName?: string;
+}
+
+/**
+ * Row state, in the web UI's vocabulary so both surfaces read the same.
+ *
+ * There is deliberately no `error` member: an errored session is something a
+ * human has to look at, so it classifies as `waiting` and lands in NEEDS YOU
+ * rather than growing a fifth color nobody designed.
+ */
+export type TuiSessionState = 'blocked-question' | 'blocked-permission' | 'waiting' | 'working' | 'idle' | 'recent';
+
+/** The four display groups, in display order. */
+export type TuiGroupKey = 'needs-you' | 'working' | 'idle' | 'recent';
+
+/** A classified session: what the cursor moves over and the renderer paints. */
+export interface TuiRow {
+  session: TuiSessionRow;
+  state: TuiSessionState;
+  group: TuiGroupKey;
+  /** The pending prompt that blocks this session, when it has one. */
+  approval?: ApprovalItem;
+  /** Epoch ms the session entered `state`; the intra-group sort key. 0 when unknown. */
+  since: number;
+}
+
+export interface TuiGroup {
+  key: TuiGroupKey;
+  label: string;
+  rows: TuiRow[];
+}
+
+/** How the client currently sees the server. */
+export type TuiConnectionStatus = 'connected' | 'reconnecting' | 'degraded' | 'down';
+
+/** Which overlay (if any) owns the keyboard. */
+export type TuiUiMode = 'list' | 'help' | 'confirm-kill' | 'prompt' | 'search' | 'digest' | 'message' | 'new-session';
+
+/**
+ * Glyph capability tier. Detection is env-driven and therefore lives in a tiny
+ * function the app layer calls (`detectGlyphTier`); the renderer only ever
+ * takes the resolved tier as an input.
+ */
+export type TuiGlyphTier = 'nerd' | 'unicode' | 'ascii';
+
+/** Header facts, all optional: the header degrades to just the product name. */
+export interface TuiHeaderInfo {
+  hostname?: string;
+  instance?: string;
+  version?: string;
+  /** Plan-usage chip text, e.g. `5h 32% · wk 61%`. */
+  planUsage?: string;
+}
+
+/** The selected session's terminal tail, already run through `toDisplayLines()`. */
+export interface TuiPreview {
+  sessionId: string;
+  /** Display lines, oldest first. */
+  lines: string[];
+  /** Set instead of lines when the tail could not be fetched. */
+  error?: string;
+  /**
+   * Set instead of lines when there is nothing to fetch (a history row has no
+   * live buffer). Distinct from `error`: nothing failed, so it must not read
+   * like something did.
+   */
+  note?: string;
+}
+
+export interface TuiMessage {
+  text: string;
+  tone: 'info' | 'warn' | 'err';
+}
+
+/** Typed-confirmation state for `x` (kill): the user retypes the session name. */
+export interface TuiConfirmState {
+  sessionId: string;
+  name: string;
+}
+
+export interface TuiPickerItem {
+  /** What choosing this item means to the caller; never shown. */
+  id: string;
+  label: string;
+  /** Second column, dimmed (a case path, a mode description). */
+  detail?: string;
+}
+
+/**
+ * A one-column chooser drawn as an overlay (the case and mode pickers behind
+ * `n`). Items are already filtered: the app owns the unfiltered list, the
+ * renderer only paints what it is given.
+ */
+export interface TuiPickerState {
+  title: string;
+  items: TuiPickerItem[];
+  /** Index into `items`; -1 when the list is empty. */
+  index: number;
+  /** Current filter text, when the picker filters as you type. */
+  filter?: string;
+  /** One line above the list: what is being chosen, or why the list is empty. */
+  hint?: string;
+}
+
+/** The `p` composer: one line aimed at one session. */
+export interface TuiPromptState {
+  sessionId: string;
+  /** What the session is called on screen, for the footer prefix. */
+  label: string;
+  composer: TuiComposerState;
+}
+
+/**
+ * One line of the `/` overlay. Group headers are chrome (the API returns typed
+ * groups), so only `result` rows are selectable.
+ */
+export interface TuiSearchEntry {
+  kind: 'header' | 'result';
+  text: string;
+  detail?: string;
+  sessionId?: string;
+  /** The row can hand the dashboard a session that is open right now. */
+  live?: boolean;
+}
+
+export interface TuiSearchState {
+  composer: TuiComposerState;
+  /** The query `entries` answer. Lags the composer while a search is in flight. */
+  query: string;
+  entries: TuiSearchEntry[];
+  /** Index into `entries`, always a `result` row; -1 when none is selectable. */
+  index: number;
+  status: 'idle' | 'searching' | 'done' | 'error';
+  /** One line under the query: what happened, or why there is nothing. */
+  note?: string;
+}
+
+/** The `g` overlay: pre-formatted lines plus where the window starts. */
+export interface TuiDigestState {
+  title: string;
+  lines: string[];
+  offset: number;
+}
+
+/**
+ * What `renderFrame()` reads. The store implements it; a test can hand-build
+ * one, which is what keeps the renderer testable without the model.
+ */
+export interface TuiRenderModel {
+  groups(): TuiGroup[];
+  readonly selectedId: string | null;
+  readonly connection: TuiConnectionStatus;
+  readonly mode: TuiUiMode;
+  readonly header: TuiHeaderInfo;
+  readonly preview: TuiPreview | null;
+  readonly message: TuiMessage | null;
+  readonly confirm: TuiConfirmState | null;
+  /** Optional so a test can hand-build a model without one. */
+  readonly picker?: TuiPickerState | null;
+  readonly prompt?: TuiPromptState | null;
+  readonly search?: TuiSearchState | null;
+  readonly digest?: TuiDigestState | null;
+  /** Live sessions only (RECENT rows are history, not sessions you have open). */
+  readonly sessionCount: number;
+}

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' | 'omp' (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,21 @@ 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'
+  | 'omp';
 
 export type RemoteCommandMode = Extract<
   SessionMode,
-  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'
+  'shell' | 'claude' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp'
 >;
 
 /**
@@ -157,7 +169,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' | 'omp'
 >;
 
 /** Container engine. Docker and Podman differ in the uid/userns + host-gateway alias. */
@@ -332,6 +344,16 @@ export interface AntigravityConfig {
   resumeConversationId?: string;
 }
 
+/** OMP CLI session configuration */
+export interface OmpConfig {
+  /** Model identifier (e.g., "crof/glm-5.2"). Passed via --model. */
+  model?: string;
+  /** Resume a previous conversation (passed via --resume). */
+  resumeSessionId?: string;
+  /** Continue the most recent session in this directory (passed via --continue). */
+  continueSession?: boolean;
+}
+
 /**
  * Pi CLI (pi.dev) session configuration.
  *
@@ -363,6 +385,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
  */
@@ -500,6 +601,14 @@ export interface SessionState {
   color?: SessionColor;
   /** Flicker filter enabled (buffers output after screen clears) */
   flickerFilterEnabled?: boolean;
+  /**
+   * True while the CLI in the pane has a mouse-tracking DECSET on, as observed
+   * by the server on its way out of the stream (those sequences are stripped for
+   * claude/codex/gemini, so the browser can never see them itself). The browser
+   * hand-encodes a click report ONLY when this is true; without it, every click
+   * sent mouse reports to a CLI that never asked for them.
+   */
+  cliMouseTracking?: boolean;
   /** Claude Code CLI version (parsed from terminal, e.g., "2.1.27") */
   cliVersion?: string;
   /** Claude model in use (parsed from terminal, e.g., "Opus 4.5") */
@@ -518,6 +627,12 @@ 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;
+  /** OMP-specific configuration (only for mode === 'omp') */
+  ompConfig?: OmpConfig;
   /** 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/update.ts

@@ -98,3 +98,52 @@ export interface UpdateCheckResult {
   source: 'github-api' | 'git-ls-remote' | 'none';
   error?: string;
 }
+
+/**
+ * Role of a remote in the repository-status view.
+ * - `tracking`: the current branch's `@{upstream}` remote (where `git pull` goes).
+ * - `upstream`: the canonical project (a remote named `origin`/`upstream` that is
+ *   not the tracking remote).
+ * - `other`: anything else explicitly requested via `CODEMAN_UPDATE_REMOTES`.
+ */
+export type RepoRemoteRole = 'tracking' | 'upstream' | 'other';
+
+/** A single incoming commit — present on the remote ref but not in local HEAD. */
+export interface RepoIncomingCommit {
+  /** Abbreviated SHA. */
+  sha: string;
+  /** Commit subject (first line). */
+  subject: string;
+}
+
+/** Ahead/behind + incoming summary for local HEAD vs one remote's compare ref. */
+export interface RepoRemoteStatus {
+  /** Remote name, e.g. `origin`, `bitbucket`. */
+  name: string;
+  /** Remote URL (best-effort; empty if unresolved). */
+  url: string;
+  role: RepoRemoteRole;
+  /** Ref HEAD is compared against, e.g. `origin/master`, `bitbucket/local`. */
+  compareRef: string;
+  /** Commits in local HEAD not on the remote ref (local-only / unpushed). */
+  ahead: number;
+  /** Commits on the remote ref not in local HEAD (incoming). */
+  behind: number;
+  /** Up to N most recent incoming commits (newest first). */
+  incoming: RepoIncomingCommit[];
+  /** Set when this remote could not be fetched/compared. */
+  error?: string;
+}
+
+/** Result of the repository-status check across the configured remotes. */
+export interface RepositoryStatusResult {
+  /** epoch ms of the check. */
+  checkedAt: number;
+  /** False when this is not a git install (then `remotes` is empty + `error` set). */
+  isGit: boolean;
+  /** Current running version, for display. */
+  currentVersion: string;
+  remotes: RepoRemoteStatus[];
+  /** Top-level error (e.g. not a git install, or no remotes resolved). */
+  error?: string;
+}

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/antigravity-cli-resolver.ts

@@ -7,22 +7,37 @@
  * @module utils/antigravity-cli-resolver
  */
 
-import { execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+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 Antigravity CLI binary may be installed */
 const ANTIGRAVITY_SEARCH_DIRS = [
   join(homedir(), '.local', 'bin'),
   join(homedir(), '.antigravity', 'bin'),
   '/usr/local/bin',
+  join(homedir(), '.bun', 'bin'),
+  join(homedir(), '.npm-global', 'bin'),
   join(homedir(), 'bin'),
 ];
 
-/** Cached directory containing the agy binary (empty string = searched but not found) */
-let _antigravityDir: string | null = null;
+const ANTIGRAVITY_NOT_FOUND =
+  'Antigravity CLI not found. Install with: curl -fsSL https://antigravity.google/cli/install.sh | bash';
+
+function createAntigravityResolver(host?: CliResolverHost, now?: () => number) {
+  return createCliExecutableResolver({ binary: 'agy', searchDirs: ANTIGRAVITY_SEARCH_DIRS, now }, host);
+}
+
+/** Creates an isolated Antigravity wrapper around an injected resolver host and clock. */
+export function createAntigravityResolverForTest(host: CliResolverHost, now?: () => number) {
+  return createAntigravityResolver(host, now);
+}
+
+const antigravityResolver = createAntigravityResolver();
 
 /**
  * Finds the directory containing the `agy` binary.
@@ -31,30 +46,7 @@ let _antigravityDir: string | null = null;
  * @returns Directory path, or null if not found
  */
 export function resolveAntigravityDir(): string | null {
-  if (_antigravityDir !== null) return _antigravityDir || null;
-
-  try {
-    const result = execSync('which agy', {
-      encoding: 'utf-8',
-      timeout: EXEC_TIMEOUT_MS,
-    }).trim();
-    if (result && existsSync(result)) {
-      _antigravityDir = dirname(result);
-      return _antigravityDir;
-    }
-  } catch {
-    // agy not in PATH, will check common locations
-  }
-
-  for (const dir of ANTIGRAVITY_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'agy'))) {
-      _antigravityDir = dir;
-      return _antigravityDir;
-    }
-  }
-
-  _antigravityDir = '';
-  return null;
+  return antigravityResolver.resolve()?.directory ?? null;
 }
 
 /**
@@ -63,3 +55,7 @@ export function resolveAntigravityDir(): string | null {
 export function isAntigravityAvailable(): boolean {
   return resolveAntigravityDir() !== null;
 }
+
+export function getAntigravityNotFoundMessage(): string {
+  return formatCliNotFoundMessage(ANTIGRAVITY_NOT_FOUND, antigravityResolver.diagnostics());
+}

src/utils/claude-cli-resolver.ts

@@ -8,11 +8,11 @@
  * @module utils/claude-cli-resolver
  */
 
-import { execSync, execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { delimiter, join } from 'node:path';
 import { homedir } from 'node:os';
 import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import { createCliExecutableResolver, formatCliNotFoundMessage } from './cli-executable-resolver.js';
 
 /** Common directories where the Claude CLI binary may be installed */
 const CLAUDE_SEARCH_DIRS = [
@@ -23,8 +23,8 @@ const CLAUDE_SEARCH_DIRS = [
   join(homedir(), 'bin'),
 ];
 
-/** Cached directory containing the claude binary (empty string = searched but not found) */
-let _claudeDir: string | null = null;
+const claudeResolver = createCliExecutableResolver({ binary: 'claude', searchDirs: CLAUDE_SEARCH_DIRS });
+const CLAUDE_NOT_FOUND = 'Claude CLI not found. Install it with: curl -fsSL https://claude.ai/install.sh | bash';
 
 /**
  * Returns true if the Claude CLI binary can be located (via `which` or one of
@@ -43,29 +43,11 @@ export function isClaudeAvailable(): boolean {
  * @returns Directory path, or null if not found
  */
 export function findClaudeDir(): string | null {
-  if (_claudeDir !== null) return _claudeDir || null;
+  return claudeResolver.resolve()?.directory ?? null;
+}
 
-  // Try `which` first (respects current PATH)
-  try {
-    const result = execSync('which claude', { encoding: 'utf-8', timeout: EXEC_TIMEOUT_MS }).trim();
-    if (result && existsSync(result)) {
-      _claudeDir = dirname(result);
-      return _claudeDir;
-    }
-  } catch {
-    // Claude not in PATH, will check common locations
-  }
-
-  // Fallback: check common installation directories
-  for (const dir of CLAUDE_SEARCH_DIRS) {
-    if (existsSync(join(dir, 'claude'))) {
-      _claudeDir = dir;
-      return _claudeDir;
-    }
-  }
-
-  _claudeDir = ''; // mark as searched, not found
-  return null;
+export function getClaudeNotFoundMessage(): string {
+  return formatCliNotFoundMessage(CLAUDE_NOT_FOUND, claudeResolver.diagnostics());
 }
 
 /**
@@ -99,7 +81,9 @@ export function getAugmentedPath(): string {
   const currentPath = process.env.PATH || '';
   const claudeDir = findClaudeDir();
 
-  if (claudeDir && !currentPath.split(delimiter).includes(claudeDir)) {
+  if (!claudeDir) return currentPath;
+
+  if (!currentPath.split(delimiter).includes(claudeDir)) {
     _augmentedPath = `${claudeDir}${delimiter}${currentPath}`;
     return _augmentedPath;
   }
@@ -193,6 +177,9 @@ function probeClaudeCliVersion(): string | null {
     encoding: 'utf-8',
     timeout: EXEC_TIMEOUT_MS,
     env: { ...process.env, PATH: getAugmentedPath() },
+    // execFileSync's timeout only SENDS the signal and then keeps waiting; a
+    // child that ignores SIGTERM would block the server thread permanently.
+    killSignal: 'SIGKILL',
   });
   const match = out.match(/(\d+\.\d+\.\d+)/);
   return match ? match[1] : null;