chore: version packages (#474)

* chore: version packages

* docs: sync CLAUDE.md version to 1.32.1

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

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Codeman maintainer <noreply@anthropic.com>

.claude-plugin/marketplace.json

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

CHANGELOG.md

@@ -1,5 +1,34 @@
 # aicodeman
 
+## 1.32.1
+
+### Patch Changes
+
+- 13e652e: Terminal copy: copying text out of a Claude Code or Codex pane no longer puts the pane's two-column transcript gutter on the clipboard, so pasted lines arrive flush instead of indented (#469). The width comes from the CLI registry (`capabilities.transcriptGutter`, 2 for claude and codex, measured on live panes) and is only a ceiling: a selection only ever shifts as a block, so its own indentation survives. Other CLIs and shells are untouched. It works in split panes and detached session windows too, and can be turned off per device in App Settings under Selection & clipboard.
+- 13e652e: Sessions: recovering a Claude session whose tmux pane had died relaunched `claude --session-id <id>`, which Claude refuses once that id has a transcript, so the pane died again straight away and the conversation was stranded. The relaunch now resumes the conversation (`--resume <id> || --session-id <id>`), including when tmux lost the whole session (#467).
+- 00f022c: Terminal: when a burst of output overflows the render queue and a frame has to be dropped, the repaint that repairs it is now retried until it actually happens, instead of being scheduled once and silently skipped when another load was in flight (#470).
+- 13e652e: Mobile: a long press on blank terminal space on Android Chrome no longer opens the keyboard and blanks the terminal (#471, fixes #360). The long-press guards are now armed before the press is checked for selectable text, so a press on empty space is swallowed the same way a press on a word already was.
+- 13e652e: Sessions: a tab whose agent has exited (the CLI quit, but tmux kept the pane) now says so with a muted dot and an `exited (137)` badge, instead of looking like an idle session (#466, part 1 of #446). The state is published as `paneExit` on the session and survives a restart. Nothing closes such sessions yet; that is part 2.
+- 13e652e: Docker: optional GitHub CLI and Azure CLI for private repositories (#472). Both are off by default. With `CODEMAN_INSTALL_GH=1` / `CODEMAN_INSTALL_AZ=1` as build args in `docker-compose.override.yml`, the server image gets `gh` and/or `az` (with the `azure-devops` extension) wired in as git credential helpers, so after one `gh auth login` or `az login` from a shell session, Add Case → Clone Repo can clone private GitHub and Azure DevOps repositories. `CODEMAN_AGENT_IMAGE_INSTALL_GH` / `_AZ` do the same for the Docker-case agent image, and only then are the sign-ins copied into new case containers. In multi-user mode a non-admin's clone runs with the credential helpers cleared. This changes `server.Dockerfile`, so Compose deployments need a `Start-Codeman.sh` rebuild rather than an in-app update.
+- 13e652e: Run menu: the Gemini, Antigravity and OMP run buttons now show their own colours on every skin; they rendered in Claude blue on all skins except OG (#463). The CLI registry's `accent` values were also corrected to the colours the UI really paints, and a test now guards the stylesheet trap that caused it.
+- 13e652e: Terminal: five ways the browser terminal could silently stop being correct are fixed (#431, #464). The browser terminal and the PTY can no longer disagree about their width, which is what produced doubled lines and half-overwritten text ("text gets muffled sometimes"): there is now one function that sizes the terminal, and every resize is answered with the geometry the PTY really holds. A replay clear goes through the terminal's own queue, so bytes written just before it no longer fuse into the next snapshot. A renderer that stops painting after an iOS PWA is backgrounded heals itself instead of needing a reload. Every terminal capture has a deadline that also covers the response body, and a capture that runs out of time during a tab switch falls back to the bounded tail instead of leaving a blank pane. Output lost to a half-open WebSocket is repainted on the next successful open. The service worker's precache list is now generated by the build and its cache is rotated per build, so old releases' assets no longer pile up.
+- 13e652e: Docker: new `docker/Update-Codeman.sh` for the major-update path the docs used to describe by hand (#465). It rebuilds the image with `--no-cache` before taking the stack down, clears the build-artefact volumes, refuses to run when another checkout's Compose project already owns the same name, and then hands over to `Start-Codeman.sh`.
+- 13e652e: Approvals: a session that is idle only because it is waiting on its own background work (Claude Code's `1 monitor` footer chip, or a Codex background terminal) no longer raises the yellow NEEDS YOU alert or a push (#473, fixes #468). Its idle item is opened already acknowledged, and the tab, the home screens and the rail show a small `watching` badge next to the state instead. The item still exists in the Approvals Inbox, and the TUI's pending count now leaves acknowledged items out.
+- b404dac: Maintainer fixes applied while landing this batch:
+  - Terminal (#431): while another device holds the pane's width, a resize retry no longer re-fits xterm to the container and re-wraps the whole buffer every 30 s, and no longer clears scrollback for a redraw that never comes. The PTY's spawn geometry is now recorded at attach, so `ptyGeometry` never reports a size the PTY never held.
+  - Terminal (#470): the `TERMINAL DROP` crash-trail line is logged once per recovery window instead of once per dropped frame (which wiped the rest of the trail within a second), and a refresh that died at its fetch deadline is no longer retried.
+  - Sessions (#467): the resume pin also covers the branch where tmux lost the whole session, the conversation id Codeman reports follows what the relaunch actually resumed, and the test setup strips `CLAUDE_CONFIG_DIR` so the suite stays green for anyone running a separate Claude config dir.
+  - Sessions (#466): detailed sidebar and rail rows show an `exited` pill instead of `idle`, the exit is announced to screen readers, and the user manual's tab-appearance table lists the new state.
+  - Approvals (#473): a failed pane capture clears the `watching` badge rather than keeping a stale one (a failure now falls toward an alert, not toward silence), and the header bell's count leaves acknowledged items out, matching the TUI.
+  - Run menu (#463): the Gemini and Antigravity run buttons no longer render two-tone on phones, Gemini's registry accent matches its tab badge, and a test now guards the stylesheet trap for every run mode.
+  - Docker (#465): `Update-Codeman.sh` removes exactly the two build-artefact volumes it names instead of every named volume in the project, reports a failing `docker compose` instead of exiting silently, and its docs and comments were corrected. (#472): the multi-user notes say that a non-admin's seeded Docker case also receives the gh/az sign-in when those switches are on.
+
+  ### Thanks
+  - @irisitymichaelgrundberg for four PRs in this release: the `watching` badge that stops background work from raising false alerts (#473, from their own report #468), the exited-agent badge (#466) and the dead-pane resume fix (#467), both from their report #446, and the transcript-gutter strip for copied text (#469), a follow-up to their #451.
+  - @rounakdatta for the terminal resilience work (#431) and the dropped-frame recovery (#470), both from their report #464, and for answering four rounds of review in full.
+  - @opticon454 for private-repository support in the Docker images (#472), the `Update-Codeman.sh` script (#465) and the run-button colour fix (#463).
+  - @DodgyBadger for the Android long-press fix (#471), from their own report #360.
+
 ## 1.32.0
 
 ### Minor Changes

docker/.env.example

@@ -50,6 +50,14 @@ CODEMAN_USERNAME=admin
 # README.md, "Reverse-proxy host allowlist".
 # CODEMAN_ALLOWED_HOSTS=codeman.example.com,.internal.example.com
 
+# The GitHub CLI (gh) and the Azure CLI (az, with the azure-devops extension)
+# can be built into the images as git credential helpers, so Codeman can clone
+# private GitHub and Azure DevOps repositories. Both are OFF by default and are
+# NOT set here: turn them on in docker-compose.override.yml with the build args
+# CODEMAN_INSTALL_GH / CODEMAN_INSTALL_AZ and, for the Docker-case agent image,
+# the environment variables CODEMAN_AGENT_IMAGE_INSTALL_GH / _AZ. See
+# README.md, "Private repositories".
+
 # Optional: authenticate Gemini CLI without an interactive login.
 GEMINI_API_KEY=
 

docker/README.md

@@ -41,6 +41,94 @@ Releases that change `server.Dockerfile`, `docker-compose.yaml`, or add a key to
 changed, and asks you to run `Start-Codeman.sh` here on the host instead. Details:
 [`../docs/docker-self-update.md`](../docs/docker-self-update.md).
 
+### Major updates
+
+`Start-Codeman.sh` rebuilds the image on every start, but with the layer cache,
+and it refreshes the build-artefact volumes selectively: `codeman-dist` when
+the checkout's HEAD moved, `codeman-node-modules` only when `package-lock.json`
+changed. That is right for an ordinary `git pull`. It is not enough when a
+`server.Dockerfile` change bumps the Node base image without touching the
+lockfile: `node-pty` is compiled from source (there is no Linux prebuild), so
+the old `codeman-node-modules` volume would keep a build made for the previous
+Node version. For that case, or whenever you want to be certain of what ships,
+`docker/Update-Codeman.sh` force-rebuilds the image with no layer cache, stops
+the stack, removes the `codeman-node-modules` and `codeman-dist` volumes, then
+hands off to `Start-Codeman.sh` for the usual start:
+
+```sh
+bash docker/Update-Codeman.sh
+```
+
+Pass `--keep-volumes` to skip clearing them (safe only if you know the
+rebuilt image's `node_modules`/`dist` did not change). The scripted default
+is the "Resetting the build artefacts" procedure in
+[`../docs/docker-self-update.md`](../docs/docker-self-update.md). Only those
+two volumes are removed, by name within this Compose project; any volume a
+`docker-compose.override.yml` adds is left alone, and application data and
+case workspaces are host bind mounts, never touched either way.
+
+## Private repositories (GitHub and Azure DevOps)
+
+The images can include the GitHub CLI (`gh`) and the Azure CLI (`az`, with the `azure-devops` extension), wired into the system Git configuration as credential helpers, so Codeman can clone private repositories. Both are **opt-in and off by default**, and are turned on per host in `docker-compose.override.yml`.
+
+### Turning them on
+
+Add the build arguments to `docker-compose.override.yml` (see [Local customisation](#local-customisation)), then rebuild with `Start-Codeman.sh`. Set only the one you need:
+
+```yaml
+services:
+  codeman:
+    build:
+      args:
+        CODEMAN_INSTALL_GH: '1'
+        CODEMAN_INSTALL_AZ: '1'
+    environment:
+      # The same two switches for the Docker-case agent image Codeman builds.
+      CODEMAN_AGENT_IMAGE_INSTALL_GH: '1'
+      CODEMAN_AGENT_IMAGE_INSTALL_AZ: '1'
+```
+
+The `build: args:` pair controls the Codeman server image. The `environment:` pair controls the agent image for [Docker cases](../docs/docker-cases.md), which Codeman builds on the first Docker case; an agent image that already exists is not rebuilt by this, so run `node scripts/build-agent-image.mjs --no-cache` inside the container afterwards. The same variables work in front of that command when building it by hand. Values must be `0` or `1`; anything else stops the build with an error naming the argument.
+
+They are not `.env` settings: turning a CLI on is a per-host choice, which is what the override file is for, and a new `.env.example` key makes the in-app updater refuse to update every existing installation until its `.env` gains the key.
+
+The Azure CLI is the large one, about 600 MB of the roughly 670 MB the pair adds. A CLI left off leaves nothing functional behind: no apt repository, no package, no `azure-devops` extension and no credential-helper entry, so git for that host behaves exactly as it does without this feature. With both off the image is functionally unchanged; it still carries the `AZURE_EXTENSION_DIR` variable, an empty extensions directory and one small layer that copies and then removes the helper script.
+
+### Signing in
+
+With a CLI on, the system Git configuration routes credentials through it:
+
+| Host                                                  | Credential helper                         | Sign in with                 |
+| ----------------------------------------------------- | ----------------------------------------- | ---------------------------- |
+| `https://github.com`, `https://gist.github.com`       | `gh auth git-credential`                  | `gh auth login`              |
+| `https://dev.azure.com`, `https://*.visualstudio.com` | `/usr/local/bin/git-credential-azure-cli` | `az login --use-device-code` |
+
+Codeman itself still collects no Git credentials. Sign the container in once from a **Terminal / Shell** session (Run menu). The session runs as the runtime account, so the sign-in is stored under `CODEMAN_APPDATA_PATH` (`~/.config/gh`, `~/.azure`) and survives rebuilds and container recreation:
+
+```sh
+gh auth login                  # GitHub.com -> HTTPS -> "Login with a web browser" (device code)
+az login --use-device-code     # then: az devops configure --defaults organization=https://dev.azure.com/<org>
+```
+
+After that, **Add Case → Clone Repo** accepts private `https://` URLs on those hosts, and `git clone` works from any session. Until a CLI is signed in its helper prints nothing, so a private clone fails immediately with the usual authentication error rather than waiting on a prompt.
+
+**Multi-user mode:** every Codeman user's git runs as the same server account, so these sign-ins would otherwise be shared. Clone Repo therefore runs a **non-admin**'s clone and preflight with every git credential helper cleared (`git -c credential.helper=`): a non-admin can clone public repositories and anything their own SSH setup allows, but not a private https repository through the admin's `gh`/`az` sign-in. Admins, and single-user mode, keep the helpers. A non-admin's own agent sessions still run as that same account, and with the agent-image `gh`/`az` switches on, a non-admin's Docker case with credential seeding on also receives the server account's `gh`/`az` sign-in, the same as the Claude and Codex credentials; see `docs/security-architecture.md`, multi-user mode.
+
+Azure DevOps is authenticated with an Entra ID access token that the helper requests from `az` for each Git operation, so nothing is written to disk beyond `az`'s own sign-in. An account that has to use a personal access token can set `AZURE_DEVOPS_EXT_PAT` for the container instead (for example under `environment:` in `docker-compose.override.yml`); the helper prefers it when present. SSH remotes are unaffected by any of this and keep using the account's own keys.
+
+Docker cases copy these sign-ins into a case container only when the matching agent-image switch is on (`CODEMAN_AGENT_IMAGE_INSTALL_GH=1` for `~/.config/gh/hosts.yml` and `config.yml`, `CODEMAN_AGENT_IMAGE_INSTALL_AZ=1` for the sign-in files from `~/.azure`) and the case has credential seeding on. With a switch off they are never copied, even when the files exist, because a GitHub token or an Azure refresh token is usable by anything in the container. The copies are made when the container is **created**, so an existing case container never picks them up: after turning a switch on, signing in, or rebuilding the agent image, **recreate the case container** (remove it; the next session in that case creates a fresh one).
+
+The GitHub agent skill for `gh` installs into the runtime account's home in the same session:
+
+```sh
+gh skill install cli/cli gh --scope user
+gh skill update gh              # after a later gh release
+```
+
+### Versions
+
+Both CLIs, and the extension, are installed from their vendors' repositories with no version pinned, so they arrive at whatever is current when that build step runs. Docker caches the step, though: `Start-Codeman.sh` rebuilds with the cache, which keeps the versions from the first build until the Dockerfile changes at or above that step or the image is rebuilt with `--no-cache`. They are apt packages owned by root, so they cannot be upgraded from a session; `az extension update --name azure-devops` is the exception and works without a rebuild.
+
 ## Local customisation
 
 Compose merges `docker-compose.override.yml` on top of `docker-compose.yaml`. Keep host-specific changes there rather than editing `docker-compose.yaml`, so this repository can be updated without losing them. Both `docker-compose.override.yml` and `docker-compose.override.yaml` are ignored by Git.

docker/Update-Codeman.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+#
+# The scripted major-update path for the Docker Compose deployment.
+#
+# docker/README.md and docs/docker-self-update.md both point operators here for
+# anything the in-app updater itself refuses to apply: a changed
+# `server.Dockerfile`, a changed `docker-compose.yaml`, or a new required
+# `.env.example` key. None of those can be applied by a container restarting
+# itself — a restart reuses the existing image and configuration (see "The
+# environment gate" in docs/docker-self-update.md) — so this script does the
+# three things an in-place update cannot: force a real image rebuild with no
+# layer cache, stop the stack, then hand off to Start-Codeman.sh for the same
+# careful PUID/PGID, override-file and fingerprint handling every other start
+# goes through.
+#
+# ⚠️ Build BEFORE stopping the stack, deliberately, same reasoning as
+# Start-Codeman.sh's own build-then-down ordering: the build needs nothing
+# stopped, so a slow --no-cache rebuild costs no downtime, and a build failure
+# (a bad Dockerfile edit, a network blip pulling a base image) leaves the
+# ALREADY-RUNNING stack untouched instead of stopped with nothing to bring it
+# back.
+#
+# ⚠️ Clears the codeman-node-modules/codeman-dist named volumes by DEFAULT.
+# Docker seeds a named volume from the image only while that volume is EMPTY,
+# so a rebuilt image's fresh node_modules/dist otherwise sit unused behind a
+# volume's old content and the container comes back up looking unchanged —
+# exactly wrong for a script whose whole point is "be certain of what ships".
+# Start-Codeman.sh clears codeman-dist when the checkout's HEAD moved and
+# codeman-node-modules only when `package-lock.json` changed. A released
+# server.Dockerfile change arrives through `git pull`, so HEAD moves and dist
+# is refreshed, but a Dockerfile change that bumps the Node base image leaves
+# the lockfile untouched while every native module (node-pty is compiled from
+# source, there is no Linux prebuild) has to be rebuilt against the new Node
+# ABI. Start-Codeman.sh would keep the old codeman-node-modules volume, and it
+# never builds with --no-cache. This script clears BOTH volumes, and ONLY
+# those two (targeted `docker volume rm` by Compose label, never
+# `down --volumes`, which would also take any volume an override file adds).
+# Pass --keep-volumes to opt out and reuse whatever is already in them.
+#
+# Usage: docker/Update-Codeman.sh [--keep-volumes]
+#   --keep-volumes   Do not clear codeman-node-modules/codeman-dist. Safe to
+#                    combine with a source change Start-Codeman.sh's own
+#                    detection would have cleared anyway; unsafe if the reason
+#                    you are here is a change to server.Dockerfile alone.
+
+set -euo pipefail
+
+script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+env_file="$script_dir/.env"
+compose_file="$script_dir/docker-compose.yaml"
+
+keep_volumes=0
+for arg in "$@"; do
+  case "$arg" in
+    --keep-volumes)
+      keep_volumes=1
+      ;;
+    --help | -h)
+      printf 'Usage: bash %s [--keep-volumes]\n' "$0"
+      exit 0
+      ;;
+    *)
+      printf 'Error: unrecognised argument: %s\n' "$arg" >&2
+      printf 'Usage: bash %s [--keep-volumes]\n' "$0" >&2
+      exit 1
+      ;;
+  esac
+done
+
+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 running this script.\n' "$script_dir" >&2
+  exit 1
+fi
+
+# Same override-file discovery as Start-Codeman.sh, and deliberately kept in
+# step with it: a stack built here and started there must resolve to the exact
+# same Compose files, or this script's build could target a configuration the
+# handoff's own `up` never actually uses. Compose's own precedence (measured on
+# v5.5.0 with both present: it uses .yml and ignores .yaml).
+override_yml="$script_dir/docker-compose.override.yml"
+override_yaml="$script_dir/docker-compose.override.yaml"
+if [[ -f "$override_yml" && -f "$override_yaml" ]]; then
+  printf 'Warning: both %s and %s exist; Compose uses .yml and ignores .yaml.\n' \
+    "$override_yml" "$override_yaml" >&2
+fi
+compose_files=(-f "$compose_file")
+for override_file in "$override_yml" "$override_yaml"; do
+  if [[ -f "$override_file" ]]; then
+    compose_files+=(-f "$override_file")
+    printf 'Using Compose override file: %s\n' "$override_file"
+    break
+  fi
+done
+compose_command=(docker compose --env-file "$env_file" "${compose_files[@]}")
+
+# Collision guard. Start-Codeman.sh has no equivalent; this is the only one,
+# and it has to run before this script's own --no-cache build, `down` and
+# volume removal below. docker-compose.yaml hard-codes `name: codeman`, so a
+# second checkout run without COMPOSE_PROJECT_NAME resolves to the SAME Compose
+# project as any other checkout on the host and would operate on ITS
+# containers and volumes.
+#
+# The project name is read from the resolved config's top-level `name` key
+# (the first `name` in the output; nested ones come later), the same parse
+# Start-Codeman.sh uses. `--format json` needs Compose v2.3+. This is the first
+# `docker` call the script makes, so its failure is reported here rather than
+# left to `set -e`, which would exit with no output at all.
+if ! project_config=$("${compose_command[@]}" config --format json); then
+  printf 'Error: `docker compose config --format json` failed (see the message above, if any).\n' >&2
+  printf 'Check that Docker and Compose v2.3+ are installed and on PATH, and that\n' >&2
+  printf '%s and the Compose files in %s are valid.\n' "$env_file" "$script_dir" >&2
+  exit 1
+fi
+project_name=$(
+  printf '%s\n' "$project_config" |
+    sed -n 's/^[[:space:]]*"name":[[:space:]]*"\([^"]*\)".*$/\1/p' | head -n1
+)
+if [[ -n "$project_name" ]]; then
+  # `|| true` on the pipeline's LAST command: under `set -o pipefail`, `grep -v`
+  # exits 1 when nothing survives the filter — the ordinary, no-collision case,
+  # since `docker ps` finds nothing at all on a first-ever deployment or a
+  # single matching (own) working_dir gets filtered out. Without it, that exit
+  # status propagates through the command substitution and `set -e` aborts the
+  # WHOLE script right here, every time, regardless of whether a collision
+  # actually exists — caught only by actually running this end-to-end (a
+  # static text/regex check on the source cannot see it). The empty-line
+  # filter keeps a container with no working_dir label from winning head -n1
+  # and hiding a real collision behind it.
+  other_working_dir=$(
+    docker ps -a --filter "label=com.docker.compose.project=$project_name" \
+      --format '{{.Label "com.docker.compose.project.working_dir"}}' 2>/dev/null |
+      grep -v -F -x -- "$script_dir" | grep -v '^$' | head -n1 || true
+  )
+  if [[ -n "$other_working_dir" ]]; then
+    printf 'Error: Compose project "%s" is already in use by a DIFFERENT checkout:\n' "$project_name" >&2
+    printf '  %s\n' "$other_working_dir" >&2
+    printf 'This checkout is:\n' >&2
+    printf '  %s\n' "$script_dir" >&2
+    printf '\n' >&2
+    printf 'docker-compose.yaml hard-codes `name: %s`, so two checkouts on the same host\n' "$project_name" >&2
+    printf 'collide unless each one sets a distinct COMPOSE_PROJECT_NAME. Continuing would\n' >&2
+    printf 'rebuild and stop the OTHER checkout'"'"'s running container and, by default,\n' >&2
+    printf 'delete its codeman-node-modules/codeman-dist volumes.\n' >&2
+    printf '\n' >&2
+    printf 'Fix: export COMPOSE_PROJECT_NAME=<something-unique-to-this-checkout> before\n' >&2
+    printf 'running this script, then retry.\n' >&2
+    printf '\n' >&2
+    printf 'If instead THIS checkout was moved or renamed after its container was created,\n' >&2
+    printf 'the path above is its own old location: remove the old container (for example\n' >&2
+    printf '`docker rm -f <container>` for the codeman container) and retry, rather than\n' >&2
+    printf 'setting COMPOSE_PROJECT_NAME, which would start a second project beside it.\n' >&2
+    exit 1
+  fi
+fi
+
+# Same owner-detection Start-Codeman.sh uses to derive PUID/PGID for its own
+# build — without it, the --no-cache build below gets Compose's untouched
+# default of 1000:1000, and on any host whose appdata owner differs (99:100 on
+# Unraid, per docker/README.md's chown example), Start-Codeman.sh's own
+# correctly-PUID'd build during the handoff then rebuilds those layers with the
+# right values anyway — so the "no cache, certain of what ships" image this
+# script produces is not the one that actually ends up running.
+#
+# Deliberately NOT the same as Start-Codeman.sh's own handling of a MISSING
+# 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.
+appdata_path=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "CODEMAN_APPDATA_PATH" { sub(/^[^=]*=/, ""); print; exit }'
+)
+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
+  printf 'Run docker/Start-Codeman.sh first to set up a new deployment.\n' >&2
+  exit 1
+fi
+
+# `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() {
+  stat -c '%u:%g' -- "$1" 2>/dev/null || stat -f '%u:%g' "$1" 2>/dev/null
+}
+
+if ! owner_ids=$(owner_of "$appdata_path"); then
+  printf 'Error: Cannot determine the owner of CODEMAN_APPDATA_PATH: %s\n' "$appdata_path" >&2
+  exit 1
+fi
+
+export PUID=${owner_ids%%:*}
+export PGID=${owner_ids##*:}
+
+if [[ "$PUID" == '0' ]]; then
+  printf 'Error: CODEMAN_APPDATA_PATH is owned by root: %s\n' "$appdata_path" >&2
+  printf 'Change the directory ownership to the unprivileged account that should run Codeman.\n' >&2
+  exit 1
+fi
+
+# --no-cache, always: a plain `build` reuses cached layers (npm install, apt
+# packages, the CLI installs baked into the image) and can silently keep them
+# frozen at whatever they were the day the cache was populated — exactly wrong
+# for a major update, whose whole point is being certain of what actually
+# ships. `scripts/build-agent-image.mjs` makes the same call for the same
+# reason (see its entry in CLAUDE.md's Additional Commands table). Runs BEFORE
+# the stack is stopped — see the header comment for why.
+printf 'Building a fresh image (--no-cache)...\n'
+"${compose_command[@]}" build --no-cache
+
+printf 'Stopping the stack...\n'
+if [[ "$keep_volumes" == '1' || -n "$project_name" ]]; then
+  "${compose_command[@]}" down
+else
+  # No resolvable project name means the label filter below could match
+  # nothing, so fall back to Compose's own removal, and say what it really does.
+  printf 'Warning: could not resolve the Compose project name; clearing EVERY named volume\n' >&2
+  printf 'in this Compose project (override file included) with `down --volumes` instead.\n' >&2
+  "${compose_command[@]}" down --volumes
+fi
+
+# Targeted removal of exactly the two build-artefact volumes, scoped by label to
+# THIS project (the volume key alone is shared by any other stack declaring the
+# same key). Same lookup as Start-Codeman.sh's refresh. A failure is reported,
+# not fatal: the stack is already down, and the handoff below is what brings
+# it back up.
+if [[ "$keep_volumes" != '1' && -n "$project_name" ]]; then
+  printf 'Clearing the codeman-node-modules/codeman-dist volumes (pass --keep-volumes to skip).\n'
+  for key in codeman-node-modules codeman-dist; do
+    volume_name=$(
+      docker volume ls -q \
+        --filter "label=com.docker.compose.volume=$key" \
+        --filter "label=com.docker.compose.project=$project_name" |
+        head -n1
+    ) || volume_name=''
+    if [[ -n "$volume_name" ]] && ! docker volume rm -- "$volume_name"; then
+      printf 'Warning: could not remove volume %s; the container may keep serving the\n' "$volume_name" >&2
+      printf 'previous build from it. Remove it by hand and rerun this script.\n' >&2
+    fi
+  done
+fi
+
+# Start-Codeman.sh does everything a plain `up -d` does not: re-derives
+# PUID/PGID, pre-creates CODEMAN_CASES_PATH with the right ownership, resolves
+# DOCKER_SOCKET_GID, records the server.Dockerfile/docker-compose.yaml
+# fingerprint the in-app updater's gate reads on every future update, and
+# starts the (already freshly built) image. Reimplementing any of that here
+# would only risk drifting out of step with it — hand off instead, exactly as
+# docs/docker-self-update.md's own reset procedure does.
+#
+# ⚠️ `bash`, not a bare exec of the path: Start-Codeman.sh is committed
+# non-executable (100644), the same as this script, and is documented
+# everywhere as `bash docker/Start-Codeman.sh` rather than
+# `./docker/Start-Codeman.sh` — execing the bare path fails with EACCES.
+printf 'Handing off to Start-Codeman.sh...\n'
+exec bash "$script_dir/Start-Codeman.sh"

docker/agent.Dockerfile

@@ -26,6 +26,88 @@ RUN apt-get update \
       openssh-client \
  && rm -rf /var/lib/apt/lists/*
 
+# GitHub CLI and Azure CLI (+ the azure-devops extension) with the same system
+# git credential helpers as docker/server.Dockerfile, so an agent in a Docker
+# case can clone and push to private GitHub / Azure DevOps repositories. The
+# sign-ins themselves are NOT baked in: `~/.config/gh` and `~/.azure` are seeded
+# per container at launch like every other CLI's credentials (CRED_STORES in
+# src/docker-hosts.ts), and a helper whose CLI is not signed in prints nothing,
+# so git fails fast instead of prompting. See server.Dockerfile for why the
+# vendor apt repositories are configured here rather than via deb_install.sh.
+#
+# Each is OPT-IN and OFF by default, like the server image: CODEMAN_INSTALL_GH=1
+# / CODEMAN_INSTALL_AZ=1 turn one on; off leaves no repository, package,
+# extension or helper entry. scripts/build-agent-image.mjs and the in-app
+# auto-build pass them from CODEMAN_AGENT_IMAGE_INSTALL_GH / _AZ in their own
+# environment (for the Compose deployment: `environment:` in
+# docker-compose.override.yml), and pass nothing when those are unset, so
+# these defaults (off) apply.
+ARG CODEMAN_INSTALL_GH=0
+ARG CODEMAN_INSTALL_AZ=0
+RUN set -eux; \
+    for flag in "CODEMAN_INSTALL_GH=${CODEMAN_INSTALL_GH}" "CODEMAN_INSTALL_AZ=${CODEMAN_INSTALL_AZ}"; do \
+      case "${flag#*=}" in 0|1) ;; *) echo "${flag%%=*} must be 0 or 1, got '${flag#*=}'" >&2; exit 1;; esac; \
+    done; \
+    codename="$(. /etc/os-release && echo "${VERSION_CODENAME}")"; \
+    arch="$(dpkg --print-architecture)"; \
+    pkgs=""; \
+    install -d -m 0755 /etc/apt/keyrings; \
+    if [ "${CODEMAN_INSTALL_GH}" = 1 ]; then \
+      curl -fsSL -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+        https://cli.github.com/packages/githubcli-archive-keyring.gpg; \
+      chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg; \
+      echo "deb [arch=${arch} signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list; \
+      pkgs="${pkgs} gh"; \
+    fi; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then \
+      curl -fsSL -o /etc/apt/keyrings/microsoft.asc \
+        https://packages.microsoft.com/keys/microsoft.asc; \
+      chmod go+r /etc/apt/keyrings/microsoft.asc; \
+      echo "deb [arch=${arch} signed-by=/etc/apt/keyrings/microsoft.asc] https://packages.microsoft.com/repos/azure-cli/ ${codename} main" \
+        > /etc/apt/sources.list.d/azure-cli.list; \
+      pkgs="${pkgs} azure-cli"; \
+    fi; \
+    if [ -n "${pkgs}" ]; then \
+      apt-get update; \
+      apt-get install -y --no-install-recommends ${pkgs}; \
+      rm -rf /var/lib/apt/lists/*; \
+    fi; \
+    if [ "${CODEMAN_INSTALL_GH}" = 1 ]; then gh --version; fi; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then az version --output none; fi
+
+# Outside HOME so the seeded `~/.azure` (auth files only) never has to carry
+# extensions. gid 0 + group-writable, the same arbitrary-uid convention as HOME
+# below, so `az extension update` works as whatever uid the container runs as.
+# Created even without az; an empty directory costs nothing.
+ENV AZURE_EXTENSION_DIR=/opt/az-extensions
+RUN set -eux; \
+    install -d -m 0755 "${AZURE_EXTENSION_DIR}"; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then \
+      az extension add --name azure-devops --only-show-errors; \
+      rm -rf /root/.azure; \
+    fi; \
+    chgrp -R 0 "${AZURE_EXTENSION_DIR}"; \
+    chmod -R g=u "${AZURE_EXTENSION_DIR}"
+
+# Only an installed CLI gets a helper entry (see server.Dockerfile).
+COPY docker/git-credential-azure-cli /usr/local/bin/git-credential-azure-cli
+RUN set -eux; \
+    if [ "${CODEMAN_INSTALL_GH}" = 1 ]; then \
+      for host in https://github.com https://gist.github.com; do \
+        git config --system "credential.${host}.helper" '!/usr/bin/gh auth git-credential'; \
+      done; \
+    fi; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then \
+      chmod 0755 /usr/local/bin/git-credential-azure-cli; \
+      for host in https://dev.azure.com 'https://*.visualstudio.com'; do \
+        git config --system "credential.${host}.helper" /usr/local/bin/git-credential-azure-cli; \
+        git config --system "credential.${host}.useHttpPath" true; \
+      done; \
+    else \
+      rm -f /usr/local/bin/git-credential-azure-cli; \
+    fi
+
 # The npm-published agent CLIs, supplied by scripts/build-agent-image.mjs from
 # config/clis.stock.json so a new stock CLI needs no edit here. The default is
 # today's literal list, so a bare `docker build` still produces the same image.

docker/git-credential-azure-cli

@@ -0,0 +1,34 @@
+#!/bin/sh
+# Git credential helper for Azure DevOps, backed by the signed-in Azure CLI.
+#
+# Configured in the image's system gitconfig for https://dev.azure.com and
+# https://*.visualstudio.com (see server.Dockerfile). On `get` it answers with
+# an Entra ID access token for the Azure DevOps resource as the password, the
+# same token type Git Credential Manager uses for Azure Repos. It never prompts:
+# when `az` is not signed in it prints nothing, so git fails fast with its own
+# authentication error instead of hanging a request that has no terminal.
+#
+# AZURE_DEVOPS_EXT_PAT, the azure-devops extension's own PAT variable, is used
+# instead when it is set, for accounts that authenticate with a PAT.
+
+# `store` and `erase` are no-ops: the token belongs to az, which refreshes it.
+[ "$1" = "get" ] || exit 0
+
+# Drain the request git writes on stdin; the host scoping is in gitconfig.
+cat >/dev/null
+
+if [ -n "${AZURE_DEVOPS_EXT_PAT:-}" ]; then
+  printf 'username=pat\npassword=%s\n' "$AZURE_DEVOPS_EXT_PAT"
+  exit 0
+fi
+
+command -v az >/dev/null 2>&1 || exit 0
+
+# 499b84ac-1321-427f-aa17-267ca6975798 is the fixed application ID of Azure
+# DevOps: https://learn.microsoft.com/azure/devops/integrate/get-started/authentication/service-principal-managed-identity
+token="$(az account get-access-token \
+  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
+  --query accessToken --output tsv 2>/dev/null)" || exit 0
+[ -n "$token" ] || exit 0
+
+printf 'username=azure-cli\npassword=%s\n' "$token"

docker/server.Dockerfile

@@ -68,6 +68,111 @@ COPY --from=docker:29-cli \
      /usr/local/libexec/docker/cli-plugins/docker-buildx \
      /usr/local/libexec/docker/cli-plugins/docker-buildx
 
+# GitHub CLI and Azure CLI (with the azure-devops extension), so a user can sign
+# this container in to GitHub and Azure DevOps from a Codeman shell session and
+# then clone PRIVATE repositories, both from that session and through Add Case
+# -> Clone Repo. Codeman still collects no Git credentials itself: the clone
+# path (src/git-clone.ts) only inherits HOME and git's config, so whatever the
+# user signs in to here is what authenticates, and nothing when they have not
+# (the clone then fails fast with AUTH_REQUIRED, exactly as before).
+#
+# Each is OPT-IN and OFF by default: the image is functionally unchanged
+# unless the build gets CODEMAN_INSTALL_GH=1 and/or CODEMAN_INSTALL_AZ=1, which
+# a deployment sets under `build: args:` in docker-compose.override.yml
+# (docker/README.md, "Private repositories"). Off installs no apt repository,
+# package, extension or credential-helper entry; all that remains is the
+# AZURE_EXTENSION_DIR variable, its empty directory and one layer that copies
+# and then removes the helper script. The Azure CLI is the heavy one (~600 MB,
+# mostly its bundled Python). The base docker-compose.yaml
+# and .env deliberately do not carry them: turning a CLI on is a per-host
+# choice, which is what the override file is for, and a new .env.example key
+# would make the self-updater refuse existing installs until their .env gained
+# it (docs/docker-self-update.md).
+#
+# Both come from their vendors' own apt repositories, the same ones the
+# documented one-liners configure (https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+# and https://learn.microsoft.com/cli/azure/install-azure-cli-linux?pivots=apt).
+# Microsoft's `deb_install.sh` is deliberately not piped into the build: it does
+# exactly this plus a `gnupg` install, and a remote script run at build time is
+# the one step a reviewer cannot read in this file. apt reads an ASCII-armoured
+# `.asc` key directly, which is what keeps `gnupg` out of the image.
+#
+# Not pinned, unlike the agent CLIs below: nothing in Codeman depends on a
+# particular gh or az behaviour, so the pinning argument there does not apply.
+# The layer cache still keeps whatever version the first build fetched until a
+# --no-cache rebuild.
+ARG CODEMAN_INSTALL_GH=0
+ARG CODEMAN_INSTALL_AZ=0
+RUN set -eux; \
+    for flag in "CODEMAN_INSTALL_GH=${CODEMAN_INSTALL_GH}" "CODEMAN_INSTALL_AZ=${CODEMAN_INSTALL_AZ}"; do \
+      case "${flag#*=}" in 0|1) ;; *) echo "${flag%%=*} must be 0 or 1, got '${flag#*=}'" >&2; exit 1;; esac; \
+    done; \
+    codename="$(. /etc/os-release && echo "${VERSION_CODENAME}")"; \
+    arch="$(dpkg --print-architecture)"; \
+    pkgs=""; \
+    install -d -m 0755 /etc/apt/keyrings; \
+    if [ "${CODEMAN_INSTALL_GH}" = 1 ]; then \
+      curl -fsSL -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+        https://cli.github.com/packages/githubcli-archive-keyring.gpg; \
+      chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg; \
+      echo "deb [arch=${arch} signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list; \
+      pkgs="${pkgs} gh"; \
+    fi; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then \
+      curl -fsSL -o /etc/apt/keyrings/microsoft.asc \
+        https://packages.microsoft.com/keys/microsoft.asc; \
+      chmod go+r /etc/apt/keyrings/microsoft.asc; \
+      echo "deb [arch=${arch} signed-by=/etc/apt/keyrings/microsoft.asc] https://packages.microsoft.com/repos/azure-cli/ ${codename} main" \
+        > /etc/apt/sources.list.d/azure-cli.list; \
+      pkgs="${pkgs} azure-cli"; \
+    fi; \
+    if [ -n "${pkgs}" ]; then \
+      apt-get update; \
+      apt-get install -y --no-install-recommends ${pkgs}; \
+      rm -rf /var/lib/apt/lists/*; \
+    fi
+
+# The azure-devops extension goes into a SYSTEM directory rather than the
+# default ~/.azure/cliextensions: HOME is the application-data bind mount, which
+# hides anything installed there at build time. The directory is handed to the
+# runtime account below (next to /opt/codeman-cli) so `az extension update`
+# works from a session. Nothing that runs as root executes from it. It is
+# created even without az, so the chown below does not have to know.
+ENV AZURE_EXTENSION_DIR=/opt/codeman-az-extensions
+RUN set -eux; \
+    install -d -m 0755 "${AZURE_EXTENSION_DIR}"; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then \
+      az extension add --name azure-devops --only-show-errors; \
+      rm -rf /root/.azure; \
+    fi
+
+# Git credential helpers, in the SYSTEM gitconfig so they apply to every
+# account and survive a fresh application-data directory. Each one answers only
+# for its own host and prints nothing when its CLI is not signed in, so git
+# falls through to its normal non-interactive failure. Only an installed CLI
+# gets an entry: a helper naming a missing binary would print an error on every
+# clone from that host.
+#   github.com     `gh auth git-credential`, what `gh auth setup-git` configures.
+#   Azure DevOps   an Entra ID token from `az login` (git-credential-azure-cli),
+#                  for both dev.azure.com and the legacy *.visualstudio.com hosts.
+COPY docker/git-credential-azure-cli /usr/local/bin/git-credential-azure-cli
+RUN set -eux; \
+    if [ "${CODEMAN_INSTALL_GH}" = 1 ]; then \
+      for host in https://github.com https://gist.github.com; do \
+        git config --system "credential.${host}.helper" '!/usr/bin/gh auth git-credential'; \
+      done; \
+    fi; \
+    if [ "${CODEMAN_INSTALL_AZ}" = 1 ]; then \
+      chmod 0755 /usr/local/bin/git-credential-azure-cli; \
+      for host in https://dev.azure.com 'https://*.visualstudio.com'; do \
+        git config --system "credential.${host}.helper" /usr/local/bin/git-credential-azure-cli; \
+        git config --system "credential.${host}.useHttpPath" true; \
+      done; \
+    else \
+      rm -f /usr/local/bin/git-credential-azure-cli; \
+    fi
+
 # Keep credentials out of the image. Users authenticate these CLIs at runtime
 # through Codeman sessions, and the configured host bind mount retains state.
 #
@@ -153,7 +258,7 @@ RUN set -eux; \
         --shell /bin/bash \
         "${CODEMAN_RUNTIME_USER}"; \
     fi; \
-    chown -R "${PUID}:${PGID}" /opt/codeman-cli
+    chown -R "${PUID}:${PGID}" /opt/codeman-cli /opt/codeman-az-extensions
 
 WORKDIR /opt/codeman
 

docs/cli-registry.md

@@ -36,7 +36,8 @@ interface CliEntry {
   launch: CliLaunch; // the structured argv template
   env: CliEnv; // exports, tmux setenv keys, the env-override allowlist
   capabilities: CliCapabilities; // what every call site reads instead of the id
-  //   .workDetect?: { promptGlyph, workingLine } — how this CLI's pane shows work
+  //   .workDetect?: { promptGlyph, workingLine, watchingLine?, watchingLines? } — how
+  //   this CLI's pane shows work, and how it shows work it started in the background
   overlays: CliOverlays; // remote-SSH / Docker pane commands, credential store
 }
 ```
@@ -45,10 +46,46 @@ interface CliEntry {
 
 ### Regexes that come from config
 
-Two capability fields carry a regular expression an override file can set: `discovery.version.regex` and `capabilities.workDetect.workingLine`. Both go through `compileVersionRegex()`, which caps the source at 200 characters, refuses the nested-quantifier shapes that cause catastrophic backtracking, and returns `null` rather than throwing so every caller degrades instead of crashing.
+Three capability fields carry a regular expression an override file can set: `discovery.version.regex`, `capabilities.workDetect.workingLine` and `capabilities.workDetect.watchingLine`. All three go through `compileVersionRegex()`, which caps the source at 200 characters, refuses the nested-quantifier shapes that cause catastrophic backtracking, and returns `null` rather than throwing so every caller degrades instead of crashing.
 
 `workingLine` is the one that matters most, because it is compiled once per session and then run against every accumulated PTY chunk and every pane capture. A nested quantifier there is a ReDoS against the event loop for the whole server, not just that session. The guard therefore runs in two places, and neither is redundant: `schema.ts` rejects the entry at LOAD time so a bad pattern never reaches a session, and `_workingLinePattern()` in `session.ts` compiles through the same helper so the runtime cannot end up with a pattern the schema would have refused.
 
+`watchingLine` reads a different row of the same screen. A CLI draws it while work the agent
+itself started is still running — Claude prints `⏵⏵ bypass permissions on · 1 monitor · ← for
+agents` while a monitor, a backgrounded shell or a cloud session is live. Codeman turns that
+into `Session.watching`, and an idle prompt from such a session opens already acknowledged,
+so a pane waiting for its own background work never raises an alert a human cannot answer.
+Group 1 is the label, and a CLI that declares no pattern reports no background work.
+
+Two CLIs declare such a row today, and they put it in different places. Claude writes its
+chip on the last row of the screen, so it keeps the default one-row window and anchors on
+the `·` its footer joins items with. Codex pins
+`1 background terminal running · /ps to view · /stop to close` ABOVE its composer, which
+puts the row third from the bottom once the status line and the composer are counted, so its
+entry declares `watchingLines: 3` and matches that row end to end. Both were measured
+against live panes rather than read out of a binary, which is the standard for adding a
+third.
+
+That label is the one value in the registry that an AGENT can influence, because it comes off
+the agent's own screen. Two things keep it honest, and both belong to whoever adds a pattern
+for a new CLI. `watchingLabel()` in `session-activity.ts` searches only the last few
+non-blank rows, which should be the part of the screen the CLI draws rather than the agent,
+and the pattern should anchor on chrome only that CLI can produce. Keep the window as small
+as the layout allows, since every row it adds is another row the agent may be able to write.
+The label is also ANSI-stripped and length-capped at the source, and every interpolation of
+it into markup goes through `escapeHtml()`, since it ends up on a badge and in an approval
+card.
+
+The two shipped entries do not sit equally well behind that rule, and the difference decides
+what a pattern is allowed to do. Claude's chip is the last row, so its one-row window holds
+nothing the agent can write — not even the status line above it, whose command a session
+running with permissions bypassed can write into its own `.claude/settings.json`. Codex's row
+shares its slot with the last row of the transcript whenever no terminal is running, so a
+message ending in that exact line is matched. What keeps that harmless is `hooks: 'none'`: no
+hook event from a codex session reaches the approvals inbox, so a forged label costs a wrong
+badge and cannot silence an alert. Before giving a CLI both hook signals and a pattern, make
+sure its row is one the agent cannot write.
+
 ### Three capabilities that must stay independent
 
 `external`, `hooks` and `altScreen` describe three different, deliberately unequal sets, and deriving any one from another has already shipped a bug. `shell` has no hooks but is **not** an external CLI, so a hooks predicate written as `!isExternalCliMode()` accepted `until=stop` on a shell session and then blocked the caller for their entire timeout. `deepseek` is the mirror image: it IS external and it DOES have hooks.
@@ -114,7 +151,7 @@ This matters because it is invisible when it is wrong. `capabilities.privilegedP
 
 `shortBadge`, `accent`, `capabilities.echo`, `capabilities.wheelForward`, `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` are **declared but not yet read**. They all describe frontend behaviour, and the frontend is deliberately untouched here: `app.js`, `terminal-ui.js` and `styles.css` keep their own hand-authored per-CLI rules, and moving them is its own piece of work verified by a browser/mobile suite the CI gate cannot see.
 
-Treat those values as **transcribed, not authoritative** — nothing enforces that `echo.policy` matches `_updateLocalEchoState`'s fallthrough, or that `accent` matches the gradient CSS paints, so re-measure before wiring one up. A field that is both wrong and unread is worse than an absent one, because the next reader trusts it; `test/cli-registry-no-id-branching.test.ts` pins the list so it cannot quietly grow, and wiring one up makes its line there fail, which is the direction you want.
+Treat those values as **transcribed, not authoritative** — nothing enforces that `echo.policy` matches `_updateLocalEchoState`'s fallthrough, so re-measure before wiring one up. `accent` is the one exception: it was measured against styles.css on 2026-09-21 (method in the comment above `CLAUDE` in `stock.ts`), though nothing keeps it in step with the CSS either. A field that is both wrong and unread is worse than an absent one, because the next reader trusts it; `test/cli-registry-no-id-branching.test.ts` pins the list so it cannot quietly grow, and wiring one up makes its line there fail, which is the direction you want.
 
 `overlays.credStore` is in the same category, for a sharper reason: the Docker credential-seeding path still reads its own `CRED_STORES` table, because this shape allows ONE store per CLI and the live table needs two for gemini (`.gemini` for the CLI's own auth plus `.config/gcloud` for Vertex), while deepseek declares none here even though `.dsh` is seeded. Wiring it means making the field an array and correcting those two entries — a change to credential seeding, which is simultaneously the worst thing here to get wrong and the least covered by tests, since every docker IO path is no-op'd under vitest.
 

docs/docker-cases.md

@@ -81,6 +81,8 @@ Antigravity (`agy`) and Grok (`grok`) are the two CLIs not installed from npm (G
 
 Pi's credentials are seeded per-FILE rather than as a whole directory (`auth.json`, `settings.json`, `trust.json`, `models.json`, `models-store.json` out of `~/.pi/agent`), because that directory also holds `sessions/`, `extensions/`, `skills/` and the installed package trees — gigabytes on an active host. Consequence: in-container pi sessions are invisible host-side, so `pi -c` inside a Docker case only sees that container's own history. See [`pi-integration.md`](./pi-integration.md). Grok is seeded per-file for the same reason (`auth.json`, `config.toml`, `pager.toml` out of `~/.grok`, which also holds `sessions/`, `memory/` and the ~160MB binary under `downloads/`), with the same consequence for `grok -c`. See [`grok-integration.md`](./grok-integration.md). OMP is the one CLI in this family where `sessions/` is the EXCEPTION rather than the rule: `~/.omp/agent/{config.yml,mcp.json,models.yml,settings.yml}` are seeded per-file (the dir also holds SQLite caches and `terminal-sessions/`), but `~/.omp/agent/sessions/` is shared RW like codex's, not seeded, because Codeman reads it host-side for history recovery and `--resume` pinning. See [`omp-integration.md`](./omp-integration.md).
 
+The image can also carry the GitHub CLI (`gh`) and the Azure CLI (`az` + the `azure-devops` extension, in `AZURE_EXTENSION_DIR=/opt/az-extensions` so it stays out of the seeded HOME), wired into the system git config as credential helpers for github.com and dev.azure.com / *.visualstudio.com, exactly as in `docker/server.Dockerfile`. Their sign-ins are seeded per-FILE like pi's: `~/.config/gh/{hosts.yml,config.yml}` and `~/.azure/{azureProfile.json,msal_token_cache.json,service_principal_entries.json,clouds.config,config}`, never `~/.azure`'s logs, command index or extensions. A token kept in a desktop keyring, or in the encrypted MSAL cache az uses on Windows/macOS, is not in those files and does not carry. None of the three is version-pinned; the `--no-cache` rebuild recommended above is also what refreshes them. Both CLIs are opt-in and OFF by default: `CODEMAN_AGENT_IMAGE_INSTALL_GH=1` / `CODEMAN_AGENT_IMAGE_INSTALL_AZ=1` in the environment of `scripts/build-agent-image.mjs`, or of the Codeman server for its own auto-build (in the Compose deployment, `environment:` in `docker-compose.override.yml`), become the `CODEMAN_INSTALL_GH` / `CODEMAN_INSTALL_AZ` build args and put that CLI, its extension and its helper entry into the image. Unset passes nothing, so a default build's argv is unchanged and the image has neither. The sign-in seeds follow the same switches, read when a case container is created: `.config/gh` only with `CODEMAN_AGENT_IMAGE_INSTALL_GH=1`, `.azure` only with `CODEMAN_AGENT_IMAGE_INSTALL_AZ=1` (`enabledByEnv` in `CRED_STORES`), never merely because the files exist. Seeds are create-time mounts and deliberately not part of the config hash (hashing them would trip the drift gate for every case), so an existing case container picks them up only when it is recreated.
+
 ## Quickest path: one-click "Run in Docker"
 
 On the **New case → Create New** tab there's a **🐳 Run in an isolated Docker container** checkbox. Checking it alone is enough: Codeman creates the case folder in `~/codeman-cases/<name>`, spins up a hardened container with sensible defaults (auto-provisioning a shared `default` host), and starts the session inside it. No host/image/network fields to fill in.

docs/docker-compose.md

@@ -6,6 +6,8 @@ For the Compose configuration, environment settings, storage migration, and macv
 
 The image includes Claude Code, Codex, Gemini CLI, and OpenCode. Authenticate a CLI from its Codeman session; credentials are never baked into the image.
 
+It can also include the GitHub CLI (`gh`) and the Azure CLI (`az`) with the `azure-devops` extension, wired in as Git credential helpers, so Clone Repo and `git clone` reach private GitHub and Azure DevOps repositories once they are signed in. Both are off by default; [Turning them on](../docker/README.md#turning-them-on) shows the `docker-compose.override.yml` settings.
+
 ## Prerequisites
 
 - Docker Engine or Docker Desktop with Docker Compose v2
@@ -67,7 +69,7 @@ If that directory was created by an earlier root-running image, change its owner
 
 Codeman updates itself from **App Settings → Updates**, as it does on a bare host. The checkout mounted at `/opt/codeman` is the same directory Compose builds from, so the update's `git checkout` and rebuild land on the host and survive container recreation; the restart is the server exiting, which `restart: unless-stopped` turns into a relaunch on the new build.
 
-That applies application code only. A release that changes `docker/server.Dockerfile`, `docker/docker-compose.yaml`, or adds a key to `docker/.env.example` needs the image rebuilt or the container recreated, which a container cannot do to itself. The updater detects each case and refuses with a message naming what changed; run `docker/Start-Codeman.sh` on the host to apply those.
+That applies application code only. A release that changes `docker/server.Dockerfile`, `docker/docker-compose.yaml`, or adds a key to `docker/.env.example` needs the image rebuilt or the container recreated, which a container cannot do to itself. The updater detects each case and refuses with a message naming what changed; run `docker/Start-Codeman.sh` on the host to apply those. For a major update, or a base-image change `Start-Codeman.sh` does not fully pick up, `docker/Update-Codeman.sh` rebuilds with no layer cache and clears the two build-artefact volumes before handing off to it (see "Major updates" in `docker/README.md`).
 
 `CODEMAN_REPO_PATH` overrides which checkout is mounted. It defaults to the compose project's parent directory, so it normally needs no setting. Point it at a directory that is not a git checkout and in-app updates are reported as unavailable.
 

docs/docker-self-update.md

@@ -10,15 +10,18 @@ this file covers only what the container changes.
 
 ## The short version
 
-| Change in the release            | Applied by                                       |
-| -------------------------------- | ------------------------------------------------ |
-| Application code                 | The in-app updater                               |
-| `docker/server.Dockerfile`       | `docker/Start-Codeman.sh` on the host            |
-| `docker/docker-compose.yaml`     | `docker/Start-Codeman.sh` on the host            |
-| New key in `docker/.env.example` | Add it to `docker/.env`, then `Start-Codeman.sh` |
+| Change in the release                     | Applied by                                                                      |
+| ----------------------------------------- | ------------------------------------------------------------------------------- |
+| Application code                          | The in-app updater                                                              |
+| `docker/server.Dockerfile`                | `docker/Start-Codeman.sh` on the host                                           |
+| `docker/docker-compose.yaml`              | `docker/Start-Codeman.sh` on the host                                           |
+| New key in `docker/.env.example`          | Add it to `docker/.env`, then `Start-Codeman.sh`                                |
+| A major update, or a Node base-image bump | `docker/Update-Codeman.sh` on the host (no-cache rebuild + fresh build volumes) |
 
-The in-app updater detects all three of the bottom rows itself and refuses with a
+The in-app updater detects the three middle rows itself and refuses with a
 message naming what changed, so you never have to work out which case you are in.
+`Update-Codeman.sh` is the heavier option for when `Start-Codeman.sh` is not
+enough: see "Major updates" in `docker/README.md`.
 
 ## Why the container needs its own path
 
@@ -224,7 +227,10 @@ the host and the in-app path works from then on.
 
 **Resetting the build artefacts** — `docker compose down -v`, then
 `Start-Codeman.sh`. This discards the named volumes and re-seeds them from a fresh
-image.
+image. `docker/Update-Codeman.sh` scripts the same reset by default for the two
+build-artefact volumes (`codeman-node-modules`, `codeman-dist`) only, plus an
+unconditional `--no-cache` rebuild, which a plain `Start-Codeman.sh` run does not
+force on its own. See "Major updates" in `docker/README.md`.
 
 ## Disabling it
 

docs/security-architecture.md

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

docs/wiki/Core-Concepts.md

@@ -20,12 +20,19 @@ Three ways to get one, all under **+** next to the case picker:
 | How               | Result                                                                                                 |
 | ----------------- | ------------------------------------------------------------------------------------------------------ |
 | **Create New**    | A fresh `~/codeman-cases/<name>` with a scaffolded `CLAUDE.md`.                                          |
-| **Clone Repo**    | A public repo cloned into `~/codeman-cases/<name>` and registered as a 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.                    |
 
 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.
 
+**Clone Repo never asks for credentials.** It uses whatever the server's own git already has:
+an ssh key, or a credential helper such as `gh auth setup-git`. The Docker image can include
+helpers for GitHub (`gh`) and Azure DevOps (`az`), turned on in `docker-compose.override.yml`;
+then signing those CLIs in once from a shell session is enough. See the private repositories
+section of `docker/README.md`. Without credentials a private repo fails straight away with an
+authentication error.
+
 **Cases created from scratch are the only copy of that code.** Uninstalling Codeman does not
 delete `~/codeman-cases/`, but treat that directory as real work, not scratch space.
 

docs/wiki/Docker-Cases.md

@@ -118,6 +118,35 @@ invisible from the host (`pi -c` and `grok -c` inside a docker case see only tha
 container's history). OMP's `sessions/` is the exception and is shared read-write, because
 Codeman reads it host-side for history and resume.
 
+**Git hosts.** The agent image can also include the GitHub CLI (`gh`) and the Azure CLI (`az`,
+with the `azure-devops` extension), off by default, and its git then uses them as credential
+helpers for github.com and Azure DevOps. When the matching switch is on, their sign-ins are
+seeded like everything else, file by file: `~/.config/gh/hosts.yml` and `config.yml`, and the
+sign-in files from `~/.azure` (not its logs or extensions). With a switch off they are never
+copied in, even if the files exist. So once a switch is on and `gh auth login` / `az login`
+have been run where Codeman runs, agents in a Docker case can clone and push private repos on
+those hosts. Two limits:
+
+- A token held in a desktop keyring or an encrypted token cache (Windows, macOS) is not
+  inside those files and does not carry in. Sign in inside the container instead. The Docker
+  server image and a headless Linux host keep it in the files, so they carry.
+- The sign-ins are mounted when a case container is **created**, so an existing container
+  never picks them up. After turning a switch on, signing in, or rebuilding the agent image,
+  **recreate the case container**: remove it, and the next session in that case creates a
+  fresh one. (Or sign in inside the existing container instead.)
+
+This hands a GitHub token and an Azure sign-in to every agent in a seeded Docker case, the
+same trust you already give it with Claude, Codex or gcloud. Turn seeding off for a case that
+should not have them.
+
+Both CLIs are opt-in. To build the agent image with them, set
+`CODEMAN_AGENT_IMAGE_INSTALL_GH=1` and/or `CODEMAN_AGENT_IMAGE_INSTALL_AZ=1` where the image
+is built: in front of `node scripts/build-agent-image.mjs`, or in the Codeman server's
+environment for the image it builds automatically (in the Docker deployment, `environment:`
+in `docker-compose.override.yml`), then rebuild the image with `--no-cache`.
+`docker/README.md` ("Private repositories") has the details and the matching switches for
+the server image.
+
 ## Isolation
 
 Every container runs hardened by default:

docs/wiki/Notifications-And-Approvals.md

@@ -103,6 +103,30 @@ locked phone and the agent continues.
 With the inbox off, the buttons are stripped from the notification payload entirely rather
 than being shown and failing.
 
+## When a session is watching its own work
+
+An agent that starts a monitor, puts a shell in the background or hands a task to a cloud
+session is told by its CLI to end the turn and wait to be notified. The pane then goes
+quiet, and the CLI's idle notification arrives about a minute later — for a session that
+wants nothing from you.
+
+Codeman reads what the CLI prints about its own background work and treats that prompt
+differently. It raises no tab alert, no desktop notification and no push, the session stays
+out of NEEDS YOU on every surface, and the row wears a blue **watching** badge instead. Hover
+it, or read it on a phone through your screen reader, and it says what is running: "1
+monitor", "2 shells", "1 background terminal".
+
+The prompt itself is not thrown away. It sits in the Approvals drawer as an ordinary card,
+still answerable, with a line reading "quiet, watching 1 monitor" where a card you had
+already looked at would say nothing. The next time that session goes quiet for an ordinary
+reason, it alerts you exactly as before.
+
+Two limits are worth knowing. A permission prompt or a question dialog still goes red
+whatever else the agent started, because that one blocks it outright. A question asked in
+plain prose is not a dialog, so an agent that starts a monitor and then writes "which branch
+should I target?" is quiet along with the rest — check a watching session yourself if it has
+been quiet longer than the work it is waiting for should take.
+
 ## The phone overview
 
 On phones, tapping the "C" logo gives a session overview with **NEEDS YOU** first, then

docs/wiki/Quick-Start.md

@@ -43,7 +43,7 @@ To make a new one, click **+** next to the picker. The Add Case dialog has three
 | Tab               | Use it when                                                                                                        |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
 | **Create New**    | Starting a fresh project. Creates `~/codeman-cases/<name>` and scaffolds a `CLAUDE.md` into it.                     |
-| **Clone Repo**    | Working on an existing public repo. Paste the URL; Codeman preflights it as you type, offers the repo's real branches and tags, and fills in the case name. |
+| **Clone Repo**    | Working on an existing repo: public, or private once this machine's git can authenticate (the Docker image can include `gh`/`az` helpers for this). Paste the URL; Codeman preflights it as you type, offers the repo's real branches and tags, and fills in the case name. |
 | **Link Existing** | The code is already on disk. Point at the folder, with **Browse** if you would rather click than type.               |
 
 The gear next to the picker holds two per-case toggles: **Agent Teams** and

docs/wiki/Settings-Reference.md

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

docs/wiki/The-Dashboard.md

@@ -48,6 +48,7 @@ One tab per session, in your order, and that order syncs across your devices.
 | Yellow tab, blinking          | The agent is waiting for input from you.                                 |
 | Red tab, blinking             | A question or permission prompt is blocking the session.                 |
 | No dot                        | The session is not running.                                              |
+| Muted grey dot plus an `exited (137)` badge | The agent inside the pane has exited, with that exit code (or `exited (signal 9)`). A bare `exited` means tmux saw the pane die but did not report how, which is not the same as a clean `exited (0)`. Detailed sidebar and rail rows read `exited` in their pill. |
 
 ![Tab alerts](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/tab-alerts-20260815.png)
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "aicodeman",
-  "version": "1.32.0",
+  "version": "1.32.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "aicodeman",
-      "version": "1.32.0",
+      "version": "1.32.1",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -55,6 +55,7 @@
         "@types/web-push": "^3.6.4",
         "@types/ws": "^8.18.1",
         "@vitest/coverage-v8": "^4.1.8",
+        "@xterm/headless": "^6.0.0",
         "agent-browser": "^0.6.0",
         "esbuild": "^0.27.3",
         "eslint": "^9.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.32.0",
+  "version": "1.32.1",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -123,6 +123,7 @@
     "@types/web-push": "^3.6.4",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.8",
+    "@xterm/headless": "^6.0.0",
     "agent-browser": "^0.6.0",
     "esbuild": "^0.27.3",
     "eslint": "^9.0.0",

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

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

scripts/build.mjs

@@ -146,10 +146,44 @@ console.log('\n[build] content-hash cache busting');
     html = html.replaceAll(`"${original}"`, `"${hashed}"`);
   }
   writeFileSync(join(distPublic, 'index.html'), html);
+
+  // Rewrite sw.js from the SAME manifest that just renamed the files.
+  //
+  // The service worker's precache list used to be maintained by hand with the
+  // pre-hash names, so after this step every entry in it pointed at a file that
+  // no longer existed and `cache.add(...).catch(() => {})` hid it. Deriving it
+  // here is the only way the two cannot drift.
+  //
+  // The cache key gets the build hash for the same reason: `activate` deletes
+  // every cache that is not the current one, so a constant key meant that
+  // cleanup never ran and hashed assets from every past release piled up.
+  const swPath = join(distPublic, 'sw.js');
+  let sw = readFileSync(swPath, 'utf8');
+  const hashedAssets = Object.values(manifest);
+  const buildId = createHash('md5').update(hashedAssets.join('|')).digest('hex').slice(0, 12);
+  // Rewrite the two declarations. Anchored on the full `const … = …;` text so
+  // each pattern occurs exactly once and cannot collide with prose in sw.js's
+  // own comments — an earlier cut used bare `__BUILD_ID__` sentinels and the
+  // first match landed in the comment that documented them, leaving the real
+  // constant untouched and still producing a plausible-looking cache key.
+  const swEdits = [
+    ["const BUILD_ID = 'dev';", `const BUILD_ID = '${buildId}';`],
+    ['const HASHED_ASSETS = [];', `const HASHED_ASSETS = [${hashedAssets.map((p) => JSON.stringify(p)).join(', ')}];`],
+  ];
+  for (const [from, to] of swEdits) {
+    const hits = sw.split(from).length - 1;
+    if (hits !== 1) {
+      throw new Error(`sw.js: expected exactly one \`${from}\`, found ${hits} — precache would ship stale`);
+    }
+    sw = sw.replace(from, to);
+  }
+  writeFileSync(swPath, sw);
+
   console.log('  Hashed files:');
   for (const [orig, hashed] of Object.entries(manifest)) {
     console.log(`    ${orig} -> ${hashed}`);
   }
+  console.log(`  sw.js: cache bucket codeman-${buildId}, ${hashedAssets.length} precached assets`);
 }
 
 // 6. Compress with gzip + brotli

scripts/lib/cli-catalog.mjs

@@ -55,9 +55,36 @@ export function agentImageNpmPackages(catalog) {
   return packages;
 }
 
-/** The `--build-arg` pairs the agent image takes. PURE. */
-export function agentImageBuildArgPairs(catalog) {
-  return [['CLI_NPM_PACKAGES', agentImageNpmPackages(catalog).join(' ')]];
+/**
+ * Environment variable → agent.Dockerfile ARG for the optional git-host CLIs (gh, az).
+ * ⚠️ Mirrored by `GIT_HOST_CLI_BUILD_ARGS` in `src/docker-hosts.ts`; the parity test pins them.
+ */
+export const GIT_HOST_CLI_BUILD_ARGS = [
+  ['CODEMAN_AGENT_IMAGE_INSTALL_GH', 'CODEMAN_INSTALL_GH'],
+  ['CODEMAN_AGENT_IMAGE_INSTALL_AZ', 'CODEMAN_INSTALL_AZ'],
+];
+
+/**
+ * The `--build-arg` pairs for the optional git-host CLIs. PURE. An unset or empty variable
+ * contributes NOTHING, so the Dockerfile's own default (off) applies and the argv is the same
+ * as before these existed; anything other than 0/1 is refused rather than guessed at.
+ */
+export function gitHostCliBuildArgPairs(env) {
+  const pairs = [];
+  for (const [envName, argName] of GIT_HOST_CLI_BUILD_ARGS) {
+    const value = env[envName];
+    if (value === undefined || value === '') continue;
+    if (value !== '0' && value !== '1') {
+      throw new Error(`${envName} must be 0 or 1, got ${JSON.stringify(value)}`);
+    }
+    pairs.push([argName, value]);
+  }
+  return pairs;
+}
+
+/** The `--build-arg` pairs the agent image takes. PURE given `env`. */
+export function agentImageBuildArgPairs(catalog, env = process.env) {
+  return [['CLI_NPM_PACKAGES', agentImageNpmPackages(catalog).join(' ')], ...gitHostCliBuildArgPairs(env)];
 }
 
 /** Read the committed catalogue. IO. */

src/config/cli-registry/schema.ts

@@ -294,6 +294,23 @@ const capabilitiesSchema = z
     effort: z.boolean(),
     agentSkillInjection: z.boolean(),
     statusLineTelemetry: z.boolean(),
+    // How many columns this CLI indents its transcript body by, so a copy can take
+    // that much off the clipboard. Bounded, because it is the whole strip: a copy
+    // never removes more than this, nor more than every selected line shares.
+    //
+    // ⚠ DECLARED, not measured off the pane, and two measured attempts are why.
+    // Asking whether the pane painted spaces across the unused part of each row
+    // separates a TUI from a shell perfectly where it fires and never
+    // over-stripped, but it is a function of pane WIDTH: that padding exists
+    // only while a rendered line stops short of the CLI's own layout width, and
+    // Claude Code's prose wraps to fill it — the share of padded rows on one
+    // live transcript ran 44%, 6%, 6%, 7% and 87% at 123, 160, 198, 235 and 298
+    // columns, so the strip did nothing at any ordinary size. Taking the
+    // narrowest indent on screen instead fires everywhere and over-strips, since
+    // a file listing inside the transcript can be the narrowest thing on it.
+    // A declared width cannot do either. Absent means no strip, so a CLI whose
+    // transcript layout nobody has measured is never touched.
+    transcriptGutter: z.number().int().min(1).max(8).optional(),
     workDetect: z
       .object({
         promptGlyph: z.string().min(1).max(8),
@@ -308,8 +325,29 @@ const capabilitiesSchema = z
             (src) => compileVersionRegex(src) !== null,
             'workingLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
           ),
+        // Same guard, same reasons: this one runs over the foot of a pane capture every
+        // time a session settles, and ~/.codeman/clis.json can set it.
+        watchingLine: z
+          .string()
+          .min(1)
+          .refine(
+            (src) => compileVersionRegex(src) !== null,
+            'watchingLine must be a regex compileVersionRegex() accepts: at most 200 characters, no nested quantifiers'
+          )
+          .optional(),
+        // Bounded hard: this is how far up the screen a config file may push the search,
+        // and every row it adds is one more row the agent itself may be able to write.
+        watchingLines: z.number().int().min(1).max(8).optional(),
       })
       .strict()
+      // A window with nothing to search is a typo, not a configuration. Refused at LOAD
+      // time for the same reason `privilegedParams[].param` is checked against the params
+      // the entry declares: the failure is otherwise silent and looks like a feature that
+      // simply never fires.
+      .refine(
+        (v) => v.watchingLines === undefined || v.watchingLine !== undefined,
+        'watchingLines has nothing to bound without a watchingLine'
+      )
       .optional(),
     model: z
       .object({ source: z.enum(['flag', 'claude-settings-file', 'none']), param: z.string().optional() })

src/config/cli-registry/stock.ts

@@ -75,11 +75,24 @@ function agentDefaults(): Pick<
   };
 }
 
+// `accent` on every entry below (except SHELL, which the frontend renders no
+// distinct color for) is measured from the actual `.btn-toolbar.btn-run.mode-<id>`
+// CSS rule's `border-color` on the OG skin (styles.css) — the single cleanest
+// representative hex each entry's own multi-stop gradient resolves around.
+// Corrected 2026-09-21 after PR #458's review found several were simply wrong
+// (e.g. claude was registered as Anthropic's brand orange, `#d97757`, but the
+// button renders blue): `docs/cli-registry.md`'s own "transcribed, not
+// authoritative, re-measure before wiring one up" warning for this
+// DECLARED-FOR-LATER field, taken literally. The one exception is GEMINI, whose
+// run-button border (#60a5fa) is the only one that disagrees with its own tab badge
+// and run-mode dot (#8ab4f8); it takes the badge colour, so every accent names the
+// same hex the frontend uses as that CLI's flat identity. This is a data-accuracy fix only —
+// `accent` still has no reader, so nothing rendered changes because of it.
 const CLAUDE: CliEntry = {
   id: 'claude' as CliEntry['id'],
   label: 'Claude',
   shortBadge: 'CC',
-  accent: '#d97757',
+  accent: '#3b82f6',
   enabled: true,
   stock: true,
   order: 0,
@@ -200,12 +213,31 @@ const CLAUDE: CliEntry = {
   },
   capabilities: {
     external: false,
+    // Claude indents its transcript body two columns and puts its own ●/✻/❯ markers
+    // in them, so a copy can drop two and paste flush. Claude and codex are the only
+    // entries that declare this, because theirs are the only gutters that have been measured.
+    transcriptGutter: 2,
     // The historical hard-coded pair, now stated as data. `workingLine` matches both the
     // `✻ Actualizing… (39s · ↓ 2.0k tokens)` status line and the bare `esc to interrupt`
     // footer, because tmux repaints partially and only one of the two may land in a chunk.
     workDetect: {
       promptGlyph: '❯',
       workingLine: String.raw`…\s*\((?:\d+h\s+)?(?:\d+m\s+)?\d+s\b|esc to interrupt`,
+      // Claude prints what it started in the background on the footer row beneath its
+      // composer, as `⏵⏵ bypass permissions on · 1 monitor · ← for agents`. The labels are
+      // the CLI's own words for each kind of background task, and group 1 is the one
+      // Codeman badges the session with. Verified against a live 2.1.278 pane on
+      // 2026-09-21.
+      // ⚠️ Two things keep an agent from writing its own label here, and both matter.
+      // The footer is the LAST row, so the default one-row window (`WATCHING_TAIL_LINES`)
+      // holds nothing but Ink's own chrome — in particular it leaves out the status line
+      // directly above, whose content comes from a `statusLine` command a bypassed
+      // session can write into its own `.claude/settings.json`. And the leading `·` keeps
+      // the match on the footer's own item list rather than on any text that happens to
+      // carry a count. A footer that ever drew the chip as its only item would report no
+      // watching rather than open that door. See `watchingLabel()` in
+      // `session-activity.ts`.
+      watchingLine: String.raw`·\s*(\d+ (?:monitors?|shells?|teams?|local agents?|cloud sessions?|MCP tasks?|background tasks?|(?:background|remote) dynamic workflows?|Artifact comment monitors?))`,
     },
     requiresMux: false,
     // Claude installs Codeman's own hooks block into every workspace it runs in, so its
@@ -368,7 +400,7 @@ const OPENCODE: CliEntry = {
   id: 'opencode' as CliEntry['id'],
   label: 'OpenCode',
   shortBadge: 'OC',
-  accent: '#f59e0b',
+  accent: '#10b981',
   enabled: true,
   stock: true,
   order: 10,
@@ -454,7 +486,7 @@ const CODEX: CliEntry = {
   id: 'codex' as CliEntry['id'],
   label: 'Codex',
   shortBadge: 'CX',
-  accent: '#6b7fd7',
+  accent: '#a855f7',
   enabled: true,
   stock: true,
   order: 20,
@@ -518,7 +550,43 @@ const CODEX: CliEntry = {
     // `Working (2m 49s • esc to interrupt)` above it while a turn runs. It animates no
     // braille spinner, and it never prints `esc to interrupt` at rest, so that phrase
     // alone separates a running turn from an idle one.
-    workDetect: { promptGlyph: '›', workingLine: '[Ee]sc to interrupt' },
+    // Codex pins a row of its own while a background terminal it started is still
+    // running: `  1 background terminal running · /ps to view · /stop to close`. Unlike
+    // Claude's footer chip that row sits ABOVE the composer, which puts it third from the
+    // bottom once the status line and the composer are counted, hence `watchingLines`.
+    // Measured against a live codex-cli 0.154.0 pane on 2026-09-22: the row appears when
+    // the terminal starts, follows the composer down as the conversation grows, and is
+    // gone after `/stop`.
+    // ⚠️ This entry CANNOT promise what Claude's does, and the difference is Codex's
+    // layout rather than its pattern. The third row from the bottom is the chip only
+    // while a terminal runs; with none running it is the last row of the transcript,
+    // which the agent writes. Matching the complete row raises the bar — an assistant
+    // message has to end with this exact line, to the character — but nothing here makes
+    // forging it impossible, so do not read the Claude comment above as applying here.
+    // What contains it is that codex declares `hooks: 'none'`: no hook event from a codex
+    // session ever reaches `notePrompt()`, so there is no idle item to pre-acknowledge
+    // and a forged label costs a wrong badge and nothing else. A CLI that gains hook
+    // signals must not keep a pattern this soft.
+    // ⚠️ Background TERMINALS are the only background work codex advertises on screen.
+    // A sub-agent started without waiting outlives the turn just as a terminal does —
+    // measured 2026-09-22, the sandboxed process was still running — and the pane shows
+    // nothing at all for it: the last rows are the composer and the status line, and
+    // `Sub-agents running` lives in the on-demand `/subagents` panel, not above the
+    // composer. So a codex session waiting on a sub-agent reads as plainly idle here.
+    // Nothing is misfiled by that (codex raises no idle prompts), and there is no row to
+    // match until codex pins one.
+    workDetect: {
+      promptGlyph: '›',
+      workingLine: '[Ee]sc to interrupt',
+      watchingLine: String.raw`^\s{0,4}(\d+ background terminals?) running · /ps to view · /stop to close$`,
+      watchingLines: 3,
+    },
+    // Two columns, like claude's, measured on a live 0.154.0 answer: the `•`/`›`/`⚠`
+    // markers sit in the gutter, prose continuations sit at 2, and a nested YAML block
+    // the model wrote rendered at 2/4/6/8 for its own 0/2/4/6. Replayed at 100, 120,
+    // 160, 198, 235 and 282 columns the indents were 0, 2, 4, 6 and 8 at every one,
+    // never 1, so the width is not a function of the pane.
+    transcriptGutter: 2,
     transcript: 'codex-rollout',
     altScreen: 'strip-full',
     echo: { policy: 'predict', anchor: { kind: 'cursor' }, predictProfile: 'codex' },
@@ -565,7 +633,8 @@ const GEMINI: CliEntry = {
   id: 'gemini' as CliEntry['id'],
   label: 'Gemini',
   shortBadge: 'GM',
-  accent: '#4285f4',
+  // The tab badge / run-mode-dot colour, not the run-button border (see the note above CLAUDE).
+  accent: '#8ab4f8',
   enabled: true,
   stock: true,
   order: 30,
@@ -657,7 +726,7 @@ const ANTIGRAVITY: CliEntry = {
   id: 'antigravity' as CliEntry['id'],
   label: 'Antigravity',
   shortBadge: 'AG',
-  accent: '#8b5cf6',
+  accent: '#22d3ee',
   enabled: true,
   stock: true,
   order: 40,
@@ -727,7 +796,7 @@ const PI: CliEntry = {
   id: 'pi' as CliEntry['id'],
   label: 'Pi',
   shortBadge: 'PI',
-  accent: '#10b981',
+  accent: '#f472b6',
   enabled: true,
   stock: true,
   order: 50,
@@ -851,10 +920,10 @@ const GROK: CliEntry = {
   shortBadge: 'GK',
   // Upstream hand-authored a charcoal GRADIENT across 4+ CSS spots (welcome button, tab
   // badge, run-mode dot, mobile skin overrides) rather than one flat colour; our registry's
-  // `accent` is a single hex, so this is the closest single value (the run-mode-dot colour,
-  // zinc-400). Nothing reads `accent` yet — the frontend is untouched in this change and
-  // keeps its own hand-authored CSS; the field is here so the entry is complete.
-  accent: '#a1a1aa',
+  // `accent` is a single hex, so this is the closest single value (zinc-300, the run-button
+  // border and tab-badge colour). Nothing reads `accent` yet: the frontend keeps its own
+  // hand-authored CSS; the field is here so the entry is complete.
+  accent: '#d4d4d8',
   enabled: true,
   stock: true,
   order: 70,
@@ -986,7 +1055,7 @@ const DEEPSEEK: CliEntry = {
   id: 'deepseek' as CliEntry['id'],
   label: 'DeepSeek',
   shortBadge: 'DS',
-  accent: '#4d6bfe',
+  accent: '#7c93ff',
   enabled: true,
   stock: true,
   order: 80,
@@ -1151,7 +1220,7 @@ const OMP: CliEntry = {
   id: 'omp' as CliEntry['id'],
   label: 'OMP',
   shortBadge: 'OM',
-  accent: '#7c9cf5',
+  accent: '#818cf8',
   enabled: true,
   stock: true,
   order: 90,

src/config/cli-registry/types.ts

@@ -344,7 +344,48 @@ export interface CliCapabilities {
     promptGlyph: string;
     /** Source of a regex matching the status line this CLI draws while a turn runs. */
     workingLine: string;
+    /**
+     * Source of a regex matching the row this CLI draws while work it started in the
+     * background is still running, e.g. Claude's `· 1 monitor ·` footer chip or Codex's
+     * `1 background terminal running · /ps to view`. Capture group 1 is the label Codeman
+     * shows, and the whole match stands in when the pattern declares no group. A CLI that
+     * omits this reports no background work, which is what every CLI did before the field
+     * existed.
+     */
+    watchingLine?: string;
+    /**
+     * How many rows at the FOOT of the screen that row can appear in, counting non-blank
+     * rows only. Claude writes its chip on the last row and keeps the default; Codex pins
+     * its own above the composer, which puts it third from the bottom, so it declares
+     * more. Keep each number as small as that CLI's layout allows: every extra row is
+     * another row an agent might be able to write, and the label is what silences an
+     * alert. See `watchingLabel()` in `session-activity.ts`.
+     */
+    watchingLines?: number;
   };
+  /**
+   * How many columns this CLI indents its transcript body by, so a copy taken from its
+   * pane can drop that much and paste flush. Claude Code indents two and puts its own
+   * markers in those columns.
+   *
+   * ⚠ DECLARED rather than measured off the pane, and two measured attempts are why.
+   * Asking whether the pane painted real spaces across the unused part of each row
+   * separates a TUI from a shell perfectly where it fires and never over-stripped; it
+   * is also a function of pane WIDTH, because that padding exists only while a
+   * rendered line stops short of the CLI's own layout width and Claude Code's prose
+   * wraps to fill it. On one live transcript the share of padded rows ran 44%, 6%, 6%,
+   * 7% and 87% at 123, 160, 198, 235 and 298 columns, so at any ordinary window size
+   * the strip silently did nothing. Taking the narrowest indent on the surrounding
+   * rows instead fires at every width and over-strips on roughly 1% of selections,
+   * because a file listing inside the transcript can be the narrowest thing on screen.
+   *
+   * A declared width can do neither. The strip is the lesser of this and what every
+   * selected line shares, so a block can only ever shift as a unit, and it can never
+   * shift further than the CLI itself says its gutter is.
+   *
+   * Absent means no strip at all, the same fail-safe direction `workDetect` takes.
+   */
+  transcriptGutter?: number;
   /** No direct-PTY fallback: the CLI must run inside tmux (secrets ride tmux setenv). */
   requiresMux: boolean;
   /**
@@ -651,7 +692,13 @@ export interface CliEntry {
   label: string;
   /** Two-ish character tab badge, e.g. 'OC'. */
   shortBadge: string;
-  /** Single hex colour. CSS derives every per-CLI gradient from it via --cli-accent. */
+  /**
+   * Single hex colour, measured from the CLI's actual `.btn-toolbar.btn-run.mode-<id>`
+   * gradient in styles.css (see stock.ts's comment above `CLAUDE` for the exact
+   * methodology). DECLARED-FOR-LATER (above) — no code reads this yet; styles.css's
+   * gradients are still hand-authored per id, not derived from this field via any
+   * CSS custom property. There is no `--cli-accent` variable in the codebase.
+   */
   accent: string;
   enabled: boolean;
   /** Set by the loader from the shipped catalog; a user entry can never claim it. */

src/docker-hosts.ts

@@ -606,9 +606,36 @@ export function agentImageNpmPackages(): string[] {
   return packages;
 }
 
-/** The `--build-arg` pairs the agent image takes. */
-export function agentImageBuildArgPairs(): Array<[string, string]> {
-  return [['CLI_NPM_PACKAGES', agentImageNpmPackages().join(' ')]];
+/**
+ * Environment variable → agent.Dockerfile ARG for the optional git-host CLIs (gh, az).
+ * ⚠️ Mirrors `GIT_HOST_CLI_BUILD_ARGS` in `scripts/lib/cli-catalog.mjs`; the parity test pins them.
+ */
+export const GIT_HOST_CLI_BUILD_ARGS: ReadonlyArray<readonly [string, string]> = [
+  ['CODEMAN_AGENT_IMAGE_INSTALL_GH', 'CODEMAN_INSTALL_GH'],
+  ['CODEMAN_AGENT_IMAGE_INSTALL_AZ', 'CODEMAN_INSTALL_AZ'],
+];
+
+/**
+ * The `--build-arg` pairs for the optional git-host CLIs. PURE. An unset or empty variable
+ * contributes NOTHING, so the Dockerfile's own default (off) applies and the argv is the same
+ * as before these existed; anything other than 0/1 is refused rather than guessed at.
+ */
+export function gitHostCliBuildArgPairs(env: NodeJS.ProcessEnv): Array<[string, string]> {
+  const pairs: Array<[string, string]> = [];
+  for (const [envName, argName] of GIT_HOST_CLI_BUILD_ARGS) {
+    const value = env[envName];
+    if (value === undefined || value === '') continue;
+    if (value !== '0' && value !== '1') {
+      throw new Error(`${envName} must be 0 or 1, got ${JSON.stringify(value)}`);
+    }
+    pairs.push([argName, value]);
+  }
+  return pairs;
+}
+
+/** The `--build-arg` pairs the agent image takes. PURE given `env`. */
+export function agentImageBuildArgPairs(env: NodeJS.ProcessEnv = process.env): Array<[string, string]> {
+  return [['CLI_NPM_PACKAGES', agentImageNpmPackages().join(' ')], ...gitHostCliBuildArgPairs(env)];
 }
 
 // ========== Credential mount resolution (IO) ==========
@@ -785,6 +812,14 @@ interface CredStorePolicy {
   seedFiles?: string[];
   /** Seed the WHOLE dir (RO mount → cp -a) — for stores with no shared/host-read state. */
   seedWhole?: boolean;
+  /**
+   * Seed this store ONLY when this environment variable is exactly `1`, read when
+   * the container is created. For credentials that belong to an opt-in tool rather
+   * than to an agent CLI every case already trusts: they are not inert just because
+   * the image lacks the tool (a gh `hosts.yml` token or an Azure refresh token is
+   * usable by anything in the container, and the agent in it is prompt-injectable).
+   */
+  enabledByEnv?: string;
 }
 
 const CRED_STORES: CredStorePolicy[] = [
@@ -829,6 +864,31 @@ const CRED_STORES: CredStorePolicy[] = [
   },
   { rel: '.config/gcloud', seedWhole: true },
   { rel: '.config/opencode', seedWhole: true },
+  // GitHub CLI: `hosts.yml` holds the token wherever no system keyring exists (the
+  // Docker server image, a headless Linux host), `config.yml` the preferences. An
+  // agent image built with CODEMAN_INSTALL_GH=1 routes github.com git credentials
+  // through `gh`, so this seed is what lets an agent clone/push a private repo. A
+  // token that lives in a desktop keyring is not in `hosts.yml` and does not carry
+  // in; sign `gh` in inside the container. OPT-IN: seeded only when the same switch
+  // that builds gh into the agent image is on, never merely because the file exists.
+  { rel: '.config/gh', seedFiles: ['hosts.yml', 'config.yml'], enabledByEnv: 'CODEMAN_AGENT_IMAGE_INSTALL_GH' },
+  // Azure CLI: only the sign-in state. `~/.azure` also accumulates `logs/`,
+  // `commands/`, telemetry and (on a bare host) `cliextensions/`, none of which is
+  // needed to authenticate; the agent image carries its own extensions outside HOME.
+  // `msal_token_cache.json` is plaintext only on Linux (Windows/macOS encrypt it), so
+  // this carries a sign-in from the Docker server image or a Linux host.
+  // OPT-IN like gh: the MSAL cache holds refresh tokens for the whole Azure account.
+  {
+    rel: '.azure',
+    enabledByEnv: 'CODEMAN_AGENT_IMAGE_INSTALL_AZ',
+    seedFiles: [
+      'azureProfile.json',
+      'msal_token_cache.json',
+      'service_principal_entries.json',
+      'clouds.config',
+      'config',
+    ],
+  },
   // OMP keeps its config in `~/.omp/agent` (config.yml/mcp.json/models.yml/
   // settings.yml — small, no bigger than grok's config.toml/pager.toml), but
   // that dir ALSO holds agent.db/history.db/models.db (SQLite caches) and
@@ -853,10 +913,14 @@ const CRED_STORES: CredStorePolicy[] = [
  * session state back into the host). Every path is existsSync-gated (on most hosts
  * only a subset exists). Pure-ish IO (no writes; just existence checks + mount specs).
  */
-export function resolveDockerCredentialArtifacts(home: string = homedir()): DockerClaudeArtifacts {
+export function resolveDockerCredentialArtifacts(
+  home: string = homedir(),
+  env: NodeJS.ProcessEnv = process.env
+): DockerClaudeArtifacts {
   const mounts: DockerMount[] = [];
   const seedCopies: DockerSeedCopy[] = [];
   for (const store of CRED_STORES) {
+    if (store.enabledByEnv && env[store.enabledByEnv] !== '1') continue;
     const hostBase = join(home, store.rel);
     if (!existsSync(hostBase)) continue;
     const containerBase = `${CONTAINER_HOME}/${store.rel}`;
@@ -1136,10 +1200,17 @@ function buildAgentImage(
       error: `docker/agent.Dockerfile not found in this install; clone the repo or build ${image} manually`,
     });
   }
+  let buildArgPairs: Array<[string, string]>;
+  try {
+    buildArgPairs = agentImageBuildArgPairs();
+  } catch (err) {
+    // A malformed CODEMAN_AGENT_IMAGE_INSTALL_* value: report it like any other build failure.
+    return Promise.resolve({ ok: false, built: false, alreadyPresent: false, error: String((err as Error).message) });
+  }
   const argv = dockerEngineArgv(docker);
   const args = [
     ...argv.slice(1),
-    ...agentImageBuildArgs(resolved.dockerfile, image, resolved.contextDir, opts.noCache, agentImageBuildArgPairs()),
+    ...agentImageBuildArgs(resolved.dockerfile, image, resolved.contextDir, opts.noCache, buildArgPairs),
   ];
   return new Promise<EnsureImageResult>((resolve) => {
     // async spawn (NEVER spawnSync) so a multi-minute build never wedges the event loop.

src/git-clone.ts

@@ -195,6 +195,8 @@ export interface CloneOptions {
   /** `--depth 1`: history-less but much faster on large repos. */
   shallow?: boolean;
   timeoutMs?: number;
+  /** Clear every git credential helper for this run (see `GIT_NO_CREDENTIAL_HELPERS`). */
+  withoutCredentialHelpers?: boolean;
 }
 
 export type CloneResult = { ok: true; stderr: string } | { ok: false; failure: GitFailure };
@@ -436,12 +438,27 @@ export function isSafeGitRef(ref: string): boolean {
 
 // ─── Pure: argv + env ────────────────────────────────────────────────────────
 
+/**
+ * Global git options that empty the credential-helper list for one run.
+ *
+ * Every Codeman user in multi-user mode runs git as the SAME OS account, so a
+ * helper that account has (the Docker image's opt-in `gh`/`az` helpers, or a
+ * user's own `gh auth setup-git`) would read private repositories on the
+ * signed-in admin's behalf for anyone who can reach Clone Repo. An empty
+ * `credential.helper` resets the helper list, and a command-line `-c` is read
+ * last, so it also drops the URL-scoped `credential.<url>.helper` entries the
+ * image configures (verified against a real private repo: refs with the helper,
+ * `could not read Username` with it cleared). Public repositories are
+ * unaffected. It must precede the subcommand.
+ */
+export const GIT_NO_CREDENTIAL_HELPERS: readonly string[] = ['-c', 'credential.helper='];
+
 /**
  * argv for the clone. `--` separates flags from operands so neither the
  * repository nor the destination can ever be read as an option.
  */
 export function buildCloneArgs(opts: CloneOptions): string[] {
-  const args = ['clone'];
+  const args = [...(opts.withoutCredentialHelpers ? GIT_NO_CREDENTIAL_HELPERS : []), 'clone'];
   // `--single-branch` is what makes "just this tag/branch" cheap on a big repo.
   if (opts.ref) args.push('--single-branch', '--branch', opts.ref);
   if (opts.shallow) args.push('--depth', '1');
@@ -450,8 +467,14 @@ export function buildCloneArgs(opts: CloneOptions): string[] {
 }
 
 /** argv for the preflight. `--symref` is what reveals the remote's default branch. */
-export function buildLsRemoteArgs(repository: string): string[] {
-  return ['ls-remote', '--symref', '--', repository];
+export function buildLsRemoteArgs(repository: string, opts: { withoutCredentialHelpers?: boolean } = {}): string[] {
+  return [
+    ...(opts.withoutCredentialHelpers ? GIT_NO_CREDENTIAL_HELPERS : []),
+    'ls-remote',
+    '--symref',
+    '--',
+    repository,
+  ];
 }
 
 /**
@@ -579,7 +602,7 @@ export function classifyGitFailure(stderr: string, timedOut: boolean, spawnError
     return {
       code: 'AUTH_REQUIRED',
       message:
-        'That repository needs authentication. Codeman clones without credentials, so private repositories have to be cloned outside Codeman and added with Link Existing.',
+        "That repository needs authentication. Codeman never asks for credentials, so sign this server's git in first (for example `gh auth login` or `az login` from a shell session; the Docker image can include both, see docker/README.md), or clone it outside Codeman and add it with Link Existing.",
       stderr: clean,
     };
   }
@@ -790,7 +813,8 @@ export function isGitAvailable(): boolean {
  */
 export async function probeGitRemote(
   repository: string,
-  timeoutMs = GIT_LS_REMOTE_TIMEOUT_MS
+  timeoutMs = GIT_LS_REMOTE_TIMEOUT_MS,
+  opts: { withoutCredentialHelpers?: boolean } = {}
 ): Promise<GitRemoteProbe> {
   if (!isGitAvailable()) {
     return {
@@ -800,7 +824,7 @@ export async function probeGitRemote(
       failure: classifyGitFailure('', false, 'ENOENT: git not found'),
     };
   }
-  const run = await runGit(buildLsRemoteArgs(repository), timeoutMs, MAX_LS_REMOTE_BYTES);
+  const run = await runGit(buildLsRemoteArgs(repository, opts), timeoutMs, MAX_LS_REMOTE_BYTES);
   if (run.code !== 0 || run.spawnError) {
     return {
       reachable: false,

src/mux-interface.ts

@@ -24,6 +24,7 @@ import type {
   OmpConfig,
   SessionRemote,
   SessionDocker,
+  PaneExit,
 } from './types.js';
 
 /**
@@ -56,6 +57,23 @@ export interface MuxSession {
   respawnConfig?: PersistedRespawnConfig;
   /** Whether Ralph / Todo tracking is enabled */
   ralphEnabled?: boolean;
+  /**
+   * This record was rebuilt from the tmux socket rather than from Codeman's own
+   * bookkeeping, so everything on it but the name and the pid is a guess. Its
+   * synthetic `restored-<fragment>` id cannot find the session's `state.json`
+   * entry either, which means a remote or docker session rediscovered this way
+   * arrives with no `remote`/`docker` metadata and looks local. Anything that
+   * would be WRONG about such a session rather than merely vague must fail
+   * closed on this flag.
+   *
+   * ⚠ It is PERMANENT, not merely true for the boot that rediscovered the
+   * session: `saveSessions()` serializes the whole record to
+   * `mux-sessions.json` and `loadSessions()` restores it, so a genuinely local
+   * session rediscovered once stays opted out of everything keyed on this for
+   * the life of that record. That is the safe direction to fail, and it costs
+   * only the guess Codeman is declining to make.
+   */
+  discovered?: boolean;
 }
 
 /**
@@ -180,6 +198,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
  */
 export interface TerminalMultiplexer extends EventEmitter {
   /** Which backend this instance uses */
@@ -294,6 +313,24 @@ export interface TerminalMultiplexer extends EventEmitter {
   /** Check if the pane in a session is dead (command exited but remain-on-exit keeps it alive) */
   isPaneDead(muxName: string): boolean;
 
+  /**
+   * What the last pane read saw of this session's agent, or `undefined` for
+   * UNKNOWN (Ark0N/Codeman#446). Unlike `isPaneDead()` this costs nothing: it
+   * reads a map the batched watcher fills, so it answers no fresher than that
+   * watcher's interval and the three synchronous `isPaneDead()` callers still
+   * need their own probe. See {@link PaneExit}.
+   */
+  getPaneExit?(muxName: string): PaneExit | undefined;
+
+  /** Forget a session's exit observation, e.g. once its pane has been respawned. */
+  clearPaneExit?(muxName: string): void;
+
+  /** Start polling every pane on the socket for an exited agent. */
+  startPaneExitWatcher?(intervalMs?: number): void;
+
+  /** Stop the pane-exit watcher. */
+  stopPaneExitWatcher?(): void;
+
   /** Respawn a dead pane with a fresh command. Returns the new PID or null on failure. */
   respawnPane(options: RespawnPaneOptions): Promise<number | null>;
 

src/session-activity.ts

@@ -21,6 +21,8 @@
  * in 12/12 windows and the four idle ones in 0/12.
  */
 
+import { stripAnsi } from './utils/regex-patterns.js';
+
 /**
  * A gap longer than this ends a run of continuous output. Claude repaints at
  * least once a second while working, so this leaves generous headroom.
@@ -91,3 +93,68 @@ export function isSustainedActivity(streak: ActivityStreak | null, streakMs: num
 export function isPaneQuiet(lastActivityAt: number, now: number, silenceMs: number = IDLE_SILENCE_MS): boolean {
   return now - lastActivityAt >= silenceMs;
 }
+
+/**
+ * How many rows at the foot of a pane capture may hold the background-work row, for a
+ * CLI that declares no number of its own (`capabilities.workDetect.watchingLines`).
+ *
+ * One, because the tightest window is the right default and Claude Code needs no more:
+ * it draws its chip on the LAST row of the screen. Blank rows are dropped before the
+ * window is taken, so a trailing blank costs nothing, and a CLI that ever prints a row
+ * BELOW its chip loses the badge rather than gaining a hole.
+ *
+ * ⚠️ The size of this window is a trust boundary, not a tidiness measure, and the row
+ * it excludes first is the one that taught us so: Claude's status line sits directly
+ * above the footer, its content comes from a `statusLine` command, and a session running
+ * with permissions bypassed can write that command into `.claude/settings.json` in its
+ * own workspace. A window of two therefore let an agent print `· 1 monitor ·` onto a row
+ * of its own and silence its own idle alert. Every row added here is another row
+ * somebody may be able to write, so widen this only for a CLI whose layout forces it,
+ * and never to a whole-pane search.
+ */
+export const WATCHING_TAIL_LINES = 1;
+
+/** Longest label a badge will carry. A footer chip is a handful of words. */
+export const MAX_WATCHING_LABEL_CHARS = 40;
+
+/**
+ * What a pane says is still running in the background, e.g. `1 monitor` or `2 shells`.
+ *
+ * The CLI writes that chip while a monitor, a backgrounded shell or a cloud session it
+ * started is still going, which is exactly the case where the agent has ended its turn
+ * without wanting anything from the user. `pattern` comes from the CLI's own registry
+ * entry (`capabilities.workDetect.watchingLine`); group 1 is the label when the pattern
+ * declares one, and the whole match stands in when it does not.
+ *
+ * Each candidate row is tested on its own, bottom row first, so a pattern can anchor
+ * itself with `^` or `$` against a single row rather than against a joined block. Blank
+ * rows are dropped before the window is taken, because a CLI that leaves a blank line
+ * between its chrome rows would otherwise spend the window on nothing. The answer is
+ * stripped of ANSI and capped, because it ends up on a badge and in an approval card.
+ *
+ * @param tailLines how many non-blank rows from the bottom to look at, defaulting to
+ *   `WATCHING_TAIL_LINES`; a CLI declares its own when its row is not the last one
+ * @returns the label, or null when the pane shows no background work
+ */
+export function watchingLabel(
+  paneText: string | null | undefined,
+  pattern: RegExp,
+  tailLines: number = WATCHING_TAIL_LINES
+): string | null {
+  if (!paneText) return null;
+  const lines = stripAnsi(paneText)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== '');
+  for (const line of lines.slice(-Math.max(1, tailLines)).reverse()) {
+    // A pattern compiled by compileVersionRegex() never carries the `g` flag, but a
+    // caller reaching in from a test or a config reload might, and a stale lastIndex
+    // would make the same screen match every other call.
+    pattern.lastIndex = 0;
+    const match = pattern.exec(line);
+    if (!match) continue;
+    const label = (match[1] ?? match[0]).trim().slice(0, MAX_WATCHING_LABEL_CHARS);
+    if (label) return label;
+  }
+  return null;
+}

src/session.ts

@@ -60,8 +60,11 @@ import {
   type SessionDocker,
   type SessionNameSource,
   type SessionWriteOptions,
+  type PaneExit,
 } from './types.js';
 import { resolveAndClaimOmpSessionId } from './utils/omp-session-resolver.js';
+import { claudeTranscriptExists } from './utils/claude-transcript.js';
+import { matchesPattern } from './config/cli-registry/patterns.js';
 import { probeDockerCliVersion } from './docker-hosts.js';
 import { probeRemoteCliVersion } from './remote-hosts.js';
 import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
@@ -81,6 +84,8 @@ import {
   trackActivityStreak,
   isSustainedActivity,
   isPaneQuiet,
+  watchingLabel,
+  WATCHING_TAIL_LINES,
   IDLE_RECHECK_MS,
   PANE_PROBE_MIN_INTERVAL_MS,
   PANE_PROBE_RECHECK_MS,
@@ -497,8 +502,35 @@ export class Session extends EventEmitter {
   private _activityStreak: ActivityStreak | null = null; // Unbroken run of PTY repaints (working detection)
   private _lastPaneProbeAt = 0; // Throttle for the tmux screen probe
   private _lastPaneProbeWorking: boolean | null = null; // Its last verdict (null = could not read)
+  /**
+   * Background work the pane's own footer reports, e.g. `1 monitor`; null for none.
+   *
+   * Cached BESIDE `_lastPaneProbeWorking` and refreshed only by a capture that really
+   * happened, so it goes stale exactly as that verdict does. The probe returns its
+   * cached boolean without re-capturing inside `PANE_PROBE_MIN_INTERVAL_MS`, and a
+   * label derived from a capture nobody took would be a guess wearing a fact's clothes.
+   *
+   * ⚠️ It then FREEZES once `_confirmIdle()` concludes: `activityTimeout` is null from
+   * there, and nothing looks at the pane again until it produces output. That is
+   * correct rather than merely tolerable, because work ending repaints the pane either
+   * way — a monitor firing wakes the agent, and codex drops its background-terminal row
+   * on its own. Do not add a timer to keep this fresh; it would spend a `capture-pane`
+   * per idle session per tick to learn nothing.
+   *
+   * A server restart is not a hole in that either, though it looks like one: this field
+   * is live state and starts empty. Reconciliation re-attaches the pane, the attach
+   * repaint carries the composer glyph, and the idle confirmation that arms on it probes
+   * and re-reads the label with no input from anyone — measured 2026-09-23 on a restarted
+   * instance, back within ~20 s for a session whose background terminal was still
+   * running. A session that comes back with no label has no chip on its screen.
+   */
+  private _watching: string | null = null;
   /** Lazily compiled `capabilities.workDetect.workingLine`. See _workingLinePattern(). */
   private _workingLineRe: RegExp | undefined = undefined;
+  /** Lazily compiled `capabilities.workDetect.watchingLine`. See _watchingLinePattern(). */
+  private _watchingLineRe: RegExp | null | undefined = undefined;
+  /** Resolved with the pattern above: how many rows at the foot of the screen to search. */
+  private _watchingWindow = WATCHING_TAIL_LINES;
   private _trustDialogAccepted: boolean = false; // Stops the trust-dialog scan (answered, or given up)
   private _trustDialogAttempts = 0; // Keystrokes sent at the trust dialog
   private _lastTrustDialogScanAt = 0; // Throttle for the trust-dialog screen read
@@ -542,6 +574,20 @@ export class Session extends EventEmitter {
   private _mux: TerminalMultiplexer | null = null;
   private _muxSession: MuxSession | null = null;
   private _useMux: boolean = false;
+  /**
+   * The agent in this session's local tmux pane has exited (Ark0N/Codeman#446).
+   * `null` is the UNKNOWN arm of the tri-state and is what {@link setPaneExit}
+   * stores for every session shape the field does not apply to. See
+   * {@link PaneExit} for the shapes and for why an unknown answer must never be
+   * rendered as "alive".
+   */
+  private _paneExit: PaneExit | null = null;
+  /**
+   * This session was rebuilt from the tmux socket rather than from Codeman's
+   * own records, so its `remote`/`docker` metadata is missing rather than known
+   * to be absent. See {@link MuxSession.discovered}.
+   */
+  private _discoveredMuxSession = false;
   // Flag to prevent new timers after session is stopped
   private _isStopped: boolean = false;
 
@@ -718,6 +764,10 @@ export class Session extends EventEmitter {
       lastSubmitAt?: number;
       /** Restored conversation chain, oldest first (see `claudeSessionChain`). */
       claudeSessionChain?: string[];
+      /** Restored agent-exit observation for this session's pane (see `paneExit`). */
+      paneExit?: PaneExit;
+      /** This session was rebuilt from the tmux socket, so its metadata is a guess. */
+      discoveredMuxSession?: boolean;
       /** Restored wall-clock ms of the pane's last output (recovery only; see `_wireActivityAt`). */
       lastActivityAt?: number;
       /** Remote execution metadata for sessions launched through SSH inside local tmux. */
@@ -870,6 +920,16 @@ export class Session extends EventEmitter {
     this._remote = config.remote;
     this._docker = config.docker;
     this._owner = config.owner;
+    this._discoveredMuxSession = config.discoveredMuxSession === true;
+    // Restored so a record that says the agent exited survives a server restart
+    // rather than being blanked by the first persist after boot. It runs here
+    // because the scoping reads `_remote`, `_docker` and the mux fields, all of
+    // which are set by now. It is a claim about a pane this process has not
+    // looked at yet, so every path that starts or re-attaches a pane drops it
+    // (see `_setupOrAttachMuxSession`) and the pane-exit watcher's own tick
+    // replaces it with a first-hand reading. NOT the stats collector, which a
+    // browser panel arms and disarms — see `startPaneExitWatcher`.
+    this.setPaneExit(config.paneExit);
     // Never self-parent: a session pointing at itself would draw a zero-length
     // lineage arc under its own tab. Only reachable via the recovery path, where
     // both the id and the saved parent come from disk.
@@ -1097,6 +1157,75 @@ export class Session extends EventEmitter {
     return this._muxSession?.muxName ?? null;
   }
 
+  /**
+   * 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
+   * 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`
+   * 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
+   * `mux-sessions.json` was lost arrives looking local, and its next transport
+   * drop would be published as an agent exit. Unproven locality fails closed.
+   */
+  private get paneExitApplies(): boolean {
+    if (this._discoveredMuxSession) return false;
+    return this._useMux && this._muxSession !== null && !this._remote && !this._docker;
+  }
+
+  /** What Codeman last observed of this pane's agent, or undefined for UNKNOWN. */
+  get paneExit(): PaneExit | undefined {
+    return this._paneExit ?? undefined;
+  }
+
+  /**
+   * Forget this pane's exit, on both this record and the mux layer's cache.
+   * Every path that starts or relaunches a command in the pane calls it, and
+   * the mux half also invalidates a pane read already in flight.
+   *
+   * It does not persist or broadcast by itself; the caller owns both. ⚠ That
+   * caller MUST persist, and the pane-exit watcher is not a fallback for it:
+   * the watcher's next tick reads UNKNOWN, finds this field already cleared,
+   * reports no change and therefore writes nothing, so a caller that only
+   * broadcasts leaves `state.json` saying the agent exited for as long as the
+   * session stays quiet. `/interactive` and `/shell` did exactly that until
+   * Ark0N/Codeman#446 review; both now persist on their success path.
+   */
+  private clearPaneExitForNewPane(): void {
+    this.setPaneExit(undefined);
+    if (this._muxSession) this._mux?.clearPaneExit?.(this._muxSession.muxName);
+  }
+
+  /**
+   * 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.
+   *
+   * A session the field does not apply to is forced to UNKNOWN here rather than
+   * at the reporting end, so the rule lives in one place and the mux layer stays
+   * free to report the raw pane reading its own remote-reconnect watcher needs.
+   */
+  setPaneExit(next: PaneExit | undefined): boolean {
+    const resolved = this.paneExitApplies ? (next ?? null) : null;
+    const prev = this._paneExit;
+    if (prev === resolved) return false;
+    if (
+      prev !== null &&
+      resolved !== null &&
+      prev.status === resolved.status &&
+      prev.signal === resolved.signal &&
+      prev.at === resolved.at
+    ) {
+      return false;
+    }
+    this._paneExit = resolved;
+    return true;
+  }
+
   /**
    * True when this session's PTY is a tmux client rather than the program itself.
    * Read by the replay-side alt-screen strip, which must apply the same
@@ -1118,6 +1247,16 @@ export class Session extends EventEmitter {
     return this._isWorking;
   }
 
+  /**
+   * What the pane says is still running in the background, e.g. `1 monitor`, or null when
+   * nothing is. A session with a label here has ended its turn without wanting anything
+   * from the user, so a surface that would otherwise file it under "needs you" can say
+   * what it is waiting for instead.
+   */
+  get watching(): string | null {
+    return this._watching;
+  }
+
   /**
    * Check if the session's process tree has active child processes beyond Claude itself.
    * Detects running bash tools, test suites, builds, servers, etc. that Claude spawned.
@@ -1620,6 +1759,10 @@ export class Session extends EventEmitter {
       // by the constructor: a Codeman restart starts with a fresh breaker so boot
       // recovery can re-attach.
       respawnBlocked: this._respawnBlocked || undefined,
+      // Ark0N/Codeman#446 — the agent in this pane has exited, published here so
+      // it rides the existing `session:updated` broadcast and lands in state.json
+      // through the same persist. `status` and `pid` above stay untouched by it.
+      paneExit: this._paneExit ?? undefined,
       attachmentHistory: this.attachmentHistory.length > 0 ? this.attachmentHistory : undefined,
       lastSubmitAt: this._lastSubmitAt || undefined,
       // Only a chain the CLI's own hooks vouched for is persisted, and only when
@@ -1675,6 +1818,7 @@ export class Session extends EventEmitter {
       totalCost: this._totalCost,
       messageCount: this._messages.length,
       isWorking: this._isWorking,
+      watching: this._watching,
       lastPromptTime: this._lastPromptTime,
       // Buffer statistics for monitoring long-running sessions
       bufferStats: {
@@ -1731,41 +1875,82 @@ export class Session extends EventEmitter {
     respawnPaneOptions: import('./mux-interface.js').RespawnPaneOptions;
     createSessionOptions: import('./mux-interface.js').CreateSessionOptions;
     spawnErrLabel: string;
-  }): Promise<{ isRestored: boolean }> {
+  }): Promise<{ isRestored: boolean; respawnedResumeId?: string; respawnedDeadPane: boolean }> {
     const mux = this._mux!;
 
-    // Verify stale mux session — tmux may have been destroyed (e.g., killed externally)
+    // Verify stale mux session — tmux may have been destroyed (e.g., killed externally).
+    // A session that HAD a mux session relaunches its CLI below just like a failed
+    // respawn does (tmux kill-server, a tmux crash, an external kill-session), so
+    // its transcript collides with the bare `--session-id` the same way. A
+    // genuinely new session starts with `_muxSession` null and never sets this.
+    let muxSessionVanished = false;
     if (this._muxSession && !mux.muxSessionExists(this._muxSession.muxName)) {
       console.log('[Session] Stale mux session detected (tmux gone):', this._muxSession.muxName);
       this._muxSession = null;
+      muxSessionVanished = true;
     }
 
     // Check if session exists but pane is dead (remain-on-exit keeps it alive)
     // Respawn the pane instead of creating a whole new session — preserves tmux scrollback
     let needsNewSession = false;
+    let respawnedDeadPane = false;
+    let respawnedResumeId: string | undefined;
     if (this._muxSession && mux.isPaneDead(this._muxSession.muxName)) {
       console.log('[Session] Dead pane detected, respawning:', this._muxSession.muxName);
       // Confirmed dead — safe to resolve/pin now (see `_pinOmpRespawnId()`).
       // `options.respawnPaneOptions` was built eagerly before this dead-pane
       // check ran, so it still carries the pre-pin ompConfig; rebuild it.
       this._pinOmpRespawnId();
-      const newPid = await mux.respawnPane(this._buildRespawnPaneOptions());
+      const respawnOptions = await this._buildRespawnPaneOptionsWithResumePin();
+      const newPid = await mux.respawnPane(respawnOptions);
       if (!newPid) {
         console.error('[Session] Failed to respawn pane, will create new session');
         needsNewSession = true;
       } else {
+        respawnedDeadPane = true;
+        respawnedResumeId = respawnOptions.resumeSessionId;
         this._pendingEnvUnsets.clear();
         // Wait a moment for the respawned process to fully start
         await new Promise((resolve) => setTimeout(resolve, MUX_STARTUP_DELAY_MS));
       }
     }
 
+    // Whatever the last reading said about the OLD command in this pane is now
+    // history: the branch above either respawned the pane or found it alive, and
+    // the branch below creates a new one. The paths that reach here are boot
+    // recovery and an explicit start, NOT a click on an exited tab — the browser
+    // re-attaches only on a null pid, and the premise of Ark0N/Codeman#446 is
+    // that an exited pane keeps its pid. `restartCli()` clears separately.
+    this.clearPaneExitForNewPane();
+
     // Check if we already have a mux session (restored session)
     const isRestored = this._muxSession !== null && !needsNewSession;
     if (isRestored) {
       console.log('[Session] Attaching to existing mux session:', this._muxSession!.muxName);
     } else {
-      // Create a new mux session
+      // Create a new mux session. When this is the FALLBACK after a failed
+      // respawn, the eagerly-built create options still carry the unpinned
+      // launch seed, so a session whose transcript exists would meet the same
+      // `--session-id ... already in use` refusal the respawn just lost to —
+      // the recovery of last resort failing for the very reason it was needed.
+      // A genuinely new session has no transcript under any of its candidate
+      // ids, so nothing is pinned and its command shape is unchanged.
+      //
+      // `_resumeSessionId` is written alongside, not just the create options:
+      // this branch leaves `isRestored` false, so the block that sets
+      // `_claudeSessionId` below reads that field and would otherwise settle on
+      // `this.id` while the CLI resumes the chain tail. The response viewer,
+      // Read My Mind and the unified-list alias map all read `_claudeSessionId`
+      // until the next first-hand hook, so the two have to name the same
+      // conversation. The vanished-tmux-session branch above relaunches for the
+      // same reason and takes the same pin.
+      if (needsNewSession || muxSessionVanished) {
+        const pinned = (await this._buildRespawnPaneOptionsWithResumePin()).resumeSessionId;
+        if (pinned) {
+          options.createSessionOptions.resumeSessionId = pinned;
+          this._resumeSessionId = pinned;
+        }
+      }
       this._muxSession = await mux.createSession(options.createSessionOptions);
       console.log('[Session] Created mux session:', this._muxSession.muxName);
       // No extra sleep — createSession() already waits for tmux readiness
@@ -1800,13 +1985,14 @@ export class Session extends EventEmitter {
           env: buildMuxAttachEnv(cliExportsTruecolor(this.mode)),
         })
       );
+      this._notePtySpawnGeometry(ptyCols, ptyRows);
     } catch (spawnErr) {
       console.error(`[Session] Failed to spawn PTY for ${options.spawnErrLabel}:`, spawnErr);
       this.emit('error', `Failed to attach to mux session: ${spawnErr}`);
       throw spawnErr;
     }
 
-    return { isRestored };
+    return { isRestored, respawnedResumeId, respawnedDeadPane };
   }
 
   /**
@@ -1844,6 +2030,9 @@ export class Session extends EventEmitter {
       console.error('[Session] reattachRemote: respawnPane failed for', this._muxSession.muxName);
       return false;
     }
+    // No-op for the record (a remote session's field is always UNKNOWN), but the
+    // mux layer's cache is keyed by muxName and this pane now runs a new client.
+    this.clearPaneExitForNewPane();
     console.log('[Session] reattachRemote: reattached remote session', this._muxSession.muxName, 'pid', newPid);
     return true;
   }
@@ -1878,26 +2067,16 @@ export class Session extends EventEmitter {
     }
 
     this._pinOmpRespawnId();
-    const options = this._buildRespawnPaneOptions();
-    // Unlike the dead-pane respawn, this one kills a WORKING pane whose conversation
-    // already has a transcript, and a CLI that launches with `--session-id <id>` refuses
-    // an id that is already in use (claude: `Error: Session ID ... is already in use.`),
-    // which turned an endpoint switch into a dead pane and a lost session. A launch that
-    // declares a `fallback` chain renders `resume || new` once a resume id is set, the
-    // same `--resume <id> || --session-id <id>` shape the docker and remote pane commands
-    // already use, so pin the live conversation id for THIS respawn only. The registry
-    // shape is the gate, not the CLI's name: an entry whose resume id is minted by the
-    // CLI itself (codex/pi/omp/grok) never declares that chain, and its resume field is
-    // read from its own `<Mode>Config` rather than this top-level one anyway.
-    if (!options.resumeSessionId && getCli(this.mode)?.launch.chain === 'fallback') {
-      options.resumeSessionId = this._claudeSessionId ?? this.id;
-    }
-    const newPid = await mux.respawnPane(options);
+    const newPid = await mux.respawnPane(await this._buildRespawnPaneOptionsWithResumePin());
     if (!newPid) {
       console.error('[Session] restartCli: respawnPane failed for', this._muxSession.muxName);
       return false;
     }
     this._pendingEnvUnsets.clear();
+    // A relaunch in the same pane, so any exit observed of the previous command
+    // is history. Without this the caller's persist-and-broadcast writes the old
+    // exit straight back onto a session that is running again.
+    this.clearPaneExitForNewPane();
     console.log('[Session] restartCli: restarted CLI for', this._muxSession.muxName, 'pid', newPid);
     return true;
   }
@@ -1947,6 +2126,112 @@ export class Session extends EventEmitter {
     return this._withCustomModelLaunchModel(options);
   }
 
+  /**
+   * Respawn options for a pane whose command is being REPLACED, with the
+   * conversation pinned so the relaunch resumes rather than collides.
+   *
+   * A CLI that launches with `--session-id <id>` refuses an id that is already
+   * in use (claude: `Error: Session ID ... is already in use.`), and every
+   * session whose agent has been prompted owns a transcript under that id. So
+   * relaunching such a pane with the bare launch line fails, the pane dies
+   * again immediately, and the user's conversation is stranded. A launch that
+   * declares a `fallback` chain renders `resume || new` once a resume id is
+   * set, which is the shape that survives both cases.
+   *
+   * Three candidates are tried in priority order — the conversation chain's
+   * tail, the launch seed, then the session's own id — and the first one a
+   * transcript backs is pinned. Four conditions gate that walk, each protecting
+   * against a way of resuming the WRONG conversation or of making a working
+   * relaunch fail.
+   *
+   * ⚠️ **A remote or docker session is never pinned.** Unlike `restartCli()`,
+   * whose route refuses both, the dead-pane respawn is reached by every session
+   * shape. Their pane commands (`buildRemoteLaunchCommand`,
+   * `claudeDockerPaneCommand`) already render a SELF-HEALING
+   * `--session-id <sid> || --resume <sid>`, and both flip to resume-first the
+   * moment the resume id differs from the session id. The conversation lives on
+   * the far side, so a local id pinned onto it resolves to nothing there, the
+   * resume fails, and the `--session-id` fallback then collides with the
+   * transcript the far side really does hold — both branches fail and the pane
+   * dies. `_pinOmpRespawnId()` refuses remote for the same reason.
+   *
+   * ⚠️ **The candidates come from the conversation CHAIN, never from
+   * `_claudeSessionId`.** That field holds either a first-hand id from the
+   * CLI's own hook payload or a history correlation, which is a guess keyed on
+   * the working directory. `_recordClaudeSessionInChain()` refuses a guess
+   * precisely so it cannot "write a foreign conversation into this pane's
+   * permanent record", and launching from one would do worse than the display
+   * bug that rule exists to prevent: the relaunched CLI would open and WRITE to
+   * a conversation that was never this pane's. The chain's tail is the live
+   * conversation and is hook-vouched, so it leads the walk, ahead of the launch
+   * seed, which is written once at construction and never moves off a `/clear`.
+   *
+   * ⚠️ **Every candidate must be backed by a transcript, the session's own id
+   * included, and a candidate that has none is passed over rather than ending
+   * the walk.** A pin that differs from the session id leaves
+   * `--session-id <this.id>` in the fallback branch, so a resume that finds
+   * nothing collides there and the pane dies exactly as it did before this
+   * pinning existed. Pinning `this.id` renders the self-healing
+   * `--resume <id> || --session-id <id>`, which is correct whether or not a
+   * transcript exists, but a pane that has none pays for the shape twice:
+   * claude prints "No conversation found" into the scrollback of a session that
+   * is brand new, and `wrapWithNice()` prefixes only the FIRST branch of the
+   * rendered `a || b`, so the branch that actually runs loses its priority for
+   * the life of the session. Falling off the end of the walk therefore adds
+   * no pin (the options keep any launch seed they already carried), which is
+   * the right answer: with no transcript anywhere there is nothing for the
+   * bare `--session-id <this.id>` to collide with.
+   *
+   * The create route pre-validates a resume id for the same reason, though it
+   * additionally requires the transcript be substantial — here mere existence
+   * is the question, because a one-line transcript still makes `--session-id`
+   * collide.
+   *
+   * The registry shape is the last gate, not the CLI's name: an entry whose
+   * resume id is minted by the CLI itself (codex/pi/omp/grok) declares no
+   * `fallback` chain and reads its resume field from its own `<Mode>Config`.
+   *
+   * `reattachRemote()` deliberately does NOT call this. It re-runs the remote
+   * session command, which attaches to the durable remote tmux with the agent
+   * still inside it and renders no local `--session-id` to collide.
+   */
+  private async _buildRespawnPaneOptionsWithResumePin(): Promise<import('./mux-interface.js').RespawnPaneOptions> {
+    const options = this._buildRespawnPaneOptions();
+    if (this._remote || this._docker) return options;
+    const entry = getCli(this.mode);
+    if (entry?.launch.chain !== 'fallback') return options;
+
+    const resumeIdPattern = entry.launch.params?.resumeId;
+    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) {
+      // A session Codeman DISCOVERED on the socket rather than created carries a
+      // synthetic `restored-<fragment>` id, which fails claude's `uuid` token
+      // pattern. The renderer would silently drop the resume flag and emit the
+      // unpinned command, so say so here rather than letting the caller believe
+      // the pane was pinned.
+      if (resumeIdPattern?.type === 'token' && !matchesPattern(resumeIdPattern.pattern, candidate)) {
+        console.log(`[Session] Not pinning resume id ${candidate} for relaunch: the CLI cannot accept that id shape`);
+        continue;
+      }
+      if (!(await claudeTranscriptExists(candidate, configDir))) continue;
+      options.resumeSessionId = candidate;
+      return options;
+    }
+    // Nothing on disk to collide with, so the bare `--session-id <this.id>` the
+    // unpinned options already carry is the correct command.
+    return options;
+  }
+
+  /** The session's Claude config dir when it has been relocated (#255), else undefined. */
+  private _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.
+    return this._envOverrides?.CLAUDE_CONFIG_DIR?.trim() || undefined;
+  }
+
   /**
    * 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
@@ -2268,7 +2553,7 @@ export class Session extends EventEmitter {
     // If mux wrapping is enabled, create or attach to a mux session
     if (this._useMux && this._mux) {
       try {
-        const { isRestored } = await this._setupOrAttachMuxSession({
+        const { isRestored, respawnedResumeId, respawnedDeadPane } = await this._setupOrAttachMuxSession({
           // Single source of truth shared with reattachRemote() (COD-108).
           respawnPaneOptions: this._buildRespawnPaneOptions(),
           createSessionOptions: {
@@ -2315,7 +2600,18 @@ export class Session extends EventEmitter {
         // persisted chain's tail is that conversation, reported first-hand by
         // the CLI's own hook, so it outranks every fallback here. A NEW pane has
         // an empty chain and falls through to the resume/alias fallbacks.
-        restoredConversation = isRestored ? this._claudeSessionChain[this._claudeSessionChain.length - 1] : undefined;
+        //
+        // A dead-pane respawn is NOT that case for a CLI whose relaunch the resume
+        // pin walk governs (`launch.chain === 'fallback'`): the CLI did stop, and
+        // the walk may have passed over a chain tail with no transcript behind it,
+        // so the conversation is whatever the respawn actually resumed. Undefined
+        // there means the pane launched unpinned, which the fallbacks below name.
+        const pinGovernsRespawn = respawnedDeadPane && getCli(this.mode)?.launch.chain === 'fallback';
+        restoredConversation = pinGovernsRespawn
+          ? respawnedResumeId
+          : isRestored
+            ? this._claudeSessionChain[this._claudeSessionChain.length - 1]
+            : undefined;
         this._claudeSessionId =
           restoredConversation ||
           this._resumeSessionId ||
@@ -2416,6 +2712,7 @@ export class Session extends EventEmitter {
             env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
           })
         );
+        this._notePtySpawnGeometry(120, 40);
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn Claude PTY:', spawnErr);
         this._status = 'stopped';
@@ -2709,9 +3006,63 @@ export class Session extends EventEmitter {
     this._lastPaneProbeAt = now;
     const text = this._mux.capturePaneText?.(this._muxSession.muxName) ?? null;
     this._lastPaneProbeWorking = text === null ? null : this._workingLinePattern().test(text);
+    this._readWatching(text);
     return this._lastPaneProbeWorking;
   }
 
+  /**
+   * Read the background-work chip off the same capture the working probe just took.
+   *
+   * The two questions are different. A turn that is running is work the user is waiting
+   * for; a monitor, a backgrounded shell or a cloud session the agent started is work
+   * the AGENT is waiting for, and it is the reason a pane can sit at its composer with
+   * nothing to say and still not want anything from the user. `_confirmIdle` takes this
+   * capture at exactly the moment the turn ends, which is the moment the answer starts
+   * mattering.
+   *
+   * A capture that could not be read CLEARS the label rather than keeping the last one.
+   * The two wrong answers are not symmetric: a stale label opens the next idle prompt
+   * already acknowledged, so a failed capture would silence a real alert, while a dropped
+   * label only costs a card and an alert that the next readable capture takes back.
+   * Degrading toward the alert is the rule the whole signal is built on.
+   */
+  private _readWatching(paneText: string | null): void {
+    const pattern = this._watchingLinePattern();
+    if (!pattern) return;
+    // `null` is "the screen could not be read". That is no evidence either way, so the
+    // label falls to null (and the change is announced below like any other).
+    const label = paneText === null ? null : watchingLabel(paneText, pattern, this._watchingWindow);
+    if (label === this._watching) return;
+    this._watching = label;
+    // ⚠️ This CHANGES while the session's status does not, so it needs an event of its
+    // own. The label is usually set on the idle transition, which broadcasts anyway, but
+    // it CLEARS when the work ends — and for a CLI whose background work ends without
+    // taking a turn (measured on codex: a background terminal finishing repaints the row
+    // away and nothing else happens) the session is idle before and after. Without this,
+    // the server knew the badge was gone and every open page went on drawing it until
+    // some unrelated event arrived.
+    this.emit('watchingChanged');
+  }
+
+  /**
+   * The regex matching this CLI's background-work chip, or null for a CLI whose registry
+   * entry declares none. Compiled once per session, like the working-line pattern, and
+   * null rather than a fallback: no other CLI has been measured drawing such a chip, and
+   * guessing one would badge sessions on the strength of an unread screen.
+   */
+  private _watchingLinePattern(): RegExp | null {
+    if (this._watchingLineRe === undefined) {
+      // The pattern and the window it runs over are one decision, so they are resolved
+      // together: how far up the screen a CLI's row can sit is as much a property of its
+      // layout as the row itself. Claude writes on the last row and keeps the default,
+      // Codex pins one above its composer and declares more.
+      const detect = getCli(this.mode)?.capabilities.workDetect;
+      this._watchingLineRe = detect?.watchingLine ? compileVersionRegex(detect.watchingLine) : null;
+      this._watchingWindow = detect?.watchingLines ?? WATCHING_TAIL_LINES;
+    }
+    return this._watchingLineRe;
+  }
+
   /**
    * The regex matching this CLI's "a turn is running" status line.
    *
@@ -2984,6 +3335,7 @@ export class Session extends EventEmitter {
             env: buildShellEnv(this.id),
           })
         );
+        this._notePtySpawnGeometry(120, 40);
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn shell PTY:', spawnErr);
         this._status = 'stopped';
@@ -3093,6 +3445,7 @@ export class Session extends EventEmitter {
               env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
             })
           );
+          this._notePtySpawnGeometry(120, 40);
         } catch (spawnErr) {
           console.error('[Session] Failed to spawn Claude PTY for runPrompt:', spawnErr);
           this.emit(
@@ -3779,6 +4132,40 @@ export class Session extends EventEmitter {
   private _ptyCols = 120;
   private _ptyRows = 40;
 
+  /**
+   * Record the geometry a PTY was just spawned at. A reattached pane keeps the
+   * tmux window's size, not the constructor's 120x40, and without this
+   * `ptyGeometry` reported the old numbers for a live pane and the dedupe in
+   * `resize()` skipped a real resize that happened to match them.
+   */
+  private _notePtySpawnGeometry(cols: number, rows: number): void {
+    this._ptyCols = cols;
+    this._ptyRows = rows;
+  }
+
+  /**
+   * The geometry the CLI is actually drawing for, or null when nothing is
+   * drawing.
+   *
+   * Exposed because `resize()` can decline a request outright (arbitration
+   * below) and the asking client has no other way to find out: a browser
+   * terminal that keeps a shape the PTY refused renders garbled output rather
+   * than wrong-sized output, because Claude Code's repaints are computed from
+   * the width it was told (issue #464). Both transports report this back.
+   *
+   * ⚠️ NULL WITHOUT A PANE, never the field values. The fields are seeded at
+   * spawn (`_notePtySpawnGeometry`) and moved by `resize()`, but a session with
+   * a dead pane (or one created through the API and never started) still
+   * holds the constructor defaults of 120x40, or the size of a pane that is
+   * gone. Reporting those made a client adopt a size no process had ever
+   * been told, and on anything narrower than 120 columns it claimed another
+   * device owned the pane when none existed. `reconcilePtyGeometry` treats a
+   * report with no finite numbers as no evidence, which is the truth here.
+   */
+  get ptyGeometry(): { cols: number; rows: number } | null {
+    return this.ptyProcess ? { cols: this._ptyCols, rows: this._ptyRows } : null;
+  }
+
   /**
    * Live WebSocket connections that have announced a desktop viewport for this
    * session. While at least one is registered, small-viewport (mobile/tablet)
@@ -3864,6 +4251,10 @@ export class Session extends EventEmitter {
     }
     if (isSmallViewport && this._desktopSizeClaims.size > 0) {
       if (Date.now() - this._lastDesktopActivityAt < Session.DESKTOP_CLAIM_IDLE_MS) {
+        // Declined. The caller is told nothing here on purpose — the decision
+        // belongs to the session, not the socket — but the caller MUST report
+        // `ptyGeometry` back afterwards so the asking client can adopt
+        // the shape it did not get. Both transports do; see issue #464.
         return;
       }
       this._mobileSizeOverride = true;
@@ -3963,6 +4354,9 @@ export class Session extends EventEmitter {
   async stop(killMux: boolean = true): Promise<void> {
     // Set stopped flag first to prevent new timers from being created
     this._isStopped = true;
+    // A pane that is gone is watching nothing. Nothing probes a stopped session, so
+    // without this the last chip it drew would ride along on its row forever.
+    this._watching = null;
 
     this._clearAllTimers();
 

src/tmux-manager.ts

@@ -58,6 +58,7 @@ import {
   type SessionRemote,
   type SessionDocker,
   type DockerCommandMode,
+  type PaneExit,
 } from './types.js';
 import { getCli } from './config/cli-registry/registry.js';
 import { missingCliMessage, resolveCliBinDir } from './utils/cli-resolver.js';
@@ -152,6 +153,16 @@ const GRACEFUL_SHUTDOWN_WAIT_MS = 100;
 /** Default stats collection interval (2 seconds) */
 const DEFAULT_STATS_INTERVAL_MS = 2000;
 
+/**
+ * How often the pane-exit watcher re-reads every pane on the socket. The
+ * watcher owns this cadence: it does NOT ride `startStatsCollection()`, whose
+ * lifetime a browser panel controls (see {@link TmuxManager.startPaneExitWatcher}).
+ * Matched to the stats cadence above because both cost one batched tmux read.
+ * ⚠ It does NOT bound a read: EXEC_TIMEOUT_MS is 5000 ms, so a slow read can
+ * outlive two ticks, which is exactly why `paneExitReadInFlight` exists.
+ */
+const DEFAULT_PANE_EXIT_INTERVAL_MS = 2000;
+
 /** Default remote-reconnect watcher poll interval (5 seconds) — COD-108 */
 const DEFAULT_REMOTE_RECONNECT_INTERVAL_MS = 5000;
 
@@ -219,8 +230,18 @@ const DEFAULT_CODEMAN_TMUX_SOCKET = DEFAULT_TMUX_SOCKET;
  */
 const PANE_LIST_SEP = '|';
 
-/** Format string for `tmux list-panes -F`. Keep in sync with {@link parsePaneList}. */
-const PANE_LIST_FORMAT = `#{session_name}${PANE_LIST_SEP}#{pane_pid}`;
+/**
+ * Format string for `tmux list-panes -F`. Keep in sync with {@link parsePaneRows}.
+ *
+ * The three `pane_dead*` fields carry the agent-exit signal of Ark0N/Codeman#446.
+ * Appending them is backward compatible in both directions. A tmux that does not
+ * know a variable substitutes the empty string rather than failing, which is how
+ * tmux 3.2a answers `#{pane_dead_signal}` (added in 3.4), and the parser reads a
+ * short row as "pid known, deadness unknown" rather than discarding it.
+ */
+const PANE_LIST_FORMAT =
+  `#{session_name}${PANE_LIST_SEP}#{pane_pid}` +
+  `${PANE_LIST_SEP}#{pane_dead}${PANE_LIST_SEP}#{pane_dead_status}${PANE_LIST_SEP}#{pane_dead_signal}`;
 
 /**
  * 构建 pane 启动前的 nofile 修复命令。
@@ -235,26 +256,141 @@ export function buildNofileLimitCommand(targetLimit = CLAUDE_CODE_NOFILE_LIMIT):
   return `ulimit -Sn ${safeLimit} 2>/dev/null || ulimit -n ${safeLimit} 2>/dev/null || true`;
 }
 
+/** One pane of one tmux session, as {@link parsePaneRows} reads it off the wire. */
+export interface PaneRow {
+  /** tmux session this pane belongs to. Repeats once per pane of a split session. */
+  sessionName: string;
+  /** `#{pane_pid}` — the process tmux started in the pane. */
+  pid: number;
+  /** `#{pane_dead}` — true for 1, false for 0, undefined when tmux said nothing. */
+  dead?: boolean;
+  /** `#{pane_dead_status}` — the exit code, absent when tmux reported none. */
+  exitStatus?: number;
+  /** `#{pane_dead_signal}` — the killing signal, absent before tmux 3.4 and when unsignalled. */
+  exitSignal?: number;
+}
+
 /**
- * Parse the output of `tmux list-panes -a -F '#{session_name}|#{pane_pid}'`
- * into a Map of session-name → pane pid. Exported for unit testing.
+ * One pane-exit reading, with the pane pid that produced it.
+ *
+ * The pid never leaves this module. It is what distinguishes "the same dead
+ * pane, seen again" from "a second command in the same pane that also exited
+ * with the same status", so the `at` stamp can hold across the first and must
+ * not across the second. {@link PaneExit} itself stays free of it: the pid on
+ * the session record is the attach client's, and a second pid there would
+ * invite exactly the confusion Ark0N/Codeman#446 is about.
+ */
+export interface PaneExitObservation {
+  /** `#{pane_pid}` of the pane this reading came from. */
+  panePid: number;
+  /** What to publish on the session record. */
+  exit: PaneExit;
+}
+
+/** Read one optional numeric field; a blank or non-numeric value is "not reported". */
+function paneField(fields: string[], index: number): number | undefined {
+  const raw = fields[index];
+  if (raw === undefined || raw === '') return undefined;
+  const value = parseInt(raw, 10);
+  return Number.isNaN(value) ? undefined : value;
+}
+
+/**
+ * Parse the output of `tmux list-panes -a -F` under {@link PANE_LIST_FORMAT}
+ * into one row per pane, in tmux's own order. Exported for unit testing.
  *
  * - Skips empty lines and lines without the separator.
  * - Skips entries with a non-numeric pid or empty name.
+ * - Leaves every field after the pid undefined when it is blank or absent, so a
+ *   row from an older tmux still yields its pid.
  */
-export function parsePaneList(output: string): Map<string, number> {
-  const result = new Map<string, number>();
+export function parsePaneRows(output: string): PaneRow[] {
+  const rows: PaneRow[] = [];
   for (const line of output.split('\n')) {
     if (!line) continue;
-    const sep = line.indexOf(PANE_LIST_SEP);
-    if (sep === -1) continue;
-    const name = line.slice(0, sep);
-    const pid = parseInt(line.slice(sep + 1), 10);
-    if (name && !Number.isNaN(pid)) {
-      result.set(name, pid);
-    }
+    if (!line.includes(PANE_LIST_SEP)) continue;
+    const fields = line.split(PANE_LIST_SEP);
+    const sessionName = fields[0];
+    const pid = parseInt(fields[1] ?? '', 10);
+    if (!sessionName || Number.isNaN(pid)) continue;
+    const deadFlag = fields[2];
+    rows.push({
+      sessionName,
+      pid,
+      dead: deadFlag === '1' ? true : deadFlag === '0' ? false : undefined,
+      exitStatus: paneField(fields, 3),
+      exitSignal: paneField(fields, 4),
+    });
   }
-  return result;
+  return rows;
+}
+
+/**
+ * Decide, from every pane tmux listed, which tmux sessions have an exited agent.
+ * Exported for unit testing. Returns one entry per session with a known answer;
+ * a session absent from the map is UNKNOWN, which must never render as alive.
+ *
+ * Two rules make a positive answer trustworthy:
+ *
+ * A session answers only when tmux listed EXACTLY ONE pane for it. Codeman
+ * creates one pane per session and `isPaneDead()` reads one pane, so a session
+ * the user has split by hand has no single "the agent" to report on, and
+ * guessing which of its panes speaks for the session could report a live
+ * session as exited.
+ *
+ * A pane answers only when `#{pane_dead}` said 1 or 0. An empty field is a tmux
+ * that did not answer, not a live pane.
+ *
+ * `status` and `signal` stay absent when tmux did not report them. Measured on
+ * tmux 3.2a, a SIGKILLed pane reports neither, so folding an absent status into
+ * 0 would turn an unexplained death into a clean exit.
+ */
+export function derivePaneExits(rows: PaneRow[], now: number): Map<string, PaneExitObservation> {
+  const panesPerSession = new Map<string, number>();
+  for (const row of rows) {
+    panesPerSession.set(row.sessionName, (panesPerSession.get(row.sessionName) ?? 0) + 1);
+  }
+  const exits = new Map<string, PaneExitObservation>();
+  for (const row of rows) {
+    if (panesPerSession.get(row.sessionName) !== 1) continue;
+    if (row.dead !== true) continue;
+    exits.set(row.sessionName, {
+      panePid: row.pid,
+      exit: {
+        ...(row.exitStatus !== undefined ? { status: row.exitStatus } : {}),
+        ...(row.exitSignal !== undefined ? { signal: row.exitSignal } : {}),
+        at: now,
+      },
+    });
+  }
+  return exits;
+}
+
+/**
+ * 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
+ * learn, and `refreshPaneExits()` skips its tmux read rather than paying for
+ * the answer.
+ *
+ * ⚠ This gates the READ, never the watcher. The watcher is always-on by
+ * design (see {@link TmuxManager.startPaneExitWatcher}), so it keeps ticking
+ * with nothing to observe and picks the read straight back up as soon as one
+ * local session exists.
+ */
+export function hasObservablePaneSession(sessions: Iterable<MuxSession>): boolean {
+  for (const session of sessions) {
+    if (session.remote) continue;
+    if (session.docker) continue;
+    if (session.discovered === true) continue;
+    return true;
+  }
+  return false;
 }
 
 /**
@@ -1527,6 +1663,30 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   private mouseSyncInterval: NodeJS.Timeout | null = null;
   /** Track last-known pane count per session to avoid unnecessary tmux set-option calls */
   private lastPaneCount: Map<string, number> = new Map();
+  /**
+   * muxName → the exited agent the pane-exit watcher last observed
+   * (Ark0N/Codeman#446). Absence is the UNKNOWN arm of the tri-state, so an
+   * entry goes the moment tmux stops reporting the pane dead, and the map is
+   * empty until the first read runs. The manager reports what tmux says and
+   * nothing more: the scoping that hides this for remote and docker sessions
+   * lives on `Session`, because the remote-reconnect watcher above needs the
+   * raw pane reading.
+   */
+  private paneExits: Map<string, PaneExitObservation> = new Map();
+  /** The pane-exit watcher's own interval. Runs whether or not stats are on. */
+  private paneExitInterval: NodeJS.Timeout | null = null;
+  /**
+   * True while a pane read is in flight. `EXEC_TIMEOUT_MS` is 5000 ms against a
+   * poll interval of 2000 ms, so without this a slow read overlaps the next two
+   * and the older one can resolve last and win.
+   */
+  private paneExitReadInFlight = false;
+  /**
+   * Bumped by every deliberate {@link clearPaneExit}. A read that started before
+   * a clear carries the older generation and is discarded rather than writing
+   * the death back over the pane that has just replaced it.
+   */
+  private paneExitGeneration = 0;
 
   // ── COD-108 remote-reconnect watcher state ────────────────────────────────
   /** Periodic watcher that re-establishes dropped remote sessions. */
@@ -2297,6 +2457,11 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       );
       // Wait for the respawned process to start
       await new Promise((resolve) => setTimeout(resolve, TMUX_CREATION_WAIT_MS));
+      // The pane now runs a fresh command, so whatever the last read observed of
+      // the old one is history. Clearing it here rather than waiting for the next
+      // poll also invalidates any read already in flight, which would otherwise
+      // write the old death back over the pane that just replaced it.
+      this.clearPaneExit(muxName);
       const pid = this.getPanePid(muxName);
       if (pid) session.pid = pid;
       return pid;
@@ -2508,6 +2673,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         }
       }
       this.lastPaneCount.delete(session.muxName);
+      this.clearPaneExit(session.muxName);
       this.sessions.delete(sessionId);
       this.clearRemoteReconnectState(sessionId);
       this.saveSessions();
@@ -2618,6 +2784,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }
 
     this.lastPaneCount.delete(session.muxName);
+    this.clearPaneExit(session.muxName);
     this.sessions.delete(sessionId);
     this.clearRemoteReconnectState(sessionId);
     this.saveSessions();
@@ -2671,7 +2838,14 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         encoding: 'utf-8',
         timeout: EXEC_TIMEOUT_MS,
       }).trim();
-      active = parsePaneList(output);
+      const rows = parsePaneRows(output);
+      active = new Map(rows.map((row) => [row.sessionName, row.pid]));
+      // The same read answers both questions, so recovery starts with a pane-exit
+      // reading rather than waiting for the first stats tick — which may never
+      // come, since the collector only starts when boot found a live session.
+      if (rows.length > 0) {
+        this.applyPaneExits(derivePaneExits(rows, Date.now()));
+      }
     } catch (err) {
       console.error('[TmuxManager] Failed to list tmux panes:', err);
       active = new Map();
@@ -2686,6 +2860,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       } else {
         dead.push(sessionId);
         this.sessions.delete(sessionId);
+        this.clearPaneExit(session.muxName);
         this.clearRemoteReconnectState(sessionId);
         this.emit('sessionDied', { sessionId });
       }
@@ -2722,6 +2897,13 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         mode: 'claude',
         attached: false,
         name: `Restored: ${sessionName}`,
+        // Every field above except the name and the pid is a guess: this record
+        // was rebuilt from the socket because Codeman's own bookkeeping did not
+        // have it. The synthetic id also cannot find the session's state.json
+        // entry, so a remote or docker session rediscovered this way arrives
+        // looking local. Consumers that would be wrong about such a session
+        // read this flag and fail closed — see `Session.paneExitApplies`.
+        discovered: true,
       };
       this.sessions.set(sessionId, session);
       knownMuxNames.add(sessionName);
@@ -2882,6 +3064,172 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     }));
   }
 
+  /**
+   * 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
+   * that is running, a tmux session that no longer exists, a probe that failed,
+   * and every poll that has not run yet. See {@link PaneExit}.
+   */
+  getPaneExit(muxName: string): PaneExit | undefined {
+    return this.paneExits.get(muxName)?.exit;
+  }
+
+  /**
+   * Re-read every pane on the socket and refresh {@link paneExits}. ONE batched
+   * `tmux list-panes -a` answers for every session at once, which is why this
+   * polls rather than probing per session.
+   *
+   * A failed or empty probe leaves the previous answers ALONE rather than
+   * clearing them, because the two cannot be told apart: the command ends in
+   * `|| true`, so a tmux that errored and a socket with genuinely no panes both
+   * arrive as empty output. Treating that as "tmux did not answer" is the
+   * conservative reading — clearing on it would turn a transient failure into a
+   * silent retraction of a death Codeman had already observed, and the cost of
+   * being wrong the other way is one stale entry for a socket that no longer
+   * has the pane. A NON-empty read is different: `list-panes -a` lists
+   * every pane on the socket, so it is authoritative and {@link applyPaneExits}
+   * prunes against it.
+   *
+   * Two guards keep a slow read from undoing a fast one. A read already in
+   * flight suppresses the next poll, and a read that started before a
+   * {@link clearPaneExit} is discarded when it lands.
+   *
+   * A third guard skips the read entirely while no session on this manager
+   * could produce an answer ({@link hasObservablePaneSession}). Skipping
+   * retracts nothing, for the same reason a failed read does not: the map
+   * still holds what the last real read saw, and every path that puts a new
+   * command in a pane calls {@link clearPaneExit} itself.
+   */
+  async refreshPaneExits(now: number = Date.now()): Promise<void> {
+    // Nothing on this socket could answer, so do not read tmux to find that
+    // out. See `hasObservablePaneSession`: the watcher above still ticks.
+    if (!hasObservablePaneSession(this.sessions.values())) return;
+    if (this.paneExitReadInFlight) return;
+
+    const generation = this.paneExitGeneration;
+    this.paneExitReadInFlight = true;
+    let rows: PaneRow[];
+    try {
+      rows = await this.readPaneRows();
+    } finally {
+      this.paneExitReadInFlight = false;
+    }
+    if (rows.length === 0) return;
+    // 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.
+    if (generation !== this.paneExitGeneration) return;
+
+    this.applyPaneExits(derivePaneExits(rows, now));
+  }
+
+  /**
+   * Read every pane on the socket. The ONLY part of the pane-exit watcher that
+   * touches tmux, which is what lets a test subclass drive the guards in
+   * {@link refreshPaneExits} — the in-flight suppression, the generation
+   * check, the empty-read retraction rule and the read gate — against rows it
+   * chooses. Split out for the reason `runRemoteReconnectTick` is: a guard no
+   * test can reach is a guard that can be deleted without anything failing.
+   *
+   * A failed read answers with NO rows, which the caller treats as "tmux did
+   * not answer" and which therefore retracts nothing.
+   */
+  protected async readPaneRows(): Promise<PaneRow[]> {
+    // The test-mode gate lives HERE rather than at the top of the tick, so that
+    // what tests cannot do is spawn a process, not exercise the bookkeeping.
+    if (IS_TEST_MODE) return [];
+    try {
+      // execAsync, not execSync: this runs on a 2000 ms timer, and a synchronous
+      // exec freezes the port while the process stays alive (see the
+      // event-loop-monitor note in CLAUDE.md). The three `isPaneDead()` callers
+      // stay synchronous because each is answering one request right then.
+      const { stdout } = await execAsync(`${this.tmux()} list-panes -a -F '${PANE_LIST_FORMAT}' 2>/dev/null || true`, {
+        encoding: 'utf-8',
+        timeout: EXEC_TIMEOUT_MS,
+      });
+      return parsePaneRows(stdout.trim());
+    } catch (err) {
+      console.error('[TmuxManager] Failed to read pane exit state:', err);
+      return [];
+    }
+  }
+
+  /**
+   * Fold one authoritative observation into {@link paneExits}. Split out from
+   * the tmux call so the merge rules are unit-testable.
+   *
+   * `observed` comes from a read of EVERY pane on the socket, so a session
+   * missing from it has no exit to report and its entry goes. That is what
+   * keeps the map from growing without bound as tmux sessions come and go
+   * outside `killSession()`. Only the caller may decide a read is authoritative:
+   * a failed or empty one never reaches here.
+   *
+   * An entry keeps the `at` of the FIRST read that saw that exit, so the stamp
+   * says when the agent was found gone rather than when the last poll ran. A
+   * changed status, a changed signal, or a different pane pid all start a new
+   * observation — the pid is what catches a second command in the same pane
+   * that happened to exit the same way.
+   */
+  applyPaneExits(observed: Map<string, PaneExitObservation>): void {
+    for (const muxName of [...this.paneExits.keys()]) {
+      if (!observed.has(muxName)) this.paneExits.delete(muxName);
+    }
+    for (const [muxName, next] of observed) {
+      const prev = this.paneExits.get(muxName);
+      const sameExit =
+        prev !== undefined &&
+        prev.panePid === next.panePid &&
+        prev.exit.status === next.exit.status &&
+        prev.exit.signal === next.exit.signal;
+      this.paneExits.set(muxName, sameExit ? prev : next);
+    }
+  }
+
+  /**
+   * Forget a session's exit observation, e.g. once its pane has been respawned.
+   * Also invalidates any read already in flight, so the answer this retracts
+   * cannot be written back a moment later.
+   */
+  clearPaneExit(muxName: string): void {
+    this.paneExits.delete(muxName);
+    this.paneExitGeneration++;
+  }
+
+  /**
+   * Poll for exited agents, on the manager's own interval.
+   *
+   * Deliberately NOT part of `startStatsCollection()`. That collector is armed
+   * when the browser opens the Monitor panel and DISARMED when it closes it
+   * (`panels-ui.js`), and it is skipped at boot entirely when no session was
+   * recovered — so riding it would leave a session created on a freshly booted
+   * server reporting nothing at all, and would let one browser turn exit
+   * detection off for every other. Started unconditionally, like the mouse-mode
+   * sync and the remote-reconnect watcher below.
+   *
+   * The `paneExitsUpdated` event is internal to the server; nothing here adds an
+   * SSE event, and the field reaches the browser on `session:updated`.
+   */
+  startPaneExitWatcher(intervalMs: number = DEFAULT_PANE_EXIT_INTERVAL_MS): void {
+    if (this.paneExitInterval) {
+      clearInterval(this.paneExitInterval);
+    }
+    this.paneExitInterval = setInterval(() => {
+      // No IS_TEST_MODE guard: `readPaneRows()` is the only thing that would
+      // spawn a process and it refuses under test, so a test can drive this
+      // whole loop with fake timers instead of being locked out of it.
+      void this.refreshPaneExits()
+        .then(() => this.emit('paneExitsUpdated'))
+        .catch((err) => console.error('[TmuxManager] Pane exit watcher error:', err));
+    }, intervalMs);
+  }
+
+  stopPaneExitWatcher(): void {
+    if (this.paneExitInterval) {
+      clearInterval(this.paneExitInterval);
+      this.paneExitInterval = null;
+    }
+  }
+
   startStatsCollection(intervalMs: number = DEFAULT_STATS_INTERVAL_MS): void {
     if (this.statsInterval) {
       clearInterval(this.statsInterval);
@@ -3101,6 +3449,8 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
 
   destroy(): void {
     this.stopStatsCollection();
+    this.stopPaneExitWatcher();
+    this.paneExits.clear();
     this.stopMouseModeSync();
     this.stopRemoteReconnectWatcher();
     this.reconnectState.clear();

src/tui/tui-approvals.ts

@@ -28,8 +28,11 @@
 import type { ApprovalItem, ApprovalOption } from '../web/approval-inbox.js';
 import type { TuiApprovalAnswer } from './tui-client.js';
 
-/** Card severity, in the same red/yellow vocabulary the web inbox uses. */
-export type TuiApprovalTone = 'err' | 'warn';
+/**
+ * Card severity, in the same red/yellow vocabulary the web inbox uses, plus the quiet
+ * third case: an item that opened acknowledged asks for nothing and reads grey.
+ */
+export type TuiApprovalTone = 'err' | 'warn' | 'info';
 
 export interface TuiApprovalCard {
   tone: TuiApprovalTone;
@@ -50,8 +53,14 @@ function clean(text: string | undefined): string {
   return (text ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_CARD_TEXT);
 }
 
+/**
+ * How loud the card is. An idle prompt the inbox opened ALREADY acknowledged is not
+ * asking for anything — the session is watching work it started itself — so it drops to
+ * `info` and out of the warning vocabulary the other two share with the web inbox.
+ */
 export function approvalTone(item: ApprovalItem): TuiApprovalTone {
-  return item.kind === 'idle' ? 'warn' : 'err';
+  if (item.kind !== 'idle') return 'err';
+  return item.acknowledgedReason ? 'info' : 'warn';
 }
 
 /**
@@ -65,9 +74,13 @@ export function approvalCard(item: ApprovalItem): TuiApprovalCard {
   const summary = clean(item.toolSummary) || clean(item.toolName);
 
   if (item.kind === 'idle') {
+    // Say what it is waiting for rather than asking for a reply, in the same words the
+    // web drawer uses for the same item. The prompt is still answerable, so the hint
+    // stays either way.
+    const quiet = clean(item.acknowledgedReason);
     return {
-      tone: 'warn',
-      title: message || 'waiting for your reply',
+      tone: approvalTone(item),
+      title: quiet ? `quiet, ${quiet}` : message || 'waiting for your reply',
       detail: [],
       options: [],
       hint: 'p to reply',

src/tui/tui-model.ts

@@ -74,13 +74,25 @@ export function isLiveRow(session: TuiSessionRow): boolean {
  * outranks a stale `busy` status because the hook is the newer signal. An
  * errored session has no state of its own here and joins the waiting tier,
  * since it is equally something only a human can clear.
+ *
+ * ⚠️ An ACKNOWLEDGED item no longer decides the row. `acknowledgedAt` means the
+ * alert this prompt armed has been spent, either because somebody opened the
+ * session on another device or because the inbox opened the item that way for a
+ * session watching its own background work. The item itself stays pending and
+ * answerable, so the row keeps carrying it and the approval card still renders;
+ * it simply stops dragging the session into NEEDS YOU. The web has honoured
+ * that since acknowledgement existed (`approvals-ui.js` clears the pending hook
+ * that `_mobileOverviewState` reads), and this gate is where the TUI had been
+ * reading past it: acknowledging on a phone cleared the alert everywhere except
+ * here. Only `idle` can be acknowledged, so a permission or question dialog is
+ * unaffected by construction, and both are checked ahead of the flag anyway.
  */
 export function classifySession(session: TuiSessionRow, approval?: ApprovalItem): TuiSessionState {
   if (!isLiveRow(session)) return 'recent';
   if (approval) {
     if (approval.kind === 'permission') return 'blocked-permission';
     if (approval.kind === 'question') return 'blocked-question';
-    return 'waiting';
+    if (!approval.acknowledgedAt) return 'waiting';
   }
   if (session.status === 'error') return 'waiting';
   if (session.isWorking === true || session.status === 'busy') return 'working';
@@ -96,7 +108,11 @@ export function classifySession(session: TuiSessionRow, approval?: ApprovalItem)
  * turn's own start is the pane's last Enter.
  */
 export function stateSince(state: TuiSessionState, session: TuiSessionRow, approval?: ApprovalItem): number {
-  if (approval) return approval.createdAt;
+  // The prompt's own age measures the state only while the prompt is what put the
+  // row in that state. An acknowledged item still rides along on a row that is
+  // plainly idle or working, and dating such a row from it would report how long
+  // ago the prompt arrived as though it were how long the session has been quiet.
+  if (approval && STATE_GROUP[state] === 'needs-you') return approval.createdAt;
   if (state === 'working') return session.lastSubmitAt ?? session.createdAt ?? 0;
   return session.lastActivityAt ?? session.createdAt ?? 0;
 }

src/tui/tui-render.ts

@@ -462,7 +462,8 @@ export function computeListWindow(
  * The pending dialog, drawn above the tail: the question, the parsed options
  * with their digits, and the keys that answer them. Red for a permission or
  * question prompt, yellow for an idle one, the same severity vocabulary the web
- * inbox uses.
+ * inbox uses. An idle prompt that opened acknowledged carries neither: it reads
+ * grey with the idle glyph, because nothing about it wants the reader.
  */
 export function renderApprovalCard(
   item: ApprovalItem,
@@ -472,8 +473,8 @@ export function renderApprovalCard(
 ): string[] {
   const paint = painterFor(opts.color);
   const card = approvalCard(item);
-  const color = card.tone === 'err' ? SGR.red : SGR.yellow;
-  const glyph = card.tone === 'err' ? glyphs.blockedPermission : glyphs.waiting;
+  const color = card.tone === 'err' ? SGR.red : card.tone === 'warn' ? SGR.yellow : SGR.gray;
+  const glyph = card.tone === 'err' ? glyphs.blockedPermission : card.tone === 'warn' ? glyphs.waiting : glyphs.idle;
   const lines: string[] = [];
   const push = (text: string, style: string): void => {
     lines.push(padDisplay(paint(clipStyledLine(text, width), style), width));
@@ -571,10 +572,19 @@ function previewBody(
 // Chrome
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Sessions with a prompt waiting on a human, which is what the badge counts. */
+/**
+ * Sessions with a prompt waiting on a human, which is what the badge counts.
+ *
+ * An ACKNOWLEDGED item is not one of them. Its alert has been spent, either by somebody
+ * opening the session elsewhere or because the inbox opened it that way for a session
+ * watching its own background work, and the row has already left NEEDS YOU by the same
+ * flag (`classifySession`). Counting it here would put a number in the header for a
+ * group the reader can see is empty.
+ */
 export function pendingApprovalCount(model: TuiRenderModel): number {
   let count = 0;
-  for (const group of model.groups()) for (const row of group.rows) if (row.approval) count++;
+  for (const group of model.groups())
+    for (const row of group.rows) if (row.approval && !row.approval.acknowledgedAt) count++;
   return count;
 }
 

src/types/session.ts

@@ -625,6 +625,54 @@ export interface CustomModelBookkeeping extends CustomModelSelection {
   launchModel?: string;
 }
 
+/**
+ * The agent inside a LOCAL tmux pane has exited, and the pane survived it.
+ *
+ * Codeman creates every pane with `remain-on-exit on`, so `/exit` ends the CLI
+ * while tmux keeps the pane, the tmux session and the `tmux attach-session`
+ * process Codeman records as the session's pid. No PTY exit handler runs, so
+ * without this record the session reads as a live idle one (Ark0N/Codeman#446).
+ *
+ * The field is TRI-STATE, and the third state is the absence of the field:
+ * `undefined` means Codeman does not know, and it must never be rendered as
+ * "alive". It is absent for a direct-PTY session (no pane exists), for a remote
+ * SSH session (the local pane holds the ssh client, whose death means transport
+ * drop OR exit) and for a docker case (the local pane holds a `docker exec`
+ * into the container's own tmux).
+ *
+ * `status` and `signal` are independently optional because tmux may know that
+ * the pane died without reporting how. Measured on tmux 3.2a: a SIGKILLed pane
+ * reports `pane_dead=1` with BOTH `#{pane_dead_status}` and `#{pane_dead_signal}`
+ * empty, and `#{pane_dead_signal}` does not exist at all before tmux 3.4. So an
+ * absent `status` means "the exit code is unknown", never "the exit code is 0".
+ *
+ * ⚠ AN ABSENT `status` STAYS ABSENT. Never write `status ?? 0`, and never read
+ * "no signal was reported" as "the exit must have been clean". On tmux 3.2a
+ * the absent status IS how a signal death presents, so absent-stays-absent is
+ * the only thing keeping a future clean-exit sweep away from crashed agents:
+ * an agent SIGKILLed by the OOM killer would otherwise read as a user typing
+ * `/exit` and be swept. Nothing here fails when somebody adds that `??` — the
+ * types allow it, the label still renders, and the damage shows up only once
+ * the sweep lands. The rule is enforced in `derivePaneExits()`
+ * (`tmux-manager.ts`), which omits the key rather than defaulting it.
+ */
+export interface PaneExit {
+  /**
+   * tmux `#{pane_dead_status}` — the command's exit code. Absent when tmux
+   * reported none, which means UNKNOWN and never 0. See the ⚠ above before
+   * giving this a default anywhere.
+   */
+  status?: number;
+  /** tmux `#{pane_dead_signal}` — the signal that killed the command. Absent when unsignalled or unsupported. */
+  signal?: number;
+  /**
+   * Wall-clock ms when THIS server process first observed the pane dead. It is
+   * not when the agent exited, which nothing records, and a restart that finds
+   * the pane still dead respawns it rather than re-timing the old exit.
+   */
+  at: number;
+}
+
 export interface SessionState {
   /** Unique session identifier */
   id: string;
@@ -780,6 +828,21 @@ export interface SessionState {
    * (COD-118). Runtime-only: never restored on boot (fresh server = fresh breaker).
    */
   respawnBlocked?: boolean;
+  /**
+   * The agent in this session's LOCAL tmux pane has exited (Ark0N/Codeman#446).
+   * See {@link PaneExit} for the tri-state rule and for which session shapes
+   * leave it absent. `status` and `pid` are deliberately untouched by it: the
+   * PTY-exit breaker owns `status: 'error'`, and a null `pid` is what makes the
+   * browser re-attach and launch a fresh CLI.
+   *
+   * Persisted so a reboot restore can tell a session whose agent exited from one
+   * that was merely idle when the power went. `reboot-restore.ts` reads the
+   * persisted record and never builds a `Session`, so the record is the only
+   * place that survives the reboot to carry it. Nothing reads it there YET:
+   * making the restore refuse such a session is a behavior change, and it
+   * belongs with the part of Ark0N/Codeman#446 that closes exited sessions.
+   */
+  paneExit?: PaneExit;
 }
 
 /**

src/utils/claude-transcript.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Does a Claude conversation transcript exist on this host?
+ *
+ * Claude writes one `<conversation-id>.jsonl` per conversation under
+ * `<config dir>/projects/<mangled cwd>/`. Two launch decisions turn on whether
+ * such a file exists: `--resume <id>` needs one, and `--session-id <id>` is
+ * REFUSED when one exists (`Error: Session ID ... is already in use.`).
+ *
+ * The project directory name is derived from the working directory, and a case
+ * that has been moved or renamed leaves its transcript under the OLD name, so
+ * the search is across every project directory rather than the one that matches
+ * the pane's cwd today.
+ *
+ * ⚠️ Existence is the whole question here, with no size floor. The create route
+ * additionally requires ~4 KB before it will resume, which is a "is this
+ * conversation worth resuming" judgement; for a relaunch the question is the
+ * opposite one — a one-line transcript still makes `--session-id` collide.
+ *
+ * ⚠️ A false answer is not the conservative one. Skipping a resume leaves the
+ * relaunch on `--session-id <id>`, which is safe only when no transcript backs
+ * that id either, so a lookup that misses the real config dir turns a
+ * recoverable pane into the collision this module exists to prevent.
+ *
+ * @dependencies none
+ * @consumedby session (relaunch resume pinning)
+ *
+ * @module utils/claude-transcript
+ */
+
+import { readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * `<config dir>/projects`, honouring a session's relocated `CLAUDE_CONFIG_DIR`
+ * (#255) and, failing that, the server process's own.
+ *
+ * ⚠️ The process env is not optional here. A pane inherits the server's
+ * environment through tmux, so on an install that exports `CLAUDE_CONFIG_DIR`
+ * the CLI writes its transcripts there and a lookup under `~/.claude` answers
+ * "no transcript" for every conversation on the host. `claudeCredentialsPath()`
+ * (claude-credentials.ts) and `realClaudeConfigDir()`
+ * (custom-model-injection-apply.ts) resolve the same directory the same way.
+ */
+export function claudeProjectsDir(configDir?: string): string {
+  const fromEnv = typeof process.env.CLAUDE_CONFIG_DIR === 'string' && process.env.CLAUDE_CONFIG_DIR.trim();
+  return join(configDir || fromEnv || join(homedir(), '.claude'), 'projects');
+}
+
+/**
+ * True when a transcript for `conversationId` exists under any project
+ * directory. Returns false for a missing projects dir or an unreadable one,
+ * which leaves the caller unpinned: safe where nothing else can collide with
+ * the bare `--session-id`, and the reason the caller walks its candidates down
+ * to the session's own id rather than treating one false answer as final.
+ */
+export async function claudeTranscriptExists(conversationId: string, configDir?: string): Promise<boolean> {
+  if (!conversationId) return false;
+  const projectsDir = claudeProjectsDir(configDir);
+  let projectDirs: string[];
+  try {
+    projectDirs = await readdir(projectsDir);
+  } catch {
+    return false;
+  }
+  for (const projectDir of projectDirs) {
+    try {
+      await stat(join(projectsDir, projectDir, `${conversationId}.jsonl`));
+      return true;
+    } catch {
+      // Not in this project directory; keep looking.
+    }
+  }
+  return false;
+}

src/web/approval-inbox.ts

@@ -71,6 +71,15 @@ export interface ApprovalItem {
    * and reach the user's other devices. See `acknowledge()`.
    */
   acknowledgedAt?: number;
+  /**
+   * Why the item arrived already acknowledged, for display only: the inbox
+   * writes `watching 1 monitor` for a session that went quiet because work it
+   * started itself is still running. A human acknowledgement leaves this unset,
+   * so a card can say "quiet, watching 1 monitor" rather than implying somebody
+   * looked. ⚠️ Pane-derived text, so it is bounded at the source and must not
+   * reach the DOM as markup — see `watchingLabel()` in `session-activity.ts`.
+   */
+  acknowledgedReason?: string;
   /**
    * Present only when the frame parsed confidently. Gates which digits the
    * answer endpoint accepts; absent → only approve('1')/deny(Esc) are allowed.
@@ -93,6 +102,12 @@ interface NotePromptArgs {
   toolSummary?: string;
   message?: string;
   cwd?: string;
+  /**
+   * What the session's pane says is still running in the background
+   * (`Session.watching`, e.g. `1 monitor`). An idle prompt from such a session
+   * opens ALREADY acknowledged: see `notePrompt()`.
+   */
+  watching?: string | null;
   /** Returns the raw (ANSI-bearing) pane frame, or null when unavailable. */
   capture?: () => string | null;
 }
@@ -217,6 +232,22 @@ export class ApprovalInbox {
    * Record a prompt for a session, superseding any previous item, and return
    * the new item. Captures context immediately and once more after a short
    * delay (see RECAPTURE_DELAY_MS).
+   *
+   * ⚠️ An idle prompt from a session that is WATCHING its own background work
+   * opens already acknowledged (`args.watching`). Claude Code ends the turn
+   * after arming a monitor or backgrounding a shell and then reports the pane
+   * idle a minute later, so the alert that follows asks a human to look at a
+   * session that wants nothing from them. Acknowledging is deliberately what
+   * happens here rather than skipping the item: the prompt is real and stays
+   * pending, answerable and available as Read My Mind context, and only the
+   * alert it would have armed is spent. A wrong label therefore costs a card
+   * that does not blink, never an alert that was never created.
+   *
+   * It re-arms by itself. The next idle prompt supersedes this item and builds
+   * a fresh one, so once the background work ends and the session goes quiet
+   * for an ordinary reason, that item carries no acknowledgement and alerts
+   * normally. Only `idle` is eligible: a permission or question dialog blocks
+   * the agent whatever else it started, so its alert must survive.
    */
   notePrompt(args: NotePromptArgs): ApprovalItem {
     this.resolveForSession(args.sessionId, 'superseded');
@@ -231,6 +262,10 @@ export class ApprovalInbox {
       message: args.message,
       cwd: args.cwd,
     };
+    if (args.kind === 'idle' && args.watching) {
+      item.acknowledgedAt = item.createdAt;
+      item.acknowledgedReason = `watching ${args.watching}`;
+    }
     this.applyCapture(item, args.capture);
     this.items.set(args.sessionId, item);
     if (args.capture) this.captures.set(args.sessionId, args.capture);

src/web/public/app.js

@@ -66,7 +66,23 @@ const _crashDiag = {
   // concurrent clients (desktop + phone) don't clobber each other.
   _pageId: Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8),
   log(msg) {
-    const entry = `${new Date().toISOString().slice(11,23)} ${msg}`;
+    // Entries are joined with '\n' into ONE localStorage value and beaconed to
+    // the server, and some call sites interpolate text this client does not
+    // control (a WebSocket close `reason` arrives from the server). A newline
+    // in there forges extra entries in the trail; an unbounded string can fill
+    // the storage quota and silently kill every later breadcrumb. Flatten and
+    // cap. CodemanDiag is loaded before app.js, but guard anyway — a
+    // diagnostic that can throw is worse than no diagnostic.
+    // Bound to a local FIRST: `CodemanDiag?.x` still throws a ReferenceError
+    // when the identifier was never declared, and this is the one function in
+    // the app that must never throw.
+    const diag = typeof CodemanDiag !== 'undefined' ? CodemanDiag : null;
+    const flat = diag?.sanitizeDiagEntry
+      ? diag.sanitizeDiagEntry(msg)
+      : String(msg == null ? '' : msg)
+          .replace(/[\r\n\u2028\u2029]+/g, ' ')
+          .slice(0, diag?.DIAG_ENTRY_MAX_CHARS ?? 300);
+    const entry = `${new Date().toISOString().slice(11,23)} ${flat}`;
     this._entries.push(entry);
     if (this._entries.length > this._maxEntries) this._entries.shift();
     try { localStorage.setItem('codeman-crash-diag', this._entries.join('\n')); } catch {}
@@ -325,6 +341,66 @@ function parseSessionPrefix(name) {
   return null;
 }
 
+// ═══════════════════════════════════════════════════════════════
+// Exited-agent tab label (Ark0N/Codeman#446)
+// ═══════════════════════════════════════════════════════════════
+// The server publishes session.paneExit when the agent inside a local tmux
+// pane has exited while remain-on-exit kept the pane. The field is tri-state
+// and its third state is absence, which means Codeman does not know — that
+// renders as nothing here and must never read as alive.
+//
+// status and signal are each optional, because tmux can know the pane died
+// without reporting how (a SIGKILLed pane on tmux 3.2a reports neither). So an
+// absent status shows a bare "exited" rather than "exited (0)": a clean exit
+// and an unexplained one must not look the same.
+function paneExitLabel(paneExit) {
+  if (!paneExit || typeof paneExit !== 'object') return '';
+  if (typeof paneExit.signal === 'number' && paneExit.signal > 0) return `exited (signal ${paneExit.signal})`;
+  if (typeof paneExit.status === 'number') return `exited (${paneExit.status})`;
+  return 'exited';
+}
+
+// The tab's accessible name, with the exit appended when there is one. Shared
+// by the full render and applyPaneExitBadge() so the two cannot disagree.
+function paneExitAriaLabel(name, label) {
+  return label ? `${name} session, agent ${label}` : `${name} session`;
+}
+
+// Add, update or remove one tab's exited-agent badge in place. Separate from
+// the render loop so it can be exercised directly: this is the only path a
+// session going live-to-exited ever takes, since that transition adds and
+// removes no tab and so never reaches the full rebuild.
+function applyPaneExitBadge(tab, paneExit) {
+  const label = paneExitLabel(paneExit);
+  const existing = tab.querySelector('.tab-exited-badge');
+  // Quiets the status dot too. That dot reports `status`, which stays `idle` or
+  // `busy` for an exited pane by design, so without this a green or pulsing dot
+  // sits next to a badge saying the agent is gone.
+  tab.classList.toggle('tab-agent-exited', !!label);
+  // The tab's aria-label overrides its contents for the accessible name, and the
+  // badge is aria-hidden like its siblings, so the exit has to ride the label.
+  const name = tab.querySelector('.tab-name')?.dataset?.fullName;
+  if (name) tab.setAttribute('aria-label', paneExitAriaLabel(name, label));
+  if (!label) {
+    existing?.remove();
+    return;
+  }
+  if (!existing) {
+    const badge = document.createElement('span');
+    badge.className = 'tab-exited-badge';
+    badge.setAttribute('aria-hidden', 'true');
+    // Generated status text, like the status pills: it carries data-i18n-skip
+    // rather than a dictionary entry. Without it the translator would rewrite
+    // the badge and the next render pass would rewrite it back, because the
+    // comparison below is against the English string.
+    badge.setAttribute('data-i18n-skip', '');
+    badge.textContent = label;
+    tab.querySelector('.tab-name')?.insertAdjacentElement('afterend', badge);
+    return;
+  }
+  if (existing.textContent !== label) existing.textContent = label;
+}
+
 const DEFAULT_SHORTCUTS = [
   {
     id: 'show-shortcuts',
@@ -682,6 +758,10 @@ class CodemanApp {
     this._wsReady = false;      // True when WS is open and ready for I/O
     this._wsState = 'disconnected'; // connecting | connected | reconnecting | fallback | disconnected
     this._wsLastRecvAt = 0;     // ms timestamp of the last frame received on the active WS
+    // Session whose socket dropped unintentionally, so output produced during
+    // the outage is missing from its buffer. Output frames carry no sequence
+    // number, so the only recovery is to refetch on the next successful open.
+    this._wsOutputGapSession = null;
 
     // Terminal write batching with DEC 2026 sync support
     this.pendingWrites = [];
@@ -1998,14 +2078,12 @@ class CodemanApp {
         + (this._loadBufferQueue?.reduce((s, w) => s + w.data.length, 0) || 0)
         + (this._terminalWriteInFlightBytes || 0);
       if (queued + data.data.length > 131072) { // 128KB — drop to prevent accumulation
-        // Schedule a self-recovery once the
-        // queue drains (debounced to avoid hammering the API during sustained bursts).
-        if (!this._clientDropRecoveryTimer) {
-          this._clientDropRecoveryTimer = setTimeout(() => {
-            this._clientDropRecoveryTimer = null;
-            this._onSessionNeedsRefresh();
-          }, 2000);
-        }
+        // The bytes are gone from the stream now, so the recovery is the only
+        // thing that puts this terminal back in step with the PTY. It also
+        // writes the crash-trail line, once per debounce window: logged here,
+        // one line per dropped frame evicted the whole 50-entry trail in
+        // under a second.
+        this._scheduleDroppedOutputRecovery(data.id, 0, queued);
         return;
       }
 
@@ -2013,6 +2091,61 @@ class CodemanApp {
     }
   }
 
+  /**
+   * Put the terminal back in step after a dropped frame, and keep trying until
+   * something actually repaints.
+   *
+   * ⚠️ A fire-and-forget timer is not a recovery, which is what this used to be:
+   * it nulled its own handle and then called `_onSessionNeedsRefresh()`, whose
+   * early returns are most likely to fire during the very burst that caused the
+   * drop. A skipped refresh lost the recovery with nothing left to retry it, so
+   * the hole stayed in the stream — and a hole in a TUI byte stream is a
+   * desynced cursor, which is muffled text (issue #464).
+   *
+   * Debounced by the same 2s as before, so a sustained burst still collapses
+   * into one attempt rather than hammering the API; bounded by
+   * `DROP_RECOVERY_MAX_ATTEMPTS`, because the early returns it retries past
+   * are transient contention. A refresh that died at the fetch DEADLINE is
+   * not retried: that is a stalled link, not contention, and each retry would
+   * be another `?full=1` capture waiting out a deadline of up to two minutes.
+   * Giving up leaves exactly what the old code left, so the floor is no worse.
+   *
+   * @param {string} sessionId - the session whose output was dropped
+   * @param {number} [attempt] - zero-based, for the bound
+   * @param {number} [queuedBytes] - render-queue bytes at the drop, for the crash trail
+   */
+  _scheduleDroppedOutputRecovery(sessionId, attempt = 0, queuedBytes) {
+    if (!sessionId || this._clientDropRecoveryTimer) return;
+    // Behind the debounce guard: one line per window, not per dropped frame.
+    if (Number.isFinite(queuedBytes)) _crashDiag.log(`TERMINAL DROP: ${(queuedBytes / 1024).toFixed(0)}KB queued`);
+    this._clientDropRecoveryTimer = setTimeout(async () => {
+      this._clientDropRecoveryTimer = null;
+      let repainted = false;
+      let timedOut = false;
+      try {
+        const result = await this._onSessionNeedsRefresh({ id: sessionId });
+        repainted = result === true;
+        timedOut = result === 'deadline';
+      } catch {
+        // Treated as "did not repaint" — retrying is the entire point of this.
+      }
+      const retry = window.CodemanDroppedOutput.shouldRetryDroppedOutputRecovery({
+        repainted,
+        timedOut,
+        attempt,
+        stillActive: this.activeSessionId === sessionId,
+      });
+      if (retry) {
+        _crashDiag.log(`DROP RECOVERY: attempt ${attempt + 1} did not repaint, retrying`);
+        this._scheduleDroppedOutputRecovery(sessionId, attempt + 1);
+      }
+      // Read through `window.` like terminal-ui.js does with its own constants:
+      // a bare global resolves in a browser but not in the vm harnesses the gate
+      // runs app.js under, and this body executes inside a timer where a
+      // ReferenceError would be swallowed — taking the recovery with it.
+    }, window.CodemanDroppedOutput.DROP_RECOVERY_DELAY_MS);
+  }
+
   // ═══════════════════════════════════════════════════════════════
   // Response Viewer — native-scroll panel for reading full Claude responses
   // ═══════════════════════════════════════════════════════════════
@@ -2436,8 +2569,14 @@ class CodemanApp {
       // placeholder beats a messy screen dump there.
       const sessionMode = this.sessions.get(this.activeSessionId)?.mode || 'claude';
       if (!lastResponse && (sessionMode === 'claude' || sessionMode === 'shell')) {
-        const termRes = await fetch(`/api/sessions/${this.activeSessionId}/terminal`);
-        const termData = (await termRes.json())?.data ?? {};
+        // The no-param form is capped only by `terminalBufferMaxBytes` (32MB by
+        // default), so it is the largest body the frontend asks for anywhere —
+        // it gets the full-history budget, not the tail one.
+        const termCapture = await this._fetchTerminalCapture(
+          `/api/sessions/${this.activeSessionId}/terminal`,
+          { full: true }
+        );
+        const termData = termCapture.json?.data ?? {};
         if (termData.terminalBuffer) {
           lastResponse = this._cleanTerminalBuffer(termData.terminalBuffer);
         }
@@ -2555,15 +2694,104 @@ class CodemanApp {
     }
   }
 
+  /**
+   * Fetch a terminal capture under a deadline.
+   *
+   * Every terminal fetch used to run with no timeout at all, including
+   * `?full=1`, which _maybeRefetchFullHistory itself calls "unbounded-ish work:
+   * at the default history limit it can be megabytes". On a stalled mobile link
+   * that request hangs on the browser default with no retry, and the load-state
+   * machinery stays armed behind it.
+   *
+   * The budget scales with what is being asked for and with how many captures
+   * are already running (see CodemanFetchDeadline): a full scrollback on a slow
+   * uplink legitimately needs longer than a tail, and eight tabs resuming must
+   * not all expire together because each assumed it had the link to itself.
+   *
+   * An abort surfaces as a rejected promise, which every caller already handles —
+   * they wrap these in try/catch and log. That is the point: a timeout becomes a
+   * recoverable error instead of an indefinite hang.
+   *
+   * ⚠️ **The body is read HERE, and that is the whole point.** `await fetch()`
+   * settles on response HEADERS, not the body, so clearing the deadline when it
+   * resolves leaves the body — the multi-megabyte `?full=1` capture this exists
+   * for — completely unbounded. Measured against a server that sends headers
+   * immediately and stalls the body: `fetch()` resolved at 30ms, the timer was
+   * cleared there, and the body completed at 4026ms unaborted under a 1000ms
+   * deadline. Reading the body inside the helper is what makes the deadline
+   * cover the transfer rather than just the handshake. `_terminalCaptureInflight`
+   * is scoped the same way, so a body still streaming counts toward the budget
+   * of a capture starting beside it.
+   *
+   * Returns the PARSED envelope plus the response headers, because two callers
+   * read `server-timing`, and `headersAt` because those same callers measure
+   * header-vs-body time and can no longer observe that moment themselves.
+   *
+   * @param {string} url
+   * @param {{full?: boolean}} [opts]
+   * @returns {Promise<{json: unknown, headers: Headers|undefined, headersAt: number}>}
+   */
+  async _fetchTerminalCapture(url, opts = {}) {
+    const deadlineMs =
+      typeof CodemanFetchDeadline !== 'undefined'
+        ? CodemanFetchDeadline.terminalFetchDeadlineMs({
+            full: !!opts.full,
+            inflight: this._terminalCaptureInflight || 0,
+          })
+        : 45000;
+    // AbortSignal.timeout() is not on every browser Codeman supports, so drive
+    // it from a controller and always clear the timer — an uncancelled one
+    // would abort a LATER request that reused this controller's signal.
+    //
+    // Degrade to a plain fetch where AbortController is missing rather than
+    // throwing: a capture with no deadline is the behaviour every caller had
+    // before this helper existed, while a ReferenceError here would take out
+    // terminal replay entirely. The deadline is a safety net, not a dependency.
+    const canAbort = typeof AbortController === 'function';
+    const controller = canAbort ? new AbortController() : null;
+    const timer = controller ? setTimeout(() => controller.abort(), deadlineMs) : null;
+    this._terminalCaptureInflight = (this._terminalCaptureInflight || 0) + 1;
+    try {
+      const res = await (controller ? fetch(url, { signal: controller.signal }) : fetch(url));
+      const headersAt = performance.now();
+      // Still inside the deadline: an abort here rejects the body stream, which
+      // is exactly the case a header-only timeout could not reach.
+      const json = await res.json();
+      return { json, headers: res.headers, headersAt };
+    } catch (err) {
+      if (err?.name === 'AbortError') {
+        _crashDiag.log(`TERMINAL FETCH TIMEOUT after ${deadlineMs}ms`);
+      }
+      throw err;
+    } finally {
+      if (timer !== null) clearTimeout(timer);
+      this._terminalCaptureInflight = Math.max(0, (this._terminalCaptureInflight || 1) - 1);
+    }
+  }
+
+  /**
+   * Reload this session's buffer from the server.
+   *
+   * ⚠️ Returns whether it ACTUALLY reloaded. Four of the paths out of here are
+   * early returns, and two of them — a buffer load in flight, a refresh already
+   * owning this session — are most likely to be true during exactly the output
+   * burst that makes a caller need this. A caller that treats "called" as
+   * "recovered" silently loses the recovery; `_scheduleDroppedOutputRecovery`
+   * is the one that cannot afford to.
+   *
+   * @returns {Promise<boolean|'deadline'>} true only once a response has been
+   *   applied; 'deadline' when the capture fetch hit its deadline (a stalled
+   *   link, which the dropped-output scheduler does not retry); false otherwise.
+   */
   async _onSessionNeedsRefresh(event = {}) {
     // Server sends this after SSE backpressure clears — terminal data was dropped,
     // so reload the buffer to recover from any display corruption.
     const sessionId = this.activeSessionId;
-    if (event?.id && event.id !== sessionId) return;
-    if (!sessionId || !this.terminal) return;
+    if (event?.id && event.id !== sessionId) return false;
+    if (!sessionId || !this.terminal) return false;
     // Skip if buffer load already in progress — avoids competing clear+rewrite cycles
-    if (this._isLoadingBuffer) return;
-    if (this._terminalRefreshOwner?.sessionId === sessionId) return;
+    if (this._isLoadingBuffer) return false;
+    if (this._terminalRefreshOwner?.sessionId === sessionId) return false;
     const refreshOwner = { sessionId };
     this._terminalRefreshOwner = refreshOwner;
     try {
@@ -2573,22 +2801,23 @@ class CodemanApp {
       // TUI modes still recover the whole picture, with the downgrade guard for
       // repaint-mode panes whose tmux capture can be smaller than xterm's buffer.
       const useFullHistory = this.sessions.get(sessionId)?.mode !== 'shell';
-      let res = await fetch(
+      let capture = await this._fetchTerminalCapture(
         useFullHistory
           ? `/api/sessions/${sessionId}/terminal?full=1`
-          : `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`
+          : `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`,
+        { full: useFullHistory }
       );
-      let headersReceivedAt = performance.now();
-      let data = (await res.json())?.data ?? {};
+      let headersReceivedAt = capture.headersAt;
+      let data = capture.json?.data ?? {};
       if (useFullHistory && data.terminalBuffer && this._replayWouldShrinkBuffer(data.terminalBuffer)) {
-        res = await fetch(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
-        headersReceivedAt = performance.now();
-        data = (await res.json())?.data ?? {};
+        capture = await this._fetchTerminalCapture(`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`);
+        headersReceivedAt = capture.headersAt;
+        data = capture.json?.data ?? {};
       }
       // Bail on a tab switch mid-fetch: writing here would paint this session's
       // history into the terminal the user is now looking at. The window is two
       // fetches wide in the fallback case, so this guard is not optional.
-      if (this.activeSessionId !== sessionId || this._terminalRefreshOwner !== refreshOwner) return;
+      if (this.activeSessionId !== sessionId || this._terminalRefreshOwner !== refreshOwner) return false;
       if (data.terminalBuffer) {
         // This refresh is SERVER-triggered, so a user quietly reading scrollback
         // did not ask for it and must not be dragged to the bottom by it (#259).
@@ -2596,8 +2825,11 @@ class CodemanApp {
         // meaningless across it — distance from the bottom is what survives.
         const before = this.terminal.buffer?.active;
         const linesFromBottom = before ? Math.max(0, (before.baseY || 0) - (before.viewportY || 0)) : 0;
-        this.terminal.clear();
-        this.terminal.reset();
+        // One queued clear, not clear()+reset(): both of those are synchronous
+        // and skip xterm's write queue, so live bytes still parsing would land
+        // after them and fuse into the buffer written below. See
+        // _resetTerminalForReplay.
+        this._resetTerminalForReplay();
         await this.chunkedTerminalWrite(
           data.terminalBuffer,
           TERMINAL_CHUNK_SIZE,
@@ -2625,13 +2857,36 @@ class CodemanApp {
           this.sendResize(this.activeSessionId);
         }
       }
+      // ⚠️ HERE: after a response arrived, and NOT in the `finally`. The marker
+      // means "this session lost output", and only a reconcile that actually
+      // completed settles it. Clearing on every exit meant one that threw — or
+      // hit the fetch deadline, which is the flaky-link case the marker exists
+      // for — dropped the gap silently with nothing to retry it.
+      // ⚠️ Outside the `if (data.terminalBuffer)` too: a server that answers
+      // with an empty capture HAS reconciled us, there was simply nothing to
+      // replay. Leaving the marker set there refetched on every reconnect for
+      // the life of the page.
+      this._markTerminalBufferReconciled(sessionId);
+      return true;
     } catch (err) {
       console.error('needsRefresh reload failed:', err);
+      return err?.name === 'AbortError' ? 'deadline' : false;
     } finally {
       if (this._terminalRefreshOwner === refreshOwner) this._terminalRefreshOwner = null;
     }
   }
 
+  /**
+   * Drop the "this session lost output" marker.
+   *
+   * Called from every path that repaints a session's buffer from the server, so
+   * the ws.onopen reconcile fires once and only when nothing else already did
+   * the work. See the ws.onclose note for what the marker means.
+   */
+  _markTerminalBufferReconciled(sessionId) {
+    if (sessionId && this._wsOutputGapSession === sessionId) this._wsOutputGapSession = null;
+  }
+
   async _onSessionClearTerminal(data) {
     if (data.id === this.activeSessionId) {
       // Skip if selectSession is already loading the buffer — clearTerminal arriving
@@ -2642,12 +2897,16 @@ class CodemanApp {
 
       // Fetch buffer, clear terminal, write buffer, resize (no Ctrl+L needed)
       try {
-        const res = await fetch(`/api/sessions/${data.id}/terminal`);
-        const headersReceivedAt = performance.now();
-        const termData = (await res.json())?.data ?? {};
+        // No-param capture: `terminalBufferMaxBytes` (32MB) is its only ceiling,
+        // so it needs the full-history budget. Defaulting to the tail budget
+        // gave the largest payload the smallest deadline.
+        const capture = await this._fetchTerminalCapture(`/api/sessions/${data.id}/terminal`, { full: true });
+        const headersReceivedAt = capture.headersAt;
+        const termData = capture.json?.data ?? {};
 
-        this.terminal.clear();
-        this.terminal.reset();
+        // Queued clear — see _resetTerminalForReplay for why clear()+reset()
+        // cannot do this job.
+        this._resetTerminalForReplay();
         if (termData.terminalBuffer) {
           // Strip any DEC 2026 markers and write raw content
           // (markers don't help here - this is a static buffer reload, not live Ink redraws)
@@ -2972,6 +3231,22 @@ class CodemanApp {
         // Flush any durably-queued input over the fresh socket (covers frames a
         // prior half-open socket silently dropped, and input typed while offline).
         this._onWsReady(sessionId);
+        // Reconcile the output hole this drop left (see the ws.onclose note).
+        // Only after an unintentional close — a first connect has no gap, and
+        // refetching there would duplicate the buffer selectSession just wrote.
+        if (this._wsOutputGapSession === sessionId) {
+          // NOT cleared here. `_onSessionNeedsRefresh` clears it once it has
+          // actually repainted; a reconcile that fails or is skipped (a buffer
+          // load already in flight, a tab switch) leaves the marker set so the
+          // next open retries. Re-entry is safe: `_terminalRefreshOwner` makes
+          // a second reconcile for the same session a no-op.
+          _crashDiag.log(`WS REOPEN: reconciling output gap for ${sessionId}`);
+          // Fire-and-forget: this is recovery, and a failure here must not stop
+          // the socket coming up. _onSessionNeedsRefresh already guards against
+          // running while a buffer load is in flight and against a tab switch
+          // landing this session's history in another session's terminal.
+          void this._onSessionNeedsRefresh({ id: sessionId });
+        }
       }
     };
 
@@ -2993,6 +3268,10 @@ class CodemanApp {
           // Input ACK — the server applied (or deduped) this seq; drop it from
           // the durable queue so it can never be re-delivered/lost.
           this._onWsInputAck(msg.seq, msg);
+        } else if (msg.t === 'zc') {
+          // Resize confirm — the geometry the PTY actually holds, which is not
+          // always the one this client asked for (issue #464).
+          this._onPtyGeometryReport(sessionId, msg.c, msg.r);
         }
       } catch {
         // Ignore malformed messages
@@ -3019,6 +3298,30 @@ class CodemanApp {
         `WS CLOSE code=${event.code} reason=${event.reason || ''} action=${plan.action} attempts=${this._wsReconnectAttempts || 0}`
       );
 
+      // Output frames carry no sequence number, so a dropped socket leaves a
+      // hole with nothing to replay it. ws.onopen re-sends dims and flushes
+      // queued INPUT; `needsRefresh` fires only on external-CLI startup and on
+      // SSE backpressure drain, never here.
+      //
+      // ⚠️ The gap this closes is NARROWER than "the device went offline". If
+      // the network drops, SSE drops with it and `handleInit`'s keepTerminal
+      // branch already reconciles on reconnect. The uncovered case is the WS
+      // dying while SSE stays up — a half-open socket, a proxy idle-timeout,
+      // a ping timeout — because `_onSSETerminal` discards every SSE terminal
+      // frame while `_wsReady` is true, and `_wsReady` only flips here, in
+      // onclose. Detecting a half-open socket takes up to the ping+pong window,
+      // and that whole span produces output nothing writes to the terminal.
+      //
+      // Reaching onclose at all means the drop was NOT intentional
+      // (_disconnectWs nulls this handler first), so mark the gap and let the
+      // next successful open reconcile from the server's buffer.
+      //
+      // Scoped to the session that actually lost bytes: a user who switches
+      // sessions during an outage gets a clean intentional disconnect for the
+      // new one, and its freshly-loaded buffer must not be refetched because a
+      // DIFFERENT session's socket dropped.
+      this._wsOutputGapSession = sessionId;
+
       const stillActive = this.activeSessionId === sessionId;
       if (plan.action === 'give-up') {
         this._wsState = stillActive ? 'fallback' : 'disconnected';
@@ -4571,11 +4874,30 @@ class CodemanApp {
   _sidebarRichRow(id, session) {
     if (typeof this._mobileOverviewState !== 'function') return null;
     const state = this._mobileOverviewState(session, this.pendingHooks?.get(id));
+    // An exited agent (Ark0N/Codeman#446) overrides the LABEL, never the state:
+    // `state` keys SESSION_ACTIVITY_RANK and the sort, while `status` stays idle
+    // or busy for an exited pane by design, so without this the muted dot sits
+    // beside a pill saying "idle". A pending alert still wins, exactly as it
+    // does for the dot.
+    const exited = !!paneExitLabel(session.paneExit) && (state === 'idle' || state === 'working');
+    const exitAt = exited ? Number(session.paneExit.at) || 0 : 0;
     return {
       state,
-      pill: this._sidebarRichPillLabel(state),
+      exited,
+      pill: exited ? 'exited' : this._sidebarRichPillLabel(state),
+      // What the pane's own footer says is still running in the background ("1 monitor",
+      // "2 shells"). A row that has one went quiet because the agent is waiting for that,
+      // which is a different thing from waiting for the user — so it rides BESIDE the
+      // state pill and never replaces it.
+      watching: typeof session.watching === 'string' ? session.watching : '',
       createdAt: Number(session.createdAt) || 0,
-      since: this._mobileOverviewSince ? this._mobileOverviewSince(state, session) : null,
+      since: exitAt
+        ? { key: 'exited', at: exitAt }
+        : exited
+          ? null
+          : this._mobileOverviewSince
+            ? this._mobileOverviewSince(state, session)
+            : null,
     };
   }
 
@@ -4608,7 +4930,19 @@ class CodemanApp {
       parts.push('<span class="tab-meta-sep" aria-hidden="true">\u00B7</span>');
       parts.push(stamp(row.since.key, row.since.at, 'for', 'tab-meta-since'));
     }
-    parts.push(`<span class="tab-pill tab-pill--${escapeHtml(row.state)}">${escapeHtml(row.pill)}</span>`);
+    const pillMod = row.exited ? 'exited' : row.state;
+    parts.push(`<span class="tab-pill tab-pill--${escapeHtml(pillMod)}">${escapeHtml(row.pill)}</span>`);
+    // The word is duplicated from mobile-overview.js for the same reason the pill labels
+    // above are: it is one word, and this file must render a complete row even when a
+    // stale cached mobile-overview.js has arrived without it.
+    // The visible text is that constant. The pane-derived label appears only in the
+    // tooltip, where escapeHtml() (which escapes both quote characters) is what this file
+    // already relies on for every untrusted string it puts in an attribute, and where the
+    // source caps it at MAX_WATCHING_LABEL_CHARS before it ever gets here.
+    if (row.watching) {
+      const title = escapeHtml(`Still running in the background: ${row.watching}`);
+      parts.push(`<span class="tab-pill tab-pill--watching" title="${title}">watching</span>`);
+    }
     // Both absolute stamps ALSO on the line itself, not only on the two items.
     // Below 288px the rail hides `.tab-meta-created` (the `tab-rail-tight`
     // rule), and a tooltip on a `display: none` element has no hover target —
@@ -4646,7 +4980,11 @@ class CodemanApp {
     const prev = tab.dataset.tabState;
     // The since ANCHOR moves without the state changing (each new turn re-stamps
     // lastSubmitAt), so key the compare on both.
-    const sig = `${row.state}:${row.since ? row.since.at : 0}:${row.createdAt}`;
+    // Unescaped on purpose, and it still matches the attribute the initial render wrote:
+    // that one goes through escapeHtml() because it is interpolated into markup, and the
+    // browser hands the decoded string back through `dataset`. `watching` is the only
+    // pane-derived value in this signature, which is why it is the only one escaped there.
+    const sig = `${row.state}${row.exited ? '+exited' : ''}:${row.since ? row.since.at : 0}:${row.createdAt}:${row.watching}`;
     if (tab.dataset.tabMetaSig === sig) return;
     tab.dataset.tabMetaSig = sig;
     tab.dataset.tabState = row.state;
@@ -4968,6 +5306,11 @@ class CodemanApp {
           statusEl.className = `tab-status ${status}`;
         }
 
+        // The exited-agent badge (Ark0N/Codeman#446). A session going from live
+        // to exited changes no tab count, so the full rebuild below never runs
+        // for it and this is the only path that ever draws the badge.
+        applyPaneExitBadge(tab, session.paneExit);
+
         // Rich sidebar meta ("created 3d ago · working 12m" + pill). The stamps
         // themselves move on _tickSidebarRichTimes(); this is here for the parts
         // a tick cannot see — the state flipping, and with it the pill, the row
@@ -5265,13 +5608,18 @@ class CodemanApp {
       const richMeta = this._sidebarRichMetaHTML(richRow);
       const richClass = richRow ? ` tab-state-${richRow.state}` : '';
       const richData = richRow
-        ? ` data-tab-state="${richRow.state}" data-tab-meta-sig="${richRow.state}:${richRow.since ? richRow.since.at : 0}:${richRow.createdAt}"`
+        ? ` data-tab-state="${richRow.state}" data-tab-meta-sig="${richRow.state}${richRow.exited ? '+exited' : ''}:${richRow.since ? richRow.since.at : 0}:${richRow.createdAt}:${escapeHtml(richRow.watching)}"`
         : '';
 
+      // '' whenever the server said nothing about this pane's agent, which covers
+      // a running pane and every session shape the field never applies to
+      // (direct-PTY, remote SSH, docker). See paneExitLabel().
+      const paneExitBadge = paneExitLabel(session.paneExit);
+
       const inlineSessionActions = this.shouldInlineSessionActions();
       const tabActionsHtml = `<span class="tab-actions"><span class="tab-gear" onclick="event.stopPropagation(); app.openSessionOptions(${escapeHtml(JSON.stringify(id))})" title="Session options" aria-label="Session options" tabindex="0">&#x2699;</span><span class="tab-detach" onclick="event.stopPropagation(); app.detachSession(${escapeHtml(JSON.stringify(id))})" title="Open in a new window" aria-label="Open session in a new window" tabindex="0">&#x29C9;</span><span class="tab-close" onclick="event.stopPropagation(); app.requestCloseSession(${escapeHtml(JSON.stringify(id))})" title="Close session" aria-label="Close session" tabindex="0">&times;</span><button type="button" class="tab-more" onclick="event.stopPropagation(); app.openTabRailActionMenu(event, ${escapeHtml(JSON.stringify(id))})" title="Session actions" aria-label="Session actions">&#x22EF;</button></span>`;
 
-      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${richClass}${loadState ? ' tab-loading' : ''}${this.hasTabDetachOverride(id) ? ' tab-show-detach' : ''}"${richData}${railOrderStyle} data-id="${id}" data-color="${color}" ${loadState ? `data-load-phase="${escapeHtml(loadState.phase)}"` : ''} onclick="app.handleSessionTabClick(event, ${escapeHtml(JSON.stringify(id))})" oncontextmenu="event.preventDefault(); app.startInlineRename(${escapeHtml(JSON.stringify(id))})" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-busy="${loadState ? 'true' : 'false'}" aria-label="${escapeHtml(name)} session" ${tabTooltip ? `title="${escapeHtml(tabTooltip)}"` : ''}>
+      parts.push(`<div class="session-tab ${isActive ? 'active' : ''}${alertClass}${richClass}${paneExitBadge ? ' tab-agent-exited' : ''}${loadState ? ' tab-loading' : ''}${this.hasTabDetachOverride(id) ? ' tab-show-detach' : ''}"${richData}${railOrderStyle} data-id="${id}" data-color="${color}" ${loadState ? `data-load-phase="${escapeHtml(loadState.phase)}"` : ''} onclick="app.handleSessionTabClick(event, ${escapeHtml(JSON.stringify(id))})" oncontextmenu="event.preventDefault(); app.startInlineRename(${escapeHtml(JSON.stringify(id))})" tabindex="0" role="tab" aria-selected="${isActive ? 'true' : 'false'}" aria-busy="${loadState ? 'true' : 'false'}" aria-label="${escapeHtml(paneExitAriaLabel(name, paneExitBadge))}" ${tabTooltip ? `title="${escapeHtml(tabTooltip)}"` : ''}>
           ${_tabIdx < 9 ? '<span class="tab-number">' + (_tabIdx + 1) + '</span>' : ''}
           ${loadState ? '<span class="tab-load-spinner" aria-hidden="true"></span>' : ''}
           <span class="tab-status ${status}" aria-hidden="true"></span>
@@ -5279,6 +5627,7 @@ class CodemanApp {
             <span class="tab-name-row">
               ${mode === 'shell' ? '<span class="tab-mode shell" aria-hidden="true">sh</span>' : mode === 'opencode' ? '<span class="tab-mode opencode" aria-hidden="true">oc</span>' : mode === 'codex' ? '<span class="tab-mode codex" aria-hidden="true">cx</span>' : mode === 'gemini' ? '<span class="tab-mode gemini" aria-hidden="true">gm</span>' : mode === 'antigravity' ? '<span class="tab-mode antigravity" aria-hidden="true">ag</span>' : mode === 'pi' ? '<span class="tab-mode pi" aria-hidden="true">pi</span>' : mode === 'grok' ? '<span class="tab-mode grok" aria-hidden="true">gk</span>' : mode === 'deepseek' ? '<span class="tab-mode deepseek" aria-hidden="true">ds</span>' : mode === 'omp' ? '<span class="tab-mode omp" aria-hidden="true">om</span>' : ''}
               <span class="tab-name" data-session-id="${id}" data-full-name="${escapeHtml(name)}">${tabLabel}</span>
+              ${paneExitBadge ? `<span class="tab-exited-badge" data-i18n-skip aria-hidden="true">${escapeHtml(paneExitBadge)}</span>` : ''}
               ${inlineSessionActions ? tabActionsHtml : ''}
               <span class="tab-detached-badge" aria-hidden="true">detached</span>
             </span>
@@ -5866,9 +6215,29 @@ class CodemanApp {
     }
   }
 
+  /**
+   * Clear the terminal for a replay, IN STREAM.
+   *
+   * xterm's `write()` is asynchronously queued (the WriteBuffer parses in ~12ms
+   * slices) while `Terminal.reset()` is synchronous and, by upstream's own
+   * documentation, "does not clear input buffers and does not reset the parser,
+   * thus the terminal will continue to apply pending input data". So bytes
+   * queued just before a `reset()` are parsed AFTER it and fuse into whatever
+   * snapshot is written next — measured upstream as `p8rmissions` rendered
+   * where `bypass permissions` belonged.
+   *
+   * A queued clear cannot race that way: it lands after the leftovers and
+   * before the snapshot, whatever the queue held. This function used to follow
+   * the sync `reset()` with a queued `\x1b[3J\x1b[H\x1b[2J`, which already got
+   * that right for CONTENT. RIS (`\x1bc`) additionally resets modes, charsets,
+   * scroll regions and SGR state, so leftover bytes cannot park the terminal in
+   * alt-screen or an odd scroll region and survive the clear.
+   *
+   * Callers may write the replacement content in as many chunks as they like —
+   * ordering within the queue is what matters, not writing it all at once.
+   */
   _resetTerminalForReplay() {
-    this.terminal.reset();
-    this.terminal.write('\x1b[3J\x1b[H\x1b[2J');
+    this.terminal.write('\x1bc');
   }
 
   _recordTerminalLoadTiming(timing) {
@@ -5932,9 +6301,9 @@ class CodemanApp {
     this._fullHistoryRepullInFlight = true;
     try {
       const requestStartedAt = performance.now();
-      const res = await fetch(`/api/sessions/${sessionId}/terminal?full=1`);
-      const headersReceivedAt = performance.now();
-      const payload = (await res.json())?.data ?? {};
+      const capture = await this._fetchTerminalCapture(`/api/sessions/${sessionId}/terminal?full=1`, { full: true });
+      const headersReceivedAt = capture.headersAt;
+      const payload = capture.json?.data ?? {};
       const bodyParsedAt = performance.now();
       const buffer = payload.terminalBuffer;
       const timing = {
@@ -5947,7 +6316,7 @@ class CodemanApp {
         bodyAndJsonMs: bodyParsedAt - headersReceivedAt,
         resetAndParseMs: 0,
         totalMs: 0,
-        serverTiming: res.headers?.get?.('server-timing') || '',
+        serverTiming: capture.headers?.get?.('server-timing') || '',
         refused: false,
       };
       // Bail on a tab switch mid-fetch: writing here would paint another session's
@@ -6315,11 +6684,18 @@ class CodemanApp {
     // For that just-created-session case we flush (not discard) queued SSE events.
     let bufferWasEmpty = false;
     let cacheResetAndParseMs = 0;
+    // Hoisted out of the try: the catch needs to know whether the pane was
+    // blanked before the fetch, because only then is there nothing on screen.
+    let clearedBeforeFresh = false;
     try {
       // Fit terminal to container BEFORE writing any buffer data.
       // If the browser was resized while viewing another session, the terminal
       // canvas may be at stale dimensions — content would render at wrong width.
-      if (this.fitAddon) this.fitAddon.fit();
+      // A width refusal belonged to the PREVIOUS session's pane, and while it
+      // stands sendResize keeps the columns it last adopted; this pane's own
+      // report re-establishes it if another device holds this one too.
+      this._paneWidthRefused = false;
+      this.syncTerminalGeometry();
 
       // Also push the new dimensions to the PTY. Without this, codex/codeman
       // sees the size that was set the last time the throttled resize handler
@@ -6396,7 +6772,8 @@ class CodemanApp {
       // blank and rewrites with fresh data. Skip the cache and write the fresh
       // buffer once for a single clean transition.
       const cachedBuffer = this.terminalBufferCache.get(sessionId);
-      let clearedBeforeFresh = false;
+      // `clearedBeforeFresh` is declared above the try, because the catch reads
+      // it — re-declaring it here would shadow that and silently break it.
       if (cachedBuffer && !sessionIsBusy && !restoredSnapshot && session?.mode !== 'shell') {
         _crashDiag.log(`CACHE_WRITE: ${(cachedBuffer.length/1024).toFixed(0)}KB`);
         this._setTerminalLoadState(sessionId, selectGen, 'replaying');
@@ -6445,17 +6822,32 @@ class CodemanApp {
       const useFullHistory = session?.mode !== 'shell' && !this._fullHistoryLoaded.has(sessionId);
       if (useFullHistory) this._fullHistoryLoaded.add(sessionId);
       const fetchStartedAt = performance.now();
-      const res = await fetch(
-        useFullHistory
-          ? `/api/sessions/${sessionId}/terminal?full=1`
-          : `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`
-      );
-      const headersReceivedAt = performance.now();
+      const tailUrl = `/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`;
+      let capture;
+      try {
+        capture = await this._fetchTerminalCapture(
+          useFullHistory ? `/api/sessions/${sessionId}/terminal?full=1` : tailUrl,
+          { full: useFullHistory }
+        );
+      } catch (err) {
+        // The deadline made a slow link reachable for the first time, and the
+        // pane was already blanked above — so an abort here used to leave a
+        // black rectangle, discard the queued live output, and never reach
+        // `_connectWs`. Degrade to the bounded tail instead: less history, but
+        // a working tab. Only for the full-history pull; the tail has nothing
+        // smaller to fall back to, and a second failure is the honest floor.
+        if (err?.name !== 'AbortError' || !useFullHistory) throw err;
+        _crashDiag.log('FULL CAPTURE ABORTED → tail');
+        // It never loaded, so the next select must be allowed to try again.
+        this._fullHistoryLoaded.delete(sessionId);
+        capture = await this._fetchTerminalCapture(tailUrl);
+      }
+      const headersReceivedAt = capture.headersAt;
       if (this._isStaleSelect(selectGen)) {
         this._clearTerminalLoadState(sessionId, selectGen);
         return;
       }
-      const data = (await res.json())?.data ?? {};
+      const data = capture.json?.data ?? {};
       const bodyParsedAt = performance.now();
       // How this load must end, decided here because `chunkedTerminalWrite` is
       // what actually ends it for a non-empty buffer. A tmux pane capture is a
@@ -6535,7 +6927,7 @@ class CodemanApp {
         cacheResetAndParseMs,
         freshResetAndParseMs,
         selectToReplayCompleteMs: performance.now() - _selStart,
-        serverTiming: res.headers?.get?.('server-timing') || '',
+        serverTiming: capture.headers?.get?.('server-timing') || '',
       };
       // Buffer load complete — unblock live SSE writes. chunkedTerminalWrite calls
       // _finishBufferLoad after ordering the fetched snapshot in xterm; if we skipped
@@ -6552,6 +6944,11 @@ class CodemanApp {
           bufferWasEmpty ? { flushQueued: true, since: 0 } : finishOpts
         );
       }
+      // This load repainted the session from the server, so any pending
+      // output-gap marker is already satisfied. Selecting a session runs BEFORE
+      // _connectWs, so without this the socket opening afterwards would replay
+      // the whole buffer again on top of the one just written.
+      this._markTerminalBufferReconciled(sessionId);
       // Drop the guard so user input clears state normally
       this._restoringFlushedState = false;
 
@@ -6646,17 +7043,28 @@ class CodemanApp {
       // and, because it goes through `forceReload`, a dropped and reopened
       // WebSocket plus a deleted xterm snapshot.
       //
-      // That equality is the signature of a CLAMP rather than a race.
-      // `getTerminalDimensions()` floors at 40x10 while `fitAddon.fit()` does
-      // not, so a terminal narrower than 40 columns or shorter than 10 rows
-      // reports a pane permanently bigger than itself, and every select would
-      // retry without ever converging. A race never produces this equality: its
-      // whole premise is that the pane was still at the size we asked it to
-      // leave. The other non-converging case, `Session.resize` declining a
-      // small viewport while a desktop claim is live, does not produce it
-      // either — that pane sits at the DESKTOP's size — so it still costs the
-      // one capped attempt, and stopping it needs the pane-ownership policy
-      // this does not touch.
+      // A race never produces this equality: its whole premise is that the pane
+      // was still at the size we asked it to leave. So the equality means the
+      // pane already IS what we asked for and a retry would capture the same
+      // frame twice.
+      //
+      // ⚠️ This used to also be the signature of a CLAMP, and that is now fixed
+      // at the source rather than worked around here (issue #464).
+      // `getTerminalDimensions()` floors at 40x10 while `fitAddon.fit()` did
+      // not, so a terminal under 40 columns or 10 rows reported a pane
+      // permanently bigger than itself and every select retried without ever
+      // converging. `syncTerminalGeometry()` now applies that floor to xterm as
+      // well, so the browser terminal IS the size it reports and the clamp can
+      // no longer manufacture a mismatch — which also means the repair below is
+      // reached only by cases it can actually repair.
+      //
+      // The other non-converging case, `Session.resize` declining a small
+      // viewport while a desktop claim is live, does not produce this equality
+      // either — that pane sits at the DESKTOP's size. It no longer needs
+      // repairing from here: the server reports the geometry the PTY actually
+      // holds ({"t":"zc"} / the resize response) and `_onPtyGeometryReport`
+      // adopts it, so the terminal matches the pane that is being drawn instead
+      // of replaying against one that never existed.
       const captureMatchesRequestedSize =
         !!dimsAfterLoad && data.captureCols === dimsAfterLoad.cols && data.captureRows === dimsAfterLoad.rows;
 
@@ -6823,14 +7231,46 @@ class CodemanApp {
     } catch (err) {
       if (this._isLoadingBuffer) this._finishBufferLoad(bufferLoadOwner);
       this._restoringFlushedState = false;
-      this._setTerminalLoadState(sessionId, selectGen, 'failed');
       console.error('Failed to load session terminal:', err);
+      if (this._isStaleSelect(selectGen)) {
+        this._clearTerminalLoadState(sessionId, selectGen);
+        return;
+      }
+      // The history did not load. That is not a reason to leave the tab dead:
+      // ⚠️ the socket is what carries LIVE output, and it is opened at the end
+      // of the happy path, so bailing here left the session mute until the user
+      // switched away and back.
+      this._connectWs(sessionId);
+      // Only when the pane was blanked for a replay that never came. A pane
+      // still holding its previous content is stale, not empty, and stacking a
+      // notice on top of readable output is worse than the staleness.
+      if (clearedBeforeFresh && this.terminal) {
+        // Three short lines, none over 25 columns, because the narrowest
+        // terminal this app will render is the 40-column floor and a notice
+        // that wraps there leaves a lone '.' on a line of its own — measured at
+        // 320px, where a single 52-character sentence did exactly that.
+        // Each line is one fact: what failed, that the session is still alive,
+        // and what to do. The last says RELOAD rather than "reopen the tab",
+        // because `selectSession` early-returns when the session is already
+        // active, so clicking the tab you are already on retries nothing.
+        this.terminal.write(
+          '\r\n\x1b[2m  History did not load.\r\n  Live output continues.\r\n  Reload to try again.\x1b[0m\r\n'
+        );
+      }
+      // ⚠️ CLEAR, not 'failed'. `_setTerminalLoadState` only marks the TAB, and
+      // nothing ever cleared it on this path — so the tab kept its spinner and
+      // `aria-busy="true"` forever, telling every reader and every screen reader
+      // that a load was still running when it had already given up.
+      this._clearTerminalLoadState(sessionId, selectGen);
     }
   }
 
   // Shared cleanup for all session data — called from both closeSession() and session:deleted handler
   _cleanupSessionData(sessionId) {
     this.closeTabRailActionMenu?.();
+    // A dead session has no buffer to reconcile; leaving the marker set would
+    // make a later socket for a REUSED id reconcile against nothing.
+    this._markTerminalBufferReconciled(sessionId);
     // If the deleted session is currently being renamed, abort the rename
     // so the inline <input> doesn't ghost as a stale tab on screen.
     if (this._activeRename?.sessionId === sessionId) {

src/web/public/approvals-ui.js

@@ -194,8 +194,21 @@ Object.assign(CodemanApp.prototype, {
     document.querySelector('.btn-approvals')?.setAttribute('aria-expanded', 'false');
   },
 
+  /**
+   * Items still waiting on a human. An acknowledged item (a human already looked, or the
+   * session opened it acknowledged because it is watching its own background work) keeps
+   * its card but arms no alert, so it must not light the bell either; this is the same
+   * count `pendingApprovalCount()` gives `codeman tui`.
+   */
+  pendingApprovalsCount() {
+    if (!this.approvals) return 0;
+    let count = 0;
+    for (const item of this.approvals.values()) if (!item.acknowledgedAt) count++;
+    return count;
+  },
+
   renderApprovals() {
-    const count = this.approvals ? this.approvals.size : 0;
+    const count = this.pendingApprovalsCount();
     const btn = document.querySelector('.btn-approvals');
     if (btn) {
       // Marker-class visibility (base header rules are display !important):
@@ -222,6 +235,15 @@ Object.assign(CodemanApp.prototype, {
       return;
     }
     list.innerHTML = items.map((item) => this._approvalCardHtml(item)).join('');
+    // The quiet reason is the only pane-derived string on a card, and it is the one
+    // an agent could write itself (it prints its own footer row), so it reaches the
+    // DOM as text and never as markup. The card leaves an empty span for it.
+    for (const item of items) {
+      if (!item.acknowledgedReason) continue;
+      const card = list.querySelector(`[data-approval-id="${CSS.escape(item.id)}"]`);
+      const slot = card && card.querySelector('.approval-quiet');
+      if (slot) slot.textContent = 'quiet, ' + item.acknowledgedReason;
+    }
   },
 
   _approvalCardHtml(item) {
@@ -260,6 +282,9 @@ Object.assign(CodemanApp.prototype, {
       `<span class="approval-session" data-i18n-skip>${escapeHtml(item.sessionName || item.sessionId.slice(0, 8))}</span>` +
       `<span class="approval-age" data-i18n-skip>${age}</span>` +
       `</div>` +
+      // Filled by renderApprovalsDrawer through textContent, never here: see the note
+      // there. An item a human acknowledged carries no reason and gets no line.
+      (item.acknowledgedReason ? `<div class="approval-quiet" data-i18n-skip></div>` : '') +
       (summary ? `<div class="approval-summary" data-i18n-skip>${escapeHtml(summary)}</div>` : '') +
       (item.context ? `<pre class="approval-context">${escapeHtml(item.context)}</pre>` : '') +
       `<div class="approval-actions">${actions}</div>` +

src/web/public/constants.js

@@ -819,36 +819,32 @@ function decideAutoCopy({ enabled, text, lastCopied, pending } = {}) {
 // _selectTouchSelectionLine already treats those cells as padding. This is that
 // same rule for the mouse and keyboard paths, which never had it.
 //
-// ⚠ Trailing padding ONLY. A shared LEADING indent is deliberately left alone,
-// and this note is here so the idea is not re-derived: it was built, measured
-// and dropped before merge. Removing the longest leading run every selected row
-// shares looks like the mirror image of the trailing trim and is not, because
-// no native terminal does it and the transform cannot tell a TUI's margin from
-// content that is genuinely indented. Measured over 401 445 three-row windows
-// across 1 010 tracked files in this repo, it fired on 73% of them: 92% inside
-// a YAML workflow, 76% over `git log` output, 48% in a TypeScript source file.
-// No width threshold separates the two, because they are the same widths: a
-// live Claude Code pane's own margins measure 2 and 5 columns while the most
-// common non-TUI shared run is 4, sitting between them.
+// A LEADING margin is stripped too, but only the one the CLI in the pane
+// DECLARES as its transcript gutter, passed in as `options.margin`. Called with
+// no options this trims trailing padding and nothing else, which is what keeps
+// every caller that has no declared gutter on the old behaviour.
 //
-// The asymmetry that settles it is in the failure modes. A wrong trailing trim
+// ⚠ The failure modes are not symmetrical, and that asymmetry sets how much
+// evidence a leading strip has to show before it fires. A wrong trailing trim
 // costs nothing. A wrong dedent silently deletes information that was on the
 // screen, with no signal to the user and nothing in the clipboard to hint at
 // it, and it is wrong on `git log` bodies, on indented code read out of `cat`
 // (semantic in Python), on `git diff` context rows where the leading space is
 // the marker, and on stack traces.
 //
-// ⚠ It also cannot be made consistent cheaply. Whether the first row joins the
-// measurement depended on the mousedown COLUMN, which the user never sees, so
-// one block of three rows produced three different clipboard results; and the
-// flag read `getSelectionPosition().start`, which is the mousedown anchor that
-// xterm never normalises, so dragging UP through a block read it off the bottom
-// row. If it is ever revisited, the one qualification that measured clean is
-// painted trailing padding (a full-screen TUI writes real spaces across every
-// row; a shell pane leaves those cells never-written, so xterm trims them):
-// zero false positives over all 401 445 windows. It still mangles a `git log`
-// body sitting inside an agent's own gutter, which is why it was not taken now.
-function cleanCopiedSelection(text) {
+// ⚠ The declared gutter is a CEILING, not the answer. The strip is the lesser
+// of it and the run every selected line shares, so a block can only ever shift
+// as a unit: the relative structure inside a selection survives by
+// construction, and a selection reaching column 0 loses nothing at all.
+//
+// ⚠ Deriving the width from the text instead is what fails, twice over. The
+// selection's own shared indent cannot tell a margin from content, because a
+// three-row window of nested YAML shares an indent for the same reason a margin
+// does — it fired on 73% of ordinary indented text. Taking the narrowest indent
+// on the surrounding rows fails more quietly: a file listing inside the
+// transcript can be the narrowest thing on screen, which over-stripped about 1%
+// of selections across six pane widths.
+function cleanCopiedSelection(text, options) {
   if (typeof text !== 'string' || !text) return '';
   // Split on \n and leave any \r in place: xterm joins rows with \r\n on
   // Windows, and the clipboard should keep the endings xterm chose.
@@ -868,7 +864,36 @@ function cleanCopiedSelection(text) {
     while (cut > 0 && (line[cut - 1] === ' ' || line[cut - 1] === '\t')) cut--;
     return cut === end ? line : line.slice(0, cut) + line.slice(end);
   };
-  return text.split('\n').map(trimEnd).join('\n');
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) lines[i] = trimEnd(lines[i]);
+
+  const margin = Math.max(0, Math.trunc(Number(options?.margin) || 0));
+  if (!margin) return lines.join('\n');
+
+  // The first line of a selection that began mid-row carries no margin — the
+  // mousedown cut it off — so it neither votes on the shared indent nor gets
+  // stripped. This is the ONE thing the mousedown column still decides, and it
+  // decides it for that line alone. Whether the rest of the block is dedented
+  // no longer depends on where the click landed, which is what made the same
+  // three rows produce three different clipboard results before.
+  const from = options?.firstLinePartial === true ? 1 : 0;
+
+  // The pane's margin is a ceiling, not the answer. Strip the narrower of it
+  // and what every selected line shares, so the block shifts as a unit and no
+  // line can lose indentation another line keeps.
+  let shared = margin;
+  for (let i = from; i < lines.length && shared > 0; i++) {
+    const line = lines[i];
+    if (!line || line === '\r') continue; // a padding-only row, already trimmed away
+    let run = 0;
+    while (run < line.length && line[run] === ' ') run++;
+    if (run < shared) shared = run;
+  }
+  if (!shared) return lines.join('\n');
+  for (let i = from; i < lines.length; i++) {
+    if (lines[i] && lines[i] !== '\r') lines[i] = lines[i].slice(shared);
+  }
+  return lines.join('\n');
 }
 
 if (typeof window !== 'undefined') {
@@ -1560,6 +1585,226 @@ function buildSplitPickerSessions(sessions, sessionOrder, excludeId, detachedIds
   return result;
 }
 
+// ── Renderer liveness ──────────────────────────────────────────────────────
+//
+// iOS DISCARDS scheduled requestAnimationFrame callbacks when a PWA goes to
+// the background — not deferred, never delivered. xterm's RenderDebouncer only
+// clears its `_animationFrame` handle from INSIDE that callback:
+//
+//   refresh() {
+//     if (this._animationFrame !== undefined) return;   // <- stale forever
+//     this._animationFrame = requestAnimationFrame(() => this._innerRefresh());
+//   }
+//   _innerRefresh() { this._animationFrame = undefined; ... }   // never runs
+//
+// So after one backgrounding the handle is permanently non-undefined and EVERY
+// later render request returns on line one. Parsing is decoupled from
+// rendering, so bytes keep filling the buffer correctly and nothing throws —
+// the terminal is simply frozen. Closing and reopening fixes it because that
+// constructs a new Terminal, and therefore a new debouncer.
+//
+// Codeman is MORE exposed than a per-session-terminal app: there is exactly one
+// xterm instance for the whole page load, so a single backgrounding can wedge
+// it until a full reload.
+//
+// This is the pure decision half. The signature that distinguishes this from
+// every other way a terminal can look stuck is that bytes were WRITTEN and the
+// element is VISIBLE, yet onRender has not fired since:
+//
+//   frozen   = wroteAt > renderedAt && now - wroteAt >= threshold && visible
+//
+// Deliberately NOT a "no output at all" check: a quiet terminal is the normal
+// state and must never be kicked. And `visible` is required because a hidden
+// terminal legitimately stops rendering (xterm pauses it), so kicking there
+// would fire constantly on every backgrounded tab.
+const RENDER_STALL_MS = 4000;
+
+// How often the watchdog checks. Deliberately coarse: the failure it catches is
+// permanent until healed, so detecting it a second late costs nothing, while a
+// tight interval would burn a wakeup per second on every idle phone.
+const RENDER_LIVENESS_POLL_MS = 2000;
+
+/**
+ * Should the renderer be kicked? Pure so the CI gate can cover it — the DOM
+ * half (cancelling the stale handle) lives in terminal-ui.js.
+ *
+ * @param {{wroteAt:number, renderedAt:number, now:number, visible:boolean,
+ *          thresholdMs?:number}} s
+ * @returns {boolean}
+ */
+function shouldKickRenderer(s) {
+  if (!s || !s.visible) return false;
+  const wroteAt = Number(s.wroteAt) || 0;
+  const renderedAt = Number(s.renderedAt) || 0;
+  const now = Number(s.now) || 0;
+  // Nothing written yet — a fresh terminal has no render to be missing.
+  if (wroteAt <= 0) return false;
+  // A render landed at or after the last write: the pipeline is alive.
+  if (renderedAt >= wroteAt) return false;
+  const threshold = Number.isFinite(s.thresholdMs) && s.thresholdMs > 0 ? s.thresholdMs : RENDER_STALL_MS;
+  return now - wroteAt >= threshold;
+}
+
+// ── Fetch deadlines ────────────────────────────────────────────────────────
+//
+// No terminal fetch carried any deadline, including `?full=1`, which the code
+// itself describes as "unbounded-ish work: at the default history limit it can
+// be megabytes". On a stalled mobile link that request hangs on the browser
+// default with no retry and no path back to a usable terminal short of a
+// reload.
+//
+// A single fixed timeout is wrong in both directions — too short for a full
+// scrollback capture on a slow uplink, too long for a small tail on a dead
+// connection. So the deadline is scaled by what is actually being asked for,
+// and by how many captures are already in flight: on a slow link those bytes
+// must drain before this request's own bytes start moving, and its timer is
+// already running the whole time.
+const FETCH_DEADLINE_TAIL_MS = 15000;
+const FETCH_DEADLINE_FULL_MS = 45000;
+const FETCH_DEADLINE_MAX_MS = 120000;
+
+/**
+ * Deadline in ms for a terminal capture.
+ *
+ * @param {{full?:boolean, inflight?:number}} s - `full` = the ?full=1 capture;
+ *   `inflight` = captures already running (this one included or not, it only
+ *   scales the budget).
+ * @returns {number}
+ */
+function terminalFetchDeadlineMs(s) {
+  const full = !!(s && s.full);
+  const base = full ? FETCH_DEADLINE_FULL_MS : FETCH_DEADLINE_TAIL_MS;
+  const inflight = Math.max(0, Number(s && s.inflight) || 0);
+  // Each already-queued capture gets the newcomer one more base budget to wait
+  // through. Linear rather than clever: the point is only that eight tabs
+  // resuming do not all time out together because each assumed it was alone.
+  return Math.min(FETCH_DEADLINE_MAX_MS, base * (1 + inflight));
+}
+
+// ── Diagnostics hygiene ────────────────────────────────────────────────────
+//
+// The crash trail is joined with '\n' into ONE localStorage value and beaconed
+// to the server, and at least one call site interpolates server-controlled text
+// (a WebSocket close `reason`). An embedded newline there forges extra entries
+// in the trail; an unbounded string can fill the storage quota. Both are cheap
+// to close, and the trail is something a user may be asked to paste into an
+// issue.
+const DIAG_ENTRY_MAX_CHARS = 300;
+
+/** Flatten a diagnostic message to one bounded, newline-free line. */
+function sanitizeDiagEntry(msg) {
+  return String(msg == null ? '' : msg)
+    .replace(/[\r\n\u2028\u2029]+/g, ' ')
+    .slice(0, DIAG_ENTRY_MAX_CHARS);
+}
+
+// ── Recovering a dropped output frame ──────────────────────────────────────
+//
+// `_onSessionTerminal` drops an incoming frame when the app-owned render queues
+// already hold 128KB, which is the right call — the alternative is an unbounded
+// backlog — but a hole in a TUI byte stream is a desynced cursor, and a desynced
+// cursor is muffled text (issue #464). So the drop is only half of it: the
+// recovery has to actually happen.
+//
+// ⚠️ It used to be a fire-and-forget timer. `_onSessionNeedsRefresh` opens with
+// four early returns, and two of them — a buffer load in flight, a refresh
+// already owning this session — are MOST likely to be true during exactly the
+// output burst that caused the drop. The timer nulled itself before the call,
+// so a skipped refresh lost the recovery silently and the dropped bytes were
+// never replayed.
+//
+// Bounded, because the early returns it retries past are transient contention
+// that clears in seconds, and a permanently failing refresh must not become a
+// forever-loop against the API. A refresh that hit the capture fetch DEADLINE
+// is not contention but a stalled link, and is not retried at all: each retry
+// would be another `?full=1` capture waiting out a deadline of up to two
+// minutes, where the old code cost exactly one. Giving up after the cap leaves
+// exactly the garbled frames the old code left, so the floor is no worse.
+const DROP_RECOVERY_DELAY_MS = 2000;
+const DROP_RECOVERY_MAX_ATTEMPTS = 5;
+
+/**
+ * Should a dropped-output recovery run again?
+ *
+ * @param {{repainted: boolean, timedOut?: boolean, attempt: number, stillActive: boolean}} state
+ *   `repainted` — whether `_onSessionNeedsRefresh` actually rewrote the buffer.
+ *   `timedOut`  - whether it failed at the capture fetch deadline.
+ *   `attempt`   — how many have already run, zero-based.
+ *   `stillActive` — whether the dropped session is still the one on screen.
+ * @returns {boolean}
+ */
+function shouldRetryDroppedOutputRecovery({ repainted, timedOut = false, attempt, stillActive }) {
+  // Switched away: `selectSession` repaints from the server on its own, so a
+  // retry here would be a second replay of a buffer that is about to be written.
+  if (!stillActive) return false;
+  if (repainted) return false;
+  if (timedOut) return false;
+  return attempt + 1 < DROP_RECOVERY_MAX_ATTEMPTS;
+}
+
+// ── Terminal geometry: xterm and the PTY must never disagree ───────────────
+//
+// Issue #464 ("text gets muffled"). Claude Code's TUI repaints by wrapping its
+// frame at the width the PTY reported and walking the cursor up that many
+// ROWS. So a browser terminal whose width differs from the PTY's makes every
+// repaint arithmetic wrong: a logical line occupies more physical rows than
+// Ink counted, `eraseLines(n)` clears too few of them, and the new frame paints
+// over rows that were never erased. Measured against a real xterm — a PTY
+// believing 120 columns against a 62-column terminal renders each wrapped line
+// twice, and a shorter replacement line leaves the tail of the old one behind.
+// That is exactly the doubled rows and half-overwritten prose in the report.
+//
+// The floor exists because a PTY a handful of columns wide makes any CLI wrap
+// every word; it is NOT a display preference, so the browser terminal has to
+// honour it too. Three separate call sites used to fit xterm to the RAW
+// proposal and report the CLAMPED one, which is how the two drifted apart with
+// nothing to notice: resize is write-only, so nobody could see the disagreement.
+const TERMINAL_MIN_COLS = 40;
+const TERMINAL_MIN_ROWS = 10;
+
+/**
+ * The geometry to apply AND report — there is only ever one answer to both.
+ * @param {{cols: number, rows: number}|null|undefined} proposed
+ * @returns {{cols: number, rows: number}|null}
+ */
+function clampTerminalDimensions(proposed) {
+  if (!proposed || !Number.isFinite(proposed.cols) || !Number.isFinite(proposed.rows)) return null;
+  return {
+    cols: Math.max(Math.trunc(proposed.cols), TERMINAL_MIN_COLS),
+    rows: Math.max(Math.trunc(proposed.rows), TERMINAL_MIN_ROWS),
+  };
+}
+
+/**
+ * What to do when the server reports the PTY's real geometry.
+ *
+ * The server is the authority: it owns the PTY the CLI is drawing for, and it
+ * can refuse a resize outright (`Session.resize` ignores small-viewport
+ * requests while a desktop connection holds an active sizing claim) without
+ * the asking client ever being told. A terminal that keeps its own WIDTH after
+ * such a refusal renders garbage, because Ink wraps its frame and counts its
+ * erase rows at the width it was told.
+ *
+ * ⚠️ COLUMNS ONLY. Rows are deliberately left alone, and adopting them was a
+ * real regression: a phone that took a desktop's 43 rows into a viewport with
+ * room for 18 painted an `.xterm-screen` far taller than its container, and
+ * because xterm's own viewport then had nothing to scroll, the bottom of the
+ * frame — the CLI's input line — sat below the container with no gesture that
+ * could reach it. Output visible, typing invisible, for as long as the claim
+ * stayed hot. Width is the axis the wrap arithmetic depends on; rows only
+ * decide how much is on screen at once, and keeping the local row count keeps
+ * the composer at the bottom of a viewport that scrolls.
+ *
+ * @param {{cols: number, rows: number}|null} local - what xterm currently holds
+ * @param {{cols: number, rows: number}|null} pty - what the server just reported
+ * @returns {{adopt: boolean, cols: number|null}}
+ */
+function reconcilePtyGeometry(local, pty) {
+  if (!pty || !Number.isFinite(pty.cols)) return { adopt: false, cols: null };
+  if (!local || !Number.isFinite(local.cols) || local.cols === pty.cols) return { adopt: false, cols: null };
+  return { adopt: true, cols: pty.cols };
+}
+
 if (typeof window !== 'undefined') {
   window.CodemanHistoryFormat = { formatHistoryBytes, computeHistoryTruncationNotice, computeRewriteScrollLine };
   window.CodemanFilePaths = { absoluteFilePathPattern, previewsInFileViewer, FILE_PREVIEW_EXTENSIONS };
@@ -1569,4 +1814,23 @@ if (typeof window !== 'undefined') {
     buildSplitPickerSessions,
     SPLIT_PANE_MIN_WIDTH,
   };
+  window.CodemanRenderLiveness = { shouldKickRenderer, RENDER_STALL_MS, RENDER_LIVENESS_POLL_MS };
+  window.CodemanFetchDeadline = {
+    terminalFetchDeadlineMs,
+    FETCH_DEADLINE_TAIL_MS,
+    FETCH_DEADLINE_FULL_MS,
+    FETCH_DEADLINE_MAX_MS,
+  };
+  window.CodemanDiag = { sanitizeDiagEntry, DIAG_ENTRY_MAX_CHARS };
+  window.CodemanDroppedOutput = {
+    shouldRetryDroppedOutputRecovery,
+    DROP_RECOVERY_DELAY_MS,
+    DROP_RECOVERY_MAX_ATTEMPTS,
+  };
+  window.CodemanTerminalGeometry = {
+    clampTerminalDimensions,
+    reconcilePtyGeometry,
+    TERMINAL_MIN_COLS,
+    TERMINAL_MIN_ROWS,
+  };
 }

src/web/public/home-sessions.js

@@ -212,6 +212,9 @@ Object.assign(CodemanApp.prototype, {
         dir: this._shortenHomePath ? this._shortenHomePath(session.workingDir) : session.workingDir || '',
         state,
         pill: HOME_SESSIONS_PILL_LABEL[state] || state,
+        // What the pane's footer says is still running in the background, straight off
+        // the session payload. Same field, same meaning as on the phone overview.
+        watching: typeof session.watching === 'string' ? session.watching : '',
         // Epoch ms, straight off the session payload; formatting happens at
         // render time so the clock below can redo it without a re-render.
         createdAt: Number(session.createdAt) || 0,
@@ -450,6 +453,12 @@ Object.assign(CodemanApp.prototype, {
     // what stops it ellipsizing.
     const meta = this._buildHomeSessionsMeta(row);
     meta.appendChild(pill);
+    // Built by the phone overview so both home screens word the badge identically.
+    // Guarded like every other cross-file call here: a stale cached mobile-overview.js
+    // must cost the badge, not the rail.
+    if (row.watching && typeof this._buildWatchingBadge === 'function') {
+      meta.appendChild(this._buildWatchingBadge(row.watching, 'home-sessions-pill'));
+    }
     item.appendChild(meta);
 
     return item;

src/web/public/index.html

@@ -1791,6 +1791,13 @@
                     </div>
                     <label class="switch switch-sm"><input type="checkbox" id="appSettingsAutoCopySelection"><span class="slider"></span></label>
                   </div>
+                  <div class="set-row" data-search="copy indent margin gutter dedent trim leading whitespace paste">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Trim the pane margin on copy</span>
+                      <span class="set-row-desc">Drop the left margin a full-screen agent CLI paints down its own edge, so copied text pastes flush instead of indented. Each CLI declares its own width, and the strip is never wider than the indent every selected line shares, so nesting inside the selection is kept. Claude Code and Codex declare a margin today; a shell, and any CLI that declares none, is left alone.</span>
+                    </div>
+                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsCopyStripMargin"><span class="slider"></span></label>
+                  </div>
                 </div>
               </div>
 

src/web/public/mobile-handlers.js

@@ -581,11 +581,10 @@ const KeyboardHandler = {
       this._settleRestoreScroll = false;
 
       if (typeof app !== 'undefined' && app.terminal) {
-        if (app.fitAddon) {
-          try {
-            app.fitAddon.fit();
-          } catch {}
-        }
+        // Floored fit, not a bare fitAddon.fit(): _shrinkPaddingToFit measures
+        // the leftover gap under the LAST row, so it has to run against the
+        // geometry xterm will actually keep (issue #464).
+        app.syncTerminalGeometry?.();
         if (this.keyboardVisible) this._shrinkPaddingToFit();
         // Following live output → bottom, as before. Reading history → back to
         // the pre-reflow anchor instead of being yanked down (#259).
@@ -601,25 +600,23 @@ const KeyboardHandler = {
     }, this.VIEWPORT_SETTLE_MS);
   },
 
-  /** Send current terminal dimensions to the server (one-shot, for keyboard open/close) */
+  /**
+   * Send the settled terminal dimensions to the server (one-shot, for keyboard
+   * open/close — `throttledResize` deliberately holds the PTY's shape for the
+   * whole animation, so this is what stops it going stale).
+   *
+   * ⚠️ Delegates rather than computing its own numbers. This used to re-read
+   * `proposeDimensions()` and floor only what it POSTed, so on a phone with the
+   * keyboard up — where the proposal is routinely under ten rows — the PTY was
+   * told ten and xterm kept six, which is the #464 divergence. Worse, it read
+   * the proposal AFTER `_shrinkPaddingToFit()` had moved the container, so even
+   * unfloored its answer could differ from the fit above it. `sendResize` fits,
+   * floors and applies in one step, and additionally gets the WS fast path and
+   * the detached-session yield this hand-rolled POST never had.
+   */
   _sendTerminalResize() {
-    if (typeof app === 'undefined' || !app.activeSessionId || !app.fitAddon) return;
-    try {
-      const dims = app.fitAddon.proposeDimensions();
-      if (dims) {
-        const cols = Math.max(dims.cols, 40);
-        const rows = Math.max(dims.rows, 10);
-        app._lastResizeDims = { cols, rows };
-        // Declare the viewport type so resize arbitration can ignore this
-        // while a desktop connection is sizing the same session.
-        const viewportType = MobileDetection.getDeviceType ? MobileDetection.getDeviceType() : 'mobile';
-        fetch(`/api/sessions/${app.activeSessionId}/resize`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ cols, rows, viewportType }),
-        }).catch(() => {});
-      }
-    } catch {}
+    if (typeof app === 'undefined' || !app.activeSessionId) return;
+    app.sendResize?.(app.activeSessionId)?.catch?.(() => {});
   },
 
   /**
@@ -676,10 +673,8 @@ const KeyboardHandler = {
         const currentPadding = parseInt(main.style.paddingBottom) || 0;
         const floor = Math.min(currentPadding, this._fixedBottomBarsHeight());
         main.style.paddingBottom = Math.max(floor, currentPadding - gap) + 'px';
-        if (app.fitAddon)
-          try {
-            app.fitAddon.fit();
-          } catch {}
+        // Floored, like every other fit of the main terminal (#464).
+        app.syncTerminalGeometry?.();
       }
     } catch {}
   },

src/web/public/mobile-overview.js

@@ -60,6 +60,14 @@ const MOBILE_OVERVIEW_RUN_MODES = [
   { mode: 'shell', label: 'Terminal / Shell', short: 'Shell' },
 ];
 
+/**
+ * The one word every surface puts on the watching badge, and the tooltip that says
+ * what the pane actually reported. Both live here so the phone overview, the desktop
+ * home rail and the rich sidebar rows cannot word the same badge three ways.
+ */
+const WATCHING_BADGE_TEXT = 'watching';
+const watchingBadgeTitle = (label) => 'Still running in the background: ' + label;
+
 /** Pill copy per state. Kept short: a phone row has ~90px for it. */
 const MOBILE_OVERVIEW_PILL_LABEL = {
   needs: 'needs you',
@@ -185,6 +193,10 @@ Object.assign(CodemanApp.prototype, {
         dir: this._shortenHomePath ? this._shortenHomePath(session.workingDir) : session.workingDir || '',
         state,
         pill: MOBILE_OVERVIEW_PILL_LABEL[state] || state,
+        // What the pane's own footer says is still running in the background ("1 monitor",
+        // "2 shells"), straight off the session payload. A row that has one is quiet
+        // because the agent is waiting for that, not because it is waiting for you.
+        watching: typeof session.watching === 'string' ? session.watching : '',
         // Epoch ms, straight off the session payload; formatting happens at
         // render time so the clock can redo it without a re-render.
         createdAt: Number(session.createdAt) || 0,
@@ -713,6 +725,8 @@ Object.assign(CodemanApp.prototype, {
     pill.textContent = row.pill;
     item.appendChild(pill);
 
+    if (row.watching) item.appendChild(this._buildWatchingBadge(row.watching, 'mobile-overview-pill'));
+
     const chevron = document.createElement('span');
     chevron.className = 'mobile-overview-chevron';
     chevron.setAttribute('aria-hidden', 'true');
@@ -734,6 +748,40 @@ Object.assign(CodemanApp.prototype, {
     return item;
   },
 
+  // ═══════════════════════════════════════════════════════════════
+  // Watching badge
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * The badge a session wears while work it started in the background is still
+   * running: a monitor, a backgrounded shell, a cloud session.
+   *
+   * It says one word, and the label the pane itself printed ("1 monitor") rides in
+   * the tooltip, because the badge shares a row with the state pill on the narrowest
+   * screen this app renders on. It does NOT replace that pill: an agent can arm a
+   * monitor and ask the user a question in the same breath, so the row still says
+   * "needs you" and this says what else is going on.
+   *
+   * Shared with the desktop home rail (home-sessions.js), for the same reason
+   * `_mobileOverviewState` is: one badge, one wording, one place to change it. The
+   * caller names its own pill class, because each surface styles its pills itself and
+   * the phone's live inside a media query the desktop never enters.
+   */
+  _buildWatchingBadge(label, baseClass) {
+    const badge = document.createElement('span');
+    const base = baseClass || 'mobile-overview-pill';
+    badge.className = base + ' ' + base + '--watching';
+    badge.setAttribute('data-i18n-skip', '');
+    badge.textContent = WATCHING_BADGE_TEXT;
+    // The label rides in BOTH, because a tooltip is desktop-only: a phone has no hover
+    // target, and a screen reader gets the one word either way. This is the surface the
+    // badge was built for first, so "watching" with no way to learn what would be the
+    // wrong place to save a line.
+    badge.title = watchingBadgeTitle(label);
+    badge.setAttribute('aria-label', watchingBadgeTitle(label));
+    return badge;
+  },
+
   // ═══════════════════════════════════════════════════════════════
   // Age stamps: started / how long in this state
   // ═══════════════════════════════════════════════════════════════

src/web/public/mobile.css

@@ -694,6 +694,22 @@ html.mobile-init .file-browser-panel {
     display: none;
   }
 
+  /* The exited-agent mute, a third time, for the phone (Ark0N/Codeman#446).
+     The rule above enlarges the working dot and gives it a green glow with
+     !important, and `status` deliberately stays `busy` for a pane whose agent
+     died mid-turn — so without this a phone renders a 9px grey dot still
+     wearing the green halo, beside a badge reading "exited". Measured; the
+     desktop rules cannot reach it, since they declare no box-shadow and lose
+     to !important anyway. !important here for the reason the glow needs it:
+     the skin block in styles.css outranks any plain class rule in this file.
+     ⚠ The alert classes and the error state are excluded exactly as they are
+     on desktop — a colour that means "this needs you" outranks "it exited". */
+  .session-tab.tab-agent-exited:not(.tab-alert-action):not(.tab-alert-idle) .tab-status:not(.error) {
+    background: var(--text-muted) !important;
+    box-shadow: none !important;
+    opacity: 0.5;
+  }
+
   /* Truncate tab names more aggressively on mobile */
   .session-tab .tab-name {
     max-width: 50px;
@@ -933,40 +949,41 @@ html.mobile-init .file-browser-panel {
     border-color: rgba(16, 185, 129, 0.5);
   }
 
-  /* Gemini mode colors on mobile */
+  /* Gemini mode colors on mobile. Same `!important` rationale as the pi block below. */
   .btn-toolbar.btn-run.mode-gemini,
   .btn-toolbar.btn-run-gear.mode-gemini {
-    background: #10243f;
-    border-color: rgba(96, 165, 250, 0.3);
-    color: #dbeafe;
+    background: #10243f !important;
+    border-color: rgba(96, 165, 250, 0.3) !important;
+    color: #dbeafe !important;
   }
 
   .btn-toolbar.btn-run.mode-gemini:active,
   .btn-toolbar.btn-run-gear.mode-gemini:active {
-    background: #174ea6;
-    border-color: rgba(96, 165, 250, 0.5);
+    background: #174ea6 !important;
+    border-color: rgba(96, 165, 250, 0.5) !important;
   }
 
-  /* Antigravity mode colors on mobile */
+  /* Antigravity mode colors on mobile. Same `!important` rationale as the pi block below. */
   .btn-toolbar.btn-run.mode-antigravity,
   .btn-toolbar.btn-run-gear.mode-antigravity {
-    background: #0b2b33;
-    border-color: rgba(34, 211, 238, 0.3);
-    color: #cffafe;
+    background: #0b2b33 !important;
+    border-color: rgba(34, 211, 238, 0.3) !important;
+    color: #cffafe !important;
   }
 
   .btn-toolbar.btn-run.mode-antigravity:active,
   .btn-toolbar.btn-run-gear.mode-antigravity:active {
-    background: #0e7490;
-    border-color: rgba(34, 211, 238, 0.5);
+    background: #0e7490 !important;
+    border-color: rgba(34, 211, 238, 0.5) !important;
   }
 
   /* Pi mode colors on mobile.
      `!important` is load-bearing here, not noise: styles.css nests its skin rules
-     inside `html:not([data-skin="og"])`, so a bare `.btn-toolbar.btn-run` in there
-     resolves to (0,2,1) and outranks this (0,2,0) `.mode-pi` pair regardless of
-     load order. The antigravity block right above omits it and is consequently
-     dead on every non-og skin (i.e. on the default) — do not copy that. */
+     inside `html:not([data-skin="og"])`, so a bare `.btn-toolbar.btn-run` or
+     `.btn-toolbar.btn-run-gear` in there outranks this `.mode-pi` pair regardless
+     of load order. Without it the gear half keeps the skin accent while the body
+     takes the nested block's mode colour, so the split button renders two-tone
+     (gemini and antigravity shipped that way until they got `!important` too). */
   .btn-toolbar.btn-run.mode-pi,
   .btn-toolbar.btn-run-gear.mode-pi {
     background: #33121f !important;
@@ -2961,6 +2978,13 @@ html.mobile-init .file-browser-panel {
     color: var(--green);
   }
 
+  /* Accent, and none of the three above: a session watching work it started itself
+     is not asking the user for anything, and red and yellow are what say it is. */
+  .mobile-overview-pill--watching {
+    border-color: var(--accent);
+    color: var(--accent);
+  }
+
   .mobile-overview-chevron {
     flex-shrink: 0;
     color: var(--text-muted);

src/web/public/notification-manager.js

@@ -512,8 +512,10 @@ class NotificationManager {
     }
     // Re-fit terminal and send resize to PTY so this client's dimensions win.
     // Fixes broken layout when switching between desktop and mobile on the same session.
-    if (this.app?.fitAddon && this.app?.activeSessionId) {
-      this.app.fitAddon.fit();
+    // sendResize fits (floored) as its first synchronous step, so the bare
+    // fit that used to precede it was both redundant and a chance to leave
+    // xterm at the unfloored proposal (#464).
+    if (this.app?.activeSessionId) {
       this.app.sendResize(this.app.activeSessionId);
     }
   }

src/web/public/panels-ui.js

@@ -5276,8 +5276,10 @@ Object.assign(CodemanApp.prototype, {
           try { localStorage.removeItem('codeman-active-session'); } catch {}
           this.renderSessionTabs();
           this.renderMuxSessions();
-          this.terminal.clear();
-          this.terminal.reset();
+          // Not a replay path, so the ordering hazard does not apply here — but
+          // there is one way to clear this terminal and this is it, so a future
+          // caller cannot copy a clear()+reset() pair out of here into one.
+          this._resetTerminalForReplay();
           this.toast('All sessions and tmux killed', 'success');
         }
       } else {
@@ -5286,8 +5288,7 @@ Object.assign(CodemanApp.prototype, {
         this.activeSessionId = null;
         try { localStorage.removeItem('codeman-active-session'); } catch {}
         this.renderSessionTabs();
-        this.terminal.clear();
-        this.terminal.reset();
+        this._resetTerminalForReplay();
         this.toast('All tabs removed, tmux still running', 'info');
       }
     } catch (err) {

src/web/public/ralph-panel.js

@@ -155,10 +155,9 @@ Object.assign(CodemanApp.prototype, {
       if (xtermViewport && scrollTop !== undefined) {
         xtermViewport.scrollTop = scrollTop;
       }
-      // Refit terminal to new container size
-      if (this.terminal && this.fitAddon) {
-        this.fitAddon.fit();
-      }
+      // Refit terminal to new container size. Through the one owner so the
+      // floor that is reported to the PTY is also the one xterm holds (#464).
+      this.syncTerminalGeometry?.();
     });
   },
 

src/web/public/settings-ui.js

@@ -14,6 +14,14 @@
 Object.assign(CodemanApp.prototype, {
   // Hooks (Claude Code hook events)
   _onHookIdlePrompt(data) {
+    // A prompt the server opened ALREADY acknowledged raises no alert here. Today that
+    // means the session is watching work it started itself (`acknowledgedReason` reads
+    // "watching 1 monitor"), so the pane is quiet because the agent is waiting for its
+    // own monitor, not for you. The item still exists and still shows in the drawer;
+    // only the tab alert and the desktop notification are declined. A page that reloads
+    // instead of receiving this event reaches the same conclusion from `acknowledgedAt`
+    // in seedApprovals (approvals-ui.js).
+    if (data.acknowledgedReason) return;
     // Always track pending hook - alert will show when switching away from session
     if (data.sessionId) {
       this.setPendingHook(data.sessionId, 'idle_prompt');
@@ -446,6 +454,8 @@ Object.assign(CodemanApp.prototype, {
     // overwrites the system clipboard on a gesture the user may have meant only as
     // a way to read, so it is opt-in rather than a default anyone has to discover.
     document.getElementById('appSettingsAutoCopySelection').checked = settings.autoCopySelection === true;
+    // Default ON, so an absent key reads as enabled rather than as off.
+    document.getElementById('appSettingsCopyStripMargin').checked = settings.copyStripMargin !== false;
     document.getElementById('appSettingsTerminalFont').value = settings.terminalFontFamily || '';
     this.populateTerminalFontWeight(document.getElementById('appSettingsTerminalFontWeight'), settings.terminalFontWeight);
     this.populateTerminalFontWeight(
@@ -2137,6 +2147,7 @@ Object.assign(CodemanApp.prototype, {
       tunnelEnabled: document.getElementById('appSettingsTunnelEnabled').checked,
       localEchoEnabled: document.getElementById('appSettingsLocalEcho').checked,
       autoCopySelection: document.getElementById('appSettingsAutoCopySelection').checked,
+      copyStripMargin: document.getElementById('appSettingsCopyStripMargin').checked,
       terminalFontFamily: document.getElementById('appSettingsTerminalFont').value.trim(),
       terminalFontWeight: this.readTerminalFontWeight(document.getElementById('appSettingsTerminalFontWeight')),
       terminalFontWeightBold: this.readTerminalFontWeight(
@@ -2363,6 +2374,10 @@ Object.assign(CodemanApp.prototype, {
       // and absent from SettingsUpdateSchema (.strict()), so sending it would
       // 400 the whole settings PUT.
       autoCopySelection: _acs,
+      // What the clipboard gets is a property of what this device is looking
+      // at, and the key is absent from SettingsUpdateSchema (.strict()), so
+      // sending it would 400 the whole settings PUT.
+      copyStripMargin: _csm,
       // Per-device by nature (the font must exist on the device) and absent
       // from SettingsUpdateSchema (.strict()) — sending it would 400 the PUT.
       terminalFontFamily: _tff,
@@ -3097,7 +3112,7 @@ Object.assign(CodemanApp.prototype, {
     const changed = orientationChanged || previousDetail !== detail || previousSort !== sort;
     if (orientationChanged) {
       this.updateTabOverflowMode?.();
-      if (!settleRailWidth) this.fitAddon?.fit();
+      if (!settleRailWidth) this.syncTerminalGeometry?.();
     }
     // applyTabWrapSettings() is the ONE owner of tabs-show-folder and is
     // rail-aware, so it has to run AFTER the two attributes above — the
@@ -3372,7 +3387,7 @@ Object.assign(CodemanApp.prototype, {
           'terminalFontFamily', 'terminalFontWeight', 'terminalFontWeightBold',
           'language',
           'terminalWheelLocalScrollback',
-          'autoCopySelection',
+          'autoCopySelection', 'copyStripMargin',
           'showSessionButton', 'showAwayDigestButton', 'showCronButton',
           'showTabDetachButton',
           'mobileOverviewEnabled',

src/web/public/styles.css

@@ -2433,6 +2433,51 @@ html[data-tab-orientation='vertical'] .tab-rail .session-tab .tab-name-prefix {
   display: inline-flex;
 }
 
+/* The agent inside the pane has exited (Ark0N/Codeman#446). Unlike the badge
+   above this one carries text the server computed, so it is added and removed
+   by the renderer rather than toggled by a class. */
+.session-tab .tab-exited-badge {
+  display: inline-flex;
+  align-items: center;
+  flex: 0 0 auto;
+  font-size: 0.55rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  padding: 1px 4px;
+  margin-left: 4px;
+  border-radius: 3px;
+  white-space: nowrap;
+  background: rgba(248, 113, 113, 0.16);
+  color: var(--danger);
+}
+
+/* An exited agent quiets the status dot, which otherwise reports `status` and
+   so stays green (or pulses, for a session the exit caught mid-turn) beside a
+   badge saying the agent is gone. `status` itself is deliberately untouched —
+   `error` is the PTY-exit breaker's value and makes the browser offer a restart
+   — so this is a rendering rule only, and it matches `.tab-status.ended`.
+
+   ⚠ Three states are excluded BY HAND rather than by cascade, the same way the
+   rich-rail dot rules below do it: a dot turning red or yellow because a
+   session is blocked on a human outranks "the agent exited", and this selector
+   is specific enough (0,5,0) to have beaten those (0,3,0) rules otherwise. The
+   third is `.tab-status.error` (0,2,0), which is the PTY-exit breaker's state
+   and the one the browser answers with a "restart it?" confirm — the same
+   argument that protects the two alert classes, and it reaches the dot rather
+   than the tab, which is why the `:not()` sits on `.tab-status` here and on
+   `.session-tab` there. The spinner ring is a pseudo-element the skin blocks
+   cannot reach, so it needs hiding explicitly rather than by unsetting the
+   animation. */
+.session-tab.tab-agent-exited:not(.tab-alert-action):not(.tab-alert-idle) .tab-status:not(.error) {
+  background: var(--text-muted);
+  opacity: 0.5;
+  animation: none;
+}
+.session-tab.tab-agent-exited:not(.tab-alert-action):not(.tab-alert-idle) .tab-status:not(.error)::after {
+  display: none;
+}
+
 /* ===== Tab action icons: active tab only =================================
    All three per-tab icons live in a .tab-actions wrapper (in flow; it adds
    no width of its own while the children keep the width:0 collapse above).
@@ -3817,6 +3862,37 @@ body.solo-mode .btn-lifecycle-log {
   background: transparent !important;
 }
 
+/* The terminal is wider than the box that shows it (issue #464). Two causes,
+   one affordance: another device holds the sizing claim so this terminal has
+   adopted a width it did not ask for, or the 40-column floor has widened it
+   past a narrow container. Either way the text is rendered CORRECTLY and simply
+   does not fit, and without horizontal reach the right-hand columns sit behind
+   .terminal-container's clip with no gesture that can get to them — measured at
+   360px, font 24: 218px of the pane, 38% of it, unreachable.
+   Present only while that is true; _syncTerminalOverflowAffordance() owns it. */
+.terminal-container.term-overflows-x {
+  /* ⚠️ BOTH axes, explicitly. mobile.css loads after this file and sets
+     `.terminal-container { overflow: visible }` — a bare `overflow-x` would
+     then leave overflow-y computing to `auto` (CSS promotes a `visible` paired
+     with a non-visible axis), handing the browser a vertical scroll container
+     the terminal's own touch handler does not know about. */
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+/* xterm's own element is width:100% above, so the container would see no
+   overflow to scroll even though .xterm-screen is wider than both. */
+.terminal-container.term-overflows-x .xterm {
+  width: max-content;
+  min-width: 100%;
+}
+/* ⚠️ NO `touch-action: pan-x` here, deliberately. The terminal's own touchmove
+   handler pans this container (see `canPanHorizontally` in terminal-ui.js),
+   because `touchstart` preventDefault()s every 'content' tap and that cancels
+   a native pan before it can start. Granting the browser pan-x as well would
+   double-handle the gestures where that preventDefault does NOT run — a tap on
+   a scrolled-up viewport — moving the pane twice for one finger. The
+   `touch-action: none` the other rules set is what keeps JS the sole owner. */
+
 /* Touch devices: prevent browser from claiming the touch gesture before
    our JS touchmove handler fires. Without this, the browser starts native
    scrolling during the first few px of finger travel and ignores our
@@ -12382,6 +12458,17 @@ kbd {
   color: var(--text-dim);
   font-size: 0.68rem;
 }
+/* Why this card is not blinking at anyone: the session is watching work it
+   started itself. Accent, like the watching badge on a session row, and never
+   the red or yellow that mean a human is needed. */
+.approval-quiet {
+  margin-bottom: 6px;
+  color: var(--accent);
+  font-size: 0.68rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
 .approval-summary {
   color: var(--text);
   font-size: 0.76rem;
@@ -15142,11 +15229,31 @@ html:not([data-skin="og"]) {
   color: #061c20;
 }
 .btn-toolbar.btn-run.mode-codex:hover { box-shadow: 0 0 14px -2px rgba(43, 203, 187, 0.45); }
-/* Pi keeps its rose identity on the non-og skins. This rule has to live INSIDE
-   this nested block: the generic `.btn-toolbar.btn-run` above resolves to (0,3,1)
-   here and would otherwise beat the base sheet's (0,3,0) `.mode-pi` pair, which
-   is exactly why gemini's and antigravity's gradients render as generic claude
-   blue on the default skin. */
+/* Gemini, Antigravity, Pi, OMP, Grok and DeepSeek all keep their own identity
+   on the non-og skins. Each rule has to live INSIDE this nested block: the
+   generic `.btn-toolbar.btn-run` above resolves to (0,3,1) here and would
+   otherwise beat the base sheet's (0,3,0) `.mode-<id>` pair — which is exactly
+   what gemini/antigravity/omp did until this fix, rendering as generic claude
+   blue on `daylight-blue`, the actual DEFAULT skin for a fresh install
+   (`index.html`'s pre-paint script), not just a corner case on `og`. */
+.btn-toolbar.btn-run.mode-gemini {
+  background: linear-gradient(135deg, #174ea6, #4f46e5);
+  border-color: #123a7a;
+  color: #dbeafe;
+}
+.btn-toolbar.btn-run.mode-gemini:hover { box-shadow: 0 0 14px -2px rgba(96, 165, 250, 0.45); }
+.btn-toolbar.btn-run.mode-antigravity {
+  background: linear-gradient(135deg, #0e7490, #0891b2);
+  border-color: #0b5566;
+  color: #cffafe;
+}
+.btn-toolbar.btn-run.mode-antigravity:hover { box-shadow: 0 0 14px -2px rgba(34, 211, 238, 0.45); }
+.btn-toolbar.btn-run.mode-omp {
+  background: linear-gradient(135deg, #4f46e5, #6366f1);
+  border-color: #3730a3;
+  color: #e0e7ff;
+}
+.btn-toolbar.btn-run.mode-omp:hover { box-shadow: 0 0 14px -2px rgba(129, 140, 248, 0.45); }
 .btn-toolbar.btn-run.mode-pi {
   background: linear-gradient(135deg, #be185d, #f472b6);
   border-color: #be185d;
@@ -16249,6 +16356,17 @@ html[data-tab-orientation='vertical'] .home-sessions {
   color: color-mix(in srgb, var(--green) 45%, var(--text-muted));
 }
 
+/* Accent, deliberately none of the three above: a session that is watching something
+   it started (a monitor, a backgrounded shell, a cloud session) is not asking for
+   anything, so it must not borrow the red or the yellow that mean it is. This badge
+   sits BESIDE the state pill rather than replacing it, since an agent can arm a
+   monitor and ask a question in the same breath. */
+.home-sessions-pill--watching {
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+  border-color: color-mix(in srgb, var(--accent) 40%, transparent);
+  color: var(--accent);
+}
+
 /* Row accents: same language as the session tabs and the phone overview — red
    means a question is pending, yellow means it wants input, green means work is
    happening. Nothing else on this screen may reuse these colors. */
@@ -18311,6 +18429,25 @@ html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail
   color: color-mix(in srgb, var(--green) 45%, var(--text-muted));
 }
 
+/* An exited agent (Ark0N/Codeman#446): neutral, like the muted dot beside it.
+   No green at all, since nothing is running behind this row. */
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--exited,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--exited {
+  background: color-mix(in srgb, var(--text-muted) 10%, transparent);
+  border-color: color-mix(in srgb, var(--text-muted) 30%, var(--border));
+  color: var(--text-muted);
+}
+
+/* Accent, deliberately none of the three above: a watching session is waiting for
+   work it started itself, not for the user, and the red and yellow here are spoken
+   for by sessions that ARE waiting for the user. */
+html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--watching,
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact) .tab-rail .tab-pill--watching {
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+  border-color: color-mix(in srgb, var(--accent) 40%, transparent);
+  color: var(--accent);
+}
+
 /* Three lines of content per row instead of two, so give them room to breathe
    and stop the row actions crowding the pill.
 
@@ -18457,6 +18594,26 @@ html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail
   border-width: 2px;
 }
 
+/* The exited-agent mute, again, for the rich rail (Ark0N/Codeman#446).
+   The strip's rule is (0,5,0) and the three state rules above are (0,9,1), so
+   on this rail an exited session kept a full green dot and the working halo
+   beside a badge reading "exited" — measured, the contradiction the mute
+   exists to remove. This twin matches their (0,9,1) exactly and therefore MUST
+   stay below them in source order; moving it above silently restores the green
+   dot. It also clears the halo, which is a box-shadow the strip's rule never
+   had to think about.
+   ⚠ The alert exclusions are repeated by hand for the same reason they are on
+   the rules above: a dot turning red or yellow because a session is blocked on
+   a human outranks "the agent exited". */
+html[data-tab-orientation='vertical'][data-tab-rail-detail='rich']:not(.tab-rail-compact)
+  .tab-rail
+  .session-tab.tab-agent-exited:not(.tab-alert-action):not(.tab-alert-idle)
+  .tab-status:not(.error) {
+  background: var(--text-muted);
+  opacity: 0.5;
+  box-shadow: none;
+}
+
 /* Card accents: the same three colours as every other session surface, and the
    same two blinks the home rail runs. `tab-alert-*` draws its own ::before ring
    on top of this for the sessions that are genuinely blocked on a human; these

src/web/public/sw.js

@@ -18,7 +18,16 @@
  * @see src/push-store.ts -- server-side VAPID key management and subscription CRUD
  */
 
-const CACHE_NAME = 'codeman-v1';
+// Build identity. scripts/build.mjs rewrites this declaration after it content-
+// hashes the assets; the literal below is what dev serves, and dev wants a
+// stable key.
+//
+// Why the cache key MUST carry it: `activate` deletes every cache whose key is
+// not the current one, so the old constant key meant that cleanup never deleted
+// anything — hashed assets from every release ever deployed accumulated in one
+// bucket until the origin hit its storage quota.
+const BUILD_ID = 'dev';
+const CACHE_NAME = `codeman-${BUILD_ID}`;
 
 // Reverse-proxy base path: the worker is served at `<base>/sw.js`, so its own
 // location tells us the mount prefix ('' at root, or '/codeman'). Every URL below
@@ -27,27 +36,27 @@ const CACHE_NAME = 'codeman-v1';
 const SW_BASE = self.location.pathname.replace(/\/sw\.js$/, '');
 const B = (p) => (p && p[0] === '/' ? SW_BASE + p : p);
 
+// Content-hashed assets. scripts/build.mjs rewrites this declaration with the
+// filenames it actually emitted; dev has no hashing, so the empty literal below
+// is correct there and the unhashed modules are simply cached on first use by
+// the runtime handler further down.
+//
+// This list used to be maintained by hand with the PRE-hash names, which the
+// build then renamed — so in production every entry 404'd and the silent
+// `.catch()` in install swallowed all of it. Measured against a running
+// instance: 15 of 23 entries failed. Offline still worked, because the fetch
+// handler caches every successful GET at runtime, but the precache warmed
+// nothing while looking like it did. Deriving it from the same manifest that
+// renames the files is the only thing that keeps the two from drifting again.
+const HASHED_ASSETS = [];
+
 // Core app shell -- cached on install for instant startup
 const APP_SHELL = [
   '/',
-  '/styles.css',
-  '/mobile.css',
-  '/constants.js',
-  '/app.js',
-  '/api-client.js',
-  '/terminal-ui.js',
-  '/session-ui.js',
-  '/settings-ui.js',
-  '/panels-ui.js',
-  '/notification-manager.js',
-  '/mobile-handlers.js',
-  '/keyboard-accessory.js',
-  '/voice-input.js',
+  ...HASHED_ASSETS.map((p) => '/' + p),
   '/vendor/xterm.min.js',
   '/vendor/xterm-addon-fit.min.js',
   '/vendor/xterm-addon-unicode11.min.js',
-  '/vendor/xterm-zerolag-input.js',
-  '/vendor/xterm-predictive-echo.js',
   '/vendor/xterm.css',
   '/icon-192.png',
   '/icon-512.png',
@@ -102,7 +111,17 @@ self.addEventListener('fetch', (event) => {
         }
         return response;
       })
-      .catch(() => caches.match(request))
+      // ignoreSearch, or the precache can never be hit. `renderIndexHtml` runs
+      // `cacheBustAssets`, which appends `?v=<mtime>` to EVERY same-origin
+      // `.js`/`.css` reference — content-hashed names included, so the page asks
+      // for `/app.556be563.js?v=1789423735875` while the precache stored
+      // `/app.556be563.js`. `caches.match` is query-sensitive by default, so
+      // every precached entry was unreachable and only `/`, the icons and the
+      // manifest could ever be served offline.
+      //
+      // It also makes runtime-cached entries survive an mtime change: the same
+      // file re-requested under a new `?v=` still matches the copy already held.
+      .catch(() => caches.match(request, { ignoreSearch: true }))
   );
 });
 

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

@@ -154,7 +154,7 @@ Object.assign(CodemanApp.prototype, {
       this._persistTabRailWidth(preferred);
       try {
         if (this.activeSessionId && this.sendResize) await this.sendResize(this.activeSessionId);
-        else this.fitAddon?.fit();
+        else this.syncTerminalGeometry?.();
         this._updateConnectionLinesImmediate?.();
       } catch (error) {
         console.warn('Failed to resize terminal after rail resize:', error);

src/web/public/terminal-split.js

@@ -188,7 +188,18 @@
         if (ev.type === 'keydown' && global.app?.shouldCopyTerminalSelectionFromShortcut?.(ev)) {
           const raw = this.terminal?.getSelection?.() || '';
           const isColumnSelection = this.terminal?._core?._selectionService?._activeSelectionMode === 3;
-          const selection = isColumnSelection ? raw : (global.CodemanCopySelection?.clean?.(raw) ?? raw);
+          // Both clean options are read for THIS pane, never the primary one:
+          // the gutter width comes from this.sessionId's own run mode, and the
+          // partial-first-line flag from this terminal's own selection range.
+          // Passing neither left Pane B keeping a margin Pane A dropped, on the
+          // same split and the same keystroke.
+          const range = global.app?._normalisedSelectionRange?.(this.terminal);
+          const selection = isColumnSelection
+            ? raw
+            : (global.CodemanCopySelection?.clean?.(raw, {
+                margin: global.app?._cliGutterColumns?.(this.sessionId) ?? 0,
+                firstLinePartial: !!range && range.start.x > 0,
+              }) ?? raw);
           if (selection.trim()) {
             ev.preventDefault();
             void global.app._copyText?.(selection).then((ok) => {

src/web/public/terminal-ui.js

@@ -368,10 +368,18 @@ Object.assign(CodemanApp.prototype, {
         // part of a row selects real padding spaces, which are truthy, so testing
         // the raw text would spend this press on a copy of nothing and make the
         // user press again to interrupt.
-        const selection = this.cleanedTerminalSelection();
+        //
+        // ⚠️ The gate cleans, and the copy is handed the RAW selection, because
+        // copyTerminalSelection cleans again on its own. The margin strip is not
+        // idempotent: a second pass takes up to `margin` more columns off what
+        // the first pass left, so passing the cleaned string through dedented a
+        // Claude or Codex copy twice. Every other copy path already hands over
+        // the raw selection or reads it live.
+        const raw = this.terminal?.hasSelection?.() ? this.terminal.getSelection() : '';
+        const selection = this.cleanedTerminalSelection(raw);
         if (selection.trim()) {
           ev.preventDefault();
-          void this.copyTerminalSelection(selection);
+          void this.copyTerminalSelection(raw);
           return false;
         }
         // Nothing worth copying. The clear is for feedback, not for the
@@ -543,6 +551,14 @@ Object.assign(CodemanApp.prototype, {
       this.terminal.onRender(() => this._syncMobileHelperTextareaToCursor());
     }
 
+    // Renderer liveness — see _startRenderLivenessWatchdog. Registered for every
+    // device, not just touch: the rAF-discard behaviour is worst on an iOS PWA
+    // but a stale handle wedges the debouncer identically anywhere it happens.
+    this.terminal.onRender(() => {
+      this._lastRenderAt = Date.now();
+    });
+    this._startRenderLivenessWatchdog();
+
     // CJK IME input — textarea in index.html, just wire up send
     this._cjkInput = null;
     if (typeof CjkInput !== 'undefined') {
@@ -579,12 +595,12 @@ Object.assign(CodemanApp.prototype, {
     if (isMobileSafari) {
       // Wait for layout, then fit multiple times to ensure proper sizing
       requestAnimationFrame(() => {
-        this.fitAddon.fit();
+        this.syncTerminalGeometry();
         // Double-check after another frame
-        requestAnimationFrame(() => this.fitAddon.fit());
+        requestAnimationFrame(() => this.syncTerminalGeometry());
       });
     } else {
-      this.fitAddon.fit();
+      this.syncTerminalGeometry();
     }
     // Whenever that first fit runs — on this line, or a frame or two later on
     // the mobile-Safari branch above — it measures whatever font the browser has
@@ -756,6 +772,32 @@ Object.assign(CodemanApp.prototype, {
       let longPressStartX = 0;
       let longPressStartY = 0;
       let touchStartY = 0;
+      let touchStartX = 0;
+      // 'x' | 'y' | null — locked on the first travel past the tap slop, so a
+      // diagonal drag cannot pan and scroll at the same time.
+      let panAxis = null;
+      /**
+       * Can this gesture pan sideways? Only while the terminal is wider than
+       * the box showing it (`.term-overflows-x`, set by
+       * `_syncTerminalOverflowAffordance`).
+       *
+       * ⚠️ This has to be done in JS. `touch-action: pan-x` alone does nothing
+       * for the sessions the affordance targets: `touchstart` calls
+       * preventDefault() for every 'content' tap — the normal case for a
+       * mouse-tracking TUI sitting at the bottom of its buffer — which cancels
+       * the browser's pan before it starts. Measured under touch emulation, a
+       * 140px horizontal swipe reached scrollLeft 141 without that
+       * preventDefault and 0 with it. It only ever worked for shell sessions,
+       * while scrolled up, or with a mouse.
+       */
+      const canPanHorizontally = () =>
+        // Both halves. The class is what makes the container a scroller at all
+        // (`overflow-x: auto`); without it `scrollLeft` silently stays 0, and a
+        // gesture locked to 'x' on that basis would do nothing AND suppress the
+        // vertical scroll it should have been. The measurement is the second
+        // half because sub-pixel cell widths can leave a stray pixel of
+        // scrollWidth on a terminal that fits perfectly well.
+        container.classList.contains('term-overflows-x') && container.scrollWidth - container.clientWidth > 1;
       let tapStartedWithTerminalFocus = false;
       let tapStartIntentCache = null;
       // px — ignore micro-drift to distinguish tap from scroll. Shared with the
@@ -775,6 +817,8 @@ Object.assign(CodemanApp.prototype, {
             touchLastX = ev.touches[0].clientX;
             touchLastY = ev.touches[0].clientY;
             touchStartY = touchLastY;
+            touchStartX = touchLastX;
+            panAxis = null;
             velocity = 0;
             pixelAccum = 0;
             isTouching = true;
@@ -843,8 +887,15 @@ Object.assign(CodemanApp.prototype, {
           }
           if (ev.touches.length === 1 && isTouching) {
             const touchY = ev.touches[0].clientY;
-            if (!didScroll && Math.abs(touchY - touchStartY) >= TAP_THRESHOLD) {
-              didScroll = true;
+            const touchX = ev.touches[0].clientX;
+            if (!didScroll) {
+              const travelY = Math.abs(touchY - touchStartY);
+              const travelX = Math.abs(touchX - touchStartX);
+              const sideways = canPanHorizontally() && travelX >= TAP_THRESHOLD;
+              if (travelY >= TAP_THRESHOLD || sideways) {
+                didScroll = true;
+                panAxis = sideways && travelX > travelY ? 'x' : 'y';
+              }
             }
             // Below the tap threshold, treat the gesture as a potential tap:
             // don't preventDefault (iOS needs click synthesis to show the
@@ -854,6 +905,15 @@ Object.assign(CodemanApp.prototype, {
             // fling, so a jittery tap would both position the cursor AND scroll.
             if (!didScroll) return;
             ev.preventDefault();
+            if (panAxis === 'x') {
+              // Pan the container, and touch nothing the vertical path owns —
+              // no pixelAccum, no velocity, so touchend cannot turn a sideways
+              // swipe into a momentum fling down the scrollback.
+              container.scrollLeft -= touchX - touchLastX;
+              touchLastX = touchX;
+              touchLastY = touchY;
+              return;
+            }
             const delta = touchLastY - touchY; // positive = scroll down
             pixelAccum += delta;
             velocity = delta * 1.2;
@@ -991,10 +1051,6 @@ Object.assign(CodemanApp.prototype, {
     this._resizeTimeout = null;
     this._lastResizeDims = null;
 
-    // Minimum terminal dimensions to prevent vertical text wrapping
-    const MIN_COLS = 40;
-    const MIN_ROWS = 10;
-
     const throttledResize = () => {
       if (this._tabRailResizeOwnsObserver) return;
       // Trailing-edge debounce: ALL resize work (fit + clear + SIGWINCH) happens
@@ -1014,10 +1070,6 @@ Object.assign(CodemanApp.prototype, {
       }
       this._resizeTimeout = setTimeout(() => {
         this._resizeTimeout = null;
-        // Fit xterm.js to final container dimensions
-        if (this.fitAddon) {
-          this.fitAddon.fit();
-        }
         // Flush any stale flicker buffer before clearing viewport
         if (this.flickerFilterBuffer) {
           if (this.flickerFilterTimeout) {
@@ -1026,32 +1078,47 @@ Object.assign(CodemanApp.prototype, {
           }
           this.flushFlickerBuffer();
         }
-        // Skip server resize while mobile keyboard is visible — sending SIGWINCH
-        // causes Ink to re-render at the new row count, garbling terminal output.
-        // Local fit() still runs so xterm knows the viewport size for scrolling.
+        // Hold the PTY's shape while the virtual keyboard is up: a SIGWINCH per
+        // step of the OS animation makes Ink re-render at a row count that is
+        // about to change again, and shifts the accessory toolbar mid-typing.
+        // KeyboardHandler's settle timer sends ONE resize once the animation
+        // stops (`_sendTerminalResize`), so the PTY is not left stale.
         const keyboardUp = typeof KeyboardHandler !== 'undefined' && KeyboardHandler.keyboardVisible;
         // Same yield as sendResize: never resize a PTY whose session is showing
         // in its own window. Dragging the dashboard's border must not reshape it.
         const detachedElsewhere = !this.isSoloWindow && this.detachedSessions?.has(this.activeSessionId);
-        if (this.activeSessionId && !keyboardUp && !detachedElsewhere) {
-          const dims = this.fitAddon.proposeDimensions();
-          // Enforce minimum dimensions to prevent layout issues
-          const cols = dims ? Math.max(dims.cols, MIN_COLS) : MIN_COLS;
-          const rows = dims ? Math.max(dims.rows, MIN_ROWS) : MIN_ROWS;
+        // ⚠️ Whether to fit is the SAME question as whether to send (issue #464).
+        // This block used to fit unconditionally and skip only the SIGWINCH,
+        // which is the one combination that cannot be right: it moves xterm to
+        // a shape the PTY is never told about, and Claude Code computes its
+        // repaints from the shape it was told. Withhold both, or neither —
+        // a reflow nothing is rendering for buys nothing and costs correctness.
+        const dims =
+          this.activeSessionId && !keyboardUp && !detachedElsewhere ? this._geometryForResizeRequest() : null;
+        // ⚠️ A null measurement is NOT a reason to report the floor. It used to
+        // fall back to a bare 40x10, which tells the PTY a shape nothing measured
+        // and xterm does not hold — the write-only guess this whole change exists
+        // to remove. An unmeasurable terminal has nothing to say; the next
+        // resize event says it.
+        if (dims) {
+          const { cols, rows } = dims;
           // Only send resize if dimensions actually changed
           if (!this._lastResizeDims || cols !== this._lastResizeDims.cols || rows !== this._lastResizeDims.rows) {
             // Clear viewport + scrollback ONLY when dimensions actually change.
-            // fitAddon.fit() reflows content: lines at old width may wrap to more rows,
-            // pushing overflow into scrollback. Ink's cursor-up count is based on the
-            // pre-reflow line count, so ghost renders accumulate in scrollback.
+            // syncTerminalGeometry() reflowed content: lines at old width may wrap to
+            // more rows, pushing overflow into scrollback. Ink's cursor-up count is
+            // based on the pre-reflow line count, so ghost renders accumulate there.
             // Fix: \x1b[3J (Erase Saved Lines) clears scrollback reflow debris,
             // then \x1b[H\x1b[2J clears the viewport for a clean Ink redraw.
             // IMPORTANT: Only clear when we're actually sending SIGWINCH (dims changed).
             // Clearing without a subsequent Ink redraw leaves the terminal blank.
             const activeResizeSession = this.activeSessionId ? this.sessions.get(this.activeSessionId) : null;
+            // Not while another device holds the width: the columns were not
+            // reflowed here, and a refused resize brings no redraw after it.
             if (
               activeResizeSession &&
               activeResizeSession.mode !== 'shell' &&
+              !this._paneWidthRefused &&
               this.terminal &&
               this.isTerminalAtBottom()
             ) {
@@ -1076,11 +1143,24 @@ Object.assign(CodemanApp.prototype, {
               }
             }
             if (!sentViaWs) {
+              // ⚠️ The reply carries the geometry that actually took, and this
+              // is the path where a declined resize is LEAST likely to be
+              // noticed: no socket means no `{"t":"zc"}` frame either, so
+              // discarding it here left the one transport that cannot hear the
+              // answer also not asking for it.
+              const resizedSessionId = this.activeSessionId;
               fetch(`/api/sessions/${this.activeSessionId}/resize`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ cols, rows, viewportType }),
-              }).catch(() => {});
+              })
+                .then(async (res) => {
+                  const applied = (await res.json())?.data ?? {};
+                  this._onPtyGeometryReport(resizedSessionId, applied.cols, applied.rows);
+                })
+                .catch(() => {
+                  /* a resize that never landed tells us nothing about the PTY */
+                });
             }
           }
         }
@@ -1934,24 +2014,22 @@ Object.assign(CodemanApp.prototype, {
     this.terminal?.select?.(index % cols, Math.floor(index / cols), length);
   },
 
-  /** Long-press fired: select the word under the finger and arm drag-to-extend. */
+  /** Long-press fired: swallow the platform gesture, then select a word if one exists. */
   _beginTouchSelection(clientX, clientY) {
+    // Reaching the 350ms threshold makes this a long press even when the finger
+    // landed on blank space. Arm every guard before looking for a word so Chrome
+    // cannot focus xterm's hidden textarea, and leave _touchSelecting set so the
+    // touchend branch preventDefaults the compatibility mouse sequence.
+    this._blurMobileTerminalInput();
+    this._suppressTrustedTapMouseEvents();
+    this._armTouchSelectionFocusGuard();
+    this._touchSelecting = true;
     const cell = this._touchSelectionCellAt(clientX, clientY);
     if (!cell) return false;
     const word = this._touchSelectionWordAt(cell);
     if (!word) return false;
-    // The keyboard must not sit on top of the thing being selected, and the
-    // composer would eat the selection on its next keystroke anyway.
-    this._blurMobileTerminalInput();
     this._touchSelectionAnchor = word;
-    this._touchSelecting = true;
     this._touchSelectionActive = true;
-    // From here until the gesture ends, no trusted mouse event may reach xterm —
-    // see _endTouchSelectionGesture for why — and the terminal input may not take
-    // focus. Both are re-armed as the gesture continues, since their windows are
-    // short and a press can be held for much longer.
-    this._suppressTrustedTapMouseEvents();
-    this._armTouchSelectionFocusGuard();
     this._applyTouchSelection(word.index, word.length);
     // Android answers; iOS ignores it silently. Both are fine.
     try {
@@ -3343,7 +3421,107 @@ Object.assign(CodemanApp.prototype, {
     return performance.now() - this._lastUserScrollUpAt < window.CodemanTerminalInput.USER_SCROLL_STICKY_SUPPRESS_MS;
   },
 
+  /**
+   * Watchdog for a frozen renderer.
+   *
+   * iOS DISCARDS scheduled requestAnimationFrame callbacks when a PWA goes to
+   * the background — not deferred, never delivered. xterm's RenderDebouncer
+   * only clears its `_animationFrame` handle from INSIDE that callback, so once
+   * one is dropped the handle stays permanently non-undefined and every later
+   * `refresh()` returns on its first line. Parsing is decoupled from rendering,
+   * so bytes keep filling the buffer correctly and nothing throws: the terminal
+   * is simply frozen until the page is reloaded.
+   *
+   * Codeman is more exposed than an app that mounts a terminal per session —
+   * there is exactly ONE xterm instance for the whole page load, so a single
+   * backgrounding can wedge it for the rest of the session.
+   *
+   * The heal is what `_innerRefresh` would have done: cancel the stale handle,
+   * clear the field, and request a full repaint (which schedules a fresh rAF).
+   * Cancelling a genuinely pending handle is harmless — the full repaint that
+   * follows covers whatever it was going to draw.
+   *
+   * Discipline for reaching into xterm privates, and it is not optional: every
+   * access is optional-chained and the whole body is wrapped, so a shape change
+   * upstream degrades to a no-op. A self-heal that can break the terminal it is
+   * healing is worse than no self-heal.
+   *
+   * ⚠️ The field path (`_core._renderService._renderDebouncer._animationFrame`)
+   * is validated against xterm 6.x and CANNOT be covered by the CI gate:
+   * `_renderService` is only constructed by `Terminal.open()`, which needs a
+   * real DOM, and the gate runs in node. `test/xterm-private-api.test.ts` pins
+   * the RESOLVED lockfile version instead, so ANY bump fails there — not only a
+   * major — and sends someone to re-check this by hand; the declared `^6.0.0`
+   * range was the wrong assertion in both directions, since 6.4.0 could rename a
+   * private field while resolving inside it. `test/terminal-resilience.test.ts`
+   * covers the decision half. If the path ever goes stale the watchdog silently
+   * stops healing — that is the failure mode to watch for, and why the version
+   * guard exists at all.
+   */
+  _startRenderLivenessWatchdog() {
+    this._stopRenderLivenessWatchdog();
+    this._lastRenderAt = Date.now();
+    this._lastTerminalWriteAt = 0;
+    this._renderLivenessTimer = setInterval(() => {
+      try {
+        if (typeof CodemanRenderLiveness === 'undefined') return;
+        const kick = CodemanRenderLiveness.shouldKickRenderer({
+          wroteAt: this._lastTerminalWriteAt || 0,
+          renderedAt: this._lastRenderAt || 0,
+          now: Date.now(),
+          // A hidden terminal legitimately stops rendering (xterm pauses it),
+          // so only a VISIBLE one that owes us a frame counts as frozen.
+          visible: document.visibilityState === 'visible' && !!this.terminal?.element?.isConnected,
+        });
+        if (!kick) return;
+        const kicked = this._kickRenderer();
+        _crashDiag.log(`RENDER STALL: kick=${kicked}`);
+        // Treat the kick as the render for accounting purposes either way, so a
+        // terminal we cannot heal logs once per stall rather than every tick.
+        this._lastRenderAt = Date.now();
+      } catch {
+        /* a watchdog must never throw into the interval */
+      }
+    }, RENDER_LIVENESS_POLL_MS);
+  },
+
+  _stopRenderLivenessWatchdog() {
+    if (this._renderLivenessTimer) {
+      clearInterval(this._renderLivenessTimer);
+      this._renderLivenessTimer = null;
+    }
+  },
+
+  /**
+   * Do what xterm's dropped `_innerRefresh` would have done. Never throws.
+   * @returns {boolean} true if a stale handle was found and cleared.
+   */
+  _kickRenderer() {
+    try {
+      const renderService = this.terminal?._core?._renderService;
+      const debouncer = renderService?._renderDebouncer;
+      if (!debouncer || typeof renderService.refreshRows !== 'function') return false;
+      const handle = debouncer._animationFrame;
+      if (handle === undefined) return false; // not wedged — nothing to clear
+      try {
+        cancelAnimationFrame(handle);
+      } catch {
+        /* a stale handle may no longer be cancellable; clearing it is the point */
+      }
+      debouncer._animationFrame = undefined;
+      renderService.refreshRows(0, Math.max(0, (this.terminal.rows || 1) - 1));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
   batchTerminalWrite(data) {
+    // Feed the renderer watchdog. Recorded before the buffer-load early return
+    // below: a write that is queued rather than written still means the pipeline
+    // owes us a frame once it drains.
+    this._lastTerminalWriteAt = Date.now();
+
     // If a buffer load (chunkedTerminalWrite) is in progress, queue live events
     // to prevent interleaving historical buffer data with live SSE data.
     // This is critical: interleaving causes cursor position chaos with Ink redraws.
@@ -4170,11 +4348,16 @@ Object.assign(CodemanApp.prototype, {
    *
    * `text` is for the callers that already read the selection to decide whether
    * to copy at all (the Ctrl+C gate and the right-click handler), so the read is
-   * not repeated. The transform is idempotent on xterm output, so an
-   * already-cleaned string is an acceptable argument: a CR is consumed by the
-   * parser as a cursor move and never stored in a cell, so the only \r the
-   * selection can carry is the Windows line join, and that is what makes the
-   * trailing scan a fixed point. Fuzzed over 300 000 realistic selections.
+   * not repeated.
+   *
+   * ⚠️ **Pass the RAW selection, never an already-cleaned one.** The trailing
+   * trim alone is a fixed point, because a CR is consumed by the parser as a
+   * cursor move and never stored in a cell, so the only \r the selection can
+   * carry is the Windows line join. The MARGIN strip is not: it takes the
+   * narrower of the declared width and the run every line shares, so a second
+   * pass over an already-stripped block takes up to `margin` columns more. A
+   * caller that cleans to decide whether to copy must still hand the raw text
+   * to copyTerminalSelection, which cleans once on its own.
    *
    * A COLUMN selection comes back untouched. Alt+drag makes one (xterm's
    * shouldColumnSelect keys on altKey alone, and Codeman sets neither of the
@@ -4191,7 +4374,73 @@ Object.assign(CodemanApp.prototype, {
     if (this.terminal?._core?._selectionService?._activeSelectionMode === 3) return raw;
     const clean = window.CodemanCopySelection?.clean;
     if (!clean) return raw;
-    return clean(raw);
+    const range = this._normalisedSelectionRange();
+    return clean(raw, {
+      margin: this._cliGutterColumns(),
+      firstLinePartial: !!range && range.start.x > 0,
+    });
+  },
+
+  /**
+   * xterm's selection range with its two ends in reading order.
+   *
+   * `getSelectionPosition()` reports `start` and `end` as the two ends of the
+   * drag, and on xterm 6.0 it already hands back the earlier one first: it
+   * reads `_selectionService.selectionStart`, whose getter returns the model's
+   * `finalSelectionStart`, and that swaps the pair for a reversed selection.
+   * A real upward mouse drag through chromium confirms it. The ordering here
+   * is a guard rather than a fix. One layer down the same model exposes the
+   * UNNORMALISED fields under the same two names, and a reversed pair would
+   * make the row window below run backwards and collapse, which would report
+   * no margin at all for every upward drag in a deep buffer.
+   *
+   * `terminal` names which xterm to read, defaulting to the primary pane's.
+   * Pane B of a split owns a second terminal and passes it, because this file's
+   * `this` is always the primary pane.
+   */
+  _normalisedSelectionRange(terminal) {
+    const range = (terminal ?? this.terminal)?.getSelectionPosition?.();
+    if (!range?.start || !range?.end) return null;
+    const { start, end } = range;
+    const reversed = end.y < start.y || (end.y === start.y && end.x < start.x);
+    return reversed ? { start: end, end: start } : { start, end };
+  },
+
+  /**
+   * How many columns to take off a copy from one session's pane: the transcript
+   * gutter its CLI declares, or 0 when it declares none. `sessionId` defaults to
+   * the active session, and Pane B of a split passes its own, so both panes of a
+   * split strip the width their own CLI declares rather than Pane A's.
+   *
+   * ⚠️ Read from `window.__codemanTranscriptGutter`, the map the server derives
+   * from the `transcriptGutter` CAPABILITY at render time — never an id literal
+   * here, which is the registry's standing rule and is also what lets a CLI that
+   * declares a gutter later work with no change to this file.
+   *
+   * ⚠️ DECLARED rather than measured off the buffer, and two measured versions
+   * are why. Asking whether the pane painted spaces across the unused part of
+   * each row separates a TUI from a shell perfectly where it fires and never
+   * over-stripped, but it is a function of pane WIDTH, since that padding exists
+   * only while a rendered line stops short of the CLI's own layout width and
+   * Claude Code's prose wraps to fill it: the share of padded rows on one live
+   * transcript ran 44%, 6%, 6%, 7% and 87% at 123, 160, 198, 235 and 298
+   * columns, so the strip did nothing at any ordinary window size. Taking the
+   * narrowest indent on the rows around the selection instead fires at every
+   * width and over-strips on about 1% of them, because a file listing inside the
+   * transcript can be the narrowest thing on screen. A declared width does
+   * neither, and it reads no buffer rows at all on a path that runs on every
+   * Ctrl+C.
+   *
+   * A missing map means no session gets a strip, the same direction an
+   * unmeasured CLI takes by declaring nothing.
+   */
+  _cliGutterColumns(sessionId) {
+    if (!this._copyStripMarginEnabled()) return 0;
+    const byMode = window.__codemanTranscriptGutter;
+    if (!byMode || typeof byMode !== 'object') return 0;
+    const mode = this.sessions?.get(sessionId ?? this.activeSessionId)?.mode;
+    const columns = mode ? byMode[mode] : 0;
+    return Number.isInteger(columns) && columns > 0 ? columns : 0;
   },
 
   // Copy the current terminal selection. Goes through _copyText (Clipboard API,
@@ -4226,6 +4475,26 @@ Object.assign(CodemanApp.prototype, {
     return ok;
   },
 
+  /**
+   * Whether this device wants the pane's left margin off the clipboard
+   * (`copyStripMargin`, per-device, default ON).
+   *
+   * Read here rather than mirrored into a field, for the same reason
+   * `_autoCopySelectionEnabled` is: there is then no apply-path a future
+   * settings save can forget to call, and the toggle takes effect on the next
+   * selection instead of the next reload. ⚠️ The test is `!== false`, not
+   * `=== true`: this one defaults ON, and the desktop branch of
+   * getDefaultSettings returns {} and leans on the read sites for defaults, so
+   * a device that has never opened App Settings has no stored value at all.
+   */
+  _copyStripMarginEnabled() {
+    try {
+      return this.loadAppSettingsFromStorage?.()?.copyStripMargin !== false;
+    } catch {
+      return true;
+    }
+  },
+
   /**
    * Auto Copy's ON/OFF, read at flush time from the CACHED settings object
    * (loadAppSettingsFromStorage memoizes, so this is not a localStorage hit).
@@ -5126,7 +5395,7 @@ Object.assign(CodemanApp.prototype, {
   setFontSize(size) {
     this.terminal.options.fontSize = size;
     document.getElementById('fontSizeDisplay').textContent = size;
-    this.fitAddon.fit();
+    this._refitAfterCellSizeChange();
     localStorage.setItem('codeman-font-size', size);
     // Update overlay font cache and re-render at new cell dimensions
     this._localEchoOverlay?.refreshFont();
@@ -5155,9 +5424,9 @@ Object.assign(CodemanApp.prototype, {
     // without needing a tab switch. The fit below still runs, so the terminal
     // is never left unfitted if the wait is slow.
     this._terminalFontReady = this._awaitTerminalFont().then(() => {
-      if (this.terminal?.options?.fontFamily === resolved) this.fitAddon?.fit();
+      if (this.terminal?.options?.fontFamily === resolved) this._refitAfterCellSizeChange();
     });
-    this.fitAddon?.fit();
+    this._refitAfterCellSizeChange();
     this._localEchoOverlay?.refreshFont();
     this._predictiveEcho?.refreshFont();
     if (this._splitPane?.terminal) {
@@ -5200,9 +5469,9 @@ Object.assign(CodemanApp.prototype, {
     // rasterized yet. Re-arm the wait and fit again once it settles; the fit
     // below still runs, so the terminal is never left unfitted.
     this._terminalFontReady = this._awaitTerminalFont().then(() => {
-      if (this.terminal?.options?.fontWeight === fontWeight) this.fitAddon?.fit();
+      if (this.terminal?.options?.fontWeight === fontWeight) this._refitAfterCellSizeChange();
     });
-    this.fitAddon?.fit();
+    this._refitAfterCellSizeChange();
     this._localEchoOverlay?.refreshFont();
     this._predictiveEcho?.refreshFont();
     for (const [, entry] of this.teammateTerminals || []) {
@@ -5293,19 +5562,126 @@ Object.assign(CodemanApp.prototype, {
   },
 
   /**
-   * Get terminal dimensions with minimum enforcement.
-   * Prevents extremely narrow terminals that cause vertical text wrapping.
+   * The geometry this terminal would report right now, floors applied.
+   * Reads only — `syncTerminalGeometry()` is what makes it true of xterm.
    * @returns {{cols: number, rows: number}|null}
    */
   getTerminalDimensions() {
-    const MIN_COLS = 40;
-    const MIN_ROWS = 10;
-    const dims = this.fitAddon?.proposeDimensions();
+    // Never throws. `proposeDimensions()` reads a rendered element and throws
+    // on a terminal that has been disposed or detached mid-resize, which is an
+    // ordinary outcome on a tab switch — and this is called from the settle
+    // timer and the resize observer, where an exception takes the rest of the
+    // callback (the padding fit, the scroll restore, the SIGWINCH) with it.
+    try {
+      return window.CodemanTerminalGeometry.clampTerminalDimensions(this.fitAddon?.proposeDimensions());
+    } catch {
+      return null;
+    }
+  },
+
+  /**
+   * Fit xterm to its container and return the geometry that was APPLIED.
+   *
+   * ⚠️ THE ONLY function that may change the terminal's size, and the only
+   * source of the numbers sent to the server. `fitAddon.fit()` on its own is
+   * not enough and the gap is issue #464: fit() resizes xterm to
+   * `proposeDimensions()` RAW, while every server-facing path reported those
+   * dimensions floored at 40x10. Whenever the floor bit — a phone with the
+   * keyboard up routinely proposes under ten rows — the PTY was told one shape
+   * and xterm held another, and Claude Code then computed every repaint for a
+   * screen that did not exist. See the note in constants.js for what that
+   * renders as, and why the floor is not negotiable at either end.
+   *
+   * Three call sites each used to do their own fit-then-clamp
+   * (`throttledResize`, `sendResize`, KeyboardHandler's one-shot), which is
+   * three chances to disagree; two of them also re-read `proposeDimensions()`
+   * after the fit, so a container that moved in between — `_shrinkPaddingToFit`
+   * runs exactly there — changed the answer without touching xterm.
+   *
+   * The second resize only happens when the floor actually bites, so the
+   * ordinary path still reflows once, as before.
+   *
+   * @returns {{cols: number, rows: number}|null} null when the terminal cannot be measured
+   */
+  syncTerminalGeometry() {
+    if (!this.fitAddon || !this.terminal) return null;
+    try {
+      this.fitAddon.fit();
+    } catch {
+      /* a disposed or unattached terminal cannot be fitted; fall through to the read */
+    }
+    const dims = this.getTerminalDimensions();
     if (!dims) return null;
-    return {
-      cols: Math.max(dims.cols, MIN_COLS),
-      rows: Math.max(dims.rows, MIN_ROWS),
-    };
+    if (!this._resizeTerminalTo(dims)) return null;
+    // The floor can leave this terminal wider than the box that shows it, and
+    // that clips columns with no gesture to reach them (issue #464, item 4).
+    this._scheduleOverflowAffordanceSync();
+    return dims;
+  },
+
+  /**
+   * The geometry to ASK the server for, applied locally only as far as the PTY
+   * can follow it.
+   *
+   * Ordinarily that is all of it: `syncTerminalGeometry()`. While another
+   * device holds the width (`_paneWidthRefused`, set by `_onPtyGeometryReport`)
+   * it is not. Fitting then re-wraps xterm to the container's columns, the
+   * request is refused, the report puts the PTY's columns back, and the whole
+   * buffer re-wraps twice per ask, with the viewport pointing at a different
+   * part of the scrollback in between. The mobile retry asks every 30 seconds,
+   * so that happened on a timer for as long as the refusal lasted. So the
+   * columns stay at the PTY's (the #464 invariant: the browser never draws at
+   * a width the PTY does not have), the rows follow the container (they are
+   * never adopted, see reconcilePtyGeometry), and the container's columns go
+   * out as the request. An accepted request is adopted by the report.
+   *
+   * @returns {{cols: number, rows: number}|null} the geometry to request
+   */
+  _geometryForResizeRequest() {
+    if (!this._paneWidthRefused) return this.syncTerminalGeometry();
+    const wanted = this.getTerminalDimensions();
+    if (!wanted || !this.terminal) return null;
+    if (!this._resizeTerminalTo({ cols: this.terminal.cols, rows: wanted.rows })) return null;
+    this._scheduleOverflowAffordanceSync();
+    return wanted;
+  },
+
+  /**
+   * Re-measure after something changed the CELL size, and tell the server.
+   *
+   * ⚠️ A font change is a geometry change. Bigger glyphs mean fewer columns in
+   * the same box, and the PTY is drawing for a column count nobody updated:
+   * `setFontSize`, `setFontFamily` and `setFontWeight` all refitted the terminal
+   * and sent NOTHING, so raising the font on a phone could drop the browser
+   * below the columns the CLI was still wrapping at until some unrelated resize
+   * event happened along. That is issue #464 reached through the font menu.
+   *
+   * With no session there is no PTY to tell, and a session detached into its own
+   * window is not this terminal's to resize — `sendResize` makes that call, and
+   * fits as its first synchronous step, so this never fits twice.
+   */
+  _refitAfterCellSizeChange() {
+    if (this.activeSessionId) {
+      this.sendResize(this.activeSessionId)?.catch?.(() => {});
+      return;
+    }
+    this.syncTerminalGeometry();
+  },
+
+  /**
+   * Make xterm exactly `dims`. Idempotent, and never throws at a caller — a
+   * terminal disposed mid-resize is an ordinary outcome on a tab switch.
+   * @returns {{cols: number, rows: number}|null} the applied geometry
+   */
+  _resizeTerminalTo(dims) {
+    if (!this.terminal || !dims) return null;
+    if (this.terminal.cols === dims.cols && this.terminal.rows === dims.rows) return dims;
+    try {
+      this.terminal.resize(dims.cols, dims.rows);
+      return dims;
+    } catch {
+      return null;
+    }
   },
 
   /**
@@ -5315,21 +5691,26 @@ Object.assign(CodemanApp.prototype, {
    * @returns {Promise<boolean>} Whether dimensions changed from the last send
    */
   async sendResize(sessionId, options = {}) {
-    // Fit terminal to container before reading dimensions — ensures local
-    // terminal size matches what we report to the server PTY.
-    if (this.fitAddon) this.fitAddon.fit();
     // One PTY cannot hold two sizes. A detached session is owned by its own
     // window, and the dashboard's terminal is narrower than that window because
     // the session rail takes width the popup does not have — so both sizing it
     // makes the CLI draw frames that fit neither, which garbles the popup. The
     // dashboard yields; the solo window sizes what it alone displays.
     // (_maybeRefetchFullHistory already stands aside for the same reason.)
-    // ⚠️ AFTER the fit, never before: the local reflow keeps the dashboard's own
-    // xterm right, and only the SERVER write is the dashboard's to withhold —
-    // the mobile-keyboard guard below draws exactly this line. tab-rail-resize
-    // performs its one settle-time refit through this call and has no fallback.
+    // ⚠️ BEFORE the fit, never after. This used to fit first and withhold only
+    // the server write, on the reasoning that the local reflow keeps the
+    // dashboard's own xterm right. It does not: it leaves this xterm at a shape
+    // the PTY was never told about, which is the #464 divergence exactly — and
+    // the popup that DOES own the PTY is drawing for its own width, so the
+    // dashboard's reflow is to a size nothing is rendering for. Withholding the
+    // resize means withholding all of it. tab-rail-resize performs its one
+    // settle-time refit through this call and has no fallback, which is correct:
+    // a pane it does not own is not its to refit either.
     if (!this.isSoloWindow && this.detachedSessions?.has(sessionId)) return false;
-    const dims = this.getTerminalDimensions();
+    // Fit, floor, and apply in one step so the numbers below are the numbers
+    // xterm is actually holding (or, while another device holds the width,
+    // the numbers this container would hold if the PTY followed).
+    const dims = this._geometryForResizeRequest();
     if (!dims) return false;
     // Did the dimensions actually change since the last resize we sent? Callers
     // use this to skip work (e.g. the post-resize TUI-redraw settle) when no
@@ -5362,14 +5743,150 @@ Object.assign(CodemanApp.prototype, {
     }
     const body = { ...dims, viewportType };
     if (options.force) body.force = true;
-    await fetch(`/api/sessions/${sessionId}/resize`, {
+    const res = await fetch(`/api/sessions/${sessionId}/resize`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
     });
+    // Same report the WS path gets as a {"t":"zc"} frame. An older server
+    // answers `{}`, which reconciles to a no-op rather than throwing.
+    try {
+      const applied = (await res.json())?.data ?? {};
+      this._onPtyGeometryReport(sessionId, applied.cols, applied.rows);
+    } catch {
+      /* a body that is not JSON tells us nothing about the PTY; keep our own geometry */
+    }
     return changed;
   },
 
+  /**
+   * Adopt the geometry the server says the PTY actually has.
+   *
+   * ⚠️ The server is the authority and this client is not always obeyed.
+   * `Session.resize` declines a small-viewport request outright while a desktop
+   * connection holds an active sizing claim, and says nothing — resize was
+   * write-only until #464. A terminal that keeps its own shape after such a
+   * refusal does not render "too narrow", it renders GARBLED: Claude Code wraps
+   * its frame at the width it was told and walks the cursor up that many rows,
+   * so a mismatch makes its erase count come out short and each repaint paints
+   * over rows it never cleared. Measured against a real xterm — a PTY believing
+   * 120 columns against a 62-column terminal draws every wrapped line twice.
+   *
+   * Adopting can leave the pane wider than the viewport, and the container is
+   * `overflow: hidden`, so `.term-overflows-x` grants horizontal reach for exactly
+   * as long as the mismatch lasts. Correct-and-reachable beats correct-and-
+   * clipped beats garbled; nothing here is worth trapping content behind.
+   *
+   * Self-resolving: `_startMobileResizeRetry` re-sends this device's dimensions
+   * on a timer, so the pane comes back to this screen once the desktop goes
+   * idle, and the next report clears the class and the notice with it.
+   */
+  _onPtyGeometryReport(sessionId, cols, rows) {
+    if (!this.terminal || sessionId !== this.activeSessionId) return;
+    const local = { cols: this.terminal.cols, rows: this.terminal.rows };
+    const { adopt } = window.CodemanTerminalGeometry.reconcilePtyGeometry(local, { cols, rows });
+    // Columns only, and the local row count is kept — see reconcilePtyGeometry
+    // for why adopting rows put the CLI's input line below the container with
+    // nothing able to scroll to it.
+    if (adopt && this._resizeTerminalTo({ cols, rows: local.rows })) {
+      // The numbers we would report next are now the PTY's, not the container's:
+      // without this the dedupe in throttledResize/sendResize compares against a
+      // request that was refused and suppresses the retry that recovers the pane.
+      this._lastResizeDims = { cols, rows: local.rows };
+    }
+    // Is the PTY at a width this container did not ask for? Compared against
+    // what we WOULD request, not against what the terminal currently holds:
+    // once adopted those two are equal, so the second question answers itself
+    // false and the condition would look resolved while it is still true.
+    // The floor widens this terminal too, and that is the reader's own font
+    // setting rather than another device — hence the comparison, not `>`.
+    const wanted = this.getTerminalDimensions();
+    this._paneWidthRefused = !!wanted && Number.isFinite(cols) && cols !== wanted.cols;
+    this._scheduleOverflowAffordanceSync();
+  },
+
+  /**
+   * Measure on the NEXT frame, coalesced.
+   *
+   * `terminal.resize()` updates the buffer synchronously but the screen element
+   * takes its new width with the render, so measuring in the same tick reads
+   * the size the terminal just left. Coalesced because a settling container
+   * fires several resizes and only the last one's measurement is the truth.
+   */
+  _scheduleOverflowAffordanceSync() {
+    if (typeof requestAnimationFrame !== 'function') {
+      this._syncTerminalOverflowAffordance();
+      return;
+    }
+    if (this._overflowAffordanceFrame) return;
+    this._overflowAffordanceFrame = requestAnimationFrame(() => {
+      this._overflowAffordanceFrame = null;
+      this._syncTerminalOverflowAffordance();
+    });
+  },
+
+  /**
+   * Let the reader reach a pane wider than the box that shows it.
+   *
+   * ⚠️ Keyed on what actually does not FIT, not on a PTY mismatch. Two
+   * different causes put the terminal wider than its container and both leave
+   * columns unreachable behind `.terminal-container`'s clip:
+   *
+   *  - another device holds the sizing claim, so this terminal adopts a width
+   *    it did not ask for; and
+   *  - the 40-column floor. On a 360px phone, font 18 applies 40 columns and
+   *    paints 433px, and font 24 paints 578px — 218px, 38% of the pane, with no
+   *    gesture that could reach it. `increaseFontSize` goes to 24 and applies
+   *    immediately, so that is two taps away, and the PTY agrees with the
+   *    terminal throughout: a mismatch test would never fire.
+   *
+   * Measured rather than derived from cell arithmetic, because the cell width
+   * is fractional and the container's padding is not ours to assume. One pixel
+   * of slack keeps sub-pixel rounding from flapping the class.
+   */
+  _syncTerminalOverflowAffordance() {
+    // ⚠️ Nothing in here may throw. It runs off every geometry change, which is
+    // the resize path, and the affordance is cosmetic: a terminal that cannot
+    // be measured — disposed mid-resize, or a harness with no real DOM — must
+    // lose the scroll affordance, never the resize.
+    let container = null;
+    let overflows = false;
+    try {
+      container = document.getElementById('terminalContainer');
+      const screen = container?.querySelector('.xterm-screen');
+      if (container && screen) {
+        overflows = screen.getBoundingClientRect().width - container.clientWidth > 1;
+      }
+    } catch {
+      /* unmeasurable; fall through with the affordance off */
+    }
+    container?.classList.toggle('term-overflows-x', overflows);
+    // The notice tells the reader to scroll sideways, so it is only true advice
+    // once there is something to scroll. A wide PTY on a screen wide enough to
+    // show it needs no explanation and gets none.
+    if (!overflows || !this._paneWidthRefused) {
+      this._paneOwnedElsewhere = false;
+      return;
+    }
+    this._notePaneOwnedElsewhere();
+  },
+
+  /**
+   * Say, once, that this pane's width belongs to another device.
+   *
+   * Once per transition, not per report: reports arrive on every resize, and a
+   * toast that repeats is noise about a situation already on screen. Silent
+   * when it resolves — the pane simply reflows back to this screen.
+   */
+  _notePaneOwnedElsewhere() {
+    if (this._paneOwnedElsewhere) return;
+    this._paneOwnedElsewhere = true;
+    // 53 characters: measured at one line on a 430px phone. The longer
+    // wording wrapped to two, which is a lot of the terminal to cover for a
+    // notice about a condition that resolves itself.
+    this.showToast('Another device is setting the width — scroll sideways', 'info');
+  },
+
   /**
    * Send input to the active session.
    * @param {string} input - Text to send (include \r for Enter)

src/web/routes/case-routes.ts

@@ -128,6 +128,18 @@ const APP_VERSION = (() => {
 const LOCAL_CLONE_ADMIN_ONLY =
   'Cloning from a local path is admin-only in multi-user mode. Use a repository URL instead.';
 
+/**
+ * Whether a clone or preflight must run with git's credential helpers cleared:
+ * a non-admin in multi-user mode. Every user's git runs as the one server
+ * account, so its helpers (the Docker image's opt-in `gh`/`az` ones, or any
+ * `gh auth setup-git`) would otherwise read a private repository with the
+ * signed-in admin's credentials, the same boundary the local-transport rule
+ * above guards. Admins and single-user mode keep the account's own helpers.
+ */
+export function cloneWithoutCredentialHelpers(req: FastifyRequest): boolean {
+  return isMultiUserMode() && !isAdmin(req);
+}
+
 /**
  * The one line of git's stderr worth appending to an error message.
  *
@@ -475,7 +487,9 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       if (!isGitAvailable()) {
         return { success: true, data: { parse: parsed, gitAvailable: false } };
       }
-      const remote = await probeGitRemote(parsed.repository);
+      const remote = await probeGitRemote(parsed.repository, undefined, {
+        withoutCredentialHelpers: cloneWithoutCredentialHelpers(req),
+      });
       return { success: true, data: { parse: parsed, remote, gitAvailable: true } };
     }
   );
@@ -491,8 +505,10 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
    * request died mid-clone still sees the case appear over SSE when git finishes.
    *
    * Deliberately NOT admin-gated in multi-user mode: unlike `/api/cases/link`,
-   * this writes only inside the caller's own `resolveCasesDir`. The one exception
-   * is a `local`-transport source, which would read through that boundary.
+   * this writes only inside the caller's own `resolveCasesDir`. Two things would
+   * otherwise read through that boundary: a `local`-transport source (refused for
+   * non-admins) and the server account's git credential helpers, which every user
+   * shares (cleared for non-admins, see `cloneWithoutCredentialHelpers`).
    *
    * Repository contents win over scaffolding: an existing CLAUDE.md is left
    * alone, and hooks are MERGED into whatever `.claude/settings.local.json` the
@@ -562,6 +578,7 @@ export function registerCaseRoutes(app: FastifyInstance, ctx: EventPort & Config
       const clone = await cloneRepository({
         repository: parsed.repository,
         destination: casePath,
+        withoutCredentialHelpers: cloneWithoutCredentialHelpers(req),
         ...(ref ? { ref } : {}),
         ...(shallow ? { shallow: true } : {}),
       });

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

@@ -176,6 +176,12 @@ export function registerHookEventRoutes(
     // identity beyond the shared per-instance secret, so a prompt claimed for a
     // session that can never show one must not create an answerable item).
     let approvalId: string | undefined;
+    // Set when the item opened ALREADY acknowledged, which today means the session is
+    // watching work it started itself. It rides the broadcast so a live page declines to
+    // arm the alert (a reloading page learns the same thing from `acknowledgedAt` when it
+    // seeds from /api/approvals), and it suppresses the push: an alert nobody can answer
+    // is worth even less on a phone than in a tab.
+    let acknowledgedReason: string | undefined;
     const approvalKind = APPROVAL_KIND_BY_EVENT[event];
     if (session && hooksAvailableForMode(session.mode, sessionHookOptions(session))) {
       if (approvalKind) {
@@ -194,6 +200,10 @@ export function registerHookEventRoutes(
           toolSummary: typeof toolSummary === 'string' ? toolSummary : undefined,
           message: typeof safeData.message === 'string' ? safeData.message : undefined,
           cwd: typeof safeData.cwd === 'string' ? safeData.cwd : undefined,
+          // What the pane says is still running in the background. An idle prompt from a
+          // session that is watching its own work opens acknowledged, so it never arms an
+          // alert nobody can answer; notePrompt() carries the whole reasoning.
+          watching: session.watching,
           // Visible tmux frame first (it IS the dialog); raw byte-buffer tail as
           // the fallback for direct-PTY sessions and the no-op test mux.
           capture: () => {
@@ -203,6 +213,7 @@ export function registerHookEventRoutes(
           },
         });
         approvalId = item.id;
+        acknowledgedReason = item.acknowledgedReason;
       } else if (APPROVAL_RESOLVING_EVENTS.has(event)) {
         approvalInbox.resolveForSession(sessionId, 'resolved_in_terminal');
       }
@@ -213,6 +224,7 @@ export function registerHookEventRoutes(
       timestamp: Date.now(),
       ...safeData,
       ...(approvalId && { approvalId }),
+      ...(acknowledgedReason && { acknowledgedReason }),
     });
     // Full state ride-along, same shape as the working/idle handlers: the home
     // screens rank the blocked group on lastActivityAt, and without this a
@@ -224,12 +236,17 @@ export function registerHookEventRoutes(
     // on approvalId, and the answer route refuses keystrokes for dsh dialogs
     // (third-party TUI, unmeasured contract) — so a dsh push stays a plain
     // notification instead of offering buttons whose answer would be refused.
-    ctx.sendPushNotifications(`hook:${event}`, {
-      sessionId,
-      sessionName,
-      ...safeData,
-      ...(approvalId && session?.mode !== 'deepseek' && { approvalId }),
-    });
+    // Nothing to push for a prompt that opened acknowledged: the agent is waiting for its
+    // own monitor or backgrounded shell, and a phone buzzing about it is the same false
+    // alarm as the tab alert, delivered where it is hardest to ignore.
+    if (!acknowledgedReason) {
+      ctx.sendPushNotifications(`hook:${event}`, {
+        sessionId,
+        sessionName,
+        ...safeData,
+        ...(approvalId && session?.mode !== 'deepseek' && { approvalId }),
+      });
+    }
 
     // Track in run summary. `prompt_submitted` fires on EVERY prompt of every
     // Claude pane; only the ones where the conversation actually moved (a /clear

src/web/routes/session-routes.ts

@@ -1583,6 +1583,12 @@ export function registerSessionRoutes(
         name: session.name,
         mode: session.mode,
       });
+      // Persist, not just broadcast. Starting a command in the pane changes
+      // `pid` and retracts any `paneExit` (Ark0N/Codeman#446), and the pane-exit
+      // watcher cannot write that retraction to disk for us: its next tick finds
+      // the in-memory field already cleared, reports no change and persists
+      // nothing, so `state.json` would keep saying the agent had exited.
+      ctx.persistSessionState(session);
       ctx.broadcast(SseEvent.SessionInteractive, { id });
       ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) });
 
@@ -1612,6 +1618,9 @@ export function registerSessionRoutes(
         name: session.name,
         mode: 'shell',
       });
+      // Persist for the same reason /interactive does: a started pane retracts
+      // `paneExit`, and the watcher's next tick cannot write that retraction.
+      ctx.persistSessionState(session);
       ctx.broadcast(SseEvent.SessionInteractive, { id, mode: 'shell' });
       ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) });
       return {};
@@ -2115,7 +2124,13 @@ export function registerSessionRoutes(
     const session = findSessionOrFail(ctx, id, req);
 
     session.resize(cols, rows, { viewportType, force });
-    return {};
+    // Answer with the geometry the PTY ACTUALLY holds, which is not always the
+    // one asked for: `Session.resize` declines small-viewport requests while a
+    // desktop connection holds an active sizing claim. A browser terminal left
+    // at a shape the PTY refused renders garbled output, not merely wrong-sized
+    // output, so the client adopts this (issue #464). A session with no pane
+    // reports nothing rather than the constructor defaults — see `ptyGeometry`.
+    return session.ptyGeometry ?? {};
   });
 
   // ========== Get Last Response (from transcript JSONL) ==========

src/web/routes/ws-routes.ts

@@ -22,6 +22,9 @@
  *     {"t":"c"}           — clear terminal
  *     {"t":"r"}           — needs refresh (reload buffer)
  *     {"t":"ia","seq":N}  — input ACK (echoes the seq of an applied/deduped input frame)
+ *     {"t":"zc","c":N,"r":N} — resize confirm: the geometry the PTY now holds, which
+ *                          is NOT always the one requested (see Session.resize
+ *                          arbitration). Clients adopt it — issue #464.
  *   Client -> Server:
  *     {"t":"i","d":"...","seq":N,"cid":"..."} — input (keystroke or paste). seq+cid are
  *                          optional reliable-delivery tags: the server applies each
@@ -240,6 +243,19 @@ export function registerWsRoutes(app: FastifyInstance, ctx: SessionPort, getHost
             }
             const force = msg.f === true;
             session.resize(msg.c, msg.r, { viewportType, force });
+            // Report the geometry that actually took. Resize used to be
+            // write-only, so a client whose request was declined by the
+            // arbitration above — or floored, or overridden by another device
+            // — had no way to find out, and went on rendering a CLI's repaints
+            // against a screen shape that did not exist (issue #464). Sent
+            // unconditionally: it is ~30 bytes on a debounced, rare message,
+            // and always-send means the client needs no "did it take?" state.
+            // A session with no pane sends nothing at all: its `_ptyCols`/
+            // `_ptyRows` are constructor defaults no process was ever told.
+            const applied = session.ptyGeometry;
+            if (applied && socket.readyState === 1) {
+              socket.send(`{"t":"zc","c":${applied.cols},"r":${applied.rows}}`);
+            }
           }
         } catch {
           // Ignore malformed messages

src/web/server.ts

@@ -463,6 +463,11 @@ export class WebServer extends EventEmitter {
     this.mux.on('statsUpdated', (sessions) => {
       this.broadcast(SseEvent.MuxStatsUpdated, sessions);
     });
+    // Ark0N/Codeman#446 — a pane read finished. Internal only: the field reaches
+    // the browser on `session:updated`, and no SSE event was added for it.
+    this.mux.on('paneExitsUpdated', () => {
+      this.applyPaneExits();
+    });
 
     // COD-108 — remote-session auto-reconnect. The TmuxManager watcher detects a
     // dead remote pane and emits `remoteSessionDropped`; the session owner (here)
@@ -1683,6 +1688,27 @@ export class WebServer extends EventEmitter {
         () => `<script>window.__codemanCustomModelClis=${customModelClisJson};</script>\n</head>`
       );
     }
+    // How many columns each run mode indents its transcript by, so a copy can drop
+    // that much. Read off `capabilities` like the payload above and never as an id
+    // list here, so a CLI that declares a gutter later needs no frontend change.
+    // Ids and small integers only, no user-settable strings, so JSON.stringify
+    // alone is enough (same reasoning as __codemanCliAvailable's booleans).
+    //
+    // ⚠️ Outside the `if (!soloSessionId)` block above, unlike every other payload
+    // here: a detached session window (`/session/:id`) runs a terminal, so Ctrl+C
+    // copies there, and an absent map reads as "no session gets a strip". The
+    // toggle used to work in the main window and do nothing in the popup on the
+    // same device. This needs no availability probe, so it costs a solo window
+    // nothing that the run menu's own payloads would have cost it.
+    const gutterClis: Record<string, number> = {};
+    for (const entry of enabledClis()) {
+      const columns = entry.capabilities.transcriptGutter;
+      if (typeof columns === 'number') gutterClis[entry.id] = columns;
+    }
+    html = html.replace(
+      '</head>',
+      () => `<script>window.__codemanTranscriptGutter=${JSON.stringify(gutterClis)};</script>\n</head>`
+    );
     if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') {
       html = html.replace('</head>', () => `<script>window.__codemanGestureAvailable=true;</script>\n</head>`);
       if (settings.gestureControlEnabled === true) {
@@ -2455,6 +2481,36 @@ export class WebServer extends EventEmitter {
     this.sse.broadcastSessionStateDebounced(sessionId);
   }
 
+  /**
+   * Fold the latest pane readings into the sessions they belong to
+   * (Ark0N/Codeman#446). A reading that changes a session's answer persists the
+   * record and pushes a `session:updated`, which is how the tab learns; a read
+   * that repeats what the last one said costs nothing.
+   *
+   * The answer is pulled per session from the mux rather than taken off a
+   * broadcast payload. The mux reports the RAW pane reading, which for a remote
+   * or docker session is the death of an ssh client or a `docker exec` rather
+   * than of the agent, so it must not travel to a browser at all;
+   * `Session.setPaneExit()` is where that scoping is applied.
+   *
+   * Nothing here touches `status` or `pid`. `status: 'error'` belongs to the
+   * PTY-exit breaker and makes the browser offer a restart, and a null `pid` is
+   * what makes the browser re-attach and launch a fresh CLI.
+   */
+  private applyPaneExits(): void {
+    const getPaneExit = this.mux.getPaneExit?.bind(this.mux);
+    if (!getPaneExit) return;
+    for (const session of this.sessions.values()) {
+      const muxName = session.muxName;
+      // No pane, so nothing to report — and `setPaneExit()` would force UNKNOWN
+      // for such a session anyway.
+      if (!muxName) continue;
+      if (!session.setPaneExit(getPaneExit(muxName))) continue;
+      this.persistSessionState(session);
+      this.broadcastSessionStateDebounced(session.id);
+    }
+  }
+
   // ========== Web Push ==========
 
   /** Map SSE event names to push notification payloads */
@@ -3336,6 +3392,15 @@ export class WebServer extends EventEmitter {
               // the conversation the CLI was on when the server stopped, which is
               // what a re-attach must point the viewer at instead of the launch id.
               claudeSessionChain: savedState?.claudeSessionChain,
+              // What the previous run last observed of this pane's agent. Carried
+              // over so the first persist after boot does not blank a record that
+              // says the agent exited; the attach below drops it, and the
+              // pane-exit watcher's own tick replaces it with a first-hand
+              // reading (not the stats collector — see `startPaneExitWatcher`).
+              paneExit: savedState?.paneExit,
+              // A record rebuilt from the socket has no provenance, so its
+              // apparent locality is a guess (see `MuxSession.discovered`).
+              discoveredMuxSession: muxSession.discovered,
               // The pane's last output, previous run's value. Without it every
               // restart restamped all sessions "now" (constructor + the attach
               // repaint within the same second), flattening the home screens'
@@ -3545,6 +3610,15 @@ export class WebServer extends EventEmitter {
         (this.mux as { startMouseModeSync: (ms?: number) => void }).startMouseModeSync();
       }
 
+      // Ark0N/Codeman#446 — poll every pane for an exited agent. Always start,
+      // even with no sessions, for the same reason as the two watchers around
+      // it: sessions arrive later. Deliberately NOT folded into the stats
+      // collector above, which the browser arms and disarms with the Monitor
+      // panel and which boot skips entirely when nothing was recovered.
+      if ('startPaneExitWatcher' in this.mux) {
+        (this.mux as { startPaneExitWatcher: (ms?: number) => void }).startPaneExitWatcher();
+      }
+
       // COD-108 — start the remote-session auto-reconnect watcher (tmux only).
       // Always-on (D3) with a `remoteAutoReconnect` kill-switch the watcher reads
       // each tick. Start even with no sessions — remote sessions may arrive later.

src/web/session-listener-wiring.ts

@@ -43,6 +43,7 @@ export interface SessionListenerRefs {
   exit: (code: number | null) => void;
   working: () => void;
   idle: () => void;
+  watchingChanged: () => void;
   taskCreated: (task: BackgroundTask) => void;
   taskUpdated: (task: BackgroundTask) => void;
   taskCompleted: (task: BackgroundTask) => void;
@@ -263,6 +264,17 @@ export function createSessionListeners(session: Session, deps: SessionListenerDe
       }
     },
 
+    /**
+     * Pushes the session state when `Session.watching` changes without the status
+     * changing with it. That is the badge appearing or, more often, going away: a CLI can
+     * finish its background work without taking a turn, so the row is idle before and
+     * after and no other broadcast fires. There is no SSE event of its own, because the
+     * badge reads off the session payload every surface already has.
+     */
+    watchingChanged: () => {
+      deps.broadcastSessionStateDebounced(session.id);
+    },
+
     // ─── Background Task Events ──────────────────────────────
 
     /** Broadcasts `task:created` — new background task discovered */
@@ -495,6 +507,7 @@ export function attachSessionListeners(session: Session, refs: SessionListenerRe
   session.on('exit', refs.exit);
   session.on('working', refs.working);
   session.on('idle', refs.idle);
+  session.on('watchingChanged', refs.watchingChanged);
   session.on('taskCreated', refs.taskCreated);
   session.on('taskUpdated', refs.taskUpdated);
   session.on('taskCompleted', refs.taskCompleted);
@@ -531,6 +544,7 @@ export function detachSessionListeners(session: Session, refs: SessionListenerRe
   session.off('exit', refs.exit);
   session.off('working', refs.working);
   session.off('idle', refs.idle);
+  session.off('watchingChanged', refs.watchingChanged);
   session.off('taskCreated', refs.taskCreated);
   session.off('taskUpdated', refs.taskUpdated);
   session.off('taskCompleted', refs.taskCompleted);

test/agent-image-build-args-parity.test.ts

@@ -20,11 +20,15 @@ import { fileURLToPath } from 'node:url';
 import {
   agentImageBuildArgPairs as mjsPairs,
   agentImageNpmPackages as mjsPackages,
+  GIT_HOST_CLI_BUILD_ARGS as mjsGitHostArgs,
+  gitHostCliBuildArgPairs as mjsGitHostPairs,
 } from '../scripts/lib/cli-catalog.mjs';
 import {
   agentImageBuildArgPairs as tsPairs,
   agentImageBuildArgs,
   agentImageNpmPackages as tsPackages,
+  GIT_HOST_CLI_BUILD_ARGS as tsGitHostArgs,
+  gitHostCliBuildArgPairs as tsGitHostPairs,
 } from '../src/docker-hosts.js';
 
 const CATALOG = JSON.parse(readFileSync(fileURLToPath(new URL('../config/clis.stock.json', import.meta.url)), 'utf-8'));
@@ -96,3 +100,48 @@ describe('agent-image build args: the .mjs and the TS mirror agree', () => {
     expect(extract(tsSource, 'docker-hosts.ts')).toBe(extract(mjsSource, 'cli-catalog.mjs'));
   });
 });
+
+describe('optional gh / az in the agent image: both producers pass the same switches', () => {
+  const ENV_GH = 'CODEMAN_AGENT_IMAGE_INSTALL_GH';
+  const ENV_AZ = 'CODEMAN_AGENT_IMAGE_INSTALL_AZ';
+
+  it('map the same environment variables to the same Dockerfile ARGs', () => {
+    expect(tsGitHostArgs).toEqual(mjsGitHostArgs);
+    expect(tsGitHostArgs.map(([, arg]) => arg)).toEqual(['CODEMAN_INSTALL_GH', 'CODEMAN_INSTALL_AZ']);
+  });
+
+  it('agree for every combination, and an unset or empty variable adds nothing', () => {
+    for (const gh of [undefined, '', '0', '1']) {
+      for (const az of [undefined, '', '0', '1']) {
+        const env: NodeJS.ProcessEnv = {};
+        if (gh !== undefined) env[ENV_GH] = gh;
+        if (az !== undefined) env[ENV_AZ] = az;
+        const expected: Array<[string, string]> = [];
+        if (gh) expected.push(['CODEMAN_INSTALL_GH', gh]);
+        if (az) expected.push(['CODEMAN_INSTALL_AZ', az]);
+        expect(tsGitHostPairs(env)).toEqual(expected);
+        expect(mjsGitHostPairs(env)).toEqual(expected);
+        expect(tsPairs(env)).toEqual(mjsPairs(CATALOG, env));
+      }
+    }
+  });
+
+  it('keeps the default argv unchanged when neither variable is set', () => {
+    expect(tsPairs({})).toEqual([['CLI_NPM_PACKAGES', tsPackages().join(' ')]]);
+  });
+
+  it('refuses anything but 0 or 1 on both sides, naming the variable', () => {
+    for (const bad of ['yes', 'true', '2', ' 1', '0 && echo']) {
+      expect(() => tsGitHostPairs({ [ENV_AZ]: bad })).toThrow(new RegExp(ENV_AZ));
+      expect(() => mjsGitHostPairs({ [ENV_AZ]: bad })).toThrow(new RegExp(ENV_AZ));
+    }
+  });
+
+  it('both Dockerfiles declare the switches, defaulting to OFF (opt-in)', () => {
+    for (const file of ['../docker/agent.Dockerfile', '../docker/server.Dockerfile']) {
+      const dockerfile = readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf-8');
+      expect(dockerfile, file).toMatch(/^ARG CODEMAN_INSTALL_GH=0$/m);
+      expect(dockerfile, file).toMatch(/^ARG CODEMAN_INSTALL_AZ=0$/m);
+    }
+  });
+});

test/approval-inbox.test.ts

@@ -330,6 +330,58 @@ describe('ApprovalInbox', () => {
     expect(inbox.getById(second.id)).toBeDefined();
   });
 
+  describe('a session watching its own background work', () => {
+    it('opens its idle prompt already acknowledged, and says why', () => {
+      const item = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'idle', watching: '1 monitor' });
+      expect(item.acknowledgedAt).toBe(item.createdAt);
+      expect(item.acknowledgedReason).toBe('watching 1 monitor');
+    });
+
+    it('keeps the prompt pending and answerable: only its alert is spent', () => {
+      // Acknowledging rather than skipping creation is what makes a wrong label cheap.
+      // The prompt is real either way, and this way it is still in the drawer, still
+      // answerable and still Read My Mind context.
+      const item = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'idle', watching: '2 shells' });
+      expect(inbox.listPending().map((i) => i.id)).toEqual([item.id]);
+      expect(inbox.getForSession('s1')?.id).toBe(item.id);
+      expect(inbox.verifyStillAnswerable(item.id)).toBe(true);
+    });
+
+    it('never pre-acknowledges a dialog that blocks the agent', () => {
+      // A permission or question dialog blocks the turn whatever else the agent started,
+      // so watching says nothing about whether a human is needed.
+      for (const kind of ['permission', 'question'] as const) {
+        const item = inbox.notePrompt({ sessionId: `s-${kind}`, sessionName: 'w1', kind, watching: '1 monitor' });
+        expect(item.acknowledgedAt).toBeUndefined();
+        expect(item.acknowledgedReason).toBeUndefined();
+      }
+    });
+
+    it('leaves an ordinary idle prompt alone', () => {
+      for (const watching of [undefined, null, '']) {
+        const item = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'idle', watching });
+        expect(item.acknowledgedAt).toBeUndefined();
+      }
+    });
+
+    it('re-arms by itself once the background work is over', () => {
+      // The next prompt supersedes this one and is built fresh, so nothing has to
+      // remember to clear the flag when the monitor ends.
+      const watched = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'idle', watching: '1 monitor' });
+      expect(watched.acknowledgedAt).toBeDefined();
+      const after = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'idle' });
+      expect(after.id).not.toBe(watched.id);
+      expect(after.acknowledgedAt).toBeUndefined();
+      expect(after.acknowledgedReason).toBeUndefined();
+    });
+
+    it('cannot be acknowledged a second time by a human opening the session', () => {
+      const item = inbox.notePrompt({ sessionId: 's1', sessionName: 'w1', kind: 'idle', watching: '1 monitor' });
+      expect(inbox.acknowledge('s1')).toBeUndefined();
+      expect(inbox.getById(item.id)?.acknowledgedReason).toBe('watching 1 monitor');
+    });
+  });
+
   describe('verifyStillAnswerable', () => {
     it('resolves the item and refuses when a parsed dialog left the screen', () => {
       const { resolved } = collect(inbox);

test/capture-geometry-retry.browser.test.ts

@@ -136,9 +136,10 @@ async function stubTerminalDynamic(
 /**
  * Answer every fetch with the geometry the client itself is asking for, read
  * live from the page. That is the clamp signature: `getTerminalDimensions()`
- * floors at 40x10 while `fitAddon.fit()` does not, so a small enough viewport
- * makes the pane permanently bigger than the terminal at a size the client
- * requested itself.
+ * floors at 40x10, and since #464 `syncTerminalGeometry()` applies that floor
+ * to xterm too — so at a small enough viewport the pane, the report and the
+ * terminal all agree on the floored size, which is the case the equality guard
+ * is left covering.
  */
 async function stubTerminalAtRequestedSize(page: Page, counter: { n: number; urls: string[] }) {
   await page.route('**/api/sessions/*/terminal*', async (route) => {
@@ -498,13 +499,22 @@ describe('a capture bigger than the terminal', () => {
   }, 60_000);
 
   it('does not replay a pane already at the size the client asked for', async () => {
-    // `getTerminalDimensions()` floors at 40x10 while `fitAddon.fit()` does
-    // not, so a viewport this small leaves the terminal shorter than the size
-    // the client itself requests, and the pane obligingly draws at the floored
-    // size. The captured height then exceeds the terminal's forever. A replay
-    // cannot converge, because it re-requests the same floored size and
-    // captures the same frame, so without the equality guard this retries on
-    // every tab switch for the life of the page.
+    // ⚠️ The premise of this case CHANGED with issue #464, and the old one can
+    // never hold again. It used to be the clamp: `getTerminalDimensions()`
+    // floors at 40x10 while `fitAddon.fit()` did not, so a viewport this small
+    // left the terminal shorter than the size the client itself requested, the
+    // pane drew at the floored size, and the captured height exceeded the
+    // terminal's forever — a replay that re-requested the same floored size and
+    // captured the same frame, on every tab switch, for the life of the page.
+    //
+    // `syncTerminalGeometry()` now applies the floor to xterm as well, so the
+    // browser terminal IS the size it reports and that divergence is gone at
+    // the source. The case survives on its own terms — a pane already drawing
+    // at the requested size must not be replayed, because the retry would
+    // capture the identical frame — and its premise is now the #464 invariant
+    // itself, asserted below: the floored report and the terminal agree. That
+    // is a stronger guard than the old one, since the clamp coming back would
+    // fail it here rather than silently restoring the replay loop.
     context = await browser.newContext({ viewport: { width: 320, height: 200 } });
     page = await context.newPage();
     const sessionId = await openSession(page);
@@ -514,8 +524,9 @@ describe('a capture bigger than the terminal', () => {
     await consumeFullHistory(page, sessionId, fetches);
     await select(page, sessionId, { forceReload: true });
 
-    // The premise: the floor really does bind here. Without this the case
-    // would pass on any viewport, proving nothing.
+    // The premise: the floor really does bind at this viewport — otherwise the
+    // case would pass on any viewport, proving nothing — AND the terminal holds
+    // exactly what it reports, which is what stops the old replay loop.
     const requested = await page.evaluate(
       () =>
         (
@@ -523,7 +534,20 @@ describe('a capture bigger than the terminal', () => {
         ).app.getTerminalDimensions?.() ?? null
     );
     expect(requested).not.toBeNull();
-    expect(requested!.rows).toBeGreaterThan(await terminalRows(page));
+    const proposed = await page.evaluate(
+      () =>
+        (
+          window as unknown as { app: { fitAddon?: { proposeDimensions?: () => { cols: number; rows: number } } } }
+        ).app.fitAddon?.proposeDimensions?.() ?? null
+    );
+    expect(proposed, 'the terminal could not be measured').not.toBeNull();
+    expect(
+      proposed!.rows < requested!.rows || proposed!.cols < requested!.cols,
+      `the floor must bind at this viewport, or the case proves nothing (proposed ${proposed!.cols}x${proposed!.rows}, reported ${requested!.cols}x${requested!.rows})`
+    ).toBe(true);
+    // The #464 invariant: what the client reports is what the terminal holds.
+    expect(requested!.rows).toBe(await terminalRows(page));
+    expect(requested!.cols).toBe(await terminalCols(page));
 
     expect(fetches.n).toBe(1);
 

test/cli-registry-schema.test.ts

@@ -122,6 +122,49 @@ describe('workDetect.workingLine is guarded like every other config regex', () =
       expect(compileVersionRegex(src), `${entry.id} declares a workingLine the guard refuses`).not.toBeNull();
     }
   });
+
+  it('holds the optional watchingLine to the same guard', () => {
+    expectRejected((e) => {
+      (e.capabilities as Record<string, unknown>).workDetect = {
+        promptGlyph: '>',
+        workingLine: 'working',
+        watchingLine: '(a+)+b',
+      };
+    }, 'this one runs over a pane capture every time a session settles, so it can freeze the event loop the same way');
+  });
+
+  it('bounds how far up the screen a config file may search', () => {
+    // The window is the injection guard: every row it adds is another row the agent
+    // itself may be able to write, and the label is what silences an idle alert.
+    for (const lines of [0, 9, 2.5]) {
+      expectRejected((e) => {
+        (e.capabilities as Record<string, unknown>).workDetect = {
+          promptGlyph: '>',
+          workingLine: 'working',
+          watchingLine: 'chip (\\d+)',
+          watchingLines: lines,
+        };
+      }, 'a config file must not be able to widen the search to the whole pane');
+    }
+  });
+
+  it('refuses a window with no pattern to bound', () => {
+    expectRejected((e) => {
+      (e.capabilities as Record<string, unknown>).workDetect = {
+        promptGlyph: '>',
+        workingLine: 'working',
+        watchingLines: 3,
+      };
+    }, 'a window with nothing to search is a typo whose failure is otherwise silent');
+  });
+
+  it('accepts every shipped watchingLine', () => {
+    for (const entry of STOCK_CLIS) {
+      const src = entry.capabilities.workDetect?.watchingLine;
+      if (!src) continue;
+      expect(compileVersionRegex(src), `${entry.id} declares a watchingLine the guard refuses`).not.toBeNull();
+    }
+  });
 });
 
 describe('no shell text can reach the command line', () => {

test/detached-session-pane-sizing.test.ts

@@ -14,6 +14,12 @@
  * already stood aside on the same condition, so this follows a rule the code
  * had already established.
  *
+ * ⚠️ It returns early BEFORE the local fit, not after (issue #464). The earlier
+ * rule was "withhold the send, never the reflow", which leaves this window's
+ * xterm at a shape the PTY was never told about — and a CLI computes its
+ * repaints from the shape it was told, so that reflow bought a garbled frame
+ * rather than a correct one. Withhold both, or neither.
+ *
  * Loaded via `vm` with a stubbed context (no jsdom — jsdom is broken on this
  * box; see connection-indicator.test.ts), the same way terminal-buffer-flush
  * extracts the real mixin methods from terminal-ui.js.
@@ -56,7 +62,19 @@ function makeApp(overrides: Record<string, unknown> = {}) {
   currentFetch = fetchMock;
   const app = {
     sendResize: mixin.sendResize,
+    // The real chain: sendResize fits, floors and applies through one function
+    // now, so the harness must let it (#464).
+    syncTerminalGeometry: mixin.syncTerminalGeometry,
+    _geometryForResizeRequest: mixin._geometryForResizeRequest,
+    _resizeTerminalTo: mixin._resizeTerminalTo,
+    // Real, so a geometry change really does re-check whether the terminal now
+    // overflows its container (#464 item 4) — the fake DOM has no container, so
+    // it measures nothing and settles on "no overflow", which is the truth here.
+    _scheduleOverflowAffordanceSync: mixin._scheduleOverflowAffordanceSync,
+    _syncTerminalOverflowAffordance: mixin._syncTerminalOverflowAffordance,
+    _onPtyGeometryReport: vi.fn(),
     getTerminalDimensions: () => ({ cols: 120, rows: 40 }),
+    terminal: { cols: 120, rows: 40, resize: vi.fn() },
     fitAddon: { fit: vi.fn() },
     detachedSessions: new Set<string>(),
     isSoloWindow: false,
@@ -77,10 +95,16 @@ describe('detached sessions own their pane size', () => {
     expect(changed).toBe(false);
     // No request: the popup's size stands on the server.
     expect(fetchMock).not.toHaveBeenCalled();
-    // The LOCAL fit still runs, so the dashboard's own xterm stays correct and
-    // tab-rail-resize's single settle-time refit is not swallowed. Same line the
-    // mobile-keyboard guard draws: withhold the send, never the reflow.
-    expect((app.fitAddon as { fit: ReturnType<typeof vi.fn> }).fit).toHaveBeenCalled();
+    // ⚠️ REVERSED by issue #464, deliberately. This used to assert that the
+    // LOCAL fit still ran — "withhold the send, never the reflow" — on the
+    // reasoning that it keeps the dashboard's own xterm correct. It does not:
+    // it leaves this xterm at a shape the PTY was never told about, and Claude
+    // Code computes every repaint from the shape it WAS told, so the frames
+    // land on rows nothing erased. The popup that owns the PTY is drawing for
+    // its own width either way, so the dashboard's reflow was a reflow nothing
+    // was rendering for. Withholding the resize means withholding all of it.
+    expect((app.fitAddon as { fit: ReturnType<typeof vi.fn> }).fit).not.toHaveBeenCalled();
+    expect((app.terminal as { resize: ReturnType<typeof vi.fn> }).resize).not.toHaveBeenCalled();
   });
 
   it('the solo window still sizes the session it displays', async () => {

test/docker-entrypoint.test.ts

@@ -18,10 +18,15 @@
  *    `CODEMAN_CASES_PATH`, so the directory it creates has the owner the
  *    container will accept, and its `git_head_commit` helper (a pure function
  *    over `.git`) resolves the three ref layouts a checkout can have.
+ * 4. `Update-Codeman.sh` (the scripted major update) runs its collision guard
+ *    before its own `--no-cache` build and `down`, removes exactly the two
+ *    build-artefact volumes rather than every volume in the project, and hands
+ *    off to `Start-Codeman.sh`; checked statically and by an end-to-end run
+ *    against a stub `docker`.
  */
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { readFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { readFileSync, mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -33,6 +38,7 @@ const compose = read('docker/docker-compose.yaml');
 const entrypoint = read('docker/entrypoint.sh');
 const dockerfile = read('docker/server.Dockerfile');
 const startScript = read('docker/Start-Codeman.sh');
+const updateScript = read('docker/Update-Codeman.sh');
 
 /** The `- NAME` entries under `cap_add:` (the block ends at the next key at the same indent). */
 function composeCapAdd(text: string): string[] {
@@ -174,6 +180,314 @@ describe('Start-Codeman.sh', () => {
   });
 });
 
+describe('Update-Codeman.sh (the scripted major-update path — docker/README.md "Major updates")', () => {
+  it('parses under bash -n', () => {
+    execFileSync('bash', ['-n', join(ROOT, 'docker/Update-Codeman.sh')]);
+  });
+
+  it('force-rebuilds with --no-cache BEFORE stopping the stack, THEN hands off to Start-Codeman.sh via `bash`', () => {
+    const build = updateScript.indexOf('"${compose_command[@]}" build --no-cache');
+    const down = updateScript.indexOf('"${compose_command[@]}" down');
+    const handoff = updateScript.indexOf('exec bash "$script_dir/Start-Codeman.sh"');
+    expect(build).toBeGreaterThan(-1);
+    expect(down).toBeGreaterThan(build);
+    expect(handoff).toBeGreaterThan(down);
+    // A bare `exec "$script_dir/Start-Codeman.sh"` fails EACCES — Start-Codeman.sh
+    // is committed non-executable (100644), same as this script.
+    expect(updateScript).not.toMatch(/exec "\$script_dir\/Start-Codeman\.sh"/);
+  });
+
+  it('resolves the collision guard BEFORE the --no-cache build and the down, not after', () => {
+    // Start-Codeman.sh has no such guard, so this is the only one, and it has
+    // to run before this script's own build, down and volume removal.
+    const projectName = updateScript.indexOf('project_name=$(');
+    const guard = updateScript.indexOf('other_working_dir=$(');
+    const build = updateScript.indexOf('"${compose_command[@]}" build --no-cache');
+    const down = updateScript.indexOf('"${compose_command[@]}" down');
+    expect(projectName).toBeGreaterThan(-1);
+    expect(guard).toBeGreaterThan(projectName);
+    expect(guard).toBeLessThan(build);
+    expect(guard).toBeLessThan(down);
+    expect(updateScript).toMatch(/label=com\.docker\.compose\.project=\$project_name/);
+    expect(updateScript).toMatch(/\{\{\.Label "com\.docker\.compose\.project\.working_dir"\}\}/);
+    expect(updateScript).toMatch(/grep -v -F -x -- "\$script_dir"/);
+  });
+
+  it('clears exactly the two build-artefact volumes by DEFAULT, by label, scoped to the project', () => {
+    expect(updateScript).toMatch(/--keep-volumes\)\s*\n\s*keep_volumes=1/);
+    expect(updateScript).toMatch(/for key in codeman-node-modules codeman-dist; do/);
+    expect(updateScript).toMatch(/--filter "label=com\.docker\.compose\.volume=\$key"/);
+    expect(updateScript).toMatch(/docker volume rm -- "\$volume_name"/);
+    // `down --volumes` survives only as the fallback for an unresolvable
+    // project name, where the label filter could not match anything.
+    const fallback = updateScript.indexOf('"${compose_command[@]}" down --volumes');
+    const warning = updateScript.indexOf('could not resolve the Compose project name');
+    expect(warning).toBeGreaterThan(-1);
+    expect(fallback).toBeGreaterThan(warning);
+  });
+
+  it('--help/-h prints usage and exits 0, rather than falling into the unrecognised-argument branch', () => {
+    expect(updateScript).toMatch(/--help \| -h\)\s*\n\s*printf 'Usage:/);
+    const helpBlock = updateScript.slice(updateScript.indexOf('--help | -h)'), updateScript.indexOf('*)'));
+    expect(helpBlock).toMatch(/exit 0/);
+  });
+
+  it('rejects an unrecognised argument rather than silently ignoring it', () => {
+    expect(updateScript).toMatch(/Error: unrecognised argument/);
+    expect(updateScript).toMatch(/exit 1/);
+  });
+
+  it('resolves the override file exactly like Start-Codeman.sh, so `down` and `up` never target different Compose files', () => {
+    // \r stripped before comparing: git's autocrlf normalises the COMMITTED blob to LF
+    // either way, but a Windows checkout can have already converted one file's line
+    // endings on disk and not the other's (e.g. Start-Codeman.sh checked out before this
+    // script existed), which would fail a raw byte comparison for a reason that has
+    // nothing to do with the two scripts actually agreeing.
+    const normalise = (s: string) => s.replace(/\r\n/g, '\n');
+    const overrideBlock = (script: string) =>
+      normalise(script.slice(script.indexOf('override_yml='), script.indexOf('compose_command=(docker compose')));
+    expect(overrideBlock(updateScript)).toBe(overrideBlock(startScript));
+  });
+
+  it('derives PUID/PGID from the SAME owner_of() helper Start-Codeman.sh uses, so the --no-cache build gets the right build args', () => {
+    const normalise = (s: string) => s.replace(/\r\n/g, '\n');
+    const ownerOfBlock = (script: string) => {
+      const start = script.indexOf('owner_of() {');
+      const end = script.indexOf('\n}', start) + '\n}'.length;
+      return normalise(script.slice(start, end));
+    };
+    expect(ownerOfBlock(updateScript)).toBe(ownerOfBlock(startScript));
+    expect(updateScript).toMatch(/export PUID=\$\{owner_ids%%:\*\}/);
+    expect(updateScript).toMatch(/export PGID=\$\{owner_ids##\*:\}/);
+    // The build must come AFTER PUID/PGID are resolved and exported, or Compose
+    // falls back to its own default of 1000:1000 for the build args.
+    const puidExport = updateScript.indexOf('export PUID=');
+    const build = updateScript.indexOf('"${compose_command[@]}" build --no-cache');
+    expect(puidExport).toBeGreaterThan(-1);
+    expect(build).toBeGreaterThan(puidExport);
+  });
+
+  describe('end-to-end smoke test (a stub `docker` on PATH, logging every invocation)', () => {
+    /**
+     * Reproduces the exact scenario the review on PR #465 caught by hand: a bare
+     * `exec` of a non-executable script exits 126 with no further `docker` calls
+     * at all. Runs the REAL Update-Codeman.sh against a synthetic deployment,
+     * asserting the actual command sequence a shell would issue — string-matching
+     * the source (the tests above) cannot tell a working `exec bash "…"` apart
+     * from a silently-broken bare `exec "…"` the way actually running it can.
+     *
+     * The harness intentionally does NOT create a real Unix socket for
+     * DOCKER_SOCKET (net.createServer().listen(path) is unreliable off Linux —
+     * measured EACCES on this Windows sandbox even outside any container). So the
+     * handoff to Start-Codeman.sh is real and fully exercises this script's own
+     * build/down/handoff sequence, but Start-Codeman.sh's OWN socket check is
+     * expected to then fail — which is itself the proof the handoff worked: a
+     * process that failed to exec would never reach a Start-Codeman.sh-only error
+     * message, and would exit 126, not 1.
+     */
+    // Windows join()/mkdtempSync() paths carry backslashes, which the stub
+    // `docker`'s naive `source "$envfile"` (a shortcut for `docker compose
+    // config --environment`'s own real parsing, which handles this fine) reads
+    // as bash ESCAPE characters and silently drops — `C:\Users\x` becomes
+    // `C:Usersx`. Forward slashes are accepted by git-bash/MSYS on Windows and
+    // by every POSIX shell, so normalising once here sidesteps a harness
+    // artifact that has nothing to do with the scripts under test.
+    const posix = (p: string) => p.replace(/\\/g, '/');
+
+    function runSmokeTest(
+      args: string[],
+      extraEnv: Record<string, string> = {}
+    ): { status: number; stderr: string; log: string[] } {
+      const dir = mkdtempSync(join(tmpdir(), 'codeman-update-smoke-'));
+      try {
+        const dockerDir = join(dir, 'docker');
+        mkdirSync(dockerDir);
+        writeFileSync(join(dockerDir, 'Update-Codeman.sh'), updateScript);
+        writeFileSync(join(dockerDir, 'Start-Codeman.sh'), startScript);
+        writeFileSync(join(dockerDir, 'docker-compose.yaml'), compose);
+
+        const appdataPath = join(dir, 'appdata');
+        const casesPath = join(dir, 'cases');
+        const socketPath = join(dir, 'docker.sock'); // deliberately NOT a real socket — see above
+        mkdirSync(appdataPath);
+        mkdirSync(casesPath);
+        writeFileSync(socketPath, '');
+
+        writeFileSync(
+          join(dockerDir, '.env'),
+          [
+            `CODEMAN_APPDATA_PATH=${posix(appdataPath)}`,
+            `CODEMAN_CASES_PATH=${posix(casesPath)}`,
+            `DOCKER_SOCKET=${posix(socketPath)}`,
+            'CODEMAN_RUNTIME_USER=codeman',
+            'CODEMAN_PORT=3000',
+            'CODEMAN_HOST=127.0.0.1',
+            'CODEMAN_PASSWORD=x',
+            'CODEMAN_USERNAME=admin',
+            'GEMINI_API_KEY=',
+            'CODEMAN_DOCKER_BRIDGE_HOOKS=',
+            'CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=',
+            'TZ=UTC',
+            'CODEMAN_IMAGE=codeman:test',
+            '',
+          ].join('\n')
+        );
+
+        // A stub `docker` that only understands the two `compose config` shapes
+        // both scripts actually issue, and logs every invocation verbatim —
+        // written and chmod+x'd from WITHIN one bash invocation (not
+        // fs.chmodSync, whose Win32 backing does not reliably set the bit this
+        // MSYS bash's own PATH lookup honours — measured, differs from a plain
+        // `chmod +x` issued by bash itself).
+        const binDir = join(dir, 'bin');
+        mkdirSync(binDir);
+        const stub = [
+          '#!/usr/bin/env bash',
+          'echo "docker $*" >> "$CMDLOG"',
+          'if [[ "$1" == "compose" ]]; then',
+          '  shift',
+          '  prev=""',
+          '  envfile=""',
+          '  for a in "$@"; do',
+          '    if [[ "$prev" == "--env-file" ]]; then envfile="$a"; fi',
+          '    prev="$a"',
+          '  done',
+          '  if [[ " $* " == *" config "* && " $* " == *" --environment "* ]]; then',
+          '    source "$envfile"',
+          '    echo "CODEMAN_APPDATA_PATH=$CODEMAN_APPDATA_PATH"',
+          '    echo "CODEMAN_CASES_PATH=$CODEMAN_CASES_PATH"',
+          '    echo "DOCKER_SOCKET=$DOCKER_SOCKET"',
+          '    exit 0',
+          '  fi',
+          '  if [[ " $* " == *" config "* && " $* " == *" --format json "* ]]; then',
+          '    if [[ -n "${STUB_CONFIG_JSON_FAIL:-}" ]]; then echo "unknown flag: --format" >&2; exit 1; fi',
+          // Real `docker compose config --format json` pretty-prints, so
+          // `"name"` starts its OWN line rather than sharing one with `{` -
+          // the sed extraction both scripts use anchors on that, and a
+          // compact one-liner here would silently resolve project_name to
+          // empty, exercising neither script's guard the way real Compose
+          // output does.
+          '    printf \'{\\n  "name": "codeman"\\n}\\n\'',
+          '    exit 0',
+          '  fi',
+          '  exit 0',
+          'fi',
+          // Mirrors the guard's own `docker ps -a --filter ... --format
+          // '{{.Label "com.docker.compose.project.working_dir"}}'` call.
+          // Empty by default (no collision) so the existing smoke tests above
+          // see no output here and proceed exactly as before; a test that
+          // wants to exercise the guard itself sets STUB_PS_WORKING_DIR.
+          'if [[ "$1" == "ps" && -n "${STUB_PS_WORKING_DIR:-}" ]]; then',
+          '  printf "%s\\n" "$STUB_PS_WORKING_DIR"',
+          '  exit 0',
+          'fi',
+          // `docker volume ls -q --filter label=com.docker.compose.volume=<key> ...`:
+          // answer with the Compose-style `<project>_<key>` name for that key.
+          'if [[ "$1" == "volume" && "$2" == "ls" ]]; then',
+          '  for a in "$@"; do',
+          '    case "$a" in label=com.docker.compose.volume=*) echo "codeman_${a#label=com.docker.compose.volume=}" ;; esac',
+          '  done',
+          '  exit 0',
+          'fi',
+          'exit 0',
+        ].join('\n');
+        const stubPath = join(binDir, 'docker');
+        writeFileSync(stubPath, stub);
+        execFileSync('bash', ['-c', `chmod +x '${stubPath}'`]);
+
+        const logPath = join(dir, 'cmdlog.txt');
+        writeFileSync(logPath, '');
+
+        let status = 0;
+        let stderr = '';
+        try {
+          execFileSync('bash', [join(dockerDir, 'Update-Codeman.sh'), ...args], {
+            env: { ...process.env, PATH: `${binDir}:${process.env.PATH}`, CMDLOG: logPath, ...extraEnv },
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } catch (err) {
+          const e = err as { status?: number; stderr?: string };
+          status = e.status ?? 1;
+          stderr = e.stderr ?? '';
+        }
+
+        const log = readFileSync(logPath, 'utf-8')
+          .split('\n')
+          .filter((l) => l.trim());
+        return { status, stderr, log };
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    }
+
+    it('default: build --no-cache, THEN a plain down, THEN removes exactly the two volumes, THEN the handoff runs Start-Codeman.sh', () => {
+      const { status, stderr, log } = runSmokeTest([]);
+
+      const buildIdx = log.findIndex((l) => l.includes('build --no-cache'));
+      const downIdx = log.findIndex((l) => / down(\s|$)/.test(l));
+      expect(buildIdx).toBeGreaterThan(-1);
+      expect(downIdx).toBeGreaterThan(buildIdx);
+      expect(log[downIdx]).not.toContain('--volumes');
+      expect(log.some((l) => l.includes('down --volumes'))).toBe(false);
+      const removed = log.filter((l) => l.startsWith('docker volume rm'));
+      expect(removed).toEqual([
+        'docker volume rm -- codeman_codeman-node-modules',
+        'docker volume rm -- codeman_codeman-dist',
+      ]);
+      expect(log.findIndex((l) => l.startsWith('docker volume rm'))).toBeGreaterThan(downIdx);
+
+      // Proof the handoff really executed Start-Codeman.sh rather than dying
+      // with EACCES right after printing "Handing off...": more `docker`
+      // invocations appear AFTER the down, which only Start-Codeman.sh's own
+      // config-resolution lines would produce.
+      const configCallsAfterDown = log.slice(downIdx + 1).filter((l) => l.includes('config'));
+      expect(configCallsAfterDown.length).toBeGreaterThan(0);
+
+      // A working handoff fails HONESTLY at Start-Codeman.sh's own socket
+      // check (this harness deliberately supplies no real Unix socket) — never
+      // with an EACCES/126 from a broken `exec`.
+      expect(status).toBe(1);
+      expect(stderr).toMatch(/DOCKER_SOCKET is not a Unix socket/);
+      expect(stderr).not.toMatch(/permission denied/i);
+    });
+
+    it('--keep-volumes: a plain `down`, with no --volumes flag', () => {
+      const { log } = runSmokeTest(['--keep-volumes']);
+      const downLine = log.find((l) => / down(\s|$)/.test(l));
+      expect(downLine).toBeDefined();
+      expect(downLine).not.toContain('--volumes');
+      expect(log.some((l) => l.startsWith('docker volume rm'))).toBe(false);
+    });
+
+    it('reports a failing first `docker compose config` call instead of exiting silently', () => {
+      const { status, stderr, log } = runSmokeTest([], { STUB_CONFIG_JSON_FAIL: '1' });
+      expect(status).not.toBe(0);
+      expect(stderr).toMatch(/docker compose config --format json` failed/);
+      expect(stderr).toMatch(/unknown flag: --format/);
+      expect(log.some((l) => l.includes('build --no-cache'))).toBe(false);
+    });
+
+    it('still refuses when an unlabelled container prints an empty line ahead of the other checkout', () => {
+      const { status, stderr, log } = runSmokeTest([], { STUB_PS_WORKING_DIR: '\n/some/other/checkout/docker' });
+      expect(status).toBe(1);
+      expect(stderr).toMatch(/already in use by a DIFFERENT checkout/);
+      expect(log.some((l) => l.includes('build --no-cache'))).toBe(false);
+    });
+
+    it('refuses BEFORE the --no-cache build when the resolved project belongs to a different checkout', () => {
+      // Start-Codeman.sh has no such guard, so nothing downstream of this
+      // script would catch the collision.
+      const { status, stderr, log } = runSmokeTest([], { STUB_PS_WORKING_DIR: '/some/other/checkout/docker' });
+      expect(status).toBe(1);
+      expect(stderr).toMatch(/already in use by a DIFFERENT checkout/);
+      expect(stderr).toContain('/some/other/checkout/docker');
+      expect(log.some((l) => l.includes('build --no-cache'))).toBe(false);
+      expect(log.some((l) => / down(\s|$)/.test(l))).toBe(false);
+    });
+  });
+});
+
 describe('git_head_commit resolves every ref layout a checkout can have', () => {
   let base: string;
   const git = (cwd: string, ...args: string[]) =>

test/docker-hosts.test.ts

@@ -351,6 +351,70 @@ describe('resolveDockerCredentialArtifacts (isolated codex/gemini/gcloud/opencod
     expect(mounts.filter((m) => m.readonly && m.dst.includes('cred-seeds')).length).toBeGreaterThanOrEqual(3);
   });
 
+  /** Host files for both opt-in stores, present whether or not the switches are on. */
+  function writeGhAzHostFiles(): void {
+    mkdirSync(join(home, '.config', 'gh'), { recursive: true });
+    writeFileSync(join(home, '.config', 'gh', 'hosts.yml'), '');
+    writeFileSync(join(home, '.config', 'gh', 'config.yml'), '');
+    mkdirSync(join(home, '.azure'), { recursive: true });
+    writeFileSync(join(home, '.azure', 'azureProfile.json'), '{}');
+    writeFileSync(join(home, '.azure', 'msal_token_cache.json'), '{}');
+  }
+  const isGhOrAz = (p: string) => /\.azure|\.config[\\/]gh/.test(p);
+
+  it('gh + az: the DEFAULT environment seeds neither, even when the host files exist', () => {
+    writeGhAzHostFiles();
+    for (const env of [{}, { CODEMAN_AGENT_IMAGE_INSTALL_GH: '0', CODEMAN_AGENT_IMAGE_INSTALL_AZ: '' }]) {
+      const { mounts, seedCopies } = resolveDockerCredentialArtifacts(home, env);
+      expect(mounts.filter((m) => isGhOrAz(m.src))).toEqual([]);
+      expect(seedCopies.filter((s) => isGhOrAz(s.to))).toEqual([]);
+    }
+  });
+
+  it('gh + az: each store follows ONLY its own switch, and only the exact value 1', () => {
+    writeGhAzHostFiles();
+    const dests = (env: NodeJS.ProcessEnv) => resolveDockerCredentialArtifacts(home, env).seedCopies.map((s) => s.to);
+    const ghOnly = dests({ CODEMAN_AGENT_IMAGE_INSTALL_GH: '1' });
+    expect(ghOnly).toContain('/home/agent/.config/gh/hosts.yml');
+    expect(ghOnly.some((d) => d.includes('.azure'))).toBe(false);
+    const azOnly = dests({ CODEMAN_AGENT_IMAGE_INSTALL_AZ: '1' });
+    expect(azOnly).toContain('/home/agent/.azure/msal_token_cache.json');
+    expect(azOnly.some((d) => d.includes('.config/gh'))).toBe(false);
+    expect(
+      dests({ CODEMAN_AGENT_IMAGE_INSTALL_GH: 'true', CODEMAN_AGENT_IMAGE_INSTALL_AZ: 'yes' }).some(isGhOrAz)
+    ).toBe(false);
+  });
+
+  it('gh + az: seed only the sign-in files, never logs/extensions/caches', () => {
+    mkdirSync(join(home, '.config', 'gh'), { recursive: true });
+    writeFileSync(join(home, '.config', 'gh', 'hosts.yml'), '');
+    writeFileSync(join(home, '.config', 'gh', 'config.yml'), '');
+    mkdirSync(join(home, '.azure', 'logs'), { recursive: true });
+    mkdirSync(join(home, '.azure', 'cliextensions'), { recursive: true });
+    writeFileSync(join(home, '.azure', 'azureProfile.json'), '{}');
+    writeFileSync(join(home, '.azure', 'msal_token_cache.json'), '{}');
+    writeFileSync(join(home, '.azure', 'config'), '');
+
+    const { mounts, seedCopies } = resolveDockerCredentialArtifacts(home, {
+      CODEMAN_AGENT_IMAGE_INSTALL_GH: '1',
+      CODEMAN_AGENT_IMAGE_INSTALL_AZ: '1',
+    });
+    const dests = seedCopies.map((s) => s.to);
+    expect(dests).toContain('/home/agent/.config/gh/hosts.yml');
+    expect(dests).toContain('/home/agent/.config/gh/config.yml');
+    expect(dests).toContain('/home/agent/.azure/azureProfile.json');
+    expect(dests).toContain('/home/agent/.azure/msal_token_cache.json');
+    expect(dests).toContain('/home/agent/.azure/config');
+    // Absent files are skipped, and nothing outside the sign-in set is seeded.
+    expect(dests).not.toContain('/home/agent/.azure/service_principal_entries.json');
+    expect(dests.some((d) => d.includes('logs') || d.includes('cliextensions'))).toBe(false);
+    expect(seedCopies.filter((s) => /\.azure|\.config\/gh/.test(s.to)).every((s) => !s.recursive)).toBe(true);
+    // Every host credential file rides a READ-ONLY mount, so the container never writes back.
+    const credMounts = mounts.filter((m) => /\.azure|\.config[\\/]gh/.test(m.src));
+    expect(credMounts.length).toBe(5);
+    expect(credMounts.every((m) => m.readonly)).toBe(true);
+  });
+
   it('gates every artifact on existsSync (absent stores contribute nothing)', () => {
     const { mounts, seedCopies } = resolveDockerCredentialArtifacts(home);
     expect(mounts).toEqual([]);

test/dropped-output-recovery.test.ts

@@ -0,0 +1,272 @@
+// Port: none (pure policy + the real scheduler from app.js under a fake clock).
+//
+// `_onSessionTerminal` drops an incoming frame once the app-owned render queues
+// hold 128KB. That is the right call — the alternative is an unbounded backlog —
+// but a hole in a TUI byte stream is a desynced cursor, and a desynced cursor is
+// muffled text (issue #464). The drop is only half of it; the recovery has to
+// actually happen.
+//
+// ⚠️ It used to be a fire-and-forget timer: it nulled its own handle and then
+// called `_onSessionNeedsRefresh()`, which opens with four early returns. Two of
+// them — a buffer load in flight, a refresh already owning this session — are
+// MOST likely to be true during exactly the output burst that caused the drop,
+// so the recovery was silently lost precisely when it was needed, and those
+// bytes were never replayed.
+//
+// The test that matters here is `retries when the refresh was skipped`, paired
+// with `does not retry once a repaint happened`. Either one alone would pass
+// against the old fire-and-forget code; only the contrast pins the fix.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+
+const publicDir = resolve(import.meta.dirname, '../src/web/public');
+const read = (rel: string) => readFileSync(resolve(import.meta.dirname, '..', rel), 'utf8');
+
+type RetryState = { repainted: boolean; timedOut?: boolean; attempt: number; stillActive: boolean };
+
+function loadConstants() {
+  const context = vm.createContext({ window: {}, globalThis: {} });
+  vm.runInContext(readFileSync(resolve(publicDir, 'constants.js'), 'utf8'), context, { filename: 'constants.js' });
+  return (
+    context.window as {
+      CodemanDroppedOutput: {
+        shouldRetryDroppedOutputRecovery: (s: RetryState) => boolean;
+        DROP_RECOVERY_DELAY_MS: number;
+        DROP_RECOVERY_MAX_ATTEMPTS: number;
+      };
+    }
+  ).CodemanDroppedOutput;
+}
+
+const { shouldRetryDroppedOutputRecovery, DROP_RECOVERY_MAX_ATTEMPTS, DROP_RECOVERY_DELAY_MS } = loadConstants();
+
+describe('shouldRetryDroppedOutputRecovery', () => {
+  it('retries a recovery that did not repaint', () => {
+    expect(shouldRetryDroppedOutputRecovery({ repainted: false, attempt: 0, stillActive: true })).toBe(true);
+  });
+
+  it('stops as soon as something repainted', () => {
+    expect(shouldRetryDroppedOutputRecovery({ repainted: true, attempt: 0, stillActive: true })).toBe(false);
+  });
+
+  it('stops when the reader has moved to another session', () => {
+    // selectSession repaints from the server on its own, so a retry here would
+    // be a second replay of a buffer that is about to be written anyway.
+    expect(shouldRetryDroppedOutputRecovery({ repainted: false, attempt: 0, stillActive: false })).toBe(false);
+  });
+
+  it('does not retry a refresh that died at the fetch deadline', () => {
+    // A stalled link, not contention: each retry would be another full capture
+    // waiting out a deadline of up to two minutes.
+    expect(shouldRetryDroppedOutputRecovery({ repainted: false, timedOut: true, attempt: 0, stillActive: true })).toBe(
+      false
+    );
+  });
+
+  it('gives up at the cap rather than looping against the API forever', () => {
+    const last = DROP_RECOVERY_MAX_ATTEMPTS - 1;
+    expect(shouldRetryDroppedOutputRecovery({ repainted: false, attempt: last - 1, stillActive: true })).toBe(true);
+    expect(shouldRetryDroppedOutputRecovery({ repainted: false, attempt: last, stillActive: true })).toBe(false);
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// The real scheduler, from app.js, under a fake clock.
+// ───────────────────────────────────────────────────────────────────────────
+
+function loadAppPrototype(): Record<string, unknown> {
+  const context = vm.createContext({
+    console: { ...console, log: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    performance: { now: () => 0 },
+    setInterval: vi.fn(),
+    clearInterval: vi.fn(),
+    // ⚠️ Delegated, not captured. Baking the real `setTimeout` into the context
+    // puts the scheduler on a clock `vi.useFakeTimers()` cannot reach, and the
+    // retry behaviour under test is entirely a matter of timers firing. These
+    // arrows resolve the identifier from the global at CALL time, so the fake
+    // clock installed later still owns them.
+    setTimeout: (fn: () => void, ms?: number) => setTimeout(fn, ms),
+    clearTimeout: (id: ReturnType<typeof setTimeout>) => clearTimeout(id),
+    requestAnimationFrame: vi.fn(),
+    HTMLCanvasElement: class HTMLCanvasElement {},
+    WebSocket: { OPEN: 1 },
+    fetch: vi.fn(),
+    document: { addEventListener: vi.fn(), getElementById: () => null, querySelector: () => null },
+    localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() },
+    window: { addEventListener: vi.fn(), removeEventListener: vi.fn() },
+    MobileDetection: { isTouchDevice: () => false },
+  });
+  vm.runInContext(
+    `${readFileSync(resolve(publicDir, 'constants.js'), 'utf8')}\n` +
+      `${readFileSync(resolve(publicDir, 'app.js'), 'utf8')}\n` +
+      `globalThis.__CodemanApp = CodemanApp;\nglobalThis.__crashDiag = _crashDiag;`,
+    context
+  );
+  crashTrail = (context as { __crashDiag: { _entries: string[] } }).__crashDiag._entries;
+  return (context as { __CodemanApp: { prototype: Record<string, unknown> } }).__CodemanApp.prototype;
+}
+
+let crashTrail: string[] = [];
+const proto = loadAppPrototype();
+const SESSION = 'session-A';
+
+/** A minimal app carrying only what the scheduler touches. */
+function makeApp(refresh: () => unknown) {
+  const calls: string[] = [];
+  return {
+    calls,
+    app: {
+      _scheduleDroppedOutputRecovery: proto._scheduleDroppedOutputRecovery,
+      activeSessionId: SESSION,
+      _clientDropRecoveryTimer: null as ReturnType<typeof setTimeout> | null,
+      _onSessionNeedsRefresh: (arg: { id: string }) => {
+        calls.push(arg.id);
+        return refresh();
+      },
+    } as unknown as {
+      _scheduleDroppedOutputRecovery: (id: string, attempt?: number) => void;
+      activeSessionId: string | null;
+      _clientDropRecoveryTimer: unknown;
+    },
+  };
+}
+
+/** Run every pending timer the scheduler laid down, up to `rounds` deep. */
+async function drain(rounds = DROP_RECOVERY_MAX_ATTEMPTS + 2) {
+  for (let i = 0; i < rounds; i++) {
+    await vi.advanceTimersByTimeAsync(DROP_RECOVERY_DELAY_MS + 1);
+  }
+}
+
+describe('_scheduleDroppedOutputRecovery', () => {
+  it('retries when the refresh was SKIPPED, which is what a burst makes likely', async () => {
+    vi.useFakeTimers();
+    try {
+      // `_onSessionNeedsRefresh` returns false from all four of its early
+      // returns — a buffer load in flight, a refresh already owning the session.
+      const { app, calls } = makeApp(() => Promise.resolve(false));
+      app._scheduleDroppedOutputRecovery(SESSION);
+      await drain();
+      expect(calls.length, 'a skipped refresh must be tried again — the old fire-and-forget timer stopped at one').toBe(
+        DROP_RECOVERY_MAX_ATTEMPTS
+      );
+      expect(new Set(calls)).toEqual(new Set([SESSION]));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  // The contrast. Without this the case above is satisfied by retrying forever.
+  it('does not retry once a repaint actually happened', async () => {
+    vi.useFakeTimers();
+    try {
+      const { app, calls } = makeApp(() => Promise.resolve(true));
+      app._scheduleDroppedOutputRecovery(SESSION);
+      await drain();
+      expect(calls.length).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('stops when the reader switches away mid-recovery', async () => {
+    vi.useFakeTimers();
+    try {
+      const { app, calls } = makeApp(() => {
+        app.activeSessionId = 'session-B';
+        return Promise.resolve(false);
+      });
+      app._scheduleDroppedOutputRecovery(SESSION);
+      await drain();
+      expect(calls.length, 'selectSession repaints session-B on its own').toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('treats a refresh that THREW as not repainted, and tries again', async () => {
+    vi.useFakeTimers();
+    try {
+      const { app, calls } = makeApp(() => Promise.reject(new Error('network')));
+      app._scheduleDroppedOutputRecovery(SESSION);
+      await drain();
+      expect(calls.length).toBe(DROP_RECOVERY_MAX_ATTEMPTS);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('does not retry a refresh that hit the fetch deadline', async () => {
+    vi.useFakeTimers();
+    try {
+      const { app, calls } = makeApp(() => Promise.resolve('deadline'));
+      app._scheduleDroppedOutputRecovery(SESSION);
+      await drain();
+      expect(calls.length, 'a stalled link is not contention; one full capture is the old cost').toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('writes one crash-trail line per debounce window, not one per dropped frame', async () => {
+    vi.useFakeTimers();
+    try {
+      const { app } = makeApp(() => Promise.resolve(true));
+      const before = crashTrail.filter((e) => e.includes('TERMINAL DROP')).length;
+      const schedule = app._scheduleDroppedOutputRecovery as (id: string, attempt?: number, queued?: number) => void;
+      for (let i = 0; i < 125; i++) schedule.call(app, SESSION, 0, 200 * 1024);
+      const drops = crashTrail.filter((e) => e.includes('TERMINAL DROP')).length - before;
+      expect(drops, 'one second of 8ms frames used to evict the whole 50-entry trail').toBe(1);
+      await drain();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('coalesces a burst of drops into one attempt, as the debounce always did', async () => {
+    vi.useFakeTimers();
+    try {
+      const { app, calls } = makeApp(() => Promise.resolve(true));
+      for (let i = 0; i < 20; i++) app._scheduleDroppedOutputRecovery(SESSION);
+      await drain();
+      expect(calls.length, 'twenty dropped frames must not become twenty fetches').toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('the drop path and the refresh agree on what counts as recovered', () => {
+  const app = read('src/web/public/app.js');
+
+  it('the 128KB drop goes through the scheduler, not a bare timer', () => {
+    const at = app.indexOf('131072');
+    expect(at, 'the cap is gone — renamed?').toBeGreaterThan(-1);
+    const branch = app.slice(at, at + 600);
+    expect(branch).toContain('this._scheduleDroppedOutputRecovery(data.id, 0, queued)');
+    // The crash-trail line belongs behind the scheduler's debounce guard.
+    expect(branch).not.toContain('_crashDiag.log');
+    expect(branch, 'a bare setTimeout here is the bug this fixes').not.toContain('setTimeout');
+  });
+
+  it('_onSessionNeedsRefresh reports false from every early return', () => {
+    const start = app.indexOf('async _onSessionNeedsRefresh(event = {})');
+    expect(start).toBeGreaterThan(-1);
+    const head = app.slice(start, app.indexOf('const refreshOwner', start));
+    const bareReturns = head.match(/\breturn;/g) ?? [];
+    expect(bareReturns, 'a bare `return` reads as undefined, which the caller cannot tell from false').toHaveLength(0);
+    expect((head.match(/return false;/g) ?? []).length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('and reports true only where it settles the reconcile marker', () => {
+    const start = app.indexOf('async _onSessionNeedsRefresh(event = {})');
+    const body = app.slice(start, app.indexOf('\n  }\n', app.indexOf('needsRefresh reload failed', start)));
+    const markerAt = body.indexOf('this._markTerminalBufferReconciled(sessionId);');
+    const trueAt = body.indexOf('return true;');
+    expect(markerAt).toBeGreaterThan(-1);
+    expect(trueAt, 'the success return must sit with the marker it settles').toBeGreaterThan(markerAt);
+    expect(trueAt - markerAt).toBeLessThan(80);
+  });
+});

test/file-browser-search.test.ts

@@ -292,6 +292,10 @@ function loadRealSelectSessionHarness(options: { terminalFailure?: boolean } = {
   app._beginBufferLoad = vi.fn(() => 1);
   app._isLoadingBuffer = false;
   app.fitAddon = { fit: vi.fn() };
+  // selectSession fits through the one owner now, which also applies the floor
+  // it reports to the PTY (#464). Without it on the fake, the unconditional
+  // call throws into selectSession's catch and nothing after it runs.
+  app.syncTerminalGeometry = vi.fn(() => ({ cols: 120, rows: 40 }));
   app.sendResize = vi.fn(() => {
     resizeCalls++;
     return resizeCalls === 1 ? terminalBoundary.promise : Promise.resolve(false);

test/git-clone.test.ts

@@ -201,6 +201,25 @@ describe('buildCloneArgs / buildLsRemoteArgs', () => {
       'd',
     ]);
   });
+
+  it('clears every credential helper, BEFORE the subcommand, only when asked', () => {
+    // Multi-user non-admin clones must not borrow the server account's git sign-in.
+    // `-c` is a global option: after `clone` git would read it as an unknown flag.
+    expect(
+      buildCloneArgs({ repository: 'https://example.com/r.git', destination: 'd', withoutCredentialHelpers: true })
+    ).toEqual(['-c', 'credential.helper=', 'clone', '--', 'https://example.com/r.git', 'd']);
+    expect(buildLsRemoteArgs('https://example.com/r.git', { withoutCredentialHelpers: true })).toEqual([
+      '-c',
+      'credential.helper=',
+      'ls-remote',
+      '--symref',
+      '--',
+      'https://example.com/r.git',
+    ]);
+    // Absent or false leaves the argv exactly as it was before the option existed.
+    expect(buildCloneArgs({ repository: 'r', destination: 'd', withoutCredentialHelpers: false })[0]).toBe('clone');
+    expect(buildLsRemoteArgs('r', {})[0]).toBe('ls-remote');
+  });
 });
 
 describe('gitNonInteractiveEnv', () => {

test/history-truncation-notice.test.ts

@@ -127,7 +127,11 @@ describe('the in-terminal truncation line is gone (static guard)', () => {
     expect(app).toContain("session?.mode !== 'shell' && !this._fullHistoryLoaded.has(sessionId)");
     expect(app).toContain("!restoredSnapshot && session?.mode !== 'shell'");
     expect(app).toContain('`/api/sessions/${sessionId}/terminal?tail=${TERMINAL_TAIL_SIZE}`');
-    expect(app).toContain('fetch(`/api/sessions/${sessionId}/terminal?full=1`)');
+    // Every terminal capture now goes through _fetchTerminalCapture, which adds
+    // an abort deadline (a `?full=1` body can be megabytes and used to hang
+    // indefinitely on a stalled mobile link). The URL and the full-vs-tail
+    // decision this guard exists to pin are unchanged.
+    expect(app).toContain('this._fetchTerminalCapture(`/api/sessions/${sessionId}/terminal?full=1`, { full: true })');
     expect(app).toContain("if (this.sessions.get(sessionId)?.mode !== 'shell')");
     expect(app).toContain("if (session?.mode === 'shell')");
     expect(app).toContain("if (!force && session?.mode === 'shell') return;");

test/home-sessions.test.ts

@@ -356,3 +356,50 @@ describe('home screens: one order, one numbering', () => {
     expect(branch).not.toContain('this.sessionOrder[idx]');
   });
 });
+
+describe('home sessions column: watching badge', () => {
+  it('carries the label off the session payload', () => {
+    const app = loadHomeSessionsApp({
+      sessions: sessionMap([{ id: 'watcher', watching: '1 monitor' }, { id: 'plain' }]),
+      sessionOrder: ['watcher', 'plain'],
+      cases: CASES,
+    });
+
+    const rows = Object.fromEntries(app.buildHomeSessionRows().map((r: any) => [r.id, r.watching]));
+    expect(rows).toEqual({ watcher: '1 monitor', plain: '' });
+  });
+
+  it("builds the badge with the phone overview, in the rail's own pill class", () => {
+    // Both home screens must word this badge identically, so the rail borrows the
+    // builder rather than writing a second one — the same arrangement it already has
+    // for state classification and for the stamp wording.
+    const app = loadHomeSessionsApp({
+      sessions: sessionMap([{ id: 'watcher', watching: '2 shells' }]),
+      sessionOrder: ['watcher'],
+      cases: CASES,
+    });
+
+    const row = app._buildHomeSessionRow(app.buildHomeSessionRows()[0]);
+    const badges = collect(row).filter((el: any) => String(el.className).includes('--watching'));
+    expect(badges).toHaveLength(1);
+    expect(badges[0].className).toBe('home-sessions-pill home-sessions-pill--watching');
+    expect(badges[0].textContent).toBe('watching');
+    expect(badges[0].title).toBe('Still running in the background: 2 shells');
+  });
+
+  it('draws no badge for a session running nothing in the background', () => {
+    const app = loadHomeSessionsApp({
+      sessions: sessionMap([{ id: 'plain' }]),
+      sessionOrder: ['plain'],
+      cases: CASES,
+    });
+
+    const row = app._buildHomeSessionRow(app.buildHomeSessionRows()[0]);
+    expect(collect(row).filter((el: any) => String(el.className).includes('--watching'))).toHaveLength(0);
+  });
+});
+
+/** Every node under one the builders made, the row itself included. */
+function collect(node: any): any[] {
+  return [node, ...(node.children || []).flatMap((child: any) => collect(child))];
+}

test/keyboard-shortcuts.test.ts

@@ -67,9 +67,14 @@ describe('keyboard shortcuts', () => {
     // selects real padding spaces, so the raw text is truthy and testing it would
     // spend the press on a copy of nothing — the same lost interrupt this test
     // guards, reached by a different door.
-    expect(terminalUiSource).toMatch(/const selection = this\.cleanedTerminalSelection\(\);/);
+    //
+    // The RAW selection is what travels on, because copyTerminalSelection cleans
+    // again on its own and the margin strip is not idempotent. Passing the
+    // cleaned string dedented every claude and codex copy twice; see
+    // test/terminal-copy-clean.test.ts for the branch's own pin.
+    expect(terminalUiSource).toMatch(/const selection = this\.cleanedTerminalSelection\(raw\);/);
     expect(terminalUiSource).toMatch(/if \(selection\.trim\(\)\) \{/);
-    expect(terminalUiSource).toContain('void this.copyTerminalSelection(selection);');
+    expect(terminalUiSource).toContain('void this.copyTerminalSelection(raw);');
     expect(appSource).toContain("id: 'copy-selection'");
   });
 

test/mobile-overview.test.ts

@@ -19,8 +19,11 @@ function fakeElement(): any {
     type: '',
     dataset: {},
     style: {},
+    attrs: {} as Record<string, string>,
     children: [] as any[],
-    setAttribute() {},
+    setAttribute(name: string, value: string) {
+      el.attrs[name] = value;
+    },
     appendChild(child: any) {
       el.children.push(child);
       return child;
@@ -485,3 +488,53 @@ describe('mobile overview run picker (CLI availability gating)', () => {
     expect(gate).toContain('isCliAvailable');
   });
 });
+
+describe('mobile overview watching badge', () => {
+  it('carries what the pane says is running in the background', () => {
+    const app = loadOverviewApp();
+    const model = app.buildMobileOverviewModel({
+      sessions: [session({ id: 'a', status: 'idle', watching: '1 monitor' }), session({ id: 'b', status: 'idle' })],
+      cases: CASES,
+    });
+
+    const rows = Object.fromEntries(model.current.map((r: any) => [r.id, r.watching]));
+    expect(rows).toEqual({ a: '1 monitor', b: '' });
+  });
+
+  it('leaves a session that is ALSO blocked on a dialog in NEEDS YOU', () => {
+    // An agent can arm a monitor and ask the user a question in the same breath, so the
+    // badge adds a fact to the row and never moves it out of the group that says a human
+    // is needed. Only the row's own pill decides that.
+    const app = loadOverviewApp();
+    const model = app.buildMobileOverviewModel({
+      sessions: [session({ id: 'a', status: 'idle', watching: '2 shells' })],
+      cases: CASES,
+      pendingHooks: new Map([['a', new Set(['permission_prompt'])]]),
+    });
+
+    expect(model.needsYou.map((r: any) => r.id)).toEqual(['a']);
+    expect(model.needsYou[0].pill).toBe('needs you');
+    expect(model.needsYou[0].watching).toBe('2 shells');
+  });
+
+  it('says one word and puts the detail where every surface can reach it', () => {
+    const app = loadOverviewApp();
+    const badge = app._buildWatchingBadge('1 monitor', 'mobile-overview-pill');
+
+    expect(badge.className).toBe('mobile-overview-pill mobile-overview-pill--watching');
+    expect(badge.textContent).toBe('watching');
+    expect(badge.title).toBe('Still running in the background: 1 monitor');
+    // A phone has no hover target and a screen reader reads neither the class nor the
+    // tooltip, so the label has to be here too or this surface says only "watching".
+    expect(badge.attrs['aria-label']).toBe('Still running in the background: 1 monitor');
+  });
+
+  it('takes the pill class of whichever surface asks for it', () => {
+    // The phone's pill styles live inside a media query the desktop rail never enters,
+    // so the rail passes its own base class and gets the same badge in its own clothes.
+    const app = loadOverviewApp();
+    expect(app._buildWatchingBadge('1 shell', 'home-sessions-pill').className).toBe(
+      'home-sessions-pill home-sessions-pill--watching'
+    );
+  });
+});

test/mobile-prompt-composer.test.ts

@@ -223,7 +223,12 @@ describe('mobile prompt composer', () => {
 
   it('wires session cleanup to composer draft cleanup', () => {
     const cleanupStart = appSource.indexOf('  _cleanupSessionData(sessionId) {');
-    const cleanup = appSource.slice(cleanupStart, cleanupStart + 1200);
+    expect(cleanupStart, '_cleanupSessionData not found — renamed?').toBeGreaterThan(-1);
+    // The whole method, not a fixed byte window. A 1200-character slice made
+    // this assertion depend on how much OTHER code sat above the line it cares
+    // about, so an unrelated addition near the top of the method failed it.
+    const cleanup = appSource.slice(cleanupStart, appSource.indexOf('\n  }\n', cleanupStart));
+    expect(cleanup.length, 'method body did not terminate').toBeGreaterThan(0);
 
     expect(cleanup).toContain('KeyboardAccessoryBar.discardComposerDraft?.(sessionId)');
   });

test/mocks/mock-session.ts

@@ -35,6 +35,12 @@ export class MockSession extends EventEmitter {
   /** `null` once the PTY is gone (or before it has ever started) — see `pid` in Session. */
   pid: number | null = 12345;
   isWorking: boolean = false;
+  /**
+   * Mirrors Session.watching — what the pane's footer says is still running in the
+   * background. An idle prompt from such a session opens acknowledged, so the routes
+   * need to be able to set it.
+   */
+  watching: string | null = null;
   private _activeChildProcesses: { pid: number; command: string }[] = [];
   ralphTracker: null = null;
   writeBuffer: string[] = [];

test/render-index-html.test.ts

@@ -143,6 +143,19 @@ describe('WebServer.renderIndexHtml', () => {
     expect(html).toContain('btn-multimonitor--hidden');
   });
 
+  it('injects the transcript-gutter map for a /session/:id window too', async () => {
+    // Every other payload is gated on !soloSessionId, but a solo window copies from a
+    // terminal like the main page does, so it needs the widths the copy strip keys on.
+    const { server } = makeServer();
+    const html = await render(server, 'sess-123');
+    const match = html.match(/window\.__codemanTranscriptGutter=(\{[^<]*\});/);
+    expect(match).not.toBeNull();
+    const map = JSON.parse(match![1]) as Record<string, number>;
+    expect(map.claude).toBe(2);
+    expect(map.codex).toBe(2);
+    expect(map.shell).toBeUndefined();
+  });
+
   it('escapes the solo id so it cannot break out of the inline <script>', async () => {
     const { server } = makeServer({});
     const html = await render(server, 'a</script><b>');

test/respawn-session-id-collision.test.ts

@@ -0,0 +1,487 @@
+/**
+ * @fileoverview Relaunching a pane must resume its conversation, not collide
+ * with it, and must not resume somebody else's.
+ *
+ * A CLI that launches with `--session-id <id>` refuses an id that is already in
+ * use (claude: `Error: Session ID ... is already in use.`), and every session
+ * whose agent has been prompted owns a transcript under that id. A relaunch
+ * that passes the bare launch line therefore dies on startup, the pane goes
+ * dead again at once, and the conversation is stranded.
+ *
+ * `restartCli()` has pinned a resume id for this reason since the custom-model
+ * work. The dead-pane respawn in `_setupOrAttachMuxSession()` did not, and its
+ * comment said so explicitly — "Unlike the dead-pane respawn, this one kills a
+ * WORKING pane whose conversation already has a transcript". That assumption is
+ * what these tests refute: a pane whose agent exited has a transcript too.
+ *
+ * The pin walks three candidates — the conversation chain's tail, the launch
+ * seed, then the session's own id — and takes the first one a transcript backs.
+ * Most of these tests are about the four gates on that walk rather than about
+ * the pin, because each gate stands for a way of resuming the WRONG
+ * conversation or of making a working relaunch fail. Two more are about what
+ * the walk does when a candidate misses: it carries on to the next, and pinning
+ * nothing is the right answer only once every candidate has missed.
+ *
+ * Port: N/A
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { Session } from '../src/session.js';
+import { getCli } from '../src/config/cli-registry/registry.js';
+import { buildSpawnCommandFromRegistry } from '../src/session-cli-registry-bridge.js';
+import { claudeTranscriptExists } from '../src/utils/claude-transcript.js';
+import type {
+  CreateSessionOptions,
+  MuxSession,
+  RespawnPaneOptions,
+  TerminalMultiplexer,
+} from '../src/mux-interface.js';
+
+/** Captures the options each respawn is invoked with. */
+function recordingMux() {
+  const calls: RespawnPaneOptions[] = [];
+  const mux = {
+    isAvailable: () => true,
+    muxSessionExists: () => true,
+    isPaneDead: () => true,
+    // Called by the PTY-exit handler during teardown. Absent, it throws
+    // asynchronously after the test body has already passed, which vitest
+    // reports as an unhandled error rather than a failure.
+    setAttached: () => {},
+    respawnPane: async (options: RespawnPaneOptions) => {
+      calls.push(options);
+      return 4242;
+    },
+  };
+  return { mux: mux as unknown as TerminalMultiplexer, calls };
+}
+
+const muxSession = (muxName = 'codeman-aaaa') => ({ muxName, sessionId: 'aaaa' }) as unknown as MuxSession;
+
+/**
+ * A mux whose `respawnPane` fails, which is what sends
+ * `_setupOrAttachMuxSession()` down its create-a-new-session fallback — the
+ * path that has to pin too, since it meets the same refusal the respawn just
+ * lost to.
+ */
+function failingRespawnMux() {
+  const calls: CreateSessionOptions[] = [];
+  const mux = {
+    isAvailable: () => true,
+    muxSessionExists: () => true,
+    isPaneDead: () => true,
+    setAttached: () => {},
+    respawnPane: async () => 0,
+    createSession: async (options: CreateSessionOptions) => {
+      calls.push(options);
+      return muxSession('codeman-recreated');
+    },
+  };
+  return { mux: mux as unknown as TerminalMultiplexer, calls };
+}
+
+/**
+ * A mux whose tmux lost the WHOLE session (tmux kill-server, a crash, an
+ * external kill-session), not just the pane. `_setupOrAttachMuxSession()` drops
+ * its stale handle and goes straight to `createSession()`, relaunching the CLI
+ * exactly as the failed-respawn fallback does.
+ */
+function vanishedSessionMux() {
+  const calls: CreateSessionOptions[] = [];
+  const respawns: RespawnPaneOptions[] = [];
+  const mux = {
+    isAvailable: () => true,
+    muxSessionExists: () => false,
+    isPaneDead: () => false,
+    setAttached: () => {},
+    respawnPane: async (options: RespawnPaneOptions) => {
+      respawns.push(options);
+      return 4242;
+    },
+    createSession: async (options: CreateSessionOptions) => {
+      calls.push(options);
+      return muxSession('codeman-recreated');
+    },
+  };
+  return { mux: mux as unknown as TerminalMultiplexer, calls, respawns };
+}
+
+const CONVERSATION = 'aaaabbbb-cccc-dddd-eeee-ffff00001111';
+
+let configDir: string;
+
+/** A relocated Claude config dir, so the transcript gate reads a real fixture. */
+beforeEach(() => {
+  configDir = mkdtempSync(join(tmpdir(), 'codeman-transcript-'));
+});
+
+afterEach(() => {
+  rmSync(configDir, { recursive: true, force: true });
+});
+
+/** Write the `<id>.jsonl` Claude would have written for a conversation. */
+function giveTranscript(conversationId: string): void {
+  const projectDir = join(configDir, 'projects', '-tmp-case');
+  mkdirSync(projectDir, { recursive: true });
+  writeFileSync(join(projectDir, `${conversationId}.jsonl`), '{"type":"user"}\n');
+}
+
+function localSession(extra: Record<string, unknown> = {}, mux?: TerminalMultiplexer) {
+  return new Session({
+    workingDir: '/tmp',
+    mode: 'claude',
+    useMux: true,
+    mux,
+    muxSession: muxSession(),
+    envOverrides: { CLAUDE_CONFIG_DIR: configDir },
+    ...extra,
+  });
+}
+
+describe('pinning a conversation onto a relaunch', () => {
+  it('pins the chain tail on the DEAD-PANE respawn, which is the bug', async () => {
+    // The path a recovered `/exit`ed session takes, and the one that was
+    // missing the pin. Driven through `startInteractive()` rather than asserted
+    // from source: a comment claiming a thing happens is exactly what was wrong
+    // here before.
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+
+    await session.startInteractive();
+    try {
+      expect(calls).toHaveLength(1);
+      expect(calls[0].resumeSessionId).toBe(CONVERSATION);
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('pins the chain tail on a custom-model restart too', async () => {
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBe(CONVERSATION);
+  });
+
+  it('prefers the live chain tail over the launch seed', async () => {
+    // `_resumeSessionId` is written once at construction and never moves, so a
+    // `/clear` after launch leaves it pointing at the predecessor. Resuming
+    // that would reopen an abandoned conversation and strand the live one.
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession(
+      { resumeSessionId: 'bbbbcccc-dddd-eeee-ffff-000011112222', claudeSessionChain: [CONVERSATION] },
+      mux
+    );
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBe(CONVERSATION);
+  });
+
+  it('falls back to the launch seed when no conversation was ever recorded', async () => {
+    const seed = 'bbbbcccc-dddd-eeee-ffff-000011112222';
+    giveTranscript(seed);
+    const { mux, calls } = recordingMux();
+    const session = localSession({ resumeSessionId: seed }, mux);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBe(seed);
+  });
+
+  it('never resumes an id the conversation chain did not vouch for', async () => {
+    // `_claudeSessionId` also holds history-CORRELATED guesses, keyed on the
+    // working directory, which the chain deliberately refuses. Launching from
+    // one would open and WRITE to a conversation that was never this pane's —
+    // worse than the display bug that rule exists to prevent.
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession({}, mux);
+    // Backed, so the walk reaching it pins it. Without this the session would
+    // land unpinned for want of a transcript rather than for refusing the
+    // guess, and the test would pass while proving nothing.
+    giveTranscript(session.id);
+    session.adoptClaudeSessionId(CONVERSATION); // no firstHand flag: a guess
+    expect(session.claudeSessionId).toBe(CONVERSATION);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).not.toBe(CONVERSATION);
+    expect(calls[0].resumeSessionId).toBe(session.id);
+  });
+
+  it('degrades to the session id rather than to the colliding bare command', async () => {
+    // The chain tail is gone from disk but the session's own id is not, which
+    // is every session prompted before its first `/clear`. Dropping the pin
+    // outright hands back `--session-id <this.id>` alone — the very refusal
+    // this whole mechanism removes — so the walk carries on to the next
+    // candidate instead of stopping at the first miss.
+    const { mux, calls } = recordingMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+    giveTranscript(session.id);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBe(session.id);
+  });
+
+  it('pins nothing at all when no candidate has a transcript', async () => {
+    // Falling off the end of the walk is the one case where the bare
+    // `--session-id <this.id>` is right: nothing on disk can collide with it,
+    // and pinning anyway would cost a brand-new pane claude's "No conversation
+    // found" line plus the `nice` priority on the branch that actually runs.
+    // The walk only ever ADDS a pin, so a session launched as a resume keeps
+    // the seed its options already carried — see the custom-model restart
+    // tests, which cover that case.
+    const { mux, calls } = recordingMux();
+    const session = localSession({}, mux);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBeUndefined();
+  });
+
+  it('pins the create-path fallback after a failed respawn', async () => {
+    // The recovery of last resort would otherwise meet the same refusal that
+    // made it the fallback, since the create options were built eagerly from
+    // the unpinned launch seed.
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = failingRespawnMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+
+    await session.startInteractive();
+    try {
+      expect(calls).toHaveLength(1);
+      expect(calls[0].resumeSessionId).toBe(CONVERSATION);
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('leaves the session naming the conversation the create path resumed', async () => {
+    // That path leaves `isRestored` false, so `_claudeSessionId` is recomputed
+    // from the launch fields and lands on `this.id` unless the pin is written
+    // back to `_resumeSessionId` as well. The response viewer, Read My Mind and
+    // the unified-list alias map read that field until the next first-hand
+    // hook, so a mismatch points all three at a conversation claude never
+    // opened.
+    giveTranscript(CONVERSATION);
+    const { mux } = failingRespawnMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+
+    await session.startInteractive();
+    try {
+      expect(session.claudeSessionId).toBe(CONVERSATION);
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('pins the create path when tmux lost the whole session, not just the pane', async () => {
+    // The stale-session branch nulls the handle and never sets the failed-respawn
+    // flag, so without its own pin the relaunch carried the bare launch line and
+    // met the same `--session-id ... already in use` refusal.
+    giveTranscript(CONVERSATION);
+    const { mux, calls, respawns } = vanishedSessionMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+
+    await session.startInteractive();
+    try {
+      expect(respawns).toHaveLength(0);
+      expect(calls).toHaveLength(1);
+      expect(calls[0].resumeSessionId).toBe(CONVERSATION);
+      expect(session.claudeSessionId).toBe(CONVERSATION);
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('leaves a genuinely new session unpinned on the create path', async () => {
+    // No mux handle to begin with, so the stale-session flag is never set and
+    // the create options keep their original shape.
+    const { mux, calls } = vanishedSessionMux();
+    const session = localSession({ muxSession: undefined }, mux);
+    giveTranscript(session.id);
+
+    await session.startInteractive();
+    try {
+      expect(calls).toHaveLength(1);
+      expect(calls[0].resumeSessionId).toBeUndefined();
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('names the conversation the dead-pane respawn actually resumed', async () => {
+    // The chain tail has no transcript, so the walk degrades to the session id.
+    // The session must then report that id, not the chain tail claude never
+    // opened: the response viewer, Read My Mind and the alias map all read it.
+    const { mux, calls } = recordingMux();
+    const session = localSession({ claudeSessionChain: [CONVERSATION] }, mux);
+    giveTranscript(session.id);
+
+    await session.startInteractive();
+    try {
+      expect(calls[0].resumeSessionId).toBe(session.id);
+      expect(session.claudeSessionId).toBe(session.id);
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('pins nothing for a remote session, whose conversation lives elsewhere', async () => {
+    // The dead-pane respawn is reached by every session shape, unlike
+    // `restartCli()` whose route refuses remote. A local id pinned onto a
+    // remote pane resolves to nothing there, and the `--session-id` fallback
+    // then collides with the transcript the remote host really does hold.
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession(
+      {
+        remote: { hostId: 'h1', label: 'box', host: 'box', username: 'dev', remotePath: '/tmp' },
+        claudeSessionChain: [CONVERSATION],
+      },
+      mux
+    );
+
+    await session.startInteractive();
+    try {
+      expect(calls[0].resumeSessionId).toBeUndefined();
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('pins nothing for a docker case, whose pane execs into the container', async () => {
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession(
+      {
+        docker: { hostId: 'd1', label: 'ctr', containerName: 'ctr' },
+        claudeSessionChain: [CONVERSATION],
+      },
+      mux
+    );
+
+    await session.startInteractive();
+    try {
+      expect(calls[0].resumeSessionId).toBeUndefined();
+    } finally {
+      await session.stop();
+    }
+  });
+
+  it('pins nothing for a CLI that mints its own resume id', async () => {
+    // codex/pi/omp/grok declare no `fallback` chain and read their resume id
+    // from their own config, so a top-level pin would be meaningless at best.
+    const { mux, calls } = recordingMux();
+    const session = localSession({ mode: 'codex' }, mux);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBeUndefined();
+  });
+
+  it('documents that a remote reattach carries no pin', async () => {
+    // `reattachRemote()` re-runs the remote session command, which attaches to
+    // the durable remote tmux with the agent still running inside it.
+    // ⚠️ Documentation, not a regression guard: `reattachRemote()` only runs for
+    // a remote session, and the pin builder refuses remote sessions on its own,
+    // so this would still pass if `reattachRemote()` were switched to the pinned
+    // builder. The builder's remote guard is what the test above pins.
+    giveTranscript(CONVERSATION);
+    const { mux, calls } = recordingMux();
+    const session = localSession(
+      {
+        remote: { hostId: 'h1', label: 'box', host: 'box', username: 'dev', remotePath: '/tmp' },
+        claudeSessionChain: [CONVERSATION],
+      },
+      mux
+    );
+
+    expect(await session.reattachRemote()).toBe(true);
+
+    expect(calls[0].resumeSessionId).toBeUndefined();
+  });
+});
+
+describe('what the pin renders', () => {
+  // The rendered command is what actually runs, and it is where each gate's
+  // reason shows. Asserting here rather than counting call sites in the source
+  // is what would have caught the divergent-pin and synthetic-id cases.
+  const SID = '0f9c2b14-1111-2222-3333-444455556666';
+  const entry = getCli('claude');
+  const render = (resumeSessionId?: string) => {
+    if (!entry) throw new Error('no registry entry for claude');
+    return buildSpawnCommandFromRegistry(entry, {
+      mode: 'claude',
+      sessionId: SID,
+      claudeCliVersion: null,
+      resumeSessionId,
+    });
+  };
+
+  it('renders the colliding bare form with no pin — the bug itself', () => {
+    expect(render()).toContain(`--session-id "${SID}"`);
+    expect(render()).not.toContain('--resume');
+  });
+
+  it('renders a self-healing resume-or-new when the pin is the session id', () => {
+    expect(render(SID)).toBe(
+      `claude --dangerously-skip-permissions --resume "${SID}" || claude --dangerously-skip-permissions --session-id "${SID}"`
+    );
+  });
+
+  it('keeps the SESSION id in the fallback branch when the pin diverges', () => {
+    // Which is why a pin with no transcript behind it has to be dropped: the
+    // fallback is the colliding form, so a failed resume dies twice.
+    expect(render(CONVERSATION)).toContain(`--resume "${CONVERSATION}"`);
+    expect(render(CONVERSATION)).toContain(`--session-id "${SID}"`);
+  });
+
+  it('drops a synthetic discovered id, which fails the uuid token pattern', () => {
+    // `reconcileSessions()` mints `restored-<fragment>` for a tmux session
+    // Codeman found but does not own. The renderer emits the unpinned command,
+    // so those panes keep the pre-existing behaviour.
+    expect(render('restored-40568a29')).not.toContain('--resume');
+  });
+});
+
+describe('where the transcript lookup reads', () => {
+  it("honours the server process's own CLAUDE_CONFIG_DIR", async () => {
+    // A pane inherits the server environment through tmux, so on an install
+    // that exports this the CLI writes its transcripts there. Reading `~/.claude`
+    // regardless answers "no transcript" for every conversation on the host,
+    // and under the walk above that means the colliding bare command.
+    giveTranscript(CONVERSATION);
+    const before = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = configDir;
+    try {
+      expect(await claudeTranscriptExists(CONVERSATION)).toBe(true);
+    } finally {
+      if (before === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+      else process.env.CLAUDE_CONFIG_DIR = before;
+    }
+  });
+
+  it("prefers the session's own relocated dir over the process one", async () => {
+    // A session pointed at a separate Claude account (#255) reads its own tree,
+    // not the server's.
+    giveTranscript(CONVERSATION);
+    const before = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = join(configDir, 'nowhere');
+    try {
+      expect(await claudeTranscriptExists(CONVERSATION, configDir)).toBe(true);
+    } finally {
+      if (before === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+      else process.env.CLAUDE_CONFIG_DIR = before;
+    }
+  });
+});

test/routes/approval-routes.test.ts

@@ -325,6 +325,65 @@ describe('approval routes', () => {
     });
   });
 
+  describe('an idle prompt from a session watching its own background work', () => {
+    beforeEach(() => {
+      session.terminalBuffer = 'claude> waiting at the composer';
+      session.watching = '1 monitor';
+    });
+
+    it('opens acknowledged, so no surface has an alert to raise', async () => {
+      await postHook(harness, 'idle_prompt', { message: 'Claude is waiting for your input' });
+      const [item] = await listApprovals(harness);
+      expect(item).toMatchObject({ kind: 'idle', acknowledgedReason: 'watching 1 monitor' });
+      expect(item.acknowledgedAt).toEqual(expect.any(Number));
+    });
+
+    it('tells a live page why, so it declines to arm the alert', async () => {
+      await postHook(harness, 'idle_prompt', {});
+      const broadcast = harness.ctx.broadcast.mock.calls.find((c) => c[0] === 'hook:idle_prompt');
+      expect(broadcast?.[1]).toMatchObject({ acknowledgedReason: 'watching 1 monitor' });
+    });
+
+    it('sends no push', async () => {
+      // The loudest surface, and the one a false alarm is hardest to ignore on.
+      await postHook(harness, 'idle_prompt', {});
+      expect(harness.ctx.sendPushNotifications.mock.calls.find((c) => c[0] === 'hook:idle_prompt')).toBeUndefined();
+    });
+
+    it('stays answerable from the drawer', async () => {
+      await postHook(harness, 'idle_prompt', {});
+      const [item] = await listApprovals(harness);
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/approvals/${item.id}/answer`,
+        payload: { action: 'text', text: 'carry on' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(session.writeBuffer.join('')).toContain('carry on');
+    });
+
+    it('still raises a permission dialog from the same session', async () => {
+      // Watching says nothing about a dialog: that one blocks the agent outright.
+      session.terminalBuffer = PERMISSION_DIALOG;
+      await postHook(harness, 'permission_prompt', { tool_name: 'Bash' });
+      const [item] = await listApprovals(harness);
+      expect(item.acknowledgedAt).toBeUndefined();
+      expect(item.acknowledgedReason).toBeUndefined();
+      const broadcast = harness.ctx.broadcast.mock.calls.find((c) => c[0] === 'hook:permission_prompt');
+      expect(broadcast?.[1]).not.toMatchObject({ acknowledgedReason: expect.any(String) });
+      expect(harness.ctx.sendPushNotifications.mock.calls.find((c) => c[0] === 'hook:permission_prompt')).toBeDefined();
+    });
+
+    it('alerts normally again once the background work is over', async () => {
+      await postHook(harness, 'idle_prompt', {});
+      session.watching = null;
+      await postHook(harness, 'idle_prompt', {});
+      const [item] = await listApprovals(harness);
+      expect(item.acknowledgedAt).toBeUndefined();
+      expect(harness.ctx.sendPushNotifications.mock.calls.filter((c) => c[0] === 'hook:idle_prompt')).toHaveLength(1);
+    });
+  });
+
   it('viewing a session acknowledges its idle prompt (item stays pending) and broadcasts it', async () => {
     session.terminalBuffer = 'claude> waiting at the composer';
     await postHook(harness, 'idle_prompt', {});

test/routes/case-clone-credential-helpers.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Clone Repo must not lend the server account's git sign-in to
+ * non-admins in multi-user mode (PR #472 review).
+ *
+ * Every Codeman user's git runs as the one server account, so a credential
+ * helper that account has (the Docker image's opt-in `gh`/`az` helpers, or any
+ * `gh auth setup-git`) would otherwise clone a PRIVATE repository with the
+ * signed-in admin's credentials into a non-admin's case space, the same
+ * boundary the local-transport rule guards. These tests pin the ROUTE decision:
+ * who gets `withoutCredentialHelpers`. The argv it becomes is pinned in
+ * `test/git-clone.test.ts`, and the real-git clone path in
+ * `case-clone-routes.test.ts`.
+ *
+ * Only the two network calls are mocked, so no git runs and nothing leaves the
+ * machine; everything else in `git-clone.ts` (URL parsing included) is real.
+ *
+ * Port: N/A (app.inject).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouteTestHarness } from './_route-test-utils.js';
+import { registerCaseRoutes } from '../../src/web/routes/case-routes.js';
+
+const calls = vi.hoisted(() => ({
+  probe: [] as Array<{ repository: string; opts: unknown }>,
+  clone: [] as Array<Record<string, unknown>>,
+}));
+
+vi.mock('../../src/git-clone.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../src/git-clone.js')>();
+  return {
+    ...actual,
+    isGitAvailable: () => true,
+    probeGitRemote: async (repository: string, _timeoutMs?: number, opts?: unknown) => {
+      calls.probe.push({ repository, opts });
+      return { reachable: false, branches: [], tags: [] };
+    },
+    cloneRepository: async (opts: Record<string, unknown>) => {
+      calls.clone.push(opts);
+      return { ok: false, failure: { code: 'AUTH_REQUIRED', message: 'needs auth', stderr: '' } };
+    },
+  };
+});
+
+const REPO = 'https://github.com/example/private-repo.git';
+
+type Who = { username: string; role: 'admin' | 'user' } | undefined;
+
+async function run(who: Who, multiUser: boolean): Promise<{ probe: unknown; clone: unknown }> {
+  const prev = process.env.CODEMAN_MULTIUSER;
+  if (multiUser) process.env.CODEMAN_MULTIUSER = '1';
+  else delete process.env.CODEMAN_MULTIUSER;
+  try {
+    const { app } = await createRouteTestHarness(registerCaseRoutes, who ? { authUser: who } : undefined);
+    await app.inject({ method: 'POST', url: '/api/cases/clone-preflight', payload: { repository: REPO } });
+    await app.inject({
+      method: 'POST',
+      url: '/api/cases/clone',
+      payload: { name: `cred-${Math.random().toString(36).slice(2, 10)}`, repository: REPO },
+    });
+    await app.close();
+    expect(calls.probe, 'the preflight never reached probeGitRemote').toHaveLength(1);
+    expect(calls.clone, 'the clone never reached cloneRepository').toHaveLength(1);
+    return {
+      probe: (calls.probe[0].opts as { withoutCredentialHelpers?: boolean } | undefined)?.withoutCredentialHelpers,
+      clone: calls.clone[0].withoutCredentialHelpers,
+    };
+  } finally {
+    if (prev === undefined) delete process.env.CODEMAN_MULTIUSER;
+    else process.env.CODEMAN_MULTIUSER = prev;
+  }
+}
+
+describe('Clone Repo credential helpers by caller', () => {
+  beforeEach(() => {
+    calls.probe.length = 0;
+    calls.clone.length = 0;
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('clears them for a NON-ADMIN in multi-user mode (preflight AND clone)', async () => {
+    expect(await run({ username: 'mallory', role: 'user' }, true)).toEqual({ probe: true, clone: true });
+  });
+
+  it('keeps them for an admin in multi-user mode', async () => {
+    expect(await run({ username: 'root', role: 'admin' }, true)).toEqual({ probe: false, clone: false });
+  });
+
+  it('keeps them in single-user mode, where the sole user owns the account', async () => {
+    expect(await run(undefined, false)).toEqual({ probe: false, clone: false });
+  });
+});

test/routes/session-routes.test.ts

@@ -1371,6 +1371,19 @@ describe('session-routes', () => {
       expect(body.success).toBe(false);
     });
 
+    // Ark0N/Codeman#446: starting a command in the pane retracts `paneExit`, and
+    // the pane-exit watcher cannot write that retraction for us — its next tick
+    // finds the field already cleared, reports no change and persists nothing.
+    // Broadcasting without persisting leaves state.json saying the agent exited.
+    it('persists the session, not just broadcasts it', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/interactive`,
+      });
+      expect(res.statusCode).toBe(200);
+      expect(harness.ctx.persistSessionState).toHaveBeenCalledWith(harness.ctx._session);
+    });
+
     it('returns error if session is busy', async () => {
       harness.ctx._session.isBusy.mockReturnValue(true);
       const res = await harness.app.inject({
@@ -1447,6 +1460,16 @@ describe('session-routes', () => {
       expect(harness.ctx.setupSessionListeners).toHaveBeenCalledWith(harness.ctx._session);
     });
 
+    // Same reason as /interactive above (Ark0N/Codeman#446).
+    it('persists the session, not just broadcasts it', async () => {
+      const res = await harness.app.inject({
+        method: 'POST',
+        url: `/api/sessions/${harness.ctx._sessionId}/shell`,
+      });
+      expect(res.statusCode).toBe(200);
+      expect(harness.ctx.persistSessionState).toHaveBeenCalledWith(harness.ctx._session);
+    });
+
     it('returns error if session is busy', async () => {
       harness.ctx._session.isBusy.mockReturnValue(true);
       const res = await harness.app.inject({

test/server-index-title.test.ts

@@ -96,9 +96,9 @@ describe('WebServer index.html <title> templating (#82)', () => {
 
   it('only substitutes the <title> tag — the rest of the template is identical (modulo asset cache-busting)', async () => {
     // renderIndexHtml also appends ?v=<mtime> cache-bust params to same-origin
-    // .js/.css refs, and injects the CLI-availability flags plus the custom-model
-    // Run-menu picker's CLI list before </head>; strip all so the title remains
-    // the only other change.
+    // .js/.css refs, and injects the CLI-availability flags, the custom-model
+    // Run-menu picker's CLI list and the transcript-gutter widths before </head>;
+    // strip all so the title remains the only other change.
     //
     // The flag strips are what keep this test environment-independent. The
     // CLI-availability one used to pass here by luck: that script was injected
@@ -109,7 +109,10 @@ describe('WebServer index.html <title> templating (#82)', () => {
     const html = (await render('laptop'))
       .replace(/(\.(?:js|css))\?v=[^"]*/g, '$1')
       .replace(/<script>window\.__codemanCliAvailable=\{.*?\};<\/script>\n/, '')
-      .replace(/<script>window\.__codemanCustomModelClis=\[.*?\];<\/script>\n/, '');
+      .replace(/<script>window\.__codemanCustomModelClis=\[.*?\];<\/script>\n/, '')
+      // Injected unconditionally as an object keyed by run mode, empty when no
+      // enabled CLI declares a gutter, so it needs stripping on every machine.
+      .replace(/<script>window\.__codemanTranscriptGutter=\{.*?\};<\/script>\n/, '');
     const beforeTitle = rawTemplate.split('<title>Codeman</title>')[0];
     const afterTitle = rawTemplate.split('<title>Codeman</title>')[1];
     expect(html.startsWith(beforeTitle)).toBe(true);

test/session-custom-model-restart.test.ts

@@ -12,7 +12,8 @@
  * 2. Applying to a local claude session killed the pane: the relaunch was
  *    `claude --session-id <id>` and Claude refuses an id that already has a
  *    transcript, so it needs the `--resume <id> || --session-id <id>` shape the
- *    docker and remote pane commands use, i.e. a pinned resume id.
+ *    docker and remote pane commands use, i.e. a pinned resume id. The pin is
+ *    gated on that transcript existing, so these tests write one.
  * 3. pi/omp/grok wrote their config file and then launched without the `--model`
  *    that selects it, so the file was ignored.
  *
@@ -20,7 +21,7 @@
  * spying on `respawnPane` to read the options the relaunch would get.
  * Port: N/A.
  */
-import { mkdirSync, rmSync } from 'node:fs';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -30,13 +31,29 @@ import { TmuxManager } from '../src/tmux-manager.js';
 import type { MuxSession, SessionMode } from '../src/types.js';
 
 const workingDir = join(homedir(), 'codeman-cases', 'custom-model-restart');
+const projectsDir = join(homedir(), '.claude', 'projects', '-custom-model-restart');
 const sessions: Session[] = [];
 
 afterEach(() => {
   for (const s of sessions.splice(0)) s.stop();
   rmSync(workingDir, { recursive: true, force: true });
+  // Only the directory these tests create. `setup.ts` gives each test file a
+  // temp HOME, but a wider sweep here would delete a real `~/.claude` the day
+  // that stops being true.
+  rmSync(projectsDir, { recursive: true, force: true });
 });
 
+/**
+ * Write the transcript Claude would have written for a conversation. A pane
+ * `restartCli()` relaunches is a WORKING one, so its conversation has a
+ * transcript on disk; that is both what makes the bare `--session-id` collide
+ * and what the pin is now gated on.
+ */
+function giveTranscript(conversationId: string): void {
+  mkdirSync(projectsDir, { recursive: true });
+  writeFileSync(join(projectsDir, `${conversationId}.jsonl`), '{"type":"user"}\n');
+}
+
 function liveSession(mode: SessionMode, extra: Record<string, unknown> = {}) {
   mkdirSync(workingDir, { recursive: true });
   const mux = new TmuxManager();
@@ -118,6 +135,7 @@ describe('clearing a selection unsets what it injected', () => {
 describe('restartCli() must not kill a working pane', () => {
   it('claude: pins the live conversation id so the relaunch renders --resume <id> || --session-id <id>', async () => {
     const { session, respawn } = liveSession('claude');
+    giveTranscript(session.id);
     await session.restartCli();
     const options = respawn.mock.calls[0][0];
     expect(options.resumeSessionId).toBe(session.claudeSessionId);
@@ -126,7 +144,33 @@ describe('restartCli() must not kill a working pane', () => {
     expect(session.toState().resumeSessionId).toBeUndefined();
   });
 
+  it('claude: pins nothing when the pane has no transcript, because nothing can collide', async () => {
+    // A pane that was launched and never prompted. `--session-id <this.id>` is
+    // accepted on an id no transcript holds, so pinning would buy nothing and
+    // cost two things: claude prints "No conversation found" into a pane with
+    // no history, and `wrapWithNice()` prefixes only the first branch of the
+    // rendered `a || b`, so the branch that actually runs loses its priority
+    // for the life of the session.
+    const { session, respawn } = liveSession('claude');
+    await session.restartCli();
+    expect(respawn.mock.calls[0][0].resumeSessionId).toBeUndefined();
+  });
+
   it('claude: an explicit resume id from a resume-from-history launch wins over the pin', async () => {
+    const RESUMED = '01a060f0-0361-7f91-abde-b283020db0d7';
+    const { session, respawn } = liveSession('claude', { resumeSessionId: RESUMED });
+    giveTranscript(RESUMED);
+    await session.restartCli();
+    expect(respawn.mock.calls[0][0].resumeSessionId).toBe(RESUMED);
+  });
+
+  it('claude: a launch seed survives the pin walk even with its transcript gone', async () => {
+    // The walk only ever ADDS a pin. The seed is what the session was created
+    // with and every respawn has always carried it, so a transcript deleted
+    // under a running session leaves the relaunch on
+    // `--resume <seed> || --session-id <this.id>` — the resume fails and the
+    // fallback runs, which is safe precisely because nothing is on disk to
+    // collide with.
     const RESUMED = '01a060f0-0361-7f91-abde-b283020db0d7';
     const { session, respawn } = liveSession('claude', { resumeSessionId: RESUMED });
     await session.restartCli();

test/session-listener-wiring.test.ts

@@ -22,6 +22,21 @@ describe('session listener wiring', () => {
     expect(registerAttachment).toHaveBeenNthCalledWith(2, 'wiring-attach-source-test', '/tmp/report.pdf', 'external');
   });
 
+  it('pushes the session state when the watching label changes on its own', () => {
+    // The badge appears on the idle transition, which broadcasts anyway. It goes AWAY
+    // when the background work ends, and a CLI can do that without taking a turn — codex
+    // repaints its background-terminal row away and stays idle — so nothing else fires
+    // and every open page would keep drawing a badge the server had already dropped.
+    const session = new Session({ id: 'wiring-watching-test', workingDir: '/tmp', mode: 'codex' });
+    const broadcastSessionStateDebounced = vi.fn();
+    const deps = { broadcastSessionStateDebounced } as unknown as Parameters<typeof createSessionListeners>[1];
+
+    const refs = createSessionListeners(session, deps);
+    refs.watchingChanged();
+
+    expect(broadcastSessionStateDebounced).toHaveBeenCalledWith('wiring-watching-test');
+  });
+
   /** The listener reads the setting asynchronously; let its promise chain settle. */
   const flush = () => new Promise((resolve) => setTimeout(resolve, 5));
 

test/session-pane-exit-ui.test.ts

@@ -0,0 +1,378 @@
+/**
+ * @fileoverview The exited-agent badge on a session tab (Ark0N/Codeman#446).
+ *
+ * The server publishes `session.paneExit` when the agent inside a local tmux
+ * pane has exited while `remain-on-exit` kept the pane. These cover the three
+ * things the browser owns: turning that field into a label, getting the label
+ * onto and off a tab, and what colour the tab's status dot ends up once the
+ * exit, the alert rules and the rich rail's own rules have all had a say.
+ *
+ * The incremental render path is the only one a live session ever reaches.
+ * Going from live to exited adds and removes no tab, so the full rebuild never
+ * runs for it, which is why `applyPaneExitBadge()` is a named function rather
+ * than a block inside the render loop.
+ *
+ * Port: N/A
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { JSDOM } from 'jsdom';
+import postcss from 'postcss';
+import { describe, expect, it } from 'vitest';
+
+describe('the exited-agent tab label', () => {
+  const appJs = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+  const load = <T>(name: string) => {
+    const source = appJs.match(new RegExp(`function ${name}\\([\\s\\S]*?\\n\\}`))?.[0];
+    if (!source) throw new Error(`${name} not found in app.js`);
+    return new Function(`${source}\nreturn ${name};`)() as T;
+  };
+  const paneExitLabel = load<(p: unknown) => string>('paneExitLabel');
+
+  it('renders nothing for an unknown answer, which must never read as alive', () => {
+    expect(paneExitLabel(undefined)).toBe('');
+    expect(paneExitLabel(null)).toBe('');
+  });
+
+  it('names the exit code', () => {
+    expect(paneExitLabel({ status: 137, at: 1 })).toBe('exited (137)');
+  });
+
+  it('shows a clean exit as 0 rather than hiding it', () => {
+    expect(paneExitLabel({ status: 0, at: 1 })).toBe('exited (0)');
+  });
+
+  it('names a signal death, which the maintainer wants kept on screen', () => {
+    expect(paneExitLabel({ signal: 9, at: 1 })).toBe('exited (signal 9)');
+  });
+
+  it('says only "exited" when tmux knew the pane died but not how', () => {
+    // Measured on tmux 3.2a: a SIGKILLed pane reports neither status nor signal.
+    // Showing that as "exited (0)" would make an unexplained death look clean.
+    expect(paneExitLabel({ at: 1 })).toBe('exited');
+  });
+});
+
+describe('the exited-agent badge in a tab', () => {
+  // The incremental render path is the only one a live session reaches: going
+  // from live to exited adds and removes no tab, so the full rebuild never runs
+  // for it. These drive that path's DOM work against a real tab element.
+  const appJs = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+  const source = [
+    appJs.match(/function paneExitLabel\([\s\S]*?\n\}/)?.[0],
+    appJs.match(/function paneExitAriaLabel\([\s\S]*?\n\}/)?.[0],
+    appJs.match(/function applyPaneExitBadge\([\s\S]*?\n\}/)?.[0],
+  ].join('\n');
+  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+  const applyPaneExitBadge = new Function('document', `${source}\nreturn applyPaneExitBadge;`)(dom.window.document) as (
+    tab: unknown,
+    paneExit: unknown
+  ) => void;
+
+  const makeTab = () => {
+    const tab = dom.window.document.createElement('div');
+    tab.className = 'session-tab';
+    tab.setAttribute('aria-label', 'w1-case session');
+    tab.innerHTML = '<span class="tab-name" data-full-name="w1-case">w1-case</span>';
+    return tab;
+  };
+  const badge = (tab: { querySelector: (s: string) => { textContent: string | null } | null }) =>
+    tab.querySelector('.tab-exited-badge');
+
+  it('draws no badge while the answer is unknown', () => {
+    const tab = makeTab();
+    applyPaneExitBadge(tab, undefined);
+    expect(badge(tab)).toBeNull();
+  });
+
+  it('adds the badge after the name once the agent exits', () => {
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 137, at: 1 });
+    expect(badge(tab)?.textContent).toBe('exited (137)');
+    expect(tab.querySelector('.tab-name')?.nextElementSibling?.className).toBe('tab-exited-badge');
+  });
+
+  it('marks the badge data-i18n-skip, like the other generated status text', () => {
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 0, at: 1 });
+    expect(badge(tab)?.hasAttribute('data-i18n-skip')).toBe(true);
+  });
+
+  it('hides the badge from assistive technology, like its sibling badges', () => {
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 0, at: 1 });
+    expect(badge(tab)?.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('carries the exit on the tab accessible name instead, and drops it again', () => {
+    // The tab's aria-label overrides its contents, so the badge alone would leave
+    // a screen reader announcing an exited tab exactly like a live one.
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 137, at: 1 });
+    expect(tab.getAttribute('aria-label')).toBe('w1-case session, agent exited (137)');
+    applyPaneExitBadge(tab, undefined);
+    expect(tab.getAttribute('aria-label')).toBe('w1-case session');
+  });
+
+  it('builds the full render path accessible name from the same helper', () => {
+    expect(appJs).toContain('aria-label="${escapeHtml(paneExitAriaLabel(name, paneExitBadge))}"');
+    expect(appJs).toContain('<span class="tab-exited-badge" data-i18n-skip aria-hidden="true">');
+  });
+
+  it('updates the text in place rather than stacking a second badge', () => {
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 0, at: 1 });
+    const first = badge(tab);
+    applyPaneExitBadge(tab, { status: 137, at: 2 });
+    expect(tab.querySelectorAll('.tab-exited-badge')).toHaveLength(1);
+    expect(badge(tab)).toBe(first);
+    expect(badge(tab)?.textContent).toBe('exited (137)');
+  });
+
+  it('marks the tab so the status dot can be quieted', () => {
+    // The dot renders from `status`, which stays `idle` or `busy` for an exited
+    // pane by design, so the tab carries the exit as a class and CSS does the
+    // rest. Without it a green or pulsing dot sits beside the badge.
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 0, at: 1 });
+    expect(tab.classList.contains('tab-agent-exited')).toBe(true);
+  });
+
+  it('unmarks the tab when the pane comes back', () => {
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 0, at: 1 });
+    applyPaneExitBadge(tab, undefined);
+    expect(tab.classList.contains('tab-agent-exited')).toBe(false);
+  });
+
+  it('removes the badge when the pane comes back', () => {
+    // The retraction half: a respawned pane must not keep reading "exited".
+    const tab = makeTab();
+    applyPaneExitBadge(tab, { status: 0, at: 1 });
+    applyPaneExitBadge(tab, undefined);
+    expect(badge(tab)).toBeNull();
+  });
+
+  it('is what the incremental render path calls', () => {
+    expect(appJs).toContain('applyPaneExitBadge(tab, session.paneExit)');
+  });
+});
+
+describe('the rich row pill of an exited session', () => {
+  // The detailed sidebar and rail classify rows through `_mobileOverviewState()`,
+  // which reads `status` and knows nothing about the exit, so without an override
+  // the muted dot sat beside a pill saying "idle".
+  const appJs = readFileSync(resolve(import.meta.dirname, '../src/web/public/app.js'), 'utf8');
+  const fn = (re: RegExp, name: string) => {
+    const m = appJs.match(re)?.[0];
+    if (!m) throw new Error(`${name} not found in app.js`);
+    return m;
+  };
+  type Row = { state: string; exited: boolean; pill: string; since: { key: string; at: number } | null };
+  const host = new Function(
+    `${fn(/function paneExitLabel\([\s\S]*?\n\}/, 'paneExitLabel')}
+    return {
+      ${fn(/ {2}_sidebarRichPillLabel\(state\) \{[\s\S]*?\n {2}\}/, '_sidebarRichPillLabel')},
+      ${fn(/ {2}_sidebarRichRow\(id, session\) \{[\s\S]*?\n {2}\}/, '_sidebarRichRow')},
+      _mobileOverviewState(session, hooks) {
+        if (hooks && hooks.has('permission_prompt')) return 'needs';
+        if (hooks && hooks.has('idle_prompt')) return 'waiting';
+        return session.status === 'busy' ? 'working' : 'idle';
+      },
+      _mobileOverviewSince(state, session) {
+        return { key: state, at: session.lastActivityAt };
+      },
+    };`
+  )() as { pendingHooks?: Map<string, Set<string>>; _sidebarRichRow: (id: string, s: unknown) => Row };
+
+  it('says exited, measured from when the exit was observed', () => {
+    const row = host._sidebarRichRow('s1', { status: 'idle', lastActivityAt: 5, paneExit: { status: 137, at: 42 } });
+    expect(row.state).toBe('idle');
+    expect(row.exited).toBe(true);
+    expect(row.pill).toBe('exited');
+    expect(row.since).toEqual({ key: 'exited', at: 42 });
+  });
+
+  it('keeps the classified state for sorting, so the home-screen order is unchanged', () => {
+    const row = host._sidebarRichRow('s1', { status: 'busy', lastActivityAt: 5, paneExit: { at: 42 } });
+    expect(row.state).toBe('working');
+    expect(row.pill).toBe('exited');
+  });
+
+  it('lets a pending permission dialog keep its own pill', () => {
+    host.pendingHooks = new Map([['s1', new Set(['permission_prompt'])]]);
+    try {
+      const row = host._sidebarRichRow('s1', { status: 'idle', lastActivityAt: 5, paneExit: { status: 0, at: 42 } });
+      expect(row.exited).toBe(false);
+      expect(row.pill).toBe('needs you');
+    } finally {
+      host.pendingHooks = undefined;
+    }
+  });
+
+  it('reads idle for a live session', () => {
+    const row = host._sidebarRichRow('s1', { status: 'idle', lastActivityAt: 5 });
+    expect(row.exited).toBe(false);
+    expect(row.pill).toBe('idle');
+    expect(row.since).toEqual({ key: 'idle', at: 5 });
+  });
+
+  it('styles the exited pill on both rich surfaces', () => {
+    const css = readFileSync(resolve(import.meta.dirname, '../src/web/public/styles.css'), 'utf8');
+    expect(css).toContain('html[data-sidebar-detail="rich"] .session-sidebar .tab-pill--exited');
+    expect(css).toContain('.tab-rail .tab-pill--exited');
+  });
+});
+
+describe('what colour the status dot ends up', () => {
+  /*
+   * The dot renders from `status`, which stays `idle` or `busy` for an exited
+   * pane, so the mute is a CSS rule keyed on the `tab-agent-exited` class. It
+   * competes with two other families of rule over the same dot, and this tree
+   * has lost that competition before: the alert rules and the rich-rail state
+   * rules already exclude each other by hand rather than by cascade.
+   *
+   * So the cascade is resolved rather than asserted from selector text. Every
+   * rule in styles.css that paints `.tab-status` goes into a real document and
+   * a real engine answers, which is what makes a rule moved up the file or a
+   * selector given one more class fail here.
+   *
+   * ⚠ In styles.css the rules inside an at-rule are skipped, so the desktop
+   * cases describe a wide viewport with motion allowed. mobile.css is loaded
+   * separately for the phone cases, and there its @media blocks are FLATTENED
+   * rather than skipped, because that file is phone-and-tablet-only and its
+   * whole content sits inside them. jsdom reports a custom property
+   * unresolved, so the expected values are the `var(--x)` tokens the
+   * stylesheets write.
+   */
+  const readRules = (file: string, flattenMedia: boolean): string[] => {
+    const out: string[] = [];
+    postcss.parse(readFileSync(resolve(import.meta.dirname, `../src/web/public/${file}`), 'utf8')).walkRules((rule) => {
+      if (!rule.selector.includes('.tab-status')) return;
+      const parents: string[] = [];
+      let insideAtRule = false;
+      for (let p = rule.parent; p && p.type !== 'root'; p = p.parent) {
+        if (p.type === 'rule') parents.unshift(p.selector);
+        else insideAtRule = true;
+      }
+      if (insideAtRule && !flattenMedia) return;
+      const decls: string[] = [];
+      rule.each((node) => {
+        if (node.type === 'decl') decls.push(`${node.prop}: ${node.value}${node.important ? ' !important' : ''};`);
+      });
+      if (decls.length === 0) return;
+      const selectors = rule.selectors.map((sel) => (parents.length ? `${parents.join(' ')} ${sel}` : sel));
+      out.push(`${selectors.join(',')} { ${decls.join(' ')} }`);
+    });
+    return out;
+  };
+
+  const dotRules = readRules('styles.css', false);
+  // index.html loads mobile.css after styles.css, so it goes last here too.
+  const phoneRules = [...dotRules, ...readRules('mobile.css', true)];
+
+  /** Paint the dot of one tab and read back what the cascade decided. */
+  const dot = (opts: { tab: string; dotState?: string; rail?: boolean; phone?: boolean }) => {
+    const railAttrs = opts.rail ? ` data-tab-orientation="vertical" data-tab-rail-detail="rich"` : '';
+    const container = opts.rail ? 'tab-rail' : 'session-tabs';
+    const rules = opts.phone ? phoneRules : dotRules;
+    const dom = new JSDOM(
+      `<!DOCTYPE html><html${railAttrs}><head><style>${rules.join('\n')}</style></head><body>` +
+        `<div class="${container}"><div class="session-tab ${opts.tab}">` +
+        `<span id="dot" class="tab-status ${opts.dotState ?? 'idle'}"></span></div></div></body></html>`
+    );
+    const style = dom.window.getComputedStyle(dom.window.document.getElementById('dot')!);
+    return {
+      background: style.background,
+      opacity: style.opacity,
+      boxShadow: style.boxShadow,
+      animation: style.animation,
+    };
+  };
+
+  it('finds the rules it is meant to be resolving', () => {
+    // A selector rename that emptied this list would make every case below pass
+    // against a stylesheet with no rules in it.
+    expect(dotRules.some((rule) => rule.includes('tab-agent-exited'))).toBe(true);
+    expect(dotRules.some((rule) => rule.includes('tab-alert-action'))).toBe(true);
+  });
+
+  it('mutes the dot of an exited session', () => {
+    expect(dot({ tab: 'tab-agent-exited' })).toMatchObject({ background: 'var(--text-muted)', opacity: '0.5' });
+  });
+
+  it('leaves a live session green', () => {
+    expect(dot({ tab: '' }).background).toBe('var(--green)');
+  });
+
+  it('keeps a pending permission dialog RED on an exited session', () => {
+    // The one the maintainer asked for: the exit must not quiet an alert. A
+    // board that says two things at once is a board people stop trusting, and
+    // between "the agent is gone" and "this session is blocked on you", the
+    // one that needs a human wins.
+    expect(dot({ tab: 'tab-agent-exited tab-alert-action' }).background).toBe('var(--red)');
+  });
+
+  it('keeps a pending idle alert YELLOW on an exited session', () => {
+    expect(dot({ tab: 'tab-agent-exited tab-alert-idle' }).background).toBe('var(--yellow)');
+  });
+
+  it('mutes a dot the exit caught mid-turn, and stops it pulsing', () => {
+    // `.tab-status.busy` animates `pulse`, so muting the colour alone would
+    // leave a grey dot breathing as if the agent were still working.
+    expect(dot({ tab: 'tab-agent-exited', dotState: 'busy' })).toMatchObject({
+      background: 'var(--text-muted)',
+      opacity: '0.5',
+      animation: 'none',
+    });
+  });
+
+  it('mutes the dot on a rich tab rail too, halo included', () => {
+    // The rail's own state rules are far more specific than the strip's mute
+    // (measured: an exited session kept a full green dot AND the working halo),
+    // so the mute carries a rail twin that must stay below them in source order.
+    expect(dot({ tab: 'tab-agent-exited tab-state-working', dotState: 'busy', rail: true })).toMatchObject({
+      background: 'var(--text-muted)',
+      opacity: '0.5',
+      boxShadow: 'none',
+    });
+    expect(dot({ tab: 'tab-agent-exited tab-state-idle', rail: true }).background).toBe('var(--text-muted)');
+  });
+
+  it('leaves an errored dot red, which is the state that offers a restart', () => {
+    // `status: 'error'` is the PTY-exit breaker's value and the browser answers
+    // it with a "restart it?" confirm, so it is a needs-you colour by the same
+    // argument that protects the two alert classes. Reachable when a restart of
+    // a dead pane keeps failing: the breaker trips while the pane stays dead.
+    expect(dot({ tab: 'tab-agent-exited', dotState: 'error' }).background).toBe('var(--red)');
+  });
+
+  it('mutes the dot on a phone, glow and all', () => {
+    // mobile.css enlarges the working dot to 9px and gives it a green glow with
+    // !important, and `status` stays `busy` for a pane whose agent died
+    // mid-turn — so without a phone-side rule this renders a grey dot wearing a
+    // green halo beside a badge reading "exited".
+    expect(dot({ tab: 'tab-agent-exited', dotState: 'busy', phone: true })).toMatchObject({
+      background: 'var(--text-muted)',
+      boxShadow: 'none',
+    });
+  });
+
+  it('keeps an alert red on a phone as well', () => {
+    expect(dot({ tab: 'tab-agent-exited tab-alert-action', dotState: 'busy', phone: true }).background).toBe(
+      'var(--red)'
+    );
+  });
+
+  it('finds the phone rules it is meant to be resolving', () => {
+    // Same self-guard as the desktop one: if mobile.css stopped contributing
+    // rules, every phone case above would pass against the desktop cascade.
+    expect(phoneRules.length).toBeGreaterThan(dotRules.length);
+  });
+
+  it('still keeps an alert red on the rich tab rail', () => {
+    expect(
+      dot({ tab: 'tab-agent-exited tab-alert-action tab-state-working', dotState: 'busy', rail: true }).background
+    ).toBe('var(--red)');
+  });
+});

test/session-pane-exit.test.ts

@@ -0,0 +1,350 @@
+/**
+ * @fileoverview `SessionState.paneExit` — Codeman noticing that a pane's agent
+ * has exited (Ark0N/Codeman#446).
+ *
+ * Codeman creates every tmux pane with `remain-on-exit on`, so `/exit` ends the
+ * CLI while tmux keeps the pane and the `tmux attach-session` process Codeman
+ * records as the session's pid. No PTY exit handler runs, and the record used to
+ * keep both its pid and `status: 'idle'`, so the board showed an exited session
+ * as a live idle one.
+ *
+ * Four properties are pinned here, each because getting it wrong costs something
+ * specific:
+ *
+ *  1. **The field is tri-state, and absence means UNKNOWN.** A direct-PTY
+ *     session owns no pane, a remote SSH session's local pane holds the ssh
+ *     client, and a docker case's local pane holds a `docker exec`. In all
+ *     three, a dead local pane is not the agent exiting.
+ *  2. **`status` and `pid` are never touched.** `status: 'error'` belongs to the
+ *     PTY-exit circuit breaker and makes the browser offer a restart, and a null
+ *     `pid` is what makes the browser re-attach and launch a fresh CLI.
+ *  3. **It reaches `toState()`**, which is both the `session:updated` payload
+ *     and what `state.json` persists.
+ *  4. **It round-trips through the store**, because a reboot takes the tmux
+ *     server and the persisted record is the only thing left that can say the
+ *     agent was already gone.
+ *
+ * Port: 3187
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Session } from '../src/session.js';
+import { WebServer } from '../src/web/server.js';
+import { StateStore } from '../src/state-store.js';
+import type { PaneExit, SessionRemote, SessionDocker, SessionState } from '../src/types.js';
+import type { MuxSession, TerminalMultiplexer } from '../src/mux-interface.js';
+import { hasObservablePaneSession } from '../src/tmux-manager.js';
+
+const PORT = 3187;
+
+const EXIT: PaneExit = { status: 0, at: 1_700_000_000_000 };
+
+/** The two mux members `Session` reads when it decides whether the field applies. */
+const stubMux = () => ({ isAvailable: () => true }) as unknown as TerminalMultiplexer;
+
+const stubMuxSession = (muxName = 'codeman-aaaa') => ({ muxName, sessionId: 'aaaa' }) as unknown as MuxSession;
+
+const remote: SessionRemote = { hostId: 'h1', label: 'box', host: 'box', user: 'dev' } as SessionRemote;
+
+const docker: SessionDocker = { hostId: 'd1', label: 'ctr', containerName: 'ctr' } as SessionDocker;
+
+/** A local, mux-backed session: the one shape the field applies to. */
+function localMuxSession(extra: Record<string, unknown> = {}) {
+  return new Session({
+    workingDir: '/tmp',
+    mode: 'claude',
+    useMux: true,
+    mux: stubMux(),
+    muxSession: stubMuxSession(),
+    ...extra,
+  });
+}
+
+describe('Session.setPaneExit scoping', () => {
+  it('accepts an exit for a local mux-backed session', () => {
+    const session = localMuxSession();
+    expect(session.setPaneExit(EXIT)).toBe(true);
+    expect(session.paneExit).toEqual(EXIT);
+  });
+
+  it('stays unknown for a direct-PTY session, which owns no pane at all', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude', useMux: false });
+    expect(session.setPaneExit(EXIT)).toBe(false);
+    expect(session.paneExit).toBeUndefined();
+  });
+
+  it('stays unknown while the session has no mux session yet', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'claude', useMux: true, mux: stubMux() });
+    expect(session.setPaneExit(EXIT)).toBe(false);
+    expect(session.paneExit).toBeUndefined();
+  });
+
+  it('stays unknown for a remote SSH session, whose pane holds the ssh client', () => {
+    // A dead ssh client means a transport drop OR an exit, and telling those two
+    // apart is the whole of PR #355. Publishing it as an agent exit would assert
+    // the answer Codeman does not have.
+    const session = localMuxSession({ remote });
+    expect(session.setPaneExit(EXIT)).toBe(false);
+    expect(session.paneExit).toBeUndefined();
+  });
+
+  it('stays unknown for a docker case, whose pane holds a docker exec', () => {
+    const session = localMuxSession({ docker });
+    expect(session.setPaneExit(EXIT)).toBe(false);
+    expect(session.paneExit).toBeUndefined();
+  });
+
+  it('clears a stored exit when a later tick reports nothing', () => {
+    const session = localMuxSession();
+    session.setPaneExit(EXIT);
+    expect(session.setPaneExit(undefined)).toBe(true);
+    expect(session.paneExit).toBeUndefined();
+  });
+
+  it('reports no change when a tick repeats the same observation', () => {
+    // The caller persists and broadcasts on a true, and this tick runs every
+    // 2000 ms for every session.
+    const session = localMuxSession();
+    session.setPaneExit(EXIT);
+    expect(session.setPaneExit({ ...EXIT })).toBe(false);
+  });
+
+  it('reports a change when the exit status changes', () => {
+    const session = localMuxSession();
+    session.setPaneExit(EXIT);
+    expect(session.setPaneExit({ status: 137, at: EXIT.at })).toBe(true);
+    expect(session.paneExit).toEqual({ status: 137, at: EXIT.at });
+  });
+});
+
+describe("the watcher's read gate agrees with the session's scoping", () => {
+  // `hasObservablePaneSession()` decides whether a watcher tick execs tmux at
+  // all, and `Session.paneExitApplies` decides whether the answer is kept. They
+  // are two copies of one rule, and drift between them is silent: too narrow
+  // and a session that could report an exit never gets read, too wide and every
+  // tick pays for an answer the session throws away.
+  const muxSession = (extra: Partial<MuxSession> = {}): MuxSession =>
+    ({
+      sessionId: 'aaaa',
+      muxName: 'codeman-aaaa',
+      pid: 100,
+      createdAt: 0,
+      workingDir: '/tmp',
+      mode: 'claude',
+      attached: true,
+      ...extra,
+    }) as MuxSession;
+
+  const cases: { shape: string; mux: MuxSession; session: () => Session }[] = [
+    { shape: 'local', mux: muxSession(), session: () => localMuxSession() },
+    { shape: 'remote SSH', mux: muxSession({ remote }), session: () => localMuxSession({ remote }) },
+    { shape: 'docker', mux: muxSession({ docker }), session: () => localMuxSession({ docker }) },
+    {
+      shape: 'rebuilt from the socket',
+      mux: muxSession({ discovered: true }),
+      session: () => localMuxSession({ discoveredMuxSession: true }),
+    },
+  ];
+
+  for (const { shape, mux, session } of cases) {
+    it(`agrees for a ${shape} session`, () => {
+      const sessionKeepsIt = session().setPaneExit(EXIT);
+      expect(hasObservablePaneSession([mux])).toBe(sessionKeepsIt);
+    });
+  }
+});
+
+describe('Session.toState with an exited agent', () => {
+  it('publishes the exit and leaves status and pid alone', () => {
+    const session = localMuxSession();
+    const before = session.toState();
+    session.setPaneExit(EXIT);
+    const after = session.toState();
+
+    expect(before.paneExit).toBeUndefined();
+    expect(after.paneExit).toEqual(EXIT);
+    expect(after.status).toBe(before.status);
+    expect(after.pid).toBe(before.pid);
+    // `status: 'error'` is the PTY-exit breaker's value; the browser answers it
+    // with a "restart it?" confirm.
+    expect(after.status).not.toBe('error');
+  });
+
+  it('restores a persisted exit so the first persist after boot cannot blank it', () => {
+    const session = localMuxSession({ paneExit: EXIT });
+    expect(session.toState().paneExit).toEqual(EXIT);
+  });
+
+  it('ignores a persisted exit for a session shape the field never applies to', () => {
+    // The scoping is not only about live ticks: a record written before a
+    // session was reconfigured must not resurrect an answer that cannot hold.
+    // The constructor alone has to enforce it, before any tick runs.
+    expect(new Session({ workingDir: '/tmp', mode: 'claude', useMux: false, paneExit: EXIT }).paneExit).toBeUndefined();
+    expect(localMuxSession({ remote, paneExit: EXIT }).paneExit).toBeUndefined();
+    expect(localMuxSession({ docker, paneExit: EXIT }).paneExit).toBeUndefined();
+  });
+});
+
+describe('a relaunch in the same pane forgetting the old exit', () => {
+  /** A mux whose respawn succeeds, so `restartCli()` reaches its success path. */
+  const respawningMux = () => {
+    const cleared: string[] = [];
+    const mux = {
+      isAvailable: () => true,
+      muxSessionExists: () => true,
+      respawnPane: async () => 4242,
+      clearPaneExit: (muxName: string) => cleared.push(muxName),
+    };
+    return { mux: mux as unknown as TerminalMultiplexer, cleared };
+  };
+
+  it('clears the exit when restartCli relaunches the CLI', async () => {
+    // restartCli() is the custom-model endpoint switch. Its caller persists and
+    // broadcasts straight afterwards, so an exit left in place here is written
+    // back onto a session that is running again.
+    const { mux, cleared } = respawningMux();
+    const session = new Session({
+      workingDir: '/tmp',
+      mode: 'claude',
+      useMux: true,
+      mux,
+      muxSession: stubMuxSession(),
+      paneExit: EXIT,
+    });
+    expect(session.paneExit).toEqual(EXIT);
+
+    expect(await session.restartCli()).toBe(true);
+
+    expect(session.paneExit).toBeUndefined();
+    expect(session.toState().paneExit).toBeUndefined();
+    // Both halves: the record and the mux layer's cache, the latter of which
+    // also invalidates a pane read already in flight.
+    expect(cleared).toEqual(['codeman-aaaa']);
+  });
+
+  it('leaves the exit alone when the relaunch fails', async () => {
+    // A failed respawn means the old command is still what the pane last ran.
+    const { mux, cleared } = respawningMux();
+    (mux as unknown as { respawnPane: () => Promise<null> }).respawnPane = async () => null;
+    const session = new Session({
+      workingDir: '/tmp',
+      mode: 'claude',
+      useMux: true,
+      mux,
+      muxSession: stubMuxSession(),
+      paneExit: EXIT,
+    });
+
+    expect(await session.restartCli()).toBe(false);
+
+    expect(session.paneExit).toEqual(EXIT);
+    expect(cleared).toEqual([]);
+  });
+});
+
+describe('paneExit round trip through state.json', () => {
+  let dir: string | null = null;
+
+  afterEach(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+    dir = null;
+  });
+
+  it('survives a write and a reload, which is what a reboot restore reads', () => {
+    dir = mkdtempSync(join(tmpdir(), 'codeman-pane-exit-'));
+    const file = join(dir, 'state.json');
+    const stored: SessionState = {
+      ...localMuxSession().toState(),
+      paneExit: { status: 0, signal: undefined, at: 1_700_000_000_000 },
+    };
+
+    const writer = new StateStore(file);
+    writer.setSession(stored.id, stored);
+    writer.saveNow();
+
+    const reader = new StateStore(file);
+    expect(reader.getSession(stored.id)?.paneExit).toEqual({ at: 1_700_000_000_000, status: 0 });
+  });
+
+  it('reads a record written before the field existed as unknown, needing no migration', () => {
+    dir = mkdtempSync(join(tmpdir(), 'codeman-pane-exit-'));
+    const file = join(dir, 'state.json');
+    const legacy = localMuxSession().toState();
+    delete legacy.paneExit;
+
+    const writer = new StateStore(file);
+    writer.setSession(legacy.id, legacy);
+    writer.saveNow();
+
+    expect(new StateStore(file).getSession(legacy.id)?.paneExit).toBeUndefined();
+  });
+});
+
+describe('a pane read reaching the session record', () => {
+  // Drives the real `paneExitsUpdated` wiring rather than asserting on source
+  // text: a fake reading goes into the mux, the event fires, and the session
+  // record is checked. This is the path findings about the watcher turn on.
+  let server: WebServer | null = null;
+
+  afterEach(async () => {
+    await server?.stop?.();
+    server = null;
+  });
+
+  const build = () => {
+    const web = new WebServer(PORT, false, true);
+    const mux = (web as unknown as { mux: Record<string, unknown> }).mux;
+    const session = localMuxSession();
+    (web as unknown as { sessions: Map<string, Session> }).sessions.set(session.id, session);
+    return { web, mux, session };
+  };
+
+  it('publishes an exit the mux reports for a local pane', () => {
+    const { web, mux, session } = build();
+    server = web;
+    mux.getPaneExit = () => EXIT;
+    (mux as unknown as { emit: (e: string) => void }).emit('paneExitsUpdated');
+
+    expect(session.paneExit).toEqual(EXIT);
+    expect(session.toState().paneExit).toEqual(EXIT);
+  });
+
+  it('leaves status and pid alone while doing it', () => {
+    const { web, mux, session } = build();
+    server = web;
+    const before = session.toState();
+    mux.getPaneExit = () => EXIT;
+    (mux as unknown as { emit: (e: string) => void }).emit('paneExitsUpdated');
+
+    const after = session.toState();
+    expect(after.status).toBe(before.status);
+    expect(after.pid).toBe(before.pid);
+    // `status: 'error'` is the PTY-exit breaker's value; it makes the browser
+    // offer a restart. A null pid makes it launch a fresh CLI.
+    expect(after.status).not.toBe('error');
+  });
+
+  it('retracts the exit once the mux reports the pane is back', () => {
+    const { web, mux, session } = build();
+    server = web;
+    mux.getPaneExit = () => EXIT;
+    (mux as unknown as { emit: (e: string) => void }).emit('paneExitsUpdated');
+    mux.getPaneExit = () => undefined;
+    (mux as unknown as { emit: (e: string) => void }).emit('paneExitsUpdated');
+
+    expect(session.paneExit).toBeUndefined();
+  });
+
+  it('publishes nothing for a session the field does not apply to', () => {
+    const { web, mux } = build();
+    server = web;
+    const remoteSession = localMuxSession({ remote });
+    (web as unknown as { sessions: Map<string, Session> }).sessions.set(remoteSession.id, remoteSession);
+    mux.getPaneExit = () => EXIT;
+    (mux as unknown as { emit: (e: string) => void }).emit('paneExitsUpdated');
+
+    expect(remoteSession.paneExit).toBeUndefined();
+  });
+});

test/session-resize-arbitration.test.ts

@@ -19,6 +19,37 @@ function attachFakePty(session: Session, cols = 160, rows = 48) {
   return resize;
 }
 
+describe('Session.ptyGeometry', () => {
+  // ⚠️ `resize()` writes `_ptyCols`/`_ptyRows` only when `ptyProcess` is set,
+  // and nothing seeds them from the spawn geometry — so the fields hold the
+  // constructor defaults of 120x40 for any session whose pane is not running.
+  // Reporting those to a client made it adopt a width no process had ever been
+  // told, and on anything narrower than 120 columns claim another device owned
+  // the pane when none existed (issue #464).
+  it('reports nothing for a session that has no pane', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'shell' });
+    expect(session.ptyGeometry).toBeNull();
+  });
+
+  it('still reports nothing after a resize it could not apply', () => {
+    const session = new Session({ workingDir: '/tmp', mode: 'shell' });
+    session.resize(45, 20, { viewportType: 'mobile' });
+    // The resize was swallowed (no pty to resize), so there is no geometry to
+    // report — NOT the 120x40 the fields still hold.
+    expect(session.ptyGeometry).toBeNull();
+  });
+
+  it('reports the pane geometry once a pane exists, and follows a resize', () => {
+    // The contrast, so "always null" would fail this.
+    const session = new Session({ workingDir: '/tmp', mode: 'shell' });
+    attachFakePty(session, 160, 48);
+    expect(session.ptyGeometry).toEqual({ cols: 160, rows: 48 });
+
+    session.resize(62, 40, { viewportType: 'mobile' });
+    expect(session.ptyGeometry).toEqual({ cols: 62, rows: 40 });
+  });
+});
+
 describe('Session resize arbitration', () => {
   it('lets a mobile-only session shrink below the spawn default (no desktop connected)', () => {
     const session = new Session({ workingDir: '/tmp', mode: 'shell' });

test/session-sidebar-ux.test.ts

@@ -73,3 +73,53 @@ describe('vertical session navigation UX contract', () => {
     expect(i18n).toContain("'Adjust only session names in the vertical sidebar.':");
   });
 });
+
+describe('watching badge on a rich session row', () => {
+  it('reads the label off the session payload', () => {
+    expect(app).toContain("watching: typeof session.watching === 'string' ? session.watching : ''");
+  });
+
+  it('renders it beside the state pill rather than in place of it', () => {
+    // A session can be watching a monitor AND holding a question for the user, so the
+    // pill that says which one still decides the row; this badge only adds a fact.
+    const meta = app.slice(app.indexOf('_sidebarRichMetaHTML(row) {'));
+    const body = meta.slice(0, meta.indexOf('_sidebarRichStampText(timestamp, format) {'));
+    expect(body).toContain('tab-pill tab-pill--${escapeHtml(pillMod)}');
+    expect(body).toContain('tab-pill tab-pill--watching');
+    expect(body).toContain('Still running in the background:');
+  });
+
+  it('re-renders the row when the background work changes', () => {
+    // The meta line is rebuilt only when this signature moves, so a badge left out of
+    // it would appear and disappear a render late, or not at all.
+    expect(app).toContain(
+      "const sig = `${row.state}${row.exited ? '+exited' : ''}:${row.since ? row.since.at : 0}:${row.createdAt}:${row.watching}`"
+    );
+  });
+
+  it('escapes the label everywhere it reaches markup', () => {
+    // `watching` is pane-derived and a config-supplied pattern decides what its capture
+    // group holds, so every interpolation of it into HTML has to go through escapeHtml().
+    // The row is installed with innerHTML, which makes an unescaped quote in that
+    // attribute an injection rather than a cosmetic bug.
+    expect(app).toContain('${richRow.createdAt}:${escapeHtml(richRow.watching)}"');
+    expect(app).not.toContain('${richRow.createdAt}:${richRow.watching}"');
+  });
+
+  it('words the tooltip exactly as the phone overview does', () => {
+    // Both files build this sentence themselves, deliberately, so that a stale cached
+    // module still renders a complete row. Substring-matching the prefix would let the
+    // two drift; the whole sentence is what has to agree.
+    const overview = readFileSync(resolve(publicDir, 'mobile-overview.js'), 'utf8');
+    expect(overview).toContain("'Still running in the background: ' + label");
+    expect(app).toContain('`Still running in the background: ${row.watching}`');
+  });
+
+  it('colours it with the accent, never with the two colours that mean a human is needed', () => {
+    const rule = styles.slice(styles.indexOf('.tab-pill--watching'));
+    const block = rule.slice(0, rule.indexOf('}'));
+    expect(block).toContain('var(--accent)');
+    expect(block).not.toContain('var(--red)');
+    expect(block).not.toContain('var(--yellow)');
+  });
+});

test/session-watching.test.ts

@@ -0,0 +1,400 @@
+/**
+ * The badge a session wears while work it started in the background is still running.
+ *
+ * The bug this pins: an agent that arms a monitor, backgrounds a shell or hands work to a
+ * cloud session is told to end its turn, so the pane falls quiet, Claude Code's idle
+ * notification arrives a minute later, and every Codeman surface files the session under
+ * NEEDS YOU. Nothing wants the user there. The CLI itself says so on the last row of its
+ * screen (`⏵⏵ bypass permissions on · 1 monitor · ← for agents`), and reading that row is
+ * what tells a session waiting for its own background work from one waiting for a human.
+ *
+ * The pane fixtures below are verbatim captures (`tmux -L codeman capture-pane -p`) from a
+ * live Claude Code 2.1.278 session on 2026-09-21.
+ */
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { Session } from '../src/session.js';
+import { getCli } from '../src/config/cli-registry/index.js';
+import { compileVersionRegex } from '../src/config/cli-registry/patterns.js';
+import {
+  watchingLabel,
+  WATCHING_TAIL_LINES,
+  MAX_WATCHING_LABEL_CHARS,
+  IDLE_SILENCE_MS,
+} from '../src/session-activity.js';
+
+/** The registry's own patterns, which are what every consumer runs. */
+const CLAUDE_WATCHING = compileVersionRegex(getCli('claude')!.capabilities.workDetect!.watchingLine!)!;
+const CODEX_WATCHING = compileVersionRegex(getCli('codex')!.capabilities.workDetect!.watchingLine!)!;
+const CODEX_TAIL = getCli('codex')!.capabilities.workDetect!.watchingLines!;
+
+/**
+ * The foot of a Codex pane, verbatim (codex-cli 0.154.0, 2026-09-22). Codex does not
+ * write on its last row: the status line is there, the composer above it, and the
+ * background-terminal row above that, which is why codex declares its own window.
+ */
+const CODEX_STATUS =
+  '  gpt-5.6-sol medium · Context 98% left · ~/codeman-cases/codex-probe · 5h 99% left · weekly 94% left';
+const CODEX_WITH_TERMINAL = [
+  '• OK',
+  '',
+  '  1 background terminal running · /ps to view · /stop to close',
+  '',
+  '',
+  '› Ask Codex to do anything',
+  '',
+  CODEX_STATUS,
+  '',
+].join('\n');
+const CODEX_STOPPED = [
+  '• OK',
+  '',
+  '• Stopping all background terminals.',
+  '',
+  '',
+  '› Ask Codex to do anything',
+  '',
+  CODEX_STATUS,
+  '',
+].join('\n');
+
+/** The bottom of a Claude pane: composer, the user's status line, the footer row. */
+function pane(footer: string, body = ''): string {
+  return (
+    body +
+    '╭──────────────────────────────────────╮\n' +
+    '│ ❯                                    │\n' +
+    '╰──────────────────────────────────────╯\n' +
+    '  ~/innovi/gtd-board [main] Opus 5 ctx: 11%\n' +
+    `  ${footer}\n`
+  );
+}
+
+const WITH_MONITOR = pane('⏵⏵ bypass permissions on · 1 monitor · ← for agents');
+const WITH_SHELL = pane('⏵⏵ bypass permissions on · 1 shell · ← for agents');
+const NOTHING_RUNNING = pane('⏵⏵ bypass permissions on (shift+tab to cycle) · ← for agents');
+
+/** A composer repaint: the frame Claude ships roughly once a second while working. */
+const COMPOSER_REPAINT =
+  '\x1b[31;1H\x1b[38;5;246m❯\xa0\x1b[39m\x1b[0m\x1b[33;1H  \x1b[38;5;246mOpus 5  in:143,699 out:669  ctx:14%\x1b[39m';
+
+type SessionInternals = {
+  _handleTerminalOutput(data: string): void;
+  _detectInteractiveActivity(data: string): void;
+};
+
+/** One PTY chunk, exactly as the interactive handler sees it. */
+function feed(session: Session, data: string): void {
+  const internals = session as unknown as SessionInternals;
+  internals._handleTerminalOutput(data);
+  internals._detectInteractiveActivity(data);
+}
+
+/** A session whose mux reports a fixed (or scripted) screen for the pane probe to read. */
+function withFakePane(screen: string | (() => string), mode: 'claude' | 'codex' = 'claude'): Session {
+  const read = typeof screen === 'function' ? screen : () => screen;
+  const mux = {
+    isAvailable: () => true,
+    capturePaneText: () => read(),
+  } as unknown as NonNullable<ConstructorParameters<typeof Session>[0]>['mux'];
+  return new Session({
+    workingDir: '/tmp',
+    mode,
+    mux,
+    muxSession: { muxName: 'codeman-test', sessionId: 'test', createdAt: Date.now() },
+  } as ConstructorParameters<typeof Session>[0]);
+}
+
+/** Codex's own composer repaint, the frame that arms its idle confirmation. */
+const CODEX_COMPOSER_REPAINT = '\x1b[31;1H\x1b[38;5;246m›\xa0\x1b[39m\x1b[0m';
+
+/** Run one turn and let it end, which is when the probe reads the screen. */
+function runAndSettle(session: Session, repaint: string = COMPOSER_REPAINT): void {
+  for (let i = 0; i < 3; i++) {
+    feed(session, repaint);
+    vi.advanceTimersByTime(1000);
+  }
+  vi.advanceTimersByTime(IDLE_SILENCE_MS + 2000);
+}
+
+describe('watchingLabel', () => {
+  it('reads the label off the footer row', () => {
+    expect(watchingLabel(WITH_MONITOR, CLAUDE_WATCHING)).toBe('1 monitor');
+    expect(watchingLabel(WITH_SHELL, CLAUDE_WATCHING)).toBe('1 shell');
+  });
+
+  it('reads every kind of background work the CLI names', () => {
+    const labels = [
+      '2 monitors',
+      '3 shells',
+      '1 cloud session',
+      '2 cloud sessions',
+      '1 local agent',
+      '4 background tasks',
+      '1 MCP task',
+      '1 background dynamic workflow',
+      '2 remote dynamic workflows',
+      '1 Artifact comment monitor',
+      '2 teams',
+    ];
+    for (const label of labels) {
+      expect(watchingLabel(pane(`⏵⏵ bypass permissions on · ${label} · ← for agents`), CLAUDE_WATCHING)).toBe(label);
+    }
+  });
+
+  it('says nothing about a pane that is running nothing', () => {
+    expect(watchingLabel(NOTHING_RUNNING, CLAUDE_WATCHING)).toBeNull();
+    expect(watchingLabel('', CLAUDE_WATCHING)).toBeNull();
+    expect(watchingLabel(null, CLAUDE_WATCHING)).toBeNull();
+  });
+
+  it('ignores the same words in the transcript above the composer', () => {
+    // The whole reason the search is confined to the foot of the screen: a session that
+    // PRINTS "1 monitor" (this one has been discussing exactly that) is not running one.
+    const transcript =
+      '> does Codeman know about watching?\n' +
+      '⏺ The footer says · 1 monitor · while a monitor is armed, and · 2 shells · for\n' +
+      '  backgrounded commands. Codeman reads neither today.\n' +
+      '  Nothing else on the screen means background work is running.\n';
+    expect(watchingLabel(pane('⏵⏵ bypass permissions on · ← for agents', transcript), CLAUDE_WATCHING)).toBeNull();
+  });
+
+  it('looks no further up the screen than the tail it declares', () => {
+    const chip = '⏵⏵ bypass permissions on · 1 monitor · ← for agents';
+    const below = Array(WATCHING_TAIL_LINES).fill('  still here').join('\n');
+    // Blank lines are dropped before the tail is taken, so a pane padded with them must
+    // still read its own footer.
+    expect(watchingLabel(`${chip}\n\n\n\n\n\n`, CLAUDE_WATCHING)).toBe('1 monitor');
+    expect(watchingLabel(`${chip}\n${below}\n`, CLAUDE_WATCHING)).toBeNull();
+  });
+
+  it('refuses a chip on the row above the footer, which the agent can write', () => {
+    // The status line is one row up, its text comes from a `statusLine` command, and a
+    // session running with permissions bypassed can write that command into
+    // `.claude/settings.json` in its own workspace. The window is what keeps that row
+    // out, so this is the test that would fail if somebody widened it.
+    const forged = pane('⏵⏵ bypass permissions on (shift+tab to cycle) · ← for agents').replace(
+      '  ~/innovi/gtd-board [main] Opus 5 ctx: 11%',
+      '  ~/innovi/gtd-board [main] Opus 5 ctx: 11% · 1 monitor'
+    );
+    expect(watchingLabel(forged, CLAUDE_WATCHING)).toBeNull();
+    // And with the window widened by one, the same screen does match — which is the
+    // whole reason the default is one row.
+    expect(watchingLabel(forged, CLAUDE_WATCHING, 2)).toBe('1 monitor');
+  });
+
+  it('keeps Claude on the default window, because its chip is the last row', () => {
+    expect(getCli('claude')?.capabilities.workDetect?.watchingLines).toBeUndefined();
+    expect(WATCHING_TAIL_LINES).toBe(1);
+  });
+
+  it('refuses a label the footer did not separate, which is the injection guard', () => {
+    // The pattern anchors on the `·` the footer joins its items with. Without that
+    // anchor an agent could silence its own idle alert by printing the words, since the
+    // only rows it cannot write are the footer and the status line.
+    expect(watchingLabel(pane('1 monitor'), CLAUDE_WATCHING)).toBeNull();
+    expect(watchingLabel(pane('running 2 shells for the build'), CLAUDE_WATCHING)).toBeNull();
+    expect(watchingLabel(pane('⏵⏵ bypass permissions on · 1 monitor'), CLAUDE_WATCHING)).toBe('1 monitor');
+  });
+
+  it('reads a coloured footer, because a capture may carry ANSI', () => {
+    const coloured = pane('\u001b[2m⏵⏵ bypass permissions on\u001b[0m · \u001b[36m1 monitor\u001b[0m · ← for agents');
+    expect(watchingLabel(coloured, CLAUDE_WATCHING)).toBe('1 monitor');
+  });
+
+  it('caps the label, because it ends up on a badge and in an approval card', () => {
+    const long = `· ${'9'.repeat(MAX_WATCHING_LABEL_CHARS * 2)} monitors`;
+    const label = watchingLabel(pane(`⏵⏵ bypass permissions on ${long} · ← for agents`), CLAUDE_WATCHING);
+    expect(label?.length).toBe(MAX_WATCHING_LABEL_CHARS);
+  });
+
+  it('survives a pattern handed to it with the global flag set', () => {
+    // compileVersionRegex() never sets `g`, but a test or a reloaded config might, and a
+    // sticky lastIndex would make the same screen match every other call.
+    const global = new RegExp(CLAUDE_WATCHING.source, 'g');
+    expect(watchingLabel(WITH_MONITOR, global)).toBe('1 monitor');
+    expect(watchingLabel(WITH_MONITOR, global)).toBe('1 monitor');
+  });
+});
+
+describe('Session.watching', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('carries what the pane reported once the turn ends', () => {
+    vi.useFakeTimers();
+    const session = withFakePane(WITH_MONITOR);
+    expect(session.watching).toBeNull();
+
+    runAndSettle(session);
+
+    expect(session.status).toBe('idle');
+    expect(session.watching).toBe('1 monitor');
+  });
+
+  it('lets the badge go when the background work is over', () => {
+    vi.useFakeTimers();
+    const screen = { text: WITH_MONITOR };
+    const session = withFakePane(() => screen.text);
+
+    runAndSettle(session);
+    expect(session.watching).toBe('1 monitor');
+
+    screen.text = NOTHING_RUNNING;
+    runAndSettle(session);
+    expect(session.watching).toBeNull();
+  });
+
+  it('announces the change, because the session status does not move with it', () => {
+    // Measured on codex: a background terminal finishing repaints the row away and the
+    // session is idle before and after, so no other event fires. Without this one the
+    // server drops the label and every open page goes on drawing the badge.
+    vi.useFakeTimers();
+    const screen = { text: WITH_MONITOR };
+    const session = withFakePane(() => screen.text);
+    const changes: (string | null)[] = [];
+    session.on('watchingChanged', () => changes.push(session.watching));
+
+    runAndSettle(session);
+    expect(changes).toEqual(['1 monitor']);
+
+    // A repaint that carries the composer glyph but no chip: the pane went quiet again
+    // without a turn, which is exactly the case the event exists for.
+    screen.text = NOTHING_RUNNING;
+    feed(session, COMPOSER_REPAINT);
+    vi.advanceTimersByTime(IDLE_SILENCE_MS + 2000);
+    expect(changes).toEqual(['1 monitor', null]);
+    expect(session.status).toBe('idle');
+  });
+
+  it('says nothing while the answer stays the same', () => {
+    vi.useFakeTimers();
+    const session = withFakePane(WITH_MONITOR);
+    const changes: (string | null)[] = [];
+    session.on('watchingChanged', () => changes.push(session.watching));
+
+    runAndSettle(session);
+    runAndSettle(session);
+    runAndSettle(session);
+    expect(changes).toEqual(['1 monitor']);
+  });
+
+  it('drops its answer when the screen cannot be read, and says so', () => {
+    vi.useFakeTimers();
+    const screen: { text: string | null } = { text: WITH_MONITOR };
+    const session = withFakePane(() => screen.text as string);
+    const changes: (string | null)[] = [];
+    session.on('watchingChanged', () => changes.push(session.watching));
+
+    runAndSettle(session);
+    expect(session.watching).toBe('1 monitor');
+
+    // A stale label would open the next idle prompt already acknowledged, so a failed
+    // capture must degrade toward the alert, not toward silence. The page is told too,
+    // or every open tab would go on drawing the badge.
+    screen.text = null;
+    runAndSettle(session);
+    expect(session.watching).toBeNull();
+    expect(changes).toEqual(['1 monitor', null]);
+  });
+
+  it('reads Codex own row, three up from the bottom of its screen', () => {
+    vi.useFakeTimers();
+    const session = withFakePane(CODEX_WITH_TERMINAL, 'codex');
+    runAndSettle(session, CODEX_COMPOSER_REPAINT);
+    expect(session.status).toBe('idle');
+    expect(session.watching).toBe('1 background terminal');
+  });
+
+  it('reports nothing for a CLI whose screen nobody has characterised', () => {
+    vi.useFakeTimers();
+    expect(getCli('gemini')?.capabilities.workDetect).toBeUndefined();
+    const session = withFakePane(WITH_MONITOR, 'gemini');
+    runAndSettle(session);
+    expect(session.watching).toBeNull();
+  });
+
+  it('never reads another CLI screen', () => {
+    vi.useFakeTimers();
+    // Each pattern is anchored on chrome its own CLI draws, so neither can fire on the
+    // other's pane. A shared fallback would have both reading a screen nobody measured.
+    const codexOnClaudeScreen = withFakePane(WITH_MONITOR, 'codex');
+    runAndSettle(codexOnClaudeScreen, CODEX_COMPOSER_REPAINT);
+    expect(codexOnClaudeScreen.watching).toBeNull();
+
+    const claudeOnCodexScreen = withFakePane(CODEX_WITH_TERMINAL, 'claude');
+    runAndSettle(claudeOnCodexScreen);
+    expect(claudeOnCodexScreen.watching).toBeNull();
+  });
+
+  it('rides along on the payload every session surface reads', () => {
+    vi.useFakeTimers();
+    const session = withFakePane(WITH_SHELL);
+    runAndSettle(session);
+
+    expect(session.toLightDetailedState().watching).toBe('1 shell');
+  });
+});
+
+describe('the row Codex draws', () => {
+  it('reads the label, and only while a terminal is running', () => {
+    expect(watchingLabel(CODEX_WITH_TERMINAL, CODEX_WATCHING, CODEX_TAIL)).toBe('1 background terminal');
+    expect(watchingLabel(CODEX_STOPPED, CODEX_WATCHING, CODEX_TAIL)).toBeNull();
+  });
+
+  it('counts terminals', () => {
+    const three = CODEX_WITH_TERMINAL.replace('1 background terminal running', '3 background terminals running');
+    expect(watchingLabel(three, CODEX_WATCHING, CODEX_TAIL)).toBe('3 background terminals');
+  });
+
+  it('needs the window Codex declares: its row is not the last one', () => {
+    // Pins WHY `watchingLines` exists. Claude's default of two rows reaches the status
+    // line and the composer, and Codex's row sits one further up.
+    expect(watchingLabel(CODEX_WITH_TERMINAL, CODEX_WATCHING, 2)).toBeNull();
+    expect(CODEX_TAIL).toBeGreaterThanOrEqual(3);
+  });
+
+  it('refuses a mention that is not the whole row', () => {
+    // The pattern matches Codex's row end to end, so prose about background terminals —
+    // including prose quoting part of the row — is not enough.
+    for (const line of [
+      '• I left 1 background terminal running for you.',
+      '  1 background terminal running · /ps to view',
+      '  see: 1 background terminal running · /ps to view · /stop to close',
+    ]) {
+      const claim = CODEX_STOPPED.replace('• Stopping all background terminals.', line);
+      expect(watchingLabel(claim, CODEX_WATCHING, CODEX_TAIL)).toBeNull();
+    }
+  });
+
+  it('CAN be forged by Codex own output, and is contained by Codex having no hooks', () => {
+    // Codex's row is third from the bottom only while a terminal runs; with none running
+    // that slot is the last row of the transcript, which the agent writes. Matching the
+    // complete row raises the bar but closes nothing, so this test states the limitation
+    // rather than a protection the code does not have.
+    const forged = CODEX_STOPPED.replace(
+      '• Stopping all background terminals.',
+      '  1 background terminal running · /ps to view · /stop to close'
+    );
+    expect(watchingLabel(forged, CODEX_WATCHING, CODEX_TAIL)).toBe('1 background terminal');
+
+    // What makes that cost a wrong badge and nothing more: no hook event from a codex
+    // session reaches the approvals inbox, so there is no idle item to pre-acknowledge
+    // and no alert to silence. A CLI that gains hook signals needs a harder anchor first.
+    expect(getCli('codex')?.capabilities.hooks).toBe('none');
+  });
+});
+
+describe('the registry pattern Claude declares', () => {
+  it('is one the config-regex guard accepts', () => {
+    // Same guard as `workingLine`: ~/.codeman/clis.json can set this field, and the
+    // compiled pattern runs over a pane capture on a timer.
+    expect(compileVersionRegex(getCli('claude')!.capabilities.workDetect!.watchingLine!)).not.toBeNull();
+  });
+
+  it('does not fire on the status line a user configured', () => {
+    // Plan-usage and context figures live one row above the footer and carry numbers.
+    const statusLine = '  ~/innovi/gtd-board [main] Opus 5 (1M context) high ctx: 10% 5h: 48% (32m) 7d: 15% (6d10h)';
+    expect(CLAUDE_WATCHING.test(statusLine)).toBe(false);
+  });
+});

test/setup.ts

@@ -45,6 +45,12 @@ delete process.env.CODEMAN_GESTURE;
 // operator who exports it (exactly who the feature is for) would otherwise see the
 // root-install byte-identity assertions fail.
 delete process.env.CODEMAN_BASE_URL;
+// CLAUDE_CONFIG_DIR (#255) relocates Claude's whole tree, transcripts included, and
+// `claudeProjectsDir()` reads it before it ever looks at `homedir()`. A developer who runs
+// Codeman against a separate Claude account exports exactly this, and every test that writes
+// a transcript fixture under the temp HOME's `~/.claude/projects` then reads "no transcript"
+// (found at merge of #467: test/session-custom-model-restart.test.ts went red).
+delete process.env.CLAUDE_CONFIG_DIR;
 
 // Instance selection is PROCESS-WIDE and is what `src/config/instance.ts` derives
 // both the data dir and the tmux socket from, so a shell that exports any of these

test/skin-themes.test.ts

@@ -176,4 +176,33 @@ describe('Codeman light skins', () => {
     expect(mobileStylesSource).toContain(':is(.header, .toolbar, .keyboard-accessory-bar)');
     expect(mobileStylesSource).toContain(':is(.case-settings-popover-mobile, .mobile-case-picker-sheet)');
   });
+
+  it('re-declares every run-mode colour inside the non-og skin block', () => {
+    // The skin block nests under `html:not([data-skin="og"])`, so its generic
+    // `.btn-toolbar.btn-run` outranks a base-sheet `.mode-<id>` pair. A mode with no
+    // resting rule of its own in there (a `:hover` alone does not count) renders as generic claude blue on the DEFAULT skin
+    // (gemini, antigravity and omp all shipped that way). Ids come from the sheet.
+    const css = stylesSource.replace(/\/\*[\s\S]*?\*\//g, '');
+    const opener = 'html:not([data-skin="og"]) {';
+    const start = css.indexOf(opener);
+    expect(start).toBeGreaterThan(-1);
+    let depth = 0;
+    let end = -1;
+    for (let i = start + opener.length - 1; i < css.length; i++) {
+      if (css[i] === '{') depth++;
+      else if (css[i] === '}' && --depth === 0) {
+        end = i;
+        break;
+      }
+    }
+    expect(end).toBeGreaterThan(start);
+    const nested = css.slice(start, end);
+    const base = css.slice(0, start) + css.slice(end);
+    const ids = (text: string) =>
+      new Set([...text.matchAll(/\.btn-toolbar\.btn-run\.mode-([\w-]+)(?![\w-]|:)/g)].map((m) => m[1]));
+    const baseIds = [...ids(base)];
+    expect(baseIds.length).toBeGreaterThanOrEqual(5);
+    const nestedIds = ids(nested);
+    expect(baseIds.filter((id) => !nestedIds.has(id))).toEqual([]);
+  });
 });

test/sw-precache-manifest.test.ts

@@ -0,0 +1,100 @@
+// Port: none (static source contract — no browser, no server).
+//
+// The service worker's precache list used to be maintained by hand with the
+// PRE-hash filenames, while scripts/build.mjs renamed those same files to
+// content-hashed names and rewrote only index.html. So in production every
+// precache entry pointed at a file that no longer existed, and
+// `cache.add(url).catch(() => {})` in the install handler swallowed all of it.
+// Measured against a running instance: 15 of 23 entries 404'd.
+//
+// Nothing caught it because nothing could: the two lists lived in different
+// files, in different languages, with no shared symbol. The fix is to derive
+// the list from the build's own manifest — and this test pins the contract that
+// makes that derivation possible, because the failure mode is silent in both
+// directions. A renamed anchor in sw.js means the build throws (loud, fine). A
+// build that stops rewriting means the worker precaches nothing while still
+// looking correct (silent, not fine).
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const root = resolve(import.meta.dirname, '..');
+const sw = readFileSync(resolve(root, 'src/web/public/sw.js'), 'utf8');
+const build = readFileSync(resolve(root, 'scripts/build.mjs'), 'utf8');
+
+// The exact declarations scripts/build.mjs rewrites. They must appear EXACTLY
+// once: the build asserts the same thing and throws otherwise, so a second
+// occurrence (in a comment, say) fails the build rather than shipping stale.
+const BUILD_ID_ANCHOR = "const BUILD_ID = 'dev';";
+const HASHED_ASSETS_ANCHOR = 'const HASHED_ASSETS = [];';
+
+describe('service worker precache contract', () => {
+  it('sw.js carries exactly one of each anchor the build rewrites', () => {
+    expect(sw.split(BUILD_ID_ANCHOR).length - 1).toBe(1);
+    expect(sw.split(HASHED_ASSETS_ANCHOR).length - 1).toBe(1);
+  });
+
+  it('build.mjs rewrites those exact anchors', () => {
+    expect(build).toContain(BUILD_ID_ANCHOR);
+    expect(build).toContain(HASHED_ASSETS_ANCHOR);
+  });
+
+  // The cache key must vary per build, or `activate`'s cleanup — which deletes
+  // every cache whose key is not the current one — never deletes anything, and
+  // hashed assets from every past release accumulate until the origin hits its
+  // storage quota. That is what the old constant 'codeman-v1' did.
+  it('derives the cache name from the build id rather than a constant', () => {
+    expect(sw).toContain('const CACHE_NAME = `codeman-${BUILD_ID}`;');
+    expect(sw).not.toMatch(/const CACHE_NAME = ['"]codeman-v\d+['"]/);
+  });
+
+  // The whole point of the rewrite: the shell is derived, not hand-listed.
+  it('builds the app shell from the hashed manifest', () => {
+    expect(sw).toContain("...HASHED_ASSETS.map((p) => '/' + p)");
+  });
+
+  // The regression itself: any pre-hash filename hand-listed in APP_SHELL will
+  // 404 in production, because the build renames it.
+  //
+  // The HASHABLE list is PARSED out of scripts/build.mjs rather than copied
+  // here. A hand-kept duplicate would be the same drift this whole PR exists to
+  // fix — it would go stale the first time someone adds an asset to the build,
+  // and then silently stop covering it.
+  it('never hand-lists a filename the build content-hashes', () => {
+    const block = build.slice(
+      build.indexOf('const HASHABLE = ['),
+      build.indexOf('];', build.indexOf('const HASHABLE = ['))
+    );
+    const hashedByBuild = [...block.matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    // Guard the parse itself: an empty list would make this test vacuously pass.
+    expect(hashedByBuild.length, 'failed to parse HASHABLE out of scripts/build.mjs').toBeGreaterThan(10);
+    expect(hashedByBuild).toContain('app.js');
+
+    const shell = sw.slice(sw.indexOf('const APP_SHELL'), sw.indexOf('].map(B);'));
+    for (const name of hashedByBuild) {
+      expect(shell, `APP_SHELL must not hand-list ${name} — the build renames it`).not.toContain(`'/${name}'`);
+    }
+  });
+
+  // Dev serves sw.js unrewritten, so the literals must be valid on their own:
+  // an empty precache plus the unhashed modules cached on first use.
+  it('is valid unrewritten, for dev', () => {
+    expect(() => new Function(sw.replace(/self\./g, 'globalThis.'))).not.toThrow();
+  });
+
+  // Without ignoreSearch the whole precache is unreachable, which is subtle
+  // enough to be re-broken by anyone tidying this handler.
+  //
+  // `renderIndexHtml` runs `cacheBustAssets`, which appends `?v=<mtime>` to
+  // EVERY same-origin `.js`/`.css` reference — content-hashed names included.
+  // Observed on a running instance: `src="app.556be563.js?v=1789423735875"`.
+  // `caches.match` is query-sensitive by default, so a precache keyed on
+  // `/app.556be563.js` can never serve that request, and the install would be
+  // downloading ~1.3MB per deploy that nothing can ever read back.
+  it('falls back to the cache ignoring the cache-busting query string', () => {
+    expect(sw).toContain('caches.match(request, { ignoreSearch: true })');
+    expect(sw, 'a bare caches.match(request) cannot match the ?v=<mtime> URLs cacheBustAssets emits').not.toMatch(
+      /caches\.match\(request\)\s*\)/
+    );
+  });
+});

test/terminal-copy-clean.test.ts

@@ -9,9 +9,11 @@
  * the string handling: a padding-only selection must not silently keep the
  * user's Ctrl+C, and must not put a bare newline on the clipboard.
  *
- * A shared LEADING indent is deliberately left alone. The block below pins that
- * as a contract rather than an accident, because stripping it was built and
- * dropped before merge: see the rule in docs/architecture-invariants.md.
+ * A shared LEADING indent is stripped only when a caller has measured a MARGIN
+ * off the pane and passed it in. The transform called with text alone still
+ * touches trailing padding and nothing else, and the block below pins that,
+ * because measuring the indent off the SELECTION was built and dropped before
+ * #451 merged: see the rule in docs/architecture-invariants.md.
  *
  * Strategy: constants.js and terminal-ui.js in one vm with a stub CodemanApp,
  * the harness shape test/terminal-auto-copy.test.ts uses. No DOM, no xterm.
@@ -25,9 +27,19 @@ import { describe, expect, it, vi } from 'vitest';
 const publicDir = resolve(import.meta.dirname, '../src/web/public');
 const read = (name: string) => readFileSync(resolve(publicDir, name), 'utf8');
 
-function loadHarness() {
+/**
+ * The map the server derives from the `transcriptGutter` CAPABILITY and injects
+ * at render, keyed by run mode. Claude is the only stock entry that declares one.
+ */
+const STOCK_GUTTERS = { claude: 2, codex: 2 };
+
+function loadHarness(
+  settingsOverride?: Record<string, unknown>,
+  gutters: Record<string, number> | null = STOCK_GUTTERS
+) {
   const CodemanApp = function CodemanApp(this: unknown) {};
   const windowRef: Record<string, any> = {};
+  if (gutters) windowRef.__codemanTranscriptGutter = gutters;
   const context = vm.createContext({
     window: windowRef,
     document: {
@@ -59,13 +71,23 @@ function loadHarness() {
   const toasts: { message: string; type: string }[] = [];
   app.showToast = (message: string, type: string) => toasts.push({ message, type });
   app._copyText = vi.fn(async () => true);
-  app.loadAppSettingsFromStorage = () => ({ autoCopySelection: true });
+  app.loadAppSettingsFromStorage = () => ({ autoCopySelection: true, ...(settingsOverride ?? {}) });
 
-  const setSelection = (selection: string, { startX = 0, columnMode = false } = {}) => {
+  // `mode` is what decides the strip: the session's run mode is looked up in the
+  // injected gutter map. No buffer is involved, because the width is declared
+  // rather than measured off the pane. The default is a mode that declares NO
+  // gutter, so a test about the trailing trim keeps its exact meaning, and only a
+  // test asking for `mode: 'claude'` gets a leading strip at all.
+  const setSelection = (
+    selection: string,
+    { startX = 0, columnMode = false, mode = 'shell', from = 0, to = 1 } = {}
+  ) => {
+    app.activeSessionId = 'S1';
+    app.sessions = new Map([['S1', { id: 'S1', mode }]]);
     app.terminal = {
       hasSelection: () => !!selection,
       getSelection: vi.fn(() => selection),
-      getSelectionPosition: () => ({ start: { x: startX, y: 0 }, end: { x: 0, y: 1 } }),
+      getSelectionPosition: vi.fn(() => ({ start: { x: startX, y: from }, end: { x: 0, y: to } })),
       clearSelection: vi.fn(),
       focus: vi.fn(),
       _core: { _selectionService: { _activeSelectionMode: columnMode ? 3 : 0 } },
@@ -100,11 +122,12 @@ describe('CodemanCopySelection.clean — trailing padding', () => {
   });
 });
 
-describe('CodemanCopySelection.clean — a shared leading indent is kept', () => {
+describe('CodemanCopySelection.clean — a shared leading indent is kept without a margin', () => {
   // Measured over 401,445 three-row windows across 1,010 tracked files, stripping
   // the run every row shares fired on 73% of them, and the transform cannot tell
-  // a TUI margin from content. These are the cases that settled it: each one is
-  // real output a user copies, and each one loses information if this changes.
+  // a TUI margin from content by looking at the selection. These are the cases
+  // that settled it, and each one still loses information if the transform ever
+  // strips an indent nobody measured off the pane.
   it('keeps the indent every selected row shares', () => {
     expect(clean('  first line\n  second line')).toBe('  first line\n  second line');
   });
@@ -176,15 +199,10 @@ describe('cleanedTerminalSelection — wiring', () => {
     expect(app.cleanedTerminalSelection()).toBe('  first\n  second');
   });
 
-  it('does not read the selection position at all', () => {
-    // The mid-row flag is gone. It read getSelectionPosition().start, which is
-    // xterm's mousedown ANCHOR and is never normalised, so an upward drag read
-    // it off the bottom row of the selection.
+  it('strips nothing for a run mode that declares no gutter', () => {
     const { app, setSelection } = loadHarness();
-    const terminal = setSelection('  first\n  second');
-    terminal.getSelectionPosition = vi.fn(() => ({ start: { x: 6, y: 0 }, end: { x: 0, y: 1 } }));
+    setSelection('  first\n  second');
     expect(app.cleanedTerminalSelection()).toBe('  first\n  second');
-    expect(terminal.getSelectionPosition).not.toHaveBeenCalled();
   });
 
   it('uses the text it is given without reading the selection again', () => {
@@ -212,6 +230,318 @@ describe('cleanedTerminalSelection — wiring', () => {
   });
 });
 
+describe('CodemanCopySelection.clean — the margin is a ceiling, never the answer', () => {
+  const clean2 = (text: string, options: Record<string, unknown>) =>
+    loadHarness().windowRef.CodemanCopySelection.clean(text, options);
+
+  it('strips a measured margin', () => {
+    expect(clean2('  first\n  second', { margin: 2 })).toBe('first\nsecond');
+  });
+
+  it('strips the margin and no more from a block indented past it', () => {
+    // Four of these six columns are the git log body's own, and they stay.
+    expect(clean2('      fix(terminal): trim it\n      xterm hands back rows', { margin: 2 })).toBe(
+      '    fix(terminal): trim it\n    xterm hands back rows'
+    );
+  });
+
+  it('strips nothing when any selected line sits at column 0', () => {
+    // Selecting a marker row along with the prose under it means the block's
+    // own shared indent is zero, and the block shifts as a unit or not at all.
+    expect(clean2('● Creating a job\n  Intent. A daily check.', { margin: 2 })).toBe(
+      '● Creating a job\n  Intent. A daily check.'
+    );
+  });
+
+  it("keeps every line's indentation relative to every other", () => {
+    const before = '  name: CI\n  on:\n    push:\n      branches: [master]';
+    expect(clean2(before, { margin: 2 })).toBe('name: CI\non:\n  push:\n    branches: [master]');
+  });
+
+  it('leaves the first line alone when the selection began mid-row', () => {
+    // That line never carried the margin: the mousedown cut it off.
+    expect(clean2('rst line\n  second\n  third', { margin: 2, firstLinePartial: true })).toBe(
+      'rst line\nsecond\nthird'
+    );
+  });
+
+  it('still trims trailing padding while it dedents', () => {
+    expect(clean2('  first   \n   \n  second  ', { margin: 2 })).toBe('first\n\nsecond');
+  });
+
+  it('keeps the Windows line join intact on both blank and content rows', () => {
+    expect(clean2('  first\r\n\r\n  second\r\n', { margin: 2 })).toBe('first\r\n\r\nsecond\r\n');
+  });
+
+  it('treats a margin it cannot use as no margin at all', () => {
+    expect(clean2('  first\n  second', { margin: 0 })).toBe('  first\n  second');
+    expect(clean2('  first\n  second', { margin: -4 })).toBe('  first\n  second');
+    expect(clean2('  first\n  second', { margin: 'two' as never })).toBe('  first\n  second');
+  });
+});
+
+describe('cleanedTerminalSelection — the two bugs that kept this out of #451', () => {
+  // Both were real, and both came from the mid-row flag reading the selection's
+  // own geometry to decide how much every row lost. The width is declared by the
+  // CLI now, so neither end of a drag can move it, and the flag governs one line.
+  const ROWS = [
+    '  Intent. A daily check tells you when it publishes.',
+    '  Scope. One recurring routine and nothing else.',
+    '  Risks. Three are worth naming here.',
+  ];
+  const body =
+    '  Intent. A daily check tells you when it publishes.\n  Scope. One recurring routine and nothing else.\n  Risks. Three are worth naming here.';
+  const dedented =
+    'Intent. A daily check tells you when it publishes.\nScope. One recurring routine and nothing else.\nRisks. Three are worth naming here.';
+
+  it('survives a reversed range, whatever end xterm reports first', () => {
+    // xterm 6.0 orders the pair itself, verified by driving a real upward drag
+    // through chromium, so this pins the guard rather than a live bug: an
+    // unordered pair would put the mid-row flag on the wrong end of the drag.
+    const from = 401;
+    const down = loadHarness();
+    down.setSelection(body, { mode: 'claude', from, to: from + 2 });
+    const up = loadHarness();
+    up.setSelection(body, { mode: 'claude', from, to: from + 2 });
+    up.app.terminal.getSelectionPosition = () => ({ start: { x: 0, y: from + 2 }, end: { x: 0, y: from } });
+    expect(down.app.cleanedTerminalSelection()).toBe(dedented);
+    expect(up.app.cleanedTerminalSelection()).toBe(dedented);
+  });
+
+  it('reads the mid-row flag off the earlier end of the range, not the later one', () => {
+    // A drag between column 9 on the first row and column 0 on the last leaves
+    // the FIRST line partial. Read off the wrong end the flag says the block is
+    // flush, and that partial line loses two characters of its own content.
+    const { app, setSelection } = loadHarness();
+    setSelection(`nt. A daily check tells you when it publishes.\n${ROWS[1]}`, { mode: 'claude', from: 1, to: 2 });
+    app.terminal.getSelectionPosition = () => ({ start: { x: 0, y: 2 }, end: { x: 9, y: 1 } });
+    expect(app.cleanedTerminalSelection()).toBe(
+      'nt. A daily check tells you when it publishes.\nScope. One recurring routine and nothing else.'
+    );
+  });
+
+  it('gives the rows below the first one the same result whatever column the mousedown hit', () => {
+    // Three rows used to produce three different clipboards depending on where
+    // the click landed, which the user never sees. Only the partial first line
+    // may differ now, and it differs because it is different text.
+    const tails = [0, 1, 2, 7].map((startX) => {
+      const h = loadHarness();
+      h.setSelection(`${ROWS[0].slice(startX)}\n${ROWS[1]}\n${ROWS[2]}`, { mode: 'claude', from: 1, to: 3, startX });
+      return h.app.cleanedTerminalSelection().split('\n').slice(1).join('\n');
+    });
+    expect(new Set(tails).size).toBe(1);
+    expect(tails[0]).toBe('Scope. One recurring routine and nothing else.\nRisks. Three are worth naming here.');
+  });
+});
+
+describe('cleanedTerminalSelection — the cases the margin has to get right', () => {
+  it('takes the gutter off Claude Code prose, which is what people copy', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection(
+      '  Intent. A daily check tells you when it publishes.\n  Scope. One recurring routine on your account.',
+      { mode: 'claude', from: 1, to: 2 }
+    );
+    expect(app.cleanedTerminalSelection()).toBe(
+      'Intent. A daily check tells you when it publishes.\nScope. One recurring routine on your account.'
+    );
+  });
+
+  it('keeps a git log body at its four-space indent inside an agent gutter', () => {
+    // This is the case that kept the painted-padding gate out on its own: the
+    // pane is a TUI, so that gate says yes, and the body shares six columns.
+    const { app, setSelection } = loadHarness();
+    setSelection(
+      '      fix(terminal): trim the padding a TUI paints\n      xterm hands back whole rows and trims only the\n      cells nothing ever wrote to.',
+      { mode: 'claude', from: 4, to: 6 }
+    );
+    expect(app.cleanedTerminalSelection()).toBe(
+      '    fix(terminal): trim the padding a TUI paints\n    xterm hands back whole rows and trims only the\n    cells nothing ever wrote to.'
+    );
+  });
+
+  it('keeps YAML nesting inside an agent gutter', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection('    build:\n      steps:\n        - run: npm ci', { mode: 'claude', from: 2, to: 4 });
+    expect(app.cleanedTerminalSelection()).toBe('  build:\n    steps:\n      - run: npm ci');
+  });
+
+  it('leaves indented Python alone in a shell pane, where the indent is semantic', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection('    if event.ready:\n        run(event)', { from: 2, to: 3 });
+    expect(app.cleanedTerminalSelection()).toBe('    if event.ready:\n        run(event)');
+  });
+
+  it('leaves git diff context rows alone, where the leading space is the marker', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection(' const x = 1;\n const y = 2;\n }', { from: 2, to: 4 });
+    expect(app.cleanedTerminalSelection()).toBe(' const x = 1;\n const y = 2;\n }');
+  });
+});
+
+describe('copyStripMargin — the per-device toggle', () => {
+  const body = '  Intent. A daily check tells you when it publishes.\n  Scope. One recurring routine and nothing else.';
+  const select = (h: ReturnType<typeof loadHarness>) => h.setSelection(body, { mode: 'claude', from: 1, to: 2 });
+
+  it('strips the margin when the device has never stored a value, because it defaults ON', () => {
+    const h = loadHarness({});
+    select(h);
+    expect(h.app.cleanedTerminalSelection()).toBe(
+      'Intent. A daily check tells you when it publishes.\nScope. One recurring routine and nothing else.'
+    );
+  });
+
+  it('leaves the margin alone when the device turned it off', () => {
+    const h = loadHarness({ copyStripMargin: false });
+    select(h);
+    expect(h.app.cleanedTerminalSelection()).toBe(body);
+  });
+
+  it('still trims trailing padding while the strip is off', () => {
+    const h = loadHarness({ copyStripMargin: false });
+    h.setSelection('  first   \n  second  ', { mode: 'claude', from: 1, to: 2 });
+    expect(h.app.cleanedTerminalSelection()).toBe('  first\n  second');
+  });
+
+  it('never consults the gutter map while it is off', () => {
+    // The lookup is the whole cost now, and it runs on every Ctrl+C, so the
+    // toggle is checked first. There is no buffer to read: the width is declared.
+    const h = loadHarness({ copyStripMargin: false });
+    select(h);
+    expect(h.app._cliGutterColumns()).toBe(0);
+    expect(h.app.cleanedTerminalSelection()).toBe(body);
+  });
+
+  it('treats an unreadable settings store as ON, matching the default', () => {
+    const h = loadHarness();
+    h.app.loadAppSettingsFromStorage = () => {
+      throw new Error('localStorage unavailable');
+    };
+    select(h);
+    expect(h.app.cleanedTerminalSelection()).toBe(
+      'Intent. A daily check tells you when it publishes.\nScope. One recurring routine and nothing else.'
+    );
+  });
+
+  it('keeps the toggle per-device: display key, stripped from the PUT, absent from the schema', () => {
+    const settingsUi = read('settings-ui.js');
+    const schemas = readFileSync(resolve(import.meta.dirname, '../src/web/schemas.ts'), 'utf8');
+    const displayKeys = settingsUi.slice(
+      settingsUi.indexOf('const displayKeys = new Set(['),
+      settingsUi.indexOf('])', settingsUi.indexOf('const displayKeys = new Set(['))
+    );
+    expect(displayKeys).toContain("'copyStripMargin'");
+    // SettingsUpdateSchema is .strict(), so a key it does not declare 400s the
+    // whole settings PUT if the client sends it.
+    expect(settingsUi).toContain('copyStripMargin: _csm,');
+    expect(schemas).not.toContain('copyStripMargin');
+  });
+
+  it('keeps the control loadable and savable by id', () => {
+    const settingsUi = read('settings-ui.js');
+    expect(read('index.html')).toContain('id="appSettingsCopyStripMargin"');
+    // `!== false`, because this one defaults ON and the desktop branch of
+    // getDefaultSettings returns {}.
+    expect(settingsUi).toContain(
+      "document.getElementById('appSettingsCopyStripMargin').checked = settings.copyStripMargin !== false;"
+    );
+    expect(settingsUi).toContain("copyStripMargin: document.getElementById('appSettingsCopyStripMargin').checked,");
+  });
+});
+
+describe('the gutter is DECLARED by the CLI, never measured off the pane', () => {
+  const body = '  Intent. A daily check tells you when it publishes.\n  Scope. One recurring routine.';
+  const flush = 'Intent. A daily check tells you when it publishes.\nScope. One recurring routine.';
+
+  it('takes the declared width off a mode that declares one', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection(body, { mode: 'claude', from: 1, to: 2 });
+    expect(app._cliGutterColumns()).toBe(2);
+    expect(app.cleanedTerminalSelection()).toBe(flush);
+  });
+
+  it('takes the two columns off Codex as well, and keeps the nesting under them', () => {
+    // Measured on a live codex-cli 0.154.0 answer: its •/›/⚠ markers sit in the
+    // gutter, prose continuations sit at 2, and a nested YAML block the model
+    // wrote rendered at 2/4/6/8 for its own 0/2/4/6. Replayed at six widths the
+    // indents were 0, 2, 4, 6 and 8 at every one, never 1.
+    const { app, setSelection } = loadHarness();
+    setSelection('  terminal:\n    pane:\n      gutter:\n        width: 1', { mode: 'codex', from: 1, to: 4 });
+    expect(app._cliGutterColumns()).toBe(2);
+    expect(app.cleanedTerminalSelection()).toBe('terminal:\n  pane:\n    gutter:\n      width: 1');
+  });
+
+  it('leaves a mode nobody has measured alone, because it declares none', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection('    build:\n      steps:', { mode: 'opencode', from: 1, to: 2 });
+    expect(app._cliGutterColumns()).toBe(0);
+    expect(app.cleanedTerminalSelection()).toBe('    build:\n      steps:');
+  });
+
+  it('leaves a shell alone for the same reason', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection('    if event.ready:\n        run(event)', { mode: 'shell', from: 1, to: 2 });
+    expect(app.cleanedTerminalSelection()).toBe('    if event.ready:\n        run(event)');
+  });
+
+  it('strips nothing at all when the server injected no map', () => {
+    // A page served before the capability existed, or a render path that skips
+    // the injection: no session gets a strip rather than every session guessing.
+    const { app, setSelection } = loadHarness(undefined, null);
+    setSelection(body, { mode: 'claude', from: 1, to: 2 });
+    expect(app._cliGutterColumns()).toBe(0);
+    expect(app.cleanedTerminalSelection()).toBe(body);
+  });
+
+  it('ignores a width that is not a positive whole number', () => {
+    for (const bad of [0, -2, 2.5, '2', null] as unknown[]) {
+      const { app, setSelection } = loadHarness(undefined, { claude: bad } as Record<string, number>);
+      setSelection(body, { mode: 'claude', from: 1, to: 2 });
+      expect(app._cliGutterColumns()).toBe(0);
+    }
+  });
+
+  it('reads no terminal buffer on the copy path at all', () => {
+    // The old version scanned up to ~240 rows per Ctrl+C to measure a width that
+    // the CLI can simply state. A buffer here would be a regression to that.
+    const { app, setSelection } = loadHarness();
+    const terminal = setSelection(body, { mode: 'claude', from: 1, to: 2 });
+    const getLine = vi.fn(() => undefined);
+    terminal.buffer = { active: { length: 0, getLine } };
+    expect(app.cleanedTerminalSelection()).toBe(flush);
+    expect(getLine).not.toHaveBeenCalled();
+  });
+});
+
+describe('the transcriptGutter capability, as the registry and server carry it', () => {
+  const registryDir = resolve(import.meta.dirname, '../src/config/cli-registry');
+  const readSrc = (n: string) => readFileSync(resolve(registryDir, n), 'utf8');
+
+  it('is a bounded integer in the schema, so a clis.json cannot declare a huge one', () => {
+    expect(readSrc('schema.ts')).toContain('transcriptGutter: z.number().int().min(1).max(8).optional()');
+  });
+
+  it('is declared by claude and codex, and by nothing else in the stock registry', () => {
+    const stock = readSrc('stock.ts');
+    expect(stock.match(/transcriptGutter: 2,/g)).toHaveLength(2);
+    // Exactly the two whose transcript layout has been measured on a live pane.
+    expect(stock.match(/transcriptGutter:/g)).toHaveLength(2);
+  });
+
+  it('reaches the page off the capability rather than as an id list', () => {
+    const server = readFileSync(resolve(import.meta.dirname, '../src/web/server.ts'), 'utf8');
+    expect(server).toContain('entry.capabilities.transcriptGutter');
+    expect(server).toContain('window.__codemanTranscriptGutter=');
+    // The frontend looks the mode up in that map; the helper holds no id itself.
+    const terminalUi = read('terminal-ui.js');
+    const helper = terminalUi.slice(
+      terminalUi.indexOf('_cliGutterColumns(sessionId) {'),
+      terminalUi.indexOf('async copyTerminalSelection')
+    );
+    expect(helper).toContain('window.__codemanTranscriptGutter');
+    expect(helper).not.toMatch(/'claude'/);
+  });
+});
+
 describe('the xterm internals the column check depends on', () => {
   // The column check reads a private field and compares it to a literal, because
   // xterm publishes the selection mode nowhere. A rename or a renumber would make
@@ -276,6 +606,56 @@ describe('copyTerminalSelection — what reaches the clipboard', () => {
       expect(terminal.clearSelection).toHaveBeenCalledTimes(1);
     });
   });
+
+  // Every case above runs on the harness default mode, which declares no gutter,
+  // so none of them can see a margin stripped twice. These two run on a mode that
+  // declares one.
+  it('takes the declared width off a claude pane exactly once', () => {
+    const { app, setSelection } = loadHarness();
+    setSelection('      fix(terminal): trim it', { mode: 'claude', from: 1, to: 2 });
+    return app.copyTerminalSelection().then(() => {
+      // 2 gutter columns off a body that carries 4 of its own.
+      expect(app._copyText).toHaveBeenCalledWith('    fix(terminal): trim it');
+    });
+  });
+
+  it("keeps a nested block's own indentation on a claude pane", () => {
+    const { app, setSelection } = loadHarness();
+    setSelection('    build:\n      steps:\n        - run: npm ci', { mode: 'claude', from: 1, to: 4 });
+    return app.copyTerminalSelection().then(() => {
+      expect(app._copyText).toHaveBeenCalledWith('  build:\n    steps:\n      - run: npm ci');
+    });
+  });
+});
+
+describe('the margin strip is not idempotent, so no caller may clean twice', () => {
+  // The trailing trim is a fixed point, and copyTerminalSelection leaned on that
+  // by re-cleaning whatever it was handed. The margin strip broke it: it takes
+  // the narrower of the declared width and the run every line shares, so a
+  // second pass takes up to `margin` columns more. Ctrl+C cleaned to decide
+  // whether to copy and then passed the CLEANED string on, which dedented every
+  // claude and codex copy twice on the most-used copy path of the four.
+  it('takes more off a block that has already been stripped', () => {
+    const h = loadHarness();
+    const clean = h.windowRef.CodemanCopySelection.clean;
+    const once = clean('      fix(terminal): trim it', { margin: 2 });
+    expect(once).toBe('    fix(terminal): trim it');
+    expect(clean(once, { margin: 2 })).toBe('  fix(terminal): trim it');
+  });
+
+  it('is pinned in the Ctrl+C branch, which gates on the clean and copies the raw', () => {
+    // The branch lives inside initTerminal's attachCustomKeyEventHandler closure,
+    // over a real xterm this harness cannot build, so the rule is pinned at the
+    // source rather than driven by a keystroke.
+    const terminalUi = read('terminal-ui.js');
+    const branch = terminalUi.slice(
+      terminalUi.indexOf('if (this.shouldCopyTerminalSelectionFromShortcut?.(ev)) {'),
+      terminalUi.indexOf('// Session-sidebar toggle chord')
+    );
+    expect(branch).toContain('const selection = this.cleanedTerminalSelection(raw);');
+    expect(branch).toContain('void this.copyTerminalSelection(raw);');
+    expect(branch).not.toContain('this.copyTerminalSelection(selection)');
+  });
 });
 
 describe('_flushAutoCopySelection — cleaned text is what Auto Copy handles', () => {

test/terminal-font-settle.test.ts

@@ -177,7 +177,11 @@ describe('selectSession font gate', () => {
 
   it('waits for the font before the first fit', () => {
     const wait = body.indexOf('await this._terminalFontReady');
-    const fit = body.indexOf('if (this.fitAddon) this.fitAddon.fit();');
+    // `syncTerminalGeometry()` replaced the bare `fitAddon.fit()` here: it fits
+    // AND applies the floor it reports, so xterm and the PTY cannot disagree
+    // (#464). The gate this test guards is unchanged — the font must be
+    // measured before the terminal is.
+    const fit = body.indexOf('this.syncTerminalGeometry();');
     expect(wait).toBeGreaterThan(-1);
     expect(fit).toBeGreaterThan(-1);
     expect(wait).toBeLessThan(fit);

test/terminal-font-weight.test.ts

@@ -74,6 +74,18 @@ function makeApp(opts: { teammates?: number; terminal?: ReturnType<typeof fakeTe
   }
   const app = {
     applyTerminalFontWeights: mixin.applyTerminalFontWeights,
+    // The REAL geometry chain, not stubs. A font change moves the cell size, so
+    // it moves cols/rows, and `applyTerminalFontWeights` now routes its refit
+    // through the one function that floors the result and reports it (#464).
+    // Wiring the real methods keeps `fit` an assertion about what the terminal
+    // actually did rather than about which helper happened to be called.
+    _refitAfterCellSizeChange: mixin._refitAfterCellSizeChange,
+    syncTerminalGeometry: mixin.syncTerminalGeometry,
+    _resizeTerminalTo: mixin._resizeTerminalTo,
+    getTerminalDimensions: mixin.getTerminalDimensions,
+    // No session: `_refitAfterCellSizeChange` then refits locally and sends
+    // nothing, which is what these cases are about.
+    activeSessionId: null,
     _awaitTerminalFont: vi.fn(() => Promise.resolve()),
     terminal: opts.terminal === undefined ? fakeTerminal() : opts.terminal,
     fitAddon: { fit },

test/terminal-pty-geometry.test.ts

@@ -0,0 +1,566 @@
+// Port: none (pure helpers + a real headless xterm + source guards).
+//
+// Issue #464, "text gets muffled sometimes". The report is a phone screenshot
+// where lines of Claude Code's output are rendered twice and short tool
+// summaries sit inside longer prose rows with the prose's tail still showing.
+//
+// That is not a dropped frame or a frozen renderer; it is arithmetic. Ink wraps
+// its frame at the width the PTY reported and erases the previous frame by
+// walking the cursor up the number of rows it BELIEVES that frame occupied. A
+// browser terminal narrower than the PTY makes each logical line occupy more
+// physical rows than Ink counted, so `eraseLines(n)` clears too few of them and
+// the new frame paints over rows that were never erased.
+//
+// `renders each wrapped line twice when the PTY is wider` below reproduces it
+// against the repo's own xterm, and is written as a CONTRAST: the same stream at
+// a matching width must come out clean. An implementation that stopped fixing
+// anything would fail the second half, not quietly satisfy the first.
+//
+// The rest pins the invariant the fix rests on: there is exactly ONE function
+// that changes the terminal's size, it applies the same floor it reports, and
+// the server reports back the geometry the PTY actually holds so a client whose
+// resize was declined can adopt it instead of rendering against a screen that
+// does not exist.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+import { describe, expect, it, vi } from 'vitest';
+import xtermHeadless from '@xterm/headless';
+
+const { Terminal } = xtermHeadless as unknown as {
+  Terminal: new (opts: Record<string, unknown>) => {
+    write(data: string, cb?: () => void): void;
+    buffer: {
+      active: { length: number; getLine(y: number): { translateToString(trim?: boolean): string } | undefined };
+    };
+  };
+};
+
+const read = (rel: string) => readFileSync(resolve(import.meta.dirname, '..', rel), 'utf8');
+
+type Dims = { cols: number; rows: number };
+
+function loadGeometry() {
+  const context = vm.createContext({ window: {}, globalThis: {} });
+  vm.runInContext(read('src/web/public/constants.js'), context, { filename: 'constants.js' });
+  return (
+    context.window as {
+      CodemanTerminalGeometry: {
+        clampTerminalDimensions: (p: Partial<Dims> | null | undefined) => Dims | null;
+        reconcilePtyGeometry: (local: Dims | null, pty: Partial<Dims> | null) => { adopt: boolean; oversized: boolean };
+        TERMINAL_MIN_COLS: number;
+        TERMINAL_MIN_ROWS: number;
+      };
+    }
+  ).CodemanTerminalGeometry;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// The failure itself, against the real terminal.
+// ───────────────────────────────────────────────────────────────────────────
+
+/** ansi-escapes `eraseLines(n)`: \x1b[2K per row walking up, then column 1. */
+function eraseLines(n: number): string {
+  let out = '';
+  for (let i = 0; i < n; i++) out += '\x1b[2K' + (i < n - 1 ? '\x1b[1A' : '');
+  return n ? out + '\x1b[G' : '';
+}
+
+/** How many physical rows Ink thinks its frame took, wrapping at `cols`. */
+const rowsAt = (frame: string[], cols: number) =>
+  frame.reduce((n, line) => n + Math.max(1, Math.ceil(line.length / cols)), 0);
+
+/**
+ * Ink's repaint loop: erase the previous frame, write the new one. The erase
+ * count is computed at `ptyCols` — the width the PTY told the CLI about —
+ * while the terminal is `xtermCols` wide.
+ */
+function inkStream(frames: string[][], ptyCols: number): string {
+  let out = '';
+  let previousRows = 0;
+  for (const frame of frames) {
+    out += eraseLines(previousRows) + frame.join('\r\n');
+    previousRows = rowsAt(frame, ptyCols);
+  }
+  return out;
+}
+
+async function render(data: string, cols: number, rows = 24): Promise<string[]> {
+  const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 500 });
+  await new Promise<void>((done) => term.write(data, () => done()));
+  const buf = term.buffer.active;
+  const lines: string[] = [];
+  for (let y = 0; y < buf.length; y++) lines.push(buf.getLine(y)?.translateToString(true) ?? '');
+  while (lines.length && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+describe('a terminal that disagrees with the PTY about width', () => {
+  const XTERM_COLS = 62;
+  // Prose long enough to wrap, then a live region that shrinks as tool calls
+  // collapse into one-line summaries — ordinary Claude Code output.
+  const PROSE = [
+    "• Password store entries exist, but GPG can't decrypt — that's the locked keyring after a pod restart. Let me get the browsers sorted.",
+  ];
+  const FRAMES = [
+    [...PROSE, '  Reading settings, scanning the pass store and checking whether the agent can reach AWS'],
+    [...PROSE, '  Ran 1 shell command'],
+  ];
+
+  it('renders each wrapped line twice when the PTY is wider', async () => {
+    const lines = await render(inkStream(FRAMES, 120), XTERM_COLS);
+    const duplicated = lines.filter((line, i) => line !== '' && lines.indexOf(line) !== i);
+    expect(
+      duplicated.length,
+      `a 120-column PTY against a ${XTERM_COLS}-column terminal must leave ghost rows:\n${lines.join('\n')}`
+    ).toBeGreaterThan(0);
+  });
+
+  // The contrast. Without this half, an implementation that fixed nothing —
+  // or a stream that never ghosted in the first place — would still pass above.
+  it('renders each line exactly once when the two agree', async () => {
+    const lines = await render(inkStream(FRAMES, XTERM_COLS), XTERM_COLS);
+    const duplicated = lines.filter((line, i) => line !== '' && lines.indexOf(line) !== i);
+    expect(duplicated, `matched widths must render cleanly:\n${lines.join('\n')}`).toEqual([]);
+    // And the frame that actually won is the last one.
+    expect(lines[lines.length - 1]).toBe('  Ran 1 shell command');
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// The decisions, pure.
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('clampTerminalDimensions', () => {
+  const { clampTerminalDimensions, TERMINAL_MIN_COLS, TERMINAL_MIN_ROWS } = loadGeometry();
+
+  it('floors a proposal too small to be a usable PTY', () => {
+    expect(clampTerminalDimensions({ cols: 12, rows: 4 })).toEqual({
+      cols: TERMINAL_MIN_COLS,
+      rows: TERMINAL_MIN_ROWS,
+    });
+  });
+
+  it('leaves a proposal that already clears the floor alone', () => {
+    expect(clampTerminalDimensions({ cols: 62, rows: 40 })).toEqual({ cols: 62, rows: 40 });
+  });
+
+  it('floors each axis independently — a short phone is not a narrow one', () => {
+    // The everyday case behind #464: keyboard up, plenty of columns, under ten rows.
+    expect(clampTerminalDimensions({ cols: 62, rows: 6 })).toEqual({ cols: 62, rows: TERMINAL_MIN_ROWS });
+  });
+
+  it('reports nothing rather than a guess when the terminal cannot be measured', () => {
+    for (const bad of [null, undefined, {}, { cols: NaN, rows: 10 }, { cols: 40, rows: Infinity }]) {
+      expect(clampTerminalDimensions(bad as Partial<Dims>)).toBeNull();
+    }
+  });
+});
+
+describe('reconcilePtyGeometry', () => {
+  const { reconcilePtyGeometry } = loadGeometry();
+
+  it('does nothing when the terminal already has the PTY\u2019s width', () => {
+    expect(reconcilePtyGeometry({ cols: 62, rows: 40 }, { cols: 62, rows: 40 })).toEqual({ adopt: false, cols: null });
+  });
+
+  it('adopts a width the client never asked for \u2014 a declined resize is still the truth', () => {
+    // Session.resize ignores a small viewport while a desktop claim is live.
+    expect(reconcilePtyGeometry({ cols: 62, rows: 40 }, { cols: 120, rows: 40 })).toEqual({ adopt: true, cols: 120 });
+  });
+
+  // \u26a0\ufe0f The regression this pins: adopting the PTY's ROWS put a phone that took
+  // a desktop's 43 into a viewport with room for 18, which painted the CLI's
+  // input line below the container with nothing able to scroll to it. Width is
+  // the axis the wrap arithmetic needs; rows only decide how much is on screen.
+  it('never asks for the PTY\u2019s rows, however far off they are', () => {
+    for (const ptyRows of [43, 4, 400]) {
+      const out = reconcilePtyGeometry({ cols: 62, rows: 18 }, { cols: 120, rows: ptyRows });
+      expect(out).toEqual({ adopt: true, cols: 120 });
+      expect(out).not.toHaveProperty('rows');
+    }
+  });
+
+  it('does nothing when only the rows differ', () => {
+    expect(reconcilePtyGeometry({ cols: 62, rows: 40 }, { cols: 62, rows: 12 })).toEqual({ adopt: false, cols: null });
+  });
+
+  it('adopts a narrower PTY too \u2014 the width it was told is the width it draws for', () => {
+    expect(reconcilePtyGeometry({ cols: 120, rows: 40 }, { cols: 80, rows: 40 })).toEqual({ adopt: true, cols: 80 });
+  });
+
+  it('keeps its own geometry when the server reported none', () => {
+    // A session with no pane answers `{}` (Session.ptyGeometry is null), and an
+    // older server answers `{}` too. Neither is evidence about any PTY.
+    for (const bad of [null, {}, { rows: 40 }, { cols: 'wide', rows: 40 }]) {
+      expect(reconcilePtyGeometry({ cols: 62, rows: 40 }, bad as Partial<Dims>)).toEqual({ adopt: false, cols: null });
+    }
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// One owner of the terminal's size. These are source guards because the code
+// they cover needs a real DOM (FitAddon measures a rendered element), which
+// the CI gate has no way to give it.
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('exactly one function may change the terminal size', () => {
+  const terminalUi = read('src/web/public/terminal-ui.js');
+  const mobileHandlers = read('src/web/public/mobile-handlers.js');
+
+  function bodyOf(source: string, signature: string): string {
+    const start = source.indexOf(signature);
+    expect(start, `${signature} not found — renamed?`).toBeGreaterThan(-1);
+    const end = source.indexOf('\n  },', start);
+    expect(end).toBeGreaterThan(start);
+    return source.slice(start, end);
+  }
+
+  it('syncTerminalGeometry applies the floor it reports, not the raw proposal', () => {
+    const body = bodyOf(terminalUi, 'syncTerminalGeometry() {');
+    expect(body).toContain('this.fitAddon.fit()');
+    // fit() resizes to proposeDimensions() RAW; the floored value is what goes
+    // to the server, so the floored value is what xterm must end up holding.
+    expect(body).toContain('this.getTerminalDimensions()');
+    expect(body).toContain('this._resizeTerminalTo(dims)');
+  });
+
+  // A sweep of every module that touches the main terminal rather than a spot
+  // check, so a NEW call site there trips it rather than quietly reopening
+  // #464. A module outside the list below is not covered. Scoped to the MAIN
+  // terminal: the split
+  // pane, the teammate windows and the log viewer are separate xterm instances
+  // with their own PTYs (or none), and each owns its own sizing.
+  it('no other call site fits the main terminal behind its back', () => {
+    // `fit(` optionally called through `?.`, so `fitAddon?.fit?.()` counts too.
+    const MAIN_TERMINAL_FIT = /^(?!.*(?:_splitPane|entry\.fitAddon)).*fitAddon[?.]*\.fit(?:\?\.)?\(\)/;
+    const offenders: string[] = [];
+    for (const rel of [
+      'src/web/public/terminal-ui.js',
+      'src/web/public/mobile-handlers.js',
+      'src/web/public/app.js',
+      'src/web/public/ralph-panel.js',
+      'src/web/public/settings-ui.js',
+      'src/web/public/tab-rail-resize.js',
+      'src/web/public/notification-manager.js',
+    ]) {
+      read(rel)
+        .split('\n')
+        .forEach((line, i) => {
+          const code = line.trim();
+          if (code.startsWith('*') || code.startsWith('//')) return; // prose about fit(), not a call
+          if (MAIN_TERMINAL_FIT.test(line)) offenders.push(`${rel}:${i + 1} ${code}`);
+        });
+    }
+    // Exactly one: the owner's own fit.
+    expect(
+      offenders,
+      'every fit of the main terminal must go through syncTerminalGeometry(), which applies ' +
+        'the same floor it reports — a bare fit() leaves xterm at the RAW proposal while the ' +
+        'server is told the floored one (issue #464)'
+    ).toHaveLength(1);
+    expect(offenders[0]).toContain('terminal-ui.js');
+    expect(bodyOf(terminalUi, 'syncTerminalGeometry() {')).toContain('this.fitAddon.fit()');
+    expect(mobileHandlers).toContain('app.syncTerminalGeometry?.()');
+  });
+
+  it('a font change tells the server, because it moves the cell size', () => {
+    // Bigger glyphs mean fewer columns in the same box. These three refitted
+    // and sent nothing, so the CLI kept wrapping at the old column count.
+    for (const setter of [
+      'setFontSize(size) {',
+      'this.terminal.options.fontFamily === resolved',
+      'this.terminal.options.fontWeight === fontWeight',
+    ]) {
+      expect(terminalUi, `${setter} no longer present`).toContain(setter);
+    }
+    expect(bodyOf(terminalUi, 'setFontSize(size) {')).toContain('this._refitAfterCellSizeChange()');
+    const helper = bodyOf(terminalUi, '_refitAfterCellSizeChange() {');
+    expect(helper).toContain('this.sendResize(this.activeSessionId)');
+    expect(helper).toContain('this.syncTerminalGeometry()');
+    // Three call sites in the font setters (size, family, weight) plus the two
+    // font-settle re-fits.
+    expect((terminalUi.match(/_refitAfterCellSizeChange\(\)/g) ?? []).length).toBeGreaterThanOrEqual(6);
+  });
+
+  it('the keyboard one-shot delegates rather than computing its own numbers', () => {
+    const body = bodyOf(mobileHandlers, '_sendTerminalResize() {');
+    expect(body).toContain('app.sendResize');
+    // The hand-rolled POST floored what it sent and nothing else.
+    expect(body).not.toContain('proposeDimensions');
+    expect(body).not.toContain('Math.max');
+    expect(body).not.toContain('fetch(');
+  });
+
+  it('sendResize yields a detached session BEFORE touching geometry, not after', () => {
+    const body = bodyOf(terminalUi, 'async sendResize(sessionId, options = {}) {');
+    const yieldAt = body.indexOf('detachedSessions?.has(sessionId)) return false');
+    const fitAt = body.indexOf('this._geometryForResizeRequest()');
+    expect(yieldAt, 'the detached-session yield is gone').toBeGreaterThan(-1);
+    expect(fitAt, 'sendResize no longer syncs geometry').toBeGreaterThan(-1);
+    expect(
+      yieldAt,
+      'withholding the server resize but reflowing anyway leaves this xterm at a shape ' +
+        'the PTY was never told about — withhold both or neither'
+    ).toBeLessThan(fitAt);
+  });
+
+  it('throttledResize withholds the fit wherever it withholds the SIGWINCH', () => {
+    const start = terminalUi.indexOf('const throttledResize = () => {');
+    expect(start).toBeGreaterThan(-1);
+    const block = terminalUi.slice(start, terminalUi.indexOf("window.addEventListener('resize', throttledResize)"));
+    const guardAt = block.indexOf('!keyboardUp && !detachedElsewhere');
+    const syncAt = block.indexOf('this._geometryForResizeRequest()');
+    expect(guardAt).toBeGreaterThan(-1);
+    expect(syncAt, 'the geometry sync must sit INSIDE the guard').toBeGreaterThan(guardAt);
+  });
+});
+
+describe('the failed-load notice fits the narrowest terminal this app will render', () => {
+  // ⚠️ `e587d845`'s commit message claimed a test asserted this against the
+  // BUILT asset. It did not: that assertion lived in a throwaway probe that was
+  // deleted with the rest of the scratch scripts, so the claim was wrong when it
+  // was written. This is the real one, and it reads the source rather than
+  // `dist/`, because `dist/` is not committed and a test that skips when it is
+  // absent would pass for the wrong reason in CI.
+  const app = read('src/web/public/app.js');
+  const { TERMINAL_MIN_COLS } = loadGeometry();
+
+  /** The literal the catch writes, escapes resolved, SGR stripped. */
+  function noticeLines(): string[] {
+    const at = app.indexOf('if (clearedBeforeFresh && this.terminal)');
+    expect(at, 'the failed-load branch is gone — renamed?').toBeGreaterThan(-1);
+    // Anchored past the comments: one of them quotes a lone '.', which a
+    // first-quote match happily returns instead of the notice.
+    const writeAt = app.indexOf('this.terminal.write(', at);
+    expect(writeAt, 'the failed-load branch no longer writes to the terminal').toBeGreaterThan(-1);
+    const call = app.slice(writeAt, app.indexOf('\n      }', writeAt));
+    const literal = call.match(/'((?:[^'\\]|\\.)*)'/);
+    expect(literal, 'no string literal in the failed-load branch').not.toBeNull();
+    return literal![1]
+      .replace(/\\x1b\[[0-9;]*m/g, '')
+      .split('\\r\\n')
+      .filter((line) => line.trim().length > 0);
+  }
+
+  it('says what failed, that the session lives, and what to do', () => {
+    const lines = noticeLines();
+    expect(lines.length).toBe(3);
+    expect(lines[0]).toMatch(/did not load/i);
+    expect(lines[1]).toMatch(/live output/i);
+    // A dead end is the most expensive defect here: the pane is blank and the
+    // reader has no idea whether the session is recoverable.
+    expect(lines[2], 'the notice must name the next step').toMatch(/reload/i);
+  });
+
+  it('never wraps, down to the 40-column floor', () => {
+    // A 52-character sentence measured at 320px wrapped and left a lone '.' on
+    // a line of its own. The floor is the narrowest this app renders, and it is
+    // two taps away on a small phone via increaseFontSize.
+    for (const line of noticeLines()) {
+      expect(
+        line.length,
+        `"${line}" is ${line.length} columns, over the ${TERMINAL_MIN_COLS} floor`
+      ).toBeLessThanOrEqual(TERMINAL_MIN_COLS);
+    }
+  });
+
+  it('does not tell the reader to reopen the tab, which retries nothing', () => {
+    // selectSession early-returns when the session is already active, so
+    // clicking the tab you are already on does not re-fetch.
+    expect(app).toContain('if (this.activeSessionId === sessionId && !forceReload)');
+    expect(noticeLines().join(' ')).not.toMatch(/reopen|switch tab/i);
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// Resize stopped being write-only.
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('the server reports the geometry the PTY actually holds', () => {
+  it('Session reports its geometry only while a pane is actually drawing', () => {
+    const session = read('src/session.ts');
+    // ⚠️ `resize()` writes _ptyCols/_ptyRows only when ptyProcess is set and
+    // nothing seeds them from the spawn geometry, so a dead-pane session still
+    // holds the constructor defaults of 120x40. Reporting those made a client
+    // adopt a size no process was ever told, and claim another device owned the
+    // pane when none existed.
+    expect(session).toMatch(/get ptyGeometry\(\): \{ cols: number; rows: number \} \| null \{/);
+    expect(session).toContain('return this.ptyProcess ? { cols: this._ptyCols, rows: this._ptyRows } : null;');
+    expect(session, 'the raw getters would report the defaults again').not.toMatch(/get ptyCols\(\)/);
+  });
+
+  it('the WebSocket answers a resize with what took', () => {
+    const ws = read('src/web/routes/ws-routes.ts');
+    const at = ws.indexOf('session.resize(msg.c, msg.r,');
+    expect(at).toBeGreaterThan(-1);
+    const after = ws.slice(at, at + 1400);
+    expect(after).toContain('"t":"zc"');
+    expect(after).toContain('const applied = session.ptyGeometry;');
+    // No pane, no frame at all.
+    expect(after).toContain('if (applied && socket.readyState === 1)');
+    // Documented in the protocol block at the top of the file, like every other frame.
+    expect(ws).toContain('{"t":"zc","c":N,"r":N}');
+  });
+
+  it('the HTTP resize answers with what took, not an empty object', () => {
+    const routes = read('src/web/routes/session-routes.ts');
+    const at = routes.indexOf("app.post('/api/sessions/:id/resize'");
+    expect(at).toBeGreaterThan(-1);
+    const handler = routes.slice(at, at + 1600);
+    expect(handler).toContain('return session.ptyGeometry ?? {};');
+  });
+
+  it('the client adopts the report and re-bases its dedupe on it', () => {
+    const terminalUi = read('src/web/public/terminal-ui.js');
+    const start = terminalUi.indexOf('_onPtyGeometryReport(sessionId, cols, rows) {');
+    expect(start).toBeGreaterThan(-1);
+    const body = terminalUi.slice(start, terminalUi.indexOf('\n  },', start));
+    expect(body).toContain('reconcilePtyGeometry');
+    // Columns only: the local row count is carried through untouched.
+    expect(body).toContain('this._resizeTerminalTo({ cols, rows: local.rows })');
+    // Without this the next resize is deduped against a request that was
+    // REFUSED, which suppresses the retry that recovers the pane.
+    expect(body).toContain('this._lastResizeDims = { cols, rows: local.rows }');
+    // And the WS frame is wired up at all.
+    expect(read('src/web/public/app.js')).toContain("msg.t === 'zc'");
+  });
+
+  it('a pane wider than the screen gets horizontal reach for as long as that lasts', () => {
+    const css = read('src/web/public/styles.css');
+    // .terminal-container is overflow:hidden, so adopting a wider PTY without
+    // this puts the right-hand columns somewhere no gesture can reach them.
+    // Read the rule's DECLARATIONS, comments stripped: the comments in this block
+    // quote CSS with braces in it, which a `[^}]*` window cannot survive.
+    const declarationsOf = (selector: string) => {
+      const at = css.indexOf(`${selector} {`);
+      expect(at, `${selector} not found`).toBeGreaterThan(-1);
+      const body = css.slice(at + selector.length, css.indexOf('\n}', at));
+      return body.replace(/\/\*[\s\S]*?\*\//g, '');
+    };
+    const oversized = declarationsOf('.terminal-container.term-overflows-x');
+    expect(oversized).toContain('overflow-x: auto;');
+    // Both axes, explicitly: mobile.css sets `overflow: visible` on the bare
+    // selector, and a lone overflow-x would leave overflow-y computing to auto.
+    expect(oversized).toContain('overflow-y: hidden;');
+    // ⚠️ NO touch-action here, deliberately. `touch-action: pan-x` does nothing
+    // for the sessions this targets — `touchstart` preventDefault()s every
+    // 'content' tap, which cancels the browser's pan before it starts — and
+    // granting it as well as the JS pan would move the pane twice for one
+    // finger on the taps where that preventDefault does not run. The terminal's
+    // own touchmove handler owns both axes; mobile.css's unscoped
+    // `touch-action: none` is what keeps it the only owner.
+    expect(css.slice(css.indexOf('.terminal-container.term-overflows-x'))).not.toMatch(
+      /\.terminal-container\.term-overflows-x[^{]*\{[^}]*touch-action/
+    );
+    expect(read('src/web/public/terminal-ui.js')).toContain('const canPanHorizontally = () =>');
+    expect(read('src/web/public/terminal-ui.js')).toContain("if (panAxis === 'x') {");
+    // The class is only ever on while the terminal really is too wide, and it
+    // is MEASURED rather than derived: the floor widens the terminal past a
+    // narrow container with the PTY agreeing throughout, so a mismatch test
+    // would never fire for it (360px, font 24: 218px unreachable).
+    expect(read('src/web/public/terminal-ui.js')).toContain("classList.toggle('term-overflows-x', overflows)");
+    expect(read('src/web/public/terminal-ui.js')).toContain(
+      'screen.getBoundingClientRect().width - container.clientWidth > 1'
+    );
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// A refused width must not be re-applied locally on every ask. The real mixin
+// methods, run against a fake terminal whose FitAddon behaves like xterm's.
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('while another device holds the width', () => {
+  const SESSION = 'session-A';
+
+  function makeApp() {
+    const FakeCodemanApp = function () {} as unknown as { prototype: Record<string, unknown> };
+    const context = vm.createContext({
+      console,
+      setTimeout,
+      clearTimeout,
+      setInterval: vi.fn(),
+      clearInterval: vi.fn(),
+      CodemanApp: FakeCodemanApp,
+      window: { addEventListener: vi.fn(), removeEventListener: vi.fn(), innerWidth: 400 },
+      document: { addEventListener: vi.fn(), getElementById: () => null },
+    });
+    vm.runInContext(read('src/web/public/constants.js'), context, { filename: 'constants.js' });
+    vm.runInContext(read('src/web/public/terminal-ui.js'), context, { filename: 'terminal-ui.js' });
+    const mixin = FakeCodemanApp.prototype as Record<string, (...a: unknown[]) => unknown>;
+    // The phone's container: 57x13. Every resize xterm performs is recorded,
+    // because a resize is a re-wrap of the whole buffer.
+    const resizes: Array<[number, number]> = [];
+    const terminal = {
+      cols: 80,
+      rows: 24,
+      resize(cols: number, rows: number) {
+        resizes.push([cols, rows]);
+        this.cols = cols;
+        this.rows = rows;
+      },
+    };
+    const proposal = { cols: 57, rows: 13 };
+    const sent: Array<{ c: number; r: number }> = [];
+    const app = Object.assign(Object.create(mixin), {
+      terminal,
+      fitAddon: {
+        proposeDimensions: () => ({ ...proposal }),
+        // xterm's FitAddon resizes to the raw proposal.
+        fit: () => terminal.resize(proposal.cols, proposal.rows),
+      },
+      activeSessionId: SESSION,
+      detachedSessions: new Set<string>(),
+      isSoloWindow: false,
+      _lastResizeDims: null,
+      _wsReady: true,
+      _wsSessionId: SESSION,
+      _ws: { send: (frame: string) => sent.push(JSON.parse(frame)) },
+      _notePaneOwnedElsewhere: vi.fn(),
+    }) as Record<string, unknown> & {
+      sendResize: (id: string) => Promise<boolean>;
+      _onPtyGeometryReport: (id: string, cols: number, rows: number) => void;
+      _paneWidthRefused?: boolean;
+    };
+    return { app, terminal, resizes, sent, proposal };
+  }
+
+  it('asks for its own width again without re-wrapping to it until the PTY follows', async () => {
+    const { app, terminal, resizes, sent } = makeApp();
+    await app.sendResize(SESSION);
+    expect(sent.at(-1)).toMatchObject({ c: 57, r: 13 });
+    // Refused: the desktop keeps the pane at 198 columns.
+    app._onPtyGeometryReport(SESSION, 198, 43);
+    expect(terminal.cols).toBe(198);
+    expect(app._paneWidthRefused).toBe(true);
+
+    // The retry timer asks again. Nothing about the screen changed, so xterm
+    // must not be re-wrapped to 57 and back (it used to be, every 30 seconds).
+    resizes.length = 0;
+    await app.sendResize(SESSION);
+    app._onPtyGeometryReport(SESSION, 198, 43);
+    expect(resizes).toEqual([]);
+    expect(terminal.cols).toBe(198);
+    // It still ASKS for this screen's width, which is how it recovers.
+    expect(sent.at(-1)).toMatchObject({ c: 57, r: 13 });
+
+    // The desktop went idle and the request took: the report is adopted.
+    await app.sendResize(SESSION);
+    app._onPtyGeometryReport(SESSION, 57, 13);
+    expect(terminal.cols).toBe(57);
+    expect(app._paneWidthRefused).toBe(false);
+  });
+
+  it('still follows the container\u2019s rows while the width is held elsewhere', async () => {
+    const { app, terminal, resizes, proposal } = makeApp();
+    await app.sendResize(SESSION);
+    app._onPtyGeometryReport(SESSION, 198, 43);
+    resizes.length = 0;
+    proposal.rows = 20; // keyboard dismissed
+    await app.sendResize(SESSION);
+    // Rows only: the columns stay at the width the PTY has.
+    expect(resizes).toEqual([[198, 20]]);
+    expect(terminal.cols).toBe(198);
+  });
+});